-
Notifications
You must be signed in to change notification settings - Fork 4
/
doc.inl
990 lines (990 loc) · 36.4 KB
/
doc.inl
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
static char *documentation =
".Overview of zmac\n"
"zmac is a Z-80 macro cross-assembler. It has all the features you'd\n"
"expect. It assembles the specified input file (with a '.z' extension\n"
"if there is no pre-existing extension and the file as given doesn't\n"
"exist) and produces program output in many different formats@format.\n"
"It also produces a nicely-formatted\n"
"listing of the machine code and cycle counts alongside the source\n"
"in a \".lst\" file.\n"
"\n"
"To reduce clutter and command line option usage, by default all zmac output is put\n"
"into an (auto-created) _zout_ subdirectory. For _file.z_ the listing\n"
"will be in _zout/file.lst_, the TRS-80 executable format in _zout/file.cmd_\n"
"and so on. For more friendly usage in make files and integrated development\n"
"environments the _-o_, _--oo_, _--xo_ and _--xd_ options may be used to select\n"
"sepcific output file formats and where they are written.\n"
"\n"
"Undocumented@undoc Z-80 instructions are supported as well as 8080 code.\n"
"\n"
"zmac strives to be a powerful assembler with expressions familiar to C\n"
"programmers while providing good backward compatibility with original\n"
"assemblers such as Edtasm, MRAS and Macro-80.\n"
"---\n"
".Usage\n"
"zmac\n"
"[ --help ]\n"
"[ --version ]\n"
"[ --dep ]\n"
"[ --mras ]\n"
"[ --od dir ]\n"
"[ --oo sfx1,sfx2 ]\n"
"[ --xo sfx1,sfx2 ]\n"
"[ --rel ]\n"
"[ --rel7 ]\n"
"[ --doc ]\n"
"[ --zmac ]\n"
"[ -8bcefghijJlLmnopstz ]\n"
"[ filename[.z] ]\n"
"\n"
".Options\n"
"\n"
" --help\n"
" Display a list of options and a terse description of what the options do.\n"
" \n"
" --version\n"
" Print zmac version name.\n"
" \n"
" --mras\n"
" MRAS compatibility mode. Any _?_ in a label will be expanded to the\n"
" current module identifier as set by _*mod_. Operator precedence@mrasord\n"
" and results are changed.\n"
" \n"
" --od dir\n"
" Place output files in _dir_ instead of the default \"zout\" subdirectory.\n"
" Creates _dir_ if necessary.\n"
" \n"
" --oo hex,cmd\n"
" Output only the the file types by suffix. Multiple --oo arguments may\n"
" be used. \"--oo lst,cas\" is equivalent to \"--oo lst --oo cas\".\n"
" See \"Output Formats\" for a list of output types by suffix@format.\n"
" \n"
" --xo tap,wav\n"
" Do not output the file type types listed by suffix.\n"
" \n"
" --rel\n"
" Output \".rel\" (relocatable object file) format only. Exported symbols are\n"
" truncated to length 6.\n"
" \n"
" --rel7\n"
" Output \".rel\" (relocatable object file) format only. Exported symbols are\n"
" truncated to length 7.\n"
" \n"
" --zmac\n"
" zmac compatibility mode. _defl_ labels are undefined after each pass.\n"
" Quotes and double quotes are stripped from macro arguments before expansion.\n"
" _$_ is ignored in identifiers allowing _foo$bar_ to construct identifiers\n"
" in macro expansions. Use _`_ (backquote) instead in normal mode. Labels\n"
" starting with _\".\"_ are temporary and are reset whenever a non-temporary\n"
" label is defined (thus they may be reused). Labels starting with _\"__\"_\n"
" are local to their file thus avoid multiple definition when brought in\n"
" with _include_.\n"
" \n"
" --dep\n"
" Print all files read by _include_, _incbin_ and _import_.\n"
" \n"
" --doc\n"
" Print this documentation in HTML format to standard output.\n"
" \n"
" -Pk=number\n"
" Set _@@k_ to the given numeric value before assembly. Up to 10 parameters\n"
" can be set from 0 though 9. _-Pk_ is shorthand for _-Pk=-1_.\n"
" For example, _P4=$123_ effectively puts _@@4 equ $123_ at the top of the\n"
" first file.\n"
" \n"
" -8\n"
" Accept 8080 mnemonics preferentially. Equivalent to _.8080_ pseudo-op.\n"
" \n"
" -b\n"
" Don't generate any machine code output at all.\n"
" \n"
" -c\n"
" Make the listing continuous, i.e., don't generate any page breaks or\n"
" page headers. Can make things less confusing if you're going to\n"
" consult the listing online rather than printing it. This is the default.\n"
" \n"
" -e\n"
" Omit the \"error report\" section in the listing.\n"
" \n"
" -f\n"
" List instructions not assembled due to \"_if_\" expressions being\n"
" false. (Normally these are not shown in the listing.)\n"
" \n"
" -g\n"
" List only the first line of equivalent hex for a source line.\n"
" \n"
" -h\n"
" Display a list of options and a terse description of what the options do.\n"
" (same as --help)\n"
" \n"
" -i\n"
" Don't list files included with _include_, _read_ or _import_.\n"
" \n"
" -I dir\n"
" Add _dir_ to the end of the include file search path.\n"
" \n"
" -j\n"
" Promote relative jumps and _DJNZ_ to absolute equivalents as needed.\n"
" \n"
" -J\n"
" Error if an absolute jump could be replaced with a relative jump.\n"
" \n"
" -l\n"
" List to standard output.\n"
" \n"
" -L\n"
" Generate listing no matter what. Overrides any conflicting options.\n"
" \n"
" -m\n"
" List macro expansions.\n"
" \n"
" -n\n"
" Omit line numbers from listing.\n"
" \n"
" -o filename.cmd\n"
" Output only the named file. Multiple \"-o\" options can be used to name a\n"
" set of different files.\n"
" \n"
" -p\n"
" Use a few linefeeds for page break in listing rather than ^L.\n"
" \n"
" -P\n"
" Output listing for a printer with headers, multiple symbols per column, etc.\n"
" \n"
" -s\n"
" Omit the symbol table from the listing.\n"
" \n"
" -t\n"
" Only output number of errors instead list of each one.\n"
" \n"
" -z\n"
" Accept Z-80 mnemonics preferentially. Equivalent to _.z80_ pseudo-op.\n"
"---\n"
".Input Format\n"
"\n"
"zmac uses the standard Zilog mnemonics, and the pseudo-ops are also\n"
"largely as you'd expect.\n"
"\n"
"A \"_._\" may optionally preceeed any psuedo-op.\n"
"For example, \"_.org_\" and \"_org_\" are treated as equivalent.\n"
"\n"
"Input can be upper or lowercase.\n"
"\n"
"Comments start with _;_ and carry on to the end of the line.\n"
"\n"
"Number constants can take a trailing h or a leading $ or 0x for hex,\n"
"a trailing b for binary, a trailing o or q for octal, or a trailing\n"
"d for decimal.\n"
"\n"
"_'LH'_ (any length 2 string) can be treated as a number whose value\n"
"is _'H'_ * 256 + _'L'_.\n"
"\n"
"Labels are declared with _label:_ or just _label_ - indentation is unimportant.\n"
"Labels can be up to 40 chars long. They can start with and contain \n"
"letters, digits, _$_, _._, _?_, _@_ and __. Ambiguous identifiers like\n"
"_$FCB_ will be treated as hex constants unless defined as a label. Labels\n"
"declared with two colons (_label::_) make the label public.\n"
"\n"
"Single quotes are ignored at the end of identifiers allowing non-binding\n"
"notation@prime indicating alternate register use during heavy applications\n"
"of _exx_ and _ex_.\n"
"\n"
"Here is how other things work. Numbers are used as examples, but a full\n"
"expression@expr can be used in their place.\n"
"\n"
"..Data\n"
"\n"
"_defb 42_\n"
"|A byte. _ascii_, _byte_, _db_, _defm_ and _text_ are synonyms.\n"
"\n"
"_defb 'foobar'_\n"
"|An ASCII character string (not NUL-terminated).\n"
"|Double quotes can also be used.\n"
"\n"
"_defb 'Who needs anything more than CP/M?',13,10,'$'_\n"
"|Strings and bytes can mix together.\n"
"\n"
"_defw 2112_\n"
"\n"
"_defw $123,0x456_\n"
"|A word (16 bits). _word_ and _dw_ are synonyms.\n"
"\n"
"_defd $12345678_\n"
"|A double word (32 bits). _dword_ is a synonym.\n"
"\n"
"_defs 500_\n"
"|Skip output ahead 500 bytes. This will insert 500 zeros in the \".ams\"\n"
"|and \".cim\" output files or if inside a \".phase\" section.\n"
"|_block_, _ds_ and _rmem_ are synonyms.\n"
"\n"
"_dc 'string'_\n"
"|Like _ascii_ but accepts only a single string and the high bit of the\n"
"|last character will be set. _bytes_ is a synonym.\n"
"\n"
"_dc count,value_\n"
"|Repeat the byte _value_ a total of _count_ times. Similar to _defs_\n"
"|except that memory is always filled with _value_.\n"
"\n"
"_incbin file_\n"
"|Inserts the raw contents of the file into the assembly. Simpler for\n"
"|large amounts of data.\n"
"\n"
"..Symbols\n"
"\n"
"_label equ 100_\n"
"|Define a symbol to have a fixed value. The symbol can be used before it\n"
"|is defined. A symbol defined with _equ_ or as a label can be defined only\n"
"|once, except that a symbol defined with _equ_ may be redefined to the\n"
"|same value.\n"
"\n"
"_varname defl 200_\n"
"|Define a symbol to have a changeable value. The symbol cannot be used\n"
"|before it is defined, and it can be redefined to a different value later\n"
"|with another _defl_. _aset_, _set_ and _=_ are synonyms (despite _set_\n"
"|also being a Z-80 mnemonic).\n"
"\n"
"_varname OP = expression_\n"
"|Shorthand for _varname defl varname OP expression_. Allows for C-like\n"
"|handling of variable such as _var += 5_. _OP_ can be _+_, _-_, _*_, _/_,\n"
"|_%_, _&_, _|_, _^_, _<<_, _>>_, _&&_ or _||_.\n"
"\n"
"_varname++_\n"
"|Shorthand for _varname defl varname + 1_\n"
"\n"
"_varname--_\n"
"|Shorthand for _varname defl varname - 1_\n"
"\n"
"_min_\n"
"\n"
"_max_\n"
"|Same as _defl_ except that the symbol is defined as the\n"
"|smaller or bigger of two comma-separated expressions.\n"
"\n"
"_*mod_\n"
"|Increment the internal module name string. The first time this results\n"
"|in \"a\". Then \"b\", \"c\", ... \"z\". Then \"aa\", \"ab\", \"ac\", etc. all the way\n"
"|up to \"zzzz\". The module name string is used in _--mras_ mode where \"?\" in\n"
"|label names is replaced with the current module name.\n"
"\n"
"_extern lab1,lab2,..._\n"
"|The listed labels are defined in an external module for later linking.\n"
"|No effect unless zmac is producing \".rel\" output.\n"
"|_ext_ and _extrn_ are synonyms.\n"
"\n"
"_public lab1,lab2,..._\n"
"|The given labels will be visible to external modules when linking.\n"
"|No effect unless zmac is producing \".rel\" output.\n"
"|_global_ and _entry_ are synonyms.\n"
"\n"
"_label ++_\n"
"|Equivalent to _label defl label + 1_.\n"
"\n"
"_label --_\n"
"|Equivalent to _label defl label - 1_.\n"
"\n"
"_label += 10_\n"
"\n"
"_label -= 10_\n"
"\n"
"|Equivalent to _label defl label + 10_ and _label defl label - 10_ respectively.\n"
"|Also works for _*=_, _/=_, _%=_, _|=_, _&=_, _^=_, _<<=_ and _>>=_.\n"
"\n"
"..Location Control\n"
"\n"
"_org 9000h_\n"
"|Set the address to assemble to 0x9000.\n"
"\n"
"_phase address_\n"
"|Continue to produce code and data for loading at the current address\n"
"|but assemble instructions and define labels as if they originated at\n"
"|the given address. Useful when producing code that will be copied to\n"
"|a different location before being executed (e.g., an overlay).\n"
"\n"
"_dephase_\n"
"|End _phase_ mode assembly.\n"
"\n"
"_aseg_\n"
"_cseg_\n"
"_dseg_\n"
"|Switch to the absolute, code and data segments respectively.\n"
"|No effect unless zmac is producing \".rel\" output.\n"
"\n"
"_common /name/_\n"
"|Set the address to the start of the selected common block. The blank\n"
"|common block will be selected if name is empty or all blanks or\n"
"|omitted entirely.\n"
"|No effect unless zmac is producing \".rel\" output.\n"
"\n"
"..Input Control\n"
"\n"
"_end_\n"
"|Ends the input. Any lines after an _end_ are silently ignored.\n"
"|If an arg is given, it declares the entry address for the program.\n"
"|This has no effect in \".cim\" output. In \".hex\" output\n"
"|it generates an S-record directing 0 bytes of data to be loaded\n"
"|at the given address. It is required for \".500.cas\", \".1000.cas\"\n"
"|and \".1500.cas\" output.\n"
"\n"
"_if_ ... [ _else_ ... ] _endif_\n"
"|For conditional assembly. If you do _if foo_ and _foo_ evaluates to\n"
"|zero, all the lines up until the next corresponding _else_ or _endif_\n"
"|are completely ignored. Conversely, if _foo_ evaluates to non-zero, any\n"
"|lines from a corresponding _else_ to the _endif_ are ignored. Ifs can\n"
"|be nested. _cond_/_endc_ are synonyms for _if_/_endif_.\n"
"\n"
"_ifdef symbol_\n"
"|Like _if_, but tests if _symbol_ has been defined. Declaring a symbol\n"
"|as external counts as it being defined.\n"
"\n"
"_ifndef symbol_\n"
"|Like _if_, but tests if _symbol_ has not yet been defined.\n"
"\n"
"_import file_\n"
"|Like _include_ but will only bring in the file once. File tracking is done\n"
"|using only the file name so, for example, an _import file_ will stop\n"
"|both _import ./file_ and _import dir/file_ even if they actually refer to\n"
"|different files.\n"
"\n"
"_include file_\n"
"|Include a file. Like C's (well, cpp's) #include and follows the same\n"
"|include path search rules, but the filename arg\n"
"|lacks the angle brackets or quotes (though single or double quotes may be used).\n"
"|_read_ is a synonym. _*include file_ also works if started in the first\n"
"|column. In _--mras_ mode _\".asm\"_ will be added if _file_ has\n"
"|no suffix.\n"
"\n"
"_maclib file_\n"
"|Like _include_ but adds _.lib_ to the file name so includes _file.lib_.\n"
"\n"
"_comment X_\n"
"|Suspend assembly until the next occurence of character _X_ on a line.\n"
"|The rest of the line will be ignored. A multi-line comment.\n"
"\n"
"_assert expr_\n"
"|Stop assembly if _expr_ is non-zero.\n"
"\n"
"..Cycle Counting\n"
"\n"
"_sett expr_\n"
"|Set the current T-state count to _expr_. _tstate_ is a synonym.\n"
"\n"
"_setocf expr_\n"
"|Set the current opcode fetch count to _expr_.\n"
"\n"
"..Code Generation\n"
"\n"
"_8080_\n"
"|Make cycle counting operators return 8080 cycle counts and\n"
"|interpret any ambiguous assembly statements as Intel 8080 mnemonics.\n"
"|_CP_ will be interpreted as \"call on positive\" and _JP_ as \"jump on positive\".\n"
"\n"
"_z80_\n"
"|Make cycle counting operators return Z-80 cycle counts and\n"
"|interpret any ambiguous assembly statements as Zilog Z-80 mnemonics.\n"
"|_CP_ will be interpreted as \"compare accumulator\" and _JP_ as \"jump unconditionally\".\n"
"\n"
"_jperror enable_\n"
"|If _enable_ is non-zero, turn on errors when _JR_ instructions could be used\n"
"|instead of _JP_, off otherwise. Used to check existing code for situations\n"
"|where shorter code could be generated. Same as _-J_ option.\n"
"|No effect if in 8080 mode.\n"
"\n"
"_jrpromote enable_\n"
"|If _enable_ is non-zero, _JR_ and _DJNZ_ instructions will be promoted to\n"
"|equivalent _JP_ and _DEC##B_, _JP##NZ_ instructions if the relative branch\n"
"|offset is out of range. If _enable_ is zero, promotion is disabled.\n"
"|Same as the _-j_ option.\n"
"|No effect if in 8080 mode.\n"
"\n"
"..Undocumented Instructions\\undoc\n"
"\n"
"Most Z-80 chips support a number of undocumented instructions that were part of\n"
"the original design but not made an offical part of the Zilog specification.\n"
"These instructions may not be supported by all Z-80 chips, especially\n"
"licensed variants, but are fairly widely available nonetheless.\n"
"\n"
"_sl1 r_\n"
"|Same as _sla r_ but shifts a 1 into the lower bit of _r_ rather than a 0.\n"
"\n"
"_in (c)_\n"
"|Inputs a byte from port _c_ but does not store the value. Flags are still\n"
"|set as with the normal _in r,(c)_ instruction.\n"
"\n"
"_out (c),0_\n"
"|Outputs a zero to port _c_.\n"
"\n"
"_bit/set/res n,(ix+d),r_\n"
"\n"
"_rlc/rrc/rl/rr/sla/sl1/sra/srl (iy+d),r_\n"
"|Same as the corresponding operation on just _(ix+d)_ or _(iy+d)_ but with\n"
"|the result being stored both into _(ix+d)_ and register _r_. Except for _bit_\n"
"|which has no effect on _r_. zmac supports the syntax to allow those\n"
"|instruction patterns to be generated.\n"
"\n"
"The upper and lower bytes of the _ix_ and _iy_ can be used in a number of\n"
"instructions much in the same way as _d_ and _e_ correspond to the upper and\n"
"lower bytes of _de_. zmac names these _ixh_, _ixl_, _iyh_ and _iyl_ and\n"
"are referred to generically as _ixylh_ here.\n"
"\n"
"_inc/dec/add/adc/sub/sbc/and/xor/or/cp ixylh_\n"
"|Arithmetic or logical operation on _ix_ or _iy_ high or low byte.\n"
"\n"
"_ld a/b/c/d/e,ixylh_\n"
"|Load register with _ix_ or _iy_ high or low byte.\n"
"\n"
"_ld ixylh,a/b/c/d/e_\n"
"|Load _ix_ or _iy_ high or low byte with register.\n"
"\n"
"_pfix_\n"
"\n"
"_pfiy_\n"
"|Output $DD and $FD prefix bytes. The Z-80 allows multiple prefix bytes\n"
"|for IX and IY instructions. This allows you to specify them abstractly.\n"
"|There is little purpose except for delaying an interrupt or confusing\n"
"|disassemblers.\n"
"\n"
"..Miscellaneous\n"
"\n"
"_pragma str ..._\n"
"|Like C's #pragma, a generic hook for special purpose operations. Only two\n"
"|are currently defined.\n"
"\n"
"|_pragma bds rest-of-line_ to\n"
"|output _rest-of-line_ to the _.bds_ output file.\n"
"\n"
"|_pragma mds rest-of-line_ to\n"
"|output _rest-of-line_ to the _.mds_ output file.\n"
"\n"
"|The _.bds_ output format supports setting initial values for Z-80 registers\n"
"|and I/O ports so _pragma_ gives you access to that.\n"
"\n"
"|The _.mds_ output format is a MAME debug script thus additional initial\n"
"|debugging commands may be output. Of particular use on the TRS-80 Model II\n"
"|is _pragma mds ib@$ff=1_ which maps page 1 of RAM into $8000 .. $FFFF\n"
"|and thus allows programs to load into that area.\n"
"\n"
"_name str_\n"
"|Set the name of the output module to _str_. For compatibility reasons\n"
"|_str_ may be parenthesized (e.g., \"_name ('foo')_\"). Not all output\n"
"|formats support an internal name and many have severe length limits.\n"
"\n"
"_rsym_ and _wsym_\n"
"|Read/write a symbol file. These simply load/save the currently defined\n"
"|symbols from/to the file specified (in a non-portable format). _rsym_\n"
"|takes place at the point it is encountered in the file (on the first\n"
"|pass); _wsym_ is delayed until assembly has finished.\n"
"\n"
"..Listing Pseudo-ops\n"
"\n"
"There are several pseudo-ops for controlling the listing. None of\n"
"these ops appear in the listing themselves:\n"
"\n"
"_eject_\n"
"|Start a new listing page.\n"
"\n"
"_nolist_\n"
"|Do nothing. This can be used to have a comment in the source but not\n"
"|the listing, I suppose.\n"
"\n"
"_elist_, _flist_, _glist_, _mlist_\n"
"|These have the same effect as the similarly-named command-line\n"
"|options, though possibly with the sense reversed depending on the\n"
"|default. Use an arg >0 (or no arg) to enable, and an arg <0 to\n"
"|disable.\n"
"\n"
"_list arg_\n"
"|Turns output to listing file (.list) off if _arg_ < 0 or on if _arg_ > 0.\n"
"|If no _arg_ supplied then listing is enabled.\n"
"|Use this to avoid listing certain parts of the source.\n"
"|In _--mras_ mode _arg_ must be either _on_ or _off_ and\n"
"|_*list_ can be used if started in the first column.\n"
"\n"
"_title_\n"
"|Set title (used in listing and symbol file).\n"
"\n"
"_space arg_\n"
"|Output arg blank lines in the listing, or one line if no arg is given.\n"
"\n"
"---\n"
"\n"
".Expressions\\expr\n"
"\n"
"Expressions feature a full set of C operators with the same precedence\n"
"rules and some common assembler extensions and names.\n"
"Here is the complete list of operators, highest-precedence first.\n"
"Operators separated only by a space are synonyms; for example, _~_\n"
"is the same as _not_.\n"
"\n"
"_!_ (logical), _~ not_ (bitwise), _+_ (unary), _-_ (unary), _low_, _high_, _t_, _tilo_, _tihi_, _ocf_\n"
"\n"
"_*_, _/_, _% mod_\n"
"\n"
"_+_, _-_\n"
"\n"
"_<< shl_, _>> shr_\n"
"\n"
"_< lt_, _> gt_, _<= le_, _>= ge_\n"
"\n"
"_== = eq_, _!= <> ne_\n"
"\n"
"_& and_ (bitwise)\n"
"\n"
"_^ xor_ (bitwise)\n"
"\n"
"_| or_ (bitwise)\n"
"\n"
"_&&_\n"
"\n"
"_||_\n"
"\n"
"_? :_ (ternary choice operator)\n"
"\n"
"Expressions\\mrasord change significantly in _--mras_ mode:\n"
"|Evaluation is strictly left to right. Except for _and_, _or_,\n"
"|_xor_ and _=_. This doesn't break compatibility as original MRAS\n"
"|source code only allows _.and._, _.or._ and _.xor._ but the precedence\n"
"|difference may surprise if code is added.\n"
"\n"
"|_!_ is bitwise OR instead of logical not.\n"
"\n"
"|_<_ is left shift (or right shift when shift amount is negative)\n"
"\n"
"|MRAS operators (_.and._ _.eq._ _.ge._ _.gt._ _.high._ _.le._ _.low._\n"
"|_.lt._ _.mod._ _.ne._ _.not._ _.or._ _.shl._ _.shr._ _.xor._)\n"
"|are recognized even if apparently in identifers. (e.g., _a.or.b_ is\n"
"|seen as _a .or. _b).\n"
"\n"
"|Logical operators return -1 for true and 0 for false. Normally\n"
"|zmac, like C, uses 1 for true.\n"
"\n"
"You can use normal parentheses or square brackets to override\n"
"the precedence rules. Square brackets can be used where parentheses would\n"
"conflict with Z-80 mnemonic syntax, but this is not necessary in any\n"
"practical case.\n"
"\n"
"The _?_ may need spaces around it to distinguish it from a label that\n"
"has _?_ in it.\n"
"\n"
"The unary operators not familiar to C programmers:\n"
"\n"
" low expr\n"
" Returns low 8 bits of _expr_\n"
" \n"
" high expr\n"
" Returns high 8 bits of _expr_\n"
" \n"
" t expr\n"
" Current count of T-states up to memory location _expr_\n"
" \n"
" tilo expr\n"
" Low count of T-states used by instruction at memory location _expr_\n"
" \n"
" tihi expr\n"
" High count of T-states used by instruction at memory location _expr_\n"
" \n"
" ocf expr\n"
" Current count of opcode fetches up to memory location _expr_\n"
"---\n"
".Macros\n"
"The following defines a macro named m with zero or more formal parameters\n"
"_p1_, _p2_, ..., _pn_, zero or more local symbols _?s1_, _?s2_, ..., _?sm_,\n"
"and body _b1_, _b2_, ...:\n"
"\n"
" _m macro p1, p2, ..., pn, ?s1, ?s2, ..., ?sm_\n"
" \n"
" _####b1_\n"
" \n"
" _####b2_\n"
" \n"
" _####..._\n"
" \n"
" _####endm_\n"
"\n"
"The macro is called by writing:\n"
"|_m v1, v2, ..., vn_\n"
"\n"
"A macro call expands to the text of the macro's body, with each \n"
"occurrence of a formal parameter _pk_ replaced by the corresponding \n"
"value _vk_, and with each local symbol _?sk_ replaced by a new, unique \n"
"symbol invented for this call. Invented symbols begin with _?_,\n"
"so you should avoid using such symbols elsewhere in your program.\n"
"\n"
"zmac currently does not check that you have provided the right number \n"
"of parameters when calling a macro. If you provide too few, unmatched \n"
"formals are replaced with the empty string. If you provide too \n"
"many, the additional values begin to replace local symbols as if \n"
"they were ordinary parameters. (This could be considered a feature.) \n"
"After the local symbols are all replaced, additional parameters \n"
"are silently ignored.\n"
"\n"
"For compatibility with Macro-80, the first line of a macro definition can\n"
"list other labels that will be treated locally:\n"
"\n"
"|_####local lab1,lab2,..._\n"
"\n"
"Each time the macro is expanded the local labels are replaced with unique\n"
"names thus avoiding multiple definition problems.\n"
"\n"
"For compatability with MRAS, macro arguments may be preceeded by _#_\n"
"in their definition and use.\n"
"\n"
"Any _`_ (backquote) in a macro is ignored thus allowing a macro to\n"
"construct identifiers. For example:\n"
"\n"
" _move macro dir_\n"
" \n"
" _######ld`dir`r_\n"
" \n"
" _######endm_\n"
"\n"
"Invoking _move i_ will construct a _ldir_ block move instruction.\n"
"\n"
"For compatibility, _&_ can also be used as in MAC to concatenate\n"
"macro parameters. This conflicts with zmac's bitwise and operator but\n"
"you can use the _and_ synonym in macros to avoid the conflict.\n"
"\n"
"In _--mras_ mode arguments will be expanded even if they are inside other\n"
"identifiers. The _move_ could be written:\n"
"\n"
" _move macro dir_\n"
" \n"
" _######lddirr_\n"
" \n"
" _######endm_\n"
"\n"
"Macro definitions can contain macro definitions which will be defined\n"
"when the outer macro is first exapnded. Macros can be redefined as\n"
"well.\n"
"\n"
"Macro expansion continues to the _endm_ directive but can be stopped\n"
"prematurely by the _exitm_ directive. Typically the _exitm_ is inside\n"
"some conditional part of the macro.\n"
"\n"
"Parameters passed to a macro can be empty and are tested with the _nul_\n"
"operator:\n"
"\n"
" _if nul &par_\n"
" \n"
" _..._\n"
" \n"
" _endif_\n"
"\n"
"Macro parameters can contain commas if grouped inside _<_ and _>_.\n"
"Or a comma can be escaped with _^_ which can also escape spaces and other\n"
"special characters. It is also be put in front of a macro parameter\n"
"name inside the expansion to suppress the replacement by its value.\n"
"\n"
"Expansion of parameters in a macro body is purely textual. This can\n"
"lead to surprises in complex situations. The _%_ character can be used\n"
"to force a macro parameter to be replaced with the evaluation of it\n"
"as an expression.\n"
"\n"
"\n"
"..Inline Macros\n"
"\n"
"zmac supports the commonly available _rept_, _irp_ and _irpc_ inline macros\n"
"\n"
"_rept_ repeats its block the given number of times. This will output 10\n"
"_nop_ instructions:\n"
"\n"
" _rept 10_\n"
" \n"
" _######nop_\n"
" \n"
" _endm_\n"
"\n"
"_irpc_ runs through a string of letters assigned them to a variable and\n"
"expanding the macro block each time. For example, this will load 7 into\n"
"registers _b_, _d_ and _h_:\n"
"\n"
" _irpc reg,bdh_\n"
" \n"
" _######ld ®,7_\n"
" \n"
" _endm_\n"
"\n"
"_irp_ runs through a list of parameters assiging each entry to a variable\n"
"and expanding the macro block. Here we load _bc_, _de_ and _hl_ with 0:\n"
"\n"
" _irp rpair,<bc,de,hl>_\n"
" \n"
" _######ld &rpair,0_\n"
" \n"
" _endm_\n"
"\n"
"Lists can be nested. Here's an example of and _irp_ passing lists on down\n"
"to another _irp_:\n"
"\n"
" _irp listlist,<<one,two,three>,<four,five,six>>_\n"
" \n"
" _irp list,<listlist>_\n"
" \n"
" _ascii '&list'_\n"
" \n"
" _endm_\n"
" \n"
" _endm_\n"
"\n"
"\n"
"---\n"
".Compatibility\n"
"\n"
"zmac is broadly compatible with many original Z-80 and 8080 assemblers\n"
"because it accepts many different names for common operations and has\n"
"liberal identifier and numeric formats. It also accepts most simple\n"
"usage of macros.\n"
"\n"
"When assembling old code keep these portability problems in mind.\n"
"\n"
"Expression order of evaluation may be different. zmac uses C semantics\n"
"more order of evaluation but assemblers often used simple left to right\n"
"ordering. zmac will evaluate _2+2*3_ as _8_ where other assemblers will\n"
"yield _12_. However, in _--mras_ mode expressions are evaluated strictly\n"
"left-to-right for compatibility.\n"
"\n"
"zmac has no support operating on strings in macros. Assemblers like Macro-80\n"
"could perform conditional tests on strings.\n"
"\n"
"Advanced macros are unlikely to work. zmac hasn't advanced to the state where\n"
"all the possible ways of substituting parameters are supported.\n"
"\n"
"Consult the original assembler manual. zmac error messages won't help you\n"
"figure out what an unknown assembler command is supposed to do.\n"
"\n"
"Compare against original output. The very safest thing to do when porting\n"
"assembly code is to compare the binary output of zmac against that produced\n"
"by the original assembler. This way you can ensure everything has been\n"
"interpreted correctly. Only once that has been achieved should you modify\n"
"the code.\n"
"---\n"
".Errors and Warnings\n"
"\n"
"Any errors or warnings encountered during assembly are reported to standard\n"
"error and in the listing file. The errors output immediately give the source\n"
"file and line number containing the error. In listings the error letter\n"
"and message appear just after the line containing the error.\n"
"\n"
" B\n"
" Balance error\n"
" ##\n"
" A string is missing an closing quote or an _if_ is missing an _endif_\n"
" E\n"
" Expression error\n"
" ##\n"
" An expression did not parse or attempts a divide or modulus by 0.\n"
" F\n"
" Syntax error\n"
" ##\n"
" General problem with the syntax on a line. Sometimes extra explanation\n"
" will be printed on standard output.\n"
" I\n"
" Digit error\n"
" ##\n"
" A numeric constant has too many digits to be represented as a 32 bit number.\n"
" M\n"
" Mult. def. error\n"
" ##\n"
" A symbol has been defined more than once and those values differ.\n"
" P\n"
" Phase error\n"
" ##\n"
" On the second or subsequent assembly passes the assembly has changed\n"
" significantly. Most commonly it means an _if_ has changed conditions\n"
" but can also happen when labels or equated values do not converge to\n"
" a fixed value.\n"
" U\n"
" Undeclared error\n"
" ##\n"
" An undeclared symbol was used in an expression or _public_ statement.\n"
" V\n"
" Value error\n"
" ##\n"
" An invalid value was given to a statement. Often this means using less\n"
" than -128 or greater then 255 in a _defb_ or less than -32768 or greater\n"
" than 65535 in a _defw_. Or similar invalid values used Z-80/8080 opcodes\n"
" requiring an 8 or 16 bit value (and other restrictions like 0 to 7 for _BIT_).\n"
" Also if a relative jump is out of range or if a negative value is given\n"
" in _defs_ or _dc_.\n"
" O\n"
" Phase/Dephase error\n"
" ##\n"
" _phase_ was used within another _phase_ or _dephase_ without _phase_.\n"
" Or if _org_ is used within _phase_.\n"
" A\n"
" Assertion failure error\n"
" ##\n"
" An assert statement evaluated to zero.\n"
" J\n"
" Use JR error\n"
" ##\n"
" An absolute jump instruction was used where relative jump was in range\n"
" of the destination address. Only generated if _-j_ or _jrpromote_ is\n"
" in effect.\n"
" R\n"
" Not relocatable error\n"
" ##\n"
" An expression was used that must be generated at link time but cannot\n"
" be handled by the \".rel\" format. For instance, an _org_ to a symbol in\n"
" the data segment when in the code segment. Or a relative jump to a\n"
" different segment. The \".rel\" format can evaluate expressions at link\n"
" time using the _high_, _low_, _not_, _-_, _+_, _*_, _/_ and _%_ operators.\n"
" zmac is clever enough to use _high_ or _low_ in place of _& $ff00_ and\n"
" _& 255_. But it won't replace a _shl_ with a multiply.\n"
" G\n"
" Register usage error\n"
" ##\n"
" A invalid register was given to an instruction. For example, _LD B,(DE)_\n"
" or _ADD HL,IX_.\n"
" Z\n"
" Z-80 instruction in 8080 mode error\n"
" ##\n"
" An instruction was assembled that is only valid on the Z-80 but _.8080_\n"
" (or _-8_) mode is in effect. However, use use of Z-80 mnemonics that\n"
" output valid 8080 instructions is always OK.\n"
" H\n"
" $hex constant interpreted as symbol warning\n"
" ##\n"
" A symbol such as _$FCB_ has been defined even though it could appear to\n"
" be a hexadecimal constant. zmac will treat _$FCB_ as symbol for the entire\n"
" assembly which could be rather surprising if that were not the intent.\n"
" N\n"
" Not implemented warning\n"
" ##\n"
" For statements that have been added as parse rules but have no effect.\n"
" The only current example is _subttl_ which sets the sub title of a listing\n"
" in certain assemblers.\n"
"\n"
"---\n"
".Output Formats\\format\n"
"\n"
"Except for \".rel\", zmac writes every known output when assembling by default.\n"
"This is no burden on modern computers and saves having to meticulously select\n"
"the desired output format.\n"
"\n"
"\".rel\" is a special case since that format is intended for linking and\n"
"can have undefined external symbols which would be errors in the other formats.\n"
"Conversely, a simple \"org $8000\" will be an error for \".rel\" output as it\n"
"defaults to the code segment where absolute origin statements are forbidden.\n"
"\n"
"If \".rel\" is selected for output either by _--relopt_ or with\n"
"_--oo rel_ or _-o file.rel_ then all other output formats are suppressed\n"
"(except the \".lst\" source file listing).\n"
"\n"
" .ams\n"
" AMSDOS executable format for Amstrad computers.\n"
" .bds\n"
" For source-level debugging in trs80gp@http://www.48k.ca/trs80gp.html\n"
" .1500.cas\n"
" TRS-80 high-speed (1500 baud) cassette SYSTEM file. The internal name of the\n"
" file is the source file name shortened to 6 characters with suffixes\n"
" removed. Requires an entry address.\n"
" .250.cas\n"
" TRS-80 250 baud cassette Level I CLOAD file. If your program has an\n"
" entry address and $41FE does not contain that entry address then the file\n"
" will be loaded at $41FE with relocation code added to move it to the desired\n"
" location.\n"
" .500.cas\n"
" TRS-80 low-speed (500 baud) cassette SYSTEM file. The internal name of the\n"
" file is the source file name shortened to 6 characters with suffixes removed.\n"
" Requires an entry address.\n"
" .1000.cas\n"
" Identical to 500 baud but intended for double-speed LNW-80 which can\n"
" can load cassette files at double speed for an effective 1000 baud rate.\n"
" Requires an entry address.\n"
" .cim\n"
" Core In-Memory image. A raw binary format with the first byte corresponding\n"
" to the lowest generated code or data and proceeding contiguously until the\n"
" highest address generated. Any gaps are filled with zeros. Typically used\n"
" for CP/M where all executables start at address 256 or for ROM images.\n"
" .cmd\n"
" TRS-80 DOS executable file format as used by all major DOSes on the TRS-80\n"
" (TRS-DOS, LDOS, MULTIDOS, NEWDOS, etc.)\n"
" .hex\n"
" Intel hex record format.\n"
" .rel\n"
" Relocatable object module format as produced by MACRO-80 and other assemblers.\n"
" .tap\n"
" ZX Spectrum cassette tape format.\n"
" .1500.wav\n"
" Same as .1500.cas but in ready-to-play audio format.\n"
" .250.wav\n"
" Same as .250.cas but in ready-to-play audio format.\n"
" .500.wav\n"
" Same as .500.cas but in ready-to-play audio format.\n"
" .1000.wav\n"
" Same as .1000.cas but in ready-to-play audio format.\n"
" .mds\n"
" MAME debug script (e.g., mame trs80 -d -debugscript zout/prog.mds)\n"
"\n"
"---\n"
".Miscellaneous\n"
"In the symbol table listing, the _=_ prefix is given for those symbols\n"
"defined by _equ_ or _defl_. The _/_ prefix is shown for common blocks.\n"
"\n"
"The _.rel_ file format can store symbol names of up to 7 characters in length.\n"
"However, MACRO-80 truncates symbols to 6 characters so that it has one\n"
"character in reserve for extending linking operations such as subtracting\n"
"two externals from each other. To be compatible (and sensible), _--rel_\n"
"truncates externals to 6 characters. For MRAS compatibility, _--mras_\n"
"truncates symbols to 7 characters. This is not a problem for MRAS as it\n"
"doesn't support extended linking. But necessary if you want zmac to produce\n"
"_.rel_ files that will link with MRAS generated _.rel_ files. The _--rel7_\n"
"option sets symbol truncation to 7 characters so you can assemble files\n"
"that will link with MRAS output. However, it will break extended linking\n"
"on labels longer than 6 characters.\n"
"\n"
"The ignoring\\prime of single quotes can be handy for tracking alternate\n"
"register usage. Consider the following code fragment:\n"
"\n"
" _ld a,(hl)_\n"
" \n"
" _rra_\n"
" \n"
" _exx_\n"
" \n"
" _ld a,(hl')_\n"
" \n"
" _ex af,af'_\n"
" \n"
" _ld a',(hl')\n"
" \n"
" _rra'_\n"
" \n"
" _ex af,af'_\n"
" \n"
" _djnz' loop_\n"
" \n"
" _ld d',e'_\n"
" \n"
" _exx_\n"
"\n"
"Although zmac does nothing but ignore the single quotes they are useful for\n"
"indicating which register we're talking using. A more advanced mode\n"
"where zmac pays attention to the trailing quotes and emits exchange instrucitons\n"
"as needed has been considered.\n"
"\n"
"---\n"
".Exit Status\n"
"\n"
" 0\n"
" No errors.\n"
" 1\n"
" One or more errors were found during assembly, or zmac exited with a\n"
" fatal error.\n"
"\n"
"--\n"
".Credits\n"
"Bruce Norskog originally wrote zmac in 1978.\n"
"\n"
"Updates and bugfixes over the years by John Providenza, Colin Kelley,\n"
"and more recently by Russell Marks, Mark RISON, Chris Smith,\n"
"Matthew Phillips and Tim Mann.\n"
"\n"
"Extensive modifications for cycle counting, multiple output formats,\n"
"\".rel\" output, 8080 mode and older assembler compatibilty were written\n"
"by George Phillips.\n"
"\n"
"This document was based on Russell Marks zmac man page which had\n"
"tweaks by Mark RISON and Tim Mann. George Phillips converted it to HTML\n"
"and documented the new features and some older ones (e.g., _phase_/_dephase_).\n"
;