diff --git a/share/man/man9/firmware.9 b/share/man/man9/firmware.9 index b0d429573cf6..6d91beb3ddd1 100644 --- a/share/man/man9/firmware.9 +++ b/share/man/man9/firmware.9 @@ -1,274 +1,300 @@ .\" Copyright (c) 2006 Max Laier .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd March 14, 2019 +.Dd January 27, 2021 .Dt FIRMWARE 9 .Os .Sh NAME .Nm firmware_register , .Nm firmware_unregister , .Nm firmware_get , +.Nm firmware_get_flags , .Nm firmware_put .Nd firmware image loading and management .Sh SYNOPSIS .In sys/param.h .In sys/systm.h .In sys/linker.h .In sys/firmware.h .Bd -literal 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 */ }; .Ed .Ft "const struct firmware *" .Fo firmware_register .Fa "const char *imagename" .Fa "const void *data" .Fa "size_t datasize" .Fa "unsigned int version" .Fa "const struct firmware *parent" .Fc .Ft int .Fn firmware_unregister "const char *imagename" .Ft "const struct firmware *" .Fn firmware_get "const char *imagename" +.Ft "const struct firmware *" +.Fn firmware_get_flags "const char *imagename" "uint32_t flags" .Ft void .Fn firmware_put "const struct firmware *fp" "int flags" .Sh DESCRIPTION The .Nm firmware abstraction provides a convenient interface for loading .Nm firmware images into the kernel, and for accessing such images from kernel components. .Pp A .Nm firmware image (or .Nm image for brevity) is an opaque block of data residing in kernel memory. It is associated to a unique .Nm imagename which constitutes a search key, and to an integer .Nm version number, which is also an opaque piece of information for the firmware subsystem. .Pp An image is registered with the .Nm firmware subsystem by calling the function .Fn firmware_register , and unregistered by calling .Fn firmware_unregister . 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 , manually at runtime, or on demand by the firmware subsystem. .Pp .Nm Clients of the firmware subsystem can request access to a given image by calling the function .Fn firmware_get with the .Nm imagename -they want as an argument. +they want as an argument, or by calling +.Fn firmware_get_flags +with the +.Nm imagename +and +.Nm flags +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 .Nm the same name as the image). .Sh API DESCRIPTION The kernel .Nm firmware API is made of the following functions: .Pp .Fn firmware_register registers with the kernel an image of size .Nm datasize located at address .Nm data , under the name .Nm imagename . .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 .Ft const struct firmware * pointer to the image requested. .Pp .Fn firmware_unregister tries to unregister the firmware image .Nm imagename 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. .Pp .Fn firmware_get -returns the requested firmware image. +and +.Fn firmware_get_flags +return the requested firmware image. +The +.Fa flags +argument may be set to +.Dv FIRMWARE_GET_NOWARN +to indicate that errors on firmware load or registration should +only be logged in case of +.Nm booverbose . If the image is not yet registered with the system, -the function tries to load it. +the functions try to load it. This involves the linker subsystem and disk access, so .Fn firmware_get +or +.Fn firmware_get_flags must not be called with any locks (except for .Va Giant ) . 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. .Pp On success, .Fn firmware_get -returns a pointer to the image description and increases the reference count +and +.Fn firmware_get_flags +return a pointer to the image description and increase the reference count for this image. -On failure, the function returns NULL. +On failure, the functions return NULL. .Pp .Fn firmware_put drops a reference to a firmware image. The .Fa flags argument may be set to .Dv FIRMWARE_UNLOAD 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 .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 As mentioned before, any component of the system can register firmware images at any time by simply calling .Fn firmware_register . .Pp This is typically done when a module containing a firmware image is given control, whether compiled in, or preloaded by .Nm /boot/loader , or manually loaded with .Xr kldload 8 . However, a system can implement additional mechanisms to bring these images in memory before calling .Fn firmware_register . .Pp When .Fn firmware_get +or +.Fn firmware_get_flags 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 -.Nm Loadable kernel modules : +.Nm Loadable kernel modules . .Pp A firmware image named .Nm foo is looked up by trying to load the module named .Nm foo.ko , using the facilities described in .Xr kld 4 . In particular, images are looked up in the directories specified by the sysctl variable .Nm kern.module_path which on most systems defaults to .Nm /boot/kernel;/boot/modules . .Pp Note that in case a module contains multiple images, the caller should first request a .Fn firmware_get +or +.Fn firmware_get_flags for the first image contained in the module, followed by requests for the other images. .Sh BUILDING FIRMWARE LOADABLE MODULES A firmware module is built by embedding the .Nm firmware image into a suitable loadable kernel module that calls .Fn firmware_register on loading, and .Fn firmware_unregister on unloading. .Pp Various system scripts and makefiles let you build a module by simply writing a Makefile with the following entries: .Bd -literal KMOD= imagename FIRMWS= image_file:imagename[:version] .include .Ed 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. .Pp If you need to embed firmware images into a system, you should write appropriate entries in the file, e.g. this example is from .Nm sys/arm/xscale/ixp425/files.ixp425 : .Bd -literal ixp425_npe_fw.c optional npe_fw \\ compile-with "${AWK} -f $S/tools/fw_stub.awk \\ IxNpeMicrocode.dat:npe_fw -mnpe -c${.TARGET}" \\ no-implicit-rule before-depend local \\ clean "ixp425_npe_fw.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. # IxNpeMicrocode.fwo optional npe_fw \\ dependency "IxNpeMicrocode.dat" \\ compile-with "${LD} -b binary -d -warn-common \\ -r -d -o ${.TARGET} IxNpeMicrocode.dat" \\ no-implicit-rule \\ clean "IxNpeMicrocode.fwo" .Ed .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. .Pp Note that generating the firmware modules in this way requires the availability of the following tools: .Xr awk 1 , .Xr make 1 , the compiler and the linker. .Sh SEE ALSO .Xr kld 4 , .Xr module 9 .Pp .Pa /usr/share/examples/kld/firmware .Sh HISTORY The .Nm firmware system was introduced in .Fx 6.1 . .Sh AUTHORS This manual page was written by .An Max Laier Aq Mt mlaier@FreeBSD.org . diff --git a/sys/kern/subr_firmware.c b/sys/kern/subr_firmware.c index db262c121918..0465f2a88483 100644 --- a/sys/kern/subr_firmware.c +++ b/sys/kern/subr_firmware.c @@ -1,492 +1,509 @@ /*- * SPDX-License-Identifier: BSD-2-Clause-FreeBSD * * Copyright (c) 2005-2008, Sam Leffler * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright * notice unmodified, this list of conditions, and the following * disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #include __FBSDID("$FreeBSD$"); #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include /* * Loadable firmware support. See sys/sys/firmware.h and firmware(9) * form more details on the subsystem. * * 'struct firmware' is the user-visible part of the firmware table. * Additional internal information is stored in a 'struct priv_fw', * which embeds the public firmware structure. */ /* * fw.name != NULL when an image is registered; file != NULL for * autoloaded images whose handling has not been completed. * * The state of a slot evolves as follows: * firmware_register --> fw.name = image_name * (autoloaded image) --> file = module reference * firmware_unregister --> fw.name = NULL * (unloadentry complete) --> file = NULL * * In order for the above to work, the 'file' field must remain * unchanged in firmware_unregister(). * * Images residing in the same module are linked to each other * through the 'parent' argument of firmware_register(). * One image (typically, one with the same name as the module to let * the autoloading mechanism work) is considered the parent image for * all other images in the same module. Children affect the refcount * on the parent image preventing improper unloading of the image itself. */ struct priv_fw { int refcnt; /* reference count */ LIST_ENTRY(priv_fw) link; /* table linkage */ /* * parent entry, see above. Set on firmware_register(), * cleared on firmware_unregister(). */ struct priv_fw *parent; int flags; /* record FIRMWARE_UNLOAD requests */ #define FW_UNLOAD 0x100 /* * 'file' is private info managed by the autoload/unload code. * Set at the end of firmware_get(), cleared only in the * firmware_unload_task, so the latter can depend on its value even * while the lock is not held. */ linker_file_t file; /* module file, if autoloaded */ /* * 'fw' is the externally visible image information. * We do not make it the first field in priv_fw, to avoid the * temptation of casting pointers to each other. * Use PRIV_FW(fw) to get a pointer to the cointainer of fw. * Beware, PRIV_FW does not work for a NULL pointer. */ struct firmware fw; /* externally visible information */ }; /* * PRIV_FW returns the pointer to the container of struct firmware *x. * Cast to intptr_t to override the 'const' attribute of x */ #define PRIV_FW(x) ((struct priv_fw *) \ ((intptr_t)(x) - offsetof(struct priv_fw, fw)) ) /* * Global firmware image registry. */ static LIST_HEAD(, priv_fw) firmware_table; /* * Firmware module operations are handled in a separate task as they * might sleep and they require directory context to do i/o. */ static struct taskqueue *firmware_tq; static struct task firmware_unload_task; /* * This mutex protects accesses to the firmware table. */ static struct mtx firmware_mtx; MTX_SYSINIT(firmware, &firmware_mtx, "firmware table", MTX_DEF); static MALLOC_DEFINE(M_FIRMWARE, "firmware", "device firmware images"); /* * Helper function to lookup a name. * As a side effect, it sets the pointer to a free slot, if any. * This way we can concentrate most of the registry scanning in * this function, which makes it easier to replace the registry * with some other data structure. */ static struct priv_fw * lookup(const char *name) { struct priv_fw *fp; mtx_assert(&firmware_mtx, MA_OWNED); LIST_FOREACH(fp, &firmware_table, link) { if (fp->fw.name != NULL && strcasecmp(name, fp->fw.name) == 0) break; } return (fp); } /* * Register a firmware image with the specified name. The * image name must not already be registered. If this is a * subimage then parent refers to a previously registered * image that this should be associated with. */ const struct firmware * firmware_register(const char *imagename, const void *data, size_t datasize, unsigned int version, const struct firmware *parent) { struct priv_fw *frp; char *name; mtx_lock(&firmware_mtx); frp = lookup(imagename); if (frp != NULL) { mtx_unlock(&firmware_mtx); printf("%s: image %s already registered!\n", __func__, imagename); return (NULL); } mtx_unlock(&firmware_mtx); frp = malloc(sizeof(*frp), M_FIRMWARE, M_WAITOK | M_ZERO); name = strdup(imagename, M_FIRMWARE); mtx_lock(&firmware_mtx); if (lookup(imagename) != NULL) { /* We lost a race. */ mtx_unlock(&firmware_mtx); free(name, M_FIRMWARE); free(frp, M_FIRMWARE); return (NULL); } frp->fw.name = name; frp->fw.data = data; frp->fw.datasize = datasize; frp->fw.version = version; if (parent != NULL) frp->parent = PRIV_FW(parent); LIST_INSERT_HEAD(&firmware_table, frp, link); mtx_unlock(&firmware_mtx); if (bootverbose) printf("firmware: '%s' version %u: %zu bytes loaded at %p\n", imagename, version, datasize, data); return (&frp->fw); } /* * Unregister/remove a firmware image. If there are outstanding * references an error is returned and the image is not removed * from the registry. */ int firmware_unregister(const char *imagename) { struct priv_fw *fp; int err; mtx_lock(&firmware_mtx); fp = lookup(imagename); if (fp == NULL) { /* * It is ok for the lookup to fail; this can happen * when a module is unloaded on last reference and the * module unload handler unregister's each of its * firmware images. */ err = 0; } else if (fp->refcnt != 0) { /* cannot unregister */ err = EBUSY; } else { LIST_REMOVE(fp, link); free(__DECONST(char *, fp->fw.name), M_FIRMWARE); free(fp, M_FIRMWARE); err = 0; } mtx_unlock(&firmware_mtx); return (err); } +struct fw_loadimage { + const char *imagename; + uint32_t flags; +}; + static void -loadimage(void *arg, int npending) +loadimage(void *arg, int npending __unused) { - char *imagename = arg; + struct fw_loadimage *fwli = arg; struct priv_fw *fp; linker_file_t result; int error; - error = linker_reference_module(imagename, NULL, &result); + error = linker_reference_module(fwli->imagename, NULL, &result); if (error != 0) { - printf("%s: could not load firmware image, error %d\n", - imagename, error); + if (bootverbose || (fwli->flags & FIRMWARE_GET_NOWARN) == 0) + printf("%s: could not load firmware image, error %d\n", + fwli->imagename, error); mtx_lock(&firmware_mtx); goto done; } mtx_lock(&firmware_mtx); - fp = lookup(imagename); + fp = lookup(fwli->imagename); if (fp == NULL || fp->file != NULL) { mtx_unlock(&firmware_mtx); if (fp == NULL) printf("%s: firmware image loaded, " - "but did not register\n", imagename); - (void) linker_release_module(imagename, NULL, NULL); + "but did not register\n", fwli->imagename); + (void) linker_release_module(fwli->imagename, NULL, NULL); mtx_lock(&firmware_mtx); goto done; } fp->file = result; /* record the module identity */ done: - wakeup_one(imagename); + wakeup_one(arg); mtx_unlock(&firmware_mtx); } /* * Lookup and potentially load the specified firmware image. * If the firmware is not found in the registry, try to load a kernel * module named as the image name. * If the firmware is located, a reference is returned. The caller must * release this reference for the image to be eligible for removal/unload. */ const struct firmware * -firmware_get(const char *imagename) +firmware_get_flags(const char *imagename, uint32_t flags) { struct task fwload_task; struct thread *td; struct priv_fw *fp; mtx_lock(&firmware_mtx); fp = lookup(imagename); if (fp != NULL) goto found; /* * Image not present, try to load the module holding it. */ td = curthread; if (priv_check(td, PRIV_FIRMWARE_LOAD) != 0 || securelevel_gt(td->td_ucred, 0) != 0) { mtx_unlock(&firmware_mtx); printf("%s: insufficient privileges to " "load firmware image %s\n", __func__, imagename); return NULL; } /* * Defer load to a thread with known context. linker_reference_module * may do filesystem i/o which requires root & current dirs, etc. * Also we must not hold any mtx's over this call which is problematic. */ if (!cold) { - TASK_INIT(&fwload_task, 0, loadimage, __DECONST(void *, - imagename)); + struct fw_loadimage fwli; + + fwli.imagename = imagename; + fwli.flags = flags; + TASK_INIT(&fwload_task, 0, loadimage, (void *)&fwli); taskqueue_enqueue(firmware_tq, &fwload_task); - msleep(__DECONST(void *, imagename), &firmware_mtx, 0, - "fwload", 0); + PHOLD(curproc); + msleep((void *)&fwli, &firmware_mtx, 0, "fwload", 0); + PRELE(curproc); } /* * After attempting to load the module, see if the image is registered. */ fp = lookup(imagename); if (fp == NULL) { mtx_unlock(&firmware_mtx); return NULL; } found: /* common exit point on success */ if (fp->refcnt == 0 && fp->parent != NULL) fp->parent->refcnt++; fp->refcnt++; mtx_unlock(&firmware_mtx); return &fp->fw; } +const struct firmware * +firmware_get(const char *imagename) +{ + + return (firmware_get_flags(imagename, 0)); +} + /* * Release a reference to a firmware image returned by firmware_get. * The caller may specify, with the FIRMWARE_UNLOAD flag, its desire * to release the resource, but the flag is only advisory. * * If this is the last reference to the firmware image, and this is an * autoloaded module, wake up the firmware_unload_task to figure out * what to do with the associated module. */ void firmware_put(const struct firmware *p, int flags) { struct priv_fw *fp = PRIV_FW(p); mtx_lock(&firmware_mtx); fp->refcnt--; if (fp->refcnt == 0) { if (fp->parent != NULL) fp->parent->refcnt--; if (flags & FIRMWARE_UNLOAD) fp->flags |= FW_UNLOAD; if (fp->file) taskqueue_enqueue(firmware_tq, &firmware_unload_task); } mtx_unlock(&firmware_mtx); } /* * Setup directory state for the firmware_tq thread so we can do i/o. */ static void set_rootvnode(void *arg, int npending) { pwd_ensure_dirs(); free(arg, M_TEMP); } /* * Event handler called on mounting of /; bounce a task * into the task queue thread to setup it's directories. */ static void firmware_mountroot(void *arg) { struct task *setroot_task; setroot_task = malloc(sizeof(struct task), M_TEMP, M_NOWAIT); if (setroot_task != NULL) { TASK_INIT(setroot_task, 0, set_rootvnode, setroot_task); taskqueue_enqueue(firmware_tq, setroot_task); } else printf("%s: no memory for task!\n", __func__); } EVENTHANDLER_DEFINE(mountroot, firmware_mountroot, NULL, 0); /* * The body of the task in charge of unloading autoloaded modules * that are not needed anymore. * Images can be cross-linked so we may need to make multiple passes, * but the time we spend in the loop is bounded because we clear entries * as we touch them. */ static void unloadentry(void *unused1, int unused2) { struct priv_fw *fp; int err; mtx_lock(&firmware_mtx); restart: LIST_FOREACH(fp, &firmware_table, link) { if (fp->file == NULL || fp->refcnt != 0 || (fp->flags & FW_UNLOAD) == 0) continue; /* * Found an entry. Now: * 1. make sure we scan the table again * 2. clear FW_UNLOAD so we don't try this entry again. * 3. release the lock while trying to unload the module. */ fp->flags &= ~FW_UNLOAD; /* do not try again */ /* * We rely on the module to call firmware_unregister() * on unload to actually free the entry. */ mtx_unlock(&firmware_mtx); err = linker_release_module(NULL, NULL, fp->file); mtx_lock(&firmware_mtx); /* * When we dropped the lock, another thread could have * removed an element, so we must restart the scan. */ goto restart; } mtx_unlock(&firmware_mtx); } /* * Module glue. */ static int firmware_modevent(module_t mod, int type, void *unused) { struct priv_fw *fp; int err; err = 0; switch (type) { case MOD_LOAD: TASK_INIT(&firmware_unload_task, 0, unloadentry, NULL); firmware_tq = taskqueue_create("taskqueue_firmware", M_WAITOK, taskqueue_thread_enqueue, &firmware_tq); /* NB: use our own loop routine that sets up context */ (void) taskqueue_start_threads(&firmware_tq, 1, PWAIT, "firmware taskq"); if (rootvnode != NULL) { /* * Root is already mounted so we won't get an event; * simulate one here. */ firmware_mountroot(NULL); } break; case MOD_UNLOAD: /* request all autoloaded modules to be released */ mtx_lock(&firmware_mtx); LIST_FOREACH(fp, &firmware_table, link) fp->flags |= FW_UNLOAD; mtx_unlock(&firmware_mtx); taskqueue_enqueue(firmware_tq, &firmware_unload_task); taskqueue_drain(firmware_tq, &firmware_unload_task); LIST_FOREACH(fp, &firmware_table, link) { if (fp->fw.name != NULL) { printf("%s: image %s still active, %d refs\n", __func__, fp->fw.name, fp->refcnt); err = EINVAL; } } if (err == 0) taskqueue_free(firmware_tq); break; default: err = EOPNOTSUPP; break; } return (err); } static moduledata_t firmware_mod = { "firmware", firmware_modevent, NULL }; DECLARE_MODULE(firmware, firmware_mod, SI_SUB_DRIVERS, SI_ORDER_FIRST); MODULE_VERSION(firmware, 1); diff --git a/sys/sys/firmware.h b/sys/sys/firmware.h index 8a9b2cf23bd7..0d74a749f4fc 100644 --- a/sys/sys/firmware.h +++ b/sys/sys/firmware.h @@ -1,66 +1,71 @@ /*- * SPDX-License-Identifier: BSD-2-Clause-FreeBSD * * Copyright (c) 2005, Sam Leffler * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright * notice unmodified, this list of conditions, and the following * disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * * $FreeBSD$ */ #ifndef _SYS_FIRMWARE_H_ #define _SYS_FIRMWARE_H_ /* * Loadable firmware support. * * The firmware abstraction provides an interface for loading firmware * images into the kernel and making them available to clients. * * Firmware images are usually embedded in kernel loadable modules that can * be loaded on-demand or pre-loaded as desired. Modules may contain * one or more firmware images that are stored as opaque data arrays * and registered with a unique string name. Clients request * firmware by name, and are returned a struct firmware * below on success. * The kernel keeps track of references to firmware images to allow/prevent * module/data unload. * * When multiple images are stored in one module, the first image is * treated as the master with the other images holding references * to it. This means that to unload the module each dependent/subimage * must first have its references removed. * In order for automatic loading to work, the master image must have * the same name as the module it is embedded into. */ 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 */ }; const struct firmware *firmware_register(const char *, const void *, size_t, unsigned int, const struct firmware *); int firmware_unregister(const char *); + +#define FIRMWARE_GET_NOWARN 0x0001 /* Do not warn if firmware not found. */ +const struct firmware *firmware_get_flags(const char *, uint32_t flags); const struct firmware *firmware_get(const char *); + #define FIRMWARE_UNLOAD 0x0001 /* unload if unreferenced */ void firmware_put(const struct firmware *, int); + #endif /* _SYS_FIRMWARE_H_ */