HP OpenVMS Systems Documentation

Figure B-9 depicts the global symbol specification subrecord for a symbol reference. It is followed by a short description of each field.

Figure B-9 GSD Subrecord for a Global Symbol Reference (EGSD$C_SYM with EGSY$V_DEF Clear)

This field redefines EGSY$W_GSDTYP. The GSD type is EGSD$C_SYM.

This field redefines EGSY$W_GSDSIZ. It is the size of the entire subrecord, including the preceding type field and any padding used to quadword align the following record.

This field redefines EGSY$B_DATYP. The linker currently ignores this field. Should be 0.

This field redefines EGSY$B_TEMP. Used for alignment, must be 0.

This field redefines EGSY$W_FLAGS. The bits in this 2-byte bit field describe the global symbol. Only bits 0 through 1 are used. The following table lists the numbers, names, and corresponding meanings of each bit in the field.

This field contains the length in bytes of the symbol name.

This field contains the symbol name in ASCII format.

B.3.3 Entity-Ident-Consistency-Check Subrecord (EGSD$C_IDC)

This subrecord allows for the consistency checking of an entity (qualified by its object) at link time. Using this subrecord, a compiler may emit code to check the consistency of any type of entity/object combination that has either an ASCII or a binary ident string associated with it.

Figure B-10 depicts the format of an entity-ident-consistency-check subrecord.

Figure B-10 GSD Subrecord for an Entity Ident Consistency Check

When this GSD subrecord is processed during Pass 1, the linker searches its entity name table (which is a single name table for all entity types) using the concatenated entity and object strings (including the length bytes) as the lookup key. This process differs from VAX systems, where the key is the entity name alone. If the linker does not find an entry using the concatenated key, it creates one. If the linker finds an entry for the key, it compares the idents. If the idents do not satisfy the specified match control value, the linker issues a message, with the severity specified by the EIDC$V_ERRSEV field.

The following is a short description of each field in the entity-ident-consistency-check subrecord.

The GSD type is EGSD$C_IDC.

This field contains the size of the entire subrecord, including the preceding type field and any padding used to quadword align the following record.

Only the first five bits of this 4-byte bit field are used. When the EIDC$V_BINIDENT bit is set, the IDENT STRING has a length of 4 and is a 32-bit binary value; when clear, the IDENT STRING is a counted ASCII string.

EIDC$V_IDMATCH points to the first bit of a two-bit substructure in the FLAGS field. The match bits specify the match control for the IDENT STRING when the EIDC$V_BINIDENT flag is set, that is, when the idents are 32-bit binary values. The match bits may have two values: 0 (EIDC$C_LEQ) or 1 (EIDC$C_EQUAL). If EIDC$V_BINIDENT is clear, then the ASCII idents must be equal.

When the match bits are clear (EIDC$C_LEQ), the binary ident of the entity specified in the subrecord must be less than or equal to the binary ident of the entity listed in the entity name table.

When the first match bit is set (EIDC$C_EQUAL), the binary ident of the entity specified in the subrecord must be equal to the binary ident of the entity listed in the linker's entity name table. Remaining values for the two-bit substructure pointed to by EIDC$V_IDMATCH (the values 2 through 3) are reserved.

EIDC$V_ERRSEV points to the first bit of a three-bit substructure in the FLAGS field. The severity bits determine the severity of the message issued if the IDENT STRING fields do not meet the match criteria. When the severity bits equal 0, the message severity is warning; when 1, success; when 2, error; when 3, informational; when 4, severe.

Bits 6 to 31 in the FLAGS field are reserved.

This field contains the length in bytes of the entity name.

This field contains the entity name in ASCII format.

This field contains the length in bytes of the object name.

This field contains the object name in ASCII format.

This field contains the length in bytes of the ident string. For binary idents, this field contains the value 4.

This field contains the ident string. The ident string may be a counted ASCII string or a 32-bit binary value, determined by the flags field. If this string specifies a 32-bit binary value, it consists of 24 bits of minor ident and 8 bits of major ident, analogous to the global section match values for a shareable image. If this string specifies a counted ASCII string, its length is variable.

B.3.4 GSD Subrecords Reserved to the OpenVMS Operating System (EGSD$C_SYMV, EGSD$C_SYMM)

The following sections define subrecords reserved to the OpenVMS Alpha operating system for building the executive. Vectored symbol definitions (EGSD$C_SYMV) occur in the global symbol tables of execlets and are used for loading. Version mask subrecords (EGSD$C_SYMM) are currently found only in the system image SYS$BASE_IMAGE.EXE. The mechanisms used by the linker to generate these record types are not documented. This section is provided for readers who need to understand more about the internals of the OpenVMS Alpha operating system.

B.3.4.1 Vectored-Symbol-Definition Subrecord (EGSD$C_SYMV)

This subrecord is identical in format to the global symbol definition subrecord described in Section B.3.2.1, with the following exceptions:

• The field names begin with ESDFV$ instead of ESDF$, as in the global symbol definition subrecord.
• This subrecord contains an additional longword field, ESDFV$L_VECTOR, which contains an offset into the symbol vector of either SYS$BASE_IMAGE.EXE or SYS$PUBLIC_VECTORS.EXE. The target image is determined by the name of the absolute program section pointed to by the field ESDFV$L_PSINDX. If the name of the psect is ".$$SYS$BASE_IMAGE$$.", then the symbol vector of SYS$BASE_IMAGE.EXE is modified. If the name of the absolute program section is ".$$SYS$PUBLIC_VECTORS$$.", then the symbol vector of SYS$PUBLIC_VECTORS.EXE is modified. Once the symbol vector is modified, it points (directly or indirectly) to the loaded data or procedure.
• This subrecord does not contain the ESDF$L_CODE_ADDESS or ESDF$L_CA_PSINDX fields.
• The VALUE field contains an image offset, not a symbol vector offset. Execlets do not have symbol vectors; therefore, the VALUE field is treated differently.

