Simtel MSDOS - Coast to Coast

home *** CD-ROM | disk | FTP | other *** search

/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast2.iso / asmutil / chasm4.zip / CHASM.DOC < prev next >

Wrap

Text File | 1985-06-01 | 146KB | 5,545 lines

READ THIS BEFORE PRINTING!!!! This document has been formatted in a special way. Virtually all dot matrix printers have a condensed mode which prints 132 characters across a standard 8 1/2 inch page. When this file is printed out in condensed mode, the resulting printed pages can be cut down to 5 1/2 X 8 1/2 inches. The cut pages will fit nicely in the back of your DOS manual for storage. Typically, you can turn on this mode by sending a special control sequence to the printer from BASIC. For example, you can turn on the condensed mode of the IBM/Epson printer with the BASIC statement: LPRINT chr$(15). If your printer has such a condensed mode, turn it on now, before printing the rest of this document. (tm) CHASM Cheap Assembler for the IBM Personal Computer User's Manual (c) 1983 by David Whitman Version 4.00 David Whitman 136 Wellington Terrace Lansdale, PA 19446 (215) 641-7114 (days) (215) 362-8526 (evenings) Table of Contents Why CHASM?..................................................1 What can CHASM do?..........................................2 What WON'T it do?...........................................3 System Requirements.........................................4 Advanced and Subset CHASM...................................5 Modifying CHASM's I/O Defaults..............................6 Syntax.....................................................10 Labels.....................................................12 Operands...................................................15 Operand Expressions........................................20 Resolution of Ambiguities..................................23 Pseudo-Operations..........................................26 Macros.....................................................33 Structures.................................................41 Outside the Program Segment................................45 Running CHASM..............................................46 Error and Diagnostic Messages..............................50 Execution of Assembled Programs............................54 Notes for Those Upgrading to This Version of CHASM.........62 Miscellaneous and A Word From Our Sponsor..................65 ============================================================= Appendix A: Mnemonic List..................................70 Appendix B: Differences Between CHASM and TOA..............72 Appendix C: Description of Files...........................77 Appendix D: Bug Reporting Procedure........................78 Appendix E: Using CHASM on "Compatable" Systems............79 Compiled Version Order Form................................80 1 >>Why CHASM?<< Why go to the trouble to write an assembler, when one already exists? The IBM Macro Assembler is a very powerful software tool available off the shelf. It supports features such as macros, multiple segments, and linking to external procedures. Unfortunately, the cost of all this power is complexity. The Macro Assembler is so complicated that IBM warns beginners it is only suitable for "experienced assembly language programmers". For most users, this sophistication is more of a hindrance than an aid. Even when writing short, simple programs, the user is saddled with a set of confusing pseudo-ops only appropriate for large, multi-segment programs. Producing a fast loading executable file requires running three separate programs (MASM, LINK and EXE2BIN) before you can get down to testing. The macro assembler is totally unsuitable for use with BASIC. Although it is *possible* to produce machine language subroutines for BASIC with the Macro Assembler, the process is incredibly convoluted and confusing. To top it all off, the Macro Assembler costs an overpriced $125. CHASM is, I hope, a more reasonable compromise between power and accessibility. CHASM is simple to use and understand. Unlike the Macro Assembler, CHASM doesn't require a second LINK step to produce a working program. CHASM also produces fast loading programs without the use of the utility EXE2BIN. CHASM supports two different, simple mechanisms for getting machine language routines into BASIC, the most popular language for the IBM Personal Computer. Finally, the suggested payment for CHASM is a modest $40. A Note for Beginners: Before going on, you might find it useful to print and read the file PRIMER.DOC, included on your CHASM disk. PRIMER is a gentle introduction to assembly language, which will teach you some of the vocabulary and key concepts you will need to start out with. 2 >>What can CHASM do?<< CHASM is a tool for translating assembly language into the native machine language of the 8088 microprocessor. Using CHASM, you can write down easy to remember "mnemonics" which are then converted into the relatively incomprehensible series of ones and zeros that your PC prefers to work with. In addition to simple mnemonic translation (such as provided by the mini-assembler in DEBUG), CHASM provides a great many "convenience" features which make writing machine language much easier. CHASM allows you to define labels for branching, rather than requiring you to figure out offsets or addresses to jump to. CHASM also lets you give symbolic names to any constants or memory locations you use, to make your program easier to understand. You can instruct CHASM to make your file "BLOADable" so that BASIC can load it as a subroutine. A utility is also provided to convert machine language into BASIC "DATA" statements, so that BASIC can "POKE" routines into memory. CHASM has intelligent error and diagnostic messages which guide you in correcting mistakes and ambiguities in your program. A nicely formatted listing is produced during assembly, to help during debugging. In general, CHASM is designed to eliminate much of the confusion and dirty work involved in writing machine language for the IBM PC. Using CHASM, you can produce: 1. Lightning fast "stand-alone" programs. 2. Machine language subroutines for BASIC programs, both interpreted and compiled. 3. External procedures for Turbo Pascal (*) * Turbo Pascal is a product of Borland International. 3 >>What WON'T it do?<< In the interest of simplicity, CHASM has the following restrictions: 1. Multiple segment definitions are not allowed. CHASM assumes that your entire program fits in one segment, that the cs, ds, and es registers all point to this same segment, and that the ss register points to a valid stack area. An equivalent statement is that CHASM produces COM files, not EXE files. 2. Linking to Microsoft languages is not supported. You can't use CHASM to produce object modules for use with IBM/Microsoft Pascal or FORTRAN. 4 >>System Requirements<< Minimum system requirements to use CHASM are: IBM PC or true compatible (must emulate IBM BIOS) 128K of memory 1 disk drive 80 column display DOS 2.0 or later. Note the DOS 2.0 requirement. To provide *true* DOS 2 support, it was necessary to give up DOS 1 compatibility. If you're still using DOS 1, you'll need to upgrade to DOS 2.0 or later to use CHASM. Adding more memory will allow you to assemble larger programs. CHASM can take advantage of all available memory, up to a megabyte. CHASM will run faster if your source files and object files are on a hard disk or RAM disk. 5 >>Advanced and Subset CHASM<< CHASM is available in two flavors, Advanced and Subset. The two versions vary in their capabilities and method of distribution. The subset version is the budget release. It may be freely copied by individuals as "user-supported" software, and is available from user groups and bulletin boards across the country. Every time the subset runs, it prints a banner page suggesting a payment of $40 to the author. As its name suggests, Subset CHASM does not support all the features of Advanced CHASM. Advanced CHASM is the deluxe release. It runs twice as fast, and has a number of features not supported by the subset: macros conditional assembly include files operand expressions structures Advanced CHASM is only available directly from Whitman Software. Users who make the suggested $40 payment receive an upgrade to Advanced CHASM. Details, and an order blank are given at the end of this document. Throughout this document, features supported only by the advanced version will be marked as follows: ==>Advanced version only. Attempts to use these features in the subset version will generally result in error messages, with the advanced feature otherwise being ignored; however, unpredictable behavior could result in some instances. 6 >>MODIFYING CHASM'S I/O DEFAULTS<< CHASM supports the use of a configuration file, which can be used to override some of CHASM's I/O defaults. If you are willing to accept CHASM's defaults, you may skip this section - CHASM will work perfectly well without the file described below. The configuration process involves supplying a text file named CHASM.CFG on your default drive. You can create this file with any text editor or word processor. You have some freedom in where you put the configuration file. If CHASM.CFG is not found in the current directory, CHASM will also try the following paths: \CHASM\CHASM.CFG \CHASM.CFG The file should contain a series of text "switches" of the following form: /SWITCH, xx [, yy, zz,...] Where "/SWITCH" is a reserved word, listed below, and xx, yy, zz are numbers. The brackets around yy and zz indicate that these numbers are optional - don't put brackets in CHASM.CFG. Each switch should start a new line, and the switch and each of the numbers should separated by one or more blanks or commas. The following switches are implemented: /132 Printer 132 column mode. The numbers following this switch are the ASCII codes for the characters which cause your printer to go into condensed mode. You may specify as many characters as you like. If you don't provide this switch, CHASM will truncate source lines in listings to avoid going over 80 columns. You can also include characters to activate any special features of your printer you want CHASM to use during printing. Example: (for IBM printer) /132, 15 7 /80 Printer 80 column mode. Similar to /132, but the numbers represent the characters to return your printer to normal. Include the codes for any characters you want CHASM to send to your printer before returning you to DOS. The following example turns off condensed mode and causes a Form Feed on the IBM printer: /80, 18, 12 /FF Formfeed. A value of zero tells CHASM that your printer doesn't recognize ASCII 12 as a formfeed command. Any other value, and CHASM assumes that formfeeds will be recognized. The default is no formfeed character. If /FF is off, CHASM will simulate formfeeds with a series of linefeeds. However, most printers respond quicker to a formfeed than to multiple line feeds, so set /FF on if possible. Example: (on) /FF, 1 /PAGELEN CHASM assumes that there are 66 lines to each printed page. If you use different sized paper, enter the number of lines per page after this switch. Example: (European standard) /PAGELEN, 72 /LINES By default, CHASM will print 58 lines on each printed page, then skip over the perforation to the next page. You can change this number to suit your paper and personal taste. Example: /LINES, 50 /BEEP Enables/Disables audible warning when errors are discovered in your source program. A value of zero turns off beeping, anything else turns it on. The default is on. Example: (off) /BEEP, 0 8 /FG Foreground color. Users with color monitors may select a foreground color from the following list: 0 Black 8 Gray 1 Blue 9 Light Blue 2 Green 10 Light Green 3 Cyan 11 Light Cyan 4 Red 12 Light Red 5 Magenta 13 Light Magenta 6 Brown 14 Yellow 7 White 15 High Intensity White Example: (Magenta) /FG, 5 /BG Background color. Selections 0-7 above are available. Example: (Cyan) /BG, 3 /DWIDTH When listing to a disk file, CHASM normally truncates listing lines to 80 columns to prevent wrap-around when viewing the file. In some instances, such as disk-based print spooling with DOS's PRINT utility, you may wish to override this truncation. You can enter a new truncation limit after this switch. Example: (128 column lines) /DWIDTH, 128 /PATH Path Stratagy. Affects the way CHASM constructs the default file names for list and object files. If /PATH is set to 0 (the default), any drive or path specified on the source file name will be included in the default file names. If /PATH is set to anything else, path and drive info are removed, thus putting the default list and object files in the current directory of the logged drive. The following table shows how this works: /PATH | Source filename | Default object file ------|-------------------|------------------------- 0 | a:\chasm\test.asm | a:\chasm\test.com 1 | a:\chasm\test.asm | test.com 9 /PATH only affects how the default file names are constructed - CHASM won't edit filenames that you explicitly type in. /TIMER Enables/Disables reporting of total assembly time. A value of 0 turns off timing, anything else turns it on. The default is off. This switch is used internally at Whitman Software to benchmark new versions of CHASM. A sample CHASM.CFG file, suitable for use with the IBM dot matrix printer, is included on your CHASM distribution disk. 10 >>Syntax<< CHASM accepts a standard DOS text file for input. Lines may be any combination of upper and lower case characters. CHASM does not distinguish between the two cases: everything except single quoted strings are automatically converted to upper case during the parsing process. Thus, BUFFER, Buffer, buffer, and bUFFer all refer to the same symbol. The characters blank ( ), comma (,), single quote (') semi-colon (;) and TAB are reserved, and have special meaning to CHASM (see below). Each line must be no more than 80 characters long and have the following format: Label Operation Operand(s) ;comment The different fields of an input line are separated by the delimiters blank ( ), comma (,) or TAB. Any number of any delimiter may be used to separate fields. Explanation of Fields: Label: A label is a string of characters, beginning in column 1. Depending on the operation field, the label might represent a program location for branching, a memory location, or a numeric constant (see the section titled "Labels" for more on this topic). To ensure that CHASM can distinguish between labels and numeric constants, the first character of a label must *not* be a number (0-9), plus sign (+) or minus sign(-). Anything beginning in column 1, except a comment, is considered a label. Operation: Either a pseudo-op (see the section with the same name) or an instruction mnemonic as defined in "The 8086 Book" by Rector and Alexy. A list of acceptable mnemonics is given in Appendix A. Note 1: Except as modified below,"The 8086 Book" is the definitive reference for use with CHASM. Note 2: There are several ways to resolve some ambiguities in 8086 assembly language. Please read page 3-285 of The 8086 Book, and "Resolution of Ambiguities" in this document. 11 Operand(s): A list of one or more operands, as defined in the section titled "Operands", separated by delimiters. Comment: Any string of characters, beginning with a semicolon (;). Anything to the right of a semicolon will be ignored by CHASM. Note that except for the case of an operation which requires operands, or the EQU pseudo-op which requires a label, all of the fields are optional. The fields MUST appear in the order shown. 12 >>Labels<< The symbol in the label field of an input line can be interpreted in four different ways by CHASM: 1. A program location which may be branched to. 2. A memory location for data storage. 3. An equated symbol, which takes the place of a numeric constant. 4. A macro name, which takes the place of a series of frequently used source code lines. The default interpretation of a symbol is a program location for branching. This default is modified by the presence of one of the following pseudo-ops in the instruction field: DB, DM, DS, or DW: Normal: The symbol is a memory location. In a Structure: The symbol is a numeric constant. EQU: Normal: The symbol is a numeric constant. Memory Option: The symbol is a memory location. MACRO: The symbol is a macro name. A given symbol may have only ONE of the above interpretations! Attempts to branch into a memory location or an equated symbol will result in error messages. Similarly, CHASM will not allow you to treat program code as a data area. Examples: TEXT DB 'Hit any key when ready' ;memory location MOV AL,TEXT ;ok JMP TEXT ;wrong! LOOP MOV AX,CX ;program location JMP LOOP ;ok MOV AX, LOOP ;wrong! 13 If for some arcane reason you *need* to branch into a data area, you can fool CHASM by placing a label on an otherwise blank line, immediately before the data area. Example: JNZ NPU RET NPU ;dummy label for jump DB D8H, 00H ;an 8087 instruction If you have a masochistic urge to crash your system by writing self-modifying code, there are at least two ways you can defeat CHASM's injunction against using program code as a data area. The first way is to use DS to declare zero bytes of storage immediately before the code you want to access. A label on the null DS will have the same offset as the immediately following code. Example: MOV JUNK1, 9090 ;change endless loop to NOP JUNK1 DS 0 JUNK JMP JUNK A sneakier approach is to load the OFFSET of a program location into a register, then use the register for indirect addressing. Using the optional displacement field, you can even address the middle of an instruction. Examples: MOV BX, OFFSET(CALL) MOVB 1[BX], 00H ;change interrupt number in code CALL INT 0 In general, I cannot recommend trying to get around CHASM's type restrictions. If you find yourself in a situation where it seems necessary to fool CHASM, there's probably a safer, more direct way to legally program what you're trying to accomplish. Labels can be up to 80 characters long, but only the first 15 characters are significant. For example, CHASM considers the following labels identical: VERYLONGLABELOVER15CHARACTERS VERYLONGLABELOVER 14 To avoid ambiguity, a given string can legally appear in the label field of only ONE statement. If the same string appears on more than one instruction, all instances after the first will receive an error message. Remember that labels are only significant to 15 characters, and if the first 15 characters are identical, an error will occur. TWO EQU '2' ;first use is ok TWO PROC FAR ;wrong! symbol already defined CHASM has a number of reserved strings which are "predefined" in the symbol table, and will generate an error message if used as labels. All the two letter register names are reserved, as are the indirect address mode combinations. The only other reserved strings are the words "NEAR" and "FAR", and the symbol "$". Examples: AX MOV AX, DX ;wrong! (register name) [DI] ADD AX, BX ;wrong! (indirect address) FAR CALL GETINPUT ;wrong! (reserved word) $ SUB AX, DX ;wrong! (reserved word) 15 >>Operands<< The following operand types are allowed. 1. Immediate data: A number, stored as part of the program's object code. Immediate data are classified as either byte, expressible as an 8 bit binary integer; or word, expressible as a 16 bit binary integer. If context requires it, CHASM will left-pad byte values with zeroes to convert them to word values. Attempts to use a word value where only a byte will fit will cause an error message to be printed. Immediate data may be represented in 9 ways: A. An optionally signed decimal number in the range -32768 to 32767. Examples: MOV AL,21 MOV BX,-6300 B. A series of up to 4 hex digits, followed by the letter H. The first digit must be non-alphabetic, i.e. in the range 0-9, to allow CHASM to distinguish between numbers and symbols. If necessary, a leading zero, which does not count in the four allowed digits, may be added to fulfill the non-alphabetic condition. Examples: ADD CX, 0B123H ADD DL, 12H C. A series of up to 16 binary digits, followed by the letter B. Examples: MASK EQU 00000111B MOV AL, 10000000B D. A symbol representing types A, B or C above, defined using the EQU pseudo-op. Examples: MASK EQU 10H MAX EQU 1000 AND CL,MASK SUB AX,MAX 16 E. The offset of a label or storage location returned by the OFFSET operator. OFFSET always returns a word value. OFFSET is used to get the address of a named memory location, rather than its contents. Example: MOV DI,OFFSET(BUFFER) BUFFER DS 0FFH F. The ASCII value of a printable character, represented by the character enclosed in single quotes ('). Thus, the following lines will generate the same object code: MOV AL,41H ;ascii code for 'A' MOV AL,'A' G. ==>Advanced version only: Labels within structures become immediate operands whose values equal their offset within the structure. See the section titled "Structures" for more detail and examples. H. ==>Advanced version only: The length of a structure, returned either by the LENGTH operator, or simply the structure's name. See the section titled "Structures" for more detail and examples. I. The number of bytes counted by the COUNT pseudo-op, returned by the LENGTH operator on the COUNT's label. Example: HLP_MSG COUNT HLP_TXT DB 'Hit F10 for Help...' cr lf ENDC MOV CX, LENGTH(HLP_MSG) ;length of message J. ==>Advanced version only: An expression that evaluates out to type Immediate. Examples: MOV AX, (3+2)*5 MOV DX, MEMLOC1-MEMLOC2 See the "Operand Expressions" section for more details. 17 2. Register Operands: One of the 8088's internal registers. A. An 8 bit register from the following list: AH AL BH BL CH CL DH DL B. A 16 bit register from the following list: AX BX CX DX SP BP SI DI C. A segment register from the following list: CS SS DS ES 3. Memory Operands: The contents of a memory location addressed by one of the following methods. Note that none of the memory addressing options specifies whether a byte or word operand is being referenced. See the section titled "Resolution of Ambiguities" for more on this topic. All memory operands can optionally be proceded with a segment overide to specify the segment register to be used in accessing memory. The overide takes the form of a segment register, followed by a colon, followed by the memory operand. No intervening delimiters are allowed. Examples: MOV AX, ES:[80H] ;80H into the extra segment MOV CS:[DI], SI ;indirect with DI in the code segment Segment overides are also discussed in the section titled "Resolution of Ambiguities". A. Direct address. 1. A number, or other immediate operand, enclosed in brackets, indicating an offset into the data segment. Example: BUFFER EQU 5A5AH MOV BH,[BUFFER] MOV [80H],DI 18 2. A symbol, defined to be a variable (i.e. a named memory location) using the EQU pseudo-op. Example: FCB EQU [80H] MOV DI,FCB 3. A symbol, defined to be a variable by its use on a storage defining pseudo-op. Examples: MOV AX,FLAG MOV DATE,BX FLAG DS 1 DATE DB 31 4. The special symbol '$'. $ returns an address of value equal to the current setting of CHASM's location counter. This address can be used as either a memory location, or a program location for branching. Used by itself, $ has little utility, but it is a very powerful tool when used in expressions. Example: MOV AX, $+4 ;get the byte after this instruction 5. ===> Advanced version only: An expression that evaluates out to type address. Example: MOV AX, buffer+3 BUFFER DS 20 See the "Operand Expressions" section for more details. B. Indirect Address: The address of the operand is the sum of the contents of the indicated register(s) and a displacement. The register, or sum of registers, are enclosed in square brackets: [] The displacement is optional, and takes the form of an immediate operand, placed without intervening delimiters to the left of the first bracket. Immediate data written as decimal numbers, with values between 127 and -128 generate a signed 8 bit offset. Values outside this range, or those expressed in some other manner generate 16 bit offsets. 19 The following indirect modes are provided: 1. Indirect through a base register (BX or BP). Examples: ENTRYLENGTH EQU 6 MOV AX, ENTRYLENGTH[BP] MOV DL, -2[BX] MOV CX, [BP] MOV 9A9AH[BX], AX 2. Indirect through an index register (DI or SI). Examples: MOV [DI], CX MOV CX, -5[SI] 3. Indirect through the sum of one base register and one index register. Examples: MOV [BP+DI], SP ;note that no spaces are MOV BX, 10H[BX+SI] ;allowed within the MOV CL, [BP+SI] ;brackets. MOV DH, -2[BX+DI] 4. Labels A label on most instructions may be used as an operand for call and jump instructions. See the section titled "Labels" for more information. Examples: START PROC NEAR CALL GETINPUT JMPS START ENDP GETINPUT PROC NEAR 5. Strings A string is any sequence of characters (including delimiters) surrounded by single quotes ('). Example: DB 'Copyright May 15,1982' 20 >>Operand Expressions<< ===> Advanced version only. Advanced CHASM can perform arithmetic calculations at assemble time, to help you generate memory addresses and immediate data constants. The following operand types can participate in operand expressions: immediate data program locations data storage locations Actually, for the purpose of expression evaluation, CHASM treats both program locations and data storage locations identically. Thus, really only two types of operands are allowed in expressions: immediate and address. Symbols standing for immediate operands must have been defined prior to use in an expression, or you may get Phase Errors (see the error message section for a discussion on this topic). You should put all your EQU and STRUC pseudo-ops at the beginning of your program, before any machine instructions. The following arithmetic operators are available: + addition - subtraction * multiplication / integer division Note that / performs *integer* division. 5/2 evaluates to 2. The normal rules of precedence apply. To force evaluation contrary to normal precedence, you can use parenthesis: (). MOV AX 2+5*3 ;means mov ax, 17 because * outranks + MOV AX, (2+5)*3 ;means mov ax, 21 21 No delimiters can appear within an expression. If you separate the parts of an expression with delimiters, CHASM will try to interpret each part as a separate operand. MOV [BX], BUFFER + 3 ;WRONG!! MOV [BX], BUFFER+3 ;ok The type of an operand expression is determined by the individual operand types that are combined within it. In evaluating each operation in an expression, the result type follows this rule: If the two operand types are the same, the result type is IMMEDIATE. If the two operand types are different, the result type is an ADDRESS. In expressions, both program locations and data storage locations are considered identical. An expression which evaluates to type address can be used in either a MOV or a JMP. The result type of a complicated expression is determined by replacing individual binary operations with their result, and evaluating the (simpler) expression thus formed, following the above rules. Here's a program fragment with some expressions, and a discussion of their types and significance: EXPSAMPLE PROC NEAR MOV AX, 3+5 ;immediate, calculated value MOV DX, STRING-END ;immediate, length of string MOV STRING+5, 'A' ;address, third byte of string JMP EXPSAMPLE+100H ;address, used as program loc. JMP STRING+100H ;valid address syntax, but silly STRING DB 'MESSaGE' ;data area END ;marks position of end of string The special symbol '$' returns the current value of CHASM's location counter for use in expressions. $ is of type address. Thus, $-1 is the address of the byte immediately prior to the instruction currently being assembled. 22 The rules for typing expressions were set up to produce the "most useful" result type, taking a guess as to why one would want to do a given calculation. If the type isn't what you have in mind, you can coerce CHASM using square brackets or the OFFSET function: MOV AX, 3+5 ;immediate MOV AX, [3+5] ;coerced to address MOV DX, $+4 ;address MOV DX, OFFSET($+4) ;coerced to immediate Under certain circumstances, CHASM can get confused when you use OFFSET or LENGTH functions in expressions. The problem occurs if the expression starts with a function, and ends with a close parenthesis: MOV AX, OFFSET(BUFFER)*(3+2) ;will be misinterpreted CHASM will try to interpret this as the offset of "BUFFER)*(3+2", and you'll get the error message "Illegal or undefined argument for OFFSET". The solution is to enclose the whole works in parenthesis, to force CHASM to recognise it as an expression: MOV AX, (OFFSET(BUFFER)*(3+2)) ;correct 23 >>Resolution of Ambiguities<< The language defined in "The 8086 Book" contains a number of ambiguities which must be resolved by an assembler. This is discussed throughout the book, but pages 3-285 and 3-286 specifically cover this topic. CHASM's solutions of these problems are discussed in this section. A. Memory references: When one specifies the address of a memory location, it is unclear how large an operand is being referenced. An operand might be a byte, or a word. 1. If a register is present as an operand, it is assumed that the memory operand matches the register in size. An exception to this rule are the shift and rotate instructions, where the CL register is used as a counter, and has nothing to do with the size of the other operand. Examples: MOV MASK,AX ;mask is a word MOV DH,[BX] ;BX points to a byte NEG [SI] ;error, operand of unknown size SHR FLAG,CL ;error, flag is of unknown size 2. If no register is present, (or if the only register is CL being used as a counter) the size of the memory operand is specified by adding the suffix "B" or "W" to the instruction mnemonic. Examples: NEGB [SI] ;SI points to a byte SHRW FLAG,CL ;flag is a word MOVW MASK,0AH ;mask is a word MOVB MASK,0AH ;mask is a byte MOVW MASK,9A9AH ;must specify size even though ;immediate operand implies word MOVB DH,[BX] ;error(!), register already ;specifies size 24 B. Indirect Branching. The 8088 supports two flavors of indirect branching: intra, and intersegment. A register is set to point at a memory location which contains a new value for the program counter, and in the case of intersegment branching, a new value for the CS register as well. The syntax of "The 8086 Book" does not specify which flavor of branch is being invoked. CHASM adds the suffixes "N" (for near, or intrasegment) and "F" (for far, or intersegment) to the indirect CALL and JMP mnemonics. Examples: CALLN [BX] ;intrasegment call JMPF [DI] ;intersegment jump JMP [BP] ;error, unspecified flavor C. Long and Short Jumps Two types of relative jumps are supported by the 8088: short (specified by a signed 8 bit displacement) and long (specified by a 16 bit displacement). Both are implemented in CHASM as a jump to a label. The short jump is specified by mnemonic JMPS, in accord with the IBM disassembler, but not with The 8086 Book, which uses JMP. Since one of the displacement bits is used to indicate direction, only seven are left to express the magnitude of jump. JMPS (and similarly, all the jump on condition instructions) is thus limited to branching to labels within a range of -128 to +127 bytes. CHASM reserves mnemonic JMP for the long jump. JMP may be used to jump anywhere within the program segment, but the object code generated is less compact than that from JMPS. Examples: START PROC NEAR JMPS END ;short jump JMP START ;long jump END ENDP 25 D. Instruction Prefixes. The 8088 supports three instruction prefixes: 1. SEG: segment override. An alternate segment register is specified for a reference to memory 2. REP, REPE,REPNE,REPZ,REPNZ: repeat. A string primitive is repeated until a condition is met. 3. LOCK: Turns on the LOCK signal. Only useful in multi-processor situations. SEG is implemented as a modifier attached to a memory operand. If you want to overide the default segment register for a memory access, precede the memory operand with the segment register followed by a colon. Examples: MOV AX, ES:FLAG ;flag is in the extra segment MOV CS:[100H], DX ;offset 100H in the code segment The other prefixes are implemented as separate instructions. They appear on a separate line, immediately before the instruction which they modify. For compatability with earlier versions of CHASM, you can also specify segment overides on a separate line, using the mnemonic SEG. Examples: REP MOVSB ;move bytes until CX decremented to 0 SEG SS MOV AX,BUFFER ;buffer is in the stack segment LOCK MOV [8FFH], AX ;lock bus to ensure data is transferred ;before other processors try to access it Note for 8087 users: You may get unexpected results using the separate instruction form of SEG on 8087 instructions. Use the operand modifier form for segment overides on 8087 instructions. (CHASM version 4.01 will have 8087 support) 26 >>Pseudo-Operations<< The following pseudo-ops are implemented: A. BSAVE: Generate object code in BSAVE format. Instructs CHASM to build a header in the format of BASIC's BSAVE command. The resulting object code file may be BLOADed by BASIC programs. No operands are required, and the pseudo-op may appear anywhere within the source code. Example: ORG 0 ;no psp SUBRT PROC FAR ;subroutine for BASIC program BSAVE ;make BLOADable object file B. COUNT ...ENDC: Count bytes. Instructs CHASM to count the number of object code bytes generated between COUNT and ENDC. Both machine instructions and pseudo-ops can appear within the COUNT block. If a label appears on the COUNT, it becomes an immediate operand of value equal to the number of bytes counted. Neither COUNT or ENDC require any operands. COUNTs cannot be nested. (COUNT and ENDC are supported mainly for compatibility for earlier releases. Now that expressions are available, you can get exactly the same result by subtracting two labels, one on either side of the area to be COUNTed.) It is *strongly* recommended that the immediate operands generated by COUNT be accessed via the LENGTH function, which unambiguously forces the "immediate" type on CHASM's first pass. If you do not use the LENGTH function, forward references to a COUNT may cause phase errors. (See Phase Error in the Error Message section.) Example: (next page) 27 MESSAGE COUNT MSG_TXT DB 'This utility requires DOS 2.0!' beep cr lf ENDC MOV SI, OFFSET(MSG_TXT) MOV DI, OFFSET(BUFFER) MOV CX, LENGTH(MESSAGE) REP MOVSB ;move message into buffer C. DB: Declare Bytes Memory locations are filled with values from the operand list. Any number of operands may appear, but all must fit on one line. Acceptable operands are immediate data, or strings enclosed in single quotes ('). DB interprets strings as a series of ASCII bytes. If a label appears, it is redefined as a memory location, and the data area may be referred to using the label, rather than an address. Examples: MOV AX,MASK MASK DB 00H,01H STG DB 'A string operand' CHASM generates an error message ("Data too large") if word operands (such as OFFSETs, or numbers greater than 255) are found in the DB operand list. DW should be used for declaring words. D. DM: Declare Multiple Bytes Used to declare blocks of storage, the number of bytes declared being the product of two immediate operands. If only one operand is present, the other operand is assumed to equal one. (DM is supported mainly for compatibility with earlier releases. Now that expressions are available, you can accomplish the thing by using DS with an expression for the immediate operand.) 28 As with DB, any label is redefined as a memory location. To save space, the object code does not appear on the listing. It is anticipated that this pseudo-op will be used in conjunction with STRUC, to declare structured storage. Example: DM LENGTH(MAILIST) 500 ;mailing list with 500 entries E. DS: Declare Storage Used to declare large blocks of identically initialized storage. The first operand is required, a number specifying how many bytes are declared. If a second operand in the form of a number 0-FFH appears, the locations will all be initialized to this value. If the second operand is not present, locations are initialized to 0. As with DB, any label is redefined as a memory location. To save space, the object code does not appear on the listing. Examples: DS 10 ;10 locs initialized to 0 DS 100H,1AH ;256 locs initialized to 1AH F. DW: Declare Words Used to unambiguously assign a word of storage for each item in the operand list. Any number of immediate operands may appear, but all must fit on one line. As with DB, any label is redefined as a memory location. Example: DW 0012H, FFFFH ;four bytes declared G. EJECT: Begin New Print Page When listing is enabled, causes CHASM to move to the top of the next page in printed listings. Has no effect on listings sent to the screen or to disk. 29 H. EJECTIF: Conditional Page Break Requires one immediate operand. If listing is enabled and fewer than that many lines are left on the current page of a printed listing, CHASM will move to the top of the next page. If you put an appropriate EJECTIF at the beginning of each procedure or section of your programs, CHASM will keep them in one piece. Like EJECT, EJECTIF has no effect on listings to the screen or disk. Example: EJECTIF 20 ;following procedure is 20 lines long I. ENDC: End of Count See COUNT (above) for details. J. ENDP: End of Procedure See PROC (below) for details. K. ENDSTRUC: End of Structure ==>Advanced version only. See STRUC (below) for details. L. EQU: Equate Used to equate a symbolic name with a number. The symbol may then be used anywhere the number would be used. Use of symbols makes programs more understandable, and simplifies modification. An alternate form of EQU encloses the number in square brackets: []. The symbol is then interpreted as a memory location, and may be used as an address for memory access. This version is provided to allow symbolic reference to locations outside the program segment. Examples: MOFFSET EQU 0B000H MONOCHROME EQU [0000H] 30 Warning: Difficult to debug errors may result from using a ======> symbol prior to its being defined by EQU. You are strongly urged to group all your equates together at the beginning of programs, before any other instructions. See "Phase Error" in the Error Message section. M. IFXX... [ELSE]... ENDIF: Conditional Assembly ===> Advanced version only. CHASM's conditional assembly pseudo-ops can be used to cause macros to expand differently according to the parameters supplied on the invocation. Eight different IF pseudo-ops are provided, to allow testing for (in)equality, relative size, and (non)existence of parameters. For more details and examples, see the Macro section of this document. N. INCLUDE: Include file ==>Advanced version only. INCLUDE requires one string operand, a filename enclosed in single quotes. If desired, you can specify a drive and/or a path as part of the filename. The contents of the specified file are logically inserted into the source file at the point where the INCLUDE appears. INCLUDEs cannot be nested: an error message will be printed if the specified file itself contains an INCLUDE. Example: INCLUDE '\ASM\STDIO.HDR' ;bring in standard library O. LIST: Enable listing output Output to the list device is enabled, presumably after a NOLIST was encountered. No operands required. 31 P. MACRO ...ENDM: Macro Definition ==> Advanced version only. Declares a macro. MACRO requires no operands, and signals CHASM that the following lines constitute a macro definition, and are to be stored for later use, rather than assembled in place. A label is required on the MACRO statement to name the defined macro. ENDM terminates the macro definition, and requires no operands. For more information and examples, see the section titled "Macros". Q. NOLIST: Disable listing output Normal output to the list device is disabled. Error messages are listed as usual. No operands required. R. ORG: Origin Allows direct manipulation of the location counter during assembly. By default, CHASM assembles code to start at offset 100H, thus leaving room for the program segment prefix normally built by COMMAND or DEBUG. In situations where no PSP is provided, such as routines to be called from BASIC, you should override this default with ORG, or incorrect assembly may result. ORG requires one operand, a number between 0 and FFFFH, which represents the new setting of CHASM's location counter. Although the location counter may be reset anywhere within a program, generally this pseudo-op should be used before any machine executable instructions for meaningful results. Example: ORG 0 ;Code will be assembled for starting ;offset of 0 32 S. PROC ...ENDP: Procedure Definition Declares a procedure. One operand is required on PROC, either the word NEAR, or the word FAR. This pseudo-op warns CHASM whether to assemble returns as intra (near) or intersegment (far). Procedures called from within the program being assembled should be declared NEAR. Generally, all others should be FAR. ENDP terminates the procedure, and requires no operands. If a RET is encountered outside of a declared procedure, an error occurs. Procedures may be nested, up to 10 deep. Example: MAIN PROC FAR ... ... ;body of procedure ENDP T. STRUC ...ENDSTRUC: Structure Definition ==> Advanced version only. Declares a structure. STRUC requires no operands, and signals CHASM that the following lines constitute a structure template, and not actual storage declaration. If a label appears on the STRUC, the label is equated with the length of the structure. ENDSTRUC terminates the structure definition, and requires no operands. Inside the structure, storage defining pseudo-ops behave somewhat differently. See the section titled "Structures" for more information. Example: DIRENTRY STRUC ;disk directory entry NAME DS 8 EXT DS 3 ATRIB DS 1 RESERVED DS 10 TIME DS 2 DATE DS 2 START DS 2 SIZE DS 4 ENDSTRUC 33 >>Macros<< ==>Advanced version only. Macros are an advanced feature. Beginners may wish to skip this section until they become more experienced with CHASM and assembly language programming. A. Introduction Macros are a shorthand way of writing frequently used sections of code. Using macros, you can write a code fragment once, then any time you want to use it, just reference it by name. Once you define a macro and give it a name, anywhere CHASM sees the name will be automatically "expanded" into the previously defined code. For example, suppose you were writing a large program, and at the beginning of each subroutine you pushed all the general purpose registers onto the stack to save their contents. Every subroutine would start out something like this: push ax ;save register contents push bx push cx push dx Before long, you'd get pretty sick of writing the same thing for each subroutine. Macros are a way to put some of the boring, repetitive nature of assembly language into the hands of the assembler, freeing you up for the more creative aspects. Here's how you define a CHASM macro to take the place of this code fragment: savestate macro push ax ;save general purpose registers push bx push cx push dx endm 34 Note the MACRO and ENDM statements. These signal to CHASM that the enclosed code is a macro definition to be saved for later use, rather than code to be assembled at this point in your program. The MACRO statement also gives a name (SAVESTATE) to the macro, which will take the place of the stored code. Now, at the beginning of each subroutine you can just write "SAVESTATE" when you want to push the general purpose registers. Here's an example: get_input proc near savestate ... ... endp Given the previous macro definition, the above example is *exactly* equivalent to: get_input proc near push ax push bx push cx push dx ... ... endp The only difference is that less busy work is required on your part. Macros are NOT subroutines! Subroutines are coded once, then called within your program at run time. Macros are expanded in-line at assembly time, and the code is inserted into your program at the invocation point. If you invoke the macro 20 times in your program, you'll end up with 20 copies of the macro code. 35 Although this does waste some memory space, you save execution time by eliminating the subroutine call and return process. At a minimum, it takes 32 machine cycles to call a subroutine. The four instruction macro given above requires 40 cycles to execute. If it were coded as a subroutine, the time to execute it would almost *double*. Macros trade off space for speed. B. Macro Parameters CHASM's macros allow 9 user defined parameters, which are evaluated at expansion time. The parameters work just like those in DOS batch files. Here's an example of a macro with one parameter. PRINT calls DOS function 9 to print a string on the console. A parameter is used to specify the name of the string to be printed: print macro mov ah, 09H ;specify print string function mov dx, offset(%1) ;point to string int 21H ;call DOS endm Given this definition, when CHASM sees a line like: print title The following code gets inserted in its place: mov ah, 09H mov dx, offset(title) int 21H Note how the "%1" in the macro definition got replaced by "title" which was put as an operand on the invocation of the macro. You can put up to 9 operands onto a macro invocation, and they will be substituted for the dummy parameters %1 through %9. 36 If you put a label on a macro invocation, two things happen. As usual, the label represents a program location for branching, with offset equal to the beginning of the expanded macro. You can branch into the expanded macro by using the label as an operand on a jump or call instruction. In addition, if the special dummy parameter "%0" is used in the macro definition, it is replaced with the label text when the macro is expanded. This feature is provided to facilitate writing loops within macros. If you fail to provide an operand for any dummy parameter used in the macro definition, CHASM substitutes a null string of length zero. To leave one parameter blank, but provide replacements for parameters with higher numbers, use the special operand "%B" for the one you want blank. For example: def_mem macro %1 db %2, %3 endm def_mem twobytes, 128, FFH def_mem %B, 'Hit any key when ready...' Expands to: twobytes db 128, FFH db 'Hit any key when ready...' C. Macro Nesting Macro invocations can be nested, up to 10 deep. Invocations are maintained on a stack, and each invocation has it's own set of parameters. CHASM does not check for recursive macro calls. If you call a macro from within itself, it's quite possible to get caught in an endless loop. This can also happen indirectly, where a macro invokes another macro, which ends up calling the first. If you get caught, you can escape by hitting Ctrl-Break. Experienced programmers can use macro recursion, along with expressions and conditional assembly, to create some really elegant macros. However, this is definitely not for beginners or the faint of heart. Enter at your own risk. 37 D. Conditional Macro Expansion This advanced feature allows you to write general purpose macros which expand in different ways based on the parameters used on the invocation. For example, suppose you wanted to write a macro to do operating system calls. Many of the DOS functions just load the function number into AH, then call DOS with an interrupt. Here's a macro to do this: doscall macro mov ah, %1 int 21H endm Given the above definition, "DOSCALL 1" will expand into a call to DOS function #1, keyboard input. Unfortunately, not all DOS calls are quite so simple. For example, the call for printing a string to the console requires that the offset of the string be loaded into DX. Different system calls are going to require somewhat different handling. One approach would be to write separate macros for each function. However, with 87 different functions in DOS 2, this starts to get unwieldy. A more general approach is to incorporate some "intelligence" into the macro, and let it expand differently for different DOS functions. Here's a slightly more general macro, which loads DX whenever the "print string" function is requested: doscall macro mov ah, %1 ife %1 9 mov dx, offset(%2) endif int 21H endm 38 "IFE" is short for "If Equal". The "IFE" and "ENDIF" bracket a line of macro code which will be included during expansion only if the "IFE" statement is satisfied. In this example, the MOV DX statement will be included only if the first parameter is equal to 9. The enclosed line is indented in this example to help show the structure of the macro, but indentation is not required. Given the above definition, "DOSCALL 1" expands to only two lines: mov ah, 1 int 21H However, "DOSCALL 9, STRING" expands to three lines: mov ah, 9 mov dx, offset(string) int 21H CHASM supports eight different conditional test statements. They are: IFE "if equal" IFNE "if not equal" IFGT "if greater than" IFGE "if greater than or equal" IFLE "if less than or equal" IFLT "if less than" IFB "if blank" IFNB "if not blank" Most of the conditionals take two operands, and perform a comparison. The operands are evaluated, and their values are compared according to the condition being tested. Strings are compared in the normal alphabetical order sense. Examples: IFE 15, 0FH ;is true IFGT 'ABCD' 'EFGH' ;is false IFLE 20H, 128 ;is true IFB and IFNB require only one operand, which should be a dummy parameter. These conditionals test whether the parameter was left "blank" or if a replacement was provided on the invocation. 39 You can place as many lines as you like between an IF statement and the ENDIF. All will be included if the condition tested is true, and none will be included if it's false. An optional "ELSE" construct is also provided. Statements after the ELSE get included only if the tested condition is false. CHASM's conditional assembly syntax can be summarized as follows: IF..... ;if statement with parameter(s) s1 ;statements included if true s2 ; " " " " ELSE ;end of "true" option, begin "false" s3 ;statements included if false s4 ; " " " " ENDIF ;end of conditional assembly IF statements can be nested, up to 10 deep. During nesting, CHASM assumes that ELSEs are paired with the latest unfinished IF statement. For example: example macro ife %1, 1 db 'Outer IF is true' ifb %2 'Inner IF is true' else 'Where do I belong?' endif endif "EXAMPLE 1, 5" expands to: db 'Outer IF is true' db 'Where do I belong?' But "EXAMPLE 2" produces no expansion at all. This is easiest to follow if you use "structured" indenting when writing the macro, as in the example above. Remember, however, that CHASM ignores indenting and follows the "latest unfinished" rule in figuring out which IF gets the ELSE. Don't fool yourself with improper indentation. 40 E. Final Notes: The conditional assembly pseudo-ops are not restricted to use only in macros, although there aren't that many useful non-macro applications. CHASM won't recursively expand parameters. If you use a dummy parameter symbol as an operand on a macro invocation, the expanded macro contains the dummy parameter symbol, NOT the indirectly referenced replacement text. Like equates and structures, macro definitions should all be placed at the beginning of your programs, before the macro gets invoked. If you invoke a macro before it's defined, a phase error will occur. Macro definitions are stored and expanded blindly by CHASM, with no syntax checking. Dummy parameter symbols can appear in any of the input line fields. Any errors in a macro definition will only become evident when CHASM expands the macro and attempts to assemble the result. In keeping with the "shorthand" philosophy of macros, the results of macro expansion don't normally appear on the listing. If you want to see the expansion for debugging purposes, insert a LIST pseudo-op as the first line of the macro definition. Once you start writing macros, you might find it useful to gather them together into a single file. You can then pull this file into the beginning of all your programs with an INCLUDE pseudo-op. Macros which don't get invoked won't add anything to the object code produced, and you'll save yourself the trouble of typing in the ones you *do* need. If you put a NOLIST at the beginning and a LIST at the end of your INCLUDE file, you don't even have to look at the definitions on your listings. 41 >>Structures<< ==>Advanced version only. Structures are an advanced feature. Beginners may wish to skip this section until they become more experienced with CHASM and assembly language programming. CHASM's structure capability allows you to generate a "template" with which to organize repetitive data structures. As an example of a repetitive data structure, consider a phone list. Each entry in the list has three components: Name - 20 characters Address - 50 characters Phone - 10 characters Each entry thus uses a total of 80 bytes of storage. To declare a list with 500 entries, you would declare 80 x 500 = 4000 bytes: PHONELIST DS 4000 ;500 entries @ 80 bytes/entry That's easy enough, but now what's the offset of the 346th address field? This is starting to get confusing, and time consuming to figure out. Furthermore, hard-coding numbers (like that 4000, above) into a program is never a good idea. What's going to happen when you decide to add a zip code field, or make more room in the name field because you just met Alexandria Zbrievskivich? You'd have to go through and change by hand each number which depended on the actual layout of your data. Murphy's law guarantees that it'll take somewhere between "several" and "too many" assemblies to find them all. Structures allow you to set up a symbolic template which makes it much easier to manage structured data like this phone list. By using symbols defined in the structure, rather than bare numbers, a change in data structure doesn't mean a frantic search throughout your entire program to make corrections. If you change the structure definition, the symbols take on new values automatically. 42 Here's what the phone list structure looks like: LISTENTRY STRUC NAME DS 20 ADDRESS DS 50 PHONE DS 10 ENDSTRUC Note the STRUC and ENDSTRUC statements. They mark the beginning and end of the structure, and give it a name (LISTENTRY). Within the structure are storage defining pseudo-ops. DS is used in this example, but DB, DW, and DM could also be used. ORG can be used within a structure, but any 8088 instruction will result in an diagnostic message and termination of the structure definition. Inside a structure, the storage defining pseudo-ops behave somewhat differently than normal. No actual storage is set aside, but CHASM keeps track of how much space would normally be declared. Labels on pseudo-ops get assigned values equal to their offset within the *structure*, not within the program as a whole. Also, CHASM will treat the labels as immediate operands, rather than memory locations. The result of the structure given above is to generate three immediate operands, with the following values: NAME = 0 ADDRESS = 20 PHONE = 70 CHASM does one other piece of useful book-keeping during structure definitions. If a label appears on the STRUC pseudo-op, it gets treated as an immediate operand, whose value is equal to the total length of the structure. You can either use the STRUC label directly as an operand, or if you like "pretty" code, use the LENGTH operator on it. In this example, both LISTENTRY and LENGTH(LISTENTRY) are immediate operands of value 80. (Inside note: LENGTH is a null operator, provided mainly for aesthetic reasons. Using LENGTH will often make your code more readable, but is equivalent to using just the label itself.) 43 Like equates and macros, structures should be placed at the beginning of your programs before any machine instructions, otherwise phase errors can occur. If you *do* embed structures inside your program, you can eliminate any phase errors by using the LENGTH function to reference any of the immediate operands generated by the embedded structure. The immediate operands generated during a structure definition can be very useful in writing your program. Following the phone list example, here's a better way to declare storage for the list: NUMENTRYS EQU 500 PHONELIST DM LISTENTRY*NUMENTRYS ;500 entries of length ;defined by the structure. Now if you add another field to the structure, PHONELIST will automatically increase in size. The 8088's indirect addressing modes, coupled with structures, make a very powerful combination for accessing structured data in memory. Suppose AX contains the number of the entry you want to work on. You can calculate the address of the entry as follows: MOV BX, LENGTH(LISTENTRY) ;length per entry MUL AX,BX ;times entry number ADD AX, OFFSET(PHONELIST) ;plus the starting offset MOV BX,AX ;BX <== frame pointer BX is now a "frame pointer" - it points to the beginning of the desired entry. You can access the various parts of the entry using the optional displacement field in the indirect address. For example, here's how you would store the letter 'A' into the first byte of the address field: MOV ADDRESS[BX], 'A' As another example, the following line reads the third letter of the name into the AL register: MOV AL, NAME+3[BX] 44 The more complicated indirect modes can be used to scan through or point within the fields. The following program fragment gets the fourth digit in the phone number: MOV DI, 4 ;specify 4th digit MOV AL, PHONE[BX+DI] ;read it into AL Often times, you'll want to process entries sequentially. To move to the next entry, you just add the length of the entry to the frame pointer: ADD BX, LENGTH(LISTENTRY) ;point to next entry The preceding examples should give you a feel for what you can do with structures, but do not exhaust all the possibilities. Experiment with this feature, and many of your programs will be both more readable and more easily modified. 45 >>Outside the Program Segment<< As mentioned previously, CHASM does not support multiple segment definitions. Provision is made for limited access outside of the program segment, however. A. Memory References: To access memory outside the program segment, you move a new segment address into the DS register, then address using offsets in the new segment. The memory option of the EQU pseudo-op allows you to give a variable name to offsets in other segments. For example, to access DOS's equipment flag: BIOS_DATA EQU 40H EQUIP_FLAG EQU [0010H] MOV AX,BIOS_DATA ;can't move immed. to DS MOV DS,AX MOV AX,EQUIP_FLAG ;get bios equipment flag B. Code Branching: CHASM supports 4 instructions for branching outside the program segment. 1. Direct CALL and JMP New values for the PC and CS registers are included in the instruction as two immediate operands. Example: BIOS EQU 0F000H ;RAM bios segment DISKETTE_IO EQU 0EC59H ;disk handler JMP DISKETTE_IO,BIOS 2. Indirect CALLF and JMPF Four consecutive bytes in memory are initialized with new values for the PC and CS registers. The CALLF or JMPF then references the address of the new values. Example: BIOS EQU 0F000H ;RAM bios segment PRINTER_IO EQU 0EFD2H ;printer routine MOV [DI],PRINTER_IO MOV 2[DI],BIOS CALLF [DI] 46 >>Running CHASM<< A. Prompt Mode From DOS, type: CHASM If you're using the Subset version, a hello screen is printed, followed by the message: Hit Esc to exit, anything else to continue... Advanced CHASM skips the commercial message. You're now presented with a series of prompts: Source code file name? [.asm] Type in the name of the file which contains your program. If you don't include an extension for the filename, CHASM assumes it to be .ASM. If CHASM is unable to find the file, it will give you the option of naming another file, or returning to DOS. Note that anywhere CHASM expects a filename, you can optionally include a drive and/or path. Assuming your file is present, CHASM prompts: Direct listing to Printer (P), Screen (S), or Disk (D)? [nul:] Respond with either an upper or lower case letter. If you just press enter, no listing will be produced. If you select "D", CHASM will prompt: Name for listing file? [fname.lst] Type in a name for the listing file. If you just press ENTER, the name defaults to that of your source file, with an extension of .LST. 47 Listing Notes: 1. The setting of the /PATH configuration switch controls the exact form of the default list file name. 2. Regardless of where the listing is sent, error messages are always echoed to the screen. 3. Suppressing the listing will result in faster assembly. The final prompt is: Name for object file? [fname.com] Type in a name for the assembled program. If you just press ENTER, the name defaults to that of your source file, with an extension of .COM. Note: The setting of the /PATH configuration switch controls the exact form of the default object file name. CHASM now assembles your program. A status line is maintained on the screen, showing how many lines have been processed, along with how many errors have been discovered. CHASM makes two passes over your source file, outputting the listing and object code on the second pass. You may abort assembly and return to DOS at any time by hitting Ctrl-C or Ctrl-Break. At the end of the second pass, a final summary of the assembly process is printed. It will look something like: 0 Error(s) detected 0 Diagnostic(s) offered 954 (3BAH) Bytes of object code generated This information should be self-explanatory. The number of bytes is given in both decimal and hex format. 48 If labels appeared in your program, a dump of the symbol table will follow. This lists each user-defined symbol, along with its value (in hex). The symbols are printed in alphabetical order. Each value is preceded by a one-letter code, which tells the symbol's type: P: a program location M: a memory location for data I: immediate data Upon exit, CHASM sets the system variable ERRORLEVEL to (surprise!) the total number of errors discovered in your source file. If you run CHASM from a batch file, you can use this feature to automatically invoke your text editor if errors were discovered. B. Expert Mode: This mode allows you to specify all i/o information on the command line which invokes CHASM. The syntax is: CHASM sourcefile [p|s|d|/] [listfile|/] [objectfile] Items within brackets ([]) are optional. You may select *one* of any list of items separated by a bar (|). Basically, you just include on the command line all your responses to the normal prompts. Each response must be separated from the others by either a space or comma. If you don't specify the list device/file or the object file, they default to NUL: and sourcename.COM respectively. To represent a carriage return (to specify a default choice, but allow modifying a later response) use the character slash (/). 49 Expert mode examples: 1. Source file is EXAMPLE.ASM, no listing, object file EXAMPLE.COM: CHASM example 2. Source file is SDIR.ASM, list to printer, object file SDIR.COM: CHASM sdir p 3. Source file is MYFILE.PRG, list to disk file MYFILE.LST, object file SUBR.COM: CHASM myfile.prg d / subr.com 50 >>Error and Diagnostic Messages<< Error messages generated on pass one appear on the listing before any source code is printed, and mention the line number to which they refer. The majority of messages occur during pass two, and will appear in the listing immediately prior to the line which caused the message. Unless the listing itself is going to the screen, messages and the source line which generated them will be echoed there. Add Leading Zero to Hex Constant: Diagnostic. The unknown symbol could be interpreted as a hexadecimal number if a leading zero was added. CHASM Internal Error: XX PC: YYYY or CHASM I/O Error: XX PC: YYYY Sigh. You just discovered a problem in CHASM itself. Please contact Whitman Software, following the procedure in the appendix on Bug Reporting. Could Use JMPS: Diagnostic. The specified label requires an offset of less than 128 bytes; specifying the short jump would result in more compact code. The assembled code is correct, however. Conditional Nested Too Deeply: IF statements can only be nested 10 deep. Data too Large: XXX XXX was found in DB operand list, but is a word value. Use DW to declare words. DM out of range: The product of the DM's operands is either negative, or greater than 32767. Duplicate Definition of XXX in (linenum): Pass 1 error. An attempt was made to define a symbol already present in the symbol table. ELSE without IF: An ELSE was encountered, but no corresponding conditional pseudo-op was found. ENDC without COUNT: An ENDC was encountered, but no corresponding COUNT was found. 51 ENDIF without IF: An ENDIF was encountered, but no corresponding conditional pseudo-op was found. ENDM without MACRO: An ENDM was encountered, but no corresponding MACRO was found. ENDP without PROC: An ENDP was encountered, but no corresponding PROC was found. ENDSTRUC without STRUC: An ENDSTRUC was encountered, but no corresponding STRUC was found. EQU Without Label: No symbol was found to equate with the operand. File not found: XXX in (linenum). Pass one error. CHASM was unable to find the file XXX, specified in the INCLUDE pseudo-op. Heap Full: Too many XXX. Usually a Pass one error. You've run out of memory for the symbol and macro tables. You shouldn't see this message unless you have only 128K and are assembling a very large program. Illegal Label: XXX in (linenum). Pass one error. The symbol XXX begins in column one and has as its first character a number, or a plus or minus sign. Alternatively, you tryed to use the reserved symbol '$' as a label. Illegal Operation for Structure - ENDSTRUC Implied: Diagnostic. The current line is within a structure, and is not a storage defining pseudo-op. CHASM generates an ENDSTRUC, which terminates the structure definition, then assembles the line normally. Illegal or Undefined Argument for LENGTH: The argument for the LENGTH function was not present in the symbol table as an immediate operand on pass 2. Illegal or Undefined Argument for OFFSET: The argument for the OFFSET function was not present in the symbol table as a near label or memory location on pass 2. Missing ENDC: The end of the input file was encountered, and at least one COUNT had not been terminated by an ENDC. 52 Missing ENDM: The end of the input file was encountered, and at least one MACRO had not been terminated by an ENDM. Missing ENDP: The end of the input file was encountered, and at least one PROC had not been terminated by an ENDP. Missing ENDSTRUC: The end of the input file was encountered, and at least one STRUC had not been terminated by an ENDSTRUC. Multiple Segment Overides are Illegal: Diagnostic. You have specified more than one segment overide on this instruction. The first overide is used, and the other(s) ignored. Nested COUNT: A COUNT was encountered while CHASM was already COUNTing. COUNTs cannot be nested. Nested INCLUDE: An INCLUDE was encountered in an INCLUDEd file. The INCLUDE pseudo-op cannot be nested. Nested Structure: A STRUC was encountered inside a structure. Structures cannot be nested. No Name For Macro: Diagnostic. The macro statement did not have a label. CHASM is unable to give a name to the macro, and you will be unable to reference it. Phase Error: A label or memory location is found to have different values on pass 1 and pass 2. A difficult to debug error: generally the problem is not caused by the statement which received the error message. There are four documented ways to generate this error. 1. A previous instruction used a symbolic immediate operand prior to the symbol's definition. 2. A previous instruction made improper use of a forward referenced label, either an attempt to branch into a data area, or to access a code area as if it was data. 3. The label on the flagged statement is defined more than once in the program. 53 4. A previous instruction invoked a macro prior to its definition. Whitman Software would appreciate hearing about any other situations which cause the Phase Error message to appear. Procedures Nested Too Deeply: Procedures may be nested no more than 10 deep. Source Line Truncated: The length of the input line exceeded 80 characters. Specify Word or Byte Operation: Diagnostic. CHASM suggests that the Syntax Error might be resolved by adding the suffix "B" or "W" to the instruction mnemonic. Most, but not all, ambiguous memory references are flagged with this diagnostic. Syntax Error: (OP) (DEST) (SOURCE). CHASM was unable to find a version of the instruction (OP) which allows the operands (DEST) and (SOURCE). Either the instruction doesn't exist, or it is an inappropriate choice for the given operands. Syntax Error messages are followed by two diagnostics which spell out in words CHASM's best guess about the operands. Too Far For Short Jump: The displacement to the specified label is not in the range -128 to +127. Undefined Operand for EQU: Any operands on an EQU statement must have been previously defined. Undefined Symbol XXX: The symbol XXX was used as an operand, but never appeared as a label, and is not a predefined symbol. Unrecognized Operand XXX: XXX is used in the DB or DW operand list, but is not a valid immediate operand. (or string, in the case of DB). 54 >>Execution of Assembled Programs<< A. Object code format The object code file produced by CHASM is in the form of a memory image, exactly as will be present in your computer at run time. No link step is required. Provided that the segment registers are set correctly, the architecture of the 8088 guarantees that code is self-relocating, and will run correctly loaded anywhere in memory. Storing a program as an exact image of memory at run time is called the COM format by IBM. This COM format is *not* that produced by the IBM assembler. The output of the IBM assembler is in the form of an "object module" suitable for input to the linker. The object module is not directly executable, but must first be "filtered" through the linker. This adds an extra step to the process of producing a working program, but gives you the option of combining multiple object modules into one program. The resulting linked program is *still* not a memory image, but has a header which is used to perform relocation during loading. This linked program plus header is called the EXE format by IBM. B. Running Assembled Programs From DOS DOS provides a loader for running machine language programs. To run a program, you merely type its name, without the extension. This is what you're doing every time you use a DOS external command such as FORMAT or CHKDSK. In fact, the COM format is named after "external COMmand". When DOS loads a program, it examines the file extension to determine what format the file is in, either COM or EXE. This is why CHASM defaults to using the extension .com for your object file. If you plan to run the program from DOS, don't change the extension. For COM programs, DOS builds a 255 byte long "program segment prefix" and sets the segment registers to point to this PSP. The contents of the file are then loaded verbatim right after the PSP, at offset hex 100 in the segment defined by the segment registers. As soon as loading is complete, your program is executed starting with the instruction at hex 100. 55 Although you can totally ignore the PSP, you should read pages E-3 through E-11 of the DOS manual to see what DOS puts there for you. It turns out there are some real goodies which your program might want to use. When your program is done, it must transfer control back to DOS, otherwise the 8088 will continue to fetch what it believes are instructions from whatever garbage or bit-hash happens to follow your program in memory. The easiest way to return to DOS is to execute the instruction: INT 20H This is the vectored interrupt reserved by DOS for program termination. While we're on the topic of vectored interrupts, you would be well rewarded to study both the DOS manual and Technical Reference to find out what happens when you execute some of the other interrupts. Some very useful functions, such as file handling and screen i/o, are available at the machine language level through this mechanism. Looking at things the other way, by changing the interrupt vector for a given function to point to your own code, you can override the way DOS or the BIOS does something, and do it your way. DOS even provides a method (via interrupt 27H) by which your new code can be grafted onto DOS, and not be overwritten by other programs. C. Debugging Assembled Programs IBM provides an excellent utility with DOS, called DEBUG.COM. By specifying your program's name as a parameter when invoking DEBUG, you can observe your program execute with DEBUG's trace and other functions. To debug your program, from DOS type: DEBUG progname.COM DEBUG builds a PSP and loads your program just like DOS does, but you have the added power of the debugging commands to monitor your program while it runs. See chapter 6 of the DOS manual for more details about using DEBUG. 56 On the topic of debugging, I can recommend most highly a program called TRACE86, from Morgan Computing (10400 N. Central Expressway, Suite 210, Dallas, TX 75231). The program replaces DEBUG, and although a little steeply priced at $125, makes the IBM debugger look silly. I've been using TRACE86 for some time now, and wouldn't be without it. D. Using Assembled Programs in BASIC To incorporate a machine language subroutine in a BASIC program, write it in assembly language, then assemble it with CHASM. You should read page C-7 of the BASIC manual for some conventions to use in writing your subroutine. In particular, note that you must declare the routine to CHASM as a FAR procedure using the PROC pseudo-op, and that the last instruction of the routine should be a RET. Unlike programs which are run directly from DOS, your routine will not be preceded by a program segment prefix. You should prevent CHASM from leaving room for a PSP by putting an ORG 0 pseudo-op at the beginning of your routine. If you don't include the ORG, memory references will not be assembled correctly. Example: ORG 0 ;no psp SUBR PROC FAR ;far procedure ... ;body of subroutine RET ENDP CHASM supports two methods for getting assembled routines into BASIC programs. The methods differ in whether the routine is included in the BASIC program file, or in a separate file. A utility program called COM2DATA is provided for including machine language within BASIC program files. The program is distributed in source code form (file COM2DATA.ASM) and must be assembled with CHASM prior to use. The program functions as a DOS 2 filter, reading a COM file in from the standard input, and writing a series of BASIC DATA statements to the standard output. 57 COM2DATA's syntax is as follows: COM2DATA [<infile] [>outfile] [linenum] You specify the input and output files as with any DOS 2 filter. The linenum parameter sets the starting line number used on the BASIC code produced. If you don't specify linenum, it defaults to 1000. If you MERGE the file of DATA statements into your BASIC program, the program can then READ the data and POKE it into memory. An example program to do this is given on page C-6 of the BASIC manual. An alternative approach would be to store the routine in a string variable, which could later be located with the VARPTR function. If you would prefer to keep your machine language subroutine in a separate file, include a BSAVE pseudo-op somewhere within your assembly language source code. CHASM will build a header on the object code produced, which will mimic that built by BASIC's BSAVE command. The resulting file may be BLOADed by BASIC to any location in memory. You transfer control to your routine with either the USR function, or the CALL statement. Syntax for these statements can be found in the BASIC manual. 58 E. Using Assembled Programs with Turbo Pascal: CHASM and Turbo Pascal work splendidly together, complementing each other's strong points. You can use CHASM to provide new functions you wish Turbo had, or to fine tune a critical procedure for optimum speed. Turbo loads external procedures and functions within the same segment as the rest of your Pascal program. You have no control of the exact load location (more on this later), but on the other hand, you don't have to worry about setting aside a special location for your procedures (as in BASIC). Since your external procedure is loaded in the same segment as the Pascal code, it should be declared NEAR to CHASM: EXTERNAL PROC NEAR ... ;body of procedure ... ENDP Turbo passes parameters to your procedure/function via the stack. To work effectively, a good grasp of the stack structure is critical. Read the Turbo manual for information on internal data formats and parameter passing, to see just what to expect on the stack. Also, remember that the stack grows down from the top of memory. If you're going to access the stack in your procedure, the first thing you should do is set up BP as a stack pointer. Since Turbo also uses BP, you have to save the current value first. The obvious place to save it is on the stack... PUSH BP ;save old BP MOV BP, SP ;and set up to indirectly address stack You can now access the parameters on the stack using offsets off the BP register. Note that since you PUSHed BP, everything is 2 bytes deeper onto the stack than what Turbo originally sent you. 59 Here's an example. Suppose you declare the following external function in Turbo: function Sum(x,y: int): int; external 'sum.com'; After you've pushed BP, here's how the stack looks: stack contents indirect address ---------------------------------------------- <value of parameter y> 6[BP] <value of parameter x> 4[BP] <return address to Turbo> 2[BP] <old BP value> [BP] The indirect addresses go up two at a time, since each item on the stack is a word (two bytes) long. You can access the parameters using their indirect addresses. Here's the code for an external function to add two integer parameters: SUM PROC NEAR PUSH BP ;save old BP MOV BP, SP ;set up stack pointer MOV AX, 4[BP] ;get parameter x MOV ADD, 6[BP] ;add parameter y ;leave sum in AX to return to Turbo POP BP ;restore old BP for Turbo RET 4 ;clear params off stack ENDP Functions return scalar results by having the value in AX upon return. This function saves some time by calculating the value in AX in the first place. Upon exit, the function POPs BP, to restore the value Turbo was using. Note the RET 4. This returns to Turbo, while simultaneously POPing (and discarding) 4 bytes off the stack. This clears off the two parameters which Turbo passed. If there were three parameters, you'd use a RET 6; if none, a simple RET would do. When Turbo receives control, it assumes that you've cleaned up the stack by removing all parameters. If you don't do this properly, a run-time error, or even a system crash will result. 60 (Typical scenario: Turbo tries to return from one of its own subroutines, thinking the top of the stack has the return address. Unfortunately, the top is really an integer parameter, left over from your external function. Turbo's RET sends control into some random area of memory, and boom - the system crashes.) It's easy to get confused about the exact contents of the stack. If your procedure doesn't seem to be working right, the first thing to suspect is Turbo and you have different ideas about what's where on the stack. A DEBUG session can usually straighten things out. A problem of addressability can crop up if your external procedure tries to maintain its own local variables and/or constants. The problem is that you have no way of knowing just where Turbo is going to load your procedure within the shared segment. As such, the address CHASM calculates for any memory locations are going to be offset from their real values by some unknown constant, the offset of the procedure within the shared segment. This is called a relocation problem. Fortunately, there's a way around this problem, but it requires using a trick. Your program has to figure out, *at run time*, just where it's located in memory. If you could find out the offset of any known point in your procedure, you'd "have your bearings" so to speak, and could go on. The trick is as follows. The 8088 CALL instruction pushes the address of the next instruction onto the stack, then branches to the location given in the CALL. By performing a dummy CALL, then stealing the value off the stack, we have the location of a known spot in the procedure. By subtracting the offset within the procedure of that known location, we get a pointer to the beginning of the procedure which can be used to access everything else. Here's an example: 61 LOCAL PROC NEAR PUSH BP ;set up to access stack MOV BP, SP ; ditto CALL DUMMY ;establish addressability DUMMY POP BX ; " " SUB BX, OFFSET(DUMMY) MOV AX, 4[BP] ;get parameter SEG CS ;offset relative to CS ADD OFFSET(TOTAL)[BX], AX ;maintain running total POP BP RET 2 TOTAL DW 0000H ENDP We use indirect addressing here. After the funny business with the CALL, POP, SUB sequence, BX has a pointer to the beginning of the procedure. Using indirect addressing, we take that pointer and we add in the offset of the memory location we want to access. In this example we're using a local variable to maintain a running total of the parameter which gets passed. Note the SEG CS just before the ADD which accesses the location TOTAL. Since we found our bearings by stealing the address of a program instruction, our offset is known relative to the CS register, NOT the DS which is normally used to access data. The SEG CS forces the 8088 to calculate the address using CS rather than the default DS register. Every time you access a memory location within your procedure, you *MUST* do it relative to CS by using a segment overide. Turbo is very forgiving about what values you leave in the registers upon return. If you modify their contents, you do have to restore BP, SP and SS before returning to Turbo. However, as far as I can tell, you can safely trash the contents of all the general purpose registers, plus DI, SI, DS and ES. 62 >>Notes for Those Upgrading to This Version of CHASM<< CHASM is not yet carved in stone - improvements and corrections are made fairly frequently, based on both my own experience in using the program, and the comments of outside users. This section summarizes the changes which have been made since version 1.2 was released. Changes followed with an asterisk (*) denote modifications which could invalidate programs written under earlier versions of CHASM. Version Notes 4.00 Total rewrite in Turbo Pascal. Subset replaces interpreted version as free distribution release. Faster assembly. Symbol and macro tables can now use all available memory. Nested macros now permitted. Operand expressions. $ now returns location counter value. New syntax for segment overides. Conditional pseudo-ops now evaluate operands. Improved error and diagnostic messages. DOS 2 or later now required (*). DOS 2 path support for files. Setting of DOS 2 ERRORLEVEL. EJECTIF pseudo-op added. New configuration switches: /FF, /DWIDTH, /TIMER, /PATH. CHASM.CFG must now have only one switch per line (*). 3.15 Macros added. New pseudo-ops: MACRO, ENDM, IFE, IFNE, IFB, IFNB, ELSE, ENDIF. 3.14 Interpreted version frozen at version 2.13, further changes apply only to compiled version. Memory requirement raised to 128K. INCLUDE, STRUC, ENDSTRUC, DM, DW, LIST, NOLIST, COUNT and ENDC pseudo-ops added. Alternate mnemonics for the jump on condition instructions, and alternate syntax for the DIV and MUL instructions. Binary numbers added. 2.13 Assembly can now be aborted with the Esc key. Negative decimal numbers are working again. Input lines now limited to 80 characters, and labels must begin with a non-numeral. (*) 2.12 Listings can now be suppressed. Error messages are echoed to the console on non-screen listings. Expert mode added. 63 2.11 Pagination improved. Listings now time stamped. OFFSETs and word values now allowed in DB operand list. 2.10 Equated symbols allowed in the DB operand list. Status line improved. 2.09 The first digit of hexadecimal constants must now be in the range 0-9. A leading zero is permitted on four digit hex constants, to allow fulfilling this condition. (*) 2.08 Configuration process expanded. CHASM now skips over perforations on printed listings. EJECT pseudo-op added. 2.07 Oops. Configuration file now works as advertised. 2.06 CHASM now supports reverse long jumps. 2.05 Compiled version released. BSAVE pseudo-op. Configuration process simplified. 2.04 TABs are now expanded and replaced with blanks, for compatibility with IBM text editors. 2.03 Two bugs corrected. The first bug involved incorrect assembly of indirect memory references which used a displacement in the range 128-255. The second caused a program crash if a hex number longer than 4 digits was in found in the input file. 2.01 COM2DATA utility added. 2.00 Corrected a bug in the DS and DB pseudo-ops which caused the last label in a program to be redefined as a memory location. Also, the TAB character was added as a new delimiter, and PRIMER.DOC was added to the CHASM package. 1.9 The short jump is now represented with mnemonic JMPS, for compatibility with DEBUG version 1.1. (*) 1.8 The operand type "character" was added as a new way to represent immediate data. 64 1.7 The DS operator now works for blocks larger than 255 bytes. Also, the OFFSET function now works properly in the displacement field of an indirect memory reference. 1.6 A revision of this document. Some sections were improved slightly, and in response to user requests, a section on execution of assembled programs was added. 1.5 Corrected an error which generated the message "Data too Long" if the value FFH was used as 8 bit immediate data. 1.4 User interface improved. CHASM now traps some common input errors such as misspelling a file name, or forgetting to turn on your printer. 1.3 A speed enhancement. Version 1.3 benchmarks about 5 times faster than version 1.2. 65 >>Miscellaneous and A Word From Our Sponsor...<< A. Programming Notes: 1. CHASM is written in Turbo Pascal. The source code is available to registered users by sending a formatted disk and stamped return mailer. If you make any improvements, I'd like to hear about them for possible inclusion in future releases. Please note that although you can modify CHASM for your own use, under NO CIRCUMSTANCES may you distribute modified or translated versions, either in the public domain or for profit. B. Red Tape and Legal Nonsense: 1. Disclaimer: CHASM is distributed as is, with no guarantee that it will work correctly in all situations. In no event will the Author be liable for any damages, including lost profits, lost savings or other incidental or consequential damages arising out of the use of or inability to use these programs, even if the Author has been advised of the possibility of such damages, or for any claim by any other party. Despite the somewhat imposing statement above, it *is* my intention to fix any bugs which are brought to my attention. See the appendix on Bug Reporting for more details. 2. Copyright Information: The entire CHASM distribution package, consisting of the main program, documentation files, and various data and utility files, is copyright (c) 1983, 1984 and 1985 by David Whitman. The author reserves the exclusive right to distribute this package, or any part thereof, for profit. The name "CHASM (tm)", applied to a microcomputer assembler program, is a trade mark of David Whitman. 66 CHASM's Subset version and various subsidiary files may be copied freely by individuals for evaluation purposes. It is expected that those who find the package useful will make a contribution directly to the author of the program. The Subset version identifies itself by displaying a banner page giving the author's address and inviting free copying. ONLY VERSIONS DISPLAYING THIS BANNER PAGE MAY BE COPIED. CHASM's Advanced version is only available to registered users who have made the $40 suggested payment. Registered users may copy the program for backup purposes, but must restrict use of the program to either one user or one CPU, at their option. CHASM's source code is made available for educational purposes and to allow users to customize for their own personal use. Under NO CIRCUMSTANCES may modified versions or translations into other computer languages be distributed, either in the public domain or for profit. User groups and clubs are authorized to distribute CHASM's Subset version under the following conditions: 1. No charge is made for the software or documentation. A nominal distribution fee may be charged, provided that it is no more than $8 total. 2. Recipients are to be informed of the user-supported software concept, and encouraged to support it with their donations. 3. The program and documentation are not modified in ANY way, and are distributed together. Interested manufacturers are invited to contact Whitman Software to discuss licensing CHASM for bundling with MS-DOS based computer systems. Distribution of CHASM outside the United States is through licensed distributors, on a royalty basis. Interested distributors are invited to contact Whitman Software. 67 3. Royalty Information: No royalties are required to distribute programs produced using CHASM. However, if you send me a copy of any major program you have produced using CHASM, I'll give you a free page of advertising in this document. 4. Educational Discount: Substantial discounts are available for multi-CPU licenses of CHASM's Advanced version to educational institutions. Contact Whitman Software for details. C. An Offer You Can't Refuse. CHASM is User-Supported software, distributed under a modification of the FREEWARE (tm) marketing scheme developed by Andrew Fluegelman, whose efforts are gratefully acknowledged. Anyone may obtain a free copy of CHASM's Subset version by sending a blank, formatted diskette to the author. An addressed, postage-paid return mailer must accompany the disk (no exceptions, please). A copy of the program, with documentation, will be sent by return mail. The program will carry a notice suggesting a payment to the program's author. Making the payment is totally voluntary on the part of the user. Regardless of whether a payment is made, the user is encouraged to share the program with others. Payment for use is discretionary on the part of each subsequent user. 68 The underlying philosophy here is based on three principles: First, that the value and utility of software is best assessed by the user on his/her own system. Only after using a program can one really determine whether it serves personal applications, needs, and tastes. Second, that the creation of independent personal computer software can and should be supported by those who benefit from its use. Remember the Tanstaafl principal: There Ain't No Such Thing as a Free Lunch. Finally, that copying and networking of programs should be encouraged, rather than restricted. The ease with which software can be distributed outside traditional commercial channels reflects the strength, rather than the weakness, of electronic information. If you like this software, please help support it. Your support can take three forms: 1. Become a registered user. The suggested payment for registration is $40. 2. Suggestions, comments, and bug reports. Your comments will be taken seriously - user feedback was responsible for most of the changes listed in CHASM's revision history. 3. Spread the word. Make copies of the Subset for friends. Write the editor of your favorite computer magazine. Astronomical advertising costs are one big reason that commercial software is so overpriced. To continue offering CHASM this way, I need your help in letting other people know about CHASM. 69 Those who make the $40 payment to become registered users receive the following benefits: 1. An upgrade to the Advanced version of the program. The Advanced version executes twice as fast as the Subset and supports macros, operand expressions and other features. An order form for the Advanced version is given at the end of this manual. 2. User support, by phone or mail. Support is only available to registered users. Phone numbers and the address for help are given below. 3. Notices announcing the release of significant upgrades. CHASM is copyrighted, and users are requested NOT to make copies of the Advanced version other than for their own use. I am strongly opposed to copy protection, and would regret being forced to protect CHASM. Please recognize the amount of time and money which went into producing CHASM, and respect the wishes of the author. David Whitman 136 Wellington Terrace Lansdale, PA 19446 (215) 641-7114 (days) (215) 362-8526 (evenings) 70 Appendix A: Mnemonic List This appendix lists the mnemonics which CHASM will recognize, grouped roughly by function. Consult "The 8086 Book" for definitions of these instructions, and for the operands each will accept. Mnemonics marked with an asterisk (*) will accept a 'B' or 'W' suffix for ambiguous memory references. Arithmetic: AAA AAD AAM AAS ADC* ADD* CBW CWD CMP* CMPS* DAA DAS DEC* DIV* IDIV* IMUL* INC* MUL* NEG* SBB* SUB* Data Movement: LAHF LDS LEA LES LODS* MOV* MOVS* POP POPF PUSH PUSHF SAHF STOS* XCHG XLAT Logical: AND* NOT* OR* TEST* XOR* String Primitives: CMPS* LODS* MOVS* SCAS* STOS* Instruction Prefixes: LOCK REP REPE REPNE REPNZ REPZ SEG Program Counter Control: (unconditional) CALL CALLN CALLF JMP JMPF JMPN JMPS RET Program Counter Control: (conditional) JA JAE JB JBE JC JCXZ JE JG JGE JL JLE JNA JNAE JNB JNBE JNC JNE JNG JNGE JNL JNLE JNO JNO JNP JNS JNZ JO JP JPE JPO JS JZ LOOP LOOPE LOOPNE LOOPNZ LOOPZ 71 Processor Control: CLC CLD CLI CMC HLT NOP STC STD STI WAIT I/O: IN OUT Interrupt: INT INTO IRET Rotate and Shift: RCL* RCR* ROL* ROR* SAL* SAR* SHL* SHR* 72 Appendix B: Differences Between CHASM and That Other Assembler Virtually all magazine articles about assembly language programming on the IBM PC assume that the reader is using That Other Assembler - you know, the one that costs $150. This appendix will try to summarize the differences between the two programs. Please note that I do not own a copy of That Other Assembler, and therefore this section is not complete, nor even guaranteed to be correct. Anyone with more experience is invited to make additions or corrections. A. General Differences The biggest difference is philosophical. The IBM assembler was designed for use by professional assembly language programmers, to write operating systems and other huge projects. This is reflected in the large size and relative complexity of the macro assembler. On the other hand, CHASM was designed for use by beginners, to write relatively short programs. This was done by leaving out a some of the power offered by IBM's assembler, in exchange for simplicity and small size. The main simplification involved producing object code in the COM format, rather than the EXE format chosen by IBM. There are two main consequences of this choice: 1. You can't link routines assembled by CHASM to Microsoft languages. (Although you *can* include them in Turbo Pascal or BASIC programs.) 2. Your program has to fit in one 64K segment. If (shudder!) you want to write a 256K assembly language program, you're out of luck. Like Pascal, the IBM assembler is a strongly typed language. By requiring you to specify the *type* of each memory location you will access in your program, the IBM assembler generally knows what size of memory operand you want. If you don't like the declared size, you have to overide the default with the PTR operator. Thus, to loading the AL register from a location declared word is a syntax error, unless you specify BYTE PTR before the address. 73 In analogy to the C language, CHASM is weakly typed. CHASM is perfectly happy extracting a byte from where you originally set aside a word - CHASM can't tell the difference. In most cases, CHASM can tell what size you want from context: if you're using a word register, it's a word memory access. On the other hand, for any access to memory which doesn't have a register as the other operand, you must add either a 'B' or a 'W' to the instruction mnemonic used by IBM. B. Miscellaneous Differences: 1. Short Jumps: IBM uses the SHORT keyword, CHASM uses an 'S' suffix. Example: JMP SHORT label ;ibm JMPS label ;chasm 2. Offset Function: Where IBM precedes an operand with the keyword OFFSET, CHASM has a *function* called OFFSET. CHASM requires parentheses around the operand. Example: MOV AX, OFFSET FCB ;ibm MOV AX, OFFSET(FCB) ;chasm 3. Declaring Storage: A. If you don't care what value a memory location is initialized to, the IBM assembler allows you to specify '?' as its contents. In CHASM, if you don't care what value the variable is initialized to, just put down a zero. Example: DB ? ;ibm DB 0 ;chasm 74 B. The IBM assembler allows the keyword DUP as an operand in storage declaring pseudo-ops. This means to repeat the definition as many times as the number just before the DUP. Example: DW 3 DUP(?) ;ibm DW 0, 0, 0 ;chasm 4. ASSUME Pseudo-op: IBM's ASSUME pseudo-op tells the assembler where the segment registers will be pointing. CHASM always assumes that the CS, DS and SS registers point to the beginning of the code segment, and that the SS register has been set up to point to a valid stack area. If you find an ASSUME pseudo-op where the CS, DS and ES registers point to different locations, you will have to figure out the addresses for memory references in the DS or ES segments yourself. 5. Segment Pseudo-op: This pseudo-op is used to set up multiple segments in the IBM assembler. Since CHASM only allows one segment, there is no equivalent pseudo-op. If there is only one segment definition in an IBM assembler program, everything is fine, just leave the pseudo-op out for CHASM. Often times the SEGMENT pseudo-op is used to provide addressing of an area in the BIOS, or perhaps the interrupt vector table at the beginning of memory. For example, if a program needed to get at the BIOS data area, in the IBM assembler you would define a dummy segment with the same structure as that in the BIOS listing in Technical Reference: DATA SEGMENT AT 40H RS232_BASE DW 4 DUP(?) PRINTER_BASE DW 4 DUP(?) EQUIP_FLAG DW ? MFG_TST DB ? MEMORY_SIZE DW ? IO_RAM_SIZE DW ? All this is really accomplishing is giving a name to some memory locations which are outside the actual program being written. 75 In CHASM, you can simulate the dummy segment using a structure. This will generate a series of immediate operands whose values correspond to the offsets of the labels in the dummy segment. You can then reference the locations by enclosing the label names in square brackets, to coerce from type immediate to type address. DUMMY STRUC ;simulate dummy segment RS232_BASE DW 0, 0, 0, 0 PRINTER_BASE DW 0, 0, 0, 0 EQUIP_FLAG DW 0 MFG_TST DB 0 MEMORY_SIZE DW 0 IO_RAM_SIZE DW 0 ENDSTRUC MOV AX, [EQUIP_FLAG] 6. Labels: The macro assembler indicates a local label by appending a colon (:). The colon does not become part of the label, and is not included when referencing the label. CHASM's labels are all global, and although they may end with a colon, the colon will become part of the label itself, and must then be used when referencing the label. Example: a2: mov ax,cx ;ibm jmp a2 ; " a2: mov ax,cx ;chasm jmp a2: ; " 7. Entry Point: The macro assembler allows you to specify the point within your program where execution will begin. A label is put on the entry point, then to indicate entry, the same label is placed on the "END" pseudo-op. Since COM programs must always start at offset 100H, CHASM doesn't allow setting an entry point. 76 Appendix C: Description of Files Your CHASM distribution disk contains a number of files. This appendix will give a brief statement of the purpose of each. FILE DESCRIPTION ---------------------------------------------------------------- CHASM.CFG Sample configuration file, for IBM printer. CHASM.COM The CHASM program (either subset or advanced) CHASMS.COM This file may appear on the disk of advanced version users. It is the current subset version, that can be shared with others. Please rename it CHASM.COM on their disk, to avoid confusion. CHASM.DOC This document. EXAMPLE.ASM Sample source file. COM2DATA.ASM Source code for COM2DATA filter. COM2DATA.DOC Documentation for COM2DATA. FREEWARE.DOC References to other User Supported programs. PRIMER.DOC Simple introduction to assembly language. Occasionally, various other sample source files for CHASM will be distributed. These files will have extension ASM, and will be accompanied by a corresponding DOC file. 77 Appendix D: Bug Reporting Procedure Although each version of CHASM is tested extensively prior to release, any program of this magnitude is bound to contain a few bugs. It is the intention of Whitman Software to correct any genuine problem which is reported. If you think you have found a bug in CHASM, please take the time to report it for correction. Although any report is helpful, correction of the problem will be easiest if you provide the following: 1. The version of CHASM you are using. Your problem may have been fixed already! 2. A brief description of what you believe the problem to be. 3. A printed listing of a source file which manifests the problem. * DON'T send a 5,000 line program which has one manifestation of the bug! Isolate the problem area, or write a short sample routine that demonstrates the bug. Unlike normal commercial software, where corrections are saved up for major a revision, bugs in CHASM are fixed as soon as reported, with a new version released almost immediately (which is why there are so many versions in CHASM's revision history). =====> BONUS <====== If you send a copy of your problem source file on disk, it will be returned with either a new, corrected version of CHASM, or with an explanation of what you were doing wrong to *think* you'd found a bug. 78 Appendix E: Using CHASM on "Compatible" Systems CHASM was written specifically for the IBM PC, but should function normally on true "compatibles". This appendix is a new section to summarize compatibility data for various systems. Since CHASM version 4.00 is a totally new program, little compatibility data is currently available. If you are using (or are unable to use...) CHASM on a non-IBM computer, please write with your experiences. Does CHASM work correctly on your system? Are there specific problem areas? Can they be worked around? The following systems are known to run CHASM version 4.00 successfully: IBM PC IBM XT IBM 3270 PC and 3270 PC/G Zenith 150 The following systems have one or more problems: ================================================================ Tandy 1200HD - version 4.00 seems to crash this system. The problem has not yet been isolated. Input from others with access to a Tandy 1200HD would be appreciated. ================================================================ 79 ********ADVANCED VERSION ORDER FORM******** Please add me to the list of registered CHASM users, and send me an upgrade to Advanced CHASM. I understand that CHASM is copyrighted, and agree not to distribute any unauthorized copies of this Advanced version. Note that version 4.00 requires DOS 2 (or later) and 128K Computer Model: ____________________________________ Diskette format: Total Memory: _______K (128K required) __ single sided/DOS 2 __ doubled sided/DOS 2 Check one: ___ I enclose a check for $40 ___ I am a past customer. The enclosed check brings my total payment up to $40. Where did you hear about CHASM? ________________________________ Name: _______________________________________________________ Address: _______________________________________________________ City, State, Zip: ______________________________________________ ================================================================ Send order form and check to: Whitman Software 136 Wellington Terrace Lansdale, PA 19446 80 ==============PRINTER ENHANCEMENT=================== Michael Hoyt, of Soft and Friendly Software, has produced a set of printer enhancement programs using CHASM, which is sold under the name Prowriter Utilities. The package supports the following printers: NEC 8023A-C Prowriter I (C. Itoh 8510) Prowriter II (C. Itoh 1550) The package contains three programs: PRINT_CHARACTERS PRINT_SCREEN PRINT_SET Once PRINT_CHARACTERS is run, it attaches itself to DOS, and makes your printer have exactly the same character set as your video monitor. The conversion is very professionally done. Particularly impressive are the line drawing characters, which actually form connected lines, both horizontally and vertically. As if this wasn't enough, PRINT_CHARACTERS adds italics capability as well. The italics make very effective emphasis in documents and letters, and look really good. PRINT_SCREEN is a graphics screen dump, activated by the normal Shift/PrtSc sequence. Several options are available which trade off speed and print quality. Since I have the mono card, I haven't tried PRINT_SCREEN, but Michael sent me a sample printout which looked quite nice. PRINT_SET is a menu-driven program to turn on and off the various special printing modes supported by these printers. A simple but effective program. I've been using this package with my NEC 8023 for a few months now, and I like them quite a bit. To get a copy, send $35 to: Soft and Friendly RR 2 Box 65 Solsberry, IN 47459 81 ================= NEW PRODUCT ================== If you use the IBM/Microsoft BASIC compiler, chances are your programs are bigger and slower than they have to be. If all unreferenced line numbers are removed from your source program, and the /N switch is used, BASCOM will "optimize" your program. The result is tighter, more efficient code. NUMZAP is a utility which carefully scans your source file, and deletes all the non-essential line numbers. Performing this task by hand would be prohibitively time consuming and you'd probably introduce errors into your program in the process. NUMZAP will do the job in minutes, 100% error free. The old BASIC version of CHASM was passed through NUMZAP, and the resulting compiled code shrank by a factor of 10% (!). That 10% reduction could make the difference between your program running in 64K, or having users with minimal systems get "Out of Memory" messages just before your program crashes. An added advantage to using NUMZAP is that bigger programs can be compiled. You may not be aware that there is a limit on the size of program which the compiler can handle. BASCOM uses up space remembering the offset of each line number in your program. If you have too many numbered lines, BASCOM will run out of room and you'll get a unending series of "TC" (Too Complex) error messages. By eliminating the unneeded line numbers, you give BASCOM more elbow room. The free space available to compile CHASM increased 27% (!) after using NUMZAP. NUMZAP is available under the standard FREEWARE deal - just send a formatted disk and self-addressed, stamped return mailer to: David Whitman 136 Wellington Terrace Lansdale, PA 19446 Be sure to specify that you are interested in NUMZAP. If you like the program, a donation of $15 is suggested.