illumos: manual page: ddi_ufm_op

DDI_UFM(9E) Driver Entry Points DDI_UFM(9E)

NAME

ddi_ufm, ddi_ufm_op_nimages, ddi_ufm_op_fill_image, ddi_ufm_op_fill_slot,
ddi_ufm_op_getcaps, ddi_ufm_op_readimg - DDI upgradable firmware module
entry points

SYNOPSIS

typedef struct ddi_ufm_handle ddi_ufm_handle_t
typedef struct ddi_ufm_ops ddi_ufm_ops_t

#include <sys/ddi_ufm.h>

int
ddi_ufm_op_getcaps(ddi_ufm_handle_t *uhp, void *drv_arg,
ddi_ufm_cap_t *caps);

int
ddi_ufm_op_nimages(ddi_ufm_handle_t *uhp, void *drv_arg, uint_t *nimgp);

int
ddi_ufm_op_fill_image(ddi_ufm_handle_t *uhp, void *drv_arg, uint_t imgno,
ddi_ufm_image_t *imgp);

int
ddi_ufm_op_fill_slot(ddi_ufm_handle_t *uhp, void *drv_arg, uint_t imgno,
uint_t slotno, ddi_ufm_slot_t *slotp);

int
ddi_ufm_op_readimg(ddi_ufm_handle_t *uhp, void *drv_arg, uint_t imgno,
uint_t slotno, uint64_t len, uint64_t offset, void *buf,
uint64_t *nreadp);

INTERFACE LEVEL

Evolving - This interface is evolving still in illumos. API and ABI
stability is not guaranteed.

PARAMETERS

uhp A handle corresponding to the device's UFM handle. This is
the same value as returned in ddi_ufm_init(9F).

drv_arg This is a private value that the driver passed in when
calling ddi_ufm_init(9F).

nimgp A pointer that the driver should set with a number of images.

imgno An integer indicating which image information is being
requested for.

imgp An opaque pointer that represents a UFM image.

slotno An integer indicating which slot information is being
requested for.

slotp An opaque pointer that represents a UFM slot.

len Indicates the number of bytes from a firmware payload that
are desired.

offset Indicates an offset in a firmware payload to start reading
from.

buf A buffer to place raw firmware data from the device into.

nreadp A pointer whose value should be updated with the number of
bytes actually read from the image.

DESCRIPTION

Upgradable firmware modules (UFM) are a potential component of many
devices. These interfaces aim to provide a simple series of callbacks for
a device driver to implement such that it is easy to report information and
in the future, manipulate firmware modules.

UFM Background

UFMs come in different flavors and styles that vary from device to device.
"Firmware" generally refers to some form of software that runs on a device
and is often packaged up as a binary payload. However, many things that
aren't always called "firmware", such as EEPROM images, CPU microcode,
flash based configuration, and more, are all just as important here. Take
for example a hard drive. While it is a field replaceable unit (FRU), it
also contains some amount of firmware that manages the drive which can be
updated independently of replacing the drive.

The motherboard often has a UFM in the form of the BIOS or UEFI. The
Lights Out Management controller on a system has a UFM, which is usually
the entire system image. CPUs also have a UFM in the form of microcode.

An important property of a UFM is that it is a persistent part of the
device itself. For example, many WiFi device drivers are required to send
a binary blob of firmware to the device after every reset. Because these
images are not persistent parts of the device and must be upgraded by
either changing the device driver or related system files, we do not
consider these UFMs.

There are also devices that have firmware which is a part of the device,
but may not be upgradable from the running OS. This may be because the
vendor doesn't have tooling to upgrade the image or because the firmware
image itself cannot be upgraded in the field at all. For example, a
YubiKey has a firmware image that's burned into it in the factory, but
there is no way to change the firmware on it short of replacing the device
in its entirety. However, because these images are a permanent and
persistent part of the device, we also consider them a UFM.

Images and Slots

A device that supports UFMs is made up of one or more distinct firmware
images. Each image has its own unique purpose. For example, a motherboard
may have both a BIOS and a CPLD image, each of which has independent
firmware revisions.

A given image may have a number of slots. A slot represents a particular
version of the image. Only one slot is considered the active slot. It
represents the currently running version of the image. Devices support
multiple slots so that an image can be downloaded to an inactive slot
without risking damage to the active slot. This ensures that a power-loss
or failure halfway through writing to a slot doesn't leave the device with
corrupted firmware.

The various entry points are designed such that all a driver has to do is
provide information about the image and its slots to the kernel, it does
not have to wrangle with how that is marshalled to users and the appearance
of those structures.

Registering with the UFM Subsystem

During a device driver's attach(9E) entry point, a device driver should
register with the UFM subsystem by filling out a UFM operations vector and
then calling ddi_ufm_init(9F). The driver may pass in a value, usually a
pointer to its soft state pointer, which it will then receive when its
subsequent entry points are called.

