Small Assembler User Notes June 10, 1989 COPYRIGHT NOTICE Copyright 1988 J. E. Hendrix All rights reserved. ASSEMBLER VERSION This diskette contains version 1.2 (revision level 14) of Small Assembler. Small Assembler is written in Small C primarily for use in processing Small C compiler output; nevertheless, it is a surprisingly capable assembler handling all of the 8086 family processors through the 80386 and their associated numeric processor extensions (NPXs). At this stage the Small Assembler runs quite slowly compared to Microsoft's latest assembler. But it is adequate for use with Small C, making it unnecessary to purchase a more expensive companion assembler. This assembler is essentially compatible with the Microsoft product. Either may be used with the Small C assembler. Differences are primarily: (1) many Microsoft directives are not supported (most notably the conditional assembly directives), (2) macros employ positional rather than named parameters, (3) not all of the Microsoft expression operators are supported, and (4) most of the expression operators in the C language are supported. THE DISTRIBUTION DISKETTE The Small Assembler files have been compressed into two ZIP files as follows: file contains ---------- --------------------------------------- EXECUTE.ZIP files needed to execute Small Assembler COMPILE.ZIP files needed to compile Small Assembler You must run PKUNZIP to unpack the ZIP files. Follow these steps: 1. Place the distribution diskette in drive A: (or B:) and make it the default drive. 2. Enter: A>PKUNZIP EXECUTE 3. Enter: A>PKUNZIP COMPILE Examples: A>PKUNZIP EXECUTE C:\SA unpack executable files to C:\SA A>PKUNZIP COMPILE C:\SA unpack source files to B: FILE LISTING The following files are included on the distribution disk(s): READ.ME This documentation. HISTORY History of Small Assembler revisions. AR.C Archive maintainer source. AR.EXE Archive maintainer. ASM.EXE Assembler. ASM.H Assembler header file. ASM1.C Assembler source, part 1. ASM2.C Assembler source, part 2. ASM3.C Assembler source, part 3. ASM4.C Assembler source, part 4. ASM.ARC Assembler library source archive. ASM.LIB Assembler library. ASMARC.LST Assembler library source archive list. ASMLIB.LST Assembler library object module list. 80X86.MIT Machine Instruction Table for all CPUs. CMIT.C Machine Instruction Table compiler source. CMIT.EXE Machine Instruction Table compiler. DUMP.C File dump utility source. DUMP.EXE File dump utility. MIT.H Header for Machine Instruction Table functions. NOTICE.H Version and copyright header. OBJ1.H Object file header, 1 of 3. OBJ2.H Object file header, 2 of 3. OBJ3.H Object file header, 3 of 3. STDIO.H Standard Small C Header. ASMCAL.BAT Compile & assemble one part of assembler, optionally link. CALIB.BAT Compile, assemble, and place module in ASM.LIB. MANUAL.TXT User's Manual DOCUMENTATION Since the manual is out of print it has been included on this diskette. To print it, copy the file MANUAL.TXT to your printer. USING THE ASSEMBLER Small Assembler reads an ASCII source file and writes an object file in the standard Microsoft OBJ file format. This makes the Small Assembler compatible with LINK which comes with most copies of DOS. In fact, Small Assembler has no linker of its own; so it must be used with the DOS linker. I understand that IBM quit including LINK with its latest versions of PC- DOS. This could be a problem if you don't have ready access to copy of it. The command line for invoking the assembler has the following format: ASM source [object] [-C] [-L] [-NM] [-P] [-S#] Command-line arguments may be given in any order. Switches may be introduced by a hyphen or a slash. The brackets indicate optional arguments; do not enter the brackets themselves. source Name of the source file to be assembled. The default, and only acceptable, extension is ASM. Drive and path may be specified. object Name of the object file to be output. It must have a OBJ extension to be recognized as the output file. Drive and path may be specified. If no object file is specified, output will go to a file bearing the same name and path as the source file, but with a OBJ extension. -C Use case sensitivity. Without this switch, all symbols are converted to upper-case. With this switch, they are taken as is; upper- and lower-case variants of the same letter are considered to be different. With or without this switch, segment, group, and class names are always converted to upper- case in the output OBJ file. Note: The .CASE directive may be included at the beginning of the source file to produce the same effect as this switch. -L Generate an assembly listing on the standard output file. If you do not want the listing to go to the screen, then provide a redirection specification (e.g., >prn or >abc.lst) to send it wherever you wish. -NM No macro processing. This speeds up the assembler somewhat. Macro processing is NOT needed for Small-C output files. -P Pause on errors waiting for an ENTER keystroke. -S# Set symbol table size to accept # symbols. Default is 1000. If an illegal switch is given, the assembler aborts with the message Usage: ASM source [object] [-C] [-L] [-NM] [-P] [-S#] The null switch (- or /) can be used to force this message. If the assembler aborts with an exit code of 1, there is insufficient memory to run it. Pressing control-S makes the assembler pause until another key is pressed, and control-C aborts the run with an exit code of 2. If the program contained errors, an exit code of 10 is returned and the output file is deleted. Press ENTER to resume execution after a pause because of an error. USING THE MIT COMPILER CMIT.EXE compiles the source machine instruction table (80X86.MIT) to obtain its object file (80X86.OBJ). This program is invoked by the command line: Usage: CMIT [-#] [-O] [-L] [table] The switches can be introduced by hyphens or slashes. The command line arguments have the following values: -# Highest numbered CPU to recognize: -0 => 8086 -1 => 80186 -2 => 80286 -3 => 80386 -O Output the indicated or default machine instruction table as an OBJ file. -L List the compiled machine instruction table. table Name of the Machine Instruction Table source file (default 80X86.MIT). The default and only allowed extension is MIT. A drive and path are allowed. If no switches are given, -L is assumed. If any switches are given, only the actions specified are taken. The object file created by CMIT must be linked into ASM.EXE. USING THE ARCHIVE MAINTAINER The archive maintainer AR.EXE collects text files into a single archive file. Modules (files that exist within the archive) can be extracted, new ones added, old ones replaced or deleted, and a list of the archive contents produced. The command line for invoking AR.EXE is: AR switch archive [list] switch The first argument is a required switch from the following set: -D Delete listed modules from the archive. -P Print listed, or all, modules on stdout. -T Table of contents of listed or all modules to stdout. -U Update the archive by adding/replacing modules from separate disk files (used to create a new library). If no file names are specified in the command line, they are obtained from stdin. -X Extract listed, or all, modules into separate files. archive The second argument is the name of the archive file. It must be complete with the filename extension. Drive and path are optional. list The third and subsequent arguments are module/file names. Use control-S to pause execution and control-C to abort the run. To extract all of the modules from the library archive enter: AR -X ASM.ARC SUGGESTIONS Phase errors are caught only at labels. So to be absolutely sure one doesn't slip by undetected, you should place a dummy label at the end of the last instance of each segment. HINTS FOR RECOMPILING THE ASSEMBLER Any changes to ASM.H will usually require the recompiling of every program source file that includes it. That is ASM1.C, ASM2.C, ASM3.C, ASM4.C, AND CMIT.C. Before linking ASM, be sure to run CMIT to create a new 80X86.OBJ containing the new #define constants. Otherwise, things won't match up properly. In any case, you must run CMIT to generate 80X86.OBJ before your first attempt to link the assembler. See ASMCAL.BAT for the commands to perform the compiling, assembling, and linking of the assembler. Each run of ASMCAL.BAT compiles and assembles one part of the assembler. For example, to compile and assemble ASM1.C enter ASMCAL ASM1 If all parts have not yet been compiled and asembled, or 80X86.OBJ has not been created by running CMIT.EXE, then you can skip the link step at the end by entering a control-C at the pause prompt. Pay careful attention to the order of the library files in the link command. Follow this order when composing your own link commands. MICROSOFT COMPATIBILITY If the behavior of Small Assembler in automatically generating ASO and OSO prefixes in 32-bit object files seems obscure and sometimes inefficient, it is not without reason. The actions taken are predicated on compatibility with the Microsoft object file processing utilities that will be coming down the pike in the future. My assumption was that if Microsoft did that way, they must have good reasons (well reasons anyway). Good or otherwise, any deviation is likely to create incompatibilities with future Microsoft software. In file ASM2.C the symbol MASM_xOS is defined. If this definition is deleted or commented out, then ASM will generate more efficient 32-bit code. James E. Hendrix 417 N. 11th Street Oxford, MS 38655