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