dkms

package
v0.0.0-...-37fa6db Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 5, 2025 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Add 

func Add(pkg *Package, options *Options) error

Add adds a package to the DKMS source tree.

This checks the user source tree (by default, /usr/src/) for the package source files. If the sources don't exist there, this will check the local ${package-name}-${package-version} path and try to copy sources from there to the user source tree, then add the copied sources to the DKMS tree.

If the DKMS tree does not already exist, this will create it. If the package has already been added, this does nothing.

func ApplyPatch 

func ApplyPatch(dir, patchPath string) error

ApplyPatch applies a patch in p1 format to the files in a directory.

func Build 

func Build(pkg *Package, options *Options) error

Build compiles a DKMS package using the MAKE command from dkms.conf and saves the results to the package's build directory in the DKMS tree.

If the package is not already added to the DKMS source tree, this will try to add it.

If options.InstallBuildDependencies is true, this will install the appropriate compiler toolchain and kernel headers for the kernel specified by the options fields.

If any patches should be applied before building the package, as specified in dkms.conf, this will apply them.

If options.MakeVariables is set to "cos-default", this will apply the values used for compiling the COS kernel and append them to the MAKE command. See DefaultMakeVariables for more detail.

func CachedAdd 

func CachedAdd(ctx context.Context, pkg *Package, cache *gcs.GCSBucket, options *Options) error

CachedAdd adds a package to the DKMS source tree, downloading sources from the cache if they are not available locally.

If options.Upload is specified, this will upload the sources to the DKMS tree in the cache after they have been added to the local DKMS tree.

See Add for more details on how sources are added locally.

func CachedBuild 

func CachedBuild(ctx context.Context, pkg *Package, cache *gcs.GCSBucket, options *Options) error

CachedBuild tries to download all of a package's built modules from the cache, and falls back to building them locally if they are not present in the cache.

If options.Upload is specified and the package's built modules are not present in the cache, then this will upload them after they are built.

See Build for more information on how modules are built locally.

func CachedCompatiblePackageVersions 

func CachedCompatiblePackageVersions(ctx context.Context, pkg *Package, cache *gcs.GCSBucket) ([]string, error)

CachedCompatiblePackageVersions checks the DKMS tree in a GCS bucket for non-broken packages which have the same field values as a provided package except for the Version, and returns the version of each compatible package.

func CachedInstall 

func CachedInstall(ctx context.Context, pkg *Package, cache *gcs.GCSBucket, options *Options) error

CachedInstall installs all of the modules from a DKMS package into the install tree, using CachedBuild to build the package if necessary.

See Install for more information on how modules are installed locally.

func CachedRemove 

func CachedRemove(ctx context.Context, pkg *Package, cache *gcs.GCSBucket) error

Remove removes a package from the local DKMS source tree and from the cache.

This will also unbuild the package locally and in the cache, if applicable. If the package is installed, this will uninstall it.

func CachedUnbuild 

func CachedUnbuild(ctx context.Context, pkg *Package, cache *gcs.GCSBucket) error

CachedUnbuild removes a package from the local DKMS build tree and from the cache build tree.

If the package is installed, this will uninstall it.

func CompareVersions 

func CompareVersions(a, b string) int

CompareVersions compares two kernel module or package versions and returns -1 if the first is less than the second, 0 if they are equal, and 1 if the first is greater than the second.

Specifically, it pads each number in the version strings with leading 0s so that all numbers have at least 3 digits, then compares them in alphabetical order. While this choice of comparison is arbitrary, this is precisely what standard DKMS does. Because kernel module version strings do not follow a standard format like semver, any choice of comparison is arbitrary, and this at least handles common cases well.

This is not compatible with semver version comparison. Specifically, the way pre-release versions are compared differs, though the major/minor/patch version comparison should be the same in most cases.

func CompatiblePackageVersions 

func CompatiblePackageVersions(pkg *Package) ([]string, error)

CompatiblePackageVersions checks the local DKMS tree for non-broken packages which have the same field values as a provided package except for the Version, and returns the version of each compatible package.

func CompilerToolchainInstalled 

func CompilerToolchainInstalled(toolchainDir string) bool

CompilerToolchainInstalled returns whether or not the toolchain has been installed in the target directory.

func DefaultMakeVariables 

func DefaultMakeVariables(pkg *Package) (string, error)

