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

NAME

firmload - Firmware loader API for device drivers

SYNOPSIS

#include <sys/firmload.h>

int
firmware_open(const char *drvname, const char *imgname,
firmware_handle_t *fhp);

int
firmware_close(firmware_handle_t fh);

off_t
firmware_get_size(firmware_handle_t fh);

int
firmware_read(firmware_handle_t fh, off_t offset, void *buf, size_t size);

PARAMETERS

drvname The name of the driver using firmload. This is used as the
subdirectory holding the firmware images.

imgname The file name of a firmware image.

fhp The pointer used for returing a firmware handle.

fh The firmware handle.

offset The offset in the firmware image to start reading from.

buf Pointer to a buffer to hold the firmware data.

size Size of the buffer to hold the firmware data.

DESCRIPTION

firmload provides a simple and convenient API for device drivers to load
firmware images from files residing in the file system that are necessary
for the devices that they control. It is primarily intended for devices
without non-volatile firmware memory, which usually require the driver to
load a firmware image at attach time. Firmware images reside in sub-
directories, one for each driver, in the namespace "firmware" in the system
default module search path as described in system(5).

The following functions are provided by the firmload API:

firmware_open()
Open the firmware image imgname for the driver drvname. The path
to the firmware image file is constructed by appending the string
"firmware/drvname/imgname" to each system module path prefix until
opening the firmware image file succeeds.

firmware_close()
Close the firmware image file associated with the firmware handle
fh.

firmware_get_size()
Returns the size of the image file associated with the firmware
handle fh.

firmware_read()
Reads from the image file associated with the firmware handle fh
beginning at offset offset for length size. The firmware image
data is placed into the buffer specified by buf. firmware_read()
will either read as much data as requested or fail, there are no
short reads.

CONTEXT

These functions can be called from user and kernel context.

RETURN VALUES

Upon successful completion, the firmware_open() function returns zero and
stores a firmware handle in fhp. Otherwise a non-zero error code is
returned.

The function firmware_read() will return zero on success and buf will be
filled with size bytes of data. On failure -1 is returned.

The function firmware_get_size() returns the size of a firmware image.

firmware_close() will always return zero.

INTERFACE STABILITY

Committed

SEE ALSO

system(5)

illumos January 22, 2016 illumos