1.\" Copyright (c) 2006 Max Laier <mlaier@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 14.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 15.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 16.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 17.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 18.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 19.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 20.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 21.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 22.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 23.\" 24.\" $FreeBSD$ 25.\" 26.Dd January 6, 2006 27.Os 28.Dt FIRMWARE 9 29.Sh NAME 30.Nm firmware_register , 31.Nm firmware_unregister , 32.Nm firmware_get , 33.Nm firmware_put 34.Nd firmware image loading and management 35.Sh SYNOPSIS 36.In sys/param.h 37.In sys/systm.h 38.In sys/linker.h 39.In sys/firmware.h 40.Bd -literal 41struct firmware { 42 const char *name; /* system-wide name */ 43 const void *data; /* location of image */ 44 size_t datasize; /* size of image in bytes */ 45 unsigned int version; /* version of the image */ 46 int refcnt; /* held references */ 47 struct firmware *parent; /* not null if a subimage */ 48 linker_file_t file; /* loadable module */ 49}; 50.Ed 51.Ft struct firmware * 52.Fo firmware_register 53.Fa "const char *imagename" 54.Fa "const void *data" 55.Fa "size_t datasize" 56.Fa "unsigned int version" 57.Fa "struct firmware *parent" 58.Fc 59.Ft int 60.Fn firmware_unregister "const char *imagename" 61.Ft struct firmware * 62.Fn firmware_get "const char *imagename" 63.Ft void 64.Fn firmware_put "struct firmware *fp" "int flags" 65.Sh DESCRIPTION 66The firmware abstraction provides a convenient interface for loading firmware 67images into the kernel. 68Specially crafted kernel modules are used to hold the firmware images. 69.Pp 70The function 71.Fn firmware_register 72is used on load of such modules to register contained firmware images. 73The arguments to 74.Fn firmware_register 75include a name that identifies the image for later requests to the firmware 76system, a pointer to the actual image, the size of the image and an optional 77parent image. 78The parent image is used to keep track of references to a given module so that 79it can be unloaded on last reference. 80.Pp 81The function 82.Fn firmware_unregister 83removes the firmware image identified by the name from the system if there 84are no pending references or returns an error otherwise. 85.Pp 86The function 87.Fn firmware_get 88returns the requested firmware image. 89If the image is not yet registered with the system 90.Fn firmware_get 91tries to load a module with the corresponding name. 92This involves the linker subsystem and disk access which is why 93.Fn firmware_get 94must not be called with any locks (except for Giant). 95On success 96.Fn firmware_get 97returns a pointer to the image description and increases the reference count 98for this image. 99.Pp 100The function 101.Fn firmware_put 102is used to drop the reference to a firmware image. 103The flags argument may be set to 104.Dv FIRMWARE_UNLOAD 105to indicate that the caller wishes to unload the corresponding module if the 106image becomes unreferenced. 107.Sh SEE ALSO 108.Xr module 9 109.Pp 110.Pa /usr/share/examples/kld 111.Sh HISTORY 112The firmware system was introduced in 113.Fx 6.1 . 114.Sh AUTHORS 115This manual page was written by 116.An Max Laier Aq mlaier@FreeBSD.org . 117