8    Symbol Table

This chapter describes the symbol table and the routines used to create and make entries in the table. The chapter addresses the following major topics:

• The purpose of the symbol table, a summary of its components, and their relationship to each other. (Section 8.1)

• The structures of symbol table entries[Footnote 1] and the values you assign them through the symbol table routines. (Section 8.2)

8.1    Symbol Table Overview

The symbol table is created by the compiler front-end as a stand-alone file. The purpose of the table is to provide information that the linker and the debugger need to perform their respective functions. At the option of the user, the linker includes information from the symbol table in the final object file for use by the debugger. (See Figure 7-1 for details about object file format.)

The elements (subtables) contained by the symbol table are shown in Figure 8-1.

Figure 8-1: Symbol Table Overview

The compiler front-end creates one group of subtables that contain global information relative to the entire compilation. It also creates a unique group of subtables for the source file and each of its include files. (Figure 8-1 uses shading to differentiate the two types of subtables: compilation-wide subtables are shaded and file-specific subtables are unshaded.)

Compiler front-ends, the assembler, and the linker interact with the symbol table in the following ways:

• The front-end, using calls to routines supplied with the compiler system, enters symbols and their descriptions in the table.

• The assembler fills in line numbers and optimization symbols, and updates the local symbol table, external symbol table, and procedure descriptor table.

• The linker eliminates duplicate information in the external symbol table and the external string table, removes tables with duplicate information, updates the local symbol table with relocation information, and creates the relative file descriptor table.

The symbol table elements shown in Figure 8-1 are summarized in the paragraphs that follow. Some of the major elements are described in more detail later in the chapter.

Symbolic Header

The symbolic header (HDRR) contains the sizes and locations (as an offset from the beginning of the file) of the subtables that make up the symbol table. Figure 8-2 shows the relationship of the header to the other tables. (See Section 8.2.1 for additional information on the symbolic header.)

Figure 8-2: Functional Overview of the Symbolic Header

Line Number Table

The assembler creates the line number table. The line number table contains an entry for every instruction. Internally, the information is stored in an encoded form. The debugger uses the entries to map instructions to the source lines and vice versa. (See Section 8.2.2 for additional information on the line number table.)

Dense Number Table

The dense number table is an array of pairs. An index into this table is called a dense number. Each pair consists of a file table index (ifd) and an index (isym) into the local symbol table. The table facilitates symbol look-up for the assembler, optimizer, and code generator by allowing direct table access to be used instead of hashing.

Procedure Descriptor Table

The procedure descriptor table contains register and frame information, and offsets into other tables that provide detailed information on the procedure. The compiler front-end creates the table and links it to the local symbol table. The assembler enters information on registers and frames. The debugger uses the entries in determining the line numbers for procedures and the frame information for stack traces. (See Section 8.2.3 for additional information on the procedure discriptor table.)

Local Symbol Table

The local symbol table contains descriptions of program variables, types, and structures, which the debugger uses to locate and interpret run-time values. The table gives the symbol type, storage class, and offsets into other tables that further define the symbol.

A unique local symbol table exists for every source and include file; the compiler locates the table through an offset from the file descriptor entry that exists for every file. The entries in the local symbol table can reference related information in the local string table and auxiliary symbol table. This relationship is shown in Figure 8-3. (See Section 8.2.4 for additional information on the local symbol table.)

Figure 8-3: Logical Relationship Between the File Descriptor Table and Local Symbols

Optimization Symbol Table

To be defined at a future date.

Auxiliary Symbol Table

The auxiliary symbol tables contain data type information specific to one language. Each entry is linked to an entry in the Local Symbol Table. The entry in the local symbol table can have multiple, contiguous entries. The format of an auxiliary entry depends on the symbol type and storage class. Table entries are required only when one of the debugging options (-g compilation options) is in effect. (See Section 8.2.5 for additional information on the auxiliary symbol table.)

Local String Table

The local string tables contain the names of local symbols.

External String Table

The external string table contains the names of external symbols.

File Descriptor Table

