git @ Cat's Eye Technologies SixtyPical / 9874b11
Update documentation. Chris Pressey 4 years ago
3 changed file(s) with 63 addition(s) and 33 deletion(s). Raw diff Collapse all Expand all
+5
-0
HISTORY.markdown less more
55
66 * Explicit word literals prefixed with `word` token.
77 * Can `copy` literals into user-defined destinations.
8 * `buffer` and `pointer` types.
9 * `copy ^` syntax to load the addr of a buffer into a pointer.
10 * `copy []+y` syntax to write a value into memory through a pointer.
11 * TODO: read through pointer.
12 * TODO: insist the buffer being read or written to through pointer, appears in approporiate set.
813
914 0.7
1015 ---
+0
-25
README.markdown less more
4040 TODO
4141 ----
4242
43 ### `byte buffer` and `pointer` types
44
45 Basically, a `buffer` is a table that can
46 be longer than 256 bytes, and a `pointer` is an address within a buffer.
47 A `pointer` is implemented as a zero-page memory location, and accessing the
48 buffer pointed to is implemented with "indirect indexed" addressing, as in
49
50 LDA ($02), Y
51 STA ($02), Y
52
53 We will likely have a new mode of `copy` for this, like
54
55 copy ^buf, ptr // this is the only way to initialize a pointer
56 add ptr, 4 // ok, but only if it does not exceed buffer's size
57 ld y, 0 // you must set this to something yourself
58 copy [ptr] + y, byt // read memory through pointer, into byte
59 copy 100, [ptr] + y // write memory through pointer (still trashes a)
60
61 where `ptr` is a user-defined storage location of `pointer` type, and the
62 `+ y` part is mandatory.
63
64 This instruction will likely be unchecked, at least to start. Basically,
65 this is to allow us to write to the `byte buffer[2048]` known as "the screen",
66 (and doing that is valuable enough that we can sacrifice checking, for now.)
67
6843 ### `word table` and `vector table` types
6944
7045 ### `low` and `high` address operators
+58
-8
doc/SixtyPical.md less more
1313 Types
1414 -----
1515
16 There are five *primitive types* in SixtyPical:
16 There are six *primitive types* in SixtyPical:
1717
1818 * bit (2 possible values)
1919 * byte (256 possible values)
2020 * word (65536 possible values)
2121 * routine (code stored somewhere in memory, read-only)
2222 * vector (address of a routine)
23
24 There is also one *type constructor*:
25
26 * X table (256 entries, each holding a value of type X)
27
28 This constructor can only be applied to one type, `byte`.
23 * pointer (address of a byte in a buffer)
24
25 There are also two *type constructors*:
26
27 * X table (256 entries, each holding a value of type X, where X is `byte`)
28 * buffer[N] (N entries; each entry is a byte; N is a power of 2, ≤ 64K)
2929
3030 Memory locations
3131 ----------------
126126 that literal integers in the code are always immediate values. (But this
127127 may change at some point.)
128128
129 ### Buffers and Pointers ###
130
131 Roughly speaking, a `buffer` is a table that can be longer than 256 bytes,
132 and a `pointer` is an address within a buffer.
133
134 A `pointer` is implemented as a zero-page memory location, and accessing the
135 buffer pointed to is implemented with "indirect indexed" addressing, as in
136
137 LDA ($02), Y
138 STA ($02), Y
139
140 There are extended modes of `copy` for using these types of memory location.
141 See `copy` below, but here is some illustrative example code:
142
143 copy ^buf, ptr // this is the only way to initialize a pointer
144 add ptr, 4 // ok, but only if it does not exceed buffer's size
145 ld y, 0 // you must set this to something yourself
146 copy [ptr] + y, byt // read memory through pointer, into byte
147 copy 100, [ptr] + y // write memory through pointer (still trashes a)
148
149 where `ptr` is a user-defined storage location of `pointer` type, and the
150 `+ y` part is mandatory.
151
129152 Routines
130153 --------
131154
236259 After execution, dest is considered initialized, and `z` and `n`, and
237260 `a` are considered uninitialized.
238261
262 There are two extra modes that this instruction can be used in. The first is
263 to load an address into a pointer:
264
265 copy ^<src-memory-location>, <dest-memory-location>
266
267 This copies the address of src into dest. In this case, src must be
268 of type buffer, and dest must be of type pointer. src will not be
269 considered a memory location that is read, since it is only its address
270 that is being retrieved.
271
272 The second is to read or write indirectly through a pointer.
273
274 copy [<src-memory-location>] + y, <dest-memory-location>
275 copy <src-memory-location>, [<dest-memory-location>] + y
276
277 In both of these, the memory location in the `[]+y` syntax must be
278 a pointer.
279
280 The first copies the contents of memory at the pointer (offset by the `y`
281 register) into a byte memory location.
282
283 The second copies a literal byte, or a byte memory location, into
284 the contents of memory at the pointer (offset by the `y` register).
285
286 In addition to the constraints above, `y` must be initialized before
287 this mode is used.
288
239289 ### add dest, src ###
240290
241291 add <dest-memory-location>, <src-memory-location>
358408 * All memory locations listed in the called routine's `trashes` are considered
359409 to now be uninitialized.
360410 * All memory locations listed in the called routine's `outputs` are considered
361 to not be initialized.
411 to now be initialized.
362412
363413 ### goto ###
364414