1.\" $NetBSD: firmload.9,v 1.10 2018/03/16 02:35:56 sevan 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 March 16, 2018 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 by the sysctl variable 65.Dv hw.firmware.path . 66.Sh FUNCTIONS 67The following functions are provided by the 68.Nm 69API: 70.Bl -tag -width indent 71.It Fn "firmware_open" "drvname" "imgname" "fhp" 72.Pp 73Open the firmware image 74.Fa imgname 75for the driver 76.Fa drvname . 77The path to the firmware image file is constructed by appending the string 78.Dq "/drvname/imgname" 79to each configured path prefix until opening the firmware image file succeeds. 80Upon success, 81.Fn firmware_open 82returns 0 and stores a firmware image handle in the location pointed to by 83.Fa fhp . 84Otherwise, an error code is returned to indicate the reason for failure. 85.It Fn "firmware_close" "fh" 86.Pp 87Close the firmware image file associated with the firmware handle 88.Fa fh . 89Returns 0 upon success or an error code to indicate the reason for failure. 90.It Fn "firmware_get_size" "fh" 91.Pp 92Returns the size of the image file associated with the firmware handle 93.Fa fh . 94.It Fn "firmware_read" "fh" "offset" "buf" "size" 95.Pp 96Reads from the image file associated with the firmware handle 97.Fa fh 98beginning at offset 99.Fa offset 100for length 101.Fa size . 102The firmware image data is placed into the buffer specified by 103.Fa buf . 104Returns 0 upon success or an error code to indicate the reason for failure. 105.It Fn "firmware_malloc" "size" 106.Pp 107Allocates a region of wired kernel memory of size 108.Fa size . 109Note: 110.Fn firmware_malloc 111may block. 112.It Fn "firmware_free" "buf" "size" 113.Pp 114Frees a region of memory previously allocated by 115.Fn firmware_malloc . 116.El 117.Sh FILES 118Default search path for firmware 119.Bl -tag -width /libdata/firmware -compact 120.It Pa /libdata/firmware 121.It Pa /usr/libdata/firmware 122.It Pa /usr/pkg/libdata/firmware 123.It Pa /usr/pkg/libdata 124.El 125.Sh SEE ALSO 126.Xr autoconf 9 , 127.Xr malloc 9 , 128.Xr vnsubr 9 129.Sh HISTORY 130The 131.Nm 132framework first appeared in 133.Nx 4.0 . 134.Sh AUTHORS 135.An Jason Thorpe Aq Mt thorpej@NetBSD.org 136