For cooks and coders
In-memory source chunk structure.
A source is stored in a linked list of chunks aligned to &xx00 addresses (rope-like data structure).
Each chunk has a header (&00-&1f) and the actual data.
A chunk may not be full, the end of data (rather than the size) is stored in the header.
&00 byte Bank next chunk (0 if last)
&01 byte MSB next chunk
&02 byte Last pos of data including sentinel (between &21 if empty and &ff if full)
&03 byte checksum See org.o
&04 byte lines # (0 if empty, -1 if not computed yet).
&05 byte flags See org.o
&06 word PC at start of chunk (see visu.o)
&08 byte IF state (see visu.o)
&09-&1f Reserved
&20 Start of data (the encoded source).
Storage source on file.
dword Tag (ORGA)
byte Version (2)
word Size of meta data (n1)
n1 Meta data (editeur related stuff like bloc and cursor position)
dword Tag (SRCc)
byte Version (2)
x * [
byte Size of chunk (n2). If 0 -> end of loop
n2 Chunk of encoded source.
]
dword Tag (LBLs)
byte Version (2)
y All labels concatenated. Bit7=1 marks end of label. 0=no more labels.
dword Tag (CHKs)
byte Version (2)
x Checksums, one byte for each chunk.
Source encoding.
Pre-assembled Z80 with some escape code.
"@" id: Naked label (address)
"d" id exp: Definition. E.g. `label = 3`
"J": New-line
"C" size: Comment (imply new-line)
...
7f 00: End of chunk (sentinel)
7f 01 c: As-is
...
See disp.o
Memory Mapping.
Let's call 'User memory' the memory as seen by user's program, e.g. the state of the memory when the program is executed or at BRK time.
The firmware might be trashed, for instance.
Orgams operates in several modes (each with its own set of benefits):
- Mode A: All user memory is connected (except page C000: todo #62). That is required for fast trace (e.g. all emulated Z80 instructions can write in memory without re-mapping).
- Mode B: Backup of some of this memory (9800-9FFF), so it can be used by Orgams for complex operations that requires stack to be out of bank and other facilities. When disassembling something at 9xxx, that's of course the user memory that is shown (a mirror mechanism reads the backup).
- Mode C: Complete backup of page 8000, so Orgams can use 8000 for additional V-RAM (status board), firmware for IO operations and some out-of-bank buffers to simplify everything, from ROM-switching to assemblage.
NB: The mode C could technically be used in place of mode B, but we want to avoid that because the swap between trace (MODE A) and trace ui (MODE B) must remain fast.
The breakpoint routine (at &30 + &be00) is only installed when launching Orgams (explicit RSX rather than boot time). Rationale:
- Don't be intrusive if Orgams isn't used.
- The trace (or rather, the other modules like monogams) expects the firmware & some internals to be backed-up in bank base - 1 (&FE typically). It's only done when launching Orgams.