1.\" $NetBSD: firmload.9,v 1.4 2008/04/30 13:10:58 martin Exp $ 2.\" 3.\" Copyright (c) 2006 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jason R. Thorpe. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd January 17, 2006 31.Dt FIRMLOAD 9 32.Os 33.Sh NAME 34.Nm firmload 35.Nd Firmware loader API for device drivers 36.Sh SYNOPSIS 37.In dev/firmload.h 38.\" 39.Ft int 40.Fn "firmware_open" "const char *drvname" "const char *imgname" \ 41"firmware_handle_t *fhp" 42.\" 43.Ft int 44.Fn "firmware_close" "firmware_handle_t fh" 45.\" 46.Ft off_t 47.Fn "firmware_get_size" "firmware_handle_t fh" 48.\" 49.Ft int 50.Fn "firmware_read" "firmware_handle_t fh" "off_t offset" "void *buf" \ 51"size_t size" 52.\" 53.Ft void * 54.Fn "firmware_malloc" "size_t size" 55.\" 56.Ft void 57.Fn "firmware_free" "void *buf" "size_t size" 58.Sh DESCRIPTION 59.Nm 60provides a simple and convenient API for device drivers to load firmware 61images from files residing in the file system that are necessary for the 62devices that they control. 63Firmware images reside in sub-directories, one for each driver, of a series 64of colon-separated path prefixes specified the sysctl variable 65.Dv hw.firmware.path . 66.Pp 67The following functions are provided by the 68.Nm 69API: 70.Bl -tag -width indent 71.It int Fn "firmware_open" "const char *drvname" "const char *imgname" \ 72"firmware_handle_t *fhp" 73.Pp 74Open then firmware image 75.Fa imgname 76for the driver 77.Fa drvname . 78The path to the firmware image file is constructed by appending the string 79.Dq "/drvname/imgname" 80to each configured path prefix until opening the firmware image file succeeds. 81Upon success, 82.Fn firmware_open 83returns 0 and stores a firmware image handle in the location pointed to by 84.Fa fhp . 85Otherwise, an error code is returned to indicate the reason for failure. 86.It int Fn "firmware_close" "firmware_handle_t fh" 87.Pp 88Close the firmware image file associated with the firmware handle 89.Fa fh . 90Returns 0 upon success or an error code to indicate the reason for failure. 91.It off_t Fn "firmware_get_size" "firmware_handle_t fh" 92.Pp 93Returns the size of the image file associated with the firmware handle 94.Fa fh . 95.It int Fn "firmware_read" "firmware_handle_t fh" "off_t offset" "void *buf" \ 96"size_t size" 97.Pp 98Reads from the image file associated with the firmware handle 99.Fa fh 100beginning at offset 101.Fa offset 102for length 103.Fa size . 104The firmware image data is placed into the buffer specified by 105.Fa buf . 106Returns 0 upon success or an error code to indicate the reason for failure. 107.It void * Ns Fn "firmware_malloc" "size_t size" 108.Pp 109Allocates a region of wired kernel memory of size 110.Fa size . 111Note: 112.Fn firmware_malloc 113may block. 114.It void Fn "firmware_free" "void *buf" "size_t size" 115.Pp 116Frees a region of memory previously allocated by 117.Fn firmware_malloc . 118.El 119.Sh SEE ALSO 120.Xr autoconf 9 , 121.Xr malloc 9 , 122.Xr vnsubr 9 123.Sh HISTORY 124The 125.Nm 126framework first appeared in 127.Nx 4.0 . 128.Sh AUTHORS 129.An Jason Thorpe Aq thorpej@NetBSD.org 130