diff --git a/share/man/man9/firmware.9 b/share/man/man9/firmware.9 --- a/share/man/man9/firmware.9 +++ b/share/man/man9/firmware.9 @@ -21,7 +21,7 @@ .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd January 19, 2024 +.Dd January 25, 2024 .Dt FIRMWARE 9 .Os .Sh NAME @@ -89,9 +89,12 @@ 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 -.Nm /boot/loader , +.Pa /boot/loader , manually at runtime, or on demand by the firmware subsystem. .Pp +In addition to residing in executable kernel modules, native +images may be loaded. +.Pp .Nm Clients of the firmware subsystem can request access to a given image by calling the function @@ -186,7 +189,7 @@ .Xr taskqueue 9 thread so the call may be done while holding a lock. In certain cases, such as on driver detach, this cannot be allowed. -.Sh FIRMWARE LOADING MECHANISMS +.Sh FIRMWARE LOADING VIA MODULES As mentioned before, any component of the system can register firmware images at any time by simply calling .Fn firmware_register . @@ -194,7 +197,7 @@ This is typically done when a module containing a firmware image is given control, whether compiled in, or preloaded by -.Nm /boot/loader , +.Pa /boot/loader , or manually loaded with .Xr kldload 8 . However, a system can implement additional mechanisms to bring @@ -220,7 +223,7 @@ by the sysctl variable .Nm kern.module_path which on most systems defaults to -.Nm /boot/kernel;/boot/modules . +.Pa /boot/kernel;/boot/modules . .Pp Note that in case a module contains multiple images, the caller should first request a @@ -281,16 +284,98 @@ .Xr awk 1 , .Xr make 1 , the compiler and the linker. +.Sh LOADING NATIVE FIRMWARE FILES +.Ss Native Firmware Format +Native firmware files can also be loaded, either from +.Pa /boot/loader , +or when +.Nm firmware_get +cannot find the registered firmware from a kernel module. +Native firmware files are raw binary files that the creator of the firmware +made. +They offer an easier way to load firmware, but one that lacks the full +flexibility and generality of kernel modules with the following restrictions: +.Bl -bullet -compact +.It +Native firmware files only hold one set of firmware. +.It +They do not offer kernel module dependencies to ensure they are loaded +automatically by the boot loader. +.It +They cannot be compiled into the kernel. +.It +The +.Nm imagename +is identical to the filename used to load the module. +.It +The version number is assumed to be zero. +.El +.Ss Loading from Pa /boot/loader +Native firmware files may be loaded either from the command line with +.Dq load -t firmware /boot/firmware/filename +or using the +.Xr loader.conf 5 +mechanism to load modules with a type of +.Dq firmware +For example +.Bd -literal +wififw_load="YES" +wififw_name="/boot/firmware/wifi2034_fw.bin" +wififw_type="firmware" +.Ed +.Ss On demand loading from Nm firmware_get +If no kernel module with a module named +.Nm imagename , +then the +.Nm imagename +will be appended to the module path (by default +.Pa /boot/firmware/ ) +and if that file exists, it will be loaded and registered using +.Nm firmware_register +using the foll path to the filename as +.Nm imagename . +.Ss Searching for imagename +.Nm firmware_get +uses the following algorithm to find firmware images. +.Bl -bullet -compact +.It +If there is an already registered firmware the an identical name, that +image is returned. +.It +If the passed +.Nm imagename +matches subpath of a registered image with a full path, that image is returned. +.It +A module whose name matches +.Nm imagename +is loaded, its +.Nm MOD_LOAD +handler is run to register any firmware and the search is conducted again. +If a match is found, that image is returned. +.It +A check for native version of the firmware is made against in the module path +(by default +.Pa /boot/firmware/ Em imagename ) +to see if that file exists and can be read. +If so, the firmware is registered with the full path as the +.Nm imagename +and that firmware is returned. +Currently, there is an 8MB limit on the size of the firmware image. +.El .Sh SEE ALSO .Xr kld 4 , .Xr module 9 .Pp +.Pa /boot/firmware +.Pp .Pa /usr/share/examples/kld/firmware .Sh HISTORY The .Nm firmware system was introduced in .Fx 6.1 . +Native firmware loading was introduced in +.Fx 15.0 . .Sh AUTHORS This manual page was written by .An Max Laier Aq Mt mlaier@FreeBSD.org .