ipmctl

package
v0.0.0-...-b34e4e8 Latest Latest
Warning

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

 Go to latest Published: Mar 4, 2026 License: BSD-2-Clause-Patent Imports: 12 Imported by: 5

README

Go language bindings for the IPMCTL API

Go bindings for the ipmctl native-C library to facilitate management of PMem (Intel(R) Optane(TM) persistent memory) modules from an application written in Go.

The bindings require libipmctl-devel (or distro equivalent) package to be installed. To install please follow steps in the ipmctl github instructions.

These bindings are currently working against ipmctl 2.x.

This is not a general purpose set of ipmctl go bindings but provides a set of capabilities tailored to the specific needs of DAOS, the PMem related features are as follows:

  • device discovery
  • device firmware version discovery
  • device firmware update

Functionality is exposed through the package's IpmCtl public interface.

Documentation

Overview

Package ipmctl provides Go bindings for libipmctl Native Management API

Package ipmctl provides Go bindings for libipmctl Native Management API

Index

Constants

View Source 
const (
	// FWUpdateStatusUnknown represents unknown status
	FWUpdateStatusUnknown = 0
	// FWUpdateStatusStaged represents a staged FW update to be loaded on reboot
	FWUpdateStatusStaged = 1
	// FWUpdateStatusSuccess represents a successfully applied FW update
	FWUpdateStatusSuccess = 2
	// FWUpdateStatusFailed represents a failed FW update
	FWUpdateStatusFailed = 3
)

FWUpdateStatus values represent the ipmctl fw_update_status enum

Variables

View Source 
var (
	NVMMajorVersionsSupported = []int{2, 3}
)

Functions

func Rc2err 

func Rc2err(label string, rc C.int) error

Rc2err returns an failure if rc != NVM_SUCCESS.

TODO: print human readable error with provided lib macros

Types

type DeviceDiscovery 

type DeviceDiscovery struct {
	All_properties_populated uint8
	Pad_cgo_0                [3]byte
	Device_handle            [4]byte
	Physical_id              uint16
	Vendor_id                uint16
	Device_id                uint16
	Revision_id              uint16
	Channel_pos              uint16
	Channel_id               uint16
	Memory_controller_id     uint16
	Socket_id                uint16
	Node_controller_id       uint16
	Pad_cgo_1                [2]byte
	Memory_type              uint32
	Dimm_sku                 uint32
	Manufacturer             [2]uint8
	Serial_number            [4]uint8
	Subsystem_vendor_id      uint16
	Subsystem_device_id      uint16
	Subsystem_revision_id    uint16
	Manufacturing_info_valid uint8
	Manufacturing_location   uint8
	Manufacturing_date       uint16
	Part_number              PartNumber
	Fw_revision              Version
	Fw_api_version           Version
	Pad_cgo_2                [5]byte
	Capacity                 uint64
	Interface_format_codes   [9]uint16
	Security_capabilities    _Ctype_struct_device_security_capabilities
	Device_capabilities      _Ctype_struct_device_capabilities
	Uid                      DeviceUID
	Lock_state               uint32
	Manageability            uint32
	Controller_revision_id   uint16
	Reserved                 [48]uint8
	Pad_cgo_3                [6]byte
}

DeviceDiscovery struct represents Go equivalent of C.struct_device_discovery from nvm_management.h (NVM API) as reported by "go tool cgo -godefs nvm.go"

type DeviceFirmwareInfo 

type DeviceFirmwareInfo struct {
	ActiveFWVersion Version // currently running FW version
	StagedFWVersion Version // FW version to be applied on next reboot
	FWImageMaxSize  uint32  // maximum FW image size in 4096-byte chunks
	FWUpdateStatus  uint32  // last update status
	Reserved        [4]uint8
}

DeviceFirmwareInfo represents an ipmctl device_fw_info structure

type DeviceUID 

type DeviceUID [22]byte

DeviceUID represents the Go equivalent of an NVM_UID string buffer

func (DeviceUID) String 

func (d DeviceUID) String() string

String converts the DeviceUID bytes to a string

type IpmCtl 

