Provided by: freebsd-manpages_6.2-1_all bug

NAME
     firmware_register, firmware_unregister, firmware_get, firmware_put -
     firmware image loading and management


SYNOPSIS
     #include <sys/param.h>
     #include <sys/systm.h>
     #include <sys/linker.h>
     #include <sys/firmware.h>

     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 */
     };

     struct firmware *
     firmware_register(const char *imagename, const void *data,
             size_t datasize, unsigned int version, struct firmware *parent);

     int
     firmware_unregister(const char *imagename);

     struct firmware *
     firmware_get(const char *imagename);

     void
     firmware_put(struct firmware *fp, int flags);


DESCRIPTION
     The firmware abstraction provides a convenient interface for loading
     firmware images into the kernel.  Specially crafted kernel modules are
     used to hold the firmware images.

     The function firmware_register() is used on load of such modules to
     register contained firmware images.  The arguments to firmware_register()
     include a name that identifies the image for later requests to the
     firmware system, a pointer to the actual image, the size of the image and
     an optional parent image.  The parent image is used to keep track of
     references to a given module so that it can be unloaded on last
     reference.

     The function firmware_unregister() removes the firmware image identified
     by the name from the system if there are no pending references or returns
     an error otherwise.

     The function firmware_get() returns the requested firmware image.  If the
     image is not yet registered with the system firmware_get() tries to load
     a module with the corresponding name.  This involves the linker subsystem
     and disk access which is why firmware_get() must not be called with any
     locks (except for Giant).  On success firmware_get() returns a pointer to
     the image description and increases the reference count for this image.

     The function firmware_put() is used to drop the reference to a firmware
     image.  The flags argument may be set to FIRMWARE_UNLOAD to indicate that
     the caller wishes to unload the corresponding module if the image becomes
     unreferenced.


SEE ALSO
     module(9)

     /usr/share/examples/kld


HISTORY
     The firmware system was introduced in FreeBSD 6.1.


AUTHORS
     This manual page was written by Max Laier 〈mlaier@FreeBSD.org〉.