-
Notifications
You must be signed in to change notification settings - Fork 50
/
documentation.xml
5282 lines (4377 loc) · 226 KB
/
documentation.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<book id="sjasmplus_manual">
<title>SjASMPlus 1.20.3 Documentation [2023-06-23]</title>
<chapter id="introduction">
<title>Introduction</title>
<section id="license">
<title>License</title>
<para>SjASMPlus is licensed under BSD license.</para>
</section>
<section id="about">
<title>What is it?</title>
<para>
SjASMPlus is Z80 Assembly Language Cross Compiler. It is available
for Win32, Linux and FreeBSD (mainly 5.x) systems. It is based on SjASM
source code by Sjoerd Mastijn (<ulink url="http://xl2s.tk">http://xl2s.tk</ulink>).
</para>
</section>
<section id="features">
<title>Main Features</title>
<para><itemizedlist>
<listitem>
<para>Full source of assembler available under BSD license, modify and extend as you wish</para>
</listitem>
<listitem>
<para>Z80/R800/Z80N/i8080/LR35902 documented and undocumented opcodes support</para>
</listitem>
<listitem>
<para>Macro language, defines, array of defines</para>
</listitem>
<listitem>
<para>Built-in Lua scripting engine</para>
</listitem>
<listitem>
<para>Conditional assembly, block repeating</para>
</listitem>
<listitem>
<para>Modules (namespaces), local and temporary labels</para>
</listitem>
<listitem>
<para>Source and binary file inclusion, include paths</para>
</listitem>
<listitem>
<para>Multi file output, file updating, various types of exports</para>
</listitem>
<listitem>
<para>Structures to work easily with structured data in memory</para>
</listitem>
<listitem>
<para>Relocation data generator to support SymbOS-like relocation of executables</para>
</listitem>
<listitem>
<para>Virtual device mode for common machines: ZX 128, ZX Next, Amstrad CPC, … (pseudo op DEVICE)</para>
</listitem>
<listitem>
<para>ZX Spectrum specific directives and pseudo ops (SAVESNA, SAVETAP, SAVEHOB, INCHOB, INCTRD…)</para>
</listitem>
<listitem>
<para>ZX Spectrum Next specific features and directives (Z80N, 8ki memory paging, SAVENEX)</para>
</listitem>
<listitem>
<para>Amstrad CPC 464/6128 specific directives (SAVECPCSNA)</para>
</listitem>
<listitem>
<para>Correctness is assured by <ulink url="https://cirrus-ci.com/github/z00m128/sjasmplus/master">
Cirrus-CI with 400+ automated tests</ulink> (that's also 400+ examples of usage!)</para>
</listitem>
<listitem>
<para>Fake instructions as LD HL,DE (LD H,D:LD L,E) and more</para>
</listitem>
<listitem>
<para>Code inlining through colon (LD A,C:INC A:PUSH AF:IFDEF FX:LD A,D:ENDIF…)</para>
</listitem>
<listitem>
<para>Very fast compilation: 1 million lines by 2-3 seconds on modern computer</para>
</listitem>
<listitem>
<para>Multiline block comments and user’s messages</para>
</listitem>
</itemizedlist></para>
</section>
<section id="credits">
<title>Credits</title>
<para>Special thanks to <emphasis>Sjoerd Mastijn</emphasis>, the author of SjASM.</para>
<para><emphasis>Aprisobal </emphasis>- main programming, documentation, etc.</para>
<para>Thanks to:<itemizedlist>
<listitem>
<para><emphasis>Kurles/HS/CPU, Alexander Kovalenko, Ped7g, Dart Alver, Oli Wilkinson</emphasis> - additional
programming;</para>
</listitem>
<listitem>
<para><emphasis>Krystian Wlosek
<kwlosek(at)gmail.com></emphasis> - bug fix patches, Linux
makefile;</para>
</listitem>
<listitem>
<para><emphasis>Ric Horne <Ric.Hohne@eads-ts.com></emphasis>
- bug fix patches.</para>
</listitem>
<listitem>
<para><emphasis>breeze <breeze@tut.by></emphasis> - bug fix
patches.</para>
</listitem>
<listitem>
<para><emphasis>psndcj <psndcj.tbk@gmail.com></emphasis> -
bug reporting, beta-testing.</para>
</listitem>
<listitem>
<para><emphasis>elfh <elphecy@gmail.com></emphasis> - bug
reporting.</para>
</listitem>
<listitem>
<para><emphasis>bugsy <bugsy@ya.ru></emphasis> - bug
reporting.</para>
</listitem>
<listitem>
<para><emphasis>skrju <sq-@mail.ru></emphasis> - bug
reporting.</para>
</listitem>
<listitem>
<para><emphasis>Tygrys, UB880D, Cizo, mborik, z00m, otis</emphasis> -
compilation errors and warnings clean up, makefiles, testing.</para>
</listitem>
<listitem>
<para><emphasis>Antipod, boo_boo, PulkoMandy, Busy, Liniya, LVD</emphasis> -
bug fix patches, testing.</para>
</listitem>
<listitem>
<para><emphasis>CKirby</emphasis> - SLD export and support in his tools.</para>
</listitem>
<listitem>
<para><emphasis>Simon Brattel</emphasis> - for creating mother of all assemblers Zeus
and bringing all the good and peace to the mankind, giving infinite inspiration
to sjasmplus contributors who stole his tremendously amazing features without
even crediting him - till now, fixed (not sure what the particular list of features
was copied from Zeus, I guess DG/DH, I believe some other similarities are rather
copied from the ALASM which had many features before Zeus, but who knows, too late
to track it all precisely, what happened in 90's and when).</para>
</listitem>
</itemizedlist></para>
<para>Big thanks to all people, who helped on development of the compiler!</para>
</section>
<section id="feedback">
<title>Feedback</title>
<para>WWW: <ulink
url="https://github.com/z00m128/sjasmplus">https://github.com/z00m128/sjasmplus</ulink>
(newer versions maintained by z00m and others)</para>
<para>WWW: <ulink
url="https://sourceforge.net/projects/sjasmplus/">https://sourceforge.net/projects/sjasmplus/</ulink>
(original Aprisobal's source)</para>
<para>E-Mail: zoom@centrum.sk, my@aprisobal.by</para>
</section>
<section id="news">
<title>What's new?</title>
<para><variablelist>
<varlistentry>
<term>23.6.2023 - 1.20.3</term>
<listitem>
<synopsis>- added alias <link linkend="s_cli">`--define`</link> for `-D`
- added <link linkend="s_strings">string-literals</link> suffixes Z and C to add zero or set high bit of last char
- end of line backslash continues source line (<ulink url="https://github.com/z00m128/sjasmplus/blob/master/tests/parsing/escape_eol.asm">limited support</ulink>, not recommended)
- Lua: minor version upgrade to 5.4.6 (from 5.4.4)
- minor updates to Makefile
</synopsis>
</listitem>
</varlistentry>
<varlistentry>
<term>14.2.2023 - 1.20.2</term>
<listitem>
<synopsis>- added optional second argument for <link linkend="po_dup">`DUP`</link> to have index variable
- option `--exp` will create file even when no `EXPORT` is used
- fixing variable name-clash when compiling against musl-clib
- LuaBridge updated, CMake and Makefile updated a bit
- minor bugfixes/improvements in parser in specific edge cases
</synopsis>
</listitem>
</varlistentry>
<varlistentry>
<term>29.7.2022 - 1.20.1</term>
<listitem>
<synopsis>- parse decimal <link linkend="s_numeric">numeric constants</link> with warning (for easier Lua 5.4 life)
- added <link linkend="po_saveamsdos">`SAVEAMSDOS`</link> (like SAVEBIN with AMSDOS header)
- added "smart" <link linkend="s_labels">SMC offset</link> syntax for self-modify-code labels: `abc+*: or 123`
- added <link linkend="po_defdevice">`DEFDEVICE`</link> to define custom devices
- Makefile cleanup
</synopsis>
</listitem>
</varlistentry>
<varlistentry>
<term>13.6.2022 - 1.20.0</term>
<listitem>
<synopsis>- Lua: <link linkend="c_lua_scripting">upgrade to 5.4</link>, replacing tolua++ bindings with LuaBridge2.6 library, extending some bindings
- Lua: bindings slightly modified (required by upgrade), refreshed docs, added test coverage
- Lua: the 3rd party extensions (BTW not working for many years) are obsolete in 5.4 and removed
- Lua: more accurate errors/warning location reported even in complex cases
- warnings: added -Wall, --help=warnings shows on/off status, rdlow off by default
- Added HIGH mode to <link linkend="po_relocate_start">relocation data generator</link> (MSB-only relocation mode)
- many open-file "fatal" errors become "non-fatal", assembling will continue
- deprecated features removed: --syntax=m, label `abs` in expressions
- `--color=auto` will stay no-color when <ulink url="https://no-color.org/">env.var. `NO_COLOR`</ulink> is defined
- refactorings, improving some error messages and parsing, small fixes in parsing logic
- fix listing of Lua's sj.parse_code (eol-comments), minor memory leaks fixed
- fix relocation of temporary labels in expressions
- invalid CLI options are reported as regular errors (also changing exit code)
- errors are colored similarly to gcc (only keyword has color), console input name is `<stdin>`
</synopsis>
</listitem>
</varlistentry>
<varlistentry>
<term>31.3.2022 - 1.19.0</term>
<listitem>
<synopsis>- added Amstrad CPC devices (<link linkend="po_device">"AMSTRADCPC464", "AMSTRADCPC6128"</link>) - by Oli Wilkinson
- added Amstrad CPC save snapshot and CDT (<link linkend="po_savecpcsna">`SAVECPCSNA`</link>, <link linkend="po_savecdt">`SAVECDT`</link>) - by Oli Wilkinson
- added <link linkend="po_save3dos">`SAVE3DOS`</link> (like SAVEBIN with +3DOS header)
- the deprecated "ok" warning suppression is removed, use "<warning-id>-ok" comment or -Wno-...
- new <link linkend="s_temp_labels">temporary label</link> suffix syntax "_b" and "_f", enabling them for all expressions
- fix `--longptr` mode to keep 32b address when `DS 0` is used
- added fake instructions adc|add|sbc|sub de,bc|de|hl|sp
- dec|inc|pop|push will accept also single-comma multiarg in --syntax=a mode
- DUP/REPT will now accept also zero count (skipping the block)
- DEFL labels can be defined even as late as in last pass
- bugfixes (macros, listing, file names in errors, SLD reversepop data)
</synopsis>
</listitem>
</varlistentry>
<varlistentry>
<term>29.8.2021 - 1.18.3</term>
<listitem>
<synopsis>- added <link linkend="s_cli">`--color`</link> to enable/disable ANSI coloring of errors/warnings
- added <link linkend="s_cli">`--syntax=s`</link> mode to disable sub-word substitutions of DEFINEs
- added at-sign prefix for <link linkend="s_local_labels">macro local labels</link> to act as non-macro local label
- <link linkend="po_savetrd">`SAVETRD`</link> accepts names containing dot ("z.x.B" is "z.x" with extension "B") - by Dart Alver
- <link linkend="po_savetrd">`SAVETRD`</link> has optional argument to save BASIC with variables (length_minus_variables)
- minor bugfixes (conditional block parser)
</synopsis>
</listitem>
</varlistentry>
<varlistentry>
<term>14.2.2021 - 1.18.2</term>
<listitem>
<synopsis>- [may break old sources] new <link linkend="s_expressions">exist operator</link> to check label existence
- the --syntax=i mode makes now also register parsing case insensitive
- minor bugfixes (predefined values, savenex BMP loader less strict about "colors used" content)
</synopsis>
</listitem>
</varlistentry>
<varlistentry>
<term>23.1.2021 - 1.18.1</term>
<listitem>
<synopsis>- Big-Endian hosts support (experimental and not tested continuously)
- added "listall", "listact" commands to <link linkend="po_opt">OPT</link> - to switch between listing types
- <link linkend="po_while">`WHILE`</link> has optional argument to set explicit guardian-counter
- <link linkend="po_assert">`ASSERT`</link> has optional argument (to add description/notes for expression)
- <link linkend="po_slot">`SLOT`</link> and <link linkend="po_mmu">`MMU`</link> will now accept also starting address of slot instead of its number
- fix: option --sym was not exporting labels starting with underscore
- fix: SAVENEX BMP-loader bug when certain builds of sjasmplus were unable to open BMP files
- fix: after STRUCT instance the "main" label is not polluted by last field of STRUCT
- minor bugfixes in parser, windows cmake-builds have now icon
- docs: adding "Index" section
- docs: adding some missing information (__DATE__, __TIME__), fixing HTML anchor names
</synopsis>
</listitem>
</varlistentry>
<varlistentry>
<term>12.12.2020 - 1.18.0</term>
<listitem>
<synopsis>- [may break old sources] the colon between end of EQU/DEFL/= expression and instruction is mandatory
- [may break old sources] new <link linkend="s_expressions">abs operator</link> for absolute integer value
- new <link linkend="s_id_warnings">system of warnings</link> (and suppression), the "; ok" comments are now deprecated
- <link linkend="po_display">`DISPLAY`</link> has now also binary and char formatting
- <link linkend="po_define">`DEFINE+`</link> added to [re]define identifier without error
- <link linkend="ca_elseif">`ELSEIF`</link> added to conditional assembling arsenal
- <link linkend="po_while">`WHILE`</link> added for conditional loops
- added <link linkend="po_device">"NOSLOT64K" device</link> with 2MiB of virtual memory
- <link linkend="po_labelslist">`LABELSLIST`</link> has new optional argument to dump 16bit "virtual labels"
- <link linkend="po_cspectmap">`CSPECTMAP`</link> exports STRUCT symbols with more detail (instance labels with physical address)
- <link linkend="s_labels">SMC offset</link> syntax for self-modify-code labels for source brevity
- added exclamation mark prefix for <link linkend="s_local_labels">labels</link> to not affect following local labels
- added "listmc" command to <link linkend="po_opt">OPT</link> - to list only lines with machine code bytes
- added <link linkend="s_cli">`--lstlab=sort`</link> variant to have symbols in listings in predictable order
- minor bugfixes in parser and listing-line-numbering, refactored symbols/labels implementation
- Added <ulink url="https://github.com/z00m128/sjasmplus/tree/master/examples/chargfx2asm">example (chargfx2asm)</ulink> how to use sjasmplus as byte-processor for binary files
- <link linkend="c_sld_data">SLD data</link> improvements based on Maziac's feedback and <ulink url="https://github.com/maziac/DeZog">DeZog</ulink>'s needs
</synopsis>
</listitem>
</varlistentry>
<varlistentry>
<term>8.8.2020 - 1.17.0</term>
<listitem>
<synopsis>- `STRUCT` has new <link linkend="st_text">`TEXT`</link> pseudo-instruction to define "DB-like" data (<ulink url="https://github.com/z00m128/sjasmplus/issues/93">Issue #93</ulink>)
- <link linkend="st_usage">`STRUCT` initializer block</link> can be now multi-line (when correctly enclosed in curly braces)
- <link linkend="po_equ">`EQU`</link> now allows for optional override of page number assigned to the new symbol
- new <link linkend="s_expressions">$$$ and $$$$ operators</link> to retrieve "physical" address/page inside DISP block
- instruction `out (c),0` now emits warning (can be suppressed by the "; ok" comment)
- fixed listing of structures using long BLOCK fields (machine code was correct, but listing not)
- fixed some memory leaks, undefined behaviour and unaligned memory access
</synopsis>
</listitem>
</varlistentry>
<varlistentry>
<term>27.7.2020 - 1.16.0</term>
<listitem>
<synopsis>- <link linkend="po_lua">`LUA`</link> the new emit warning (v1.15.1) is now suppressible
- <link linkend="s_predefined">Predefined defines</link> extended and renamed (following gcc/clang ones)
- Added <link linkend="po_relocate_end">relocation data generator</link> (similar to WinAPE feature), check also <ulink url="https://github.com/z00m128/sjasmplus/tree/master/examples/relocation">example</ulink>
- bugfixes/improvements in parser like: operators `not`, `low`, `high` can be followed also by "("
</synopsis>
</listitem>
</varlistentry>
</variablelist></para>
<para>See <ulink url="https://github.com/z00m128/sjasmplus/blob/master/CHANGELOG.md">CHANGELOG.md</ulink> for full list of changes.</para>
</section>
</chapter>
<chapter id="where_to_get">
<title>Where to get and how to use</title>
<section id="s_packages">
<title>Packages</title>
<para>
The <emphasis role="strong">latest release</emphasis> of this sjasmplus variant is
<emphasis role="strong">available at <ulink url="https://github.com/z00m128/sjasmplus/releases/latest">
https://github.com/z00m128/sjasmplus/releases/latest</ulink></emphasis>
- there is available zip archive with <emphasis role="strong">windows binary</emphasis>
(toward <emphasis role="strong">bottom of the page</emphasis>), and zip archives with
<emphasis role="strong">full source code</emphasis> of the sjasmplus.
</para>
<para>Win32 package has:<itemizedlist>
<listitem>
<para>sjasmplus.exe - the Win32 executable.</para>
</listitem>
<listitem>
<para>examples directory - some examples of use</para>
</listitem>
<listitem>
<para>documentation directory - documentation in various
formats</para>
</listitem>
</itemizedlist>
</para>
<para>
You may want to download also the full source package, as it contains more than 400
<emphasis role="strong">automated tests</emphasis> used to verify correctness of executable,
and these can be often helpful to better understand how specific feature of sjasmplus works,
and <emphasis role="strong">how to use it</emphasis> effectively.
</para>
<para>
<emphasis role="strong">Linux, Unix, MacOS</emphasis> and <emphasis role="strong">BSD</emphasis>
version can be built from the full source archive. You can compile it using <emphasis>GCC</emphasis>
and included <emphasis>Makefile</emphasis>. There is an option to use <emphasis>CMake</emphasis>
for compilation. See
<ulink url="https://github.com/z00m128/sjasmplus/blob/master/INSTALL.md">INSTALL.md</ulink> for details.
</para>
<para>Windows binaries are compiled with <emphasis>MinGW</emphasis> environment and included
<emphasis>Makefile.win</emphasis> file.</para>
<para>You can grab older (up to v1.07) binaries and sources at SourceForge project page:
<ulink url="https://sourceforge.net/projects/sjasmplus/">https://sourceforge.net/projects/sjasmplus/</ulink></para>
</section>
<section id="s_cli">
<title>Command line</title>
<para>Usage:</para>
<synopsis>sjasmplus [options] sourcefile(s)</synopsis>
<para>Option flags as follows:</para>
<para><synopsis> -h or --help[=warnings] Help information
--version Basic info (with --nologo only raw version string)
--zxnext[=cspect] Enable ZX Next Z80 extensions (CSpect emulator has
extra "exit" DD00 and "break" DD01 fake instructions)
--i8080 Limit valid instructions to i8080 only (+ no fakes)
--lr35902 Sharp LR35902/SM83 CPU instructions mode (+ no fakes)
--outprefix=<path> Prefix for save/output/.. filenames in directives
Note: if prefix is folder, it must already exist and add trailing slash. Prefix
is applied only to filenames defined in source (not to CLI arguments).
-i<path> or -I<path> or --inc=<path> ( --inc without "=" to empty the list)
Include path (later defined have higher priority)
--lst[=<filename>] Save listing to <filename> (<source>.lst is default)
--lstlab[=sort] Append [sorted] symbol table to listing
--sym=<filename> Save symbol table to <filename>
--exp=<filename> Save exports to <filename> (see EXPORT pseudo-op)
--raw=<filename> Machine code saved also to <filename> (- is STDOUT)
--sld[=<filename>] Save Source Level Debugging data to <filename>
Default name is: "<first input filename>.sld.txt"
Note: use OUTPUT,LUA/ENDLUA and other pseudo-ops to control output
Logging:
--nologo Do not show startup message
--msg=[all|war|err|none|lst|lstlab] Stderr messages verbosity ("all" is default)
Note: "lst" or "lstlab" will turn STDERR into listing file (this will clash with
`--lst`, use only one of the options) and some diagnostic messages of "all"
are omitted, as they are not part of listing files. "lstlab" does sort symbols.
--fullpath Show full path to file in errors
Note: the "fullpath" starts from current working directory, not from file system
root (the MS_VS build was fixed to behave this way since v1.15.0)
--color=[on|off|auto] Enable or disable ANSI coloring of warnings/errors
Note: auto detection checks for existence of environment variable TERM, and its
content is scanned for sub-string "color" (like "xterm-256color")
Other:
-D<NAME>[=<value>] or --define <NAME>[=<value>]
Define <NAME> as <value> (--define since v1.20.3)
-W[no-]<warning_id> Disables/enabled particular warning type
- Reads STDIN as source (even in between regular files)
--longptr No device: program counter $ can go beyond 0x10000
--reversepop Enable reverse POP order (as in base SjASM version)
--dirbol Enable directives processing from the beginning of line
--nofakes Disable fake instructions (same as --syntax=F)
--dos866 Encode from Windows codepage to DOS 866 (Cyrillic)
--syntax=<...> Adjust parsing syntax, read details below.</synopsis></para>
<para>
The option <code>--lstlab=sort</code> will cause also other symbol dumps being sorted (along
listing): <code>--sym</code>, <code>CSPECTMAP</code> and <code>LABELSLIST</code>.
The <code>--msg=lstlab</code> sets always sorting "on" (no "unsorted" option).
</para>
<para>Value for <code>--syntax</code> option may consist of multiple letters, omitting letter
for particular feature will use the default setting:
<synopsis> a Multi-argument delimiter ",," (default is ",") (but dec|inc|pop|push accept also ",")
b Whole expression parentheses are legal for memory access only (default = immediate or memory)
B memory access brackets [] required (default = relaxed syntax, [] allowed as extra)
f F Fake instructions: warning / disabled (default = enabled)
i Case insensitive instructions/directives (default = same case required)
† <emphasis>l L Keyword labels (registers, instructions, ...): warning / error (default = silent)</emphasis>
M Alias "m" and "M" for "(hl)" to cover 8080-like syntax: ADD A,M
s Use only "simple" whole-word substitutions, no sub-words (since v1.18.3)
w Warnings option: report warnings as errors
m *REMOVED* in v1.20.0, use -Wno-rdlow</synopsis>
† work in progress: options "l" and "L" are not implemented yet, following example is then
not working correctly either.
</para>
<para>
I.e. <code>--syntax=faBil</code> will modify parser to process source line
<programlisting>hl: Ld a,(hl),,de,hl</programlisting>
in a way to produce warnings about keyword "hl" being used for label, about fake instruction
being used (ld de,hl) and assemble <code>(hl)</code> as numeric expression, not memory access.
Warnings on fake instructions can be suppressed for particular line by adding any end-of-line
comment containing string "fake", i.e. "<code>ld de,hl ; fake DE=HL</code>" will assemble
without warning. The "F" option is identical to "--nofakes" and preferred.
</para>
<para>
The recommended setup for new projects is <code>--syntax=abfw</code> which makes syntax less relaxed,
so some typos and mistakes are easier to catch, for example:
<programlisting> OPT reset --syntax=abfw
label: dw 15
ld b,(label)
sub a,b</programlisting> will produce "error: Illegal instruction
(can't access memory): (label)" message for the <code>ld b,(label)</code> and the <code>sub a,b</code>
will produce only the <code>sub b</code> instruction (to give the <code>sub</code> multi-argument
with syntax option "a" the line would have to be <code>sub a,,b</code>).
</para>
<para>
The assembler will also read the environment variable <code>SJASMPLUSOPTS</code> (if available),
and process its content as part of command line options (before the actual options), so you
can pre-configure certain options in your environment, for example:
<programlisting>export SJASMPLUSOPTS="--zxnext=cspect --msg=war"
sjasmplus --lst --lstlab example.asm</programlisting>
will execute the assembling as if command line "<code>sjasmplus --zxnext=cspect --msg=war --lst --lstlab example.asm</code>"
was used. Known issue: parser of environment variable delimits each option on any white-space character, so
option containing space character will be incorrectly parsed (like "-Ifile-path with space" = fails and
there is no way to escape/quote the path in the SJASMPLUSOPTS variable to make it work).
</para>
</section>
<section id="s_id_warnings">
<title>Warnings with id</title>
<para>
Some warnings have own "id" - these can be switched off or suppressed for particular line.
The line suppression mechanism requires you to add end-of-line comment with "id-ok" string
somewhere in the comment (exception: for fake instructions and --syntax=f mode the word
"fake" is enough without -ok suffix) (the "ok" comment suppression mechanism from previous
versions of sjasmplus is removed since v1.19.0).
</para>
<para>
The id-warning is emitted together with its id in brackets:
<programlisting> ld a,(10-2) ; read memory address 8 - emits warning "rdlow"
ld a,(10-2) ; same instruction, but suppress warning: rdlow-ok
file.asm(1): warning[rdlow]: Reading memory at low address: 8</programlisting>
To list all warning-ids, their on/off state and short description of each use:
<programlisting><command line>$ sjasmplus --help=warnings</programlisting>
Most of the extra warnings are by default enabled, but to enable/disable all of them you can use (also in source with OPT directive):
<programlisting><command line>$ sjasmplus -Wall
<command line>$ sjasmplus -Wno-all</programlisting>
To disable particular warning globally you can use option <code>-Wno-<id></code>,
either on command line, or from source by using <code><link linkend="po_opt">OPT</link></code>:
<programlisting><command line>$ sjasmplus -Wno-out0
; in source code:
OPT -Wno-trdext -Wno-trdext3 ; disable "trdext" and "trdext3" warnings
SAVETRD "image.trd", "file.txt", 30000, 100
OPT -Wtrdext3 ; re-enable "trdext3" warning for following code
; ...</programlisting>
</para>
<para>
Warnings without id can't be suppressed and generally should happen only when the source
code has actual bug (in our opinion) and can be modified to fix the warning, or when you
are hitting limits of sjasmplus architecture and/or implementation.
</para>
<para>
If you believe you are hitting warning without id on correct code, which can be safely
ignored (the machine code produced is stable and as expected), open issue on github with
example source, so we can assign the warning new id (or explain why it is problematic :) ).
</para>
<para>
Warnings with id usually signal bug in the code (in common scenarios), but may be misleading
in more specialized cases - the decision is left to the author, whether to modify
the code to avoid the warning or suppress it and use the resulting machine code "as is".
</para>
</section>
<section id="s_source_format">
<title>Source file format</title>
<para>
Lines in the source file should have the following form:
<programlisting>Label Operator Operand Comment</programlisting>
<emphasis role="strong">Lines without label must start with whitespace.</emphasis>
All fields are optional.
End of line backslash continues source line (since 1.20.3, <ulink url="https://github.com/z00m128/sjasmplus/blob/master/tests/parsing/escape_eol.asm">limited support</ulink>, not recommended).
Operators and operands can be inlined with colon:
<programlisting> Operator Operand:Operator Operand:Operator Operand... Comment</programlisting>
Comments should start with '<code>;</code>' or '<code>//</code>'.
Comment blocks start with '<code>/*</code>' and end with '<code>*/</code>' (work in "nested" way,
i.e. comment block started inside comment block must be also ended, before main block ends).
<example>
<title></title>
<programlisting>; comment
// comment
ld /* comment */ a,80
/*
comment /* nested comment block */
*/
ld /*
but this won't be ld a,3!
*/ a,3</programlisting>
</example>
</para>
</section>
</chapter>
<chapter id="c_labels">
<title>Labels</title>
<section id="s_labels">
<title>Labels</title>
<para>Labels are case-sensitive and may be of any reasonable length,
that is: up to about 70 characters. Label definitions must start on
the beginning of a line, but don't have to be followed by a colon ':'.
Generally labels should start with a letter or a underscore ('_'), the
following characters may be chosen from letters, numbers and the
following special symbols: '_', '.', '!', '?', '#' and '@'. Note that
the '.' has special meaning, as it is used between module names, labels
and local labels. The following are all legal and distinct
labels:<programlisting>Kip
KIP
Kip@@
MAIN.loop?</programlisting>It is possible to use mnemonics, pseudo-ops and
register names as labels but it is not advised to do so (expression operator keyword used
as label will emit warning, and is also not advised). Also note that
the identifiers defined with the DEFINE pseudo-op use another name
space.</para>
<para>(since v1.18.0) Right after label (before the optional colon) you
can write extra "SMC offset" (Self Modify Code offset) in the form of plus
sign and single decimal digit. The defined label will become equal to current
address plus the SMC offset:
<programlisting> ; SMC-offset syntax is very strict, no spacing, single '+', single digit
answer+1: ld a,13 ; "answer" points second opcode byte
; this helps to keep the SMC-label together with the target instruction
ld hl,answer
ld (hl),42 ; fix immediate in `ld a,*` to correct answer
; compare with classic syntax:
classic equ $+1 : ld a,7 ; often even split to two lines</programlisting>
</para>
<para>(since v1.20.1) Smart SMC labels: you can write "plus asterisk" to let sjasmplus adjust
self-modify label by most likely offset for following instruction. This works only
for instructions with "obvious" target immediate value:
<programlisting> ; smart-SMC syntax is very strict, no spacing, single '+', single '*'
answer+*: ld a,13 ; "answer" points second opcode byte
; this helps to keep the SMC-label together with the target instruction
ld hl,answer
ld (hl),42 ; fix immediate in `ld a,*` to correct answer
; few more examples which byte the "smart SMC" will target in the opcode
jptarget+*: jp nz,12345 ; "jptarget" points at second opcode byte (word value 12345)
ixvalue+*: ld ix,12345 ; "ixvalue" points at third opcode byte (word value 12345)
nxtrval+*: nextreg $44,123 ; "nxtrval" points at fourth opcode byte (byte value 123)
; unsupported situations, will cause error
invalid1+*: inc (ix+123) ; IXY displacements are not considered (not significant enough)
invalid2+*: cpl : ld a,14 ; only first instruction after label is considered</programlisting>
</para>
</section>
<section id="s_local_labels">
<title>Local labels</title>
<para>When there is a <link linkend="po_module">module definition</link> all
labels (except those starting with a '@') are local to that module. To
use a label from outside the module use modulename.labelname, in this
example: 'vdp.Cls'. Labels starting with a '.' are also local to the
previous non-local label.</para>
<para>(since v1.18.0) If you start the label with an ! (exclamation mark), it will not
affect following local labels (same syntax as <ulink url="http://www.xl2s.tk/">sjasm</ulink>).</para>
<para>(since v1.18.3) Local label inside macro prefixed with @ (at sign) acts as regular local label,
otherwise (older behaviour) the local label is local to each macro's instance.</para>
<para><example>
<title>docs_examples/s_local_labels.asm</title>
<para><programlisting> MODULE main ; module "main"
Main: ; main.Main
CALL SetScreen ; SetScreen
CALL vdp.Cls ; main.vdp.Cls
.loop: ; main.Main.loop
LD A,(.event) ; main.Main.event
CALL ProcessEvent ; label not found: main.ProcessEvent
DJNZ .loop ; main.Main.loop
MODULE vdp ; module "main.vdp"
@SetScreen: ; SetScreen
.loop: ; main.vdp.SetScreen.loop
RET
Cls: ; main.vdp.Cls
!KeepClsForLocal: ; main.vdp.KeepClsForLocal (since v1.18.0)
.loop: DJNZ .loop ; main.vdp.Cls.loop
RET
ENDMODULE
Main.event DB 0 ; main.Main.event
ENDMODULE</programlisting></para>
</example></para>
<para><example>
<title>local labels inside macro</title>
<programlisting> macro test
.kip0 ; this is local to every instance of macro
@.kip1 ; syntax added in v1.18.3
endm
module main
hoi test ; produce labels: main.hoi, 0>kip0, main.hoi.kip1
endmodule</programlisting>
</example></para>
</section>
<section id="s_at_labels">
<title>@ Labels</title>
<para>Labels starting with a '@' are not touched by the label processing
and used 'as-is'. See 'SetScreen' in the previous example code. <example>
<title>docs_examples/s_at_labels.asm</title>
<para><programlisting> MODULE xxx
Label ; xxx.Label
.Local ; xxx.Label.Local
@Label ; Label
.Local ; xxx.Label.Local => duplicate label error
@Label2 ; Label2
.Local ; xxx.Label2.Local
@yyy.Local ; yyy.Local
yyy.Local ; xxx.yyy.Local</programlisting></para>
</example></para>
</section>
<section id="s_temp_labels">
<title>Temporary labels</title>
<para>To keep the number of used labels reasonable it is possible to use
numbers as labels. These labels can only be used as labels to jump to.
To jump to these labels, use the number followed by an 'F' for forward
branches or a 'B' for backward branches. Temporary labels should be defined
in the same order during every pass of assembling, but they can be used
within macro, or repeating blocks (old sjasmplus versions didn't allow usage within macro).</para>
<para>Since v1.19.0 there is alternative syntax using underscore before 'B' and 'F', this
alternative underscored suffix enables temporary labels also for regular instructions
(in all expressions, same way as other labels).</para>
<para><example>
<title>docs_examples/s_temp_labels.asm</title>
<para><programlisting> ADD A,E
JR NC,1F
INC D
1 LD E,A
2 LD B,4
LD A,(DE)
OUT (152),A
DJNZ 2B
MACRO zing
DUP 2
JR 1F
1 DJNZ 1B
EDUP
ENDM
.4 zing
; since v1.19.0
ld hl,1B ; *old* HL = binary 1, NOT temporary label
ld hl,1_B ; *new* HL = previous temporary label 1
ld hl,1_B*3 ; *new* works also in expressions</programlisting></para>
</example></para>
</section>
</chapter>
<chapter id="c_constants">
<title>Constants, expressions and other features</title>
<section id="s_numeric">
<title>Numeric constants</title>
<para>Numeric constants should always start with a digit or $, # or %.
The following formats are supported:</para>
<para><programlisting>12 decimal
12d decimal
0xc hexadecimal
$c hexadecimal
#c hexadecimal
0ch hexadecimal
0b1100 binary (v1.12.1)
%1100 binary
1100b binary
0q14 octal (v1.12.1)
14q octal
14o octal</programlisting></para>
<para>(v1.12.1) Optional single quotes(') may be inserted between the digits as a separator
(example: <computeroutput> ld a,%11'01'11'00 </computeroutput>).
They are ignored by the assembler.</para>
<para>(v1.20.1) decimal parts are now parsed and ignored (with optional warning), instead of
causing syntax error - this should make life easier when formatting values from Lua script.
It is also possible to fix all Lua scripts to produce only integer values, but if you prefer
to silently ignore the extra decimal part, you can.</para>
</section>
<section id="s_strings">
<title>Character and string constants</title>
<para>Character constants are characters surrounded by single quotes. It
is possible to use double quotes in some cases, but in general it is
better to use single quotes. String constants are characters surrounded
by double quotes. When double quotes are used, the following escape
sequences are recognized:</para>
<para><programlisting>\\ 92
\? 63
\' 39
\" 34
\0 0 ; since v1.11
\A 7
\B 8
\D 127
\E 27
\F 12
\N 10
\R 13
\T 9
\V 11</programlisting><para>Inside single quotes two quotes after each other are
parsed as the apostrophe itself (since v1.11).</para>
<para>Adding Z or C after quotes/apostrophes will make string zero-terminated or set top bit of last character (since v1.20.3).</para><example>
<title></title>
<para><programlisting> BYTE "stringconstant\n" ; escape sequence assembles to newline
BYTE 'stringconstant\n' ; \n assembles literally as two bytes: '\', 'n'
LD HL,'hl' ; hl = 0x686C = 'l', 'h'
LD HL,"hl" ; hl = 0x686C = 'l', 'h'
LD A,"7" ; not recommended (but works)
LD A,'8' ; recommended
LD A,'\E' ; warning + truncating value to 'E' (0x45)
LD A,'"' ; A = 0x22
LD A,"'" ; A = 0x27
LD A,'''' ; A = 0x27 ; since v1.11
BYTE "AB"Z, "CD"C, 'E'Z, 'F'C ; hex: 41 42 00 43 C4 45 00 C6</programlisting></para>
</example></para>
</section>
<section id="s_expressions">
<title>Expressions</title>
<para>Expressions are evaluated in signed 32 bits in this version of SjASMPlus (unless explicitly
specified as unsigned, like ">>>" operator), so intermediate values have range -2147483648
to +2147483647. True for boolean results is equal to value -1, false is equal to 0 (so
result of compare or logical operators can be used as all-bit-mask further). </para>
<para>'$' represents the current program counter. '$$' represents the
current page in the current slot in the <link
linkend="s_realdevice">real device emulation mode</link>, '$$label' evaluates to number of page
where the "label" was defined (only regular labels have meaningful value, labels defined
under DISP mode may return the page specified in DISP itself, EQU/DEFL/... will produce mostly
irrelevant values). '$$$' and '$$$$' can be used inside DISP block to retrieve the "physical"
memory address and page (where the displaced machine code is written to). '{address}' can be used
to read WORD from virtual device memory (correct value is read only in last pass of assembling,
in early passes the zero value is always returned), '{b address}' reads only BYTE.</para>
<para>It is possible to use parenthesis '(' and ')' to override the
precedence of the operators. The following operators may be used in
expressions:</para>
<para><programlisting>norel norel L <indexterm id="op_norel"><primary>norel</primary></indexterm>Label/symbol L will be treated as non-relocatable
exist exist L <indexterm id="op_exist"><primary>exist</primary></indexterm>is label/symbol L defined in source (even when not used) (since v1.18.2)
! !x <indexterm id="op_log_not"><primary>!</primary></indexterm>logical not
~ ~x <indexterm id="op_cpl"><primary>~</primary></indexterm>complement
+ +x does "nothing", can be used to make "+(...)" parse as value (not as memory)
- -x minus
low low x <indexterm id="op_low"><primary>low</primary></indexterm>low 8 bits of 16 bit value or lower part of register pair
high high x <indexterm id="op_high"><primary>high</primary></indexterm>high 8 bits of 16 bit value or higher part of register pair
not not x <indexterm id="op_log_not2"><primary>not</primary></indexterm>logical not
abs abs x <indexterm id="op_abs"><primary>abs</primary></indexterm>absolute value (since v1.18.0)
* x*y <indexterm id="op_mul"><primary>*</primary></indexterm>multiplication
/ x/y <indexterm id="op_div"><primary>/</primary></indexterm>division
% x%y <indexterm id="op_mod"><primary>%</primary></indexterm>modulo
mod x mod y <indexterm id="op_mod2"><primary>mod</primary></indexterm>modulo
+ x+y <indexterm id="op_add"><primary>+</primary></indexterm>addition
- x-y <indexterm id="op_sub"><primary>-</primary></indexterm>subtraction
<< x<<y <indexterm id="op_sla"><primary><<</primary></indexterm>shift left
>> x>>y <indexterm id="op_sra"><primary>>></primary></indexterm>shift right signed
>>> x>>>y <indexterm id="op_srl"><primary>>>></primary></indexterm>shift right unsigned
shl x shl y <indexterm id="op_shl"><primary>shl</primary></indexterm>shift left
shr x shr y <indexterm id="op_shr"><primary>shr</primary></indexterm>shift right signed
<? x<?y <indexterm id="op_min"><primary><?</primary></indexterm>minimum
>? x>?y <indexterm id="op_max"><primary>>?</primary></indexterm>maximum
< x<y <indexterm id="op_lt"><primary><</primary></indexterm>less than
> x>y <indexterm id="op_gt"><primary>></primary></indexterm>greater than
<= x<=y <indexterm id="op_lte"><primary><=</primary></indexterm>equal or less than
>= x>=y <indexterm id="op_gte"><primary>>=</primary></indexterm>equal or greater than
= x=y <indexterm id="op_eq"><primary>=</primary></indexterm>equal
== x==y <indexterm id="op_eq2"><primary>==</primary></indexterm>equal
!= x!=y <indexterm id="op_neq"><primary>!=</primary></indexterm>not equal
& x&y <indexterm id="op_bit_and"><primary>&</primary></indexterm>bitwise and
and x and y <indexterm id="op_bit_and2"><primary>and</primary></indexterm>bitwise and
^ x^y <indexterm id="op_bit_xor"><primary>^</primary></indexterm>bitwise xor
xor x xor y <indexterm id="op_bit_xor2"><primary>xor</primary></indexterm>bitwise xor
| x|y <indexterm id="op_bit_or"><primary>|</primary></indexterm>bitwise or
or x or y <indexterm id="op_bit_or2"><primary>or</primary></indexterm>bitwise or
&& x&&y <indexterm id="op_logic_and"><primary>&&</primary></indexterm>logical and
|| x||y <indexterm id="op_logic_or"><primary>||</primary></indexterm>logical or
$ $ <indexterm id="op_dollar"><primary>$</primary></indexterm>current program counter
$$ $$ <indexterm id="op_dollar2"><primary>$$</primary></indexterm>current page at program counter (in virtual device mode)
$$$ $$$ <indexterm id="op_dollar3"><primary>$$$</primary></indexterm>"physical" program counter (inside DISP block)
$$$$ $$$$ <indexterm id="op_dollar4"><primary>$$$$</primary></indexterm>"physical" memory page (inside DISP block in virtual device mode)
label label value of label (aka symbol), usually memory address
$$lab $$lab <indexterm id="op_label_page"><primary>$$label</primary></indexterm>page of "lab" label (in virtual device mode)
{} {x} <indexterm id="op_read_word"><primary>{..}</primary></indexterm>reads WORD from address x (in virtual device mode, in last pass)
{b} {b x} <indexterm id="op_read_byte"><primary>{b ..}</primary></indexterm>reads BYTE from address x (in virtual device mode, in last pass)
</programlisting></para>
</section>
<section id="s_asm_lang">
<title>Assembly language</title>
<para>This version only accepts Z80 mnemonics. There are some additions
to what I think is standard Z80: <itemizedlist>
<listitem>
<para>'[' and ']' can be used instead of '(' and ')' for
indirection. So <code>LD A,[HL]</code> is the same as <code>LD A,(HL)</code> (does not
apply to IN/OUT ports, those must use '(...)' form)</para>
</listitem>
<listitem>
<para><code>IN F,(C)</code> and <code>OUT (C),0</code> and <code>SLL/SLI</code> can be used
(warning: on some CPU versions of Z80 the OUT (C),0 is working as OUT (C),255).</para>
</listitem>
<listitem>
<para>IXL (or LX, XL), IYL (or LY, YL), IXH (or HX, XH) and IYH
(or HY, YH) registers are supported.</para>
</listitem>
<listitem>
<para>Can write code throught colon: ORG 100h:LD A,10:LD B,10:SUB
B:RET:IFDEF AA:.....</para>
</listitem>
<listitem>
<para>JP HL, JP IX and JP IY may be used instead of JP (HL),
etc.</para>
</listitem>
<listitem>
<para>EX AF,AF or EX AF or EXA may be used instead of EX
AF,AF'.</para>
</listitem>
<listitem>
<para>R800's MULUB and MULUW are recognised (but won't work on
Z80, of course:)</para>
</listitem>
<listitem>
<para>Z80N, i8080 and LR35902 (SM83) modes use the identical Z80 sjasmplus syntax (!), for the
correct (and incorrect) syntax examples of extended opcodes, please check the test files:
Z80N <ulink url="https://github.com/z00m128/sjasmplus/blob/master/tests/z80n/op_zx_spectrum_next_2_00_26.asm">test 1</ulink>