Once the driver has finished initializing, it must call ddi_ufm_update(9F)
to indicate that the driver is in a state where it's ready to receive calls
to the entry points.

The various UFM entry points may be called from an arbitrary kernel
context. However, they will only ever be called from a single thread at a
given time.

UFM operations vector

The UFM operations vector is a structure that has the following members:

typedef struct ddi_ufm_ops {
int (*ddi_ufm_op_nimages)(ddi_ufm_handle_t *uhp, void *drv_arg,
uint_t *nimgp);
int (*ddi_ufm_op_fill_image)(ddi_ufm_handle_t *uhp, void *drv_arg,
uint_t imgno, ddi_ufm_image_t *imgp);
int (*ddi_ufm_op_fill_slot)(ddi_ufm_handle_t *uhp, void *drv_arg,
int imgno, ddi_ufm_image_t *img, uint_t slotno,
ddi_ufm_slot_t *slotp);
int (*ddi_ufm_op_getcaps)(ddi_ufm_handle_t *uhp, void *drv_arg,
ddi_ufm_cap_t *caps);
int (*ddi_ufm_op_readimg)(ddi_ufm_handle_t *uhp, void *drv_arg,
uint_t imgno, uint_t slotno, uint64_t len, uint64_t offset,
void *buf, uint64_t *nreadp);
} ddi_ufm_ops_t;

The ddi_ufm_op_nimages() and ddi_ufm_op_readimg() entry points are
optional. If a device only has a single image, then there is no
requirement to implement the ddi_ufm_op_nimages() entry point and it may be
set to NULL. The system will assume that there is only a single image.

Slots and images are numbered starting at zero. If a driver indicates
support for multiple images, through the ddi_ufm_op_nimages() entry point,
or slots, by using the ddi_ufm_image_set_nslots(9F) function in the
ddi_fum_op_fill_image() callback then the images or slots will be numbered
sequentially going from 0 to the number of images or slots minus one.
These values will be passed to the various entry points to indicate which
image and slot the system is interested in. It is up to the driver to
maintain a consistent view of the images and slots for a given UFM.

ddi_ufm_op_nimages()
The ddi_ufm_op_nimages() entry point is an optional entry point that
answers the question of how many different, distinct firmware images are
present on the device. Once the driver determines how many are present, it
should set the value in nimgp to the determined value.

It is legal for a device to pass in zero for this value, which indicates
that there are none present.

Upon successful completion, the driver should return 0. Otherwise, the
driver should return the appropriate error number. For a full list of
error numbers, see Intro(2). Common values are:

EIO An error occurred while communicating with the
device to determine the number of firmware images.

ddi_ufm_op_fill_image()
The ddi_ufm_op_fill_image() entry point is used to fill in information
about a given image. The value in imgno is used to indicate which image
the system is asking to fill information about. If the driver does not
recognize the image ID in imgno then it should return an error.

The ddi_ufm_image_t structure passed in imgp is opaque. To fill in
information about the image, the driver should call the functions described
in ddi_ufm_image(9F).

The driver must call the ddi_ufm_image_set_desc(9F) function to set a
description of the image which indicates its purpose. This should be a
human-readable string. In addition, the driver must call the
ddi_ufm_image_set_nslots(9F) function to indicate the number of slots that
the device supports for that particular firmware image. The driver may
also set any ancillary data that it deems may be useful with the
ddi_ufm_image_set_misc(9F) function. This function takes an nvlist,
allowing the driver to set arbitrary keys and values.

Once the driver has finished setting all of the information about the image
then the driver should return 0. Otherwise, the driver should return the
appropriate error number. For a full list of error numbers, see Intro(2).
Common values are:

EINVAL The image indicated by imgno is unknown.

EIO An error occurred talking to the device while
trying to fill out firmware image information.

ENOMEM The driver was unable to allocate memory while
filling out image information.

ddi_ufm_op_fill_slot()
The ddi_ufm_op_fill_slot() function is used to fill in information about a
specific slot for a specific image. The value in imgno indicates the image
the system wants slot information for and the value in slotno indicates
which slot of that image the system is interested in. If the device driver
does not recognize the value in either or imgno or slotno, then it should
return an error.

The ddi_ufm_slot_t structure passed in slotp is opaque. To fill in
information about the image the driver should call the functions described
in ddi_ufm_slot(9F).

The driver should call the ddi_ufm_slot_set_version(9F) function to
indicate the version of the UFM. The version is a device-specific
character string. It should contain the current version of the UFM as a
human can understand it and it should try to match the format used by
device vendor.

The ddi_ufm_slot_set_attrs(9F) function should be used to set the
attributes of the UFM slot. These attributes include the following
enumeration values:

