--- name: "firmware" section: "9freebsd" platform: "linux" package: "freebsd-manpages" version: "12.2-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/firmware/9freebsd" --- # firmware(9freebsd) firmware image loading and management ## NAME **firmware\_register**, **firmware\_unregister**, **firmware\_get**, **firmware\_put** – firmware image loading and management ## SYNOPSIS **#include \** **#include \** **#include \** **#include \** ``` struct firmware { const char *name; /* system-wide name */ const void *data; /* location of image */ size_t datasize; /* size of image in bytes */ unsigned int version; /* version of the image */ }; ``` *const struct firmware \**\ **firmware\_register**(*const char \*imagename*, *const void \*data*, *size\_t datasize*, *unsigned int version*, *const struct firmware \*parent*); *int*\ **firmware\_unregister**(*const char \*imagename*); *const struct firmware \**\ **firmware\_get**(*const char \*imagename*); *void*\ **firmware\_put**(*const struct firmware \*fp*, *int flags*); ## DESCRIPTION The **firmware** abstraction provides a convenient interface for loading **firmware** **images** into the kernel, and for accessing such images from kernel components. A **firmware** **image** (or **image** for brevity) is an opaque block of data residing in kernel memory. It is associated to a unique **imagename** which constitutes a search key, and to an integer **version** number, which is also an opaque piece of information for the firmware subsystem. An image is registered with the **firmware** subsystem by calling the function **firmware\_register**(), and unregistered by calling **firmware\_unregister**(). These functions are usually (but not exclusively) called by specially crafted kernel modules that contain the firmware image. The modules can be statically compiled in the kernel, or loaded by **/boot/loader**, manually at runtime, or on demand by the firmware subsystem. **Clients** of the firmware subsystem can request access to a given image by calling the function **firmware\_get**() with the **imagename** they want as an argument. If a matching image is not already registered, the firmware subsystem will try to load it using the mechanisms specified below (typically, a kernel module with **firmware\_register** the same name as the image). ## API DESCRIPTION The kernel **firmware\_register** firmware API is made of the following functions: **firmware\_register**() registers with the kernel an image of size **datasize** located at address **data**, under the name **imagename**. The function returns NULL on error (e.g. because an image with the same name already exists, or the image table is full), or a *const* *struct* *firmware* *\** pointer to the image requested. **firmware\_unregister**() tries to unregister the firmware image **imagename** from the system. The function is successful and returns 0 if there are no pending references to the image, otherwise it does not unregister the image and returns EBUSY. **firmware\_get**() returns the requested firmware image. If the image is not yet registered with the system, the function tries to load it. This involves the linker subsystem and disk access, so **firmware\_get**() must not be called with any locks (except for *Giant*). Note also that if the firmware image is loaded from a filesystem it must already be mounted. In particular this means that it may be necessary to defer requests from a driver attach method unless it is known the root filesystem is already mounted. On success, **firmware\_get**() returns a pointer to the image description and increases the reference count for this image. On failure, the function returns NULL. **firmware\_put**() drops a reference to a firmware image. The *flags* argument may be set to FIRMWARE\_UNLOAD to indicate that firmware\_put is free to reclaim resources associated with the firmware image if this is the last reference. By default a firmware image will be deferred to a [taskqueue(9)](/taskqueue/9.md) thread so the call may be done while holding a lock. In certain cases, such as on driver detach, this cannot be allowed. ## FIRMWARE LOADING MECHANISMS As mentioned before, any component of the system can register firmware images at any time by simply calling **firmware\_register**(). This is typically done when a module containing a firmware image is given control, whether compiled in, or preloaded by **/boot/loader**, or manually loaded with [kldload(8)](/kldload/8.md). However, a system can implement additional mechanisms to bring these images in memory before calling **firmware\_register**(). When **firmware\_get**() does not find the requested image, it tries to load it using one of the available loading mechanisms. At the moment, there is only one, namely **Loadable** **kernel** **modules**: A firmware image named **foo** is looked up by trying to load the module named **foo.ko**, using the facilities described in [kld(4)](/kld/4.md). In particular, images are looked up in the directories specified by the sysctl variable **kern.module\_path** which on most systems defaults to **/boot/kernel;/boot/modules**. Note that in case a module contains multiple images, the caller should first request a **firmware\_get**() for the first image contained in the module, followed by requests for the other images. ## BUILDING FIRMWARE LOADABLE MODULES A firmware module is built by embedding the **firmware** **image** into a suitable loadable kernel module that calls **firmware\_register**() on loading, and **firmware\_unregister**() on unloading. Various system scripts and makefiles let you build a module by simply writing a Makefile with the following entries: ``` KMOD= imagename FIRMWS= image_file:imagename[:version] .include ``` where KMOD is the basename of the module; FIRMWS is a list of colon-separated tuples indicating the image\_file's to be embedded in the module, the imagename and version of each firmware image. If you need to embed firmware images into a system, you should write appropriate entries in the \ file, e.g. this example is from **sys/arm/xscale/ixp425/files.ixp425**: ``` ixp425_npe_fw.c optional npe_fw \ compile-with "${AWK} -f $S/tools/fw_stub.awk \ IxNpeMicrocode.dat:npe_fw -mnpe -c${.TARGET}" \ no-implicit-rule before-depend local \ clean "ixp425_npe_fw.c" # # NB: ld encodes the path in the binary symbols generated for the # firmware image so link the file to the object directory to # get known values for reference in the _fw.c file. # IxNpeMicrocode.fwo optional npe_fw \ dependency "IxNpeMicrocode.dat" \ compile-with "${LD} -b binary -d -warn-common \ -r -d -o ${.TARGET} IxNpeMicrocode.dat" \ no-implicit-rule \ clean "IxNpeMicrocode.fwo" IxNpeMicrocode.dat optional npe_fw \ dependency ".PHONY" \ compile-with "uudecode < $S/contrib/dev/npe/IxNpeMicrocode.dat.uu" \ no-obj no-implicit-rule \ clean "IxNpeMicrocode.dat" ``` Note that generating the firmware modules in this way requires the availability of the following tools: [awk(1)](/awk/1.md), [make(1)](/make/1.md), the compiler and the linker. ## SEE ALSO [kld(4)](/kld/4.md), [module(9)](/module/9.md) */usr/share/examples/kld/firmware* ## HISTORY The **firmware** system was introduced in FreeBSD 6.1. ## AUTHORS This manual page was written by Max Laier ⟨*mlaier@FreeBSD.org*⟩.