diff options
Diffstat (limited to 'static/freebsd/man9/firmware.9 3.html')
| -rw-r--r-- | static/freebsd/man9/firmware.9 3.html | 319 |
1 files changed, 0 insertions, 319 deletions
diff --git a/static/freebsd/man9/firmware.9 3.html b/static/freebsd/man9/firmware.9 3.html deleted file mode 100644 index 06e4ca52..00000000 --- a/static/freebsd/man9/firmware.9 3.html +++ /dev/null @@ -1,319 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">FIRMWARE(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">FIRMWARE(9)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">firmware_register</code>, - <code class="Nm">firmware_unregister</code>, - <code class="Nm">firmware_get</code>, - <code class="Nm">firmware_get_flags</code>, - <code class="Nm">firmware_put</code> — <span class="Nd">firmware - image loading and management</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="In">#include - <<a class="In">sys/param.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/systm.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/linker.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/firmware.h</a>></code></p> -<div class="Bd Pp Li"> -<pre>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 */ -};</pre> -</div> -<br/> -<var class="Ft">const struct firmware *</var> -<br/> -<code class="Fn">firmware_register</code>(<var class="Fa">const char - *imagename</var>, <var class="Fa">const void *data</var>, - <var class="Fa">size_t datasize</var>, <var class="Fa">unsigned int - version</var>, <var class="Fa">const struct firmware *parent</var>); -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">firmware_unregister</code>(<var class="Fa" style="white-space: nowrap;">const - char *imagename</var>);</p> -<p class="Pp"><var class="Ft">const struct firmware *</var> - <br/> - <code class="Fn">firmware_get</code>(<var class="Fa" style="white-space: nowrap;">const - char *imagename</var>);</p> -<p class="Pp"><var class="Ft">const struct firmware *</var> - <br/> - <code class="Fn">firmware_get_flags</code>(<var class="Fa" style="white-space: nowrap;">const - char *imagename</var>, <var class="Fa" style="white-space: nowrap;">uint32_t - flags</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">firmware_put</code>(<var class="Fa" style="white-space: nowrap;">const - struct firmware *fp</var>, <var class="Fa" style="white-space: nowrap;">int - flags</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The <code class="Nm">firmware</code> abstraction provides a - convenient interface for loading <code class="Nm">firmware images</code> - into the kernel, and for accessing such images from kernel components.</p> -<p class="Pp">A <code class="Nm">firmware image</code> (or - <code class="Nm">image</code> for brevity) is an opaque block of data - residing in kernel memory. It is associated to a unique - <code class="Nm">imagename</code> which constitutes a search key, and to an - integer <code class="Nm">version</code> number, which is also an opaque - piece of information for the firmware subsystem.</p> -<p class="Pp" id="firmware_register">An image is registered with the - <code class="Nm">firmware</code> subsystem by calling the function - <a class="permalink" href="#firmware_register"><code class="Fn">firmware_register</code></a>(), - and unregistered by calling <code class="Fn">firmware_unregister</code>(). - 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 - <span class="Pa">/boot/loader</span>, manually at runtime, or on demand by - the firmware subsystem.</p> -<p class="Pp">Firmware binary files may also be loaded directly rather than - embedded into kernel modules.</p> -<p class="Pp" id="firmware_get"><code class="Nm">Clients</code> of the firmware - subsystem can request access to a given image by calling the function - <a class="permalink" href="#firmware_get"><code class="Fn">firmware_get</code></a>() - with the <code class="Nm">imagename</code> they want as an argument, or by - calling - <a class="permalink" href="#firmware_get_flags"><code class="Fn" id="firmware_get_flags">firmware_get_flags</code></a>() - with the <code class="Nm">imagename</code> and <code class="Nm">flags</code> - they want as an arguments. 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 - <code class="Nm">firmware_register</code> the same name as the image).</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="API_DESCRIPTION"><a class="permalink" href="#API_DESCRIPTION">API - DESCRIPTION</a></h1> -<p class="Pp">The kernel <code class="Nm">firmware_register</code> firmware API - is made of the following functions:</p> -<p class="Pp" id="firmware_register~2"><a class="permalink" href="#firmware_register~2"><code class="Fn">firmware_register</code></a>() - registers with the kernel an image of size <code class="Nm">datasize</code> - located at address <code class="Nm">data</code>, under the name - <code class="Nm">imagename</code>.</p> -<p class="Pp">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 - <var class="Ft">const struct firmware *</var> pointer to the image - requested.</p> -<p class="Pp" id="firmware_unregister"><a class="permalink" href="#firmware_unregister"><code class="Fn">firmware_unregister</code></a>() - tries to unregister the firmware image <code class="Nm">imagename</code> - 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.</p> -<p class="Pp" id="firmware_get~2"><a class="permalink" href="#firmware_get~2"><code class="Fn">firmware_get</code></a>() - and - <a class="permalink" href="#firmware_get_flags~2"><code class="Fn" id="firmware_get_flags~2">firmware_get_flags</code></a>() - return the requested firmware image. The <var class="Fa">flags</var> - argument may be set to <code class="Dv">FIRMWARE_GET_NOWARN</code> to - indicate that errors on firmware load or registration should only be logged - in case of <code class="Nm">booverbose</code>. If the image is not yet - registered with the system, the functions try to load it. This involves the - linker subsystem and disk access, so <code class="Fn">firmware_get</code>() - or <code class="Fn">firmware_get_flags</code>() must not be called with any - locks (except for <var class="Va">Giant</var>). 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.</p> -<p class="Pp" id="firmware_get~3">On success, - <a class="permalink" href="#firmware_get~3"><code class="Fn">firmware_get</code></a>() - and - <a class="permalink" href="#firmware_get_flags~3"><code class="Fn" id="firmware_get_flags~3">firmware_get_flags</code></a>() - return a pointer to the image description and increase the reference count - for this image. On failure, the functions return NULL.</p> -<p class="Pp" id="firmware_put"><a class="permalink" href="#firmware_put"><code class="Fn">firmware_put</code></a>() - drops a reference to a firmware image. The <var class="Fa">flags</var> - argument may be set to <code class="Dv">FIRMWARE_UNLOAD</code> 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 <a class="Xr">taskqueue(9)</a> thread so the call may be done - while holding a lock. In certain cases, such as on driver detach, this - cannot be allowed.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="FIRMWARE_LOADING_VIA_MODULES"><a class="permalink" href="#FIRMWARE_LOADING_VIA_MODULES">FIRMWARE - LOADING VIA MODULES</a></h1> -<p class="Pp">As mentioned before, any component of the system can register - firmware images at any time by simply calling - <code class="Fn">firmware_register</code>().</p> -<p class="Pp" id="firmware_register~3">This is typically done when a module - containing a firmware image is given control, whether compiled in, or - preloaded by <span class="Pa">/boot/loader</span>, or manually loaded with - <a class="Xr">kldload(8)</a>. However, a system can implement additional - mechanisms to bring these images into memory before calling - <a class="permalink" href="#firmware_register~3"><code class="Fn">firmware_register</code></a>().</p> -<p class="Pp" id="firmware_get~4">When - <a class="permalink" href="#firmware_get~4"><code class="Fn">firmware_get</code></a>() - or - <a class="permalink" href="#firmware_get_flags~4"><code class="Fn" id="firmware_get_flags~4">firmware_get_flags</code></a>() - 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 - <code class="Nm">Loadable kernel modules</code>.</p> -<p class="Pp">A firmware image named <code class="Nm">foo</code> is looked up by - trying to load the module named <code class="Nm">foo.ko</code>, using the - facilities described in <a class="Xr">kld(4)</a>. In particular, images are - looked up in the directories specified by the sysctl variable - <code class="Nm">kern.module_path</code> which on most systems defaults to - <span class="Pa">/boot/kernel;/boot/modules</span>.</p> -<p class="Pp" id="firmware_get~5">Note that in case a module contains multiple - images, the caller should first request a - <a class="permalink" href="#firmware_get~5"><code class="Fn">firmware_get</code></a>() - or - <a class="permalink" href="#firmware_get_flags~5"><code class="Fn" id="firmware_get_flags~5">firmware_get_flags</code></a>() - for the first image contained in the module, followed by requests for the - other images.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="BUILDING_FIRMWARE_LOADABLE_MODULES"><a class="permalink" href="#BUILDING_FIRMWARE_LOADABLE_MODULES">BUILDING - FIRMWARE LOADABLE MODULES</a></h1> -<p class="Pp">A firmware module is built by embedding the - <code class="Nm">firmware image</code> into a suitable loadable kernel - module that calls <code class="Fn">firmware_register</code>() on loading, - and <code class="Fn">firmware_unregister</code>() on unloading.</p> -<p class="Pp">Various system scripts and makefiles let you build a module by - simply writing a Makefile with the following entries:</p> -<div class="Bd Pp Li"> -<pre> - KMOD= imagename - FIRMWS= image_file:imagename[:version] - .include <bsd.kmod.mk> - -</pre> -</div> -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. -<p class="Pp">If you need to embed firmware images into a system, you should - write appropriate entries in the <files.arch> or <files> file, - e.g. this example is from <code class="Nm">sys/conf/files</code></p> -<div class="Bd Pp Li"> -<pre>iwn1000fw.c optional iwn1000fw | iwnfw \ - compile-with "${AWK} -f $S/tools/fw_stub.awk iwn1000.fw:iwn1000fw -miwn1000fw -c${.TARGET}" \ - no-ctfconvert no-implicit-rule before-depend local \ - clean "iwn1000fw.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. -# -iwn1000fw.fwo optional iwn1000fw | iwnfw \ - dependency "iwn1000.fw" \ - compile-with "${NORMAL_FWO}" \ - no-implicit-rule \ - clean "iwn1000fw.fwo"</pre> -</div> -<p class="Pp">Firmware was previously committed to the source tree as uuencoded - files, but this is no longer required; the binary firmware file should be - committed to the tree as provided by the vendor.</p> -<p class="Pp">Note that generating the firmware modules in this way requires the - availability of the following tools: <a class="Xr">awk(1)</a>, - <a class="Xr">make(1)</a>, the compiler and the linker.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="LOADING_BINARY_FIRMWARE_FILES"><a class="permalink" href="#LOADING_BINARY_FIRMWARE_FILES">LOADING - BINARY FIRMWARE FILES</a></h1> -<section class="Ss"> -<h2 class="Ss" id="Binary_Firmware_Format"><a class="permalink" href="#Binary_Firmware_Format">Binary - Firmware Format</a></h2> -<p class="Pp">Binary firmware files can also be loaded, either from - <span class="Pa">/boot/loader</span>, or when - <code class="Nm">firmware_get</code> 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:</p> -<ul class="Bl-bullet Bl-compact"> - <li>Binary firmware files only hold one set of firmware.</li> - <li>They do not offer kernel module dependencies to ensure they are loaded - automatically by the boot loader.</li> - <li>They cannot be compiled into the kernel.</li> - <li>The <code class="Nm">imagename</code> is identical to the full path name - used to load the module.</li> - <li>The version number is assumed to be zero.</li> -</ul> -</section> -<section class="Ss"> -<h2 class="Ss" id="Loading_from_/boot/loader"><a class="permalink" href="#Loading_from_/boot/loader">Loading - from <span class="Pa">/boot/loader</span></a></h2> -<p class="Pp">Binary firmware files may be loaded either from the command line - with “load -t firmware /boot/firmware/filename” or using the - <a class="Xr">loader.conf(5)</a> mechanism to load modules with a type of - “firmware” For example</p> -<div class="Bd Pp Li"> -<pre>wififw_load="YES" -wififw_name="/boot/firmware/wifi2034_fw.bin" -wififw_type="firmware"</pre> -</div> -</section> -<section class="Ss"> -<h2 class="Ss" id="On_demand_loading_from_firmware_get"><a class="permalink" href="#On_demand_loading_from_firmware_get">On - demand loading from <code class="Nm">firmware_get</code></a></h2> -<p class="Pp">If no kernel module with an embedded firmware image named - <code class="Nm">imagename</code> is loaded, then - <code class="Nm">imagename</code> will be appended to the module path (by - default <span class="Pa">/boot/firmware/</span>) and if that file exists, it - will be loaded and registered using - <code class="Nm">firmware_register</code> using the full path to the - filename as <code class="Nm">imagename</code>.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Searching_for_imagename"><a class="permalink" href="#Searching_for_imagename">Searching - for imagename</a></h2> -<p class="Pp"><code class="Nm">firmware_get</code> uses the following algorithm - to find firmware images:</p> -<ul class="Bl-bullet Bl-compact"> - <li>If an existing firmware image is registered for - <var class="Fa">imagename,</var> that image is returned.</li> - <li>If <var class="Fa">imagename</var> matches the trailing subpath of a - registered image with a full path, that image is returned.</li> - <li>The kernel linker searches for a kernel module named - <var class="Fa">imagename</var>. 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.</li> - <li>The kernel searches for a file named <var class="Fa">imagename</var> in - the firmware image path (by default - <span class="Pa">/boot/firmware/</span>). If that file exists and can be - read, it contents are registered as a firmware image with the full path as - the <code class="Nm">imagename</code> 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 - <code class="Nm">debug.max_firmware_size</code>.</li> -</ul> -</section> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">kld(4)</a>, <a class="Xr">module(9)</a></p> -<p class="Pp"><span class="Pa">/boot/firmware</span></p> -<p class="Pp"><span class="Pa">/usr/share/examples/kld/firmware</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">The <code class="Nm">firmware</code> system was introduced in - <span class="Ux">FreeBSD 6.1</span>. Binary firmware loading was introduced - in <span class="Ux">FreeBSD 15.0</span>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp">This manual page was written by <span class="An">Max Laier</span> - <<a class="Mt" href="mailto:mlaier@FreeBSD.org">mlaier@FreeBSD.org</a>>.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">January 25, 2024</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |