svn commit: r337957 - in head: lib/libefivar share/man/man4 share/man/man9
Kyle Evans
kevans at FreeBSD.org
Fri Aug 17 04:17:53 UTC 2018
Author: kevans
Date: Fri Aug 17 04:17:51 2018
New Revision: 337957
URL: https://svnweb.freebsd.org/changeset/base/337957
Log:
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
Added:
head/share/man/man4/efidev.4 (contents, props changed)
head/share/man/man9/efirt.9 (contents, props changed)
Modified:
head/lib/libefivar/efivar.3
head/share/man/man4/Makefile
head/share/man/man9/Makefile
Modified: head/lib/libefivar/efivar.3
==============================================================================
--- head/lib/libefivar/efivar.3 Fri Aug 17 04:15:51 2018 (r337956)
+++ head/lib/libefivar/efivar.3 Fri Aug 17 04:17:51 2018 (r337957)
@@ -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
Modified: head/share/man/man4/Makefile
==============================================================================
--- head/share/man/man4/Makefile Fri Aug 17 04:15:51 2018 (r337956)
+++ head/share/man/man4/Makefile Fri Aug 17 04:17:51 2018 (r337957)
@@ -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
Added: head/share/man/man4/efidev.4
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/share/man/man4/efidev.4 Fri Aug 17 04:17:51 2018 (r337957)
@@ -0,0 +1,143 @@
+.\"-
+.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
+.\"
+.\" Copyright (c) 2018 Kyle Evans <kevans at 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 .
Modified: head/share/man/man9/Makefile
==============================================================================
--- head/share/man/man9/Makefile Fri Aug 17 04:15:51 2018 (r337956)
+++ head/share/man/man9/Makefile Fri Aug 17 04:17:51 2018 (r337957)
@@ -123,6 +123,7 @@ MAN= accept_filter.9 \
drbr.9 \
driver.9 \
DRIVER_MODULE.9 \
+ efirt.9 \
epoch.9 \
EVENTHANDLER.9 \
eventtimers.9 \
Added: head/share/man/man9/efirt.9
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/share/man/man9/efirt.9 Fri Aug 17 04:17:51 2018 (r337957)
@@ -0,0 +1,250 @@
+.\"-
+.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
+.\"
+.\" Copyright (c) 2018 Kyle Evans <kevans at 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 at FreeBSD.org .
More information about the svn-src-head
mailing list