hardwaremapping

Documentation

Index

• Constants
• Variables
• type DeviceID
  • func ParseDeviceID(input string) (DeviceID, error)
  • func (did DeviceID) EncodeValues(key string, v *url.Values) error
  • func (did DeviceID) MarshalJSON() ([]byte, error)
  • func (did DeviceID) String() string
  • func (did DeviceID) ToValue() types.String
  • func (did *DeviceID) UnmarshalJSON(b []byte) error
• type ID
  • func ParseID(input string) (ID, error)
  • func (hmid ID) EncodeValues(key string, v *url.Values) error
  • func (hmid ID) MarshalJSON() ([]byte, error)
  • func (hmid ID) String() string
  • func (hmid ID) ToValue() types.String
  • func (hmid *ID) UnmarshalJSON(b []byte) error
• type Map
  • func ParseMap(input string) (Map, error)
  • func (hm Map) EncodeValues(key string, v *url.Values) error
  • func (hm Map) MarshalJSON() ([]byte, error)
  • func (hm Map) String() string
  • func (hm Map) ToValue() types.String
  • func (hm *Map) UnmarshalJSON(b []byte) error
• type Type
  • func ParseType(input string) (Type, error)
  • func (t Type) EncodeValues(key string, v *url.Values) error
  • func (t Type) MarshalJSON() ([]byte, error)
  • func (t Type) String() string
  • func (t Type) ToValue() types.String
  • func (t *Type) UnmarshalJSON(b []byte) error

Constants

const (

	// AttrNameDescription is the attribute key name of the description in a hardware mapping.
	// The Proxmox VE API attribute is named "description" while we name it "comment" internally since this naming is
	// generally used across the Proxmox VE web UI and API documentations. This still follows the
	// [Terraform "best practices"] as it improves the user experience by matching the field name to the naming used in
	// the human-facing interfaces.
	//
	// [Terraform "best practices"]: https://developer.hashicorp.com/terraform/plugin/best-practices/hashicorp-provider-design-principles#resource-and-attribute-schema-should-closely-match-the-underlying-api
	AttrNameDescription = "description"
)

Variables

var (
	// ErrIDMarshal indicates an error while marshalling a hardware mapping ID.
	ErrIDMarshal = function.NewFuncError("cannot unmarshal hardware mapping ID")

	// ErrIDParsing indicates an error while parsing a hardware mapping ID.
	ErrIDParsing = func(hmID string) error {
		return function.NewFuncError(fmt.Sprintf("%q is not a valid hardware mapping ID", hmID))
	}

	// ErrDeviceIDMarshal indicates an error while marshalling a hardware mapping device ID.
	ErrDeviceIDMarshal = function.NewFuncError("cannot marshal hardware mapping device ID")

	// ErrDeviceIDParsing indicates an error while parsing a hardware mapping device ID.
	ErrDeviceIDParsing = func(hmID string) error {
		return function.NewFuncError(
			fmt.Sprintf(
				"invalid value %q for hardware mapping device ID attribute %q: no match for regular expression %q",
				hmID,
				attrNameDeviceID,
				DeviceIDAttrValueRegEx.String(),
			),
		)
	}

	// ErrDeviceIDUnmarshal indicates an error while unmarshalling a hardware mapping device ID.
	ErrDeviceIDUnmarshal = function.NewFuncError("cannot unmarshal hardware mapping device ID")

	// ErrMapMarshal indicates an error while marshalling a hardware mapping.
	ErrMapMarshal = function.NewFuncError("cannot marshal hardware mapping")

	// ErrMapParsingFormat indicates an error the format of a hardware mapping while parsing.
	ErrMapParsingFormat = func(format string, attrs ...any) error {
		return function.NewFuncError(fmt.Sprintf(format, attrs...))
	}

	// ErrMapUnknownAttribute indicates an unknown hardware mapping attribute.
	ErrMapUnknownAttribute = func(attr string) error {
		return function.NewFuncError(fmt.Sprintf("unknown hardware mapping attribute %q", attr))
	}

	// ErrMapUnmarshal indicates an error while unmarshalling a hardware mapping.
	ErrMapUnmarshal = function.NewFuncError("cannot unmarshal hardware mapping")

	// ErrTypeIllegal indicates an error for an illegal hardware mapping type.
	ErrTypeIllegal = func(hmTypeName string) error {
		return function.NewFuncError(fmt.Sprintf("illegal hardware mapping type %q", hmTypeName))
	}

	// ErrTypeMarshal indicates an error while marshalling a hardware mapping type.
	ErrTypeMarshal = function.NewFuncError("cannot marshal hardware mapping type")

	// ErrTypeUnmarshal indicates an error while unmarshalling a hardware mapping type.
	ErrTypeUnmarshal = function.NewFuncError("cannot unmarshal hardware mapping type")
)

var (
	// TypePCI is an identifier for a PCI hardware mapping type.
	// Do not modify this package-global variable as it acts as a safer variant compared to "iota" based constants!
	TypePCI = Type{"pci"}

	// TypeUSB is an identifier for a PCI hardware mapping type.
	// Do not modify this package-global variable as it acts as a safer variant compared to "iota" based constants!
	TypeUSB = Type{"usb"}
)

var DeviceIDAttrValueRegEx = regexp.MustCompile(`^[0-9A-Fa-f]{4}:[0-9A-Fa-f]{4}$`)

DeviceIDAttrValueRegEx is the regular expression for device ID attribute value in a hardware mapping.

Types

type DeviceID

type DeviceID string

DeviceID represents a hardware mapping device ID. An ID is composed of two parts, either…

