DDI_UFM(9F) Kernel Functions for Drivers DDI_UFM(9F)

NAME

ddi_ufm, ddi_ufm_init, ddi_ufm_update, ddi_ufm_fini - DDI upgradable
firmware module interfaces

SYNOPSIS

#include <sys/ddi_ufm.h>

int
ddi_ufm_init(dev_info_t *dip, int version, ddi_ufm_ops_t *ops,
ddi_ufm_handle_t **ufmpp, void *drv_arg);

void
ddi_ufm_update(ddi_ufm_handle_t *ufmp);

void
ddi_ufm_fini(ddi_ufm_handle_t *ufmp);

INTERFACE LEVEL

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

PARAMETERS

dip Pointer to the devices dev_info structure for the specific
instance.

version A value which indicates the current revision of the interface
that the device supports. Should generally be set to
DDI_UFM_CURRENT_VERSION.

ops A pointer to a UFM operations structure. See ddi_ufm(9E) for
more information.

ufmp A pointer to the opaque handle returned from ddi_ufm_init().

ufmpp A pointer to store the opaque handle from ddi_ufm_init().

drv_arg A driver specific argument that will be passed to various
operations.

DESCRIPTION

These functions provide support for initializing and performing various
upgradeable firmware module (UFM) operations. For more information, please
see ddi_ufm(9E).

The ddi_ufm_init() function is used to initialize support for the UFM
subsystem for a given device. The dip argument should be the dev_info
structure of the specific device. The version argument represents the
current revision of the UFM interface that the driver supports. Drivers
inside of illumos should always use DDI_UFM_CURRENT_VERSION. Device
drivers which need to bind to a specific revision, should instead pass the
latest version: DDI_UFM_VERSION_ONE. The operations structure, ops, should
be filled according to the rules in ddi_ufm(9E). These will be the entry
points that device drivers call. The value of drv_arg will be passed to
all of the driver's entry points. When the function returns, ufmpp will be
filled in with a handle that the driver should reference when needing to
perform subsequent UFM operations. No UFM entry points will be called
until after the driver calls the ddi_ufm_update() function.

When the device driver is detaching or needs to unregister from the UFM
subsystem, then the device driver should call the ddi_ufm_fini() function
with the handle that they obtained during the call to initialize. Note,
this function will block and ensure that any outstanding UFM operations are
terminated. The driver must not hold any locks that are required in its
callbacks across the call to ddi_ufm_fini().

The ddi_ufm_update() function should be used in two different
circumstances. It should be used at the end of a driver's attach(9E)
endpoint to indicate that it is ready to receive UFM requests. It should
also be called whenever the driver believes that the UFM might have changed
or the device's capabilities. This may happen after a device reset or
firmware change. Unlike the other functions, this can be called from any
context with any locks held, excepting high-level interrupt context which
normal device drivers will not have interrupts for.

RETURN VALUES

Upon successful completion, the ddi_ufm_init() function returns zero,
indicating that it has successfully registered with the UFM subsystem.
ufmpp will be filled in with a pointer to the UFM handle.

The ddi_ufm_init() and ddi_ufm_fini() functions are generally called from a
device's attach(9E) and _fini(9E) routines, though they may be called from
user or kernel context.

The ddi_ufm_update() function may be called from any context except a high-
level interrupt handler above lock level.

SEE ALSO

_fini(9E), attach(9E), ddi_ufm(9E)

illumos August 22, 2023 illumos