NEX file format - Revision history

Xalior at 15:27, 1 December 2023

2023-12-01T15:27:32Z

← Older revision		Revision as of 16:27, 1 December 2023
Line 95:		Line 95:
	------------------------------		------------------------------

	Alternative file formats, and possible extensions to this fileformat are noted on the [[~~Alternative_Next_file_formats~~\|Alternative ~~Next~~ file formats]] page, to prevent confusion with supported features in the shipping distribtion and the licensed "Retail SD Card" distribution.		Alternative file formats, and possible extensions to this fileformat are noted on the [[Alternative_NEX_file_formats\|Alternative NEX file formats]] page, to prevent confusion with supported features in the shipping distribtion and the licensed "Retail SD Card" distribution.

Xalior: Remove confusing unsupported 1.3 information into own dedicated page

2023-12-01T15:24:00Z

Remove confusing unsupported 1.3 information into own dedicated page

@@ Line 1: / Line 1: @@
-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.3 at this moment, which allows for even more complex use cases.
+The NEX file format was designed as very simple and straightforward format to load self-contained applications into memory and start them.
-The official distribution sports some goodies for NEX files (currently supporting V1.2 NEX files):
+At this time the official Distro supported version is the V1.2 of the specification.
 * [https://gitlab.com/thesmog358/tbblue/blob/master/src/asm/nexload/nexload.asm nexload.asm]
 * [https://gitlab.com/thesmog358/tbblue/blob/master/src/c/NexCreator.c NexCreator.c]
@@ Line 8: / Line 10: @@
 * [https://github.com/Threetwosevensixseven/NexCreator/tree/master/nexload SevenFFF's fork of NexCreator and nexload]
 * [https://github.com/varmfskii/zxnext_tools Varmfskii's ZX Next tools]
-* [https://github.com/ped7g/ZXSpectrumNextMisc/tree/master/nexload2 Ped's nexload2.asm] (rewritten from scratch, supports V1.3 NEX files)
+* [https://github.com/z00m128/sjasmplus/releases Z00m's sjasmplus] has support for [http://z00m128.github.io/sjasmplus/documentation.html#c_savenex NEX saving] since v1.13.0
 ------------------------------
@@ Line 48: / Line 49: @@
 | 0 || 4 || "Next" string
 |-
-| 4 || 4 || string with NEX file version, currently "V1.0", "V1.1", "V1.2" or "V1.3"
+| 4 || 4 || string with NEX file version, currently "V1.0", "V1.1", or "V1.2"
 |-
 | 8 || 1 || RAM required: 0 = 768k, 1 = 1792k
@@ Line 55: / Line 56: @@
 |-
 | 10 || 1 || Loading-screen blocks in file (bit-flags):
-= no palette block, 64 = "flags 2" in V1.3 part of header define screen, 16 = Hi-Colour, 8 = Hi-Res, 4 = Lo-Res, 2 = ULA, 1 = Layer2
+= 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).
@@ Line 90: / Line 91: @@
 |-
 | 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.
 |}
 ------------------------------
-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):
+Alternative file formats, and possible extensions to this fileformat are noted on the [[Alternative_Next_file_formats|Alternative Next file formats]] page, to prevent confusion with supported features in the shipping distribtion and the licensed "Retail SD Card" distribution.

Xalior: Reverted edits by SevenFFF (talk) to last revision by Em00k

2022-09-28T11:54:07Z

Reverted edits by SevenFFF (talk) to last revision by Em00k

← Older revision		Revision as of 12:54, 28 September 2022
Line 132:		Line 132:
	** 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)		** 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)
	** 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)		** 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)
	** ~~Return~~ multiple open file handles to the .nex file. Specify how many handles and an address in the header (you can now since V1.3 re-parse the original arguments in CLI buffer and re-open the NEX file yourself).		** return multiple open file handles to the .nex file. Specify how many handles and an address in the header (you can now since V1.3 re-parse the original arguments in CLI buffer and re-open the NEX file yourself).
	** With a flag (bit 7 of number of handles?) to force close all existing open handles first.		** With a flag (bit 7 of number of handles?) to force close all existing open handles first.
	** Call [https://gitlab.com/thesmog358/tbblue/-/blob/master/docs/nextzxos/NextZXOS_and_esxDOS_APIs.pdf IDE_MODE] to query the current NextZXOS LAYER mode details, and make them available to user code inside the NEX. Use case is to be able to call dot commands from within the NEX while preserving the screen mode as it was before the NEX was launched.		** Call [https://gitlab.com/thesmog358/tbblue/-/blob/master/docs/nextzxos/NextZXOS_and_esxDOS_APIs.pdf IDE_MODE] to query the current NextZXOS LAYER mode details, and make them available to user code inside the NEX. Use case is to be able to call dot commands from within the NEX while preserving the screen mode as it was before the NEX was launched.

SevenFFF at 18:53, 7 May 2020

2020-05-07T18:53:47Z

← Older revision		Revision as of 19:53, 7 May 2020
Line 132:		Line 132:
	** 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)		** 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)
	** 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)		** 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)
	** ~~return~~ multiple open file handles to the .nex file. Specify how many handles and an address in the header (you can now since V1.3 re-parse the original arguments in CLI buffer and re-open the NEX file yourself).		** Return multiple open file handles to the .nex file. Specify how many handles and an address in the header (you can now since V1.3 re-parse the original arguments in CLI buffer and re-open the NEX file yourself).
	** With a flag (bit 7 of number of handles?) to force close all existing open handles first.		** With a flag (bit 7 of number of handles?) to force close all existing open handles first.
	** Call [https://gitlab.com/thesmog358/tbblue/-/blob/master/docs/nextzxos/NextZXOS_and_esxDOS_APIs.pdf IDE_MODE] to query the current NextZXOS LAYER mode details, and make them available to user code inside the NEX. Use case is to be able to call dot commands from within the NEX while preserving the screen mode as it was before the NEX was launched.		** Call [https://gitlab.com/thesmog358/tbblue/-/blob/master/docs/nextzxos/NextZXOS_and_esxDOS_APIs.pdf IDE_MODE] to query the current NextZXOS LAYER mode details, and make them available to user code inside the NEX. Use case is to be able to call dot commands from within the NEX while preserving the screen mode as it was before the NEX was launched.

Em00k: Protected "NEX file format" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

2020-05-07T18:51:45Z

Protected "NEX file format" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

← Older revision		Revision as of 19:51, 7 May 2020
(No difference)

SevenFFF at 18:09, 24 April 2020

2020-04-24T18:09:45Z

← Older revision		Revision as of 19:09, 24 April 2020
Line 134:		Line 134:
	** return multiple open file handles to the .nex file. Specify how many handles and an address in the header (you can now since V1.3 re-parse the original arguments in CLI buffer and re-open the NEX file yourself).		** return multiple open file handles to the .nex file. Specify how many handles and an address in the header (you can now since V1.3 re-parse the original arguments in CLI buffer and re-open the NEX file yourself).
	** With a flag (bit 7 of number of handles?) to force close all existing open handles first.		** With a flag (bit 7 of number of handles?) to force close all existing open handles first.
			** Call [https://gitlab.com/thesmog358/tbblue/-/blob/master/docs/nextzxos/NextZXOS_and_esxDOS_APIs.pdf IDE_MODE] to query the current NextZXOS LAYER mode details, and make them available to user code inside the NEX. Use case is to be able to call dot commands from within the NEX while preserving the screen mode as it was before the NEX was launched.

Ped7g: NEX V1.3 format finalized

2020-01-12T16:29:52Z

NEX V1.3 format finalized

Show changes

Ped7g at 09:45, 7 January 2020

2020-01-07T09:45:54Z

← Older revision		Revision as of 10:45, 7 January 2020
Line 121:		Line 121:
	\| 154 \|\| 4 \|\| When Tilemode screen: four bytes array, values to set NextRegs: $6B, $6C, $6E, $6F		\| 154 \|\| 4 \|\| When Tilemode screen: four bytes array, values to set NextRegs: $6B, $6C, $6E, $6F
	\|-		\|-
	\| 158 \|\| 1 \|\| When Layer 2 320x256 or 640x256 screen + loading bar: loading bar Y position		\| 158 \|\| 1 \|\| When Layer 2 320x256 or 640x256 screen + loading bar: loading bar Y position (bar is 2px tall, so 254 is very bottom)
	\|-		\|-
	\| 159 \|\| 349 \|\| reserved for future extensions, set to zero in older versions of file format.		\| 159 \|\| 349 \|\| reserved for future extensions, set to zero in older versions of file format.

Ped7g: V1.3 extensions proposal - probably final version of proposal, changes documented in text

2020-01-06T13:48:14Z

V1.3 extensions proposal - probably final version of proposal, changes documented in text

← Older revision		Revision as of 14:48, 6 January 2020
Line 93:		Line 93:
	Currently I (Ped7g) am considering to add these fields to the V1.3 header, feel free to comment about these on SpectrumNext discord server in #tools channel (I believe I will have prototype implementation in following days, and eventually based on the feedback this may become final V1.3 header in a week or so):		Currently I (Ped7g) am considering to add these fields to the V1.3 header, feel free to comment about these on SpectrumNext discord server in #tools channel (I believe I will have prototype implementation in following days, and eventually based on the feedback this may become final V1.3 header in a week or so):

	Proposed further changes of the header block for V1.3:		Proposed further changes of the header block for V1.3 - second version of proposal:
			changes:
			1) moving tilemode four control bytes from palette into header itself, now palette is full 256 colours and optional as well
			2) adding loading-bar-pos-Y for the new Layer 2 modes (as the current "bottom of screen" may be hidden on many TVs/LCDs)
	{\| class="wikitable"		{\| class="wikitable"
	\|-		\|-
Line 100:		Line 103:
	\| 143 \|\| 1 \|\| 1 = Has checksum value, checksum algorithm is CRC-32C (Castagnoli), value itself is at the very end of the header block		\| 143 \|\| 1 \|\| 1 = Has checksum value, checksum algorithm is CRC-32C (Castagnoli), value itself is at the very end of the header block
	\|-		\|-
	\| 144 \|\| 4 \|\| File offset of first bank data (when loader is parsing known version, it should know where the banks start without this value, but it may use it for extra check whether the parsing of optional blocks between header and first bank was done correctly)		\| 144 \|\| 4 \|\| File offset of first bank data (when loader is parsing known version, it should know where the banks start without this value, but it may use it for extra check whether the parsing of optional blocks between header and first bank was done correctly for files V1.3+, or it may even try to partially-load unknown future versions of NEX files by skipping unknown blocks between header and banks data, although that may lead to unexpected state for the app)
	\|-		\|-
	\| 148 \|\| 2 \|\| CLI buffer address (after "Entry bank" is paged in), 0 = no buffer		\| 148 \|\| 2 \|\| CLI buffer address (after "Entry bank" is paged in), 0 = no buffer
	\|-		\|-
	\| 150 \|\| 2 \|\| CLI buffer size - when address and size are provided, the original ~~command~~ line passed to NEX loader will be copied to defined buffer (and truncated to "size", shorter string may be zero/colon/enter terminated as any other BASIC line) and register DE is set to the buffer address. The maximum size is 2048 bytes (longer lines can be probably salvaged from Bank 5 memory if the NEX file is not loading that bank and ~~will~~ search for the original line on its own).		\| 150 \|\| 2 \|\| CLI buffer size - when address and size are provided, the original argument line passed to NEX loader will be copied to defined buffer (and truncated to "size", shorter string may be zero/colon/enter terminated as any other BASIC line) and register DE is set to the buffer address. The maximum size is 2048 bytes (longer lines can be probably salvaged from Bank 5 memory if the NEX file is not loading that bank and the app code search for the original line on its own).
	\|-		\|-
	\| 152 \|\| 1 \|\| Loading screen flags 2 - when first flag has ~~value~~ 64 set (+128 no-palette is ~~partially~~ valid for new cases too, other bits should be ~~not~~ mixed with new modes):		\| 152 \|\| 1 \|\| Loading screen flags 2 - when first flag has bit6 +64 set (+128 no-palette is valid for new cases too, other old bits should be NOT mixed with new modes):
	1 = Layer 2 320x256x8bpp ~~(old +128 no-palette does apply too)~~ blocks: 512B palette + 81920B data		1 = Layer 2 320x256x8bpp, blocks: [512B palette +] 81920B data
	2 = Layer 2 640x256x4bpp ~~(old +128 no-palette does apply too)~~ blocks: 512B palette + 81920B data		2 = Layer 2 640x256x4bpp, blocks: [512B palette +] 81920B data
	(HiRes color value is used as L2 palette offset - does apply to ~~both~~ new Layer 2 modes)		(HiRes color value 0..15 is used as L2 palette offset - does apply to two new Layer 2 modes)
	~~3 = Tilemode screen, block 512B: 508B palette (254 colors only) + 4B NextRegs $6B, $6C, $6E, $6F~~		For Layer 2 banks 9,10,11,12,13 are used to display the loading screen.
	~~Tilemap data are stored in regular bank 5 - no specialized data block is used.~~		3 = Tilemode screen, block: [512B palette] (plus four configuration bytes in header at offset 154)
	For Layer 2 banks 9,10,11,12,13 are used to display the loading screen.		Tilemap data are stored in regular (!) bank 5 - no specialized data block is used.

	~~EDIT~~: ~~I'm deeply tempted to drop the~~ palette ~~hack, and move the~~ four bytes ~~into~~ header ~~as separate fields... so far I heard~~ no ~~opinions about these proposals, and if it stays like this, I will go for new header fields, the palette hack feels just wrong, and there's still enough free space in the header for extra 4B~~.
	\|-		\|-
	\| 153 \|\| 1 \|\| 1 = Has copper code block, extra 2048B block after last screen data block, which will be set to Copper and the copper will be started with %01 control code (reset CPC to 0, and start). This can be used for example as "loading screen animation" feature (be aware the timing of load may vary greatly).		\| 153 \|\| 1 \|\| 1 = Has copper code block, extra 2048B block after last screen data block, which will be set to Copper and the copper will be started with %01 control code (reset CPC to 0, and start). This can be used for example as "loading screen animation" feature (be aware the timing of load may vary greatly).
	\|-		\|-
	\| 154 \|\| ~~354~~ \|\| reserved for future extensions, set to zero in older versions of file format.		\| 154 \|\| 4 \|\| When Tilemode screen: four bytes array, values to set NextRegs: $6B, $6C, $6E, $6F
			\|-
			\| 158 \|\| 1 \|\| When Layer 2 320x256 or 640x256 screen + loading bar: loading bar Y position
			\|-
			\| 159 \|\| 349 \|\| reserved for future extensions, set to zero in older versions of file format.
	\|-		\|-
	\| 508 \|\| 4 \|\| optional CRC-32C (Castagnoli) - is calculated by checksumming file content from offset 512 (after this value) till end of file (including the optional custom binary appended after regular NEX file), and then further checksumming first 508 bytes of the header (the only skipped four bytes are then this checksum value). This is intended for PC tools working with NEX files, or extra check tool running on Next, but not for regular loading of NEX files.		\| 508 \|\| 4 \|\| optional CRC-32C (Castagnoli) - is calculated by checksumming file content from offset 512 (after this value) till end of file (including the optional custom binary appended after regular NEX file), and then further checksumming first 508 bytes of the header (the only skipped four bytes are then this checksum value). This is intended for PC tools working with NEX files, or extra check tool running on Next, but not for regular loading of NEX files (value is stored as "uint32_t" in little-endian way).
	\|}		\|}

	~~I tried to consider also the~~ multi-handle ~~of NEX file~~ feature, ~~but I was unable to figure out implementation details~~ how to ~~achieve desired outcome~~ and ~~what are~~ the ~~limits~~ and ~~API~~, so ~~it's not included in my current~~ V1.3 ~~proposal~~.		The multi-handle feature from backlock didn't make it through, not sure how to implement it correctly in loader, and by passing whole argument line the code can re-parse it the same way as loader, and open the NEX file as many times as it wants, under its own control, so the possibility of solution is here since V1.3, even if not straightforward.

	------------------------------		------------------------------

	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):		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~~		* probably compatible with current V1.2/V1.3 file formats
	** checking machine memory and use the RAMREQ to report low memory		** checking machine memory and use the RAMREQ to report low memory
	** having entry bank dynamically allocated by NextZXOS (entrybank = 255?)		** having entry bank dynamically allocated by NextZXOS (entrybank = 255?)
	** changing working directory if path with directories was provided (adjust that also when passing command line in V1.3 to make file-only like)		** changing working directory if path with directories was provided (adjust that also when passing command line in V1.3 to make file-only like) (can be extra option of loader, not stored in the file itself)
	* V1.3+		* V1.4+
	** passing cmd line args to the loaded code - after discussion with Allen A. => BC = file handle (~~or 255)~~, ~~DE = command line (is equal to the field buffer value~~ in ~~header), zero terminated string (if~~ the ~~zero terminator is missing, the line is probably truncated to buffer size~~) ~~= two new words into~~ V1.~~3 header [cliBuffer, cliSize].~~
	** 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)		** 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)		** 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.		** 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.		** With a flag (bit 7 of number of handles?) to force close all existing open handles first.