The file descriptor table contains one entry each for each source file and each of its include files. Each entry is composed of pointers to a group of subtables related to a file. The structure of an entry is shown in Table 8-12, and the physical layout of the subtables is shown in Figure 8-4. (See Section 8.2.6 for additional information on the file descriptor table.)

Figure 8-4: Physical Relationship of a File Descriptor Entry to Other Tables

The file descriptor entry allows the compiler to access a group of subtables unique to one file. The logical relationship between entries in the file descriptor table and its subtables is shown in Figure 8-5.

Figure 8-5: Logical Relationship Between the File Descriptor Table and Other Tables

Relative File Descriptor Table

Each file in the symbol table contains a relative file descriptor for each file it was compiled with (including itself and include files). The relative file descriptor maps the index of each file at compile time to its index after linking. All file indices inside the local symbols and auxiliary table must be mapped through the relative file descriptor table for the file they occur in. A missing file descriptor table implies the identity function.

External Symbol Table

The external symbol table contains global symbols entered by the compiler front-end. The symbols are defined in one module and referenced in one or more other modules. The assembler updates the entries, and the linker merges the symbols and resolves their addresses. (See Section 8.2.7 for additional information on the external symbol table.)

8.2    Format of Symbol Table Entries

The symbol table is comprised of several subtables. The symbolic header acts as a directory for the subtables; it provides the locations of the subtables and gives their sizes.

The following sections describe the symbolic header and the subtables.

8.2.1    Symbolic Header

The structure of the symbolic header is shown in Table 8-1. The header file sym.h contains the header declaration.

Table 8-1: Format of the Symbolic Header

The lower byte of the vstamp field contains LS_STAMP and the upper byte contains MS_STAMP (see the header file stamp.h). These values are defined in the stamp.h file.

The iMax fields and the cbOffset fields must be set to zero if one of the tables shown in Table 8-1 is not present.

The magic field must contain the constant magicSym, which is also defined in symconst.h.

8.2.2    Line Number Table

Table 8-2 shows the format of an entry in the line number table; the header file sym.h contains its declaration.

Table 8-2: Format of a Line Number Entry

The line number section in the symbol table is rounded to the nearest 4-byte boundary.

Line numbers map executable instructions to source lines; one line number is stored for each instruction associated with a source line. Line numbers are stored as integers in memory and in packed format on disk. Figure 8-6 shows the layout of a line number entry on disk.

Figure 8-6: Layout of Line Number Entries

The compiler assigns a line number only to those lines of source code that generate executable instructions.

The uses of the delta and count fields are as follows:

• Delta is a 4-bit field with a value in the range -7 to 7. It defines the number of source lines between the current source line and the previous line generating executable instructions. The delta value of the first line number entry is the displacement from the lnLow field in the procedure descriptor table.

• Count is a 4-bit field with a value in the range 0 to 15 indicating the number (1 - 16) of executable instructions associated with a source line. If more than 16 instructions (15+1) are associated with a source line, new line number entries are generated when the delta value is zero.

An extended format of the line number entry is used when the delta value is outside the range -7 to 7. Figure 8-7 shows the layout of an extended line number entry on disk.

Figure 8-7: Layout of Extended Line Number Entries

Note

Between two source lines that produce executable code, the compiler allows a maximum of 32,767 comment lines, blank lines, continuation lines, and other lines not producing executable instructions.

The following source listing can be used to show how the compiler assigns line numbers:

1   #include <stdio.h>
2   main()
3   {
4       char c;
5
6       printf("this program just prints input\n");
7       for (;;) {
8          if ((c =fgetc(stdin)) != EOF) break;
9       /*   this is a greater than 7-line comment
10           * 1
11           * 2
12           * 3
13           * 4
14           * 5
15           * 6
16           * 7
17           */
18           printf("%c", c);
19      } /* end for */
20  } /* end main */

The compiler generates line numbers only for the lines 3, 6, 8, 18, and 20; the other lines are either blank or contain comments.

The following table shows the LINER entries for each source line:

Source	LINER
Line	Contents	Meaning
3	03	Delta 0, count 3
6	35	Delta 3, count 5
8	2a	Delta 2, count 10
18[Table Note 1]	89 00 0a	Delta 10, count 9
20	23	Delta 2, count 3

