OpenVMS Linker Utility Manual

Updated: 11 December 1998

OpenVMS Linker Utility Manual

Contents

Index

B.3.2.3 GSD Subrecord for a Symbol Reference

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)

GSD SUBRECORD TYPE Name: ESRF$W_GSDTYP

Length: 2 bytes

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

GSD SUBRECORD SIZE Name: ESRF$W_SIZE

Length: 2 bytes

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.

DATA TYPE Name: ESRF$B_DATYP

Length: 1 byte

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

ALIGNMENT BYTE Name: ESRF$B_TEMP

Length: 1 byte

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

FLAGS Name: ESRF$W_FLAGS

Length: 2 bytes

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.

Bit Name Meaning

0 EGSY$V_WEAK When this bit is set, a weak symbol definition or reference is indicated; when clear, a strong symbol definition or reference.

1 EGSY$V_DEF This bit must be 0.

2--15 Reserved to Digital.

Bit	Name	Meaning
0	EGSY$V_WEAK	When this bit is set, a weak symbol definition or reference is indicated; when clear, a strong symbol definition or reference.
1	EGSY$V_DEF	This bit must be 0.
2--15		Reserved to Digital.

SYMBOL NAME LENGTH Name: ESRF$B_NAMLNG

Length: 1 byte

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

SYMBOL NAME Name: ESRF$T_NAME

Length: Variable, 1 to 64 bytes

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.

GSD SUBRECORD TYPE Name: EIDC$W_GSDTYP

Length: 2 bytes

The GSD type is EGSD$C_IDC.

GSD SUBRECORD SIZE Name: EIDC$W_SIZE

Length: 2 bytes

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

FLAGS Name: EIDC$L_FLAGS

Length: 4 bytes

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.

ENTITY NAME LENGTH Name: EIDC$B_NAMLNG

Length: 1 byte

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

ENTITY NAME Name: EIDC$T_NAME

Length: Variable, 1 to 31 bytes

This field contains the entity name in ASCII format.

OBJECT NAME LENGTH Name: None

Length: 1 byte

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

OBJECT NAME Name: None

Length: Variable, 1 to 31 bytes

This field contains the object name in ASCII format.

IDENT STRING LENGTH Name: None

Length: 1 byte

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

IDENT STRING Name: None

Length: Variable, 1 to 31 bytes

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 Digital 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 Digital 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.

RECORD TYPE Name: EOBJ$W_RECTYP

Length: 2 bytes

The record type is EOBJ$C_ETIR.

RECORD SIZE Name: EOBJ$W_SIZE

Length: 2 bytes

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.

TIR COMMAND TYPE Name: ETIR$W_RECTYP

Length: 2 bytes

This field designates the TIR command type.

TIR COMMAND SIZE Name: ETIR$W_SIZE

Length: 2 bytes

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:

Command Type Minimum Value Maximum Value

Stack ETIR$C_MINSTACOD (0) ETIR$C_MAXSTACOD (6)

Store ETIR$C_MINSTOCOD (50) ETIR$C_MAXSTOCOD (65)

Operator ETIR$C_MINOPRCOD (100) ETIR$C_MAXOPRCOD (116)

Control ETIR$C_MINCTLCOD (150) ETIR$C_MAXCTLCOD (154)

Store Conditional ETIR$C_MINSTCCOD (200) ETIR$C_MAXCTLCOD (214)

Command Type	Minimum Value	Maximum Value
Stack	ETIR$C_MINSTACOD (0)	ETIR$C_MAXSTACOD (6)
Store	ETIR$C_MINSTOCOD (50)	ETIR$C_MAXSTOCOD (65)
Operator	ETIR$C_MINOPRCOD (100)	ETIR$C_MAXOPRCOD (116)
Control	ETIR$C_MINCTLCOD (150)	ETIR$C_MAXCTLCOD (154)
Store Conditional	ETIR$C_MINSTCCOD (200)	ETIR$C_MAXCTLCOD (214)

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.

Table B-8 Stack Commands
Value Command Description

0 ETIR$C_STA_GBL
(Stack Global) Argument is a counted ASCII string containing the name of a global symbol. The command stacks the 32-bit binary value of the symbol. The value is not sign extended. The high-order 32 bits are always 0. The saved context identifies the value as relocatable if the EGSY$V_REL bit in the symbol definition was set. The saved context identifies the value as external if the symbol was defined by a shareable image.

1 ETIR$C_STA_LW
(Stack Longword) Argument is a 4-byte constant. The value is sign extended to 64 bits.

2 ETIR$C_STA_QW
(Stack Quadword) Argument is an 8-byte constant. If the high-order 32 bits are nonzero, they are ignored in calculations performed with subsequent operator commands.

3 ETIR$C_STA_PQ
(Stack Psect Base Plus Byte Offset) Arguments are a longword program section index and a quadword whose low-order 32 bits represent a signed byte offset from the program section base. ¹ The quadword argument is pushed onto the stack and context is saved to indicate whether the program section is relocatable or defined by another shareable image. A subsequent ETIR$C_STO_OFF adds the 32-bit offset to the program section base and sign-extends the result to 64 bits. This command should always be followed by an ETIR$C_STO_OFF command.

