.bp odd .cs 5 .he .mt 5 .mb 6 .pl 66 .ll 65 .po 10 .hm 2 .fm 2 .ft All Information Presented Here is Proprietary to Digital Research .he .ce 2 .tc 3 Command File Format .sh Section 3 .qs .sp .sh Command File Format .qs .he CP/M-8000 Programmer's Guide 3.1 Command File Format .sp 2 .pp 5 This section describes the format of a command file. The linker processes one or more compiled or assembled files to produce an executable machine-readable file called a command file. By default, a command file has a filetype of 8000. .ix command file .ix symbol table .pp A command file always contains a header, two program segments (a text segment and an initialized data segment), and optionally contains a symbol table and relocation information. These components are described in the following sections. ============ THE ENTIRE REMAINDER OF THIS SECTION MUST BE ========== ============ RE-WRITTEN BASED ON INFORMATION IN X.OUT.H ========== .sp 2 .tc 3.1 The Header and Program Segments .sh 3.1 The Header and Program Segments .ix header .ix program segments .qs .pp The header, the first component in the file, specifies the size and starting address of the other components in the command file, which are listed below. .sp 2 .in 5 .ti -2 o Program segments: .sp text: contains the program instructions. .sp .in 12 .ti -7 data: contains data initialized within the command file. .sp .ti -7 block storage segment (bss): .sp 0 specifies space for uninitialized data generated by the program during execution. Although space for the bss is specified in the source command file, the space is not allocated until the command file is loaded in memory. Therefore, the source command file on the disk contains no uninitialized data. .sp .in 5 .ti -2 o Symbol table: defines referenced symbols. .sp .ti -2 o Relocation information: .sp 0 .in 12 specifies the relative relocation of each word within each program segment, if required. .in 0 .sp .ix command file format .pp The command file format supports two types of headers. The size and content of each type differs. The contiguity of the program segments determines which type of header a command file contains. When the program segments must be contiguous, the file contains a 14-word header in the format shown in Figure 3-1. When the program segments can be noncontiguous, the file contains an 18-word header in the format shown in Figure 3-2. The first word of each header contains a hexadecimal integer that defines which type of header the file contains. .sp 3 .po 5 .nf Byte Sample Values Size Contents Offset 1 Word Integer 601AH denotes text, 0H 601AH data, and bss are contiguous 2H 2376H 1 Longword Number of bytes in text segment 6H 422H 1 Longword Number of bytes in data segment 0AH 1806H 1 Longword Number of bytes in bss 0EH 142H 1 Longword Number of bytes in symbol table 12H 0000H 1 Longword Reserved; always zero 16H 500H 1 Longword Beginning of text segment and of program execution 1AH 00H 1 Word Integer flag for relocation bits; if 0, relocation bits exist; if not 0, no relocation bits exist. .fi .po 10 .ce .sh Figure 3-1. Header for Contiguous Program Segments .qs .sp 2 .pp To create a file that can contain noncontiguous program segments, specify the -T, -D, and -B linker options described in Section 6 when you link the files. The header, identified by 601BH denotes the size and location of each program segment. Note that this header indicates the program segments can be noncontiguous and does not imply the segments must be noncontiguous. See Figure 3-2. .sp 2 .ne 32 .nf .po 5 Byte Sample Values Size Contents Offset 1 Word Integer 601BH denotes text, data, 0H 601BH and bss can be noncontiguous 2H 57864H 1 Longword Number of bytes in text segment 6H 446H 1 Longword Number of bytes in data segment 0AH 2568H 1 Longword Number of bytes in bss 0EH 69H 1 Longword Number of bytes in symbol table 12H 0000H 1 Longword Reserved; always zero 16H 500H 1 Longword Beginning of text segment 1AH 00H 1 Word Integer flag for relocation bits; if 0, relocation bits exist; if not 0, no relocation bits exist. 1CH 57D64H 1 Longword Starting address of data segment 20H 581AAH 1 Longword Starting address of bss .fi .po 10 .sp 2 .ce .sh Figure 3-2. Header for Noncontiguous Program Segments .sp .qs .he CP/M-8000 Programmer's Guide 3.2 The Symbol Table .sp .pp The linker computes the size of the segments in bytes. The result is always rounded up to an even number. For example, the linker adds a byte to a program segment that contains an odd number of bytes. The linker does not include the size of the header when it computes the size of the segments. .pp After a program is linked and loaded in memory, it contains three program segments: text, initialized data, and uninitialized data (bss). The BDOS Program Load Function (59) zeroes the bss when a program is loaded. A program begins execution at the beginning of the text segment. See Figures 3-1 and 3-2 above. .sp 2 .tc 3.2 The Symbol Table .he CP/M-8000 Programmer's Guide 3.2 The Symbol Table .sh 3.2 The Symbol Table .qs .pp The symbol table lists all the symbols specified in a program. Each symbol in the table consists of a 7-word entry that describes the symbol name, type, and value. See Figure 3-3. .bp .ix symbol table .in 3 .nf Field BYTE N A WORD M E Name Null Null Null Null Type A400H Value A6F0H .sp .fi .in 0 .ce .sh Figure 3-3. Entry in Symbol Table .sp 2 .pp The name field, the first four words, contains the ASCII name of the symbol. This field is padded with null characters when the ASCII name is less than eight characters. The fifth word contains the symbol type. Valid values are listed in Table 3-1. .sp 2 .ce .sh Table 3-1. Values For Symbol Types .sp Type Value .sp .qs defined 8000H .sp equated 4000H .sp global 2000H .sp equated register 1000H .sp external reference 800H .sp data based relocatable 400H .sp text based relocatable 200H .sp bss based relocatable 100H .sp .pp When specifying a symbol type with multiple characteristics, the linker uses an OR instruction to combine several of the above values. For example, to specify a defined, global, data based, relocatable symbol, the linker combines the values of each characteristic for a value of A400H. .ix symbol type .pp The last field in an entry is the value field. It consists of a longword that contains the value of the symbol. The value can be an address, a register number, the value of an expression, or some other value. When the value field is nonzero and the type field contains an external symbol, the linker interprets the symbol to be a common region in which the size of the region equals the value of the symbol. .sp 2 ============= ALL PRINTING OF OBJECT FILE INFO DONE WITH XDUMP ========= .ix symbol table, printing .tc 3.2.1 Printing The Symbol Table .sh 3.2.1 Printing The Symbol Table .qs .pp Use the NM68 Utility to print the symbol table of an object or command file. To invoke this utility, specify the NM68 command and filename as shown below. .sp .ti 8 NM68 filename.O [>filespec] .pp You must enter the filename of an object file or a command file. You can optionally redirect the NM68 output from your console to a file. To redirect the NM68 output to a file, specify a greater than sign (>) followed by a file specification after the filename and filetype of the file from which NM68 prints the symbol table. .pp The NM68 utility does not sort the symbols; it prints them in the order in which they appear in the file. Each symbol name is printed, followed by its value and one or more of the type descriptors listed below: .sp 2 .nf .in 3 o equ (equated) o global o equreg (equated register) o external o data o text o bss o abs (absolute) .fi .in 0 .sp 2 .he CP/M-8000 Programmer's Guide 3.3 Relocation Information .tc 3.3 Relocation Information .sh 3.3 Relocation Information .qs .ix relocation information .pp Relocation information is optional. The header relocation word, the last word in the header, indicates whether relocation information exists. When its value is zero, relocation information exists. None exists when the its value is nonzero. .pp Relocation information specifies the relocation of words in program segments. One word of relocation information, called a relocation word, exists for each word in each of the program segments. The assembler and compiler generate relocation words for external symbols and address constants referenced in the text and data program segments. The linker and sometimes the BDOS Program Load Function (59) use these relocation words as described below. .pp The linker resolves external symbols when linking files by modifying bits 0 through 2 of each relocation word that references an external symbol. After being modified, the relocation word indicates the program segment that the symbol references. Therefore, instead of referencing an external symbol, the relocation word references a word located in one of the program segments. Because the linker only modifies relocation words that refer to external symbols, relocation words that do not reference this type of symbol have the same value in the source file input to the linker and the executable file output by the linker. .ix relocation words .pp ================= RELOCATION ON LOADING IS NOT SUPPORTED ============= The BDOS Program Load Function uses relocation words when it loads a program in a location other than the one at which it was linked. The Program Load Parameter Block (LPB) used by the Program Load Function specifies where the program is loaded. When the LPB specifies a location other than the linked location, the BDOS computes a bias (the difference between where a program segment is linked and where it will be loaded in memory). When loading the program, the BDOS adds the bias as indicated by the relocation words to the address of the relocatable words in the text and/or data segments. However, when the BDOS loads the program in the memory locations at which it was linked, the BDOS does not use the relocation words. .ix Program Load Parameter Block (LPB) .sp 2 .tc 3.3.1 The Format of A Relocation Word .sh 3.3.1 The Format Of A Relocation Word .qs .pp A relocation word is a 16-bit quantity. Bits 0 through 2 in each relocation word indicate the type of address referenced and, if applicable, designate the segment to which the relocation word refers. Values for these bits are described in Table 3-2. .sp 2 .sh .ce Table 3-2. Relocation Word Values (bits 0 through 2) .sp .in 5 .ll 60 Value Description .in 12 .ti -5 .sp 00 no relocation information required; the reference is absolute .sp .ti -5 01 reference relative to the base address of the data segment .sp .ti -5 02 reference relative to the base address of the text segment .sp .ti -5 03 reference relative to the base address of the bss .sp .ti -5 04 references an undefined symbol .sp .ti -5 05 references the upper word of a longword; the next relocation word contains the value determining whether the reference is absolute or dependent on the base address of the text or data segments, or the bss. .bp .in 0 .ll 65 .sh .ce Table 3-2. (continued) .sp .in 5 .ll 60 Value Description .in 12 .sp .ti -5 06 16-bit PC-relative reference .sp .ti -5 07 indicates the first word of an instruction, which does not require relocation information. .in 0 .ll 65 .mb 6 .fm 2 .pp The remaining bits, 3 through 15, are not used unless the program references an external symbol. In that case, these bits contain an index to the symbol table. The index specifies the entry number of the symbol listed in the symbol table. Entry numbers in the symbol table are numbered sequentially starting with zero. .he CP/M-8000 Programmer's Guide 3.3 Relocation Words .sp 2 .ce End of Section 3 .bp .he CP/M-8000 Programmer's Guide End of Section 3 .sp 50 .nx four