share/man/man9/efirt.9

   1 .\"-
   2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   3 .\"
   4 .\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org>
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD: head/share/man/man9/efirt.9 337957 2018-08-17 04:17:51Z kevans $
  28 .\"
  29 .Dd January 21, 2019
  30 .Dt EFIRT 9
  31 .Os
  32 .Sh NAME
  33 .Nm efirt ,
  34 .\".Nm efi_rt_ok ,
  35 .Nm efi_get_table ,
  36 .Nm efi_get_time ,
  37 .\".Nm efi_get_time_capabilities ,
  38 .Nm efi_reset_system ,
  39 .Nm efi_set_time ,
  40 .Nm efi_var_get ,
  41 .Nm efi_var_nextname ,
  42 .Nm efi_var_set
  43 .Nd kernel access to UEFI runtime services
  44 .Sh SYNOPSIS
  45 .Cd "options EFIRT"
  46 .Pp
  47 .In sys/efi.h
  48 .In machine/efi.h
  49 .\".Ft int
  50 .\".Fn efi_rt_ok "void"
  51 .Ft int
  52 .Fn efi_get_table "struct uuid *uuid" "void **ptr"
  53 .Ft int
  54 .Fn efi_get_time "struct efi_tm *tm"
  55 .\".Ft int
  56 .\".Fn efi_get_time_locked "struct efi_tm *tm"
  57 .\".Ft int
  58 .\".Fn efi_get_time_capabilities "struct efi_tmcap *tmcap"
  59 .Ft int
  60 .Fn efi_reset_system "void"
  61 .Ft int
  62 .Fn efi_set_time "struct efi_tm *tm"
  63 .\".Ft int
  64 .\".Fn efi_set_time_locked "struct efi_tm *tm"
  65 .Ft int
  66 .Fn efi_var_get "uint16_t *name" "struct uuid *vendor" "uint32_t *attrib" \
  67     "size_t *datasize" "void *data"
  68 .Ft int
  69 .Fn efi_var_nextname "size_t *namesize" "uint16_t *name" "struct uuid *vendor"
  70 .Ft int
  71 .Fn efi_var_set "uint16_t *name" "struct uuid *vendor" "uint32_t attrib" \
  72     "size_t datasize" "void *data"
  73 .Sh DESCRIPTION
  74 .\"All of the following calls will return
  75 .\".Er ENXIO
  76 .\"if UEFI runtime services are not available.
  77 .\".Nm
  78 .\"is currently only available on amd64 and arm64.
  79 .\".Pp
  80 .\"The
  81 .\".Fn efi_rt_ok
  82 .\"Returns 0 if UEFI runtime services are present and functional, or
  83 .\".Er ENXIO
  84 .\"if not.
  85 .\".Pp
  86 The
  87 .Fn efi_get_table
  88 function gets a table by uuid from the UEFI system table.
  89 Returns 0 if the table was found and populates *ptr with the address.
  90 Returns
  91 .Er ENXIO
  92 if the configuration table or system table are unset.
  93 Returns
  94 .Er ENOENT
  95 if the requested table cannot be found.
  96 .Pp
  97 The
  98 .Fn efi_get_time
  99 function gets the current time from the RTC, if available.
 100 Returns 0 and populates the
 101 .Vt struct efi_tm
 102 on success.
 103 Returns
 104 .Er EINVAL
 105 if the
 106 .Vt struct efi_tm
 107 is
 108 .Dv NULL ,
 109 or
 110 .Er EIO
 111 if the time could not be retrieved due to a hardware error.
 112 .Pp
 113 .\"The
 114 .\".Fn efi_get_time_capabilities
 115 .\"function gets the capabilities from the RTC.
 116 .\"Returns 0 and populates the
 117 .\".Vt struct efi_tmcap
 118 .\"on success.
 119 .\"Returns
 120 .\".Er EINVAL
 121 .\"if the
 122 .\".Vt struct efi_tm
 123 .\"is
 124 .\".Dv NULL ,
 125 .\"or
 126 .\".Er EIO
 127 .\"if the time could not be retrieved due to a hardware error.
 128 .\".Pp
 129 The
 130 .Fn efi_reset_system
 131 function requests a warm reset and reboot of the system.
 132 .Pp
 133 The
 134 .Fn efi_set_time
 135 function sets the time on the RTC to the time described by the
 136 .Vt struct efi_tm
 137 passed in.
 138 Returns 0 on success,
 139 .Er EINVAL
 140 if a time field is out of range, or
 141 .Er EIO
 142 if the time could not be set due to a hardware error.
 143 .Pp
 144 The
 145 .Fn efi_var_get
 146 function fetches the variable identified by
 147 .Fa vendor
 148 and
 149 .Fa name .
 150 Returns 0 and populates
 151 .Fa attrib ,
 152 .Fa datasize ,
 153 and
 154 .Fa data
 155 on success.
 156 Otherwise, one of the following errors are returned:
 157 .Bl -tag -width ".Er EOVERFLOW"
 158 .It Er ENOENT
 159 The variable was not found.
 160 .It Er EOVERFLOW
 161 .Fa datasize
 162 is not sufficient to hold the variable data.
 163 .Fa namesize
 164 is updated to reflect the size needed to complete the request.
 165 .It Er EINVAL
 166 One of
 167 .Fa name ,
 168 .Fa vendor ,
 169 or
 170 .Fa datasize
 171 are NULL.
 172 Alternatively,
 173 .Fa datasize
 174 is large enough to hold the response but
 175 .Fa data
 176 is NULL.
 177 .It Er EIO
 178 The variable could not be retrieved due to a hardware error.
 179 .It Er EDOOFUS
 180 The variable could not be retireved due to an authentication failure.
 181 .El
 182 .Pp
 183 The
 184 .Fn efi_var_nextname
 185 function is used for enumeration of variables.
 186 On the initial call to
 187 .Fn efi_var_nextname ,
 188 .Fa name
 189 should be an empty string.
 190 Subsequent calls should pass in the last
 191 .Fa name
 192 and
 193 .Fa vendor
 194 returned until
 195 .Er ENOENT
 196 is returned.
 197 Returns 0 and populates
 198 .Fa namesize ,
 199 .Fa name ,
 200 and
 201 .Fa vendor
 202 with the next variable's data.
 203 Otherwise, returns one of the following errors:
 204 .Bl -tag -width ".Er EOVERFLOW"
 205 .It Er ENOENT
 206 The next variable was not found.
 207 .It Er EOVERFLOW
 208 .Fa datasize
 209 is not sufficient to hold the variable data.
 210 .Fa namesize
 211 is updated to reflect the size needed to complete the request.
 212 .It Er EINVAL
 213 One of
 214 .Fa name ,
 215 .Fa vendor ,
 216 or
 217 .Fa datasize
 218 are NULL.
 219 .It Er EIO
 220 The variable could not be retrieved due to a hardware error.
 221 .El
 222 .Pp
 223 The
 224 .Fn efi_var_set
 225 function sets the variable described by
 226 .Fa name
 227 and
 228 .Fa vendor .
 229 Returns 0 if the variable has been successfully.
 230 Otherwise, returns one of the following errors:
 231 .Bl -tag -width ".Er EOVERFLOW"
 232 .It Er EINVAL
 233 Either
 234 .Fa attrib
 235 was an invalid combination of attributes,
 236 .Fa datasize
 237 exceeds the maximum allowed size, or
 238 .Fa name
 239 is an empty Unicode stirng.
 240 .It Er EAGAIN
 241 Not enough storage is available to hold the variable and its data.
 242 .It Er EIO
 243 The variable could not be saved due to a hardware error.
 244 .It Er EROFS
 245 The variable in question is read-only or may not be deleted.
 246 .It Er EDOOFUS
 247 The varialbe could not be set due to an authentication failure.
 248 .It Er ENOENT
 249 The variable trying to be updated or deleted was not found.
 250 .El
 251 .Sh SEE ALSO
 252 .Xr efidev 4
 253 .Sh AUTHORS
 254 This manual page was written by
 255 .An Kyle Evans Aq Mt kevans@FreeBSD.org .