DefaultMakeVariables returns the default make variables for a package.

The values of CC and CXX are expected to be provided by sourcing the toolchain_env file in the kernel source tree. The values set in toolchain_env take precedence over the default CC and CXX values.

The default values are: 

ARCH=${arch}
CC=toolchain/bin/${arch}-cros-linux-gnu-clang
CXX=toolchain/bin/${arch}-cros-linux-gnu-clang++
LD=toolchain/bin/${arch}-cros-linux-gnu-ld.lld
STRIP=toolchain/bin/llvm-strip
OBJCOPY=toolchain/bin/llvm-objcopy
HOSTCC=${arch}-pc-linux-gnu-clang
HOSTCXX=${arch}-pc-linux-gnu-clang++
HOSTLD=${arch}-pc-linux-gnu-clang

func Depmod 

func Depmod() error

Depmod runs depmod to recalculate module dependencies. This is required for modprobe to work properly the first time a module has been installed, or if its dependencies change.

func FindKernelModules 

func FindKernelModules(root string) (map[string]string, error)

FindKernelModules returns a map from kernel module names to the paths to those modules for each module in a directory tree.

func InsertModules 

func InsertModules(modules []string, modulePaths map[string]string) error

InsertModules inserts a list of modules into the running kernel.

The modules will be inserted in an order which respects their dependencies, as determined by modinfo, and which maintains the relative order of modules in the modules list as well as possible. See ModuleInsertionOrder for more detail.

This also takes care not to insert or get dependencies for modules which are already inserted, which saves some time.

func InsertedModules 

func InsertedModules() (map[string]bool, error)

InsertedModules returns the list of modules which have been inserted into the running kernel.

func Insmod 

func Insmod(path string) error

Insmod runs insmod on a module to insert it into the running kernel.

func Install 

func Install(pkg *Package, options *Options) error

Install installs all of the modules from a DKMS package into the install tree.

This will add and build the package if it is not already added and built.

For each module in the package, this will check if the version being installed is newer than the version of the module which is already installed, if applicable. If the module version is older than the one already installed, this will skip installing that module and emit an info message. options.ForceVersionOverride can be set to bypass the version check and install the module anyway.

If options.ModprobeOnInstall is passed, then modprobe will be called on the module after it is copied to the install tree to insert it into the running kernel.

func InstallBuildDependencies 

func InstallBuildDependencies(pkg *Package) error

InstallBuildDependencies downloads and installs the kernel headers and compiler toolchain for a package, if they are not already present.

func InstallCompilerToolchain 

func InstallCompilerToolchain(ctx context.Context, downloader cos.ArtifactsDownloader, dstDir string) error

InstallCompilerToolchain installs the COS compiler toolchain in a target directory.

Once the toolchain has been installed, the toolchain tarball is removed to save space, and a toolchain-installed.txt file is created. If the installation fails for any reason, toolchain-installed.txt file will not be written, so it can be used as a reliable indicator that the installation succeeded.

func InstallKernelHeaders 

func InstallKernelHeaders(ctx context.Context, downloader cos.ArtifactsDownloader, dstDir string) error

InstallKernelHeaders installs the COS kernel headers in a target directory.

Once the headers have been installed, the header tarball is removed to save space, and a kernel-headers-installed.txt file is created. If the installation fails for any reason, the kernel-headers-installed.txt file will not be written, so it can be used as a reliable indicator that the installation succeeded.

func IsAdded 

func IsAdded(pkg *Package) bool

IsAdded checks if a package has been added to the DKMS tree and if it has a valid dkms.conf file. Note that an empty or absent dkms.conf is considered valid, since default values can be used for all settings.

func IsAddedInCache 

func IsAddedInCache(ctx context.Context, pkg *Package, cache *gcs.GCSBucket) bool

IsAddedInCache checks if a package has been added to the DKMS tree in the cache and if it has a valid dkms.conf file. Note that an empty or absent dkms.conf is considered valid, since default values can be used for all settings.

func IsBuilt 

func IsBuilt(pkg *Package) bool

IsBuilt returns whether or not a package has been added to the DKMS source tree and all of its modules have been built.

func IsBuiltInCache 

func IsBuiltInCache(ctx context.Context, pkg *Package, cache *gcs.GCSBucket) bool

IsBuiltInCache returns whether or not all of a package's built modules are present in a cache. If the package has an invalid dkms.conf, this returns false.

