usr/src/man/man9f/firmload.9f

   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
  64 The name of the driver using
  65 .Nm .
  66 This is used as the subdirectory holding the firmware images.
  67 .It Fa imgname
  68 The file name of a firmware image.
  69 .It Fa fhp
  70 The pointer used for returing a firmware handle.
  71 .It Fa fh
  72 The firmware handle.
  73 .It Fa offset
  74 The offset in the firmware image to start reading from.
  75 .It Fa buf
  76 Pointer to a buffer to hold the firmware data.
  77 .It Fa size
  78 Size of the buffer to hold the firmware data.
  79 .El
  80 .Sh DESCRIPTION
  81 .Nm
  82 provides a simple and convenient API for device drivers to load firmware
  83 images from files residing in the file system that are necessary for the
  84 devices that they control.
  85 It is primarily intended for devices without non-volatile firmware
  86 memory, which usually require the driver to load a firmware image at
  87 attach time.
  88 Firmware images reside in sub-directories, one for each driver, in the
  89 namespace "firmware" in the system default module search path as
  90 described in
  91 .Xr system 4 .
  92 .sp
  93 The following functions are provided by the
  94 .Nm
  95 API:
  96 .Bl -tag -width indent
  97 .It Fn "firmware_open"
  98 Open the firmware image
  99 .Fa imgname
 100 for the driver
 101 .Fa drvname .
 102 The path to the firmware image file is constructed by appending the string
 103 .Dq "firmware/drvname/imgname"
 104 to each system module path prefix until opening the firmware image
 105 file succeeds.
 106 .It Fn "firmware_close"
 107 Close the firmware image file associated with the firmware handle
 108 .Fa fh .
 109 .It Fn "firmware_get_size"
 110 Returns the size of the image file associated with the firmware handle
 111 .Fa fh .
 112 .It Fn "firmware_read"
 113 Reads from the image file associated with the firmware handle
 114 .Fa fh
 115 beginning at offset
 116 .Fa offset
 117 for length
 118 .Fa size .
 119 The firmware image data is placed into the buffer specified by
 120 .Fa buf .
 121 .Fn "firmware_read"
 122 will either read as much data as requested or fail, there are no short
 123 reads.
 124 .El
 125 .Sh CONTEXT
 126 These functions can be called from user and kernel context.
 127 .Sh RETURN VALUES
 128 Upon successful completion, the
 129 .Fn firmware_open
 130 function returns zero and stores a firmware handle in
 131 .Fa fhp .
 132 Otherwise a non-zero error code is returned.
 133 .sp
 134 The function
 135 .Fn firmware_read
 136 will return zero on success and
 137 .Fa buf
 138 will be filled with
 139 .Fa size
 140 bytes of data.
 141 On failure -1 is returned.
 142 .sp
 143 The function
 144 .Fn firmware_get_size
 145 returns the size of a firmware image.
 146 .sp
 147 .Fn firmware_close
 148 will always return zero.
 149 .Sh INTERFACE STABILITY
 150 .Sy Committed
 151 .Sh SEE ALSO
 152 .Xr system 4