?login_element?

Subversion Repositories NedoOS

Rev

Rev 145 | Go to most recent revision | Blame | Compare with Previous | Last modification | View Log | Download

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
  3. "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
  4. <book>
  5.   <title>SjASMPlus 1.15.1 Documentation [2020-07-07]</title>
  6.  
  7.   <chapter>
  8.     <title>Introduction</title>
  9.  
  10.     <section>
  11.       <title>License</title>
  12.  
  13.       <para>SjASMPlus is licensed under BSD license.</para>
  14.     </section>
  15.  
  16.     <section>
  17.       <title>What is it?</title>
  18.  
  19.       <para>
  20.                 SjASMPlus is Z80 Assembly Language Cross Compiler. It is available
  21.                 for Win32, Linux and FreeBSD (mainly 5.x) systems. It is based on SjASM
  22.                 source code by Sjoerd Mastijn (<ulink url="http://xl2s.tk">http://xl2s.tk</ulink>).
  23.           </para>
  24.     </section>
  25.  
  26.     <section>
  27.       <title>Main Features</title>
  28.  
  29.       <para><itemizedlist>
  30.           <listitem>
  31.             <para>Full source of assembler available under BSD license, modify and extend as you wish</para>
  32.           </listitem>
  33.  
  34.           <listitem>
  35.             <para>Z80/R800/Z80N/i8080/LR35902 documented and undocumented opcodes support</para>
  36.           </listitem>
  37.  
  38.           <listitem>
  39.             <para>Macro language, defines, array of defines</para>
  40.           </listitem>
  41.  
  42.           <listitem>
  43.             <para>Built-in Lua scripting engine</para>
  44.           </listitem>
  45.  
  46.           <listitem>
  47.             <para>Conditional assembly, block repeating</para>
  48.           </listitem>
  49.  
  50.           <listitem>
  51.             <para>Modules (namespaces), local and temporary labels</para>
  52.           </listitem>
  53.  
  54.           <listitem>
  55.             <para>Source and binary file inclusion, include paths</para>
  56.           </listitem>
  57.  
  58.           <listitem>
  59.             <para>Multi file output, file updating, various types of exports</para>
  60.           </listitem>
  61.  
  62.           <listitem>
  63.             <para>Structures to work easily with structured data in memory</para>
  64.           </listitem>
  65.  
  66.           <listitem>
  67.             <para>Virtual device mode for common machines: ZX 128, ZX Next, … (pseudo op DEVICE)</para>
  68.           </listitem>
  69.  
  70.           <listitem>
  71.             <para>ZX Spectrum specific directives and pseudo ops (SAVESNA, SAVETAP, SAVEHOB, INCHOB, INCTRD…)</para>
  72.           </listitem>
  73.  
  74.           <listitem>
  75.             <para>ZX Spectrum Next specific features and directives (Z80N, 8ki memory paging, SAVENEX)</para>
  76.           </listitem>
  77.  
  78.           <listitem>
  79.             <para>Correctness is assured by <ulink url="https://cirrus-ci.com/github/z00m128/sjasmplus/master">
  80.             Cirrus-CI with 240+ automated tests</ulink> (that's also 240+ examples of usage!)</para>
  81.          </listitem>
  82.  
  83.          <listitem>
  84.            <para>Fake instructions as LD HL,DE (LD H,D:LD L,E) and more</para>
  85.          </listitem>
  86.  
  87.          <listitem>
  88.            <para>Code inlining through colon (LD A,C:INC A:PUSH AF:IFDEF FX:LD A,D:ENDIF…)</para>
  89.          </listitem>
  90.  
  91.          <listitem>
  92.            <para>Very fast compilation: 1 million lines by 2-3 seconds on modern computer</para>
  93.          </listitem>
  94.  
  95.          <listitem>
  96.            <para>Multiline block comments and user’s messages</para>
  97.          </listitem>
  98.        </itemizedlist></para>
  99.    </section>
  100.  
  101.    <section>
  102.      <title>Credits</title>
  103.  
  104.      <para>Special thanks to <emphasis>Sjoerd Mastijn</emphasis>, the author of SjASM.</para>
  105.  
  106.      <para><emphasis>Aprisobal </emphasis>- main programming, documentation, etc.</para>
  107.  
  108.      <para>Thanks to:<itemizedlist>
  109.          <listitem>
  110.            <para><emphasis>Kurles/HS/CPU, Alexander Kovalenko, Ped7g</emphasis> - additional
  111.            programming;</para>
  112.          </listitem>
  113.  
  114.          <listitem>
  115.            <para><emphasis>Krystian Wlosek
  116.            &lt;kwlosek(at)gmail.com&gt;</emphasis> - bug fix patches, Linux
  117.            makefile;</para>
  118.          </listitem>
  119.  
  120.          <listitem>
  121.            <para><emphasis>Ric Horne &lt;Ric.Hohne@eads-ts.com&gt;</emphasis>
  122.            - bug fix patches.</para>
  123.          </listitem>
  124.  
  125.          <listitem>
  126.            <para><emphasis>breeze &lt;breeze@tut.by&gt;</emphasis> - bug fix
  127.            patches.</para>
  128.          </listitem>
  129.  
  130.          <listitem>
  131.            <para><emphasis>psndcj &lt;psndcj.tbk@gmail.com&gt;</emphasis> -
  132.            bug reporting, beta-testing.</para>
  133.          </listitem>
  134.  
  135.          <listitem>
  136.            <para><emphasis>elfh &lt;elphecy@gmail.com&gt;</emphasis> - bug
  137.            reporting.</para>
  138.          </listitem>
  139.  
  140.          <listitem>
  141.            <para><emphasis>bugsy &lt;bugsy@ya.ru&gt;</emphasis> - bug
  142.            reporting.</para>
  143.          </listitem>
  144.  
  145.          <listitem>
  146.            <para><emphasis>skrju &lt;sq-@mail.ru&gt;</emphasis> - bug
  147.            reporting.</para>
  148.          </listitem>
  149.  
  150.          <listitem>
  151.            <para><emphasis>Tygrys, UB880D, Cizo, mborik, z00m</emphasis> -
  152.            compilation errors and warnings clean up, makefiles, testing.</para>
  153.          </listitem>
  154.  
  155.          <listitem>
  156.            <para><emphasis>Antipod, boo_boo, PulkoMandy, Busy, Liniya, Dart Alver</emphasis> -
  157.            bug fix patches, testing.</para>
  158.          </listitem>
  159.  
  160.          <listitem>
  161.            <para><emphasis>CKirby</emphasis> - SLD export and support in his tools.</para>
  162.          </listitem>
  163.  
  164.        </itemizedlist></para>
  165.  
  166.      <para>Big thanks to all people, who helped on development of the compiler!</para>
  167.    </section>
  168.  
  169.    <section>
  170.      <title><anchor id="feedback" />Feedback</title>
  171.  
  172.      <para>WWW: <ulink
  173.      url="https://github.com/z00m128/sjasmplus">https://github.com/z00m128/sjasmplus</ulink>
  174.      (newer versions maintained by z00m and others)</para>
  175.  
  176.      <para>WWW: <ulink
  177.      url="https://sourceforge.net/projects/sjasmplus/">https://sourceforge.net/projects/sjasmplus/</ulink>
  178.      (original Aprisobal's source)</para>
  179.  
  180.       <para>E-Mail: zoom@centrum.sk, my@aprisobal.by</para>
  181.     </section>
  182.  
  183.     <section>
  184.       <title>What's new?</title>
  185.  
  186.      <para><variablelist>
  187.  
  188. <varlistentry>
  189.            <term>WIP - 1.15.2</term>
  190.  
  191.            <listitem>
  192.              <synopsis>- <link linkend="po_lua">`LUA`</link> thew new emit warning (v1.15.1) is now suppressible
  193. - <link linkend="s_predefined">Predefined defines</link> extended and renamed (following gcc/clang ones)
  194. - bugfixes/improvements in parser like: operators `not`, `low`, `high` can be followed also by "("
  195. </synopsis>
  196.            </listitem>
  197.          </varlistentry>
  198.  
  199. <varlistentry>
  200.            <term>7.7.2020 - 1.15.1</term>
  201.  
  202.            <listitem>
  203.              <synopsis>- <link linkend="po_equ">`EQU`</link> now assigns memory page to symbol based on the symbol value and current memory mapping
  204. - this does affect also results of <link linkend="po_labelslist">`LABELSLIST`</link> (<ulink url="https://github.com/z00m128/sjasmplus/issues/111">Issue #111</ulink>)
  205. - <link linkend="po_lua">`LUA`</link> emits warning when some machine code is emitted without "ALLPASS" modifier
  206. - <link linkend="po_savetrd">`SAVETRD`</link> refactored: fix couple of bugs and make TRD files conform the actual TR-DOS practice
  207. - `SAVETRD`: new "&amp;" modifier to produce "mono-loaders" with extra files appended
  208. - `SAVETRD`: added support for the unofficial 3-letter extensions ("; ok" to suppress warnings)
  209. - <link linkend="po_inctrd">`INCTRD`</link> refactored and added support for unofficial 3-letter extensions
  210. - fix <ulink url="https://github.com/z00m128/sjasmplus/issues/108">issue #108</ulink> to detect windows drive letters at beginning of file names with full windows paths
  211. - bugfixes: RAMTOP w/ global device, "r+w" file operations code review, memory buffer overrun in LUA</synopsis>
  212.            </listitem>
  213.          </varlistentry>
  214.  
  215. <varlistentry>
  216.            <term>18.5.2020 - 1.15.0</term>
  217.  
  218.            <listitem>
  219.              <synopsis>- added <link linkend="po_bplist">`BPLIST`</link> and <link linkend="po_setbp">`SETBP`</link> to export breakpoints info from asm for Unreal and ZEsarUX emulators
  220. - added ZX-like <link linkend="po_device">devices</link> with 2/4/8 MiB of virtual memory
  221. - the fake-sysvars/state of ZXSPECTRUM48/128/... devices reworked, moving stack down by default
  222. - behaviour of <link linkend="s_cli">`--fullpath`</link> option unified across all platforms and compilers
  223. - <link linkend="po_defarray">`DEFARRAY`</link> has new operator `[#]` to retrieve current size of array.
  224. - <link linkend="po_mmu">`MMU`</link> has new optional third argument to set also address (like ORG)
  225. - use of forward reference in <link linkend="ca_if">IF/IFN</link> emits only warning, and can be suppressed
  226. - internal Lua updated to 5.1.5 (last official 5.1 version), STDIN can be read multiple times
  227. - new <ulink url="https://github.com/z00m128/sjasmplus/tree/master/tests/macro_examples">macro_examples</ulink>: `sj_sysvars.i.asm` and `section.asm`, new <ulink url="https://github.com/z00m128/sjasmplus/tree/master/tests/lua_examples">lua_examples</ulink>: `lua_sin_table.asm`
  228. - RAM limit exceeded warning/error reworked to report with more sense, fixed bug with missing labels
  229. - <link linkend="po_savetrd">`SAVETRD`</link> warning about invalid extension can be suppressed by "; ok"
  230. - <link linkend="po_emptytrd">`EMPTYTRD`</link> takes as second argument disc label
  231. - added <link linkend="s_cli">`--outprefix`</link> option to prefix any output-directive filename (<ulink url="https://github.com/z00m128/sjasmplus/issues/102">issue #102</ulink>)</synopsis>
  232.            </listitem>
  233.          </varlistentry>
  234.  
  235. <varlistentry>
  236.            <term>30.1.2020 - 1.14.5</term>
  237.  
  238.            <listitem>
  239.              <synopsis>- fix crash when opening source file fails
  240. - <link linkend="po_disp">`DISP`</link>/<link linkend="po_org">`ORG`</link> warns about being used inside DISP block (also docs extended)
  241. </synopsis>
  242.            </listitem>
  243.          </varlistentry>
  244.  
  245. <varlistentry>
  246.            <term>13.1.2020 - 1.14.4</term>
  247.  
  248.            <listitem>
  249.              <synopsis>- added few example utility macros in tests/macro_examples/sj_library.asm (neg r16)
  250. - added <link linkend="nex_screen">`SAVENEX SCREEN BMP`</link> sub-command to include BMP loading-screen
  251. - added support for V1.3 of <link linkend="c_savenex">`NEX file format`</link> (new commands: CFG3, PALETTE, COPPER, new screen modes)
  252. - in lua scripts: `sj.calc(..)` (alias `_c(..)`) now substitutes defines and macro arguments
  253. - error reporting inside LUA and MACRO refactored to give better info about origin of error
  254. - macro-arguments parser now recognizes C++ numeric literals with apostrophe as digits-group separator
  255. - the assembler will instantly exit when run at Big-Endian platform (the rest of code is broken on BE)
  256. - updated syntax-highlight file for KDE5 editors (Kate)</synopsis>
  257.            </listitem>
  258.          </varlistentry>
  259.  
  260. <varlistentry>
  261.            <term>15.11.2019 - 1.14.3</term>
  262.  
  263.            <listitem>
  264.              <synopsis>- fix detection of `.end:` and `.END` labels when `--dirbol` is used
  265. - added export of <link linkend="c_sld_data">SLD (Source Level Debugging) data</link>, see also <ulink url="https://github.com/Ckirby101/NDS-NextDevSystem">NDS (NextDevSystem)</ulink>
  266. - added <link linkend="s_cli">`--longptr`</link> option to allow labels outside of 16b address space
  267. - docs: added small details about <link linkend="po_fpos">FPOS</link>, <link linkend="po_savetap">SAVETAP</link>, <link linkend="ca_ifused">IFUSED</link>
  268. - fix assembling-time reported in linux</synopsis>
  269.            </listitem>
  270.          </varlistentry>
  271.  
  272. <varlistentry>
  273.            <term>3.10.2019 - 1.14.2</term>
  274.  
  275.            <listitem>
  276.              <synopsis>- added i8080 mode (--i8080 CLI option) (it's still Z80 Zilog syntax, just limited instruction set)
  277. - added Sharp LR35902 mode (--lr35902 CLI option) (100% syntax compatibility with IDA, 95% bgb)
  278. - new <link linkend="s_expressions">$$label operator</link> to retrieve page of label
  279. - 1.14.0 include-path bugfix reverted, the "." is again <link linkend="po_include">automatically added</link> (*did* break projects)
  280. - small improvements/polish/extra-info in docs, INSTALL, README, few new tests added
  281. - cmake script fix of SYSTEM_LUA=ON option, <ulink url="https://cirrus-ci.com/github/z00m128/sjasmplus/master">CirrusCI</ulink> configs added for macOS and FreeBSD
  282. - few fixes of memory leaks, invalid memory access, double free/delete, ...
  283. </synopsis>
  284.             </listitem>
  285.           </varlistentry>
  286.  
  287. <varlistentry>
  288.             <term>30.8.2019 - 1.14.1</term>
  289.  
  290.             <listitem>
  291.               <synopsis>- refactored <link linkend="po_shellexec">SHELLEXEC</link> to use clib "system(..)" on all platforms (also MS VS), minor fixes
  292. - <ulink url="https://github.com/z00m128/sjasmplus/blob/master/tests/lua_examples/lua_inctext.lua">lua example "inc_text"</ulink> (result of specific request from sjasmplus user)
  293. - listing fixed when Lua was used to emit bytes and also parsed lines of assembly source
  294. - MinGW windows exe prefers "/" file system delimiter ("\" should still work on windows (only))
  295. - lot of small bugfixes and Cirrus CI infrastructure adjustments (windows MinGW build does run full tests)
  296. - MS VS builds stabilized and fixed, should now work mostly on par with MinGW builds (99.5%)
  297. - Using <ulink url="https://lgtm.com/projects/g/z00m128/sjasmplus/">lgtm.com</ulink> code analysis (did help to find new bugs and memory leaks)
  298. - <ulink url="https://github.com/unittest-cpp/unittest-cpp">UnitTest++</ulink> framework added for regular C++ unit tests, first few tests added
  299. </synopsis>
  300.             </listitem>
  301.           </varlistentry>
  302.  
  303. <varlistentry>
  304.             <term>17.8.2019 - 1.14.0</term>
  305.  
  306.             <listitem>
  307.               <synopsis>- <link linkend="po_include">INCLUDE</link> bugfix, now searching paths according to original documentation (may break some projects)
  308. - <link linkend="po_undefine">UNDEFINE</link> had undocumented feature of removing also labels, cancelled (was broken beyond repair)
  309. - R800 `MULUB` was producing wrong opcode all those years... fixed
  310. - <link linkend="po_module">MODULE</link> names can't contain dot any more! MODULE and ENDMODULE resets non-local label to "_"
  311. - <link linkend="s_cli">--syntax</link> option: "m" (switch off low-mem access warning) and "M" added, "A" removed
  312. - <link linkend="s_macros">macro</link> expansion can be inhibited by using "@" in front of instruction
  313. - expression evaluator was not strictly 32 bit (64b binaries could have produced different results than 32b binaries)
  314. - reading memory addresses 0..255 directly emits warning, use "; ok" comment to suppress it.
  315. - several tests added to improve the code coverage: <ulink url="https://coveralls.io/github/z00m128/sjasmplus?branch=master">coveralls.io/github/z00m128/sjasmplus</ulink>
  316. - as tests were added, minor bugs were found and squashed (errors wording, etc)</synopsis>
  317.            </listitem>
  318.          </varlistentry>
  319.  
  320.        </variablelist></para>
  321.  
  322.      <para>See <ulink url="https://github.com/z00m128/sjasmplus/blob/master/CHANGELOG.md">CHANGELOG.md</ulink> for full list of changes.</para>
  323.    </section>
  324.  </chapter>
  325.  
  326.  <chapter>
  327.    <title>Where to get and how to use</title>
  328.  
  329.    <section>
  330.      <title>Packages</title>
  331.  
  332.         <para>
  333.                 The <emphasis role="strong">latest release</emphasis> of this sjasmplus variant is
  334.                 <emphasis role="strong">available at <ulink url="https://github.com/z00m128/sjasmplus/releases/latest">
  335.                                 https://github.com/z00m128/sjasmplus/releases/latest</ulink></emphasis>
  336.                 - there is available zip archive with <emphasis role="strong">windows binary</emphasis>
  337.                 (toward <emphasis role="strong">bottom of the page</emphasis>), and zip archives with
  338.                 <emphasis role="strong">full source code</emphasis> of the sjasmplus.
  339.         </para>
  340.  
  341.         <para>Win32 package has:<itemizedlist>
  342.          <listitem>
  343.            <para>sjasmplus.exe - the Win32 executable.</para>
  344.          </listitem>
  345.  
  346.          <listitem>
  347.            <para>examples directory - some examples of use</para>
  348.          </listitem>
  349.  
  350.          <listitem>
  351.            <para>documentation directory - documentation in various
  352.            formats</para>
  353.          </listitem>
  354.        </itemizedlist>
  355.         </para>
  356.  
  357.         <para>
  358.                 You may want to download also the full source package, as it contains more than 240
  359.                 <emphasis role="strong">automated tests</emphasis> used to verify correctness of executable,
  360.                 and these can be often helpful to better understand how specific feature of sjasmplus works,
  361.                 and <emphasis role="strong">how to use it</emphasis> effectively.
  362.         </para>
  363.  
  364.         <para>
  365.                 <emphasis role="strong">Linux, Unix, MacOS</emphasis> and <emphasis role="strong">BSD</emphasis>
  366.                 version can be built from the full source archive. You can compile it using <emphasis>GCC</emphasis>
  367.                 and included <emphasis>Makefile</emphasis>. There is an option to use <emphasis>CMake</emphasis>
  368.                 for compilation. See
  369.                 <ulink url="https://github.com/z00m128/sjasmplus/blob/master/INSTALL.md">INSTALL.md</ulink> for details.
  370.         </para>
  371.  
  372.      <para>Windows binaries are compiled with <emphasis>MinGW</emphasis> environment and included
  373.                   <emphasis>Makefile.win</emphasis> file.</para>
  374.  
  375.      <para>You can grab older (up to v1.07) binaries and sources at SourceForge project page:
  376.      <ulink url="https://sourceforge.net/projects/sjasmplus/">https://sourceforge.net/projects/sjasmplus/</ulink></para>
  377.  
  378.    </section>
  379.  
  380.    <section>
  381.      <title><anchor id="s_cli"/>Command line</title>
  382.  
  383.      <para>Usage:</para>
  384.  
  385.      <synopsis>sjasmplus [options] sourcefile(s)</synopsis>
  386.  
  387.      <para>Option flags as follows:</para>
  388.  
  389.      <para><synopsis>  -h or --help             Help information
  390.  --version                Basic info (with --nologo only raw version string)
  391.  --zxnext[=cspect]        Enable ZX Next Z80 extensions (CSpect emulator has
  392.  extra "exit" DD00 and "break" DD01 fake instructions)
  393.  --i8080                  Limit valid instructions to i8080 only (+ no fakes)
  394.  --lr35902                Sharp LR35902 CPU instructions mode (+ no fakes)
  395.  --outprefix=&lt;path&gt;       Prefix for save/output/.. filenames in directives
  396.  Note: if the prefix is folder, the folder must exist before assembling. Prefix
  397.        is applied only to filenames defined in source (not to CLI arguments).
  398.  -i&lt;path&gt; or -I&lt;path&gt; or --inc=&lt;path&gt; ( --inc without "=" to empty the list)
  399.                           Include path (later defined have higher priority)
  400.  --lst[=&lt;filename&gt;]       Save listing to &lt;filename&gt; (&lt;source&gt;.lst is default)
  401.  --lstlab                 Enable label table in listing
  402.  --sym=&lt;filename&gt;         Save symbols list to &lt;filename&gt;
  403.  --exp=&lt;filename&gt;         Save exports to &lt;filename&gt; (see EXPORT pseudo-op)
  404.  --raw=&lt;filename&gt;         Machine code saved also to &lt;filename&gt; (- is STDOUT)
  405.  --sld[=&lt;filename&gt;]       Save Source Level Debugging data to &lt;filename&gt;
  406.                           Default name is: "&lt;first input filename&gt;.sld.txt"
  407.  Note: use OUTPUT,LUA/ENDLUA and other pseudo-ops to control output
  408. Logging:
  409.  --nologo                 Do not show startup message
  410.  --msg=[all|war|err|none|lst|lstlab]  Stderr messages verbosity ("all" is default)
  411.  Note: "lst" or "lstlab" will turn STDERR into listing file (this will clash with
  412.  `--lst`, use only one of the options) and some diagnostic messages of "all"
  413.  are omitted, as they are not part of listing files.
  414.  --fullpath               Show full path to file in errors
  415.  Note: the "fullpath" starts from current working directory, not from file system
  416.                 root (the MS_VS build was fixed to behave this way since v1.15.0)
  417. Other:
  418.  -D&lt;NAME&gt;[=&lt;value&gt;]       Define &lt;NAME&gt; as &lt;value&gt;
  419.  -                        Reads STDIN as source (even in between regular files)
  420.  --longptr                No device: program counter $ can go beyond 0x10000
  421.  --reversepop             Enable reverse POP order (as in base SjASM version)
  422.  --dirbol                 Enable directives processing from the beginning of line
  423.  --nofakes                Disable fake instructions (obsolete, use --syntax=F)
  424.  --dos866                 Encode from Windows codepage to DOS 866 (Cyrillic)
  425.  --syntax=&lt;...&gt;           Adjust parsing syntax, read details below.</synopsis></para>
  426.  
  427.  <para>Value for <code>--syntax</code> option may consist of multiple letters, omitting letter
  428.         for particular feature will use the default setting:
  429.         <synopsis>  a      Multi-argument delimiter ",," (default is ",")
  430.  b      Whole expression parentheses are legal for memory access only (default = immediate or memory)
  431.  B      memory access brackets [] required (default = relaxed syntax, [] allowed as extra)
  432.  f F    Fake instructions: warning / disabled (default = enabled)
  433.  i      Case insensitive instructions/directives (default = same case required)
  434. &dagger; <emphasis>l L    Keyword labels (registers, instructions, ...): warning / error (default = silent)</emphasis>
  435.  m      Switch off "Accessing low memory" warning globally
  436.  M      Alias "m" and "M" for "(hl)" to cover 8080-like syntax: ADD A,M
  437.  w      Warnings option: report warnings as errors</synopsis>
  438.  &dagger; work in progress: options "l" and "L" are not implemented yet, following example is then
  439.  not working correctly either.
  440.  </para>
  441.  <para>
  442.  I.e. <code>--syntax=faBil</code> will modify parser to process source line
  443.  <programlisting>hl:  Ld a,(hl),,de,hl</programlisting>
  444.  in a way to produce warnings about keyword "hl" being used for label, about fake instruction
  445.  being used (ld de,hl) and assemble <code>(hl)</code> as numeric expression, not memory access.
  446.  Warnings on fake instructions can be suppressed for particular line by adding any end-of-line
  447.  comment containing string "fake", i.e. "<code>ld de,hl ; fake DE=HL</code>" will assemble
  448.  without warning. The "F" option is identical to "--nofakes" and preferred.
  449.  </para>
  450.  
  451.  <para>
  452.  The recommended setup for new projects is <code>--syntax=abfw</code> which makes syntax less relaxed,
  453.  so some typos and mistakes are easier to catch, for example:
  454.  <programlisting>        OPT reset --syntax=abfw
  455. label:  dw 15
  456.        ld b,(label)
  457.        sub a,b</programlisting> will produce "error: Illegal instruction
  458.  (can't access memory): (label)" message for the <code>ld b,(label)</code> and the <code>sub a,b</code>
  459.  will produce only the <code>sub b</code> instruction (to give the <code>sub</code> multi-argument
  460.  with syntax option "a" the line would have to be <code>sub a,,b</code>).
  461.  </para>
  462.  
  463.  <para>
  464.           The assembler will also read the environment variable <code>SJASMPLUSOPTS</code> (if available),
  465.           and process its content as part of command line options (before the actual options), so you
  466.           can pre-configure certain options in your environment, for example:
  467.           <programlisting>export SJASMPLUSOPTS="--zxnext=cspect --msg=war"
  468. sjasmplus --lst --lstlab example.asm</programlisting>
  469.         will execute the assembling as if command line "<code>sjasmplus --zxnext=cspect --msg=war --lst --lstlab example.asm</code>"
  470.         was used. Known issue: parser of environment variable delimits each option on any white-space character, so
  471.         option containing space character will be incorrectly parsed (like "-Ifile-path with space" = fails and
  472.         there is no way to escape/quote the path in the SJASMPLUSOPTS variable to make it work).
  473.  </para>
  474.    </section>
  475.  
  476.    <section>
  477.      <title>Source file format</title>
  478.  
  479.                 <para>
  480.                   Lines in the source file should have the following form:
  481.                   <programlisting>Label Operator Operand Comment</programlisting>
  482.                   All fields are optional.
  483.                   <emphasis role="strong">Lines without label should start with whitespace.</emphasis>
  484.                   Operators and operands can be inlined with colon:
  485.                   <programlisting>      Operator Operand:Operator Operand:Operator Operand... Comment</programlisting>
  486.                   Comments should start with '<code>;</code>' or '<code>//</code>'.
  487.                   Comment blocks start with '<code>/*</code>' and end with '<code>*/</code>' (work in "nested" way,
  488.                   i.e. comment block started inside comment block must be also ended, before main block ends).
  489.  
  490.                         <example>
  491.                                 <title></title>
  492.  
  493.                                 <programlisting>; comment
  494. // comment
  495. ld /* comment */ a,80
  496. /*
  497. comment /* nested comment block */
  498. */
  499. ld /*
  500. but this won't be ld a,3!
  501. */ a,3</programlisting>
  502.                         </example>
  503.  
  504.                         Some warnings (low memory-access and fake instruction) can be suppressed for particular
  505.                         line by adding end-of-line type of comment starting with "ok":
  506.                         <example>
  507.                                 <title></title>
  508.  
  509.                                 <programlisting>        OPT --syntax=f  ; warning on accidental fake instructions
  510.        ld  hl,de    ; warning here
  511.        ld  hl,de    ; ok (warning will be suppressed by this comment)</programlisting>
  512.                         </example>
  513.                 </para>
  514.    </section>
  515.  </chapter>
  516.  
  517.  <chapter>
  518.    <title>Labels</title>
  519.  
  520.    <section>
  521.      <title><anchor id="s_labels" />Labels</title>
  522.  
  523.      <para>Labels are case-sensitive and may be of any reasonable length,
  524.      that is: up to about 70 characters. Label definitions should start on
  525.      the beginning of a line, but don't have to be followed by a colon ':'.
  526.      Generally labels should start with a letter or a underscore ('_'), the
  527.      following characters may be chosen from letters, numbers and the
  528.      following special symbols: '_', '.', '!', '?', '#' and '@'. Note that
  529.      the '.' has special meaning, as it is used between module names, labels
  530.      and local labels. The following are all legal and distinct
  531.      labels:<programlisting>Kip
  532. KIP
  533. Kip@@
  534. MAIN.loop?</programlisting>It is possible to use mnemonics, pseudo-ops and
  535.      register names as labels but it is not advised to do so. Also note that
  536.      the identifiers defined with the DEFINE pseudo-op use another name
  537.      space.</para>
  538.    </section>
  539.  
  540.    <section>
  541.      <title><anchor id="s_local_labels" />Local labels</title>
  542.  
  543.      <para>When there is a <link linkend="po_module">module definition</link> all
  544.      labels (except those starting with a '@') are local to that module. To
  545.      use a label from outside the module use modulename.labelname, in this
  546.      example: 'vdp.Cls' Labels starting with a '.' are also local to the
  547.      previous non-local label.</para>
  548.  
  549.      <para><example>
  550.          <title>docs_examples/s_local_labels.asm</title>
  551.  
  552.          <para><programlisting>    MODULE main             ; module "main"
  553. Main:                       ; main.Main
  554.        CALL SetScreen      ; SetScreen
  555.        CALL vdp.Cls        ; main.vdp.Cls
  556. .loop:                      ; main.Main.loop
  557.        LD A,(.event)       ; main.Main.event
  558.        CALL ProcessEvent   ; label not found: main.ProcessEvent
  559.        DJNZ .loop          ; main.Main.loop
  560.  
  561.        MODULE vdp          ; module "main.vdp"
  562. @SetScreen:                 ; SetScreen
  563. .loop:                      ; main.vdp.SetScreen.loop
  564.            RET
  565. Cls:                        ; main.vdp.Cls
  566. .loop:      DJNZ .loop      ; main.vdp.Cls.loop
  567.            RET
  568.        ENDMODULE
  569.  
  570. Main.event DB 0             ; main.Main.event
  571.    ENDMODULE</programlisting></para>
  572.        </example></para>
  573.    </section>
  574.  
  575.    <section>
  576.      <title><anchor id="s_at_labels" />@ Labels</title>
  577.  
  578.      <para>Labels starting with a '@' are not touched by the label processing
  579.      and used 'as-is'. See 'SetScreen' in the previous example code. <example>
  580.          <title>docs_examples/s_at_labels.asm</title>
  581.  
  582.          <para><programlisting>    MODULE xxx
  583. Label      ; xxx.Label
  584. .Local     ; xxx.Label.Local
  585. @Label     ; Label
  586. .Local     ; xxx.Label.Local =&gt; duplicate label error
  587. @Label2    ; Label2
  588. .Local     ; xxx.Label2.Local
  589. @yyy.Local ; yyy.Local
  590. yyy.Local  ; xxx.yyy.Local</programlisting></para>
  591.        </example></para>
  592.    </section>
  593.  
  594.    <section>
  595.      <title><anchor id="s_temp_labels" />Temporary labels</title>
  596.  
  597.      <para>To keep the number of used labels reasonable it is possible to use
  598.      numbers as labels. These labels can only be used as labels to jump to.
  599.      To jump to these labels, use the number followed by an 'F' for forward
  600.      branches or a 'B' for backward branches. Temporary labels should be defined
  601.      in the same order during every pass of assembling, but they can be used
  602.      within macro, or repeating blocks (old sjasmplus versions didn't allow usage within macro).</para>
  603.  
  604.      <para><example>
  605.          <title>docs_examples/s_temp_labels.asm</title>
  606.  
  607.          <para><programlisting>        ADD A,E
  608.        JR NC,1F
  609.        INC D
  610. 1       LD E,A
  611. 2       LD B,4
  612.        LD A,(DE)
  613.        OUT (152),A
  614.        DJNZ 2B
  615.  
  616.        MACRO zing
  617.            DUP 2
  618.                JR 1F
  619. 1               DJNZ    1B
  620.            EDUP
  621.        ENDM
  622.  
  623.        .4 zing</programlisting></para>
  624.        </example></para>
  625.    </section>
  626.  </chapter>
  627.  
  628.  <chapter>
  629.    <title>Constants, expressions and other features</title>
  630.  
  631.    <section>
  632.      <title><anchor id="s_numeric" />Numeric constants</title>
  633.  
  634.      <para>Numeric constants should always start with a digit or $, # or %.
  635.      The following formats are supported:</para>
  636.  
  637.      <para><programlisting>12     decimal
  638. 12d    decimal
  639. 0xc    hexadecimal
  640. $c     hexadecimal
  641. #c     hexadecimal
  642. 0ch    hexadecimal
  643. 0b1100 binary (v1.12.1)
  644. %1100  binary
  645. 1100b  binary
  646. 0q14   octal (v1.12.1)
  647. 14q    octal
  648. 14o    octal</programlisting></para>
  649.  
  650.      <para>(v1.12.1) Optional single quotes(') may be inserted between the digits as a separator
  651.      (example: <computeroutput> ld a,%11'01'11'00 </computeroutput>).
  652.      They are ignored by the assembler.</para>
  653.    </section>
  654.  
  655.    <section>
  656.      <title>Character and string constants</title>
  657.  
  658.      <para>Character constants are characters surrounded by single quotes. It
  659.      is possible to use double quotes in some cases, but in general it is
  660.      better to use single quotes. String constants are characters surrounded
  661.      by double quotes. When double quotes are used, the following escape
  662.      sequences are recognized:</para>
  663.      <para><programlisting>\\ 92
  664. \? 63
  665. \' 39
  666. \" 34
  667. \0 0     ; since v1.11
  668. \A 7
  669. \B 8
  670. \D 127
  671. \E 27
  672. \F 12
  673. \N 10
  674. \R 13
  675. \T 9
  676. \V 11</programlisting><para>Inside single quotes two quotes after each other are
  677.     parsed as the apostrophe itself (since v1.11).</para><example>
  678.           <title></title>
  679.  
  680.           <para><programlisting>    BYTE "stringconstant\n" ; escape sequence assembles to newline
  681.     BYTE 'stringconstant\n' ; \n assembles literally as two bytes: '\', 'n'
  682.     LD HL,'hl'  ; hl = 0x686C = 'l', 'h'
  683.     LD HL,"hl"  ; hl = 0x686C = 'l', 'h'
  684.     LD A,"7"    ; not recommended (but works)
  685.     LD A,'8'    ; recommended
  686.     LD A,'\E'   ; warning + truncating value to 'E' (0x45)
  687.     LD A,'"'    ; A = 0x22
  688.     LD A,"'"    ; A = 0x27
  689.     LD A,''''   ; A = 0x27 ; since v1.11</programlisting></para>
  690.         </example></para>
  691.     </section>
  692.  
  693.     <section>
  694.       <title><anchor id="s_expressions" />Expressions</title>
  695.  
  696.       <para>Expressions are evaluated in signed 32 bits in this version of SjASMPlus (unless explicitly
  697.                   specified as unsigned, like ">>>" operator), so intermediate values have range -2147483648
  698.                   to +2147483647.</para>
  699.  
  700.       <para>'$' represents the current program counter. '$$' represents the
  701.       current page in the current slot in the <link
  702.       linkend="s_realdevice">real device emulation mode</link>, '$$label' evaluates to number of page
  703.           where the "label" was defined (only regular labels have meaningful value, labels defined
  704.           under DISP mode or EQU/DEFL/... will produce irrelevant values) and '{address}' can be used
  705.       to read WORD from virtual device memory (correct value is read only in last pass of assembling,
  706.           in early passes the zero value is always returned), '{b address}' reads only BYTE.</para>
  707.  
  708.       <para>It is possible to use parenthesis '(' and ')' to override the
  709.       precedence of the operators. The following operators may be used in
  710.       expressions:</para>
  711.  
  712.       <para><programlisting>!     !x       logical not
  713. ~     ~x       complement
  714. +     +x       does "nothing", can be used to make "+(...)" parse as value (not as memory)
  715. -     -x       minus
  716. low   low x    low 8 bits of 16 bit value or lower part of register pair
  717. high  high x   high 8 bits of 16 bit value or higher part of register pair
  718. not   not x    logical not
  719.  
  720. *     x*y      multiplication
  721. /     x/y      division
  722. %     x%y      modulo
  723. mod   x mod y  modulo
  724.  
  725. +     x+y      addition
  726. -     x-y      subtraction
  727.  
  728. &lt;&lt;    x&lt;&lt;y     shift left
  729. &gt;&gt;    x&gt;&gt;y     shift right signed
  730. &gt;&gt;&gt;   x&gt;&gt;&gt;y    shift right unsigned
  731. shl   x shl y  shift left
  732. shr   x shr y  shift right signed
  733.  
  734. &lt;?    x&lt;?y     minimum
  735. &gt;?    x&gt;?y     maximum
  736.  
  737. &lt;     x&lt;y      less than
  738. &gt;     x&gt;y      greater than
  739. &lt;=    x&lt;=y     equal or less than
  740. &gt;=    x&gt;=y     equal or greater than
  741.  
  742. =     x=y      equal
  743. ==    x==y     equal
  744. !=    x!=y     not equal
  745.  
  746. &amp;     x&amp;y      bitwise and
  747. and   x and y  bitwise and
  748.  
  749. ^     x^y      bitwise xor
  750. xor   x xor y  bitwise xor
  751.  
  752. |     x|y      bitwise or
  753. or    x or y   bitwise or
  754.  
  755. &amp;&amp;    x&amp;&amp;y     logical and
  756.  
  757. ||    x||y     logical or
  758.  
  759. $     $        current program counter
  760. $$    $$       current page at program counter (in virtual device mode)
  761. label label    value of label (aka symbol), usually memory address
  762. $$lab $$lab    page of "lab" label (in virtual device mode)
  763. {}    {x}      reads WORD from address x (in virtual device mode, in last pass)
  764. {b}   {b x}    reads BYTE from address x (in virtual device mode, in last pass)
  765. </programlisting></para>
  766.     </section>
  767.  
  768.     <section>
  769.       <title>Assembly language</title>
  770.  
  771.       <para>This version only accepts Z80 mnemonics. There are some additions
  772.       to what I think is standard Z80: <itemizedlist>
  773.           <listitem>
  774.             <para>'[' and ']' can be used instead of '(' and ')' for
  775.             indirection. So <code>LD A,[HL]</code> is the same as <code>LD A,(HL)</code> (does not
  776.             apply to IN/OUT ports, those must use '(...)' form)</para>
  777.           </listitem>
  778.  
  779.           <listitem>
  780.             <para><code>IN F,(C)</code> and <code>OUT (C),0</code> and <code>SLL/SLI</code> can be used
  781.                                 (warning: on some CPU versions of Z80 the OUT (C),0 is working as OUT (C),255).</para>
  782.           </listitem>
  783.  
  784.           <listitem>
  785.             <para>IXL (or LX, XL), IYL (or LY, YL), IXH (or HX, XH) and IYH
  786.             (or HY, YH) registers are supported.</para>
  787.           </listitem>
  788.  
  789.           <listitem>
  790.             <para>Can write code throught colon: ORG 100h:LD A,10:LD B,10:SUB
  791.             B:RET:IFDEF AA:.....</para>
  792.           </listitem>
  793.  
  794.           <listitem>
  795.             <para>JP HL, JP IX and JP IY may be used instead of JP (HL),
  796.             etc.</para>
  797.           </listitem>
  798.  
  799.           <listitem>
  800.             <para>EX AF,AF or EX AF or EXA may be used instead of EX
  801.             AF,AF'.</para>
  802.          </listitem>
  803.  
  804.          <listitem>
  805.            <para>R800's MULUB and MULUW are recognised (but won't work on
  806.            Z80, of course:)</para>
  807.          </listitem>
  808.  
  809.          <listitem>
  810.            <para>Z80N, i8080 and LR35902 modes use the identical Z80 sjasmplus syntax (!), for the
  811.                                 correct (and incorrect) syntax examples of extended opcodes, please check the test files:
  812.                                 Z80N <ulink url="https://github.com/z00m128/sjasmplus/blob/master/tests/z80n/op_zx_spectrum_next_2_00_26.asm">test 1</ulink>
  813.                                 <ulink url="https://github.com/z00m128/sjasmplus/blob/master/tests/z80n/op_next_syntax.lst">test 2</ulink>
  814.                                 and LR35902 <ulink url="https://github.com/z00m128/sjasmplus/blob/master/tests/lr35902/LR35902_syntax_by_neo.lst">test 1</ulink>
  815.                                 <ulink url="https://github.com/z00m128/sjasmplus/blob/master/tests/lr35902/LR35902_specifics_exercise.lst">test 2</ulink>
  816.                                 (also for the Z80 syntax examples you can check <ulink url="https://github.com/z00m128/sjasmplus/tree/master/tests/z80">
  817.                                         Z80 tests</ulink>).
  818.                                 </para>
  819.          </listitem>
  820.  
  821.          <listitem>
  822.            <para>RLC, RRC, RL, RR, SLA, SRA, SLL (SLI), RES, SET undocumented
  823.            instructions added.</para>
  824.          </listitem>
  825.        </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
  826.    RRC (IY),A     ; (aka LD A,RRC (IY+0))   is LD A,(IY)   / RRC A   / LD (IY),A</programlisting><itemizedlist>
  827.          <listitem>
  828.            <para>PUSH and POP can take register lists:</para>
  829.          </listitem>
  830.        </itemizedlist><programlisting>    PUSH AF,BC  ; push af / push bc
  831.    POP  AF,BC  ; pop  af / pop  bc</programlisting><itemizedlist>
  832.          <listitem>
  833.            <para>and many other instructions support this "multi-argument" syntax:</para>
  834.          </listitem>
  835.        </itemizedlist><programlisting>    LD A,B,B,D,D,H
  836.   /* this is:
  837.     LD A,B
  838.     LD B,D
  839.     LD D,H
  840.   */
  841.   ;or you can write  LD A,B:LD B,D:LD D,H
  842.  
  843.   ; since v1.13.1 it is possible and *recommended* to change the multi-arg delimiter
  844.   ; into ",,", to avoid some ambiguities with certain instructions.
  845.   OPT --syntax=a
  846.   LD A,B,,B,D,,D,H ; same as example above in default syntax
  847.   SUB A,B,,C  ; = SUB B, SUB C (the default syntax does for SUB A,B two SUBs!)</programlisting></para>
  848.    </section>
  849.  
  850.    <section>
  851.      <title><anchor id="s_fake_instructions" />Fake instructions</title>
  852.  
  853.      <para>Of course the Z80 is only an 8 bit cpu, but sometimes <code>ld hl,de</code>
  854.      would be nice. SjASMPlus now 'fakes' some instructions like that. This
  855.      improves the readability of the source, but it might not be the fastest
  856.      way to get the result. Also possibly some 'new' load instructions do
  857.      affect the flags in ways you wouldn't expect. You can use option <code>--syntax=f</code>
  858.       to get warnings when fake instruction is used, to avoid using them by accident. Here's the
  859.      list:</para>
  860.  
  861.      <para><programlisting>
  862.  rl bc           ; rl c : rl b
  863.  rl de           ; rl e : rl d
  864.  rl hl           ; rl l : rl h
  865.  rr bc           ; rr b : rr c
  866.  rr de           ; rr d : rr e
  867.  rr hl           ; rr h : rr l
  868.  sla bc          ; sla c : rl b
  869.  sla de          ; sla e : rl d
  870.  sla hl          ; add hl,hl
  871.  sll bc          ; sli c : rl b
  872.  sll de          ; sli e : rl d
  873.  sll hl          ; sli l : rl h
  874.  sli bc          ; sli c : rl b
  875.  sli de          ; sli e : rl d
  876.  sli hl          ; sli l : rl h
  877.  sra bc          ; sra b : rr c
  878.  sra de          ; sra d : rr e
  879.  sra hl          ; sra h : rr l
  880.  srl bc          ; srl b : rr c
  881.  srl de          ; srl d : rr e
  882.  srl hl          ; srl h : rr l
  883.  
  884.  ld bc,bc        ; ld b,b : ld c,c
  885.  ld bc,de        ; ld b,d : ld c,e
  886.  ld bc,hl        ; ld b,h : ld c,l
  887.  ld bc,ix        ; ld b,xh : ld c,xl
  888.  ld bc,iy        ; ld b,yh : ld c,yl
  889.  ld bc,(hl)      ; ld c,(hl) : inc hl : ld b,(hl) : dec hl
  890.  ld bc,(ix+nn)   ; ld c,(ix+nn) : ld b,(ix+nn+1)
  891.  ld bc,(iy+nn)   ; ld c,(iy+nn) : ld b,(iy+nn+1)
  892.  
  893.  ld de,bc        ; ld d,b : ld e,c
  894.  ld de,de        ; ld d,d : ld e,e
  895.  ld de,hl        ; ld d,h : ld e,l
  896.  ld de,ix        ; ld d,xh : ld e,xl
  897.  ld de,iy        ; ld d,yh : ld e,yl
  898.  ld de,(hl)      ; ld e,(hl) : inc hl : ld d,(hl) : dec hl
  899.  ld de,(ix+nn)   ; ld e,(ix+nn) : ld d,(ix+nn+1)
  900.  ld de,(iy+nn)   ; ld e,(iy+nn) : ld d,(iy+nn+1)
  901.  
  902.  ld hl,bc        ; ld h,b : ld l,c
  903.  ld hl,de        ; ld h,d : ld l,e
  904.  ld hl,hl        ; ld h,h : ld l,l
  905.  ld hl,ix        ; push ix : pop hl
  906.  ld hl,iy        ; push iy : pop hl
  907.  ld hl,(ix+nn)   ; ld l,(ix+nn) : ld h,(ix+nn+1)
  908.  ld hl,(iy+nn)   ; ld l,(iy+nn) : ld h,(iy+nn+1)
  909.  
  910.  ld ix,bc        ; ld xh,b : ld xl,c
  911.  ld ix,de        ; ld xh,d : ld xl,e
  912.  ld ix,hl        ; push hl : pop ix
  913.  ld ix,ix        ; ld xh,xh : ld xl,xl
  914.  ld ix,iy        ; push iy : pop ix
  915.  
  916.  ld iy,bc        ; ld yh,b : ld yl,c
  917.  ld iy,de        ; ld yh,d : ld yl,e
  918.  ld iy,hl        ; push hl : pop iy
  919.  ld iy,ix        ; push ix : pop iy
  920.  ld iy,iy        ; ld yh,yh : ld yl,yl
  921.  
  922.  ld (hl),bc      ; ld (hl),c : inc hl : ld (hl),b : dec hl
  923.  ld (hl),de      ; ld (hl),e : inc hl : ld (hl),d : dec hl
  924.  
  925.  ld (ix+nn),bc   ; ld (ix+nn),c : ld (ix+nn+1),b
  926.  ld (ix+nn),de   ; ld (ix+nn),e : ld (ix+nn+1),d
  927.  ld (ix+nn),hl   ; ld (ix+nn),l : ld (ix+nn+1),h
  928.  
  929.  ld (iy+nn),bc   ; ld (iy+nn),c : ld (iy+nn+1),b
  930.  ld (iy+nn),de   ; ld (iy+nn),e : ld (iy+nn+1),d
  931.  ld (iy+nn),hl   ; ld (iy+nn),l : ld (iy+nn+1),h
  932.  
  933.  ldi bc,(hl)     ; ld c,(hl) : inc hl : ld b,(hl) : inc hl
  934.  ldi bc,(ix+nn)  ; ld c,(ix+nn) : inc ix : ld b,(ix+nn) : inc ix
  935.  ldi bc,(iy+nn)  ; ld c,(iy+nn) : inc iy : ld b,(iy+nn) : inc iy
  936.  
  937.  ldi de,(hl)     ; ld e,(hl) : inc hl : ld d,(hl) : inc hl
  938.  ldi de,(ix+nn)  ; ld e,(ix+nn) : inc ix : ld d,(ix+nn) : inc ix
  939.  ldi de,(iy+nn)  ; ld e,(iy+nn) : inc iy : ld d,(iy+nn) : inc iy
  940.  
  941.  ldi hl,(ix+nn)  ; ld l,(ix+nn) : inc ix : ld h,(ix+nn) : inc ix
  942.  ldi hl,(iy+nn)  ; ld l,(iy+nn) : inc iy : ld h,(iy+nn) : inc iy
  943.  
  944.  ldi (hl),bc     ; ld (hl),c : inc hl : ld (hl),b : inc hl
  945.  ldi (hl),de     ; ld (hl),e : inc hl : ld (hl),d : inc hl
  946.  
  947.  ldi (ix+nn),bc  ; ld (ix+nn),c : inc ix : ld (ix+nn),b : inc ix
  948.  ldi (ix+nn),de  ; ld (ix+nn),e : inc ix : ld (ix+nn),d : inc ix
  949.  ldi (ix+nn),hl  ; ld (ix+nn),l : inc ix : ld (ix+nn),h : inc ix
  950.  
  951.  ldi (iy+nn),bc  ; ld (iy+nn),c : inc iy : ld (iy+nn),b : inc iy
  952.  ldi (iy+nn),de  ; ld (iy+nn),e : inc iy : ld (iy+nn),d : inc iy
  953.  ldi (iy+nn),hl  ; ld (iy+nn),l : inc iy : ld (iy+nn),h : inc iy
  954.  
  955.  ldi a,(bc)      ; ld a,(bc) : inc bc
  956.  ldi a,(de)      ; ld a,(de) : inc de
  957.  ldi a,(hl)      ; ld a,(hl) : inc hl
  958.  ldi b,(hl)      ; ld b,(hl) : inc hl
  959.  ldi c,(hl)      ; ld c,(hl) : inc hl
  960.  ldi d,(hl)      ; ld d,(hl) : inc hl
  961.  ldi e,(hl)      ; ld e,(hl) : inc hl
  962.  ldi h,(hl)      ; ld h,(hl) : inc hl
  963.  ldi l,(hl)      ; ld l,(hl) : inc hl
  964.  ldi a,(ix+nn)   ; ld a,(ix+nn) : inc ix
  965.  ldi b,(ix+nn)   ; ld b,(ix+nn) : inc ix
  966.  ldi c,(ix+nn)   ; ld c,(ix+nn) : inc ix
  967.  ldi d,(ix+nn)   ; ld d,(ix+nn) : inc ix
  968.  ldi e,(ix+nn)   ; ld e,(ix+nn) : inc ix
  969.  ldi h,(ix+nn)   ; ld h,(ix+nn) : inc ix
  970.  ldi l,(ix+nn)   ; ld l,(ix+nn) : inc ix
  971.  ldi a,(iy+nn)   ; ld a,(iy+nn) : inc iy
  972.  ldi b,(iy+nn)   ; ld b,(iy+nn) : inc iy
  973.  ldi c,(iy+nn)   ; ld c,(iy+nn) : inc iy
  974.  ldi d,(iy+nn)   ; ld d,(iy+nn) : inc iy
  975.  ldi e,(iy+nn)   ; ld e,(iy+nn) : inc iy
  976.  ldi h,(iy+nn)   ; ld h,(iy+nn) : inc iy
  977.  ldi l,(iy+nn)   ; ld l,(iy+nn) : inc iy
  978.  
  979.  ldd a,(bc)      ; ld a,(bc) : dec bc
  980.  ldd a,(de)      ; ld a,(de) : dec de
  981.  ldd a,(hl)      ; ld a,(hl) : dec hl
  982.  ldd b,(hl)      ; ld b,(hl) : dec hl
  983.  ldd c,(hl)      ; ld c,(hl) : dec hl
  984.  ldd d,(hl)      ; ld d,(hl) : dec hl
  985.  ldd e,(hl)      ; ld e,(hl) : dec hl
  986.  ldd h,(hl)      ; ld h,(hl) : dec hl
  987.  ldd l,(hl)      ; ld l,(hl) : dec hl
  988.  ldd a,(ix+nn)   ; ld a,(ix+nn) : dec ix
  989.  ldd b,(ix+nn)   ; ld b,(ix+nn) : dec ix
  990.  ldd c,(ix+nn)   ; ld c,(ix+nn) : dec ix
  991.  ldd d,(ix+nn)   ; ld d,(ix+nn) : dec ix
  992.  ldd e,(ix+nn)   ; ld e,(ix+nn) : dec ix
  993.  ldd h,(ix+nn)   ; ld h,(ix+nn) : dec ix
  994.  ldd l,(ix+nn)   ; ld l,(ix+nn) : dec ix
  995.  ldd a,(iy+nn)   ; ld a,(iy+nn) : dec iy
  996.  ldd b,(iy+nn)   ; ld b,(iy+nn) : dec iy
  997.  ldd c,(iy+nn)   ; ld c,(iy+nn) : dec iy
  998.  ldd d,(iy+nn)   ; ld d,(iy+nn) : dec iy
  999.  ldd e,(iy+nn)   ; ld e,(iy+nn) : dec iy
  1000.  ldd h,(iy+nn)   ; ld h,(iy+nn) : dec iy
  1001.  ldd l,(iy+nn)   ; ld l,(iy+nn) : dec iy
  1002.  
  1003.  ldi (bc),a      ; ld (bc),a : inc bc
  1004.  ldi (de),a      ; ld (de),a : inc de
  1005.  ldi (hl),a      ; ld (hl),a : inc hl
  1006.  ldi (hl),b      ; ld (hl),b : inc hl
  1007.  ldi (hl),c      ; ld (hl),c : inc hl
  1008.  ldi (hl),d      ; ld (hl),d : inc hl
  1009.  ldi (hl),e      ; ld (hl),e : inc hl
  1010.  ldi (hl),h      ; ld (hl),h : inc hl
  1011.  ldi (hl),l      ; ld (hl),l : inc hl
  1012.  ldi (ix+nn),a   ; ld (ix+nn),a : inc ix
  1013.  ldi (ix+nn),b   ; ld (ix+nn),b : inc ix
  1014.  ldi (ix+nn),c   ; ld (ix+nn),c : inc ix
  1015.  ldi (ix+nn),d   ; ld (ix+nn),d : inc ix
  1016.  ldi (ix+nn),e   ; ld (ix+nn),e : inc ix
  1017.  ldi (ix+nn),h   ; ld (ix+nn),h : inc ix
  1018.  ldi (ix+nn),l   ; ld (ix+nn),l : inc ix
  1019.  ldi (iy+nn),a   ; ld (iy+nn),a : inc iy
  1020.  ldi (iy+nn),b   ; ld (iy+nn),b : inc iy
  1021.  ldi (iy+nn),c   ; ld (iy+nn),c : inc iy
  1022.  ldi (iy+nn),d   ; ld (iy+nn),d : inc iy
  1023.  ldi (iy+nn),e   ; ld (iy+nn),e : inc iy
  1024.  ldi (iy+nn),h   ; ld (iy+nn),h : inc iy
  1025.  ldi (iy+nn),l   ; ld (iy+nn),l : inc iy
  1026.  
  1027.  ldd (bc),a      ; ld (bc),a : dec bc
  1028.  ldd (de),a      ; ld (de),a : dec de
  1029.  ldd (hl),a      ; ld (hl),a : dec hl
  1030.  ldd (hl),b      ; ld (hl),b : dec hl
  1031.  ldd (hl),c      ; ld (hl),c : dec hl
  1032.  ldd (hl),d      ; ld (hl),d : dec hl
  1033.  ldd (hl),e      ; ld (hl),e : dec hl
  1034.  ldd (hl),h      ; ld (hl),h : dec hl
  1035.  ldd (hl),l      ; ld (hl),l : dec hl
  1036.  ldd (ix+nn),a   ; ld (ix+nn),a : dec ix
  1037.  ldd (ix+nn),b   ; ld (ix+nn),b : dec ix
  1038.  ldd (ix+nn),c   ; ld (ix+nn),c : dec ix
  1039.  ldd (ix+nn),d   ; ld (ix+nn),d : dec ix
  1040.  ldd (ix+nn),e   ; ld (ix+nn),e : dec ix
  1041.  ldd (ix+nn),h   ; ld (ix+nn),h : dec ix
  1042.  ldd (ix+nn),l   ; ld (ix+nn),l : dec ix
  1043.  ldd (iy+nn),a   ; ld (iy+nn),a : dec iy
  1044.  ldd (iy+nn),b   ; ld (iy+nn),b : dec iy
  1045.  ldd (iy+nn),c   ; ld (iy+nn),c : dec iy
  1046.  ldd (iy+nn),d   ; ld (iy+nn),d : dec iy
  1047.  ldd (iy+nn),e   ; ld (iy+nn),e : dec iy
  1048.  ldd (iy+nn),h   ; ld (iy+nn),h : dec iy
  1049.  ldd (iy+nn),l   ; ld (iy+nn),l : dec iy
  1050.  
  1051.  ldi (hl),mm     ; ld (hl),mm : inc hl
  1052.  ldi (ix+nn),mm  ; ld (ix+nn),mm : inc ix
  1053.  ldi (iy+nn),mm  ; ld (iy+nn),mm : inc iy
  1054.  
  1055.  ldd (hl),mm     ; ld (hl),mm : dec hl
  1056.  ldd (ix+nn),mm  ; ld (ix+nn),mm : dec ix
  1057.  ldd (iy+nn),mm  ; ld (iy+nn),mm : dec iy
  1058.  
  1059.  sub hl,bc       ; or a : sbc hl,bc
  1060.  sub hl,de       ; or a : sbc hl,de
  1061.  sub hl,hl       ; or a : sbc hl,hl
  1062.  sub hl,sp       ; or a : sbc hl,sp
  1063.  
  1064.  ; Z80N only
  1065.  mul             ; mul de ; to avoid warning specify registers</programlisting>
  1066.      <code>LDI</code> increases the data pointer after the data
  1067.      access, so <code>LDI A,(HL)</code> is the same as <code>LD A,(HL):INC HL</code>.
  1068.      Likewise, <code>LDD A,(DE)</code> is <code>LD A,(DE):DEC DE</code>.</para>
  1069.    </section>
  1070.  
  1071.    <section>
  1072.      <title><anchor id="s_realdevice" />Real device emulation mode</title>
  1073.  
  1074.      <para>To enable this mode you must use pseudo-op <link
  1075.      linkend="po_device">DEVICE</link>.</para>
  1076.  
  1077.      <para>In this mode the compiler compiling program to virtual memory (as
  1078.      at MSX's WB-ASS2, ZX-Spectrum's GENS, ZEUS, ALASM etc). After this all
  1079.      you can use new pseudo-ops as <link linkend="s_pseudoops">SAVEBIN, SAVEDEV
  1080.      SAVEHOB, SAVETRD, SAVETAP, PAGE, SLOT, MMU, LABELSLIST</link>, use special
  1081.      functions in <link linkend="c_lua_scripting">Lua scripts</link> and use operators
  1082.      <code>{address}, {b address}</code> to read WORD/BYTE from the virtual memory.</para>
  1083.  
  1084.      <para>If only single DEVICE is used in whole source batch, the device
  1085.      becomes "global" and will affect also source ahead of the DEVICE line.
  1086.          <example>
  1087.          <title>docs_examples/s_realdevice.asm</title>
  1088.  
  1089.          <para><programlisting>    DEVICE ZXSPECTRUM128
  1090.    ; in this device the default slot is SLOT 3 with PAGE 0 paged in.
  1091.  
  1092.    ORG 32768
  1093. StartProg:
  1094.    JP $
  1095.  
  1096.    DEVICE NONE
  1097.    ;do something, if you don't want to corrupt virtual
  1098.     ;memory with other code, for example, loader of code.
  1099.     ;...code...
  1100.  
  1101.     ;return to our virtual device:
  1102.     DEVICE ZXSPECTRUM128
  1103.  
  1104.     SAVESNA "snapshotname.sna", StartProg</programlisting></para>
  1105.         </example>Predefined devices:<variablelist>
  1106.           <varlistentry>
  1107.             <term><anchor id="device_none" />NONE</term>
  1108.  
  1109.             <listitem>
  1110.               <para>Disable real device emulation mode. By default.</para>
  1111.             </listitem>
  1112.           </varlistentry>
  1113.  
  1114.           <varlistentry>
  1115.             <term><anchor id="device_zx48" />ZXSPECTRUM48</term>
  1116.  
  1117.             <listitem>
  1118.               <para>Has 4 slots (0-3) with size 4000h, 4 pages (0-3) with size
  1119.               4000h. Slot 3 (it from 0C000h) enables to current by
  1120.               default.</para>
  1121.             </listitem>
  1122.           </varlistentry>
  1123.  
  1124.           <varlistentry>
  1125.             <term><anchor id="device_zx128" />ZXSPECTRUM128</term>
  1126.  
  1127.             <listitem>
  1128.               <para>Has 8 RAM pages (0-7) with size 4000h. Default slot is 3.</para>
  1129.             </listitem>
  1130.           </varlistentry>
  1131.  
  1132.           <varlistentry>
  1133.             <term><anchor id="device_zx256" />ZXSPECTRUM256</term>
  1134.  
  1135.             <listitem>
  1136.               <para>Same as Russian clone Scorption 256. Has 16 RAM pages
  1137.               (0-15) with size 4000h.</para>
  1138.             </listitem>
  1139.           </varlistentry>
  1140.  
  1141.           <varlistentry>
  1142.             <term><anchor id="device_zx512" />ZXSPECTRUM512</term>
  1143.  
  1144.             <listitem>
  1145.               <para>Same as Russian clones ATM Turbo 512 and Pentagon 512. Has
  1146.               32 RAM pages (0-31) with size 4000h.</para>
  1147.             </listitem>
  1148.           </varlistentry>
  1149.  
  1150.           <varlistentry>
  1151.             <term><anchor id="device_zx1024" />ZXSPECTRUM1024</term>
  1152.  
  1153.             <listitem>
  1154.               <para>Same as Russian clones ATM Turbo 2 and Pentagon 1024 SL.
  1155.               Has 64 RAM pages (0-63) with size 4000h.</para>
  1156.             </listitem>
  1157.           </varlistentry>
  1158.  
  1159.           <varlistentry>
  1160.             <term><anchor id="device_zx2048" />ZXSPECTRUM2048</term>
  1161.  
  1162.             <listitem>
  1163.               <para>Similar to other spectrum devices, has 128 RAM pages (0-127) with size 4000h.</para>
  1164.             </listitem>
  1165.           </varlistentry>
  1166.  
  1167.           <varlistentry>
  1168.             <term><anchor id="device_zx4096" />ZXSPECTRUM4096</term>
  1169.  
  1170.             <listitem>
  1171.               <para>Similar to other spectrum devices, has 256 RAM pages (0-255) with size 4000h.</para>
  1172.             </listitem>
  1173.           </varlistentry>
  1174.  
  1175.           <varlistentry>
  1176.             <term><anchor id="device_zx8192" />ZXSPECTRUM8192</term>
  1177.  
  1178.             <listitem>
  1179.               <para>Similar to other spectrum devices, has 512 RAM pages (0-511) with size 4000h.</para>
  1180.             </listitem>
  1181.           </varlistentry>
  1182.  
  1183.           <varlistentry>
  1184.             <term><anchor id="device_zxn" />ZXSPECTRUMNEXT</term>
  1185.  
  1186.             <listitem>
  1187.               <para>ZX Spectrum Next, has 8 slots (0-7) of size 0x2000 and 224
  1188.               RAM pages (0-223) totalling at 1.75MiB of memory. The <ulink
  1189.                 url="https://wiki.specnext.dev/Memory_map#Z80_Visible_Memory_map">default mapping</ulink>
  1190.               is similar to ZX128, paging in: {14, 15, 10, 11, 4, 5, 0, 1} pages.
  1191.               Default slot is 7 (memory range 0xE000..0xFFFF).
  1192.               All memory is zeroed during initialization.</para>
  1193.             </listitem>
  1194.           </varlistentry>
  1195.         </variablelist></para>
  1196.  
  1197.       <para>If you want to see other devices you must write to us. See <link
  1198.       linkend="feedback">Feedback</link> chapter.</para>
  1199.     </section>
  1200.  
  1201.     <section>
  1202.       <title><anchor id="s_predefined" />Predefined defines</title>
  1203.  
  1204.       <para>SjASMPlus has predefined <link
  1205.       linkend="po_define">defines</link>.<variablelist>
  1206.  
  1207.           <varlistentry>
  1208.             <term>__SJASMPLUS__ = &lt;24bit number&gt;</term>
  1209.  
  1210.             <listitem>
  1211.               <para>Current version split into three 8bit values, ie. 0x010F02 for "1.15.2".</para>
  1212.             </listitem>
  1213.           </varlistentry>
  1214.  
  1215.           <varlistentry>
  1216.             <term>__VERSION__ = "version string"</term>
  1217.  
  1218.             <listitem>
  1219.               <para>String value (with quotes around it) of current version like <code>"1.15.2"</code>.</para>
  1220.             </listitem>
  1221.           </varlistentry>
  1222.  
  1223.           <varlistentry>
  1224.             <term>__ERRORS__ = &lt;number&gt;</term>
  1225.  
  1226.             <listitem>
  1227.               <para>Number of errors.</para>
  1228.             </listitem>
  1229.           </varlistentry>
  1230.  
  1231.           <varlistentry>
  1232.             <term>__WARNINGS__ = &lt;number&gt;</term>
  1233.  
  1234.             <listitem>
  1235.               <para>Number of warnings.</para>
  1236.             </listitem>
  1237.           </varlistentry>
  1238.  
  1239.           <varlistentry>
  1240.             <term>__PASS__ = &lt;number&gt;</term>
  1241.  
  1242.             <listitem>
  1243.               <para>Current assembling pass (1, 2 or 3).</para>
  1244.             </listitem>
  1245.           </varlistentry>
  1246.  
  1247.           <varlistentry>
  1248.             <term>__INCLUDE_LEVEL__ = &lt;number&gt;</term>
  1249.  
  1250.             <listitem>
  1251.               <para>Current include-nesting level.</para>
  1252.             </listitem>
  1253.           </varlistentry>
  1254.  
  1255.           <varlistentry>
  1256.             <term>__BASE_FILE__ = &lt;name of base file&gt;</term>
  1257.  
  1258.             <listitem>
  1259.               <para>Name of base file (include-level zero).</para>
  1260.               <para>This is raw value without quotes, practically unusable by asm source, but LUA
  1261.                                   provides means to operate with such string value.</para>
  1262.             </listitem>
  1263.           </varlistentry>
  1264.  
  1265.           <varlistentry>
  1266.             <term>__FILE__ = &lt;name of current file&gt;</term>
  1267.  
  1268.             <listitem>
  1269.               <para>Name of current file.</para>
  1270.               <para>This is raw value without quotes, practically unusable by asm source, but LUA
  1271.                                   provides means to operate with such string value.</para>
  1272.             </listitem>
  1273.           </varlistentry>
  1274.  
  1275.           <varlistentry>
  1276.             <term>__LINE__ = &lt;number&gt;</term>
  1277.  
  1278.             <listitem>
  1279.               <para>Current line number.</para>
  1280.             </listitem>
  1281.           </varlistentry>
  1282.  
  1283.           <varlistentry>
  1284.             <term>__COUNTER__ = &lt;incrementing number&gt;</term>
  1285.  
  1286.             <listitem>
  1287.               <para>Does increment upon each usage (starting as value 0). Currently difficult to
  1288.                                   use for labels/symbols, because the starting `_` of the define name prevents
  1289.                                   mid-word substitution, will make more sense with new substitution rules (if ever
  1290.                                   the sjasmplus v2.x happens, would be too big change for v1.x). Right now call
  1291.                                   LUA for the rescue.</para>
  1292.                           <example>
  1293.                   <title>__COUNTER__ usage in LUA script</title>
  1294.  
  1295.                   <programlisting>    DB __COUNTER__   ; DB 0
  1296.     LUA ALLPASS
  1297.         sj.insert_label("label_" .. sj.get_define("__COUNTER__"), sj.current_address)
  1298.                 -- creates "label_1" at "$" (0x0001)
  1299.         sj.insert_label("label_" .. sj.get_define("__COUNTER__"), _c("$+10"))
  1300.                 -- creates "label_2" at "$+10" (0x000B)
  1301.     ENDLUA
  1302. label__COUNTER__: ; does *NOT* substitute in current sjasmplus, sorry
  1303.     DB __COUNTER__   ; DB 3
  1304.  
  1305.     ; also macro arguments substitution can be used
  1306.     MACRO createLabelWithSuffix label?, suffix?
  1307. label?_suffix? ; define global label
  1308.     ENDM
  1309.     createLabelWithSuffix label, __COUNTER__    ; label_4
  1310.     createLabelWithSuffix label, __COUNTER__    ; label_5</programlisting>
  1311.                 </example>
  1312.             </listitem>
  1313.           </varlistentry>
  1314.  
  1315.           <varlistentry>
  1316.             <term>Deprecated predefined values from sjasmplus till version 1.15.1:</term>
  1317.  
  1318.             <listitem>
  1319.                                 <para>The predefined values were renamed and extended to be more like gcc/clang pre-defines,
  1320.                                         the following ones are deprecated originals.</para>
  1321.             </listitem>
  1322.           </varlistentry>
  1323.  
  1324.           <varlistentry>
  1325.             <term>_SJASMPLUS = 1</term>
  1326.  
  1327.             <listitem>
  1328.               <para>Deprecated, consider using similar __SJASMPLUS__<example>
  1329.                   <title></title>
  1330.  
  1331.                   <para><programlisting>   IFDEF _SJASMPLUS
  1332.      ;code for sjasmplus
  1333.    ELSE
  1334.      ;code for other compiler
  1335.    ENDIF</programlisting></para>
  1336.                 </example></para>
  1337.             </listitem>
  1338.           </varlistentry>
  1339.  
  1340.           <varlistentry>
  1341.             <term>_VERSION = "version"</term>
  1342.  
  1343.             <listitem>
  1344.               <para>Deprecated, renamed to __VERSION__<example>
  1345.                   <title></title>
  1346.  
  1347.                   <para><programlisting>   IF _VERSION = "1.07"
  1348.      ;code for 1.07
  1349.    ELSE
  1350.      ;code for other version
  1351.    ENDIF</programlisting></para>
  1352.                 </example></para>
  1353.             </listitem>
  1354.           </varlistentry>
  1355.  
  1356.           <varlistentry>
  1357.             <term>_RELEASE = releasenumber</term>
  1358.  
  1359.             <listitem>
  1360.               <para>Deprecated, consider using similar __SJASMPLUS__<example>
  1361.                   <title></title>
  1362.  
  1363.                   <para><programlisting>   IF _RELEASE = 1 ; 0 - is stable version
  1364.      ;code for Release Candidate 1
  1365.    ELSE
  1366.      ;code for other version
  1367.    ENDIF</programlisting></para>
  1368.                 </example></para>
  1369.             </listitem>
  1370.           </varlistentry>
  1371.  
  1372.           <varlistentry>
  1373.             <term>_ERRORS = &lt;number&gt;</term>
  1374.  
  1375.             <listitem>
  1376.               <para>Number of errors. Deprecated, renamed to __ERRORS__</para>
  1377.             </listitem>
  1378.           </varlistentry>
  1379.  
  1380.           <varlistentry>
  1381.             <term>_WARNINGS = &lt;number&gt;</term>
  1382.  
  1383.             <listitem>
  1384.               <para>Number of warnings. Deprecated, renamed to __WARNINGS__</para>
  1385.             </listitem>
  1386.           </varlistentry>
  1387.         </variablelist></para>
  1388.     </section>
  1389.   </chapter>
  1390.  
  1391.   <chapter>
  1392.     <title>Pseudo-ops (aka Pseudo-instructions, Directives etc)</title>
  1393.  
  1394.     <section>
  1395.       <title>Simple example of usage</title>
  1396.  
  1397.       <para><programlisting>     .SOMEPSEUDOOP ;or
  1398.      SOMEPSEUDOOP  ;or
  1399.      somepseudoop</programlisting></para>
  1400.     </section>
  1401.  
  1402.     <section>
  1403.       <title><anchor id="s_pseudoops" />Almost complete list</title>
  1404.  
  1405.       <para></para>
  1406.  
  1407.       <para><variablelist>
  1408.           <varlistentry>
  1409.             <term><anchor id="po_dot_repeat" />.&lt;repeat-count&gt; &lt;single instruction&gt;</term>
  1410.  
  1411.             <listitem>
  1412.               <para>Repeat &lt;single instruction&gt; &lt;repeat-count&gt; many times. Doesn't work
  1413.                                   in the beginning of line. The &lt;repeat-count&gt; must be either simple integer
  1414.                                   number or expression fully enclosed in parentheses.<example>
  1415.                  <title>docs_examples/po_dot_repeat.asm</title>
  1416.  
  1417.                  <para><programlisting> .3        INC A    ;will be compiled to INC A:INC A:INC A
  1418. len        EQU 10
  1419. .(12-len) BYTE 0   ;will be compiled to BYTE 0,0
  1420. .2 .3     RET      ;will be compiled to 6x RET</programlisting></para>
  1421.                </example></para>
  1422.            </listitem>
  1423.          </varlistentry>
  1424.  
  1425.          <varlistentry>
  1426.            <term><anchor id="po_abyte" />ABYTE &lt;offset&gt; &lt;bytes&gt;</term>
  1427.  
  1428.            <listitem>
  1429.              <para>Defines a byte or a string of bytes. The offset is added
  1430.              to each of the following bytes.<example>
  1431.                  <title></title>
  1432.  
  1433.                  <para><programlisting>    ABYTE 2 4,9    ; Same as BYTE 6,11
  1434.    ABYTE 3 "ABC"  ; Same as BYTE "DEF"</programlisting></para>
  1435.                </example></para>
  1436.            </listitem>
  1437.          </varlistentry>
  1438.  
  1439.          <varlistentry>
  1440.            <term><anchor id="po_abytec" />ABYTEC &lt;offset&gt; &lt;bytes&gt;</term>
  1441.  
  1442.            <listitem>
  1443.              <para>Defines a byte or a string of bytes, where the last byte
  1444.              of the string will have bit 7 set. The offset is added to each
  1445.              of the following bytes.<example>
  1446.                  <title></title>
  1447.  
  1448.                  <para><programlisting>    ABYTEC 0 "KIP"        ; Same as BYTE "KI",'P'|128
  1449.    ABYTEC 1 "ABC",0,"DE" ; Same as BYTE "BC",'D'|128,1,'E','F'|128</programlisting></para>
  1450.                </example></para>
  1451.            </listitem>
  1452.          </varlistentry>
  1453.  
  1454.          <varlistentry>
  1455.            <term><anchor id="po_abytez" />ABYTEZ &lt;offset&gt; &lt;bytes&gt;</term>
  1456.  
  1457.            <listitem>
  1458.              <para>Defines a byte or a string of bytes, followed by a zero.
  1459.              The offset is added to each of the following bytes.<example>
  1460.                  <title></title>
  1461.  
  1462.                  <para><programlisting>    ABYTEZ 0 "KIP"        ; Same as BYTE "KIP",0</programlisting></para>
  1463.                </example></para>
  1464.            </listitem>
  1465.          </varlistentry>
  1466.  
  1467.          <varlistentry>
  1468.            <term><anchor id="po_align" />ALIGN
  1469.            [&lt;expression equal to 1,2,4,8,16,32,64,128,256,512,1024,2048,4096,8192,16384 or
  1470.            32768&gt;[, &lt;byte&gt;]]</term>
  1471.  
  1472.            <listitem>
  1473.              <para>Align advances to nearest address where &lt;new address&gt; modulo &lt;expression&gt; (default 4)
  1474.                  equals zero (stays at current address if possible).</para>
  1475.              <para>If &lt;byte&gt; is specified, memory advanced over is set to it.
  1476.                  <example>
  1477.                  <title></title>
  1478.  
  1479.                  <para><programlisting>    ALIGN         ; =&gt; ALIGN 4 - simply align by 4
  1480.    ALIGN 2       ; by 2 (preserves value of "device" memory)
  1481.    ALIGN 2,0     ; + fills memory with zero</programlisting></para>
  1482.                </example></para>
  1483.            </listitem>
  1484.          </varlistentry>
  1485.  
  1486.          <varlistentry>
  1487.            <term><anchor id="po_assert" />ASSERT &lt;expression&gt;</term>
  1488.  
  1489.            <listitem>
  1490.              <para>An 'assertion failed' error is issued if the expression
  1491.              evaluates to zero.<example>
  1492.                  <title></title>
  1493.  
  1494.                  <para><programlisting>STACKPOINTER=0D500H
  1495.    ASSERT END_OF_PROGRAM &lt; STACKPOINTER
  1496. END_OF_PROGRAM</programlisting></para>
  1497.                </example></para>
  1498.            </listitem>
  1499.          </varlistentry>
  1500.  
  1501.          <varlistentry>
  1502.            <term><anchor id="po_binary" />BINARY &lt;filename&gt;[,&lt;offset&gt;[,&lt;length&gt;]]</term>
  1503.  
  1504.            <listitem>
  1505.              <para>Synonym of <link linkend="po_incbin">INCBIN</link>.</para>
  1506.            </listitem>
  1507.          </varlistentry>
  1508.  
  1509.          <varlistentry>
  1510.            <term><anchor id="po_block" />BLOCK &lt;length&gt;[,&lt;fill
  1511.            byte&gt;]</term>
  1512.  
  1513.            <listitem>
  1514.              <para>Defines space. Has to be followed by the number of byte to
  1515.              reserve, optionally followed by the value to fill these bytes
  1516.              with.<example>
  1517.                  <title></title>
  1518.  
  1519.                  <para><programlisting>    BLOCK 500     ; define a block of 500 bytes of zero
  1520.    BLOCK 500,0   ; define a block of 500 bytes of zero
  1521.    BLOCK 400,-1  ; define a block of 400 bytes of 255</programlisting></para>
  1522.                </example></para>
  1523.            </listitem>
  1524.          </varlistentry>
  1525.  
  1526.          <varlistentry>
  1527.            <term><anchor id="po_bplist" />BPLIST &lt;filename&gt; [unreal|zesarux]</term>
  1528.  
  1529.            <listitem>
  1530.                                 <para>
  1531.                                         <emphasis>Works only in real device emulation mode. See
  1532.                                                 <link linkend="po_device">DEVICE</link>.</emphasis>
  1533.                                 </para>
  1534.                                 <para>Opens file to export breakpoints info directly from ASM source, currently two
  1535.                                         flavours of export are supported: <code>unreal</code> (default) and
  1536.                                         <code>zesarux</code>. For latest Unreal emulators use filename "bpx.ini", you
  1537.                                         can then load the file from the emulator UI. For ZEsarUX the file will contain
  1538.                                         command-line options, which you can add to the command when launching the emulator.
  1539.                                 </para>
  1540.                                 <para>(current version of ZEsarUX will not catch the very first instruction of freshly
  1541.                                         loaded snapshot/NEX/... file, or it will even disable breakpoints when changing
  1542.                                         machine parameters and ignore the <code>--enable-breakpoints</code> option - will
  1543.                                         be hopefully improved in the future)
  1544.                                   <example>
  1545.                  <title></title>
  1546.  
  1547.                  <programlisting>    BPLIST "bpx.ini" unreal  ; open breakpoints list in "Unreal" format
  1548.    ; or (only one file per assembling-unit can be specified)
  1549.    BPLIST "cmd_line_options.txt" zesarux ; open breakpoints list in "ZEsarUX" format</programlisting>
  1550.                                   </example>
  1551.                                 </para>
  1552.            </listitem>
  1553.          </varlistentry>
  1554.  
  1555.          <varlistentry>
  1556.            <term><anchor id="po_byte" />BYTE &lt;bytes&gt;</term>
  1557.  
  1558.            <listitem>
  1559.              <para>Defines a byte or a string of bytes. Each value should be
  1560.              between -129 and 256.<example>
  1561.                  <title></title>
  1562.  
  1563.                  <para><programlisting>    BYTE 0x56
  1564.    BYTE 1,-78,'@'
  1565.    BYTE "Format C:? ",0h</programlisting></para>
  1566.                </example></para>
  1567.            </listitem>
  1568.          </varlistentry>
  1569.  
  1570.          <varlistentry>
  1571.            <term><anchor id="po_cspectmap" />CSPECTMAP [&lt;filename&gt;]</term>
  1572.  
  1573.            <listitem>
  1574.              <para><emphasis>Useful for ZX-Spectrum Emulator
  1575.              #CSpect by Mike Dailly.</emphasis></para>
  1576.  
  1577.              <para><emphasis>Works only in real device emulation mode. See
  1578.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  1579.  
  1580.              <para>Saves labels list in format:</para>
  1581.  
  1582.              <para><synopsis>HEXA_16BIT_ADDRESS HEXA_LONG_ADDRESS TYPE LABELNAME</synopsis>
  1583.              where TYPE is: 00 = regular label, 01 = EQU or struct defined, 02 = DEFL defined.</para>
  1584.  
  1585.              <para>If no filename is provided, default is created by appending ".map" to source name.</para>
  1586.            </listitem>
  1587.          </varlistentry>
  1588.  
  1589.          <varlistentry>
  1590.            <term><anchor id="po_d24" />D24</term>
  1591.  
  1592.            <listitem>
  1593.              <para>Defines three bytes by 24b constant. Values should be between
  1594.              -16777217 and 16777216.<example>
  1595.                  <title></title>
  1596.  
  1597.                  <para><programlisting>    D24 0x123456   ; define three bytes 0x56, 0x34, 0x12</programlisting></para>
  1598.                </example></para>
  1599.            </listitem>
  1600.          </varlistentry>
  1601.  
  1602.          <varlistentry>
  1603.            <term><anchor id="po_db" />DB</term>
  1604.  
  1605.            <listitem>
  1606.              <para>Synonym of <link linkend="po_byte">BYTE</link>.</para>
  1607.            </listitem>
  1608.          </varlistentry>
  1609.  
  1610.          <varlistentry>
  1611.            <term><anchor id="po_dc" />DC</term>
  1612.  
  1613.            <listitem>
  1614.              <para>Same as <link linkend="po_byte">BYTE</link>, but every
  1615.              last character of a string will have bit 7 set.<example>
  1616.                  <title></title>
  1617.  
  1618.                  <para><programlisting>    DC "kip" ; same as BYTE "ki",'p'|128</programlisting></para>
  1619.                </example></para>
  1620.            </listitem>
  1621.          </varlistentry>
  1622.  
  1623.          <varlistentry>
  1624.            <term><anchor id="po_dd" />DD</term>
  1625.  
  1626.            <listitem>
  1627.              <para>Synonym of <link linkend="po_dword">DWORD</link>.</para>
  1628.            </listitem>
  1629.          </varlistentry>
  1630.  
  1631.          <varlistentry>
  1632.            <term><anchor id="po_defarray" />DEFARRAY &lt;id&gt; &lt;replacements&gt;</term>
  1633.  
  1634.            <listitem>
  1635.                                 <para>Array of DEFINEs. Use <code>id[#]</code> to retrieve current size of array.<example>
  1636.                  <title>docs_examples/po_defarray.asm</title>
  1637.  
  1638.                  <para><programlisting>    DEFARRAY myarray 10*20,"A",20,&lt;/D,40&gt;,50,70
  1639. CNT DEFL 0 ;or CNT=0
  1640.    DUP myarray[#]      ; 6
  1641.    DISPLAY myarray[CNT]
  1642. CNT DEFL CNT+1 ;or CNT=CNT+1
  1643.    EDUP</programlisting></para>
  1644.                </example></para>
  1645.            </listitem>
  1646.          </varlistentry>
  1647.  
  1648.          <varlistentry>
  1649.            <term><anchor id="po_defarray_plus" />DEFARRAY+ &lt;id&gt; &lt;additional replacements&gt;</term>
  1650.  
  1651.            <listitem>
  1652.              <para>Appending more DEFINEs to already defined array<example>
  1653.                  <title></title>
  1654.  
  1655.                  <para><programlisting>    DEFARRAY   myarray 'A', 'B', 'C'
  1656.    DEFARRAY+  myarray 'D', 'E'            ; now "myarray" has 5 items
  1657.    DUP 3 : DEFARRAY+ myarray '!' : EDUP   ; "DEFARRAYFILL" adding 3x '!'</programlisting></para>
  1658.                </example></para>
  1659.            </listitem>
  1660.          </varlistentry>
  1661.  
  1662.          <varlistentry>
  1663.            <term><anchor id="po_defb" />DEFB</term>
  1664.  
  1665.            <listitem>
  1666.              <para>Synonym of <link linkend="po_byte">BYTE</link>.</para>
  1667.            </listitem>
  1668.          </varlistentry>
  1669.  
  1670.          <varlistentry>
  1671.            <term><anchor id="po_defd" />DEFD</term>
  1672.  
  1673.            <listitem>
  1674.              <para>Synonym of <link linkend="po_dword">DWORD</link>.</para>
  1675.            </listitem>
  1676.          </varlistentry>
  1677.  
  1678.          <varlistentry>
  1679.            <term><anchor id="po_defdevice" />DEFDEVICE
  1680.            &lt;deviceid&gt;</term>
  1681.  
  1682.            <listitem>
  1683.              <para>Sorry, not available yet. If you want to see new device in
  1684.              SjASMPlus, please, <link linkend="feedback">write
  1685.              us</link>.</para>
  1686.            </listitem>
  1687.          </varlistentry>
  1688.  
  1689.          <varlistentry>
  1690.            <term><anchor id="po_defg" />DEFG</term>
  1691.  
  1692.            <listitem>
  1693.              <para>Synonym of <link linkend="po_dg">DG</link>.</para>
  1694.            </listitem>
  1695.          </varlistentry>
  1696.  
  1697.          <varlistentry>
  1698.            <term><anchor id="po_defh" />DEFH</term>
  1699.  
  1700.            <listitem>
  1701.              <para>Synonym of <link linkend="po_dh">DH</link>.</para>
  1702.            </listitem>
  1703.          </varlistentry>
  1704.  
  1705.          <varlistentry>
  1706.            <term><anchor id="po_define" />DEFINE &lt;id&gt;
  1707.            &lt;replacement&gt;</term>
  1708.  
  1709.            <listitem>
  1710.              <para>The identifier &lt;id&gt; will be replaced with the
  1711.              &lt;replacement&gt;. The replacement could be omitted, in such
  1712.              case it is still possible to check if the identifier was defined
  1713.              with IFDEF or IFNDEF.<example>
  1714.                  <title></title>
  1715.  
  1716.                  <para><programlisting>    DEFINE str_honderd "Honderd"
  1717.    BYTE str_honderd,0             ; BYTE "Honderd",0</programlisting></para>
  1718.                </example></para>
  1719.            </listitem>
  1720.          </varlistentry>
  1721.  
  1722.          <varlistentry>
  1723.            <term><anchor id="po_defl" />&lt;label&gt; DEFL &lt;expression&gt;</term>
  1724.  
  1725.            <listitem>
  1726.              <para>Assigns value of &lt;expression&gt; to symbol &lt;label&gt;. New label defined
  1727.                                   by DEFL is marked internally as "modifiable", allowing to re-assign new values to it with
  1728.                                   further DEFL statements (you can use also <code>=</code> instead of <code>DEFL</code>).
  1729.                                   <example>
  1730.                  <title></title>
  1731.  
  1732.                  <para><programlisting>counter DEFL 0
  1733.    DUP 4
  1734.        DB 0xAA, counter
  1735. counter = counter + 1
  1736.    EDUP
  1737. ; machine code produced: AA 00 AA 01 AA 02 AA 03</programlisting></para>
  1738.                </example></para>
  1739.            </listitem>
  1740.          </varlistentry>
  1741.  
  1742.          <varlistentry>
  1743.            <term><anchor id="po_defm" />DEFM</term>
  1744.  
  1745.            <listitem>
  1746.              <para>Synonym of <link linkend="po_byte">BYTE</link>.</para>
  1747.            </listitem>
  1748.          </varlistentry>
  1749.  
  1750.          <varlistentry>
  1751.            <term><anchor id="po_defs" />DEFS</term>
  1752.  
  1753.            <listitem>
  1754.              <para>Synonym of <link linkend="po_block">BLOCK</link>.</para>
  1755.            </listitem>
  1756.          </varlistentry>
  1757.  
  1758.          <varlistentry>
  1759.            <term><anchor id="po_defw" />DEFW</term>
  1760.  
  1761.            <listitem>
  1762.              <para>Synonym of <link linkend="po_word">WORD</link>.</para>
  1763.            </listitem>
  1764.          </varlistentry>
  1765.  
  1766.          <varlistentry>
  1767.            <term><anchor id="po_dephase" />DEPHASE</term>
  1768.  
  1769.            <listitem>
  1770.              <para>Synonym of <link linkend="po_ent">ENT</link>.</para>
  1771.            </listitem>
  1772.          </varlistentry>
  1773.  
  1774.          <varlistentry>
  1775.            <term><anchor id="po_device" />DEVICE &lt;deviceid&gt;[, &lt;RAMTOP&gt;]</term>
  1776.  
  1777.            <listitem>
  1778.              <para>Enables <link linkend="s_realdevice">real device emulation
  1779.              mode</link> by it identifier. If there is only single DEVICE directive
  1780.              in whole source batch, it becomes "global" and the device affects all
  1781.              lines of source, otherwise the DEVICE is applied for lines following it.</para>
  1782.  
  1783.              <para>For ZXSPECTRUM-like devices (except ZX Next) you can provide RAMTOP value,
  1784.                                   which will init the device memory in similar way as "<code>CLEAR &lt;RAMTOP&gt;</code>"
  1785.                                   in BASIC would do, putting top of the fake-stack at the RAMTOP address. The
  1786.                                   default RAMTOP is since v1.15.0 0x5D5B (it was 0xFF57 before).</para>
  1787.  
  1788.              <para>Predefined devices' identifiers list:</para>
  1789.  
  1790.               <synopsis> NONE ; off real device emulation mode
  1791.  ZXSPECTRUM48  ; ZX-Spectrum 48 (4 slots, 4 pages, slot/page size 0x4000, default map: 0, 1, 2, 3)
  1792.  ZXSPECTRUM128 ; ZX-Spectrum 128 (like 48 with 8 pages, default map: 7, 5, 2, 0)
  1793.  ZXSPECTRUM256 ; e.g. Scorpion 256 (exUSSR clone of ZX-Spectrum 128)
  1794.  ZXSPECTRUM512 ; e.g. ATM-Turbo 512 (another clone)
  1795.  ZXSPECTRUM1024
  1796.  ZXSPECTRUM2048
  1797.  ZXSPECTRUM4096
  1798.  ZXSPECTRUM8192
  1799.  ZXSPECTRUMNEXT ; ZX Spectrum Next (8 slots, 224 pages, slot size 0x2000 = 1.75MiB RAM)
  1800.                 ; (default pages map: 14, 15, 10, 11, 4, 5, 0, 1) (default slot: 7 (0xE000..0xFFFF))
  1801.  
  1802.  ;disable:
  1803.    DEVICE NONE
  1804.  ;enable:
  1805.    DEVICE ZXSPECTRUM128</synopsis>
  1806.             </listitem>
  1807.           </varlistentry>
  1808.  
  1809.           <varlistentry>
  1810.             <term><anchor id="po_dg" />DG &lt;data encoded in bits&gt;</term>
  1811.  
  1812.             <listitem>
  1813.               <para>Data comprises of characters in multiples of eight, each block
  1814.               is converted to a byte value.</para>
  1815.  
  1816.               <para>A hyphen '-' (also '.' and '_') represents 0 and any other non-whitespace character
  1817.               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>
  1818.                   <title></title>
  1819.                   <para><programlisting>    DG 1-1----1  ; store 161 at the current location
  1820.     DG ...# #... .##. .... ; store two bytes: 0x18, 0x60</programlisting></para>
  1821.               </example></para>
  1822.             </listitem>
  1823.           </varlistentry>
  1824.  
  1825.           <varlistentry>
  1826.             <term><anchor id="po_dh" />DH "&lt;data&gt;"[,"&lt;data2&gt;"...]</term>
  1827.  
  1828.             <listitem>
  1829.               <para>The data string comprises pairs of hexadecimal digits, each pair is converted to
  1830.               a byte value. You can add spaces between pairs as you like. (since v1.11)<example>
  1831.                   <title></title>
  1832.                   <para><programlisting>    DH "0123456789ABCDEF"   ; eight bytes #01 #23 ...
  1833.     DH "01 23  45 67"       ; four bytes #01 #23 #45 #67</programlisting></para>
  1834.               </example></para>
  1835.             </listitem>
  1836.           </varlistentry>
  1837.  
  1838.           <varlistentry>
  1839.             <term><anchor id="po_disp" />DISP &lt;address&gt;[,&lt;page_number&gt;]</term>
  1840.  
  1841.             <listitem>
  1842.               <para>Set the address in which the part of code should work.
  1843.               <link linkend="po_phase">PHASE</link> and <link
  1844.               linkend="po_textarea">TEXTAREA</link> are synonyms of DISP.
  1845.               <link linkend="po_ent">ENT</link> will restore current address.
  1846.               <link linkend="po_unphase">UNPHASE</link>, <link
  1847.               linkend="po_dephase">DEPHASE</link> and <link
  1848.               linkend="po_endt">ENDT</link> are synonyms of <link
  1849.               linkend="po_ent">ENT</link>. DISP blocks can NOT be nested, and to change
  1850.               the displacement address within current DISP block use the ordinary ORG.
  1851.               When in device mode, you can specify fixed value for "fake" page of emitted
  1852.               instructions and regular labels, but to avoid warning, you must also map-in
  1853.               the target page into the target memory slot (<link linkend="po_mmu">MMU</link>).
  1854.               When no fixed page in DISP is specified, the current mapping of memory pages is used.
  1855.               <example>
  1856.                   <title>docs_examples/po_disp.asm</title>
  1857.  
  1858.                   <para><programlisting>    DEVICE ZXSPECTRUM48
  1859. SCREEN  EQU $4000
  1860.         ORG $8000
  1861.         LD HL,BEGIN
  1862.         LD DE,SCREEN
  1863.         LD BC,ENDOFPROG-BEGIN
  1864.         LDIR
  1865.         JP SCREEN
  1866. BEGIN   DISP SCREEN ;code will compile for address $4000, but to the current ORG
  1867. MARKA       DEC A
  1868.             HALT
  1869.             JP NZ,MARKA
  1870.             DI
  1871.             HALT
  1872.         ENT
  1873. ENDOFPROG
  1874.  
  1875.     ASSERT $800E == BEGIN &amp;&amp; $8015 == ENDOFPROG &amp;&amp; $4000 == MARKA
  1876.     ASSERT $76 == {B $800F}     ; HALT instruction lands at $800F (BEGIN+1)</programlisting></para>
  1877.                 </example></para>
  1878.             </listitem>
  1879.           </varlistentry>
  1880.  
  1881.           <varlistentry>
  1882.             <term><anchor id="po_display" />DISPLAY &lt;bytes&gt;</term>
  1883.  
  1884.             <listitem>
  1885.               <para><emphasis>This pseudo-op comes from ZX-Spectrum assembler
  1886.               ALASM.</emphasis></para>
  1887.  
  1888.               <para>Out to console a string of bytes. Each value should be
  1889.               between -129 and 256. Keys /D, /H and /A set format of output of
  1890.               numbers:<synopsis>/D - out only in Decimal
  1891. /H - out only in Hexadecimal
  1892. /A - out both in Hexadecimal and Decimal</synopsis>
  1893.               <example>
  1894.                   <title>docs_examples/po_display.asm</title>
  1895.  
  1896.                   <para><programlisting>    ORG 100h
  1897. TESTLABEL:
  1898.     ;...some code...
  1899.     RET
  1900.     DISPLAY "--the some program-- by me"
  1901.     DISPLAY "TESTLABEL address is:",/A,TESTLABEL
  1902. /*
  1903. will output to the console strings:
  1904. &gt; --the some program-- by me
  1905. &gt; TESTLABEL address is:0x100, 256
  1906. */</programlisting></para>
  1907.                 </example></para>
  1908.             </listitem>
  1909.           </varlistentry>
  1910.  
  1911.           <varlistentry>
  1912.             <term><anchor id="po_dm" />DM</term>
  1913.  
  1914.             <listitem>
  1915.               <para>Synonym of <link linkend="po_byte">BYTE</link>.</para>
  1916.             </listitem>
  1917.           </varlistentry>
  1918.  
  1919.           <varlistentry>
  1920.             <term><anchor id="po_ds" />DS</term>
  1921.  
  1922.             <listitem>
  1923.               <para>Synonym of <link linkend="po_block">BLOCK</link>.</para>
  1924.             </listitem>
  1925.           </varlistentry>
  1926.  
  1927.           <varlistentry>
  1928.             <term><anchor id="po_dup" />DUP &lt;count&gt;</term>
  1929.  
  1930.             <listitem>
  1931.               <para>DUP specifies the number of times to generate the
  1932.               following lines until an EDUP pseudo-op is encountered. DUP can be used in macro's.<example>
  1933.                  <title></title>
  1934.  
  1935.                  <para><programlisting>    DUP 3
  1936.    NOP
  1937.    EDUP
  1938.  
  1939. /*this will expand to:
  1940.    NOP
  1941.    NOP
  1942.    NOP
  1943. */</programlisting></para>
  1944.                </example></para>
  1945.            </listitem>
  1946.          </varlistentry>
  1947.  
  1948.          <varlistentry>
  1949.            <term><anchor id="po_dw" />DW</term>
  1950.  
  1951.            <listitem>
  1952.              <para>Synonym of <link linkend="po_word">WORD</link>.</para>
  1953.            </listitem>
  1954.          </varlistentry>
  1955.  
  1956.          <varlistentry>
  1957.            <term><anchor id="po_dword" />DWORD</term>
  1958.  
  1959.            <listitem>
  1960.              <para>Defines a so called doubleword. Values should be between
  1961.              -2147483649 and 4294967296.<example>
  1962.                  <title></title>
  1963.  
  1964.                  <para><programlisting>    DWORD 4000h,0d000h
  1965.    DWORD 4</programlisting></para>
  1966.                </example></para>
  1967.            </listitem>
  1968.          </varlistentry>
  1969.  
  1970.          <varlistentry>
  1971.            <term><anchor id="po_dz" />DZ</term>
  1972.  
  1973.            <listitem>
  1974.              <para>Same as <link linkend="po_byte">BYTE</link>, but an extra
  1975.              zero will be added at the end.<example>
  1976.                  <title></title>
  1977.  
  1978.                  <para><programlisting>    DZ 1      ; same as BYTE 1,0
  1979.    DZ "kip"  ; same as BYTE "kip",0</programlisting></para>
  1980.                </example></para>
  1981.            </listitem>
  1982.          </varlistentry>
  1983.  
  1984.          <varlistentry>
  1985.            <term><anchor id="po_emptytap" />EMPTYTAP &lt;filenameoftapefile&gt;</term>
  1986.  
  1987.            <listitem>
  1988.              <para><emphasis>Useful only for ZX-Spectrum
  1989.              users</emphasis></para>
  1990.  
  1991.              <para>Create the new or truncate existing standard tape file
  1992.              for emulators of ZX-Spectrum. See example of
  1993.              <link linkend="po_savetap">SAVETAP</link>.</para>
  1994.            </listitem>
  1995.          </varlistentry>
  1996.  
  1997.          <varlistentry>
  1998.            <term><anchor id="po_emptytrd" />EMPTYTRD &lt;filenameoftrdimage&gt;[,&lt;disclabel&gt;]</term>
  1999.  
  2000.            <listitem>
  2001.              <para><emphasis>Useful only for ZX-Spectrum users</emphasis></para>
  2002.  
  2003.              <para>Create the empty TRD image for emulators of ZX-Spectrum.
  2004.              See example of <link linkend="po_savetrd">SAVETRD</link>.</para>
  2005.            </listitem>
  2006.          </varlistentry>
  2007.  
  2008.          <varlistentry>
  2009.            <term><anchor id="po_encoding" />ENCODING &lt;encoding&gt;</term>
  2010.  
  2011.            <listitem>
  2012.              <para><emphasis>Useful only for non English
  2013.              users</emphasis></para>
  2014.  
  2015.              <para>Set the current encoding, i.e. if you set "DOS", SjASMPlus
  2016.              will automatically convert strings from ANSI to DOS-866.
  2017.              Encoding may be "DOS"(DOS-866) or "WIN"(ANSI/Win-1251). Default
  2018.              is "WIN". <example>
  2019.                  <title></title>
  2020.  
  2021.                  <para><programlisting>    ENCODING "WIN"
  2022.    DB "тексттекст" ;will be тексттекст
  2023.    ENCODING "DOS"
  2024.    DB "тексттекст" ;will be ⥪бв⥪бв</programlisting></para>
  2025.                </example></para>
  2026.            </listitem>
  2027.          </varlistentry>
  2028.  
  2029.          <varlistentry>
  2030.            <term><anchor id="po_end" />END [&lt;startaddress&gt;]</term>
  2031.  
  2032.            <listitem>
  2033.              <para>The assembler will stop at this point. The pseudo-op
  2034.              END does NOT work in the beginning of line (even with --dirbol).
  2035.              The optional argument is used by SAVESNA, SAVETAP and SAVENEX.</para>
  2036.            </listitem>
  2037.          </varlistentry>
  2038.  
  2039.          <varlistentry>
  2040.            <term><anchor id="po_endlua" />ENDLUA</term>
  2041.  
  2042.            <listitem>
  2043.              <para>See <link linkend="po_lua">LUA</link> for more
  2044.              information.</para>
  2045.            </listitem>
  2046.          </varlistentry>
  2047.  
  2048.          <varlistentry>
  2049.            <term><anchor id="po_endmod" />ENDMOD</term>
  2050.  
  2051.            <listitem>
  2052.              <para>Synonym of <link
  2053.              linkend="po_endmodule">ENDMODULE</link>.</para>
  2054.            </listitem>
  2055.          </varlistentry>
  2056.  
  2057.          <varlistentry>
  2058.            <term><anchor id="po_endmodule" />ENDMODULE</term>
  2059.  
  2060.            <listitem>
  2061.              <para>To indicate the end of a module (see <link
  2062.              linkend="po_module">MODULE</link>).</para>
  2063.            </listitem>
  2064.          </varlistentry>
  2065.  
  2066.          <varlistentry>
  2067.            <term><anchor id="po_endt" />ENDT</term>
  2068.  
  2069.            <listitem>
  2070.              <para>Synonym of <link linkend="po_ent">ENT</link>.</para>
  2071.            </listitem>
  2072.          </varlistentry>
  2073.  
  2074.          <varlistentry>
  2075.            <term><anchor id="po_ent" />ENT</term>
  2076.  
  2077.            <listitem>
  2078.              <para>Restore current address. See <link
  2079.              linkend="po_disp">DISP</link> for more information.</para>
  2080.            </listitem>
  2081.          </varlistentry>
  2082.  
  2083.          <varlistentry>
  2084.            <term><anchor id="po_equ" />&lt;label&gt; EQU &lt;expression&gt;</term>
  2085.  
  2086.            <listitem>
  2087.              <para>To give the label a value other than the current program
  2088.              counter. The label should not already exist (you can assign only one value to it).
  2089.                           For modifiable labels holding temporary values use <link linkend="po_defl">DEFL</link>.<example>
  2090.                  <title></title>
  2091.  
  2092.                  <para><programlisting>Label EQU 3
  2093. Kip   EQU 0x23*256 + low $</programlisting></para>
  2094.                </example></para>
  2095.            </listitem>
  2096.          </varlistentry>
  2097.  
  2098.          <varlistentry>
  2099.            <term><anchor id="po_export" />EXPORT &lt;label&gt;</term>
  2100.  
  2101.            <listitem>
  2102.              <para>The named label will be written to the export-file, in the
  2103.              form 'label: EQU value'. This way the export-file can be
  2104.              included in other sources.<example>
  2105.                  <title></title>
  2106.  
  2107.                  <para><programlisting>DRIE=3
  2108.    EXPORT DRIE  ; adds into export file line: "DRIE: EQU 0x00000003"</programlisting></para>
  2109.                </example></para>
  2110.            </listitem>
  2111.          </varlistentry>
  2112.  
  2113.          <varlistentry>
  2114.            <term><anchor id="po_fpos" />FPOS &lt;position&gt;</term>
  2115.  
  2116.            <listitem>
  2117.              <para>The FPOS directive makes it possible to set the file
  2118.              position to anywhere in the output file. Position value without sign
  2119.              is used as absolute one to be set, position starting with + or - sign will be
  2120.              used as relative position.</para>
  2121.  
  2122.              <para>In combination with <link
  2123.              linkend="po_output">OUTPUT</link> &lt;filename&gt;,r it is
  2124.              possible to update existing files.</para>
  2125.  
  2126.              <para><example>
  2127.                  <title></title>
  2128.  
  2129.                  <para><programlisting>; This example will result in a file with a length of one byte:
  2130.    BYTE 0
  2131.    FPOS 0
  2132.    BYTE 1
  2133.    END</programlisting></para>
  2134.                </example></para>
  2135.            </listitem>
  2136.          </varlistentry>
  2137.  
  2138.          <varlistentry>
  2139.            <term><anchor id="po_hex" />HEX</term>
  2140.  
  2141.            <listitem>
  2142.              <para>Synonym of <link linkend="po_dh">DH</link>, usually used without quotes around data.</para>
  2143.            </listitem>
  2144.          </varlistentry>
  2145.  
  2146.          <varlistentry>
  2147.            <term><anchor id="po_incbin" />INCBIN
  2148.            &lt;filename&gt;[,&lt;offset&gt;[,&lt;length&gt;]]</term>
  2149.  
  2150.            <listitem>
  2151.              <para>To include a binary file into the outputfile. The offset
  2152.              and length are optional. Added in v1.12.1: if negative offset or length is provided,
  2153.              it counts relatively from the end of the file.<example>
  2154.                  <title></title>
  2155.  
  2156.                  <para><programlisting>    INCBIN "gfx.scc",7        ; include gfx.scc, skip first 7 bytes
  2157.    INCBIN "rantab.com",3,256 ; include 256 bytes from offset 3
  2158.    INCBIN gfx.scc ,,7        ; 7 bytes from offset 0 (unquoted filename must end with space)
  2159.    INCBIN "48.rom",-768,-256 ; include (from 16kiB file) 512 bytes 15616..16127</programlisting></para>
  2160.                </example></para>
  2161.            </listitem>
  2162.          </varlistentry>
  2163.  
  2164.          <varlistentry>
  2165.            <term><anchor id="po_inchob" />INCHOB &lt;filename&gt;[,&lt;offset&gt;[,&lt;length&gt;]]</term>
  2166.  
  2167.            <listitem>
  2168.              <para>To include a data from a hobeta file into the outputfile.
  2169.              The offset and length are optional.<example>
  2170.                  <title></title>
  2171.  
  2172.                  <para><programlisting>    INCHOB "gfx.$c",7        ; include gfx.scc, skip first 7 bytes
  2173.    INCHOB "sprs.$c",3,256   ; include 256 bytes from offset 3
  2174.    INCHOB gfx.$c ,7        ; note the space between the filename and the ',7' here :)</programlisting></para>
  2175.                </example></para>
  2176.            </listitem>
  2177.          </varlistentry>
  2178.  
  2179.          <varlistentry>
  2180.            <term><anchor id="po_include" />INCLUDE &lt;filename&gt;</term>
  2181.  
  2182.            <listitem>
  2183.              <para>To include another sourcefile into the current.
  2184.              Sourcefiles can be nested 20 levels deep. If the file cannot be
  2185.              found in the current directory (the current directory is the
  2186.              directory the current asm file comes from!) the file will be searched
  2187.              for in the directories specified at the commandline. When angle
  2188.              brackets are used, the commandline directories are searched
  2189.              before the current directory.</para>
  2190.              <para>The directory used to launch the assembling process is automatically added
  2191.              to the list (as if "<code>-i.</code>" was added to command line manually)
  2192.              (v1.14.0 and v1.14.1 don't add it, reverted back for v1.14.2). If you want to start
  2193.               with completely empty include-path list, use "<code>--inc</code>" option
  2194.               early (order matters) without the "=" to empty the current list, like:
  2195.               <code>sjasmplus --inc --inc=path1 --inc=path2 file.asm</code>
  2196.               <example>
  2197.                   <title></title>
  2198.  
  2199.                   <para><programlisting>    INCLUDE &lt;VDP.I&gt;     ; search for file "VDP.I" in the include directories, then in current
  2200.     INCLUDE MORE.I      ; search for "MORE.I" in current directory, then in include directories
  2201.     INCLUDE "MORE.I"</programlisting></para>
  2202.                 </example></para>
  2203.             </listitem>
  2204.           </varlistentry>
  2205.  
  2206.           <varlistentry>
  2207.             <term><anchor id="po_includelua" />INCLUDELUA &lt;filename&gt;</term>
  2208.  
  2209.             <listitem>
  2210.               <para>To include another LUA script in first pass(!). If the
  2211.               file cannot be found in the current directory (the current
  2212.               directory is the directory the current file comes from) the file
  2213.               will be searched for in the directories specified at the
  2214.               commandline. When angle brackets are used, the commandline
  2215.               directories are searched before the current directory.<example>
  2216.                   <title></title>
  2217.  
  2218.                   <para><programlisting>    INCLUDELUA &lt;mylibrary1.lua&gt;
  2219.     INCLUDELUA mylibrary2.lua
  2220.     INCLUDELUA "library_for_zx.lua"</programlisting></para>
  2221.                 </example></para>
  2222.             </listitem>
  2223.           </varlistentry>
  2224.  
  2225.           <varlistentry>
  2226.             <term><anchor id="po_inctrd" />INCTRD
  2227.             &lt;filenameoftrdimage&gt;,&lt;filenameintrdimage&gt;[,&lt;offset&gt;[,&lt;length&gt;]]</term>
  2228.  
  2229.             <listitem>
  2230.               <para>To include a file from a TRD image into the outputfile.
  2231.               The offset and length are optional.<example>
  2232.                   <title></title>
  2233.  
  2234.                   <para><programlisting>    INCTRD "test.trd","mygfx.C" ; include mygfx.C from test.trd
  2235.     INCTRD "test.trd","mygfx.C",12 ; include mygfx.C from test.trd, skip first 12 bytes</programlisting></para>
  2236.                 </example></para>
  2237.             </listitem>
  2238.           </varlistentry>
  2239.  
  2240.           <varlistentry>
  2241.             <term><anchor id="po_insert" />INSERT &lt;filename&gt;[,&lt;offset&gt;[,&lt;length&gt;]]</term>
  2242.  
  2243.             <listitem>
  2244.               <para>INSERT is a synonym of <link
  2245.               linkend="po_incbin">INCBIN</link>. See above.</para>
  2246.             </listitem>
  2247.           </varlistentry>
  2248.  
  2249.           <varlistentry>
  2250.             <term><anchor id="po_labelslist" />LABELSLIST &lt;filename&gt;</term>
  2251.  
  2252.             <listitem>
  2253.               <para><emphasis>Useful only for ZX-Spectrum Emulator
  2254.               UNREALSPECCY.</emphasis></para>
  2255.  
  2256.               <para><emphasis>Work only in real device emulation mode. See
  2257.               <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2258.  
  2259.               <para>Save labels list in format:</para>
  2260.  
  2261.               <para><synopsis>NN:ADDRESS LABELNAME</synopsis>
  2262.               where NN is number of RAM page and ADDRESS is truncated to 0000..3FFF range</para>
  2263.  
  2264.               <para><example>
  2265.                   <title></title>
  2266.  
  2267.                   <para><programlisting>    LABELSLIST "x:/somepath/user.l"</programlisting></para>
  2268.                 </example></para>
  2269.             </listitem>
  2270.           </varlistentry>
  2271.  
  2272.           <varlistentry>
  2273.             <term><anchor id="po_lua" />LUA [pass] [; ok comment to suppress "emit with allpass" warning]</term>
  2274.  
  2275.             <listitem>
  2276.               <para>Using pseudo-ops LUA and ENDLUA you can insert Lua
  2277.               scripts. See more in the chapter "<link
  2278.              linkend="c_lua_scripting">Lua scripting</link>".</para>
  2279.  
  2280.               <para>Parameter is optional. It may be:<synopsis>PASS1   -  interpret Lua script in first pass only.
  2281. PASS2   -  interpret Lua script in second pass only.
  2282. PASS3   -  interpret Lua script in third pass only. By default.
  2283. ALLPASS -  interpret Lua script in all passes. It is need, if you generate some Z80 code.</synopsis></para>
  2284.  
  2285.               <para><example>
  2286.                   <title></title>
  2287.  
  2288.                   <para><programlisting>    LUA
  2289. -- some comments
  2290.         print "Hi, man! This is Lua!"
  2291.     ENDLUA
  2292. ; some code now:
  2293.     LUA ALLPASS
  2294.         _pl("LABEL LD A,10")
  2295.         _pc("RET")
  2296.     ENDLUA</programlisting></para>
  2297.                 </example></para>
  2298.             </listitem>
  2299.           </varlistentry>
  2300.  
  2301.           <varlistentry>
  2302.             <term><anchor id="po_memorymap" />MEMORYMAP</term>
  2303.  
  2304.             <listitem>
  2305.               <para>Not available yet.</para>
  2306.             </listitem>
  2307.           </varlistentry>
  2308.  
  2309.           <varlistentry>
  2310.             <term><anchor id="po_mmu" />MMU &lt;first slot number&gt; [&lt;last slot number&gt;|&lt;single slot option&gt;], &lt;page number&gt;[,&lt;address&gt;]</term>
  2311.  
  2312.             <listitem>
  2313.               <para>Maps memory page(s) to slot(s), similar to SLOT + PAGE combination, but allows
  2314.               to set up whole range of consecutive slots (with consecutive memory pages). Or when
  2315.               only single slot is specified, extra option can be used to extend particular slot
  2316.               functionality. The slot behaviour will stay set in the current DEVICE until reset
  2317.               by another MMU specifying same slot (even as part of range, that will clear the option
  2318.               to "default").</para>
  2319.  
  2320.                   <para>The optional third argument is address for <link linkend="po_org">ORG</link>
  2321.                           functionality.</para>
  2322.  
  2323.               <para>Single slot option (default state is: no error/warning and no wrap = nothing special):
  2324.                 <synopsis>e = error on writing beyond last byte of slot
  2325. w = warning on writing beyond last byte of slot
  2326. n = wrap address back to start of slot, map next page</synopsis>
  2327.                 <example>
  2328.                   <title>docs_examples/po_mmu.asm</title>
  2329.  
  2330.                   <para><programlisting>    DEVICE ZXSPECTRUM128 : LABELSLIST "po_mmu.lbl"  ; to check label pages
  2331.     MMU 1 3, 5      ; maps slots 1, 2, 3 with pages 5, 6, 7
  2332.     ORG 0xBFFF
  2333. label1_p6: scf      ; last byte of page 6 (in slot 2)
  2334. label2_p7: scf      ; first byte of page 7 (in slot 3)
  2335.  
  2336.     MMU 3 e, 0      ; page 0 into slot 3, write beyond slot will cause error
  2337.     ORG 0xFFFF
  2338.     ld  a,1         ; error: Write outside of memory slot: 65536 (65536 = address outside)
  2339.  
  2340.     MMU 3 n, 1      ; page 1 into slot 3, make it wrap + map next page automatically
  2341.     ORG 0xFFFF      ; ! also the $ address was truncated by MMU from $10001 to $0001 !
  2342. label3_p1: scf      ; last byte of page 1, then wrapping back to 0xC000 with page 2
  2343. label4_p2: scf      ; first byte of page 2 at 0xC000</programlisting></para>
  2344.                 </example></para>
  2345.             </listitem>
  2346.           </varlistentry>
  2347.  
  2348.           <varlistentry>
  2349.             <term><anchor id="po_module" />MODULE &lt;name&gt;</term>
  2350.  
  2351.             <listitem>
  2352.               <para>
  2353.                                   Labels has to be unique only whithin the current module (module is added as prefix to them).
  2354.                                   Also note the use of '@' operator to suppress all this label-processing. Modules can
  2355.                                   be nested, and module has to be ended by <link linkend="po_endmodule">ENDMODULE</link>.
  2356.                           <example>
  2357.                   <title>docs_examples/po_module.asm</title>
  2358.  
  2359.                   <programlisting>    MODULE xxx
  2360. Kip:                ; label xxx.Kip
  2361.     ld  hl,@Kip     ; global Kip
  2362.     ld  hl,@Kop     ; global Kop
  2363.     ld  hl,Kop      ; xxx.Kop
  2364. Kop:                ; label xxx.Kop
  2365.     ld  hl,Kip      ; xxx.Kip
  2366.     ld  hl,yyy.Kip  ; yyy.Kip
  2367.     ld  hl,nested.Kip   ; xxx.nested.Kip
  2368.         MODULE nested
  2369. Kip:        ret     ; label xxx.nested.Kip
  2370.         ENDMODULE
  2371.     ENDMODULE
  2372.  
  2373.     MODULE yyy
  2374. Kip:    ret         ; label yyy.Kip
  2375. @Kop:   ret         ; label Kop (global one, no module prefix)
  2376. @xxx.Kop: nop       ; ERROR: duplicate: label xxx.Kop
  2377.     ENDMODULE
  2378.  
  2379. Kip     ret         ; global label Kip</programlisting>
  2380.                 </example>
  2381.                                 Since v1.14.0 the module <code>&lt;name&gt;</code> can NOT contain dot character. You can
  2382.                                 use nested modules to get identical identifier as in older versions, or please rename with
  2383.                                 underscores/etc:
  2384.                                 <programlisting>    ; invalid since v1.14.0
  2385.         MODULE older.version
  2386. fn1:        ret        ; final label: @older.version.fn1
  2387.         ENDMODULE
  2388.     ; can be replaced in v1.14.0 with
  2389.         MODULE new
  2390.             MODULE version
  2391. fn1:            ret    ; final label: @new.version.fn1
  2392.             ENDMODULE
  2393.         ENDMODULE</programlisting>
  2394.         Since v1.14.0 the <code>MODULE</code> and <code>ENDMODULE</code> also resets the current "non-local"
  2395. label prefix back to "_":
  2396. <programlisting>Kep:    ; "Kep" label (global one), and also works as "non-local" prefix for local labels
  2397.     MODULE zzz
  2398. .local: ; in v1.14.0 this will be "zzz._.local" label, previously it was "zzz.Kep.local"
  2399. Kup:    ; this is "zzz.Kup", but also defines "non-local" prefix as "Kup"
  2400. .local  ; this is "zzz.Kup.local"
  2401.     ENDMODULE
  2402. .local: ; in v1.14.0 this will be "_.local" label, previously it was "Kup.local"</programlisting>
  2403.                                 </para>
  2404.             </listitem>
  2405.           </varlistentry>
  2406.  
  2407.           <varlistentry>
  2408.             <term><anchor id="po_opt" /><para>OPT [push] [reset] [listoff] [liston] [&lt;command line options&gt;]</para>
  2409.                         <para>OPT pop</para></term>
  2410.  
  2411.             <listitem>
  2412.               <para>Allows to reset and modify <link linkend="s_cli">options</link> affecting syntax and
  2413.                                   parsing (for lines of source following the OPT). The options allowed for OPT
  2414.                                   are: <code>--nofakes</code>, <code>--syntax</code>, <code>--zxnext</code>,
  2415.                                   <code>--reversepop</code> and <code>--dirbol</code>.
  2416.                           </para>
  2417.                           <para>
  2418.                                   Ahead of options you can use OPT commands: push, pop, reset, listoff, liston.
  2419.                                   The "push" command will make OPT to preserve current state of options. The "reset"
  2420.                                   command will reset OPT-related options to default state. The "listoff" command will
  2421.                                   suspend the listing for following lines until "liston" command is used (listing
  2422.                                   availability is part of the push/pop state, so to "nest" listing-off you can use
  2423.                                   "OPT push listoff : ... code ... : OPT pop" code sequence.
  2424.                           </para>
  2425.                           <para>Then the provided options are applied. The default values are: fake instructions
  2426.                                   enabled (no warning), multi-argument delimiter is ",", both () and [] brackets
  2427.                                   can be used to access memory, labels can have any name, ZX Next instructions are OFF,
  2428.                                   POP with multiple arguments doesn't reverse them and pseudo-ops at beginning of
  2429.                                   line are OFF (to just reset to these defaults you can use <code>OPT reset</code>).
  2430.              </para>
  2431.                           <para>The "pop" command: the previously preserved state of options is restored (states
  2432.                                   are preserved in "stack" way, so further OPT with "pop" will restore older states).
  2433.                           </para>
  2434.                           <example>
  2435.                  <title>docs_examples/po_opt.asm</title>
  2436.  
  2437.                  <programlisting>    POP bc, hl   ; pops BC first
  2438.    OPT push reset --reversepop --syntax=af
  2439.    POP bc,,hl   ; pops HL first
  2440.    LD  bc,hl    ; warning about Fake instruction
  2441.    LD  bc,hl    ; warning supressed by lowercase "fake" in this comment
  2442.    OPT reset --syntax=a
  2443.    POP bc,,hl   ; pop BC first (--reversepop was reset)
  2444.    OPT pop      ; restoring syntax to original state</programlisting>
  2445.                           </example>
  2446.            </listitem>
  2447.          </varlistentry>
  2448.  
  2449.          <varlistentry>
  2450.            <term><anchor id="po_org" />ORG &lt;address&gt;[,&lt;page_number&gt;]</term>
  2451.  
  2452.            <listitem>
  2453.              <para>Set the program counter to a specific address. If the second argument is
  2454.              provided, it will change memory page in the current slot, see
  2455.              <link linkend="po_page">PAGE</link> and <link linkend="po_slot">SLOT</link> (it will
  2456.              warn you when &lt;address&gt; is outside of it, you can suppress the warning with
  2457.              ";ok" comment).</para>
  2458.              <para>When used inside <link linkend="po_disp">DISP</link> block, only the virtual
  2459.                                   "displaced" program counter is affected, but the machine code will be still
  2460.                                   sequentially emitted in the original physical location and warning is emitted
  2461.                                   (you can suppress the warning with ";ok" comment, if you want to use ORG
  2462.                                   intentionally in this way).
  2463.                  <example>
  2464.                  <title>docs_examples/po_org.asm</title>
  2465.  
  2466.                  <para><programlisting>    ORG 100h ; or 0x100, or $100, or #100
  2467.  
  2468.    ; useful macro that padding code
  2469.    MACRO PADORG addr
  2470.         ; add padding
  2471.         IF $ &lt; addr
  2472.         BLOCK addr-$
  2473.         ENDIF
  2474.         ORG addr
  2475.    ENDM
  2476.  
  2477.    MACRO PADORG2 addr ; z80asm "FORG" replacement
  2478.         ; add padding + display warning
  2479.         IF $ &gt; addr
  2480.           ; no padding
  2481.           DISPLAY /L, "Warning! PADORG failed! ", $, " is more than ", addr
  2482.         ELSE
  2483.           ; add padding
  2484.           BLOCK addr-$
  2485.         ENDIF
  2486.         ORG addr
  2487.    ENDM</programlisting></para>
  2488.                </example></para>
  2489.            </listitem>
  2490.          </varlistentry>
  2491.  
  2492.          <varlistentry>
  2493.            <term><anchor id="po_outend" />OUTEND</term>
  2494.  
  2495.            <listitem>
  2496.              <para>Ends generating compiler output to file specified in OUTPUT and resets
  2497.              <link linkend="po_size">SIZE</link> value to default "none".</para>
  2498.            </listitem>
  2499.          </varlistentry>
  2500.  
  2501.          <varlistentry>
  2502.            <term><anchor id="po_output" />OUTPUT
  2503.            [&lt;filename&gt;[,&lt;mode&gt;]]</term>
  2504.  
  2505.            <listitem>
  2506.              <para>With OUTPUT it is possible to create multiple files from
  2507.              one source. All following instructions will be assembled to this
  2508.              file. It will also <link linkend="po_outend">close (OUTEND)</link>
  2509.              and finalize any previously opened output.</para>
  2510.  
  2511.              <para>There are three possible output modes: truncate (overwrite
  2512.              existing files, this is the default), rewind (open and execute
  2513.              FPOS 0) and append (open and leave the file pointer at the end
  2514.              of the file).<synopsis>OUTPUT &lt;filename&gt;,t  ; truncate (default)
  2515. OUTPUT &lt;filename&gt;,r  ; rewind
  2516. OUTPUT &lt;filename&gt;,a  ; append</synopsis>
  2517.              <example>
  2518.                  <title>bigfile.asm</title>
  2519.  
  2520.                  <para><programlisting>    OUTPUT loader.com
  2521.    ORG 100H
  2522.    INCLUDE loader.asm
  2523.    INCLUDE bios.asm
  2524.  
  2525.    OUTPUT bigfile.dat
  2526.    ORG 4000H
  2527.    INCLUDE main.asm
  2528.    ORG 8000H
  2529.    INCLUDE data.asm
  2530.    OUTEND
  2531.    INCLUDE next.asm</programlisting></para>
  2532.                </example>This will create two files: loader.com and
  2533.              bigfile.dat.</para>
  2534.  
  2535.            </listitem>
  2536.          </varlistentry>
  2537.  
  2538.          <varlistentry>
  2539.            <term><anchor id="po_page" />PAGE &lt;number&gt;</term>
  2540.  
  2541.            <listitem>
  2542.              <para><emphasis>Work only in real device emulation mode. See
  2543.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2544.  
  2545.              <para>Set the current memory page to current slot.</para>
  2546.  
  2547.              <para><example>
  2548.                  <title></title>
  2549.  
  2550.                  <para><programlisting>    PAGE 7 ;set 7 page
  2551.    SAVEBIN "ram7.bin",$C000,$4000 ;- save $4000 begin from $C000 of RAM to file</programlisting></para>
  2552.                </example></para>
  2553.            </listitem>
  2554.          </varlistentry>
  2555.  
  2556.          <varlistentry>
  2557.            <term><anchor id="po_phase" />PHASE</term>
  2558.  
  2559.            <listitem>
  2560.              <para>Synonym of <link linkend="po_disp">DISP</link>.</para>
  2561.            </listitem>
  2562.          </varlistentry>
  2563.  
  2564.          <varlistentry>
  2565.            <term><anchor id="po_rept" />REPT &lt;count&gt;</term>
  2566.  
  2567.            <listitem>
  2568.              <para>Synonym of <link linkend="po_dup">DUP</link>. There is also synonym ENDR to end REPT block (EDUP works too).</para>
  2569.            </listitem>
  2570.          </varlistentry>
  2571.  
  2572.          <varlistentry>
  2573.            <term><anchor id="po_savebin" />SAVEBIN
  2574.            &lt;filename&gt;,&lt;startadress&gt;,&lt;lengthofcode&gt;</term>
  2575.  
  2576.            <listitem>
  2577.              <para><emphasis>Works only in real device emulation mode. See
  2578.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2579.  
  2580.              <para>Save the block of RAM.</para>
  2581.  
  2582.              <para><example>
  2583.                  <title></title>
  2584.  
  2585.                  <para><programlisting>    PAGE 7 ;set 7 page to current slot
  2586.    SAVEBIN "ram7.bin",$C000,$4000 ;- save 4000h begin from C000h of RAM to file
  2587.    SAVEBIN "ram2.bin",$8000,$3000 ;- save 3000h begin from 8000h of RAM to file</programlisting></para>
  2588.                </example></para>
  2589.            </listitem>
  2590.          </varlistentry>
  2591.  
  2592.          <varlistentry>
  2593.            <term><anchor id="po_savedev" />SAVEDEV
  2594.            &lt;filename&gt;,&lt;startPage&gt;,&lt;startOffset&gt;,&lt;length&gt;</term>
  2595.  
  2596.            <listitem>
  2597.              <para><emphasis>Works only in real device emulation mode. See
  2598.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2599.  
  2600.              <para>Like <link linkend="po_savebin">SAVEBIN</link>, saves the block of device RAM.</para>
  2601.  
  2602.              <para>But it allows lengths over 64ki, and the offset value goes directly into device
  2603.              virtual memory (where pages are allocated consecutively), ignoring current slot
  2604.              "mapping". I.e. page=2,offset=0 will start saving data from page 2 at its beginning,
  2605.              going through pages 3, 4, 5, ... until the requested length of data is saved.</para>
  2606.  
  2607.              <para>The offset is not limited to page size, i.e. arguments page=1,offset=0x500 are equal
  2608.              to arguments page=0,offset=0x4500 for ZXSPECTRUM128 device (has page size 0x4000).</para>
  2609.  
  2610.              <example>
  2611.                  <title></title>
  2612.  
  2613.                  <programlisting>    DEVICE ZXSPECTRUM128 : SAVEDEV "fullram.bin",0,0,0x20000 ; save full 128kiB</programlisting>
  2614.                </example>
  2615.            </listitem>
  2616.          </varlistentry>
  2617.  
  2618.          <varlistentry>
  2619.            <term><anchor id="po_savehob" />SAVEHOB
  2620.            &lt;filename&gt;,&lt;filename_in_trdos&gt;,&lt;startadress&gt;,&lt;lengthofcode&gt;</term>
  2621.  
  2622.            <listitem>
  2623.              <para><emphasis>Work only in real device emulation mode. See
  2624.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2625.  
  2626.              <para>Save the block of RAM in Hobeta format.</para>
  2627.  
  2628.              <para><example>
  2629.                  <title></title>
  2630.  
  2631.                  <para><programlisting>    PAGE 7 ;set 7 page to current slot
  2632.    SAVEHOB "ram7.$c","myfile1.C",$C000,$4000 ;- save 4000h begin from C000h of RAM to file
  2633.    SAVEHOB "ram2.$c","myfile2.C",$8000,$3000 ;- save 3000h begin from 8000h of RAM to file</programlisting></para>
  2634.                </example></para>
  2635.            </listitem>
  2636.          </varlistentry>
  2637.  
  2638.          <varlistentry>
  2639.            <term><anchor id="po_savenex" />SAVENEX &lt;command&gt; &lt;command arguments&gt;</term>
  2640.  
  2641.            <listitem>
  2642.              <para>Commands to build NEX file, for details check <link linkend="c_savenex">SAVENEX
  2643.              </link> chapter.</para>
  2644.  
  2645.              <para><emphasis>Works only in ZXSPECTRUMNEXT device emulation mode. See
  2646.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2647.            </listitem>
  2648.          </varlistentry>
  2649.  
  2650.          <varlistentry>
  2651.            <term><anchor id="po_savesna" />SAVESNA &lt;filename&gt;[,&lt;startadressofprogram&gt;]</term>
  2652.  
  2653.            <listitem>
  2654.              <para><emphasis>Work only in real device emulation mode. See
  2655.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2656.  
  2657.              <para>Save the snapshot for emulators of ZX-Spectrum. (If start address is omitted,
  2658.              the one provided by <link linkend="po_end">END</link> is used)<example>
  2659.                  <title></title>
  2660.  
  2661.                  <para><programlisting>    DEVICE ZXSPECTRUM128
  2662.    ORG $8000
  2663. START  .... ;something code
  2664.    RET
  2665.    SAVESNA "game.sna",START ;save snapshot to file game.sna. Start address is START ($8000)</programlisting></para>
  2666.                </example></para>
  2667.            </listitem>
  2668.          </varlistentry>
  2669.  
  2670.          <varlistentry>
  2671.            <term><anchor id="po_savetap" /><para>SAVETAP &lt;filename&gt;,BASIC,&lt;fileintapeheader&gt;,&lt;start&gt;,&lt;length&gt;[,&lt;autorunline&gt;[,&lt;lengthwithoutvars&gt;]]</para>
  2672.            <para>SAVETAP &lt;filename&gt;,CODE,&lt;fileintapeheader&gt;,&lt;start&gt;,&lt;length&gt;[,&lt;customstartaddress&gt;[,&lt;optional3rdparam&gt;]]</para>
  2673.            <para>SAVETAP &lt;filename&gt;,NUMBERS,&lt;fileintapeheader&gt;,&lt;start&gt;,&lt;length&gt;[,&lt;variableletter(A..Z)&gt;]</para>
  2674.            <para>SAVETAP &lt;filename&gt;,CHARS,&lt;fileintapeheader&gt;,&lt;start&gt;,&lt;length&gt;[,&lt;variableletter(A..Z)&gt;]</para>
  2675.            <para>SAVETAP &lt;filename&gt;,HEADLESS,&lt;start&gt;,&lt;length&gt;[,&lt;customblockflag(0..255)&gt;]</para></term>
  2676.  
  2677.            <listitem>
  2678.              <para><emphasis>Work only in real device emulation mode. See
  2679.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2680.  
  2681.              <para>Append the tape header or block of data to the end of the
  2682.              standard tape file for emulators of ZX-Spectrum.<example>
  2683.                  <title></title>
  2684.  
  2685.                  <para><programlisting>    DEVICE ZXSPECTRUM48
  2686.    ...
  2687.    EMPTYTAP "output.tap"
  2688.  
  2689.    SAVETAP "output.tap",BASIC,"noAutorun",label,100
  2690.    SAVETAP "output.tap",BASIC,"w/Autorun",label,100,9999
  2691.    SAVETAP "output.tap",BASIC,"withVars",label,123,9999,100
  2692.    SAVETAP "output.tap",CODE,"bank17",screen,6912
  2693.    SAVETAP "output.tap",CODE,"screen",demo,length,org
  2694.    SAVETAP "output.tap",NUMBERS,"dimArray",label,100      ; a()
  2695.    SAVETAP "output.tap",NUMBERS,"othernum",label,200,'b'  ; b()
  2696.    SAVETAP "output.tap",CHARS,"charArray",label,300       ; a$()
  2697.    SAVETAP "output.tap",CHARS,"nextone",label,400,'m'     ; m$()
  2698.    SAVETAP "output.tap",HEADLESS,start,length</programlisting></para>
  2699.                </example></para>
  2700.            </listitem>
  2701.          </varlistentry>
  2702.  
  2703.          <varlistentry>
  2704.            <term>SAVETAP &lt;filename&gt;[,&lt;startadressofprogram&gt;]</term>
  2705.  
  2706.            <listitem>
  2707.              <para><emphasis>Work only in real device emulation mode. See
  2708.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2709.  
  2710.              <para>Save the tape file for emulators of ZX-Spectrum as a
  2711.              "snapshot" of almost-whole memory. Generated tape file supports the
  2712.              ZX-Spectrum clones with extended RAM such as ATM Turbo 512, etc.
  2713.              (If start address is omitted, the one provided by <link linkend=
  2714.              "po_end">END</link> is used)</para>
  2715.  
  2716.              <para>The stored memory starts at $5E00 (with screen data at $4000 auto-detected
  2717.                                   and optionally stored into the TAP file). The stored memory is automatically
  2718.                                   trimmed of zero values at start and end of the region (put non-zero byte markers
  2719.                                   around region you want to store, if you have zero-ed bytes at beginning or end
  2720.                                   of your code).
  2721.  
  2722.              <example>
  2723.                  <title></title>
  2724.  
  2725.                  <programlisting>    DEVICE ZXSPECTRUM48
  2726.    ORG $7FFF
  2727.    DB $01      ; non-zero marker to store the following zero-ed data
  2728. DAT DS 1024, 0  ; zero-ed data at $8000 (1024 bytes)
  2729. START  ....     ; some code
  2730.    RET
  2731.    SAVETAP "game.tap", START ; save tape-snapshot to file game.tap. Start address is $8400</programlisting>
  2732.                </example></para>
  2733.            </listitem>
  2734.          </varlistentry>
  2735.  
  2736.          <varlistentry>
  2737.            <term><anchor id="po_savetrd" />SAVETRD &lt;filename_of_trd_image&gt;,&lt;filename_in_trdos&gt;,&lt;address&gt;,&lt;length&gt;[,&lt;autostart_BASIC_line&gt;]</term>
  2738.          </varlistentry>
  2739.          <varlistentry>
  2740.            <term><anchor />SAVETRD &lt;filename_of_trd_image&gt;,|&lt;filename_in_trdos&gt;,&lt;address&gt;,&lt;length&gt;[,&lt;autostart_BASIC_line&gt;]</term>
  2741.          </varlistentry>
  2742.          <varlistentry>
  2743.            <term><anchor />SAVETRD &lt;filename_of_trd_image&gt;,&amp;&lt;filename_in_trdos&gt;,&lt;address&gt;,&lt;length&gt;</term>
  2744.  
  2745.            <listitem>
  2746.              <para><emphasis>Works only in real device emulation mode. See
  2747.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2748.  
  2749.                           <para>Save the device memory into TRD disk image. Saving two files with same filename will
  2750.                                   emit warning which can be suppressed by "; ok" comment, but two files (with same name)
  2751.                                   will be created in the disk directory.</para>
  2752.  
  2753.                           <para>Adding pipe character "|" ahead of file
  2754.                                   name will make sjasmplus to delete old file(s) with the same name before writing
  2755.                                   the new one =&gt; replace-like functionality. If the deleted file did occupy all
  2756.                                   sectors till the free space position in disc info, sjasmplus will salvage those sectors
  2757.                                   back and save new file over them (but it will not do full reshuffle/defrag in more
  2758.                                   complex cases, sjasmplus is just assembler, not full featured TRD images manipulation tool).</para>
  2759.  
  2760.                           <para>Adding ampersand character "&amp;" ahead of file name will make sjasmplus to look
  2761.                                   for existing file with the requested name (last of them, any earlier duplicates are deleted).
  2762.                                   The new content is appended to the file (sector aligned append) and the catalog entry gets
  2763.                                   only number of sectors patched, up to 255 sectors at most. This is special mode for
  2764.                                   single-file big-loaders.</para>
  2765.  
  2766.                           <para>The unofficial three-letter extensions are supported, use "; ok" comment to suppress
  2767.                                   warning about unofficial extension (official extensions are only: B, C, D and #).
  2768.  
  2769.                                 <example><title></title>
  2770.                  <para><programlisting>    EMPTYTRD "test.trd" ;create empty TRD image
  2771.    PAGE 7 ;set 7 page to current slot
  2772.    SAVETRD "test.trd","myfile1.C",$C000,$4000 ;- save 4000h begin from C000h of RAM to file to TRD image
  2773.    SAVETRD "test.trd","myfile2.C",$8000,$3000 ;- save 3000h begin from 8000h of RAM to file to TRD image
  2774.    SAVETRD "test.trd",|"myfile1.C",$B000,$400 ;- replace "myfile1.C" with new file
  2775.    SAVETRD "test.trd",&amp;"myfile1.C",$9000,$734 ;- sector-append new data to "myfile1.C"</programlisting></para>
  2776.                </example>
  2777.                           </para>
  2778.            </listitem>
  2779.          </varlistentry>
  2780.  
  2781.          <varlistentry>
  2782.            <term><anchor id="po_setbp" />SETBP [&lt;expression&gt;]</term>
  2783.          </varlistentry>
  2784.          <varlistentry>
  2785.            <term><anchor id="po_setbreakpoint" />SETBREAKPOINT [&lt;expression&gt;]</term>
  2786.  
  2787.            <listitem>
  2788.                                 <para>
  2789.                                         <emphasis>Works only in real device emulation mode. See
  2790.                                                 <link linkend="po_device">DEVICE</link>.</emphasis>
  2791.                                 </para>
  2792.                                 <para>Will add execution-type breakpoint at address &lt;expression&gt; to the
  2793.                                         <link linkend="po_bplist">BPLIST</link> export file. If no expression is specified,
  2794.                                         the current program counter will be used.
  2795.                                   <example>
  2796.                  <title></title>
  2797.  
  2798.                  <programlisting>    BPLIST "cmd_line.options.txt" zesarux ; open breakpoints list in "ZEsarUX" format
  2799. start:
  2800.        nop     ; ZEsarUX will not catch very first instruction of snapshot file loaded
  2801.        SETBP   ; so breakpoint ahead of the second instruction (after first "nop")
  2802.        xor  a
  2803.        SETBP some_routine_label  ; set also some breakpoint to other code by its label
  2804.        SETBREAKPOINT $0D6B       ; alias of SETBP, works identically
  2805.        ; ... your code of app
  2806.                                           </programlisting>
  2807.                                   </example>
  2808.                                 </para>
  2809.            </listitem>
  2810.          </varlistentry>
  2811.  
  2812.          <varlistentry>
  2813.            <term><anchor id="po_shellexec" />SHELLEXEC &lt;filename&gt;[,&lt;parameters&gt;]</term>
  2814.  
  2815.            <listitem>
  2816.              <para>Execute external program &lt;filename&gt; using optional
  2817.              command line &lt;parameters&gt;.<example>
  2818.                  <title></title>
  2819.  
  2820.                  <para><programlisting>    OUTPUT "mybin.bin"
  2821.    ;some code
  2822.    IF ((_ERRORS = 0) &amp;&amp; (_WARNINGS = 0))
  2823.        SHELLEXEC "x:/somepath/bin2tap.exe mybin.bin mytap.tap"
  2824.       ; or SHELLEXEC "x:/somepath/bin2tap.exe","mybin.bin mytap.tap"
  2825.    ENDIF</programlisting></para>
  2826.                </example></para>
  2827.            </listitem>
  2828.          </varlistentry>
  2829.  
  2830.          <varlistentry>
  2831.            <term><anchor id="po_size" />SIZE &lt;filesize in bytes&gt;</term>
  2832.  
  2833.            <listitem>
  2834.              <para>If the resulting file is less than the given length, as
  2835.              many zero bytes are added as necessary. See <link
  2836.              linkend="po_output">OUTPUT</link> for more.<example>
  2837.                  <title></title>
  2838.  
  2839.                  <para><programlisting>    SIZE 32768       ; make sure file will be 32K</programlisting></para>
  2840.                </example></para>
  2841.            </listitem>
  2842.          </varlistentry>
  2843.  
  2844.          <varlistentry>
  2845.            <term><anchor id="po_slot" />SLOT &lt;number&gt;</term>
  2846.  
  2847.            <listitem>
  2848.              <para><emphasis>Work only in real device emulation mode. See
  2849.              <link linkend="po_device">DEVICE</link>.</emphasis></para>
  2850.  
  2851.              <para>Set current slot. Slot's defined by MEMORYMAP pseudo-op.
  2852.               Use pseudo-op <link linkend="po_page">PAGE</link> to change page
  2853.               in the current slot.</para>
  2854.  
  2855.               <para><example>
  2856.                   <title></title>
  2857.  
  2858.                   <para><programlisting>    DEVICE ZXSPECTRUM128
  2859.     SLOT 3 ;from 0C000h to 0FFFFh
  2860.     PAGE 1 ;set page 1 to slot 3
  2861.     ORG 0C000h
  2862.     ;your program here
  2863.     PAGE 2
  2864.     INCBIN "somegfx.bin"
  2865.     ;....</programlisting></para>
  2866.                 </example></para>
  2867.             </listitem>
  2868.           </varlistentry>
  2869.  
  2870.           <varlistentry>
  2871.             <term><anchor id="po_tapend" />TAPEND</term>
  2872.  
  2873.             <listitem>
  2874.               <para>Ends generating compiler output to tape file block specified in TAPOUT.</para>
  2875.             </listitem>
  2876.           </varlistentry>
  2877.  
  2878.           <varlistentry>
  2879.             <term><anchor id="po_tapout" />TAPOUT &lt;filename&gt;[,&lt;flagbyte&gt;]</term>
  2880.  
  2881.             <listitem>
  2882.               <para>Appends one tape block at the end of specified file.
  2883.               All following code will be assembled to this tape file block.</para>
  2884.  
  2885.               <para>Default value of flagbyte is 255.<example>
  2886.                   <title>bigfile.asm</title>
  2887.  
  2888.                   <para><programlisting>    EMPTYTAP screen.tap
  2889.  
  2890.     TAPOUT screen.tap,0
  2891.     DB 3
  2892.     DB 'ScreenName'
  2893.     DW 6912
  2894.     DW 16384
  2895.     DW 32768
  2896.     TAPEND
  2897.  
  2898.     TAPOUT screen.tap
  2899.     INCBIN screen.bin
  2900.     TAPEND</programlisting></para>
  2901.                 </example>This will create tap file with the screen.</para>
  2902.             </listitem>
  2903.           </varlistentry>
  2904.  
  2905.  
  2906.           <varlistentry>
  2907.             <term><anchor id="po_textarea" />TEXTAREA &lt;address&gt;</term>
  2908.  
  2909.             <listitem>
  2910.               <para>Synonym of <link linkend="po_disp">DISP</link>.</para>
  2911.             </listitem>
  2912.           </varlistentry>
  2913.  
  2914.           <varlistentry>
  2915.             <term><anchor id="po_undefine" />UNDEFINE &lt;id&gt;</term>
  2916.  
  2917.             <listitem>
  2918.               <para>Removes the identifier defined by <link
  2919.               linkend="po_define">DEFINE</link></para>
  2920.  
  2921.               <para><example>
  2922.                   <title></title>
  2923.  
  2924.                   <para><programlisting>    DEFINE Release 1
  2925.  
  2926.     IFDEF Release
  2927.       DISPLAY "Building release version"
  2928.     ENDIF
  2929.  
  2930.     UNDEFINE Release
  2931.  
  2932.     IFNDEF Release
  2933.       DISPLAY "It's works!"
  2934.     ENDIF
  2935.  
  2936.     IFDEF _SJASMPLUS
  2937.       DISPLAY "Yes, it's the sjasmplus!"
  2938.     ENDIF
  2939.  
  2940.     UNDEFINE *  ; undefine all identifiers
  2941.  
  2942.     IFNDEF _SJASMPLUS
  2943.       DISPLAY "It's not the sjasmplus??"
  2944.     ENDIF</programlisting></para>
  2945.                 </example></para>
  2946.             </listitem>
  2947.           </varlistentry>
  2948.  
  2949.           <varlistentry>
  2950.             <term><anchor id="po_unphase" />UNPHASE</term>
  2951.  
  2952.             <listitem>
  2953.               <para>Synonym of <link linkend="po_ent">ENT</link>.</para>
  2954.             </listitem>
  2955.           </varlistentry>
  2956.  
  2957.           <varlistentry>
  2958.             <term><anchor id="po_word" />WORD &lt;words&gt;</term>
  2959.  
  2960.             <listitem>
  2961.               <para>Defines a word. Values should be between -32787 and
  2962.               65536.<example>
  2963.                   <title></title>
  2964.  
  2965.                   <para><programlisting>    WORD 4000h,0d000h
  2966.     WORD 4,"HA"</programlisting></para>
  2967.                 </example></para>
  2968.             </listitem>
  2969.           </varlistentry>
  2970.         </variablelist></para>
  2971.     </section>
  2972.  
  2973.     <section>
  2974.       <title><anchor id="s_conditional_assembly" />Conditional assembly</title>
  2975.  
  2976.       <para>It may be useful to assemble a part (or not) based on a certain
  2977.       condition.</para>
  2978.  
  2979.       <para><variablelist>
  2980.           <varlistentry>
  2981.             <term><anchor id="ca_if" />IF &lt;expression&gt;</term>
  2982.  
  2983.             <listitem>
  2984.               <para>If &lt;expression&gt; is non-zero the following lines are
  2985.               assembled until an ELSE or ENDIF.</para>
  2986.  
  2987.               <para>Forward reference of label will cause warning - as any machine code emitted inside
  2988.                                   the IF/IFN block with such expression can lead to unstable results. If you are sure
  2989.                                   the late definition of label will not affect resulting machine code (the IF block
  2990.                                   does not emit any machine code and does not define any label), you can suppress the
  2991.                                   warning with end-of-line comment "ok".</para>
  2992.  
  2993.                           <example>
  2994.                                   <title></title>
  2995.  
  2996.                                   <para><programlisting>    IF (aaa == 0) || (2 = aaa &amp;&amp; ((bbb % 13) &amp; 0x01))
  2997.         ; some code to assemble only if the symbol `aaa` is zero
  2998.         ; or (logical OR) when symbol `aaa` is two
  2999.         ; and (logical AND) modulo 13 of `bbb` is odd number
  3000.     ENDIF</programlisting>
  3001.                                   </para>
  3002.                           </example>
  3003.                   </listitem>
  3004.           </varlistentry>
  3005.  
  3006.           <varlistentry>
  3007.             <term><anchor id="ca_ifn" />IFN &lt;expression&gt;</term>
  3008.  
  3009.             <listitem>
  3010.               <para>If &lt;expression&gt; is zero the following lines are
  3011.               assembled until an ELSE or ENDIF.</para>
  3012.             </listitem>
  3013.           </varlistentry>
  3014.  
  3015.           <varlistentry>
  3016.             <term><anchor id="ca_ifdef" />IFDEF &lt;id&gt;</term>
  3017.  
  3018.             <listitem>
  3019.               <para>The condition is true if there is an id defined. These are
  3020.               NOT labels.</para>
  3021.  
  3022.               <para><example>
  3023.                   <title></title>
  3024.  
  3025.                   <para><programlisting>    IFDEF MSX_LEAN_AND_MEAN
  3026.         CALL InitOwnMM
  3027.     ELSE
  3028.         CALL InitDos2MemMan
  3029.     ENDIF</programlisting></para>
  3030.                 </example></para>
  3031.             </listitem>
  3032.           </varlistentry>
  3033.  
  3034.           <varlistentry>
  3035.             <term><anchor id="ca_ifndef" />IFNDEF &lt;id&gt;</term>
  3036.  
  3037.             <listitem>
  3038.               <para>The condition is true if there isn't an id defined. These
  3039.              are NOT labels.</para>
  3040.  
  3041.              <para><example>
  3042.                  <title></title>
  3043.  
  3044.                  <para><programlisting>1   IN A,(0C4H)
  3045.    AND 2
  3046.    IFNDEF DEBUG
  3047.        JR NC,1B
  3048.    ENDIF</programlisting></para>
  3049.                </example></para>
  3050.            </listitem>
  3051.          </varlistentry>
  3052.  
  3053.          <varlistentry>
  3054.            <term><anchor id="ca_ifused" />IFUSED &lt;label&gt;</term>
  3055.  
  3056.            <listitem>
  3057.              <para>The condition is true if there is an label used somewhere
  3058.              in the code. You can create libraries of useful functions using
  3059.              IFUSED pseudo-op</para>
  3060.  
  3061.              <para><example>
  3062.                  <title>(similar to tests/misc/ifused_test.asm)</title>
  3063.  
  3064.                  <para><programlisting>    OUTPUT "TEST.OUT"
  3065.  
  3066.    CALL LABEL3 ; LABEL3 - yes
  3067.    LD A,(LABEL1) ; LABEL1 - yes
  3068.  
  3069.    IFUSED LABEL1
  3070. LABEL1:
  3071.    DB 1
  3072.    ENDIF
  3073.  
  3074.    IFUSED LABEL2
  3075. LABEL2:
  3076.    DB 2
  3077.    ENDIF
  3078.  
  3079.    IFUSED LABEL3
  3080. LABEL3:
  3081.    DB 3
  3082.    ENDIF
  3083.  
  3084.    IFUSED LABEL4
  3085. LABEL4:
  3086.    DB 4
  3087.    ENDIF
  3088.  
  3089.    LD A,LABEL2 ; LABEL2 - yes
  3090.  
  3091.    RET
  3092.  
  3093. ; Output will contain bytes from LABEL1 to LABEL3 (1, 2, 3), but not contain from LABEL4, because this label is not used.
  3094.  
  3095. ; Alternative syntax:
  3096. LABEL5:
  3097.    IFUSED ; sjasmplus will use name of previous label, i.e. LABEL5
  3098.  
  3099.    ENDIF
  3100.    </programlisting></para>
  3101.                </example></para>
  3102.                 <para>Known bug: when code is using label inside module "moduleX",
  3103.                         like <code>call labelY</code>, only usage of <code>moduleX.labelY</code> label is noted.
  3104.                         Then if you define "labelY" outside of module and hide it inside <code>IFUSED labelY</code>
  3105.                         block, the call from module will be unable to find the routine.
  3106.                 </para>
  3107.                 <para>
  3108.                         Workaround: you can use the global-label operator @: "<code>call @labelY</code>" to
  3109.                         trigger usage of the global "labelY", or you can use the alternative IFUSED syntax
  3110.                         "<code>labelY: IFUSED</code>" which does not only check condition, but also does define the label.
  3111.                         Once the label is defined, the "call labelY" line inside module will find the global
  3112.                         variant and mark it as "used" correctly.
  3113.                 </para>
  3114.            </listitem>
  3115.          </varlistentry>
  3116.  
  3117.          <varlistentry>
  3118.            <term><anchor id="ca_ifnused" />IFNUSED &lt;label&gt;</term>
  3119.  
  3120.            <listitem>
  3121.              <para>The condition is true if there is an label
  3122.              <emphasis>not</emphasis> used somewhere in the code.</para>
  3123.            </listitem>
  3124.          </varlistentry>
  3125.  
  3126.          <varlistentry>
  3127.            <term><anchor id="ca_else" />ELSE</term>
  3128.  
  3129.            <listitem>
  3130.              <para>See <link linkend="ca_if">IF</link>. If the condition is
  3131.              not true, the else-part is assembled.</para>
  3132.            </listitem>
  3133.          </varlistentry>
  3134.  
  3135.          <varlistentry>
  3136.            <term><anchor id="ca_endif" />ENDIF</term>
  3137.  
  3138.            <listitem>
  3139.              <para>Every <link linkend="ca_if">IF</link> should be followed
  3140.              by an ENDIF.</para>
  3141.            </listitem>
  3142.          </varlistentry>
  3143.        </variablelist></para>
  3144.    </section>
  3145.  
  3146.    <section>
  3147.      <title><anchor id="s_macros"/>Macros</title>
  3148.  
  3149.      <para>The MACRO pseudo-op defines a macro. It should be followed by the
  3150.      name of the macro, optionally followed by the parameters. The following
  3151.      lines will be stored as the macro-body until an ENDM pseudo-op is
  3152.      encountered. Macro's have to be defined before their use.
  3153.           <example>
  3154.           <title>Macro without parameters (docs_examples/s_macros.asm)</title>
  3155.  
  3156.           <programlisting>  MACRO ADD_HL_A
  3157.     ADD A,L
  3158.     JR NC,.hup
  3159.     INC H
  3160. .hup
  3161.     LD L,A
  3162.   ENDM</programlisting>
  3163.         </example></para>
  3164.  
  3165.       <para>Labels in a macro starting with a dot are local to each macro
  3166.       expansion.<example>
  3167.           <title>A macro with parameters (docs_examples/s_macros.asm)</title>
  3168.  
  3169.           <programlisting>  MACRO WAVEOUT reg, data
  3170.     LD A,reg
  3171.     OUT (7EH),A
  3172.     LD A,data
  3173.     OUT (7FH),A
  3174.   ENDM
  3175. ; this macro will make
  3176.   WAVEOUT 2,17
  3177. ; expand to:
  3178.   LD A,2
  3179.   OUT (7EH),A
  3180.   LD A,17
  3181.   OUT (7FH),A</programlisting>
  3182.         </example>
  3183.                 <example>
  3184.           <title>Another example (docs_examples/s_macros.asm)</title>
  3185.  
  3186.           <programlisting>    MACRO LOOP
  3187.       IF $-.lus&lt;127
  3188.         DJNZ .lus
  3189.       ELSE
  3190.         DEC B
  3191.         JP NZ,.lus
  3192.       ENDIF
  3193.     ENDM
  3194.  
  3195. Main
  3196. .lus
  3197.     CALL DoALot
  3198.     LOOP
  3199. ; This will expand to:
  3200. Main
  3201. .lus                  ; Main.lus
  3202.     CALL DoALot
  3203.     DJNZ .lus         ; Main.lus</programlisting>
  3204.         </example></para>
  3205.  
  3206.       <para>Angle brackets can be used when the arguments contain commas.
  3207.       <example>
  3208.           <title>Argument in angle brackets (docs_examples/s_macros.asm)</title>
  3209.  
  3210.           <programlisting>    MACRO UseLess data
  3211.       DB data
  3212.     ENDM
  3213.  
  3214.     UseLess &lt;10,12,13,0&gt;
  3215. ; expands to:
  3216.     DB 10,12,13,0
  3217.  
  3218. ; use '!' to include '!' and '&gt;' in those strings.
  3219.  
  3220.     UseLess &lt;5, 6 !&gt; 3&gt;
  3221. ; expands to:
  3222.     DB 5, 6 &gt; 3
  3223.  
  3224.     UseLess &lt;"Kip!!",3&gt;
  3225. ; expands to:
  3226.     DB "Kip!",3</programlisting>
  3227.         </example></para>
  3228.  
  3229.                 <para>As compatibility convenience to make porting from different assemblers somewhat
  3230.                         easier, there is alternative syntax, where the macro name is written at beginning
  3231.                         of line (as if label, but MODULE part is NOT applied to macro name).
  3232.                         <example><title>Macro name at beginning of line (docs_examples/s_macros.asm)</title>
  3233.                                 <programlisting>LabelAsMacroName    MACRO  arg1?, arg2?
  3234.                         ld  a,arg1?
  3235.                         ld  hl,arg2?
  3236.                     ENDM
  3237.  
  3238.                 LabelAsMacroName 1,$1234
  3239.             ; expands to:
  3240.                 ld a,1 : ld hl,$1234</programlisting>
  3241.                         </example>
  3242.                 </para>
  3243.  
  3244.                 <para>
  3245.                         If some macro over-shadows regular instruction or directive name, the <code>@</code>
  3246.                         character in front of instruction/directive name can be used to inhibit macro expansion.
  3247.                         <example><title>Inhibit macro expansion operator (docs_examples/s_macros.asm)</title>
  3248.                                 <programlisting>djnz    MACRO   arg1?
  3249.             dec c
  3250.             jr  nz,arg1?
  3251.             @djnz arg1? ; avoid self-reference and use real instruction
  3252.         ENDM
  3253.  
  3254. 1:      djnz    1B      ; macro replacement will be used here
  3255. 1:      @djnz   1B      ; original djnz instruction here</programlisting>
  3256.                         </example>
  3257.                 </para>
  3258.  
  3259.     </section>
  3260.   </chapter>
  3261.  
  3262.   <chapter>
  3263.     <title><anchor id="c_structures" />Structures</title>
  3264.  
  3265.     <section>
  3266.       <title>What is it?</title>
  3267.  
  3268.       <para>Structures can be used to define data structures in memory more
  3269.       easily. The name of the structure is set to the total size of the
  3270.       structure.</para>
  3271.     </section>
  3272.  
  3273.     <section>
  3274.       <title>Defining structure</title>
  3275.  
  3276.       <para>A structure definition starts with: <code>STRUCT
  3277.       &lt;name&gt;[,&lt;initial offset&gt;]</code> and ends with
  3278.       <code>ENDS</code>. Structure definitions are local to the current
  3279.       module, but, as with labels, '@' can be used to override this.</para>
  3280.  
  3281.       <para>Lines between STRUCT and ENDS should have the following
  3282.       format:</para>
  3283.  
  3284.       <para><code>membername pseudo-operation operands</code></para>
  3285.  
  3286.       <para>All fields are optional. Lines without label should start with
  3287.       whitespace.</para>
  3288.  
  3289.       <para>When non zero <code>offset</code> is used, it acts as if
  3290.        <link linkend="st_block">BLOCK</link> with <code>length</code> equal to
  3291.        <code>offset</code> was defined as first member of structure.</para>
  3292.     </section>
  3293.  
  3294.     <section>
  3295.       <title>Instructions</title>
  3296.  
  3297.       <para>Between the STRUCT and ENDS pseudo-instructions the following
  3298.       instructions can be used:</para>
  3299.  
  3300.       <para><variablelist>
  3301.           <varlistentry>
  3302.             <term><anchor id="st_byte" />BYTE [&lt;defaultvalue&gt;]</term>
  3303.  
  3304.             <listitem>
  3305.               <para>To define a one byte member. The defaultvalue is used when
  3306.               no initialisation value is given when the structure is declared.
  3307.               (DB and DEFB may be used instead of BYTE).</para>
  3308.             </listitem>
  3309.           </varlistentry>
  3310.  
  3311.           <varlistentry>
  3312.             <term><anchor id="st_word" />WORD [&lt;defaultvalue&gt;]</term>
  3313.  
  3314.             <listitem>
  3315.               <para>To define a two byte member. The defaultvalue is used when
  3316.               no initialisation value is given when the structure is declared.
  3317.               (DW and DEFW may be used instead of WORD).</para>
  3318.             </listitem>
  3319.           </varlistentry>
  3320.  
  3321.           <varlistentry>
  3322.             <term><anchor id="st_d24" />D24 [&lt;defaultvalue&gt;]</term>
  3323.  
  3324.             <listitem>
  3325.               <para>To define a three byte member. The defaultvalue is used
  3326.               when no initialisation value is given when the structure is
  3327.               declared.</para>
  3328.             </listitem>
  3329.           </varlistentry>
  3330.  
  3331.           <varlistentry>
  3332.             <term><anchor id="st_dword" />DWORD [&lt;defaultvalue&gt;]</term>
  3333.  
  3334.             <listitem>
  3335.               <para>To define a four byte member. The defaultvalue is used
  3336.               when no initialisation value is given when the structure is
  3337.               declared. (DD and DEFD may be used instead of DWORD).</para>
  3338.             </listitem>
  3339.           </varlistentry>
  3340.  
  3341.           <varlistentry>
  3342.             <term><anchor id="st_block" />BLOCK &lt;length&gt;[,&lt;fillbyte&gt;]]</term>
  3343.  
  3344.             <listitem>
  3345.               <para>To define a member of the specified number of bytes. Arguments are set
  3346.                   when defining the current structure, and are not part of init values when
  3347.                   the structure is later used.
  3348.               ('#', DS and DEFS may be used instead of BLOCK).</para>
  3349.  
  3350.               <para>(since v1.11) If <code>fillbyte</code> is omitted, the device memory
  3351.                   content in the block area is preserved (not zeroed).</para>
  3352.             </listitem>
  3353.           </varlistentry>
  3354.  
  3355.           <varlistentry>
  3356.             <term><anchor id="st_align" />ALIGN [&lt;expression&gt;[, &lt;byte&gt;]]</term>
  3357.  
  3358.             <listitem>
  3359.               <para>To <link linkend="po_align">align</link> the offset. If the expression
  3360.                   is omitted, 4 is assumed. ('##' May be used instead of ALIGN).</para>
  3361.  
  3362.               <para>(since v1.11) If the byte is omitted, device memory content is preserved (not zeroed).</para>
  3363.             </listitem>
  3364.           </varlistentry>
  3365.  
  3366.           <varlistentry>
  3367.             <term>&lt;structure name&gt; [&lt;init values&gt;]</term>
  3368.  
  3369.             <listitem>
  3370.               <para>It is possible to nest structures, and give new defaults
  3371.               for the BYTE and WORD members.</para>
  3372.             </listitem>
  3373.           </varlistentry>
  3374.         </variablelist></para>
  3375.     </section>
  3376.  
  3377.     <section>
  3378.       <title><anchor id="st_usage" />Usage of defined structure</title>
  3379.  
  3380.       <para><code>[&lt;label&gt;] &lt;struct_name&gt; [&lt;initial values&gt;]</code> will emit full
  3381.                 structure into machine code, either using default values from structure definition,
  3382.                 or overriding them with explicit value from the &lt;initial values&gt; list. In initial
  3383.                 values you can use curly brackets {} to group particular initial values for particular
  3384.                 sub-structure, any missing values in particular sub-structure init-list are set up by
  3385.                 default values of particular field. See "SDOT" example below or tests/struct asm files
  3386.                 for more examples.</para>
  3387.  
  3388.       <para><code>&lt;label&gt; &lt;struct_name&gt; = &lt;expression&gt;</code> will only set up
  3389.                 &lt;label&gt;.&lt;struct_field&gt; labels starting from designed address provided by
  3390.                 expression, but there will be no machine code emitted (and current address "$" will not
  3391.                 advance).</para>
  3392.  
  3393.     </section>
  3394.  
  3395.     <section>
  3396.       <title>Examples</title>
  3397.  
  3398.       <example>
  3399.           <title>docs_examples/c_structures.asm</title>
  3400.  
  3401.           <para><programlisting>        STRUCT SCOLOR
  3402. RED     BYTE 4
  3403. GREEN   BYTE 5
  3404. BLUE    BYTE 6
  3405.         ENDS</programlisting></para>
  3406.  
  3407.           <para>This is identical to:</para>
  3408.  
  3409.           <synopsis>SCOLOR              EQU 3 ; length
  3410. SCOLOR.RED      EQU 0 ; offset
  3411. SCOLOR.GREEN    EQU 1 ; offset
  3412. SCOLOR.BLUE     EQU 2 ; offset</synopsis>
  3413.           </example>
  3414.           <example>
  3415.           <title>docs_examples/c_structures.asm</title>
  3416.  
  3417.           <para><programlisting>        STRUCT SDOT
  3418. X       BYTE
  3419. Y       BYTE
  3420. C       SCOLOR 0,0,0 ; use new default values
  3421.         ENDS
  3422. </programlisting></para>
  3423.  
  3424.           <para>This is identical to:</para>
  3425.  
  3426.           <synopsis>SDOT                EQU 5 ; length
  3427. SDOT.X          EQU 0 ; offset
  3428. SDOT.Y          EQU 1 ; offset
  3429. SDOT.C          EQU 2 ; offset
  3430. SDOT.C.RED      EQU 2 ; offset
  3431. SDOT.C.GREEN    EQU 3 ; offset
  3432. SDOT.C.BLUE     EQU 4 ; offset
  3433. </synopsis>
  3434.           </example>
  3435.           <example>
  3436.           <title>docs_examples/c_structures.asm</title>
  3437.  
  3438.           <para><programlisting>        STRUCT SPOS,4
  3439. X       WORD
  3440. Y       BYTE
  3441.         ALIGN 2
  3442. AD      WORD
  3443.         ENDS</programlisting></para>
  3444.  
  3445.           <para>This is identical to:</para>
  3446.  
  3447.           <synopsis>SPOS        EQU 10 ; length
  3448. SPOS.X  EQU  4 ; offset
  3449. SPOS.Y  EQU  6 ; offset
  3450. SPOS.AD EQU  8 ; offset</synopsis>
  3451.           </example>
  3452.           <example>
  3453.           <title>docs_examples/c_structures.asm</title>
  3454.  
  3455.           <para>When a structure is defined it is possible to declare labels
  3456.           with it<programlisting>COLOR SCOLOR</programlisting>This is
  3457.           identical to:<synopsis>COLOR
  3458. COLOR.RED   BYTE 4
  3459. COLOR.GREEN BYTE 5
  3460. COLOR.BLUE  BYTE 6
  3461. </synopsis>Note the default values.</para>
  3462.  
  3463.           <para>Or without label:<programlisting>COLORTABLE
  3464.   SCOLOR 0,0,0
  3465.   SCOLOR 1,2,3
  3466.   SCOLOR ,2
  3467.   ; etc.</programlisting>This is identical to:<synopsis>COLORTABLE
  3468.   BYTE 0,0,0
  3469.   BYTE 1,2,3
  3470.   BYTE 4,2,6
  3471.   ; etc.</synopsis>
  3472.  
  3473. <programlisting>DOT1 SDOT 0,0, 0,0,0     ; or 0,0,0,0,0 or {0,0,{0,0,0}}</programlisting>Only
  3474.           BYTE and WORD members can be initialised.</para>
  3475.  
  3476.           <para>The resulting labels can be used as any other
  3477.           label:<programlisting>  ld b,(ix+SCOLOR.RED)
  3478.   ld a,(COLOR.GREEN)
  3479.   ld de,COLOR
  3480.   ; etc.</programlisting></para>
  3481.  
  3482.           </example>
  3483.       <example>
  3484.           <title>docs_examples/st_usage_example.asm</title>
  3485.  
  3486.           <para><programlisting>        STRUCT BIN_FILE_MAP, 256
  3487. value1  BYTE
  3488. value2  WORD
  3489.         ENDS
  3490.  
  3491.         ORG  0x8000
  3492. binData BIN_FILE_MAP = $        ; set up label values only (no bytes)
  3493.         INCBIN "some_data.bin"  ; load the bytes from file instead
  3494.  
  3495.         ; using the data through struct definition
  3496.         ld  a,(binData.value1)
  3497.         ld  hl,(binData.value2)</programlisting></para>
  3498.  
  3499.           <para>This is identical to:</para>
  3500.  
  3501.           <synopsis>BIN_FILE_MAP            EQU 259      ; length
  3502. BIN_FILE_MAP.value1     EQU 256      ; offset
  3503. BIN_FILE_MAP.value2     EQU 257      ; offset
  3504. ; labels to access binary data loaded by INCBIN
  3505. binData                 EQU 0x8000   ; address
  3506. binData.value1          EQU 0x8100   ; address
  3507. binData.value2          EQU 0x8101   ; address</synopsis>
  3508.           </example>
  3509.  
  3510.           <warning>
  3511.                 <para>Do not use the offset labels in indirections
  3512.                 like:<programlisting>LD A,(SDOT.X)</programlisting>This will
  3513.                 conflict with futher 'improvements' ;-)</para>
  3514.  
  3515.                 <para>If this is absolutely necessary (why?) use something like
  3516.                 this:<programlisting>LD A,(+SDOT.X)</programlisting></para>
  3517.           </warning>
  3518.     </section>
  3519.   </chapter>
  3520.  
  3521.   <chapter>
  3522.     <title><anchor id="c_lua_scripting" />Lua scripting</title>
  3523.  
  3524.     <section>
  3525.       <title>Why?</title>
  3526.  
  3527.       <para><graphic align="left" fileref="lua.gif" />Why is scripting engine
  3528.       as Lua embedded to the compiler? Answer is simple: It need to add extra
  3529.       features by users. And to whole other Lua is enough small, fast and
  3530.       powerful scripting engine.</para>
  3531.     </section>
  3532.  
  3533.     <section>
  3534.       <title>How to use?</title>
  3535.  
  3536.       <para>You must use <link linkend="po_lua">LUA</link> and <link
  3537.       linkend="po_endlua">ENDLUA</link> pseudo-ops.<example>
  3538.           <title>Hello World!</title>
  3539.  
  3540.           <para><programlisting>    LUA
  3541.         print ("Hello World!")
  3542.     ENDLUA</programlisting></para>
  3543.         </example></para>
  3544.     </section>
  3545.  
  3546.     <section>
  3547.       <title>SjASMPlus binded functions</title>
  3548.  
  3549.       <para>From Lua you can control some variables and use functions of the
  3550.       compiler. Complete list:</para>
  3551.  
  3552.       <para><variablelist>
  3553.           <varlistentry>
  3554.             <term><anchor id="lua__c" />[integer] _c("expression")</term>
  3555.  
  3556.             <listitem>
  3557.               <para>Calculate expression using calculator of the compiler.
  3558.               Example: <code>val = _c("SOMELABEL+12")</code>.</para>
  3559.             </listitem>
  3560.           </varlistentry>
  3561.  
  3562.           <varlistentry>
  3563.             <term><anchor id="lua__pc" />[void] _pc("code")</term>
  3564.  
  3565.             <listitem>
  3566.               <para>Parse string of Z80 assembly. Example: <code>_pc("ADD
  3567.              A,B")</code></para>
  3568.             </listitem>
  3569.           </varlistentry>
  3570.  
  3571.           <varlistentry>
  3572.             <term><anchor id="lua__pl" />[void] _pl("label code")</term>
  3573.  
  3574.             <listitem>
  3575.               <para>Parse line of Z80 assembly. Example: <code>_pc("SOMELABEL
  3576.              ADD A,B")</code></para>
  3577.             </listitem>
  3578.           </varlistentry>
  3579.  
  3580.           <varlistentry>
  3581.             <term>[integer] sj.calc("expression")</term>
  3582.  
  3583.             <listitem>
  3584.               <para>See <link linkend="lua__c">_c</link></para>
  3585.             </listitem>
  3586.           </varlistentry>
  3587.  
  3588.           <varlistentry>
  3589.             <term>[void] sj.parse_code("code")</term>
  3590.  
  3591.             <listitem>
  3592.               <para>See <link linkend="lua__pc">_pc</link></para>
  3593.             </listitem>
  3594.           </varlistentry>
  3595.  
  3596.           <varlistentry>
  3597.             <term>[void] sj.parse_line("label code")</term>
  3598.  
  3599.             <listitem>
  3600.               <para>See <link linkend="lua__pl">_pl</link></para>
  3601.             </listitem>
  3602.           </varlistentry>
  3603.  
  3604.           <varlistentry>
  3605.             <term>[void] sj.error("message")</term>
  3606.  
  3607.             <listitem>
  3608.               <para>Print error message.</para>
  3609.             </listitem>
  3610.           </varlistentry>
  3611.  
  3612.           <varlistentry>
  3613.             <term>[void] sj.warning("message")</term>
  3614.  
  3615.             <listitem>
  3616.               <para>Print warning message.</para>
  3617.             </listitem>
  3618.           </varlistentry>
  3619.  
  3620.           <varlistentry>
  3621.             <term>[boolean] sj.file_exists("filename")</term>
  3622.  
  3623.             <listitem>
  3624.               <para>Check for file exists.</para>
  3625.             </listitem>
  3626.           </varlistentry>
  3627.  
  3628.           <varlistentry>
  3629.             <term>[string] sj.get_define("name")</term>
  3630.  
  3631.             <listitem>
  3632.               <para>Get define value.</para>
  3633.             </listitem>
  3634.           </varlistentry>
  3635.  
  3636.           <varlistentry>
  3637.             <term>[boolean] sj.insert_define("name", "value")</term>
  3638.  
  3639.             <listitem>
  3640.               <para>Add new define.</para>
  3641.             </listitem>
  3642.           </varlistentry>
  3643.  
  3644.           <varlistentry>
  3645.             <term>[integer] sj.get_label("name")</term>
  3646.  
  3647.             <listitem>
  3648.               <para>Get label address.</para>
  3649.             </listitem>
  3650.           </varlistentry>
  3651.  
  3652.           <varlistentry>
  3653.             <term>[boolean] sj.insert_label("name", address)</term>
  3654.  
  3655.             <listitem>
  3656.               <para>Add new label.</para>
  3657.             </listitem>
  3658.           </varlistentry>
  3659.  
  3660.           <varlistentry>
  3661.             <term><anchor id="lua_sj_current_address" />[integer]
  3662.             sj.current_address</term>
  3663.  
  3664.             <listitem>
  3665.               <para>Variable. Current address.</para>
  3666.             </listitem>
  3667.           </varlistentry>
  3668.  
  3669.           <varlistentry>
  3670.             <term>[integer] sj.error_count</term>
  3671.  
  3672.             <listitem>
  3673.               <para>Variable. Count of Errors.</para>
  3674.             </listitem>
  3675.           </varlistentry>
  3676.  
  3677.           <varlistentry>
  3678.             <term>[integer] sj.warning_count</term>
  3679.  
  3680.             <listitem>
  3681.               <para>Variable. Count of Warnings.</para>
  3682.             </listitem>
  3683.           </varlistentry>
  3684.  
  3685.           <varlistentry>
  3686.             <term>[void] sj.exit(errorcode)</term>
  3687.  
  3688.             <listitem>
  3689.               <para>Shutdown the compiler.</para>
  3690.             </listitem>
  3691.           </varlistentry>
  3692.  
  3693.           <varlistentry>
  3694.             <term>[void] sj.add_byte(byte)</term>
  3695.  
  3696.             <listitem>
  3697.               <para>Add byte to output (or to memory) and increase <link
  3698.               linkend="lua_sj_current_address">sj.current_address</link></para>
  3699.             </listitem>
  3700.           </varlistentry>
  3701.  
  3702.           <varlistentry>
  3703.             <term>[void] sj.add_word(word)</term>
  3704.  
  3705.             <listitem>
  3706.               <para>Add word to output (or to memory) and twice increase <link
  3707.               linkend="lua_sj_current_address">sj.current_address</link></para>
  3708.             </listitem>
  3709.           </varlistentry>
  3710.  
  3711.           <varlistentry>
  3712.             <term>[integer] sj.get_byte(address)</term>
  3713.  
  3714.             <listitem>
  3715.               <para>Get byte from memory. <emphasis>Work only in real device
  3716.               emulation mode.</emphasis></para>
  3717.             </listitem>
  3718.           </varlistentry>
  3719.  
  3720.           <varlistentry>
  3721.             <term>[integer] sj.get_word(address)</term>
  3722.  
  3723.             <listitem>
  3724.               <para>Get word from memory. <emphasis>Work only in real device
  3725.               emulation mode.</emphasis></para>
  3726.             </listitem>
  3727.           </varlistentry>
  3728.  
  3729.           <varlistentry>
  3730.             <term>[string] sj.get_device()</term>
  3731.  
  3732.             <listitem>
  3733.               <para>Return current emulating device's identifier. Returns
  3734.              "NONE" if no emulation mode.</para>
  3735.            </listitem>
  3736.          </varlistentry>
  3737.  
  3738.          <varlistentry>
  3739.            <term>[boolean] sj.set_device("id")</term>
  3740.  
  3741.            <listitem>
  3742.              <para>Set current emulating device's identifier. Returns false
  3743.               if no device found.</para>
  3744.             </listitem>
  3745.           </varlistentry>
  3746.  
  3747.           <varlistentry>
  3748.             <term>[boolean] sj.set_page(number)</term>
  3749.  
  3750.             <listitem>
  3751.               <para>Set page with number "number" to the current slot. Works
  3752.               as pseudo-op PAGE.</para>
  3753.             </listitem>
  3754.           </varlistentry>
  3755.  
  3756.           <varlistentry>
  3757.             <term>[boolean] sj.set_slot(number)</term>
  3758.  
  3759.             <listitem>
  3760.               <para>Set current slot with number "number". Works as pseudo-op
  3761.               SLOT.</para>
  3762.             </listitem>
  3763.           </varlistentry>
  3764.  
  3765.           <varlistentry>
  3766.             <term>[void] sj.shellexec("programname")</term>
  3767.  
  3768.             <listitem>
  3769.               <para>See pseudo-op SHELLEXEC.</para>
  3770.             </listitem>
  3771.           </varlistentry>
  3772.  
  3773.           <varlistentry>
  3774.             <term>[void] zx.trdimage_create("filename")</term>
  3775.  
  3776.             <listitem>
  3777.               <para>Creates emptry TRD image file.</para>
  3778.             </listitem>
  3779.           </varlistentry>
  3780.  
  3781.           <varlistentry>
  3782.             <term>[void] zx.trdimage_add_file("filename", "somenameC",
  3783.             startaddress, length, autostart, replace)</term>
  3784.  
  3785.             <listitem>
  3786.               <para>Save block of memory to TRD image file. <emphasis>Work
  3787.               only in real device emulation mode.</emphasis></para>
  3788.             </listitem>
  3789.           </varlistentry>
  3790.  
  3791.           <varlistentry>
  3792.             <term>[void] zx.save_snapshot_sna("filename.sna",
  3793.             startaddressofprogram)</term>
  3794.  
  3795.             <listitem>
  3796.               <para>Save snapshot of memory in SNA format. <emphasis>Work only
  3797.               in real device emulation mode and only for ZXSPECTRUM48 and
  3798.               ZXSPECTRUM128..</emphasis></para>
  3799.             </listitem>
  3800.           </varlistentry>
  3801.         </variablelist></para>
  3802.     </section>
  3803.  
  3804.     <section>
  3805.       <title>Third-party embedded library(ies)</title>
  3806.  
  3807.       <para><emphasis>lpack.c</emphasis></para>
  3808.  
  3809.       <para>a Lua library for packing and unpacking binary data</para>
  3810.  
  3811.       <para>by Luiz Henrique de Figueiredo
  3812.       &lt;lhf(at)tecgraf.puc-rio.br&gt;</para>
  3813.  
  3814.       <para>The library adds two functions to the string library:
  3815.       <emphasis>string.pack</emphasis> and
  3816.       <emphasis>string.unpack</emphasis>.</para>
  3817.  
  3818.       <para>pack is called as follows: string.pack(F,x1,x2,...), where F is a
  3819.       string describing how the values x1, x2, ... are to be interpreted and
  3820.       formatted. Each letter in the format string F consumes one of the given
  3821.       values. Only values of type number or string are accepted. pack returns
  3822.       a (binary) string containing the values packed as described in F. The
  3823.       letter codes understood by pack are listed in lpack.c (they are inspired
  3824.       by Perl's codes but are not the same). Numbers following letter codes in
  3825.      F indicate repetitions.</para>
  3826.  
  3827.      <para>unpack is called as follows: string.unpack(s,F,[init]), where s is
  3828.      a (binary) string containing data packed as if by pack, F is a format
  3829.      string describing what is to be read from s, and the optional init marks
  3830.      where in s to begin reading the values. unpack returns one value per
  3831.      letter in F until F or s is exhausted (the letters codes are the same as
  3832.      for pack, except that numbers following 'A' are interpreted as the
  3833.      number of characters to read into the string, not as
  3834.      repetitions).</para>
  3835.  
  3836.      <para>The first value returned by unpack is the next unread position in
  3837.      s, which can be used as the init position in a subsequent call to
  3838.      unpack. This allows you to unpack values in a loop or in several steps.
  3839.      If the position returned by unpack is beyond the end of s, then s has
  3840.      been exhausted; any calls to unpack starting beyond the end of s will
  3841.      always return nil values.</para>
  3842.  
  3843.      <para>List of types for F string:<variablelist>
  3844.          <varlistentry>
  3845.            <term>z</term>
  3846.  
  3847.            <listitem>
  3848.              <para>zero-terminated string</para>
  3849.            </listitem>
  3850.          </varlistentry>
  3851.  
  3852.          <varlistentry>
  3853.            <term>p</term>
  3854.  
  3855.            <listitem>
  3856.              <para>string preceded by length byte</para>
  3857.            </listitem>
  3858.          </varlistentry>
  3859.  
  3860.          <varlistentry>
  3861.            <term>P</term>
  3862.  
  3863.            <listitem>
  3864.              <para>string preceded by length word</para>
  3865.            </listitem>
  3866.          </varlistentry>
  3867.  
  3868.          <varlistentry>
  3869.            <term>a</term>
  3870.  
  3871.            <listitem>
  3872.              <para>string preceded by length size_t</para>
  3873.            </listitem>
  3874.          </varlistentry>
  3875.  
  3876.          <varlistentry>
  3877.            <term>A</term>
  3878.  
  3879.            <listitem>
  3880.              <para>string</para>
  3881.            </listitem>
  3882.          </varlistentry>
  3883.  
  3884.          <varlistentry>
  3885.            <term>f</term>
  3886.  
  3887.            <listitem>
  3888.              <para>float</para>
  3889.            </listitem>
  3890.          </varlistentry>
  3891.  
  3892.          <varlistentry>
  3893.            <term>d</term>
  3894.  
  3895.            <listitem>
  3896.              <para>double</para>
  3897.            </listitem>
  3898.          </varlistentry>
  3899.  
  3900.          <varlistentry>
  3901.            <term>n</term>
  3902.  
  3903.            <listitem>
  3904.              <para>Lua number</para>
  3905.            </listitem>
  3906.          </varlistentry>
  3907.  
  3908.          <varlistentry>
  3909.            <term>c</term>
  3910.  
  3911.            <listitem>
  3912.              <para>char</para>
  3913.            </listitem>
  3914.          </varlistentry>
  3915.  
  3916.          <varlistentry>
  3917.            <term>b</term>
  3918.  
  3919.            <listitem>
  3920.              <para>byte = unsigned char</para>
  3921.            </listitem>
  3922.          </varlistentry>
  3923.  
  3924.          <varlistentry>
  3925.            <term>h</term>
  3926.  
  3927.            <listitem>
  3928.              <para>short = word</para>
  3929.            </listitem>
  3930.          </varlistentry>
  3931.  
  3932.          <varlistentry>
  3933.            <term>H</term>
  3934.  
  3935.            <listitem>
  3936.              <para>unsigned short</para>
  3937.            </listitem>
  3938.          </varlistentry>
  3939.  
  3940.          <varlistentry>
  3941.            <term>i</term>
  3942.  
  3943.            <listitem>
  3944.              <para>int</para>
  3945.            </listitem>
  3946.          </varlistentry>
  3947.  
  3948.          <varlistentry>
  3949.            <term>I</term>
  3950.  
  3951.            <listitem>
  3952.              <para>unsigned int</para>
  3953.            </listitem>
  3954.          </varlistentry>
  3955.  
  3956.          <varlistentry>
  3957.            <term>l</term>
  3958.  
  3959.            <listitem>
  3960.              <para>long</para>
  3961.            </listitem>
  3962.          </varlistentry>
  3963.  
  3964.          <varlistentry>
  3965.            <term>L</term>
  3966.  
  3967.            <listitem>
  3968.              <para>unsigned long</para>
  3969.            </listitem>
  3970.          </varlistentry>
  3971.  
  3972.          <varlistentry>
  3973.            <term>&lt;</term>
  3974.  
  3975.            <listitem>
  3976.              <para>little endian</para>
  3977.            </listitem>
  3978.          </varlistentry>
  3979.  
  3980.          <varlistentry>
  3981.            <term>&gt;</term>
  3982.  
  3983.            <listitem>
  3984.              <para>big endian</para>
  3985.            </listitem>
  3986.          </varlistentry>
  3987.  
  3988.          <varlistentry>
  3989.            <term>=</term>
  3990.  
  3991.            <listitem>
  3992.              <para>native endian</para>
  3993.            </listitem>
  3994.          </varlistentry>
  3995.        </variablelist></para>
  3996.    </section>
  3997.  
  3998.    <section>
  3999.      <title>Example</title>
  4000.  
  4001.      <para></para>
  4002.  
  4003.      <para><example>
  4004.          <title>Variables doesn't clear in new passes of the compiler</title>
  4005.  
  4006.           <para><programlisting>    LUA PASS1
  4007.        v = 1
  4008.     ENDLUA
  4009.  
  4010.     LUA PASS2
  4011.        print (v)
  4012. -- out to console: 1
  4013.        v++
  4014.     ENDLUA
  4015.  
  4016.     LUA PASS3
  4017.        print (v)
  4018. -- out to console: 2
  4019.     ENDLUA</programlisting></para>
  4020.         </example><example>
  4021.           <title>To generate some code you need to generate it in all
  4022.           passes</title>
  4023.  
  4024.           <para><programlisting>    LUA ALLPASS
  4025.         _pl("ClearScreen LD (.savesp+1),SP")
  4026.         _pc("LD SP,16384+6144")
  4027.         _pc("LD HL,0")
  4028.         for i = 32768, 38912, 2 do
  4029.             _pc("PUSH HL")
  4030.         end
  4031.         _pl(".savesp: LD SP,0")
  4032.         _pc("RET")
  4033.     ENDLUA
  4034.  
  4035.     LUA PASS2 ; if you fully understand what you are doing
  4036.         sj.add_byte(123) -- and you need emit bytes in other mode
  4037.     ENDLUA ; ok ; you can suppress warning here or at start of block</programlisting></para>
  4038.         </example><example>
  4039.           <title>Declare function and use it</title>
  4040.  
  4041.           <para><programlisting>     LUA
  4042.          function savetape_mytype(filename, startaddress)
  4043.              local fp
  4044.              fp = assert(io.open(fname, "wb"))
  4045.              for i = 16384, 32767, 4 do
  4046.                  assert(fp:write( string.pack("bbbb",
  4047.                                 sj.get_byte(i),
  4048.                                 sj.get_byte(i+1),
  4049.                                 sj.get_byte(i+2),
  4050.                                 sj.get_byte(i+3)) ))
  4051.              end
  4052.              assert(fp:flush())
  4053.              assert(fp:close())
  4054.          end
  4055.      ENDLUA
  4056.  
  4057.  ;somewhere in your program
  4058.      LUA
  4059.          savetape_mytype("tapefiles/myprogram.tape", _c("StartGameLabel"))
  4060.      ENDLUA</programlisting></para>
  4061.         </example><example>
  4062.           <title>Simple sample :)</title>
  4063.  
  4064.           <para><programlisting>        LUA
  4065. -- Function reads number from file &lt;fname&gt;, increases it, creates define "BUILD" with the number and saves the number to &lt;fname&gt;.
  4066. -- With this function you can control count of compilations.
  4067.         function increase_build(fname)
  4068.                 local fp
  4069.                 local build
  4070.                 fp = assert(io.open(fname, "rb"))
  4071.                 build = tonumber(fp:read("*all"))
  4072.                 assert(fp:close())
  4073.                 if type(build) == "nil" then
  4074.                     build = 0
  4075.                 end
  4076.                 build = build + 1;
  4077.                 sj.insert_define("BUILD", build)
  4078.                 fp = assert(io.open(fname, "wb"))
  4079.                 assert(fp:write( build ))
  4080.                 assert(fp:flush())
  4081.                 assert(fp:close())
  4082.         end
  4083.  
  4084. -- Before using you must create empty file "build.txt"!
  4085.         increase_build("build.txt")
  4086.  
  4087. -- Creates define "TIME" with current time
  4088.         sj.insert_define("TIME", '"' .. os.date("%Y-%m-%d %H:%M:%S") .. '"')
  4089.         ENDLUA
  4090.  
  4091. ; print to console our time and build number
  4092.         DISPLAY "Build time: ", TIME
  4093.         DISPLAY "Build number: ", /D, BUILD</programlisting></para>
  4094.         </example></para>
  4095.  
  4096.       <para></para>
  4097.  
  4098.       <para></para>
  4099.     </section>
  4100.   </chapter>
  4101.  
  4102.   <chapter>
  4103.     <title><anchor id="c_savenex" />SAVENEX guide</title>
  4104.        
  4105.     <section>
  4106.       <title><anchor id="s_savenex_file_format" />NEX File Format</title>
  4107.  
  4108.       <para>NEX is binary format for ZX Spectrum Next, aiming to provide simple delivery of software
  4109.       for the platform. For file format details check <ulink url="https://specnext.dev/wiki/NEX_file_format">
  4110.       https://specnext.dev/wiki/NEX_file_format</ulink>. In short it is header + loading screen +
  4111.       like-snapshot binary and remaining resources appended after.</para>
  4112.  
  4113.   <para>Sjasmplus currently supports V1.2 and V1.3 of NEX file format (see wiki for details).</para>
  4114.  
  4115.   <para>As such, the SAVENEX commands are available only in ZXSPECTRUMNEXT device emulation mode,
  4116.           see <link linkend="po_device">DEVICE</link>.</para>
  4117.  
  4118.   <para>As the file is designed for self-contained distribution of whole applications/games,
  4119.           its configuration and assembling is a bit too complex for single directive, and the
  4120.           configuration is instead divided into multiple commands, and the assembling goes
  4121.           through multiple stages, so some commands must be used in correct sequence.</para>
  4122.  
  4123.   <para>While the format technically allows to include multiple screen types data, they are all
  4124.           loaded at the beginning over each other, so it makes sense to provide only single loading
  4125.           screen (sjasmplus enforces that).</para>
  4126.   </section>
  4127.  
  4128.   <section>
  4129.           <title><anchor id="s_savenex_commands" />Detailed description of each SAVENEX command</title>
  4130.           <variablelist>
  4131.                  
  4132.                   <varlistentry>
  4133.                           <term><anchor id="nex_open" />
  4134.                                   SAVENEX OPEN &lt;filename&gt;[,&lt;startAddress&gt;[,&lt;stackAddress&gt;[,&lt;entryBank16k 0..111&gt;[,&lt;fileVersion 2..3&gt;]]]]
  4135.                           </term>
  4136.                           <listitem>
  4137.                                   <para>
  4138.                                           Opens a NEX file, defines start address, stack address and 16k bank to be mapped
  4139.                                           at 0xC000 before code is executed (if values are omitted, start address is zero
  4140.                                           = no start, stack address is 0xFFFE, entryBank is zero, fileVersion is 2).
  4141.                                   </para>
  4142.                                   <para>
  4143.                                           Only single NEX file can be open at the same time, and to finalize the header
  4144.                                           content the command CLOSE has to be used (does auto-close if source ends).
  4145.                                   </para>
  4146.                                   <para>
  4147.                                           Entry bank is number of 16k bank (0..111), not native 8k page, default is zero,
  4148.                                           i.e. the default memory map is identical to ZX 128 (ROM, RAM banks 5, 2 and 0).
  4149.                                   </para>
  4150.                                   <para>
  4151.                                           Make sure your new stack has at least tens of bytes available as those will be
  4152.                                           used already by the NEX loader before executing your entry point (although
  4153.                                           released back).
  4154.                                   </para>
  4155.                                   <para>
  4156.                                           The fileVersion can be 2 (NEX V1.2) or 3 (NEX V1.3), which will enforce the
  4157.                                           specified version of file. Otherwise the file is V1.2 by default and will
  4158.                                           auto-switch to V1.3 when some V1.3 feature is configured/used. When version 2
  4159.                                           is enforced, any usage of V1.3 feature will emit error.
  4160.                                   </para>
  4161.                           </listitem>
  4162.                   </varlistentry>
  4163.                  
  4164.                   <varlistentry>
  4165.                           <term><anchor id="nex_core" />
  4166.                                   SAVENEX CORE &lt;major 0..15&gt;,&lt;minor 0..15&gt;,&lt;subminor 0..255&gt;
  4167.                           </term>
  4168.                           <listitem>
  4169.                                   <para>
  4170.                                           Set minimum required Next core version, can be set any time before <link
  4171.                                                   linkend="nex_close">CLOSE</link>.
  4172.                                   </para>
  4173.                           </listitem>
  4174.                   </varlistentry>
  4175.                  
  4176.                   <varlistentry>
  4177.                           <term><anchor id="nex_cfg" />
  4178.                                   SAVENEX CFG &lt;border 0..7&gt;[,&lt;fileHandle 0/1/$4000+&gt;[,&lt;PreserveNextRegs 0/1&gt;[,&lt;2MbRamReq 0/1&gt;]]]
  4179.                           </term>
  4180.                           <listitem>
  4181.                                   <para>
  4182.                                           Set border colour (during loading), whether the machine should be set to default
  4183.                                           state (PreserveNextRegs = 0 = default), if the app requires extended RAM
  4184.                                           (224 8k pages) and how the file handle of the NEX file should be treated:
  4185.                                           0 = default = close, 1 = keep open and pass in BC, $4000..$FFFE = keep open,
  4186.                                           and write into memory at provided address (after entry bank is paged in). This
  4187.                                           can be set any time before <link linkend="nex_close">CLOSE</link>.
  4188.                                   </para>
  4189.                           </listitem>
  4190.                   </varlistentry>
  4191.                  
  4192.                   <varlistentry>
  4193.                           <term><anchor id="nex_cfg3" />
  4194.                                   SAVENEX CFG3 &lt;DoCRC 0/1&gt;[,&lt;PreserveExpansionBus 0/1&gt;[,&lt;CLIbufferAdr&gt;,&lt;CLIbufferSize&gt;]]
  4195.                           </term>
  4196.                           <listitem>
  4197.                                   <para>
  4198.                                           All of these are NEX format V1.3 features and using "CFG3" command will change
  4199.                                           the version to V1.3 automatically (if not specified by <link linkend="nex_open">OPEN</link>).
  4200.                                   </para>
  4201.                                   <para>
  4202.                                           DoCRC: default = 1, sjasmplus will checksum the file (if you know you will be
  4203.                                           further patching file afterwards, switch it off, otherwise keep 1).
  4204.                                   </para>
  4205.                                   <para>
  4206.                                           PreserveExpansionBus: default = 0, 0 = the NEX loader will disable expansion
  4207.                                           bus through NextReg $80 / 1 = the NEX loader will not do anything.
  4208.                                   </para>
  4209.                                   <para>
  4210.                                           CLIbufferAdr, CLIbufferSize: default = [0, 0], address and size of buffer for
  4211.                                           NEX loader to copy the arguments line into. The buffer is copied after the
  4212.                                           "entryBank" is mapped, so you can allocate buffer in your entryBank. The
  4213.                                           loader/format has hard limit 2048 bytes, the argument line will be truncated
  4214.                                           if longer. If your reserved buffer is shorter than 2048 bytes, the copy will
  4215.                                           be also truncated to your buffer size only. If not truncated, the argument line
  4216.                                           can end with any of these: Enter (13), colon or zero byte (truncated has no
  4217.                                           terminator character, just fills the full buffer).
  4218.                                   </para>
  4219.                           </listitem>
  4220.                   </varlistentry>
  4221.  
  4222.                   <varlistentry>
  4223.                           <term><anchor id="nex_bar" />
  4224.                                   SAVENEX BAR &lt;loadBar 0/1&gt;,&lt;barColour 0..255&gt;[,&lt;startDelay 0..255&gt;[,&lt;bankDelay 0..255&gt;[,&lt;posY 0..255&gt;]]]
  4225.                           </term>
  4226.                           <listitem>
  4227.                                   <para>
  4228.                                           Loading-bar related setup ("colour" usage depends on screen mode), can be set
  4229.                                           any time before <link linkend="nex_close">CLOSE</link>.
  4230.                                   </para>
  4231.                                   <para>
  4232.                                           The posY argument will apply only to V1.3 Layer2 screens in 320x256 and
  4233.                                           640x256 resolution (then defaults to 254 = bottom of screen, 2px tall bar).
  4234.                                   </para>
  4235.                           </listitem>
  4236.                   </varlistentry>
  4237.                  
  4238.                   <varlistentry>
  4239.                           <term><anchor id="nex_palette" />
  4240.                                   <para>SAVENEX PALETTE NONE</para>
  4241.                                   <para>SAVENEX PALETTE DEFAULT</para>
  4242.                                   <para>SAVENEX PALETTE MEM &lt;palPage8kNum 0..223&gt;,&lt;palOffset&gt;</para>
  4243.                                   <para>SAVENEX PALETTE BMP &lt;filename&gt;</para>
  4244.                           </term>
  4245.                           <listitem>
  4246.                                   <para>
  4247.                                           This is optional command to set palette in alternative way ahead of SCREEN
  4248.                                           command, with higher priority (if the PALETTE command is used, following
  4249.                                           SCREEN commands will ignore the palette arguments and keep the palette defined
  4250.                                           by this command). You can be use it between <link linkend="nex_open">OPEN</link>
  4251.                                           and <link linkend="nex_auto">SCREEN</link> command. But appropriate SCREEN
  4252.                                           type supporting palette must be defined by SCREEN command too.
  4253.                                   </para>
  4254.                                   <para>
  4255.                                           Palette consists of 512 bytes (256 palette items from index 0), in 9b colour
  4256.                                           format: first byte is %RRRGGGBB, second byte is %P000000B (P is priority flag
  4257.                                           for Layer 2 colours).
  4258.                                   </para>
  4259.                                   <para>
  4260.                                           The DEFAULT palette will generate colour values from the colour index, the same
  4261.                                           way how default Layer 2 palette is initialized on the ZX Spectrum Next.
  4262.                                   </para>
  4263.                                   <para>
  4264.                                           The NONE palette will force the "no palette" flag even if SCREEN command later
  4265.                                           does specify some palette (it will be still ignored).
  4266.                                   </para>
  4267.                           </listitem>
  4268.                   </varlistentry>
  4269.  
  4270.                   <varlistentry>
  4271.                           <term><anchor id="nex_screen" />
  4272.                                   SAVENEX SCREEN L2 [&lt;Page8kNum 0..223&gt;,&lt;offset&gt;[,&lt;palPage8kNum 0..223&gt;,&lt;palOffset&gt;]]
  4273.                           </term>
  4274.                           <listitem>
  4275.                                   <para>
  4276.                                           Layer 2 loading screen, can be used between <link linkend="nex_open">OPEN</link>
  4277.                                           and first <link linkend="nex_auto">AUTO</link>/<link linkend="nex_bank">BANK</link> command.
  4278.                                   </para>
  4279.                                   <para>
  4280.                                           Palette consists of 512 bytes (256 palette items from index 0), in 9b colour
  4281.                                           format: first byte is %RRRGGGBB, second byte is %P000000B (P is priority flag
  4282.                                           for Layer 2 colours).
  4283.                                   </para>
  4284.                                   <para>
  4285.                                           Image data are 48kiB block of memory, the loader will use always banks 9..11 to display
  4286.                                           it (8k pages 18..23), but if you will prepare the data there, it will be also re-saved
  4287.                                           by <link linkend="nex_auto">AUTO</link> command, so either use other banks, and overwrite
  4288.                                           them with valid data/code after using the SCREEN command, or reset pages 18..23 to zero
  4289.                                           after SCREEN.
  4290.                                   </para>
  4291.                                   <para>
  4292.                                           If no memory address is specified, the pages 18..23 are stored in file, and if
  4293.                                           no palette address is specified, no-palette flag is set in NEX file.
  4294.                                   </para>
  4295.                           </listitem>
  4296.                   </varlistentry>
  4297.                  
  4298.                   <varlistentry>
  4299.                           <term>
  4300.                                   <para>SAVENEX SCREEN L2_320 [&lt;Page8kNum 0..223&gt;,&lt;offset&gt;[,&lt;palPage8kNum 0..223&gt;,&lt;palOffset&gt;]]</para>
  4301.                                   <para>SAVENEX SCREEN L2_640 [&lt;Page8kNum 0..223&gt;,&lt;offset&gt;[,&lt;palPage8kNum 0..223&gt;,&lt;palOffset&gt;]]</para>
  4302.                           </term>
  4303.                           <listitem>
  4304.                                   <para>
  4305.                                           Works same way as "L2" variant, but will set up screen for new resolutions 320x256x8
  4306.                                           and 640x256x4. The difference is that the required image data are 80kiB (five 16kiB
  4307.                                           banks; equals ten 8kiB pages), the banks used to show the screen in loader are
  4308.                                           9..13 (8k pages 18..27 - that's also the default address of data if not specified)
  4309.                                           - avoid these in regular banks stored in the file.
  4310.                                   </para>
  4311.                                   <para>
  4312.                                           These are NEX format V1.3 features and using them will change the version to V1.3
  4313.                                           automatically (if not specified by <link linkend="nex_open">OPEN</link>). This
  4314.                                           command doesn't allow to set specific palette offset value (too lazy to add it,
  4315.                                           use BMP variant if you really need it).
  4316.                                   </para>
  4317.                                   <para>
  4318.                                           The data has to be already in correct format and organized as if displayed (the
  4319.                                           "transposed" bitmap where +1 address goes to pixel below, and +256 goes to pixel
  4320.                                           on the right (or pair of pixels in case of 640x256x4bpp mode), this command will
  4321.                                           just dump them into file "as is".
  4322.                                   </para>
  4323.                                   <para>
  4324.                                           The loading bar colour byte will be also used "as is", which in 4bpp mode means
  4325.                                           the byte does define pair of 4 bit pixels, i.e. if you want solid-colour "3"
  4326.                                           loading bar in 4bpp mode, define it as value $33. Keep also in mind the default
  4327.                                           loading bar position is Y=254, which on most of the TV/LCD displays is outside
  4328.                                           of visible range, the reasonably "safe" (visible on almost all of the screens)
  4329.                                           resolution is about 288x224 (+16px around PAPER area, +24px is visible on many
  4330.                                           displays too), you may want to organize your screen in a way to show all important
  4331.                                           information within this area, and make the rest "unimportant" so it can hide
  4332.                                           beyond the edge of screen.
  4333.                                   </para>
  4334.                           </listitem>
  4335.                   </varlistentry>
  4336.  
  4337.                   <varlistentry>
  4338.                           <term>
  4339.                                   SAVENEX SCREEN LR [&lt;Page8kNum 0..223&gt;,&lt;offset&gt;[,&lt;palPage8kNum 0..223&gt;,&lt;palOffset&gt;]]
  4340.                           </term>
  4341.                           <listitem>
  4342.                                   <para>
  4343.                                           LoRes (128x96) loading screen, can be used between <link linkend="nex_open">OPEN</link>
  4344.                                           and first <link linkend="nex_auto">AUTO</link>/<link linkend="nex_bank">BANK</link> command.
  4345.                                   </para>
  4346.                                   <para>
  4347.                                           Palette is similar to Layer 2 mode, just LoRes mode doesn't have priority bit.
  4348.                                   </para>
  4349.                                   <para>
  4350.                                           Image data are 12288 bytes memory block - either consecutive block if specific
  4351.                                           address is provided, or without address the actual bank 5 memory is stored
  4352.                                           (taking 6144 bytes from address 0x4000 and 6144 bytes from address 0x6000).
  4353.                                   </para>
  4354.                           </listitem>
  4355.                   </varlistentry>
  4356.                  
  4357.                   <varlistentry>
  4358.                           <term>
  4359.                                   SAVENEX SCREEN BMP &lt;filename&gt;[,&lt;savePalette 0/1&gt;[,&lt;paletteOffset 0..15&gt;]]
  4360.                           </term>
  4361.                           <listitem>
  4362.                                   <para>
  4363.                                           Only small subset of BMP files can be used: 256x192 (Layer 2) or 128x96 (LoRes),
  4364.                                           indexed (8bit image data with palette) and palette data will be truncated
  4365.                                           to 3:3:3 color space directly (no smart colour quantization or dithering is applied).
  4366.                                           And the file must be uncompressed.
  4367.                                   </para>
  4368.                                   <para>
  4369.                                           For V1.3 NEX files you can include also 320x256 and 640x256 files (Layer 2), the
  4370.                                           640x256 should be also 8bit indexed, but only 4 bits of pixel data will be used
  4371.                                           (256 colour palette is legitimate and will be stored "as is" in NEX file).
  4372.                                           These two new modes can also include paletteOffset argument 0..15 (does not apply
  4373.                                           to V1.2 BMP files above), the offset is added to top four bits of pixel value.
  4374.                                   </para>
  4375.                                   <para>
  4376.                                           The BMP will be included as loading screen, can be used between <link linkend="nex_open">OPEN</link>
  4377.                                           and first <link linkend="nex_auto">AUTO</link>/<link linkend="nex_bank">BANK</link> command.
  4378.                                   </para>
  4379.                                   <para>
  4380.                                           By default the palette from BMP file is used, but you can override that by savePalette = 0.
  4381.                                           The warning about palette containing less than 256 colours can be suppressed by end-of-line
  4382.                                           OK comment like: <code>SAVENEX SCREEN BMP ... ; ok ...your comment</code>.
  4383.                                   </para>
  4384.                           </listitem>
  4385.                   </varlistentry>
  4386.  
  4387.                   <varlistentry>
  4388.                           <term>
  4389.                                   SAVENEX SCREEN (SCR|SHC|SHR) [&lt;hiResColour 0..7&gt;]
  4390.                           </term>
  4391.                           <listitem>
  4392.                                   <para>
  4393.                                           ULA/Timex modes loading screen, can be used between <link linkend="nex_open">OPEN</link>
  4394.                                           and first <link linkend="nex_auto">AUTO</link>/<link linkend="nex_bank">BANK</link> command.
  4395.                                   </para>
  4396.                                   <para>
  4397.                                           The actual bank 5 memory (pages 10..11) is stored as if the image is displayed,
  4398.                                           in these modes the palette can't be specified.
  4399.                                   </para>
  4400.                                   <para>
  4401.                                           SCR is classic ZX 6912 bytes long screen from address 0x4000 (page 10 is used,
  4402.                                           even if the slot 1 is modified to other page, so you must prepare the image "in place").
  4403.                                   </para>
  4404.                                   <para>
  4405.                                           SHC and SHR are Timex HiColor (8x1 attribute) and HiRes (512x192 bitmap) modes,
  4406.                                           prepare data "in place", i.e. 6144 bytes into page 10 and 6144 bytes into page
  4407.                                           11 (0x4000 and 0x6000 addresses in default memory setup). For HiRes mode you
  4408.                                           should specify ink colour (the paper is complement of ink).
  4409.                                   </para>
  4410.                           </listitem>
  4411.                   </varlistentry>
  4412.                  
  4413.                   <varlistentry>
  4414.                           <term>
  4415.                                   SAVENEX SCREEN TILE &lt;NextReg $6B&gt;,&lt;NextReg $6C&gt;,&lt;NextReg $6E&gt;,&lt;NextReg $6F&gt;[,&lt;AlsoStoreBank5 0/1 = 1&gt;]
  4416.                           </term>
  4417.                           <listitem>
  4418.                                   <para>
  4419.                                           NEX V1.3 tilemap loading screen, can be used between <link linkend="nex_open">OPEN</link>
  4420.                                           and first <link linkend="nex_auto">AUTO</link>/<link linkend="nex_bank">BANK</link> command.
  4421.                                   </para>
  4422.                                   <para>
  4423.                                           To define palette use the <link linkend="nex_palette">PALETTE</link> command.
  4424.                                   </para>
  4425.                                   <para>
  4426.                                           The image data are stored as regular Bank 5 of the NEX file (which is the first bank
  4427.                                           to be loaded by loader), depending on AlsoStoreBank5 value (default 1), this SCREEN
  4428.                                           command will also execute <link linkend="nex_bank">BANK  5</link> command to store
  4429.                                           the image data.
  4430.                                   </para>
  4431.                                   <para>
  4432.                                           The NextRegisters $6B, $6C, $6E and $6F should be enough to specify any variant
  4433.                                           of tilemap mode, so the precise sub-type and image data layout is under control
  4434.                                           of user, the sjasmplus doesn't enforce any particular configuration.
  4435.                                   </para>
  4436.                                   <para>
  4437.                                           If you want to use also <link linkend="nex_copper">COPPER</link> command, use it
  4438.                                           either ahead of the SCREEN TILE command, or use "AlsoStoreBank5 = 0" to delay the
  4439.                                           storage of Bank 5 data. In such case you must then later explicitly store
  4440.                                           the Bank 5 as regular bank, either with BANK or AUTO command.
  4441.                                   </para>
  4442.                           </listitem>
  4443.                   </varlistentry>
  4444.  
  4445.                   <varlistentry>
  4446.                           <term><anchor id="nex_copper" />
  4447.                                   SAVENEX COPPER &lt;Page8kNum 0..223&gt;,&lt;offset&gt;
  4448.                           </term>
  4449.                           <listitem>
  4450.                                   <para>
  4451.                                           Can be used after <link linkend="nex_open">OPEN</link> and before first <link
  4452.                                                   linkend="nex_auto">AUTO</link> or <link linkend="nex_bank">BANK</link>
  4453.                                           command (the copper data are stored between screen and bank data).
  4454.                                   </para>
  4455.                                   <para>
  4456.                                           Exactly 2048 bytes are stored (full Copper memory), and the loader will start
  4457.                                           the copper code in mode %01 (reset CPC to 0, then starts the copper), so the
  4458.                                           copper code will wrap around infinitely after the 1024th instruction executed.
  4459.                                           The copper is started after the screen block is loaded and displayed.
  4460.                                   </para>
  4461.                           </listitem>
  4462.                   </varlistentry>
  4463.  
  4464.                   <varlistentry>
  4465.                           <term><anchor id="nex_bank" />
  4466.                                   SAVENEX BANK &lt;bank16k 0..111&gt;[,...]
  4467.                           </term>
  4468.                           <listitem>
  4469.                                   <para>
  4470.                                           Can be used after <link linkend="nex_open">OPEN</link> or <link linkend="nex_screen">
  4471.                                                   SCREEN</link> and before <link linkend="nex_close">CLOSE</link>, but the 16ki
  4472.                                           banks must be saved in correct order: 5, 2, 0, 1, 3, 4, 6, 7, 8, 9, 10, ..., 111
  4473.                                   </para>
  4474.                           </listitem>
  4475.                   </varlistentry>
  4476.                  
  4477.                   <varlistentry>
  4478.                           <term><anchor id="nex_auto" />
  4479.                                   SAVENEX AUTO [&lt;fromBank16k 0..111&gt;[,&lt;toBank16k 0..111&gt;]]
  4480.                           </term>
  4481.                           <listitem>
  4482.                                   <para>
  4483.                                           Can be used after <link linkend="nex_open">OPEN</link> or <link linkend="nex_screen">
  4484.                                                   SCREEN</link> and before <link linkend="nex_close">CLOSE</link>. The sjasmplus
  4485.                                           will save every 16k bank containing at least one non-zero byte; detected in the correct order (automatically
  4486.                                           will save every non-zero 16k bank detected in the correct order (automatically
  4487.                                           starting from first possible bank after previous BANK/AUTO commands, or from
  4488.                                           provided "fromBank").
  4489.                                   </para>
  4490.                                   <para>
  4491.                                           For "fromBank" value use the specified order above in <link linkend="nex_bank">BANK
  4492.                                                   </link> command, i.e. 5, 2, 0, ...
  4493.                                   </para>
  4494.                           </listitem>
  4495.                   </varlistentry>
  4496.                  
  4497.                   <varlistentry>
  4498.                           <term><anchor id="nex_close" />
  4499.                                   SAVENEX CLOSE [&lt;fileToAppend&gt;]
  4500.                           </term>
  4501.                           <listitem>
  4502.                                   <para>
  4503.                                           Can be used after <link linkend="nex_open">OPEN</link>. The currently open NEX
  4504.                                           file will be finalized (header adjusted), and optional extra file just appended
  4505.                                           to the end of NEX file.
  4506.                                   </para>
  4507.                           </listitem>
  4508.                   </varlistentry>
  4509.                  
  4510.           </variablelist>
  4511.  
  4512.  </section>
  4513.          
  4514.  <section>
  4515.           <title><anchor id="s_savenex_examples" />Examples</title>
  4516.  
  4517.           <example>
  4518.          <title>docs_examples/s_savenex_examples.asm</title>
  4519.                   <para>
  4520.                           Creating NEX file which will have Layer2 loading screen (stripes), progress bar, and will
  4521.                           enter infinite loop with calling stack (used by IM 1 interrupt handler) visible on the
  4522.                           Layer 2 screen.
  4523.                   </para>
  4524.                   <programlisting>    DEVICE ZXSPECTRUMNEXT
  4525.    ORG $7E00
  4526. start:  ei : jr $           ; app code entry point, BC = NEX file handle
  4527.    ; Layer2 screen (top 1/3 defined, bottom of it will be used also as "visible" stack)
  4528.    ORG $C000 : DUP 64*32 : DB $90,$91,$92,$93,$94,$95,$96,$97 : EDUP
  4529.  
  4530.    ; write everything into NEX file
  4531.    SAVENEX OPEN "example.nex", start, $FFFE, 9  ; stack will go into Layer2
  4532.    SAVENEX CORE 2, 0, 0        ; Next core 2.0.0 required as minimum
  4533.    SAVENEX CFG 4, 1            ; green border, file handle in BC
  4534.    SAVENEX BAR 1, $E0, 50, 25  ; do load bar, red colour, start/load delays 50/25 frames
  4535.    SAVENEX SCREEN L2 0, 0      ; store the data from C000 (page 0, offset 0), no palette
  4536.    SAVENEX BANK 5, 100, 101    ; store the 16ki banks 5 (contains the code at 0x7E00), 100, 101
  4537.    SAVENEX CLOSE               ; (banks 100 and 101 are added just as example)
  4538.                   </programlisting>
  4539.           </example>
  4540.  </section>
  4541.  
  4542.  </chapter>
  4543.  
  4544.  <chapter>
  4545.    <title><anchor id="c_sld_data" />Source Level Debugging (SLD) data</title>
  4546.  
  4547.    <section>
  4548.                 <title><anchor id="s_sld_intro" />What is it?</title>
  4549.  
  4550.                 <para>
  4551.                         SLD data are extra "tracing" data produced during assembling for debuggers and IDEs,
  4552.                         similar to "map" files already supported by sjasmplus (<link linkend="po_labelslist">
  4553.                         LABELSLIST</link> and <link linkend="po_cspectmap">CSPECTMAP</link>).
  4554.                 </para>
  4555.  
  4556.                 <para>
  4557.                         The debugger can read these data, and with non-tricky source producing machine code
  4558.                         with correct device memory mapping, the debugger can trace the origins of every
  4559.                         instruction back to the original source code line, and display the source instead/along
  4560.                         the disassembly view (the "map" files mentioned above provide only list of labels
  4561.                         which is usually already super helpful, but can't track the source origins of each
  4562.                         instruction).
  4563.                 </para>
  4564.  
  4565.                 <para>
  4566.                         The original impulse and working patch for this feature came from Chris Kirby, adding the
  4567.                         single-instruction-step feature to his development tools: <ulink url="https://github.com/Ckirby101/NDS-NextDevSystem">
  4568.                                 Next Development System</ulink> (currently in 2019 under heavy development).
  4569.                 </para>
  4570.         </section>
  4571.  
  4572.     <section>
  4573.                 <title><anchor id="s_sld_cli" />Usage</title>
  4574.  
  4575.                 <para>
  4576.                         On the sjasmplus side all you need is to add another command line option when starting
  4577.                         the assembler.
  4578.                         <synopsis>prompt$ sjasmplus --sld=project.sld.txt file1.asm file2.asm</synopsis>
  4579.                         This will produce along regular files also file `project.sld.txt` containing the
  4580.                         tracing data. The file format is text-like, so the content can be viewed
  4581.                         in any text editor, but it's supposed to be processed by the debugger.
  4582.                 </para>
  4583.  
  4584.                 <para>
  4585.                         The SLD data are being exported <emphasis role="strong">only</emphasis> for machine code produced
  4586.                         within one of the virtual devices (see <link linkend="s_realdevice">DEVICE</link>).
  4587.                         And the accuracy of the data directly depends on the state of the virtual device at
  4588.                         the moment when the particular instruction is assembled, see next section for further
  4589.                         advice how to get best tracing data.
  4590.                 </para>
  4591.  
  4592.                 <para>
  4593.                         If the option `--sld` without explicit filename is used, the first input source filename
  4594.                         will be copied and its extension changed to `.sld.txt`, which should work well for
  4595.                         single-main file type of projects.
  4596.                 </para>
  4597.  
  4598.         </section>
  4599.  
  4600.         <section>
  4601.                 <title><anchor id="s_sld_source_advice" />How to write "non tricky" source</title>
  4602.  
  4603.                 <para>
  4604.                         For best results (tracing data covering all your instructions and making source-level
  4605.                         debugging available all the time):
  4606.                 </para>
  4607.  
  4608.                 <para>
  4609.                         Generate machine code only with instructions, i.e. while `db 0` in source will produce
  4610.                         `nop` instruction, the tracing data for such `nop` will be missing. Only source line
  4611.                         containing the "nop" will emit both the zero byte into machine code and tracing data.
  4612.                 </para>
  4613.  
  4614.                 <para>
  4615.                         Keep the memory map of the virtual device as it will be set at run-time when writing
  4616.                         particular code. While using only regular <link linkend="po_org">ORG</link> to place
  4617.                         the code in desired memory area, keeping only the modified area with memory pages
  4618.                         mapped-in is enough to get correct SLD data - but when using <link linkend="po_disp">DISP</link>
  4619.                         directive to generate code in displaced way, you need to map-in correct pages in both
  4620.                         memory areas (where the code is currently assembled, and where it is supposed to be
  4621.                         operational at run-time - currently impossible if the two areas share the same SLOT area).
  4622.                 </para>
  4623.  
  4624.                 <para>
  4625.                         To map-in correct pages you can use directives:
  4626.                         <link linkend="po_slot">SLOT</link>, <link linkend="po_page">PAGE</link>,
  4627.                         <link linkend="po_mmu">MMU</link> and <link linkend="po_org">ORG</link>
  4628.                 </para>
  4629.  
  4630.                 <para>
  4631.                         Only labels defined in regular way get also the memory-page data in SLD file, EQU
  4632.                         values are exported without the page information, even if they represent memory
  4633.                         address:
  4634.                         <programlisting>
  4635. regularLabel:   nop             ; current page exported to SLD data
  4636. equLabel        EQU   $8000     ; only value without page is exported
  4637. varSymbol       =     14        ; =/DEFL labels are omitted completely</programlisting>
  4638.                 </para>
  4639.  
  4640.                 <para>
  4641.                         Re-using the same memory area (page + address) for two different pieces of code (for
  4642.                         example by having multiple routines targeting the same address with DISP, and run-time
  4643.                         code uploading the correct variant dynamically at the destination) will highly likely
  4644.                         confuse the debugger, producing two source-origins data for the identical address.
  4645.                         You may want to avoid this, especially with early version of tools not being able to
  4646.                         resolve such ambiguity in reasonable way (the sjasmplus will generate tracing data ok
  4647.                         even in this case, but they are tricky to interpret).
  4648.                 </para>
  4649.  
  4650.                 <para>
  4651.                         If you are using the colons to put multiple instructions on single line, verify the
  4652.                         debugger can cope with the tracing data containing full line + column begin/end
  4653.                         information, the simple/early tools will likely highlight only whole line of source.
  4654.                         For a start keeping single instruction per line may keep things simple.
  4655.                 </para>
  4656.  
  4657.                 <para>
  4658.                         The multi-arg instructions produce the tracing data only for the first instruction,
  4659.                         which will probably cause problems with single-stepping through such code. Rather
  4660.                         avoid multi-arg syntax when you are planning to debug the code.
  4661.                 </para>
  4662.  
  4663.                 <para>
  4664.                         The various code generators written in macros or Lua scripts will produce accurate
  4665.                         tracing data in case of macros, and condensed (pointing at "ENDLUA" line) data for
  4666.                         Lua generators, but it still depends on the debugger if it can display both top
  4667.                         level source code triggering the generator and source lines containing definitions
  4668.                         of particular instructions.
  4669.                 </para>
  4670.  
  4671.         </section>
  4672.  
  4673.    <section>
  4674.                 <title><anchor id="s_sld_file_format" />SLD File Format definition (version "0")</title>
  4675.  
  4676.                 <para>The SLD data is text-file (sjasmplus is using UNIX-like newlines 0x0A, but parsers
  4677.                         should rather cope with any of common EOL scheme). The general format is CSV-like
  4678.                         using pipe character as delimiter between fields.
  4679.                 </para>
  4680.  
  4681.                 <para>
  4682.                         If the first field is empty, the line is one of the special control lines - the second
  4683.                         field selects type of control line. If also the second field is empty, the remaining
  4684.                         part of line should be ignored (comment line).
  4685.                         Currently only one type of "control line" exists, the "SLD.data.version" (third
  4686.                         field is integer number):
  4687. <programlisting>|SLD.data.version|0
  4688. ||anything ... comment-like line</programlisting>
  4689.                         The file format version line should be always first line of the SLD data file.
  4690.                 </para>
  4691.  
  4692.                 <para>
  4693.                         The regular tracing data lines have fixed amount of fields: eight. The seventh field
  4694.                         contains single uppercase letter defining type of the line, which affects sub-variants
  4695.                         of format for eighth field, but first six fields share the same formatting and meaning
  4696.                         across all types of regular lines:
  4697. <programlisting>
  4698. &lt;source file&gt;|&lt;src line&gt;|&lt;definition file&gt;|&lt;def line&gt;|&lt;page&gt;|&lt;value&gt;|&lt;type&gt;|&lt;data&gt;
  4699. </programlisting>
  4700.                 </para>
  4701.  
  4702.                 <para>
  4703.                         <code>&lt;source file&gt;</code> - file name of top-level source emitting the
  4704.                         instruction/label/device.
  4705.                 </para>
  4706.  
  4707.                 <para>
  4708.                         <code>&lt;src line&gt;</code> - line and characters in top-level source file, the precise
  4709.                         format is "<code>&lt;line&gt;[:&lt;column begin&gt;[:&lt;column end&gt;]]</code>" where
  4710.                         first number is line number (starting at 1). The two following numbers delimited by colon
  4711.                         are optional, representing the column where the segment starts/ends at the line. The
  4712.                         column values are starting from 1 too, the "end" column is pointing beyond the current
  4713.                         segment. The columns are in "bytes", i.e. tabulator does increase the column value by +1
  4714.                         only, and the "end" may actually point well beyond "strlen(line)".
  4715.                 </para>
  4716.  
  4717.                 <para>
  4718.                         <code>&lt;definition file&gt;</code> - file name of the source defining the particular
  4719.                         instruction (for example where the instruction inside MACRO was originally defined).
  4720.                         If empty, the definition-file name is identical to <code>&lt;source file&gt;</code>
  4721.                         (common case for single-source projects).
  4722.                 </para>
  4723.  
  4724.  
  4725.                 <para>
  4726.                         <code>&lt;def line&gt;</code> - zero when there is no extra "definition" of instruction
  4727.                         involved. When non-zero, the format is identical to <code>&lt;src line&gt;</code>, but
  4728.                         with regard to the file specified in <code>&lt;definition file&gt;</code> field.
  4729.                 </para>
  4730.  
  4731.                 <para>
  4732.                         <code>&lt;page&gt;</code> - number of memory page where the <code>&lt;value&gt;</code>
  4733.                         address points to, or -1 when value is not memory address.
  4734.                 </para>
  4735.  
  4736.                 <para>
  4737.                         <code>&lt;value&gt;</code> - any 32 bit integer value (EQU), but when representing memory
  4738.                         address, it is full 16 bit value from Z80 address space (the top bits beyond the memory
  4739.                         page size contains the number of "slot" where the instruction/label resides).
  4740.                 </para>
  4741.  
  4742.                 <para>
  4743.                         <code>&lt;type&gt;</code> - single uppercase letter representing type of line, current
  4744.                         types: T (instruction Trace), F (Function), D (equ Data), Z (device memory model)
  4745.                 </para>
  4746.  
  4747.                 <para>
  4748.                         <code>&lt;data&gt;</code> - extra data specific for particular line type. Empty for
  4749.                         "T" lines, contains label/symbol name for types "F" and "D". The "D" values usually
  4750.                         don't have page defined (equals -1), but the tools should accept also valid page
  4751.                         value for "D" type too, just like for "F" lines.
  4752.                 </para>
  4753.  
  4754.                 <para>
  4755.                         For type "Z" the data field contains string describing the device memory model which
  4756.                         is being selected in source and should be applied for following SLD data lines. The
  4757.                         memory model string format is:
  4758. <programlisting>
  4759. pages.size:&lt;page size&gt;,pages.count:&lt;page count&gt;,slots.count:&lt;slots count&gt;[,slots.adr:&lt;slot0 adr&gt;,...,&lt;slotLast adr&gt;]
  4760. // unsigned &lt;page size&gt; is also any-slot size in current version.
  4761. // unsigned &lt;page count&gt; and &lt;slots count&gt; define how many pages/slots there are
  4762. // uint16_t &lt;slotX adr&gt; is starting address of slot memory region in Z80 16b addressing
  4763. </programlisting>
  4764.                 </para>
  4765.  
  4766.                 <example>
  4767.                         <title>Example of SLD file</title>
  4768.  
  4769. <programlisting>
  4770. |SLD.data.version|0
  4771. || ZX Spectrum Next device description:
  4772. 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
  4773. || label "main" points to 32768, with page 14 mapped-in (defined in toplevel.asm:62)
  4774. toplevel.asm|62||0|14|32768|F|main
  4775. || instruction opcode at 32768 (page 14) was created by toplevel.asm:64
  4776. toplevel.asm|64||0|14|32768|T|
  4777. || instruction opcode at 32769 (p 14) was created by toplevel.asm:67
  4778. || (but it is a line using macro, the instruction was defined by toplevel.asm:52)
  4779. toplevel.asm|67||52|14|32769|T|
  4780. || instruction opcode at 32770 (p 18) was created by toplevel.asm:68:12-24
  4781. toplevel.asm|68:12:24||0|18|32770|T|
  4782. || instruction opcode at 32771 (p 18) was created by toplevel.asm:68:24 (till EOL)
  4783. toplevel.asm|68:24||0|18|32771|T|
  4784. || "PORT_NUMBER EQU 254" defined at toplevel.asm:69
  4785. toplevel.asm|69||0|-1|254|D|PORT_NUMBER
  4786. || label+instruction emitted from toplevel.asm:70, but defined in include.asm:3
  4787. toplevel.asm|70|include.asm|3|37|40976|F|0>macro_defined_in_include_asm
  4788. toplevel.asm|70|include.asm|3|37|40976|T|
  4789. </programlisting>
  4790.  
  4791.                 </example>
  4792.  
  4793. </section>
  4794.  
  4795.   </chapter>
  4796.  
  4797. </book>
  4798.