OrgamsInternals

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.
Sauf mention contraire, le contenu de cette page est protégé par la licence Creative Commons Attribution-ShareAlike 3.0 License