PCI_IOV_SCHEMA(9)

✨ NAME ✨

okay so bestie, welcome to pci_iov_schema 💖 — this is the PCI SR-IOV config schema interface, and honestly it's giving "build a lil blueprint for your device settings" energy. The whole squad of functions is:

• pci_iov_schema
• pci_iov_schema_alloc_node
• pci_iov_schema_add_bool
• pci_iov_schema_add_string
• pci_iov_schema_add_uint8
• pci_iov_schema_add_uint16
• pci_iov_schema_add_uint32
• pci_iov_schema_add_uint64
• pci_iov_schema_add_unicast_mac

(It lives in the Kernel Developer's Manual, section 9, iykyk 🫶)

---

🌸 SYNOPSIS 🌸

First you gotta include the lore:

#include <machine/stdarg.h>
#include <sys/nv.h>
#include <sys/iov_schema.h>

Then the whole cast of characters:

nvlist_t *
pci_iov_schema_alloc_node(void);

void
pci_iov_schema_add_bool(nvlist_t *schema, const char *name,
    uint32_t flags, int defaultVal);

void
pci_iov_schema_add_string(nvlist_t *schema, const char *name,
    uint32_t flags, const char *defaultVal);

void
pci_iov_schema_add_uint8(nvlist_t *schema, const char *name,
    uint32_t flags, uint8_t defaultVal);

void
pci_iov_schema_add_uint16(nvlist_t *schema, const char *name,
    uint32_t flags, uint16_t defaultVal);

void
pci_iov_schema_add_uint32(nvlist_t *schema, const char *name,
    uint32_t flags, uint32_t defaultVal);

void
pci_iov_schema_add_uint64(nvlist_t *schema, const char *name,
    uint32_t flags, uint64_t defaultVal);

void
pci_iov_schema_add_unicast_mac(nvlist_t *schema, const char *name,
    uint32_t flags, const uint8_t *defaultVal);

---

💅 DESCRIPTION 💅

So the PCI Single-Root I/O Virtualization (SR-IOV) configuration schema? It's literally just a data structure that describes the device-specific config parameters a PF driver will accept once SR-IOV is enabled on the PF device. Main character behavior tbh 👑

Every PF driver defines two schema instances:

• the PF schema — describes config that applies to the PF device as a whole
• the VF schema — describes config that applies to an individual VF device

And bestie, different VF devices can totally have different config applied to them, as long as each VF's config conforms to the VF schema. Slay. ✨

A PF driver builds a config schema by first allocating a schema node, then adding configuration parameter specifications to the schema. Each parameter spec = a name + a value type. Simple as that.

Config parameter names are case-insensitive. And it is an error to specify two or more config parameters with the same name. It's also an error to specify a config parameter that uses the same name as one used by the SR-IOV infrastructure itself. Peep iovctl.conf(5) for the docs on every config parameter the SR-IOV infrastructure uses. 🎀

The parameter type constrains the possible values that config parameter can take. That's the whole point, bestie.

🫶 required vs default (the flag drama)

A config parameter can be marked as required by setting the IOV_SCHEMA_REQUIRED flag in the flags argument. Required parameters must be specified by the user when SR-IOV is enabled. If the user forgets? The SR-IOV infrastructure will abort the request to enable SR-IOV and return an error to the user. no cap.

Alternatively, a config parameter can be given a default value by setting the IOV_SCHEMA_HASDEFAULT flag in the flags argument. If a parameter has a default value but the user never specified one, the SR-IOV infrastructure will apply defaultVal for that parameter in the config before passing it to the PF driver. And listen — it is an error for the value of the defaultVal parameter to not conform to the restrictions of the specified type. If this flag isn't set, then the defaultVal argument is just ignored. Also IOV_SCHEMA_HASDEFAULT is not compatible with IOV_SCHEMA_REQUIRED — it's an error to specify both on the same parameter. pick a lane bestie 😭

The SR-IOV infrastructure guarantees that all config parameters that are either specified as required or given a default value will be present in the config passed to the PF driver. Config parameters that are neither required nor given a default are optional — they may or may not show up in the config passed to the PF driver. 🤷

It is highly recommended that a PF driver reserve the use of optional parameters for configuration that is truly optional.

Example time (and this one's iconic):

• Say a Network Interface PF device has the option to encapsulate all traffic to and from a VF device in a vlan tag. The PF driver could expose that as a "vlan" parameter accepting an integer argument specifying the vlan tag. In this case it would be appropriate to set the "vlan" parameter as an optional parameter, since it would be legitimate for a VF to be configured with no vlan tagging enabled at all. vibe check: passed ✅
• But flip it: if the PF device had a boolean option controlling whether the VF was allowed to change its MAC address, that would not be appropriate to set as optional. The PF driver must either allow the MAC to change or not — so it'd be more appropriate to document the default behaviour by specifying a default value in the schema (or potentially force the user to make the choice by setting the parameter to be required). periodt.

Config parameters that have security implications must default to the most secure configuration possible. 🔒 do not play with this one.

Also, all device-specific config parameters must be documented in the manual page for the PF driver, or in a separate manual page that's cross-referenced from the main driver manual page. docs or it didn't happen 💖

🌈 the "don't bother checking" part

It is not necessary for a PF driver to check for failure from any of these functions. If an error occurs, it's flagged in the schema. The pci_iov_attach(9) function checks for this error and will fail to initialize SR-IOV on the PF device if an error is set in the schema. If that happens, it's recommended that the PF driver still succeed in attaching and run with SR-IOV disabled on the device. graceful queen energy 👑

🧚 the functions themselves

• pci_iov_schema_alloc_node() — allocates an empty configuration schema. You don't need to check for failure here either. The SR-IOV infrastructure will gracefully handle failure to allocate a schema and will simply not enable SR-IOV on the PF device.
• pci_iov_schema_add_bool() — specifies a config parameter in the given schema with the name name and a boolean type. Boolean values can only be true or false (1 or 0, respectively).
• pci_iov_schema_add_string() — specifies a config parameter in the given schema with the name name and a string type. String values are standard C strings.
• pci_iov_schema_add_uint8() — specifies a config parameter in the given schema with the name name and a uint8_t type. Values of type uint8_t are unsigned integers in the range 0 to 255, inclusive.
• pci_iov_schema_add_uint16() — specifies a config parameter in the given schema with the name name and a uint16_t type. Values of type uint16_t are unsigned integers in the range 0 to 65535, inclusive.
• pci_iov_schema_add_uint32() — specifies a config parameter in the given schema with the name name and a uint32_t type. Values of type uint32_t are unsigned integers in the range 0 to (2**32 - 1), inclusive.
• pci_iov_schema_add_uint64() — specifies a config parameter in the given schema with the name name and a uint64_t type. Values of type uint64_t are unsigned integers in the range 0 to (2**64 - 1), inclusive.
• pci_iov_schema_add_unicast_mac() — specifies a config parameter in the given schema with the name name and a unicast-mac type. Values of type unicast-mac are binary values exactly 6 bytes long. The MAC address is guaranteed to not be a multicast or broadcast address. 🦋

---

⭐ RETURN VALUES ⭐

• pci_iov_schema_alloc_node() — returns a pointer to the allocated schema, or NULL if a failure occurs.

---

🦋 SEE ALSO 🦋

• pci(9)
• PCI_IOV_ADD_VF(9)
• PCI_IOV_INIT(9)

---

👑 AUTHORS 👑

This manual page was written by Ryan Stone <rstone@FreeBSD.org>. 💜

---

okay that's the whole page bestie, go forth and schema 🫶✨

Debian • July 8, 2015 • PCI_IOV_SCHEMA(9) — mwah, that's the version and date, ty for coming to my ted talk 💅💖