doc: update AT28 instructions for new ~AT28 routine

This commit is contained in:
Virgil Dupras 2020-12-09 20:44:04 -05:00
parent cbd9f035ae
commit 374a0a8e46

View File

@ -31,14 +31,31 @@ I don't think you need a schematic. It's really simple.
# Writing contents to the AT28
There is an AT28! writer word in B400 which is C!*-compatible
(see "Indirect memory access" in doc/usage.txt) and and waits
until the write is complete before returning. If you use C!
directly, bytes you write might not have the time to completely
write themselves before you write another one.
If you wait 10ms between each byte you write, you can write dir-
ectly to the AT28 with regular memory access words. If you don't
wait, the AT28 writing program will fail. Because it's not very
pratical to insert waiting time between each byte writes, you
need another solution.
To use, set C!* with "' AT28! ' C!* **!". Once this is done, you
can use MOVE, or /tools/upload, both will call C!* and do the
right thing. Unset C!* with "' C! ' C!* **!" afterwards.
To that end, Collapse OS has a "memory write override" mech-
anism. Whenever C! or ! is about to set a byte somewhere in
memory, it checks whether such an override is active. If it is,
it calls it. That override is set with the "~C!" word.
B400 also has AT28, which is the same as AT28!, but for C,.
B400 contains an override routine compatible with ~C! called
~AT28. When you're about to write to your AT28, activate that
override with "' ~AT28 ~C!". That overwrite will write the byte,
then poll the AT28 until it indicates that it is finished
writing. This ensures that Collapse OS doesn't try writing
another byte before the AT28 is ready.
When you're done writing to the AT28, unset override with
"0 ~C!". The override routine has a non-negligible speed impact
on all memory writes.
When polling, ~AT28 also verifies that the final byte in memory
is the same as the byte written. If it's not, it will place a
non-zero value in the ~C!ERR 1b variable. Therefore, if you want
to see, after a big write operation to your AT28, whether any
write failed, do "~C!ERR C@ .". Re-initialize to zero before
your next write operation.