Table Note:

1. Extended format (delta is greater than 7 lines).

The compiler generates the following instructions for the example program:

[main.c:   3] 0x0:    27bb0001        ldah    gp, 1(t12)
[main.c:   3] 0x4:    23bd80d0        lda     gp, -32560(gp)
[main.c:   3] 0x8:    23deffe0        lda     sp, -32(sp)
[main.c:   3] 0xc:    b75e0008        stq     ra, 8(sp)
[main.c:   6] 0x10:   a61d8010        ldq     a0, -32752(gp)
[main.c:   6] 0x14:   22108000        lda     a0, -32768(a0)
[main.c:   6] 0x18:   a77d8018        ldq     t12, -32744(gp)
[main.c:   6] 0x1c:   6b5b4000        jsr     ra, (t12), printf
[main.c:   6] 0x20:   27ba0001        ldah    gp, 1(ra)
[main.c:   6] 0x24:   23bd80b0        lda     gp, -32592(gp)
[main.c:   8] 0x28:   a61d8020        ldq     a0, -32736(gp)
[main.c:   8] 0x2c:   a77d8028        ldq     t12, -32728(gp)
[main.c:   8] 0x30:   6b5b4000        jsr     ra, (t12), fgetc
[main.c:   8] 0x34:   27ba0001        ldah    gp, 1(ra)
[main.c:   8] 0x38:   23bd809c        lda     gp, -32612(gp)
[main.c:   8] 0x3c:   b41e0018        stq     v0, 24(sp)
[main.c:   8] 0x40:   44000401        bis     v0, v0, t0
[main.c:   8] 0x44:   48203f41        extqh   t0, 0x1, t0
[main.c:   8] 0x48:   48271781        sra     t0, 0x38, t0
[main.c:   8] 0x4c:   40203402        addq    t0, 0x1, t1
[main.c:   8] 0x50:   f440000a        bne     t1, 0x7c
[main.c:  18] 0x54:   a61d8010        ldq     a0, -32752(gp)
[main.c:  18] 0x58:   22108020        lda     a0, -32736(a0)
[main.c:  18] 0x5c:   44000411        bis     v0, v0, a1
[main.c:  18] 0x60:   4a203f51        extqh   a1, 0x1, a1
[main.c:  18] 0x64:   4a271791        sra     a1, 0x38, a1
[main.c:  18] 0x68:   a77d8018        ldq     t12, -32744(gp)
[main.c:  18] 0x6c:   6b5b4000        jsr     ra, (t12), printf
[main.c:  18] 0x70:   27ba0001        ldah    gp, 1(ra)
[main.c:  18] 0x74:   23bd8060        lda     gp, -32672(gp)
[main.c:  18] 0x78:   c3ffffeb        br      zero, 0x28
[main.c:  20] 0x7c:   47ff0400        bis     zero, zero, v0
[main.c:  20] 0x80:   a75e0008        ldq     ra, 8(sp)
[main.c:  20] 0x84:   23de0020        lda     sp, 32(sp)
[main.c:  20] 0x88:   6bfa8001        ret     zero, (ra), 1

8.2.3    Procedure Descriptor Table

Table 8-3 shows the format of an entry in the procedure descriptor table; the header file sym.h contains its declaration.

Table 8-3: Format of a Procedure Descriptor Table Entry

Table Notes:

1. If the value of iline is null and the cycm field in the file descriptor table is zero, the iline field is indexed to the actual table.

2. If the value of reg_frame is 1, the regoffset field contains the register number of the register in which the return address is stored.

3. If the value of gp_prologue is zero and gp_used is 1, a gp prologue is present but has been scheduled into the procedure prologue.

8.2.4    Local Symbol Table

Table 8-4 shows the format of an entry in the local symbol table; the header file sym.h contains its declaration.

Table 8-4: Format of a Local Symbol Table Entry

Table Notes:

1. An integer representing an address, size, offset from a frame pointer. The value is determined by the symbol type, as illustrated in Table 8-5.