func IsInstalled 

func IsInstalled(pkg *Package) bool

IsInstalled returns whether or not a package has been built in the DKMS build tree and all of its modules have been installed in the install tree.

func KernelHeadersInstalled 

func KernelHeadersInstalled(buildDir string) bool

KernelHeadersInstalled returns whether or not the kernel headers have been installed in the target directory.

func ModprobeModule 

func ModprobeModule(name string) error

ModprobeModule runs modprobe on a module to insert it into the running kernel.

func ModprobeModules 

func ModprobeModules(modules []Module) error

ModprobeModules modprobes a list of modules, ignoring ones which have already been inserted into the running kernel.

func ModuleDependencies 

func ModuleDependencies(modulePath string) ([]string, error)

ModuleDependencies gets the list of dependencies for a module via a call to modinfo.

func ModuleDependencyGraph 

func ModuleDependencyGraph(modules []string, modulePaths map[string]string) (map[string][]string, error)

ModuleDependencyGraph uses modinfo to compute a mapping from module names to the list of modules that must be inserted before a given module.

For example, the output {a: [], b: [d], c: [a, b], d: []} indicates that module d must be inserted before module b, and modules a and b must be inserted before module c.

func ModuleInsertionOrder 

func ModuleInsertionOrder(modules []string, dependencyGraph map[string][]string) []string

ModuleInsertionOrder takes a list of modules and a graph of their dependencies and returns a valid order in which a list of modules can be inserted into the running kernel.

The structure of the dependency graph is described in ModuleDependencyGraph.

Where there is not a dependency preventing it, the ordered modules will be in the same relative order as in the slice provided. For example, if the module list is [a, b, c, d] and the dependency graph is {a: [], b: [d], c: [a, b], d: []}, then the returned ordering must be [a, d, b, c]}. While a different ordering like [d, b, a, c] would be valid with respect to the depencency graph, it would not be output because a comes before b in the given module list and there is no dependency forcing b to be inserted before a.

func ModuleVersion 

func ModuleVersion(moduleNameOrPath string) (string, error)

ModuleVersion returns the version of a compiled module based on the version string output by modinfo.

func Remove 

func Remove(pkg *Package) error

Remove removes a package from the DKMS source tree. This will also unbuild and uninstall the package, if applicable.

func Unbuild 

func Unbuild(pkg *Package) error

Unbuild removes a module from the DKMS build tree and uninstalls it.

This removes the compiled modules from the build directory, then calls the MAKE clean command for the package from the package's build directory.

func Uninstall 

func Uninstall(pkg *Package) error

Uninstall removes all of the installed modules of a DKMS package from the install tree.

func UnpackCompilerToolchain 

func UnpackCompilerToolchain(toolchainPath, dstDir string) error

UnpackCompilerToolchain unpacks a compiler toolchain to a target directory. This omits the rust toolchain components since they are unused by COS and use a significant amount of space.

func UnpackKernelHeaders 

func UnpackKernelHeaders(headersPath, dstDir string) error

UnpackKernelHeaders unpacks kernel headers to a target directory.

Types

type Config 

type Config struct {
	// The name of the package.
	PackageName string
	// The version of the package.
	PackageVersion string
	// The make command which will be used to compile all of the
	// modules in the package.
	MakeCommand string
	// A list of patches to apply to the package before it is built.
	// This is constructed from the PATCH[#] and PATCH_MATCH[#] arrays.
	Patches []string
	// The list of Modules in the package.
	Modules []Module
	// The make command which will be used to clean the package when
	// it is unbuilt or removed.
	Clean string
	// Whether or not the package should be automatically installed when
	// the kernel is upgraded.
	Autoinstall bool
	// A list of packages which should be built before this one.
	// Currently, this is only an annotation and does not affect the
	// build order.
	BuildDepends []string
	// A regex which specifies the kernels for which this package can
	// be built.
	BuildExclusiveKernel string
	// A regex which specifies which arches for which this package can
	// be built.
	BuildExclusiveArch string
	// The name of a script to run after adding the package..
	PostAdd string
	// The name of a script to run after building the package.
	PostBuild string
	// The name of a script to run after installing the package.
	PostInstall string
	// The name of a script to run after removing the package.
	PostRemove string
	// The name of a script to run before building the package.
	PreBuild string
	// The name of a script to run before installing the package.
	PreInstall string
}

