Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

kldd (1)

Name

kldd - list dependencies of kernel modules

Synopsis

kldd [-bcmprsuUvVw] [-k file | -K] [-R path] [-S dir]  file...

Description

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.

Options

The following options are supported:

–b

Report symbol binding.

–c

Display any common (tentative) symbols encountered in the objects being inspected.

–k file

Specify the unix kernel to be used. By default, kldd will use the default kernel.

–K

Limit processing to the objects being inspected, and their dependencies. Do not inspect the kernel, or dependencies of the kernel.

–m

Display any multiply defined symbols encountered in the objects being inspected.

–p

Display any unresolved explicit parent or external references. See External Interfaces under USAGE.

–r

Check references. See Interface Verification under USAGE.

–R path

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.

–s

Displays the search path used to locate kernel module dependencies.

–S dir

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.

–u

Displays any unused objects. If the –s is specified in conjunction with –u, used dependencies are also displayed. See Unused Material under USAGE.

–U

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.

–v

Displays all dependency relationships incurred when processing file. This option also displays any dependency version requirements. See pvs(1).

–V
–-version

Print version information and immediately exit.

–w

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.

–?
–-help

Print usage message and immediately exit.

Operands

The following operand is supported:

file

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.

Usage

External Interfaces

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.

Interface Verification

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.

Unused Material

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.

Weak References

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 Module Search Path

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.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/linker

See Also

dump(1), elfdump(1), elfedit(1), ld(1), ldd(1), ldd(1), attributes(7), modinfo(8)

Oracle Solaris 11.4 Linkers and Libraries Guide

Diagnostics

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.

Notes

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. The kldd utility always 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 equivalent for the purposes of dependency analysis.

Examples

Example 1 Displaying module dependencies by file path

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