This file was all I could extract from the original Appendix_C.doc,
it killed Word 2002 everytime I tried to load it. I used the "EasyRecovery
FileRepair" tool to salvage this text from it.
If you have time to restore this to the layout of the other documentation
and remove the extra word tags please send it in and I will update the site
copies. (mailto:asm@deformed.us)
file shows precisely how the assembler translates your source file into machine code. The listing documents the assemblers assumptions, memory allocations, and optimizations.
xe "aa" \z "PGAPCW.DOC-1027"MASM creates an assembly listing of your source file whenever you do one of the following:
xe "aa" \z "PGAPCW.DOC-1028"SYMBOL 117 \f "MSIcons" \s 9.5 \h Select the appropriate option in PWB.
xe "aa" \z "PGAPCW.DOC-1029"SYMBOL 117 \f "MSIcons" \s 9.5 \h Use one of the related source code
xe "aa" \z "PGAPCW.DOC-1030"SYMBOL 117 \f "MSIcons" \s 9.5 \h Specify the /Fl option on the MASM command line.
xe "Assembly:listing files" \t "See Listing files" \z "PGAPCW.DOC-1001"The assembly listing contains both the statements in the source file and the binary code (if any) generated for each statement. The listing also shows the names and values of all labels, variables, and symbols in your file.
xe "aa" \z "PGAPCW.DOC-1031"The assembler creates tables for macros, stru
ctures, unions, records, segments, groups, and other symbols, and places the tables at the end of the assembly listing. Only the types of symbols encountered in the program are included. For example, if your program has no macros, the symbol table does not have a macros section.
Generating Listing Files
XE "Listing files:generating" \z "PGAPCW.DOC-1002"XE "Listing files:PWB options" \z "PGAPCW.DOC-1003"XE "Listing files:command-line options" \z "PGAPCW.DOC-1004"To generate a listing file from wit
hin PWB, follow these steps:
1. From the Options menu, choose MASM Options.
XE "Command-line options:listing file options (list)" \z "PGAPCW.DOC-1005"2. In the MASM Options dialog box, choose Set Debug or Release Options.
xe "aa" \z "PGAPCW.DOC-1032"The dialog box for Set Debug or Release Options lists the choices summarized in Table C.1. This table also shows the equivalent source code directives and command-line options.
Table C.Options for Generating or Modifying Listing F
iles
To generate this information:
In PWB1, select:
In source code, enter:
From command line, enter:
Default listing includes all assembled lines
Generate Listing File
.LIST (default)
/Fl
Turn off all source listings (overrides all listing directives)
Generate Listing File (turn off)
.NOLIST(synonym = .SFCOND)
List all source lines, including false conditionals and generated code
Include All Source Lines
.LISTALL
/Fl /Sa
Show instruction timings
List
/Fl /Sc
Show assembler-generated code
List Generated /Fl /Sg
Include false conditionals2
List False Conditionals
.LISTIF (synonym = .LFCOND)
/Fl /Sx
Suppress listing of any subsequent conditional blocks whose condition is false
List False Conditionals (turn off)
.NOLISTIF (synonym = .SFCOND)
Toggle between .LISTIF and .NOLISTIF
Suppress symbol table generation
Generate Symbol Table (turn off the default)
/Fl /Sn
List all processed macro statements
(synonym = .LALL)
List only instructions, data, and segment directives in macros
(synonym = .XALL)
Turn off all listing during macro expansion
(synonym = .SALL)
Specify title for each page (use only once per file)
TITLE name
/St name
Specify subtitle for page
SUBTITLE name
/Ss name
Designate page length and line width, increment section number, or generate page breaks
PAGE [[length,width]][[+]]
/Sp length/Sl width
Generate first-pass listing
/Ep
1 Select MASM Options from the Options menu, then choose Set Dialog Options from the MASM Options dialog box.
2 See Conditional Directivesin Chapter 1
Precedence of Command-Line Options and Listing Directives
XE "Listing files:command-line options" \z "PGAPCW.DOC-1006"XE "Listing files:PWB options" \z "PGAPCW.DOC-1007"Since command-line options and source code directives can specify opposite behavior
for the same listing file option, the assembler interprets the commands according to the following precedence levels. Selecting PWB options is equivalent to specifying /Fl /Sx on the command line:
xe "aa" \z "PGAPCW.DOC-1033"SYMBOL 117 \f "MSIcons" \s 9.5 \h /Sa overrides any source code directives that suppress listing.
xe "aa" \z "PGAPCW.DOC-1034"SYMBOL 117 \f "MSIcons" \s 9.5 \h Source code directives override all command-line options except /Sa.
xe "aa" \z "PGAPCW.DOC-1035"
SYMBOL 117 \f "MSIcons" \s 9.5 \h .NOLIST overrides other listing directives such as .NOLISTIF and.LISTMACROALL.
xe "aa" \z "PGAPCW.DOC-1036"SYMBOL 117 \f "MSIcons" \s 9.5 \h The /Sx, /Ss, /Sp, and /Sl options set initial values for their respective features. Directives in the source file can override these command-line options.
Reading the Listing File
xe "aa" \z "PGAPCW.DOC-1037"The first half of the listing shows macros from the include file DOS.MAC, structure declarations, and data. After th
e .DATA directive, the columns on the left show offsets and initialized byte values within the data segment.
XE "Listing files:reading" \z "PGAPCW.DOC-1008"XE "Instructions:timing" \z "PGAPCW.DOC-1009"XE "Timing (cycle/second)" \z "PGAPCW.DOC-1010"XE "Processors:timing" \z "PGAPCW.DOC-1011"Instructions begin after the .CODE directive. The three columns on the left show offsets, instruction timings, and binary code generated by the assembler. The columns on the right list the source statements exa
ctly as they appear in the source file or as expanded by a macro. Various symbols and abbreviations in the middle column provide information about the code, as explained in the following section. The subsequent section, Symbols and Abbreviations,explains the meanings of listing symbols.
Generated Code
XE "Listing files:code generated" \z "PGAPCW.DOC-1012"The assembler lists the code generated from the statements of a source file. With the /Sc command-line switch, which generates instruction timin
gs, each line has this syntax:
offset [[timing]] [[code]]
XE "Instructions:timing" \z "PGAPCW.DOC-1013"XE "Timing (cycle/second)" \z "PGAPCW.DOC-1014"XE "Processors:timing" \z "PGAPCW.DOC-1015"The offset is the offset from the beginning of the current code segment. The timing shows the number of cycles the processor needs to execute the instruction. The value of timing reflects the CPU type; for example, specifying the .386 directive produces instruction timings for the 80386 processor. If the sta
tement generates code or data, code shows the numeric value in hexadecimal notation if the value is known at assembly time. If the value is calculated at run time, the assembler indicates what action is necessary to compute the value.
xe "aa" \z "PGAPCW.DOC-1038"When assembling under the default .8086 directive, timing includes an effective address value if the instruction accesses memory. The 80186/486 processors do not use effective address values. For more information on effective address timing, s
section in the Reference book.
Error Messages
XE "Listing files:error messages" \z "PGAPCW.DOC-1016"If any errors occur during assembly, each error message and error number appears directly below the statement where the error occurred. An example of an error line and message is:
mov ax, [dx][di] listtst.asm(77): error A2031: must be index or base register
Symbols and Abbreviations
XE "Listing files:symbols used in (list)" \z "PGAPCW.DOC-1017"The assembler uses the sym
bols and abbreviations shown in Table C.2 to indicate addresses that need to be resolved by the linker or values that were generated in a special way. The example in this section illustrates many of these symbols.
XE "Instructions:timing" \z "PGAPCW.DOC-1018"XE "Timing (cycle/second)" \z "PGAPCW.DOC-1019"XE "Processors:timing" \z "PGAPCW.DOC-1020"The example listing was produced using List Generated InstructionsList Instruction Timingsin PWB. These options correspond to the ML command-lin
e switches /Fl /Sg /Sc.
Table C.Symbols and Abbreviations in Listings
Character
Meaning
C
Line from include file
=
EQU or equal-sign (=) directive
nn[xx]
DUP expression: nn copies of the value xx
----
Segment/group address (linker must resolve)
R
Relocatable address (linker must resolve)
*
Assembler-generated code
E
External address (linker must resolve)
n
Macro-expansion nesting level (+ if more than 9)
|
Operator size override
&
Add
ress size override
nn:
Segment override in statement
nn/
REP or LOCK prefix instruction
XE "Listing files:examples" \z "PGAPCW.DOC-1021"Table C.3 explains the five symbols that may follow timing values in your listing. The Reference book will help you determine correct timings for those values marked with a symbol.
Table C.3 Symbols in Timing Column
Symbol
Meaning
m
Add cycles depending on next executed instruction.
n
Add cycles depending on number of i
0009 3 C1 E3 04 * shl bx, 004h000C 2p 8E D0 * mov ss, ax000E 2 03 E3 * add sp, bxEXTERNDEF work:NEAR0010 7m E8 0000 E call workINVOKE PutStr, ADDR msg0013 2 68 0052 R * push OFFSET Msg0016 7m E8 0029 * call PutStr0019 2 83 C4 02 * add sp, 00002h
001C 2 B8 ---- R mov ax, @data001F 2p 8E C0 mov es, ax0021 2 B0 63 mov al, 'c'0023 4 26: 8B 0E mov cx, es:num0028 2 BF 0052 mov di, 82002B 7n F2/ AE repne scasb002D 4 66| A1 0000 R mov eax, ddData0031 6 67& FE 03 inc BYTE PTR [ebx]EXTERNDEF
0042 2 55 * push bp0043 4 8B EC * mov bp, sp0045 2 B4 02 mov ah, 02H0047 4 8B 7E 04 mov di, pMsg004A 4 8A 15 mov dl, [di]mov ax, [dx][di]listtst.asm(77): error A2031: must be index or base register004C 7m EB 10 * jmp @C00010059
Reading Tables in a Listing File
XE "Listing files:reading" \z "PGAPCW.DOC-1022"XE "Listing files:tables in" \z "PGAPCW.DOC-1023"The tables at the end of a listing file list the macros, structures, unions, records, segments, groups, and symbols that appear in a source file. These tables are not printed in the previous sample listing, but are summarized as follows.
Macro Table
xe "aa" \z "PGAPCW.DOC-1039"Lists all macros in the
main file or the include files. Differentiates between macro functions and macro procedures.
Structures and Unions Table
xe "aa" \z "PGAPCW.DOC-1040"Provides the size in bytes of the structure or union and the offset of each field. The type of each field is also given.
Record Table
xe "aa" \z "PGAPCW.DOC-1041"gives the number of bits of the entire record. provides the offset in bits from the low-order bit of the record to the low-order bit of the field. for fields gives
the number of bits in the field. gives the maximum value of the field, expressed in hexadecimal notation. gives the initial value supplied for the field.
Type Table
xe "aa" \z "PGAPCW.DOC-1042"column in this table gives the size of the TYPEDEF type in bytes, and the column gives the base type for the TYPEDEF definition.
Segment and Group Table
xe "aa" \z "PGAPCW.DOC-1043"specifies whether the segment is 16 bit or 32 bit. gives the size of the se
gment in bytes. gives the segment alignment (WORD, PARA, and so on). gives the combine type (PUBLIC, STACK, and so on). gives the segments class (CODE, DATA, STACK, or CONST).
Procedures, Parameters, and Locals
xe "aa" \z "PGAPCW.DOC-1044"Gives the types and offsets from BP of all parameters and locals defined in each procedure, as well as the size and memory location of each procedure.
Symbol Table
XE "Listing files:tables in" \z "PGAPCW.DOC-1024"XE "Symbol table, list
ing files" \z "PGAPCW.DOC-1025"All symbols (except names for macros, structures, unions, records, and segments) are listed in a symbol table at the end of the listing. The column lists the names in alphabetical order. The column lists each symbolxe "aa" \z "PGAPCW.DOC-1045"The length of a multiple-element variable, such as an array or string, is the length of a single element, not the length of the entire variable.
xe "aa" \z "PGAPCW.DOC-1046"If the symbol represents an
absolute value defined with an EQU or equal sign (=) directive, the column shows the symbols value. The value may be another symbol, a string, or a constant numeric value (in hexadecimal), depending on the type. If the symbol represents a variable or label, the column shows the symbols hexadecimal offset from the beginning of the segment in which it is defined.
xe "aa" \z "PGAPCW.DOC-1047"column shows the attributes of the symbol. The attributes include the name of the seg
ment (if any) in which the symbol is defined, the scope of the symbol, and the code length. A symbols scope is given only if the symbol is defined using the EXTERN and PUBLIC directives. The scope can be external, global, or communal. The column is blank if the symbol has no attribute.
s Guide
Appendix C Generating and Reading Assembly Listings print \p page "
/ndf{1 index where{pop pop pop}{dup xcheck{bind}if def} ifelse}bd
/SetPageOffset{n
eg wp$y add/dTop ed/dLeft ed}ndf
/SetPageSize {neg dTop add/dBot ed dLeft add/dRight ed}ndf
/DoCropMarks{gs 0 setgray /dopaint true def 0.25 sl
dLeft 76 sub dTop M 72 0 rlt dLeft 76 sub dBot M 72 0 rlt
dRight 4 add dTop M 72 0 rlt dRight 4 add dBot M 72 0 rlt
dLeft dTop 76 add M 0 -72 rlt dRight dTop 76 add M 0 -72 rlt
dLeft dBot 4 sub M 0 -72 rlt dRight dBot 4 sub M 0 -72 rlt
stroke gr}ndf
/DoPageBox {gs 0 setgray /dopaint true def 0.25 sl
dLeft dTop M dRight dTop L dRight dBot L dLeft
rint \p para "
0 setgray /dopaint true def 2 2 moveto
/str 30 string def /Times-Roman findfont 5 scalefont setfont
(Printed On: ) show statusdict begin product show end
( Colorlayer: ) show /colorlayer where {pop colorlayer str cvs show}{(?) show}ifelse
( Document Page: ) show wp$fpage show"!Unexpected End of Expressionprint \p page "
/ndf{1 index where{pop pop pop}{dup xcheck{bind}if def} ifelse}bd
/SetPageOffset{neg wp$y add/dTop ed/dLeft ed}ndf
/SetPageSize {neg dTop add/dBot ed
dLeft add/dRight ed}ndf
/DoCropMarks{gs 0 setgray /dopaint true def 0.25 sl
dLeft 76 sub dTop M 72 0 rlt dLeft 76 sub dBot M 72 0 rlt
dRight 4 add dTop M 72 0 rlt dRight 4 add dBot M 72 0 rlt
dLeft dTop 76 add M 0 -72 rlt dRight dTop 76 add M 0 -72 rlt
dLeft dBot 4 sub M 0 -72 rlt dRight dBot 4 sub M 0 -72 rlt
stroke gr}ndf
/DoPageBox {gs 0 setgray /dopaint true def 0.25 sl
dLeft dTop M dRight dTop L dRight dBot L dLeft dBot L
cp stroke gr}ndf
40.5 72 SetPageOffset
531 648 SetPageSi
g def /Times-Roman findfont 5 scalefont setfont
(Printed On: ) show statusdict begin product show end
( Colorlayer: ) show /colorlayer where {pop colorlayer str cvs show}{(?) show}ifelse
( Document Page: ) show wp$fpage show"!Unexpected End of Expressionprint \p page "
/ndf{1 index where{pop pop pop}{dup xcheck{bind}if def} ifelse}bd
/SetPageOffset{neg wp$y add/dTop ed/dLeft ed}ndf
/SetPageSize {neg dTop add/dBot ed dLeft add/dRight ed}ndf
/DoCropMarks{gs 0 setgray /
dopaint true def 0.25 sl
dLeft 76 sub dTop M 72 0 rlt dLeft 76 sub dBot M 72 0 rlt
dRight 4 add dTop M 72 0 rlt dRight 4 add dBot M 72 0 rlt
dLeft dTop 76 add M 0 -72 rlt dRight dTop 76 add M 0 -72 rlt
dLeft dBot 4 sub M 0 -72 rlt dRight dBot 4 sub M 0 -72 rlt
stroke gr}ndf
/DoPageBox {gs 0 setgray /dopaint true def 0.25 sl
dLeft dTop M dRight dTop L dRight dBot L dLeft dBot L
cp stroke gr}ndf
40.5 72 SetPageOffset
531 648 SetPageSize
DoCropMarks
DoPageBox"