Capabilities Section (Linker and Libraries Guide)

Linker and Libraries Guide

Capabilities Section

A SHT_SUNW_cap section identifies the capability requirements of an object. These capabilities are referred to as object capabilities. This section can also identify the capability requirements of functions, or initialized data items, within an object. These capabilities are referred to as symbol capabilities. This section contains an array of the following structures. See sys/elf.h.

typedef struct {
        Elf32_Word      c_tag;
        union {
                Elf32_Word      c_val;
                Elf32_Addr      c_ptr;
        } c_un;
} Elf32_Cap;

typedef struct {
        Elf64_Xword     c_tag;
        union {
                Elf64_Xword     c_val;
                Elf64_Addr      c_ptr;
        } c_un;
} Elf64_Cap;

For each object with this type, c_tag controls the interpretation of c_un.

c_val: These objects represent integer values with various interpretations.
c_ptr: These objects represent program virtual addresses.

The following capabilities tags exist.

Table 7–12 ELF Capability Array Tags


Name	Value	`c_un`
`CA_SUNW_NULL`	`0`	Ignored
`CA_SUNW_HW_1`	`1`	`c_val`
`CA_SUNW_SF_1`	`2`	`c_val`
`CA_SUNW_HW_2`	`3`	`c_val`
`CA_SUNW_PLAT`	`4`	`c_ptr`
`CA_SUNW_MACH`	`5`	`c_ptr`
`CA_SUNW_ID`	`6`	`c_ptr`

CA_SUNW_NULL: Marks the end of a group of capabilities.
CA_SUNW_HW_1, CA_SUNW_HW_2: Indicates hardware capability values. The c_val element contains a value that represents the associated hardware capabilities. On SPARC platforms, hardware capabilities are defined in sys/auxv_SPARC.h. On x86 platforms, hardware capabilities are defined in sys/auxv_386.h.
CA_SUNW_SF_1: Indicates software capability values. The c_val element contains a value that represents the associated software capabilities that are defined in sys/elf.h.
CA_SUNW_PLAT: Specifies a platform name. The c_ptr element contains the string table offset of a null-terminated string, that defines a platform name.
CA_SUNW_MACH: Specifies a machine name. The c_ptr element contains the string table offset of a null-terminated string, that defines a machine hardware name.
CA_SUNW_ID: Specifies a capability identifier name. The c_ptr element contains the string table offset of a null-terminated string, that defines an identifier name. This element does not define a capability, but assigns a unique symbolic name to the capability group by which the group can be referenced. This identifier name is appended to any global symbol names that are transformed to local symbols as part of the link-editors -z symbolcap processing. See Converting Object Capabilities to Symbol Capabilities.

Relocatable objects can contain a capabilities section. The link-editor combines any capabilities sections from multiple input relocatable objects into a single capabilities section. The link-editor also allows capabilities to be defined at the time an object is built. See Identifying Capability Requirements.

Multiple CA_SUNW_NULL terminated groups of capabilities can exist within an object. The first group, starting at index 0, identifies the object capabilities. A dynamic object that defines object capabilities, has a PT_SUNWCAP program header associated to the section. This program header allows the runtime linker to validate the object against the system capabilities that are available to the process. Dynamic objects that use different object capabilities can provide a flexible runtime environment using filters. See Capability Specific Shared Objects.

Additional groups of capabilities identify symbol capabilities. Symbol capabilities allow multiple instances of the same symbol to exist within an object. Each instance is associated to a set of capabilities that must be available for the instance to be used. When symbol capabilities are present, the sh_link element of the SHT_SUNW_cap section points to the associated SHT_SUNW_capinfo table. Dynamic objects that use symbol capabilities can provide a flexible means of enabling optimized functions for specific systems. See Creating a Family of Symbol Capabilities Functions.

The SHT_SUNW_capinfo table parallels the associated symbol table. The sh_link element of the SHT_SUNW_capinfo section points to the associated symbol table. Functions that are associated with capabilities, have indexes within the SHT_SUNW_capinfo table that identify the capabilities group within the SHT_SUNW_cap section.

Within a dynamic object, the sh_info element of the SHT_SUNW_capinfo section points to a capabilities chain table, SHT_SUNW_capchain. This table is used by the runtime linker to locate members of a capabilities family.

A SHT_SUNW_capinfo table entry has the following format. See sys/elf.h.

typedef Elf32_Word    Elf32_Capinfo;
typedef Elf64_Xword   Elf64_Capinfo;

Elements within this table are interpreted using the following macros. See sys/elf.h.

#define ELF32_C_SYM(info)       ((info)>>8)
#define ELF32_C_GROUP(info)     ((unsigned char)(info))
#define ELF32_C_INFO(sym, grp)  (((sym)<<8)+(unsigned char)(grp))

#define ELF64_C_SYM(info)       ((info)>>32)
#define ELF64_C_GROUP(info)     ((Elf64_Word)(info))
#define ELF64_C_INFO(sym, grp)  (((Elf64_Xword)(sym)<<32)+(Elf64_Xword)(grp))

A SHT_SUNW_capinfo entry group element contains the index of the SHT_SUNW_cap table that this symbol is associated with. This element thus associates symbols to a capability group. A reserved group index, CAPINFO_SUNW_GLOB, identifies a lead symbol of a family of capabilities instances, that provides a default instance.

Name	Value	Meaning
`CAPINFO_SUNW_GLOB`	`0xff`	Identifies a default symbol. This symbol is not associated with any specific capabilities, but leads a symbol capabilities family.

A SHT_SUNW_capinfo entry symbol element contains the index of the lead symbol associated with this symbol. The group and symbol information allow the link-editor to process families of capabilities symbols from relocatable objects, and construct the necessary capabilities information in any output object. Within a dynamic object, the symbol element of a lead symbol, one tagged with the group CAPINFO_SUNW_GLOB, is an index into the SHT_SUNW_capchain table. This index allows the runtime linker to traverse the capabilities chain table, starting at this index, and inspects each following entry until a 0 entry is found. The chain entries contain symbol indices for each capabilities family member.

A dynamic object that defines symbol capabilities, has a DT_SUNW_CAP dynamic entry, and a DT_SUNW_CAPINFO dynamic entry. These entries identify the SHT_SUNW_cap section, and SHT_SUNW_capinfo section respectively. The object also contains DT_SUNW_CAPCHAIN, DT_SUNW_CAPCHAINENT and DT_SUNW_CAPCHAINSZ entries that identify the SHT_SUNW_capchain section, the sections entry size and total size. These entries allow the runtime linker to establish the best symbol to use, from a family of symbol capability instances.

An object can define only object capabilities, or can define only symbol capabilities, or can define both types of capabilities. An object capabilities group starts at index 0. Symbol capabilities groups start at any index other than 0. If an object defines symbol capabilities, but no object capabilities, then a single CA_SUNW_NULL entry must exist at index 0 to indicate the start of symbol capabilities.