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