• a Vendor ID and device ID. This is the device class and subclass (two 8-bit numbers).
• Subsystem ID and Subsystem device ID. This identifies the assembly in which the device is contained. Subsystems have their vendor ID (from the same namespace as device vendors) and subsystem ID.

References:

• Linux Kernel Documentation — PCI drivers
• Linux Hardware Database
• Linux USB ID Repository
• man(5) — pci.ids

func ParseDeviceID

func ParseDeviceID(input string) (DeviceID, error)

ParseDeviceID parses a string that represents a hardware mapping device ID into a DeviceID.

func (DeviceID) EncodeValues

func (did DeviceID) EncodeValues(key string, v *url.Values) error

EncodeValues encodes a hardware mapping device ID field into a URL-encoded set of values.

func (DeviceID) MarshalJSON

func (did DeviceID) MarshalJSON() ([]byte, error)

MarshalJSON marshals a hardware mapping device ID into JSON value.

func (DeviceID) String

func (did DeviceID) String() string

String converts a DeviceID value into a string.

func (DeviceID) ToValue

func (did DeviceID) ToValue() types.String

ToValue converts a hardware mapping device ID into a Terraform value.

func (*DeviceID) UnmarshalJSON

func (did *DeviceID) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals a hardware mapping device ID.

type ID

type ID struct {
	// Name is the name of the hardware mapping.
	Name string

	// Type is the type of the hardware mapping.
	Type Type
}

ID represents a hardware mapping ID, composed of the type and identifier.

func ParseID

func ParseID(input string) (ID, error)

ParseID parses a string that represents a hardware mapping ID into a value of `ID`.

func (ID) EncodeValues

func (hmid ID) EncodeValues(key string, v *url.Values) error

EncodeValues encodes a hardware mapping ID field into a URL-encoded set of values.

func (ID) MarshalJSON

func (hmid ID) MarshalJSON() ([]byte, error)

MarshalJSON marshals a hardware mapping ID into JSON value.

func (ID) String

func (hmid ID) String() string

String converts an ID value into a string.

func (ID) ToValue

func (hmid ID) ToValue() types.String

ToValue converts a hardware mapping ID into a Terraform value.

func (*ID) UnmarshalJSON

func (hmid *ID) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals a hardware mapping ID.

type Map

type Map struct {
	// Description is the optional "description" for a hardware mapping for both TypePCI and TypeUSB.
	Description *string

	// Description is the required "ID" for a hardware mapping for both TypePCI and TypeUSB.
	ID DeviceID

	// IOMMUGroup is the optional "IOMMU group" for a hardware mapping for TypePCI.
	// The value is not mandatory for the Proxmox VE API, but causes a TypePCI to be incomplete when not set.
	// It is not used for TypeUSB.
	//
	// Using a pointer is required to prevent the default value of 0 to be used as a valid IOMMU group but differentiate
	// between and unset value instead.
	//
	// References:
	//   - [Proxmox VE Wiki — PCI Passthrough]
	//   - [Linux Kernel Documentations — VFIO - "Virtual Function I/O"]
	//   - [IOMMU DB]
	//
	// [Proxmox VE Wiki — PCI Passthrough]: https://pve.proxmox.com/wiki/PCI_Passthrough
	// [Linux Kernel Documentations — VFIO - "Virtual Function I/O"]: https://docs.kernel.org/driver-api/vfio.html
	// [IOMMU DB]: https://iommu.info
	IOMMUGroup *int64

	// Node is the required "node name" for a hardware mapping for both TypePCI and TypeUSB.
	Node string

	// Path is the "path" for a hardware mapping where this field is required for TypePCI but optional for
	// TypeUSB.
	Path *string

	// SubsystemID is the optional "subsystem ID" for a hardware mapping for TypePCI.
	// The value is not mandatory for the Proxmox VE API, but causes a TypePCI to be incomplete when not set.
	// It is not used for TypeUSB.
	SubsystemID DeviceID
}

Map represents a hardware mapping composed of multiple attributes.

func ParseMap

func ParseMap(input string) (Map, error)

ParseMap parses a string that represents a hardware mapping into a Map.

func (Map) EncodeValues

func (hm Map) EncodeValues(key string, v *url.Values) error

EncodeValues encodes a cluster mapping PCI map field into a URL-encoded set of values.

func (Map) MarshalJSON

func (hm Map) MarshalJSON() ([]byte, error)

MarshalJSON marshals a hardware mapping into JSON value.

func (Map) String

func (hm Map) String() string

String converts a Map value into a string.

func (Map) ToValue

func (hm Map) ToValue() types.String

ToValue converts a hardware mapping into a Terraform value.

func (*Map) UnmarshalJSON

func (hm *Map) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals a hardware mapping.

type Type

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

Type is the type of the hardware mapping.

func ParseType

func ParseType(input string) (Type, error)

ParseType converts the string representation of a hardware mapping type into the corresponding value. An error is returned if the input string does not match any known type.

func (Type) EncodeValues

func (t Type) EncodeValues(key string, v *url.Values) error

EncodeValues encodes a hardware mapping type field into a URL-encoded set of values.

func (Type) MarshalJSON

func (t Type) MarshalJSON() ([]byte, error)

MarshalJSON marshals a hardware mapping type into JSON value.

func (Type) String

func (t Type) String() string

String converts a Type value into a string.

func (Type) ToValue

func (t Type) ToValue() types.String

ToValue converts a hardware mapping type into a Terraform value.

func (*Type) UnmarshalJSON

func (t *Type) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals a hardware mapping type.