1.\" Copyright (c) 2006 Max Laier <mlaier@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 14.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 15.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 16.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 17.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 18.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 19.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 20.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 21.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 22.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 23.\" 24.Dd January 19, 2024 25.Dt FIRMWARE 9 26.Os 27.Sh NAME 28.Nm firmware_register , 29.Nm firmware_unregister , 30.Nm firmware_get , 31.Nm firmware_get_flags , 32.Nm firmware_put 33.Nd firmware image loading and management 34.Sh SYNOPSIS 35.In sys/param.h 36.In sys/systm.h 37.In sys/linker.h 38.In sys/firmware.h 39.Bd -literal 40struct firmware { 41 const char *name; /* system-wide name */ 42 const void *data; /* location of image */ 43 size_t datasize; /* size of image in bytes */ 44 unsigned int version; /* version of the image */ 45}; 46.Ed 47.Ft "const struct firmware *" 48.Fo firmware_register 49.Fa "const char *imagename" 50.Fa "const void *data" 51.Fa "size_t datasize" 52.Fa "unsigned int version" 53.Fa "const struct firmware *parent" 54.Fc 55.Ft int 56.Fn firmware_unregister "const char *imagename" 57.Ft "const struct firmware *" 58.Fn firmware_get "const char *imagename" 59.Ft "const struct firmware *" 60.Fn firmware_get_flags "const char *imagename" "uint32_t flags" 61.Ft void 62.Fn firmware_put "const struct firmware *fp" "int flags" 63.Sh DESCRIPTION 64The 65.Nm firmware 66abstraction provides a convenient interface for loading 67.Nm firmware images 68into the kernel, and for accessing such images from kernel components. 69.Pp 70A 71.Nm firmware image 72(or 73.Nm image 74for brevity) 75is an opaque block of data residing in kernel memory. 76It is associated to a unique 77.Nm imagename 78which constitutes a search key, and to an integer 79.Nm version 80number, which is also an opaque piece of information for the 81firmware subsystem. 82.Pp 83An image is registered with the 84.Nm firmware 85subsystem by calling the function 86.Fn firmware_register , 87and unregistered by calling 88.Fn firmware_unregister . 89These functions are usually (but not exclusively) called by 90specially crafted kernel modules that contain the firmware image. 91The modules can be statically compiled in the kernel, or loaded by 92.Nm /boot/loader , 93manually at runtime, or on demand by the firmware subsystem. 94.Pp 95.Nm Clients 96of the firmware subsystem can request access to a given image 97by calling the function 98.Fn firmware_get 99with the 100.Nm imagename 101they want as an argument, or by calling 102.Fn firmware_get_flags 103with the 104.Nm imagename 105and 106.Nm flags 107they want as an arguments. 108If a matching image is not already registered, 109the firmware subsystem will try to load it using the 110mechanisms specified below (typically, a kernel module 111with 112.Nm 113the same name 114as the image). 115.Sh API DESCRIPTION 116The kernel 117.Nm 118firmware API 119is made of the following functions: 120.Pp 121.Fn firmware_register 122registers with the kernel an image of size 123.Nm datasize 124located at address 125.Nm data , 126under the name 127.Nm imagename . 128.Pp 129The function returns NULL on error (e.g. because an 130image with the same name already exists, or the image 131table is full), or a 132.Ft const struct firmware * 133pointer to the image requested. 134.Pp 135.Fn firmware_unregister 136tries to unregister the firmware image 137.Nm imagename 138from the system. 139The function is successful and returns 0 140if there are no pending references to the image, otherwise 141it does not unregister the image and returns EBUSY. 142.Pp 143.Fn firmware_get 144and 145.Fn firmware_get_flags 146return the requested firmware image. 147The 148.Fa flags 149argument may be set to 150.Dv FIRMWARE_GET_NOWARN 151to indicate that errors on firmware load or registration should 152only be logged in case of 153.Nm booverbose . 154If the image is not yet registered with the system, 155the functions try to load it. 156This involves the linker subsystem and disk access, so 157.Fn firmware_get 158or 159.Fn firmware_get_flags 160must not be called with any locks (except for 161.Va Giant ) . 162Note also that if the firmware image is loaded from a filesystem 163it must already be mounted. 164In particular this means that it may be necessary to defer requests 165from a driver attach method unless it is known the root filesystem is 166already mounted. 167.Pp 168On success, 169.Fn firmware_get 170and 171.Fn firmware_get_flags 172return a pointer to the image description and increase the reference count 173for this image. 174On failure, the functions return NULL. 175.Pp 176.Fn firmware_put 177drops a reference to a firmware image. 178The 179.Fa flags 180argument may be set to 181.Dv FIRMWARE_UNLOAD 182to indicate that 183firmware_put is free to reclaim resources associated with 184the firmware image if this is the last reference. 185By default a firmware image will be deferred to a 186.Xr taskqueue 9 187thread so the call may be done while holding a lock. 188In certain cases, such as on driver detach, this cannot be allowed. 189.Sh FIRMWARE LOADING MECHANISMS 190As mentioned before, any component of the system can register 191firmware images at any time by simply calling 192.Fn firmware_register . 193.Pp 194This is typically done when a module containing 195a firmware image is given control, 196whether compiled in, or preloaded by 197.Nm /boot/loader , 198or manually loaded with 199.Xr kldload 8 . 200However, a system can implement additional mechanisms to bring 201these images in memory before calling 202.Fn firmware_register . 203.Pp 204When 205.Fn firmware_get 206or 207.Fn firmware_get_flags 208does not find the requested image, it tries to load it using 209one of the available loading mechanisms. 210At the moment, there is only one, namely 211.Nm Loadable kernel modules . 212.Pp 213A firmware image named 214.Nm foo 215is looked up by trying to load the module named 216.Nm foo.ko , 217using the facilities described in 218.Xr kld 4 . 219In particular, images are looked up in the directories specified 220by the sysctl variable 221.Nm kern.module_path 222which on most systems defaults to 223.Nm /boot/kernel;/boot/modules . 224.Pp 225Note that in case a module contains multiple images, 226the caller should first request a 227.Fn firmware_get 228or 229.Fn firmware_get_flags 230for the first image contained in the module, followed by requests 231for the other images. 232.Sh BUILDING FIRMWARE LOADABLE MODULES 233A firmware module is built by embedding the 234.Nm firmware image 235into a suitable loadable kernel module that calls 236.Fn firmware_register 237on loading, and 238.Fn firmware_unregister 239on unloading. 240.Pp 241Various system scripts and makefiles let you build a module 242by simply writing a Makefile with the following entries: 243.Bd -literal 244 245 KMOD= imagename 246 FIRMWS= image_file:imagename[:version] 247 .include <bsd.kmod.mk> 248 249.Ed 250where KMOD is the basename of the module; FIRMWS is a list of 251colon-separated tuples indicating the image_file's to be embedded 252in the module, the imagename and version of each firmware image. 253.Pp 254If you need to embed firmware images into a system, you should write 255appropriate entries in the <files.arch> or <files> file, e.g. this example is 256from 257.Nm sys/conf/files 258.Bd -literal 259iwn1000fw.c optional iwn1000fw | iwnfw \\ 260 compile-with "${AWK} -f $S/tools/fw_stub.awk iwn1000.fw:iwn1000fw -miwn1000fw -c${.TARGET}" \\ 261 no-ctfconvert no-implicit-rule before-depend local \\ 262 clean "iwn1000fw.c" 263# 264# NB: ld encodes the path in the binary symbols generated for the 265# firmware image so link the file to the object directory to 266# get known values for reference in the _fw.c file. 267# 268iwn1000fw.fwo optional iwn1000fw | iwnfw \\ 269 dependency "iwn1000.fw" \\ 270 compile-with "${NORMAL_FWO}" \\ 271 no-implicit-rule \\ 272 clean "iwn1000fw.fwo" 273.Ed 274.Pp 275Firmware was previously committed to the source tree as uuencoded files, 276but this is no longer required; the binary firmware file should be committed 277to the tree as provided by the vendor. 278.Pp 279Note that generating the firmware modules in this way requires 280the availability of the following tools: 281.Xr awk 1 , 282.Xr make 1 , 283the compiler and the linker. 284.Sh SEE ALSO 285.Xr kld 4 , 286.Xr module 9 287.Pp 288.Pa /usr/share/examples/kld/firmware 289.Sh HISTORY 290The 291.Nm firmware 292system was introduced in 293.Fx 6.1 . 294.Sh AUTHORS 295This manual page was written by 296.An Max Laier Aq Mt mlaier@FreeBSD.org . 297