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 returning 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