Hardware Capability Specific Shared Objects

The dynamic token $HWCAP can be used to specify a directory in which hardware capability specific shared objects exist. This token is available for filters and dependencies. As this token can expand to multiple objects, its use with dependencies is controlled. Dependencies obtained with dlopen(3C), can use this token with the mode RTLD_FIRST. Explicit dependencies that use this token will load the first appropriate dependency found.

The path name specification must consist of a full path name terminated with the $HWCAP token. Shared objects that exist in the directory that is specified with the $HWCAP token are inspected at runtime. These objects should indicate their hardware capability requirements. See Identifying Hardware and Software Capabilities. Each object is validated against the hardware capabilities that are available to the process. Those objects that are applicable for use with the process, are sorted in descending order of their hardware capability values. These sorted filtees are used to resolve symbols that are defined within the filter.

Filtees within the hardware capabilities directory have no naming restrictions. The following example shows how the auxiliary filter libfoo.so.1 can be designed to access hardware capability filtees.

$ LD_OPTIONS='-f /opt/ISV/lib/hwcap/$HWCAP' \
cc -o libfoo.so.1 -G -K pic -h libfoo.so.1 -R. foo.c
$ dump -Lv libfoo.so.1 | egrep "SONAME|AUXILIARY"
  [1]    SONAME    libfoo.so.1
  [2]    AUXILIARY /opt/ISV/lib/hwcap/$HWCAP
$ elfdump -H /opt/ISV/lib/hwcap/*

/opt/ISV/lib/hwcap/filtee.so.3:

Hardware/Software Capabilities Section:  .SUNW_cap
     index  tag               value
       [0]  CA_SUNW_HW_1     0x1000  [ SSE2 ]

/opt/ISV/lib/hwcap/filtee.so.1:

Hardware/Software Capabilities Section:  .SUNW_cap
     index  tag               value
       [0]  CA_SUNW_HW_1     0x40  [ MMX ]

/opt/ISV/lib/hwcap/filtee.so.2:

Hardware/Software Capabilities Section:  .SUNW_cap
     index  tag               value
       [0]  CA_SUNW_HW_1     0x800  [ SSE ]

If the filter libfoo.so.1 is processed on a platform where the MMX and SSE capabilities are available, the following filtee search order occurs.

$ cc -o prog prog.c -R. -lfoo
$ LD_DEBUG=symbols prog
.....
01233: symbol=foo;  lookup in file=libfoo.so.1  [ ELF ]
01233: symbol=foo;  lookup in file=hwcap/filtee.so.2  [ ELF ]
01233: symbol=foo;  lookup in file=hwcap/filtee.so.1  [ ELF ]
.....

Note that the capability value for filtee.so.2 is greater than the capability value for filtee.so.1. filtee.so.3 is not a candidate for inclusion in the symbol search, as the SSE2 capability is not available.

Reducing Filtee Searches

The use of $HWCAP within a filter enables one or more filtees to provide implementations of interfaces that are defined within the filter.

All shared objects within the specified $HWCAP directory are inspected to validate their availability, and to sort those found appropriate for the process. Once sorted, all objects are loaded in preparation for use.

A filtee can be built with the link-editor's -z endfiltee option to indicate that it is the last of the available filtees. A filtee identified with this option, terminates the sorted list of filtees for that filter. No objects sorted after this filtee are loaded for the filter. From the previous example, if the filter.so.2 filtee was tagged with -z endfiltee, the filtee search would be as follows.

$ LD_DEBUG=symbols prog
.....
01424: symbol=foo;  lookup in file=libfoo.so.1  [ ELF ]
01424: symbol=foo;  lookup in file=hwcap/filtee.so.2  [ ELF ]
.....