path: root/sys/sys/firmware.h
diff options
authorLuigi Rizzo <luigi@FreeBSD.org>2007-02-15 17:21:31 +0000
committerLuigi Rizzo <luigi@FreeBSD.org>2007-02-15 17:21:31 +0000
commit33d5497079b6a4e3bf95a36795dbb4153ec702bb (patch)
tree8756dca03e08a58907b842fa664348bb2f5be1b9 /sys/sys/firmware.h
parent1a5f5dc0973e9307be0e0f0d33a5b727ba450a06 (diff)
Cleanup and document the implementation of firmware(9) based on
a version that i posted earlier on the -current mailing list, and subsequent feedback received. The core of the change is just in sys/firmware.h and kern/subr_firmware.c, while other files are just adaptation of the clients to the ABI change (const-ification of some parameters and hiding of internal info, so this is fully compatible at the binary level). In detail: - reduce the amount of information exported to clients in struct firmware, and constify the pointer; - internally, document and simplify the implementation of the various functions, and make sure error conditions are dealt with properly. The diffs are large, but the code is really straightforward now (i hope). Note also that there is a subtle issue with the implementation of firmware_register(): currently, as in the previous version, we just store a reference to the 'imagename' argument, but we should rather copy it because there is no guarantee that this is a static string. I realised this while testing this code, but i prefer to fix it in a later commit -- there is no regression with respect to the past. Note, too, that the version in RELENG_6 has various bugs including missing locks around the module release calls, mishandling of modules loaded by /boot/loader, and so on, so an MFC is absolutely necessary there. I was just postponing it until this cleanup to avoid doing things twice. MFC after: 1 week
Notes: svn path=/head/; revision=166756
Diffstat (limited to 'sys/sys/firmware.h')
1 files changed, 15 insertions, 16 deletions
diff --git a/sys/sys/firmware.h b/sys/sys/firmware.h
index c1994504404c..ce02831a589f 100644
--- a/sys/sys/firmware.h
+++ b/sys/sys/firmware.h
@@ -30,36 +30,35 @@
* Loadable firmware support.
- * Firmware images are embedded in kernel loadable modules that can
+ * 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. Consumers request
- * firmware by name with held references counted to use in disallowing
+ * 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 one image is
+ * 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 */
- int refcnt; /* held references */
- struct firmware *parent; /* not null if a subimage */
- linker_file_t file; /* loadable module */
- int flags; /* FIRMWAREFLAG_ flags */
-/* "flags" field definitions */
-#define FIRMWAREFLAG_KEEPKLDREF 0x0001 /* don't release KLD reference */
-struct firmware *firmware_register(const char *, const void *, size_t,
- unsigned int, struct firmware *);
-int firmware_unregister(const char *);
-struct firmware *firmware_get(const char *);
+const struct firmware *firmware_register(const char *,
+ const void *, size_t, unsigned int, const struct firmware *);
+int firmware_unregister(const char *);
+const struct firmware *firmware_get(const char *);
#define FIRMWARE_UNLOAD 0x0001 /* unload if unreferenced */
-void firmware_put(struct firmware *, int);
+void firmware_put(const struct firmware *, int);
#endif /* _SYS_FIRMWARE_H_ */