Ped7g: V1.3 extensions proposal - refined some details after testing NEXLOAD2 prototype

2020-01-03T17:07:51Z

V1.3 extensions proposal - refined some details after testing NEXLOAD2 prototype

← Older revision		Revision as of 18:07, 3 January 2020
Line 104:		Line 104:
	\| 148 \|\| 2 \|\| CLI buffer address (after "Entry bank" is paged in), 0 = no buffer		\| 148 \|\| 2 \|\| CLI buffer address (after "Entry bank" is paged in), 0 = no buffer
	\|-		\|-
	\| 150 \|\| 2 \|\| CLI buffer size - when address and size are provided, the original command line passed to NEX loader will be copied to defined buffer (and truncated to "size", shorter string may be zero-terminated) and register DE is set to the buffer address. The maximum size is 2048 bytes (longer lines can be probably salvaged from Bank 5 memory if the NEX file is not loading that bank and will search for the original line on its own).		\| 150 \|\| 2 \|\| CLI buffer size - when address and size are provided, the original command line passed to NEX loader will be copied to defined buffer (and truncated to "size", shorter string may be zero/colon/enter terminated as any other BASIC line) and register DE is set to the buffer address. The maximum size is 2048 bytes (longer lines can be probably salvaged from Bank 5 memory if the NEX file is not loading that bank and will search for the original line on its own).
	\|-		\|-
	\| 152 \|\| 1 \|\| Loading screen flags 2 - when first flag has value 64 set (+128 no-palette is partially valid for new cases too, other bits should be not mixed with new modes):		\| 152 \|\| 1 \|\| Loading screen flags 2 - when first flag has value 64 set (+128 no-palette is partially valid for new cases too, other bits should be not mixed with new modes):