Page MenuHomeFreeBSD
Files F132575355

D43611.diff
No OneTemporary
Actions

D43611.diff
View Options

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
+Firmware binary files may also be loaded directly rather than embedded into
+kernel modules.
+.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,102 @@
.Xr awk 1 ,
.Xr make 1 ,
the compiler and the linker.
+.Sh LOADING BINARY FIRMWARE FILES
+.Ss Binary Firmware Format
+Binary 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.
+Binary 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
+Binary 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 full path name used to load the module.
+.It
+The version number is assumed to be zero.
+.El
+.Ss Loading from Pa /boot/loader
+Binary 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 an embedded firmware image named
+.Nm imagename
+is loaded, then
+.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 full 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 an existing firmware image is registered for
+.Fa imagename,
+.that image is returned.
+.It
+If
+.Fa imagename
+matches the trailing subpath of a registered image with a full path, that image is returned.
+.It
+he kernel linker searches for a kernel module named
+.Fa imagename .
+If a kernel module is found, it is loaded, and
+the list of registered firmware images is searched again.
+If a match is found, the matching image is returned.
+.It
+The kernel searches for a file named
+.Fa imagename
+in the firmware image path
+(by default
+.Pa /boot/firmware/ ) .
+If that file exists and can be read,
+it contents are registered as a firmware image 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.
+This can be changed by by the sysctl variable
+.Nm debug.max_firmware_size .
+.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 .
+Binary firmware loading was introduced in
+.Fx 15.0 .
.Sh AUTHORS
This manual page was written by
.An Max Laier Aq Mt mlaier@FreeBSD.org .

File Metadata

Mime Type
text/plain
Expires
Sun, Oct 19, 2:44 AM (9 h, 51 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
23906535
Default Alt Text
D43611.diff (4 KB)

Event Timeline