CAPABILITY Directive (Linker and Libraries Guide)

Linker and Libraries Guide

CAPABILITY Directive

The hardware, software, machine, and platform capabilities of a relocatable object are typically recorded within an object at compile time. The link-editor combines the capabilities of any input relocatable objects to create a final capabilities section for the output file. Capabilities can be defined within a mapfile, to augment, or completely replace, the capabilities that are supplied from input relocatable objects.

        CAPABILITY [capid] {
                HW  = [hwcap_flag...];
                HW += [hwcap_flag...];
                HW -= [hwcap_flag...];
 
                HW_1  = [value...];
                HW_1 += [value...];
                HW_1 -= [value...];
 
                HW_2  = [value...];
                HW_2 += [value...];
                HW_2 -= [value...];
 
                MACHINE  = [machine_name...];
                MACHINE += [machine_name...];
                MACHINE -= [machine_name...];
 
                PLATFORM  = [platform_name...];
                PLATFORM += [platform_name...];
                PLATFORM -= [platform_name...];
 
                SF  = [sfcap_flag...];
                SF += [sfcap_flag...];
                SF -= [sfcap_flag...];
 
                SF_1  = [value...];
                SF_1 += [value...];
                SF_1 -= [value...];
        };

If present, the optional capid name provides a symbolic name for the object capabilities, resulting in a CA_SUNW_ID capability entry in the output object. If multiple CAPABILITY directives are seen, the capid provided by the final directive is used.

An empty CAPABILITY directive can be used to specify a capid for the object capabilities without specifying any capability values.

        CAPABILITY capid;

For each type of capability, the link-editor maintains a current value (value), and a set of values to be excluded (exclude). For hardware and software capabilities, these values are bitmasks. For machine and platform capabilities, they are lists of names. Prior to processing mapfiles, the value and exclude values for all capabilities are cleared. The assignment operators work as follows.

If the “+=” operator is used, the value specified is added to the current value for that capability, and removed from the exclude values for that capability.
If the “-=” operator is used, the value specified is added to the exclude values for that capability, and removed from the current value for that capability.
If the “=” operator is used, the value specified replaces the previous value, and exclude is reset to 0. In addition, the use of “=” overrides any capabilities that are collected from input file processing.

Input objects are processed after mapfiles have been read. Capability values specified by the input objects are merged with those from the mapfiles, unless the “=” operator was used, in which case that capability is ignored when encountered in an input object. Hence, the “=” operator overrides the input objects, whereas the “+=” operator is used to augment them.

Prior to writing the resulting capability value to the output object, the link-editor subtracts any capability values specified with the “-=” operator.

To completely eliminate a given capability from the output object, it suffices to use the “=” operator and an empty value list. For example, the following suppresses any hardware capabilities contributed by the input objects:

        $mapfile_version 2
        CAPABILITY {
                HW = ;
        };

Within an ELF object, hardware and software capabilities are represented as bit assignments within one or more bitmasks found in the capabilities section of the object. The HW and SF mapfile attributes provide a more abstract view of this implementation, accepting a space separated list of symbolic capability names that the link-editor translates to the appropriate mask and bit. The numbered attributes (HW_1, HW_2, SF_1) exist in order to allow direct numeric access to the underlying capability bitmasks. They can be used to specify capability bits that have not been officially defined. Where possible, use of the HW and SF attributes is recommended.

HW Attribute

Hardware capabilities are specified as a space separated list of symbolic capability names. For SPARC platforms, hardware capabilities are defined as AV_ values in <sys/auxv_SPARC.h>. For x86 platforms, hardware capabilities are defined as AV_ values in <sys/auxv_386.h>. Mapfiles use the same names, without the AV_ prefix. For example, the x86 AV_SSE hardware capability is called SSE within a mapfile. This list can contain any of the capability names defined for the CA_SUNW_HW_ capability masks.

HW_1 / HW_2 Attributes

The HW_1 and HW_2 attributes allow the CA_SUNW_HW_1 and CA_SUNW_HW_2 capability masks to be specified directly as numeric values, or as the symbolic hardware capability names that correspond to that mask.

MACHINE Attribute

The MACHINE attribute specifies the machine hardware names for the systems that the object can execute upon. The machine hardware name of a system can be displayed by the utility uname(1) with the -m option. A CAPABILITY directive can specify multiple machine names. Each name results in a CA_SUNW_MACH capability entry in the output object.

PLATFORM Attribute

The PLATFORM attribute specifies the platform names for the systems that the object can execute upon. The platform name of a system can be displayed by the utility uname(1) with the -i option. A CAPABILITY directive can specify multiple platform names. Each name results in a CA_SUNW_PLAT capability entry in the output object.

SF Attribute

Software capabilities are specified as a space separated list of symbolic capability names. Software capabilities are defined as SF1_SUNW_ values in <sys/elf.h>. Mapfiles use the same names, without the SF1_SUNW_ prefix. For example, the SF1_SUNW_ADDR32 software capability is called ADDR32 in a mapfile. This list can contain any of the capability names defined for the CA_SUNW_SF_1.

SF_1 Attribute

The SF_1 attribute allows the CA_SUNW_SF_1 capability mask to be specified directly as a numeric value, or as symbolic software capability names that correspond to that mask.