?login_element?

Subversion Repositories NedoOS

Rev

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