cdi

Documentation

Index

• Constants
• func ApplyHooksToContainer(hooksFilePath string, c instance.Container) error
• func GenerateFromCDI(isCore bool, inst instance.Instance, cdiID ID) (*ConfigDevices, *Hooks, error)
• type CDILogger
  • func NewCDILogger(l logger.Logger) *CDILogger
  • func (l *CDILogger) Debugf(format string, args ...any)
  • func (l *CDILogger) Errorf(format string, args ...any)
  • func (l *CDILogger) Info(args ...any)
  • func (l *CDILogger) Infof(format string, args ...any)
  • func (l *CDILogger) Tracef(format string, args ...any)
  • func (l *CDILogger) Warning(args ...any)
  • func (l *CDILogger) Warningf(format string, args ...any)
• type Class
  • func ToClass(c string) (Class, error)
• type ConfigDevices
  • func ReloadConfigDevicesFromDisk(pathsToConfigDevicesFilePath string) (ConfigDevices, error)
• type Hooks
• type ID
  • func ToCDI(id string) (*ID, error)
  • func (id ID) String() string
• type SymlinkEntry
• type Vendor
  • func ToVendor(vendor string) (Vendor, error)

Constants

const (
	// CDIHooksFileSuffix is the suffix for the file that contains the CDI hooks.
	CDIHooksFileSuffix = "_cdi_hooks.json"
	// CDIConfigDevicesFileSuffix is the suffix for the file that contains the CDI config devices.
	CDIConfigDevicesFileSuffix = "_cdi_config_devices.json"
	// CDIUnixPrefix is the prefix used for creating unix char devices
	// (e.g. cdi.unix.<device_name>.<encoded_dest_path>).
	CDIUnixPrefix = "cdi.unix"
	// CDIDiskPrefix is the prefix used for creating bind mounts (or 'disk' devices)
	// representing user space files required for a CDI passthrough
	// (e.g. cdi.disk.<device_name>.<encoded_dest_path>).
	CDIDiskPrefix = "cdi.disk"
)

Functions

func ApplyHooksToContainer

func ApplyHooksToContainer(hooksFilePath string, c instance.Container) error

ApplyHooksToContainer applies CDI hooks to a container by creating symlinks and updating the linker configuration using SFTP.

func GenerateFromCDI

func GenerateFromCDI(isCore bool, inst instance.Instance, cdiID ID) (*ConfigDevices, *Hooks, error)

