?login_element?

Subversion Repositories NedoOS

Rev

Rev 129 | Blame | Compare with Previous | Last modification | View Log | Download

  1. ;;; docs design (missing the changes after V1.3 introduction, added directly in docs.xml)
  2. ;     SAVENEX <command> <command arguments>
  3. ;  Works only in ZXSPECTRUMNEXT device emulation mode. See DEVICE.
  4. ;
  5. ;  For file format details, check https://specnext.dev/wiki/NEX_file_format
  6. ;
  7. ;  As the file is designed for self-contained distribution of whole applications/games,
  8. ; its configuration and assembling is a bit too complex for single directive, and the
  9. ; configuration is instead divided into multiple commands, and the assembling goes
  10. ; through multiple stages, so some commands must be used in correct sequence.
  11. ;
  12. ; While the format technically allows to include multiple screen types data, they are
  13. ; all loaded at the beginning over each other, so it makes sense to provide only single
  14. ; loading screen (sjasmplus enforces that).
  15. ;
  16. ; More detailed description of each command follows:
  17. ;
  18. ;     SAVENEX OPEN <filename>[,<startAddress>[,<stackAddress>[,<entryBank 0..111>]]]
  19. ; Opens a NEX file, defines start address and stack address (if omitted, start address is
  20. ; zero = no start, stack address is 0xFFFE, entryBank is zero), and 16k bank to be mapped
  21. ; at 0xC000 before code is started.
  22. ;
  23. ; Only single NEX file can be open at the same time, and to finalize the header content
  24. ; the command CLOSE has to be used (does auto-close if source ends).
  25. ;
  26. ; Entry bank is number of 16k bank (0..111), not native 8k page, default is zero, i.e.
  27. ; the default memory map is identical to ZX 128 (ROM, RAM banks 5, 2 and 0).
  28. ;
  29. ; Make sure your new stack has at least tens of bytes available as those will be used
  30. ; already by the NEX loader before executing your entry point (although released back).
  31. ;
  32. ;     SAVENEX CORE <major 0..15>,<minor 0..15>,<subminor 0..255>
  33. ; Set minimum required Next core version, can be set any time before CLOSE.
  34. ;
  35. ;     SAVENEX CFG <border 0..7>[,<fileHandle 0/1/$4000+>[,<PreserveNextRegs 0/1>[,<2MbRamReq 0/1>]]]
  36. ; Set border colour (during loading), whether the machine should be set to default state
  37. ; (PreserveNextRegs = 0 = default), if the app requires extended RAM (224 8k pages) and
  38. ; how the file handle of the NEX file should be treated: 0 = default = close, 1 = keep
  39. ; open and pass in BC, $4000..$FFFE = keep open, and write into memory at provided address
  40. ; (after entry bank is paged in). This can be set any time before CLOSE.
  41. ;
  42. ;     SAVENEX BAR <loadBar 0/1>,<barColour 0..255>[,<startDelay 0..255>[,<bankDelay 0..255>]]
  43. ; Loading-bar related setup ("colour" usage depends on screen mode), can be set any time
  44. ; before CLOSE.
  45. ;
  46. ;     SAVENEX SCREEN L2 [<Page8kNum 0..223>,<offset>[,<palPage8kNum 0..223>,<palOffset>]]
  47. ; Layer 2 loading screen, can be used between OPEN and first AUTO/BANK command.
  48. ;
  49. ; Palette consists of 512 bytes (256 palette items from index 0), in 9b colour format:
  50. ; first byte is %RRRGGGBB, second byte is %P000000B (P is priority flag for Layer 2 colours).
  51. ;
  52. ; Image data are 48kiB block of memory, the loader will use always banks 9..11 to display
  53. ; it (8k pages 18..23), but if you will prepare the data there, it will be also re-saved
  54. ; by AUTO command, so either use other banks, and overwrite them with valid data/code
  55. ; after using the SCREEN command, or reset pages 18..23 to zero after SCREEN.
  56. ;
  57. ; If no memory address is specified, the pages 18..23 are stored in file, and if no
  58. ; palette address is specified, no-palette flag is set in NEX file.
  59. ;
  60. ;     SAVENEX SCREEN LR [<Page8kNum 0..223>,<offset>[,<palPage8kNum 0..223>,<palOffset>]]
  61. ; LoRes (128x96) loading screen, can be used between OPEN and first AUTO/BANK command.
  62. ;
  63. ; Palette is similar to Layer 2 mode, just LoRes mode doesn't have priority bit.
  64. ;
  65. ; Image data are 12288 bytes memory block - either consecutive block if specific address
  66. ; is provided, or without address the actual bank 5 memory is stored (taking 6144 bytes
  67. ; from address 0x4000 and 6144 bytes from address 0x6000).
  68. ;
  69. ;     SAVENEX SCREEN (SCR|SHC|SHR) [<hiResColour 0..7>]
  70. ; ULA/Timex modes loading screen, can be used between OPEN and first AUTO/BANK command.
  71. ;
  72. ; The actual bank 5 memory (pages 10..11) is stored as if the image is displayed, in
  73. ; these modes the palette can't be specified.
  74. ;
  75. ; SCR is classic ZX 6912 bytes long screen from address 0x4000 (page 10 is used, even
  76. ; if the slot 1 is modified to other page, so you must prepare the image "in place").
  77. ;
  78. ; SHC and SHR are Timex HiColor (8x1 attribute) and HiRes (512x192 bitmap) modes, prepare
  79. ; data "in place", i.e. 6144 bytes into page 10 and 6144 bytes into page 11 (0x4000 and
  80. ; 0x6000 addresses in default memory setup). For HiRes mode you should specify ink colour
  81. ; (the paper is complement of ink).
  82. ;
  83. ;     SAVENEX BANK <bank 0..111>[,...]
  84. ; Can be used after OPEN or SCREEN and before CLOSE, but the 16ki banks must be saved in
  85. ; correct order: 5, 2, 0, 1, 3, 4, 6, 7, ..., 111
  86. ;
  87. ;     SAVENEX AUTO [<fromBank 0..111>[,<toBank 0..111>]]
  88. ; Can be used after OPEN or SCREEN and before CLOSE. The sjasmplus will save every
  89. ; 16k bank containing at least one non-zero byte; detected in the correct order
  90. ; (automatically starting from first possible bank after previous BANK/AUTO commands,
  91. ; or from provided "fromBank").
  92. ;
  93. ; For "fromBank" value use the specified order above in BANK command, i.e. 5, 2, 0, ...
  94. ;
  95. ;     SAVENEX CLOSE [<fileToAppend>]
  96. ; Can be used after OPEN. The currently open NEX file will be finalized (header adjusted),
  97. ; and optional extra file just appended to the end of NEX file.
  98.  
  99.     DEVICE NONE     ; correct commands, but outside of NEXT device
  100.     SAVENEX     OPEN    "savenexSyntax.nex",    $8000,$FFE0,    15  ; not in NEXT mode
  101.  
  102.     DEVICE ZXSPECTRUMNEXT
  103.     SAVENEX NEPO    ; wrong command
  104.  
  105. ;; OPEN <filename>[,<startAddress>,<stackAddress>[,<entryBank 0..111>]]
  106.     ; errors - [un]expected arguments
  107.     SAVENEX
  108.     SAVENEX                 ; no command, but with comment
  109.     SAVENEX     OPEN
  110.     SAVENEX     OPEN    "savenexSyntax.nex",
  111.     SAVENEX     OPEN    "savenexSyntax.nex",    $8000,
  112.     SAVENEX     OPEN    "savenexSyntax.nex",    $8000,$FFE0,
  113.     SAVENEX     OPEN    "savenexSyntax.nex",    $8000,$FFE0,    15,
  114.     SAVENEX OPEN "savenexSyntax.nex", $7170, $F1F0, 112 ; error entryBank
  115.  
  116.     ; one correct NEX file to verify simple case (but induce all sorts of warnings)
  117.     SAVENEX     OPEN    "savenexSyntax.nex",    $18180,$1F1F0,  'B'
  118.  
  119.     ; error = NEX file is already open
  120.     SAVENEX     OPEN    "savenexSyntax.nex", $8180, $F1F0, 'B'
  121.  
  122. ;; CORE <major 0..15>,<minor 0..15>,<subminor 0..255>
  123.     ; errors - [un]expected arguments
  124.     SAVENEX     CORE
  125.     SAVENEX     CORE    0
  126.     SAVENEX     CORE    0,
  127.     SAVENEX     CORE    0,0
  128.     SAVENEX     CORE    0,0,
  129.     SAVENEX     CORE    0,0,0,
  130.  
  131.     ; one correct + one with warnings
  132.     SAVENEX     CORE    15,15,255
  133.     SAVENEX     CORE    'a','b',$100+'c'    ; warn about values
  134.  
  135. ;; CFG <border 0..7>[,<fileHandle 0/1/$4000+>[,<PreserveNextRegs 0/1>[,<2MbRamReq 0/1>]]]
  136.     ; errors - [un]expected arguments
  137.     SAVENEX     CFG
  138.     SAVENEX     CFG     5,
  139.     SAVENEX     CFG     5,  1,
  140.     SAVENEX     CFG     5,  1,  1,
  141.     SAVENEX     CFG     5,  1,  1,  1,
  142.  
  143.     ; correct ones with value warnings, and omitting optional arguments
  144.     SAVENEX     CFG     9
  145.     SAVENEX     CFG     5,  -1
  146.     SAVENEX     CFG     5,  1,  2
  147.     SAVENEX     CFG     5,  "hf",  1,  1    ; one completely correct (no warning)
  148.     SAVENEX     CFG     5,  "hf",  1,  'R'
  149.  
  150. ;; BAR <loadBar 0/1>,<barColour 0..255>[,<startDelay 0..255>[,<bankDelay 0..255>]]
  151.     ; errors - [un]expected arguments
  152.     SAVENEX     BAR
  153.     SAVENEX     BAR     1
  154.     SAVENEX     BAR     1,
  155.     SAVENEX     BAR     1,  'L',
  156.     SAVENEX     BAR     1,  'L',    'D',
  157.     SAVENEX     BAR     1,  'L',    'D',    'd',
  158.  
  159.     ; correct ones with value warnings, and omitting optional arguments
  160.     SAVENEX     BAR     2,  255
  161.     SAVENEX     BAR     1,  256
  162.     SAVENEX     BAR     1,  255, 256
  163.     SAVENEX     BAR     1,  255, 255, 256
  164.     SAVENEX     BAR     1,  'L',    'D',    'd' ; one fully valid (no warning)
  165.  
  166. ;; SCREEN L2 [<Page8kNum 0..223>,<offset>[,<palPage8kNum 0..223>,<palOffset>]]
  167.     ; errors - [un]expected arguments
  168.     SAVENEX     SCREEN
  169.     SAVENEX     SCREEN  NEERCS
  170.     SAVENEX     SCREEN  L2  9
  171.     SAVENEX     SCREEN  L2  9 ,
  172.     SAVENEX     SCREEN  L2  9 ,    $1FFF ,
  173.     SAVENEX     SCREEN  L2  9 ,    $1FFF ,  10
  174.     SAVENEX     SCREEN  L2  9 ,    $1FFF ,  10 ,
  175.     SAVENEX     SCREEN  L2  9 ,    $1FFF ,  10 ,    $1800,
  176.  
  177.     ; errors - wrong values
  178.     SAVENEX     SCREEN  L2 224, 0, 0, 0     ; pagenum outside of range
  179.     SAVENEX     SCREEN  L2 0, 0, 224, 0     ; pagenum outside of range
  180.     SAVENEX     SCREEN  L2 218, 1, 0, 0     ; values in range, but leaks out of memory
  181.     SAVENEX     SCREEN  L2 0, $1B4001, 0, 0 ; values in range, but leaks out of memory
  182.     SAVENEX     SCREEN  L2 0, 0, 223, 7681  ; values in range, but leaks out of memory
  183.     SAVENEX     SCREEN  L2 0, 0, 0, $1BFE01 ; values in range, but leaks out of memory
  184.     SAVENEX     SCREEN  L2 218, 1           ; values in range, but leaks out of memory
  185.     SAVENEX     SCREEN  L2 0, $1B4001       ; values in range, but leaks out of memory
  186.     ; not testing correct variants, because it would make impossible to test other types
  187.  
  188. ;; SCREEN LR [<Page8kNum 0..223>,<offset>[,<palPage8kNum 0..223>,<palOffset>]]
  189.     ; errors - [un]expected arguments
  190.     SAVENEX     SCREEN  LR  5
  191.     SAVENEX     SCREEN  LR  5 ,
  192.     SAVENEX     SCREEN  LR  5 ,    $1FFF ,
  193.     SAVENEX     SCREEN  LR  5 ,    $1FFF ,  10
  194.     SAVENEX     SCREEN  LR  5 ,    $1FFF ,  10 ,
  195.     SAVENEX     SCREEN  LR  5 ,    $1FFF ,  10 ,    $1800,
  196.  
  197.     ; errors - wrong values
  198.     SAVENEX     SCREEN  LR 224, 0, 0, 0     ; pagenum outside of range
  199.     SAVENEX     SCREEN  LR 0, 0, 224, 0     ; pagenum outside of range
  200.     SAVENEX     SCREEN  LR 222, $1001, 0, 0 ; values in range, but leaks out of memory
  201.     SAVENEX     SCREEN  LR 0, $1BD001, 0, 0 ; values in range, but leaks out of memory
  202.     SAVENEX     SCREEN  LR 0, 0, 223, 7681  ; values in range, but leaks out of memory
  203.     SAVENEX     SCREEN  LR 0, 0, 0, $1BFE01 ; values in range, but leaks out of memory
  204.     SAVENEX     SCREEN  LR 222, $1001       ; values in range, but leaks out of memory
  205.     SAVENEX     SCREEN  LR 0, $1BD001       ; values in range, but leaks out of memory
  206.     ; not testing correct variants, because it would make impossible to test other types
  207.  
  208. ;; SCREEN (SCR|SHC|SHR) [<hiResColour 0..7>]
  209.     ; there's basically no syntax error possible with these
  210.  
  211. ;; BANK <bank 0..111>[,...]
  212.     ; errors - invalid/missing arguments (will eventually also save some banks correctly)
  213.     SAVENEX     BANK    ()
  214.     SAVENEX     BANK    -1
  215.     SAVENEX     BANK    112
  216.     SAVENEX     BANK    5,                  ; bank 5 will be stored
  217.     SAVENEX     BANK    0, 2, 3             ; bank 0 will be stored, 2 = wrong order
  218.  
  219.     ; revisit screen errors - here no screen should work because bank was written already
  220.     SAVENEX     SCREEN  L2
  221.     SAVENEX     SCREEN  LR
  222.     SAVENEX     SCREEN  SCR
  223.     SAVENEX     SCREEN  SHC
  224.     SAVENEX     SCREEN  SHR 10
  225.  
  226. ;; AUTO [<fromBank 0..111>[,<toBank 0..111>]]
  227.     SAVENEX     AUTO    21,
  228.     SAVENEX     AUTO    21,     25,
  229.     SAVENEX     AUTO    -1, 20
  230.     SAVENEX     AUTO    112, 20
  231.     SAVENEX     AUTO    21, -1
  232.     SAVENEX     AUTO    21, 112
  233.     SAVENEX     AUTO    21, 20
  234.     SAVENEX     AUTO    5, 1                ; already stored by BANK above
  235.     SAVENEX     AUTO    0, 1
  236.     SAVENEX     AUTO    1, 1                ; correct one (but bank is zeroed = no output)
  237.     SAVENEX     AUTO    1, 1                ; but disabled for second try
  238.     SAVENEX     AUTO                        ; correct (but all zeroes = no output)
  239.     SAVENEX     AUTO                        ; but all are disabled now
  240.  
  241. ;; CLOSE [<fileToAppend>]
  242.     SAVENEX     CLOSE   "savenexSyntax.asm" ; correct one (there's not much to do wrong
  243.     SAVENEX     CLOSE                       ; should be error (no NEX is open)
  244.  
  245. ;; create small NEX for BIN comparison, if the thing at least somewhat works
  246. ;; also verify it works twice per source (in sequential order)
  247.     SAVENEX OPEN "savenexSyntax.bin", $5000
  248.     SAVENEX CORE 2,0,28 : SAVENEX CFG 4,0,0,1 : SAVENEX BAR 0,0,100,0
  249.     ORG $4800 : DB $45, $5F, $F5, $44
  250.     ORG $5000 : jr $                        ; infinite JR loop
  251.     SAVENEX AUTO 5, 5                       ; should store bank5
  252.     ; let it close automatically by ending source
  253.  
  254.     END $7170       ; invoke warning about different start address
  255.