Add efidev.4 and efirt.9 manual pages from FreeBSD.
authorSascha Wildner <saw@online.de>
Fri, 14 Dec 2018 23:56:19 +0000 (00:56 +0100)
committerSascha Wildner <saw@online.de>
Fri, 14 Dec 2018 23:56:19 +0000 (00:56 +0100)
lib/libefivar/efivar.3
share/man/man4/Makefile
share/man/man4/efidev.4 [new file with mode: 0644]
share/man/man9/Makefile
share/man/man9/efirt.9 [new file with mode: 0644]

index a017981..a988373 100644 (file)
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD: head/lib/libefivar/efivar.3 307071 2016-10-11 22:30:41Z imp $
 .\"
-.Dd September 14, 2016
+.Dd December 15, 2018
 .Dt LIBEFIVAR 3
 .Os
 .Sh NAME
@@ -92,6 +92,7 @@ and
 .Fn efi_guid_to_symbol
 This function is not actually implemented.
 .Sh SEE ALSO
+.Xr efidev 4 ,
 .Xr efivar 8
 .Sh AUTHORS
 .An -nosplit
index 4fffa43..d6e41f3 100644 (file)
@@ -88,6 +88,7 @@ MAN=  aac.4 \
        drm.4 \
        dummynet.4 \
        ecc.4 \
+       efidev.4 \
        ehci.4 \
        em.4 \
        ena.4 \
@@ -434,6 +435,7 @@ MLINKS+=cue.4 if_cue.4
 MLINKS+=dc.4 if_dc.4
 MLINKS+=disc.4 if_disc.4
 MLINKS+=dm.4 dm_target_linear.4
+MLINKS+=efidev.4 efirtc.4
 MLINKS+=em.4 emx.4 \
        em.4 if_em.4 \
        em.4 if_emx.4
diff --git a/share/man/man4/efidev.4 b/share/man/man4/efidev.4
new file mode 100644 (file)
index 0000000..2c17b79
--- /dev/null
@@ -0,0 +1,147 @@
+.\"-
+.\" 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: head/share/man/man4/efidev.4 338121 2018-08-20 22:16:15Z 0mp $
+.\"
+.Dd December 15, 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
+.\"The driver may be disabled by setting the
+.\".Xr loader 8
+.\"tunable
+.\".Va efi.rt.disabled
+.\"to
+.\".Dq Li 1 .
+.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 indent
+.It Dv EFIIOC_GET_TABLE Pq Vt "struct efi_get_table_ioc"
+Get a table by uuid from the UEFI system table.
+.Bd -literal -offset indent
+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 -offset indent
+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
+.Fa data
+field.
+.Dv EFIIOC_VAR_GET Pq Vt "struct efi_var_ioc"
+will also populate the
+.Fa 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 .
+.\".Sh BUGS
+.\".Nm
+.\"is currently only available on amd64 and arm64.
index 0bc3ee9..0bea286 100644 (file)
@@ -79,6 +79,7 @@ MAN=  accept_filter.9 \
        devtoname.9 \
        driver.9 \
        DRIVER_MODULE.9 \
+       efirt.9 \
        errno.9 \
        EVENTHANDLER.9 \
        extattr.9 \
@@ -476,6 +477,13 @@ MLINKS+=devstat.9 devicestat.9 \
        devstat.9 devstat_remove_entry.9 \
        devstat.9 devstat_start_transaction.9
 MLINKS+=DRIVER_MODULE.9 DRIVER_MODULE_ORDERED.9
+MLINKS+=efirt.9 efi_get_table.9 \
+       efirt.9 efi_get_time.9 \
+       efirt.9 efi_reset_system.9 \
+       efirt.9 efi_set_time.9 \
+       efirt.9 efi_var_get.9 \
+       efirt.9 efi_var_nextname.9 \
+       efirt.9 efi_var_set.9
 MLINKS+=EVENTHANDLER.9 EVENTHANDLER_DECLARE.9 \
        EVENTHANDLER.9 EVENTHANDLER_DEREGISTER.9 \
        EVENTHANDLER.9 eventhandler_deregister.9 \
diff --git a/share/man/man9/efirt.9 b/share/man/man9/efirt.9
new file mode 100644 (file)
index 0000000..52b138c
--- /dev/null
@@ -0,0 +1,254 @@
+.\"-
+.\" 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: head/share/man/man9/efirt.9 337957 2018-08-17 04:17:51Z kevans $
+.\"
+.Dd December 15, 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_locked "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_set_time_locked "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 .