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