DDI_UFM_ATTR_READABLE
The DDI_UFM_ATTR_READABLE attribute indicates that the
firmware image in the specified slot may be read, even if the
device driver does not currently support such functionality.

DDI_UFM_ATTR_WRITEABLE
The DDI_UFM_ATTR_WRITEABLE attribute indicates that the
firmware image in the specified slot may be updated, even if
the driver does not currently support such functionality.

DDI_UFM_ATTR_ACTIVE
The DDI_UFM_ATTR_ACTIVE attribute indicates that the firmware
image in the specified slot is the active (i.e. currently
running) firmware. Only one slot should be marked active.

DDI_UFM_ATTR_EMPTY
The DDI_UFM_ATTR_EMPTY attribute indicates that the specified
slot does not currently contain any firmware image.

If the driver supports the ddi_ufm_op_readimg() entry point, then the
driver should attempt to determine the size in bytes of the image in the
slot and indicate that by calling the ddi_ufm_slot_set_imgsize(9F)
function.

Finally, if there are any device-specific key-value pairs that form useful,
ancillary data, then the driver should assemble an nvlist and pass it to
the ddi_ufm_slot_set_misc(9F) function.

Once the driver has finished setting all of the information about the slot
then the driver should return 0. Otherwise, the driver should return the
appropriate error number. For a full list of error numbers, see Intro(2).
Common values are:

EINVAL The image or slot indicated by imgno and slotno is
unknown.

EIO An error occurred talking to the device while
trying to fill out firmware slot information.

ENOMEM The driver was unable to allocate memory while
filling out slot information.

ddi_ufm_op_getcaps()
The ddi_ufm_op_getcaps() function is used to indicate which DDI UFM
capabilities are supported by this driver instance. Currently, all UFM-
capable drivers are required to implement the DDI_UFM_CAP_REPORT
capability. The following capabilities are supported and the drivers
should return a bitwise-inclusive-OR of the following values:

DDI_UFM_CAP_REPORT
Indicates that the driver is capable of reporting UFM
information and implements the ddi_ufm_op_fill_slot()
and ddi_ufm_op_fill_image() entry points. It also
indicates, that it optionally implements
ddi_ufm_op_nimages() entry point.

DDI_UFM_CAP_READIMG
Indicates that the driver is capable of reading a binary
firmware payload off of a device.

The driver should indicate the supported capabilities by setting the value
in the caps parameter. Once the driver has populated caps with an
appropriate value, then the driver should return 0. Otherwise, the driver
should return the appropriate error number. For a full list of error
numbers, see Intro(2). Common values are:

EIO An error occurred talking to the device while
trying to discover firmware capabilities.

ENOMEM The driver was unable to allocate memory.

ddi_ufm_op_readimg()
The ddi_ufm_op_readimg() is an optional entry point that allows the system
to read a binary firmware payload from the device. The driver should read
the firmware payload indicated by both imgno and slotno. The driver should
check to make sure that the region requested, starting at offset bytes into
the image and len bytes long is valid for the image and if not, return the
error EINVAL. Data from the device should be copied into buf and the
number of bytes successfully read should be placed into nreadp.

Upon successfully reading this data, the driver should return 0. Otherwise
the driver should return the appropriate error number. For a full list of
error numbers, see Intro(2). Common values are:

EINVAL The image or slot indicate by imgno and slotno is
unknown. The combination of offset and len would
overflow or read from a region of the image which
is not valid. The device currently has an
alignment restriction and the requested offset and
length do not honor that.

EIO An error occurred while communicating with the
device to read the firmware image.

ENOTSUP The driver does not support reading a firmware
payload on this device or from a particular image
and slot.

Caching and Updates

The system will fetch firmware and slot information on an as-needed basis.
Once it obtains some information, it may end up caching this information on
behalf of the driver. Whenever the driver believes that something could
have changed then the driver must call ddi_ufm_update(9F). The driver does
not need to know for certain that something has changed. For example,
after a device reset or firmware upgrade, the driver doesn't need to check
if the firmware revision changed at all, it can simply call
ddi_ufm_update(9F).

Locking

All UFM operations on a single UFM handle will always be run serially.
However, the device driver may still need to apply adequate locking to its
structure members as other entry points may be called on the device in
parallel, which could access the same data structures and try to
communicate with the device.

Unregistering from the UFM subsystem

When a device driver is detached, it should unregister from the UFM
subsystem. To do so, the driver should call ddi_ufm_fini(9F). By the time
this function returns, the driver is guaranteed that no UFM entry points
will be called. However, if there are outstanding UFM related activity,
the function will block until it is terminated.

ioctl Interface
Userland consumers can access UFM information via a set of ioctls that are
implemented by the ufm(4D) driver.

CONTEXT

The various UFM entry points that a device driver must implement will
always be called from kernel context.