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