GenerateFromCDI does several things: 1. Generate a CDI specification from a CDI ID and an instance. According the the specified 'vendor', 'class' and 'name' (this assembled triplet is called a fully-qualified CDI ID. We'll just call it ID in the context of this package), the CDI specification is generated. The CDI specification is a JSON-like format that describes a per-device configuration and general container edits. - Per-device configuration represents a single device identified by the CDI ID (e.g. /dev/nvidia0) It contains device-specific 'container edits' (device nodes, hooks and mounts). We only select those that matches the provided CDI ID (which can be a device index, uuid or 'all'). The hooks will be centralized in a single resource file that will be read and executed as a LXC `lxc.hook.mount` hook, through LXD's `callhook` command. - General container edits are instructions on how to modify the container when a CDI device is used. These edits are not specific to a single device, rather they apply to all devices of a given class/vendor. These edits must be applied if one or multiple devices are getting passed through (e.g. /dev/nvidia-uvm) 2. Process per-device configuration(s): we convert this information into a map of devices (keyed by their path given in the spec, it mapped to a map of device properties). We also collect mounts (but we do not process them yet) and hooks. 3. Process general container edits in the same fashion. 4. Process all the mounts collected from the spec in order to turn them into disk devices. This operations generate a side effect: it generates a list of indirect symlinks (see `specMountToLXDDev`) 5. Merge all the hooks (direct + indirect) into a single list of hooks.

Types

type CDILogger

type CDILogger struct {
	// contains filtered or unexported fields
}

CDILogger reuses LXD's shared logger to log the internal operations of the CDI spec generator.

func NewCDILogger

func NewCDILogger(l logger.Logger) *CDILogger

NewCDILogger creates a new CDI logger from a LXD logger instance.

func (*CDILogger) Debugf

func (l *CDILogger) Debugf(format string, args ...any)

Debugf logs at the DEBUG log level using a standard printf format string.

func (*CDILogger) Errorf

func (l *CDILogger) Errorf(format string, args ...any)

Errorf logs at the ERROR log level using a standard printf format string.

func (*CDILogger) Info

func (l *CDILogger) Info(args ...any)

Info logs a message (with optional context) at the INFO log level.

func (*CDILogger) Infof

func (l *CDILogger) Infof(format string, args ...any)

Infof logs at the INFO log level using a standard printf format string.

func (*CDILogger) Tracef

func (l *CDILogger) Tracef(format string, args ...any)

Tracef logs at the TRACE log level using a standard printf format string.

func (*CDILogger) Warning

func (l *CDILogger) Warning(args ...any)

Warning logs a message (with optional context) at the WARNING log level.

func (*CDILogger) Warningf

func (l *CDILogger) Warningf(format string, args ...any)

Warningf logs at the WARNING log level using a standard printf format string.

type Class

type Class string

Class represents the compatible CDI class.

const (
	// GPU is a single discrete GPU.
	GPU Class = "gpu"
	// IGPU is an integrated GPU.
	IGPU Class = "igpu"
	// MIG is a single MIG compatible GPU.
	MIG Class = "mig"
)

func ToClass

func ToClass(c string) (Class, error)

ToClass converts a string to a CDI class.

type ConfigDevices

type ConfigDevices struct {
	// UnixCharDevs is a slice of unix-char device configuration.
	UnixCharDevs []map[string]string `json:"unix_char_devs" yaml:"unix_char_devs"`
	// BindMounts is a slice of mount configuration.
	BindMounts []map[string]string `json:"bind_mounts" yaml:"bind_mounts"`
}

ConfigDevices represents devices and mounts that need to be configured from a CDI specification.

func ReloadConfigDevicesFromDisk

func ReloadConfigDevicesFromDisk(pathsToConfigDevicesFilePath string) (ConfigDevices, error)

ReloadConfigDevicesFromDisk reads the paths to the CDI configuration devices file from the disk. This is useful in order to cache the CDI configuration devices file so that wee don't have to re-generate a CDI spec whhen stopping the container.

type Hooks

type Hooks struct {
	// ContainerRootFS is the path to the container's root filesystem.
	ContainerRootFS string `json:"container_rootfs" yaml:"container_rootfs"`
	// LdCacheUpdates is a list of entries to update the ld cache.
	LDCacheUpdates []string `json:"ld_cache_updates" yaml:"ld_cache_updates"`
	// SymLinks is a list of entries to create a symlink.
	Symlinks []SymlinkEntry `json:"symlinks" yaml:"symlinks"`
}

Hooks represents all the hook instructions that can be executed by `lxd-cdi-hook`.

type ID

type ID struct {
	Vendor Vendor
	Class  Class
	Name   string
}

ID represents a Container Device Interface (CDI) identifier.

+------------+-------+------------------------------------------+ | Vendor | Class | Name | +---------------------------------------------------------------+ | nvidia.com | gpu | [dev_idx], [dev_uuid] or `all` | | | mig | [dev_idx]:[mig_idx], [dev_uuid] or `all` | | | igpu | [dev_idx], [dev_uuid] or `all` | +------------+-------+------------------------------------------+

Examples:

• nvidia.com/gpu=0
• nvidia.com/gpu=d1f1c76e-7a72-487e-b121-e6d2e5555dc8
• nvidia.com/gpu=all
• nvidia.com/mig=0:1
• nvidia.com/igpu=0

func ToCDI

func ToCDI(id string) (*ID, error)

ToCDI converts a string identifier to a CDI ID. Returns api.StatusError with status code set to http.StatusBadRequest if unable to parse CDI ID.

func (ID) String

func (id ID) String() string

String returns the string representation of the ID.

type SymlinkEntry

type SymlinkEntry struct {
	Target string `json:"target" yaml:"target"`
	Link   string `json:"link" yaml:"link"`
}

SymlinkEntry represents a symlink entry.

type Vendor

type Vendor string

Vendor represents the compatible CDI vendor.

const (
	// NVIDIA represents the Nvidia CDI vendor.
	NVIDIA Vendor = "nvidia.com"
	// AMD represents the AMD CDI vendor.
	AMD Vendor = "amd.com"
)

func ToVendor

func ToVendor(vendor string) (Vendor, error)

ToVendor converts a string to a CDI vendor.