This subrecord is reserved for use by Compaq only.

B.3.4.2 Symbol-Definition-with-Version-Mask Subrecord (EGSD$C_SYMM)

This subrecord is identical in format to the global symbol definition subrecord described in Section B.3.2.1, with the following exceptions:

• The field names in this record begin with ESDFM$ instead of ESDF$, as in the global symbol definition subrecord.
• This subrecord contains an additional longword field, ESDFM$L_VERSION_MASK. This mask is used to index a list of system components on which the symbol is dependent. This mask is used by the linker to create the system version array in an image that links against SYS$BASE_IMAGE.EXE.
• This subrecord does not contain the ESDF$L_CODE_ADDESS or ESDF$L_CA_PSINDX fields.

This subrecord is reserved for use by Compaq only.

B.4 Text Information and Relocation Records (EOBJ$C_ETIR)

A text information and relocation (TIR) record contains commands and data that the linker uses to manipulate its internal stack, perform calculations, and initialize the image.

A TIR record consists of the RECORD TYPE field (EOBJ$W_RECTYP, set to EOBJ$C_ETIR), the record size (EOBJ$W_SIZE), and one or more TIR commands. Each TIR command consists of a type (ETIR$W_RECTYP), the command size (ETIR$W_SIZE), and the command arguments. A TIR record may contain many TIR commands, but it must not exceed the record size limit for the object module as defined in the MAXIMUM RECORD SIZE field (EMH$L_RECSIZ) of the main module header record.

The record type is EOBJ$C_ETIR.

The record size must include the record size and type fields themselves, as well as the size of any TIR commands that the record contains.

This field designates the TIR command type.

The command size must include the command size and type fields themselves, as well as the aggregate length of any command arguments.

There are 69 text information and relocation commands, divided into five classes with the following associated ranges:

TIR commands either manipulate the linker's stack or initialize storage in the image. Stack commands cause the linker to push values onto the stack. The linker's stack is 64 bits wide. Each value pushed onto the stack is converted to a 64-bit value as required. Store commands are used to fetch global values or to pop the stack and store the results in the image. Operator commands perform operations on values that were pushed onto the stack with previous operations. The result is always stored back on the stack. Control commands set the linker's location counter in preparation for the next store command. Conditional store commands are used to set up conditional linkages and to optimize the instruction stream.

The most common store command, STORE IMMEDIATE (ETIR$C_STO_IMM), is used to write the specified binary directly into the image. This is how the instruction stream is written. The linker is unaware of the instructions written by a STORE IMMEDIATE command. The only way for the linker to interact with the instruction stream is by means of the conditional store commands. The linker does not execute a STORE IMMEDIATE command (either ETIR$C_STO_IMM or ETIR$C_STO_IMMR) when the value being stored is zero. Such a command is, in effect, a null operation. The pages of an image file are guaranteed to be zero until they are specifically initialized by the compiler.

When the linker finishes processing the TIR commands for a given module (that is, when it processes the EEOM record), the stack must be completely collapsed. Otherwise, the linker will issue a warning, LINK-W-EOMSTCK.

TIR commands are described in the following five subsections. Section B.4.1 discusses the stack commands; Section B.4.2, the store commands; Section B.4.3, operator commands; Section B.4.4, control commands; and Section B.4.5, conditional store commands. The commands are presented in numerical order, based on their equivalent numerical values (in decimal).

B.4.1 Stack Commands

The stack commands place longwords and quadwords on the stack. The value placed on the stack is taken from one of the following sources:

• The arguments directly following the ETIR$W_SIZE field
• A global symbol
• A computation derived by adding an offset to the base address of a program section

Each stack command increments the linker's stack pointer. Context is saved to indicate whether the value on the stack is relocatable or defined by a shareable image and therefore external to the image. This context is used later by the operator and store commands. Table B-8 lists the stack commands and their related values, together with a brief description of each command.

Store commands instruct the linker to write a stream of bytes at the current image location counter. The image location counter is set implicitly by a previous store command or explicitly with a control command (for example, ETIR$C_CTL_SETRB). After a store command is executed, the image location counter is pointing to the next byte in the output image. Some store commands pop values from the linker's stack (decrementing the linker's stack pointer), and others do not.

The context for a value that is saved by a stack command indicates whether the value is relocatable and must be treated as an address by subsequent operator and store commands. A relocation is generated if the image is relocatable (for example, linked /SHARE) and the saved context indicates that the address occurs within the image. When the image activator processes relocations, it adds the base address of the image to the value stored at the location indicated by the linker.

If the saved context indicates that the value is defined by a shareable image and is therefore external to the image being created, then a fix-up is generated. Fix-ups are generated without consideration of whether the value is relocatable. For VAX images, references to constants that were defined externally were resolved at link time, and therefore they did not require fixing up. For Alpha images, the linker generates fix-ups for references to externally defined constants. The references are finally resolved by the image activator. This makes it easier to construct an upwardly compatible Alpha shareable image. When the image activator processes fix-ups, it moves an entry from the symbol vector of the shareable image that defined the symbol into the linkage section of the image that referenced it.

Table B-9 lists the store commands and a brief description of each command. Commands that pop the stack and thereby decrement the linker's stack pointer are noted.