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.