home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / mbug / mbug039.arc / ZMAC.DOC < prev   
Text File  |  1979-12-31  |  11KB  |  318 lines
  1. NAME
  2.     zmac - relocating Z-80 assembler
  3.  
  4. SYNOPSIS
  5.     zmac  relfile,listfile=asmfile
  6.  
  7. DESCRIPTION
  8.  
  9. ZMAC is a Zilog mnemonic assembler with command and language
  10. syntax similar to DEC assemblers. "relfile" is the object file
  11. name, with the default extension ".OBJ" (for the format, see
  12. OBJ.DOC). "listfile" is the listing file, with the default
  13. extension ".PRN". In addition to standard disk files, you can
  14. specify "LST:" for the list device or "CON:" for the console.
  15. "asmfile" is the input assembly language file, with the default
  16. extension ".ASM". The output files are both optional, so that
  17.  
  18.     zmac frodo=frodo
  19.  
  20. reads FRODO.ASM and creates FRODO.OBJ, while
  21.  
  22.     zmac ,frodo=frodo
  23.  
  24. creates only FRODO.PRN, and
  25.  
  26.     zmac frodo,frodo=frodo
  27.  
  28. creates both. Listing files are rarely needed except for final
  29. documentation, since lines with syntax errors are automatically
  30. listed to the console.
  31.  
  32. If ZMAC is called with no arguments, it will obey multiple
  33. commands of the above format, prompting for each with "ZMAC>".
  34. Operating this way saves time, since the assembler gets read in
  35. only once. An empty command line terminates the input.
  36.  
  37.  
  38. INPUT LANGUAGE 
  39.  
  40. The language accepted by ZMAC is like that for the Zilog
  41. assembler, with a few exceptions...
  42.  
  43. ZMAC does not require the "-$" after relative jump arguments.
  44. The standard and ZMAC syntaxes are as follows:
  45.  
  46. standard:        JR    SOMEWHERE-$
  47. ZMAC:            JR    SOMEWHERE .
  48.  
  49. For equates, the syntaxes are:
  50.  
  51. standard:    BELL    EQU    7H
  52. ZMAC:        BELL    =    7H .
  53.  
  54. A colon is forbidden after an equated symbol, but both a colon
  55. and whitespace (space, tab, or carriage return) are required
  56. after a label.
  57.  
  58. Symbols defined in the current module which are to be
  59. referenced in other modules (exported symbols), or those
  60. referenced in the current module but defined elsewhere
  61. (imported symbols) must be declared GLOBAL:
  62.  
  63.             GLOBAL    WARFARE
  64.  
  65. The ORG directive is illegal. There is instead the AORG
  66. ("absolute ORG") to set the program counter to a given absolute
  67. address. The bad news is that ZLINK has a bug in its handling
  68. of AORG. If one module has an AORG, then the NEXT module can't
  69. correctly import symbols. The good news is that an AORG is
  70. hardly ever necessary. ZLINK starts the code at 100H by
  71. default. There is also an RORG ("relative ORG") directive,
  72. which sets the program counter to a particular value with
  73. respect to the module beginning.
  74.  
  75. Symbols and opcodes can be in either upper or lower case (no
  76. case distinction). A symbol may have at least 100 characters,
  77. and the first 16 characters are significant. In addition to the
  78. standard alphabetic and numeric characters, the four characters
  79. "_$.%" are also permitted in symbols. A "$" by itself stands
  80. for the value of the program counter (the location of the first
  81. byte in the CURRENT machine instruction). For example, an
  82. infinite loop can be coded as "JP $". 
  83.  
  84. Numbers should start with a numeral, which can be zero. By
  85. default, the number is interpreted in decimal. The base of the
  86. number can be set by a letter at the end of the number: D for
  87. decimal, H for hex, O for octal, or B for binary.
  88.  
  89. The assembler can evaluate quite complex expressions.
  90. Multiplication and division have higher precedence than
  91. addition or subtraction (as usual for most software, but untrue
  92. for the Zilog assembler). Parentheses are permitted to enforce
  93. a certain evaluation order, but parentheses around an entire
  94. expression denote indexing. 
  95.  
  96. The unary operations are:    +    (no operation)
  97.                 -    negate (2's complement) 
  98.                 #    1's complement 
  99.  
  100. The binary operations are:    + - * /    as usual
  101.                 \    inclusive or
  102.                 &    and
  103.  
  104. EXAMPLE 
  105.  
  106. Consider the following assembly:
  107.  
  108.     C>zmac demo,demo=demo
  109.     SSD RELOCATING   (AND EVENTUALLY MACRO)  Z80 ASSEMBLER VER 1.07
  110.     
  111.         0  ERRORS
  112.  
  113. ...or the equivalent assembly using interactive input:
  114.  
  115.     C>zmac
  116.     SSD RELOCATING   (AND EVENTUALLY MACRO)  Z80 ASSEMBLER VER 1.07
  117.     ZMAC>demo,demo=demo
  118.     
  119.     
  120.         0  ERRORS
  121.     ZMAC>
  122.     
  123.     
  124.         0  ERRORS TOTAL
  125.     C> 
  126.                                                                
  127. The resulting listing file DEMO.PRN is as follows: 
  128.  
  129.                                           PAGE NO.    1 
  130.                       1 ;Demonstration of ZMAC assembly language 
  131.                       2 ;syntax and resulting object code 
  132.                       3 ; 
  133.                       4 ;declare imported symbol before use 
  134.                       5     GLOBAL    OMICRON 
  135.                       6 ;declare exported symbol before definition 
  136.                       7     GLOBAL    ALPHA 
  137.                       8 ; 
  138.                       9 ;Equal sign rather than "EQU", 
  139.                      10 ;and colon is illegal 
  140.    0001=             11 ONE    =    1 
  141.                      12 ;using local symbol 
  142.   '0000  0700'       13     DW    SIGMA 
  143.                      14 ;lower case is synonymous 
  144.   '0002  0700'       15     dw    sigma 
  145.   '0004  0C00'       16     DW    MU 
  146.                      17 ;both colon and whitespace (blank, tab,
  147.  
  148.                      18 ;or CRLF) are required after label 
  149.   '0006: 00          19 ALPHA:    DB    0 
  150.   '0007:             20 SIGMA: 
  151.                      21 ;using "extended alphabet" 
  152.                      22 ;in symbol names 
  153.   '0007: 01          23 _BETA:    DB    1 
  154.   '0008: 0F          24 BE_TA:    DB    15 
  155.   '0009: 02          25 .GAMMA:    DB    2 
  156.   '000A: 03          26 $DELTA:    DB    3 
  157.   '000B: 04          27 %EPSILON: DB    4 
  158.                      28 ;    "EF" is optional  
  159.   '000C: 05          29 MU:    DEFB    5 
  160.   '000D: 0600        30 NU:    DEFW    6 
  161.                      31 ; 
  162.   '000F:             32 RHO:    DS    16 
  163.                      33 ;precedence used in  
  164.                      34 ;evaluating expressions 
  165.   '001F  07          35     DB    1+2*3 
  166.   '0020? 0000        36     DW    OMICRON 
  167.   '0022  88          37     DB    88H 
  168.                      38 ;single or double quotes around string 
  169.                      39 ;(double either to insert into string) 
  170.   '0023  4A6F6527    40     DB    'Joe''s mom' 
  171.   '002C  20226861    41     db    " ""hates"" chocolate" 
  172.   '003E? 00          42     DB    OMEGA 
  173.   '003F  88          43     DB    88H 
  174.                      44 ;declare exported symbol after definition 
  175.                      45     GLOBAL    RHO 
  176.                      46 ;declare imported symbol after use 
  177.                      47     GLOBAL    OMEGA 
  178.     0  ERRORS 
  179.                                                                
  180.                                           PAGE NO.    1
  181.   
  182. Addresses and data values subject to relocation are marked with
  183. single quotes.  Imported values are marked with question marks.
  184.  
  185.  
  186. FORMAT OF .OBJ FILE
  187.  
  188. The following information was gleaned from inspection of the
  189. source code of the assembler and linker, and output generated
  190. by the assembler. It didn't come from Bruce Mallett, so any
  191. errors aren't his fault.              - Jim Van Zandt 
  192.  
  193. The relocatable file created by ZMAC consists of a module
  194. record, a series of data records, symbol records, and set
  195. address records, and is terminated by an end of module record.
  196.  
  197.  
  198. An end of module record has the format:
  199.  
  200.     DB    2,0
  201.  
  202.  
  203. A module start record has the format:
  204.  
  205. LGH1:    DB    NEXT1-LGH1    ;# bytes in record
  206.     DB    1        ;signals MODULE record
  207.     DB    YY        ;descriptor bits (see below)
  208.     DB    'FREEMONT'    ;optional module name 
  209. NEXT1: 
  210.  
  211.  
  212. A set address record is generated for each DEFS or DS opcode.
  213. It has the effect of resetting the linker's program counter. It
  214. has the format:
  215.  
  216. LGH2:    DB    NEXT2-LGH2    ;# bytes in record
  217.     DB    2        ;signals SET ADDRESS record
  218.     DB    YY        ;descriptor bits
  219.     DW    XXXX        ;new value for program
  220. ;                counter 
  221. NEXT2: 
  222.  
  223.  
  224. A data record has the following format:
  225.  
  226. LGH3:    DB    NEXT3-LGH3    ;# bytes in record
  227.     DB    3        ;signals DATA record
  228.     DS    28        ;one bit is set for each word
  229.                 ;of data requiring relocation.
  230.     DB    23,34,17,...,1BH ;1 to 224 bytes of data. 
  231. NEXT3:
  232.  
  233.  
  234. A symbol record is used to import or export a global symbol. It
  235. has the format:
  236.  
  237. LGH4:    DB    NEXT4-LGH4    ;# bytes in record 
  238.     DB    4        ;signals SYMBOL record 
  239.     DB    YY        ;descriptor bits
  240.     DW    XXXX    ;if defined here, XXXX is the value of
  241. ;            the symbol. If not defined here, XXXX
  242. ;            is the  address requiring the symbol.
  243. ;            The value of the symbol will be added
  244. ;            to the word  at XXXX. In either case,
  245. ;            if "relocatable",  then XXXX is with
  246. ;            respect to the beginning  of the module.
  247.     DB    'GANDOLF'    ;the symbol 
  248. NEXT4: 
  249.  
  250. In the above records, the "descriptor bits" are defined as
  251. follows:
  252.  
  253.     bit 0    if word rather than byte 
  254.     bit 1    if defined here 
  255.     bit 2    if global rather than local 
  256.     bit 3    if relocatable rather than absolute 
  257.     bit 4    if value of symbol is to be shifted left 
  258.         by 3 bits. 
  259.  
  260. The "shift left 3 bits" note is used when the bit number in a
  261. SET, BIT, or RES instruction is an imported symbol. In those
  262. instructions, the bit number field is in bits 3 through 5 of a
  263. byte. Note that it is always characteristic of a use, never a
  264. definition, of a symbol.
  265.  
  266. The object code corresponding to the above assembly listing is:
  267.  
  268. C>dump demo.obj 
  269. DUMP version 00.05 
  270.         RECORD:  0 
  271. 0000 0301 002D 03A8 0000-0000 0000 0000 0000  ...-.(.......... 
  272. 0010 0000 0000 0000 0000-0000 0000 0000 0000  ................ 
  273. 0020 0007 0007 000C 0000-010F 0203 0405 0600  ................ 
  274. 0030 0502 0A1F 000C 0405-2000 4F4D 4943 524F  ........ .OMICRO 
  275. 0040 4E0A 0404 3E00 4F4D-4547 413F 0300 0000  N...>.OMEGA?.... 
  276. 0050 0000 0000 0000 0000-0000 0000 0000 0000  ................ 
  277. 0060 0000 0000 0000 0000-0007 0000 884A 6F65  .............Joe 
  278. 0070 2773 206D 6F6D 2022-6861 7465 7322 2063  's mom "hates" c 
  279.         RECORD:  1 
  280. 0080 686F 636F 6C61 7465-0088 0B04 0B0A 0024  hocolate.......$ 
  281. 0090 4445 4C54 4108 0402-0100 4F4E 4508 040F  DELTA.....ONE... 
  282. 00A0 0F00 5248 4F0B 040B-0900 2E47 414D 4D41  ..RHO......GAMMA 
  283. 00B0 0D04 0B0B 0025 4550-5349 4C4F 4E0A 040B  .....%EPSILON... 
  284. 00C0 0700 5349 474D 410A-040F 0600 414C 5048  ..SIGMA.....ALPH 
  285. 00D0 410A 040B 0800 4245-5F54 4107 040B 0C00  A.....BE_TA..... 
  286. 00E0 4D55 0704 0B0D 004E-550A 040B 0700 5F42  MU.....NU....._B 
  287. 00F0 4554 4102 0000 0000-0000 0000 0000 0000  ETA............. 
  288.  
  289. The first byte of relocation bits in the first data record
  290. (relative address 0005 in the file) is A8 hex, or 10101000
  291. binary, signifying that words beginning at bytes 0, 2, and 4
  292. among the following data bytes must be relocated. The last nine
  293. bytes displayed are extraneous, since the end of module record
  294. is at 00F3 and 00F4.
  295.  
  296. For more information, see the source files.
  297.  
  298.  
  299. POTENTIAL IMPROVEMENTS
  300.     
  301. Handle multiple program counters, such as one each for "code",
  302. "initialized data", and "uninitialized data".
  303.     
  304. Permit "EQU" as well as "=".
  305.     
  306. Make colons optional after either equated symbols or labels.
  307.     
  308. Make "ORG" a synonym for "AORG".
  309.  
  310.  
  311. BUGS
  312.  
  313. A file name can't include a '-'.
  314.  
  315.  
  316. AUTHOR
  317.     Bruce Mallett
  318.