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