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....];

                HW_3  = [value....];
                HW_3 += [value....];
                HW_3 -= [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, HW_3, 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.