Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrVPDInvalidTag = errors.New("vpd: invalid resource tag")
ErrVPDInvalidTag is returned when an unknown or invalid tag byte appears at a resource boundary.
var ErrVPDNotPresent = errors.New("vpd: not present for device")
ErrVPDNotPresent is returned by Device.VPD when the sysfs vpd file does not exist (the device does not expose VPD).
var ErrVPDTruncated = errors.New("vpd: truncated input")
ErrVPDTruncated is returned when the input ends before a complete resource boundary.
ErrVPDUnavailable is returned by Device.VPD when the device was not discovered through sysfs and therefore has no associated VPD file to read. Devices constructed via Info.ParseDevice fall into this category.
Functions ¶
func DeviceNamesByLinuxSystem ¶ added in v0.25.0
DeviceNamesByLinuxSystem returns a map, keyed by well-known Linux system string ("drm", "infiniband", "net", "nvme"), of lists of Linux device names associated with the supplied PCI Device.
For example, a ConnectX NIC may produce:
{
"infiniband": ["mlx5_0"],
"net": ["enp4s0"],
}
The map only contains keys for which at least one device name was found, so an empty map indicates no recognized system links for this device. Returns nil if the supplied device has no PCI address resolvable to a sysfs path.
Types ¶
type Device ¶
type Device struct {
// The PCI address of the device
Address string `json:"address"`
// The PCI address of the parent device
ParentAddress string `json:"parent_address"`
Vendor *pcidb.Vendor `json:"vendor"`
Product *pcidb.Product `json:"product"`
Revision string `json:"revision"`
Subsystem *pcidb.Product `json:"subsystem"`
// optional subvendor/sub-device information
Class *pcidb.Class `json:"class"`
// optional sub-class for the device
Subclass *pcidb.Subclass `json:"subclass"`
// optional programming interface
ProgrammingInterface *pcidb.ProgrammingInterface `json:"programming_interface"`
// Topology node that the PCI device is affined to. Will be nil if the
// architecture is not NUMA.
Node *topology.Node `json:"node,omitempty"`
Driver string `json:"driver"`
// for IOMMU Groups see also:
// https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/7/html/virtualization_deployment_and_administration_guide/sect-iommu-deep-dive
IOMMUGroup string `json:"iommu_group"`
// Modalias is the raw contents of the device's sysfs `modalias` file.
// Useful for callers that want to do custom vendor/device/class matching
// beyond what the pcidb lookup provides.
Modalias string `json:"modalias,omitempty"`
// Parent is the resolved parent Device pointer for this device (the
// PCIe upstream port or root complex device). It is nil for root
// devices. Populated after enumeration; not included in JSON output to
// avoid cycles. Use ParentAddress for the serialized form.
Parent *Device `json:"-"`
// Children are the resolved downstream Device pointers, in
// no particular order. Populated after enumeration; not included in
// JSON output.
Children []*Device `json:"-"`
}
func (*Device) Ancestors ¶ added in v0.25.0
Ancestors returns d's proper ancestors, nearest first: parent, grandparent, and so on up to the root. The returned slice is empty for a root device.
func (*Device) MarshalJSON ¶
NOTE(jaypipes) Device has a custom JSON marshaller because we don't want to serialize the entire PCIDB information for the Vendor (which includes all of the vendor's products, etc). Instead, we simply serialize the ID and human-readable name of the vendor, product, class, etc.
func (*Device) Root ¶ added in v0.25.0
Root returns the topmost device in d's chain (the ancestor whose Parent is nil). For a root device, Root returns d itself.
func (*Device) VPD ¶ added in v0.25.0
VPD returns the parsed Vital Product Data for the device, reading it from the device's sysfs `vpd` file. The sysfs root is taken from ctx, so a ctx built via option.WithChroot reads VPD from inside the chroot; context.Background() reads the live /sys.
The sysfs VPD file is typically root-readable only. Callers running without sufficient privilege will receive a wrapped permission error.
VPD returns ErrVPDUnavailable for devices with no resolvable PCI address (e.g. those constructed via Info.ParseDevice) and ErrVPDNotPresent for devices whose sysfs entry exists but exposes no `vpd` file.
type Info ¶
type Info struct {
// All PCI devices on the host system
Devices []*Device
// contains filtered or unexported fields
}
func New ¶
New returns a pointer to an Info struct that contains information about the PCI devices on the host system
func (*Info) GetDevice ¶
GetDevice returns a pointer to a Device struct that describes the PCI device at the requested address. If no such device could be found, returns nil.
func (*Info) JSONString ¶
JSONString returns a string with the PCI information formatted as JSON under a top-level "pci:" key
func (*Info) ParseDevice ¶
ParseDevice returns a pointer to a Device given its describing data. The PCI device obtained this way may not exist in the system; use GetDevice to get a *Device which is found in the system
func (*Info) YAMLString ¶
YAMLString returns a string with the PCI information formatted as YAML under a top-level "pci:" key
type VPD ¶ added in v0.25.0
type VPD struct {
// Identifier is the ASCII string from the 0x82 Identifier String
// resource. Typically a vendor-friendly product name.
Identifier string `json:"identifier,omitempty"`
// ReadOnly holds the keyword/value pairs from the 0x90 VPD-R section.
// Values are stored as raw bytes (without trailing padding spaces
// removed) so callers can decide how to interpret them.
ReadOnly map[string]string `json:"read_only,omitempty"`
// ReadWrite holds the keyword/value pairs from the 0x91 VPD-W
// section, if present.
ReadWrite map[string]string `json:"read_write,omitempty"`
}
VPD is a parsed PCI Vital Product Data block. The format is defined in the PCI Local Bus Specification (revision 2.2 and later) appendix I.
A VPD block consists of an Identifier String resource, one or more VPD-R (read-only) resources, optionally a VPD-W (read-write) resource, and an End Tag. Each VPD-R/VPD-W resource contains a sequence of 3-byte-keyword-prefixed fields: a two-character ASCII keyword (e.g. "PN", "EC", "SN", "V0"-"VZ"), a 1-byte length, and the value bytes.
Keywords with well-known meanings:
PN Part Number EC Engineering Change Level FG Fabric Geography LC Location MN Manufacturer ID PG Extended Capability SN Serial Number V0-VZ Vendor-specific Y0-YZ System-specific
Vendor-specific keywords are returned in ReadOnly/ReadWrite keyed by the two-character keyword name (e.g. "V3").
func ParseVPD ¶ added in v0.25.0
ParseVPD parses a raw VPD byte stream as read from /sys/bus/pci/devices/<addr>/vpd (or equivalent PCI config space VPD register window).
The parser is lenient: unknown large-resource tags are skipped using their declared length, and parsing terminates cleanly on the End tag (0x78) or on a zero byte (sometimes used as padding).
Source Files
Directories