firmware(9)

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 im

age identified
by the name from the system if there are no pending refer

ences 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@FreeB

SD.org>.

BSD January 6, 2006

BSD