January 17, 2006 FIRMLOAD 9

### NAME

firmload - Firmware loader API for device drivers

### SYNOPSIS

```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 the sysctl variable ```hw.firmware.path`.

The following functions are provided by the firmload API:

intfirmware_open(```, const char *drvname``, const char *imgname``, firmware_handle_t *fhp`)

  Open then 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.

intfirmware_close(```, firmware_handle_t 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.

off_tfirmware_get_size(```, firmware_handle_t fh`)

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

intfirmware_read(```, firmware_handle_t fh``, off_t offset``, void *buf``, size_t 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.

void *firmware_malloc(```size_t size`)

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

voidfirmware_free(```, void *buf``, size_t size`)

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

### SEE ALSO

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

### HISTORY

The firmload framework first appeared in NetBSD4.0.

### AUTHORS

Jason Thorpe <thorpej@NetBSD.org>