2 * SPDX-License-Identifier: BSD-2-Clause
4 * Copyright (c) 2005-2008, Sam Leffler <sam@errno.com>
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
10 * 1. Redistributions of source code must retain the above copyright
11 * notice unmodified, this list of conditions, and the following
13 * 2. Redistributions in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in the
15 * documentation and/or other materials provided with the distribution.
17 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 #include <sys/param.h>
30 #include <sys/errno.h>
31 #include <sys/eventhandler.h>
32 #include <sys/fcntl.h>
33 #include <sys/firmware.h>
34 #include <sys/kernel.h>
35 #include <sys/linker.h>
37 #include <sys/malloc.h>
38 #include <sys/module.h>
39 #include <sys/mutex.h>
40 #include <sys/namei.h>
43 #include <sys/queue.h>
45 #include <sys/sysctl.h>
46 #include <sys/systm.h>
47 #include <sys/taskqueue.h>
49 #include <sys/filedesc.h>
50 #include <sys/vnode.h>
53 * Loadable firmware support. See sys/sys/firmware.h and firmware(9)
54 * form more details on the subsystem.
56 * 'struct firmware' is the user-visible part of the firmware table.
57 * Additional internal information is stored in a 'struct priv_fw',
58 * which embeds the public firmware structure.
62 * fw.name != NULL when an image is registered; file != NULL for
63 * autoloaded images whose handling has not been completed.
65 * The state of a slot evolves as follows:
66 * firmware_register --> fw.name = image_name
67 * (autoloaded image) --> file = module reference
68 * firmware_unregister --> fw.name = NULL
69 * (unloadentry complete) --> file = NULL
71 * In order for the above to work, the 'file' field must remain
72 * unchanged in firmware_unregister().
74 * Images residing in the same module are linked to each other
75 * through the 'parent' argument of firmware_register().
76 * One image (typically, one with the same name as the module to let
77 * the autoloading mechanism work) is considered the parent image for
78 * all other images in the same module. Children affect the refcount
79 * on the parent image preventing improper unloading of the image itself.
83 int refcnt; /* reference count */
84 LIST_ENTRY(priv_fw) link; /* table linkage */
87 * parent entry, see above. Set on firmware_register(),
88 * cleared on firmware_unregister().
90 struct priv_fw *parent;
93 #define FW_BINARY 0x080 /* Firmware directly loaded, file == NULL */
94 #define FW_UNLOAD 0x100 /* record FIRMWARE_UNLOAD requests */
97 * 'file' is private info managed by the autoload/unload code.
98 * Set at the end of firmware_get(), cleared only in the
99 * firmware_unload_task, so the latter can depend on its value even
100 * while the lock is not held.
102 linker_file_t file; /* module file, if autoloaded */
105 * 'fw' is the externally visible image information.
106 * We do not make it the first field in priv_fw, to avoid the
107 * temptation of casting pointers to each other.
108 * Use PRIV_FW(fw) to get a pointer to the cointainer of fw.
109 * Beware, PRIV_FW does not work for a NULL pointer.
111 struct firmware fw; /* externally visible information */
115 * PRIV_FW returns the pointer to the container of struct firmware *x.
116 * Cast to intptr_t to override the 'const' attribute of x
118 #define PRIV_FW(x) ((struct priv_fw *) \
119 ((intptr_t)(x) - offsetof(struct priv_fw, fw)) )
122 * Global firmware image registry.
124 static LIST_HEAD(, priv_fw) firmware_table;
127 * Firmware module operations are handled in a separate task as they
128 * might sleep and they require directory context to do i/o. We also
129 * use this when loading binaries directly.
131 static struct taskqueue *firmware_tq;
132 static struct task firmware_unload_task;
135 * This mutex protects accesses to the firmware table.
137 static struct mtx firmware_mtx;
138 MTX_SYSINIT(firmware, &firmware_mtx, "firmware table", MTX_DEF);
140 static MALLOC_DEFINE(M_FIRMWARE, "firmware", "device firmware images");
142 static uint64_t firmware_max_size = 8u << 20; /* Default to 8MB cap */
143 SYSCTL_U64(_debug, OID_AUTO, firmware_max_size,
144 CTLFLAG_RWTUN, &firmware_max_size, 0,
145 "Max size permitted for a firmware file.");
148 * Helper function to lookup a name.
149 * As a side effect, it sets the pointer to a free slot, if any.
150 * This way we can concentrate most of the registry scanning in
151 * this function, which makes it easier to replace the registry
152 * with some other data structure.
154 static struct priv_fw *
155 lookup(const char *name)
159 mtx_assert(&firmware_mtx, MA_OWNED);
161 LIST_FOREACH(fp, &firmware_table, link) {
162 if (fp->fw.name != NULL && strcasecmp(name, fp->fw.name) == 0)
166 * If the name looks like an absolute path, also try to match
167 * the last part of the string to the requested firmware if it
168 * matches the trailing components. This allows us to load
169 * /boot/firmware/abc/bca2233_fw.bin and match it against
170 * requests for bca2233_fw.bin or abc/bca2233_fw.bin.
172 if (*fp->fw.name == '/' && strlen(fp->fw.name) > strlen(name)) {
173 const char *p = fp->fw.name + strlen(fp->fw.name) - strlen(name);
174 if (p[-1] == '/' && strcasecmp(name, p) == 0)
182 * Register a firmware image with the specified name. The
183 * image name must not already be registered. If this is a
184 * subimage then parent refers to a previously registered
185 * image that this should be associated with.
187 const struct firmware *
188 firmware_register(const char *imagename, const void *data, size_t datasize,
189 unsigned int version, const struct firmware *parent)
194 mtx_lock(&firmware_mtx);
195 frp = lookup(imagename);
197 mtx_unlock(&firmware_mtx);
198 printf("%s: image %s already registered!\n",
199 __func__, imagename);
202 mtx_unlock(&firmware_mtx);
204 frp = malloc(sizeof(*frp), M_FIRMWARE, M_WAITOK | M_ZERO);
205 name = strdup(imagename, M_FIRMWARE);
207 mtx_lock(&firmware_mtx);
208 if (lookup(imagename) != NULL) {
209 /* We lost a race. */
210 mtx_unlock(&firmware_mtx);
211 free(name, M_FIRMWARE);
212 free(frp, M_FIRMWARE);
217 frp->fw.datasize = datasize;
218 frp->fw.version = version;
220 frp->parent = PRIV_FW(parent);
221 LIST_INSERT_HEAD(&firmware_table, frp, link);
222 mtx_unlock(&firmware_mtx);
224 printf("firmware: '%s' version %u: %zu bytes loaded at %p\n",
225 imagename, version, datasize, data);
230 * Unregister/remove a firmware image. If there are outstanding
231 * references an error is returned and the image is not removed
235 firmware_unregister(const char *imagename)
240 mtx_lock(&firmware_mtx);
241 fp = lookup(imagename);
244 * It is ok for the lookup to fail; this can happen
245 * when a module is unloaded on last reference and the
246 * module unload handler unregister's each of its
250 } else if (fp->refcnt != 0) { /* cannot unregister */
253 LIST_REMOVE(fp, link);
254 free(__DECONST(char *, fp->fw.name), M_FIRMWARE);
255 free(fp, M_FIRMWARE);
258 mtx_unlock(&firmware_mtx);
262 struct fw_loadimage {
263 const char *imagename;
267 static const char *fw_path = "/boot/firmware/";
270 try_binary_file(const char *imagename, uint32_t flags)
273 struct thread *td = curthread;
274 struct ucred *cred = td ? td->td_ucred : NULL;
280 const struct firmware *fw;
284 bool warn = flags & FIRMWARE_GET_NOWARN;
287 * XXX TODO: Loop over some path instead of a single element path.
288 * and fetch this path from the 'firmware_path' kenv the loader sets.
290 sb = sbuf_new_auto();
291 sbuf_printf(sb, "%s%s", fw_path, imagename);
295 printf("Trying to load binary firmware from %s\n", fn);
297 NDINIT(&nd, LOOKUP, FOLLOW, UIO_SYSSPACE, fn);
299 error = vn_open(&nd, &oflags, 0, NULL);
303 if (nd.ni_vp->v_type != VREG)
305 error = VOP_GETATTR(nd.ni_vp, &vattr, cred);
310 * Limit this to something sane, 8MB by default.
312 if (vattr.va_size > firmware_max_size) {
313 printf("Firmware %s is too big: %lld bytes, %ld bytes max.\n",
314 fn, (long long)vattr.va_size, (long)firmware_max_size);
317 data = malloc(vattr.va_size, M_FIRMWARE, M_WAITOK);
318 error = vn_rdwr(UIO_READ, nd.ni_vp, (caddr_t)data, vattr.va_size, 0,
319 UIO_SYSSPACE, IO_NODELOCKED, cred, NOCRED, &resid, td);
320 /* XXX make data read only? */
321 VOP_UNLOCK(nd.ni_vp);
322 vn_close(nd.ni_vp, FREAD, cred, td);
324 if (error != 0 || resid != 0)
326 fw = firmware_register(fn, data, vattr.va_size, 0, NULL);
330 fp->flags |= FW_BINARY;
332 printf("%s: Loaded binary firmware using %s\n", imagename, fn);
336 err2: /* cleanup in vn_open through vn_close */
337 VOP_UNLOCK(nd.ni_vp);
338 vn_close(nd.ni_vp, FREAD, cred, td);
340 free(data, M_FIRMWARE);
341 if (bootverbose || warn)
342 printf("%s: could not load binary firmware %s either\n", imagename, fn);
347 loadimage(void *arg, int npending __unused)
349 struct fw_loadimage *fwli = arg;
351 linker_file_t result;
354 error = linker_reference_module(fwli->imagename, NULL, &result);
356 if (bootverbose || (fwli->flags & FIRMWARE_GET_NOWARN) == 0)
357 printf("%s: could not load firmware image, error %d\n",
358 fwli->imagename, error);
359 try_binary_file(fwli->imagename, fwli->flags);
360 mtx_lock(&firmware_mtx);
364 mtx_lock(&firmware_mtx);
365 fp = lookup(fwli->imagename);
366 if (fp == NULL || fp->file != NULL) {
367 mtx_unlock(&firmware_mtx);
369 printf("%s: firmware image loaded, "
370 "but did not register\n", fwli->imagename);
371 (void) linker_release_module(fwli->imagename, NULL, NULL);
372 mtx_lock(&firmware_mtx);
375 fp->file = result; /* record the module identity */
378 mtx_unlock(&firmware_mtx);
382 * Lookup and potentially load the specified firmware image.
383 * If the firmware is not found in the registry, try to load a kernel
384 * module named as the image name.
385 * If the firmware is located, a reference is returned. The caller must
386 * release this reference for the image to be eligible for removal/unload.
388 const struct firmware *
389 firmware_get_flags(const char *imagename, uint32_t flags)
391 struct task fwload_task;
395 mtx_lock(&firmware_mtx);
396 fp = lookup(imagename);
400 * Image not present, try to load the module holding it.
403 if (priv_check(td, PRIV_FIRMWARE_LOAD) != 0 ||
404 securelevel_gt(td->td_ucred, 0) != 0) {
405 mtx_unlock(&firmware_mtx);
406 printf("%s: insufficient privileges to "
407 "load firmware image %s\n", __func__, imagename);
411 * Defer load to a thread with known context. linker_reference_module
412 * may do filesystem i/o which requires root & current dirs, etc.
413 * Also we must not hold any mtx's over this call which is problematic.
416 struct fw_loadimage fwli;
418 fwli.imagename = imagename;
420 TASK_INIT(&fwload_task, 0, loadimage, (void *)&fwli);
421 taskqueue_enqueue(firmware_tq, &fwload_task);
423 msleep((void *)&fwli, &firmware_mtx, 0, "fwload", 0);
427 * After attempting to load the module, see if the image is registered.
429 fp = lookup(imagename);
431 mtx_unlock(&firmware_mtx);
434 found: /* common exit point on success */
435 if (fp->refcnt == 0 && fp->parent != NULL)
436 fp->parent->refcnt++;
438 mtx_unlock(&firmware_mtx);
442 const struct firmware *
443 firmware_get(const char *imagename)
446 return (firmware_get_flags(imagename, 0));
450 * Release a reference to a firmware image returned by firmware_get.
451 * The caller may specify, with the FIRMWARE_UNLOAD flag, its desire
452 * to release the resource, but the flag is only advisory.
454 * If this is the last reference to the firmware image, and this is an
455 * autoloaded module, wake up the firmware_unload_task to figure out
456 * what to do with the associated module.
459 firmware_put(const struct firmware *p, int flags)
461 struct priv_fw *fp = PRIV_FW(p);
463 mtx_lock(&firmware_mtx);
465 if (fp->refcnt == 0) {
466 if (fp->parent != NULL)
467 fp->parent->refcnt--;
468 if (flags & FIRMWARE_UNLOAD)
469 fp->flags |= FW_UNLOAD;
471 taskqueue_enqueue(firmware_tq, &firmware_unload_task);
473 mtx_unlock(&firmware_mtx);
477 * Setup directory state for the firmware_tq thread so we can do i/o.
480 set_rootvnode(void *arg, int npending)
488 * Event handler called on mounting of /; bounce a task
489 * into the task queue thread to setup it's directories.
492 firmware_mountroot(void *arg)
494 struct task *setroot_task;
496 setroot_task = malloc(sizeof(struct task), M_TEMP, M_NOWAIT);
497 if (setroot_task != NULL) {
498 TASK_INIT(setroot_task, 0, set_rootvnode, setroot_task);
499 taskqueue_enqueue(firmware_tq, setroot_task);
501 printf("%s: no memory for task!\n", __func__);
503 EVENTHANDLER_DEFINE(mountroot, firmware_mountroot, NULL, 0);
506 * The body of the task in charge of unloading autoloaded modules
507 * that are not needed anymore.
508 * Images can be cross-linked so we may need to make multiple passes,
509 * but the time we spend in the loop is bounded because we clear entries
513 unloadentry(void *unused1, int unused2)
515 struct priv_fw *fp, *tmp;
517 mtx_lock(&firmware_mtx);
519 LIST_FOREACH_SAFE(fp, &firmware_table, link, tmp) {
520 if (((fp->flags & FW_BINARY) == 0 && fp->file == NULL) ||
521 fp->refcnt != 0 || (fp->flags & FW_UNLOAD) == 0)
525 * If we directly loaded the firmware, then we just need to
526 * remove the entry from the list and free the entry and go to
527 * the next one. There's no need for the indirection of the kld
528 * module case, we free memory and go to the next one.
530 if ((fp->flags & FW_BINARY) != 0) {
531 LIST_REMOVE(fp, link);
532 free(__DECONST(char *, fp->fw.data), M_FIRMWARE);
533 free(__DECONST(char *, fp->fw.name), M_FIRMWARE);
534 free(fp, M_FIRMWARE);
539 * Found an entry. This is the kld case, so we have a more
540 * complex dance. Now:
541 * 1. make sure we scan the table again
542 * 2. clear FW_UNLOAD so we don't try this entry again.
543 * 3. release the lock while trying to unload the module.
545 fp->flags &= ~FW_UNLOAD; /* do not try again */
548 * We rely on the module to call firmware_unregister()
549 * on unload to actually free the entry.
551 mtx_unlock(&firmware_mtx);
552 (void)linker_release_module(NULL, NULL, fp->file);
553 mtx_lock(&firmware_mtx);
556 * When we dropped the lock, another thread could have
557 * removed an element, so we must restart the scan.
561 mtx_unlock(&firmware_mtx);
565 * Find all the binary firmware that was loaded in the boot loader via load -t
566 * firmware foo. There is only one firmware per file, it's the whole file, and
567 * there's no meaningful version passed in, so pass 0 for that. If version is
568 * needed by the consumer (and not just arbitrarily defined), the .ko version
569 * must be used instead.
572 firmware_binary_files(void)
579 unsigned int version = 0;
580 const struct firmware *fw;
585 file = preload_search_next_name(file);
588 type = (const char *)preload_search_info(file, MODINFO_TYPE);
589 if (type == NULL || strcmp(type, "firmware") != 0)
591 name = preload_search_info(file, MODINFO_NAME);
592 addr = preload_fetch_addr(file);
593 size = preload_fetch_size(file);
594 fw = firmware_register(name, addr, size, version, NULL);
596 fp->refcnt++; /* Hold an extra reference so we never unload */
604 firmware_modevent(module_t mod, int type, void *unused)
612 TASK_INIT(&firmware_unload_task, 0, unloadentry, NULL);
613 firmware_tq = taskqueue_create("taskqueue_firmware", M_WAITOK,
614 taskqueue_thread_enqueue, &firmware_tq);
615 /* NB: use our own loop routine that sets up context */
616 (void) taskqueue_start_threads(&firmware_tq, 1, PWAIT,
618 firmware_binary_files();
619 if (rootvnode != NULL) {
621 * Root is already mounted so we won't get an event;
624 firmware_mountroot(NULL);
629 /* request all autoloaded modules to be released */
630 mtx_lock(&firmware_mtx);
631 LIST_FOREACH(fp, &firmware_table, link)
632 fp->flags |= FW_UNLOAD;
633 mtx_unlock(&firmware_mtx);
634 taskqueue_enqueue(firmware_tq, &firmware_unload_task);
635 taskqueue_drain(firmware_tq, &firmware_unload_task);
637 LIST_FOREACH(fp, &firmware_table, link) {
638 if (fp->fw.name != NULL) {
639 printf("%s: image %s still active, %d refs\n",
640 __func__, fp->fw.name, fp->refcnt);
645 taskqueue_free(firmware_tq);
655 static moduledata_t firmware_mod = {
660 DECLARE_MODULE(firmware, firmware_mod, SI_SUB_DRIVERS, SI_ORDER_FIRST);
661 MODULE_VERSION(firmware, 1);