Config is the set of configurations for a DKMS package. See ParseConfig for details on how to write a dkms.conf file to populate these values.

func LoadConfig 

func LoadConfig(pkg *Package) (*Config, error)

LoadConfig reads a dkms.conf file for a package and parses its contents. See ParseConfig for more details.

func ParseConfig 

func ParseConfig(contents string, pkg *Package) (*Config, error)

ParseConfig parses the contents of a dkms.conf file for a package, applying defaults where required.

The defaults are assigned as bash variables in a string which is prepended to the contents of dkms.conf. The resulting script is then sourced, and the shell variables after executing the script are collected into a Config.

In addition, the following DKMS variables are available as bash variables in dkms.conf: 

module: The package name (--module from the command line)
module_version: The package version (--module-version from the command line)
arch: The target architecture for the package.
build_id: The build id of the COS kernel for the package.
board: The board of the COS kernel for the package.
kernelver: The version of the kernel for the package.
dkms_tree: The path to the DKMS tree.
source_tree: The path to the user source tree.
kernel_source_dir: The path to the directory containing the COS kernel sources.

type Module 

type Module struct {
	// The Package that this module is a part of.
	Package *Package
	// The name that the module is expected to have after the MAKE command
	// is run for a Package. This should not include a .ko extension.
	BuiltName string
	// The directory where the module is expected to be after the MAKE command
	// is run for a Package. This should be relative to the Package's build
	// directory in the DKMS tree.
	BuiltLocation string
	// The name that will be used for the installed module. This should not
	// include a .ko extension.
	DestName string
	// The directory that the module will be copied to after it is installed.
	DestLocation string
	// Whether or not debug symbols will be stripped from the built module.
	Strip bool
}

A Module represents a single kernel module built as part of a Package.

func ModulesToInstall 

func ModulesToInstall(modules []Module, installTree string) ([]Module, error)

ModulesToInstall returns the list of modules which should be installed.

This takes a list of candidate modules to install and a directory where they would be installed and checks for each module if there is a newer version of that module already installed. If there is a newer or equal version already installed, the module is omitted from the output list and an info message is emitted.

func (*Module) BuiltPath 

func (module *Module) BuiltPath() string

BuiltPath returns the path where this module is expected to be built within the DKMS tree.

func (*Module) CacheBuiltPath 

func (module *Module) CacheBuiltPath() string

CacheBuiltPath returns the path where this module is expected to be built within the cache DKMS tree.

func (*Module) DestPath 

func (module *Module) DestPath() string

DestPath returns the path where this module is expected to be installed in the install tree.

type Options 

type Options struct {
	// Version tells cos-dkms to print out the version, then exit.
	Version bool
	// Latest tells cos-dkms to use the latest compatible version of the
	// package that is available in the DKMS tree.
	Latest bool
	// KernelConfig tells Build where to find the kernel .config file
	// when preparing the kernel, if it is not in the standard COS location.
	Force bool
	// ForceVersionOverride tells Install to skip the version check when
	// installing modules which already have a potentially newer version
	// installed.
	ForceVersionOverride bool
	// InsertOnInstall tells Install to insert each kernel module into the
	// running kernel after it has been installed. This will take into
	// account dependencies on any modules in the install tree and the
	// built-in modules tree.
	InsertOnInstall bool
	// ModprobeOnInstall tells Install to modprobe each kernel module after
	// it has been installed, thus inserting it into the running kernel.
	// Note that a very specific set of mounts is required for this to work
	// on COS instances because the default kernel modules tree is read-only.
	ModprobeOnInstall bool
	// NoDepmod tells install not to run depmod before modprobe, if
	// ModprobeOnInstall is specified. This can save time if module
	// dependencies don't need to be recalculated.
	NoDepmod bool
	// Jobs tells Build how many parallel jobs should be used when running
	// the MAKE command for each module.
	Jobs int
	// GCSBucket is the name of the GCS bucket to use as a cache. This will
	// be used during:
	// Add - to download module sources if they are not present locally and
	//   to upload module sources if Upload is specified and they are not
	//   present in the cache.
	// Build and Install - to download built modules if they are present in
	//   the cache and to upload built modules if Upload is specified and
	//   they are not present in the cache.
	// Remove - to remove module sources and built modules if they are present
	//   in the cache.
	// Unbuild - to remove built modules if they are present in the cache.
	//
	// If the bucket includes a path, that path will be used as the prefix
	// for cache operations. For instance, if the value of GCSBucket is
	// gs://my-bucket/my-dkms-root/, then all operations will be relative
	// to my-dkms-root/ within the bucket.
	GCSBucket string
	// Upload determines whether or not to upload module sources or built
	// modules to the GCSBucket during Add, Build, and Install.
	Upload bool
	// MakeVariables is a string containing variables which will be passed
	// to the MAKE command when building modules in Build.
	MakeVariables string
	// InstallBuildDependencies tells Build and Install to build the COS
	// compiler toolchain and kernel headers before running a build.
	InstallBuildDependencies bool
	// LSBReleasePath is the path to the LSB Release file that will be used
	// to fill in the package Build and Board values if they are not otherwise
	// specified.
	LSBReleasePath string
}

Options is the set of options which can be used to control the behavior of various DKMS commands. Keeping these in one struct is simpler and easier to work with than breaking them down by command, since most DKMS commands will directly call another and need to pass along the arguments for that command as well (for instance, Install calls Build and needs to pass all corresponding Build options).

type Package 

type Package struct {
	// These fields disambiguate which package is being referred to.
	// For instance, two packages with the same source code but which have been compiled
	// for different kernel versions are considered different and will have different
	// corresponding paths within the DKMS tree.
	Name          string
	Version       string
	Arch          string
	KernelVersion string
	BuildId       string
	Board         string
	// This is the collection of trees which will be used as the base directories
	// for the paths related to this package.
	Trees *Trees
}

A Package contains the information necessary to manage a collection of kernel modules. Specifically, a Package has all of the fields required for constructing the paths required to perform DKMS operations on that package, such as compiling and installing modules.

func (*Package) BuildDir 

func (pkg *Package) BuildDir() string

BuildDir returns the path to the package build directory within the DKMS tree.

func (*Package) CacheBuildDir 

func (pkg *Package) CacheBuildDir() string

CacheBuildDir returns the path to the package build directory within the cache DKMS tree.

func (*Package) CacheConfigPath 

func (pkg *Package) CacheConfigPath() string

CacheConfigPath returns the path to package's configuration within the cache DKMS tree.

func (*Package) CacheSourceDir 

func (pkg *Package) CacheSourceDir() string

CacheSourceDir returns the path to the package sources within the cache DKMS tree.

func (*Package) ConfigPath 

func (pkg *Package) ConfigPath() string

ConfigPath returns the path to package's configuration within the DKMS tree.

func (*Package) Path 

func (pkg *Package) Path() string

Path returns the disambiguated path to the package within the DKMS tree.

func (*Package) SourceDir 

func (pkg *Package) SourceDir() string

SourceDir returns the path to the package sources within the DKMS tree.

func (*Package) SourceTreeDir 

func (pkg *Package) SourceTreeDir() string

SourceTreeDir returns the path to the package within the user's source tree.

type PackageStatus 

type PackageStatus int

PackageStatus is an enum representing the different possible states for a package. A package can be Added, Built, Installed, or Broken. See the IsAdded, IsBuilt, etc., functions for more detail. 

const (
	Broken PackageStatus = iota
	Added
	Built
	Installed
)

func CachedStatus 

func CachedStatus(ctx context.Context, pkg *Package, cache *gcs.GCSBucket) PackageStatus

CachedStatus returns the status of a DKMS package. If a module is built or added only in the cache, the module will have a status of Built or Added, respectively.

func Status 

func Status(pkg *Package) PackageStatus

Status returns the status of a DKMS package.

func (PackageStatus) String 

func (i PackageStatus) String() string

type Trees 

type Trees struct {
	// The path to the DKMS tree, where package sources will be copied and package
	// build directories will be maintained.
	Dkms string
	// The path to the install tree where packages will be installed.
	Install string
	// The path to the user source tree from which package sources will be copied
	// into the DKMS tree.
	Source string
	// The path to the kernel source directory which will be used for compiling
	// the modules within a package.
	Kernel string
	// The path to the directory where compiled (possibly read-only) kernel modules are
	// stored. This is separate from the install tree because the built-in kernel modules
	// tree in COS is read-only.
	KernelModules string
}

Trees is the collection of directories which DKMS will use as the root paths for adding, compiling, and installing packages.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.