?login_element?

Subversion Repositories NedoOS

Rev

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