share/man/man4/efidev.4

   1 .\"-
   2 .\" SPDX-License-Identifier: BSD-2-Clause
   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 .Dd June 18, 2021
  28 .Dt EFIDEV 4
  29 .Os
  30 .Sh NAME
  31 .Nm efidev ,
  32 .Nm efirtc
  33 .Nd user-mode access to UEFI runtime services
  34 .Sh SYNOPSIS
  35 To compile this driver into the kernel, place the following lines in your
  36 kernel configuration file:
  37 .Bd -ragged -offset -indent
  38 .Cd "options EFIRT"
  39 .Ed
  40 .Pp
  41 Alternatively, to load the driver as a module at boot time, place the following
  42 line in
  43 .Xr loader.conf 5 :
  44 .Bd -literal -offset indent
  45 efirt_load="YES"
  46 .Ed
  47 .Pp
  48 The driver may be disabled by setting the
  49 .Xr loader 8
  50 tunable
  51 .Va efi.rt.disabled
  52 to
  53 .Dq Li 1 .
  54 .Sh DESCRIPTION
  55 The
  56 .Nm
  57 device provides user-mode access to UEFI runtime services.
  58 .Nm
  59 also includes a driver to provide a time-of-day clock using the UEFI
  60 real time clock (RTC).
  61 However, the RTC may not always be available, based on the UEFI firmware.
  62 If the RTC is not available, it will not be registered as a time-of-day clock
  63 and the time related ioctls below will not be functional.
  64 .Pp
  65 .Nm
  66 provides the following ioctls defined in
  67 .In sys/efiio.h
  68 with supplemental structures and constants defined in
  69 .In sys/efi.h :
  70 .Bl -tag -width indent
  71 .It Dv EFIIOC_GET_TABLE Pq Vt "struct efi_get_table_ioc"
  72 Copy the UEFI table specified by the
  73 .Va uuid
  74 field of the
  75 .Vt struct efi_get_table_ioc
  76 into the
  77 .Va buf
  78 field.
  79 The memory size for the buf field can be queried by passing
  80 .Dv NULL
  81 pointer as a buf value.
  82 The required size will be stored in the
  83 .Va table_len
  84 field.
  85 The size of the allocated memory must be specified in the
  86 .Va buf_len
  87 field.
  88 .Bd -literal -offset indent
  89 struct efi_get_table_ioc {
  90         void *buf;
  91         struct uuid uuid;
  92         size_t table_len;
  93         size_t buf_len;
  94 };
  95 .Ed
  96 .It Dv EFIIOC_GET_TIME Pq Vt "struct efi_tm"
  97 Get the time from the RTC, if the RTC is available.
  98 The
  99 .Vt struct efi_tm
 100 passed is populated with the current time, unless an error occurs.
 101 .Bd -literal -offset indent
 102 struct efi_tm {
 103         uint16_t        tm_year;
 104         uint8_t         tm_mon
 105         uint8_t         tm_mday
 106         uint8_t         tm_hour;
 107         uint8_t         tm_min;
 108         uint8_t         tm_sec;
 109         uint8_t          __pad1;
 110         uint32_t        tm_nsec;
 111         int16_t         tm_tz;
 112         uint8_t         tm_dst;
 113         uint8_t         __pad2;
 114 };
 115 .Ed
 116 .It Dv EFIIOC_SET_TIME Pq Vt "struct efi_tm"
 117 Sets the time stored by the RTC, if the RTC is available.
 118 .It Dv EFIIOC_VAR_GET Pq Vt "struct efi_var_ioc"
 119 Gets data from the variable described by the vendor and name fields of the
 120 .Vt struct efi_var_ioc
 121 into the
 122 .Fa data
 123 field.
 124 .Dv EFIIOC_VAR_GET Pq Vt "struct efi_var_ioc"
 125 will also populate the
 126 .Fa attrib
 127 field.
 128 .Bd -literal
 129 struct efi_var_ioc {
 130         efi_char        *name;
 131         size_t           namesize;
 132         struct uuid      vendor;
 133         uint32_t         attrib;
 134         void            *data;
 135         size_t           datasize;
 136 };
 137 .Ed
 138 .It Dv EFIIOC_VAR_NEXT Pq Vt "struct efi_var_ioc"
 139 Used for enumerating all UEFI variables.
 140 The initial call should use an empty string for the name attribute.
 141 Subsequent calls should supply the vendor uuid and name of the last variable
 142 returned.
 143 .It Dv EFIIOC_VAR_SET Pq Vt "struct efi_var_ioc"
 144 Sets data and attributes for the variable described by the name and vendor in
 145 the
 146 .Vt struct efi_var_ioc .
 147 .El
 148 .Sh FILES
 149 .Bl -tag -width /dev/efi
 150 .It Pa /dev/efi
 151 .El
 152 .Sh SEE ALSO
 153 .Xr efivar 3 ,
 154 .Xr efirt 9
 155 .Sh HISTORY
 156 A
 157 .Nm
 158 device first appeared in
 159 .Fx 11.1 .
 160 .Sh BUGS
 161 .Nm
 162 is currently only available on amd64 and arm64.