mirror of
https://github.com/freebsd/freebsd-src
synced 2024-07-23 03:06:48 +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:
Kyle Evans
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
|
||||
No facilities exist to process the strings as native UTF.
|
||||
This is a limitation in the Linux libefivar library interface.
|
||||
.Sh SEE ALSO
|
||||
.Xr efidev 4
|
||||
.Sh AUTHORS
|
||||
.An -nosplit
|
||||
This software was originally written by
|
||||
|
|
|
|||
|
|
@ -900,6 +900,12 @@ _dtrace_provs= dtrace_io.4 \
|
|||
dtrace_udplite.4
|
||||
.endif
|
||||
|
||||
.if ${MK_EFI} != "no"
|
||||
MAN+= efidev.4
|
||||
|
||||
MLINKS+= efidev.4 efirtc.4
|
||||
.endif
|
||||
|
||||
.if ${MK_ISCSI} != "no"
|
||||
MAN+= cfiscsi.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 \
|
||||
driver.9 \
|
||||
DRIVER_MODULE.9 \
|
||||
efirt.9 \
|
||||
epoch.9 \
|
||||
EVENTHANDLER.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