<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<book id="sjasmplus_manual">
<title>SjASMPlus 1.20.1 Documentation [2022-07-29]</title>
<chapter id="introduction">
<title>Introduction</title>
<section id="license">
<title>License</title>
<para>SjASMPlus is licensed under BSD license.</para>
</section>
<section id="about">
<title>What is it?</title>
<para>
SjASMPlus is Z80 Assembly Language Cross Compiler. It is available
for Win32, Linux and FreeBSD (mainly 5.x) systems. It is based on SjASM
source code by Sjoerd Mastijn (<ulink url="http://xl2s.tk">http://xl2s.tk</ulink>).
</para>
</section>
<section id="features">
<title>Main Features</title>
<para><itemizedlist>
<listitem>
<para>Full source of assembler available under BSD license, modify and extend as you wish</para>
</listitem>
<listitem>
<para>Z80/R800/Z80N/i8080/LR35902 documented and undocumented opcodes support</para>
</listitem>
<listitem>
<para>Macro language, defines, array of defines</para>
</listitem>
<listitem>
<para>Built-in Lua scripting engine</para>
</listitem>
<listitem>
<para>Conditional assembly, block repeating</para>
</listitem>
<listitem>
<para>Modules (namespaces), local and temporary labels</para>
</listitem>
<listitem>
<para>Source and binary file inclusion, include paths</para>
</listitem>
<listitem>
<para>Multi file output, file updating, various types of exports</para>
</listitem>
<listitem>
<para>Structures to work easily with structured data in memory</para>
</listitem>
<listitem>
<para>Relocation data generator to support SymbOS-like relocation of executables</para>
</listitem>
<listitem>
<para>Virtual device mode for common machines: ZX 128, ZX Next, Amstrad CPC, … (pseudo op DEVICE)</para>
</listitem>
<listitem>
<para>ZX Spectrum specific directives and pseudo ops (SAVESNA, SAVETAP, SAVEHOB, INCHOB, INCTRD…)</para>
</listitem>
<listitem>
<para>ZX Spectrum Next specific features and directives (Z80N, 8ki memory paging, SAVENEX)</para>
</listitem>
<listitem>
<para>Amstrad CPC 464/6128 specific directives (SAVECPCSNA)</para>
</listitem>
<listitem>
<para>Correctness is assured by <ulink url="https://cirrus-ci.com/github/z00m128/sjasmplus/master">
Cirrus-CI with 400+ automated tests</ulink> (that's also 400+ examples of usage!)</para>
</listitem>
<listitem>
<para>Fake instructions as LD HL,DE (LD H,D:LD L,E) and more</para>
</listitem>
<listitem>
<para>Code inlining through colon (LD A,C:INC A:PUSH AF:IFDEF FX:LD A,D:ENDIF…)</para>
</listitem>
<listitem>
<para>Very fast compilation: 1 million lines by 2-3 seconds on modern computer</para>
</listitem>
<listitem>
<para>Multiline block comments and user’s messages</para>
</listitem>
</itemizedlist></para>
</section>
<section id="credits">
<title>Credits</title>
<para>Special thanks to <emphasis>Sjoerd Mastijn</emphasis>, the author of SjASM.</para>
<para><emphasis>Aprisobal </emphasis>- main programming, documentation, etc.</para>
<para>Thanks to:<itemizedlist>
<listitem>
<para><emphasis>Kurles/HS/CPU, Alexander Kovalenko, Ped7g, Dart Alver, Oli Wilkinson</emphasis> - additional
programming;</para>
</listitem>
<listitem>
<para><emphasis>Krystian Wlosek
<kwlosek(at)gmail.com></emphasis> - bug fix patches, Linux
makefile;</para>
</listitem>
<listitem>
<para><emphasis>Ric Horne <Ric.Hohne@eads-ts.com></emphasis>
- bug fix patches.</para>
</listitem>
<listitem>
<para><emphasis>breeze <breeze@tut.by></emphasis> - bug fix
patches.</para>
</listitem>
<listitem>
<para><emphasis>psndcj <psndcj.tbk@gmail.com></emphasis> -
bug reporting, beta-testing.</para>
</listitem>
<listitem>
<para><emphasis>elfh <elphecy@gmail.com></emphasis> - bug
reporting.</para>
</listitem>
<listitem>
<para><emphasis>bugsy <bugsy@ya.ru></emphasis> - bug
reporting.</para>
</listitem>
<listitem>
<para><emphasis>skrju <sq-@mail.ru></emphasis> - bug
reporting.</para>
</listitem>
<listitem>
<para><emphasis>Tygrys, UB880D, Cizo, mborik, z00m</emphasis> -
compilation errors and warnings clean up, makefiles, testing.</para>
</listitem>
<listitem>
<para><emphasis>Antipod, boo_boo, PulkoMandy, Busy, Liniya, LVD</emphasis> -
bug fix patches, testing.</para>
</listitem>
<listitem>
<para><emphasis>CKirby</emphasis> - SLD export and support in his tools.</para>
</listitem>
<listitem>
<para><emphasis>Simon Brattel</emphasis> - for creating mother of all assemblers Zeus
and bringing all the good and peace to the mankind, giving infinite inspiration
to sjasmplus contributors who stole his tremendously amazing features without
even crediting him - till now, fixed (not sure what the particular list of features
was copied from Zeus, I guess DG/DH, I believe some other similarities are rather
copied from the ALASM which had many features before Zeus, but who knows, too late
to track it all precisely, what happened in 90's and when).</para>
</listitem>
</itemizedlist></para>
<para>Big thanks to all people, who helped on development of the compiler!</para>
</section>
<section id="feedback">
<title>Feedback</title>
<para>WWW: <ulink
url="https://github.com/z00m128/sjasmplus">https://github.com/z00m128/sjasmplus</ulink>
(newer versions maintained by z00m and others)</para>
<para>WWW: <ulink
url="https://sourceforge.net/projects/sjasmplus/">https://sourceforge.net/projects/sjasmplus/</ulink>
(original Aprisobal's source)</para>
<para>E-Mail: zoom@centrum.sk, my@aprisobal.by</para>
</section>
<section id="news">
<title>What's new?</title>
<para><variablelist>
<varlistentry>
<term>WIP - 1.20.2</term>
<listitem>
<synopsis>- added optional second argument for <link linkend="po_dup">`DUP`</link> to have index variable
- fixing variable name-clash when compiling against musl-clib
- LuaBridge updated to version 2.8
- minor bugfixes/improvements in parser in specific edge cases
</synopsis>
</listitem>
</varlistentry>
<varlistentry>
<term>29.7.2022 - 1.20.1</term>
<listitem>
<synopsis>- parse decimal <link linkend="s_numeric">numeric constants</link> with warning (for easier Lua 5.4 life)
- added <link linkend="po_saveamsdos">`SAVEAMSDOS`</link> (like SAVEBIN with AMSDOS header)
- added "smart" <link linkend="s_labels">SMC offset</link> syntax for self-modify-code labels: `abc+*: or 123`
- added <link linkend="po_defdevice">`DEFDEVICE`</link> to define custom devices
- Makefile cleanup
</synopsis>
</listitem>
</varlistentry>
<varlistentry>
<term>13.6.2022 - 1.20.0</term>
<listitem>
<synopsis>- Lua: <link linkend="c_lua_scripting">upgrade to 5.4</link>, replacing tolua++ bindings with LuaBridge2.6 library, extending some bindings
- Lua: bindings slightly modified (required by upgrade), refreshed docs, added test coverage
- Lua: the 3rd party extensions (BTW not working for many years) are obsolete in 5.4 and removed
- Lua: more accurate errors/warning location reported even in complex cases
- warnings: added -Wall, --help=warnings shows on/off status, rdlow off by default
- Added HIGH mode to <link linkend="po_relocate_start">relocation data generator</link> (MSB-only relocation mode)
- many open-file "fatal" errors become "non-fatal", assembling will continue
- deprecated features removed: --syntax=m, label `abs` in expressions
- `--color=auto` will stay no-color when <ulink url="https://no-color.org/">env.var. `NO_COLOR`</ulink> is defined
- refactorings, improving some error messages and parsing, small fixes in parsing logic
- fix listing of Lua's sj.parse_code (eol-comments), minor memory leaks fixed
- fix relocation of temporary labels in expressions
- invalid CLI options are reported as regular errors (also changing exit code)
- errors are colored similarly to gcc (only keyword has color), console input name is `<stdin>`
</synopsis>
</listitem>
</varlistentry>
<varlistentry>
<term>31.3.2022 - 1.19.0</term>
<listitem>
<synopsis>- added Amstrad CPC devices (<link linkend="po_device">"AMSTRADCPC464", "AMSTRADCPC6128"</link>) - by Oli Wilkinson
- added Amstrad CPC save snapshot and CDT (<link linkend="po_savecpcsna">`SAVECPCSNA`</link>, <link linkend="po_savecdt">`SAVECDT`</link>) - by Oli Wilkinson
- added <link linkend="po_save3dos">`SAVE3DOS`</link> (like SAVEBIN with +3DOS header)
- the deprecated "ok" warning suppression is removed, use "<warning-id>-ok" comment or -Wno-...
- new <link linkend="s_temp_labels">temporary label</link> suffix syntax "_b" and "_f", enabling them for all expressions
- fix `--longptr` mode to keep 32b address when `DS 0` is used
- added fake instructions adc|add|sbc|sub de,bc|de|hl|sp
- dec|inc|pop|push will accept also single-comma multiarg in --syntax=a mode
- DUP/REPT will now accept also zero count (skipping the block)
- DEFL labels can be defined even as late as in last pass
- bugfixes (macros, listing, file names in errors, SLD reversepop data)
</synopsis>
</listitem>
</varlistentry>
<varlistentry>
<term>29.8.2021 - 1.18.3</term>
<listitem>
<synopsis>- added <link linkend="s_cli">`--color`</link> to enable/disable ANSI coloring of errors/warnings
- added <link linkend="s_cli">`--syntax=s`</link> mode to disable sub-word substitutions of DEFINEs
- added at-sign prefix for <link linkend="s_local_labels">macro local labels</link> to act as non-macro local label
- <link linkend="po_savetrd">`SAVETRD`</link> accepts names containing dot ("z.x.B" is "z.x" with extension "B") - by Dart Alver
- <link linkend="po_savetrd">`SAVETRD`</link> has optional argument to save BASIC with variables (length_minus_variables)
- minor bugfixes (conditional block parser)
</synopsis>
</listitem>
</varlistentry>
<varlistentry>
<term>14.2.2021 - 1.18.2</term>
<listitem>
<synopsis>- [may break old sources] new <link linkend="s_expressions">exist operator</link> to check label existence
- the --syntax=i mode makes now also register parsing case insensitive
- minor bugfixes (predefined values, savenex BMP loader less strict about "colors used" content)
</synopsis>
</listitem>
</varlistentry>
<varlistentry>
<term>23.1.2021 - 1.18.1</term>
<listitem>
<synopsis>- Big-Endian hosts support (experimental and not tested continuously)
- added "listall", "listact" commands to <link linkend="po_opt">OPT</link> - to switch between listing types
- <link linkend="po_while">`WHILE`</link> has optional argument to set explicit guardian-counter
- <link linkend="po_assert">`ASSERT`</link> has optional argument (to add description/notes for expression)
- <link linkend="po_slot">`SLOT`</link> and <link linkend="po_mmu">`MMU`</link> will now accept also starting address of slot instead of its number
- fix: option --sym was not exporting labels starting with underscore
- fix: SAVENEX BMP-loader bug when certain builds of sjasmplus were unable to open BMP files
- fix: after STRUCT instance the "main" label is not polluted by last field of STRUCT
- minor bugfixes in parser, windows cmake-builds have now icon
- docs: adding "Index" section
- docs: adding some missing information (__DATE__, __TIME__), fixing HTML anchor names
</synopsis>
</listitem>
</varlistentry>
<varlistentry>
<term>12.12.2020 - 1.18.0</term>
<listitem>
<synopsis>- [may break old sources] the colon between end of EQU/DEFL/= expression and instruction is mandatory
- [may break old sources] new <link linkend="s_expressions">abs operator</link> for absolute integer value
- new <link linkend="s_id_warnings">system of warnings</link> (and suppression), the "; ok" comments are now deprecated
- <link linkend="po_display">`DISPLAY`</link> has now also binary and char formatting
- <link linkend="po_define">`DEFINE+`</link> added to [re]define identifier without error
- <link linkend="ca_elseif">`ELSEIF`</link> added to conditional assembling arsenal
- <link linkend="po_while">`WHILE`</link> added for conditional loops
- added <link linkend="po_device">"NOSLOT64K" device</link> with 2MiB of virtual memory
- <link linkend="po_labelslist">`LABELSLIST`</link> has new optional argument to dump 16bit "virtual labels"
- <link linkend="po_cspectmap">`CSPECTMAP`</link> exports STRUCT symbols with more detail (instance labels with physical address)
- <link linkend="s_labels">SMC offset</link> syntax for self-modify-code labels for source brevity
- added exclamation mark prefix for <link linkend="s_local_labels">labels</link> to not affect following local labels
- added "listmc" command to <link linkend="po_opt">OPT</link> - to list only lines with machine code bytes
- added <link linkend="s_cli">`--lstlab=sort`</link> variant to have symbols in listings in predictable order
- minor bugfixes in parser and listing-line-numbering, refactored symbols/labels implementation
- Added <ulink url="https://github.com/z00m128/sjasmplus/tree/master/examples/chargfx2asm">example (chargfx2asm)</ulink> how to use sjasmplus as byte-processor for binary files
- <link linkend="c_sld_data">SLD data</link> improvements based on Maziac's feedback and <ulink url="https://github.com/maziac/DeZog">DeZog</ulink>'s needs
</synopsis>
</listitem>
</varlistentry>
<varlistentry>
<term>8.8.2020 - 1.17.0</term>
<listitem>
<synopsis>- `STRUCT` has new <link linkend="st_text">`TEXT`</link> pseudo-instruction to define "DB-like" data (<ulink url="https://github.com/z00m128/sjasmplus/issues/93">Issue #93</ulink>)
- <link linkend="st_usage">`STRUCT` initializer block</link> can be now multi-line (when correctly enclosed in curly braces)
- <link linkend="po_equ">`EQU`</link> now allows for optional override of page number assigned to the new symbol
- new <link linkend="s_expressions">$$$ and $$$$ operators</link> to retrieve "physical" address/page inside DISP block
- instruction `out (c),0` now emits warning (can be suppressed by the "; ok" comment)
- fixed listing of structures using long BLOCK fields (machine code was correct, but listing not)
- fixed some memory leaks, undefined behaviour and unaligned memory access
</synopsis>
</listitem>
</varlistentry>
<varlistentry>
<term>27.7.2020 - 1.16.0</term>
<listitem>
<synopsis>- <link linkend="po_lua">`LUA`</link> the new emit warning (v1.15.1) is now suppressible
- <link linkend="s_predefined">Predefined defines</link> extended and renamed (following gcc/clang ones)
- Added <link linkend="po_relocate_end">relocation data generator</link> (similar to WinAPE feature), check also <ulink url="https://github.com/z00m128/sjasmplus/tree/master/examples/relocation">example</ulink>
- bugfixes/improvements in parser like: operators `not`, `low`, `high` can be followed also by "("
</synopsis>
</listitem>
</varlistentry>
</variablelist></para>
<para>See <ulink url="https://github.com/z00m128/sjasmplus/blob/master/CHANGELOG.md">CHANGELOG.md</ulink> for full list of changes.</para>
</section>
</chapter>
<chapter id="where_to_get">
<title>Where to get and how to use</title>
<section id="s_packages">
<title>Packages</title>
<para>
The <emphasis role="strong">latest release</emphasis> of this sjasmplus variant is
<emphasis role="strong">available at <ulink url="https://github.com/z00m128/sjasmplus/releases/latest">
https://github.com/z00m128/sjasmplus/releases/latest</ulink></emphasis>
- there is available zip archive with <emphasis role="strong">windows binary</emphasis>
(toward <emphasis role="strong">bottom of the page</emphasis>), and zip archives with
<emphasis role="strong">full source code</emphasis> of the sjasmplus.
</para>
<para>Win32 package has:<itemizedlist>
<listitem>
<para>sjasmplus.exe - the Win32 executable.</para>
</listitem>
<listitem>
<para>examples directory - some examples of use</para>
</listitem>
<listitem>
<para>documentation directory - documentation in various
formats</para>
</listitem>
</itemizedlist>
</para>
<para>
You may want to download also the full source package, as it contains more than 400
<emphasis role="strong">automated tests</emphasis> used to verify correctness of executable,
and these can be often helpful to better understand how specific feature of sjasmplus works,
and <emphasis role="strong">how to use it</emphasis> effectively.
</para>
<para>
<emphasis role="strong">Linux, Unix, MacOS</emphasis> and <emphasis role="strong">BSD</emphasis>
version can be built from the full source archive. You can compile it using <emphasis>GCC</emphasis>
and included <emphasis>Makefile</emphasis>. There is an option to use <emphasis>CMake</emphasis>
for compilation. See
<ulink url="https://github.com/z00m128/sjasmplus/blob/master/INSTALL.md">INSTALL.md</ulink> for details.
</para>
<para>Windows binaries are compiled with <emphasis>MinGW</emphasis> environment and included
<emphasis>Makefile.win</emphasis> file.</para>
<para>You can grab older (up to v1.07) binaries and sources at SourceForge project page:
<ulink url="https://sourceforge.net/projects/sjasmplus/">https://sourceforge.net/projects/sjasmplus/</ulink></para>
</section>
<section id="s_cli">
<title>Command line</title>
<para>Usage:</para>
<synopsis>sjasmplus [options] sourcefile(s)</synopsis>
<para>Option flags as follows:</para>
<para><synopsis> -h or --help[=warnings] Help information
--version Basic info (with --nologo only raw version string)
--zxnext[=cspect] Enable ZX Next Z80 extensions (CSpect emulator has
extra "exit" DD00 and "break" DD01 fake instructions)
--i8080 Limit valid instructions to i8080 only (+ no fakes)
--lr35902 Sharp LR35902/SM83 CPU instructions mode (+ no fakes)
--outprefix=<path> Prefix for save/output/.. filenames in directives
Note: if the prefix is folder, the folder must exist before assembling. Prefix
is applied only to filenames defined in source (not to CLI arguments).
-i<path> or -I<path> or --inc=<path> ( --inc without "=" to empty the list)
Include path (later defined have higher priority)
--lst[=<filename>] Save listing to <filename> (<source>.lst is default)
--lstlab[=sort] Append [sorted] symbol table to listing
--sym=<filename> Save symbol table to <filename>
--exp=<filename> Save exports to <filename> (see EXPORT pseudo-op)
--raw=<filename> Machine code saved also to <filename> (- is STDOUT)
--sld[=<filename>] Save Source Level Debugging data to <filename>
Default name is: "<first input filename>.sld.txt"
Note: use OUTPUT,LUA/ENDLUA and other pseudo-ops to control output
Logging:
--nologo Do not show startup message
--msg=[all|war|err|none|lst|lstlab] Stderr messages verbosity ("all" is default)
Note: "lst" or "lstlab" will turn STDERR into listing file (this will clash with
`--lst`, use only one of the options) and some diagnostic messages of "all"
are omitted, as they are not part of listing files. "lstlab" does sort symbols.
--fullpath Show full path to file in errors
Note: the "fullpath" starts from current working directory, not from file system
root (the MS_VS build was fixed to behave this way since v1.15.0)
--color=[on|off|auto] Enable or disable ANSI coloring of warnings/errors
Note: auto detection checks for existence of environment variable TERM, and its
content is scanned for sub-string "color" (like "xterm-256color")
Other:
-D<NAME>[=<value>] Define <NAME> as <value>
-W[no-]<warning_id> Disables/enabled particular warning type
- Reads STDIN as source (even in between regular files)
--longptr No device: program counter $ can go beyond 0x10000
--reversepop Enable reverse POP order (as in base SjASM version)
--dirbol Enable directives processing from the beginning of line
--nofakes Disable fake instructions (same as --syntax=F)
--dos866 Encode from Windows codepage to DOS 866 (Cyrillic)
--syntax=<...> Adjust parsing syntax, read details below.</synopsis></para>
<para>
The option <code>--lstlab=sort</code> will cause also other symbol dumps being sorted (along
listing): <code>--sym</code>, <code>CSPECTMAP</code> and <code>LABELSLIST</code>.
The <code>--msg=lstlab</code> sets always sorting "on" (no "unsorted" option).
</para>
<para>Value for <code>--syntax</code> option may consist of multiple letters, omitting letter
for particular feature will use the default setting:
<synopsis> a Multi-argument delimiter ",," (default is ",") (but dec|inc|pop|push accept also ",")
b Whole expression parentheses are legal for memory access only (default = immediate or memory)
B memory access brackets [] required (default = relaxed syntax, [] allowed as extra)
f F Fake instructions: warning / disabled (default = enabled)
i Case insensitive instructions/directives (default = same case required)
† <emphasis>l L Keyword labels (registers, instructions, ...): warning / error (default = silent)</emphasis>
M Alias "m" and "M" for "(hl)" to cover 8080-like syntax: ADD A,M
s Use only "simple" whole-word substitutions, no sub-words (since v1.18.3)
w Warnings option: report warnings as errors
m *REMOVED* in v1.20.0, use -Wno-rdlow</synopsis>
† work in progress: options "l" and "L" are not implemented yet, following example is then
not working correctly either.
</para>
<para>
I.e. <code>--syntax=faBil</code> will modify parser to process source line
<programlisting>hl: Ld a,(hl),,de,hl</programlisting>
in a way to produce warnings about keyword "hl" being used for label, about fake instruction
being used (ld de,hl) and assemble <code>(hl)</code> as numeric expression, not memory access.
Warnings on fake instructions can be suppressed for particular line by adding any end-of-line
comment containing string "fake", i.e. "<code>ld de,hl ; fake DE=HL</code>" will assemble
without warning. The "F" option is identical to "--nofakes" and preferred.
</para>
<para>
The recommended setup for new projects is <code>--syntax=abfw</code> which makes syntax less relaxed,
so some typos and mistakes are easier to catch, for example:
<programlisting> OPT reset --syntax=abfw
label: dw 15
ld b,(label)
sub a,b</programlisting> will produce "error: Illegal instruction
(can't access memory): (label)" message for the <code>ld b,(label)</code> and the <code>sub a,b</code>
will produce only the <code>sub b</code> instruction (to give the <code>sub</code> multi-argument
with syntax option "a" the line would have to be <code>sub a,,b</code>).
</para>
<para>
The assembler will also read the environment variable <code>SJASMPLUSOPTS</code> (if available),
and process its content as part of command line options (before the actual options), so you
can pre-configure certain options in your environment, for example:
<programlisting>export SJASMPLUSOPTS="--zxnext=cspect --msg=war"
sjasmplus --lst --lstlab example.asm</programlisting>
will execute the assembling as if command line "<code>sjasmplus --zxnext=cspect --msg=war --lst --lstlab example.asm</code>"
was used. Known issue: parser of environment variable delimits each option on any white-space character, so
option containing space character will be incorrectly parsed (like "-Ifile-path with space" = fails and
there is no way to escape/quote the path in the SJASMPLUSOPTS variable to make it work).
</para>
</section>
<section id="s_id_warnings">
<title>Warnings with id</title>
<para>
Some warnings have own "id" - these can be switched off or suppressed for particular line.
The line suppression mechanism requires you to add end-of-line comment with "id-ok" string
somewhere in the comment (exception: for fake instructions and --syntax=f mode the word
"fake" is enough without -ok suffix) (the "ok" comment suppression mechanism from previous
versions of sjasmplus is removed since v1.19.0).
</para>
<para>
The id-warning is emitted together with its id in brackets:
<programlisting> ld a,(10-2) ; read memory address 8 - emits warning "rdlow"
ld a,(10-2) ; same instruction, but suppress warning: rdlow-ok
file.asm(1): warning[rdlow]: Reading memory at low address: 8</programlisting>
To list all warning-ids, their on/off state and short description of each use:
<programlisting><command line>$ sjasmplus --help=warnings</programlisting>
Most of the extra warnings are by default enabled, but to enable/disable all of them you can use (also in source with OPT directive):
<programlisting><command line>$ sjasmplus -Wall
<command line>$ sjasmplus -Wno-all</programlisting>
To disable particular warning globally you can use option <code>-Wno-<id></code>,
either on command line, or from source by using <code><link linkend="po_opt">OPT</link></code>:
<programlisting><command line>$ sjasmplus -Wno-out0
; in source code:
OPT -Wno-trdext -Wno-trdext3 ; disable "trdext" and "trdext3" warnings
SAVETRD "image.trd", "file.txt", 30000, 100
OPT -Wtrdext3 ; re-enable "trdext3" warning for following code
; ...</programlisting>
</para>
<para>
Warnings without id can't be suppressed and generally should happen only when the source
code has actual bug (in our opinion) and can be modified to fix the warning, or when you
are hitting limits of sjasmplus architecture and/or implementation.
</para>
<para>
If you believe you are hitting warning without id on correct code, which can be safely
ignored (the machine code produced is stable and as expected), open issue on github with
example source, so we can assign the warning new id (or explain why it is problematic :) ).
</para>
<para>
Warnings with id usually signal bug in the code (in common scenarios), but may be misleading
in more specialized cases - the decision is left to the author, whether to modify
the code to avoid the warning or suppress it and use the resulting machine code "as is".
</para>
</section>
<section id="s_source_format">
<title>Source file format</title>
<para>
Lines in the source file should have the following form:
<programlisting>Label Operator Operand Comment</programlisting>
All fields are optional.
<emphasis role="strong">Lines without label should start with whitespace.</emphasis>
Operators and operands can be inlined with colon:
<programlisting> Operator Operand:Operator Operand:Operator Operand... Comment</programlisting>
Comments should start with '<code>;</code>' or '<code>//</code>'.
Comment blocks start with '<code>/*</code>' and end with '<code>*/</code>' (work in "nested" way,
i.e. comment block started inside comment block must be also ended, before main block ends).
<example>
<title></title>
<programlisting>; comment
// comment
ld /* comment */ a,80
/*
comment /* nested comment block */
*/
ld /*
but this won't be ld a,3!
*/ a,3</programlisting>
</example>
</para>
</section>
</chapter>
<chapter id="c_labels">
<title>Labels</title>
<section id="s_labels">
<title>Labels</title>
<para>Labels are case-sensitive and may be of any reasonable length,
that is: up to about 70 characters. Label definitions must start on
the beginning of a line, but don't have to be followed by a colon ':'.
Generally labels should start with a letter or a underscore ('_'), the
following characters may be chosen from letters, numbers and the
following special symbols: '_', '.', '!', '?', '#' and '@'. Note that
the '.' has special meaning, as it is used between module names, labels
and local labels. The following are all legal and distinct
labels:<programlisting>Kip
KIP
Kip@@
MAIN.loop?</programlisting>It is possible to use mnemonics, pseudo-ops and
register names as labels but it is not advised to do so (expression operator keyword used
as label will emit warning, and is also not advised). Also note that
the identifiers defined with the DEFINE pseudo-op use another name
space.</para>
<para>(since v1.18.0) Right after label (before the optional colon) you
can write extra "SMC offset" (Self Modify Code offset) in the form of plus
sign and single decimal digit. The defined label will become equal to current
address plus the SMC offset:
<programlisting> ; SMC-offset syntax is very strict, no spacing, single '+', single digit
answer+1: ld a,13 ; "answer" points second opcode byte
; this helps to keep the SMC-label together with the target instruction
ld hl,answer
ld (hl),42 ; fix immediate in `ld a,*` to correct answer
; compare with classic syntax:
classic equ $+1 : ld a,7 ; often even split to two lines</programlisting>
</para>
<para>(since v1.20.1) Smart SMC labels: you can write "plus asterisk" to let sjasmplus adjust
self-modify label by most likely offset for following instruction. This works only
for instructions with "obvious" target immediate value:
<programlisting> ; smart-SMC syntax is very strict, no spacing, single '+', single '*'
answer+*: ld a,13 ; "answer" points second opcode byte
; this helps to keep the SMC-label together with the target instruction
ld hl,answer
ld (hl),42 ; fix immediate in `ld a,*` to correct answer
; few more examples which byte the "smart SMC" will target in the opcode
jptarget+*: jp nz,12345 ; "jptarget" points at second opcode byte (word value 12345)
ixvalue+*: ld ix,12345 ; "ixvalue" points at third opcode byte (word value 12345)
nxtrval+*: nextreg $44,123 ; "nxtrval" points at fourth opcode byte (byte value 123)
; unsupported situations, will cause error
invalid1+*: inc (ix+123) ; IXY displacements are not considered (not significant enough)
invalid2+*: cpl : ld a,14 ; only first instruction after label is considered</programlisting>
</para>
</section>
<section id="s_local_labels">
<title>Local labels</title>
<para>When there is a <link linkend="po_module">module definition</link> all
labels (except those starting with a '@') are local to that module. To
use a label from outside the module use modulename.labelname, in this
example: 'vdp.Cls'. Labels starting with a '.' are also local to the
previous non-local label.</para>
<para>(since v1.18.0) If you start the label with an ! (exclamation mark), it will not
affect following local labels (same syntax as <ulink url="http://www.xl2s.tk/">sjasm</ulink>).</para>
<para>(since v1.18.3) Local label inside macro prefixed with @ (at sign) acts as regular local label,
otherwise (older behaviour) the local label is local to each macro's instance.</para>
<para><example>
<title>docs_examples/s_local_labels.asm</title>
<para><programlisting> MODULE main ; module "main"
Main: ; main.Main
CALL SetScreen ; SetScreen
CALL vdp.Cls ; main.vdp.Cls
.loop: ; main.Main.loop
LD A,(.event) ; main.Main.event
CALL ProcessEvent ; label not found: main.ProcessEvent
DJNZ .loop ; main.Main.loop
MODULE vdp ; module "main.vdp"
@SetScreen: ; SetScreen
.loop: ; main.vdp.SetScreen.loop
RET
Cls: ; main.vdp.Cls
!KeepClsForLocal: ; main.vdp.KeepClsForLocal (since v1.18.0)
.loop: DJNZ .loop ; main.vdp.Cls.loop
RET
ENDMODULE
Main.event DB 0 ; main.Main.event
ENDMODULE</programlisting></para>
</example></para>
<para><example>
<title>local labels inside macro</title>
<programlisting> macro test
.kip0 ; this is local to every instance of macro
@.kip1 ; syntax added in v1.18.3
endm
module main
hoi test ; produce labels: main.hoi, 0>kip0, main.hoi.kip1
endmodule</programlisting>
</example></para>
</section>
<section id="s_at_labels">
<title>@ Labels</title>
<para>Labels starting with a '@' are not touched by the label processing
and used 'as-is'. See 'SetScreen' in the previous example code. <example>
<title>docs_examples/s_at_labels.asm</title>
<para><programlisting> MODULE xxx
Label ; xxx.Label
.Local ; xxx.Label.Local
@Label ; Label
.Local ; xxx.Label.Local => duplicate label error
@Label2 ; Label2
.Local ; xxx.Label2.Local
@yyy.Local ; yyy.Local
yyy.Local ; xxx.yyy.Local</programlisting></para>
</example></para>
</section>
<section id="s_temp_labels">
<title>Temporary labels</title>
<para>To keep the number of used labels reasonable it is possible to use
numbers as labels. These labels can only be used as labels to jump to.
To jump to these labels, use the number followed by an 'F' for forward
branches or a 'B' for backward branches. Temporary labels should be defined
in the same order during every pass of assembling, but they can be used
within macro, or repeating blocks (old sjasmplus versions didn't allow usage within macro).</para>
<para>Since v1.19.0 there is alternative syntax using underscore before 'B' and 'F', this
alternative underscored suffix enables temporary labels also for regular instructions
(in all expressions, same way as other labels).</para>
<para><example>
<title>docs_examples/s_temp_labels.asm</title>
<para><programlisting> ADD A,E
JR NC,1F
INC D
1 LD E,A
2 LD B,4
LD A,(DE)
OUT (152),A
DJNZ 2B
MACRO zing
DUP 2
JR 1F
1 DJNZ 1B
EDUP
ENDM
.4 zing
; since v1.19.0
ld hl,1B ; *old* HL = binary 1, NOT temporary label
ld hl,1_B ; *new* HL = previous temporary label 1
ld hl,1_B*3 ; *new* works also in expressions</programlisting></para>
</example></para>
</section>
</chapter>
<chapter id="c_constants">
<title>Constants, expressions and other features</title>
<section id="s_numeric">
<title>Numeric constants</title>
<para>Numeric constants should always start with a digit or $, # or %.
The following formats are supported:</para>
<para><programlisting>12 decimal
12d decimal
0xc hexadecimal
$c hexadecimal
#c hexadecimal
0ch hexadecimal
0b1100 binary (v1.12.1)
%1100 binary
1100b binary
0q14 octal (v1.12.1)
14q octal
14o octal</programlisting></para>
<para>(v1.12.1) Optional single quotes(') may be inserted between the digits as a separator
(example: <computeroutput> ld a,%11'01'11'00 </computeroutput>).
They are ignored by the assembler.</para>
<para>(v1.20.1) decimal parts are now parsed and ignored (with optional warning), instead of
causing syntax error - this should make life easier when formatting values from Lua script.
It is also possible to fix all Lua scripts to produce only integer values, but if you prefer
to silently ignore the extra decimal part, you can.</para>
</section>
<section id="s_strings">
<title>Character and string constants</title>
<para>Character constants are characters surrounded by single quotes. It
is possible to use double quotes in some cases, but in general it is
better to use single quotes. String constants are characters surrounded
by double quotes. When double quotes are used, the following escape
sequences are recognized:</para>
<para><programlisting>\\ 92
\? 63
\' 39
\" 34
\0 0 ; since v1.11
\A 7
\B 8
\D 127
\E 27
\F 12
\N 10
\R 13
\T 9
\V 11</programlisting><para>Inside single quotes two quotes after each other are
parsed as the apostrophe itself (since v1.11).</para><example>
<title></title>
<para><programlisting> BYTE "stringconstant\n" ; escape sequence assembles to newline
BYTE 'stringconstant\n' ; \n assembles literally as two bytes: '\', 'n'
LD HL,'hl' ; hl = 0x686C = 'l', 'h'
LD HL,"hl" ; hl = 0x686C = 'l', 'h'
LD A,"7" ; not recommended (but works)
LD A,'8' ; recommended
LD A,'\E' ; warning + truncating value to 'E' (0x45)
LD A,'"' ; A = 0x22
LD A,"'" ; A = 0x27
LD A,'''' ; A = 0x27 ; since v1.11</programlisting></para>
</example></para>
</section>
<section id="s_expressions">
<title>Expressions</title>
<para>Expressions are evaluated in signed 32 bits in this version of SjASMPlus (unless explicitly
specified as unsigned, like ">>>" operator), so intermediate values have range -2147483648
to +2147483647.</para>
<para>'$' represents the current program counter. '$$' represents the
current page in the current slot in the <link
linkend="s_realdevice">real device emulation mode</link>, '$$label' evaluates to number of page
where the "label" was defined (only regular labels have meaningful value, labels defined
under DISP mode may return the page specified in DISP itself, EQU/DEFL/... will produce mostly
irrelevant values). '$$$' and '$$$$' can be used inside DISP block to retrieve the "physical"
memory address and page (where the displaced machine code is written to). '{address}' can be used
to read WORD from virtual device memory (correct value is read only in last pass of assembling,
in early passes the zero value is always returned), '{b address}' reads only BYTE.</para>
<para>It is possible to use parenthesis '(' and ')' to override the
precedence of the operators. The following operators may be used in
expressions:</para>
<para><programlisting>norel norel L <indexterm id="op_norel"><primary>norel</primary></indexterm>Label/symbol L will be treated as non-relocatable
exist exist L <indexterm id="op_exist"><primary>exist</primary></indexterm>is label/symbol L defined in source (even when not used) (since v1.18.2)
! !x <indexterm id="op_log_not"><primary>!</primary></indexterm>logical not
~ ~x <indexterm id="op_cpl"><primary>~</primary></indexterm>complement
+ +x does "nothing", can be used to make "+(...)" parse as value (not as memory)
- -x minus
low low x <indexterm id="op_low"><primary>low</primary></indexterm>low 8 bits of 16 bit value or lower part of register pair
high high x <indexterm id="op_high"><primary>high</primary></indexterm>high 8 bits of 16 bit value or higher part of register pair
not not x <indexterm id="op_log_not2"><primary>not</primary></indexterm>logical not
abs abs x <indexterm id="op_abs"><primary>abs</primary></indexterm>absolute value (since v1.18.0)
* x*y <indexterm id="op_mul"><primary>*</primary></indexterm>multiplication
/ x/y <indexterm id="op_div"><primary>/</primary></indexterm>division
% x%y <indexterm id="op_mod"><primary>%</primary></indexterm>modulo
mod x mod y <indexterm id="op_mod2"><primary>mod</primary></indexterm>modulo
+ x+y <indexterm id="op_add"><primary>+</primary></indexterm>addition
- x-y <indexterm id="op_sub"><primary>-</primary></indexterm>subtraction
<< x<<y <indexterm id="op_sla"><primary><<</primary></indexterm>shift left
>> x>>y <indexterm id="op_sra"><primary>>></primary></indexterm>shift right signed
>>> x>>>y <indexterm id="op_srl"><primary>>>></primary></indexterm>shift right unsigned
shl x shl y <indexterm id="op_shl"><primary>shl</primary></indexterm>shift left
shr x shr y <indexterm id="op_shr"><primary>shr</primary></indexterm>shift right signed
<? x<?y <indexterm id="op_min"><primary><?</primary></indexterm>minimum
>? x>?y <indexterm id="op_max"><primary>>?</primary></indexterm>maximum
< x<y <indexterm id="op_lt"><primary><</primary></indexterm>less than
> x>y <indexterm id="op_gt"><primary>></primary></indexterm>greater than
<= x<=y <indexterm id="op_lte"><primary><=</primary></indexterm>equal or less than
>= x>=y <indexterm id="op_gte"><primary>>=</primary></indexterm>equal or greater than
= x=y <indexterm id="op_eq"><primary>=</primary></indexterm>equal
== x==y <indexterm id="op_eq2"><primary>==</primary></indexterm>equal
!= x!=y <indexterm id="op_neq"><primary>!=</primary></indexterm>not equal
& x&y <indexterm id="op_bit_and"><primary>&</primary></indexterm>bitwise and
and x and y <indexterm id="op_bit_and2"><primary>and</primary></indexterm>bitwise and
^ x^y <indexterm id="op_bit_xor"><primary>^</primary></indexterm>bitwise xor
xor x xor y <indexterm id="op_bit_xor2"><primary>xor</primary></indexterm>bitwise xor
| x|y <indexterm id="op_bit_or"><primary>|</primary></indexterm>bitwise or
or x or y <indexterm id="op_bit_or2"><primary>or</primary></indexterm>bitwise or
&& x&&y <indexterm id="op_logic_and"><primary>&&</primary></indexterm>logical and
|| x||y <indexterm id="op_logic_or"><primary>||</primary></indexterm>logical or
$ $ <indexterm id="op_dollar"><primary>$</primary></indexterm>current program counter
$$ $$ <indexterm id="op_dollar2"><primary>$$</primary></indexterm>current page at program counter (in virtual device mode)
$$$ $$$ <indexterm id="op_dollar3"><primary>$$$</primary></indexterm>"physical" program counter (inside DISP block)
$$$$ $$$$ <indexterm id="op_dollar4"><primary>$$$$</primary></indexterm>"physical" memory page (inside DISP block in virtual device mode)
label label value of label (aka symbol), usually memory address
$$lab $$lab <indexterm id="op_label_page"><primary>$$label</primary></indexterm>page of "lab" label (in virtual device mode)
{} {x} <indexterm id="op_read_word"><primary>{..}</primary></indexterm>reads WORD from address x (in virtual device mode, in last pass)
{b} {b x} <indexterm id="op_read_byte"><primary>{b ..}</primary></indexterm>reads BYTE from address x (in virtual device mode, in last pass)
</programlisting></para>
</section>
<section id="s_asm_lang">
<title>Assembly language</title>
<para>This version only accepts Z80 mnemonics. There are some additions
to what I think is standard Z80: <itemizedlist>
<listitem>
<para>'[' and ']' can be used instead of '(' and ')' for
indirection. So <code>LD A,[HL]</code> is the same as <code>LD A,(HL)</code> (does not
apply to IN/OUT ports, those must use '(...)' form)</para>
</listitem>
<listitem>
<para><code>IN F,(C)</code> and <code>OUT (C),0</code> and <code>SLL/SLI</code> can be used
(warning: on some CPU versions of Z80 the OUT (C),0 is working as OUT (C),255).</para>
</listitem>
<listitem>
<para>IXL (or LX, XL), IYL (or LY, YL), IXH (or HX, XH) and IYH
(or HY, YH) registers are supported.</para>
</listitem>
<listitem>
<para>Can write code throught colon: ORG 100h:LD A,10:LD B,10:SUB
B:RET:IFDEF AA:.....</para>
</listitem>
<listitem>
<para>JP HL, JP IX and JP IY may be used instead of JP (HL),
etc.</para>
</listitem>
<listitem>
<para>EX AF,AF or EX AF or EXA may be used instead of EX
AF,AF'.</para>
</listitem>
<listitem>
<para>R800's MULUB and MULUW are recognised (but won't work on
Z80, of course:)</para>
</listitem>
<listitem>
<para>Z80N, i8080 and LR35902 (SM83) modes use the identical Z80 sjasmplus syntax (!), for the
correct (and incorrect) syntax examples of extended opcodes, please check the test files:
Z80N <ulink url="https://github.com/z00m128/sjasmplus/blob/master/tests/z80n/op_zx_spectrum_next_2_00_26.asm">test 1</ulink>
<ulink url="https://github.com/z00m128/sjasmplus/blob/master/tests/z80n/op_next_syntax.lst">test 2</ulink>
and LR35902 (SM83) <ulink url="https://github.com/z00m128/sjasmplus/blob/master/tests/lr35902/LR35902_syntax_by_neo.lst">test 1</ulink>
<ulink url="https://github.com/z00m128/sjasmplus/blob/master/tests/lr35902/LR35902_specifics_exercise.lst">test 2</ulink>
(also for the Z80 syntax examples you can check <ulink url="https://github.com/z00m128/sjasmplus/tree/master/tests/z80">
Z80 tests</ulink>).
</para>
</listitem>
<listitem>
<para>RLC, RRC, RL, RR, SLA, SRA, SLL (SLI), RES, SET undocumented
instructions added.</para>
</listitem>
</itemizedlist><programlisting> SET 4,(IX+4),C ; (aka LD C,SET 4,(IX+4)) is LD C,(IX+4) / SET 4,C / LD (IX+4),C
RRC (IY),A ; (aka LD A,RRC (IY+0)) is LD A,(IY) / RRC A / LD (IY),A</programlisting><itemizedlist>
<listitem>
<para>PUSH and POP can take register lists:</para>
</listitem>
</itemizedlist><programlisting> PUSH AF,BC ; push af / push bc
POP AF,BC ; pop af / pop bc</programlisting><itemizedlist>
<listitem>
<para>and many other instructions support this "multi-argument" syntax:</para>
</listitem>
</itemizedlist><programlisting> LD A,B,B,D,D,H
/* this is:
LD A,B
LD B,D
LD D,H
*/
;or you can write LD A,B:LD B,D:LD D,H
; since v1.13.1 it is possible and *recommended* to change the multi-arg delimiter
; into ",,", to avoid some ambiguities with certain instructions.
OPT --syntax=a
LD A,B,,B,D,,D,H ; same as example above in default syntax
SUB A,B,,C ; = SUB B, SUB C (the default syntax does for SUB A,B two SUBs!)
; since v1.19.0 DEC|INC|POP|PUSH accepts also single-comma in --syntax=a mode
POP bc,de,hl,,af ; both single/double comma works for these four instructions
</programlisting></para>
</section>
<section id="s_fake_instructions">
<title>Fake instructions</title>
<para>Of course the Z80 is only an 8 bit cpu, but sometimes <code>ld hl,de</code>
would be nice. SjASMPlus now 'fakes' some instructions like that. This
improves the readability of the source, but it might not be the fastest
way to get the result. Also possibly some 'new' load instructions do
affect the flags in ways you wouldn't expect. You can use option <code>--syntax=f</code>
to get warnings when fake instruction is used, to avoid using them by accident. Here's the
list:</para>
<para><programlisting>
rl bc ; rl c : rl b
rl de ; rl e : rl d
rl hl ; rl l : rl h
rr bc ; rr b : rr c
rr de ; rr d : rr e
rr hl ; rr h : rr l
sla bc ; sla c : rl b
sla de ; sla e : rl d
sla hl ; add hl,hl
sll bc ; sli c : rl b
sll de ; sli e : rl d
sll hl ; sli l : rl h
sli bc ; sli c : rl b
sli de ; sli e : rl d
sli hl ; sli l : rl h
sra bc ; sra b : rr c
sra de ; sra d : rr e
sra hl ; sra h : rr l
srl bc ; srl b : rr c
srl de ; srl d : rr e
srl hl ; srl h : rr l
ld bc,bc ; ld b,b : ld c,c
ld bc,de ; ld b,d : ld c,e
ld bc,hl ; ld b,h : ld c,l
ld bc,ix ; ld b,xh : ld c,xl
ld bc,iy ; ld b,yh : ld c,yl
ld bc,(hl) ; ld c,(hl) : inc hl : ld b,(hl) : dec hl
ld bc,(ix+nn) ; ld c,(ix+nn) : ld b,(ix+nn+1)
ld bc,(iy+nn) ; ld c,(iy+nn) : ld b,(iy+nn+1)
ld de,bc ; ld d,b : ld e,c
ld de,de ; ld d,d : ld e,e
ld de,hl ; ld d,h : ld e,l
ld de,ix ; ld d,xh : ld e,xl
ld de,iy ; ld d,yh : ld e,yl
ld de,(hl) ; ld e,(hl) : inc hl : ld d,(hl) : dec hl
ld de,(ix+nn) ; ld e,(ix+nn) : ld d,(ix+nn+1)
ld de,(iy+nn) ; ld e,(iy+nn) : ld d,(iy+nn+1)
ld hl,bc ; ld h,b : ld l,c
ld hl,de ; ld h,d : ld l,e
ld hl,hl ; ld h,h : ld l,l
ld hl,ix ; push ix : pop hl
ld hl,iy ; push iy : pop hl
ld hl,(ix+nn) ; ld l,(ix+nn) : ld h,(ix+nn+1)
ld hl,(iy+nn) ; ld l,(iy+nn) : ld h,(iy+nn+1)
ld ix,bc ; ld xh,b : ld xl,c
ld ix,de ; ld xh,d : ld xl,e
ld ix,hl ; push hl : pop ix
ld ix,ix ; ld xh,xh : ld xl,xl
ld ix,iy ; push iy : pop ix
ld iy,bc ; ld yh,b : ld yl,c
ld iy,de ; ld yh,d : ld yl,e
ld iy,hl ; push hl : pop iy
ld iy,ix ; push ix : pop iy
ld iy,iy ; ld yh,yh : ld yl,yl
ld (hl),bc ; ld (hl),c : inc hl : ld (hl),b : dec hl
ld (hl),de ; ld (hl),e : inc hl : ld (hl),d : dec hl
ld (ix+nn),bc ; ld (ix+nn),c : ld (ix+nn+1),b
ld (ix+nn),de ; ld (ix+nn),e : ld (ix+nn+1),d
ld (ix+nn),hl ; ld (ix+nn),l : ld (ix+nn+1),h
ld (iy+nn),bc ; ld (iy+nn),c : ld (iy+nn+1),b
ld (iy+nn),de ; ld (iy+nn),e : ld (iy+nn+1),d
ld (iy+nn),hl ; ld (iy+nn),l : ld (iy+nn+1),h
ldi bc,(hl) ; ld c,(hl) : inc hl : ld b,(hl) : inc hl
ldi bc,(ix+nn) ; ld c,(ix+nn) : inc ix : ld b,(ix+nn) : inc ix
ldi bc,(iy+nn) ; ld c,(iy+nn) : inc iy : ld b,(iy+nn) : inc iy
ldi de,(hl) ; ld e,(hl) : inc hl : ld d,(hl) : inc hl
ldi de,(ix+nn) ; ld e,(ix+nn) : inc ix : ld d,(ix+nn) : inc ix
ldi de,(iy+nn) ; ld e,(iy+nn) : inc iy : ld d,(iy+nn) : inc iy
ldi hl,(ix+nn) ; ld l,(ix+nn) : inc ix : ld h,(ix+nn) : inc ix
ldi hl,(iy+nn) ; ld l,(iy+nn) : inc iy : ld h,(iy+nn) : inc iy
ldi (hl),bc ; ld (hl),c : inc hl : ld (hl),b : inc hl
ldi (hl),de ; ld (hl),e : inc hl : ld (hl),d : inc hl
ldi (ix+nn),bc ; ld (ix+nn),c : inc ix : ld (ix+nn),b : inc ix
ldi (ix+nn),de ; ld (ix+nn),e : inc ix : ld (ix+nn),d : inc ix
ldi (ix+nn),hl ; ld (ix+nn),l : inc ix : ld (ix+nn),h : inc ix
ldi (iy+nn),bc ; ld (iy+nn),c : inc iy : ld (iy+nn),b : inc iy
ldi (iy+nn),de ; ld (iy+nn),e : inc iy : ld (iy+nn),d : inc iy
ldi (iy+nn),hl ; ld (iy+nn),l : inc iy : ld (iy+nn),h : inc iy
ldi a,(bc) ; ld a,(bc) : inc bc
ldi a,(de) ; ld a,(de) : inc de
ldi a,(hl) ; ld a,(hl) : inc hl
ldi b,(hl) ; ld b,(hl) : inc hl
ldi c,(hl) ; ld c,(hl) : inc hl
ldi d,(hl) ; ld d,(hl) : inc hl
ldi e,(hl) ; ld e,(hl) : inc hl
ldi h,(hl) ; ld h,(hl) : inc hl
ldi l,(hl) ; ld l,(hl) : inc hl
ldi a,(ix+nn) ; ld a,(ix+nn) : inc ix
ldi b,(ix+nn) ; ld b,(ix+nn) : inc ix
ldi c,(ix+nn) ; ld c,(ix+nn) : inc ix
ldi d,(ix+nn) ; ld d,(ix+nn) : inc ix
ldi e,(ix+nn) ; ld e,(ix+nn) : inc ix
ldi h,(ix+nn) ; ld h,(ix+nn) : inc ix
ldi l,(ix+nn) ; ld l,(ix+nn) : inc ix
ldi a,(iy+nn) ; ld a,(iy+nn) : inc iy
ldi b,(iy+nn) ; ld b,(iy+nn) : inc iy
ldi c,(iy+nn) ; ld c,(iy+nn) : inc iy
ldi d,(iy+nn) ; ld d,(iy+nn) : inc iy
ldi e,(iy+nn) ; ld e,(iy+nn) : inc iy
ldi h,(iy+nn) ; ld h,(iy+nn) : inc iy
ldi l,(iy+nn) ; ld l,(iy+nn) : inc iy
ldd a,(bc) ; ld a,(bc) : dec bc
ldd a,(de) ; ld a,(de) : dec de
ldd a,(hl) ; ld a,(hl) : dec hl
ldd b,(hl) ; ld b,(hl) : dec hl
ldd c,(hl) ; ld c,(hl) : dec hl
ldd d,(hl) ; ld d,(hl) : dec hl
ldd e,(hl) ; ld e,(hl) : dec hl
ldd h,(hl) ; ld h,(hl) : dec hl
ldd l,(hl) ; ld l,(hl) : dec hl
ldd a,(ix+nn) ; ld a,(ix+nn) : dec ix
ldd b,(ix+nn) ; ld b,(ix+nn) : dec ix
ldd c,(ix+nn) ; ld c,(ix+nn) : dec ix
ldd d,(ix+nn) ; ld d,(ix+nn) : dec ix
ldd e,(ix+nn) ; ld e,(ix+nn) : dec ix
ldd h,(ix+nn) ; ld h,(ix+nn) : dec ix
ldd l,(ix+nn) ; ld l,(ix+nn) : dec ix
ldd a,(iy+nn) ; ld a,(iy+nn) : dec iy
ldd b,(iy+nn) ; ld b,(iy+nn) : dec iy
ldd c,(iy+nn) ; ld c,(iy+nn) : dec iy
ldd d,(iy+nn) ; ld d,(iy+nn) : dec iy
ldd e,(iy+nn) ; ld e,(iy+nn) : dec iy
ldd h,(iy+nn) ; ld h,(iy+nn) : dec iy
ldd l,(iy+nn) ; ld l,(iy+nn) : dec iy
ldi (bc),a ; ld (bc),a : inc bc
ldi (de),a ; ld (de),a : inc de
ldi (hl),a ; ld (hl),a : inc hl
ldi (hl),b ; ld (hl),b : inc hl
ldi (hl),c ; ld (hl),c : inc hl
ldi (hl),d ; ld (hl),d : inc hl
ldi (hl),e ; ld (hl),e : inc hl
ldi (hl),h ; ld (hl),h : inc hl
ldi (hl),l ; ld (hl),l : inc hl
ldi (ix+nn),a ; ld (ix+nn),a : inc ix
ldi (ix+nn),b ; ld (ix+nn),b : inc ix
ldi (ix+nn),c ; ld (ix+nn),c : inc ix
ldi (ix+nn),d ; ld (ix+nn),d : inc ix
ldi (ix+nn),e ; ld (ix+nn),e : inc ix
ldi (ix+nn),h ; ld (ix+nn),h : inc ix
ldi (ix+nn),l ; ld (ix+nn),l : inc ix
ldi (iy+nn),a ; ld (iy+nn),a : inc iy
ldi (iy+nn),b ; ld (iy+nn),b : inc iy
ldi (iy+nn),c ; ld (iy+nn),c : inc iy
ldi (iy+nn),d ; ld (iy+nn),d : inc iy
ldi (iy+nn),e ; ld (iy+nn),e : inc iy
ldi (iy+nn),h ; ld (iy+nn),h : inc iy
ldi (iy+nn),l ; ld (iy+nn),l : inc iy
ldd (bc),a ; ld (bc),a : dec bc
ldd (de),a ; ld (de),a : dec de
ldd (hl),a ; ld (hl),a : dec hl
ldd (hl),b ; ld (hl),b : dec hl
ldd (hl),c ; ld (hl),c : dec hl
ldd (hl),d ; ld (hl),d : dec hl
ldd (hl),e ; ld (hl),e : dec hl
ldd (hl),h ; ld (hl),h : dec hl
ldd (hl),l ; ld (hl),l : dec hl
ldd (ix+nn),a ; ld (ix+nn),a : dec ix
ldd (ix+nn),b ; ld (ix+nn),b : dec ix
ldd (ix+nn),c ; ld (ix+nn),c : dec ix
ldd (ix+nn),d ; ld (ix+nn),d : dec ix
ldd (ix+nn),e ; ld (ix+nn),e : dec ix
ldd (ix+nn),h ; ld (ix+nn),h : dec ix
ldd (ix+nn),l ; ld (ix+nn),l : dec ix
ldd (iy+nn),a ; ld (iy+nn),a : dec iy
ldd (iy+nn),b ; ld (iy+nn),b : dec iy
ldd (iy+nn),c ; ld (iy+nn),c : dec iy
ldd (iy+nn),d ; ld (iy+nn),d : dec iy
ldd (iy+nn),e ; ld (iy+nn),e : dec iy
ldd (iy+nn),h ; ld (iy+nn),h : dec iy
ldd (iy+nn),l ; ld (iy+nn),l : dec iy
ldi (hl),mm ; ld (hl),mm : inc hl
ldi (ix+nn),mm ; ld (ix+nn),mm : inc ix
ldi (iy+nn),mm ; ld (iy+nn),mm : inc iy
ldd (hl),mm ; ld (hl),mm : dec hl
ldd (ix+nn),mm ; ld (ix+nn),mm : dec ix
ldd (iy+nn),mm ; ld (iy+nn),mm : dec iy
adc de,bc ; ex de,hl : adc hl,bc : ex de,hl
adc de,de ; ex de,hl : adc hl,hl : ex de,hl ;; consider alternative: rl e : rl d (-7T)
adc de,hl ; ex de,hl : adc hl,de : ex de,hl
adc de,sp ; ex de,hl : adc hl,sp : ex de,hl
add de,bc ; ex de,hl : add hl,bc : ex de,hl
add de,de ; ex de,hl : add hl,hl : ex de,hl ;; consider alternative: srl e : rl d (-3T)
add de,hl ; ex de,hl : add hl,de : ex de,hl
add de,sp ; ex de,hl : add hl,sp : ex de,hl
sbc de,bc ; ex de,hl : sbc hl,bc : ex de,hl
sbc de,de ; ex de,hl : sbc hl,hl : ex de,hl
sbc de,hl ; ex de,hl : sbc hl,de : ex de,hl
sbc de,sp ; ex de,hl : sbc hl,sp : ex de,hl
sub de,bc ; or a : ex de,hl : sbc hl,bc : ex de,hl
sub de,de ; or a : ex de,hl : sbc hl,hl : ex de,hl ;; consider alternative: ld de,0 (-17T)
sub de,hl ; or a : ex de,hl : sbc hl,de : ex de,hl
sub de,sp ; or a : ex de,hl : sbc hl,sp : ex de,hl
sub hl,bc ; or a : sbc hl,bc
sub hl,de ; or a : sbc hl,de
sub hl,hl ; or a : sbc hl,hl ;; consider alternative: ld hl,0 (-9T)
sub hl,sp ; or a : sbc hl,sp
; Z80N only
mul ; mul de ; to avoid warning specify registers</programlisting>
<code>LDI</code> increases the data pointer after the data
access, so <code>LDI A,(HL)</code> is the same as <code>LD A,(HL):INC HL</code>.
Likewise, <code>LDD A,(DE)</code> is <code>LD A,(DE):DEC DE</code>.</para>
</section>
<section id="s_realdevice">
<title>Real device emulation mode</title>
<para>To enable this mode you must use pseudo-op <link
linkend="po_device">DEVICE</link>.</para>
<para>In this mode the compiler compiling program to virtual memory (as
at MSX's WB-ASS2, ZX-Spectrum's GENS, ZEUS, ALASM etc). After this all
you can use new pseudo-ops as <link linkend="s_pseudoops">SAVEBIN, SAVEDEV
SAVEHOB, SAVETRD, SAVETAP, PAGE, SLOT, MMU, LABELSLIST</link>, use special
functions in <link linkend="c_lua_scripting">Lua scripts</link> and use operators
<code>{address}, {b address}</code> to read WORD/BYTE from the virtual memory.</para>
<para>If only single DEVICE is used in whole source batch, the device
becomes "global" and will affect also source ahead of the DEVICE line.
<example>
<title>docs_examples/s_realdevice.asm</title>
<para><programlisting> DEVICE ZXSPECTRUM128
; in this device the default slot is SLOT 3 with PAGE 0 paged in.
ORG 32768
StartProg:
JP $
DEVICE NONE
;do something, if you don't want to corrupt virtual
;memory with other code, for example, loader of code.
;...code...
;return to our virtual device:
DEVICE ZXSPECTRUM128
SAVESNA "snapshotname.sna", StartProg</programlisting></para>
</example>Predefined devices:<variablelist>
<varlistentry>
<term>NONE<indexterm id="device_none"><primary>NONE</primary></indexterm></term>
<listitem>
<para>Disable real device emulation mode. By default.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ZXSPECTRUM48<indexterm id="device_zx48"><primary>ZXSPECTRUM48</primary></indexterm></term>
<listitem>
<para>Has 4 slots (0-3) with size 4000h, 4 pages (0-3) with size
4000h. Slot 3 (it from 0C000h) enables to current by
default.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ZXSPECTRUM128<indexterm id="device_zx128"><primary>ZXSPECTRUM128</primary></indexterm></term>
<listitem>
<para>Has 8 RAM pages (0-7) with size 4000h. Default slot is 3.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ZXSPECTRUM256<indexterm id="device_zx256"><primary>ZXSPECTRUM256</primary></indexterm></term>
<listitem>
<para>Same as Russian clone Scorption 256. Has 16 RAM pages
(0-15) with size 4000h.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ZXSPECTRUM512<indexterm id="device_zx512"><primary>ZXSPECTRUM512</primary></indexterm></term>
<listitem>
<para>Same as Russian clones ATM Turbo 512 and Pentagon 512. Has
32 RAM pages (0-31) with size 4000h.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ZXSPECTRUM1024<indexterm id="device_zx1024"><primary>ZXSPECTRUM1024</primary></indexterm></term>
<listitem>
<para>Same as Russian clones ATM Turbo 2 and Pentagon 1024 SL.
Has 64 RAM pages (0-63) with size 4000h.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ZXSPECTRUM2048<indexterm id="device_zx2048"><primary>ZXSPECTRUM2048</primary></indexterm></term>
<listitem>
<para>Similar to other spectrum devices, has 128 RAM pages (0-127) with size 4000h.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ZXSPECTRUM4096<indexterm id="device_zx4096"><primary>ZXSPECTRUM4096</primary></indexterm></term>
<listitem>
<para>Similar to other spectrum devices, has 256 RAM pages (0-255) with size 4000h.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ZXSPECTRUM8192<indexterm id="device_zx8192"><primary>ZXSPECTRUM8192</primary></indexterm></term>
<listitem>
<para>Similar to other spectrum devices, has 512 RAM pages (0-511) with size 4000h.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ZXSPECTRUMNEXT<indexterm id="device_zxn"><primary>ZXSPECTRUMNEXT</primary></indexterm></term>
<listitem>
<para>ZX Spectrum Next, has 8 slots (0-7) of size 0x2000 and 224
RAM pages (0-223) totalling at 1.75MiB of memory. The <ulink
url="https://wiki.specnext.dev/Memory_map#Z80_Visible_Memory_map">default mapping</ulink>
is similar to ZX128, paging in: {14, 15, 10, 11, 4, 5, 0, 1} pages.
Default slot is 7 (memory range 0xE000..0xFFFF).
All memory is zeroed during initialization.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>NOSLOT64K<indexterm id="device_noslot64k"><primary>NOSLOT64K</primary></indexterm></term>
<listitem>
<para>Has only single slot of size 64kiB (slot 0), covering full Z80 CPU addressing range.
There are 32 memory pages available, by default page 0 is mapped.
That makes in total 2MiB of memory available (32 * 64 ki = 2 Mi).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>AMSTRADCPC464<indexterm id="device_cpc464"><primary>AMSTRADCPC464</primary></indexterm></term>
<listitem>
<para>Has 4 slots (0-3) of size 0x4000 and 4 pages (0-3) of 0x4000, totalling 64K. These pages are mapped linearly as
{ 0, 1, 2, 3 }.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>AMSTRADCPC6128<indexterm id="device_cpc6128"><primary>AMSTRADCPC6128</primary></indexterm></term>
<listitem>
<para>Has 4 slots (0-3) of size 0x4000 and 8 RAM pages (0-7) of 0x4000 (128K total). The default page mapping is
{ 0, 1, 2, 3 }.</para>
</listitem>
</varlistentry>
</variablelist></para>
<para>If you want to see other devices you must write to us. See <link
linkend="feedback">Feedback</link> chapter.</para>
</section>
<section id="s_predefined">
<title>Predefined defines</title>
<para>SjASMPlus has predefined <link
linkend="po_define">defines</link>.<variablelist>
<varlistentry>
<term>__SJASMPLUS__<indexterm id="def__sjasmplus__"><primary>__SJASMPLUS__</primary></indexterm> = <24bit number></term>
<listitem>
<para>Current version split into three 8bit values, ie. 0x010F02 for "1.15.2".</para>
</listitem>
</varlistentry>
<varlistentry>
<term>__VERSION__<indexterm id="def__version__"><primary>__VERSION__</primary></indexterm> = "version string"</term>
<listitem>
<para>String value (with quotes around it) of current version like <code>"1.15.2"</code>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>__ERRORS__<indexterm id="def__errrors__"><primary>__ERRORS__</primary></indexterm> = <number></term>
<listitem>
<para>Number of errors.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>__WARNINGS__<indexterm id="def__warnings__"><primary>__WARNINGS__</primary></indexterm> = <number></term>
<listitem>
<para>Number of warnings.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>__DATE__<indexterm id="def__date__"><primary>__DATE__</primary></indexterm> = "YYYY-MM-DD"</term>
<listitem>
<para>Date of assembling (timestamp before first pass).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>__TIME__<indexterm id="def__time__"><primary>__TIME__</primary></indexterm> = "hh:mm:ss"</term>
<listitem>
<para>Time of assembling (timestamp before first pass, 24h form).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>__PASS__<indexterm id="def__pass__"><primary>__PASS__</primary></indexterm> = <number></term>
<listitem>
<para>Current assembling pass (1, 2 or 3).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>__INCLUDE_LEVEL__<indexterm id="def__include_level__"><primary>__INCLUDE_LEVEL__</primary></indexterm> = <number></term>
<listitem>
<para>Current include-nesting level.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>__BASE_FILE__<indexterm id="def__base_file__"><primary>__BASE_FILE__</primary></indexterm> = <name of base file></term>
<listitem>
<para>Name of base file (include-level zero).</para>
<para>This is raw value without quotes, practically unusable by asm source, but LUA
provides means to operate with such string value.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>__FILE__<indexterm id="def__file__"><primary>__FILE__</primary></indexterm> = <name of current file></term>
<listitem>
<para>Name of current file.</para>
<para>This is raw value without quotes, practically unusable by asm source, but LUA
provides means to operate with such string value.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>__LINE__<indexterm id="def__line__"><primary>__LINE__</primary></indexterm> = <number></term>
<listitem>
<para>Current line number.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>__COUNTER__<indexterm id="def__counter__"><primary>__COUNTER__</primary></indexterm> = <incrementing number></term>
<listitem>
<para>Does increment upon each usage (starting as value 0). Currently difficult to
use for labels/symbols, because the starting `_` of the define name prevents
mid-word substitution, will make more sense with new substitution rules (if ever
the sjasmplus v2.x happens, would be too big change for v1.x). Right now call
LUA for the rescue.</para>
<example>
<title>__COUNTER__ usage in LUA script</title>
<programlisting> DB __COUNTER__ ; DB 0
LUA ALLPASS
sj.insert_label("label_" .. sj.get_define("__COUNTER__"), sj.current_address)
-- creates "label_1" at "$" (0x0001)
sj.insert_label("label_" .. sj.get_define("__COUNTER__"), _c("$+10"))
-- creates "label_2" at "$+10" (0x000B)
ENDLUA
label__COUNTER__: ; does *NOT* substitute in current sjasmplus, sorry
DB __COUNTER__ ; DB 3
; also macro arguments substitution can be used
MACRO createLabelWithSuffix label?, suffix?
label?_suffix? ; define global label
ENDM
createLabelWithSuffix label, __COUNTER__ ; label_4
createLabelWithSuffix label, __COUNTER__ ; label_5</programlisting>
</example>
</listitem>
</varlistentry>
<varlistentry>
<term>Deprecated predefined values from sjasmplus till version 1.15.1:</term>
<listitem>
<para>The predefined values were renamed and extended to be more like gcc/clang pre-defines,
the following ones are deprecated originals.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>_SJASMPLUS = 1</term>
<listitem>
<para>Deprecated, consider using similar __SJASMPLUS__<example>
<title></title>
<para><programlisting> IFDEF _SJASMPLUS
;code for sjasmplus
ELSE
;code for other compiler
ENDIF</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>_VERSION = "version"</term>
<listitem>
<para>Deprecated, renamed to __VERSION__<example>
<title></title>
<para><programlisting> IF _VERSION = "1.07"
;code for 1.07
ELSE
;code for other version
ENDIF</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>_RELEASE = releasenumber</term>
<listitem>
<para>Deprecated, consider using similar __SJASMPLUS__<example>
<title></title>
<para><programlisting> IF _RELEASE = 1 ; 0 - is stable version
;code for Release Candidate 1
ELSE
;code for other version
ENDIF</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>_ERRORS = <number></term>
<listitem>
<para>Number of errors. Deprecated, renamed to __ERRORS__</para>
</listitem>
</varlistentry>
<varlistentry>
<term>_WARNINGS = <number></term>
<listitem>
<para>Number of warnings. Deprecated, renamed to __WARNINGS__</para>
</listitem>
</varlistentry>
</variablelist></para>
</section>
</chapter>
<chapter id="c_directives">
<title>Pseudo-ops (aka Pseudo-instructions, Directives etc)</title>
<section id="s_directive_usage">
<title>Simple example of usage</title>
<para><programlisting> .SOMEPSEUDOOP ;or
SOMEPSEUDOOP ;or
somepseudoop</programlisting></para>
<para>[Almost] complete list of pseudo-ops follows:</para>
</section>
<section id="s_pseudoops">
<title>Pseudo-ops</title>
<para></para>
<para><variablelist>
<varlistentry>
<term>.<repeat-count><indexterm id="po_dot_repeat"><primary>.<repeat-count></primary></indexterm> <single instruction></term>
<listitem>
<para>Repeat <single instruction> <repeat-count> many times. Doesn't work
in the beginning of line. The <repeat-count> must be either simple integer
number or expression fully enclosed in parentheses.<example>
<title>docs_examples/po_dot_repeat.asm</title>
<para><programlisting> .3 INC A ;will be compiled to INC A:INC A:INC A
len EQU 10
.(12-len) BYTE 0 ;will be compiled to BYTE 0,0
.2 .3 RET ;will be compiled to 6x RET</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>ABYTE<indexterm id="po_abyte"><primary>ABYTE</primary></indexterm> <offset> <bytes></term>
<listitem>
<para>Defines a byte or a string of bytes. The offset is added
to each of the following bytes.<example>
<title></title>
<para><programlisting> ABYTE 2 4,9 ; Same as BYTE 6,11
ABYTE 3 "ABC" ; Same as BYTE "DEF"</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>ABYTEC<indexterm id="po_abytec"><primary>ABYTEC</primary></indexterm> <offset> <bytes></term>
<listitem>
<para>Defines a byte or a string of bytes, where the last byte
of the string will have bit 7 set. The offset is added to each
of the following bytes.<example>
<title></title>
<para><programlisting> ABYTEC 0 "KIP" ; Same as BYTE "KI",'P'|128
ABYTEC 1 "ABC",0,"DE" ; Same as BYTE "BC",'D'|128,1,'E','F'|128</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>ABYTEZ<indexterm id="po_abytez"><primary>ABYTEZ</primary></indexterm> <offset> <bytes></term>
<listitem>
<para>Defines a byte or a string of bytes, followed by a zero.
The offset is added to each of the following bytes.<example>
<title></title>
<para><programlisting> ABYTEZ 0 "KIP" ; Same as BYTE "KIP",0</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>ALIGN<indexterm id="po_align"><primary>ALIGN</primary></indexterm>
[<expression equal to 1,2,4,8,16,32,64,128,256,512,1024,2048,4096,8192,16384 or
32768>[, <byte>]]</term>
<listitem>
<para>Align advances to nearest address where <new address> modulo <expression> (default 4)
equals zero (stays at current address if possible).</para>
<para>If <byte> is specified, memory advanced over is set to it.
<example>
<title></title>
<para><programlisting> ALIGN ; => ALIGN 4 - simply align by 4
ALIGN 2 ; by 2 (preserves value of "device" memory)
ALIGN 2,0 ; + fills memory with zero</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>ASSERT<indexterm id="po_assert"><primary>ASSERT</primary></indexterm> <expression>[, <anything>]</term>
<listitem>
<para>An 'assertion failed' error is issued if the expression evaluates to zero.
The "anything" (optional argument since v1.18.1) is then also visible in the error
message, so you can add description/notes about expression there.<example>
<title></title>
<para><programlisting>STACKPOINTER=0D500H
ASSERT END_OF_PROGRAM < STACKPOINTER, Program code leaks into stack area
END_OF_PROGRAM</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>BINARY<indexterm id="po_binary"><primary>BINARY</primary><see>INCBIN</see></indexterm> <filename>[,<offset>[,<length>]]</term>
<listitem>
<para>Synonym of <link linkend="po_incbin">INCBIN</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>BLOCK<indexterm id="po_block"><primary>BLOCK</primary></indexterm> <length>[,<fill
byte>]</term>
<listitem>
<para>Defines space. Has to be followed by the number of byte to
reserve, optionally followed by the value to fill these bytes
with.<example>
<title></title>
<para><programlisting> BLOCK 500 ; define a block of 500 bytes of zero
BLOCK 500,0 ; define a block of 500 bytes of zero
BLOCK 400,-1 ; define a block of 400 bytes of 255</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>BPLIST<indexterm id="po_bplist"><primary>BPLIST</primary><seealso>SETBP</seealso></indexterm> <filename> [unreal|zesarux]</term>
<listitem>
<para>
<emphasis>Works only in real device emulation mode. See
<link linkend="po_device">DEVICE</link>.</emphasis>
</para>
<para>Opens file to export breakpoints info directly from ASM source, currently two
flavours of export are supported: <code>unreal</code> (default) and
<code>zesarux</code>. For latest Unreal emulators use filename "bpx.ini", you
can then load the file from the emulator UI. For ZEsarUX the file will contain
command-line options, which you can add to the command when launching the emulator.
</para>
<para>(current version of ZEsarUX will not catch the very first instruction of freshly
loaded snapshot/NEX/... file, or it will even disable breakpoints when changing
machine parameters and ignore the <code>--enable-breakpoints</code> option - will
be hopefully improved in the future)
<example>
<title></title>
<programlisting> BPLIST "bpx.ini" unreal ; open breakpoints list in "Unreal" format
; or (only one file per assembling-unit can be specified)
BPLIST "cmd_line_options.txt" zesarux ; open breakpoints list in "ZEsarUX" format</programlisting>
</example>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>BYTE<indexterm id="po_byte"><primary>BYTE</primary></indexterm> <bytes></term>
<listitem>
<para>Defines a byte or a string of bytes. Each value should be
between -129 and 256.<example>
<title></title>
<para><programlisting> BYTE 0x56
BYTE 1,-78,'@'
BYTE "Format C:? ",0h</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>CSPECTMAP<indexterm id="po_cspectmap"><primary>CSPECTMAP</primary></indexterm> [<filename>]</term>
<listitem>
<para><emphasis>Useful for ZX-Spectrum Emulator
#CSpect by Mike Dailly.</emphasis></para>
<para><emphasis>Works only in real device emulation mode. See
<link linkend="po_device">DEVICE</link>.</emphasis></para>
<para>Saves labels list in format:</para>
<para><synopsis>HEXA_16BIT_ADDRESS HEXA_LONG_ADDRESS TYPE LABELNAME</synopsis>
where TYPE is: 00 = regular label, 01 = EQU or struct defined, 02 = DEFL defined,
03 = ROM page/"none" device, 04 = STRUCT definition.</para>
<para>If no filename is provided, default is created by appending ".map" to source name.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>D24<indexterm id="po_d24"><primary>D24</primary></indexterm></term>
<listitem>
<para>Defines three bytes by 24b constant. Values should be between
-16777217 and 16777216.<example>
<title></title>
<para><programlisting> D24 0x123456 ; define three bytes 0x56, 0x34, 0x12</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>DB<indexterm id="po_db"><primary>DB</primary><see>BYTE</see></indexterm></term>
<listitem>
<para>Synonym of <link linkend="po_byte">BYTE</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DC<indexterm id="po_dc"><primary>DC</primary></indexterm></term>
<listitem>
<para>Same as <link linkend="po_byte">BYTE</link>, but every
last character of a string will have bit 7 set.<example>
<title></title>
<para><programlisting> DC "kip" ; same as BYTE "ki",'p'|128</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>DD<indexterm id="po_dd"><primary>DD</primary><see>DWORD</see></indexterm></term>
<listitem>
<para>Synonym of <link linkend="po_dword">DWORD</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DEFARRAY<indexterm id="po_defarray"><primary>DEFARRAY</primary></indexterm> <id> <replacements></term>
<listitem>
<para>Array of DEFINEs.</para>
<para>Use <code>id[#]</code> to retrieve current size of array.
<example>
<title>docs_examples/po_defarray.asm</title>
<programlisting> DEFARRAY myarray 10*20,"A",20,</D,40>,50,70
CNT DEFL 0 ;or CNT=0
DUP myarray[#] ; 6
DISPLAY myarray[CNT]
CNT DEFL CNT+1 ;or CNT=CNT+1
EDUP</programlisting>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>DEFARRAY+<indexterm id="po_defarray_plus"><primary>DEFARRAY+</primary></indexterm> <id> <additional replacements></term>
<listitem>
<para>Appending more DEFINEs to already defined array<example>
<title></title>
<para><programlisting> DEFARRAY myarray 'A', 'B', 'C'
DEFARRAY+ myarray 'D', 'E' ; now "myarray" has 5 items
DUP 3 : DEFARRAY+ myarray '!' : EDUP ; "DEFARRAYFILL" adding 3x '!'</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>DEFB<indexterm id="po_defb"><primary>DEFB</primary><see>BYTE</see></indexterm></term>
<listitem>
<para>Synonym of <link linkend="po_byte">BYTE</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DEFD<indexterm id="po_defd"><primary>DEFD</primary><see>DWORD</see></indexterm></term>
<listitem>
<para>Synonym of <link linkend="po_dword">DWORD</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DEFDEVICE<indexterm id="po_defdevice"><primary>DEFDEVICE</primary><seealso>DEVICE</seealso></indexterm>
<deviceid>, <slot_size $100..$10000>, <page_count 1..1024>[, <slot_0_initial_page>[, ...]]</term>
<listitem>
<para>(since v1.20.1) Add custom device definition. The 64ki Z80 address space is divided evenly by <code>slot_size</code>
to form N slots and the total device memory is <code>slot_size * page_count</code> bytes.</para>
<para>The initial pages are implicitly going from <code>0</code> to <code>page_count-1</code>
(repeating page <code>page_count-1</code> for remaining slots when there's not enough pages), but you
can specify initial page layout explicitly.</para>
<para>Use <link linkend="po_device">DEVICE</link> to select the newly defined device.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DEFG<indexterm id="po_defg"><primary>DEFG</primary><see>DG</see></indexterm></term>
<listitem>
<para>Synonym of <link linkend="po_dg">DG</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DEFH<indexterm id="po_defh"><primary>DEFH</primary><see>DH</see></indexterm></term>
<listitem>
<para>Synonym of <link linkend="po_dh">DH</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DEFINE+<indexterm id="po_define"><primary>DEFINE+</primary></indexterm> <id> <replacement></term>
</varlistentry>
<varlistentry>
<term>DEFINE<indexterm id="po_define2"><primary>DEFINE</primary></indexterm> <id> <replacement></term>
<listitem>
<para>The identifier <id> will be replaced with the <replacement>.
The <code>DEFINE+</code> (since v1.18.0) will also redefine the identifier <id>
if it already exists. The replacement could be omitted,
in such case it is still possible to check if the identifier was defined
with IFDEF or IFNDEF.<example>
<title></title>
<para><programlisting> DEFINE str_honderd "Honderd"
BYTE str_honderd,0 ; BYTE "Honderd",0
DEFINE+ do_stuff set 4,e
do_stuff ; set 4,e
DEFINE+ do_stuff set 2,e
do_stuff ; set 2,e</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term><label> DEFL<indexterm id="po_defl"><primary>DEFL</primary><seealso>EQU</seealso></indexterm> <expression></term>
<listitem>
<para>Assigns value of <expression> to symbol <label>. New label defined
by DEFL is marked internally as "modifiable", allowing to re-assign new values to it with
further DEFL statements (you can use also <code>=</code> instead of <code>DEFL</code>).
<example>
<title></title>
<para><programlisting>counter DEFL 0
DUP 4
DB 0xAA, counter
counter = counter + 1
EDUP
; machine code produced: AA 00 AA 01 AA 02 AA 03</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>DEFM<indexterm id="po_defm"><primary>DEFM</primary><see>BYTE</see></indexterm></term>
<listitem>
<para>Synonym of <link linkend="po_byte">BYTE</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DEFS<indexterm id="po_defs"><primary>DEFS</primary><see>BLOCK</see></indexterm></term>
<listitem>
<para>Synonym of <link linkend="po_block">BLOCK</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DEFW<indexterm id="po_defw"><primary>DEFW</primary><see>WORD</see></indexterm></term>
<listitem>
<para>Synonym of <link linkend="po_word">WORD</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DEPHASE<indexterm id="po_dephase"><primary>DEPHASE</primary><see>ENT</see><seealso>DISP</seealso></indexterm></term>
<listitem>
<para>Synonym of <link linkend="po_ent">ENT</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DEVICE<indexterm id="po_device"><primary>DEVICE</primary><seealso>MMU</seealso><seealso>ZXSPECTRUM128</seealso><seealso>ZXSPECTRUMNEXT</seealso><seealso>DEFDEVICE</seealso></indexterm> <deviceid>[, <RAMTOP>]</term>
<listitem>
<para>Enables <link linkend="s_realdevice">real device emulation
mode</link> by it identifier. If there is only single DEVICE directive
in whole source batch, it becomes "global" and the device affects all
lines of source, otherwise the DEVICE is applied for lines following it.</para>
<para>For ZXSPECTRUM-like devices (except ZX Next) you can provide RAMTOP value,
which will init the device memory in similar way as "<code>CLEAR <RAMTOP></code>"
in BASIC would do, putting top of the fake-stack at the RAMTOP address. The
default RAMTOP is since v1.15.0 0x5D5B (it was 0xFF57 before).</para>
<para>Predefined devices' identifiers list:</para>
<synopsis> NONE ; off real device emulation mode
ZXSPECTRUM48 ; ZX-Spectrum 48 (4 slots, 4 pages, slot/page size 0x4000, default map: 0, 1, 2, 3)
ZXSPECTRUM128 ; ZX-Spectrum 128 (like 48 with 8 pages, default map: 7, 5, 2, 0)
ZXSPECTRUM256 ; e.g. Scorpion 256 (exUSSR clone of ZX-Spectrum 128)
ZXSPECTRUM512 ; e.g. ATM-Turbo 512 (another clone)
ZXSPECTRUM1024
ZXSPECTRUM2048
ZXSPECTRUM4096
ZXSPECTRUM8192
ZXSPECTRUMNEXT ; ZX Spectrum Next (8 slots, 224 pages, slot size 0x2000 = 1.75MiB RAM)
; (default pages map: 14, 15, 10, 11, 4, 5, 0, 1) (default slot: 7 (0xE000..0xFFFF))
NOSLOT64K ; Single slot (slot 0) covering full 64kiB address range of Z80, 32 pages
AMSTRADCPC464 ; Amstrad CPC 464 (4 slots, 4 pages, slot/page size 0x4000, default map: 0, 1, 2, 3)
AMSTRADCPC6128 ; Amstrad CPC 6128 (like 464 with 8 pages)
;disable:
DEVICE NONE
;enable:
DEVICE ZXSPECTRUM128</synopsis>
</listitem>
</varlistentry>
<varlistentry>
<term>DG<indexterm id="po_dg"><primary>DG</primary></indexterm> <data encoded in bits></term>
<listitem>
<para>Data comprises of characters in multiples of eight, each block
is converted to a byte value.</para>
<para>A hyphen '-' (also '.' and '_') represents 0 and any other non-whitespace character
represents 1. It ignores spaces, use them for formatting if you like. Warning, "DG 10100001" is value 255, because character '0' is not a dash '-'. (since v1.11)<example>
<title></title>
<para><programlisting> DG 1-1----1 ; store 161 at the current location
DG ...# #... .##. .... ; store two bytes: 0x18, 0x60</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>DH<indexterm id="po_dh"><primary>DH</primary></indexterm> "<data>"[,"<data2>"...]</term>
<listitem>
<para>The data string comprises pairs of hexadecimal digits, each pair is converted to
a byte value. You can add spaces between pairs as you like. (since v1.11)<example>
<title></title>
<para><programlisting> DH "0123456789ABCDEF" ; eight bytes #01 #23 ...
DH "01 23 45 67" ; four bytes #01 #23 #45 #67</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>DISP<indexterm id="po_disp"><primary>DISP</primary><seealso>ENT</seealso></indexterm> <address>[,<page_number>]</term>
<listitem>
<para>Set the address in which the part of code should work.
<link linkend="po_phase">PHASE</link> and <link
linkend="po_textarea">TEXTAREA</link> are synonyms of DISP.
<link linkend="po_ent">ENT</link> will restore current address.
<link linkend="po_unphase">UNPHASE</link>, <link
linkend="po_dephase">DEPHASE</link> and <link
linkend="po_endt">ENDT</link> are synonyms of <link
linkend="po_ent">ENT</link>. DISP blocks can NOT be nested, and to change
the displacement address within current DISP block use the ordinary ORG.
When in device mode, you can specify fixed value for "fake" page of emitted
instructions and regular labels, but to avoid warning, you must also map-in
the target page into the target memory slot (<link linkend="po_mmu">MMU</link>).
When no fixed page in DISP is specified, the current mapping of memory pages is used.
<example>
<title>docs_examples/po_disp.asm</title>
<para><programlisting> DEVICE ZXSPECTRUM48
SCREEN EQU $4000
ORG $8000
LD HL,BEGIN
LD DE,SCREEN
LD BC,ENDOFPROG-BEGIN
LDIR
JP SCREEN
BEGIN DISP SCREEN ;code will compile for address $4000, but to the current ORG
MARKA DEC A
HALT
JP NZ,MARKA
DI
HALT
ENT
ENDOFPROG
ASSERT $800E == BEGIN && $8015 == ENDOFPROG && $4000 == MARKA
ASSERT $76 == {B $800F} ; HALT instruction lands at $800F (BEGIN+1)</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>DISPLAY<indexterm id="po_display"><primary>DISPLAY</primary></indexterm> <bytes></term>
<listitem>
<para><emphasis>This pseudo-op comes from ZX-Spectrum assembler
ALASM.</emphasis></para>
<para>Out to console a string of bytes. Each value should be
between -129 and 256. Keys /D, /B, /C, /H and /A set format of output of
numbers:<synopsis>/D - out only in Decimal
/B - out only in Binary (truncated to 8 bit)
/C - out as character in apostrophes (truncated to 8 bit)
/H - out only in Hexadecimal
/A - out both in Hexadecimal and Decimal</synopsis>
<example>
<title>docs_examples/po_display.asm</title>
<para><programlisting> ORG 100h
TESTLABEL:
;...some code...
RET
DISPLAY "--the some program-- by me"
DISPLAY "TESTLABEL address is:",/A,TESTLABEL
/*
will output to the console strings:
> --the some program-- by me
> TESTLABEL address is:0x100, 256
*/</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>DM<indexterm id="po_dm"><primary>DM</primary><see>BYTE</see></indexterm></term>
<listitem>
<para>Synonym of <link linkend="po_byte">BYTE</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DS<indexterm id="po_ds"><primary>DS</primary><see>BLOCK</see></indexterm></term>
<listitem>
<para>Synonym of <link linkend="po_block">BLOCK</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DUP<indexterm id="po_dup"><primary>DUP</primary></indexterm> <count>[, <index_variable>]</term>
<listitem>
<para>DUP specifies the number of times to generate the
following lines until an EDUP pseudo-op is encountered. DUP can be used in macro's.</para>
<para>Optional second argument (since v1.20.2) is label name to have repetition index
available inside the block (values 0, 1, 2, 3, ...).
<example>
<title></title>
<para><programlisting> DUP 3 ; zero count would skip whole block
NOP
EDUP
/*this will expand to:
NOP
NOP
NOP
*/</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>DW<indexterm id="po_dw"><primary>DW</primary><see>WORD</see></indexterm></term>
<listitem>
<para>Synonym of <link linkend="po_word">WORD</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DWORD<indexterm id="po_dword"><primary>DWORD</primary></indexterm></term>
<listitem>
<para>Defines a so called doubleword. Values should be between
-2147483649 and 4294967296.<example>
<title></title>
<para><programlisting> DWORD 4000h,0d000h
DWORD 4</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>DZ<indexterm id="po_dz"><primary>DZ</primary></indexterm></term>
<listitem>
<para>Same as <link linkend="po_byte">BYTE</link>, but an extra
zero will be added at the end.<example>
<title></title>
<para><programlisting> DZ 1 ; same as BYTE 1,0
DZ "kip" ; same as BYTE "kip",0</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>EMPTYTAP<indexterm id="po_emptytap"><primary>EMPTYTAP</primary></indexterm> <filenameoftapefile></term>
<listitem>
<para><emphasis>Useful only for ZX-Spectrum
users</emphasis></para>
<para>Create the new or truncate existing standard tape file
for emulators of ZX-Spectrum. See example of
<link linkend="po_savetap">SAVETAP</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>EMPTYTRD<indexterm id="po_emptytrd"><primary>EMPTYTRD</primary></indexterm> <filenameoftrdimage>[,<disclabel>]</term>
<listitem>
<para><emphasis>Useful only for ZX-Spectrum users</emphasis></para>
<para>Create the empty TRD image for emulators of ZX-Spectrum.
See example of <link linkend="po_savetrd">SAVETRD</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ENCODING<indexterm id="po_encoding"><primary>ENCODING</primary></indexterm> <encoding></term>
<listitem>
<para><emphasis>Useful only for non English
users</emphasis></para>
<para>Set the current encoding, i.e. if you set "DOS", SjASMPlus
will automatically convert strings from ANSI to DOS-866.
Encoding may be "DOS"(DOS-866) or "WIN"(ANSI/Win-1251). Default
is "WIN". <example>
<title></title>
<para><programlisting> ENCODING "WIN"
DB "тексттекст" ;will be тексттекст
ENCODING "DOS"
DB "тексттекст" ;will be ⥪бв⥪бв</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>END<indexterm id="po_end"><primary>END</primary></indexterm> [<startaddress>]</term>
<listitem>
<para>The assembler will stop at this point. The pseudo-op
END does NOT work in the beginning of line (even with --dirbol).
The optional argument is used by SAVESNA, SAVECPCSNA, SAVETAP and SAVENEX.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ENDLUA<indexterm id="po_endlua"><primary>ENDLUA</primary><seealso>LUA</seealso></indexterm></term>
<listitem>
<para>See <link linkend="po_lua">LUA</link> for more
information.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ENDMOD<indexterm id="po_endmod"><primary>ENDMOD</primary><see>ENDMODULE</see></indexterm></term>
<listitem>
<para>Synonym of <link
linkend="po_endmodule">ENDMODULE</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ENDMODULE<indexterm id="po_endmodule"><primary>ENDMODULE</primary><seealso>MODULE</seealso></indexterm></term>
<listitem>
<para>To indicate the end of a module (see <link
linkend="po_module">MODULE</link>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ENDT<indexterm id="po_endt"><primary>ENDT</primary><see>ENT</see></indexterm></term>
<listitem>
<para>Synonym of <link linkend="po_ent">ENT</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ENT<indexterm id="po_ent"><primary>ENT</primary><seealso>DISP</seealso></indexterm></term>
<listitem>
<para>Restore current address. See <link
linkend="po_disp">DISP</link> for more information.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><label> EQU<indexterm id="po_equ"><primary>EQU</primary><seealso>DEFL</seealso></indexterm> <expression>[,<pageNumber>]</term>
<listitem>
<para>To give the label a value other than the current program
counter. The label should not already exist (you can assign only one value to it).
The optional <code>pageNumber</code> can enforce explicit page value for the label
(for the <code>$$label</code> operator).
For modifiable labels holding temporary values use <link linkend="po_defl">DEFL</link>.<example>
<title></title>
<para><programlisting>Label EQU 3
Kip EQU 0x23*256 + low $</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>EXPORT<indexterm id="po_export"><primary>EXPORT</primary></indexterm> <label></term>
<listitem>
<para>The named label will be written to the export-file, in the
form 'label: EQU value'. This way the export-file can be
included in other sources. Order of labels in file follows the order of EXPORT statements.
<example>
<title></title>
<para><programlisting>DRIE=3
EXPORT DRIE ; adds into export file line: "DRIE: EQU 0x00000003"</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>FPOS<indexterm id="po_fpos"><primary>FPOS</primary></indexterm> <position></term>
<listitem>
<para>The FPOS directive makes it possible to set the file
position to anywhere in the output file. Position value without sign
is used as absolute one to be set, position starting with + or - sign will be
used as relative position.</para>
<para>In combination with <link
linkend="po_output">OUTPUT</link> <filename>,r it is
possible to update existing files.</para>
<para><example>
<title></title>
<para><programlisting>; This example will result in a file with a length of one byte:
BYTE 0
FPOS 0
BYTE 1
END</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>HEX<indexterm id="po_hex"><primary>HEX</primary><seealso>DH</seealso></indexterm></term>
<listitem>
<para>Synonym of <link linkend="po_dh">DH</link>, usually used without quotes around data.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>INCBIN<indexterm id="po_incbin"><primary>INCBIN</primary></indexterm>
<filename>[,<offset>[,<length>]]</term>
<listitem>
<para>To include a binary file into the outputfile. The offset
and length are optional. Added in v1.12.1: if negative offset or length is provided,
it counts relatively from the end of the file.<example>
<title></title>
<para><programlisting> INCBIN "gfx.scc",7 ; include gfx.scc, skip first 7 bytes
INCBIN "rantab.com",3,256 ; include 256 bytes from offset 3
INCBIN gfx.scc ,,7 ; 7 bytes from offset 0 (unquoted filename must end with space)
INCBIN "48.rom",-768,-256 ; include (from 16kiB file) 512 bytes 15616..16127</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>INCHOB<indexterm id="po_inchob"><primary>INCHOB</primary></indexterm> <filename>[,<offset>[,<length>]]</term>
<listitem>
<para>To include a data from a hobeta file into the outputfile.
The offset and length are optional.<example>
<title></title>
<para><programlisting> INCHOB "gfx.$c",7 ; include gfx.scc, skip first 7 bytes
INCHOB "sprs.$c",3,256 ; include 256 bytes from offset 3
INCHOB gfx.$c ,7 ; note the space between the filename and the ',7' here :)</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>INCLUDE<indexterm id="po_include"><primary>INCLUDE</primary></indexterm> <filename></term>
<listitem>
<para>To include another sourcefile into the current.
Sourcefiles can be nested 20 levels deep. If the file cannot be
found in the current directory (the current directory is the
directory the current asm file comes from!) the file will be searched
for in the directories specified at the commandline. When angle
brackets are used, the commandline directories are searched
before the current directory.</para>
<para>The directory used to launch the assembling process is automatically added
to the list (as if "<code>-i.</code>" was added to command line manually)
(v1.14.0 and v1.14.1 don't add it, reverted back for v1.14.2). If you want to start
with completely empty include-path list, use "<code>--inc</code>" option
early (order matters) without the "=" to empty the current list, like:
<code>sjasmplus --inc --inc=path1 --inc=path2 file.asm</code>
<example>
<title></title>
<para><programlisting> INCLUDE <VDP.I> ; search for file "VDP.I" in the include directories, then in current
INCLUDE MORE.I ; search for "MORE.I" in current directory, then in include directories
INCLUDE "MORE.I"</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>INCLUDELUA<indexterm id="po_includelua"><primary>INCLUDELUA</primary></indexterm> <filename></term>
<listitem>
<para>To include another LUA script in first pass(!). If the
file cannot be found in the current directory (the current
directory is the directory the current file comes from) the file
will be searched for in the directories specified at the
commandline. When angle brackets are used, the commandline
directories are searched before the current directory.<example>
<title></title>
<para><programlisting> INCLUDELUA <mylibrary1.lua>
INCLUDELUA mylibrary2.lua
INCLUDELUA "library_for_zx.lua"</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>INCTRD<indexterm id="po_inctrd"><primary>INCTRD</primary></indexterm>
<filenameoftrdimage>,<filenameintrdimage>[,<offset>[,<length>]]</term>
<listitem>
<para>To include a file from a TRD image into the outputfile.
The offset and length are optional.<example>
<title></title>
<para><programlisting> INCTRD "test.trd","mygfx.C" ; include mygfx.C from test.trd
INCTRD "test.trd","mygfx.C",12 ; include mygfx.C from test.trd, skip first 12 bytes</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>INSERT<indexterm id="po_insert"><primary>INSERT</primary><see>INCBIN</see></indexterm> <filename>[,<offset>[,<length>]]</term>
<listitem>
<para>INSERT is a synonym of <link
linkend="po_incbin">INCBIN</link>. See above.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LABELSLIST<indexterm id="po_labelslist"><primary>LABELSLIST</primary></indexterm> <filename>[,<virtual labels>]</term>
<listitem>
<para><emphasis>Useful only for ZX-Spectrum Emulator
UNREALSPECCY.</emphasis></para>
<para><emphasis>Works only in real device emulation mode. See
<link linkend="po_device">DEVICE</link>.</emphasis></para>
<para>Save labels list in format:</para>
<para><synopsis>NN:ADDRESS LABELNAME</synopsis>
where NN is number of RAM page and ADDRESS is truncated to 0000..3FFF range</para>
<para>If <code><virtual labels></code> is non zero, then the page number NN is not
part of output, and ADDRESS is truncated to 0000..FFFF range.</para>
<para><example>
<title></title>
<para><programlisting> LABELSLIST "x:/somepath/user.l"</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>LUA<indexterm id="po_lua"><primary>LUA</primary></indexterm> [pass]</term>
<listitem>
<para>Using pseudo-ops LUA and ENDLUA you can insert Lua
scripts. See more in the chapter "<link
linkend="c_lua_scripting">Lua scripting</link>".</para>
<para>Parameter is optional. It may be:<synopsis>PASS1 - interpret Lua script in first pass only.
PASS2 - interpret Lua script in second pass only.
PASS3 - interpret Lua script in third pass only. By default.
ALLPASS - interpret Lua script in all passes. It is needed if you generate some Z80 code.</synopsis></para>
<para><example>
<title></title>
<para><programlisting> LUA
-- some comments
print "Hi, man! This is Lua!"
ENDLUA
; some code now:
LUA ALLPASS
_pl("LABEL LD A,10")
_pc("RET")
ENDLUA</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>MEMORYMAP</term> <!-- intentionally removed from index -->
<listitem>
<para>Not available yet.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>MMU<indexterm id="po_mmu"><primary>MMU</primary><seealso>DEVICE</seealso><seealso>SLOT</seealso><seealso>PAGE</seealso></indexterm> <first slot number or address> [<last slot number or address>|<single slot option>], <page number>[,<address>]</term>
<listitem>
<para>Maps memory page(s) to slot(s), similar to SLOT + PAGE combination, but allows
to set up whole range of consecutive slots (with consecutive memory pages). Or when
only single slot is specified, extra option can be used to extend particular slot
functionality. The slot behaviour will stay set in the current DEVICE until reset
by another MMU specifying same slot (even as part of range, that will clear the option
to "default").</para>
<para>The optional third argument is address for <link linkend="po_org">ORG</link>
functionality.</para>
<para>(since v1.18.1) You can also use starting address of particular slot instead
of its number, ie. for ZX128: <code>MMU $8000,3</code> is alias of <code>MMU 2,3</code></para>
<para>Single slot option (default state is: no error/warning and no wrap = nothing special):
<synopsis>e = error on writing beyond last byte of slot
w = warning on writing beyond last byte of slot
n = wrap address back to start of slot, map next page</synopsis>
<example>
<title>docs_examples/po_mmu.asm</title>
<para><programlisting> DEVICE ZXSPECTRUM128 : LABELSLIST "po_mmu.lbl" ; to check label pages
MMU 1 3, 5 ; maps slots 1, 2, 3 with pages 5, 6, 7
ORG 0xBFFF
label1_p6: scf ; last byte of page 6 (in slot 2)
label2_p7: scf ; first byte of page 7 (in slot 3)
MMU 3 e, 0 ; page 0 into slot 3, write beyond slot will cause error
ORG 0xFFFF
ld a,1 ; error: Write outside of memory slot: 65536 (65536 = address outside)
MMU 3 n, 1 ; page 1 into slot 3, make it wrap + map next page automatically
ORG 0xFFFF ; ! also the $ address was truncated by MMU from $10001 to $0001 !
label3_p1: scf ; last byte of page 1, then wrapping back to 0xC000 with page 2
label4_p2: scf ; first byte of page 2 at 0xC000</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>MODULE<indexterm id="po_module"><primary>MODULE</primary></indexterm> <name></term>
<listitem>
<para>
Labels has to be unique only whithin the current module (module is added as prefix to them).
Also note the use of '@' operator to suppress all this label-processing. Modules can
be nested, and module has to be ended by <link linkend="po_endmodule">ENDMODULE</link>.
<example>
<title>docs_examples/po_module.asm</title>
<programlisting> MODULE xxx
Kip: ; label xxx.Kip
ld hl,@Kip ; global Kip
ld hl,@Kop ; global Kop
ld hl,Kop ; xxx.Kop
Kop: ; label xxx.Kop
ld hl,Kip ; xxx.Kip
ld hl,yyy.Kip ; yyy.Kip
ld hl,nested.Kip ; xxx.nested.Kip
MODULE nested
Kip: ret ; label xxx.nested.Kip
ENDMODULE
ENDMODULE
MODULE yyy
Kip: ret ; label yyy.Kip
@Kop: ret ; label Kop (global one, no module prefix)
@xxx.Kop: nop ; ERROR: duplicate: label xxx.Kop
ENDMODULE
Kip ret ; global label Kip</programlisting>
</example>
Since v1.14.0 the module <code><name></code> can NOT contain dot character. You can
use nested modules to get identical identifier as in older versions, or please rename with
underscores/etc:
<programlisting> ; invalid since v1.14.0
MODULE older.version
fn1: ret ; final label: @older.version.fn1
ENDMODULE
; can be replaced in v1.14.0 with
MODULE new
MODULE version
fn1: ret ; final label: @new.version.fn1
ENDMODULE
ENDMODULE</programlisting>
Since v1.14.0 the <code>MODULE</code> and <code>ENDMODULE</code> also resets the current "non-local"
label prefix back to "_":
<programlisting>Kep: ; "Kep" label (global one), and also works as "non-local" prefix for local labels
MODULE zzz
.local: ; in v1.14.0 this will be "zzz._.local" label, previously it was "zzz.Kep.local"
Kup: ; this is "zzz.Kup", but also defines "non-local" prefix as "Kup"
.local ; this is "zzz.Kup.local"
ENDMODULE
.local: ; in v1.14.0 this will be "_.local" label, previously it was "Kup.local"</programlisting>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><para>OPT<indexterm id="po_opt"><primary>OPT</primary></indexterm> [push] [reset] [listoff] [liston] [listall] [listact] [listmc] [<command line options>]</para>
<para>OPT pop</para></term>
<listitem>
<para>Allows to reset and modify <link linkend="s_cli">options</link> affecting syntax and
parsing (for lines of source following the OPT). The options allowed for OPT
are: <code>-W[no-]<warning_id></code>, <code>--syntax</code>, <code>--zxnext</code>,
<code>--reversepop</code> and <code>--dirbol</code>.
</para>
<para>
Ahead of options you can use OPT commands: push, pop, reset, listoff, liston, listall, listact, listmc.
The "push" command will make OPT to preserve current state of options. The "reset"
command will reset OPT-related options to default state. The "listoff" command will
suspend the listing for following lines until "liston" command is used (listing
availability is part of the push/pop state, so to "nest" listing-off you can use
"OPT push listoff : ... code ... : OPT pop" code sequence). The "listall", "listact"
and "listmc" commands will select the filter for listing. The "listmc" lists only
lines containing machine code bytes, "listact" will remove the "skipped" blocks
(like false-blocks of IF/ELSE conditional assembling, or inner definitions of macros
and structures), "listall" will switch back to default listing without filtering.
</para>
<para>Then the provided options are applied. The default values are: fake instructions
enabled (no warning), multi-argument delimiter is ",", both () and [] brackets
can be used to access memory, labels can have any name, ZX Next instructions are OFF,
POP with multiple arguments doesn't reverse them and pseudo-ops at beginning of
line are OFF (to just reset to these defaults you can use <code>OPT reset</code>).
</para>
<para>The "pop" command: the previously preserved state of options is restored (states
are preserved in "stack" way, so further OPT with "pop" will restore older states).
</para>
<para>The <link linkend="s_id_warnings">id-warning system</link> state is NOT saved/restored
by OPT push/pop/reset and can be modified only by <code>-W</code> option.
</para>
<example>
<title>docs_examples/po_opt.asm</title>
<programlisting> POP bc, hl ; pops BC first
OPT push reset --reversepop --syntax=af
POP bc,,hl ; pops HL first
LD bc,hl ; warning about Fake instruction
LD bc,hl ; warning supressed by lowercase "fake" in this comment
OPT reset --syntax=a
POP bc,,hl ; pop BC first (--reversepop was reset)
OPT pop ; restoring syntax to original state</programlisting>
</example>
</listitem>
</varlistentry>
<varlistentry>
<term>ORG<indexterm id="po_org"><primary>ORG</primary><seealso>DEVICE</seealso></indexterm> <address>[,<page_number>]</term>
<listitem>
<para>Set the program counter to a specific address. If the second argument is
provided, it will change memory page in the current slot, see
<link linkend="po_page">PAGE</link> and <link linkend="po_slot">SLOT</link> (it will
warn you when <address> is outside of it).</para>
<para>When used inside <link linkend="po_disp">DISP</link> block, only the virtual
"displaced" program counter is affected, but the machine code will be still
sequentially emitted in the original physical location and warning is emitted.
<example>
<title>docs_examples/po_org.asm</title>
<para><programlisting> ORG 100h ; or 0x100, or $100, or #100
; useful macro that padding code
MACRO PADORG addr
; add padding
IF $ < addr
BLOCK addr-$
ENDIF
ORG addr
ENDM
MACRO PADORG2 addr ; z80asm "FORG" replacement
; add padding + display warning
IF $ > addr
; no padding
DISPLAY /L, "Warning! PADORG failed! ", $, " is more than ", addr
ELSE
; add padding
BLOCK addr-$
ENDIF
ORG addr
ENDM</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>OUTEND<indexterm id="po_outend"><primary>OUTEND</primary><seealso>OUTPUT</seealso><seealso>SIZE</seealso></indexterm></term>
<listitem>
<para>Ends generating compiler output to file specified in OUTPUT and resets
<link linkend="po_size">SIZE</link> value to default "none".</para>
</listitem>
</varlistentry>
<varlistentry>
<term>OUTPUT<indexterm id="po_output"><primary>OUTPUT</primary><seealso>SIZE</seealso></indexterm>
[<filename>[,<mode>]]</term>
<listitem>
<para>With OUTPUT it is possible to create multiple files from
one source. All following instructions will be assembled to this
file. It will also <link linkend="po_outend">close (OUTEND)</link>
and finalize any previously opened output.</para>
<para>There are three possible output modes: truncate (overwrite
existing files, this is the default), rewind (open and execute
FPOS 0) and append (open and leave the file pointer at the end
of the file).<synopsis>OUTPUT <filename>,t ; truncate (default)
OUTPUT <filename>,r ; rewind
OUTPUT <filename>,a ; append</synopsis>
<example>
<title>bigfile.asm</title>
<para><programlisting> OUTPUT loader.com
ORG 100H
INCLUDE loader.asm
INCLUDE bios.asm
OUTPUT bigfile.dat
ORG 4000H
INCLUDE main.asm
ORG 8000H
INCLUDE data.asm
OUTEND
INCLUDE next.asm</programlisting></para>
</example>This will create two files: loader.com and
bigfile.dat.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAGE<indexterm id="po_page"><primary>PAGE</primary><seealso>DEVICE</seealso><seealso>MMU</seealso><seealso>SLOT</seealso></indexterm> <number></term>
<listitem>
<para><emphasis>Works only in real device emulation mode. See
<link linkend="po_device">DEVICE</link>.</emphasis></para>
<para>Set the current memory page to current slot.</para>
<para><example>
<title></title>
<para><programlisting> PAGE 7 ;set 7 page
SAVEBIN "ram7.bin",$C000,$4000 ;- save $4000 begin from $C000 of RAM to file</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>PHASE<indexterm id="po_phase"><primary>PHASE</primary><see>DISP</see></indexterm></term>
<listitem>
<para>Synonym of <link linkend="po_disp">DISP</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RELOCATE_END<indexterm id="po_relocate_end"><primary>RELOCATE_END</primary></indexterm></term>
<listitem>
<para>Ends the block of code for which relocation data are produced (started by
<link linkend="po_relocate_start">RELOCATE_START</link>). To get the relocation
data themselves, use <link linkend="po_relocate_table">RELOCATE_TABLE</link> and
related symbols.</para>
<para>For more details/examples check the <ulink url="https://github.com/z00m128/sjasmplus/tree/master/examples/relocation">examples/relocation</ulink>,
<ulink url="https://github.com/z00m128/sjasmplus/tree/master/examples/SymbOS_nslookup">examples/SymbOS_nslookup</ulink> and the
<ulink url="https://github.com/z00m128/sjasmplus/tree/master/tests/relocate">relocation tests</ulink>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RELOCATE_START<indexterm id="po_relocate_start"><primary>RELOCATE_START</primary></indexterm> [HIGH]</term>
<listitem>
<para>Marks start of block for which relocation data are produced. Any *regular* label
(not EQU/DEFL symbols) defined inside the RELOCATE_START .. RELOCATE_END block will
be treated as "relocatable" label. Any instruction/directive within the block which
needs resulting opcode adjusted when relocated to different address will produce
relocation-data for the <link linkend="po_relocate_table">RELOCATE_TABLE</link>.
</para>
<para>The <code>RELOCATE_START HIGH</code> variant checks only high-byte relocation.
The produced table points to high byte (MSB) of the machine code. This mode is
for OS/loaders which relocate only to 256-byte aligned boundaries (keeping LSB intact).</para>
<para>The relocation feature of regular label is transitive and EQU value based on already
relocatable label will be tagged as relocatable too. Also structures instantiated in
relocatable block have their labels tagged as relocatable and their initial values may
become part of relocation data if the initial value is based on relocatable value.</para>
<para>You can prepend operator <code>norel</code> to label to strip it of its relocatable
property for particular expression.</para>
<para>The internal heuristic is not bullet-proof, some complex expression may fail
to be recognised as fixed/relocatable value and instead warn about unstable result.
It is recommended to assemble relocatable blocks in lower regions of address space
(like <code>ORG 0</code> or <code>ORG $1000</code>) and to keep expressions simple enough.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RELOCATE_TABLE<indexterm id="po_relocate_table"><primary>RELOCATE_TABLE</primary></indexterm> [<subtract_offset>]</term>
<listitem>
<para>Emits relocation data gathered across all relocation blocks. There are also
two built-in symbols <code>relocate_count</code> and <code>relocate_size</code>
containing the size of the table (only word-type tables are supported in sjasmplus,
so size is always doubled count).</para>
<para>The table is raw array of WORD (16 bit) values with memory offsets of machine
code which should be adjusted (when the code is relocated to different than original
base address). To get offsets from particular base address, use <link linkend="po_org">ORG</link>
ahead of relocation block to land instructions and labels from there.</para>
<para>The <subtract_offset> is subtracted from every offset recorded in the relocation table
(same what WinAPE does with its optional argument "base_address" for RELOCATE_TABLE).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>REPT<indexterm id="po_rept"><primary>REPT</primary><see>DUP</see></indexterm> <count>[, <index_variable>]</term>
<listitem>
<para>Synonym of <link linkend="po_dup">DUP</link>. There is also synonym ENDR to end REPT block (EDUP works too).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SAVE3DOS<indexterm id="po_save3dos"><primary>SAVE3DOS</primary></indexterm>
<filename>,<address>,<size>[,<type>[,<w2_line>[,<w3>]]]</term>
<listitem>
<para><emphasis>Works only in virtual device emulation mode. See
<link linkend="po_device">DEVICE</link>.</emphasis></para>
<para>Like <link linkend="po_savebin">SAVEBIN</link>, saves the block of device RAM
from "address", but with +3DOS 128 byte header prepended.<example>
<title></title>
<para><programlisting> DEVICE ZXSPECTRUM48
...
; +3 BASIC header (8 bytes starting from offset 15 in +3DOS header):
; type is first byte (0 = basic, 1, 2 = arrays, 3 = code/screen$)
; size is "first word" (bytes 1 and 2)
; w2_line argument is "second word" (bytes 3 and 4)
; w3 argument is "third word" (bytes 5 and 6) (default value = size)
; by default the type=3 (CODE/SCREEN$) is saved
SAVE3DOS "screen.bin", $4000, $1b00
; type 3: w2 argument $C000 is target load-address
SAVE3DOS "code.bin", $8000, $1234, 3, $C000
; type 0: BASIC, default w2 = $8000 (no auto-run)
SAVE3DOS "prg1.bas", $5c00, 1234, 0
; type 0: w2_line is LINE auto-run (30 in example)
SAVE3DOS "prg2.bas", $5c00, 1234, 0, 30
; type 1: Numeric array (refer to +3 manual for these)
SAVE3DOS "b.dat", $8000, 30, 1
; type 2: Character array (or maybe just ignore these)
SAVE3DOS "c.dat", $8000, 30, 2</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>SAVEAMSDOS<indexterm id="po_saveamsdos"><primary>SAVEAMSDOS</primary></indexterm>
<filename>,<address>,<size>[,<start = 0>[,<type = 2>]]</term>
<listitem>
<para><emphasis>Works only in virtual device emulation mode. See
<link linkend="po_device">DEVICE</link>.</emphasis></para>
<para>Like <link linkend="po_savebin">SAVEBIN</link>, saves the block of device RAM
from "address", but with AMSDOS 128 byte header prepended.<example>
<title></title>
<para><programlisting> DEVICE AMSTRADCPC464
... some code ...
; by default the type=2 (BINARY) is saved
; "start" (entry) value is by default 0, overriden here to $1234
SAVEAMSDOS "code.bin", $1000, $1b00, $1234</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>SAVEBIN<indexterm id="po_savebin"><primary>SAVEBIN</primary></indexterm>
<filename>,<startadress>,<lengthofcode></term>
<listitem>
<para><emphasis>Works only in real device emulation mode. See
<link linkend="po_device">DEVICE</link>.</emphasis></para>
<para>Save the block of RAM.</para>
<para><example>
<title></title>
<para><programlisting> PAGE 7 ;set 7 page to current slot
SAVEBIN "ram7.bin",$C000,$4000 ;- save 4000h begin from C000h of RAM to file
SAVEBIN "ram2.bin",$8000,$3000 ;- save 3000h begin from 8000h of RAM to file</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term><para>SAVECDT<indexterm id="po_savecdt"><primary>SAVECDT</primary></indexterm>
FULL <cdtname>[,<startaddr>[,<screenmode>[,<border>[,<ink0>...<ink15>]]]]</para>
<para>SAVECDT EMPTY <cdtname></para>
<para>SAVECDT BASIC <cdtname>,<name>,<start>,<length></para>
<para>SAVECDT CODE <cdtname>,<name>,<start>,<length>[,<customstartaddress>]</para>
<para>SAVECDT HEADLESS <cdtname>,<start>,<length>[,<sync>[,<format>]]</para></term>
<listitem>
<para><emphasis>Works only in Amstrad device emulation mode. See
<link linkend="po_device">DEVICE</link>.</emphasis></para>
<para>Manipulate CDT file (tape/TZX file format used by Amstrad CPC emulators).<example>
<title></title>
<para><programlisting> DEVICE AMSTRADCPC6128
...
; create empty CDT file (truncates already existing file to make it empty)
SAVECDT EMPTY "output.cdt"
; snapshot-like dump with default loader, including loading screen, all banks, ...
SAVECDT FULL "output.cdt" ; defaults: END start addres, screenmode=1, border=1
; ink# = 1, 24, 20, 6, 26, 0, 2, 8, 10, 12, 14, 16, 18, 22, 24, 16
; BASIC program prepared at address "label"
SAVECDT BASIC "output.cdt","A",label,length
; block of binary data at address "label" (default "entry" = "label")
SAVECDT CODE "output.cdt","C",label,length,entry
; headless block with custom sync and format at address "label", formats: 0 = AMSTRAD, 1 = ZX
SAVECDT HEADLESS "output.cdt",label,length,sync,format ; default sync = 0x16, format = 0</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>SAVECPCSNA<indexterm id="po_savecpcsna"><primary>SAVECPCSNA</primary></indexterm> <filename>[,<startadressofprogram>]</term>
<listitem>
<para><emphasis>Works only in AMSTRADCPC464 / AMSTRADCPC6128 real device emulation mode. See
<link linkend="po_device">DEVICE</link>.</emphasis></para>
<para>Save the snapshot for emulators of Amstrad CPC machines. (If start address is omitted,
the one provided by <link linkend="po_end">END</link> is used)</para>
<para>The snapshot header content is hard-wired in the sjasmplus binary, with the CRTC, Palette and Gate Array registers
set to those of a CPC after a boot into the main ROM. Similarly to the ZX-Spectrum SAVESNA directive, interrupts are disabled and must
be re-enabled by your program. A full list of the settings can be found in the
<ulink url="https://github.com/z00m128/sjasmplus/blob/master/sjasm/io_cpc.cpp#L66">source</ulink>.
If you absolutely need different defaults and can't afford init-code modifying the state, you can post-patch the resulting SNA
file directly from source, see <ulink url="https://github.com/z00m128/sjasmplus/issues/139">Issue #139</ulink> for example.
<example>
<title></title>
<para><programlisting> DEVICE AMSTRADCPC464
ORG $1200
START .... ;some code
RET
SAVECPCSNA "game.sna",START ;save snapshot to file game.sna. Start address is START ($1200)</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>SAVEDEV<indexterm id="po_savedev"><primary>SAVEDEV</primary></indexterm>
<filename>,<startPage>,<startOffset>,<length></term>
<listitem>
<para><emphasis>Works only in real device emulation mode. See
<link linkend="po_device">DEVICE</link>.</emphasis></para>
<para>Like <link linkend="po_savebin">SAVEBIN</link>, saves the block of device RAM.</para>
<para>But it allows lengths over 64ki, and the offset value goes directly into device
virtual memory (where pages are allocated consecutively), ignoring current slot
"mapping". I.e. page=2,offset=0 will start saving data from page 2 at its beginning,
going through pages 3, 4, 5, ... until the requested length of data is saved.</para>
<para>The offset is not limited to page size, i.e. arguments page=1,offset=0x500 are equal
to arguments page=0,offset=0x4500 for ZXSPECTRUM128 device (has page size 0x4000).</para>
<example>
<title></title>
<programlisting> DEVICE ZXSPECTRUM128 : SAVEDEV "fullram.bin",0,0,0x20000 ; save full 128kiB</programlisting>
</example>
</listitem>
</varlistentry>
<varlistentry>
<term>SAVEHOB<indexterm id="po_savehob"><primary>SAVEHOB</primary></indexterm>
<filename>,<filename_in_trdos>,<startadress>,<lengthofcode></term>
<listitem>
<para><emphasis>Works only in real device emulation mode. See
<link linkend="po_device">DEVICE</link>.</emphasis></para>
<para>Save the block of RAM in Hobeta format.</para>
<para><example>
<title></title>
<para><programlisting> PAGE 7 ;set 7 page to current slot
SAVEHOB "ram7.$c","myfile1.C",$C000,$4000 ;- save 4000h begin from C000h of RAM to file
SAVEHOB "ram2.$c","myfile2.C",$8000,$3000 ;- save 3000h begin from 8000h of RAM to file</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>SAVENEX<indexterm id="po_savenex"><primary>SAVENEX</primary></indexterm> <command> <command arguments></term>
<listitem>
<para>Commands to build NEX file, for details check <link linkend="c_savenex">SAVENEX
</link> chapter.</para>
<para><emphasis>Works only in ZXSPECTRUMNEXT device emulation mode. See
<link linkend="po_device">DEVICE</link>.</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term>SAVESNA<indexterm id="po_savesna"><primary>SAVESNA</primary></indexterm> <filename>[,<startadressofprogram>]</term>
<listitem>
<para><emphasis>Works only in real device emulation mode. See
<link linkend="po_device">DEVICE</link>.</emphasis></para>
<para>Save the snapshot for emulators of ZX-Spectrum. (If start address is omitted,
the one provided by <link linkend="po_end">END</link> is used)</para>
<para>The snapshot header content is hard-wired in sjasmplus binary (disabled interrupts may surprise some users, you can check
the <ulink url="https://github.com/z00m128/sjasmplus/blob/master/sjasm/io_snapshots.cpp#L55">source</ulink> to see all the values).
If you absolutely need different defaults and can't afford init-code modifying the state, you can post-patch the resulting SNA
file directly from source, see <ulink url="https://github.com/z00m128/sjasmplus/issues/139">Issue #139</ulink> for example.
<example>
<title></title>
<para><programlisting> DEVICE ZXSPECTRUM128
ORG $8000
START .... ;something code
RET
SAVESNA "game.sna",START ;save snapshot to file game.sna. Start address is START ($8000)</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term><para>SAVETAP<indexterm id="po_savetap"><primary>SAVETAP</primary></indexterm> <filename>,BASIC,<fileintapeheader>,<start>,<length>[,<autorunline>[,<lengthwithoutvars>]]</para>
<para>SAVETAP <filename>,CODE,<fileintapeheader>,<start>,<length>[,<customstartaddress>[,<optional3rdparam>]]</para>
<para>SAVETAP <filename>,NUMBERS,<fileintapeheader>,<start>,<length>[,<variableletter(A..Z)>]</para>
<para>SAVETAP <filename>,CHARS,<fileintapeheader>,<start>,<length>[,<variableletter(A..Z)>]</para>
<para>SAVETAP <filename>,HEADLESS,<start>,<length>[,<customblockflag(0..255)>]</para></term>
<listitem>
<para><emphasis>Works only in real device emulation mode. See
<link linkend="po_device">DEVICE</link>.</emphasis></para>
<para>Append the tape header or block of data to the end of the
standard tape file for emulators of ZX-Spectrum.<example>
<title></title>
<para><programlisting> DEVICE ZXSPECTRUM48
...
EMPTYTAP "output.tap"
SAVETAP "output.tap",BASIC,"noAutorun",label,100
SAVETAP "output.tap",BASIC,"w/Autorun",label,100,9999
SAVETAP "output.tap",BASIC,"withVars",label,123,9999,100
SAVETAP "output.tap",CODE,"bank17",screen,6912
SAVETAP "output.tap",CODE,"screen",demo,length,org
SAVETAP "output.tap",NUMBERS,"dimArray",label,100 ; a()
SAVETAP "output.tap",NUMBERS,"othernum",label,200,'b' ; b()
SAVETAP "output.tap",CHARS,"charArray",label,300 ; a$()
SAVETAP "output.tap",CHARS,"nextone",label,400,'m' ; m$()
SAVETAP "output.tap",HEADLESS,start,length</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>SAVETAP <filename>[,<startadressofprogram>]</term>
<listitem>
<para><emphasis>Works only in real device emulation mode. See
<link linkend="po_device">DEVICE</link>.</emphasis></para>
<para>Save the tape file for emulators of ZX-Spectrum as a
"snapshot" of almost-whole memory. Generated tape file supports the
ZX-Spectrum clones with extended RAM such as ATM Turbo 512, etc.
(If start address is omitted, the one provided by <link linkend=
"po_end">END</link> is used)</para>
<para>The stored memory starts at $5E00 (with screen data at $4000 auto-detected
and optionally stored into the TAP file). The stored memory is automatically
trimmed of zero values at start and end of the region (put non-zero byte markers
around region you want to store, if you have zero-ed bytes at beginning or end
of your code).
<example>
<title></title>
<programlisting> DEVICE ZXSPECTRUM48
ORG $7FFF
DB $01 ; non-zero marker to store the following zero-ed data
DAT DS 1024, 0 ; zero-ed data at $8000 (1024 bytes)
START .... ; some code
RET
SAVETAP "game.tap", START ; save tape-snapshot to file game.tap. Start address is $8400</programlisting>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>SAVETRD<indexterm id="po_savetrd"><primary>SAVETRD</primary></indexterm> <filename_of_trd_image>,<filename_in_trdos>,<address>,<length>[,<autostart_BASIC_line>[,<length_minus_variables>]]</term>
</varlistentry>
<varlistentry>
<term>SAVETRD <filename_of_trd_image>,|<filename_in_trdos>,<address>,<length>[,<autostart_BASIC_line>]</term>
</varlistentry>
<varlistentry>
<term>SAVETRD <filename_of_trd_image>,&<filename_in_trdos>,<address>,<length></term>
<listitem>
<para><emphasis>Works only in real device emulation mode. See
<link linkend="po_device">DEVICE</link>.</emphasis></para>
<para>Save the device memory into TRD disk image. Saving two files with same filename will
emit warning, but two files (with same name) will be created in the disk directory.</para>
<para>Adding pipe character "|" ahead of file
name will make sjasmplus to delete old file(s) with the same name before writing
the new one => replace-like functionality. If the deleted file did occupy all
sectors till the free space position in disc info, sjasmplus will salvage those sectors
back and save new file over them (but it will not do full reshuffle/defrag in more
complex cases, sjasmplus is just assembler, not full featured TRD images manipulation tool).</para>
<para>Adding ampersand character "&" ahead of file name will make sjasmplus to look
for existing file with the requested name (last of them, any earlier duplicates are deleted).
The new content is appended to the file (sector aligned append) and the catalog entry gets
only number of sectors patched, up to 255 sectors at most. This is special mode for
single-file big-loaders.</para>
<para>The unofficial three-letter extensions are also supported (official extensions
are only: B, C, D and #).
<example><title></title>
<para><programlisting> EMPTYTRD "test.trd" ;create empty TRD image
PAGE 7 ;set 7 page to current slot
SAVETRD "test.trd","myfile1.C",$C000,$4000 ;- save 4000h begin from C000h of RAM to file to TRD image
SAVETRD "test.trd","myfile2.C",$8000,$3000 ;- save 3000h begin from 8000h of RAM to file to TRD image
SAVETRD "test.trd",|"myfile1.C",$B000,$400 ;- replace "myfile1.C" with new file
SAVETRD "test.trd",&"myfile1.C",$9000,$734 ;- sector-append new data to "myfile1.C"</programlisting></para>
</example>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SETBP<indexterm id="po_setbp"><primary>SETBP</primary><seealso>BPLIST</seealso></indexterm> [<expression>]</term>
</varlistentry>
<varlistentry>
<term>SETBREAKPOINT<indexterm id="po_setbreakpoint"><primary>SETBREAKPOINT</primary><see>SETBP</see></indexterm> [<expression>]</term>
<listitem>
<para>
<emphasis>Works only in real device emulation mode. See
<link linkend="po_device">DEVICE</link>.</emphasis>
</para>
<para>Will add execution-type breakpoint at address <expression> to the
<link linkend="po_bplist">BPLIST</link> export file. If no expression is specified,
the current program counter will be used.
<example>
<title></title>
<programlisting> BPLIST "cmd_line.options.txt" zesarux ; open breakpoints list in "ZEsarUX" format
start:
nop ; ZEsarUX will not catch very first instruction of snapshot file loaded
SETBP ; so breakpoint ahead of the second instruction (after first "nop")
xor a
SETBP some_routine_label ; set also some breakpoint to other code by its label
SETBREAKPOINT $0D6B ; alias of SETBP, works identically
; ... your code of app
</programlisting>
</example>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SHELLEXEC<indexterm id="po_shellexec"><primary>SHELLEXEC</primary></indexterm> <filename>[,<parameters>]</term>
<listitem>
<para>Execute external program <filename> using optional
command line <parameters>.<example>
<title></title>
<para><programlisting> OUTPUT "mybin.bin"
;some code
IF ((_ERRORS = 0) && (_WARNINGS = 0))
SHELLEXEC "x:/somepath/bin2tap.exe mybin.bin mytap.tap"
; or SHELLEXEC "x:/somepath/bin2tap.exe","mybin.bin mytap.tap"
ENDIF</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>SIZE<indexterm id="po_size"><primary>SIZE</primary><seealso>OUTPUT</seealso></indexterm> <filesize in bytes></term>
<listitem>
<para>If the resulting file is less than the given length, as
many zero bytes are added as necessary. See <link
linkend="po_output">OUTPUT</link> for more.<example>
<title></title>
<para><programlisting> SIZE 32768 ; make sure file will be 32K</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>SLDOPT<indexterm id="po_sldopt"><primary>SLDOPT</primary></indexterm> <type> <arguments></term>
<listitem>
<para>Type `<code>COMMENT</code>` - add comma delimited list of case sensitive keywords
to be detected in end-of-line comments and exported to
<link linkend="c_sld_data">Source Level Debugging (SLD) data</link>.
The particular keywords depend on the debugger you are using to process SLD data.</para>
<para><example>
<title></title>
<para><programlisting> DEVICE ZXSPECTRUM128
SLDOPT COMMENT WPMEM, Log
ORG $8000
call init ; Log("calling init") - gets exported to SLD
ret ; no keyword here - not exported to SLD
var1 DB 1 ; WPMEM - exported
var2 DB 2 ; WpMem - not exported, case sensitive!</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>SLOT<indexterm id="po_slot"><primary>SLOT</primary><seealso>DEVICE</seealso><seealso>MMU</seealso><seealso>PAGE</seealso></indexterm> <number_or_address></term>
<listitem>
<para><emphasis>Works only in real device emulation mode. See
<link linkend="po_device">DEVICE</link>.</emphasis></para>
<para>Set current slot. Slots are defined by DEVICE pseudo-op.
Use pseudo-op <link linkend="po_page">PAGE</link> to change page
in the current slot.</para>
<para>(since v1.18.1) You can also use starting address of particular slot instead
of its number, ie. for ZX128: <code>SLOT $8000</code> is alias of <code>SLOT 2</code></para>
<para><example>
<title></title>
<para><programlisting> DEVICE ZXSPECTRUM128
SLOT 3 ;from 0C000h to 0FFFFh
PAGE 1 ;set page 1 to slot 3
ORG 0C000h
;your program here
PAGE 2
INCBIN "somegfx.bin"
;....</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>TAPEND<indexterm id="po_tapend"><primary>TAPEND</primary><seealso>TAPOUT</seealso></indexterm></term>
<listitem>
<para>Ends generating compiler output to tape file block specified in TAPOUT.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>TAPOUT<indexterm id="po_tapout"><primary>TAPOUT</primary></indexterm> <filename>[,<flagbyte>]</term>
<listitem>
<para>Appends one tape block at the end of specified file.
All following code will be assembled to this tape file block.</para>
<para>Default value of flagbyte is 255.<example>
<title>bigfile.asm</title>
<para><programlisting> EMPTYTAP screen.tap
TAPOUT screen.tap,0
DB 3
DB 'ScreenName'
DW 6912
DW 16384
DW 32768
TAPEND
TAPOUT screen.tap
INCBIN screen.bin
TAPEND</programlisting></para>
</example>This will create tap file with the screen.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>TEXTAREA<indexterm id="po_textarea"><primary>TEXTAREA</primary><see>DISP</see></indexterm> <address></term>
<listitem>
<para>Synonym of <link linkend="po_disp">DISP</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>UNDEFINE<indexterm id="po_undefine"><primary>UNDEFINE</primary><seealso>DEFINE</seealso></indexterm> <id></term>
<listitem>
<para>Removes the identifier defined by <link
linkend="po_define">DEFINE</link></para>
<para><example>
<title></title>
<para><programlisting> DEFINE Release 1
IFDEF Release
DISPLAY "Building release version"
ENDIF
UNDEFINE Release
IFNDEF Release
DISPLAY "It's works!"
ENDIF
IFDEF _SJASMPLUS
DISPLAY "Yes, it's the sjasmplus!"
ENDIF
UNDEFINE * ; undefine all identifiers
IFNDEF _SJASMPLUS
DISPLAY "It's not the sjasmplus??"
ENDIF</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>UNPHASE<indexterm id="po_unphase"><primary>UNPHASE</primary><see>ENT</see></indexterm></term>
<listitem>
<para>Synonym of <link linkend="po_ent">ENT</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>WHILE<indexterm id="po_while"><primary>WHILE</primary></indexterm> <expression>[, <guardian-counter>]</term>
<listitem>
<para>While expression evaluates to non-zero value, generates following lines until
an ENDW (EDUP/ENDR alias) pseudo-op is encountered.</para>
<para>The optional guardian-counter value will abort the WHILE if there are
more iterations, default guardian-counter is set to 100k.
<example>
<title></title>
<programlisting>ptr = $4000
WHILE ptr < $4020, 500 ; max 500 loops before error
DB low ptr
ptr = ptr + 1
ENDW ; EDUP or ENDR works too, but ENDW is advised for WHILE
/* will emit bytes $00, $01, ..., $1F */</programlisting>
</example>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>WORD<indexterm id="po_word"><primary>WORD</primary></indexterm> <words></term>
<listitem>
<para>Defines a word. Values should be between -32787 and
65536.<example>
<title></title>
<para><programlisting> WORD 4000h,0d000h
WORD 4,"HA"</programlisting></para>
</example></para>
</listitem>
</varlistentry>
</variablelist></para>
</section>
<section id="s_conditional_assembly"><indexterm id="s_conditional_assembly2"><primary>Conditional assembly</primary></indexterm>
<title>Conditional assembly</title>
<para>It may be useful to assemble a part (or not) based on a certain
condition.</para>
<para><variablelist>
<varlistentry>
<term>IF<indexterm id="ca_if"><primary>IF</primary></indexterm> <expression></term>
<listitem>
<para>If <expression> is non-zero the following lines are
assembled until an ELSE, ELSEIF or ENDIF.</para>
<para>Forward reference of label will cause warning - as any machine code emitted inside
the IF/IFN block with such expression can lead to unstable results. If you are sure
the late definition of label will not affect resulting machine code (the IF block
does not emit any machine code and does not define any label), you can suppress the
warning.</para>
<example>
<title></title>
<para><programlisting> IF (aaa == 0) || (2 = aaa && ((bbb % 13) & 0x01))
; some code to assemble only if the symbol `aaa` is zero
; or (logical OR) when symbol `aaa` is two
; and (logical AND) modulo 13 of `bbb` is odd number
ENDIF</programlisting>
</para>
</example>
</listitem>
</varlistentry>
<varlistentry>
<term>IFN<indexterm id="ca_ifn"><primary>IFN</primary></indexterm> <expression></term>
<listitem>
<para>If <expression> is zero the following lines are
assembled until an ELSE, ELSEIF or ENDIF.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>IFDEF<indexterm id="ca_ifdef"><primary>IFDEF</primary></indexterm> <id></term>
<listitem>
<para>The condition is true if there is an id defined. These are
NOT labels.</para>
<para><example>
<title></title>
<para><programlisting> IFDEF MSX_LEAN_AND_MEAN
CALL InitOwnMM
ELSE
CALL InitDos2MemMan
ENDIF</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>IFNDEF<indexterm id="ca_ifndef"><primary>IFNDEF</primary></indexterm> <id></term>
<listitem>
<para>The condition is true if there isn't an id defined. These
are NOT labels.</para>
<para><example>
<title></title>
<para><programlisting>1 IN A,(0C4H)
AND 2
IFNDEF DEBUG
JR NC,1B
ENDIF</programlisting></para>
</example></para>
</listitem>
</varlistentry>
<varlistentry>
<term>IFUSED<indexterm id="ca_ifused"><primary>IFUSED</primary></indexterm> <label></term>
<listitem>
<para>The condition is true if there is an label used somewhere
in the code. You can create libraries of useful functions using
IFUSED pseudo-op</para>
<para><example>
<title>(similar to tests/misc/ifused_test.asm)</title>
<para><programlisting> OUTPUT "TEST.OUT"
CALL LABEL3 ; LABEL3 - yes
LD A,(LABEL1) ; LABEL1 - yes
IFUSED LABEL1
LABEL1:
DB 1
ENDIF
IFUSED LABEL2
LABEL2:
DB 2
ENDIF
IFUSED LABEL3
LABEL3:
DB 3
ENDIF
IFUSED LABEL4
LABEL4:
DB 4
ENDIF
LD A,LABEL2 ; LABEL2 - yes
RET
; Output will contain bytes from LABEL1 to LABEL3 (1, 2, 3), but not contain from LABEL4, because this label is not used.
; Alternative syntax:
LABEL5:
IFUSED ; sjasmplus will use name of previous label, i.e. LABEL5
ENDIF
</programlisting></para>
</example></para>
<para>Known bug: when code is using label inside module "moduleX",
like <code>call labelY</code>, only usage of <code>moduleX.labelY</code> label is noted.
Then if you define "labelY" outside of module and hide it inside <code>IFUSED labelY</code>
block, the call from module will be unable to find the routine.
</para>
<para>
Workaround: you can use the global-label operator @: "<code>call @labelY</code>" to
trigger usage of the global "labelY", or you can use the alternative IFUSED syntax
"<code>labelY: IFUSED</code>" which does not only check condition, but also does define the label.
Once the label is defined, the "call labelY" line inside module will find the global
variant and mark it as "used" correctly.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>IFNUSED<indexterm id="ca_ifnused"><primary>IFNUSED</primary></indexterm> <label></term>
<listitem>
<para>The condition is true if there is an label
<emphasis>not</emphasis> used somewhere in the code.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ELSE<indexterm id="ca_else"><primary>ELSE</primary><seealso>IF</seealso></indexterm></term>
<listitem>
<para>See <link linkend="ca_if">IF</link>. If the IF condition is
false (in all previous IF/ELSEIF blocks), the else-part is assembled.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ELSEIF<indexterm id="ca_elseif"><primary>ELSEIF</primary><seealso>IF</seealso></indexterm> <expression></term>
<listitem>
<para>If the previous IF-block had false condition, the ELSEIF expression is evaluated
and the ELSEIF acts as new <link linkend="ca_if">IF</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ENDIF<indexterm id="ca_endif"><primary>ENDIF</primary></indexterm></term>
<listitem>
<para>Every <link linkend="ca_if">IF</link> should be followed
by an ENDIF.</para>
</listitem>
</varlistentry>
</variablelist></para>
</section>
<section id="s_macros">
<title>Macros</title>
<para>The MACRO pseudo-op defines a macro. It should be followed by the
name of the macro, optionally followed by the parameters. The following
lines will be stored as the macro-body until an ENDM pseudo-op is
encountered. Macro's have to be defined before their use. Macro's name
must be unique (even if two macros differ by required arguments).
<example>
<title>Macro without parameters (docs_examples/s_macros.asm)</title>
<programlisting> MACRO ADD_HL_A
ADD A,L
JR NC,.hup
INC H
.hup
LD L,A
ENDM</programlisting>
</example></para>
<para>Labels in a macro starting with a dot are local to each macro
expansion.<example>
<title>A macro with parameters (docs_examples/s_macros.asm)</title>
<programlisting> MACRO WAVEOUT reg, data
LD A,reg
OUT (7EH),A
LD A,data
OUT (7FH),A
ENDM
; this macro will make
WAVEOUT 2,17
; expand to:
LD A,2
OUT (7EH),A
LD A,17
OUT (7FH),A</programlisting>
</example>
<example>
<title>Another example (docs_examples/s_macros.asm)</title>
<programlisting> MACRO LOOP
IF $-.lus<127
DJNZ .lus
ELSE
DEC B
JP NZ,.lus
ENDIF
ENDM
Main
.lus
CALL DoALot
LOOP
; This will expand to:
Main
.lus ; Main.lus
CALL DoALot
DJNZ .lus ; Main.lus</programlisting>
</example></para>
<para>Angle brackets can be used when the arguments contain commas.
<example>
<title>Argument in angle brackets (docs_examples/s_macros.asm)</title>
<programlisting> MACRO UseLess data
DB data
ENDM
UseLess <10,12,13,0>
; expands to:
DB 10,12,13,0
; use '!' to include '!' and '>' in those strings.
UseLess <5, 6 !> 3>
; expands to:
DB 5, 6 > 3
UseLess <"Kip!!",3>
; expands to:
DB "Kip!",3</programlisting>
</example></para>
<para>As compatibility convenience to make porting from different assemblers somewhat
easier, there is alternative syntax, where the macro name is written at beginning
of line (as if label, but MODULE part is NOT applied to macro name).
<example><title>Macro name at beginning of line (docs_examples/s_macros.asm)</title>
<programlisting>LabelAsMacroName MACRO arg1?, arg2?
ld a,arg1?
ld hl,arg2?
ENDM
LabelAsMacroName 1,$1234
; expands to:
ld a,1 : ld hl,$1234</programlisting>
</example>
</para>
<para>
If some macro over-shadows regular instruction or directive name, the <code>@</code>
character in front of instruction/directive name can be used to inhibit macro expansion.
<example><title>Inhibit macro expansion operator (docs_examples/s_macros.asm)</title>
<programlisting>djnz MACRO arg1?
dec c
jr nz,arg1?
@djnz arg1? ; avoid self-reference and use real instruction
ENDM
1: djnz 1B ; macro replacement will be used here
1: @djnz 1B ; original djnz instruction here</programlisting>
</example>
</para>
</section>
</chapter>
<chapter id="c_structures">
<title>Structures</title>
<section id="s_structures_about">
<title>What is it?</title>
<para>Structures can be used to define data structures in memory more
easily. The name of the structure is set to the total size of the
structure.</para>
</section>
<section id="s_define_structure">
<title>Defining structure</title>
<para>A structure definition starts with: <code>STRUCT
<name>[,<initial offset>]</code> and ends with
<code>ENDS</code>. Structure definitions are local to the current
module, but, as with labels, '@' can be used to override this.</para>
<para>Lines between STRUCT and ENDS should have the following
format:</para>
<para><code>membername pseudo-operation operands</code></para>
<para>All fields are optional. Lines without label should start with
whitespace.</para>
<para>When non zero <code>offset</code> is used, it acts as if
<link linkend="st_block">BLOCK</link> with <code>length</code> equal to
<code>offset</code> was defined as first member of structure.</para>
</section>
<section id="s_structure_instructions">
<title>STRUCT instructions</title>
<para>Between the STRUCT and ENDS pseudo-instructions the following
instructions can be used:</para>
<para><variablelist>
<varlistentry>
<term>BYTE<indexterm id="st_byte"><primary>BYTE</primary></indexterm> [<defaultvalue>]</term>
<listitem>
<para>To define a one byte member. The defaultvalue is used when
no initialisation value is given when the structure is declared.
(DB and DEFB may be used instead of BYTE).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>WORD<indexterm id="st_word"><primary>WORD</primary></indexterm> [<defaultvalue>]</term>
<listitem>
<para>To define a two byte member. The defaultvalue is used when
no initialisation value is given when the structure is declared.
(DW and DEFW may be used instead of WORD).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>D24<indexterm id="st_d24"><primary>D24</primary></indexterm> [<defaultvalue>]</term>
<listitem>
<para>To define a three byte member. The defaultvalue is used
when no initialisation value is given when the structure is
declared.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DWORD<indexterm id="st_dword"><primary>DWORD</primary></indexterm> [<defaultvalue>]</term>
<listitem>
<para>To define a four byte member. The defaultvalue is used
when no initialisation value is given when the structure is
declared. (DD and DEFD may be used instead of DWORD).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>TEXT<indexterm id="st_text"><primary>TEXT</primary></indexterm> <length>[,{<DB-like operand(s)>}]</term>
<listitem>
<para>(since v1.17) To define a member of the specified <code>length</code> of bytes.
The operands are <link linkend="po_byte">DB-like</link> formatted, and the last
byte explicitly defined will fill the remaining bytes reserved upon definition
(zeroed when no value is specified at all).</para>
<para>The default value can be modified with init values when structure is used, but
then only the given bytes overwrite default content, NOT filling remainder of it.</para>
<para>While the operands are DB-like formatted, they must be enclosed in curly braces.
Also make sure the braces are not mistaken with the optional braces on the sub-structure
boundaries, when using TEXT member in sub-structure, you may need to use curly braces
for the sub-structure itself around of curly braces used for TEXT values (making the
sub-structure braces mandatory in such case). The length can be from 1 to 8192 bytes
(if you need even longer "text", use two members and split your arguments).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>BLOCK<indexterm id="st_block"><primary>BLOCK</primary></indexterm> <length>[,<fillbyte>]</term>
<listitem>
<para>To define a member of the specified number of bytes. Arguments are set
when defining the current structure, and are not part of init values when
the structure is later used.
('#', DS and DEFS may be used instead of BLOCK).</para>
<para>(since v1.11) If <code>fillbyte</code> is omitted, the device memory
content in the block area is preserved (not zeroed).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ALIGN<indexterm id="st_align"><primary>ALIGN</primary></indexterm> [<expression>[, <byte>]]</term>
<listitem>
<para>To <link linkend="po_align">align</link> the offset. If the expression
is omitted, 4 is assumed. ('##' May be used instead of ALIGN).</para>
<para>(since v1.11) If the byte is omitted, device memory content is preserved (not zeroed).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><structure name> [<init values>]</term>
<listitem>
<para>It is possible to nest structures, and give new defaults
for the BYTE and WORD members.</para>
</listitem>
</varlistentry>
</variablelist></para>
</section>
<section id="st_usage">
<title>Usage of defined structure</title>
<para><code>[<label>] <struct_name> [<initial values>]</code> will emit full
structure into machine code, either using default values from structure definition,
or overriding them with explicit value from the <initial values> list. In initial
values you can use curly brackets {} to group particular initial values for particular
sub-structure, any missing values in particular sub-structure init-list are set up by
default values of particular field. See "SDOT" example below or tests/struct asm files
for more examples.</para>
<para><code><label> <struct_name> = <expression></code> will only set up
<label>.<struct_field> labels starting from designed address provided by
expression, but there will be no machine code emitted (and current address "$" will not
advance).</para>
<para>(since v1.17) The initial values inside curly braces block can now span over multiple
lines with new line ending current value expression (the comma after expression is optional
in such case). Please bear in mind this is pushing original sjasmplus architecture beyond
its original design (multi-line definitions) and may fail in complex scenarios (for
example the "dot-repeater" macro mechanics will repeat only the remainder of current
line, ignoring the curly-braces block spanning across following lines). If you have
example of code which fails but you believe it's reasonable use case, please open the
issue on github with such example, so it is possible to improve the feature in future
(the dot-repeater is "won't fix" case, but otherwise the feature should work reliably).
</para>
</section>
<section id="s_structure_examples">
<title>Examples</title>
<example>
<title>docs_examples/c_structures.asm</title>
<para><programlisting> STRUCT SCOLOR
RED BYTE 4
GREEN BYTE 5
BLUE BYTE 6
ENDS</programlisting></para>
<para>This is identical to:</para>
<synopsis>SCOLOR EQU 3 ; length
SCOLOR.RED EQU 0 ; offset
SCOLOR.GREEN EQU 1 ; offset
SCOLOR.BLUE EQU 2 ; offset</synopsis>
</example>
<example>
<title>docs_examples/c_structures.asm</title>
<para><programlisting> STRUCT SDOT
X BYTE
Y BYTE
C SCOLOR 0,0,0 ; use new default values
ENDS
</programlisting></para>
<para>This is identical to:</para>
<synopsis>SDOT EQU 5 ; length
SDOT.X EQU 0 ; offset
SDOT.Y EQU 1 ; offset
SDOT.C EQU 2 ; offset
SDOT.C.RED EQU 2 ; offset
SDOT.C.GREEN EQU 3 ; offset
SDOT.C.BLUE EQU 4 ; offset
</synopsis>
</example>
<example>
<title>docs_examples/c_structures.asm</title>
<para><programlisting> STRUCT SPOS,4
X WORD
Y BYTE
ALIGN 2
AD WORD
ENDS</programlisting></para>
<para>This is identical to:</para>
<synopsis>SPOS EQU 10 ; length
SPOS.X EQU 4 ; offset
SPOS.Y EQU 6 ; offset
SPOS.AD EQU 8 ; offset</synopsis>
</example>
<example>
<title>docs_examples/c_structures.asm</title>
<para>When a structure is defined it is possible to declare labels
with it<programlisting>COLOR SCOLOR</programlisting>This is
identical to:<synopsis>COLOR
COLOR.RED BYTE 4
COLOR.GREEN BYTE 5
COLOR.BLUE BYTE 6
</synopsis>Note the default values.</para>
<para>Or without label:<programlisting>COLORTABLE
SCOLOR 0,0,0
SCOLOR 1,2,3
SCOLOR ,2
; etc.</programlisting>This is identical to:<synopsis>COLORTABLE
BYTE 0,0,0
BYTE 1,2,3
BYTE 4,2,6
; etc.</synopsis>
<programlisting>DOT1 SDOT 0,0, 0,0,0 ; or 0,0,0,0,0 or {0,0,{0,0,0}}</programlisting>Only
BYTE and WORD members can be initialised.</para>
<para>The resulting labels can be used as any other
label:<programlisting> ld b,(ix+SCOLOR.RED)
ld a,(COLOR.GREEN)
ld de,COLOR
; etc.</programlisting></para>
</example>
<example>
<title>docs_examples/st_usage_example.asm</title>
<para><programlisting> STRUCT BIN_FILE_MAP, 256
value1 BYTE
value2 WORD
ENDS
ORG 0x8000
binData BIN_FILE_MAP = $ ; set up label values only (no bytes)
INCBIN "some_data.bin" ; load the bytes from file instead
; using the data through struct definition
ld a,(binData.value1)
ld hl,(binData.value2)</programlisting></para>
<para>This is identical to:</para>
<synopsis>BIN_FILE_MAP EQU 259 ; length
BIN_FILE_MAP.value1 EQU 256 ; offset
BIN_FILE_MAP.value2 EQU 257 ; offset
; labels to access binary data loaded by INCBIN
binData EQU 0x8000 ; address
binData.value1 EQU 0x8100 ; address
binData.value2 EQU 0x8101 ; address</synopsis>
</example>
<example>
<title>docs_examples/st_text.asm</title>
<para><programlisting> STRUCT BLOCK_HEADER
length WORD BLOCK_HEADER
type BYTE $AB
name TEXT 10, { "none", 32, '!' } ; will produce "none !!!!!" default data
; because this is definition of the field, here last byte is "filler"
datastart WORD
datalen WORD
checksum BYTE $CC
ENDS
ORG 0x8000
head1 BLOCK_HEADER { ; Multi-line initialization requires curly braces.
, , ; Keeping default length and type by specifying empty values.
{ 'New', ; The final `name` data will be "New Name!!"
32, ; overwriting only 8 bytes of default data.
"Name" }, ; The last "e" is NOT "filler" in the non-default value.
$8000, $1234 ; Explicit datastart and datalen values.
} ; End of initial data block ("checksum" keeps default value).
; machine code (struct data):
; 12 00 AB 4E 65 77 20 4E 61 6D 65 21 21 00 80 34 12 CC
; = { $0012, $AB, "New Name!!", $8000, $1234, $CC }</programlisting></para>
</example>
<warning>
<para>Do not use the offset labels in indirections
like:<programlisting>LD A,(SDOT.X)</programlisting>This will
conflict with futher 'improvements' ;-)</para>
<para>If this is absolutely necessary (why?) use something like
this:<programlisting>LD A,(+SDOT.X)</programlisting></para>
</warning>
</section>
</chapter>
<chapter id="c_lua_scripting">
<title>Lua scripting</title>
<section id="s_lua_oh_why">
<title>Why?</title>
<para><graphic align="top" fileref="lua.gif" />Why is scripting engine
as Lua embedded to the compiler? Answer is simple: it can be used to add extra
features by users. And Lua is small enough, fast and powerful scripting engine.</para>
<para>Since v1.20.0 sjasmplus integrates Lua 5.4.4. Before it was using Lua 5.1.5 with
few 3rd party external libraries, which were mostly non-functional due to neglected
refreshing of tolua++ tool and integration itself. The upgrade to Lua 5.4 was done
along replacing tolua++ with LuaBridge2.6, and while there was put lot of effort
to maintain original Lua bindings to sjasmplus, there are few changes to the API.</para>
<para>If your old source does not work any more after upgrade, please carefully check
against the <link linkend="s_lua_sjasmplus_bindings">bindings documentation</link> below.</para>
<para>Check if your code does use only official API, and if you were using secret extra
arguments, check the test files and examples how those lua scripts were adjusted to
build with v1.20.0. The bindings API documentation has been cleaned up, some API
extended and has better test-coverage to make it less likely to change in the future.</para>
<para>Also please mind the breaking changes of the Lua itself, and adjust your scripts
to Lua 5.4 syntax and library functions, there is example below with common issues
already encountered (open github issues with others so we can add them to docs).</para>
</section>
<section id="s_lua_how_to">
<title>How to use?</title>
<para>You must use <link linkend="po_lua">LUA</link> and <link
linkend="po_endlua">ENDLUA</link> pseudo-ops.<example>
<title>Hello World!</title>
<para><programlisting> LUA
print ("Hello World!")
ENDLUA</programlisting></para>
</example></para>
</section>
<section id="s_lua_sjasmplus_bindings">
<title>SjASMPlus functions bindings to Lua</title>
<para>From Lua you can control some variables and use functions of the
compiler. Complete list:</para>
<para><variablelist>
<varlistentry>
<term>[integer] _c("expression")<indexterm id="lua__c"><primary>_c(..)</primary></indexterm></term>
<listitem>
<para>Calculate expression using calculator of the compiler (32-bit only).
Example: <code>val = _c("SOMELABEL+12")</code></para>
</listitem>
</varlistentry>
<varlistentry>
<term>[void] _pc("code")<indexterm id="lua__pc"><primary>_pc(..)</primary></indexterm></term>
<listitem>
<para>Parse string of Z80 assembly. Example: <code>_pc("ADD A,B")</code></para>
</listitem>
</varlistentry>
<varlistentry>
<term>[void] _pl("label code")<indexterm id="lua__pl"><primary>_pl(..)</primary></indexterm></term>
<listitem>
<para>Parse line of Z80 assembly. Example: <code>_pl("SOMELABEL ADD A,B")</code></para>
<para>This binding makes almost all pseudo-instructions (directives) available from Lua script
with all options and features. In the future the bindings API will be mostly frozen, extended
only in case where using <code>_pl(...)</code> is too cumbersome.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>[integer] sj.calc("expression")<indexterm id="lua_sj_calc"><primary>sj.calc(..)</primary><see>_c(..)</see></indexterm></term>
<listitem>
<para>See <link linkend="lua__c">_c</link></para>
</listitem>
</varlistentry>
<varlistentry>
<term>[void] sj.parse_code("code")<indexterm id="lua_sj_parse_code"><primary>sj.parse_code(..)</primary><see>_pc(..)</see></indexterm></term>
<listitem>
<para>See <link linkend="lua__pc">_pc</link></para>
</listitem>
</varlistentry>
<varlistentry>
<term>[void] sj.parse_line("label code")<indexterm id="lua_sj_parse_line"><primary>sj.parse_line(..)</primary><see>_pl(..)</see></indexterm></term>
<listitem>
<para>See <link linkend="lua__pl">_pl</link></para>
</listitem>
</varlistentry>
<varlistentry>
<term>[void] sj.error("message","bad_value" = nil)<indexterm id="lua_sj_error"><primary>sj.error(..)</primary></indexterm></term>
<listitem>
<para>Print error message.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>[void] sj.warning("message","bad_value" = nil)<indexterm id="lua_sj_warning"><primary>sj.warning(..)</primary></indexterm></term>
<listitem>
<para>Print warning message.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>[boolean] sj.file_exists("filename")<indexterm id="lua_sj_file_exists"><primary>sj.file_exists(..)</primary></indexterm></term>
<listitem>
<para>Check for file exists.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>[string] sj.get_define("name", "include_macro_args" = false)<indexterm id="lua_sj_get_define"><primary>sj.get_define(..)</primary></indexterm></term>
<listitem>
<para>Get define value, returns nil if define is not found. Can optionally search also macro arguments (with higher priority).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>[boolean] sj.insert_define("id", "value" = "")<indexterm id="lua_sj_insert_define"><primary>sj.insert_define(..)</primary></indexterm></term>
<listitem>
<para>Add new define. Returns true if the define is new, false when define already existed and value was replaced or when id is invalid.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>[integer] sj.get_label("name")<indexterm id="lua_sj_get_label"><primary>sj.get_label(..)</primary></indexterm></term>
<listitem>
<para>Get label address. Returns -1 if name is invalid, 0 when not found or has still undefined value (you can use also <code>_c("name")</code> to get symbol value and do some calculations with it).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>[boolean] sj.insert_label("name", address)<indexterm id="lua_sj_insert_label"><primary>sj.insert_label(..)</primary></indexterm></term>
<listitem>
<para>Add new label. Returns true when label was successfully inserted (or value modified first time in next assembling pass), false when name is invalid or label was already defined.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>[integer] sj.current_address<indexterm id="lua_sj_current_address"><primary>sj.current_address</primary></indexterm></term>
<listitem>
<para>Read-only variable. Current address.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>[integer] sj.error_count<indexterm id="lua_sj_error_count"><primary>sj.error_count</primary></indexterm></term>
<listitem>
<para>Read-only variable. Count of Errors.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>[integer] sj.warning_count<indexterm id="lua_sj_warning_count"><primary>sj.warning_count</primary></indexterm></term>
<listitem>
<para>Read-only variable. Count of Warnings.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>[void] sj.exit(errorcode = 1)<indexterm id="lua_sj_exit"><primary>sj.exit(..)</primary></indexterm></term>
<listitem>
<para>Shutdown the compiler.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>[void] sj.add_byte(byte)<indexterm id="lua_sj_add_byte"><primary>sj.add_byte(..)</primary></indexterm></term>
<listitem>
<para>Add byte to output (or to memory) and increase <link
linkend="lua_sj_current_address">sj.current_address</link></para>
</listitem>
</varlistentry>
<varlistentry>
<term>[void] sj.add_word(word)<indexterm id="lua_sj_add_word"><primary>sj.add_word(..)</primary></indexterm></term>
<listitem>
<para>Add word to output (or to memory) and twice increase <link
linkend="lua_sj_current_address">sj.current_address</link></para>
</listitem>
</varlistentry>
<varlistentry>
<term>[integer] sj.get_byte(address)<indexterm id="lua_sj_get_byte"><primary>sj.get_byte(..)</primary></indexterm></term>
<listitem>
<para>Get byte from memory. <emphasis>Works only in real device
emulation mode and only in last assembling pass.</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term>[integer] sj.get_word(address)<indexterm id="lua_sj_get_word"><primary>sj.get_word(..)</primary></indexterm></term>
<listitem>
<para>Get word from memory. <emphasis>Works only in real device
emulation mode and only in last assembling pass.</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term>[string] sj.get_device()<indexterm id="lua_sj_get_device"><primary>sj.get_device()</primary></indexterm></term>
<listitem>
<para>Return current emulating device's identifier. Returns
"NONE" if no emulation mode.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>[boolean] sj.set_device("id" = "NONE", ramtop = 0)<indexterm id="lua_sj_set_device"><primary>sj.set_device(..)</primary></indexterm></term>
<listitem>
<para>Set current emulating device's identifier. Returns false
if requested device id is not found and current device set is lost ("NONE" is set).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>[boolean] sj.set_page(number)<indexterm id="lua_sj_set_page"><primary>sj.set_page(..)</primary></indexterm></term>
<listitem>
<para>Set page "number" to the current slot. Works as pseudo-op <link linkend="po_page">PAGE</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>[boolean] sj.set_slot(number_or_address)<indexterm id="lua_sj_set_slot"><primary>sj.set_slot(..)</primary></indexterm></term>
<listitem>
<para>Set current slot to "number". Works as pseudo-op <link linkend="po_slot">SLOT</link>.</para>
<para>(since v1.20.0) You can also use starting address of slot instead, ie. for ZX128
<code>sj.set_slot(0x8000)</code> is alias of <code>sj.set_slot(2)</code>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>[void] sj.shellexec("programname")<indexterm id="lua_sj_shellexec"><primary>sj.shellexec(..)</primary></indexterm></term>
<listitem>
<para>See pseudo-op SHELLEXEC.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>[boolean] zx.trdimage_create("trd_name", "label" = "")<indexterm id="lua_zx_trdimage_create"><primary>zx.trdimage_create(..)</primary></indexterm></term>
<listitem>
<para>Creates empty TRD image file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>[boolean] zx.trdimage_add_file<indexterm id="lua_zx_trdimage_add_file"><primary>zx.trdimage_add_file(..)</primary></indexterm>("trd_name", "somenameC",
startaddress, length, autostart = -1, replace = false)</term>
<listitem>
<para>Save block of memory to TRD image file. <emphasis>Work
only in real device emulation mode.</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term>[boolean] zx.save_snapshot_sna<indexterm id="lua_zx_save_snapshot_sna"><primary>zx.save_snapshot_sna(..)</primary></indexterm>("filename.sna",
startaddressofprogram)</term>
<listitem>
<para>Save snapshot of memory in SNA format. <emphasis>Works only
in real device emulation mode and only for ZXSPECTRUM48 and
ZXSPECTRUM128..</emphasis></para>
</listitem>
</varlistentry>
</variablelist></para>
</section>
<section id="s_lua_third_party_libs">
<title>Third-party embedded library(ies)</title>
<para><emphasis>None at this moment.</emphasis></para>
<para>Since v1.20.0 the sjasmplus integrates Lua 5.4.4.</para>
<para>The libraries included in older versions of sjasmplus: lpack.c, bit (bitwise operators)
and hex (convert to/from hexa numbers) are now all part of the standard Lua 5.4.</para>
<para>Refer to <ulink url="https://www.lua.org/manual/5.4/manual.html#6">Lua documentation</ulink>
for full list of functions and detailed help.</para>
<para>For small example check the test <code>tests/lua_examples/trivial/lua_standard_libs.asm</code></para>
</section>
<section id="s_lua_examples">
<title>Example</title>
<para></para>
<para><example>
<title>Variables doesn't clear in new passes of the compiler</title>
<para><programlisting> LUA PASS1
v = 1
ENDLUA
LUA PASS2
print (v)
-- out to console: 1
v = v + 1
ENDLUA
LUA PASS3
print (v)
-- out to console: 2
ENDLUA</programlisting></para>
</example><example>
<title>To generate some code you need to generate it in all
passes</title>
<para><programlisting> LUA ALLPASS
_pl("ClearScreen LD (.savesp+1),SP")
_pc("LD SP,16384+6144")
_pc("LD HL,0")
for i = 32768, 38912, 2 do
_pc("PUSH HL")
end
_pl(".savesp: LD SP,0")
_pc("RET")
ENDLUA
LUA PASS2 ; if you fully understand what you are doing
sj.add_byte(123) -- and you need emit bytes in other mode
ENDLUA ; luamc-ok ; you can suppress warning here or at start of block</programlisting></para>
</example><example>
<title>Declare function and use it</title>
<para><programlisting> LUA
function savetape_mytype(filename, startaddress)
local fp
fp = assert(io.open(filename, "wb"))
for i = 16384, 32767, 4 do
assert(fp:write( string.pack("bbbb",
sj.get_byte(i),
sj.get_byte(i+1),
sj.get_byte(i+2),
sj.get_byte(i+3)) ))
end
assert(fp:flush())
assert(fp:close())
end
ENDLUA
;somewhere in your program
LUA
savetape_mytype("tapefiles/myprogram.tape", _c("StartGameLabel"))
ENDLUA</programlisting></para>
</example><example>
<title>Simple sample :)</title>
<para><programlisting> LUA
-- Function reads number from file <fname>, increases it, creates define "BUILD" with the number and saves the number to <fname>.
-- With this function you can control count of compilations.
function increase_build(fname)
local fp
local build
fp = assert(io.open(fname, "rb"))
build = tonumber(fp:read("*all"))
assert(fp:close())
if type(build) == "nil" then
build = 0
end
build = build + 1;
sj.insert_define("BUILD", build)
fp = assert(io.open(fname, "wb"))
assert(fp:write( build ))
assert(fp:flush())
assert(fp:close())
end
-- Before using you must create empty file "build.txt"!
increase_build("build.txt")
-- Creates define "TIME" with current time
sj.insert_define("TIME", '"' .. os.date("%Y-%m-%d %H:%M:%S") .. '"')
ENDLUA
; print to console our time and build number
DISPLAY "Build time: ", TIME
DISPLAY "Build number: ", /D, BUILD</programlisting></para>
</example>
<example>
<title>Common issues with upgrade to Lua 5.4</title>
<para><programlisting> LUA ALLPASS
x = 2.3 ^ 4.5 -- old syntax: math.exp(2.3, 4.5)
_pc("db " .. math.floor(x))
_pc("db " .. 35//7) -- old syntax: 35/7
-- floating point values are now formatted rigorously with ".0" from the Lua
-- which leads to error in sjasmplus parser: Unexpected: .0
-- and requires to enforce integer type already at lua side
-- you can use either `math.floor()` function, or integer
-- operators like integer divide `//` or left shift `1<<7`
-- the floating point values (like "12.0") are silently truncated since v1.20.1 (to "12"),
-- but v1.20.0 errors out on these, unless you patch the lua script to produce integers
ENDLUA
</programlisting></para>
</example>
</para>
<para></para>
<para></para>
</section>
</chapter>
<chapter id="c_savenex">
<title>SAVENEX guide</title>
<section id="s_savenex_file_format">
<title>NEX File Format</title>
<para>NEX is binary format for ZX Spectrum Next, aiming to provide simple delivery of software
for the platform. For file format details check <ulink url="https://specnext.dev/wiki/NEX_file_format">
https://specnext.dev/wiki/NEX_file_format</ulink>. In short it is header + loading screen +
like-snapshot binary and remaining resources appended after.</para>
<para>Sjasmplus currently supports V1.2 and V1.3 of NEX file format (see wiki for details).</para>
<para>As such, the SAVENEX commands are available only in ZXSPECTRUMNEXT device emulation mode,
see <link linkend="po_device">DEVICE</link>.</para>
<para>As the file is designed for self-contained distribution of whole applications/games,
its configuration and assembling is a bit too complex for single directive, and the
configuration is instead divided into multiple commands, and the assembling goes
through multiple stages, so some commands must be used in correct sequence.</para>
<para>While the format technically allows to include multiple screen types data, they are all
loaded at the beginning over each other, so it makes sense to provide only single loading
screen (sjasmplus enforces that).</para>
</section>
<section id="s_savenex_commands">
<title>Detailed description of each SAVENEX command</title>
<variablelist>
<varlistentry>
<term id="nex_open">
SAVENEX OPEN <filename>[,<startAddress>[,<stackAddress>[,<entryBank16k 0..111>[,<fileVersion 2..3>]]]]
</term>
<listitem>
<para>
Opens a NEX file, defines start address, stack address and 16k bank to be mapped
at 0xC000 before code is executed (if values are omitted, start address is zero
= no start, stack address is 0xFFFE, entryBank is zero, fileVersion is 2).
</para>
<para>
Only single NEX file can be open at the same time, and to finalize the header
content the command CLOSE has to be used (does auto-close if source ends).
</para>
<para>
Entry bank is number of 16k bank (0..111), not native 8k page, default is zero,
i.e. the default memory map is identical to ZX 128 (ROM, RAM banks 5, 2 and 0).
</para>
<para>
Make sure your new stack has at least tens of bytes available as those will be
used already by the NEX loader before executing your entry point (although
released back).
</para>
<para>
The fileVersion can be 2 (NEX V1.2) or 3 (NEX V1.3), which will enforce the
specified version of file. Otherwise the file is V1.2 by default and will
auto-switch to V1.3 when some V1.3 feature is configured/used. When version 2
is enforced, any usage of V1.3 feature will emit error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="nex_core">
SAVENEX CORE <major 0..15>,<minor 0..15>,<subminor 0..255>
</term>
<listitem>
<para>
Set minimum required Next core version, can be set any time before <link
linkend="nex_close">CLOSE</link>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="nex_cfg">
SAVENEX CFG <border 0..7>[,<fileHandle 0/1/$4000+>[,<PreserveNextRegs 0/1>[,<2MbRamReq 0/1>]]]
</term>
<listitem>
<para>
Set border colour (during loading), whether the machine should be set to default
state (PreserveNextRegs = 0 = default), if the app requires extended RAM
(224 8k pages) and how the file handle of the NEX file should be treated:
0 = default = close, 1 = keep open and pass in BC, $4000..$FFFE = keep open,
and write into memory at provided address (after entry bank is paged in). This
can be set any time before <link linkend="nex_close">CLOSE</link>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="nex_cfg3">
SAVENEX CFG3 <DoCRC 0/1>[,<PreserveExpansionBus 0/1>[,<CLIbufferAdr>,<CLIbufferSize>]]
</term>
<listitem>
<para>
All of these are NEX format V1.3 features and using "CFG3" command will change
the version to V1.3 automatically (if not specified by <link linkend="nex_open">OPEN</link>).
</para>
<para>
DoCRC: default = 1, sjasmplus will checksum the file (if you know you will be
further patching file afterwards, switch it off, otherwise keep 1).
</para>
<para>
PreserveExpansionBus: default = 0, 0 = the NEX loader will disable expansion
bus through NextReg $80 / 1 = the NEX loader will not do anything.
</para>
<para>
CLIbufferAdr, CLIbufferSize: default = [0, 0], address and size of buffer for
NEX loader to copy the arguments line into. The buffer is copied after the
"entryBank" is mapped, so you can allocate buffer in your entryBank. The
loader/format has hard limit 2048 bytes, the argument line will be truncated
if longer. If your reserved buffer is shorter than 2048 bytes, the copy will
be also truncated to your buffer size only. If not truncated, the argument line
can end with any of these: Enter (13), colon or zero byte (truncated has no
terminator character, just fills the full buffer).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="nex_bar">
SAVENEX BAR <loadBar 0/1>,<barColour 0..255>[,<startDelay 0..255>[,<bankDelay 0..255>[,<posY 0..255>]]]
</term>
<listitem>
<para>
Loading-bar related setup ("colour" usage depends on screen mode), can be set
any time before <link linkend="nex_close">CLOSE</link>.
</para>
<para>
The posY argument will apply only to V1.3 Layer2 screens in 320x256 and
640x256 resolution (then defaults to 254 = bottom of screen, 2px tall bar).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="nex_palette">
<para>SAVENEX PALETTE NONE</para>
<para>SAVENEX PALETTE DEFAULT</para>
<para>SAVENEX PALETTE MEM <palPage8kNum 0..223>,<palOffset></para>
<para>SAVENEX PALETTE BMP <filename></para>
</term>
<listitem>
<para>
This is optional command to set palette in alternative way ahead of SCREEN
command, with higher priority (if the PALETTE command is used, following
SCREEN commands will ignore the palette arguments and keep the palette defined
by this command). You can be use it between <link linkend="nex_open">OPEN</link>
and <link linkend="nex_auto">SCREEN</link> command. But appropriate SCREEN
type supporting palette must be defined by SCREEN command too.
</para>
<para>
Palette consists of 512 bytes (256 palette items from index 0), in 9b colour
format: first byte is %RRRGGGBB, second byte is %P000000B (P is priority flag
for Layer 2 colours).
</para>
<para>
The DEFAULT palette will generate colour values from the colour index, the same
way how default Layer 2 palette is initialized on the ZX Spectrum Next.
</para>
<para>
The NONE palette will force the "no palette" flag even if SCREEN command later
does specify some palette (it will be still ignored).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="nex_screen">
SAVENEX SCREEN L2 [<Page8kNum 0..223>,<offset>[,<palPage8kNum 0..223>,<palOffset>]]
</term>
<listitem>
<para>
Layer 2 loading screen, can be used between <link linkend="nex_open">OPEN</link>
and first <link linkend="nex_auto">AUTO</link>/<link linkend="nex_bank">BANK</link> command.
</para>
<para>
Palette consists of 512 bytes (256 palette items from index 0), in 9b colour
format: first byte is %RRRGGGBB, second byte is %P000000B (P is priority flag
for Layer 2 colours).
</para>
<para>
Image data are 48kiB block of memory, the loader will use always banks 9..11 to display
it (8k pages 18..23), but if you will prepare the data there, it will be also re-saved
by <link linkend="nex_auto">AUTO</link> command, so either use other banks, and overwrite
them with valid data/code after using the SCREEN command, or reset pages 18..23 to zero
after SCREEN.
</para>
<para>
If no memory address is specified, the pages 18..23 are stored in file, and if
no palette address is specified, no-palette flag is set in NEX file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<para>SAVENEX SCREEN L2_320 [<Page8kNum 0..223>,<offset>[,<palPage8kNum 0..223>,<palOffset>]]</para>
<para>SAVENEX SCREEN L2_640 [<Page8kNum 0..223>,<offset>[,<palPage8kNum 0..223>,<palOffset>]]</para>
</term>
<listitem>
<para>
Works same way as "L2" variant, but will set up screen for new resolutions 320x256x8
and 640x256x4. The difference is that the required image data are 80kiB (five 16kiB
banks; equals ten 8kiB pages), the banks used to show the screen in loader are
9..13 (8k pages 18..27 - that's also the default address of data if not specified)
- avoid these in regular banks stored in the file.
</para>
<para>
These are NEX format V1.3 features and using them will change the version to V1.3
automatically (if not specified by <link linkend="nex_open">OPEN</link>). This
command doesn't allow to set specific palette offset value (too lazy to add it,
use BMP variant if you really need it).
</para>
<para>
The data has to be already in correct format and organized as if displayed (the
"transposed" bitmap where +1 address goes to pixel below, and +256 goes to pixel
on the right (or pair of pixels in case of 640x256x4bpp mode), this command will
just dump them into file "as is".
</para>
<para>
The loading bar colour byte will be also used "as is", which in 4bpp mode means
the byte does define pair of 4 bit pixels, i.e. if you want solid-colour "3"
loading bar in 4bpp mode, define it as value $33. Keep also in mind the default
loading bar position is Y=254, which on most of the TV/LCD displays is outside
of visible range, the reasonably "safe" (visible on almost all of the screens)
resolution is about 288x224 (+16px around PAPER area, +24px is visible on many
displays too), you may want to organize your screen in a way to show all important
information within this area, and make the rest "unimportant" so it can hide
beyond the edge of screen.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
SAVENEX SCREEN LR [<Page8kNum 0..223>,<offset>[,<palPage8kNum 0..223>,<palOffset>]]
</term>
<listitem>
<para>
LoRes (128x96) loading screen, can be used between <link linkend="nex_open">OPEN</link>
and first <link linkend="nex_auto">AUTO</link>/<link linkend="nex_bank">BANK</link> command.
</para>
<para>
Palette is similar to Layer 2 mode, just LoRes mode doesn't have priority bit.
</para>
<para>
Image data are 12288 bytes memory block - either consecutive block if specific
address is provided, or without address the actual bank 5 memory is stored
(taking 6144 bytes from address 0x4000 and 6144 bytes from address 0x6000).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
SAVENEX SCREEN BMP <filename>[,<savePalette 0/1>[,<paletteOffset 0..15>]]
</term>
<listitem>
<para>
Only small subset of BMP files can be used: 256x192 (Layer 2) or 128x96 (LoRes),
indexed (8bit image data with palette) and palette data will be truncated
to 3:3:3 color space directly (no smart colour quantization or dithering is applied).
And the file must be uncompressed.
</para>
<para>
For V1.3 NEX files you can include also 320x256 and 640x256 files (Layer 2), the
640x256 should be also 8bit indexed, but only 4 bits of pixel data will be used
(256 colour palette is legitimate and will be stored "as is" in NEX file).
These two new modes can also include paletteOffset argument 0..15 (does not apply
to V1.2 BMP files above), the offset is added to top four bits of pixel value.
</para>
<para>
The BMP will be included as loading screen, can be used between <link linkend="nex_open">OPEN</link>
and first <link linkend="nex_auto">AUTO</link>/<link linkend="nex_bank">BANK</link> command.
</para>
<para>
By default the palette from BMP file is used, but you can override that by savePalette = 0.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
SAVENEX SCREEN (SCR|SHC|SHR) [<hiResColour 0..7>]
</term>
<listitem>
<para>
ULA/Timex modes loading screen, can be used between <link linkend="nex_open">OPEN</link>
and first <link linkend="nex_auto">AUTO</link>/<link linkend="nex_bank">BANK</link> command.
</para>
<para>
The actual bank 5 memory (pages 10..11) is stored as if the image is displayed,
in these modes the palette can't be specified.
</para>
<para>
SCR is classic ZX 6912 bytes long screen from address 0x4000 (page 10 is used,
even if the slot 1 is modified to other page, so you must prepare the image "in place").
</para>
<para>
SHC and SHR are Timex HiColor (8x1 attribute) and HiRes (512x192 bitmap) modes,
prepare data "in place", i.e. 6144 bytes into page 10 and 6144 bytes into page
11 (0x4000 and 0x6000 addresses in default memory setup). For HiRes mode you
should specify ink colour (the paper is complement of ink).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
SAVENEX SCREEN TILE <NextReg $6B>,<NextReg $6C>,<NextReg $6E>,<NextReg $6F>[,<AlsoStoreBank5 0/1 = 1>]
</term>
<listitem>
<para>
NEX V1.3 tilemap loading screen, can be used between <link linkend="nex_open">OPEN</link>
and first <link linkend="nex_auto">AUTO</link>/<link linkend="nex_bank">BANK</link> command.
</para>
<para>
To define palette use the <link linkend="nex_palette">PALETTE</link> command.
</para>
<para>
The image data are stored as regular Bank 5 of the NEX file (which is the first bank
to be loaded by loader), depending on AlsoStoreBank5 value (default 1), this SCREEN
command will also execute <link linkend="nex_bank">BANK 5</link> command to store
the image data.
</para>
<para>
The NextRegisters $6B, $6C, $6E and $6F should be enough to specify any variant
of tilemap mode, so the precise sub-type and image data layout is under control
of user, the sjasmplus doesn't enforce any particular configuration.
</para>
<para>
If you want to use also <link linkend="nex_copper">COPPER</link> command, use it
either ahead of the SCREEN TILE command, or use "AlsoStoreBank5 = 0" to delay the
storage of Bank 5 data. In such case you must then later explicitly store
the Bank 5 as regular bank, either with BANK or AUTO command.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="nex_copper">
SAVENEX COPPER <Page8kNum 0..223>,<offset>
</term>
<listitem>
<para>
Can be used after <link linkend="nex_open">OPEN</link> and before first <link
linkend="nex_auto">AUTO</link> or <link linkend="nex_bank">BANK</link>
command (the copper data are stored between screen and bank data).
</para>
<para>
Exactly 2048 bytes are stored (full Copper memory), and the loader will start
the copper code in mode %01 (reset CPC to 0, then starts the copper), so the
copper code will wrap around infinitely after the 1024th instruction executed.
The copper is started after the screen block is loaded and displayed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="nex_bank">
SAVENEX BANK <bank16k 0..111>[,...]
</term>
<listitem>
<para>
Can be used after <link linkend="nex_open">OPEN</link> or <link linkend="nex_screen">
SCREEN</link> and before <link linkend="nex_close">CLOSE</link>, but the 16ki
banks must be saved in correct order: 5, 2, 0, 1, 3, 4, 6, 7, 8, 9, 10, ..., 111
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="nex_auto">
SAVENEX AUTO [<fromBank16k 0..111>[,<toBank16k 0..111>]]
</term>
<listitem>
<para>
Can be used after <link linkend="nex_open">OPEN</link> or <link linkend="nex_screen">
SCREEN</link> and before <link linkend="nex_close">CLOSE</link>. The sjasmplus
will save every 16k bank containing at least one non-zero byte; detected in the correct order (automatically
will save every non-zero 16k bank detected in the correct order (automatically
starting from first possible bank after previous BANK/AUTO commands, or from
provided "fromBank").
</para>
<para>
For "fromBank" value use the specified order above in <link linkend="nex_bank">BANK
</link> command, i.e. 5, 2, 0, ...
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="nex_close">
SAVENEX CLOSE [<fileToAppend>]
</term>
<listitem>
<para>
Can be used after <link linkend="nex_open">OPEN</link>. The currently open NEX
file will be finalized (header adjusted), and optional extra file just appended
to the end of NEX file.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section id="s_savenex_examples">
<title>Examples</title>
<example>
<title>docs_examples/s_savenex_examples.asm</title>
<para>
Creating NEX file which will have Layer2 loading screen (stripes), progress bar, and will
enter infinite loop with calling stack (used by IM 1 interrupt handler) visible on the
Layer 2 screen.
</para>
<programlisting> DEVICE ZXSPECTRUMNEXT
ORG $7E00
start: ei : jr $ ; app code entry point, BC = NEX file handle
; Layer2 screen (top 1/3 defined, bottom of it will be used also as "visible" stack)
ORG $C000 : DUP 64*32 : DB $90,$91,$92,$93,$94,$95,$96,$97 : EDUP
; write everything into NEX file
SAVENEX OPEN "example.nex", start, $FFFE, 9 ; stack will go into Layer2
SAVENEX CORE 2, 0, 0 ; Next core 2.0.0 required as minimum
SAVENEX CFG 4, 1, 0, 1 ; green border, file handle in BC, reset NextRegs, 2MB required
SAVENEX BAR 1, $E0, 50, 25 ; do load bar, red colour, start/load delays 50/25 frames
SAVENEX SCREEN L2 0, 0 ; store the data from C000 (page 0, offset 0), no palette
SAVENEX BANK 5, 100, 101 ; store the 16ki banks 5 (contains the code at 0x7E00), 100, 101
SAVENEX CLOSE ; (banks 100 and 101 are added just as example)
</programlisting>
</example>
</section>
</chapter>
<chapter id="c_sld_data">
<title>Source Level Debugging (SLD) data</title>
<section id="s_sld_intro">
<title>What is it?</title>
<para>
SLD data are extra "tracing" data produced during assembling for debuggers and IDEs,
similar to "map" files already supported by sjasmplus (<link linkend="po_labelslist">
LABELSLIST</link> and <link linkend="po_cspectmap">CSPECTMAP</link>).
</para>
<para>
The debugger can read these data, and with non-tricky source producing machine code
with correct device memory mapping, the debugger can trace the origins of every
instruction back to the original source code line, and display the source instead/along
the disassembly view (the "map" files mentioned above provide only list of labels
which is usually already super helpful, but can't track the source origins of each
instruction).
</para>
<para>
The original impulse and working patch for this feature came from Chris Kirby, adding the
single-instruction-step feature to his development tools: <ulink url="https://github.com/Ckirby101/NDS-NextDevSystem">
Next Development System</ulink> (currently in 2019 under heavy development).
</para>
</section>
<section id="s_sld_cli">
<title>Usage</title>
<para>
On the sjasmplus side all you need is to add another command line option when starting
the assembler.
<synopsis>prompt$ sjasmplus --sld=project.sld.txt file1.asm file2.asm</synopsis>
This will produce along regular files also file `project.sld.txt` containing the
tracing data. The file format is text-like, so the content can be viewed
in any text editor, but it's supposed to be processed by the debugger.
</para>
<para>
The SLD data are being exported <emphasis role="strong">only</emphasis> for machine code produced
within one of the virtual devices (see <link linkend="s_realdevice">DEVICE</link>).
And the accuracy of the data directly depends on the state of the virtual device at
the moment when the particular instruction is assembled, see next section for further
advice how to get best tracing data.
</para>
<para>
If the option `--sld` without explicit filename is used, the first input source filename
will be copied and its extension changed to `.sld.txt`, which should work well for
single-main file type of projects.
</para>
</section>
<section id="s_sld_source_advice">
<title>How to write "non tricky" source</title>
<para>
For best results (tracing data covering all your instructions and making source-level
debugging available all the time):
</para>
<para>
Generate machine code only with instructions, i.e. while `db 0` in source will produce
`nop` instruction, the tracing data for such `nop` will be missing. Only source line
containing the "nop" will emit both the zero byte into machine code and tracing data.
</para>
<para>
Keep the memory map of the virtual device as it will be set at run-time when writing
particular code. While using only regular <link linkend="po_org">ORG</link> to place
the code in desired memory area, keeping only the modified area with memory pages
mapped-in is enough to get correct SLD data - but when using <link linkend="po_disp">DISP</link>
directive to generate code in displaced way, you need to map-in correct pages in both
memory areas (where the code is currently assembled, and where it is supposed to be
operational at run-time - currently impossible if the two areas share the same SLOT area).
</para>
<para>
To map-in correct pages you can use directives:
<link linkend="po_slot">SLOT</link>, <link linkend="po_page">PAGE</link>,
<link linkend="po_mmu">MMU</link> and <link linkend="po_org">ORG</link>
</para>
<para>
Only labels defined in regular way get also the memory-page data in SLD file, EQU
values are exported without the page information, even if they represent memory
address:
<programlisting>
regularLabel: nop ; current page exported to SLD data
equLabel EQU $8000 ; only value without page is exported
varSymbol = 14 ; =/DEFL labels are omitted completely</programlisting>
</para>
<para>
Re-using the same memory area (page + address) for two different pieces of code (for
example by having multiple routines targeting the same address with DISP, and run-time
code uploading the correct variant dynamically at the destination) will highly likely
confuse the debugger, producing two source-origins data for the identical address.
You may want to avoid this, especially with early version of tools not being able to
resolve such ambiguity in reasonable way (the sjasmplus will generate tracing data ok
even in this case, but they are tricky to interpret).
</para>
<para>
If you are using the colons to put multiple instructions on single line, verify the
debugger can cope with the tracing data containing full line + column begin/end
information, the simple/early tools will likely highlight only whole line of source.
For a start keeping single instruction per line may keep things simple.
</para>
<para>
The various code generators written in macros or Lua scripts will produce accurate
tracing data in case of macros, and condensed (pointing at "ENDLUA" line) data for
Lua generators, but it still depends on the debugger if it can display both top
level source code triggering the generator and source lines containing definitions
of particular instructions.
</para>
</section>
<section id="s_sld_file_format">
<title>SLD File Format definition (version "1")</title>
<para><emphasis>The file format is still under development. If you are working on support in debugger, stay
in touch with us, so we can discuss any modifications to current format with you.</emphasis>
</para>
<para>The SLD data is text-file (sjasmplus is using UNIX-like newlines 0x0A, but parsers
should rather cope with any of common EOL scheme). The general format is CSV-like
using pipe character as delimiter between fields.
</para>
<para>
If the first field is empty, the line is one of the special control lines - the second
field selects type of control line. If also the second field is empty, the remaining
part of line should be ignored (comment line).
Currently only one type of "control line" exists, the "SLD.data.version" (third
field is integer number):
<programlisting>|SLD.data.version|1
||anything ... comment-like line</programlisting>
The file format version line should be always first line of the SLD data file.
</para>
<para>
The regular tracing data lines have fixed amount of fields: eight. The seventh field
contains single uppercase letter defining type of the line, which affects sub-variants
of format for eighth field, but first six fields share the same formatting and meaning
across all types of regular lines:
<programlisting>
<source file>|<src line>|<definition file>|<def line>|<page>|<value>|<type>|<data>
</programlisting>
</para>
<para>
<code><source file></code> - file name of top-level source emitting the
instruction/label/device.
</para>
<para>
<code><src line></code> - line and characters in top-level source file, the precise
format is "<code><line>[:<column begin>[:<column end>]]</code>" where
first number is line number (starting at 1). The two following numbers delimited by colon
are optional, representing the column where the segment starts/ends at the line. The
column values are starting from 1 too, the "end" column is pointing beyond the current
segment. The columns are in "bytes", i.e. tabulator does increase the column value by +1
only, and the "end" may actually point well beyond "strlen(line)".
</para>
<para>
<code><definition file></code> - file name of the source defining the particular
instruction (for example where the instruction inside MACRO was originally defined).
If empty, the definition-file name is identical to <code><source file></code>
(common case for single-source projects).
</para>
<para>
<code><def line></code> - zero when there is no extra "definition" of instruction
involved. When non-zero, the format is identical to <code><src line></code>, but
with regard to the file specified in <code><definition file></code> field.
</para>
<para>
<code><page></code> - number of memory page where the <code><value></code>
address points to, or -1 when value is not memory address.
</para>
<para>
<code><value></code> - any 32 bit integer value (EQU), but when representing memory
address, it is full 16 bit value from Z80 address space (the top bits beyond the memory
page size contains the number of "slot" where the instruction/label resides).
</para>
<para>
<code><type></code> - single uppercase letter representing type of line, current
types: T (instruction Trace), L (Label), F [deprecated, parse L], D [deprecated, parse L], Z (device memory model),
K (keyword comment, see <link linkend="po_sldopt">`SLDOPT COMMENT`</link>).
</para>
<para>
<code><data></code> - extra data specific for particular line type. Empty for
"T" lines. For "L" a list of items separated by comma, where first three items
represent sub-parts of symbol name: module name, main label, local label (sub-part
may be empty), optional remaining items are usage-traits giving away various internal info about
usage of symbol (currently exported traits: +equ, +macro, +reloc, +reloc_high, +used, +module, +endmod,
+struct_def, +struct_data).
For type "K" the comment containing one of they defined keywords is present.
</para>
<para>
For type "Z" the data field contains string describing the device memory model which
is being selected in source and should be applied for following SLD data lines. The
memory model string format is:
<programlisting>
pages.size:<page size>,pages.count:<page count>,slots.count:<slots count>[,slots.adr:<slot0 adr>,...,<slotLast adr>]
// unsigned <page size> is also any-slot size in current version.
// unsigned <page count> and <slots count> define how many pages/slots there are
// uint16_t <slotX adr> is starting address of slot memory region in Z80 16b addressing
</programlisting>
</para>
<example>
<title>Example of SLD file</title>
<programlisting>
|SLD.data.version|1
|| ZX Spectrum Next device description:
toplevel.asm|59||0|-1|-1|Z|pages.size:8192,pages.count:224,slots.count:8,slots.adr:0,8192,16384,24576,32768,40960,49152,57344
|| label "main" points to 32768, with page 14 mapped-in (defined in toplevel.asm:62)
|| the label "main" is used by other code (IFUSED-like), and has relocation data
toplevel.asm|62||0|14|32768|L|,main,,+reloc,+used
|| instruction opcode at 32768 (page 14) was created by toplevel.asm:64
toplevel.asm|64||0|14|32768|T|
|| instruction opcode at 32769 (p 14) was created by toplevel.asm:67
|| (but it is a line using macro, the instruction was defined by toplevel.asm:52)
toplevel.asm|67||52|14|32769|T|
|| instruction opcode at 32770 (p 18) was created by toplevel.asm:68:12-24
toplevel.asm|68:12:24||0|18|32770|T|
|| instruction opcode at 32771 (p 18) was created by toplevel.asm:68:24 (till EOL)
toplevel.asm|68:24||0|18|32771|T|
|| "PORT_NUMBER EQU 254" defined at toplevel.asm:69
toplevel.asm|69||0|-1|254|L|,PORT_NUMBER,,+equ
|| label+instruction emitted from toplevel.asm:70, but defined in include.asm:3
|| with macro label "0>macro_defined_in_include_asm" (source ".macro_defined_in_include_asm:")
toplevel.asm|70|include.asm|3|37|40976|L|,0,macro_defined_in_include_asm,+macro,+used
toplevel.asm|70|include.asm|3|37|40976|T|
</programlisting>
</example>
</section>
</chapter>
<index id="index"/>
</book>