1.\" $NetBSD: firmload.9,v 1.8 2014/03/18 18:20:40 riastradh Exp $ 2.\" 3.\" Copyright 2016 Hans Rosenfeld <rosenfeld@grumpf.hope-2000.org> 4.\" 5.\" Copyright (c) 2006 The NetBSD Foundation, Inc. 6.\" All rights reserved. 7.\" 8.\" This code is derived from software contributed to The NetBSD Foundation 9.\" by Jason R. Thorpe. 10.\" 11.\" Redistribution and use in source and binary forms, with or without 12.\" modification, are permitted provided that the following conditions 13.\" are met: 14.\" 1. Redistributions of source code must retain the above copyright 15.\" notice, this list of conditions and the following disclaimer. 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in the 18.\" documentation and/or other materials provided with the distribution. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 21.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 22.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 23.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 24.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 25.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 26.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 27.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 28.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 29.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 30.\" POSSIBILITY OF SUCH DAMAGE. 31.\" 32.Dd January 22, 2016 33.Dt FIRMLOAD 9F 34.Os 35.Sh NAME 36.Nm firmload 37.Nd Firmware loader API for device drivers 38.Sh SYNOPSIS 39.In sys/firmload.h 40.Ft int 41.Fo "firmware_open" 42.Fa "const char *drvname" 43.Fa "const char *imgname" 44.Fa "firmware_handle_t *fhp" 45.Fc 46.Ft int 47.Fo "firmware_close" 48.Fa "firmware_handle_t fh" 49.Fc 50.Ft off_t 51.Fo "firmware_get_size" 52.Fa "firmware_handle_t fh" 53.Fc 54.Ft int 55.Fo "firmware_read" 56.Fa "firmware_handle_t fh" 57.Fa "off_t offset" 58.Fa "void *buf" 59.Fa "size_t size" 60.Fc 61.Sh PARAMETERS 62.Bl -tag -width Va 63.It Fa drvname 64The name of the driver using 65.Nm . 66This is used as the subdirectory holding the firmware images. 67.It Fa imgname 68The file name of a firmware image. 69.It Fa fhp 70The pointer used for returing a firmware handle. 71.It Fa fh 72The firmware handle. 73.It Fa offset 74The offset in the firmware image to start reading from. 75.It Fa buf 76Pointer to a buffer to hold the firmware data. 77.It Fa size 78Size of the buffer to hold the firmware data. 79.El 80.Sh DESCRIPTION 81.Nm 82provides a simple and convenient API for device drivers to load firmware 83images from files residing in the file system that are necessary for the 84devices that they control. 85It is primarily intended for devices without non-volatile firmware 86memory, which usually require the driver to load a firmware image at 87attach time. 88Firmware images reside in sub-directories, one for each driver, in the 89namespace "firmware" in the system default module search path as 90described in 91.Xr system 4 . 92.sp 93The following functions are provided by the 94.Nm 95API: 96.Bl -tag -width indent 97.It Fn "firmware_open" 98Open the firmware image 99.Fa imgname 100for the driver 101.Fa drvname . 102The path to the firmware image file is constructed by appending the string 103.Dq "firmware/drvname/imgname" 104to each system module path prefix until opening the firmware image 105file succeeds. 106.It Fn "firmware_close" 107Close the firmware image file associated with the firmware handle 108.Fa fh . 109.It Fn "firmware_get_size" 110Returns the size of the image file associated with the firmware handle 111.Fa fh . 112.It Fn "firmware_read" 113Reads from the image file associated with the firmware handle 114.Fa fh 115beginning at offset 116.Fa offset 117for length 118.Fa size . 119The firmware image data is placed into the buffer specified by 120.Fa buf . 121.Fn "firmware_read" 122will either read as much data as requested or fail, there are no short 123reads. 124.El 125.Sh CONTEXT 126These functions can be called from user and kernel context. 127.Sh RETURN VALUES 128Upon successful completion, the 129.Fn firmware_open 130function returns zero and stores a firmware handle in 131.Fa fhp . 132Otherwise a non-zero error code is returned. 133.sp 134The function 135.Fn firmware_read 136will return zero on success and 137.Fa buf 138will be filled with 139.Fa size 140bytes of data. 141On failure -1 is returned. 142.sp 143The function 144.Fn firmware_get_size 145returns the size of a firmware image. 146.sp 147.Fn firmware_close 148will always return zero. 149.Sh INTERFACE STABILITY 150.Sy Committed 151.Sh SEE ALSO 152.Xr system 4 153