2. The index into string space (iss) is an offset from the issBase field of an entry in the file descriptor table to the name of the symbol.

3. The symbol type (st) defines the symbol. The valid st Constants are given in Table 8-6. These constants are defined in symconst.h.

4. The storage class (sc), where applicable, explains how to access the symbol type in memory. The valid sc constants are given in Table 8-7. These constants are defined in symconst.h.

5. An offset into either the local symbol table or auxiliary symbol tables, depending of the storage type (st) as shown in Table 8-5. The compiler uses isymBase in the file descriptor entry as the base for an entry in the local symbol table and iauxBase for an entry in the auxiliary symbol table.

Table 8-5: Index and Value as a Function of Symbol Type and Storage Class

Table Notes:

1. The scD/B storage class (data, sdata, bss, or sbss) is determined by the assembler.

2. The frame offset value is the offset from the virtual frame pointer.

3. The isymFull index is the isym of the corresponding full parameter description.

4. The bit offset value is computed from the beginning of the procedure.

5. The isymMac index is the isym of the corresponding stEnd symbol plus 1.

6. The relative address value is the relative displacement from the beginning of the procedure.

7. The isymTag index is the isym to the symbol that is the tag for the variant.

8. The iauxRanges index is the iaux to the ranges for the variant arm.

9. The isymStart index is the isym of the corresponding begin block (for example, stBlock, stFile, or stProc).

The linker ignores all symbols except the types that it will relocate: stLabel, stStatic, stProc, and stStaticProc. Other symbols are used only by the debugger and need to be entered in the table only when one of the debugging options (-g compilation options) is in effect.

8.2.4.1    Symbol Type (st) Constants

Table 8-6 gives the allowable constants that can be specified in the st field of entries in the local symbol table; the header file symconst.h contains the declarations for the constants.

Table 8-6: Symbol Type (st) Constants

8.2.4.2    Storage Class (sc) Constants

Table 8-7 gives the allowable constants that can be specified in the sc field of entries in the local symbol table; the header file symconst.h contains the declarations for the constants.

Table 8-7: Storage Class Constants

8.2.5    Auxiliary Symbol Table

Table 8-8 shows the format of an entry in the auxiliary symbol table; the sym.h file contains its declaration. Note that the entry is declared as a union; Table 8-8 lists the members of the union.

Table 8-8: Auxiliary Symbol Table Entries

Table Notes:

1. Table 8-9 shows the format of a ti entry; the sym.h file contains its declaration.

2. The compiler front-end fills this field in describing structures, enumerations, and other complex types. The relative file index is a pair of indexes. One index is an offset from the start of the file descriptor table to one of its entries. The second is an offset from the file descriptor entry to an entry in the local symbol table or auxiliary symbol table.

3. This index is always an offset to an stEnd entry denoting the end of a procedure.

4. Used in describing case variants. Gives the number of elements that are separated by commas in a case variant.

Table 8-9: Format of a Type Information Record Entry

All groups of auxiliary entries have a type information record with the following entries:

• fbitfield is set if the basic type (bt) is of nonstandard width.

• bt (for basic type) specifies the type of the symbol (for example, integer, real, complex, or structure). The valid entries for this field are shown in Table 8-10; the sym.h file contains its declaration.

• tq (for type qualifier) defines whether the basic type (bt) has an array of, function returning, or pointer to qualifier. The valid entries for this field are shown in Table 8-11; the sym.h file contains its declaration.

Table 8-10: Basic Type (bt) Constants

Table Notes:

1. Size in bits.

Table 8-11: Type Qualifier (tq) Constants

8.2.6    File Descriptor Table

Table 8-12 shows the format of an entry in the file descriptor table; the header file sym.h contains its declaration.

Table 8-12: Format of File Descriptor Entry

8.2.7    External Symbol Table

The external symbol table has the same format as the local symbol table, except an offset (ifd) field has been added to the file descriptor table. This field is used to locate information associated with the symbol in an auxiliary symbol table. Table 8-13 shows the format of an entry in the external symbol table; the sym.h file contains its declaration.

Table 8-13: External Symbol Table Entries