mirror of
https://github.com/freebsd/freebsd-src
synced 2024-09-06 17:18:32 +00:00
Add efidev(4)/efirt(9)
Document efidev(4), provider of userland access to EFI Runtime Services. A link is created to efirtc(4), which handles the time-of-day clock side. efirt(9) is the kernel side of this. Reviewed by: imp, kib (earlier version) Differential Revision: https://reviews.freebsd.org/D16696
This commit is contained in:
parent
e10ba80063
commit
503478afd1
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=337957
|
@ -92,6 +92,8 @@ This function is not actually implemented.
|
||||||
.Sh BUGS
|
.Sh BUGS
|
||||||
No facilities exist to process the strings as native UTF.
|
No facilities exist to process the strings as native UTF.
|
||||||
This is a limitation in the Linux libefivar library interface.
|
This is a limitation in the Linux libefivar library interface.
|
||||||
|
.Sh SEE ALSO
|
||||||
|
.Xr efidev 4
|
||||||
.Sh AUTHORS
|
.Sh AUTHORS
|
||||||
.An -nosplit
|
.An -nosplit
|
||||||
This software was originally written by
|
This software was originally written by
|
||||||
|
|
|
@ -900,6 +900,12 @@ _dtrace_provs= dtrace_io.4 \
|
||||||
dtrace_udplite.4
|
dtrace_udplite.4
|
||||||
.endif
|
.endif
|
||||||
|
|
||||||
|
.if ${MK_EFI} != "no"
|
||||||
|
MAN+= efidev.4
|
||||||
|
|
||||||
|
MLINKS+= efidev.4 efirtc.4
|
||||||
|
.endif
|
||||||
|
|
||||||
.if ${MK_ISCSI} != "no"
|
.if ${MK_ISCSI} != "no"
|
||||||
MAN+= cfiscsi.4
|
MAN+= cfiscsi.4
|
||||||
MAN+= iscsi.4
|
MAN+= iscsi.4
|
||||||
|
|
143
share/man/man4/efidev.4
Normal file
143
share/man/man4/efidev.4
Normal file
|
@ -0,0 +1,143 @@
|
||||||
|
.\"-
|
||||||
|
.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
|
||||||
|
.\"
|
||||||
|
.\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org>
|
||||||
|
.\"
|
||||||
|
.\" Redistribution and use in source and binary forms, with or without
|
||||||
|
.\" modification, are permitted provided that the following conditions
|
||||||
|
.\" are met:
|
||||||
|
.\" 1. Redistributions of source code must retain the above copyright
|
||||||
|
.\" notice, this list of conditions and the following disclaimer.
|
||||||
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||||
|
.\" notice, this list of conditions and the following disclaimer in the
|
||||||
|
.\" documentation and/or other materials provided with the distribution.
|
||||||
|
.\"
|
||||||
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
||||||
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||||
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||||
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
||||||
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||||
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||||
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||||
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||||
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||||
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||||
|
.\" SUCH DAMAGE.
|
||||||
|
.\"
|
||||||
|
.\" $FreeBSD$
|
||||||
|
.\"
|
||||||
|
.Dd August 12, 2018
|
||||||
|
.Dt EFIDEV 4
|
||||||
|
.Os
|
||||||
|
.Sh NAME
|
||||||
|
.Nm efidev ,
|
||||||
|
.Nm efirtc
|
||||||
|
.Nd user-mode access to UEFI runtime services
|
||||||
|
.Sh SYNOPSIS
|
||||||
|
To compile this driver into the kernel, place the following lines in your
|
||||||
|
kernel configuration file:
|
||||||
|
.Bd -ragged -offset -indent
|
||||||
|
.Cd "options EFIRT"
|
||||||
|
.Ed
|
||||||
|
.Pp
|
||||||
|
Alternatively, to load the driver as a module at boot time, place the following
|
||||||
|
line in
|
||||||
|
.Xr loader.conf 5 :
|
||||||
|
.Bd -literal -offset indent
|
||||||
|
efirt_load="YES"
|
||||||
|
.Ed
|
||||||
|
.Pp
|
||||||
|
.Nm
|
||||||
|
may be disabled by setting the
|
||||||
|
.Xr loader 8
|
||||||
|
tunable
|
||||||
|
.Va efi.rt.disabled
|
||||||
|
to 1.
|
||||||
|
.Pp
|
||||||
|
.Nm
|
||||||
|
is currently only available on amd64 and arm64.
|
||||||
|
.Sh DESCRIPTION
|
||||||
|
The
|
||||||
|
.Nm
|
||||||
|
device provides user-mode access to UEFI runtime services.
|
||||||
|
.Nm
|
||||||
|
also includes a driver to provide a time-of-day clock using the UEFI
|
||||||
|
real time clock (RTC).
|
||||||
|
However, the RTC may not always be available, based on the UEFI firmware.
|
||||||
|
If the RTC is not available, it will not be registered as a time-of-day clock
|
||||||
|
and the time related ioctls below will not be functional.
|
||||||
|
.Pp
|
||||||
|
.Nm
|
||||||
|
provides the following ioctls defined in
|
||||||
|
.In sys/efiio.h
|
||||||
|
with supplemental structures and constants defined in
|
||||||
|
.In sys/efi.h :
|
||||||
|
.Bl -tag -width ".Dv EFIIOC_GET_TABLE"
|
||||||
|
.It Dv EFIIOC_GET_TABLE Pq Vt "struct efi_get_table_ioc"
|
||||||
|
Get a table by uuid from the UEFI system table.
|
||||||
|
.Bd -literal
|
||||||
|
struct efi_get_table_ioc {
|
||||||
|
struct uuid uuid;
|
||||||
|
void *ptr;
|
||||||
|
};
|
||||||
|
.Ed
|
||||||
|
.It Dv EFIIOC_GET_TIME Pq Vt "struct efi_tm"
|
||||||
|
Get the time from the RTC, if the RTC is available.
|
||||||
|
The
|
||||||
|
.Vt struct efi_tm
|
||||||
|
passed is populated with the current time, unless an error occurs.
|
||||||
|
.Bd -literal
|
||||||
|
struct efi_tm {
|
||||||
|
uint16_t tm_year;
|
||||||
|
uint8_t tm_mon
|
||||||
|
uint8_t tm_mday
|
||||||
|
uint8_t tm_hour;
|
||||||
|
uint8_t tm_min;
|
||||||
|
uint8_t tm_sec;
|
||||||
|
uint8_t __pad1;
|
||||||
|
uint32_t tm_nsec;
|
||||||
|
int16_t tm_tz;
|
||||||
|
uint8_t tm_dst;
|
||||||
|
uint8_t __pad2;
|
||||||
|
};
|
||||||
|
.Ed
|
||||||
|
.It Dv EFIIOC_SET_TIME Pq Vt "struct efi_tm"
|
||||||
|
Sets the time stored by the RTC, if the RTC is available.
|
||||||
|
.It Dv EFIIOC_VAR_GET Pq Vt "struct efi_var_ioc"
|
||||||
|
Gets data from the variable described by the vendor and name fields of the
|
||||||
|
.Vt struct efi_var_ioc
|
||||||
|
into the aata field.
|
||||||
|
.Dv EFIIOC_VAR_GET Pq Vt "struct efi_var_ioc"
|
||||||
|
will also populate the attrib field.
|
||||||
|
.Bd -literal
|
||||||
|
struct efi_var_ioc {
|
||||||
|
efi_char *name;
|
||||||
|
size_t namesize;
|
||||||
|
struct uuid vendor;
|
||||||
|
uint32_t attrib;
|
||||||
|
void *data;
|
||||||
|
size_t datasize;
|
||||||
|
};
|
||||||
|
.Ed
|
||||||
|
.It Dv EFIIOC_VAR_NEXT Pq Vt "struct efi_var_ioc"
|
||||||
|
Used for enumerating all UEFI variables.
|
||||||
|
The initial call should use an empty string for the name attribute.
|
||||||
|
Subsequent calls should supply the vendor uuid and name of the last variable
|
||||||
|
returned.
|
||||||
|
.It Dv EFIIOC_VAR_SET Pq Vt "struct efi_var_ioc"
|
||||||
|
Sets data and attributes for the variable described by the name and vendor in
|
||||||
|
the
|
||||||
|
.Vt struct efi_var_ioc .
|
||||||
|
.El
|
||||||
|
.Sh FILES
|
||||||
|
.Bl -tag -width /dev/efi
|
||||||
|
.It Pa /dev/efi
|
||||||
|
.El
|
||||||
|
.Sh SEE ALSO
|
||||||
|
.Xr efivar 3
|
||||||
|
.Xr efirt 9
|
||||||
|
.Sh HISTORY
|
||||||
|
A
|
||||||
|
.Nm
|
||||||
|
device first appeared in
|
||||||
|
.Fx 11.1 .
|
|
@ -123,6 +123,7 @@ MAN= accept_filter.9 \
|
||||||
drbr.9 \
|
drbr.9 \
|
||||||
driver.9 \
|
driver.9 \
|
||||||
DRIVER_MODULE.9 \
|
DRIVER_MODULE.9 \
|
||||||
|
efirt.9 \
|
||||||
epoch.9 \
|
epoch.9 \
|
||||||
EVENTHANDLER.9 \
|
EVENTHANDLER.9 \
|
||||||
eventtimers.9 \
|
eventtimers.9 \
|
||||||
|
|
250
share/man/man9/efirt.9
Normal file
250
share/man/man9/efirt.9
Normal file
|
@ -0,0 +1,250 @@
|
||||||
|
.\"-
|
||||||
|
.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
|
||||||
|
.\"
|
||||||
|
.\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org>
|
||||||
|
.\"
|
||||||
|
.\" Redistribution and use in source and binary forms, with or without
|
||||||
|
.\" modification, are permitted provided that the following conditions
|
||||||
|
.\" are met:
|
||||||
|
.\" 1. Redistributions of source code must retain the above copyright
|
||||||
|
.\" notice, this list of conditions and the following disclaimer.
|
||||||
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||||
|
.\" notice, this list of conditions and the following disclaimer in the
|
||||||
|
.\" documentation and/or other materials provided with the distribution.
|
||||||
|
.\"
|
||||||
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
||||||
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||||
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||||
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
||||||
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||||
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||||
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||||
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||||
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||||
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||||
|
.\" SUCH DAMAGE.
|
||||||
|
.\"
|
||||||
|
.\" $FreeBSD$
|
||||||
|
.\"
|
||||||
|
.Dd August 12, 2018
|
||||||
|
.Dt EFIRT 9
|
||||||
|
.Os
|
||||||
|
.Sh NAME
|
||||||
|
.Nm efirt ,
|
||||||
|
.Nm efi_rt_ok ,
|
||||||
|
.Nm efi_get_table ,
|
||||||
|
.Nm efi_get_time ,
|
||||||
|
.Nm efi_get_time_capabilities ,
|
||||||
|
.Nm efi_reset_system ,
|
||||||
|
.Nm efi_set_time ,
|
||||||
|
.Nm efi_var_get ,
|
||||||
|
.Nm efi_var_nextname ,
|
||||||
|
.Nm efi_var_set
|
||||||
|
.Nd kernel access to UEFI runtime services
|
||||||
|
.Sh SYNOPSIS
|
||||||
|
.Cd "options EFIRT"
|
||||||
|
.Pp
|
||||||
|
.In sys/efi.h
|
||||||
|
.Ft int
|
||||||
|
.Fn efi_rt_ok "void"
|
||||||
|
.Ft int
|
||||||
|
.Fn efi_get_table "struct uuid *uuid" "void **ptr"
|
||||||
|
.Ft int
|
||||||
|
.Fn efi_get_time "struct efi_tm *tm"
|
||||||
|
.Ft int
|
||||||
|
.Fn efi_get_time_capabilities "struct efi_tmcap *tmcap"
|
||||||
|
.Ft int
|
||||||
|
.Fn efi_reset_system "void"
|
||||||
|
.Ft int
|
||||||
|
.Fn efi_set_time "struct efi_tm *tm"
|
||||||
|
.Ft int
|
||||||
|
.Fn efi_var_get "uint16_t *name" "struct uuid *vendor" "uint32_t *attrib" \
|
||||||
|
"size_t *datasize" "void *data"
|
||||||
|
.Ft int
|
||||||
|
.Fn efi_var_nextname "size_t *namesize" "uint16_t *name" "struct uuid *vendor"
|
||||||
|
.Ft int
|
||||||
|
.Fn efi_var_set "uint16_t *name" "struct uuid *vendor" "uint32_t *attrib" \
|
||||||
|
"size_t *datasize" "void *data"
|
||||||
|
.Sh DESCRIPTION
|
||||||
|
All of the following calls will return
|
||||||
|
.Dv ENXIO
|
||||||
|
if UEFI runtime services are not available.
|
||||||
|
.Nm
|
||||||
|
is currently only available on amd64 and arm64.
|
||||||
|
.Pp
|
||||||
|
The
|
||||||
|
.Fn efi_rt_ok
|
||||||
|
Returns 0 if UEFI runtime services are present and functional, or
|
||||||
|
.Dv ENXIO
|
||||||
|
if not.
|
||||||
|
.Pp
|
||||||
|
The
|
||||||
|
.Fn efi_get_table
|
||||||
|
function gets a table by uuid from the UEFI system table.
|
||||||
|
Returns 0 if the table was found and populates *ptr with the address.
|
||||||
|
Returns
|
||||||
|
.Dv ENXIO
|
||||||
|
if the configuration table or system table are unset.
|
||||||
|
Returns
|
||||||
|
.Dv ENOENT
|
||||||
|
if the requested table cannot be found.
|
||||||
|
.Pp
|
||||||
|
The
|
||||||
|
.Fn efi_get_time
|
||||||
|
function gets the current time from the RTC, if available.
|
||||||
|
Returns 0 and populates the
|
||||||
|
.Vt struct efi_tm
|
||||||
|
on success.
|
||||||
|
Returns
|
||||||
|
.Dv EINVAL
|
||||||
|
if the
|
||||||
|
.Vt struct efi_tm
|
||||||
|
is
|
||||||
|
.Dv NULL ,
|
||||||
|
or
|
||||||
|
.Dv EIO
|
||||||
|
if the time could not be retrieved due to a hardware error.
|
||||||
|
.Pp
|
||||||
|
The
|
||||||
|
.Fn efi_get_time_capabilities
|
||||||
|
function gets the capabilities from the RTC.
|
||||||
|
Returns 0 and populates the
|
||||||
|
.Vt struct efi_tmcap
|
||||||
|
on success.
|
||||||
|
Returns
|
||||||
|
.Dv EINVAL
|
||||||
|
if the
|
||||||
|
.Vt struct efi_tm
|
||||||
|
is
|
||||||
|
.Dv NULL ,
|
||||||
|
or
|
||||||
|
.Dv EIO
|
||||||
|
if the time could not be retrieved due to a hardware error.
|
||||||
|
.Pp
|
||||||
|
The
|
||||||
|
.Fn efi_reset_system
|
||||||
|
function requests a warm reset and reboot of the system.
|
||||||
|
.Pp
|
||||||
|
The
|
||||||
|
.Fn efi_set_time
|
||||||
|
function sets the time on the RTC to the time described by the
|
||||||
|
.Vt struct efi_tm
|
||||||
|
passed in.
|
||||||
|
Returns 0 on success,
|
||||||
|
.Dv EINVAL
|
||||||
|
if a time field is out of range, or
|
||||||
|
.Dv EIO
|
||||||
|
if the time could not be set due to a hardware error.
|
||||||
|
.Pp
|
||||||
|
The
|
||||||
|
.Fn efi_var_get
|
||||||
|
function fetches the variable identified by
|
||||||
|
.Fa vendor
|
||||||
|
and
|
||||||
|
.Fa name .
|
||||||
|
Returns 0 and populates
|
||||||
|
.Fa attrib ,
|
||||||
|
.Fa datasize ,
|
||||||
|
and
|
||||||
|
.Fa data
|
||||||
|
on success.
|
||||||
|
Otherwise, one of the following errors are returned:
|
||||||
|
.Bl -tag -width ".Dv EOVERFLOW"
|
||||||
|
.It Dv ENOENT
|
||||||
|
The variable was not found.
|
||||||
|
.It Dv EOVERFLOW
|
||||||
|
.Fa datasize
|
||||||
|
is not sufficient to hold the variable data.
|
||||||
|
.Fa namesize
|
||||||
|
is updated to reflect the size needed to complete the request.
|
||||||
|
.It Dv EINVAL
|
||||||
|
One of
|
||||||
|
.Fa name ,
|
||||||
|
.Fa vendor ,
|
||||||
|
or
|
||||||
|
.Fa datasize
|
||||||
|
are NULL.
|
||||||
|
Alternatively,
|
||||||
|
.Fa datasize
|
||||||
|
is large enough to hold the response but
|
||||||
|
.Fa data
|
||||||
|
is NULL.
|
||||||
|
.It Dv EIO
|
||||||
|
The variable could not be retrieved due to a hardware error.
|
||||||
|
.It Dv EDOOFUS
|
||||||
|
The variable could not be retireved due to an authentication failure.
|
||||||
|
.El
|
||||||
|
.Pp
|
||||||
|
The
|
||||||
|
.Fn efi_var_nextname
|
||||||
|
function is used for enumeration of variables.
|
||||||
|
On the initial call to
|
||||||
|
.Fn efi_var_nextname ,
|
||||||
|
.Fa name
|
||||||
|
should be an empty string.
|
||||||
|
Subsequent calls should pass in the last
|
||||||
|
.Fa name
|
||||||
|
and
|
||||||
|
.Fa vendor
|
||||||
|
returned until
|
||||||
|
.Dv ENOENT
|
||||||
|
is returned.
|
||||||
|
Returns 0 and populates
|
||||||
|
.Fa namesize ,
|
||||||
|
.Fa name ,
|
||||||
|
and
|
||||||
|
.Fa vendor
|
||||||
|
with the next variable's data.
|
||||||
|
Otherwise, returns one of the following errors:
|
||||||
|
.Bl -tag -width ".Dv EOVERFLOW"
|
||||||
|
.It Dv ENOENT
|
||||||
|
The next variable was not found.
|
||||||
|
.It Dv EOVERFLOW
|
||||||
|
.Fa datasize
|
||||||
|
is not sufficient to hold the variable data.
|
||||||
|
.Fa namesize
|
||||||
|
is updated to reflect the size needed to complete the request.
|
||||||
|
.It Dv EINVAL
|
||||||
|
One of
|
||||||
|
.Fa name ,
|
||||||
|
.Fa vendor ,
|
||||||
|
or
|
||||||
|
.Fa datasize
|
||||||
|
are NULL.
|
||||||
|
.It Dv EIO
|
||||||
|
The variable could not be retrieved due to a hardware error.
|
||||||
|
.El
|
||||||
|
.Pp
|
||||||
|
The
|
||||||
|
.Fn efi_var_set
|
||||||
|
function sets the variable described by
|
||||||
|
.Fa name
|
||||||
|
and
|
||||||
|
.Fa vendor .
|
||||||
|
Returns 0 if the variable has been successfully.
|
||||||
|
Otherwise, returns one of the following errors:
|
||||||
|
.Bl -tag -width ".Dv EOVERFLOW"
|
||||||
|
.It Dv EINVAL
|
||||||
|
Either
|
||||||
|
.Fa attrib
|
||||||
|
was an invalid combination of attributes,
|
||||||
|
.Fa datasize
|
||||||
|
exceeds the maximum allowed size, or
|
||||||
|
.Fa name
|
||||||
|
is an empty Unicode stirng.
|
||||||
|
.It Dv EAGAIN
|
||||||
|
Not enough storage is available to hold the variable and its data.
|
||||||
|
.It Dv EIO
|
||||||
|
The variable could not be saved due to a hardware error.
|
||||||
|
.It Dv EROFS
|
||||||
|
The variable in question is read-only or may not be deleted.
|
||||||
|
.It Dv EDOOFUS
|
||||||
|
The varialbe could not be set due to an authentication failure.
|
||||||
|
.It Dv ENOENT
|
||||||
|
The variable trying to be updated or deleted was not found.
|
||||||
|
.El
|
||||||
|
.Sh SEE ALSO
|
||||||
|
.Xr efidev 4
|
||||||
|
.Sh AUTHORS
|
||||||
|
This manual page was written by
|
||||||
|
.An Kyle Evans Aq Mt kevans@FreeBSD.org .
|
Loading…
Reference in a new issue