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 August 12, 2018 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 "void" 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 warm reset and reboot of the system. 127.Pp 128The 129.Fn efi_set_time 130function sets the time on the RTC to the time described by the 131.Vt struct efi_tm 132passed in. 133Returns 0 on success, 134.Dv EINVAL 135if a time field is out of range, or 136.Dv EIO 137if the time could not be set due to a hardware error. 138.Pp 139The 140.Fn efi_var_get 141function fetches the variable identified by 142.Fa vendor 143and 144.Fa name . 145Returns 0 and populates 146.Fa attrib , 147.Fa datasize , 148and 149.Fa data 150on success. 151Otherwise, one of the following errors are returned: 152.Bl -tag -width ".Dv EOVERFLOW" 153.It Dv ENOENT 154The variable was not found. 155.It Dv EOVERFLOW 156.Fa datasize 157is not sufficient to hold the variable data. 158.Fa namesize 159is updated to reflect the size needed to complete the request. 160.It Dv EINVAL 161One of 162.Fa name , 163.Fa vendor , 164or 165.Fa datasize 166are NULL. 167Alternatively, 168.Fa datasize 169is large enough to hold the response but 170.Fa data 171is NULL. 172.It Dv EIO 173The variable could not be retrieved due to a hardware error. 174.It Dv EDOOFUS 175The variable could not be retireved due to an authentication failure. 176.El 177.Pp 178The 179.Fn efi_var_nextname 180function is used for enumeration of variables. 181On the initial call to 182.Fn efi_var_nextname , 183.Fa name 184should be an empty string. 185Subsequent calls should pass in the last 186.Fa name 187and 188.Fa vendor 189returned until 190.Dv ENOENT 191is returned. 192Returns 0 and populates 193.Fa namesize , 194.Fa name , 195and 196.Fa vendor 197with the next variable's data. 198Otherwise, returns one of the following errors: 199.Bl -tag -width ".Dv EOVERFLOW" 200.It Dv ENOENT 201The next variable was not found. 202.It Dv EOVERFLOW 203.Fa datasize 204is not sufficient to hold the variable data. 205.Fa namesize 206is updated to reflect the size needed to complete the request. 207.It Dv EINVAL 208One of 209.Fa name , 210.Fa vendor , 211or 212.Fa datasize 213are NULL. 214.It Dv EIO 215The variable could not be retrieved due to a hardware error. 216.El 217.Pp 218The 219.Fn efi_var_set 220function sets the variable described by 221.Fa name 222and 223.Fa vendor . 224Returns 0 if the variable has been successfully. 225Otherwise, returns one of the following errors: 226.Bl -tag -width ".Dv EOVERFLOW" 227.It Dv EINVAL 228Either 229.Fa attrib 230was an invalid combination of attributes, 231.Fa datasize 232exceeds the maximum allowed size, or 233.Fa name 234is an empty Unicode stirng. 235.It Dv EAGAIN 236Not enough storage is available to hold the variable and its data. 237.It Dv EIO 238The variable could not be saved due to a hardware error. 239.It Dv EROFS 240The variable in question is read-only or may not be deleted. 241.It Dv EDOOFUS 242The varialbe could not be set due to an authentication failure. 243.It Dv ENOENT 244The variable trying to be updated or deleted was not found. 245.El 246.Sh SEE ALSO 247.Xr efidev 4 248.Sh AUTHORS 249This manual page was written by 250.An Kyle Evans Aq Mt kevans@FreeBSD.org . 251