home | help
UNTITLED()			      LOCAL			      UNTITLED()

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 regis-
     ter contained firmware images.  The arguments  to	firmware_register()  in-
     clude  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  op-
     tional  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 im-
     age description and increases the reference count for this image.

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

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>.

FreeBSD 6.1			 January 6, 2006		     FIRMWARE(9)

home | help