10. Using SMAL32
Part of
the SMAL Manual
|
On Unix systems (including Linux), SMAL32 is invoked by typing the command
smal32 [ -L ][ -D ][ -P <number> ][ -U <directory> ] <filename>
Where <filename> is the name of the assembly language file to be processed. Typically, the file name will end with the suffix .a indicating that it is an assembly language file (in fact, SMAL32 does not care what file name suffix is used). If no other versions of SMAL are in use, the name smal is frequently defined as an alias for smal32; this alias may also specify defaults for one or more of the command-line options.
The loadable or linkable object code resulting from the assembly will be produced on a file with a name based on <filename>, with any suffix such as .a or .txt removed. Regardless of whether a suffix was removed, a new suffix is added, .o (for object). For example, the command smal32 file.a will produce an object file named file.o.
The assembly listing will be produced on a file with names based on <filename>, with suffix removal above, and with the suffix .l (for listing) appended. For example, the command smal32 code will produce a listing file named code.l.
The -L command-line option suppresses generation of a listing. This will generally be used when the SMAL assembler is used as a linker, since the listing produced by linkage is generally near-useless.
The -D command-line option causes SMAL to dump the contents of the symbol table at the end of the assembly process. The dump, if produced, will be on a file named with a .d suffix and the same prefix as was used for the object and listing files (see Section 10.3). For example, the command smal32 -D file.txt will produce a dump file named file.d.
The -P command-line option sets the number of lines per page in SMAL listings. This defaults to 60 and must be larger than 5 to allow room for page titles and subtitles.
The -U command-line option sets the name of the directory to search for files to be included by the USE assembler directive (see Section 7.1). By default, only the directory containing the source file will be searched.
When SMAL32 is run, any errors that preclude assembly, such as improperly formed command line arguments, will cause SMAL to exit and output a diagnostic message prior to attemtpting to open or create any files. Any assembly errors will be noted in the listing and also noted with diagnostic error messages. The notes on assembly errors included in the listing contain the same diagnostic message, augmented by underlining the offending parts of the input line.
Each line of a SMAL listing file contains 4 fields; these are, from left to right, the location counter, the generated object code, the source line number and the assembly language source. Here is a fragment of a typical listing:
+000082: 01 02 03 84 B 1, #2, 1+(5-3)
+000085: 00000001 85 W 1, #2, 1+(5-3)
00000002
00000003
+000091: 41 27 22 5A 86 ASCII "A'", '"Z'
+000095: 41 27 22 5A 87 ASCII "A'", ('"'), ('X'+2)
Note that lines in listing files are long. If the source file is composed using an editing window 80 characters wide, as many coding standards recommend, you will need to open the listing in a significantly wider window. If the text of the source file is legible when printed on standrd letter-sized paper in portrait mode, the assembly listing generated from the same source will generally need to be printed in landscape mode to fit on the same size paper.
The location counter at the start of the above fragment was relocatable 8216. The leading plus in front of any value in the first two fields indicates that that value is relocatable; that is, that some constant, known to the loader, will be added to it. For the location counter, the value to be added is the relocation base — the location in memory where the loading of this object file begins. The relocation base is also added to the addresses of other parts of the same relocatable block of code. For external symbols and common blocks, the value to be added is the address of that external symbol or common block.
The location counter value is only given at the start of each line of assembly code and only when that line actually caused object code to be generated; consecutive bytes, halfwords, triple bytes and words will be shown without showing the value of the location counter again, so long as these are loaded consecutively in memory.
The second field above contains the object code generated, listed in hexadecimal, again, with a leading plus used to indicate relocation. In this example, the first line (line 84) generated 3 bytes of absolute object code, while the second line (line 85) generated 3 words of object code. All object code that would not fit on a line is printed on successive lines.
The third field is the source line number, printed in decimal; lines 84 through 87 are included above. The source code is set off from the line number by two spaces.
All error messages resulting from assembling a line of code are listed after that line (and after any generated object code). In addition, the offending parts of the input line are underlined, to the extent that the assembler is able to identify the source of the problem. The listing of a line containing errors is given below:
+0000C0: 00000000 12 W 0, UNFUNC(1)+UNDEF)
00000001
unbalanced parentheses ====== ======
undefined symbol
invalid function
Note in this example that the order of the error messages and the order of the errors on the input line is not necessarily the same. Furthermore, the underlining of the undefined identifier UNDEF has run into the underlining of the unbalanced parenthesis, so that it looks like only two errors are underlined.
When attempting to print an assembly listing, it is important to set the printer's font to a monospaced font such as Courier. That particular font is the classic typewriter font that was imitated by many first and second generation computer printers, while the VT100 font, if it is available, imitates the typical fonts found on third-generation display screens and terminal windows. Generally, font names containing mono or Mono as part of the name or as a name modifier are monospaced.
The symbol table dump produced by the SMAL32 -D option consists of the contents of the symbol table, one line per symbol, in almost random order. Standard sort programs can be run on the dump file to sort it in either numerical order by definition or alphabetical order by symbol, depending on the use to be made of it. The definiton file is formatted as legal SMAL code, so inserting a definiton file into another program will sometimes suffice to give the same symbols the same definitons they had in the first program.
Note that the linker shell script given in Section 8.7 includes example code to automatically sort the dump.