NEX file format
The NEX file format was designed as very simple and straightforward format to load self-contained applications into memory and start them. Through various extensions it did reach v1.2 at this moment, which allows even for more complex use cases.
The official distribution sports some goodies for NEX files:
Additional resources:
- Varmfskii's ZX Next tools
- Ped's nexload2.asm (rewritten from scratch)
The basic structure of the file is:
| block size | optional | description |
|---|---|---|
| 512 | "Next" string followed by file header, containing also map of memory banks stored in the file | |
| 512 | * | optional palette (for Layer2 or LoRes screen) |
| 49152 | * | Layer2 loading screen |
| 6912 | * | classic ULA loading screen |
| 12288 | * | LoRes loading screen |
| 12288 | * | Timex HiRes (512x192) loading screen |
| 12288 | * | Timex HiCol (8x1) loading screen |
| n * 16384 | * | 16kiB raw memory bank data in predefined order: 5,2,0,1,3,4,6,7,8,9,10,...,111 (particular bank may be omitted completely) |
Structure of the header block:
| offset | size | description |
|---|---|---|
| 0 | 4 | "Next" string |
| 4 | 4 | string with NEX file version, currently "V1.0", "V1.1" or "V1.2" |
| 8 | 1 | RAM required: 0 = 768k, 1 = 1792k |
| 9 | 1 | Number of 16k Banks to Load: 0-112 (see also the byte array at offset 18, which must yield this count) |
| 10 | 1 | Loading-screen blocks in file (bit-flags):
128 = no palette block, 16 = Hi-Colour, 8 = Hi-Res, 4 = Lo-Res, 2 = ULA, 1 = Layer2 The loader does use common banks to load the graphics into, and show it from, i.e. bank5 for all ULA related modes and banks 9,10 and 11 for Layer2 graphics (loading these banks afterwards as regular bank will thus replace the shown data on screen). Only Layer2 and Lo-Res screens expect the palette block (unless +128 flag set). While one can include multiple screen data in single file (setting up all relevant bits), the recommended/expected usage is to have only one type of screen in NEX file. |
| 11 | 1 | Border Colour: 0-7 |
| 12 | 2 | Stack pointer |
| 14 | 2 | Program counter (0 = don't run, just load) |
| 16 | 2 | "Number of extra files" (currently not used by anything/anyone?) |
| 18 | 112 | byte flag (0/1) of 16k banks included in the file - this array is in regular order 0..111, i.e. bank5 in file will set 1 to header byte at offset 18+5 = 23, but the 16kiB of data for bank 5 are first in the file (order of bank data in file is: 5,2,0,1,3,4,6,7,8,9,10,...,111) |
| 130 | 1 | Layer2 "loading bar" 0 = OFF, 1 = ON (works only in combination with Layer2 screen data) |
| 131 | 1 | "Loading bar" colour (0..255) |
| 132 | 1 | Loading delay per bank (0..255 amount of frames), 0 = no delay |
| 133 | 1 | Start delay (0..255 amount of frames), 0 = no delay |
| 134 | 1 | Preserve current Next-Registers values (0 = reset, 1 = preserve) |
| 135 | 3 | Required core version, three bytes 0..15 "major", 0..15 "minor", 0..255 "subminor" version numbers. |
| 138 | 1 | Timex HiRes 512x192 mode colour, encoded as for port 255 = bits 5-3. I.e. values 0, 8, 16, .., 56 (0..7 * 8) |
| 139 | 1 | Entry bank = bank to be mapped into slot 3 (0xC000..0xFFFF address space), the "Program Counter" (header offset +14) and "File handle address" (header offset +140) are used by NEX loader after the mapping is set (The default ZX128 has bank 0 mapped after reset, which makes zero value nice default). |
| 140 | 2 | File handle address: 0 = NEX file is closed by the loader, 1..0x3FFF values (1 recommended) = NEX loader keeps NEX file open and does pass the file handle in BC register, 0x4000..0xFFFF values (for 0xC000..0xFFFF see also "Entry bank") = NEX loader keeps NEX file open and the file handle is written into memory at the desired address. |
| 142 | 370 | reserved for future extensions, set to zero in V1.1 and V1.2 file format. |
Possible roadmap/ideas for future (this is just collection of ideas, no timeframe or guarantee that they will ever happen, feel free to comment on them):
- probably compatible with current V1.2 file format
- checking machine memory and use the RAMREQ to report low memory
- having entry bank dynamically allocated by NextZXOS (entrybank = 255?)
- V1.3+
- passing cmd line args to the loaded code (ideally in C-compatible way) - after discussion with Allen A. = seems like copy of command line into RAM and passing pointer in BC is nice to interface with C, i.e. add two words in header (buffer adr + length), copy command line, pass it in BC? (it's still a bit unclear how to pass these things into C in the most-cooperating way)
- preserving original NextZXOS stack SP value (stack pointer = 2?) (0 is valid SP starting from very "top" of RAM) (preserving is risky, as there is always possibility of ramtop being set in such unfortunate manner, that preserved sp will cause destruction of the loaded code, so the SP should be set up by the header every time, but maybe there can be extra flag to put old value into the new stack by loader, so the code can eventually get to the content of old stack - if the NEX file doesn't overwrite the banks 5/2/0)
- checksums incorporated into the NEX file (maybe into header?) - mostly for file archival/transfers, not loader itself
- custom palettes also for ULA/HiRes/HiCol screens (maybe +64 flag?) (or invert the +128 in V1.3 for those three modes, i.e. 0 = no pal / 128 = has pal)
- tilemap screen
- return multiple open file handles to the .nex file. Specify how many handles and an address in the header.
- With a flag (bit 7 of number of handles?) to force close all existing open handles first.