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 67.Nm firmware 68abstraction provides a convenient interface for loading firmware 69images into the kernel. 70Specially crafted kernel modules are used to hold the firmware images. 71.Pp 72The function 73.Fn firmware_register 74is used on load of such modules to register contained firmware images. 75The arguments to 76.Fn firmware_register 77include a name that identifies the image for later requests to the 78.Nm firmware 79system, a pointer to the actual image, the size of the image and an optional 80parent image. 81The parent image is used to keep track of references to a given module so that 82it can be unloaded on last reference. 83.Pp 84The function 85.Fn firmware_unregister 86removes the firmware image identified by the name from the system if there 87are no pending references or returns an error otherwise. 88.Pp 89The function 90.Fn firmware_get 91returns the requested firmware image. 92If the image is not yet registered with the system, 93.Fn firmware_get 94tries to load a module with the corresponding name. 95This involves the linker subsystem and disk access which is why 96.Fn firmware_get 97must not be called with any locks (except for 98.Va Giant ) . 99On success, 100.Fn firmware_get 101returns a pointer to the image description and increases the reference count 102for this image. 103.Pp 104The function 105.Fn firmware_put 106is used to drop the reference to a firmware image. 107The 108.Fa flags 109argument may be set to 110.Dv FIRMWARE_UNLOAD 111to indicate that the caller wishes to unload the corresponding module if the 112image becomes unreferenced. 113.Sh SEE ALSO 114.Xr module 9 115.Pp 116.Pa /usr/share/examples/kld 117.Sh HISTORY 118The 119.Nm firmware 120system was introduced in 121.Fx 6.1 . 122.Sh AUTHORS 123This manual page was written by 124.An Max Laier Aq mlaier@FreeBSD.org . 125