1/*-
2 * SPDX-License-Identifier: BSD-2-Clause-FreeBSD
3 *
4 * Copyright (c) 2005-2008, Sam Leffler <sam@errno.com>
5 * All rights reserved.
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
9 * are met:
10 * 1. Redistributions of source code must retain the above copyright
11 *    notice unmodified, this list of conditions, and the following
12 *    disclaimer.
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.
16 *
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.
27 */
28
29#include <sys/cdefs.h>
30__FBSDID("$FreeBSD$");
31
32#include <sys/param.h>
33#include <sys/kernel.h>
34#include <sys/malloc.h>
35#include <sys/queue.h>
36#include <sys/taskqueue.h>
37#include <sys/systm.h>
38#include <sys/lock.h>
39#include <sys/mutex.h>
40#include <sys/errno.h>
41#include <sys/linker.h>
42#include <sys/firmware.h>
43#include <sys/priv.h>
44#include <sys/proc.h>
45#include <sys/module.h>
46#include <sys/eventhandler.h>
47
48#include <sys/filedesc.h>
49#include <sys/vnode.h>
50
51/*
52 * Loadable firmware support. See sys/sys/firmware.h and firmware(9)
53 * form more details on the subsystem.
54 *
55 * 'struct firmware' is the user-visible part of the firmware table.
56 * Additional internal information is stored in a 'struct priv_fw',
57 * which embeds the public firmware structure.
58 */
59
60/*
61 * fw.name != NULL when an image is registered; file != NULL for
62 * autoloaded images whose handling has not been completed.
63 *
64 * The state of a slot evolves as follows:
65 *	firmware_register	-->  fw.name = image_name
66 *	(autoloaded image)	-->  file = module reference
67 *	firmware_unregister	-->  fw.name = NULL
68 *	(unloadentry complete)	-->  file = NULL
69 *
70 * In order for the above to work, the 'file' field must remain
71 * unchanged in firmware_unregister().
72 *
73 * Images residing in the same module are linked to each other
74 * through the 'parent' argument of firmware_register().
75 * One image (typically, one with the same name as the module to let
76 * the autoloading mechanism work) is considered the parent image for
77 * all other images in the same module. Children affect the refcount
78 * on the parent image preventing improper unloading of the image itself.
79 */
80
81struct priv_fw {
82	int		refcnt;		/* reference count */
83	LIST_ENTRY(priv_fw) link;	/* table linkage */
84
85	/*
86	 * parent entry, see above. Set on firmware_register(),
87	 * cleared on firmware_unregister().
88	 */
89	struct priv_fw	*parent;
90
91	int 		flags;	/* record FIRMWARE_UNLOAD requests */
92#define FW_UNLOAD	0x100
93
94	/*
95	 * 'file' is private info managed by the autoload/unload code.
96	 * Set at the end of firmware_get(), cleared only in the
97	 * firmware_unload_task, so the latter can depend on its value even
98	 * while the lock is not held.
99	 */
100	linker_file_t   file;	/* module file, if autoloaded */
101
102	/*
103	 * 'fw' is the externally visible image information.
104	 * We do not make it the first field in priv_fw, to avoid the
105	 * temptation of casting pointers to each other.
106	 * Use PRIV_FW(fw) to get a pointer to the cointainer of fw.
107	 * Beware, PRIV_FW does not work for a NULL pointer.
108	 */
109	struct firmware	fw;	/* externally visible information */
110};
111
112/*
113 * PRIV_FW returns the pointer to the container of struct firmware *x.
114 * Cast to intptr_t to override the 'const' attribute of x
115 */
116#define PRIV_FW(x)	((struct priv_fw *)		\
117	((intptr_t)(x) - offsetof(struct priv_fw, fw)) )
118
119/*
120 * Global firmware image registry.
121 */
122static LIST_HEAD(, priv_fw) firmware_table;
123
124/*
125 * Firmware module operations are handled in a separate task as they
126 * might sleep and they require directory context to do i/o.
127 */
128static struct taskqueue *firmware_tq;
129static struct task firmware_unload_task;
130
131/*
132 * This mutex protects accesses to the firmware table.
133 */
134static struct mtx firmware_mtx;
135MTX_SYSINIT(firmware, &firmware_mtx, "firmware table", MTX_DEF);
136
137static MALLOC_DEFINE(M_FIRMWARE, "firmware", "device firmware images");
138
139/*
140 * Helper function to lookup a name.
141 * As a side effect, it sets the pointer to a free slot, if any.
142 * This way we can concentrate most of the registry scanning in
143 * this function, which makes it easier to replace the registry
144 * with some other data structure.
145 */
146static struct priv_fw *
147lookup(const char *name)
148{
149	struct priv_fw *fp;
150
151	mtx_assert(&firmware_mtx, MA_OWNED);
152
153	LIST_FOREACH(fp, &firmware_table, link) {
154		if (fp->fw.name != NULL && strcasecmp(name, fp->fw.name) == 0)
155			break;
156	}
157	return (fp);
158}
159
160/*
161 * Register a firmware image with the specified name.  The
162 * image name must not already be registered.  If this is a
163 * subimage then parent refers to a previously registered
164 * image that this should be associated with.
165 */
166const struct firmware *
167firmware_register(const char *imagename, const void *data, size_t datasize,
168    unsigned int version, const struct firmware *parent)
169{
170	struct priv_fw *frp;
171	char *name;
172
173	mtx_lock(&firmware_mtx);
174	frp = lookup(imagename);
175	if (frp != NULL) {
176		mtx_unlock(&firmware_mtx);
177		printf("%s: image %s already registered!\n",
178		    __func__, imagename);
179		return (NULL);
180	}
181	mtx_unlock(&firmware_mtx);
182
183	frp = malloc(sizeof(*frp), M_FIRMWARE, M_WAITOK | M_ZERO);
184	name = strdup(imagename, M_FIRMWARE);
185
186	mtx_lock(&firmware_mtx);
187	if (lookup(imagename) != NULL) {
188		/* We lost a race. */
189		mtx_unlock(&firmware_mtx);
190		free(name, M_FIRMWARE);
191		free(frp, M_FIRMWARE);
192		return (NULL);
193	}
194	frp->fw.name = name;
195	frp->fw.data = data;
196	frp->fw.datasize = datasize;
197	frp->fw.version = version;
198	if (parent != NULL)
199		frp->parent = PRIV_FW(parent);
200	LIST_INSERT_HEAD(&firmware_table, frp, link);
201	mtx_unlock(&firmware_mtx);
202	if (bootverbose)
203		printf("firmware: '%s' version %u: %zu bytes loaded at %p\n",
204		    imagename, version, datasize, data);
205	return (&frp->fw);
206}
207
208/*
209 * Unregister/remove a firmware image.  If there are outstanding
210 * references an error is returned and the image is not removed
211 * from the registry.
212 */
213int
214firmware_unregister(const char *imagename)
215{
216	struct priv_fw *fp;
217	int err;
218
219	mtx_lock(&firmware_mtx);
220	fp = lookup(imagename);
221	if (fp == NULL) {
222		/*
223		 * It is ok for the lookup to fail; this can happen
224		 * when a module is unloaded on last reference and the
225		 * module unload handler unregister's each of its
226		 * firmware images.
227		 */
228		err = 0;
229	} else if (fp->refcnt != 0) {	/* cannot unregister */
230		err = EBUSY;
231	} else {
232		LIST_REMOVE(fp, link);
233		free(__DECONST(char *, fp->fw.name), M_FIRMWARE);
234		free(fp, M_FIRMWARE);
235		err = 0;
236	}
237	mtx_unlock(&firmware_mtx);
238	return (err);
239}
240
241static void
242loadimage(void *arg, int npending)
243{
244	char *imagename = arg;
245	struct priv_fw *fp;
246	linker_file_t result;
247	int error;
248
249	error = linker_reference_module(imagename, NULL, &result);
250	if (error != 0) {
251		printf("%s: could not load firmware image, error %d\n",
252		    imagename, error);
253		mtx_lock(&firmware_mtx);
254		goto done;
255	}
256
257	mtx_lock(&firmware_mtx);
258	fp = lookup(imagename);
259	if (fp == NULL || fp->file != NULL) {
260		mtx_unlock(&firmware_mtx);
261		if (fp == NULL)
262			printf("%s: firmware image loaded, "
263			    "but did not register\n", imagename);
264		(void) linker_release_module(imagename, NULL, NULL);
265		mtx_lock(&firmware_mtx);
266		goto done;
267	}
268	fp->file = result;	/* record the module identity */
269done:
270	wakeup_one(imagename);
271	mtx_unlock(&firmware_mtx);
272}
273
274/*
275 * Lookup and potentially load the specified firmware image.
276 * If the firmware is not found in the registry, try to load a kernel
277 * module named as the image name.
278 * If the firmware is located, a reference is returned. The caller must
279 * release this reference for the image to be eligible for removal/unload.
280 */
281const struct firmware *
282firmware_get(const char *imagename)
283{
284	struct task fwload_task;
285	struct thread *td;
286	struct priv_fw *fp;
287
288	mtx_lock(&firmware_mtx);
289	fp = lookup(imagename);
290	if (fp != NULL)
291		goto found;
292	/*
293	 * Image not present, try to load the module holding it.
294	 */
295	td = curthread;
296	if (priv_check(td, PRIV_FIRMWARE_LOAD) != 0 ||
297	    securelevel_gt(td->td_ucred, 0) != 0) {
298		mtx_unlock(&firmware_mtx);
299		printf("%s: insufficient privileges to "
300		    "load firmware image %s\n", __func__, imagename);
301		return NULL;
302	}
303	/*
304	 * Defer load to a thread with known context.  linker_reference_module
305	 * may do filesystem i/o which requires root & current dirs, etc.
306	 * Also we must not hold any mtx's over this call which is problematic.
307	 */
308	if (!cold) {
309		TASK_INIT(&fwload_task, 0, loadimage, __DECONST(void *,
310		    imagename));
311		taskqueue_enqueue(firmware_tq, &fwload_task);
312		msleep(__DECONST(void *, imagename), &firmware_mtx, 0,
313		    "fwload", 0);
314	}
315	/*
316	 * After attempting to load the module, see if the image is registered.
317	 */
318	fp = lookup(imagename);
319	if (fp == NULL) {
320		mtx_unlock(&firmware_mtx);
321		return NULL;
322	}
323found:				/* common exit point on success */
324	if (fp->refcnt == 0 && fp->parent != NULL)
325		fp->parent->refcnt++;
326	fp->refcnt++;
327	mtx_unlock(&firmware_mtx);
328	return &fp->fw;
329}
330
331/*
332 * Release a reference to a firmware image returned by firmware_get.
333 * The caller may specify, with the FIRMWARE_UNLOAD flag, its desire
334 * to release the resource, but the flag is only advisory.
335 *
336 * If this is the last reference to the firmware image, and this is an
337 * autoloaded module, wake up the firmware_unload_task to figure out
338 * what to do with the associated module.
339 */
340void
341firmware_put(const struct firmware *p, int flags)
342{
343	struct priv_fw *fp = PRIV_FW(p);
344
345	mtx_lock(&firmware_mtx);
346	fp->refcnt--;
347	if (fp->refcnt == 0) {
348		if (fp->parent != NULL)
349			fp->parent->refcnt--;
350		if (flags & FIRMWARE_UNLOAD)
351			fp->flags |= FW_UNLOAD;
352		if (fp->file)
353			taskqueue_enqueue(firmware_tq, &firmware_unload_task);
354	}
355	mtx_unlock(&firmware_mtx);
356}
357
358/*
359 * Setup directory state for the firmware_tq thread so we can do i/o.
360 */
361static void
362set_rootvnode(void *arg, int npending)
363{
364
365	pwd_ensure_dirs();
366	free(arg, M_TEMP);
367}
368
369/*
370 * Event handler called on mounting of /; bounce a task
371 * into the task queue thread to setup it's directories.
372 */
373static void
374firmware_mountroot(void *arg)
375{
376	struct task *setroot_task;
377
378	setroot_task = malloc(sizeof(struct task), M_TEMP, M_NOWAIT);
379	if (setroot_task != NULL) {
380		TASK_INIT(setroot_task, 0, set_rootvnode, setroot_task);
381		taskqueue_enqueue(firmware_tq, setroot_task);
382	} else
383		printf("%s: no memory for task!\n", __func__);
384}
385EVENTHANDLER_DEFINE(mountroot, firmware_mountroot, NULL, 0);
386
387/*
388 * The body of the task in charge of unloading autoloaded modules
389 * that are not needed anymore.
390 * Images can be cross-linked so we may need to make multiple passes,
391 * but the time we spend in the loop is bounded because we clear entries
392 * as we touch them.
393 */
394static void
395unloadentry(void *unused1, int unused2)
396{
397	struct priv_fw *fp;
398	int err;
399
400	mtx_lock(&firmware_mtx);
401restart:
402	LIST_FOREACH(fp, &firmware_table, link) {
403		if (fp->file == NULL || fp->refcnt != 0 ||
404		    (fp->flags & FW_UNLOAD) == 0)
405			continue;
406
407		/*
408		 * Found an entry. Now:
409		 * 1. make sure we scan the table again
410		 * 2. clear FW_UNLOAD so we don't try this entry again.
411		 * 3. release the lock while trying to unload the module.
412		 */
413		fp->flags &= ~FW_UNLOAD;	/* do not try again */
414
415		/*
416		 * We rely on the module to call firmware_unregister()
417		 * on unload to actually free the entry.
418		 */
419		mtx_unlock(&firmware_mtx);
420		err = linker_release_module(NULL, NULL, fp->file);
421		mtx_lock(&firmware_mtx);
422
423		/*
424		 * When we dropped the lock, another thread could have
425		 * removed an element, so we must restart the scan.
426		 */
427		goto restart;
428	}
429	mtx_unlock(&firmware_mtx);
430}
431
432/*
433 * Module glue.
434 */
435static int
436firmware_modevent(module_t mod, int type, void *unused)
437{
438	struct priv_fw *fp;
439	int err;
440
441	err = 0;
442	switch (type) {
443	case MOD_LOAD:
444		TASK_INIT(&firmware_unload_task, 0, unloadentry, NULL);
445		firmware_tq = taskqueue_create("taskqueue_firmware", M_WAITOK,
446		    taskqueue_thread_enqueue, &firmware_tq);
447		/* NB: use our own loop routine that sets up context */
448		(void) taskqueue_start_threads(&firmware_tq, 1, PWAIT,
449		    "firmware taskq");
450		if (rootvnode != NULL) {
451			/*
452			 * Root is already mounted so we won't get an event;
453			 * simulate one here.
454			 */
455			firmware_mountroot(NULL);
456		}
457		break;
458
459	case MOD_UNLOAD:
460		/* request all autoloaded modules to be released */
461		mtx_lock(&firmware_mtx);
462		LIST_FOREACH(fp, &firmware_table, link)
463			fp->flags |= FW_UNLOAD;
464		mtx_unlock(&firmware_mtx);
465		taskqueue_enqueue(firmware_tq, &firmware_unload_task);
466		taskqueue_drain(firmware_tq, &firmware_unload_task);
467
468		LIST_FOREACH(fp, &firmware_table, link) {
469			if (fp->fw.name != NULL) {
470				printf("%s: image %s still active, %d refs\n",
471				    __func__, fp->fw.name, fp->refcnt);
472				err = EINVAL;
473			}
474		}
475		if (err == 0)
476			taskqueue_free(firmware_tq);
477		break;
478
479	default:
480		err = EOPNOTSUPP;
481		break;
482	}
483	return (err);
484}
485
486static moduledata_t firmware_mod = {
487	"firmware",
488	firmware_modevent,
489	NULL
490};
491DECLARE_MODULE(firmware, firmware_mod, SI_SUB_DRIVERS, SI_ORDER_FIRST);
492MODULE_VERSION(firmware, 1);
493