Doc.txt 38 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803
  1. A68k - a freely distributable assembler for the Amiga
  2. by Charlie Gibbs
  3. with special thanks to
  4. Brian R. Anderson and Jeff Lydiatt
  5. The current versions are now part of the TIGCC project.
  6. As such, they will be aimed much more at development for the TI-89 and
  7. TI-92+ calculators than at the Amiga.
  8. Modifications of this document are marked with (TIGCC)
  9. (Version 2.71.F3w - July 27, 2006)
  10. Note: This program is Freely Distributable, as opposed to Public
  11. Domain. Permission is given to freely distribute this program provided no
  12. fee is charged, and this documentation file is included with the program.
  13. This assembler is based on Brian R. Anderson's 68000 cross-
  14. assembler published in Dr. Dobb's Journal, April through June 1986.
  15. I have converted it to produce AmigaDOS-format object modules, and
  16. have made many enhancements, such as macros and INCLUDE files.
  17. My first step was to convert the original Modula-2 code into C.
  18. I did this for two reasons. First, I had access to a C compiler, but
  19. not a Modula-2 compiler. Second, I like C better anyway.
  20. The executable code generator code (GetObjectCode and MergeModes)
  21. is essentially the same as in the original article, aside from its
  22. translation into C. I have almost completely rewritten the remainder
  23. of the code, however, in order to remove restrictions, add enhancements,
  24. and adapt it to the AmigaDOS environment. Since the only reference book
  25. available to me was the AmigaDOS Developer's Manual (Bantam, February
  26. 1986), this document describes the assembler in terms of that book.
  27. RESTRICTIONS
  28. Let's get these out of the way first:
  29. o The verification file (-v) option is not supported. Diagnostic
  30. messages always appear on the console. They also appear in the
  31. listing file, however (see extensions below). You can produce
  32. an error file by redirecting console output to a file - the
  33. line number counter and final summary are displayed on stderr
  34. so you can still see what's happening.
  35. WARNING: The new -v switch introduced in v.2.71.F3c is NOT the
  36. same as this one! (TIGCC)
  37. o The file names in the INCLUDE directory list (-i) must be
  38. separated by commas. The list may not be enclosed in quotes.
  39. o Labels assigned by EQUR and REG directives are case-sensitive.
  40. o Strange things will happen if your source code (including
  41. INCLUDE files and macro expansions) exceeds 32,766 lines.
  42. Tough darts. Break up your source file. Can you actually
  43. read that monster? :-)
  44. (TIGCC) The maximum has been increased from 32,766 to
  45. 2,147,483,646 for 32-bit operating systems starting
  46. from version 2.71.F3s.
  47. o The following directives are not supported, and will be flagged
  48. as invalid op-codes:
  49. OFFSET
  50. NOPAGE
  51. LLEN
  52. PLEN
  53. NOOBJ
  54. FAIL
  55. FORMAT
  56. NOFORMAT
  57. MASK2
  58. I feel that NOPAGE, LLEN, and PLEN should not be defined within
  59. a source module. It doesn't make sense to me to have to change
  60. your program just because you want to print your listings on
  61. different paper. The command-line switch "-p" (see below) can
  62. be used as a replacement for PLEN; setting it to a high value
  63. (like 32767) is a good substitute for NOPAGE. The effect of
  64. LLEN can be obtained by running the listing file through an
  65. appropriate filter.
  66. EXTENSIONS
  67. Now for the good stuff:
  68. o Labels can be any length that will fit onto one source line
  69. (currently 127 characters maximum). Since labels are stored
  70. on the heap, the number of labels that can be processed is
  71. limited only by available memory.
  72. (TIGCC) The maximum has been increased from 127 to 256 (for
  73. Win32, starting from 2.71.F3a, for GNU/Linux,
  74. starting from 2.71.F3c, for all other platforms,
  75. starting from 2.71.F3s).
  76. o The first character of a label can be '@' if the next character
  77. is not numeric (this avoids confusion with octal constants).
  78. This provides compatibility with the Lattice C compiler.
  79. o Since section data and user macro definitions are stored in
  80. the symbol table (see above), they too are limited only by
  81. available memory. (Actually, there is a hard-coded limit of
  82. 32,767 sections, but I doubt anyone will run into that one.)
  83. o The only values a label cannot take are the register names -
  84. A68k can distinguish between the same name used as a label,
  85. instruction name or directive, macro name, or section name.
  86. o Section and user macro names appear in the symbol table dump,
  87. and will also be cross-referenced. Their names can be the same
  88. as any label (see above); they will be listed separately.
  89. o INCLUDEs and macro calls can be nested indefinitely, limited
  90. only by available memory. The message "Secondary heap
  91. overflow - assembly terminated" will be displayed if memory
  92. is exhausted. You can increase the size of this heap using
  93. the -w switch (see below). Recursive macros are supported;
  94. recursive INCLUDEs will, of course, result in a loop that
  95. will be broken only when the heap overflows.
  96. o The EVEN directive forces alignment on a word (2-byte)
  97. boundary. It does the same thing as CNOP 0,2.
  98. (This one is left over from the original code.)
  99. o Backward references to labels within the current CODE section
  100. will be converted to PC-relative addressing with displacement
  101. if this mode is legal for the instruction. This feature is
  102. disabled by the -n switch.
  103. o If a MOVEM instruction only specifies one register, it is
  104. converted to the corresponding MOVE instruction. Instructions
  105. such as MOVEM D0-D0,label will not be converted, however.
  106. This feature is disabled by the -n switch.
  107. (TIGCC) Starting from v.2.71.F3c, this feature can now also be
  108. disabled by using the -rm switch.
  109. o ADD, SUB, and MOVE instructions will be converted to ADDQ,
  110. SUBQ, and MOVEQ respectively if possible. Instructions coded
  111. explicitly (e.g. ADDA or ADDI) will not be converted. This
  112. feature is disabled by the -n switch.
  113. o ADD, CMP, SUB, and MOVE to an address register are converted to
  114. ADDA, CMPA, SUBA, and MOVEA respectively, unless (for ADD, SUB,
  115. or MOVE) they have already been converted to quick form.
  116. o ADD, AND, CMP, EOR, OR, and SUB of an immediate value are
  117. converted to ADDI, ANDI, CMPI, EORI, ORI, and SUBI respectively
  118. (unless the address register or quick conversion above has
  119. already been done).
  120. o (TIGCC) Starting from v.2.71.F3c, ADDA and SUBA (or ADD and SUB
  121. to an addressregister) will now be converted to LEA if
  122. possible. This feature can be disabled using the -n
  123. switch (disables all optimizations) or the -ra switch
  124. (disables just this single optimization).
  125. o (TIGCC) Starting from v.2.71.F3c, LEA n(an),an will now be
  126. converted to ADDQ or SUBQ if possible. This feature can
  127. be disabled using the -n switch (disables all
  128. optimizations) or the -rl switch (disables just this
  129. single optimization).
  130. o If both operands of a CMP instruction are postincrement mode,
  131. the instruction is converted to CMPM.
  132. o Operands of the form 0(An) will be treated as (An) except for
  133. the MOVEP instruction, which always requires a displacement.
  134. This feature is disabled by the -n switch.
  135. o The SECTION directive allows a third parameter. This can be
  136. specified as either CHIP or FAST (upper or lower case). If
  137. this parameter is present, the hunk will be written with the
  138. MEMF_CHIP or MEMF_FAST bit set. This allows you to produce
  139. "pre-ATOMized" object modules.
  140. o The synonyms DATA and BSS are accepted for SECTION directives
  141. starting data or BSS hunks. The CHIP and FAST options (see
  142. above) can also be used, e.g. BSS name,CHIP.
  143. o The following synonyms have been implemented for compatibility
  144. with the Aztec assembler:
  145. CSEG is treated the same as CODE or SECTION name,CODE
  146. DSEG is treated the same as DATA or SECTION name,DATA
  147. PUBLIC is treated as either XDEF or XREF, depending on
  148. whether or not the symbol in question has been
  149. defined in the current source module.
  150. A single PUBLIC directive can name a mixture
  151. internally- and externally-defined symbols.
  152. o The ability to produce Motorola S-records is retained from the
  153. original code. The -s switch causes the assembler to produce
  154. S-format instead of AmigaDOS format. Relocatable code cannot
  155. be produced in this format.
  156. o Error messages consist of three parts.
  157. The position of the offending line is given as a line
  158. number within the current module. If the line is within a
  159. macro expansion or INCLUDE file, the position of the macro
  160. call or INCLUDE statement in the outer module is given as
  161. well. This process is repeated until the outermost source
  162. module is reached.
  163. Next, the offending source line itself is listed.
  164. Finally, the errors for that line are displayed. A flag
  165. (^) is placed under the column where the error was detected.
  166. o Named local labels are supported. These work the same as the
  167. local labels supported by the Metacomco assembler (nnn$) but
  168. are formed in the same manner as normal labels, except that
  169. they must be preceded by a backslash (\).
  170. o The following synonyms have been implemented for compatibility
  171. with the Assempro assembler:
  172. ENDIF is treated the same as ENDC
  173. = is treated the same as EQU
  174. | is treated the same as ! (logical OR)
  175. o Quotation marks (") can be used as string delimiters
  176. as well as apostrophes ('). Any given string must begin
  177. and end with the same delimiter. This allows such statements
  178. as the following:
  179. MOVEQ "'",D0
  180. DC.B "This is Charlie's assembler."
  181. Note that you can still define an apostrophe within a string
  182. delimited by apostrophes if you double it, e.g.
  183. MOVEQ '''',D0
  184. DC.B 'This is Charlie''s assembler.'
  185. o If any errors are found in the assembly, the object code file
  186. will be scratched, unless you include the -k (keep) flag on
  187. the command line.
  188. o The symbols .A68K, .a68k, .a68K, and .A68k are automatically
  189. defined as SET symbols having absolute values of 1.
  190. This enables a source program to determine whether it is
  191. being assembled by this assembler, and is effectively
  192. insensitive as to whether or not it is checked in upper case.
  193. o A zeroth positional macro parameter (\0) is supported. It
  194. is replaced by the length of the macro call (B, W, or L,
  195. defaulting to W). For instance, given the macro:
  196. moov MACRO
  197. move.\0 \1,\2
  198. ENDM
  199. the macro call
  200. moov.l d0,d1
  201. would be expanded as
  202. move.l d0,d1
  203. o If an INCLUDE file doesn't generate any code and no listing
  204. file is required (including suppression of the listing using
  205. NOLIST), it won't be read again in pass 2. The statement
  206. numbers will be bumped to keep in proper alignment. This
  207. can really speed up assemblies that INCLUDE lots of EQUates.
  208. o The ORG directive is supported. It works like RORG, except
  209. that it takes the actual address to be jumped to, rather
  210. than an offset from the start of the current section.
  211. The given address must be in the current section.
  212. As far as A68k is concerned, the only real difference
  213. between ORG and RORG is that the ORG value must be
  214. relocatable, while the RORG value must be absolute.
  215. o Branch (Bcc, including BRA and BSR) instructions will be
  216. converted to short form if possible. Shortening a branch
  217. may bring other branches within range of shortening - this
  218. can set up a ripple effect, and A68k may not catch all
  219. branches that could theoretically be optimized. Any branches
  220. which A68k misses (there shouldn't be too many under normal
  221. circumstances) can be displayed by specifying the -f switch
  222. (see below). Branch optimization is disabled by the -n switch.
  223. o The INCBIN directive allows the contents of any file to be
  224. included in A68k's object code output. Its format is the same
  225. as the INCLUDE directive, but the file can contain any data
  226. at all, printable or not. Rather than being processed as
  227. source code by the assembler, the entire contents of the file
  228. is copied directly to the current position in the object code
  229. output file with no reformatting whatsoever. The effect is
  230. the same as if DC statements whose constants represent the
  231. file's contents were inserted in place of the INCBIN directive.
  232. o The opcode TTL is accepted as a synonym for TITLE.
  233. o A command-line option (-g) causes A68k to treat any undefined
  234. symbol as XREF.
  235. o The register list in a MOVEM instruction can be an
  236. immediate operand which specifies the actual mask bits.
  237. o (TIGCC) The following synonyms are also supported:
  238. Starting from 2.71.F3a:
  239. * BLO = BCS
  240. * BHS = BCC
  241. * DBLO = DBCS
  242. * DBHS = DBCC
  243. * ROLX = ROXL
  244. * RORX = ROXR
  245. Starting from 2.71.F3c:
  246. * SLO = SCS
  247. * SHS = SCC
  248. THE SMALL CODE / SMALL DATA MODEL
  249. Version 2.4 implements a rudimentary small code/data model.
  250. It consists of converting any data reference to one of the following
  251. three addressing modes:
  252. address register indirect with displacement using a
  253. specified address register, defaulting to A4
  254. (for references to the DATA or BSS section)
  255. program counter indirect with displacement
  256. (for references to the CODE section)
  257. absolute word
  258. (for absolute and 16-bit relocatable values)
  259. These conversions do not take place unless a NEAR directive is
  260. encountered. The NEAR directive can take one operand, which
  261. must be either an address register or a symbol which has been
  262. equated (using EQUR) to an address register. Register A7 (SP)
  263. may not be used. If no register is given, A4 is assumed.
  264. Conversion is done for all operands until a FAR directive
  265. is encountered. NEAR and FAR directives can occur any number
  266. of times, enabling conversion to be turned on and off at will.
  267. Backward references which cannot be converted (e.g. external
  268. labels declared as XREF) will remain as absolute long addressing.
  269. All forward references are assumed to be convertible, since during
  270. pass 1 A68k has no way of telling whether conversion is possible.
  271. If conversion turns out to be impossible, invalid object code will
  272. be generated - an error message ("Invalid forward reference") will
  273. indicate when this occurs.
  274. Although the small code/data model can greatly reduce the
  275. size of assembled programs, several restrictions apply:
  276. o Small code and small data models are active simultaneously.
  277. You can't have one without the other, since during pass 1
  278. A68k doesn't know whether forward references are to CODE
  279. or to DATA/BSS.
  280. o Programs can consist of a maximum of two sections,
  281. one CODE, the other DATA or BSS. If you try to define
  282. a third section, the message "Too many SECTIONs" will
  283. be displayed. The NEAR directive is active only within
  284. the CODE section.
  285. o While the NEAR directive is active, external labels (XREF)
  286. must be declared before they are used, CODE section references
  287. must be with 32K of the current position (i.e. expressible as
  288. PC-relative), and DATA/BSS section references must be in the
  289. first 64K of the DATA/BSS section (i.e. expressible as
  290. address register indirect with displacement). Any instructions
  291. which do not satisfy these requirements cannot be detected in
  292. pass 1, so A68k has no choice but to display an error message
  293. in pass 2 ("Invalid forward reference") which in this case
  294. indicates that invalid code has been generated. To properly
  295. assemble such instructions, you can temporarily disable
  296. conversion with a FAR directive, then resume afterwards
  297. with another NEAR directive.
  298. o Conversion cannot be done for references between modules.
  299. All external references must be left as absolute long.
  300. o A68k assumes that the base register (normally A4) points to
  301. the start of the DATA/BSS section plus 32768 bytes. (This
  302. assumed offset can be changed by the -m command-line parameter.)
  303. The register must be preloaded with this value before executing
  304. any code converted by the NEAR directive. One way to do this
  305. is to code the instruction that loads the register prior to
  306. the NEAR directive. Another way is to use a MOVE.L with
  307. immediate mode, which is never converted. Here are examples
  308. of the two methods:
  309. LEA data+32768,a4 NEAR
  310. NEAR ;defaults to A4 MOVE.L #data+32768,a4
  311. <remainder of code> <remainder of code>
  312. BSS BSS
  313. data: data:
  314. <data areas> <data areas>
  315. END END
  316. I'll be the first to admit that this is a very crude and ugly
  317. implementation. I hope to improve it in future versions.
  318. FILES
  319. A68k uses the following files:
  320. o The source code file - this file contains the program to be
  321. assembled. This file is an ASCII text file whose last line
  322. must be an END statement.
  323. (TIGCC) This END statement is no longer necessary starting
  324. from v.2.71.F3c.
  325. Moreover, the assembler will no longer accept an END
  326. statement in include files or macros, since it did
  327. never expect that and caused bugs.
  328. o The object code file - this file is created by A68k, replacing
  329. any previous version which may exist. If any errors are
  330. encountered during the assembly, this file will be scratched,
  331. unless the -k (keep) switch is specified (see below).
  332. Although this file is normally written in AmigaDOS format,
  333. the -s switch (see below) will cause it to be written in
  334. Motorola S-record format instead.
  335. o The listing file - this file is optionally created by A68k
  336. and contains a listing complete with page headings (including
  337. form feeds), generated object code, and error messages if any.
  338. It is suitable for feeding to a printer.
  339. o An equate file - this file is optionally created by A68k
  340. and consists of a leading comment line followed by EQU
  341. statements, one for each symbol encountered by A68k whose
  342. value is absolute. This file is only created if the -e
  343. command-line switch is specified (see below).
  344. o A header file - if requested, this file is read by A68k
  345. immediately prior to the source code file. It treated
  346. exactly as if it were requested by an INCLUDE statement
  347. at the front of the source file, but is selected only if
  348. the -h command-line switch is specified (see below).
  349. o Include files are selected by INCLUDE directives within the
  350. source file, and are inserted in the source code in place
  351. of the INCLUDE directive itself. A68k first searches the
  352. current directory for INCLUDE files; the -i command-line
  353. switch (see below) specifies additional directories which
  354. can be searched.
  355. FILE NAMES
  356. The names of the above files can be explicitly specified.
  357. However, A68k will generate default file names in the following cases:
  358. o If the -o switch is omitted, a default name will be assigned
  359. to the object code file.
  360. o If the -e switch is specified with no file name, a default
  361. name will be assigned to the equate file.
  362. o If the -l or -x switch is specified with no file name, a
  363. default name will be assigned to the listing file.
  364. A default name is generated by deriving a stem name from the source
  365. code file name, and appending .o for an object code file name (.s
  366. if the -s switch is specified to produce Motorola S-records), .equ
  367. for an equate file name, or .lst for a listing file name. The stem
  368. name consists of all characters of the source file name up to the
  369. last period (or the entire source file name if it contains no period).
  370. Here are some examples:
  371. Default names
  372. --------------------------------------------
  373. Source file Object file Equate file Listing file
  374. ----------- ----------- ----------- ------------
  375. myprog.asm myprog.o myprog.equ myprog.lst
  376. myprog myprog.o myprog.equ myprog.lst
  377. new.prog.asm new.prog.o new.prog.equ new.prog.lst
  378. HOW TO USE A68k
  379. The command-line syntax to run the assembler is as follows:
  380. a68k <source file name>
  381. [<object file name>]
  382. [<listing file name>]
  383. (TIGCC) [-a]
  384. [-d[[!]<prefix>]]
  385. [-e[<equate file name>]]
  386. [-f]
  387. [-g]
  388. [-h<header file name>]
  389. [-i<INCLUDE directory list>]
  390. [-k]
  391. [-l[<listing file name>]]
  392. [-m<small data offset>]
  393. [-n]
  394. [-o<object file name>]
  395. [-p<page depth>]
  396. [-q[<quiet interval>]]
  397. (TIGCC) [-r[a][l][m]]
  398. [-s]
  399. [-t]
  400. (TIGCC) [-u]
  401. (TIGCC) [-v<name>[,<value>]]
  402. [-w[<hash table size>][,<secondary heap size>]]
  403. [-x[<listing file name>]]
  404. [-y]
  405. [-z[<debug start line>][,<debug end line>]]
  406. These options can be given in any order. Any parameter which is not
  407. a switch (denoted by a leading hyphen) is assumed to be a file name;
  408. up to three file names (assumed to be source, object, and listing file
  409. names respectively) can be given. A source file name is always required.
  410. If a switch is being given a value, that value must immediately follow
  411. the switch letter with no intervening spaces. For instance, to specify
  412. a page depth of 40 lines, the specification "-p40" should be used;
  413. "-p 40" will be rejected.
  414. Switches perform the following actions:
  415. (TIGCC) -a causes all relocs to be emitted, even PC-relative relocs
  416. within a section. It also emits address differences in a
  417. special TIGCC-specific format. This will allow more
  418. aggressive linker-side optimization.
  419. -d causes symbol table entries (hunk_symbol) to be written
  420. to the object module for the use of symbolic debuggers.
  421. If the switch is followed by a string of characters, only
  422. those symbols beginning with that prefix string will be
  423. written. This can be used to suppress internal symbols
  424. generated by compilers. If the first character is an
  425. exclamation mark (!), only symbols which do NOT begin
  426. with the following characters are written out.
  427. Here are some examples:
  428. -d writes all symbols
  429. -dabc writes only symbols beginning with "abc"
  430. -d!x writes symbols which do not begin with "x"
  431. -e causes an equate file (see above) to be produced. A file
  432. name can be specified; otherwise a default name will be used.
  433. -f causes any branches (Bcc, BRA, BSR) that could be converted
  434. to short form to be flagged. A68k will convert as many
  435. branches as possible to short form (unless the -n switch is
  436. is specified), but certain combinations of instructions may
  437. set up a ripple effect where shortening one branch brings
  438. another one into range. This switch will cause A68k to
  439. flag any branches that it may have missed; during pass 2
  440. it is possible to tell this, although during pass 1 it might
  441. not be. If the -n switch (see below) is specified along
  442. with this switch (suppressing all optimization), no branches
  443. will be shortened, but all branches which could be shortened
  444. will be flagged.
  445. -g causes any undefined symbols to be treated as if they were
  446. externally defined (XREF), rather than being flagged as errors.
  447. -h causes a header file to be read prior to the source code file.
  448. A file name must be given. The action is the same as if the
  449. first statement of the source file were an INCLUDE statement
  450. naming the header file. To find the header file, the same
  451. directories will be searched as for INCLUDE files (see the
  452. -i switch below).
  453. -i specifies directories to be searched for INCLUDE files in
  454. addition to the current directory. Several names, separated
  455. by commas, may be specified. No embedded blanks are allowed.
  456. For example, the specification
  457. -imylib,df1:another.lib
  458. will cause INCLUDE files to be searched for first in the
  459. current directory, then in "mylib", then in "df1:another.lib".
  460. -k causes the object file to be kept even if any errors were
  461. found. Otherwise, it will be scratched if any errors occur.
  462. -l causes a listing file to be produced. If you want the listing
  463. file to include a symbol table dump and cross-reference, use
  464. the -x switch instead (see below).
  465. -m changes the assumed offset from the start of the DATA/BSS
  466. section to the base register used when the small code /
  467. small data option is activated by the NEAR directive.
  468. If this parameter is not specified, the offset defaults
  469. to 32768.
  470. -n causes all object code optimization (see above) to be disabled.
  471. -o allows the default name for the object code file (see above)
  472. to be overridden.
  473. -p causes the page depth to be set to the specified value.
  474. This takes the place of the PLEN directive in the Metacomco
  475. assembler. Page depth defaults to 60 lines (-p60).
  476. -q changes the interval at which A68k displays the line number
  477. it has reached in its progress through the assembly. The
  478. default is to display every 100 lines (-q100). Specifying
  479. larger values reduces console I/O, making assemblies run
  480. slightly faster.
  481. If you specify a negative number (e.g. -q-10), line numbers
  482. will be displayed at an interval equal to the absolute value
  483. of the specified number, but will be given as positions
  484. within the current module (source, macro, or INCLUDE) rather
  485. than as a total statement count - the module name will also
  486. be displayed.
  487. A special case is the value zero (-q0 or just -q) - this
  488. will cause all console output, except for error messages,
  489. to be suppressed.
  490. (TIGCC) -r Allows to disable specific optimizations:
  491. -rm Disable the MOVEM -> MOVE optimization
  492. -ra Disable the ADD(A)/SUB(A) -> LEA optimization
  493. -rl Disable the LEA -> ADDQ/SUBQ optimization
  494. You might use more than one -r switch (as in "-rm -ra") or
  495. combine them into a single switch (as in "-rma").
  496. -s causes the object file to be written in Motorola S-record
  497. format, rather than AmigaDOS format. The default name for
  498. an S-record file ends with ".s" rather than ".o"; this can
  499. still be overridden with the -o switch, though.
  500. -t allows tabs in the source file to be passed through to the
  501. listing file, rather than being expanded. In addition, tabs
  502. will be generated in the listing file to skip from the object
  503. code to the source statement, etc. This can greatly reduce
  504. the size of the listing file, as well as making it quicker to
  505. produce. Do not use this option if you will be displaying or
  506. listing the list file on a device which does not assume a tab
  507. stop at every 8th position.
  508. (TIGCC) -u Disables automatic alignment of DC.W, DC.L, DCB.W, DCB.L,
  509. DS.W, DS.L and code.
  510. (TIGCC) -v Allows to set a variable in the command line (like -d with
  511. GCC). The variable will be a SET, not EQU variable. Syntax:
  512. "-v<name>[,<value>]" (without spaces, and without the
  513. quotes). Note that <value> can only be a NUMBER at the
  514. moment. (We might support symbols as values in a future
  515. version.) The default value of <value> is 1.
  516. -w specifies the sizes of fixed memory areas that A68k allocates
  517. for its own use. You should normally never have to specify
  518. this switch, but it may be useful for tuning.
  519. The first parameter gives the number of entries that the hash
  520. table (used for searching the symbol table) will contain.
  521. The default value of 2047 should be enough for all but the
  522. very largest programs. The assembly will not fail if this
  523. value is too small, but may slow down if too many long hash
  524. chains must be searched. The hashing statistics displayed by
  525. the -y switch (see below) can be used to tune this parameter.
  526. I've heard that you should really specify a prime number for
  527. this parameter, but I haven't gone into hashing theory enough
  528. to know whether it's actually necessary.
  529. The second parameter of the -w switch specifies the size (in
  530. bytes) of the secondary heap, which is used to store nested
  531. macro and INCLUDE file information (see below). It defaults
  532. to 1024, which should be enough unless you use very deeply
  533. nested macros and/or INCLUDE files with long path names.
  534. (TIGCC) The default sizes are 4095,2048 in the Win32 (since
  535. v.2.71.F3a) and GNU/Linux (since v.2.71.F3c) versions.
  536. You can specify either or both parameters. For example:
  537. -w4093 secondary heap size remains at 1024 bytes
  538. -w,2000 hash table size remains at 2047 entries
  539. -w4093,2000 increases the size of both areas
  540. If you're really tight for memory, and are assembling small
  541. modules, you can use this switch to shrink these areas below
  542. their default sizes. At the end of an assembly, a message
  543. will be displayed giving the sizes actually used, in the form
  544. of the -w command you would have to enter to allocate that much
  545. space. This is primarily useful to see how much secondary
  546. heap space was used.
  547. NOTE: All other memory used by A68k (e.g. the actual symbol
  548. table) is allocated as required (currently in 8K chunks).
  549. -x works the same as -l (see above), except that a symbol table
  550. dump, including cross-reference information, will be added
  551. to the end of the listing file.
  552. -y causes hashing statistics to be displayed at the end of the
  553. assembly. First the number of symbols in the table is given,
  554. followed by a summary of hash chains by length. Chains with
  555. length zero denote unused hash table entries. Ideally (i.e.
  556. if there were no collisions) there should be as many chains
  557. with length 1 as there are symbols, and there should be no
  558. chains of length 2 or greater. I added this option to help
  559. me tune my hashing algorithm, but you can also use it to see
  560. whether you should allocate a larger hash table (using the
  561. first parameter of the -w switch, see above).
  562. -z was provided to help debug A68k itself. It causes A68k to
  563. list a range of source lines, complete with line number and
  564. current location counter value, during both passes. Lines
  565. are listed immediately after they have been read from the
  566. source file, before any processing occurs.
  567. Here are some examples of the -z switch:
  568. -z lists all source lines
  569. -z100,200 lists lines 100 through 200
  570. -z100 lists all lines starting at 100
  571. -z,100 lists the first 100 lines
  572. TECHNICAL INFORMATION
  573. The actual symbol table entries (pointed to by the hash table,
  574. colliding entries are linked together) are stored in 8K chunks which
  575. are allocated as required. The first entry of each chunk is reserved
  576. as a link to the next chunk (or NULL in the last chunk) - this makes
  577. it easy to find all the chunks to free them when we're finished. All
  578. symbol table entries are stored in pass 1. During pass 2, cross-
  579. reference table entries are built in the same group of chunks,
  580. immediately following the last symbol table entry. Additional chunks
  581. will continue to be linked in if necessary.
  582. Symbol names and macro text are stored in another series of linked
  583. chunks. These chunks consist of a link pointer followed by strings
  584. (terminated by nulls) laid end to end. Symbols are independent entries,
  585. linked from the corresponding symbol table entry. Macros are stored as
  586. consecutive strings, one per line - the end of the macro is indicated by
  587. an ENDM statement. If a macro spans two chunks, the last line in the
  588. original chunk is followed by a newline character to indicate that the
  589. macro is continued in the next chunk.
  590. Relocation information is built during pass 2 in yet another
  591. series of linked chunks. If more than one chunk is needed to hold one
  592. section's relocation information, all additional chunks are released
  593. at the end of the section.
  594. The secondary heap is built from both ends, and it grows and
  595. shrinks according to how many macros and INCLUDE files are currently
  596. open. At all times there will be at least one entry on the heap, for
  597. the original source code file. The expression parser also uses the
  598. secondary heap to store its working stacks - this space is freed as
  599. soon as an expression has been evaluated.
  600. The bottom of the heap holds the names of the source code file
  601. and any macro or INCLUDE files that are currently open. The full path
  602. is given. A null string is stored for user macros. Macro arguments
  603. are stored by additional strings, one for each argument in the macro
  604. call line. All strings are stored in minimum space, similar to the
  605. labels and user macro text on the primary heap. File names are
  606. pointed to by the fixed table entries (see below) - macro arguments
  607. are accessed by stepping past the macro name to the desired argument,
  608. unless NARG would be exceeded.
  609. The fixed portion of the heap is built down from the top. Each
  610. entry occupies 16 bytes. Enough information is stored to return to
  611. the proper position in the outer file once the current macro or
  612. INCLUDE file has been completely processed.
  613. The diagram below illustrates the layout of the secondary heap.
  614. Heap2 + maxheap2 -----------> ___________________________
  615. | |
  616. | Input file table |
  617. struct InFCtl *InF ---------> |___________________________|
  618. | |
  619. | Parser operator stack |
  620. struct OpStack *Ops --------> |___________________________|
  621. | |
  622. | (unused space) |
  623. struct TermStack *Term -----> |___________________________|
  624. | |
  625. | Parser term stack |
  626. char *NextFNS --------------> |___________________________|
  627. | |
  628. | Input file name stack |
  629. char *Heap2 ----------------> |___________________________|
  630. The "high-water mark" for NextFNS is stored in char *High2,
  631. and the "low-water mark" (to stretch a metaphor) for InF is stored
  632. in struct InFCtl *LowInF. These figures are used only to determine
  633. the maximum heap usage.
  634. AND FINALLY...
  635. Please send me any bug reports, flames, etc. I can be reached
  636. on Mind Link (604/533-2312), at any meeting of the Commodore
  637. Computer Club / Panorama (PAcific NORthwest AMiga Association),
  638. or via Jeff Lydiatt or Larry Phillips. I don't have the time
  639. or money to live on Compuserve or BIX, but my Usenet address is
  640. Charlie_Gibbs@mindlink.UUCP (...uunet!van-bc!rsoft!mindlink!a218).
  641. Charlie Gibbs
  642. 2121 Rindall Avenue
  643. Port Coquitlam, B.C.
  644. Canada
  645. V3C 1T9
  646. (TIGCC) Since, as far as we can tell, Charlie Gibbs is no longer
  647. maintaining A68k since 1991, you are better off filing a bug
  648. report to Kevin Kofler of the TIGCC team:
  649. Kevin@tigcc.ticalc.org (or kevin.kofler@chello.at)