type IpmCtl interface {
	// Init verifies the version of the library is compatible.
	Init(logging.Logger) error
	// GetModules discovers persistent memory modules. Note that the Linux
	// implementation has been seen to have intermittent long latency (multiple minutes)
	// on calls to this API endpoint (27-Feb-2024).
	GetModules(logging.Logger) ([]DeviceDiscovery, error)
	// GetRegions discovers persistent memory regions.
	GetRegions(logging.Logger) ([]PMemRegion, error)
	// DeleteConfigGoals removes any pending but not yet applied PMem configuration goals.
	DeleteConfigGoals(logging.Logger) error
	// GetFirmwareInfo retrieves firmware information from persistent memory modules.
	GetFirmwareInfo(uid DeviceUID) (DeviceFirmwareInfo, error)
	// UpdateFirmware updates persistent memory module firmware.
	UpdateFirmware(uid DeviceUID, fwPath string, force bool) error
}

IpmCtl is the interface that provides access to libipmctl.

type NvmMgmt 

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

NvmMgmt is an implementation of the IpmCtl interface which exercises libipmctl's NVM API.

func (*NvmMgmt) DeleteConfigGoals 

func (n *NvmMgmt) DeleteConfigGoals(log logging.Logger) error

DeleteConfigGoals removes any pending but not yet applied PMem configuration goals.

func (*NvmMgmt) GetFirmwareInfo 

func (n *NvmMgmt) GetFirmwareInfo(uid DeviceUID) (fw DeviceFirmwareInfo, err error)

GetFirmwareInfo fetches the firmware revision and other information from the device

func (*NvmMgmt) GetModules 

func (n *NvmMgmt) GetModules(log logging.Logger) (devices []DeviceDiscovery, err error)

GetModules queries number of PMem modules and retrieves device_discovery structs for each before converting to Go DeviceDiscovery structs.

func (*NvmMgmt) GetRegions 

func (n *NvmMgmt) GetRegions(log logging.Logger) (regions []PMemRegion, err error)

GetRegions queries number of PMem regions and retrieves region structs for each before converting to Go PMemRegion structs.

func (*NvmMgmt) Init 

func (n *NvmMgmt) Init(log logging.Logger) error

Init verifies library version is compatible with this application code.

func (*NvmMgmt) UpdateFirmware 

func (n *NvmMgmt) UpdateFirmware(uid DeviceUID, fwPath string, force bool) error

UpdateFirmware updates the firmware on the device

type PMemRegion 

type PMemRegion struct {
	IsetId        uint64     // Unique identifier of the region.
	Type          uint32     // The type of region.
	Capacity      uint64     // Size of the region in bytes.
	Free_capacity uint64     // Available size of the region in bytes.
	Socket_id     int16      // socket ID
	Dimm_count    uint16     // The number of PMem modules in this region.
	Dimms         [24]uint16 // Unique ID's of underlying PMem modules.
	Health        uint32     // Rolled up health of the underlying PMem modules.
	Reserved      [40]uint8  // reserved
}

PMemRegion represents Go equivalent of C.struct_region from nvm_management.h (NVM API) as reported by "go tool cgo -godefs nvm.go".

type PMemRegionHealth 

type PMemRegionHealth uint32

PMemRegionHealth represents PMem region health. 

const (
	RegionHealthNormal  PMemRegionHealth // All underlying PMem module capacity is available.
	RegionHealthError                    // Issue with some or all of the underlying PMem module capacity.
	RegionHealthUnknown                  // The region health cannot be determined.
	RegionHealthPending                  // A new memory allocation goal has been created but not applied.
	RegionHealthLocked                   // One or more of the underlying PMem modules are locked.
)

PMemRegionHealth values represent the ipmctl region_health enum. Rolled-up health of the underlying PMem modules from which the REGION is created. Constant values start at 1.

func PMemRegionHealthFromString 

func PMemRegionHealthFromString(in string) PMemRegionHealth

func (PMemRegionHealth) String 

func (pmrh PMemRegionHealth) String() string

type PMemRegionType 

type PMemRegionType uint32

PMemRegionType represents PMem region type. 

const (
	RegionTypeUnknown        PMemRegionType = iota
	RegionTypeAppDirect                     // App Direct mode.
	RegionTypeNotInterleaved                // Non-interleaved App Direct mode.
	RegionTypeVolatile                      // Volatile.
)

PMemRegionType values represent the ipmctl region_type enum. Type of region.

func PMemRegionTypeFromString 

func PMemRegionTypeFromString(in string) PMemRegionType

func (PMemRegionType) String 

func (pmrt PMemRegionType) String() string

type PartNumber 

type PartNumber [21]byte

PartNumber represents the part number string for an NVM device.

func (PartNumber) String 

func (p PartNumber) String() string

String converts the PartNumber bytes to a string

type Version 

type Version [25]byte

Version represents the Go equivalent of an NVM_VERSION string buffer

func (Version) String 

func (v Version) String() string

String converts the Version bytes to a string

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.