From 9874b11639a57eb10a15eca3a8584cc4dd990da3 Mon Sep 17 00:00:00 2001 From: Chris Pressey Date: Fri, 1 Dec 2017 13:09:25 +0000 Subject: [PATCH] Update documentation. --- HISTORY.markdown | 5 ++++ README.markdown | 25 ------------------- doc/SixtyPical.md | 62 ++++++++++++++++++++++++++++++++++++++++++----- 3 files changed, 61 insertions(+), 31 deletions(-) diff --git a/HISTORY.markdown b/HISTORY.markdown index a1a376a..564decd 100644 --- a/HISTORY.markdown +++ b/HISTORY.markdown @@ -6,6 +6,11 @@ History of SixtyPical * Explicit word literals prefixed with `word` token. * Can `copy` literals into user-defined destinations. +* `buffer` and `pointer` types. +* `copy ^` syntax to load the addr of a buffer into a pointer. +* `copy []+y` syntax to write a value into memory through a pointer. +* TODO: read through pointer. +* TODO: insist the buffer being read or written to through pointer, appears in approporiate set. 0.7 --- diff --git a/README.markdown b/README.markdown index b38da83..982d137 100644 --- a/README.markdown +++ b/README.markdown @@ -41,31 +41,6 @@ Documentation TODO ---- -### `byte buffer` and `pointer` types - -Basically, a `buffer` is a table that can -be longer than 256 bytes, and a `pointer` is an address within a buffer. -A `pointer` is implemented as a zero-page memory location, and accessing the -buffer pointed to is implemented with "indirect indexed" addressing, as in - - LDA ($02), Y - STA ($02), Y - -We will likely have a new mode of `copy` for this, like - - copy ^buf, ptr // this is the only way to initialize a pointer - add ptr, 4 // ok, but only if it does not exceed buffer's size - ld y, 0 // you must set this to something yourself - copy [ptr] + y, byt // read memory through pointer, into byte - copy 100, [ptr] + y // write memory through pointer (still trashes a) - -where `ptr` is a user-defined storage location of `pointer` type, and the -`+ y` part is mandatory. - -This instruction will likely be unchecked, at least to start. Basically, -this is to allow us to write to the `byte buffer[2048]` known as "the screen", -(and doing that is valuable enough that we can sacrifice checking, for now.) - ### `word table` and `vector table` types ### `low` and `high` address operators diff --git a/doc/SixtyPical.md b/doc/SixtyPical.md index a6ac3e5..b4315ca 100644 --- a/doc/SixtyPical.md +++ b/doc/SixtyPical.md @@ -14,19 +14,19 @@ the language. Types ----- -There are five *primitive types* in SixtyPical: +There are six *primitive types* in SixtyPical: * bit (2 possible values) * byte (256 possible values) * word (65536 possible values) * routine (code stored somewhere in memory, read-only) * vector (address of a routine) +* pointer (address of a byte in a buffer) -There is also one *type constructor*: +There are also two *type constructors*: -* X table (256 entries, each holding a value of type X) - -This constructor can only be applied to one type, `byte`. +* X table (256 entries, each holding a value of type X, where X is `byte`) +* buffer[N] (N entries; each entry is a byte; N is a power of 2, ≤ 64K) Memory locations ---------------- @@ -127,6 +127,29 @@ This is actually useful, at least at this point, as you can rely on the fact that literal integers in the code are always immediate values. (But this may change at some point.) +### Buffers and Pointers ### + +Roughly speaking, a `buffer` is a table that can be longer than 256 bytes, +and a `pointer` is an address within a buffer. + +A `pointer` is implemented as a zero-page memory location, and accessing the +buffer pointed to is implemented with "indirect indexed" addressing, as in + + LDA ($02), Y + STA ($02), Y + +There are extended modes of `copy` for using these types of memory location. +See `copy` below, but here is some illustrative example code: + + copy ^buf, ptr // this is the only way to initialize a pointer + add ptr, 4 // ok, but only if it does not exceed buffer's size + ld y, 0 // you must set this to something yourself + copy [ptr] + y, byt // read memory through pointer, into byte + copy 100, [ptr] + y // write memory through pointer (still trashes a) + +where `ptr` is a user-defined storage location of `pointer` type, and the +`+ y` part is mandatory. + Routines -------- @@ -237,6 +260,33 @@ copy more general types of data (for example, vectors,) and it trashes the After execution, dest is considered initialized, and `z` and `n`, and `a` are considered uninitialized. +There are two extra modes that this instruction can be used in. The first is +to load an address into a pointer: + + copy ^, + +This copies the address of src into dest. In this case, src must be +of type buffer, and dest must be of type pointer. src will not be +considered a memory location that is read, since it is only its address +that is being retrieved. + +The second is to read or write indirectly through a pointer. + + copy [] + y, + copy , [] + y + +In both of these, the memory location in the `[]+y` syntax must be +a pointer. + +The first copies the contents of memory at the pointer (offset by the `y` +register) into a byte memory location. + +The second copies a literal byte, or a byte memory location, into +the contents of memory at the pointer (offset by the `y` register). + +In addition to the constraints above, `y` must be initialized before +this mode is used. + ### add dest, src ### add , @@ -359,7 +409,7 @@ Just after the call, * All memory locations listed in the called routine's `trashes` are considered to now be uninitialized. * All memory locations listed in the called routine's `outputs` are considered - to not be initialized. + to now be initialized. ### goto ###