kldd - list dependencies of kernel modules
kldd [-bcmprsuUvVw] [-D CPU=cpuname] [-k file | -K] [-R path]
[-S dir] file...
The kldd utility lists the dependencies of kernel modules. kldd emulates the behavior of the kernel runtime linker, krtld, to generate the diagnostics.
By default, kldd examines all kernel module dependencies that are associated with the file being inspected, followed by the unix kernel, and any dependencies of the kernel.
In its simplest form, kldd analyzes the dependency requirements of the objects being inspected. kldd can also be instructed to analyze the relocation requirements of each object, which result in binding symbol references to symbol definitions.
The following options are supported:
Report symbol binding.
Display any common (tentative) symbols encountered in the objects being inspected.
Change the expansion of $CPU tokens in dependency names from the default of generic to the string given by cpuname. See NOTES.
Specify the unix kernel to be used. By default, kldd will use the default kernel.
Limit processing to the objects being inspected, and their dependencies. Do not inspect the kernel, or dependencies of the kernel.
Display any multiply defined symbols encountered in the objects being inspected.
Display any unresolved explicit parent or external references. See External Interfaces under USAGE.
Check references. See Interface Verification under USAGE.
A colon-separated list of directories to search for kernel modules. Directories specified with –R are searched ahead of the default module path. See Kernel Module Search Path under USAGE.
Displays the search path used to locate kernel module dependencies.
Specify the system root to be applied to the default module search path, and to the unix kernel. kldd searches for kernel modules, and the unix kernel, in standard locations. By default, this default module path is interpreted relative to the system root directory /. The –S option can is used to specify an alternative system root, or to entirely disable the use of the default module path. If dir is set to a non-empty string, the default search path is interpreted relative to that directory. If dir is set to an empty string, '', then the default search path is not used. In this later case, the –R option must be used to supply a path for kldd to use. See Kernel Module Search Path under USAGE.
Displays any unused objects. If the –s is specified in conjunction with –u, used dependencies are also displayed. See Unused Material under USAGE.
Displays any unreferenced, or unused dependencies. If an unreferenced dependency is not bound to by other objects loaded with file, the dependency is flagged as unused. If the –s is specified in conjunction with –U, referenced dependencies are also displayed. The –U is a superset of of –u. See Unused Material under USAGE.
Displays all dependency relationships incurred when processing file. This option also displays any dependency version requirements. See pvs(1).
Print version information and immediately exit.
Display any unresolved weak symbol references. See Weak References under USAGE.
Display any weak symbol definitions. Unlike their behavior in non-kernel objects, weak definitions have no special meaning in kernel modules. The kernel runtime linker treats weak definitions identically to normal global definitions.
Print usage message and immediately exit.
The following operand is supported:
The name of the specified kernel module. If file specifies an existing file, that file is opened and analyzed.
If the given file does not exist, and contains at most one slash (/) character, it is interpreted as the soname of a kernel module. The kernel module search path is searched for a kernel module matching the given soname, and if such a module is found, that file is opened and analyzed.
A kernel module can make reference to symbols that should be supplied externally to the module. These references can be explicitly classified when the kernel module is created, as being available from the unix kernel or a dependency of the unix kernel (parent), or simply as being external. See the –M mapfile option of ld(1), and the PARENT and EXTERN symbol definition keywords.
When examining a kernel module, a dependency reference to a parent that cannot be resolved is flagged as an error. A dependency reference to an external is not flagged as an error.
The –p option causes any unresolved parent or external reference to be flagged as an error.
kldd can check the compatibility of symbol references and symbol definitions for the objects being inspected. With the –r option, kldd prints warnings for any unresolved symbol references that can occur when file is loaded.
kldd can validate dependency use. Only when a symbol reference is bound to a dependency, is that dependency deemed used. With the –U option and the –u option, kldd prints warnings for any unreferenced, or unused dependencies that are loaded when file is loaded. These options are useful when symbol references are being checked.
A dependency that is defined by an object but is not bound to from that object is an unreferenced dependency. A dependency that is not bound to by any other object when file is loaded is an unused object.
Dependencies can be located in default system locations used by the kernel runtime loader, krtld, or in locations specified with the –R option.
Objects that are found to be unreferenced, or unused, should be removed as dependencies. These objects provide no references, but result in unnecessary overhead when file is loaded.
The removal of unused dependencies reduces system runtime overhead. The removal of unreferenced dependencies reduces system runtime overhead to a lesser degree. However, the removal of unreferenced dependencies guards against a dependency being unused when combined with different objects, or as the other object dependencies evolve.
Symbols that are used by relocations may be defined as weak references. By default, if a weak symbol reference can not be resolved, the relocation is ignored and a zero written to the relocation offset. The –w option, causes any unresolved relocation against a weak symbol reference to be flagged as a relocation error.
Kernel modules specify dependencies on other kernel modules using a simple string referred to as an soname. An soname can have one of 2 forms. The first form gives a plain module name, such as genunix. The second, more common form uses a slash delimiter to specify a module class as well as a module name, such as sys/doorfs). The soname is not a file path, and cannot be used directly to locate the kernel module they refer to. Instead, the kernel runtime loader, krtld uses a search path to look for the module that matches the soname. The search path used is constructed by the kernel at boot time, and can differ in minor details between systems. kldd obtains this default module path from the kernel, and uses it to mimic the behavior of krtld. kldd will display this path as part of the information produced when the –s option is specified.
Before searching, the kernel rewrites the given soname to insert the name of the system platform between the class and name parts of the soname. For example, given an soname of sys/doorfs, the kernel will transform this into sys/platform/doorfs, where platform is one of amd64 or sparcv9, depending on the system. For example, on a sparc system, and assuming a default search path of /kernel:/usr/kernel, krtld will look for /kernel/sys/sparcv9/doorfs, and if that is not found, /usr/kernel/sys/sparcv9/doorfs.
The –S option alters, or deletes, the default module path. By default, the default search path is interpreted relative to the system root directory, /. The –S option can be used to alter the location used for the system root. This is useful when testing a complete set of new modules together, independent of the running system. It can also be used to access modules from a different system. This can be used to analyze kernel modules from a different platform than the currently running system.
The –S option can also specify an empty string, '', for the system root. In this case, the effect is to discard the default search path entirely. In this mode, the –R option must be used to specify the path for kldd to use. This mode of operation provides full control over the path used.
See attributes(7) for descriptions of the following attributes:
|
dump(1), elfdump(1), elfedit(1), ld(1), ldd(1), ldd(1), attributes(7), modinfo(8)
Oracle Solaris 11.4 Linkers and Libraries Guide
kldd prints the record of object path names to stdout. The optional list of symbol resolution problems is printed to stderr. If file is not a kernel module or if file cannot be opened for reading, a non-zero exit status is returned.
The following options depend on symbol resolution, and automatically enable the –r option: –c, –m, –p, –U, –u, and –w.
Ideally, all kernel modules should fully define their dependencies. The use of the kldd –r option verifies that this is the case. However, in practice, a kernel module for which the –r option reports missing dependencies may still be able to load successfully. This can occur if symbols reported by kldd as unresolved are provided by other kernel modules that have already been loaded into the system.
The kernel runtime loader, krtld allows required dependency names to contain the token $CPU. krtld substitutes a string specific to the running system for this token. By default, the kldd utility replaces $CPU with the string generic, which is a valid CPU string on all systems. As a result, kldd will display the path for the generic module, rather than the cpu-specific one that may instead be selected by the kernel. The results are generally equivalent for the purposes of dependency analysis. The –D option can be used to specify a different translation for $CPU in cases where the generic version is insufficient.
The following example displays dependencies of the misc/idmap kernel module, specified by its file path.
$ kldd /kernel/misc/amd64/idmap
sys/doorfs => /kernel/sys/amd64/doorfs
strmod/rpcmod => /kernel/strmod/amd64/rpcmod
misc/tlimod => /kernel/misc/amd64/tlimod
unix (parent) => /platform/i86pc/kernel/amd64/unix
genunix (parent dependency) => /kernel/amd64/genunix
Example 2 Displaying module dependencies by soname
The following example displays dependencies of the misc/idmap kernel module, specified by its module soname.
$ kldd misc/idmap
sys/doorfs => /kernel/sys/amd64/doorfs
strmod/rpcmod => /kernel/strmod/amd64/rpcmod
misc/tlimod => /kernel/misc/amd64/tlimod
unix (parent) => /platform/i86pc/kernel/amd64/unix
genunix (parent dependency) => /kernel/amd64/genunix
Example 3 Displaying module dependencies by modinfo ID
The following example demonstrates the use of the modinfo utility to display the dependencies of the misc/sha2 kernel module currently loaded on the system.
$ modinfo -i misc/sha2
ID LOADADDR SIZE INFO REV NAMEDESC
54 -- be68 -- 1 sha2 (SHA2 Message-Digest Algorithm)
54 -- be68 -- 1 sha2 (SHA2 Kernel SW Provider)
$ kldd `modinfo -i sha2 -o path -p | uniq`
misc/kcf => /kernel/misc/amd64/kcf
unix (parent) => /platform/i86pc/kernel/amd64/unix
genunix (parent dependency) => /kernel/amd64/genunix
Example 4 Viewing search path details
The following example displays dependencies of the misc/idmap kernel module, showing the search details.
$ kldd -s misc/idmap
search path=/platform/i86pc/kernel:/kernel:/usr/kernel (default)
trying path=/platform/i86pc/kernel/misc/amd64/idmap
trying path=/kernel/misc/amd64/idmap
find module=sys/doorfs; required by /kernel/misc/amd64/idmap
trying path=/platform/i86pc/kernel/sys/amd64/doorfs
trying path=/kernel/sys/amd64/doorfs
sys/doorfs => /kernel/sys/amd64/doorfs
find module=strmod/rpcmod; required by /kernel/misc/amd64/idmap
trying path=/platform/i86pc/kernel/strmod/amd64/rpcmod
trying path=/kernel/strmod/amd64/rpcmod
strmod/rpcmod => /kernel/strmod/amd64/rpcmod
find module=misc/tlimod; required by /kernel/strmod/amd64/rpcmod
trying path=/platform/i86pc/kernel/misc/amd64/tlimod
trying path=/kernel/misc/amd64/tlimod
misc/tlimod => /kernel/misc/amd64/tlimod
find kernel=unix; implicit
unix => /platform/i86pc/kernel/amd64/unix
find module=genunix; required by /platform/i86pc/kernel/amd64/unix
trying path=/platform/i86pc/kernel/amd64/genunix
trying path=/kernel/amd64/genunix
genunix => /kernel/amd64/genunix
Example 5 Exposing module deficiencies
The following example employs a pair of kernel modules, demo/mod_a, and demo/mod_b, which have not been installed on the running system, and which are therefore found in a directory named /local/test. The –R option is used to allow kldd to locate them. These modules have intentionally been built with some deficiences in order to demonstrate the operation of the –p, –r, –U, and –w options.
This output has been formatted for display purposes, and errors not directly related to mod_a or mod_b have been omitted.
$ kldd -prUw -R real demo/mod_b
demo/mod_a => /local/test/demo/amd64/mod_a
misc/sha2 => /kernel/misc/amd64/sha2
misc/kcf => /kernel/misc/amd64/kcf
unix (parent) => /platform/i86pc/kernel/amd64/unix
genunix (parent dependency) => /kernel/amd64/genunix
symbol not found: extern_sym (/local/test/demo/amd64/mod_a)
symbol not found: parent_sym (/local/test/demo/amd64/mod_a)
symbol not found: weakref_sym (/local/test/demo/amd64/mod_a)
unreferenced object=/kernel/misc/amd64/sha2;
unused dependency of /local/test/demo/amd64/mod_a
Example 6 Specifying a non-default CPU module
By default, kldd replaces $CPU tokens in dependency names with generic. The –D option can be used to specify a different version of the cpu module. This output has been formatted for display purposes.
$ kldd misc/bignum | grep cpu
cpu/$CPU (parent dependency) =>
/platform/sun4v/kernel/cpu/sparcv9/generic
$ kldd -DCPU=SPARC-T5 misc/bignum | grep cpu
cpu/$CPU (parent dependency) =>
/platform/sun4v/kernel/cpu/sparcv9/SPARC-T5