?login_element?

Subversion Repositories NedoOS

Rev

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

  1. <!DOCTYPE html><html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>SjASMPlus 1.15.1 Documentation [2020-07-07]</title><link rel="stylesheet" type="text/css" href="docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book"><div class="titlepage"><div><div><h1 class="title"><a name="idp1"></a>SjASMPlus 1.15.1 Documentation [2020-07-07]</h1></div></div><hr></div><div class="toc"><dl class="toc"><dt><span class="chapter"><a href="#idp8">1. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#idp2">License</a></span></dt><dt><span class="section"><a href="#idp3">What is it?</a></span></dt><dt><span class="section"><a href="#idp4">Main Features</a></span></dt><dt><span class="section"><a href="#idp5">Credits</a></span></dt><dt><span class="section"><a href="#idp6">Feedback</a></span></dt><dt><span class="section"><a href="#idp7">What's new?</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp12">2. Where to get and how to use</a></span></dt><dd><dl><dt><span class="section"><a href="#idp9">Packages</a></span></dt><dt><span class="section"><a href="#idp10">Command line</a></span></dt><dt><span class="section"><a href="#idp11">Source file format</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp17">3. Labels</a></span></dt><dd><dl><dt><span class="section"><a href="#idp13">Labels</a></span></dt><dt><span class="section"><a href="#idp14">Local labels</a></span></dt><dt><span class="section"><a href="#idp15">@ Labels</a></span></dt><dt><span class="section"><a href="#idp16">Temporary labels</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp25">4. Constants, expressions and other features</a></span></dt><dd><dl><dt><span class="section"><a href="#idp18">Numeric constants</a></span></dt><dt><span class="section"><a href="#idp19">Character and string constants</a></span></dt><dt><span class="section"><a href="#idp20">Expressions</a></span></dt><dt><span class="section"><a href="#idp21">Assembly language</a></span></dt><dt><span class="section"><a href="#idp22">Fake instructions</a></span></dt><dt><span class="section"><a href="#idp23">Real device emulation mode</a></span></dt><dt><span class="section"><a href="#idp24">Predefined defines</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp30">5. Pseudo-ops (aka Pseudo-instructions, Directives etc)</a></span></dt><dd><dl><dt><span class="section"><a href="#idp26">Simple example of usage</a></span></dt><dt><span class="section"><a href="#idp27">Almost complete list</a></span></dt><dt><span class="section"><a href="#idp28">Conditional assembly</a></span></dt><dt><span class="section"><a href="#idp29">Macros</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp36">6. Structures</a></span></dt><dd><dl><dt><span class="section"><a href="#idp31">What is it?</a></span></dt><dt><span class="section"><a href="#idp32">Defining structure</a></span></dt><dt><span class="section"><a href="#idp33">Instructions</a></span></dt><dt><span class="section"><a href="#idp34">Usage of defined structure</a></span></dt><dt><span class="section"><a href="#idp35">Examples</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp42">7. Lua scripting</a></span></dt><dd><dl><dt><span class="section"><a href="#idp37">Why?</a></span></dt><dt><span class="section"><a href="#idp38">How to use?</a></span></dt><dt><span class="section"><a href="#idp39">SjASMPlus binded functions</a></span></dt><dt><span class="section"><a href="#idp40">Third-party embedded library(ies)</a></span></dt><dt><span class="section"><a href="#idp41">Example</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp46">8. SAVENEX guide</a></span></dt><dd><dl><dt><span class="section"><a href="#idp43">NEX File Format</a></span></dt><dt><span class="section"><a href="#idp44">Detailed description of each SAVENEX command</a></span></dt><dt><span class="section"><a href="#idp45">Examples</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp51">9. Source Level Debugging (SLD) data</a></span></dt><dd><dl><dt><span class="section"><a href="#idp47">What is it?</a></span></dt><dt><span class="section"><a href="#idp48">Usage</a></span></dt><dt><span class="section"><a href="#idp49">How to write "non tricky" source</a></span></dt><dt><span class="section"><a href="#idp50">SLD File Format definition (version "0")</a></span></dt></dl></dd></dl></div>
  2.  
  3.  
  4.  <div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="idp8"></a>Chapter 1. Introduction</h1></div></div></div>
  5.    
  6.  
  7.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2"></a>License</h2></div></div></div>
  8.      
  9.  
  10.      <p>SjASMPlus is licensed under BSD license.</p>
  11.    </div>
  12.  
  13.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3"></a>What is it?</h2></div></div></div>
  14.      
  15.  
  16.      <p>
  17.                 SjASMPlus is Z80 Assembly Language Cross Compiler. It is available
  18.                 for Win32, Linux and FreeBSD (mainly 5.x) systems. It is based on SjASM
  19.                 source code by Sjoerd Mastijn (<a class="ulink" href="http://xl2s.tk" target="_top">http://xl2s.tk</a>).
  20.           </p>
  21.    </div>
  22.  
  23.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp4"></a>Main Features</h2></div></div></div>
  24.      
  25.  
  26.      <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  27.            <p>Full source of assembler available under BSD license, modify and extend as you wish</p>
  28.          </li><li class="listitem">
  29.            <p>Z80/R800/Z80N/i8080/LR35902 documented and undocumented opcodes support</p>
  30.          </li><li class="listitem">
  31.            <p>Macro language, defines, array of defines</p>
  32.          </li><li class="listitem">
  33.            <p>Built-in Lua scripting engine</p>
  34.          </li><li class="listitem">
  35.            <p>Conditional assembly, block repeating</p>
  36.          </li><li class="listitem">
  37.            <p>Modules (namespaces), local and temporary labels</p>
  38.          </li><li class="listitem">
  39.            <p>Source and binary file inclusion, include paths</p>
  40.          </li><li class="listitem">
  41.            <p>Multi file output, file updating, various types of exports</p>
  42.          </li><li class="listitem">
  43.            <p>Structures to work easily with structured data in memory</p>
  44.          </li><li class="listitem">
  45.            <p>Virtual device mode for common machines: ZX 128, ZX Next, … (pseudo op DEVICE)</p>
  46.          </li><li class="listitem">
  47.            <p>ZX Spectrum specific directives and pseudo ops (SAVESNA, SAVETAP, SAVEHOB, INCHOB, INCTRD…)</p>
  48.          </li><li class="listitem">
  49.            <p>ZX Spectrum Next specific features and directives (Z80N, 8ki memory paging, SAVENEX)</p>
  50.          </li><li class="listitem">
  51.            <p>Correctness is assured by <a class="ulink" href="https://cirrus-ci.com/github/z00m128/sjasmplus/master" target="_top">
  52.            Cirrus-CI with 240+ automated tests</a> (that's also 240+ examples of usage!)</p>
  53.           </li><li class="listitem">
  54.             <p>Fake instructions as LD HL,DE (LD H,D:LD L,E) and more</p>
  55.           </li><li class="listitem">
  56.             <p>Code inlining through colon (LD A,C:INC A:PUSH AF:IFDEF FX:LD A,D:ENDIF…)</p>
  57.           </li><li class="listitem">
  58.             <p>Very fast compilation: 1 million lines by 2-3 seconds on modern computer</p>
  59.           </li><li class="listitem">
  60.             <p>Multiline block comments and user’s messages</p>
  61.           </li></ul></div>
  62.     </div>
  63.  
  64.     <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp5"></a>Credits</h2></div></div></div>
  65.      
  66.  
  67.       <p>Special thanks to <span class="emphasis"><em>Sjoerd Mastijn</em></span>, the author of SjASM.</p>
  68.  
  69.       <p><span class="emphasis"><em>Aprisobal </em></span>- main programming, documentation, etc.</p>
  70.  
  71.       <p>Thanks to:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  72.             <p><span class="emphasis"><em>Kurles/HS/CPU, Alexander Kovalenko, Ped7g</em></span> - additional
  73.             programming;</p>
  74.           </li><li class="listitem">
  75.             <p><span class="emphasis"><em>Krystian Wlosek
  76.             &lt;kwlosek(at)gmail.com&gt;</em></span> - bug fix patches, Linux
  77.             makefile;</p>
  78.           </li><li class="listitem">
  79.             <p><span class="emphasis"><em>Ric Horne &lt;Ric.Hohne@eads-ts.com&gt;</em></span>
  80.             - bug fix patches.</p>
  81.           </li><li class="listitem">
  82.             <p><span class="emphasis"><em>breeze &lt;breeze@tut.by&gt;</em></span> - bug fix
  83.             patches.</p>
  84.           </li><li class="listitem">
  85.             <p><span class="emphasis"><em>psndcj &lt;psndcj.tbk@gmail.com&gt;</em></span> -
  86.             bug reporting, beta-testing.</p>
  87.           </li><li class="listitem">
  88.             <p><span class="emphasis"><em>elfh &lt;elphecy@gmail.com&gt;</em></span> - bug
  89.             reporting.</p>
  90.           </li><li class="listitem">
  91.             <p><span class="emphasis"><em>bugsy &lt;bugsy@ya.ru&gt;</em></span> - bug
  92.             reporting.</p>
  93.           </li><li class="listitem">
  94.             <p><span class="emphasis"><em>skrju &lt;sq-@mail.ru&gt;</em></span> - bug
  95.             reporting.</p>
  96.           </li><li class="listitem">
  97.             <p><span class="emphasis"><em>Tygrys, UB880D, Cizo, mborik, z00m</em></span> -
  98.             compilation errors and warnings clean up, makefiles, testing.</p>
  99.           </li><li class="listitem">
  100.             <p><span class="emphasis"><em>Antipod, boo_boo, PulkoMandy, Busy, Liniya, Dart Alver</em></span> -
  101.             bug fix patches, testing.</p>
  102.           </li><li class="listitem">
  103.             <p><span class="emphasis"><em>CKirby</em></span> - SLD export and support in his tools.</p>
  104.           </li></ul></div>
  105.  
  106.       <p>Big thanks to all people, who helped on development of the compiler!</p>
  107.     </div>
  108.  
  109.     <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp6"></a><a name="feedback"></a>Feedback</h2></div></div></div>
  110.      
  111.  
  112.       <p>WWW: <a class="ulink" href="https://github.com/z00m128/sjasmplus" target="_top">https://github.com/z00m128/sjasmplus</a>
  113.       (newer versions maintained by z00m and others)</p>
  114.  
  115.       <p>WWW: <a class="ulink" href="https://sourceforge.net/projects/sjasmplus/" target="_top">https://sourceforge.net/projects/sjasmplus/</a>
  116.       (original Aprisobal's source)</p>
  117.  
  118.      <p>E-Mail: zoom@centrum.sk, my@aprisobal.by</p>
  119.    </div>
  120.  
  121.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp7"></a>What's new?</h2></div></div></div>
  122.      
  123.  
  124.       <div class="variablelist"><dl class="variablelist"><dt><span class="term">WIP - 1.15.2</span></dt><dd>
  125.               <pre class="synopsis">- <a class="link" href="#po_lua">`LUA`</a> thew new emit warning (v1.15.1) is now suppressible
  126. - <a class="link" href="#s_predefined">Predefined defines</a> extended and renamed (following gcc/clang ones)
  127. - bugfixes/improvements in parser like: operators `not`, `low`, `high` can be followed also by "("
  128. </pre>
  129.             </dd><dt><span class="term">7.7.2020 - 1.15.1</span></dt><dd>
  130.               <pre class="synopsis">- <a class="link" href="#po_equ">`EQU`</a> now assigns memory page to symbol based on the symbol value and current memory mapping
  131. - this does affect also results of <a class="link" href="#po_labelslist">`LABELSLIST`</a> (<a class="ulink" href="https://github.com/z00m128/sjasmplus/issues/111" target="_top">Issue #111</a>)
  132. - <a class="link" href="#po_lua">`LUA`</a> emits warning when some machine code is emitted without "ALLPASS" modifier
  133. - <a class="link" href="#po_savetrd">`SAVETRD`</a> refactored: fix couple of bugs and make TRD files conform the actual TR-DOS practice
  134. - `SAVETRD`: new "&amp;" modifier to produce "mono-loaders" with extra files appended
  135. - `SAVETRD`: added support for the unofficial 3-letter extensions ("; ok" to suppress warnings)
  136. - <a class="link" href="#po_inctrd">`INCTRD`</a> refactored and added support for unofficial 3-letter extensions
  137. - fix <a class="ulink" href="https://github.com/z00m128/sjasmplus/issues/108" target="_top">issue #108</a> to detect windows drive letters at beginning of file names with full windows paths
  138. - bugfixes: RAMTOP w/ global device, "r+w" file operations code review, memory buffer overrun in LUA</pre>
  139.             </dd><dt><span class="term">18.5.2020 - 1.15.0</span></dt><dd>
  140.               <pre class="synopsis">- added <a class="link" href="#po_bplist">`BPLIST`</a> and <a class="link" href="#po_setbp">`SETBP`</a> to export breakpoints info from asm for Unreal and ZEsarUX emulators
  141. - added ZX-like <a class="link" href="#po_device">devices</a> with 2/4/8 MiB of virtual memory
  142. - the fake-sysvars/state of ZXSPECTRUM48/128/... devices reworked, moving stack down by default
  143. - behaviour of <a class="link" href="#s_cli">`--fullpath`</a> option unified across all platforms and compilers
  144. - <a class="link" href="#po_defarray">`DEFARRAY`</a> has new operator `[#]` to retrieve current size of array.
  145. - <a class="link" href="#po_mmu">`MMU`</a> has new optional third argument to set also address (like ORG)
  146. - use of forward reference in <a class="link" href="#ca_if">IF/IFN</a> emits only warning, and can be suppressed
  147. - internal Lua updated to 5.1.5 (last official 5.1 version), STDIN can be read multiple times
  148. - new <a class="ulink" href="https://github.com/z00m128/sjasmplus/tree/master/tests/macro_examples" target="_top">macro_examples</a>: `sj_sysvars.i.asm` and `section.asm`, new <a class="ulink" href="https://github.com/z00m128/sjasmplus/tree/master/tests/lua_examples" target="_top">lua_examples</a>: `lua_sin_table.asm`
  149. - RAM limit exceeded warning/error reworked to report with more sense, fixed bug with missing labels
  150. - <a class="link" href="#po_savetrd">`SAVETRD`</a> warning about invalid extension can be suppressed by "; ok"
  151. - <a class="link" href="#po_emptytrd">`EMPTYTRD`</a> takes as second argument disc label
  152. - added <a class="link" href="#s_cli">`--outprefix`</a> option to prefix any output-directive filename (<a class="ulink" href="https://github.com/z00m128/sjasmplus/issues/102" target="_top">issue #102</a>)</pre>
  153.             </dd><dt><span class="term">30.1.2020 - 1.14.5</span></dt><dd>
  154.               <pre class="synopsis">- fix crash when opening source file fails
  155. - <a class="link" href="#po_disp">`DISP`</a>/<a class="link" href="#po_org">`ORG`</a> warns about being used inside DISP block (also docs extended)
  156. </pre>
  157.             </dd><dt><span class="term">13.1.2020 - 1.14.4</span></dt><dd>
  158.               <pre class="synopsis">- added few example utility macros in tests/macro_examples/sj_library.asm (neg r16)
  159. - added <a class="link" href="#nex_screen">`SAVENEX SCREEN BMP`</a> sub-command to include BMP loading-screen
  160. - added support for V1.3 of <a class="link" href="#c_savenex">`NEX file format`</a> (new commands: CFG3, PALETTE, COPPER, new screen modes)
  161. - in lua scripts: `sj.calc(..)` (alias `_c(..)`) now substitutes defines and macro arguments
  162. - error reporting inside LUA and MACRO refactored to give better info about origin of error
  163. - macro-arguments parser now recognizes C++ numeric literals with apostrophe as digits-group separator
  164. - the assembler will instantly exit when run at Big-Endian platform (the rest of code is broken on BE)
  165. - updated syntax-highlight file for KDE5 editors (Kate)</pre>
  166.             </dd><dt><span class="term">15.11.2019 - 1.14.3</span></dt><dd>
  167.               <pre class="synopsis">- fix detection of `.end:` and `.END` labels when `--dirbol` is used
  168. - added export of <a class="link" href="#c_sld_data">SLD (Source Level Debugging) data</a>, see also <a class="ulink" href="https://github.com/Ckirby101/NDS-NextDevSystem" target="_top">NDS (NextDevSystem)</a>
  169. - added <a class="link" href="#s_cli">`--longptr`</a> option to allow labels outside of 16b address space
  170. - docs: added small details about <a class="link" href="#po_fpos">FPOS</a>, <a class="link" href="#po_savetap">SAVETAP</a>, <a class="link" href="#ca_ifused">IFUSED</a>
  171. - fix assembling-time reported in linux</pre>
  172.             </dd><dt><span class="term">3.10.2019 - 1.14.2</span></dt><dd>
  173.               <pre class="synopsis">- added i8080 mode (--i8080 CLI option) (it's still Z80 Zilog syntax, just limited instruction set)
  174. - added Sharp LR35902 mode (--lr35902 CLI option) (100% syntax compatibility with IDA, 95% bgb)
  175. - new <a class="link" href="#s_expressions">$$label operator</a> to retrieve page of label
  176. - 1.14.0 include-path bugfix reverted, the "." is again <a class="link" href="#po_include">automatically added</a> (*did* break projects)
  177. - small improvements/polish/extra-info in docs, INSTALL, README, few new tests added
  178. - cmake script fix of SYSTEM_LUA=ON option, <a class="ulink" href="https://cirrus-ci.com/github/z00m128/sjasmplus/master" target="_top">CirrusCI</a> configs added for macOS and FreeBSD
  179. - few fixes of memory leaks, invalid memory access, double free/delete, ...
  180. </pre>
  181.            </dd><dt><span class="term">30.8.2019 - 1.14.1</span></dt><dd>
  182.              <pre class="synopsis">- refactored <a class="link" href="#po_shellexec">SHELLEXEC</a> to use clib "system(..)" on all platforms (also MS VS), minor fixes
  183. - <a class="ulink" href="https://github.com/z00m128/sjasmplus/blob/master/tests/lua_examples/lua_inctext.lua" target="_top">lua example "inc_text"</a> (result of specific request from sjasmplus user)
  184. - listing fixed when Lua was used to emit bytes and also parsed lines of assembly source
  185. - MinGW windows exe prefers "/" file system delimiter ("\" should still work on windows (only))
  186. - lot of small bugfixes and Cirrus CI infrastructure adjustments (windows MinGW build does run full tests)
  187. - MS VS builds stabilized and fixed, should now work mostly on par with MinGW builds (99.5%)
  188. - Using <a class="ulink" href="https://lgtm.com/projects/g/z00m128/sjasmplus/" target="_top">lgtm.com</a> code analysis (did help to find new bugs and memory leaks)
  189. - <a class="ulink" href="https://github.com/unittest-cpp/unittest-cpp" target="_top">UnitTest++</a> framework added for regular C++ unit tests, first few tests added
  190. </pre>
  191.            </dd><dt><span class="term">17.8.2019 - 1.14.0</span></dt><dd>
  192.              <pre class="synopsis">- <a class="link" href="#po_include">INCLUDE</a> bugfix, now searching paths according to original documentation (may break some projects)
  193. - <a class="link" href="#po_undefine">UNDEFINE</a> had undocumented feature of removing also labels, cancelled (was broken beyond repair)
  194. - R800 `MULUB` was producing wrong opcode all those years... fixed
  195. - <a class="link" href="#po_module">MODULE</a> names can't contain dot any more! MODULE and ENDMODULE resets non-local label to "_"
  196. - <a class="link" href="#s_cli">--syntax</a> option: "m" (switch off low-mem access warning) and "M" added, "A" removed
  197. - <a class="link" href="#s_macros">macro</a> expansion can be inhibited by using "@" in front of instruction
  198. - expression evaluator was not strictly 32 bit (64b binaries could have produced different results than 32b binaries)
  199. - reading memory addresses 0..255 directly emits warning, use "; ok" comment to suppress it.
  200. - several tests added to improve the code coverage: <a class="ulink" href="https://coveralls.io/github/z00m128/sjasmplus?branch=master" target="_top">coveralls.io/github/z00m128/sjasmplus</a>
  201. - as tests were added, minor bugs were found and squashed (errors wording, etc)</pre>
  202.             </dd></dl></div>
  203.  
  204.       <p>See <a class="ulink" href="https://github.com/z00m128/sjasmplus/blob/master/CHANGELOG.md" target="_top">CHANGELOG.md</a> for full list of changes.</p>
  205.     </div>
  206.   </div>
  207.  
  208.   <div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="idp12"></a>Chapter 2. Where to get and how to use</h1></div></div></div>
  209.    
  210.  
  211.     <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp9"></a>Packages</h2></div></div></div>
  212.      
  213.  
  214.         <p>
  215.                 The <span class="strong"><strong>latest release</strong></span> of this sjasmplus variant is
  216.                 <span class="strong"><strong>available at <a class="ulink" href="https://github.com/z00m128/sjasmplus/releases/latest" target="_top">
  217.                                 https://github.com/z00m128/sjasmplus/releases/latest</a></strong></span>
  218.                 - there is available zip archive with <span class="strong"><strong>windows binary</strong></span>
  219.                 (toward <span class="strong"><strong>bottom of the page</strong></span>), and zip archives with
  220.                 <span class="strong"><strong>full source code</strong></span> of the sjasmplus.
  221.         </p>
  222.  
  223.         <p>Win32 package has:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  224.             <p>sjasmplus.exe - the Win32 executable.</p>
  225.           </li><li class="listitem">
  226.             <p>examples directory - some examples of use</p>
  227.           </li><li class="listitem">
  228.             <p>documentation directory - documentation in various
  229.             formats</p>
  230.           </li></ul></div><p>
  231.         </p>
  232.  
  233.         <p>
  234.                 You may want to download also the full source package, as it contains more than 240
  235.                 <span class="strong"><strong>automated tests</strong></span> used to verify correctness of executable,
  236.                 and these can be often helpful to better understand how specific feature of sjasmplus works,
  237.                 and <span class="strong"><strong>how to use it</strong></span> effectively.
  238.         </p>
  239.  
  240.         <p>
  241.                 <span class="strong"><strong>Linux, Unix, MacOS</strong></span> and <span class="strong"><strong>BSD</strong></span>
  242.                 version can be built from the full source archive. You can compile it using <span class="emphasis"><em>GCC</em></span>
  243.                 and included <span class="emphasis"><em>Makefile</em></span>. There is an option to use <span class="emphasis"><em>CMake</em></span>
  244.                 for compilation. See
  245.                 <a class="ulink" href="https://github.com/z00m128/sjasmplus/blob/master/INSTALL.md" target="_top">INSTALL.md</a> for details.
  246.         </p>
  247.  
  248.       <p>Windows binaries are compiled with <span class="emphasis"><em>MinGW</em></span> environment and included
  249.                   <span class="emphasis"><em>Makefile.win</em></span> file.</p>
  250.  
  251.       <p>You can grab older (up to v1.07) binaries and sources at SourceForge project page:
  252.       <a class="ulink" href="https://sourceforge.net/projects/sjasmplus/" target="_top">https://sourceforge.net/projects/sjasmplus/</a></p>
  253.  
  254.     </div>
  255.  
  256.     <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp10"></a><a name="s_cli"></a>Command line</h2></div></div></div>
  257.      
  258.  
  259.       <p>Usage:</p>
  260.  
  261.       <pre class="synopsis">sjasmplus [options] sourcefile(s)</pre>
  262.  
  263.       <p>Option flags as follows:</p>
  264.  
  265.       <pre class="synopsis">  -h or --help             Help information
  266.   --version                Basic info (with --nologo only raw version string)
  267.   --zxnext[=cspect]        Enable ZX Next Z80 extensions (CSpect emulator has
  268.   extra "exit" DD00 and "break" DD01 fake instructions)
  269.   --i8080                  Limit valid instructions to i8080 only (+ no fakes)
  270.   --lr35902                Sharp LR35902 CPU instructions mode (+ no fakes)
  271.   --outprefix=&lt;path&gt;       Prefix for save/output/.. filenames in directives
  272.   Note: if the prefix is folder, the folder must exist before assembling. Prefix
  273.         is applied only to filenames defined in source (not to CLI arguments).
  274.   -i&lt;path&gt; or -I&lt;path&gt; or --inc=&lt;path&gt; ( --inc without "=" to empty the list)
  275.                            Include path (later defined have higher priority)
  276.   --lst[=&lt;filename&gt;]       Save listing to &lt;filename&gt; (&lt;source&gt;.lst is default)
  277.   --lstlab                 Enable label table in listing
  278.   --sym=&lt;filename&gt;         Save symbols list to &lt;filename&gt;
  279.   --exp=&lt;filename&gt;         Save exports to &lt;filename&gt; (see EXPORT pseudo-op)
  280.   --raw=&lt;filename&gt;         Machine code saved also to &lt;filename&gt; (- is STDOUT)
  281.   --sld[=&lt;filename&gt;]       Save Source Level Debugging data to &lt;filename&gt;
  282.                            Default name is: "&lt;first input filename&gt;.sld.txt"
  283.   Note: use OUTPUT,LUA/ENDLUA and other pseudo-ops to control output
  284.  Logging:
  285.   --nologo                 Do not show startup message
  286.   --msg=[all|war|err|none|lst|lstlab]  Stderr messages verbosity ("all" is default)
  287.   Note: "lst" or "lstlab" will turn STDERR into listing file (this will clash with
  288.   `--lst`, use only one of the options) and some diagnostic messages of "all"
  289.   are omitted, as they are not part of listing files.
  290.   --fullpath               Show full path to file in errors
  291.   Note: the "fullpath" starts from current working directory, not from file system
  292.                 root (the MS_VS build was fixed to behave this way since v1.15.0)
  293.  Other:
  294.   -D&lt;NAME&gt;[=&lt;value&gt;]       Define &lt;NAME&gt; as &lt;value&gt;
  295.   -                        Reads STDIN as source (even in between regular files)
  296.   --longptr                No device: program counter $ can go beyond 0x10000
  297.   --reversepop             Enable reverse POP order (as in base SjASM version)
  298.   --dirbol                 Enable directives processing from the beginning of line
  299.   --nofakes                Disable fake instructions (obsolete, use --syntax=F)
  300.   --dos866                 Encode from Windows codepage to DOS 866 (Cyrillic)
  301.   --syntax=&lt;...&gt;           Adjust parsing syntax, read details below.</pre>
  302.  
  303.   <p>Value for <code class="code">--syntax</code> option may consist of multiple letters, omitting letter
  304.         for particular feature will use the default setting:
  305.         </p><pre class="synopsis">  a      Multi-argument delimiter ",," (default is ",")
  306.   b      Whole expression parentheses are legal for memory access only (default = immediate or memory)
  307.   B      memory access brackets [] required (default = relaxed syntax, [] allowed as extra)
  308.   f F    Fake instructions: warning / disabled (default = enabled)
  309.   i      Case insensitive instructions/directives (default = same case required)
  310. † <span class="emphasis"><em>l L    Keyword labels (registers, instructions, ...): warning / error (default = silent)</em></span>
  311.   m      Switch off "Accessing low memory" warning globally
  312.   M      Alias "m" and "M" for "(hl)" to cover 8080-like syntax: ADD A,M
  313.   w      Warnings option: report warnings as errors</pre><p>
  314.   † work in progress: options "l" and "L" are not implemented yet, following example is then
  315.   not working correctly either.
  316.   </p>
  317.   <p>
  318.   I.e. <code class="code">--syntax=faBil</code> will modify parser to process source line
  319.   </p><pre class="programlisting">hl:  Ld a,(hl),,de,hl</pre><p>
  320.   in a way to produce warnings about keyword "hl" being used for label, about fake instruction
  321.   being used (ld de,hl) and assemble <code class="code">(hl)</code> as numeric expression, not memory access.
  322.   Warnings on fake instructions can be suppressed for particular line by adding any end-of-line
  323.   comment containing string "fake", i.e. "<code class="code">ld de,hl ; fake DE=HL</code>" will assemble
  324.   without warning. The "F" option is identical to "--nofakes" and preferred.
  325.   </p>
  326.  
  327.   <p>
  328.   The recommended setup for new projects is <code class="code">--syntax=abfw</code> which makes syntax less relaxed,
  329.   so some typos and mistakes are easier to catch, for example:
  330.   </p><pre class="programlisting">        OPT reset --syntax=abfw
  331. label:  dw 15
  332.         ld b,(label)
  333.         sub a,b</pre><p> will produce "error: Illegal instruction
  334.  (can't access memory): (label)" message for the <code class="code">ld b,(label)</code> and the <code class="code">sub a,b</code>
  335.   will produce only the <code class="code">sub b</code> instruction (to give the <code class="code">sub</code> multi-argument
  336.   with syntax option "a" the line would have to be <code class="code">sub a,,b</code>).
  337.   </p>
  338.  
  339.   <p>
  340.           The assembler will also read the environment variable <code class="code">SJASMPLUSOPTS</code> (if available),
  341.           and process its content as part of command line options (before the actual options), so you
  342.           can pre-configure certain options in your environment, for example:
  343.           </p><pre class="programlisting">export SJASMPLUSOPTS="--zxnext=cspect --msg=war"
  344. sjasmplus --lst --lstlab example.asm</pre><p>
  345.         will execute the assembling as if command line "<code class="code">sjasmplus --zxnext=cspect --msg=war --lst --lstlab example.asm</code>"
  346.         was used. Known issue: parser of environment variable delimits each option on any white-space character, so
  347.         option containing space character will be incorrectly parsed (like "-Ifile-path with space" = fails and
  348.         there is no way to escape/quote the path in the SJASMPLUSOPTS variable to make it work).
  349.   </p>
  350.     </div>
  351.  
  352.     <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp11"></a>Source file format</h2></div></div></div>
  353.      
  354.  
  355.                 <p>
  356.                   Lines in the source file should have the following form:
  357.                   </p><pre class="programlisting">Label Operator Operand Comment</pre><p>
  358.                   All fields are optional.
  359.                   <span class="strong"><strong>Lines without label should start with whitespace.</strong></span>
  360.                   Operators and operands can be inlined with colon:
  361.                   </p><pre class="programlisting">      Operator Operand:Operator Operand:Operator Operand... Comment</pre><p>
  362.                   Comments should start with '<code class="code">;</code>' or '<code class="code">//</code>'.
  363.                   Comment blocks start with '<code class="code">/*</code>' and end with '<code class="code">*/</code>' (work in "nested" way,
  364.                   i.e. comment block started inside comment block must be also ended, before main block ends).
  365.  
  366.                         </p><div class="example"><a name="idp300"></a><p class="title"><b>Example 2.1. </b></p><div class="example-contents">
  367.                                
  368.  
  369.                                 <pre class="programlisting">; comment
  370. // comment
  371.  ld /* comment */ a,80
  372. /*
  373.  comment /* nested comment block */
  374. */
  375.  ld /*
  376.  but this won't be ld a,3!
  377. */ a,3</pre>
  378.                         </div></div><p><br class="example-break">
  379.  
  380.                         Some warnings (low memory-access and fake instruction) can be suppressed for particular
  381.                         line by adding end-of-line type of comment starting with "ok":
  382.                         </p><div class="example"><a name="idp303"></a><p class="title"><b>Example 2.2. </b></p><div class="example-contents">
  383.                                
  384.  
  385.                                 <pre class="programlisting">        OPT --syntax=f  ; warning on accidental fake instructions
  386.        ld  hl,de    ; warning here
  387.        ld  hl,de    ; ok (warning will be suppressed by this comment)</pre>
  388.                         </div></div><p><br class="example-break">
  389.                 </p>
  390.    </div>
  391.  </div>
  392.  
  393.  <div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="idp17"></a>Chapter 3. Labels</h1></div></div></div>
  394.    
  395.  
  396.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp13"></a><a name="s_labels"></a>Labels</h2></div></div></div>
  397.      
  398.  
  399.      <p>Labels are case-sensitive and may be of any reasonable length,
  400.      that is: up to about 70 characters. Label definitions should start on
  401.      the beginning of a line, but don't have to be followed by a colon ':'.
  402.       Generally labels should start with a letter or a underscore ('_'), the
  403.       following characters may be chosen from letters, numbers and the
  404.       following special symbols: '_', '.', '!', '?', '#' and '@'. Note that
  405.       the '.' has special meaning, as it is used between module names, labels
  406.       and local labels. The following are all legal and distinct
  407.       labels:</p><pre class="programlisting">Kip
  408. KIP
  409. Kip@@
  410. MAIN.loop?</pre><p>It is possible to use mnemonics, pseudo-ops and
  411.       register names as labels but it is not advised to do so. Also note that
  412.       the identifiers defined with the DEFINE pseudo-op use another name
  413.       space.</p>
  414.     </div>
  415.  
  416.     <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp14"></a><a name="s_local_labels"></a>Local labels</h2></div></div></div>
  417.      
  418.  
  419.       <p>When there is a <a class="link" href="#po_module">module definition</a> all
  420.       labels (except those starting with a '@') are local to that module. To
  421.       use a label from outside the module use modulename.labelname, in this
  422.       example: 'vdp.Cls' Labels starting with a '.' are also local to the
  423.       previous non-local label.</p>
  424.  
  425.       <div class="example"><a name="idp316"></a><p class="title"><b>Example 3.1. docs_examples/s_local_labels.asm</b></p><div class="example-contents">
  426.          
  427.  
  428.           <pre class="programlisting">    MODULE main             ; module "main"
  429. Main:                       ; main.Main
  430.         CALL SetScreen      ; SetScreen
  431.         CALL vdp.Cls        ; main.vdp.Cls
  432. .loop:                      ; main.Main.loop
  433.         LD A,(.event)       ; main.Main.event
  434.         CALL ProcessEvent   ; label not found: main.ProcessEvent
  435.         DJNZ .loop          ; main.Main.loop
  436.  
  437.         MODULE vdp          ; module "main.vdp"
  438. @SetScreen:                 ; SetScreen
  439. .loop:                      ; main.vdp.SetScreen.loop
  440.             RET
  441. Cls:                        ; main.vdp.Cls
  442. .loop:      DJNZ .loop      ; main.vdp.Cls.loop
  443.             RET
  444.         ENDMODULE
  445.  
  446. Main.event DB 0             ; main.Main.event
  447.     ENDMODULE</pre>
  448.         </div></div><p><br class="example-break"></p>
  449.     </div>
  450.  
  451.     <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp15"></a><a name="s_at_labels"></a>@ Labels</h2></div></div></div>
  452.      
  453.  
  454.       <p>Labels starting with a '@' are not touched by the label processing
  455.       and used 'as-is'. See 'SetScreen' in the previous example code. </p><div class="example"><a name="idp323"></a><p class="title"><b>Example 3.2. docs_examples/s_at_labels.asm</b></p><div class="example-contents">
  456.          
  457.  
  458.           <pre class="programlisting">    MODULE xxx
  459. Label      ; xxx.Label
  460. .Local     ; xxx.Label.Local
  461. @Label     ; Label
  462. .Local     ; xxx.Label.Local =&gt; duplicate label error
  463. @Label2    ; Label2
  464. .Local     ; xxx.Label2.Local
  465. @yyy.Local ; yyy.Local
  466. yyy.Local  ; xxx.yyy.Local</pre>
  467.         </div></div><p><br class="example-break"></p>
  468.     </div>
  469.  
  470.     <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp16"></a><a name="s_temp_labels"></a>Temporary labels</h2></div></div></div>
  471.      
  472.  
  473.       <p>To keep the number of used labels reasonable it is possible to use
  474.       numbers as labels. These labels can only be used as labels to jump to.
  475.       To jump to these labels, use the number followed by an 'F' for forward
  476.       branches or a 'B' for backward branches. Temporary labels should be defined
  477.       in the same order during every pass of assembling, but they can be used
  478.       within macro, or repeating blocks (old sjasmplus versions didn't allow usage within macro).</p>
  479.  
  480.      <div class="example"><a name="idp331"></a><p class="title"><b>Example 3.3. docs_examples/s_temp_labels.asm</b></p><div class="example-contents">
  481.          
  482.  
  483.          <pre class="programlisting">        ADD A,E
  484.        JR NC,1F
  485.        INC D
  486. 1       LD E,A
  487. 2       LD B,4
  488.        LD A,(DE)
  489.        OUT (152),A
  490.        DJNZ 2B
  491.  
  492.        MACRO zing
  493.            DUP 2
  494.                JR 1F
  495. 1               DJNZ    1B
  496.            EDUP
  497.        ENDM
  498.  
  499.        .4 zing</pre>
  500.        </div></div><p><br class="example-break"></p>
  501.    </div>
  502.  </div>
  503.  
  504.  <div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="idp25"></a>Chapter 4. Constants, expressions and other features</h1></div></div></div>
  505.    
  506.  
  507.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp18"></a><a name="s_numeric"></a>Numeric constants</h2></div></div></div>
  508.      
  509.  
  510.      <p>Numeric constants should always start with a digit or $, # or %.
  511.      The following formats are supported:</p>
  512.  
  513.      <pre class="programlisting">12     decimal
  514. 12d    decimal
  515. 0xc    hexadecimal
  516. $c     hexadecimal
  517. #c     hexadecimal
  518. 0ch    hexadecimal
  519. 0b1100 binary (v1.12.1)
  520. %1100  binary
  521. 1100b  binary
  522. 0q14   octal (v1.12.1)
  523. 14q    octal
  524. 14o    octal</pre>
  525.  
  526.      <p>(v1.12.1) Optional single quotes(') may be inserted between the digits as a separator
  527.       (example: <code class="computeroutput"> ld a,%11'01'11'00 </code>).
  528.      They are ignored by the assembler.</p>
  529.    </div>
  530.  
  531.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp19"></a>Character and string constants</h2></div></div></div>
  532.      
  533.  
  534.      <p>Character constants are characters surrounded by single quotes. It
  535.      is possible to use double quotes in some cases, but in general it is
  536.      better to use single quotes. String constants are characters surrounded
  537.      by double quotes. When double quotes are used, the following escape
  538.      sequences are recognized:</p>
  539.      <pre class="programlisting">\\ 92
  540. \? 63
  541. \' 39
  542. \" 34
  543. \0 0     ; since v1.11
  544. \A 7
  545. \B 8
  546. \D 127
  547. \E 27
  548. \F 12
  549. \N 10
  550. \R 13
  551. \T 9
  552. \V 11</pre><p>Inside single quotes two quotes after each other are
  553.    parsed as the apostrophe itself (since v1.11).</p><div class="example"><a name="idp348"></a><p class="title"><b>Example 4.1. </b></p><div class="example-contents">
  554.          
  555.  
  556.          <pre class="programlisting">    BYTE "stringconstant\n" ; escape sequence assembles to newline
  557.    BYTE 'stringconstant\n' ; \n assembles literally as two bytes: '\', 'n'
  558.    LD HL,'hl'  ; hl = 0x686C = 'l', 'h'
  559.    LD HL,"hl"  ; hl = 0x686C = 'l', 'h'
  560.    LD A,"7"    ; not recommended (but works)
  561.    LD A,'8'    ; recommended
  562.    LD A,'\E'   ; warning + truncating value to 'E' (0x45)
  563.    LD A,'"'    ; A = 0x22
  564.    LD A,"'"    ; A = 0x27
  565.    LD A,''''   ; A = 0x27 ; since v1.11</pre>
  566.        </div></div><p><br class="example-break"></p>
  567.    </div>
  568.  
  569.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp20"></a><a name="s_expressions"></a>Expressions</h2></div></div></div>
  570.      
  571.  
  572.      <p>Expressions are evaluated in signed 32 bits in this version of SjASMPlus (unless explicitly
  573.                   specified as unsigned, like "&gt;&gt;&gt;" operator), so intermediate values have range -2147483648
  574.                   to +2147483647.</p>
  575.  
  576.      <p>'$' represents the current program counter. '$$' represents the
  577.      current page in the current slot in the <a class="link" href="#s_realdevice">real device emulation mode</a>, '$$label' evaluates to number of page
  578.           where the "label" was defined (only regular labels have meaningful value, labels defined
  579.           under DISP mode or EQU/DEFL/... will produce irrelevant values) and '{address}' can be used
  580.      to read WORD from virtual device memory (correct value is read only in last pass of assembling,
  581.           in early passes the zero value is always returned), '{b address}' reads only BYTE.</p>
  582.  
  583.      <p>It is possible to use parenthesis '(' and ')' to override the
  584.      precedence of the operators. The following operators may be used in
  585.      expressions:</p>
  586.  
  587.      <pre class="programlisting">!     !x       logical not
  588. ~     ~x       complement
  589. +     +x       does "nothing", can be used to make "+(...)" parse as value (not as memory)
  590. -     -x       minus
  591. low   low x    low 8 bits of 16 bit value or lower part of register pair
  592. high  high x   high 8 bits of 16 bit value or higher part of register pair
  593. not   not x    logical not
  594.  
  595. *     x*y      multiplication
  596. /     x/y      division
  597. %     x%y      modulo
  598. mod   x mod y  modulo
  599.  
  600. +     x+y      addition
  601. -     x-y      subtraction
  602.  
  603. &lt;&lt;    x&lt;&lt;y     shift left
  604. &gt;&gt;    x&gt;&gt;y     shift right signed
  605. &gt;&gt;&gt;   x&gt;&gt;&gt;y    shift right unsigned
  606. shl   x shl y  shift left
  607. shr   x shr y  shift right signed
  608.  
  609. &lt;?    x&lt;?y     minimum
  610. &gt;?    x&gt;?y     maximum
  611.  
  612. &lt;     x&lt;y      less than
  613. &gt;     x&gt;y      greater than
  614. &lt;=    x&lt;=y     equal or less than
  615. &gt;=    x&gt;=y     equal or greater than
  616.  
  617. =     x=y      equal
  618. ==    x==y     equal
  619. !=    x!=y     not equal
  620.  
  621. &amp;     x&amp;y      bitwise and
  622. and   x and y  bitwise and
  623.  
  624. ^     x^y      bitwise xor
  625. xor   x xor y  bitwise xor
  626.  
  627. |     x|y      bitwise or
  628. or    x or y   bitwise or
  629.  
  630. &amp;&amp;    x&amp;&amp;y     logical and
  631.  
  632. ||    x||y     logical or
  633.  
  634. $     $        current program counter
  635. $$    $$       current page at program counter (in virtual device mode)
  636. label label    value of label (aka symbol), usually memory address
  637. $$lab $$lab    page of "lab" label (in virtual device mode)
  638. {}    {x}      reads WORD from address x (in virtual device mode, in last pass)
  639. {b}   {b x}    reads BYTE from address x (in virtual device mode, in last pass)
  640. </pre>
  641.    </div>
  642.  
  643.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp21"></a>Assembly language</h2></div></div></div>
  644.      
  645.  
  646.      <p>This version only accepts Z80 mnemonics. There are some additions
  647.      to what I think is standard Z80: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  648.            <p>'[' and ']' can be used instead of '(' and ')' for
  649.            indirection. So <code class="code">LD A,[HL]</code> is the same as <code class="code">LD A,(HL)</code> (does not
  650.            apply to IN/OUT ports, those must use '(...)' form)</p>
  651.          </li><li class="listitem">
  652.            <p><code class="code">IN F,(C)</code> and <code class="code">OUT (C),0</code> and <code class="code">SLL/SLI</code> can be used
  653.                                 (warning: on some CPU versions of Z80 the OUT (C),0 is working as OUT (C),255).</p>
  654.          </li><li class="listitem">
  655.            <p>IXL (or LX, XL), IYL (or LY, YL), IXH (or HX, XH) and IYH
  656.            (or HY, YH) registers are supported.</p>
  657.          </li><li class="listitem">
  658.            <p>Can write code throught colon: ORG 100h:LD A,10:LD B,10:SUB
  659.            B:RET:IFDEF AA:.....</p>
  660.          </li><li class="listitem">
  661.            <p>JP HL, JP IX and JP IY may be used instead of JP (HL),
  662.            etc.</p>
  663.          </li><li class="listitem">
  664.            <p>EX AF,AF or EX AF or EXA may be used instead of EX
  665.            AF,AF'.</p>
  666.          </li><li class="listitem">
  667.            <p>R800's MULUB and MULUW are recognised (but won't work on
  668.            Z80, of course:)</p>
  669.          </li><li class="listitem">
  670.            <p>Z80N, i8080 and LR35902 modes use the identical Z80 sjasmplus syntax (!), for the
  671.                                 correct (and incorrect) syntax examples of extended opcodes, please check the test files:
  672.                                 Z80N <a class="ulink" href="https://github.com/z00m128/sjasmplus/blob/master/tests/z80n/op_zx_spectrum_next_2_00_26.asm" target="_top">test 1</a>
  673.                                 <a class="ulink" href="https://github.com/z00m128/sjasmplus/blob/master/tests/z80n/op_next_syntax.lst" target="_top">test 2</a>
  674.                                 and LR35902 <a class="ulink" href="https://github.com/z00m128/sjasmplus/blob/master/tests/lr35902/LR35902_syntax_by_neo.lst" target="_top">test 1</a>
  675.                                 <a class="ulink" href="https://github.com/z00m128/sjasmplus/blob/master/tests/lr35902/LR35902_specifics_exercise.lst" target="_top">test 2</a>
  676.                                 (also for the Z80 syntax examples you can check <a class="ulink" href="https://github.com/z00m128/sjasmplus/tree/master/tests/z80" target="_top">
  677.                                         Z80 tests</a>).
  678.                                 </p>
  679.          </li><li class="listitem">
  680.            <p>RLC, RRC, RL, RR, SLA, SRA, SLL (SLI), RES, SET undocumented
  681.            instructions added.</p>
  682.          </li></ul></div><pre class="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
  683.    RRC (IY),A     ; (aka LD A,RRC (IY+0))   is LD A,(IY)   / RRC A   / LD (IY),A</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  684.            <p>PUSH and POP can take register lists:</p>
  685.          </li></ul></div><pre class="programlisting">    PUSH AF,BC  ; push af / push bc
  686.    POP  AF,BC  ; pop  af / pop  bc</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  687.            <p>and many other instructions support this "multi-argument" syntax:</p>
  688.          </li></ul></div><pre class="programlisting">    LD A,B,B,D,D,H
  689.   /* this is:
  690.     LD A,B
  691.     LD B,D
  692.     LD D,H
  693.   */
  694.   ;or you can write  LD A,B:LD B,D:LD D,H
  695.  
  696.   ; since v1.13.1 it is possible and *recommended* to change the multi-arg delimiter
  697.   ; into ",,", to avoid some ambiguities with certain instructions.
  698.   OPT --syntax=a
  699.   LD A,B,,B,D,,D,H ; same as example above in default syntax
  700.   SUB A,B,,C  ; = SUB B, SUB C (the default syntax does for SUB A,B two SUBs!)</pre>
  701.    </div>
  702.  
  703.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp22"></a><a name="s_fake_instructions"></a>Fake instructions</h2></div></div></div>
  704.      
  705.  
  706.      <p>Of course the Z80 is only an 8 bit cpu, but sometimes <code class="code">ld hl,de</code>
  707.      would be nice. SjASMPlus now 'fakes' some instructions like that. This
  708.      improves the readability of the source, but it might not be the fastest
  709.      way to get the result. Also possibly some 'new' load instructions do
  710.      affect the flags in ways you wouldn't expect. You can use option <code class="code">--syntax=f</code>
  711.      to get warnings when fake instruction is used, to avoid using them by accident. Here's the
  712.      list:</p>
  713.  
  714.      <pre class="programlisting">
  715.  rl bc           ; rl c : rl b
  716.  rl de           ; rl e : rl d
  717.  rl hl           ; rl l : rl h
  718.  rr bc           ; rr b : rr c
  719.  rr de           ; rr d : rr e
  720.  rr hl           ; rr h : rr l
  721.  sla bc          ; sla c : rl b
  722.  sla de          ; sla e : rl d
  723.  sla hl          ; add hl,hl
  724.  sll bc          ; sli c : rl b
  725.  sll de          ; sli e : rl d
  726.  sll hl          ; sli l : rl h
  727.  sli bc          ; sli c : rl b
  728.  sli de          ; sli e : rl d
  729.  sli hl          ; sli l : rl h
  730.  sra bc          ; sra b : rr c
  731.  sra de          ; sra d : rr e
  732.  sra hl          ; sra h : rr l
  733.  srl bc          ; srl b : rr c
  734.  srl de          ; srl d : rr e
  735.  srl hl          ; srl h : rr l
  736.  
  737.  ld bc,bc        ; ld b,b : ld c,c
  738.  ld bc,de        ; ld b,d : ld c,e
  739.  ld bc,hl        ; ld b,h : ld c,l
  740.  ld bc,ix        ; ld b,xh : ld c,xl
  741.  ld bc,iy        ; ld b,yh : ld c,yl
  742.  ld bc,(hl)      ; ld c,(hl) : inc hl : ld b,(hl) : dec hl
  743.  ld bc,(ix+nn)   ; ld c,(ix+nn) : ld b,(ix+nn+1)
  744.  ld bc,(iy+nn)   ; ld c,(iy+nn) : ld b,(iy+nn+1)
  745.  
  746.  ld de,bc        ; ld d,b : ld e,c
  747.  ld de,de        ; ld d,d : ld e,e
  748.  ld de,hl        ; ld d,h : ld e,l
  749.  ld de,ix        ; ld d,xh : ld e,xl
  750.  ld de,iy        ; ld d,yh : ld e,yl
  751.  ld de,(hl)      ; ld e,(hl) : inc hl : ld d,(hl) : dec hl
  752.  ld de,(ix+nn)   ; ld e,(ix+nn) : ld d,(ix+nn+1)
  753.  ld de,(iy+nn)   ; ld e,(iy+nn) : ld d,(iy+nn+1)
  754.  
  755.  ld hl,bc        ; ld h,b : ld l,c
  756.  ld hl,de        ; ld h,d : ld l,e
  757.  ld hl,hl        ; ld h,h : ld l,l
  758.  ld hl,ix        ; push ix : pop hl
  759.  ld hl,iy        ; push iy : pop hl
  760.  ld hl,(ix+nn)   ; ld l,(ix+nn) : ld h,(ix+nn+1)
  761.  ld hl,(iy+nn)   ; ld l,(iy+nn) : ld h,(iy+nn+1)
  762.  
  763.  ld ix,bc        ; ld xh,b : ld xl,c
  764.  ld ix,de        ; ld xh,d : ld xl,e
  765.  ld ix,hl        ; push hl : pop ix
  766.  ld ix,ix        ; ld xh,xh : ld xl,xl
  767.  ld ix,iy        ; push iy : pop ix
  768.  
  769.  ld iy,bc        ; ld yh,b : ld yl,c
  770.  ld iy,de        ; ld yh,d : ld yl,e
  771.  ld iy,hl        ; push hl : pop iy
  772.  ld iy,ix        ; push ix : pop iy
  773.  ld iy,iy        ; ld yh,yh : ld yl,yl
  774.  
  775.  ld (hl),bc      ; ld (hl),c : inc hl : ld (hl),b : dec hl
  776.  ld (hl),de      ; ld (hl),e : inc hl : ld (hl),d : dec hl
  777.  
  778.  ld (ix+nn),bc   ; ld (ix+nn),c : ld (ix+nn+1),b
  779.  ld (ix+nn),de   ; ld (ix+nn),e : ld (ix+nn+1),d
  780.  ld (ix+nn),hl   ; ld (ix+nn),l : ld (ix+nn+1),h
  781.  
  782.  ld (iy+nn),bc   ; ld (iy+nn),c : ld (iy+nn+1),b
  783.  ld (iy+nn),de   ; ld (iy+nn),e : ld (iy+nn+1),d
  784.  ld (iy+nn),hl   ; ld (iy+nn),l : ld (iy+nn+1),h
  785.  
  786.  ldi bc,(hl)     ; ld c,(hl) : inc hl : ld b,(hl) : inc hl
  787.  ldi bc,(ix+nn)  ; ld c,(ix+nn) : inc ix : ld b,(ix+nn) : inc ix
  788.  ldi bc,(iy+nn)  ; ld c,(iy+nn) : inc iy : ld b,(iy+nn) : inc iy
  789.  
  790.  ldi de,(hl)     ; ld e,(hl) : inc hl : ld d,(hl) : inc hl
  791.  ldi de,(ix+nn)  ; ld e,(ix+nn) : inc ix : ld d,(ix+nn) : inc ix
  792.  ldi de,(iy+nn)  ; ld e,(iy+nn) : inc iy : ld d,(iy+nn) : inc iy
  793.  
  794.  ldi hl,(ix+nn)  ; ld l,(ix+nn) : inc ix : ld h,(ix+nn) : inc ix
  795.  ldi hl,(iy+nn)  ; ld l,(iy+nn) : inc iy : ld h,(iy+nn) : inc iy
  796.  
  797.  ldi (hl),bc     ; ld (hl),c : inc hl : ld (hl),b : inc hl
  798.  ldi (hl),de     ; ld (hl),e : inc hl : ld (hl),d : inc hl
  799.  
  800.  ldi (ix+nn),bc  ; ld (ix+nn),c : inc ix : ld (ix+nn),b : inc ix
  801.  ldi (ix+nn),de  ; ld (ix+nn),e : inc ix : ld (ix+nn),d : inc ix
  802.  ldi (ix+nn),hl  ; ld (ix+nn),l : inc ix : ld (ix+nn),h : inc ix
  803.  
  804.  ldi (iy+nn),bc  ; ld (iy+nn),c : inc iy : ld (iy+nn),b : inc iy
  805.  ldi (iy+nn),de  ; ld (iy+nn),e : inc iy : ld (iy+nn),d : inc iy
  806.  ldi (iy+nn),hl  ; ld (iy+nn),l : inc iy : ld (iy+nn),h : inc iy
  807.  
  808.  ldi a,(bc)      ; ld a,(bc) : inc bc
  809.  ldi a,(de)      ; ld a,(de) : inc de
  810.  ldi a,(hl)      ; ld a,(hl) : inc hl
  811.  ldi b,(hl)      ; ld b,(hl) : inc hl
  812.  ldi c,(hl)      ; ld c,(hl) : inc hl
  813.  ldi d,(hl)      ; ld d,(hl) : inc hl
  814.  ldi e,(hl)      ; ld e,(hl) : inc hl
  815.  ldi h,(hl)      ; ld h,(hl) : inc hl
  816.  ldi l,(hl)      ; ld l,(hl) : inc hl
  817.  ldi a,(ix+nn)   ; ld a,(ix+nn) : inc ix
  818.  ldi b,(ix+nn)   ; ld b,(ix+nn) : inc ix
  819.  ldi c,(ix+nn)   ; ld c,(ix+nn) : inc ix
  820.  ldi d,(ix+nn)   ; ld d,(ix+nn) : inc ix
  821.  ldi e,(ix+nn)   ; ld e,(ix+nn) : inc ix
  822.  ldi h,(ix+nn)   ; ld h,(ix+nn) : inc ix
  823.  ldi l,(ix+nn)   ; ld l,(ix+nn) : inc ix
  824.  ldi a,(iy+nn)   ; ld a,(iy+nn) : inc iy
  825.  ldi b,(iy+nn)   ; ld b,(iy+nn) : inc iy
  826.  ldi c,(iy+nn)   ; ld c,(iy+nn) : inc iy
  827.  ldi d,(iy+nn)   ; ld d,(iy+nn) : inc iy
  828.  ldi e,(iy+nn)   ; ld e,(iy+nn) : inc iy
  829.  ldi h,(iy+nn)   ; ld h,(iy+nn) : inc iy
  830.  ldi l,(iy+nn)   ; ld l,(iy+nn) : inc iy
  831.  
  832.  ldd a,(bc)      ; ld a,(bc) : dec bc
  833.  ldd a,(de)      ; ld a,(de) : dec de
  834.  ldd a,(hl)      ; ld a,(hl) : dec hl
  835.  ldd b,(hl)      ; ld b,(hl) : dec hl
  836.  ldd c,(hl)      ; ld c,(hl) : dec hl
  837.  ldd d,(hl)      ; ld d,(hl) : dec hl
  838.  ldd e,(hl)      ; ld e,(hl) : dec hl
  839.  ldd h,(hl)      ; ld h,(hl) : dec hl
  840.  ldd l,(hl)      ; ld l,(hl) : dec hl
  841.  ldd a,(ix+nn)   ; ld a,(ix+nn) : dec ix
  842.  ldd b,(ix+nn)   ; ld b,(ix+nn) : dec ix
  843.  ldd c,(ix+nn)   ; ld c,(ix+nn) : dec ix
  844.  ldd d,(ix+nn)   ; ld d,(ix+nn) : dec ix
  845.  ldd e,(ix+nn)   ; ld e,(ix+nn) : dec ix
  846.  ldd h,(ix+nn)   ; ld h,(ix+nn) : dec ix
  847.  ldd l,(ix+nn)   ; ld l,(ix+nn) : dec ix
  848.  ldd a,(iy+nn)   ; ld a,(iy+nn) : dec iy
  849.  ldd b,(iy+nn)   ; ld b,(iy+nn) : dec iy
  850.  ldd c,(iy+nn)   ; ld c,(iy+nn) : dec iy
  851.  ldd d,(iy+nn)   ; ld d,(iy+nn) : dec iy
  852.  ldd e,(iy+nn)   ; ld e,(iy+nn) : dec iy
  853.  ldd h,(iy+nn)   ; ld h,(iy+nn) : dec iy
  854.  ldd l,(iy+nn)   ; ld l,(iy+nn) : dec iy
  855.  
  856.  ldi (bc),a      ; ld (bc),a : inc bc
  857.  ldi (de),a      ; ld (de),a : inc de
  858.  ldi (hl),a      ; ld (hl),a : inc hl
  859.  ldi (hl),b      ; ld (hl),b : inc hl
  860.  ldi (hl),c      ; ld (hl),c : inc hl
  861.  ldi (hl),d      ; ld (hl),d : inc hl
  862.  ldi (hl),e      ; ld (hl),e : inc hl
  863.  ldi (hl),h      ; ld (hl),h : inc hl
  864.  ldi (hl),l      ; ld (hl),l : inc hl
  865.  ldi (ix+nn),a   ; ld (ix+nn),a : inc ix
  866.  ldi (ix+nn),b   ; ld (ix+nn),b : inc ix
  867.  ldi (ix+nn),c   ; ld (ix+nn),c : inc ix
  868.  ldi (ix+nn),d   ; ld (ix+nn),d : inc ix
  869.  ldi (ix+nn),e   ; ld (ix+nn),e : inc ix
  870.  ldi (ix+nn),h   ; ld (ix+nn),h : inc ix
  871.  ldi (ix+nn),l   ; ld (ix+nn),l : inc ix
  872.  ldi (iy+nn),a   ; ld (iy+nn),a : inc iy
  873.  ldi (iy+nn),b   ; ld (iy+nn),b : inc iy
  874.  ldi (iy+nn),c   ; ld (iy+nn),c : inc iy
  875.  ldi (iy+nn),d   ; ld (iy+nn),d : inc iy
  876.  ldi (iy+nn),e   ; ld (iy+nn),e : inc iy
  877.  ldi (iy+nn),h   ; ld (iy+nn),h : inc iy
  878.  ldi (iy+nn),l   ; ld (iy+nn),l : inc iy
  879.  
  880.  ldd (bc),a      ; ld (bc),a : dec bc
  881.  ldd (de),a      ; ld (de),a : dec de
  882.  ldd (hl),a      ; ld (hl),a : dec hl
  883.  ldd (hl),b      ; ld (hl),b : dec hl
  884.  ldd (hl),c      ; ld (hl),c : dec hl
  885.  ldd (hl),d      ; ld (hl),d : dec hl
  886.  ldd (hl),e      ; ld (hl),e : dec hl
  887.  ldd (hl),h      ; ld (hl),h : dec hl
  888.  ldd (hl),l      ; ld (hl),l : dec hl
  889.  ldd (ix+nn),a   ; ld (ix+nn),a : dec ix
  890.  ldd (ix+nn),b   ; ld (ix+nn),b : dec ix
  891.  ldd (ix+nn),c   ; ld (ix+nn),c : dec ix
  892.  ldd (ix+nn),d   ; ld (ix+nn),d : dec ix
  893.  ldd (ix+nn),e   ; ld (ix+nn),e : dec ix
  894.  ldd (ix+nn),h   ; ld (ix+nn),h : dec ix
  895.  ldd (ix+nn),l   ; ld (ix+nn),l : dec ix
  896.  ldd (iy+nn),a   ; ld (iy+nn),a : dec iy
  897.  ldd (iy+nn),b   ; ld (iy+nn),b : dec iy
  898.  ldd (iy+nn),c   ; ld (iy+nn),c : dec iy
  899.  ldd (iy+nn),d   ; ld (iy+nn),d : dec iy
  900.  ldd (iy+nn),e   ; ld (iy+nn),e : dec iy
  901.  ldd (iy+nn),h   ; ld (iy+nn),h : dec iy
  902.  ldd (iy+nn),l   ; ld (iy+nn),l : dec iy
  903.  
  904.  ldi (hl),mm     ; ld (hl),mm : inc hl
  905.  ldi (ix+nn),mm  ; ld (ix+nn),mm : inc ix
  906.  ldi (iy+nn),mm  ; ld (iy+nn),mm : inc iy
  907.  
  908.  ldd (hl),mm     ; ld (hl),mm : dec hl
  909.  ldd (ix+nn),mm  ; ld (ix+nn),mm : dec ix
  910.  ldd (iy+nn),mm  ; ld (iy+nn),mm : dec iy
  911.  
  912.  sub hl,bc       ; or a : sbc hl,bc
  913.  sub hl,de       ; or a : sbc hl,de
  914.  sub hl,hl       ; or a : sbc hl,hl
  915.  sub hl,sp       ; or a : sbc hl,sp
  916.  
  917.  ; Z80N only
  918.  mul             ; mul de ; to avoid warning specify registers</pre><p>
  919.      <code class="code">LDI</code> increases the data pointer after the data
  920.      access, so <code class="code">LDI A,(HL)</code> is the same as <code class="code">LD A,(HL):INC HL</code>.
  921.      Likewise, <code class="code">LDD A,(DE)</code> is <code class="code">LD A,(DE):DEC DE</code>.</p>
  922.    </div>
  923.  
  924.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp23"></a><a name="s_realdevice"></a>Real device emulation mode</h2></div></div></div>
  925.      
  926.  
  927.      <p>To enable this mode you must use pseudo-op <a class="link" href="#po_device">DEVICE</a>.</p>
  928.  
  929.      <p>In this mode the compiler compiling program to virtual memory (as
  930.      at MSX's WB-ASS2, ZX-Spectrum's GENS, ZEUS, ALASM etc). After this all
  931.      you can use new pseudo-ops as <a class="link" href="#s_pseudoops">SAVEBIN, SAVEDEV
  932.      SAVEHOB, SAVETRD, SAVETAP, PAGE, SLOT, MMU, LABELSLIST</a>, use special
  933.      functions in <a class="link" href="#c_lua_scripting">Lua scripts</a> and use operators
  934.      <code class="code">{address}, {b address}</code> to read WORD/BYTE from the virtual memory.</p>
  935.  
  936.      <p>If only single DEVICE is used in whole source batch, the device
  937.      becomes "global" and will affect also source ahead of the DEVICE line.
  938.          </p><div class="example"><a name="idp421"></a><p class="title"><b>Example 4.2. docs_examples/s_realdevice.asm</b></p><div class="example-contents">
  939.          
  940.  
  941.          <pre class="programlisting">    DEVICE ZXSPECTRUM128
  942.    ; in this device the default slot is SLOT 3 with PAGE 0 paged in.
  943.  
  944.    ORG 32768
  945. StartProg:
  946.    JP $
  947.  
  948.    DEVICE NONE
  949.    ;do something, if you don't want to corrupt virtual
  950.    ;memory with other code, for example, loader of code.
  951.    ;...code...
  952.  
  953.    ;return to our virtual device:
  954.    DEVICE ZXSPECTRUM128
  955.  
  956.    SAVESNA "snapshotname.sna", StartProg</pre>
  957.        </div></div><p><br class="example-break">Predefined devices:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><a name="device_none"></a>NONE</span></dt><dd>
  958.              <p>Disable real device emulation mode. By default.</p>
  959.            </dd><dt><span class="term"><a name="device_zx48"></a>ZXSPECTRUM48</span></dt><dd>
  960.              <p>Has 4 slots (0-3) with size 4000h, 4 pages (0-3) with size
  961.              4000h. Slot 3 (it from 0C000h) enables to current by
  962.              default.</p>
  963.            </dd><dt><span class="term"><a name="device_zx128"></a>ZXSPECTRUM128</span></dt><dd>
  964.              <p>Has 8 RAM pages (0-7) with size 4000h. Default slot is 3.</p>
  965.            </dd><dt><span class="term"><a name="device_zx256"></a>ZXSPECTRUM256</span></dt><dd>
  966.              <p>Same as Russian clone Scorption 256. Has 16 RAM pages
  967.              (0-15) with size 4000h.</p>
  968.            </dd><dt><span class="term"><a name="device_zx512"></a>ZXSPECTRUM512</span></dt><dd>
  969.              <p>Same as Russian clones ATM Turbo 512 and Pentagon 512. Has
  970.              32 RAM pages (0-31) with size 4000h.</p>
  971.            </dd><dt><span class="term"><a name="device_zx1024"></a>ZXSPECTRUM1024</span></dt><dd>
  972.              <p>Same as Russian clones ATM Turbo 2 and Pentagon 1024 SL.
  973.              Has 64 RAM pages (0-63) with size 4000h.</p>
  974.            </dd><dt><span class="term"><a name="device_zx2048"></a>ZXSPECTRUM2048</span></dt><dd>
  975.              <p>Similar to other spectrum devices, has 128 RAM pages (0-127) with size 4000h.</p>
  976.            </dd><dt><span class="term"><a name="device_zx4096"></a>ZXSPECTRUM4096</span></dt><dd>
  977.              <p>Similar to other spectrum devices, has 256 RAM pages (0-255) with size 4000h.</p>
  978.            </dd><dt><span class="term"><a name="device_zx8192"></a>ZXSPECTRUM8192</span></dt><dd>
  979.              <p>Similar to other spectrum devices, has 512 RAM pages (0-511) with size 4000h.</p>
  980.            </dd><dt><span class="term"><a name="device_zxn"></a>ZXSPECTRUMNEXT</span></dt><dd>
  981.              <p>ZX Spectrum Next, has 8 slots (0-7) of size 0x2000 and 224
  982.              RAM pages (0-223) totalling at 1.75MiB of memory. The <a class="ulink" href="https://wiki.specnext.dev/Memory_map#Z80_Visible_Memory_map" target="_top">default mapping</a>
  983.              is similar to ZX128, paging in: {14, 15, 10, 11, 4, 5, 0, 1} pages.
  984.              Default slot is 7 (memory range 0xE000..0xFFFF).
  985.              All memory is zeroed during initialization.</p>
  986.            </dd></dl></div>
  987.  
  988.      <p>If you want to see other devices you must write to us. See <a class="link" href="#feedback">Feedback</a> chapter.</p>
  989.    </div>
  990.  
  991.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp24"></a><a name="s_predefined"></a>Predefined defines</h2></div></div></div>
  992.      
  993.  
  994.      <p>SjASMPlus has predefined <a class="link" href="#po_define">defines</a>.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">__SJASMPLUS__ = &lt;24bit number&gt;</span></dt><dd>
  995.              <p>Current version split into three 8bit values, ie. 0x010F02 for "1.15.2".</p>
  996.            </dd><dt><span class="term">__VERSION__ = "version string"</span></dt><dd>
  997.              <p>String value (with quotes around it) of current version like <code class="code">"1.15.2"</code>.</p>
  998.            </dd><dt><span class="term">__ERRORS__ = &lt;number&gt;</span></dt><dd>
  999.              <p>Number of errors.</p>
  1000.            </dd><dt><span class="term">__WARNINGS__ = &lt;number&gt;</span></dt><dd>
  1001.              <p>Number of warnings.</p>
  1002.            </dd><dt><span class="term">__PASS__ = &lt;number&gt;</span></dt><dd>
  1003.              <p>Current assembling pass (1, 2 or 3).</p>
  1004.            </dd><dt><span class="term">__INCLUDE_LEVEL__ = &lt;number&gt;</span></dt><dd>
  1005.              <p>Current include-nesting level.</p>
  1006.            </dd><dt><span class="term">__BASE_FILE__ = &lt;name of base file&gt;</span></dt><dd>
  1007.              <p>Name of base file (include-level zero).</p>
  1008.              <p>This is raw value without quotes, practically unusable by asm source, but LUA
  1009.                                   provides means to operate with such string value.</p>
  1010.            </dd><dt><span class="term">__FILE__ = &lt;name of current file&gt;</span></dt><dd>
  1011.              <p>Name of current file.</p>
  1012.              <p>This is raw value without quotes, practically unusable by asm source, but LUA
  1013.                                   provides means to operate with such string value.</p>
  1014.            </dd><dt><span class="term">__LINE__ = &lt;number&gt;</span></dt><dd>
  1015.              <p>Current line number.</p>
  1016.            </dd><dt><span class="term">__COUNTER__ = &lt;incrementing number&gt;</span></dt><dd>
  1017.              <p>Does increment upon each usage (starting as value 0). Currently difficult to
  1018.                                   use for labels/symbols, because the starting `_` of the define name prevents
  1019.                                   mid-word substitution, will make more sense with new substitution rules (if ever
  1020.                                   the sjasmplus v2.x happens, would be too big change for v1.x). Right now call
  1021.                                   LUA for the rescue.</p>
  1022.                           <div class="example"><a name="idp527"></a><p class="title"><b>Example 4.3. __COUNTER__ usage in LUA script</b></p><div class="example-contents">
  1023.                  
  1024.  
  1025.                  <pre class="programlisting">    DB __COUNTER__   ; DB 0
  1026.    LUA ALLPASS
  1027.        sj.insert_label("label_" .. sj.get_define("__COUNTER__"), sj.current_address)
  1028.                -- creates "label_1" at "$" (0x0001)
  1029.        sj.insert_label("label_" .. sj.get_define("__COUNTER__"), _c("$+10"))
  1030.                -- creates "label_2" at "$+10" (0x000B)
  1031.    ENDLUA
  1032. label__COUNTER__: ; does *NOT* substitute in current sjasmplus, sorry
  1033.    DB __COUNTER__   ; DB 3
  1034.  
  1035.    ; also macro arguments substitution can be used
  1036.    MACRO createLabelWithSuffix label?, suffix?
  1037. label?_suffix? ; define global label
  1038.    ENDM
  1039.    createLabelWithSuffix label, __COUNTER__    ; label_4
  1040.    createLabelWithSuffix label, __COUNTER__    ; label_5</pre>
  1041.                </div></div><br class="example-break">
  1042.            </dd><dt><span class="term">Deprecated predefined values from sjasmplus till version 1.15.1:</span></dt><dd>
  1043.                                 <p>The predefined values were renamed and extended to be more like gcc/clang pre-defines,
  1044.                                         the following ones are deprecated originals.</p>
  1045.            </dd><dt><span class="term">_SJASMPLUS = 1</span></dt><dd>
  1046.              <p>Deprecated, consider using similar __SJASMPLUS__</p><div class="example"><a name="idp538"></a><p class="title"><b>Example 4.4. </b></p><div class="example-contents">
  1047.                  
  1048.  
  1049.                  <pre class="programlisting">   IFDEF _SJASMPLUS
  1050.     ;code for sjasmplus
  1051.   ELSE
  1052.     ;code for other compiler
  1053.   ENDIF</pre>
  1054.                </div></div><p><br class="example-break"></p>
  1055.            </dd><dt><span class="term">_VERSION = "version"</span></dt><dd>
  1056.              <p>Deprecated, renamed to __VERSION__</p><div class="example"><a name="idp546"></a><p class="title"><b>Example 4.5. </b></p><div class="example-contents">
  1057.                  
  1058.  
  1059.                  <pre class="programlisting">   IF _VERSION = "1.07"
  1060.     ;code for 1.07
  1061.   ELSE
  1062.     ;code for other version
  1063.   ENDIF</pre>
  1064.                </div></div><p><br class="example-break"></p>
  1065.            </dd><dt><span class="term">_RELEASE = releasenumber</span></dt><dd>
  1066.              <p>Deprecated, consider using similar __SJASMPLUS__</p><div class="example"><a name="idp554"></a><p class="title"><b>Example 4.6. </b></p><div class="example-contents">
  1067.                  
  1068.  
  1069.                  <pre class="programlisting">   IF _RELEASE = 1 ; 0 - is stable version
  1070.     ;code for Release Candidate 1
  1071.   ELSE
  1072.     ;code for other version
  1073.   ENDIF</pre>
  1074.                </div></div><p><br class="example-break"></p>
  1075.            </dd><dt><span class="term">_ERRORS = &lt;number&gt;</span></dt><dd>
  1076.              <p>Number of errors. Deprecated, renamed to __ERRORS__</p>
  1077.            </dd><dt><span class="term">_WARNINGS = &lt;number&gt;</span></dt><dd>
  1078.              <p>Number of warnings. Deprecated, renamed to __WARNINGS__</p>
  1079.            </dd></dl></div>
  1080.    </div>
  1081.  </div>
  1082.  
  1083.  <div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="idp30"></a>Chapter 5. Pseudo-ops (aka Pseudo-instructions, Directives etc)</h1></div></div></div>
  1084.    
  1085.  
  1086.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp26"></a>Simple example of usage</h2></div></div></div>
  1087.      
  1088.  
  1089.      <pre class="programlisting">     .SOMEPSEUDOOP ;or
  1090.     SOMEPSEUDOOP  ;or
  1091.     somepseudoop</pre>
  1092.    </div>
  1093.  
  1094.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp27"></a><a name="s_pseudoops"></a>Almost complete list</h2></div></div></div>
  1095.      
  1096.  
  1097.      <p></p>
  1098.  
  1099.      <div class="variablelist"><dl class="variablelist"><dt><span class="term"><a name="po_dot_repeat"></a>.&lt;repeat-count&gt; &lt;single instruction&gt;</span></dt><dd>
  1100.              <p>Repeat &lt;single instruction&gt; &lt;repeat-count&gt; many times. Doesn't work
  1101.                                   in the beginning of line. The &lt;repeat-count&gt; must be either simple integer
  1102.                                   number or expression fully enclosed in parentheses.</p><div class="example"><a name="idp580"></a><p class="title"><b>Example 5.1. docs_examples/po_dot_repeat.asm</b></p><div class="example-contents">
  1103.                  
  1104.  
  1105.                  <pre class="programlisting"> .3        INC A    ;will be compiled to INC A:INC A:INC A
  1106. len        EQU 10
  1107. .(12-len) BYTE 0   ;will be compiled to BYTE 0,0
  1108. .2 .3     RET      ;will be compiled to 6x RET</pre>
  1109.                </div></div><p><br class="example-break"></p>
  1110.            </dd><dt><span class="term"><a name="po_abyte"></a>ABYTE &lt;offset&gt; &lt;bytes&gt;</span></dt><dd>
  1111.              <p>Defines a byte or a string of bytes. The offset is added
  1112.              to each of the following bytes.</p><div class="example"><a name="idp589"></a><p class="title"><b>Example 5.2. </b></p><div class="example-contents">
  1113.                  
  1114.  
  1115.                  <pre class="programlisting">    ABYTE 2 4,9    ; Same as BYTE 6,11
  1116.    ABYTE 3 "ABC"  ; Same as BYTE "DEF"</pre>
  1117.                </div></div><p><br class="example-break"></p>
  1118.            </dd><dt><span class="term"><a name="po_abytec"></a>ABYTEC &lt;offset&gt; &lt;bytes&gt;</span></dt><dd>
  1119.              <p>Defines a byte or a string of bytes, where the last byte
  1120.              of the string will have bit 7 set. The offset is added to each
  1121.              of the following bytes.</p><div class="example"><a name="idp598"></a><p class="title"><b>Example 5.3. </b></p><div class="example-contents">
  1122.                  
  1123.  
  1124.                  <pre class="programlisting">    ABYTEC 0 "KIP"        ; Same as BYTE "KI",'P'|128
  1125.    ABYTEC 1 "ABC",0,"DE" ; Same as BYTE "BC",'D'|128,1,'E','F'|128</pre>
  1126.                </div></div><p><br class="example-break"></p>
  1127.            </dd><dt><span class="term"><a name="po_abytez"></a>ABYTEZ &lt;offset&gt; &lt;bytes&gt;</span></dt><dd>
  1128.              <p>Defines a byte or a string of bytes, followed by a zero.
  1129.              The offset is added to each of the following bytes.</p><div class="example"><a name="idp607"></a><p class="title"><b>Example 5.4. </b></p><div class="example-contents">
  1130.                  
  1131.  
  1132.                  <pre class="programlisting">    ABYTEZ 0 "KIP"        ; Same as BYTE "KIP",0</pre>
  1133.                </div></div><p><br class="example-break"></p>
  1134.            </dd><dt><span class="term"><a name="po_align"></a>ALIGN
  1135.            [&lt;expression equal to 1,2,4,8,16,32,64,128,256,512,1024,2048,4096,8192,16384 or
  1136.            32768&gt;[, &lt;byte&gt;]]</span></dt><dd>
  1137.              <p>Align advances to nearest address where &lt;new address&gt; modulo &lt;expression&gt; (default 4)
  1138.                  equals zero (stays at current address if possible).</p>
  1139.              <p>If &lt;byte&gt; is specified, memory advanced over is set to it.
  1140.                  </p><div class="example"><a name="idp617"></a><p class="title"><b>Example 5.5. </b></p><div class="example-contents">
  1141.                  
  1142.  
  1143.                  <pre class="programlisting">    ALIGN         ; =&gt; ALIGN 4 - simply align by 4
  1144.    ALIGN 2       ; by 2 (preserves value of "device" memory)
  1145.    ALIGN 2,0     ; + fills memory with zero</pre>
  1146.                </div></div><p><br class="example-break"></p>
  1147.            </dd><dt><span class="term"><a name="po_assert"></a>ASSERT &lt;expression&gt;</span></dt><dd>
  1148.              <p>An 'assertion failed' error is issued if the expression
  1149.              evaluates to zero.</p><div class="example"><a name="idp626"></a><p class="title"><b>Example 5.6. </b></p><div class="example-contents">
  1150.                  
  1151.  
  1152.                  <pre class="programlisting">STACKPOINTER=0D500H
  1153.    ASSERT END_OF_PROGRAM &lt; STACKPOINTER
  1154. END_OF_PROGRAM</pre>
  1155.                </div></div><p><br class="example-break"></p>
  1156.            </dd><dt><span class="term"><a name="po_binary"></a>BINARY &lt;filename&gt;[,&lt;offset&gt;[,&lt;length&gt;]]</span></dt><dd>
  1157.              <p>Synonym of <a class="link" href="#po_incbin">INCBIN</a>.</p>
  1158.            </dd><dt><span class="term"><a name="po_block"></a>BLOCK &lt;length&gt;[,&lt;fill
  1159.            byte&gt;]</span></dt><dd>
  1160.              <p>Defines space. Has to be followed by the number of byte to
  1161.              reserve, optionally followed by the value to fill these bytes
  1162.              with.</p><div class="example"><a name="idp641"></a><p class="title"><b>Example 5.7. </b></p><div class="example-contents">
  1163.                  
  1164.  
  1165.                  <pre class="programlisting">    BLOCK 500     ; define a block of 500 bytes of zero
  1166.    BLOCK 500,0   ; define a block of 500 bytes of zero
  1167.    BLOCK 400,-1  ; define a block of 400 bytes of 255</pre>
  1168.                </div></div><p><br class="example-break"></p>
  1169.            </dd><dt><span class="term"><a name="po_bplist"></a>BPLIST &lt;filename&gt; [unreal|zesarux]</span></dt><dd>
  1170.                                 <p>
  1171.                                         <span class="emphasis"><em>Works only in real device emulation mode. See
  1172.                                                 <a class="link" href="#po_device">DEVICE</a>.</em></span>
  1173.                                 </p>
  1174.                                 <p>Opens file to export breakpoints info directly from ASM source, currently two
  1175.                                         flavours of export are supported: <code class="code">unreal</code> (default) and
  1176.                                         <code class="code">zesarux</code>. For latest Unreal emulators use filename "bpx.ini", you
  1177.                                         can then load the file from the emulator UI. For ZEsarUX the file will contain
  1178.                                         command-line options, which you can add to the command when launching the emulator.
  1179.                                 </p>
  1180.                                 <p>(current version of ZEsarUX will not catch the very first instruction of freshly
  1181.                                         loaded snapshot/NEX/... file, or it will even disable breakpoints when changing
  1182.                                         machine parameters and ignore the <code class="code">--enable-breakpoints</code> option - will
  1183.                                         be hopefully improved in the future)
  1184.                                   </p><div class="example"><a name="idp657"></a><p class="title"><b>Example 5.8. </b></p><div class="example-contents">
  1185.                  
  1186.  
  1187.                  <pre class="programlisting">    BPLIST "bpx.ini" unreal  ; open breakpoints list in "Unreal" format
  1188.    ; or (only one file per assembling-unit can be specified)
  1189.    BPLIST "cmd_line_options.txt" zesarux ; open breakpoints list in "ZEsarUX" format</pre>
  1190.                                   </div></div><p><br class="example-break">
  1191.                                 </p>
  1192.            </dd><dt><span class="term"><a name="po_byte"></a>BYTE &lt;bytes&gt;</span></dt><dd>
  1193.              <p>Defines a byte or a string of bytes. Each value should be
  1194.              between -129 and 256.</p><div class="example"><a name="idp665"></a><p class="title"><b>Example 5.9. </b></p><div class="example-contents">
  1195.                  
  1196.  
  1197.                  <pre class="programlisting">    BYTE 0x56
  1198.    BYTE 1,-78,'@'
  1199.    BYTE "Format C:? ",0h</pre>
  1200.                </div></div><p><br class="example-break"></p>
  1201.            </dd><dt><span class="term"><a name="po_cspectmap"></a>CSPECTMAP [&lt;filename&gt;]</span></dt><dd>
  1202.              <p><span class="emphasis"><em>Useful for ZX-Spectrum Emulator
  1203.              #CSpect by Mike Dailly.</em></span></p>
  1204.  
  1205.              <p><span class="emphasis"><em>Works only in real device emulation mode. See
  1206.              <a class="link" href="#po_device">DEVICE</a>.</em></span></p>
  1207.  
  1208.              <p>Saves labels list in format:</p>
  1209.  
  1210.              <pre class="synopsis">HEXA_16BIT_ADDRESS HEXA_LONG_ADDRESS TYPE LABELNAME</pre><p>
  1211.              where TYPE is: 00 = regular label, 01 = EQU or struct defined, 02 = DEFL defined.</p>
  1212.  
  1213.              <p>If no filename is provided, default is created by appending ".map" to source name.</p>
  1214.            </dd><dt><span class="term"><a name="po_d24"></a>D24</span></dt><dd>
  1215.              <p>Defines three bytes by 24b constant. Values should be between
  1216.              -16777217 and 16777216.</p><div class="example"><a name="idp687"></a><p class="title"><b>Example 5.10. </b></p><div class="example-contents">
  1217.                  
  1218.  
  1219.                  <pre class="programlisting">    D24 0x123456   ; define three bytes 0x56, 0x34, 0x12</pre>
  1220.                </div></div><p><br class="example-break"></p>
  1221.            </dd><dt><span class="term"><a name="po_db"></a>DB</span></dt><dd>
  1222.              <p>Synonym of <a class="link" href="#po_byte">BYTE</a>.</p>
  1223.            </dd><dt><span class="term"><a name="po_dc"></a>DC</span></dt><dd>
  1224.              <p>Same as <a class="link" href="#po_byte">BYTE</a>, but every
  1225.              last character of a string will have bit 7 set.</p><div class="example"><a name="idp703"></a><p class="title"><b>Example 5.11. </b></p><div class="example-contents">
  1226.                  
  1227.  
  1228.                  <pre class="programlisting">    DC "kip" ; same as BYTE "ki",'p'|128</pre>
  1229.                </div></div><p><br class="example-break"></p>
  1230.            </dd><dt><span class="term"><a name="po_dd"></a>DD</span></dt><dd>
  1231.              <p>Synonym of <a class="link" href="#po_dword">DWORD</a>.</p>
  1232.            </dd><dt><span class="term"><a name="po_defarray"></a>DEFARRAY &lt;id&gt; &lt;replacements&gt;</span></dt><dd>
  1233.                                 <p>Array of DEFINEs. Use <code class="code">id[#]</code> to retrieve current size of array.</p><div class="example"><a name="idp719"></a><p class="title"><b>Example 5.12. docs_examples/po_defarray.asm</b></p><div class="example-contents">
  1234.                  
  1235.  
  1236.                  <pre class="programlisting">    DEFARRAY myarray 10*20,"A",20,&lt;/D,40&gt;,50,70
  1237. CNT DEFL 0 ;or CNT=0
  1238.    DUP myarray[#]      ; 6
  1239.    DISPLAY myarray[CNT]
  1240. CNT DEFL CNT+1 ;or CNT=CNT+1
  1241.    EDUP</pre>
  1242.                </div></div><p><br class="example-break"></p>
  1243.            </dd><dt><span class="term"><a name="po_defarray_plus"></a>DEFARRAY+ &lt;id&gt; &lt;additional replacements&gt;</span></dt><dd>
  1244.              <p>Appending more DEFINEs to already defined array</p><div class="example"><a name="idp728"></a><p class="title"><b>Example 5.13. </b></p><div class="example-contents">
  1245.                  
  1246.  
  1247.                  <pre class="programlisting">    DEFARRAY   myarray 'A', 'B', 'C'
  1248.    DEFARRAY+  myarray 'D', 'E'            ; now "myarray" has 5 items
  1249.    DUP 3 : DEFARRAY+ myarray '!' : EDUP   ; "DEFARRAYFILL" adding 3x '!'</pre>
  1250.                </div></div><p><br class="example-break"></p>
  1251.            </dd><dt><span class="term"><a name="po_defb"></a>DEFB</span></dt><dd>
  1252.              <p>Synonym of <a class="link" href="#po_byte">BYTE</a>.</p>
  1253.            </dd><dt><span class="term"><a name="po_defd"></a>DEFD</span></dt><dd>
  1254.              <p>Synonym of <a class="link" href="#po_dword">DWORD</a>.</p>
  1255.            </dd><dt><span class="term"><a name="po_defdevice"></a>DEFDEVICE
  1256.            &lt;deviceid&gt;</span></dt><dd>
  1257.              <p>Sorry, not available yet. If you want to see new device in
  1258.              SjASMPlus, please, <a class="link" href="#feedback">write
  1259.              us</a>.</p>
  1260.            </dd><dt><span class="term"><a name="po_defg"></a>DEFG</span></dt><dd>
  1261.              <p>Synonym of <a class="link" href="#po_dg">DG</a>.</p>
  1262.            </dd><dt><span class="term"><a name="po_defh"></a>DEFH</span></dt><dd>
  1263.              <p>Synonym of <a class="link" href="#po_dh">DH</a>.</p>
  1264.            </dd><dt><span class="term"><a name="po_define"></a>DEFINE &lt;id&gt;
  1265.            &lt;replacement&gt;</span></dt><dd>
  1266.              <p>The identifier &lt;id&gt; will be replaced with the
  1267.              &lt;replacement&gt;. The replacement could be omitted, in such
  1268.              case it is still possible to check if the identifier was defined
  1269.              with IFDEF or IFNDEF.</p><div class="example"><a name="idp767"></a><p class="title"><b>Example 5.14. </b></p><div class="example-contents">
  1270.                  
  1271.  
  1272.                  <pre class="programlisting">    DEFINE str_honderd "Honderd"
  1273.    BYTE str_honderd,0             ; BYTE "Honderd",0</pre>
  1274.                </div></div><p><br class="example-break"></p>
  1275.            </dd><dt><span class="term"><a name="po_defl"></a>&lt;label&gt; DEFL &lt;expression&gt;</span></dt><dd>
  1276.              <p>Assigns value of &lt;expression&gt; to symbol &lt;label&gt;. New label defined
  1277.                                   by DEFL is marked internally as "modifiable", allowing to re-assign new values to it with
  1278.                                   further DEFL statements (you can use also <code class="code">=</code> instead of <code class="code">DEFL</code>).
  1279.                                   </p><div class="example"><a name="idp778"></a><p class="title"><b>Example 5.15. </b></p><div class="example-contents">
  1280.                  
  1281.  
  1282.                  <pre class="programlisting">counter DEFL 0
  1283.    DUP 4
  1284.        DB 0xAA, counter
  1285. counter = counter + 1
  1286.    EDUP
  1287. ; machine code produced: AA 00 AA 01 AA 02 AA 03</pre>
  1288.                </div></div><p><br class="example-break"></p>
  1289.            </dd><dt><span class="term"><a name="po_defm"></a>DEFM</span></dt><dd>
  1290.              <p>Synonym of <a class="link" href="#po_byte">BYTE</a>.</p>
  1291.            </dd><dt><span class="term"><a name="po_defs"></a>DEFS</span></dt><dd>
  1292.              <p>Synonym of <a class="link" href="#po_block">BLOCK</a>.</p>
  1293.            </dd><dt><span class="term"><a name="po_defw"></a>DEFW</span></dt><dd>
  1294.              <p>Synonym of <a class="link" href="#po_word">WORD</a>.</p>
  1295.            </dd><dt><span class="term"><a name="po_dephase"></a>DEPHASE</span></dt><dd>
  1296.              <p>Synonym of <a class="link" href="#po_ent">ENT</a>.</p>
  1297.            </dd><dt><span class="term"><a name="po_device"></a>DEVICE &lt;deviceid&gt;[, &lt;RAMTOP&gt;]</span></dt><dd>
  1298.              <p>Enables <a class="link" href="#s_realdevice">real device emulation
  1299.              mode</a> by it identifier. If there is only single DEVICE directive
  1300.              in whole source batch, it becomes "global" and the device affects all
  1301.              lines of source, otherwise the DEVICE is applied for lines following it.</p>
  1302.  
  1303.              <p>For ZXSPECTRUM-like devices (except ZX Next) you can provide RAMTOP value,
  1304.                                   which will init the device memory in similar way as "<code class="code">CLEAR &lt;RAMTOP&gt;</code>"
  1305.                                   in BASIC would do, putting top of the fake-stack at the RAMTOP address. The
  1306.                                   default RAMTOP is since v1.15.0 0x5D5B (it was 0xFF57 before).</p>
  1307.  
  1308.              <p>Predefined devices' identifiers list:</p>
  1309.  
  1310.              <pre class="synopsis"> NONE ; off real device emulation mode
  1311. ZXSPECTRUM48  ; ZX-Spectrum 48 (4 slots, 4 pages, slot/page size 0x4000, default map: 0, 1, 2, 3)
  1312. ZXSPECTRUM128 ; ZX-Spectrum 128 (like 48 with 8 pages, default map: 7, 5, 2, 0)
  1313. ZXSPECTRUM256 ; e.g. Scorpion 256 (exUSSR clone of ZX-Spectrum 128)
  1314. ZXSPECTRUM512 ; e.g. ATM-Turbo 512 (another clone)
  1315. ZXSPECTRUM1024
  1316. ZXSPECTRUM2048
  1317. ZXSPECTRUM4096
  1318. ZXSPECTRUM8192
  1319. ZXSPECTRUMNEXT ; ZX Spectrum Next (8 slots, 224 pages, slot size 0x2000 = 1.75MiB RAM)
  1320.                ; (default pages map: 14, 15, 10, 11, 4, 5, 0, 1) (default slot: 7 (0xE000..0xFFFF))
  1321.  
  1322. ;disable:
  1323.   DEVICE NONE
  1324. ;enable:
  1325.   DEVICE ZXSPECTRUM128</pre>
  1326.            </dd><dt><span class="term"><a name="po_dg"></a>DG &lt;data encoded in bits&gt;</span></dt><dd>
  1327.              <p>Data comprises of characters in multiples of eight, each block
  1328.              is converted to a byte value.</p>
  1329.  
  1330.              <p>A hyphen '-' (also '.' and '_') represents 0 and any other non-whitespace character
  1331.              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)</p><div class="example"><a name="idp822"></a><p class="title"><b>Example 5.16. </b></p><div class="example-contents">
  1332.                  
  1333.                  <pre class="programlisting">    DG 1-1----1  ; store 161 at the current location
  1334.    DG ...# #... .##. .... ; store two bytes: 0x18, 0x60</pre>
  1335.              </div></div><p><br class="example-break"></p>
  1336.            </dd><dt><span class="term"><a name="po_dh"></a>DH "&lt;data&gt;"[,"&lt;data2&gt;"...]</span></dt><dd>
  1337.              <p>The data string comprises pairs of hexadecimal digits, each pair is converted to
  1338.              a byte value. You can add spaces between pairs as you like. (since v1.11)</p><div class="example"><a name="idp831"></a><p class="title"><b>Example 5.17. </b></p><div class="example-contents">
  1339.                  
  1340.                  <pre class="programlisting">    DH "0123456789ABCDEF"   ; eight bytes #01 #23 ...
  1341.    DH "01 23  45 67"       ; four bytes #01 #23 #45 #67</pre>
  1342.              </div></div><p><br class="example-break"></p>
  1343.            </dd><dt><span class="term"><a name="po_disp"></a>DISP &lt;address&gt;[,&lt;page_number&gt;]</span></dt><dd>
  1344.              <p>Set the address in which the part of code should work.
  1345.              <a class="link" href="#po_phase">PHASE</a> and <a class="link" href="#po_textarea">TEXTAREA</a> are synonyms of DISP.
  1346.              <a class="link" href="#po_ent">ENT</a> will restore current address.
  1347.              <a class="link" href="#po_unphase">UNPHASE</a>, <a class="link" href="#po_dephase">DEPHASE</a> and <a class="link" href="#po_endt">ENDT</a> are synonyms of <a class="link" href="#po_ent">ENT</a>. DISP blocks can NOT be nested, and to change
  1348.              the displacement address within current DISP block use the ordinary ORG.
  1349.              When in device mode, you can specify fixed value for "fake" page of emitted
  1350.              instructions and regular labels, but to avoid warning, you must also map-in
  1351.              the target page into the target memory slot (<a class="link" href="#po_mmu">MMU</a>).
  1352.              When no fixed page in DISP is specified, the current mapping of memory pages is used.
  1353.              </p><div class="example"><a name="idp848"></a><p class="title"><b>Example 5.18. docs_examples/po_disp.asm</b></p><div class="example-contents">
  1354.                  
  1355.  
  1356.                  <pre class="programlisting">    DEVICE ZXSPECTRUM48
  1357. SCREEN  EQU $4000
  1358.        ORG $8000
  1359.        LD HL,BEGIN
  1360.        LD DE,SCREEN
  1361.        LD BC,ENDOFPROG-BEGIN
  1362.        LDIR
  1363.        JP SCREEN
  1364. BEGIN   DISP SCREEN ;code will compile for address $4000, but to the current ORG
  1365. MARKA       DEC A
  1366.            HALT
  1367.            JP NZ,MARKA
  1368.            DI
  1369.            HALT
  1370.        ENT
  1371. ENDOFPROG
  1372.  
  1373.    ASSERT $800E == BEGIN &amp;&amp; $8015 == ENDOFPROG &amp;&amp; $4000 == MARKA
  1374.    ASSERT $76 == {B $800F}     ; HALT instruction lands at $800F (BEGIN+1)</pre>
  1375.                </div></div><p><br class="example-break"></p>
  1376.            </dd><dt><span class="term"><a name="po_display"></a>DISPLAY &lt;bytes&gt;</span></dt><dd>
  1377.              <p><span class="emphasis"><em>This pseudo-op comes from ZX-Spectrum assembler
  1378.              ALASM.</em></span></p>
  1379.  
  1380.              <p>Out to console a string of bytes. Each value should be
  1381.              between -129 and 256. Keys /D, /H and /A set format of output of
  1382.              numbers:</p><pre class="synopsis">/D - out only in Decimal
  1383. /H - out only in Hexadecimal
  1384. /A - out both in Hexadecimal and Decimal</pre><p>
  1385.              </p><div class="example"><a name="idp860"></a><p class="title"><b>Example 5.19. docs_examples/po_display.asm</b></p><div class="example-contents">
  1386.                  
  1387.  
  1388.                  <pre class="programlisting">    ORG 100h
  1389. TESTLABEL:
  1390.    ;...some code...
  1391.    RET
  1392.    DISPLAY "--the some program-- by me"
  1393.    DISPLAY "TESTLABEL address is:",/A,TESTLABEL
  1394. /*
  1395. will output to the console strings:
  1396. &gt; --the some program-- by me
  1397. &gt; TESTLABEL address is:0x100, 256
  1398. */</pre>
  1399.                </div></div><p><br class="example-break"></p>
  1400.            </dd><dt><span class="term"><a name="po_dm"></a>DM</span></dt><dd>
  1401.              <p>Synonym of <a class="link" href="#po_byte">BYTE</a>.</p>
  1402.            </dd><dt><span class="term"><a name="po_ds"></a>DS</span></dt><dd>
  1403.              <p>Synonym of <a class="link" href="#po_block">BLOCK</a>.</p>
  1404.            </dd><dt><span class="term"><a name="po_dup"></a>DUP &lt;count&gt;</span></dt><dd>
  1405.              <p>DUP specifies the number of times to generate the
  1406.              following lines until an EDUP pseudo-op is encountered. DUP can be used in macro's.</p><div class="example"><a name="idp881"></a><p class="title"><b>Example 5.20. </b></p><div class="example-contents">
  1407.                  
  1408.  
  1409.                  <pre class="programlisting">    DUP 3
  1410.    NOP
  1411.    EDUP
  1412.  
  1413. /*this will expand to:
  1414.    NOP
  1415.    NOP
  1416.    NOP
  1417. */</pre>
  1418.                </div></div><p><br class="example-break"></p>
  1419.            </dd><dt><span class="term"><a name="po_dw"></a>DW</span></dt><dd>
  1420.              <p>Synonym of <a class="link" href="#po_word">WORD</a>.</p>
  1421.            </dd><dt><span class="term"><a name="po_dword"></a>DWORD</span></dt><dd>
  1422.              <p>Defines a so called doubleword. Values should be between
  1423.              -2147483649 and 4294967296.</p><div class="example"><a name="idp896"></a><p class="title"><b>Example 5.21. </b></p><div class="example-contents">
  1424.                  
  1425.  
  1426.                  <pre class="programlisting">    DWORD 4000h,0d000h
  1427.    DWORD 4</pre>
  1428.                </div></div><p><br class="example-break"></p>
  1429.            </dd><dt><span class="term"><a name="po_dz"></a>DZ</span></dt><dd>
  1430.              <p>Same as <a class="link" href="#po_byte">BYTE</a>, but an extra
  1431.              zero will be added at the end.</p><div class="example"><a name="idp906"></a><p class="title"><b>Example 5.22. </b></p><div class="example-contents">
  1432.                  
  1433.  
  1434.                  <pre class="programlisting">    DZ 1      ; same as BYTE 1,0
  1435.    DZ "kip"  ; same as BYTE "kip",0</pre>
  1436.                </div></div><p><br class="example-break"></p>
  1437.            </dd><dt><span class="term"><a name="po_emptytap"></a>EMPTYTAP &lt;filenameoftapefile&gt;</span></dt><dd>
  1438.              <p><span class="emphasis"><em>Useful only for ZX-Spectrum
  1439.              users</em></span></p>
  1440.  
  1441.              <p>Create the new or truncate existing standard tape file
  1442.              for emulators of ZX-Spectrum. See example of
  1443.              <a class="link" href="#po_savetap">SAVETAP</a>.</p>
  1444.            </dd><dt><span class="term"><a name="po_emptytrd"></a>EMPTYTRD &lt;filenameoftrdimage&gt;[,&lt;disclabel&gt;]</span></dt><dd>
  1445.              <p><span class="emphasis"><em>Useful only for ZX-Spectrum users</em></span></p>
  1446.  
  1447.              <p>Create the empty TRD image for emulators of ZX-Spectrum.
  1448.              See example of <a class="link" href="#po_savetrd">SAVETRD</a>.</p>
  1449.            </dd><dt><span class="term"><a name="po_encoding"></a>ENCODING &lt;encoding&gt;</span></dt><dd>
  1450.              <p><span class="emphasis"><em>Useful only for non English
  1451.              users</em></span></p>
  1452.  
  1453.              <p>Set the current encoding, i.e. if you set "DOS", SjASMPlus
  1454.              will automatically convert strings from ANSI to DOS-866.
  1455.              Encoding may be "DOS"(DOS-866) or "WIN"(ANSI/Win-1251). Default
  1456.              is "WIN". </p><div class="example"><a name="idp933"></a><p class="title"><b>Example 5.23. </b></p><div class="example-contents">
  1457.                  
  1458.  
  1459.                  <pre class="programlisting">    ENCODING "WIN"
  1460.    DB "тексттекст" ;will be тексттекст
  1461.    ENCODING "DOS"
  1462.    DB "тексттекст" ;will be ⥪бв⥪бв</pre>
  1463.                </div></div><p><br class="example-break"></p>
  1464.            </dd><dt><span class="term"><a name="po_end"></a>END [&lt;startaddress&gt;]</span></dt><dd>
  1465.              <p>The assembler will stop at this point. The pseudo-op
  1466.              END does NOT work in the beginning of line (even with --dirbol).
  1467.              The optional argument is used by SAVESNA, SAVETAP and SAVENEX.</p>
  1468.            </dd><dt><span class="term"><a name="po_endlua"></a>ENDLUA</span></dt><dd>
  1469.              <p>See <a class="link" href="#po_lua">LUA</a> for more
  1470.              information.</p>
  1471.            </dd><dt><span class="term"><a name="po_endmod"></a>ENDMOD</span></dt><dd>
  1472.              <p>Synonym of <a class="link" href="#po_endmodule">ENDMODULE</a>.</p>
  1473.            </dd><dt><span class="term"><a name="po_endmodule"></a>ENDMODULE</span></dt><dd>
  1474.              <p>To indicate the end of a module (see <a class="link" href="#po_module">MODULE</a>).</p>
  1475.            </dd><dt><span class="term"><a name="po_endt"></a>ENDT</span></dt><dd>
  1476.              <p>Synonym of <a class="link" href="#po_ent">ENT</a>.</p>
  1477.            </dd><dt><span class="term"><a name="po_ent"></a>ENT</span></dt><dd>
  1478.              <p>Restore current address. See <a class="link" href="#po_disp">DISP</a> for more information.</p>
  1479.            </dd><dt><span class="term"><a name="po_equ"></a>&lt;label&gt; EQU &lt;expression&gt;</span></dt><dd>
  1480.              <p>To give the label a value other than the current program
  1481.              counter. The label should not already exist (you can assign only one value to it).
  1482.                           For modifiable labels holding temporary values use <a class="link" href="#po_defl">DEFL</a>.</p><div class="example"><a name="idp978"></a><p class="title"><b>Example 5.24. </b></p><div class="example-contents">
  1483.                  
  1484.  
  1485.                  <pre class="programlisting">Label EQU 3
  1486. Kip   EQU 0x23*256 + low $</pre>
  1487.                </div></div><p><br class="example-break"></p>
  1488.            </dd><dt><span class="term"><a name="po_export"></a>EXPORT &lt;label&gt;</span></dt><dd>
  1489.              <p>The named label will be written to the export-file, in the
  1490.              form 'label: EQU value'. This way the export-file can be
  1491.              included in other sources.</p><div class="example"><a name="idp987"></a><p class="title"><b>Example 5.25. </b></p><div class="example-contents">
  1492.                  
  1493.  
  1494.                  <pre class="programlisting">DRIE=3
  1495.    EXPORT DRIE  ; adds into export file line: "DRIE: EQU 0x00000003"</pre>
  1496.                </div></div><p><br class="example-break"></p>
  1497.            </dd><dt><span class="term"><a name="po_fpos"></a>FPOS &lt;position&gt;</span></dt><dd>
  1498.              <p>The FPOS directive makes it possible to set the file
  1499.              position to anywhere in the output file. Position value without sign
  1500.              is used as absolute one to be set, position starting with + or - sign will be
  1501.              used as relative position.</p>
  1502.  
  1503.              <p>In combination with <a class="link" href="#po_output">OUTPUT</a> &lt;filename&gt;,r it is
  1504.              possible to update existing files.</p>
  1505.  
  1506.              <div class="example"><a name="idp999"></a><p class="title"><b>Example 5.26. </b></p><div class="example-contents">
  1507.                  
  1508.  
  1509.                  <pre class="programlisting">; This example will result in a file with a length of one byte:
  1510.    BYTE 0
  1511.    FPOS 0
  1512.    BYTE 1
  1513.    END</pre>
  1514.                </div></div><p><br class="example-break"></p>
  1515.            </dd><dt><span class="term"><a name="po_hex"></a>HEX</span></dt><dd>
  1516.              <p>Synonym of <a class="link" href="#po_dh">DH</a>, usually used without quotes around data.</p>
  1517.            </dd><dt><span class="term"><a name="po_incbin"></a>INCBIN
  1518.            &lt;filename&gt;[,&lt;offset&gt;[,&lt;length&gt;]]</span></dt><dd>
  1519.              <p>To include a binary file into the outputfile. The offset
  1520.              and length are optional. Added in v1.12.1: if negative offset or length is provided,
  1521.              it counts relatively from the end of the file.</p><div class="example"><a name="idp1014"></a><p class="title"><b>Example 5.27. </b></p><div class="example-contents">
  1522.                  
  1523.  
  1524.                  <pre class="programlisting">    INCBIN "gfx.scc",7        ; include gfx.scc, skip first 7 bytes
  1525.    INCBIN "rantab.com",3,256 ; include 256 bytes from offset 3
  1526.    INCBIN gfx.scc ,,7        ; 7 bytes from offset 0 (unquoted filename must end with space)
  1527.    INCBIN "48.rom",-768,-256 ; include (from 16kiB file) 512 bytes 15616..16127</pre>
  1528.                </div></div><p><br class="example-break"></p>
  1529.            </dd><dt><span class="term"><a name="po_inchob"></a>INCHOB &lt;filename&gt;[,&lt;offset&gt;[,&lt;length&gt;]]</span></dt><dd>
  1530.              <p>To include a data from a hobeta file into the outputfile.
  1531.              The offset and length are optional.</p><div class="example"><a name="idp1023"></a><p class="title"><b>Example 5.28. </b></p><div class="example-contents">
  1532.                  
  1533.  
  1534.                  <pre class="programlisting">    INCHOB "gfx.$c",7        ; include gfx.scc, skip first 7 bytes
  1535.    INCHOB "sprs.$c",3,256   ; include 256 bytes from offset 3
  1536.    INCHOB gfx.$c ,7        ; note the space between the filename and the ',7' here :)</pre>
  1537.                </div></div><p><br class="example-break"></p>
  1538.            </dd><dt><span class="term"><a name="po_include"></a>INCLUDE &lt;filename&gt;</span></dt><dd>
  1539.              <p>To include another sourcefile into the current.
  1540.              Sourcefiles can be nested 20 levels deep. If the file cannot be
  1541.              found in the current directory (the current directory is the
  1542.              directory the current asm file comes from!) the file will be searched
  1543.              for in the directories specified at the commandline. When angle
  1544.              brackets are used, the commandline directories are searched
  1545.              before the current directory.</p>
  1546.              <p>The directory used to launch the assembling process is automatically added
  1547.              to the list (as if "<code class="code">-i.</code>" was added to command line manually)
  1548.              (v1.14.0 and v1.14.1 don't add it, reverted back for v1.14.2). If you want to start
  1549.              with completely empty include-path list, use "<code class="code">--inc</code>" option
  1550.              early (order matters) without the "=" to empty the current list, like:
  1551.              <code class="code">sjasmplus --inc --inc=path1 --inc=path2 file.asm</code>
  1552.              </p><div class="example"><a name="idp1036"></a><p class="title"><b>Example 5.29. </b></p><div class="example-contents">
  1553.                  
  1554.  
  1555.                  <pre class="programlisting">    INCLUDE &lt;VDP.I&gt;     ; search for file "VDP.I" in the include directories, then in current
  1556.    INCLUDE MORE.I      ; search for "MORE.I" in current directory, then in include directories
  1557.    INCLUDE "MORE.I"</pre>
  1558.                </div></div><p><br class="example-break"></p>
  1559.            </dd><dt><span class="term"><a name="po_includelua"></a>INCLUDELUA &lt;filename&gt;</span></dt><dd>
  1560.              <p>To include another LUA script in first pass(!). If the
  1561.              file cannot be found in the current directory (the current
  1562.              directory is the directory the current file comes from) the file
  1563.              will be searched for in the directories specified at the
  1564.              commandline. When angle brackets are used, the commandline
  1565.              directories are searched before the current directory.</p><div class="example"><a name="idp1045"></a><p class="title"><b>Example 5.30. </b></p><div class="example-contents">
  1566.                  
  1567.  
  1568.                  <pre class="programlisting">    INCLUDELUA &lt;mylibrary1.lua&gt;
  1569.    INCLUDELUA mylibrary2.lua
  1570.    INCLUDELUA "library_for_zx.lua"</pre>
  1571.                </div></div><p><br class="example-break"></p>
  1572.            </dd><dt><span class="term"><a name="po_inctrd"></a>INCTRD
  1573.            &lt;filenameoftrdimage&gt;,&lt;filenameintrdimage&gt;[,&lt;offset&gt;[,&lt;length&gt;]]</span></dt><dd>
  1574.              <p>To include a file from a TRD image into the outputfile.
  1575.              The offset and length are optional.</p><div class="example"><a name="idp1054"></a><p class="title"><b>Example 5.31. </b></p><div class="example-contents">
  1576.                  
  1577.  
  1578.                  <pre class="programlisting">    INCTRD "test.trd","mygfx.C" ; include mygfx.C from test.trd
  1579.    INCTRD "test.trd","mygfx.C",12 ; include mygfx.C from test.trd, skip first 12 bytes</pre>
  1580.                </div></div><p><br class="example-break"></p>
  1581.            </dd><dt><span class="term"><a name="po_insert"></a>INSERT &lt;filename&gt;[,&lt;offset&gt;[,&lt;length&gt;]]</span></dt><dd>
  1582.              <p>INSERT is a synonym of <a class="link" href="#po_incbin">INCBIN</a>. See above.</p>
  1583.            </dd><dt><span class="term"><a name="po_labelslist"></a>LABELSLIST &lt;filename&gt;</span></dt><dd>
  1584.              <p><span class="emphasis"><em>Useful only for ZX-Spectrum Emulator
  1585.              UNREALSPECCY.</em></span></p>
  1586.  
  1587.              <p><span class="emphasis"><em>Work only in real device emulation mode. See
  1588.              <a class="link" href="#po_device">DEVICE</a>.</em></span></p>
  1589.  
  1590.              <p>Save labels list in format:</p>
  1591.  
  1592.              <pre class="synopsis">NN:ADDRESS LABELNAME</pre><p>
  1593.              where NN is number of RAM page and ADDRESS is truncated to 0000..3FFF range</p>
  1594.  
  1595.              <div class="example"><a name="idp1077"></a><p class="title"><b>Example 5.32. </b></p><div class="example-contents">
  1596.                  
  1597.  
  1598.                  <pre class="programlisting">    LABELSLIST "x:/somepath/user.l"</pre>
  1599.                </div></div><p><br class="example-break"></p>
  1600.            </dd><dt><span class="term"><a name="po_lua"></a>LUA [pass] [; ok comment to suppress "emit with allpass" warning]</span></dt><dd>
  1601.              <p>Using pseudo-ops LUA and ENDLUA you can insert Lua
  1602.              scripts. See more in the chapter "<a class="link" href="#c_lua_scripting">Lua scripting</a>".</p>
  1603.  
  1604.              <p>Parameter is optional. It may be:</p><pre class="synopsis">PASS1   -  interpret Lua script in first pass only.
  1605. PASS2   -  interpret Lua script in second pass only.
  1606. PASS3   -  interpret Lua script in third pass only. By default.
  1607. ALLPASS -  interpret Lua script in all passes. It is need, if you generate some Z80 code.</pre>
  1608.  
  1609.              <div class="example"><a name="idp1090"></a><p class="title"><b>Example 5.33. </b></p><div class="example-contents">
  1610.                  
  1611.  
  1612.                  <pre class="programlisting">    LUA
  1613. -- some comments
  1614.        print "Hi, man! This is Lua!"
  1615.    ENDLUA
  1616. ; some code now:
  1617.    LUA ALLPASS
  1618.        _pl("LABEL LD A,10")
  1619.        _pc("RET")
  1620.    ENDLUA</pre>
  1621.                </div></div><p><br class="example-break"></p>
  1622.            </dd><dt><span class="term"><a name="po_memorymap"></a>MEMORYMAP</span></dt><dd>
  1623.              <p>Not available yet.</p>
  1624.            </dd><dt><span class="term"><a name="po_mmu"></a>MMU &lt;first slot number&gt; [&lt;last slot number&gt;|&lt;single slot option&gt;], &lt;page number&gt;[,&lt;address&gt;]</span></dt><dd>
  1625.              <p>Maps memory page(s) to slot(s), similar to SLOT + PAGE combination, but allows
  1626.              to set up whole range of consecutive slots (with consecutive memory pages). Or when
  1627.              only single slot is specified, extra option can be used to extend particular slot
  1628.              functionality. The slot behaviour will stay set in the current DEVICE until reset
  1629.              by another MMU specifying same slot (even as part of range, that will clear the option
  1630.              to "default").</p>
  1631.  
  1632.                   <p>The optional third argument is address for <a class="link" href="#po_org">ORG</a>
  1633.                           functionality.</p>
  1634.  
  1635.              <p>Single slot option (default state is: no error/warning and no wrap = nothing special):
  1636.                </p><pre class="synopsis">e = error on writing beyond last byte of slot
  1637. w = warning on writing beyond last byte of slot
  1638. n = wrap address back to start of slot, map next page</pre><p>
  1639.                </p><div class="example"><a name="idp1108"></a><p class="title"><b>Example 5.34. docs_examples/po_mmu.asm</b></p><div class="example-contents">
  1640.                  
  1641.  
  1642.                  <pre class="programlisting">    DEVICE ZXSPECTRUM128 : LABELSLIST "po_mmu.lbl"  ; to check label pages
  1643.    MMU 1 3, 5      ; maps slots 1, 2, 3 with pages 5, 6, 7
  1644.    ORG 0xBFFF
  1645. label1_p6: scf      ; last byte of page 6 (in slot 2)
  1646. label2_p7: scf      ; first byte of page 7 (in slot 3)
  1647.  
  1648.    MMU 3 e, 0      ; page 0 into slot 3, write beyond slot will cause error
  1649.    ORG 0xFFFF
  1650.    ld  a,1         ; error: Write outside of memory slot: 65536 (65536 = address outside)
  1651.  
  1652.    MMU 3 n, 1      ; page 1 into slot 3, make it wrap + map next page automatically
  1653.    ORG 0xFFFF      ; ! also the $ address was truncated by MMU from $10001 to $0001 !
  1654. label3_p1: scf      ; last byte of page 1, then wrapping back to 0xC000 with page 2
  1655. label4_p2: scf      ; first byte of page 2 at 0xC000</pre>
  1656.                </div></div><p><br class="example-break"></p>
  1657.            </dd><dt><span class="term"><a name="po_module"></a>MODULE &lt;name&gt;</span></dt><dd>
  1658.              <p>
  1659.                                   Labels has to be unique only whithin the current module (module is added as prefix to them).
  1660.                                   Also note the use of '@' operator to suppress all this label-processing. Modules can
  1661.                                   be nested, and module has to be ended by <a class="link" href="#po_endmodule">ENDMODULE</a>.
  1662.                           </p><div class="example"><a name="idp1118"></a><p class="title"><b>Example 5.35. docs_examples/po_module.asm</b></p><div class="example-contents">
  1663.                  
  1664.  
  1665.                  <pre class="programlisting">    MODULE xxx
  1666. Kip:                ; label xxx.Kip
  1667.    ld  hl,@Kip     ; global Kip
  1668.    ld  hl,@Kop     ; global Kop
  1669.    ld  hl,Kop      ; xxx.Kop
  1670. Kop:                ; label xxx.Kop
  1671.    ld  hl,Kip      ; xxx.Kip
  1672.    ld  hl,yyy.Kip  ; yyy.Kip
  1673.    ld  hl,nested.Kip   ; xxx.nested.Kip
  1674.        MODULE nested
  1675. Kip:        ret     ; label xxx.nested.Kip
  1676.        ENDMODULE
  1677.    ENDMODULE
  1678.  
  1679.    MODULE yyy
  1680. Kip:    ret         ; label yyy.Kip
  1681. @Kop:   ret         ; label Kop (global one, no module prefix)
  1682. @xxx.Kop: nop       ; ERROR: duplicate: label xxx.Kop
  1683.    ENDMODULE
  1684.  
  1685. Kip     ret         ; global label Kip</pre>
  1686.                </div></div><p><br class="example-break">
  1687.                                 Since v1.14.0 the module <code class="code">&lt;name&gt;</code> can NOT contain dot character. You can
  1688.                                 use nested modules to get identical identifier as in older versions, or please rename with
  1689.                                 underscores/etc:
  1690.                                 </p><pre class="programlisting">    ; invalid since v1.14.0
  1691.        MODULE older.version
  1692. fn1:        ret        ; final label: @older.version.fn1
  1693.        ENDMODULE
  1694.    ; can be replaced in v1.14.0 with
  1695.        MODULE new
  1696.            MODULE version
  1697. fn1:            ret    ; final label: @new.version.fn1
  1698.            ENDMODULE
  1699.        ENDMODULE</pre><p>
  1700.         Since v1.14.0 the <code class="code">MODULE</code> and <code class="code">ENDMODULE</code> also resets the current "non-local"
  1701. label prefix back to "_":
  1702. </p><pre class="programlisting">Kep:    ; "Kep" label (global one), and also works as "non-local" prefix for local labels
  1703.    MODULE zzz
  1704. .local: ; in v1.14.0 this will be "zzz._.local" label, previously it was "zzz.Kep.local"
  1705. Kup:    ; this is "zzz.Kup", but also defines "non-local" prefix as "Kup"
  1706. .local  ; this is "zzz.Kup.local"
  1707.    ENDMODULE
  1708. .local: ; in v1.14.0 this will be "_.local" label, previously it was "Kup.local"</pre><p>
  1709.                                 </p>
  1710.            </dd><dt><span class="term"><a name="po_opt"></a><p>OPT [push] [reset] [listoff] [liston] [&lt;command line options&gt;]</p>
  1711.                         <p>OPT pop</p></span></dt><dd>
  1712.              <p>Allows to reset and modify <a class="link" href="#s_cli">options</a> affecting syntax and
  1713.                                   parsing (for lines of source following the OPT). The options allowed for OPT
  1714.                                   are: <code class="code">--nofakes</code>, <code class="code">--syntax</code>, <code class="code">--zxnext</code>,
  1715.                                   <code class="code">--reversepop</code> and <code class="code">--dirbol</code>.
  1716.                           </p>
  1717.                           <p>
  1718.                                   Ahead of options you can use OPT commands: push, pop, reset, listoff, liston.
  1719.                                   The "push" command will make OPT to preserve current state of options. The "reset"
  1720.                                   command will reset OPT-related options to default state. The "listoff" command will
  1721.                                   suspend the listing for following lines until "liston" command is used (listing
  1722.                                   availability is part of the push/pop state, so to "nest" listing-off you can use
  1723.                                   "OPT push listoff : ... code ... : OPT pop" code sequence.
  1724.                           </p>
  1725.                           <p>Then the provided options are applied. The default values are: fake instructions
  1726.                                   enabled (no warning), multi-argument delimiter is ",", both () and [] brackets
  1727.                                   can be used to access memory, labels can have any name, ZX Next instructions are OFF,
  1728.                                   POP with multiple arguments doesn't reverse them and pseudo-ops at beginning of
  1729.                                   line are OFF (to just reset to these defaults you can use <code class="code">OPT reset</code>).
  1730.              </p>
  1731.                           <p>The "pop" command: the previously preserved state of options is restored (states
  1732.                                   are preserved in "stack" way, so further OPT with "pop" will restore older states).
  1733.                           </p>
  1734.                           <div class="example"><a name="idp1143"></a><p class="title"><b>Example 5.36. docs_examples/po_opt.asm</b></p><div class="example-contents">
  1735.                  
  1736.  
  1737.                  <pre class="programlisting">    POP bc, hl   ; pops BC first
  1738.    OPT push reset --reversepop --syntax=af
  1739.    POP bc,,hl   ; pops HL first
  1740.    LD  bc,hl    ; warning about Fake instruction
  1741.    LD  bc,hl    ; warning supressed by lowercase "fake" in this comment
  1742.    OPT reset --syntax=a
  1743.    POP bc,,hl   ; pop BC first (--reversepop was reset)
  1744.    OPT pop      ; restoring syntax to original state</pre>
  1745.                           </div></div><br class="example-break">
  1746.            </dd><dt><span class="term"><a name="po_org"></a>ORG &lt;address&gt;[,&lt;page_number&gt;]</span></dt><dd>
  1747.              <p>Set the program counter to a specific address. If the second argument is
  1748.              provided, it will change memory page in the current slot, see
  1749.              <a class="link" href="#po_page">PAGE</a> and <a class="link" href="#po_slot">SLOT</a> (it will
  1750.              warn you when &lt;address&gt; is outside of it, you can suppress the warning with
  1751.              ";ok" comment).</p>
  1752.              <p>When used inside <a class="link" href="#po_disp">DISP</a> block, only the virtual
  1753.                                   "displaced" program counter is affected, but the machine code will be still
  1754.                                   sequentially emitted in the original physical location and warning is emitted
  1755.                                   (you can suppress the warning with ";ok" comment, if you want to use ORG
  1756.                                   intentionally in this way).
  1757.                  </p><div class="example"><a name="idp1155"></a><p class="title"><b>Example 5.37. docs_examples/po_org.asm</b></p><div class="example-contents">
  1758.                  
  1759.  
  1760.                  <pre class="programlisting">    ORG 100h ; or 0x100, or $100, or #100
  1761.  
  1762.    ; useful macro that padding code
  1763.    MACRO PADORG addr
  1764.         ; add padding
  1765.         IF $ &lt; addr
  1766.         BLOCK addr-$
  1767.         ENDIF
  1768.         ORG addr
  1769.    ENDM
  1770.  
  1771.    MACRO PADORG2 addr ; z80asm "FORG" replacement
  1772.         ; add padding + display warning
  1773.         IF $ &gt; addr
  1774.           ; no padding
  1775.           DISPLAY /L, "Warning! PADORG failed! ", $, " is more than ", addr
  1776.         ELSE
  1777.           ; add padding
  1778.           BLOCK addr-$
  1779.         ENDIF
  1780.         ORG addr
  1781.    ENDM</pre>
  1782.                </div></div><p><br class="example-break"></p>
  1783.            </dd><dt><span class="term"><a name="po_outend"></a>OUTEND</span></dt><dd>
  1784.              <p>Ends generating compiler output to file specified in OUTPUT and resets
  1785.              <a class="link" href="#po_size">SIZE</a> value to default "none".</p>
  1786.            </dd><dt><span class="term"><a name="po_output"></a>OUTPUT
  1787.            [&lt;filename&gt;[,&lt;mode&gt;]]</span></dt><dd>
  1788.              <p>With OUTPUT it is possible to create multiple files from
  1789.              one source. All following instructions will be assembled to this
  1790.              file. It will also <a class="link" href="#po_outend">close (OUTEND)</a>
  1791.              and finalize any previously opened output.</p>
  1792.  
  1793.              <p>There are three possible output modes: truncate (overwrite
  1794.              existing files, this is the default), rewind (open and execute
  1795.              FPOS 0) and append (open and leave the file pointer at the end
  1796.              of the file).</p><pre class="synopsis">OUTPUT &lt;filename&gt;,t  ; truncate (default)
  1797. OUTPUT &lt;filename&gt;,r  ; rewind
  1798. OUTPUT &lt;filename&gt;,a  ; append</pre><p>
  1799.              </p><div class="example"><a name="idp1173"></a><p class="title"><b>Example 5.38. bigfile.asm</b></p><div class="example-contents">
  1800.                  
  1801.  
  1802.                  <pre class="programlisting">    OUTPUT loader.com
  1803.    ORG 100H
  1804.    INCLUDE loader.asm
  1805.    INCLUDE bios.asm
  1806.  
  1807.    OUTPUT bigfile.dat
  1808.    ORG 4000H
  1809.    INCLUDE main.asm
  1810.    ORG 8000H
  1811.    INCLUDE data.asm
  1812.    OUTEND
  1813.    INCLUDE next.asm</pre>
  1814.                </div></div><p><br class="example-break">This will create two files: loader.com and
  1815.              bigfile.dat.</p>
  1816.  
  1817.            </dd><dt><span class="term"><a name="po_page"></a>PAGE &lt;number&gt;</span></dt><dd>
  1818.              <p><span class="emphasis"><em>Work only in real device emulation mode. See
  1819.              <a class="link" href="#po_device">DEVICE</a>.</em></span></p>
  1820.  
  1821.              <p>Set the current memory page to current slot.</p>
  1822.  
  1823.              <div class="example"><a name="idp1186"></a><p class="title"><b>Example 5.39. </b></p><div class="example-contents">
  1824.                  
  1825.  
  1826.                  <pre class="programlisting">    PAGE 7 ;set 7 page
  1827.    SAVEBIN "ram7.bin",$C000,$4000 ;- save $4000 begin from $C000 of RAM to file</pre>
  1828.                </div></div><p><br class="example-break"></p>
  1829.            </dd><dt><span class="term"><a name="po_phase"></a>PHASE</span></dt><dd>
  1830.              <p>Synonym of <a class="link" href="#po_disp">DISP</a>.</p>
  1831.            </dd><dt><span class="term"><a name="po_rept"></a>REPT &lt;count&gt;</span></dt><dd>
  1832.              <p>Synonym of <a class="link" href="#po_dup">DUP</a>. There is also synonym ENDR to end REPT block (EDUP works too).</p>
  1833.            </dd><dt><span class="term"><a name="po_savebin"></a>SAVEBIN
  1834.            &lt;filename&gt;,&lt;startadress&gt;,&lt;lengthofcode&gt;</span></dt><dd>
  1835.              <p><span class="emphasis"><em>Works only in real device emulation mode. See
  1836.              <a class="link" href="#po_device">DEVICE</a>.</em></span></p>
  1837.  
  1838.              <p>Save the block of RAM.</p>
  1839.  
  1840.              <div class="example"><a name="idp1211"></a><p class="title"><b>Example 5.40. </b></p><div class="example-contents">
  1841.                  
  1842.  
  1843.                  <pre class="programlisting">    PAGE 7 ;set 7 page to current slot
  1844.    SAVEBIN "ram7.bin",$C000,$4000 ;- save 4000h begin from C000h of RAM to file
  1845.    SAVEBIN "ram2.bin",$8000,$3000 ;- save 3000h begin from 8000h of RAM to file</pre>
  1846.                </div></div><p><br class="example-break"></p>
  1847.            </dd><dt><span class="term"><a name="po_savedev"></a>SAVEDEV
  1848.            &lt;filename&gt;,&lt;startPage&gt;,&lt;startOffset&gt;,&lt;length&gt;</span></dt><dd>
  1849.              <p><span class="emphasis"><em>Works only in real device emulation mode. See
  1850.              <a class="link" href="#po_device">DEVICE</a>.</em></span></p>
  1851.  
  1852.              <p>Like <a class="link" href="#po_savebin">SAVEBIN</a>, saves the block of device RAM.</p>
  1853.  
  1854.              <p>But it allows lengths over 64ki, and the offset value goes directly into device
  1855.              virtual memory (where pages are allocated consecutively), ignoring current slot
  1856.              "mapping". I.e. page=2,offset=0 will start saving data from page 2 at its beginning,
  1857.              going through pages 3, 4, 5, ... until the requested length of data is saved.</p>
  1858.  
  1859.              <p>The offset is not limited to page size, i.e. arguments page=1,offset=0x500 are equal
  1860.              to arguments page=0,offset=0x4500 for ZXSPECTRUM128 device (has page size 0x4000).</p>
  1861.  
  1862.              <div class="example"><a name="idp1226"></a><p class="title"><b>Example 5.41. </b></p><div class="example-contents">
  1863.                  
  1864.  
  1865.                  <pre class="programlisting">    DEVICE ZXSPECTRUM128 : SAVEDEV "fullram.bin",0,0,0x20000 ; save full 128kiB</pre>
  1866.                </div></div><br class="example-break">
  1867.            </dd><dt><span class="term"><a name="po_savehob"></a>SAVEHOB
  1868.            &lt;filename&gt;,&lt;filename_in_trdos&gt;,&lt;startadress&gt;,&lt;lengthofcode&gt;</span></dt><dd>
  1869.              <p><span class="emphasis"><em>Work only in real device emulation mode. See
  1870.              <a class="link" href="#po_device">DEVICE</a>.</em></span></p>
  1871.  
  1872.              <p>Save the block of RAM in Hobeta format.</p>
  1873.  
  1874.              <div class="example"><a name="idp1238"></a><p class="title"><b>Example 5.42. </b></p><div class="example-contents">
  1875.                  
  1876.  
  1877.                  <pre class="programlisting">    PAGE 7 ;set 7 page to current slot
  1878.    SAVEHOB "ram7.$c","myfile1.C",$C000,$4000 ;- save 4000h begin from C000h of RAM to file
  1879.    SAVEHOB "ram2.$c","myfile2.C",$8000,$3000 ;- save 3000h begin from 8000h of RAM to file</pre>
  1880.                </div></div><p><br class="example-break"></p>
  1881.            </dd><dt><span class="term"><a name="po_savenex"></a>SAVENEX &lt;command&gt; &lt;command arguments&gt;</span></dt><dd>
  1882.              <p>Commands to build NEX file, for details check <a class="link" href="#c_savenex">SAVENEX
  1883.              </a> chapter.</p>
  1884.  
  1885.              <p><span class="emphasis"><em>Works only in ZXSPECTRUMNEXT device emulation mode. See
  1886.              <a class="link" href="#po_device">DEVICE</a>.</em></span></p>
  1887.            </dd><dt><span class="term"><a name="po_savesna"></a>SAVESNA &lt;filename&gt;[,&lt;startadressofprogram&gt;]</span></dt><dd>
  1888.              <p><span class="emphasis"><em>Work only in real device emulation mode. See
  1889.              <a class="link" href="#po_device">DEVICE</a>.</em></span></p>
  1890.  
  1891.              <p>Save the snapshot for emulators of ZX-Spectrum. (If start address is omitted,
  1892.              the one provided by <a class="link" href="#po_end">END</a> is used)</p><div class="example"><a name="idp1260"></a><p class="title"><b>Example 5.43. </b></p><div class="example-contents">
  1893.                  
  1894.  
  1895.                  <pre class="programlisting">    DEVICE ZXSPECTRUM128
  1896.    ORG $8000
  1897. START  .... ;something code
  1898.    RET
  1899.    SAVESNA "game.sna",START ;save snapshot to file game.sna. Start address is START ($8000)</pre>
  1900.                </div></div><p><br class="example-break"></p>
  1901.            </dd><dt><span class="term"><a name="po_savetap"></a><p>SAVETAP &lt;filename&gt;,BASIC,&lt;fileintapeheader&gt;,&lt;start&gt;,&lt;length&gt;[,&lt;autorunline&gt;[,&lt;lengthwithoutvars&gt;]]</p>
  1902.            <p>SAVETAP &lt;filename&gt;,CODE,&lt;fileintapeheader&gt;,&lt;start&gt;,&lt;length&gt;[,&lt;customstartaddress&gt;[,&lt;optional3rdparam&gt;]]</p>
  1903.            <p>SAVETAP &lt;filename&gt;,NUMBERS,&lt;fileintapeheader&gt;,&lt;start&gt;,&lt;length&gt;[,&lt;variableletter(A..Z)&gt;]</p>
  1904.            <p>SAVETAP &lt;filename&gt;,CHARS,&lt;fileintapeheader&gt;,&lt;start&gt;,&lt;length&gt;[,&lt;variableletter(A..Z)&gt;]</p>
  1905.            <p>SAVETAP &lt;filename&gt;,HEADLESS,&lt;start&gt;,&lt;length&gt;[,&lt;customblockflag(0..255)&gt;]</p></span></dt><dd>
  1906.              <p><span class="emphasis"><em>Work only in real device emulation mode. See
  1907.              <a class="link" href="#po_device">DEVICE</a>.</em></span></p>
  1908.  
  1909.              <p>Append the tape header or block of data to the end of the
  1910.              standard tape file for emulators of ZX-Spectrum.</p><div class="example"><a name="idp1277"></a><p class="title"><b>Example 5.44. </b></p><div class="example-contents">
  1911.                  
  1912.  
  1913.                  <pre class="programlisting">    DEVICE ZXSPECTRUM48
  1914.    ...
  1915.    EMPTYTAP "output.tap"
  1916.  
  1917.    SAVETAP "output.tap",BASIC,"noAutorun",label,100
  1918.    SAVETAP "output.tap",BASIC,"w/Autorun",label,100,9999
  1919.    SAVETAP "output.tap",BASIC,"withVars",label,123,9999,100
  1920.    SAVETAP "output.tap",CODE,"bank17",screen,6912
  1921.    SAVETAP "output.tap",CODE,"screen",demo,length,org
  1922.    SAVETAP "output.tap",NUMBERS,"dimArray",label,100      ; a()
  1923.    SAVETAP "output.tap",NUMBERS,"othernum",label,200,'b'  ; b()
  1924.    SAVETAP "output.tap",CHARS,"charArray",label,300       ; a$()
  1925.    SAVETAP "output.tap",CHARS,"nextone",label,400,'m'     ; m$()
  1926.    SAVETAP "output.tap",HEADLESS,start,length</pre>
  1927.                </div></div><p><br class="example-break"></p>
  1928.            </dd><dt><span class="term">SAVETAP &lt;filename&gt;[,&lt;startadressofprogram&gt;]</span></dt><dd>
  1929.              <p><span class="emphasis"><em>Work only in real device emulation mode. See
  1930.              <a class="link" href="#po_device">DEVICE</a>.</em></span></p>
  1931.  
  1932.              <p>Save the tape file for emulators of ZX-Spectrum as a
  1933.              "snapshot" of almost-whole memory. Generated tape file supports the
  1934.              ZX-Spectrum clones with extended RAM such as ATM Turbo 512, etc.
  1935.              (If start address is omitted, the one provided by <a class="link" href="#po_end">END</a> is used)</p>
  1936.  
  1937.              <p>The stored memory starts at $5E00 (with screen data at $4000 auto-detected
  1938.                                   and optionally stored into the TAP file). The stored memory is automatically
  1939.                                   trimmed of zero values at start and end of the region (put non-zero byte markers
  1940.                                   around region you want to store, if you have zero-ed bytes at beginning or end
  1941.                                   of your code).
  1942.  
  1943.              </p><div class="example"><a name="idp1290"></a><p class="title"><b>Example 5.45. </b></p><div class="example-contents">
  1944.                  
  1945.  
  1946.                  <pre class="programlisting">    DEVICE ZXSPECTRUM48
  1947.    ORG $7FFF
  1948.    DB $01      ; non-zero marker to store the following zero-ed data
  1949. DAT DS 1024, 0  ; zero-ed data at $8000 (1024 bytes)
  1950. START  ....     ; some code
  1951.    RET
  1952.    SAVETAP "game.tap", START ; save tape-snapshot to file game.tap. Start address is $8400</pre>
  1953.                </div></div><p><br class="example-break"></p>
  1954.            </dd><dt><span class="term"><a name="po_savetrd"></a>SAVETRD &lt;filename_of_trd_image&gt;,&lt;filename_in_trdos&gt;,&lt;address&gt;,&lt;length&gt;[,&lt;autostart_BASIC_line&gt;]</span></dt><dd></dd><dt><span class="term">SAVETRD &lt;filename_of_trd_image&gt;,|&lt;filename_in_trdos&gt;,&lt;address&gt;,&lt;length&gt;[,&lt;autostart_BASIC_line&gt;]</span></dt><dd></dd><dt><span class="term">SAVETRD &lt;filename_of_trd_image&gt;,&amp;&lt;filename_in_trdos&gt;,&lt;address&gt;,&lt;length&gt;</span></dt><dd>
  1955.              <p><span class="emphasis"><em>Works only in real device emulation mode. See
  1956.              <a class="link" href="#po_device">DEVICE</a>.</em></span></p>
  1957.  
  1958.                           <p>Save the device memory into TRD disk image. Saving two files with same filename will
  1959.                                   emit warning which can be suppressed by "; ok" comment, but two files (with same name)
  1960.                                   will be created in the disk directory.</p>
  1961.  
  1962.                           <p>Adding pipe character "|" ahead of file
  1963.                                   name will make sjasmplus to delete old file(s) with the same name before writing
  1964.                                   the new one =&gt; replace-like functionality. If the deleted file did occupy all
  1965.                                   sectors till the free space position in disc info, sjasmplus will salvage those sectors
  1966.                                   back and save new file over them (but it will not do full reshuffle/defrag in more
  1967.                                   complex cases, sjasmplus is just assembler, not full featured TRD images manipulation tool).</p>
  1968.  
  1969.                           <p>Adding ampersand character "&amp;" ahead of file name will make sjasmplus to look
  1970.                                   for existing file with the requested name (last of them, any earlier duplicates are deleted).
  1971.                                   The new content is appended to the file (sector aligned append) and the catalog entry gets
  1972.                                   only number of sectors patched, up to 255 sectors at most. This is special mode for
  1973.                                   single-file big-loaders.</p>
  1974.  
  1975.                           <p>The unofficial three-letter extensions are supported, use "; ok" comment to suppress
  1976.                                   warning about unofficial extension (official extensions are only: B, C, D and #).
  1977.  
  1978.                                 </p><div class="example"><a name="idp1310"></a><p class="title"><b>Example 5.46. </b></p><div class="example-contents">
  1979.                  <pre class="programlisting">    EMPTYTRD "test.trd" ;create empty TRD image
  1980.    PAGE 7 ;set 7 page to current slot
  1981.    SAVETRD "test.trd","myfile1.C",$C000,$4000 ;- save 4000h begin from C000h of RAM to file to TRD image
  1982.    SAVETRD "test.trd","myfile2.C",$8000,$3000 ;- save 3000h begin from 8000h of RAM to file to TRD image
  1983.    SAVETRD "test.trd",|"myfile1.C",$B000,$400 ;- replace "myfile1.C" with new file
  1984.    SAVETRD "test.trd",&amp;"myfile1.C",$9000,$734 ;- sector-append new data to "myfile1.C"</pre>
  1985.                </div></div><p><br class="example-break">
  1986.                           </p>
  1987.            </dd><dt><span class="term"><a name="po_setbp"></a>SETBP [&lt;expression&gt;]</span></dt><dd></dd><dt><span class="term"><a name="po_setbreakpoint"></a>SETBREAKPOINT [&lt;expression&gt;]</span></dt><dd>
  1988.                                 <p>
  1989.                                         <span class="emphasis"><em>Works only in real device emulation mode. See
  1990.                                                 <a class="link" href="#po_device">DEVICE</a>.</em></span>
  1991.                                 </p>
  1992.                                 <p>Will add execution-type breakpoint at address &lt;expression&gt; to the
  1993.                                         <a class="link" href="#po_bplist">BPLIST</a> export file. If no expression is specified,
  1994.                                         the current program counter will be used.
  1995.                                   </p><div class="example"><a name="idp1326"></a><p class="title"><b>Example 5.47. </b></p><div class="example-contents">
  1996.                  
  1997.  
  1998.                  <pre class="programlisting">    BPLIST "cmd_line.options.txt" zesarux ; open breakpoints list in "ZEsarUX" format
  1999. start:
  2000.        nop     ; ZEsarUX will not catch very first instruction of snapshot file loaded
  2001.        SETBP   ; so breakpoint ahead of the second instruction (after first "nop")
  2002.        xor  a
  2003.        SETBP some_routine_label  ; set also some breakpoint to other code by its label
  2004.        SETBREAKPOINT $0D6B       ; alias of SETBP, works identically
  2005.        ; ... your code of app
  2006.                                           </pre>
  2007.                                   </div></div><p><br class="example-break">
  2008.                                 </p>
  2009.            </dd><dt><span class="term"><a name="po_shellexec"></a>SHELLEXEC &lt;filename&gt;[,&lt;parameters&gt;]</span></dt><dd>
  2010.              <p>Execute external program &lt;filename&gt; using optional
  2011.              command line &lt;parameters&gt;.</p><div class="example"><a name="idp1334"></a><p class="title"><b>Example 5.48. </b></p><div class="example-contents">
  2012.                  
  2013.  
  2014.                  <pre class="programlisting">    OUTPUT "mybin.bin"
  2015.    ;some code
  2016.    IF ((_ERRORS = 0) &amp;&amp; (_WARNINGS = 0))
  2017.        SHELLEXEC "x:/somepath/bin2tap.exe mybin.bin mytap.tap"
  2018.       ; or SHELLEXEC "x:/somepath/bin2tap.exe","mybin.bin mytap.tap"
  2019.    ENDIF</pre>
  2020.                </div></div><p><br class="example-break"></p>
  2021.            </dd><dt><span class="term"><a name="po_size"></a>SIZE &lt;filesize in bytes&gt;</span></dt><dd>
  2022.              <p>If the resulting file is less than the given length, as
  2023.              many zero bytes are added as necessary. See <a class="link" href="#po_output">OUTPUT</a> for more.</p><div class="example"><a name="idp1344"></a><p class="title"><b>Example 5.49. </b></p><div class="example-contents">
  2024.                  
  2025.  
  2026.                  <pre class="programlisting">    SIZE 32768       ; make sure file will be 32K</pre>
  2027.                </div></div><p><br class="example-break"></p>
  2028.            </dd><dt><span class="term"><a name="po_slot"></a>SLOT &lt;number&gt;</span></dt><dd>
  2029.              <p><span class="emphasis"><em>Work only in real device emulation mode. See
  2030.              <a class="link" href="#po_device">DEVICE</a>.</em></span></p>
  2031.  
  2032.              <p>Set current slot. Slot's defined by MEMORYMAP pseudo-op.
  2033.              Use pseudo-op <a class="link" href="#po_page">PAGE</a> to change page
  2034.              in the current slot.</p>
  2035.  
  2036.              <div class="example"><a name="idp1358"></a><p class="title"><b>Example 5.50. </b></p><div class="example-contents">
  2037.                  
  2038.  
  2039.                  <pre class="programlisting">    DEVICE ZXSPECTRUM128
  2040.    SLOT 3 ;from 0C000h to 0FFFFh
  2041.    PAGE 1 ;set page 1 to slot 3
  2042.    ORG 0C000h
  2043.    ;your program here
  2044.    PAGE 2
  2045.    INCBIN "somegfx.bin"
  2046.    ;....</pre>
  2047.                </div></div><p><br class="example-break"></p>
  2048.            </dd><dt><span class="term"><a name="po_tapend"></a>TAPEND</span></dt><dd>
  2049.              <p>Ends generating compiler output to tape file block specified in TAPOUT.</p>
  2050.            </dd><dt><span class="term"><a name="po_tapout"></a>TAPOUT &lt;filename&gt;[,&lt;flagbyte&gt;]</span></dt><dd>
  2051.              <p>Appends one tape block at the end of specified file.
  2052.              All following code will be assembled to this tape file block.</p>
  2053.  
  2054.              <p>Default value of flagbyte is 255.</p><div class="example"><a name="idp1373"></a><p class="title"><b>Example 5.51. bigfile.asm</b></p><div class="example-contents">
  2055.                  
  2056.  
  2057.                  <pre class="programlisting">    EMPTYTAP screen.tap
  2058.  
  2059.    TAPOUT screen.tap,0
  2060.    DB 3
  2061.    DB 'ScreenName'
  2062.    DW 6912
  2063.    DW 16384
  2064.    DW 32768
  2065.    TAPEND
  2066.  
  2067.    TAPOUT screen.tap
  2068.    INCBIN screen.bin
  2069.    TAPEND</pre>
  2070.                </div></div><p><br class="example-break">This will create tap file with the screen.</p>
  2071.            </dd><dt><span class="term"><a name="po_textarea"></a>TEXTAREA &lt;address&gt;</span></dt><dd>
  2072.              <p>Synonym of <a class="link" href="#po_disp">DISP</a>.</p>
  2073.            </dd><dt><span class="term"><a name="po_undefine"></a>UNDEFINE &lt;id&gt;</span></dt><dd>
  2074.              <p>Removes the identifier defined by <a class="link" href="#po_define">DEFINE</a></p>
  2075.  
  2076.              <div class="example"><a name="idp1390"></a><p class="title"><b>Example 5.52. </b></p><div class="example-contents">
  2077.                  
  2078.  
  2079.                  <pre class="programlisting">    DEFINE Release 1
  2080.  
  2081.    IFDEF Release
  2082.      DISPLAY "Building release version"
  2083.    ENDIF
  2084.  
  2085.    UNDEFINE Release
  2086.  
  2087.    IFNDEF Release
  2088.      DISPLAY "It's works!"
  2089.    ENDIF
  2090.  
  2091.    IFDEF _SJASMPLUS
  2092.      DISPLAY "Yes, it's the sjasmplus!"
  2093.    ENDIF
  2094.  
  2095.    UNDEFINE *  ; undefine all identifiers
  2096.  
  2097.    IFNDEF _SJASMPLUS
  2098.      DISPLAY "It's not the sjasmplus??"
  2099.    ENDIF</pre>
  2100.                </div></div><p><br class="example-break"></p>
  2101.            </dd><dt><span class="term"><a name="po_unphase"></a>UNPHASE</span></dt><dd>
  2102.              <p>Synonym of <a class="link" href="#po_ent">ENT</a>.</p>
  2103.            </dd><dt><span class="term"><a name="po_word"></a>WORD &lt;words&gt;</span></dt><dd>
  2104.              <p>Defines a word. Values should be between -32787 and
  2105.              65536.</p><div class="example"><a name="idp1405"></a><p class="title"><b>Example 5.53. </b></p><div class="example-contents">
  2106.                  
  2107.  
  2108.                  <pre class="programlisting">    WORD 4000h,0d000h
  2109.    WORD 4,"HA"</pre>
  2110.                </div></div><p><br class="example-break"></p>
  2111.            </dd></dl></div>
  2112.    </div>
  2113.  
  2114.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp28"></a><a name="s_conditional_assembly"></a>Conditional assembly</h2></div></div></div>
  2115.      
  2116.  
  2117.      <p>It may be useful to assemble a part (or not) based on a certain
  2118.      condition.</p>
  2119.  
  2120.      <div class="variablelist"><dl class="variablelist"><dt><span class="term"><a name="ca_if"></a>IF &lt;expression&gt;</span></dt><dd>
  2121.              <p>If &lt;expression&gt; is non-zero the following lines are
  2122.              assembled until an ELSE or ENDIF.</p>
  2123.  
  2124.              <p>Forward reference of label will cause warning - as any machine code emitted inside
  2125.                                   the IF/IFN block with such expression can lead to unstable results. If you are sure
  2126.                                   the late definition of label will not affect resulting machine code (the IF block
  2127.                                   does not emit any machine code and does not define any label), you can suppress the
  2128.                                   warning with end-of-line comment "ok".</p>
  2129.  
  2130.                           <div class="example"><a name="idp1420"></a><p class="title"><b>Example 5.54. </b></p><div class="example-contents">
  2131.                                  
  2132.  
  2133.                                   <pre class="programlisting">    IF (aaa == 0) || (2 = aaa &amp;&amp; ((bbb % 13) &amp; 0x01))
  2134.        ; some code to assemble only if the symbol `aaa` is zero
  2135.        ; or (logical OR) when symbol `aaa` is two
  2136.        ; and (logical AND) modulo 13 of `bbb` is odd number
  2137.    ENDIF</pre><p>
  2138.                                   </p>
  2139.                           </div></div><br class="example-break">
  2140.                   </dd><dt><span class="term"><a name="ca_ifn"></a>IFN &lt;expression&gt;</span></dt><dd>
  2141.              <p>If &lt;expression&gt; is zero the following lines are
  2142.              assembled until an ELSE or ENDIF.</p>
  2143.            </dd><dt><span class="term"><a name="ca_ifdef"></a>IFDEF &lt;id&gt;</span></dt><dd>
  2144.              <p>The condition is true if there is an id defined. These are
  2145.              NOT labels.</p>
  2146.  
  2147.              <div class="example"><a name="idp1435"></a><p class="title"><b>Example 5.55. </b></p><div class="example-contents">
  2148.                  
  2149.  
  2150.                  <pre class="programlisting">    IFDEF MSX_LEAN_AND_MEAN
  2151.        CALL InitOwnMM
  2152.    ELSE
  2153.        CALL InitDos2MemMan
  2154.    ENDIF</pre>
  2155.                </div></div><p><br class="example-break"></p>
  2156.            </dd><dt><span class="term"><a name="ca_ifndef"></a>IFNDEF &lt;id&gt;</span></dt><dd>
  2157.              <p>The condition is true if there isn't an id defined. These
  2158.               are NOT labels.</p>
  2159.  
  2160.               <div class="example"><a name="idp1445"></a><p class="title"><b>Example 5.56. </b></p><div class="example-contents">
  2161.                  
  2162.  
  2163.                   <pre class="programlisting">1   IN A,(0C4H)
  2164.     AND 2
  2165.     IFNDEF DEBUG
  2166.         JR NC,1B
  2167.     ENDIF</pre>
  2168.                 </div></div><p><br class="example-break"></p>
  2169.             </dd><dt><span class="term"><a name="ca_ifused"></a>IFUSED &lt;label&gt;</span></dt><dd>
  2170.               <p>The condition is true if there is an label used somewhere
  2171.               in the code. You can create libraries of useful functions using
  2172.               IFUSED pseudo-op</p>
  2173.  
  2174.               <div class="example"><a name="idp1455"></a><p class="title"><b>Example 5.57. (similar to tests/misc/ifused_test.asm)</b></p><div class="example-contents">
  2175.                  
  2176.  
  2177.                   <pre class="programlisting">    OUTPUT "TEST.OUT"
  2178.  
  2179.     CALL LABEL3 ; LABEL3 - yes
  2180.     LD A,(LABEL1) ; LABEL1 - yes
  2181.  
  2182.     IFUSED LABEL1
  2183. LABEL1:
  2184.     DB 1
  2185.     ENDIF
  2186.  
  2187.     IFUSED LABEL2
  2188. LABEL2:
  2189.     DB 2
  2190.     ENDIF
  2191.  
  2192.     IFUSED LABEL3
  2193. LABEL3:
  2194.     DB 3
  2195.     ENDIF
  2196.  
  2197.     IFUSED LABEL4
  2198. LABEL4:
  2199.     DB 4
  2200.     ENDIF
  2201.  
  2202.     LD A,LABEL2 ; LABEL2 - yes
  2203.  
  2204.     RET
  2205.  
  2206. ; Output will contain bytes from LABEL1 to LABEL3 (1, 2, 3), but not contain from LABEL4, because this label is not used.
  2207.  
  2208. ; Alternative syntax:
  2209. LABEL5:
  2210.     IFUSED ; sjasmplus will use name of previous label, i.e. LABEL5
  2211.  
  2212.     ENDIF
  2213.     </pre>
  2214.                 </div></div><p><br class="example-break"></p>
  2215.                 <p>Known bug: when code is using label inside module "moduleX",
  2216.                         like <code class="code">call labelY</code>, only usage of <code class="code">moduleX.labelY</code> label is noted.
  2217.                         Then if you define "labelY" outside of module and hide it inside <code class="code">IFUSED labelY</code>
  2218.                         block, the call from module will be unable to find the routine.
  2219.                 </p>
  2220.                 <p>
  2221.                         Workaround: you can use the global-label operator @: "<code class="code">call @labelY</code>" to
  2222.                         trigger usage of the global "labelY", or you can use the alternative IFUSED syntax
  2223.                         "<code class="code">labelY: IFUSED</code>" which does not only check condition, but also does define the label.
  2224.                         Once the label is defined, the "call labelY" line inside module will find the global
  2225.                         variant and mark it as "used" correctly.
  2226.                 </p>
  2227.             </dd><dt><span class="term"><a name="ca_ifnused"></a>IFNUSED &lt;label&gt;</span></dt><dd>
  2228.               <p>The condition is true if there is an label
  2229.               <span class="emphasis"><em>not</em></span> used somewhere in the code.</p>
  2230.             </dd><dt><span class="term"><a name="ca_else"></a>ELSE</span></dt><dd>
  2231.               <p>See <a class="link" href="#ca_if">IF</a>. If the condition is
  2232.               not true, the else-part is assembled.</p>
  2233.             </dd><dt><span class="term"><a name="ca_endif"></a>ENDIF</span></dt><dd>
  2234.               <p>Every <a class="link" href="#ca_if">IF</a> should be followed
  2235.               by an ENDIF.</p>
  2236.             </dd></dl></div>
  2237.     </div>
  2238.  
  2239.     <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp29"></a><a name="s_macros"></a>Macros</h2></div></div></div>
  2240.      
  2241.  
  2242.       <p>The MACRO pseudo-op defines a macro. It should be followed by the
  2243.       name of the macro, optionally followed by the parameters. The following
  2244.       lines will be stored as the macro-body until an ENDM pseudo-op is
  2245.       encountered. Macro's have to be defined before their use.
  2246.           </p><div class="example"><a name="idp1487"></a><p class="title"><b>Example 5.58. Macro without parameters (docs_examples/s_macros.asm)</b></p><div class="example-contents">
  2247.          
  2248.  
  2249.          <pre class="programlisting">  MACRO ADD_HL_A
  2250.    ADD A,L
  2251.    JR NC,.hup
  2252.    INC H
  2253. .hup
  2254.    LD L,A
  2255.  ENDM</pre>
  2256.        </div></div><p><br class="example-break"></p>
  2257.  
  2258.      <p>Labels in a macro starting with a dot are local to each macro
  2259.      expansion.</p><div class="example"><a name="idp1491"></a><p class="title"><b>Example 5.59. A macro with parameters (docs_examples/s_macros.asm)</b></p><div class="example-contents">
  2260.          
  2261.  
  2262.          <pre class="programlisting">  MACRO WAVEOUT reg, data
  2263.    LD A,reg
  2264.    OUT (7EH),A
  2265.    LD A,data
  2266.    OUT (7FH),A
  2267.  ENDM
  2268. ; this macro will make
  2269.  WAVEOUT 2,17
  2270. ; expand to:
  2271.  LD A,2
  2272.  OUT (7EH),A
  2273.  LD A,17
  2274.  OUT (7FH),A</pre>
  2275.        </div></div><p><br class="example-break">
  2276.                 </p><div class="example"><a name="idp1494"></a><p class="title"><b>Example 5.60. Another example (docs_examples/s_macros.asm)</b></p><div class="example-contents">
  2277.          
  2278.  
  2279.          <pre class="programlisting">    MACRO LOOP
  2280.      IF $-.lus&lt;127
  2281.        DJNZ .lus
  2282.      ELSE
  2283.        DEC B
  2284.        JP NZ,.lus
  2285.      ENDIF
  2286.    ENDM
  2287.  
  2288. Main
  2289. .lus
  2290.    CALL DoALot
  2291.    LOOP
  2292. ; This will expand to:
  2293. Main
  2294. .lus                  ; Main.lus
  2295.    CALL DoALot
  2296.    DJNZ .lus         ; Main.lus</pre>
  2297.        </div></div><p><br class="example-break"></p>
  2298.  
  2299.      <p>Angle brackets can be used when the arguments contain commas.
  2300.      </p><div class="example"><a name="idp1498"></a><p class="title"><b>Example 5.61. Argument in angle brackets (docs_examples/s_macros.asm)</b></p><div class="example-contents">
  2301.          
  2302.  
  2303.          <pre class="programlisting">    MACRO UseLess data
  2304.      DB data
  2305.    ENDM
  2306.  
  2307.    UseLess &lt;10,12,13,0&gt;
  2308. ; expands to:
  2309.    DB 10,12,13,0
  2310.  
  2311. ; use '!' to include '!' and '&gt;' in those strings.
  2312.  
  2313.    UseLess &lt;5, 6 !&gt; 3&gt;
  2314. ; expands to:
  2315.    DB 5, 6 &gt; 3
  2316.  
  2317.    UseLess &lt;"Kip!!",3&gt;
  2318. ; expands to:
  2319.    DB "Kip!",3</pre>
  2320.        </div></div><p><br class="example-break"></p>
  2321.  
  2322.                 <p>As compatibility convenience to make porting from different assemblers somewhat
  2323.                         easier, there is alternative syntax, where the macro name is written at beginning
  2324.                         of line (as if label, but MODULE part is NOT applied to macro name).
  2325.                         </p><div class="example"><a name="idp1502"></a><p class="title"><b>Example 5.62. Macro name at beginning of line (docs_examples/s_macros.asm)</b></p><div class="example-contents">
  2326.                                 <pre class="programlisting">LabelAsMacroName    MACRO  arg1?, arg2?
  2327.                        ld  a,arg1?
  2328.                        ld  hl,arg2?
  2329.                    ENDM
  2330.  
  2331.                LabelAsMacroName 1,$1234
  2332.            ; expands to:
  2333.                ld a,1 : ld hl,$1234</pre>
  2334.                         </div></div><p><br class="example-break">
  2335.                 </p>
  2336.  
  2337.                 <p>
  2338.                         If some macro over-shadows regular instruction or directive name, the <code class="code">@</code>
  2339.                         character in front of instruction/directive name can be used to inhibit macro expansion.
  2340.                         </p><div class="example"><a name="idp1507"></a><p class="title"><b>Example 5.63. Inhibit macro expansion operator (docs_examples/s_macros.asm)</b></p><div class="example-contents">
  2341.                                 <pre class="programlisting">djnz    MACRO   arg1?
  2342.            dec c
  2343.            jr  nz,arg1?
  2344.            @djnz arg1? ; avoid self-reference and use real instruction
  2345.        ENDM
  2346.  
  2347. 1:      djnz    1B      ; macro replacement will be used here
  2348. 1:      @djnz   1B      ; original djnz instruction here</pre>
  2349.                         </div></div><p><br class="example-break">
  2350.                 </p>
  2351.  
  2352.    </div>
  2353.  </div>
  2354.  
  2355.  <div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="idp36"></a>Chapter 6. <a name="c_structures"></a>Structures</h1></div></div></div>
  2356.    
  2357.  
  2358.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp31"></a>What is it?</h2></div></div></div>
  2359.      
  2360.  
  2361.      <p>Structures can be used to define data structures in memory more
  2362.      easily. The name of the structure is set to the total size of the
  2363.      structure.</p>
  2364.    </div>
  2365.  
  2366.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp32"></a>Defining structure</h2></div></div></div>
  2367.      
  2368.  
  2369.      <p>A structure definition starts with: <code class="code">STRUCT
  2370.      &lt;name&gt;[,&lt;initial offset&gt;]</code> and ends with
  2371.      <code class="code">ENDS</code>. Structure definitions are local to the current
  2372.      module, but, as with labels, '@' can be used to override this.</p>
  2373.  
  2374.      <p>Lines between STRUCT and ENDS should have the following
  2375.      format:</p>
  2376.  
  2377.      <p><code class="code">membername pseudo-operation operands</code></p>
  2378.  
  2379.      <p>All fields are optional. Lines without label should start with
  2380.      whitespace.</p>
  2381.  
  2382.      <p>When non zero <code class="code">offset</code> is used, it acts as if
  2383.       <a class="link" href="#st_block">BLOCK</a> with <code class="code">length</code> equal to
  2384.       <code class="code">offset</code> was defined as first member of structure.</p>
  2385.    </div>
  2386.  
  2387.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp33"></a>Instructions</h2></div></div></div>
  2388.      
  2389.  
  2390.      <p>Between the STRUCT and ENDS pseudo-instructions the following
  2391.      instructions can be used:</p>
  2392.  
  2393.      <div class="variablelist"><dl class="variablelist"><dt><span class="term"><a name="st_byte"></a>BYTE [&lt;defaultvalue&gt;]</span></dt><dd>
  2394.              <p>To define a one byte member. The defaultvalue is used when
  2395.              no initialisation value is given when the structure is declared.
  2396.              (DB and DEFB may be used instead of BYTE).</p>
  2397.            </dd><dt><span class="term"><a name="st_word"></a>WORD [&lt;defaultvalue&gt;]</span></dt><dd>
  2398.              <p>To define a two byte member. The defaultvalue is used when
  2399.              no initialisation value is given when the structure is declared.
  2400.              (DW and DEFW may be used instead of WORD).</p>
  2401.            </dd><dt><span class="term"><a name="st_d24"></a>D24 [&lt;defaultvalue&gt;]</span></dt><dd>
  2402.              <p>To define a three byte member. The defaultvalue is used
  2403.              when no initialisation value is given when the structure is
  2404.              declared.</p>
  2405.            </dd><dt><span class="term"><a name="st_dword"></a>DWORD [&lt;defaultvalue&gt;]</span></dt><dd>
  2406.              <p>To define a four byte member. The defaultvalue is used
  2407.              when no initialisation value is given when the structure is
  2408.              declared. (DD and DEFD may be used instead of DWORD).</p>
  2409.            </dd><dt><span class="term"><a name="st_block"></a>BLOCK &lt;length&gt;[,&lt;fillbyte&gt;]]</span></dt><dd>
  2410.              <p>To define a member of the specified number of bytes. Arguments are set
  2411.                  when defining the current structure, and are not part of init values when
  2412.                  the structure is later used.
  2413.              ('#', DS and DEFS may be used instead of BLOCK).</p>
  2414.  
  2415.              <p>(since v1.11) If <code class="code">fillbyte</code> is omitted, the device memory
  2416.                  content in the block area is preserved (not zeroed).</p>
  2417.            </dd><dt><span class="term"><a name="st_align"></a>ALIGN [&lt;expression&gt;[, &lt;byte&gt;]]</span></dt><dd>
  2418.              <p>To <a class="link" href="#po_align">align</a> the offset. If the expression
  2419.                  is omitted, 4 is assumed. ('##' May be used instead of ALIGN).</p>
  2420.  
  2421.              <p>(since v1.11) If the byte is omitted, device memory content is preserved (not zeroed).</p>
  2422.            </dd><dt><span class="term">&lt;structure name&gt; [&lt;init values&gt;]</span></dt><dd>
  2423.              <p>It is possible to nest structures, and give new defaults
  2424.              for the BYTE and WORD members.</p>
  2425.            </dd></dl></div>
  2426.    </div>
  2427.  
  2428.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp34"></a><a name="st_usage"></a>Usage of defined structure</h2></div></div></div>
  2429.      
  2430.  
  2431.      <p><code class="code">[&lt;label&gt;] &lt;struct_name&gt; [&lt;initial values&gt;]</code> will emit full
  2432.                 structure into machine code, either using default values from structure definition,
  2433.                 or overriding them with explicit value from the &lt;initial values&gt; list. In initial
  2434.                 values you can use curly brackets {} to group particular initial values for particular
  2435.                 sub-structure, any missing values in particular sub-structure init-list are set up by
  2436.                 default values of particular field. See "SDOT" example below or tests/struct asm files
  2437.                 for more examples.</p>
  2438.  
  2439.      <p><code class="code">&lt;label&gt; &lt;struct_name&gt; = &lt;expression&gt;</code> will only set up
  2440.                 &lt;label&gt;.&lt;struct_field&gt; labels starting from designed address provided by
  2441.                 expression, but there will be no machine code emitted (and current address "$" will not
  2442.                 advance).</p>
  2443.  
  2444.    </div>
  2445.  
  2446.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp35"></a>Examples</h2></div></div></div>
  2447.      
  2448.  
  2449.      <div class="example"><a name="idp1576"></a><p class="title"><b>Example 6.1. docs_examples/c_structures.asm</b></p><div class="example-contents">
  2450.          
  2451.  
  2452.           <pre class="programlisting">  STRUCT SCOLOR
  2453. RED     BYTE 4
  2454. GREEN   BYTE 5
  2455. BLUE    BYTE 6
  2456.         ENDS</pre>
  2457.  
  2458.          <p>This is identical to:</p>
  2459.  
  2460.           <pre class="synopsis">SCOLOR          EQU 3 ; length
  2461. SCOLOR.RED      EQU 0 ; offset
  2462. SCOLOR.GREEN    EQU 1 ; offset
  2463. SCOLOR.BLUE     EQU 2 ; offset</pre>
  2464.           </div></div><br class="example-break">
  2465.           <div class="example"><a name="idp1582"></a><p class="title"><b>Example 6.2. docs_examples/c_structures.asm</b></p><div class="example-contents">
  2466.          
  2467.  
  2468.           <pre class="programlisting">  STRUCT SDOT
  2469. X       BYTE
  2470. Y       BYTE
  2471. C       SCOLOR 0,0,0 ; use new default values
  2472.         ENDS
  2473. </pre>
  2474.  
  2475.          <p>This is identical to:</p>
  2476.  
  2477.           <pre class="synopsis">SDOT            EQU 5 ; length
  2478. SDOT.X          EQU 0 ; offset
  2479. SDOT.Y          EQU 1 ; offset
  2480. SDOT.C          EQU 2 ; offset
  2481. SDOT.C.RED      EQU 2 ; offset
  2482. SDOT.C.GREEN    EQU 3 ; offset
  2483. SDOT.C.BLUE     EQU 4 ; offset
  2484. </pre>
  2485.           </div></div><br class="example-break">
  2486.           <div class="example"><a name="idp1588"></a><p class="title"><b>Example 6.3. docs_examples/c_structures.asm</b></p><div class="example-contents">
  2487.          
  2488.  
  2489.           <pre class="programlisting">  STRUCT SPOS,4
  2490. X       WORD
  2491. Y       BYTE
  2492.         ALIGN 2
  2493. AD      WORD
  2494.         ENDS</pre>
  2495.  
  2496.          <p>This is identical to:</p>
  2497.  
  2498.           <pre class="synopsis">SPOS    EQU 10 ; length
  2499. SPOS.X  EQU  4 ; offset
  2500. SPOS.Y  EQU  6 ; offset
  2501. SPOS.AD EQU  8 ; offset</pre>
  2502.           </div></div><br class="example-break">
  2503.           <div class="example"><a name="idp1594"></a><p class="title"><b>Example 6.4. docs_examples/c_structures.asm</b></p><div class="example-contents">
  2504.          
  2505.  
  2506.          <p>When a structure is defined it is possible to declare labels
  2507.          with it</p><pre class="programlisting">COLOR SCOLOR</pre><p>This is
  2508.          identical to:</p><pre class="synopsis">COLOR
  2509. COLOR.RED   BYTE 4
  2510. COLOR.GREEN BYTE 5
  2511. COLOR.BLUE  BYTE 6
  2512. </pre><p>Note the default values.</p>
  2513.  
  2514.          <p>Or without label:</p><pre class="programlisting">COLORTABLE
  2515.  SCOLOR 0,0,0
  2516.  SCOLOR 1,2,3
  2517.  SCOLOR ,2
  2518.  ; etc.</pre><p>This is identical to:</p><pre class="synopsis">COLORTABLE
  2519.  BYTE 0,0,0
  2520.  BYTE 1,2,3
  2521.  BYTE 4,2,6
  2522.  ; etc.</pre><p>
  2523.  
  2524. </p><pre class="programlisting">DOT1 SDOT 0,0, 0,0,0     ; or 0,0,0,0,0 or {0,0,{0,0,0}}</pre><p>Only
  2525.          BYTE and WORD members can be initialised.</p>
  2526.  
  2527.          <p>The resulting labels can be used as any other
  2528.          label:</p><pre class="programlisting">  ld b,(ix+SCOLOR.RED)
  2529.  ld a,(COLOR.GREEN)
  2530.  ld de,COLOR
  2531.  ; etc.</pre>
  2532.  
  2533.           </div></div><br class="example-break">
  2534.      <div class="example"><a name="idp1605"></a><p class="title"><b>Example 6.5. docs_examples/st_usage_example.asm</b></p><div class="example-contents">
  2535.          
  2536.  
  2537.           <pre class="programlisting">  STRUCT BIN_FILE_MAP, 256
  2538. value1  BYTE
  2539. value2  WORD
  2540.         ENDS
  2541.  
  2542.        ORG  0x8000
  2543. binData BIN_FILE_MAP = $        ; set up label values only (no bytes)
  2544.        INCBIN "some_data.bin"  ; load the bytes from file instead
  2545.  
  2546.        ; using the data through struct definition
  2547.        ld  a,(binData.value1)
  2548.        ld  hl,(binData.value2)</pre>
  2549.  
  2550.          <p>This is identical to:</p>
  2551.  
  2552.          <pre class="synopsis">BIN_FILE_MAP            EQU 259      ; length
  2553. BIN_FILE_MAP.value1     EQU 256      ; offset
  2554. BIN_FILE_MAP.value2     EQU 257      ; offset
  2555. ; labels to access binary data loaded by INCBIN
  2556. binData                 EQU 0x8000   ; address
  2557. binData.value1          EQU 0x8100   ; address
  2558. binData.value2          EQU 0x8101   ; address</pre>
  2559.           </div></div><br class="example-break">
  2560.  
  2561.           <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3>
  2562.                 <p>Do not use the offset labels in indirections
  2563.                 like:</p><pre class="programlisting">LD A,(SDOT.X)</pre><p>This will
  2564.                 conflict with futher 'improvements' ;-)</p>
  2565.  
  2566.                 <p>If this is absolutely necessary (why?) use something like
  2567.                 this:</p><pre class="programlisting">LD A,(+SDOT.X)</pre>
  2568.           </div>
  2569.    </div>
  2570.  </div>
  2571.  
  2572.  <div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="idp42"></a>Chapter 7. <a name="c_lua_scripting"></a>Lua scripting</h1></div></div></div>
  2573.    
  2574.  
  2575.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp37"></a>Why?</h2></div></div></div>
  2576.      
  2577.  
  2578.      <div align="left"><img src="lua.gif" align="left"></div><p>Why is scripting engine
  2579.      as Lua embedded to the compiler? Answer is simple: It need to add extra
  2580.      features by users. And to whole other Lua is enough small, fast and
  2581.      powerful scripting engine.</p>
  2582.    </div>
  2583.  
  2584.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp38"></a>How to use?</h2></div></div></div>
  2585.      
  2586.  
  2587.      <p>You must use <a class="link" href="#po_lua">LUA</a> and <a class="link" href="#po_endlua">ENDLUA</a> pseudo-ops.</p><div class="example"><a name="idp1625"></a><p class="title"><b>Example 7.1. Hello World!</b></p><div class="example-contents">
  2588.          
  2589.  
  2590.          <pre class="programlisting">    LUA
  2591.        print ("Hello World!")
  2592.    ENDLUA</pre>
  2593.        </div></div><p><br class="example-break"></p>
  2594.    </div>
  2595.  
  2596.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp39"></a>SjASMPlus binded functions</h2></div></div></div>
  2597.      
  2598.  
  2599.      <p>From Lua you can control some variables and use functions of the
  2600.      compiler. Complete list:</p>
  2601.  
  2602.      <div class="variablelist"><dl class="variablelist"><dt><span class="term"><a name="lua__c"></a>[integer] _c("expression")</span></dt><dd>
  2603.              <p>Calculate expression using calculator of the compiler.
  2604.              Example: <code class="code">val = _c("SOMELABEL+12")</code>.</p>
  2605.            </dd><dt><span class="term"><a name="lua__pc"></a>[void] _pc("code")</span></dt><dd>
  2606.              <p>Parse string of Z80 assembly. Example: <code class="code">_pc("ADD
  2607.              A,B")</code></p>
  2608.            </dd><dt><span class="term"><a name="lua__pl"></a>[void] _pl("label code")</span></dt><dd>
  2609.              <p>Parse line of Z80 assembly. Example: <code class="code">_pc("SOMELABEL
  2610.              ADD A,B")</code></p>
  2611.            </dd><dt><span class="term">[integer] sj.calc("expression")</span></dt><dd>
  2612.              <p>See <a class="link" href="#lua__c">_c</a></p>
  2613.            </dd><dt><span class="term">[void] sj.parse_code("code")</span></dt><dd>
  2614.              <p>See <a class="link" href="#lua__pc">_pc</a></p>
  2615.            </dd><dt><span class="term">[void] sj.parse_line("label code")</span></dt><dd>
  2616.              <p>See <a class="link" href="#lua__pl">_pl</a></p>
  2617.            </dd><dt><span class="term">[void] sj.error("message")</span></dt><dd>
  2618.              <p>Print error message.</p>
  2619.            </dd><dt><span class="term">[void] sj.warning("message")</span></dt><dd>
  2620.              <p>Print warning message.</p>
  2621.            </dd><dt><span class="term">[boolean] sj.file_exists("filename")</span></dt><dd>
  2622.              <p>Check for file exists.</p>
  2623.            </dd><dt><span class="term">[string] sj.get_define("name")</span></dt><dd>
  2624.              <p>Get define value.</p>
  2625.            </dd><dt><span class="term">[boolean] sj.insert_define("name", "value")</span></dt><dd>
  2626.              <p>Add new define.</p>
  2627.            </dd><dt><span class="term">[integer] sj.get_label("name")</span></dt><dd>
  2628.              <p>Get label address.</p>
  2629.            </dd><dt><span class="term">[boolean] sj.insert_label("name", address)</span></dt><dd>
  2630.              <p>Add new label.</p>
  2631.            </dd><dt><span class="term"><a name="lua_sj_current_address"></a>[integer]
  2632.            sj.current_address</span></dt><dd>
  2633.              <p>Variable. Current address.</p>
  2634.            </dd><dt><span class="term">[integer] sj.error_count</span></dt><dd>
  2635.              <p>Variable. Count of Errors.</p>
  2636.            </dd><dt><span class="term">[integer] sj.warning_count</span></dt><dd>
  2637.              <p>Variable. Count of Warnings.</p>
  2638.            </dd><dt><span class="term">[void] sj.exit(errorcode)</span></dt><dd>
  2639.              <p>Shutdown the compiler.</p>
  2640.            </dd><dt><span class="term">[void] sj.add_byte(byte)</span></dt><dd>
  2641.              <p>Add byte to output (or to memory) and increase <a class="link" href="#lua_sj_current_address">sj.current_address</a></p>
  2642.            </dd><dt><span class="term">[void] sj.add_word(word)</span></dt><dd>
  2643.              <p>Add word to output (or to memory) and twice increase <a class="link" href="#lua_sj_current_address">sj.current_address</a></p>
  2644.            </dd><dt><span class="term">[integer] sj.get_byte(address)</span></dt><dd>
  2645.              <p>Get byte from memory. <span class="emphasis"><em>Work only in real device
  2646.              emulation mode.</em></span></p>
  2647.            </dd><dt><span class="term">[integer] sj.get_word(address)</span></dt><dd>
  2648.              <p>Get word from memory. <span class="emphasis"><em>Work only in real device
  2649.              emulation mode.</em></span></p>
  2650.            </dd><dt><span class="term">[string] sj.get_device()</span></dt><dd>
  2651.              <p>Return current emulating device's identifier. Returns
  2652.               "NONE" if no emulation mode.</p>
  2653.             </dd><dt><span class="term">[boolean] sj.set_device("id")</span></dt><dd>
  2654.               <p>Set current emulating device's identifier. Returns false
  2655.              if no device found.</p>
  2656.            </dd><dt><span class="term">[boolean] sj.set_page(number)</span></dt><dd>
  2657.              <p>Set page with number "number" to the current slot. Works
  2658.              as pseudo-op PAGE.</p>
  2659.            </dd><dt><span class="term">[boolean] sj.set_slot(number)</span></dt><dd>
  2660.              <p>Set current slot with number "number". Works as pseudo-op
  2661.              SLOT.</p>
  2662.            </dd><dt><span class="term">[void] sj.shellexec("programname")</span></dt><dd>
  2663.              <p>See pseudo-op SHELLEXEC.</p>
  2664.            </dd><dt><span class="term">[void] zx.trdimage_create("filename")</span></dt><dd>
  2665.              <p>Creates emptry TRD image file.</p>
  2666.            </dd><dt><span class="term">[void] zx.trdimage_add_file("filename", "somenameC",
  2667.            startaddress, length, autostart, replace)</span></dt><dd>
  2668.              <p>Save block of memory to TRD image file. <span class="emphasis"><em>Work
  2669.              only in real device emulation mode.</em></span></p>
  2670.            </dd><dt><span class="term">[void] zx.save_snapshot_sna("filename.sna",
  2671.            startaddressofprogram)</span></dt><dd>
  2672.              <p>Save snapshot of memory in SNA format. <span class="emphasis"><em>Work only
  2673.              in real device emulation mode and only for ZXSPECTRUM48 and
  2674.              ZXSPECTRUM128..</em></span></p>
  2675.            </dd></dl></div>
  2676.    </div>
  2677.  
  2678.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp40"></a>Third-party embedded library(ies)</h2></div></div></div>
  2679.      
  2680.  
  2681.      <p><span class="emphasis"><em>lpack.c</em></span></p>
  2682.  
  2683.      <p>a Lua library for packing and unpacking binary data</p>
  2684.  
  2685.      <p>by Luiz Henrique de Figueiredo
  2686.      &lt;lhf(at)tecgraf.puc-rio.br&gt;</p>
  2687.  
  2688.      <p>The library adds two functions to the string library:
  2689.      <span class="emphasis"><em>string.pack</em></span> and
  2690.      <span class="emphasis"><em>string.unpack</em></span>.</p>
  2691.  
  2692.      <p>pack is called as follows: string.pack(F,x1,x2,...), where F is a
  2693.      string describing how the values x1, x2, ... are to be interpreted and
  2694.      formatted. Each letter in the format string F consumes one of the given
  2695.      values. Only values of type number or string are accepted. pack returns
  2696.      a (binary) string containing the values packed as described in F. The
  2697.      letter codes understood by pack are listed in lpack.c (they are inspired
  2698.      by Perl's codes but are not the same). Numbers following letter codes in
  2699.       F indicate repetitions.</p>
  2700.  
  2701.       <p>unpack is called as follows: string.unpack(s,F,[init]), where s is
  2702.       a (binary) string containing data packed as if by pack, F is a format
  2703.       string describing what is to be read from s, and the optional init marks
  2704.       where in s to begin reading the values. unpack returns one value per
  2705.       letter in F until F or s is exhausted (the letters codes are the same as
  2706.       for pack, except that numbers following 'A' are interpreted as the
  2707.       number of characters to read into the string, not as
  2708.       repetitions).</p>
  2709.  
  2710.       <p>The first value returned by unpack is the next unread position in
  2711.       s, which can be used as the init position in a subsequent call to
  2712.       unpack. This allows you to unpack values in a loop or in several steps.
  2713.       If the position returned by unpack is beyond the end of s, then s has
  2714.       been exhausted; any calls to unpack starting beyond the end of s will
  2715.       always return nil values.</p>
  2716.  
  2717.       <p>List of types for F string:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">z</span></dt><dd>
  2718.               <p>zero-terminated string</p>
  2719.             </dd><dt><span class="term">p</span></dt><dd>
  2720.               <p>string preceded by length byte</p>
  2721.             </dd><dt><span class="term">P</span></dt><dd>
  2722.               <p>string preceded by length word</p>
  2723.             </dd><dt><span class="term">a</span></dt><dd>
  2724.               <p>string preceded by length size_t</p>
  2725.             </dd><dt><span class="term">A</span></dt><dd>
  2726.               <p>string</p>
  2727.             </dd><dt><span class="term">f</span></dt><dd>
  2728.               <p>float</p>
  2729.             </dd><dt><span class="term">d</span></dt><dd>
  2730.               <p>double</p>
  2731.             </dd><dt><span class="term">n</span></dt><dd>
  2732.               <p>Lua number</p>
  2733.             </dd><dt><span class="term">c</span></dt><dd>
  2734.               <p>char</p>
  2735.             </dd><dt><span class="term">b</span></dt><dd>
  2736.               <p>byte = unsigned char</p>
  2737.             </dd><dt><span class="term">h</span></dt><dd>
  2738.               <p>short = word</p>
  2739.             </dd><dt><span class="term">H</span></dt><dd>
  2740.               <p>unsigned short</p>
  2741.             </dd><dt><span class="term">i</span></dt><dd>
  2742.               <p>int</p>
  2743.             </dd><dt><span class="term">I</span></dt><dd>
  2744.               <p>unsigned int</p>
  2745.             </dd><dt><span class="term">l</span></dt><dd>
  2746.               <p>long</p>
  2747.             </dd><dt><span class="term">L</span></dt><dd>
  2748.               <p>unsigned long</p>
  2749.             </dd><dt><span class="term">&lt;</span></dt><dd>
  2750.               <p>little endian</p>
  2751.             </dd><dt><span class="term">&gt;</span></dt><dd>
  2752.               <p>big endian</p>
  2753.             </dd><dt><span class="term">=</span></dt><dd>
  2754.               <p>native endian</p>
  2755.             </dd></dl></div>
  2756.     </div>
  2757.  
  2758.     <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp41"></a>Example</h2></div></div></div>
  2759.      
  2760.  
  2761.       <p></p>
  2762.  
  2763.       <div class="example"><a name="idp1857"></a><p class="title"><b>Example 7.2. Variables doesn't clear in new passes of the compiler</b></p><div class="example-contents">
  2764.          
  2765.  
  2766.          <pre class="programlisting">    LUA PASS1
  2767.       v = 1
  2768.    ENDLUA
  2769.  
  2770.    LUA PASS2
  2771.       print (v)
  2772. -- out to console: 1
  2773.       v++
  2774.    ENDLUA
  2775.  
  2776.    LUA PASS3
  2777.       print (v)
  2778. -- out to console: 2
  2779.    ENDLUA</pre>
  2780.        </div></div><p><br class="example-break"></p><div class="example"><a name="idp1861"></a><p class="title"><b>Example 7.3. To generate some code you need to generate it in all
  2781.          passes</b></p><div class="example-contents">
  2782.          
  2783.  
  2784.          <pre class="programlisting">    LUA ALLPASS
  2785.        _pl("ClearScreen LD (.savesp+1),SP")
  2786.        _pc("LD SP,16384+6144")
  2787.        _pc("LD HL,0")
  2788.        for i = 32768, 38912, 2 do
  2789.            _pc("PUSH HL")
  2790.        end
  2791.        _pl(".savesp: LD SP,0")
  2792.        _pc("RET")
  2793.    ENDLUA
  2794.  
  2795.    LUA PASS2 ; if you fully understand what you are doing
  2796.        sj.add_byte(123) -- and you need emit bytes in other mode
  2797.    ENDLUA ; ok ; you can suppress warning here or at start of block</pre>
  2798.        </div></div><p><br class="example-break"></p><div class="example"><a name="idp1865"></a><p class="title"><b>Example 7.4. Declare function and use it</b></p><div class="example-contents">
  2799.          
  2800.  
  2801.          <pre class="programlisting">     LUA
  2802.         function savetape_mytype(filename, startaddress)
  2803.             local fp
  2804.             fp = assert(io.open(fname, "wb"))
  2805.             for i = 16384, 32767, 4 do
  2806.                 assert(fp:write( string.pack("bbbb",
  2807.                                sj.get_byte(i),
  2808.                                sj.get_byte(i+1),
  2809.                                sj.get_byte(i+2),
  2810.                                sj.get_byte(i+3)) ))
  2811.             end
  2812.             assert(fp:flush())
  2813.             assert(fp:close())
  2814.         end
  2815.     ENDLUA
  2816.  
  2817. ;somewhere in your program
  2818.     LUA
  2819.         savetape_mytype("tapefiles/myprogram.tape", _c("StartGameLabel"))
  2820.     ENDLUA</pre>
  2821.        </div></div><p><br class="example-break"></p><div class="example"><a name="idp1869"></a><p class="title"><b>Example 7.5. Simple sample :)</b></p><div class="example-contents">
  2822.          
  2823.  
  2824.           <pre class="programlisting">  LUA
  2825. -- Function reads number from file &lt;fname&gt;, increases it, creates define "BUILD" with the number and saves the number to &lt;fname&gt;.
  2826. -- With this function you can control count of compilations.
  2827.         function increase_build(fname)
  2828.                 local fp
  2829.                 local build
  2830.                 fp = assert(io.open(fname, "rb"))
  2831.                 build = tonumber(fp:read("*all"))
  2832.                 assert(fp:close())
  2833.                 if type(build) == "nil" then
  2834.                     build = 0
  2835.                 end
  2836.                 build = build + 1;
  2837.                 sj.insert_define("BUILD", build)
  2838.                 fp = assert(io.open(fname, "wb"))
  2839.                 assert(fp:write( build ))
  2840.                 assert(fp:flush())
  2841.                 assert(fp:close())
  2842.         end
  2843.  
  2844. -- Before using you must create empty file "build.txt"!
  2845.         increase_build("build.txt")
  2846.  
  2847. -- Creates define "TIME" with current time
  2848.         sj.insert_define("TIME", '"' .. os.date("%Y-%m-%d %H:%M:%S") .. '"')
  2849.         ENDLUA
  2850.  
  2851. ; print to console our time and build number
  2852.         DISPLAY "Build time: ", TIME
  2853.         DISPLAY "Build number: ", /D, BUILD</pre>
  2854.        </div></div><p><br class="example-break"></p>
  2855.  
  2856.      <p></p>
  2857.  
  2858.      <p></p>
  2859.    </div>
  2860.  </div>
  2861.  
  2862.  <div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="idp46"></a>Chapter 8. <a name="c_savenex"></a>SAVENEX guide</h1></div></div></div>
  2863.    
  2864.        
  2865.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp43"></a><a name="s_savenex_file_format"></a>NEX File Format</h2></div></div></div>
  2866.      
  2867.  
  2868.      <p>NEX is binary format for ZX Spectrum Next, aiming to provide simple delivery of software
  2869.      for the platform. For file format details check <a class="ulink" href="https://specnext.dev/wiki/NEX_file_format" target="_top">
  2870.      https://specnext.dev/wiki/NEX_file_format</a>. In short it is header + loading screen +
  2871.      like-snapshot binary and remaining resources appended after.</p>
  2872.  
  2873.  <p>Sjasmplus currently supports V1.2 and V1.3 of NEX file format (see wiki for details).</p>
  2874.  
  2875.  <p>As such, the SAVENEX commands are available only in ZXSPECTRUMNEXT device emulation mode,
  2876.           see <a class="link" href="#po_device">DEVICE</a>.</p>
  2877.  
  2878.  <p>As the file is designed for self-contained distribution of whole applications/games,
  2879.           its configuration and assembling is a bit too complex for single directive, and the
  2880.           configuration is instead divided into multiple commands, and the assembling goes
  2881.           through multiple stages, so some commands must be used in correct sequence.</p>
  2882.  
  2883.  <p>While the format technically allows to include multiple screen types data, they are all
  2884.           loaded at the beginning over each other, so it makes sense to provide only single loading
  2885.           screen (sjasmplus enforces that).</p>
  2886.  </div>
  2887.  
  2888.  <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp44"></a><a name="s_savenex_commands"></a>Detailed description of each SAVENEX command</h2></div></div></div>
  2889.          
  2890.           <div class="variablelist"><dl class="variablelist"><dt><span class="term"><a name="nex_open"></a>
  2891.                                   SAVENEX OPEN &lt;filename&gt;[,&lt;startAddress&gt;[,&lt;stackAddress&gt;[,&lt;entryBank16k 0..111&gt;[,&lt;fileVersion 2..3&gt;]]]]
  2892.                           </span></dt><dd>
  2893.                                   <p>
  2894.                                           Opens a NEX file, defines start address, stack address and 16k bank to be mapped
  2895.                                           at 0xC000 before code is executed (if values are omitted, start address is zero
  2896.                                           = no start, stack address is 0xFFFE, entryBank is zero, fileVersion is 2).
  2897.                                   </p>
  2898.                                   <p>
  2899.                                           Only single NEX file can be open at the same time, and to finalize the header
  2900.                                           content the command CLOSE has to be used (does auto-close if source ends).
  2901.                                   </p>
  2902.                                   <p>
  2903.                                           Entry bank is number of 16k bank (0..111), not native 8k page, default is zero,
  2904.                                           i.e. the default memory map is identical to ZX 128 (ROM, RAM banks 5, 2 and 0).
  2905.                                   </p>
  2906.                                   <p>
  2907.                                           Make sure your new stack has at least tens of bytes available as those will be
  2908.                                           used already by the NEX loader before executing your entry point (although
  2909.                                           released back).
  2910.                                   </p>
  2911.                                   <p>
  2912.                                           The fileVersion can be 2 (NEX V1.2) or 3 (NEX V1.3), which will enforce the
  2913.                                           specified version of file. Otherwise the file is V1.2 by default and will
  2914.                                           auto-switch to V1.3 when some V1.3 feature is configured/used. When version 2
  2915.                                           is enforced, any usage of V1.3 feature will emit error.
  2916.                                   </p>
  2917.                           </dd><dt><span class="term"><a name="nex_core"></a>
  2918.                                   SAVENEX CORE &lt;major 0..15&gt;,&lt;minor 0..15&gt;,&lt;subminor 0..255&gt;
  2919.                           </span></dt><dd>
  2920.                                   <p>
  2921.                                           Set minimum required Next core version, can be set any time before <a class="link" href="#nex_close">CLOSE</a>.
  2922.                                   </p>
  2923.                           </dd><dt><span class="term"><a name="nex_cfg"></a>
  2924.                                   SAVENEX CFG &lt;border 0..7&gt;[,&lt;fileHandle 0/1/$4000+&gt;[,&lt;PreserveNextRegs 0/1&gt;[,&lt;2MbRamReq 0/1&gt;]]]
  2925.                           </span></dt><dd>
  2926.                                   <p>
  2927.                                           Set border colour (during loading), whether the machine should be set to default
  2928.                                           state (PreserveNextRegs = 0 = default), if the app requires extended RAM
  2929.                                           (224 8k pages) and how the file handle of the NEX file should be treated:
  2930.                                           0 = default = close, 1 = keep open and pass in BC, $4000..$FFFE = keep open,
  2931.                                           and write into memory at provided address (after entry bank is paged in). This
  2932.                                           can be set any time before <a class="link" href="#nex_close">CLOSE</a>.
  2933.                                   </p>
  2934.                           </dd><dt><span class="term"><a name="nex_cfg3"></a>
  2935.                                   SAVENEX CFG3 &lt;DoCRC 0/1&gt;[,&lt;PreserveExpansionBus 0/1&gt;[,&lt;CLIbufferAdr&gt;,&lt;CLIbufferSize&gt;]]
  2936.                           </span></dt><dd>
  2937.                                   <p>
  2938.                                           All of these are NEX format V1.3 features and using "CFG3" command will change
  2939.                                           the version to V1.3 automatically (if not specified by <a class="link" href="#nex_open">OPEN</a>).
  2940.                                   </p>
  2941.                                   <p>
  2942.                                           DoCRC: default = 1, sjasmplus will checksum the file (if you know you will be
  2943.                                           further patching file afterwards, switch it off, otherwise keep 1).
  2944.                                   </p>
  2945.                                   <p>
  2946.                                           PreserveExpansionBus: default = 0, 0 = the NEX loader will disable expansion
  2947.                                           bus through NextReg $80 / 1 = the NEX loader will not do anything.
  2948.                                   </p>
  2949.                                   <p>
  2950.                                           CLIbufferAdr, CLIbufferSize: default = [0, 0], address and size of buffer for
  2951.                                           NEX loader to copy the arguments line into. The buffer is copied after the
  2952.                                           "entryBank" is mapped, so you can allocate buffer in your entryBank. The
  2953.                                           loader/format has hard limit 2048 bytes, the argument line will be truncated
  2954.                                           if longer. If your reserved buffer is shorter than 2048 bytes, the copy will
  2955.                                           be also truncated to your buffer size only. If not truncated, the argument line
  2956.                                           can end with any of these: Enter (13), colon or zero byte (truncated has no
  2957.                                           terminator character, just fills the full buffer).
  2958.                                   </p>
  2959.                           </dd><dt><span class="term"><a name="nex_bar"></a>
  2960.                                   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;]]]
  2961.                           </span></dt><dd>
  2962.                                   <p>
  2963.                                           Loading-bar related setup ("colour" usage depends on screen mode), can be set
  2964.                                           any time before <a class="link" href="#nex_close">CLOSE</a>.
  2965.                                   </p>
  2966.                                   <p>
  2967.                                           The posY argument will apply only to V1.3 Layer2 screens in 320x256 and
  2968.                                           640x256 resolution (then defaults to 254 = bottom of screen, 2px tall bar).
  2969.                                   </p>
  2970.                           </dd><dt><span class="term"><a name="nex_palette"></a>
  2971.                                   <p>SAVENEX PALETTE NONE</p>
  2972.                                   <p>SAVENEX PALETTE DEFAULT</p>
  2973.                                   <p>SAVENEX PALETTE MEM &lt;palPage8kNum 0..223&gt;,&lt;palOffset&gt;</p>
  2974.                                   <p>SAVENEX PALETTE BMP &lt;filename&gt;</p>
  2975.                           </span></dt><dd>
  2976.                                   <p>
  2977.                                           This is optional command to set palette in alternative way ahead of SCREEN
  2978.                                           command, with higher priority (if the PALETTE command is used, following
  2979.                                           SCREEN commands will ignore the palette arguments and keep the palette defined
  2980.                                           by this command). You can be use it between <a class="link" href="#nex_open">OPEN</a>
  2981.                                           and <a class="link" href="#nex_auto">SCREEN</a> command. But appropriate SCREEN
  2982.                                           type supporting palette must be defined by SCREEN command too.
  2983.                                   </p>
  2984.                                   <p>
  2985.                                           Palette consists of 512 bytes (256 palette items from index 0), in 9b colour
  2986.                                           format: first byte is %RRRGGGBB, second byte is %P000000B (P is priority flag
  2987.                                           for Layer 2 colours).
  2988.                                   </p>
  2989.                                   <p>
  2990.                                           The DEFAULT palette will generate colour values from the colour index, the same
  2991.                                           way how default Layer 2 palette is initialized on the ZX Spectrum Next.
  2992.                                   </p>
  2993.                                   <p>
  2994.                                           The NONE palette will force the "no palette" flag even if SCREEN command later
  2995.                                           does specify some palette (it will be still ignored).
  2996.                                   </p>
  2997.                           </dd><dt><span class="term"><a name="nex_screen"></a>
  2998.                                   SAVENEX SCREEN L2 [&lt;Page8kNum 0..223&gt;,&lt;offset&gt;[,&lt;palPage8kNum 0..223&gt;,&lt;palOffset&gt;]]
  2999.                           </span></dt><dd>
  3000.                                   <p>
  3001.                                           Layer 2 loading screen, can be used between <a class="link" href="#nex_open">OPEN</a>
  3002.                                           and first <a class="link" href="#nex_auto">AUTO</a>/<a class="link" href="#nex_bank">BANK</a> command.
  3003.                                   </p>
  3004.                                   <p>
  3005.                                           Palette consists of 512 bytes (256 palette items from index 0), in 9b colour
  3006.                                           format: first byte is %RRRGGGBB, second byte is %P000000B (P is priority flag
  3007.                                           for Layer 2 colours).
  3008.                                   </p>
  3009.                                   <p>
  3010.                                           Image data are 48kiB block of memory, the loader will use always banks 9..11 to display
  3011.                                           it (8k pages 18..23), but if you will prepare the data there, it will be also re-saved
  3012.                                           by <a class="link" href="#nex_auto">AUTO</a> command, so either use other banks, and overwrite
  3013.                                           them with valid data/code after using the SCREEN command, or reset pages 18..23 to zero
  3014.                                           after SCREEN.
  3015.                                   </p>
  3016.                                   <p>
  3017.                                           If no memory address is specified, the pages 18..23 are stored in file, and if
  3018.                                           no palette address is specified, no-palette flag is set in NEX file.
  3019.                                   </p>
  3020.                           </dd><dt><span class="term">
  3021.                                   <p>SAVENEX SCREEN L2_320 [&lt;Page8kNum 0..223&gt;,&lt;offset&gt;[,&lt;palPage8kNum 0..223&gt;,&lt;palOffset&gt;]]</p>
  3022.                                   <p>SAVENEX SCREEN L2_640 [&lt;Page8kNum 0..223&gt;,&lt;offset&gt;[,&lt;palPage8kNum 0..223&gt;,&lt;palOffset&gt;]]</p>
  3023.                           </span></dt><dd>
  3024.                                   <p>
  3025.                                           Works same way as "L2" variant, but will set up screen for new resolutions 320x256x8
  3026.                                           and 640x256x4. The difference is that the required image data are 80kiB (five 16kiB
  3027.                                           banks; equals ten 8kiB pages), the banks used to show the screen in loader are
  3028.                                           9..13 (8k pages 18..27 - that's also the default address of data if not specified)
  3029.                                           - avoid these in regular banks stored in the file.
  3030.                                   </p>
  3031.                                   <p>
  3032.                                           These are NEX format V1.3 features and using them will change the version to V1.3
  3033.                                           automatically (if not specified by <a class="link" href="#nex_open">OPEN</a>). This
  3034.                                           command doesn't allow to set specific palette offset value (too lazy to add it,
  3035.                                           use BMP variant if you really need it).
  3036.                                   </p>
  3037.                                   <p>
  3038.                                           The data has to be already in correct format and organized as if displayed (the
  3039.                                           "transposed" bitmap where +1 address goes to pixel below, and +256 goes to pixel
  3040.                                           on the right (or pair of pixels in case of 640x256x4bpp mode), this command will
  3041.                                           just dump them into file "as is".
  3042.                                   </p>
  3043.                                   <p>
  3044.                                           The loading bar colour byte will be also used "as is", which in 4bpp mode means
  3045.                                           the byte does define pair of 4 bit pixels, i.e. if you want solid-colour "3"
  3046.                                           loading bar in 4bpp mode, define it as value $33. Keep also in mind the default
  3047.                                           loading bar position is Y=254, which on most of the TV/LCD displays is outside
  3048.                                           of visible range, the reasonably "safe" (visible on almost all of the screens)
  3049.                                           resolution is about 288x224 (+16px around PAPER area, +24px is visible on many
  3050.                                           displays too), you may want to organize your screen in a way to show all important
  3051.                                           information within this area, and make the rest "unimportant" so it can hide
  3052.                                           beyond the edge of screen.
  3053.                                   </p>
  3054.                           </dd><dt><span class="term">
  3055.                                   SAVENEX SCREEN LR [&lt;Page8kNum 0..223&gt;,&lt;offset&gt;[,&lt;palPage8kNum 0..223&gt;,&lt;palOffset&gt;]]
  3056.                           </span></dt><dd>
  3057.                                   <p>
  3058.                                           LoRes (128x96) loading screen, can be used between <a class="link" href="#nex_open">OPEN</a>
  3059.                                           and first <a class="link" href="#nex_auto">AUTO</a>/<a class="link" href="#nex_bank">BANK</a> command.
  3060.                                   </p>
  3061.                                   <p>
  3062.                                           Palette is similar to Layer 2 mode, just LoRes mode doesn't have priority bit.
  3063.                                   </p>
  3064.                                   <p>
  3065.                                           Image data are 12288 bytes memory block - either consecutive block if specific
  3066.                                           address is provided, or without address the actual bank 5 memory is stored
  3067.                                           (taking 6144 bytes from address 0x4000 and 6144 bytes from address 0x6000).
  3068.                                   </p>
  3069.                           </dd><dt><span class="term">
  3070.                                   SAVENEX SCREEN BMP &lt;filename&gt;[,&lt;savePalette 0/1&gt;[,&lt;paletteOffset 0..15&gt;]]
  3071.                           </span></dt><dd>
  3072.                                   <p>
  3073.                                           Only small subset of BMP files can be used: 256x192 (Layer 2) or 128x96 (LoRes),
  3074.                                           indexed (8bit image data with palette) and palette data will be truncated
  3075.                                           to 3:3:3 color space directly (no smart colour quantization or dithering is applied).
  3076.                                           And the file must be uncompressed.
  3077.                                   </p>
  3078.                                   <p>
  3079.                                           For V1.3 NEX files you can include also 320x256 and 640x256 files (Layer 2), the
  3080.                                           640x256 should be also 8bit indexed, but only 4 bits of pixel data will be used
  3081.                                           (256 colour palette is legitimate and will be stored "as is" in NEX file).
  3082.                                           These two new modes can also include paletteOffset argument 0..15 (does not apply
  3083.                                           to V1.2 BMP files above), the offset is added to top four bits of pixel value.
  3084.                                   </p>
  3085.                                   <p>
  3086.                                           The BMP will be included as loading screen, can be used between <a class="link" href="#nex_open">OPEN</a>
  3087.                                           and first <a class="link" href="#nex_auto">AUTO</a>/<a class="link" href="#nex_bank">BANK</a> command.
  3088.                                   </p>
  3089.                                   <p>
  3090.                                           By default the palette from BMP file is used, but you can override that by savePalette = 0.
  3091.                                           The warning about palette containing less than 256 colours can be suppressed by end-of-line
  3092.                                           OK comment like: <code class="code">SAVENEX SCREEN BMP ... ; ok ...your comment</code>.
  3093.                                   </p>
  3094.                           </dd><dt><span class="term">
  3095.                                   SAVENEX SCREEN (SCR|SHC|SHR) [&lt;hiResColour 0..7&gt;]
  3096.                           </span></dt><dd>
  3097.                                   <p>
  3098.                                           ULA/Timex modes loading screen, can be used between <a class="link" href="#nex_open">OPEN</a>
  3099.                                           and first <a class="link" href="#nex_auto">AUTO</a>/<a class="link" href="#nex_bank">BANK</a> command.
  3100.                                   </p>
  3101.                                   <p>
  3102.                                           The actual bank 5 memory (pages 10..11) is stored as if the image is displayed,
  3103.                                           in these modes the palette can't be specified.
  3104.                                   </p>
  3105.                                   <p>
  3106.                                           SCR is classic ZX 6912 bytes long screen from address 0x4000 (page 10 is used,
  3107.                                           even if the slot 1 is modified to other page, so you must prepare the image "in place").
  3108.                                   </p>
  3109.                                   <p>
  3110.                                           SHC and SHR are Timex HiColor (8x1 attribute) and HiRes (512x192 bitmap) modes,
  3111.                                           prepare data "in place", i.e. 6144 bytes into page 10 and 6144 bytes into page
  3112.                                           11 (0x4000 and 0x6000 addresses in default memory setup). For HiRes mode you
  3113.                                           should specify ink colour (the paper is complement of ink).
  3114.                                   </p>
  3115.                           </dd><dt><span class="term">
  3116.                                   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;]
  3117.                           </span></dt><dd>
  3118.                                   <p>
  3119.                                           NEX V1.3 tilemap loading screen, can be used between <a class="link" href="#nex_open">OPEN</a>
  3120.                                           and first <a class="link" href="#nex_auto">AUTO</a>/<a class="link" href="#nex_bank">BANK</a> command.
  3121.                                   </p>
  3122.                                   <p>
  3123.                                           To define palette use the <a class="link" href="#nex_palette">PALETTE</a> command.
  3124.                                   </p>
  3125.                                   <p>
  3126.                                           The image data are stored as regular Bank 5 of the NEX file (which is the first bank
  3127.                                           to be loaded by loader), depending on AlsoStoreBank5 value (default 1), this SCREEN
  3128.                                           command will also execute <a class="link" href="#nex_bank">BANK  5</a> command to store
  3129.                                           the image data.
  3130.                                   </p>
  3131.                                   <p>
  3132.                                           The NextRegisters $6B, $6C, $6E and $6F should be enough to specify any variant
  3133.                                           of tilemap mode, so the precise sub-type and image data layout is under control
  3134.                                           of user, the sjasmplus doesn't enforce any particular configuration.
  3135.                                   </p>
  3136.                                   <p>
  3137.                                           If you want to use also <a class="link" href="#nex_copper">COPPER</a> command, use it
  3138.                                           either ahead of the SCREEN TILE command, or use "AlsoStoreBank5 = 0" to delay the
  3139.                                           storage of Bank 5 data. In such case you must then later explicitly store
  3140.                                           the Bank 5 as regular bank, either with BANK or AUTO command.
  3141.                                   </p>
  3142.                           </dd><dt><span class="term"><a name="nex_copper"></a>
  3143.                                   SAVENEX COPPER &lt;Page8kNum 0..223&gt;,&lt;offset&gt;
  3144.                           </span></dt><dd>
  3145.                                   <p>
  3146.                                           Can be used after <a class="link" href="#nex_open">OPEN</a> and before first <a class="link" href="#nex_auto">AUTO</a> or <a class="link" href="#nex_bank">BANK</a>
  3147.                                           command (the copper data are stored between screen and bank data).
  3148.                                   </p>
  3149.                                   <p>
  3150.                                           Exactly 2048 bytes are stored (full Copper memory), and the loader will start
  3151.                                           the copper code in mode %01 (reset CPC to 0, then starts the copper), so the
  3152.                                           copper code will wrap around infinitely after the 1024th instruction executed.
  3153.                                           The copper is started after the screen block is loaded and displayed.
  3154.                                   </p>
  3155.                           </dd><dt><span class="term"><a name="nex_bank"></a>
  3156.                                   SAVENEX BANK &lt;bank16k 0..111&gt;[,...]
  3157.                           </span></dt><dd>
  3158.                                   <p>
  3159.                                           Can be used after <a class="link" href="#nex_open">OPEN</a> or <a class="link" href="#nex_screen">
  3160.                                                   SCREEN</a> and before <a class="link" href="#nex_close">CLOSE</a>, but the 16ki
  3161.                                           banks must be saved in correct order: 5, 2, 0, 1, 3, 4, 6, 7, 8, 9, 10, ..., 111
  3162.                                   </p>
  3163.                           </dd><dt><span class="term"><a name="nex_auto"></a>
  3164.                                   SAVENEX AUTO [&lt;fromBank16k 0..111&gt;[,&lt;toBank16k 0..111&gt;]]
  3165.                           </span></dt><dd>
  3166.                                   <p>
  3167.                                           Can be used after <a class="link" href="#nex_open">OPEN</a> or <a class="link" href="#nex_screen">
  3168.                                                   SCREEN</a> and before <a class="link" href="#nex_close">CLOSE</a>. The sjasmplus
  3169.                                           will save every 16k bank containing at least one non-zero byte; detected in the correct order (automatically
  3170.                                           will save every non-zero 16k bank detected in the correct order (automatically
  3171.                                           starting from first possible bank after previous BANK/AUTO commands, or from
  3172.                                           provided "fromBank").
  3173.                                   </p>
  3174.                                   <p>
  3175.                                           For "fromBank" value use the specified order above in <a class="link" href="#nex_bank">BANK
  3176.                                                   </a> command, i.e. 5, 2, 0, ...
  3177.                                   </p>
  3178.                           </dd><dt><span class="term"><a name="nex_close"></a>
  3179.                                   SAVENEX CLOSE [&lt;fileToAppend&gt;]
  3180.                           </span></dt><dd>
  3181.                                   <p>
  3182.                                           Can be used after <a class="link" href="#nex_open">OPEN</a>. The currently open NEX
  3183.                                           file will be finalized (header adjusted), and optional extra file just appended
  3184.                                           to the end of NEX file.
  3185.                                   </p>
  3186.                           </dd></dl></div>
  3187.  
  3188.   </div>
  3189.          
  3190.   <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp45"></a><a name="s_savenex_examples"></a>Examples</h2></div></div></div>
  3191.          
  3192.  
  3193.           <div class="example"><a name="idp2041"></a><p class="title"><b>Example 8.1. docs_examples/s_savenex_examples.asm</b></p><div class="example-contents">
  3194.          
  3195.                   <p>
  3196.                           Creating NEX file which will have Layer2 loading screen (stripes), progress bar, and will
  3197.                           enter infinite loop with calling stack (used by IM 1 interrupt handler) visible on the
  3198.                           Layer 2 screen.
  3199.                   </p>
  3200.                   <pre class="programlisting">    DEVICE ZXSPECTRUMNEXT
  3201.     ORG $7E00
  3202. start:  ei : jr $           ; app code entry point, BC = NEX file handle
  3203.     ; Layer2 screen (top 1/3 defined, bottom of it will be used also as "visible" stack)
  3204.     ORG $C000 : DUP 64*32 : DB $90,$91,$92,$93,$94,$95,$96,$97 : EDUP
  3205.  
  3206.     ; write everything into NEX file
  3207.     SAVENEX OPEN "example.nex", start, $FFFE, 9  ; stack will go into Layer2
  3208.     SAVENEX CORE 2, 0, 0        ; Next core 2.0.0 required as minimum
  3209.     SAVENEX CFG 4, 1            ; green border, file handle in BC
  3210.     SAVENEX BAR 1, $E0, 50, 25  ; do load bar, red colour, start/load delays 50/25 frames
  3211.     SAVENEX SCREEN L2 0, 0      ; store the data from C000 (page 0, offset 0), no palette
  3212.     SAVENEX BANK 5, 100, 101    ; store the 16ki banks 5 (contains the code at 0x7E00), 100, 101
  3213.     SAVENEX CLOSE               ; (banks 100 and 101 are added just as example)
  3214.                   </pre>
  3215.           </div></div><br class="example-break">
  3216.   </div>
  3217.  
  3218.   </div>
  3219.  
  3220.   <div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="idp51"></a>Chapter 9. <a name="c_sld_data"></a>Source Level Debugging (SLD) data</h1></div></div></div>
  3221.    
  3222.  
  3223.     <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp47"></a><a name="s_sld_intro"></a>What is it?</h2></div></div></div>
  3224.                
  3225.  
  3226.                 <p>
  3227.                         SLD data are extra "tracing" data produced during assembling for debuggers and IDEs,
  3228.                         similar to "map" files already supported by sjasmplus (<a class="link" href="#po_labelslist">
  3229.                         LABELSLIST</a> and <a class="link" href="#po_cspectmap">CSPECTMAP</a>).
  3230.                 </p>
  3231.  
  3232.                 <p>
  3233.                         The debugger can read these data, and with non-tricky source producing machine code
  3234.                         with correct device memory mapping, the debugger can trace the origins of every
  3235.                         instruction back to the original source code line, and display the source instead/along
  3236.                         the disassembly view (the "map" files mentioned above provide only list of labels
  3237.                         which is usually already super helpful, but can't track the source origins of each
  3238.                         instruction).
  3239.                 </p>
  3240.  
  3241.                 <p>
  3242.                         The original impulse and working patch for this feature came from Chris Kirby, adding the
  3243.                         single-instruction-step feature to his development tools: <a class="ulink" href="https://github.com/Ckirby101/NDS-NextDevSystem" target="_top">
  3244.                                 Next Development System</a> (currently in 2019 under heavy development).
  3245.                 </p>
  3246.         </div>
  3247.  
  3248.    <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp48"></a><a name="s_sld_cli"></a>Usage</h2></div></div></div>
  3249.                
  3250.  
  3251.                 <p>
  3252.                         On the sjasmplus side all you need is to add another command line option when starting
  3253.                         the assembler.
  3254.                         </p><pre class="synopsis">prompt$ sjasmplus --sld=project.sld.txt file1.asm file2.asm</pre><p>
  3255.                         This will produce along regular files also file `project.sld.txt` containing the
  3256.                         tracing data. The file format is text-like, so the content can be viewed
  3257.                         in any text editor, but it's supposed to be processed by the debugger.
  3258.                 </p>
  3259.  
  3260.                 <p>
  3261.                         The SLD data are being exported <span class="strong"><strong>only</strong></span> for machine code produced
  3262.                         within one of the virtual devices (see <a class="link" href="#s_realdevice">DEVICE</a>).
  3263.                         And the accuracy of the data directly depends on the state of the virtual device at
  3264.                         the moment when the particular instruction is assembled, see next section for further
  3265.                         advice how to get best tracing data.
  3266.                 </p>
  3267.  
  3268.                 <p>
  3269.                         If the option `--sld` without explicit filename is used, the first input source filename
  3270.                         will be copied and its extension changed to `.sld.txt`, which should work well for
  3271.                         single-main file type of projects.
  3272.                 </p>
  3273.  
  3274.         </div>
  3275.  
  3276.         <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp49"></a><a name="s_sld_source_advice"></a>How to write "non tricky" source</h2></div></div></div>
  3277.                
  3278.  
  3279.                 <p>
  3280.                         For best results (tracing data covering all your instructions and making source-level
  3281.                         debugging available all the time):
  3282.                 </p>
  3283.  
  3284.                 <p>
  3285.                         Generate machine code only with instructions, i.e. while `db 0` in source will produce
  3286.                         `nop` instruction, the tracing data for such `nop` will be missing. Only source line
  3287.                         containing the "nop" will emit both the zero byte into machine code and tracing data.
  3288.                 </p>
  3289.  
  3290.                 <p>
  3291.                         Keep the memory map of the virtual device as it will be set at run-time when writing
  3292.                         particular code. While using only regular <a class="link" href="#po_org">ORG</a> to place
  3293.                         the code in desired memory area, keeping only the modified area with memory pages
  3294.                         mapped-in is enough to get correct SLD data - but when using <a class="link" href="#po_disp">DISP</a>
  3295.                         directive to generate code in displaced way, you need to map-in correct pages in both
  3296.                         memory areas (where the code is currently assembled, and where it is supposed to be
  3297.                         operational at run-time - currently impossible if the two areas share the same SLOT area).
  3298.                 </p>
  3299.  
  3300.                 <p>
  3301.                         To map-in correct pages you can use directives:
  3302.                         <a class="link" href="#po_slot">SLOT</a>, <a class="link" href="#po_page">PAGE</a>,
  3303.                         <a class="link" href="#po_mmu">MMU</a> and <a class="link" href="#po_org">ORG</a>
  3304.                 </p>
  3305.  
  3306.                 <p>
  3307.                         Only labels defined in regular way get also the memory-page data in SLD file, EQU
  3308.                         values are exported without the page information, even if they represent memory
  3309.                         address:
  3310.                         </p><pre class="programlisting">
  3311. regularLabel:   nop             ; current page exported to SLD data
  3312. equLabel        EQU   $8000     ; only value without page is exported
  3313. varSymbol       =     14        ; =/DEFL labels are omitted completely</pre><p>
  3314.                 </p>
  3315.  
  3316.                 <p>
  3317.                         Re-using the same memory area (page + address) for two different pieces of code (for
  3318.                         example by having multiple routines targeting the same address with DISP, and run-time
  3319.                         code uploading the correct variant dynamically at the destination) will highly likely
  3320.                         confuse the debugger, producing two source-origins data for the identical address.
  3321.                         You may want to avoid this, especially with early version of tools not being able to
  3322.                         resolve such ambiguity in reasonable way (the sjasmplus will generate tracing data ok
  3323.                         even in this case, but they are tricky to interpret).
  3324.                 </p>
  3325.  
  3326.                 <p>
  3327.                         If you are using the colons to put multiple instructions on single line, verify the
  3328.                         debugger can cope with the tracing data containing full line + column begin/end
  3329.                         information, the simple/early tools will likely highlight only whole line of source.
  3330.                         For a start keeping single instruction per line may keep things simple.
  3331.                 </p>
  3332.  
  3333.                 <p>
  3334.                         The multi-arg instructions produce the tracing data only for the first instruction,
  3335.                         which will probably cause problems with single-stepping through such code. Rather
  3336.                         avoid multi-arg syntax when you are planning to debug the code.
  3337.                 </p>
  3338.  
  3339.                 <p>
  3340.                         The various code generators written in macros or Lua scripts will produce accurate
  3341.                         tracing data in case of macros, and condensed (pointing at "ENDLUA" line) data for
  3342.                         Lua generators, but it still depends on the debugger if it can display both top
  3343.                         level source code triggering the generator and source lines containing definitions
  3344.                         of particular instructions.
  3345.                 </p>
  3346.  
  3347.         </div>
  3348.  
  3349.     <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp50"></a><a name="s_sld_file_format"></a>SLD File Format definition (version "0")</h2></div></div></div>
  3350.                
  3351.  
  3352.                 <p>The SLD data is text-file (sjasmplus is using UNIX-like newlines 0x0A, but parsers
  3353.                         should rather cope with any of common EOL scheme). The general format is CSV-like
  3354.                         using pipe character as delimiter between fields.
  3355.                 </p>
  3356.  
  3357.                 <p>
  3358.                         If the first field is empty, the line is one of the special control lines - the second
  3359.                         field selects type of control line. If also the second field is empty, the remaining
  3360.                         part of line should be ignored (comment line).
  3361.                         Currently only one type of "control line" exists, the "SLD.data.version" (third
  3362.                         field is integer number):
  3363. </p><pre class="programlisting">|SLD.data.version|0
  3364. ||anything ... comment-like line</pre><p>
  3365.                         The file format version line should be always first line of the SLD data file.
  3366.                 </p>
  3367.  
  3368.                 <p>
  3369.                         The regular tracing data lines have fixed amount of fields: eight. The seventh field
  3370.                         contains single uppercase letter defining type of the line, which affects sub-variants
  3371.                         of format for eighth field, but first six fields share the same formatting and meaning
  3372.                         across all types of regular lines:
  3373. </p><pre class="programlisting">
  3374. &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;
  3375. </pre><p>
  3376.                 </p>
  3377.  
  3378.                 <p>
  3379.                         <code class="code">&lt;source file&gt;</code> - file name of top-level source emitting the
  3380.                         instruction/label/device.
  3381.                 </p>
  3382.  
  3383.                 <p>
  3384.                         <code class="code">&lt;src line&gt;</code> - line and characters in top-level source file, the precise
  3385.                         format is "<code class="code">&lt;line&gt;[:&lt;column begin&gt;[:&lt;column end&gt;]]</code>" where
  3386.                         first number is line number (starting at 1). The two following numbers delimited by colon
  3387.                         are optional, representing the column where the segment starts/ends at the line. The
  3388.                         column values are starting from 1 too, the "end" column is pointing beyond the current
  3389.                         segment. The columns are in "bytes", i.e. tabulator does increase the column value by +1
  3390.                         only, and the "end" may actually point well beyond "strlen(line)".
  3391.                 </p>
  3392.  
  3393.                 <p>
  3394.                         <code class="code">&lt;definition file&gt;</code> - file name of the source defining the particular
  3395.                         instruction (for example where the instruction inside MACRO was originally defined).
  3396.                         If empty, the definition-file name is identical to <code class="code">&lt;source file&gt;</code>
  3397.                         (common case for single-source projects).
  3398.                 </p>
  3399.  
  3400.  
  3401.                 <p>
  3402.                         <code class="code">&lt;def line&gt;</code> - zero when there is no extra "definition" of instruction
  3403.                         involved. When non-zero, the format is identical to <code class="code">&lt;src line&gt;</code>, but
  3404.                         with regard to the file specified in <code class="code">&lt;definition file&gt;</code> field.
  3405.                 </p>
  3406.  
  3407.                 <p>
  3408.                         <code class="code">&lt;page&gt;</code> - number of memory page where the <code class="code">&lt;value&gt;</code>
  3409.                         address points to, or -1 when value is not memory address.
  3410.                 </p>
  3411.  
  3412.                 <p>
  3413.                         <code class="code">&lt;value&gt;</code> - any 32 bit integer value (EQU), but when representing memory
  3414.                         address, it is full 16 bit value from Z80 address space (the top bits beyond the memory
  3415.                         page size contains the number of "slot" where the instruction/label resides).
  3416.                 </p>
  3417.  
  3418.                 <p>
  3419.                         <code class="code">&lt;type&gt;</code> - single uppercase letter representing type of line, current
  3420.                         types: T (instruction Trace), F (Function), D (equ Data), Z (device memory model)
  3421.                 </p>
  3422.  
  3423.                 <p>
  3424.                         <code class="code">&lt;data&gt;</code> - extra data specific for particular line type. Empty for
  3425.                         "T" lines, contains label/symbol name for types "F" and "D". The "D" values usually
  3426.                         don't have page defined (equals -1), but the tools should accept also valid page
  3427.                         value for "D" type too, just like for "F" lines.
  3428.                 </p>
  3429.  
  3430.                 <p>
  3431.                         For type "Z" the data field contains string describing the device memory model which
  3432.                         is being selected in source and should be applied for following SLD data lines. The
  3433.                         memory model string format is:
  3434. </p><pre class="programlisting">
  3435. 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;]
  3436. // unsigned &lt;page size&gt; is also any-slot size in current version.
  3437. // unsigned &lt;page count&gt; and &lt;slots count&gt; define how many pages/slots there are
  3438. // uint16_t &lt;slotX adr&gt; is starting address of slot memory region in Z80 16b addressing
  3439. </pre><p>
  3440.                 </p>
  3441.  
  3442.                 <div class="example"><a name="idp2111"></a><p class="title"><b>Example 9.1. Example of SLD file</b></p><div class="example-contents">
  3443.                        
  3444.  
  3445. <pre class="programlisting">
  3446. |SLD.data.version|0
  3447. || ZX Spectrum Next device description:
  3448. 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
  3449. || label "main" points to 32768, with page 14 mapped-in (defined in toplevel.asm:62)
  3450. toplevel.asm|62||0|14|32768|F|main
  3451. || instruction opcode at 32768 (page 14) was created by toplevel.asm:64
  3452. toplevel.asm|64||0|14|32768|T|
  3453. || instruction opcode at 32769 (p 14) was created by toplevel.asm:67
  3454. || (but it is a line using macro, the instruction was defined by toplevel.asm:52)
  3455. toplevel.asm|67||52|14|32769|T|
  3456. || instruction opcode at 32770 (p 18) was created by toplevel.asm:68:12-24
  3457. toplevel.asm|68:12:24||0|18|32770|T|
  3458. || instruction opcode at 32771 (p 18) was created by toplevel.asm:68:24 (till EOL)
  3459. toplevel.asm|68:24||0|18|32771|T|
  3460. || "PORT_NUMBER EQU 254" defined at toplevel.asm:69
  3461. toplevel.asm|69||0|-1|254|D|PORT_NUMBER
  3462. || label+instruction emitted from toplevel.asm:70, but defined in include.asm:3
  3463. toplevel.asm|70|include.asm|3|37|40976|F|0&gt;macro_defined_in_include_asm
  3464. toplevel.asm|70|include.asm|3|37|40976|T|
  3465. </pre>
  3466.  
  3467.                 </div></div><br class="example-break">
  3468.  
  3469. </div>
  3470.  
  3471.  </div>
  3472.  
  3473. </div></body></html>
  3474.