man/man9/firmware.9

0 .\" 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 .\" $FreeBSD: releng/10.2/share/man/man9/firmware.9 256114 2013-10-07 16:49:53Z jmg $
25 .\"
26 .Dd August 2, 2008
27 .Dt FIRMWARE 9
28 .Os
29 .Sh NAME
30 .Nm firmware_register ,
31 .Nm firmware_unregister ,
32 .Nm firmware_get ,
33 .Nm firmware_put
34 .Nd firmware image loading and management
35 .Sh SYNOPSIS
36 .In sys/param.h
37 .In sys/systm.h
38 .In sys/linker.h
39 .In sys/firmware.h
40 .Bd -literal
47 .Ed
48 .Ft "const struct firmware *"
49 .Fo firmware_register
50 .Fa "const char *imagename"
51 .Fa "const void *data"
52 .Fa "size_t datasize"
53 .Fa "unsigned int version"
54 .Fa "const struct firmware *parent"
55 .Fc
56 .Ft int
57 .Fn firmware_unregister "const char *imagename"
58 .Ft "const struct firmware *"
59 .Fn firmware_get "const char *imagename"
60 .Ft void
61 .Fn firmware_put "const struct firmware *fp" "int flags"
62 .Sh DESCRIPTION
64 .Nm firmware
66 .Nm firmware images
67 into the kernel, and for accessing such images from kernel components.
68 .Pp
70 .Nm firmware image
72 .Nm image
74 is an opaque block of data residing in kernel memory.
76 .Nm imagename
78 .Nm version
80 firmware subsystem.
81 .Pp
83 .Nm firmware
85 .Fn firmware_register ,
87 .Fn firmware_unregister .
89 specially crafted kernel modules that contain the firmware image.
91 .Nm /boot/loader ,
92 manually at runtime, or on demand by the firmware subsystem.
93 .Pp
94 .Nm Clients
97 .Fn firmware_get
99 .Nm imagename
100 they want as an argument. If a matching image is not already registered,
104 .Nm
106 as the image).
107 .Sh API DESCRIPTION
109 .Nm
112 .Pp
113 .Fn firmware_register
115 .Nm datasize
117 .Nm data ,
119 .Nm imagename .
120 .Pp
121 The function returns NULL on error (e.g. because an
124 .Ft const struct firmware *
125 pointer to the image requested.
126 .Pp
127 .Fn firmware_unregister
129 .Nm imagename
130 from the system. The function is successful and returns 0
132 it does not unregister the image and returns EBUSY.
133 .Pp
134 .Fn firmware_get
135 returns the requested firmware image.
137 the function tries to load it.
139 .Fn firmware_get
141 .Va Giant ) .
143 it must already be mounted.
146 already mounted.
147 .Pp
149 .Fn firmware_get
151 for this image. On failure, the function returns NULL.
152 .Pp
153 .Fn firmware_put
154 drops a reference to a firmware image.
156 .Fa flags
158 .Dv FIRMWARE_UNLOAD
161 the firmware image if this is the last reference.
163 .Xr taskqueue 9
164 thread so the call may be done while holding a lock.
165 In certain cases, such as on driver detach, this cannot be allowed.
166 .Sh FIRMWARE LOADING MECHANISMS
169 .Fn firmware_register .
170 .Pp
174 .Nm /boot/loader ,
176 .Xr kldload 8 .
179 .Fn firmware_register .
180 .Pp
182 .Fn firmware_get
184 one of the available loading mechanisms.
186 .Nm Loadable kernel modules :
187 .Pp
189 .Nm foo
191 .Nm foo.ko ,
193 .Xr kld 4 .
196 .Nm kern.module_path
198 .Nm /boot/kernel;/boot/modules .
199 .Pp
202 .Fn firmware_get
204 for the other images.
205 .Sh BUILDING FIRMWARE LOADABLE MODULES
207 .Nm firmware image
209 .Fn firmware_register
211 .Fn firmware_unregister
212 on unloading.
213 .Pp
216 .Bd -literal
220         .include <bsd.kmod.mk>
222 .Ed
225 in the module, the imagename and version of each firmware image.
226 .Pp
228 appropriate entries in the <files.arch> file, e.g. this example is
230 .Nm sys/arm/xscale/ixp425/files.ixp425 :
231 .Bd -literal
232 ixp425_npe_fw.c                         optional npe_fw                 \\
233         compile-with    "${AWK} -f $S/tools/fw_stub.awk			\\
234 			IxNpeMicrocode.dat:npe_fw -mnpe -c${.TARGET}"	\\
236         clean           "ixp425_npe_fw.c"
240 #     get known values for reference in the _fw.c file.
242 IxNpeMicrocode.fwo  optional npe_fw					\\
243         dependency      "IxNpeMicrocode.dat"				\\
245 			    -r -d -o ${.TARGET} IxNpeMicrocode.dat"	\\
247         clean           "IxNpeMicrocode.fwo"
248 IxNpeMicrocode.dat                      optional npe_fw                 \\
249         dependency      ".PHONY"                                        \\
250         compile-with    "uudecode < $S/contrib/dev/npe/IxNpeMicrocode.dat.uu" \\
252         clean           "IxNpeMicrocode.dat"
253 .Ed
254 .Pp
257 .Xr awk 1 ,
258 .Xr make 1 ,
259 the compiler and the linker.
260 .Sh SEE ALSO
261 .Xr kld 4 ,
262 .Xr module 9
263 .Pp
264 .Pa /usr/share/examples/kld/firmware
265 .Sh HISTORY
267 .Nm firmware
269 .Fx 6.1 .
270 .Sh AUTHORS
272 .An Max Laier Aq mlaier@FreeBSD.org .