4 ETIR$C_STA_LI
(Stack Literal) Not supported in structure level 2.

5 ETIR$C_STA_MOD
(Stack Module) Not supported in structure level 2.

6 ETIR$C_STA_CKARG
(Compare Procedure Argument and Stack for TRUE or FALSE) Not supported in structure level 2.

7--49 Reserved to Digital.

**Table B-8 Stack Commands**
Value	Command	Description
0	ETIR$C_STA_GBL (Stack Global)	Argument is a counted ASCII string containing the name of a global symbol. The command stacks the 32-bit binary value of the symbol. The value is not sign extended. The high-order 32 bits are always 0. The saved context identifies the value as relocatable if the EGSY$V_REL bit in the symbol definition was set. The saved context identifies the value as external if the symbol was defined by a shareable image.
1	ETIR$C_STA_LW (Stack Longword)	Argument is a 4-byte constant. The value is sign extended to 64 bits.
2	ETIR$C_STA_QW (Stack Quadword)	Argument is an 8-byte constant. If the high-order 32 bits are nonzero, they are ignored in calculations performed with subsequent operator commands.
3	ETIR$C_STA_PQ (Stack Psect Base Plus Byte Offset)	Arguments are a longword program section index and a quadword whose low-order 32 bits represent a signed byte offset from the program section base. ¹ The quadword argument is pushed onto the stack and context is saved to indicate whether the program section is relocatable or defined by another shareable image. A subsequent ETIR$C_STO_OFF adds the 32-bit offset to the program section base and sign-extends the result to 64 bits. This command should always be followed by an ETIR$C_STO_OFF command.
4	ETIR$C_STA_LI (Stack Literal)	Not supported in structure level 2.
5	ETIR$C_STA_MOD (Stack Module)	Not supported in structure level 2.
6	ETIR$C_STA_CKARG (Compare Procedure Argument and Stack for TRUE or FALSE)	Not supported in structure level 2.
7--49		Reserved to Digital.

¹For VAX object language, the TIR$C_STA_PB command provides for a signed offset value, to be used with absolute psects to express constants. For Alpha object language, this is illegal. The result will be relocated, which is inappropriate for constants. Use the ETIR$C_STA_QW and ETIR$C_STA_LW commands with constants.

B.4.2 Store Commands

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.

Table B-9 Store Commands
Value Command Description

50 ETIR$C_STO_B
(Store Byte) The stack is popped. The low byte is written to the image. If the value on the stack is a constant contributed by a shareable image, the linker issues an error message indicating that byte fix-ups are not supported.

51 ETIR$C_STO_W
(Store Word) The stack is popped. The low word is written to the image. If the value on the stack is a constant contributed by a shareable image, the linker issues an error message indicating that word fix-ups are not supported.

52 ETIR$C_STO_LW
(Store Longword) The stack is popped. The low longword is written to the image. A relocation or fix-up is generated based on the saved context.

53 ETIR$C_STO_QW
(Store Quadword) The stack is popped. A quadword is written to the image. A relocation or fix-up is generated based on the saved context.

54 ETIR$C_STO_IMMR
(Store Immediate Repeated) Arguments are a longword count of bytes and a stream of binary data. The stack is popped. The low-order 32 bits of the popped value are used as a repeat count. The data stream is successively stored the number of times the count indicates.

55 ETIR$C_STO_GBL
(Store Global) Argument is a counted ASCII string containing the name of a global symbol. If the global value is not external and not relocatable then the 32-bit value field is sign extended to 64 bits. Otherwise, the high-order 32 bits are 0. A quadword is written to image. If the global value is relocatable and the image is relocatable, a relocation is generated. If the global value is contributed by a shareable image, a fix-up is generated.

56 ETIR$C_STO_CA
(Store Code Address) Argument is a counted ASCII string containing the name of a global symbol. The address of the entry point of the procedure named by the string is written into the image. The address is written as a quadword with the high-order 32 bits set to 0. A relocation is generated if the image is relocatable and the global symbol is not external. A fix-up is generated if the procedure is defined by a shareable image.

57 ETIR$C_STO_RB
(Store Relative Branch) Not supported in structure level 2.

58 ETIR$C_STO_AB
(Store Absolute Branch) Not supported in structure level 2.

59 ETIR$C_STO_OFF
(Store Offset to Psect) The quadword offset is popped from the stack and the low-order 32 bits are added to the base of the saved program section. The result is sign extended to 64 bits and written to the image. The value is always treated as an address and relocated if the image is relocatable, or fixed up if the program section is contributed by a shareable image. This command should always be preceded by an ETIR$C_STA_PQ command.

60 Reserved to Digital.

61 ETIR$C_STO_IMM
(Store Immediate) Arguments are a longword count of bytes and a stream of binary data. The data stream is stored directly into the image at the current image location counter.

62 Reserved to Digital.

63 ETIR$C_STO_LP_PSB
(Store LP with Procedure Signature) Not supported in structure level 2.

64 ETIR$C_STO_BR_GBL
(Store Branch Global) Arguments are a longword program section index and quadword offset pointing to the instruction to be replaced, a longword program section and quadword offset pointing to a base address, and a counted string containing the name of a procedure. If the longword displacement from the base address to the code address associated with the procedure name can be expressed as a signed 21-bit integer, then store the displacement in the low-order 21 bits of the instruction pointed to by the first program section index and quadword offset.

65 ETIR$C_STO_BR_PS
(Store Branch Psect + Offset) Arguments are a longword program section index and quadword offset pointing to the instruction to be replaced; a longword program section and quadword offset pointing to a base address; and a longword program section and quadword offset pointing to a target address. If the longword displacement from the base address to the target address can be expressed as a signed 21-bit integer, then store the displacement in the low-order 21 bits of the instruction pointed to by the first program section index and quadword offset.

66--99 Reserved to Digital.

**Table B-9 Store Commands**
Value	Command	Description
50	ETIR$C_STO_B (Store Byte)	The stack is popped. The low byte is written to the image. If the value on the stack is a constant contributed by a shareable image, the linker issues an error message indicating that byte fix-ups are not supported.
51	ETIR$C_STO_W (Store Word)	The stack is popped. The low word is written to the image. If the value on the stack is a constant contributed by a shareable image, the linker issues an error message indicating that word fix-ups are not supported.
52	ETIR$C_STO_LW (Store Longword)	The stack is popped. The low longword is written to the image. A relocation or fix-up is generated based on the saved context.
53	ETIR$C_STO_QW (Store Quadword)	The stack is popped. A quadword is written to the image. A relocation or fix-up is generated based on the saved context.
54	ETIR$C_STO_IMMR (Store Immediate Repeated)	Arguments are a longword count of bytes and a stream of binary data. The stack is popped. The low-order 32 bits of the popped value are used as a repeat count. The data stream is successively stored the number of times the count indicates.
55	ETIR$C_STO_GBL (Store Global)	Argument is a counted ASCII string containing the name of a global symbol. If the global value is not external and not relocatable then the 32-bit value field is sign extended to 64 bits. Otherwise, the high-order 32 bits are 0. A quadword is written to image. If the global value is relocatable and the image is relocatable, a relocation is generated. If the global value is contributed by a shareable image, a fix-up is generated.
56	ETIR$C_STO_CA (Store Code Address)	Argument is a counted ASCII string containing the name of a global symbol. The address of the entry point of the procedure named by the string is written into the image. The address is written as a quadword with the high-order 32 bits set to 0. A relocation is generated if the image is relocatable and the global symbol is not external. A fix-up is generated if the procedure is defined by a shareable image.
57	ETIR$C_STO_RB (Store Relative Branch)	Not supported in structure level 2.
58	ETIR$C_STO_AB (Store Absolute Branch)	Not supported in structure level 2.
59	ETIR$C_STO_OFF (Store Offset to Psect)	The quadword offset is popped from the stack and the low-order 32 bits are added to the base of the saved program section. The result is sign extended to 64 bits and written to the image. The value is always treated as an address and relocated if the image is relocatable, or fixed up if the program section is contributed by a shareable image. This command should always be preceded by an ETIR$C_STA_PQ command.
60		Reserved to Digital.
61	ETIR$C_STO_IMM (Store Immediate)	Arguments are a longword count of bytes and a stream of binary data. The data stream is stored directly into the image at the current image location counter.
62		Reserved to Digital.
63	ETIR$C_STO_LP_PSB (Store LP with Procedure Signature)	Not supported in structure level 2.
64	ETIR$C_STO_BR_GBL (Store Branch Global)	Arguments are a longword program section index and quadword offset pointing to the instruction to be replaced, a longword program section and quadword offset pointing to a base address, and a counted string containing the name of a procedure. If the longword displacement from the base address to the code address associated with the procedure name can be expressed as a signed 21-bit integer, then store the displacement in the low-order 21 bits of the instruction pointed to by the first program section index and quadword offset.
65	ETIR$C_STO_BR_PS (Store Branch Psect + Offset)	Arguments are a longword program section index and quadword offset pointing to the instruction to be replaced; a longword program section and quadword offset pointing to a base address; and a longword program section and quadword offset pointing to a target address. If the longword displacement from the base address to the target address can be expressed as a signed 21-bit integer, then store the displacement in the low-order 21 bits of the instruction pointed to by the first program section index and quadword offset.
66--99		Reserved to Digital.

Contents

Index

Legal

 
4548PRO_023.HTML

SYMBOL NAME	Name: ESRF$T_NAME
	Length: Variable, 1 to 64 bytes

ENTITY NAME	Name: EIDC$T_NAME
	Length: Variable, 1 to 31 bytes