FIRMLOAD(9) | Kernel Developer's Manual | FIRMLOAD(9)

# NAME

`firmload` —
Firmware loader API for device drivers

# SYNOPSIS

`#include <dev/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);

void *
`firmware_malloc`(size_t size);

void
`firmware_free`(void *buf, size_t size);

# 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. Firmware images reside in sub-directories, one for each driver, of a series of colon-separated path prefixes specified by the sysctl variable `hw.firmware.path`.

# FUNCTIONS

The following functions are provided by the `firmload` API:

`firmware_open`(drvname, imgname, fhp)

  Open the firmware image imgname for the driver drvname. The path to the firmware image file is constructed by appending the string “/drvname/imgname” to each configured path prefix until opening the firmware image file succeeds. Upon success, `firmware_open`() returns 0 and stores a firmware image handle in the location pointed to by fhp. Otherwise, an error code is returned to indicate the reason for failure.

`firmware_close`(fh)

  Close the firmware image file associated with the firmware handle fh. Returns 0 upon success or an error code to indicate the reason for failure.

`firmware_get_size`(fh)

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

`firmware_read`(fh, offset, buf, size)

  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. Returns 0 upon success or an error code to indicate the reason for failure.

`firmware_malloc`(size)

  Allocates a region of wired kernel memory of size size. Note: `firmware_malloc`() may block.

`firmware_free`(buf, size)

  Frees a region of memory previously allocated by `firmware_malloc`().

# FILES

Default search path for firmware

/libdata/firmware
/usr/libdata/firmware
/usr/pkg/libdata/firmware
/usr/pkg/libdata

# SEE ALSO

autoconf(9), malloc(9), vnsubr(9)

# HISTORY

The `firmload` framework first appeared in NetBSD 4.0.

# AUTHORS

Jason Thorpe <thorpej@NetBSD.org>

March 16, 2018 | NetBSD 9.2