Skip site navigation (1)Skip section navigation (2)
Date:      Fri, 17 Aug 2018 04:17:51 +0000 (UTC)
From:      Kyle Evans <kevans@FreeBSD.org>
To:        src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org
Subject:   svn commit: r337957 - in head: lib/libefivar share/man/man4 share/man/man9
Message-ID:  <201808170417.w7H4HpL0046896@repo.freebsd.org>

next in thread | raw e-mail | index | archive | help
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@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@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 .



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201808170417.w7H4HpL0046896>