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$ 28.\" 29.Dd November 2, 2021 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.Ft int 49.Fn efi_rt_ok "void" 50.Ft int 51.Fn efi_get_table "struct uuid *uuid" "void **ptr" 52.Ft int 53.Fn efi_get_time "struct efi_tm *tm" 54.Ft int 55.Fn efi_get_time_capabilities "struct efi_tmcap *tmcap" 56.Ft int 57.Fn efi_reset_system "enum efi_reset type" 58.Ft int 59.Fn efi_set_time "struct efi_tm *tm" 60.Ft int 61.Fn efi_var_get "uint16_t *name" "struct uuid *vendor" "uint32_t *attrib" \ 62 "size_t *datasize" "void *data" 63.Ft int 64.Fn efi_var_nextname "size_t *namesize" "uint16_t *name" "struct uuid *vendor" 65.Ft int 66.Fn efi_var_set "uint16_t *name" "struct uuid *vendor" "uint32_t attrib" \ 67 "size_t datasize" "void *data" 68.Sh DESCRIPTION 69All of the following calls will return 70.Dv ENXIO 71if UEFI runtime services are not available. 72.Nm 73is currently only available on amd64 and arm64. 74.Pp 75The 76.Fn efi_rt_ok 77Returns 0 if UEFI runtime services are present and functional, or 78.Dv ENXIO 79if not. 80.Pp 81The 82.Fn efi_get_table 83function gets a table by uuid from the UEFI system table. 84Returns 0 if the table was found and populates *ptr with the address. 85Returns 86.Dv ENXIO 87if the configuration table or system table are unset. 88Returns 89.Dv ENOENT 90if the requested table cannot be found. 91.Pp 92The 93.Fn efi_get_time 94function gets the current time from the RTC, if available. 95Returns 0 and populates the 96.Vt struct efi_tm 97on success. 98Returns 99.Dv EINVAL 100if the 101.Vt struct efi_tm 102is 103.Dv NULL , 104or 105.Dv EIO 106if the time could not be retrieved due to a hardware error. 107.Pp 108The 109.Fn efi_get_time_capabilities 110function gets the capabilities from the RTC. 111Returns 0 and populates the 112.Vt struct efi_tmcap 113on success. 114Returns 115.Dv EINVAL 116if the 117.Vt struct efi_tm 118is 119.Dv NULL , 120or 121.Dv EIO 122if the time could not be retrieved due to a hardware error. 123.Pp 124The 125.Fn efi_reset_system 126function requests a reset of the system. 127The 128.Fa type 129argument may be one of the 130.Vt enum efi_reset 131values: 132.Bl -tag -width ".Dv EFI_RESET_SHUTDOWN" 133.It Dv EFI_RESET_COLD 134Perform a cold reset of the system, and reboot. 135.It Dv EFI_RESET_WARM 136Perform a warm reset of the system, and reboot. 137.It Dv EFI_RESET_SHUTDOWN 138Power off the system. 139.El 140.Pp 141The 142.Fn efi_set_time 143function sets the time on the RTC to the time described by the 144.Vt struct efi_tm 145passed in. 146Returns 0 on success, 147.Dv EINVAL 148if a time field is out of range, or 149.Dv EIO 150if the time could not be set due to a hardware error. 151.Pp 152The 153.Fn efi_var_get 154function fetches the variable identified by 155.Fa vendor 156and 157.Fa name . 158Returns 0 and populates 159.Fa attrib , 160.Fa datasize , 161and 162.Fa data 163on success. 164Otherwise, one of the following errors are returned: 165.Bl -tag -width ".Dv EOVERFLOW" 166.It Dv ENOENT 167The variable was not found. 168.It Dv EOVERFLOW 169.Fa datasize 170is not sufficient to hold the variable data. 171.Fa namesize 172is updated to reflect the size needed to complete the request. 173.It Dv EINVAL 174One of 175.Fa name , 176.Fa vendor , 177or 178.Fa datasize 179are NULL. 180Alternatively, 181.Fa datasize 182is large enough to hold the response but 183.Fa data 184is NULL. 185.It Dv EIO 186The variable could not be retrieved due to a hardware error. 187.It Dv EDOOFUS 188The variable could not be retireved due to an authentication failure. 189.El 190.Pp 191The 192.Fn efi_var_nextname 193function is used for enumeration of variables. 194On the initial call to 195.Fn efi_var_nextname , 196.Fa name 197should be an empty string. 198Subsequent calls should pass in the last 199.Fa name 200and 201.Fa vendor 202returned until 203.Dv ENOENT 204is returned. 205Returns 0 and populates 206.Fa namesize , 207.Fa name , 208and 209.Fa vendor 210with the next variable's data. 211Otherwise, returns one of the following errors: 212.Bl -tag -width ".Dv EOVERFLOW" 213.It Dv ENOENT 214The next variable was not found. 215.It Dv EOVERFLOW 216.Fa datasize 217is not sufficient to hold the variable data. 218.Fa namesize 219is updated to reflect the size needed to complete the request. 220.It Dv EINVAL 221One of 222.Fa name , 223.Fa vendor , 224or 225.Fa datasize 226are NULL. 227.It Dv EIO 228The variable could not be retrieved due to a hardware error. 229.El 230.Pp 231The 232.Fn efi_var_set 233function sets the variable described by 234.Fa name 235and 236.Fa vendor . 237Returns 0 if the variable has been successfully. 238Otherwise, returns one of the following errors: 239.Bl -tag -width ".Dv EOVERFLOW" 240.It Dv EINVAL 241Either 242.Fa attrib 243was an invalid combination of attributes, 244.Fa datasize 245exceeds the maximum allowed size, or 246.Fa name 247is an empty Unicode stirng. 248.It Dv EAGAIN 249Not enough storage is available to hold the variable and its data. 250.It Dv EIO 251The variable could not be saved due to a hardware error. 252.It Dv EROFS 253The variable in question is read-only or may not be deleted. 254.It Dv EDOOFUS 255The variable could not be set due to an authentication failure. 256.It Dv ENOENT 257The variable trying to be updated or deleted was not found. 258.El 259.Sh SEE ALSO 260.Xr efidev 4 261.Sh AUTHORS 262This manual page was written by 263.An Kyle Evans Aq Mt kevans@FreeBSD.org . 264