xref: /freebsd/share/man/man9/efirt.9 (revision fa9896e082a1046ff4fbc75fcba4d18d1f2efc19)
1503478afSKyle Evans.\"-
2*4d846d26SWarner Losh.\" SPDX-License-Identifier: BSD-2-Clause
3503478afSKyle Evans.\"
4503478afSKyle Evans.\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org>
5503478afSKyle Evans.\"
6503478afSKyle Evans.\" Redistribution and use in source and binary forms, with or without
7503478afSKyle Evans.\" modification, are permitted provided that the following conditions
8503478afSKyle Evans.\" are met:
9503478afSKyle Evans.\" 1. Redistributions of source code must retain the above copyright
10503478afSKyle Evans.\"    notice, this list of conditions and the following disclaimer.
11503478afSKyle Evans.\" 2. Redistributions in binary form must reproduce the above copyright
12503478afSKyle Evans.\"    notice, this list of conditions and the following disclaimer in the
13503478afSKyle Evans.\"    documentation and/or other materials provided with the distribution.
14503478afSKyle Evans.\"
15503478afSKyle Evans.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16503478afSKyle Evans.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17503478afSKyle Evans.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18503478afSKyle Evans.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19503478afSKyle Evans.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20503478afSKyle Evans.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21503478afSKyle Evans.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22503478afSKyle Evans.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23503478afSKyle Evans.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24503478afSKyle Evans.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25503478afSKyle Evans.\" SUCH DAMAGE.
26503478afSKyle Evans.\"
272fe85640SLakshman.Dd November 2, 2021
28503478afSKyle Evans.Dt EFIRT 9
29503478afSKyle Evans.Os
30503478afSKyle Evans.Sh NAME
31503478afSKyle Evans.Nm efirt ,
32503478afSKyle Evans.Nm efi_rt_ok ,
33503478afSKyle Evans.Nm efi_get_table ,
34503478afSKyle Evans.Nm efi_get_time ,
35503478afSKyle Evans.Nm efi_get_time_capabilities ,
36503478afSKyle Evans.Nm efi_reset_system ,
37503478afSKyle Evans.Nm efi_set_time ,
38503478afSKyle Evans.Nm efi_var_get ,
39503478afSKyle Evans.Nm efi_var_nextname ,
40503478afSKyle Evans.Nm efi_var_set
41503478afSKyle Evans.Nd kernel access to UEFI runtime services
42503478afSKyle Evans.Sh SYNOPSIS
43503478afSKyle Evans.Cd "options EFIRT"
44503478afSKyle Evans.Pp
45503478afSKyle Evans.In sys/efi.h
46503478afSKyle Evans.Ft int
47503478afSKyle Evans.Fn efi_rt_ok "void"
48503478afSKyle Evans.Ft int
49503478afSKyle Evans.Fn efi_get_table "struct uuid *uuid" "void **ptr"
50503478afSKyle Evans.Ft int
51503478afSKyle Evans.Fn efi_get_time "struct efi_tm *tm"
52503478afSKyle Evans.Ft int
53503478afSKyle Evans.Fn efi_get_time_capabilities "struct efi_tmcap *tmcap"
54503478afSKyle Evans.Ft int
5526649bb5SConrad Meyer.Fn efi_reset_system "enum efi_reset type"
56503478afSKyle Evans.Ft int
57503478afSKyle Evans.Fn efi_set_time "struct efi_tm *tm"
58503478afSKyle Evans.Ft int
59503478afSKyle Evans.Fn efi_var_get "uint16_t *name" "struct uuid *vendor" "uint32_t *attrib" \
60503478afSKyle Evans    "size_t *datasize" "void *data"
61503478afSKyle Evans.Ft int
62503478afSKyle Evans.Fn efi_var_nextname "size_t *namesize" "uint16_t *name" "struct uuid *vendor"
63503478afSKyle Evans.Ft int
642fe85640SLakshman.Fn efi_var_set "uint16_t *name" "struct uuid *vendor" "uint32_t attrib" \
652fe85640SLakshman    "size_t datasize" "void *data"
66503478afSKyle Evans.Sh DESCRIPTION
67503478afSKyle EvansAll of the following calls will return
68503478afSKyle Evans.Dv ENXIO
69503478afSKyle Evansif UEFI runtime services are not available.
70503478afSKyle Evans.Nm
71503478afSKyle Evansis currently only available on amd64 and arm64.
72503478afSKyle Evans.Pp
73503478afSKyle EvansThe
74503478afSKyle Evans.Fn efi_rt_ok
75503478afSKyle EvansReturns 0 if UEFI runtime services are present and functional, or
76503478afSKyle Evans.Dv ENXIO
77503478afSKyle Evansif not.
78503478afSKyle Evans.Pp
79503478afSKyle EvansThe
80503478afSKyle Evans.Fn efi_get_table
81503478afSKyle Evansfunction gets a table by uuid from the UEFI system table.
82503478afSKyle EvansReturns 0 if the table was found and populates *ptr with the address.
83503478afSKyle EvansReturns
84503478afSKyle Evans.Dv ENXIO
85503478afSKyle Evansif the configuration table or system table are unset.
86503478afSKyle EvansReturns
87503478afSKyle Evans.Dv ENOENT
88503478afSKyle Evansif the requested table cannot be found.
89503478afSKyle Evans.Pp
90503478afSKyle EvansThe
91503478afSKyle Evans.Fn efi_get_time
92503478afSKyle Evansfunction gets the current time from the RTC, if available.
93503478afSKyle EvansReturns 0 and populates the
94503478afSKyle Evans.Vt struct efi_tm
95503478afSKyle Evanson success.
96503478afSKyle EvansReturns
97503478afSKyle Evans.Dv EINVAL
98503478afSKyle Evansif the
99503478afSKyle Evans.Vt struct efi_tm
100503478afSKyle Evansis
101503478afSKyle Evans.Dv NULL ,
102503478afSKyle Evansor
103503478afSKyle Evans.Dv EIO
104503478afSKyle Evansif the time could not be retrieved due to a hardware error.
105503478afSKyle Evans.Pp
106503478afSKyle EvansThe
107503478afSKyle Evans.Fn efi_get_time_capabilities
108503478afSKyle Evansfunction gets the capabilities from the RTC.
109503478afSKyle EvansReturns 0 and populates the
110503478afSKyle Evans.Vt struct efi_tmcap
111503478afSKyle Evanson success.
112503478afSKyle EvansReturns
113503478afSKyle Evans.Dv EINVAL
114503478afSKyle Evansif the
115503478afSKyle Evans.Vt struct efi_tm
116503478afSKyle Evansis
117503478afSKyle Evans.Dv NULL ,
118503478afSKyle Evansor
119503478afSKyle Evans.Dv EIO
120503478afSKyle Evansif the time could not be retrieved due to a hardware error.
121503478afSKyle Evans.Pp
122503478afSKyle EvansThe
123503478afSKyle Evans.Fn efi_reset_system
12426649bb5SConrad Meyerfunction requests a reset of the system.
12526649bb5SConrad MeyerThe
12626649bb5SConrad Meyer.Fa type
12726649bb5SConrad Meyerargument may be one of the
12826649bb5SConrad Meyer.Vt enum efi_reset
12926649bb5SConrad Meyervalues:
13026649bb5SConrad Meyer.Bl -tag -width ".Dv EFI_RESET_SHUTDOWN"
13126649bb5SConrad Meyer.It Dv EFI_RESET_COLD
13226649bb5SConrad MeyerPerform a cold reset of the system, and reboot.
13326649bb5SConrad Meyer.It Dv EFI_RESET_WARM
13426649bb5SConrad MeyerPerform a warm reset of the system, and reboot.
13526649bb5SConrad Meyer.It Dv EFI_RESET_SHUTDOWN
13626649bb5SConrad MeyerPower off the system.
13726649bb5SConrad Meyer.El
138503478afSKyle Evans.Pp
139503478afSKyle EvansThe
140503478afSKyle Evans.Fn efi_set_time
141503478afSKyle Evansfunction sets the time on the RTC to the time described by the
142503478afSKyle Evans.Vt struct efi_tm
143503478afSKyle Evanspassed in.
144503478afSKyle EvansReturns 0 on success,
145503478afSKyle Evans.Dv EINVAL
146503478afSKyle Evansif a time field is out of range, or
147503478afSKyle Evans.Dv EIO
148503478afSKyle Evansif the time could not be set due to a hardware error.
149503478afSKyle Evans.Pp
150503478afSKyle EvansThe
151503478afSKyle Evans.Fn efi_var_get
152503478afSKyle Evansfunction fetches the variable identified by
153503478afSKyle Evans.Fa vendor
154503478afSKyle Evansand
155503478afSKyle Evans.Fa name .
156503478afSKyle EvansReturns 0 and populates
157503478afSKyle Evans.Fa attrib ,
158503478afSKyle Evans.Fa datasize ,
159503478afSKyle Evansand
160503478afSKyle Evans.Fa data
161503478afSKyle Evanson success.
162503478afSKyle EvansOtherwise, one of the following errors are returned:
163503478afSKyle Evans.Bl -tag -width ".Dv EOVERFLOW"
164503478afSKyle Evans.It Dv ENOENT
165503478afSKyle EvansThe variable was not found.
166503478afSKyle Evans.It Dv EOVERFLOW
167503478afSKyle Evans.Fa datasize
168503478afSKyle Evansis not sufficient to hold the variable data.
169503478afSKyle Evans.Fa namesize
170503478afSKyle Evansis updated to reflect the size needed to complete the request.
171503478afSKyle Evans.It Dv EINVAL
172503478afSKyle EvansOne of
173503478afSKyle Evans.Fa name ,
174503478afSKyle Evans.Fa vendor ,
175503478afSKyle Evansor
176503478afSKyle Evans.Fa datasize
177503478afSKyle Evansare NULL.
178503478afSKyle EvansAlternatively,
179503478afSKyle Evans.Fa datasize
180503478afSKyle Evansis large enough to hold the response but
181503478afSKyle Evans.Fa data
182503478afSKyle Evansis NULL.
183503478afSKyle Evans.It Dv EIO
184503478afSKyle EvansThe variable could not be retrieved due to a hardware error.
185503478afSKyle Evans.It Dv EDOOFUS
186503478afSKyle EvansThe variable could not be retireved due to an authentication failure.
187503478afSKyle Evans.El
188503478afSKyle Evans.Pp
189503478afSKyle EvansThe
190503478afSKyle Evans.Fn efi_var_nextname
191503478afSKyle Evansfunction is used for enumeration of variables.
192503478afSKyle EvansOn the initial call to
193503478afSKyle Evans.Fn efi_var_nextname ,
194503478afSKyle Evans.Fa name
195503478afSKyle Evansshould be an empty string.
196503478afSKyle EvansSubsequent calls should pass in the last
197503478afSKyle Evans.Fa name
198503478afSKyle Evansand
199503478afSKyle Evans.Fa vendor
200503478afSKyle Evansreturned until
201503478afSKyle Evans.Dv ENOENT
202503478afSKyle Evansis returned.
203503478afSKyle EvansReturns 0 and populates
204503478afSKyle Evans.Fa namesize ,
205503478afSKyle Evans.Fa name ,
206503478afSKyle Evansand
207503478afSKyle Evans.Fa vendor
208503478afSKyle Evanswith the next variable's data.
209503478afSKyle EvansOtherwise, returns one of the following errors:
210503478afSKyle Evans.Bl -tag -width ".Dv EOVERFLOW"
211503478afSKyle Evans.It Dv ENOENT
212503478afSKyle EvansThe next variable was not found.
213503478afSKyle Evans.It Dv EOVERFLOW
214503478afSKyle Evans.Fa datasize
215503478afSKyle Evansis not sufficient to hold the variable data.
216503478afSKyle Evans.Fa namesize
217503478afSKyle Evansis updated to reflect the size needed to complete the request.
218503478afSKyle Evans.It Dv EINVAL
219503478afSKyle EvansOne of
220503478afSKyle Evans.Fa name ,
221503478afSKyle Evans.Fa vendor ,
222503478afSKyle Evansor
223503478afSKyle Evans.Fa datasize
224503478afSKyle Evansare NULL.
225503478afSKyle Evans.It Dv EIO
226503478afSKyle EvansThe variable could not be retrieved due to a hardware error.
227503478afSKyle Evans.El
228503478afSKyle Evans.Pp
229503478afSKyle EvansThe
230503478afSKyle Evans.Fn efi_var_set
231503478afSKyle Evansfunction sets the variable described by
232503478afSKyle Evans.Fa name
233503478afSKyle Evansand
234503478afSKyle Evans.Fa vendor .
235503478afSKyle EvansReturns 0 if the variable has been successfully.
236503478afSKyle EvansOtherwise, returns one of the following errors:
237503478afSKyle Evans.Bl -tag -width ".Dv EOVERFLOW"
238503478afSKyle Evans.It Dv EINVAL
239503478afSKyle EvansEither
240503478afSKyle Evans.Fa attrib
241503478afSKyle Evanswas an invalid combination of attributes,
242503478afSKyle Evans.Fa datasize
243503478afSKyle Evansexceeds the maximum allowed size, or
244503478afSKyle Evans.Fa name
245503478afSKyle Evansis an empty Unicode stirng.
246503478afSKyle Evans.It Dv EAGAIN
247503478afSKyle EvansNot enough storage is available to hold the variable and its data.
248503478afSKyle Evans.It Dv EIO
249503478afSKyle EvansThe variable could not be saved due to a hardware error.
250503478afSKyle Evans.It Dv EROFS
251503478afSKyle EvansThe variable in question is read-only or may not be deleted.
252503478afSKyle Evans.It Dv EDOOFUS
25326649bb5SConrad MeyerThe variable could not be set due to an authentication failure.
254503478afSKyle Evans.It Dv ENOENT
255503478afSKyle EvansThe variable trying to be updated or deleted was not found.
256503478afSKyle Evans.El
257503478afSKyle Evans.Sh SEE ALSO
258503478afSKyle Evans.Xr efidev 4
259503478afSKyle Evans.Sh AUTHORS
260503478afSKyle EvansThis manual page was written by
261503478afSKyle Evans.An Kyle Evans Aq Mt kevans@FreeBSD.org .
262