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

SEE ALSO

system(5)

illumos August 22, 2023 illumos