[PATCH 1/2] docs: filesystems: add info about efivars content

[PATCH 1/2] docs: filesystems: add info about efivars content

[Flavio Suligoi]

When an EFI variable is reading from:

/sys/firmware/efi/efivars

(for example using "hexdump"), the first 4 bytes of the
output are not the real EFI variable data, but the variable
attributes (in little-endian format).

Signed-off-by: Flavio Suligoi <f.suligoi@asem.it>
---
 Documentation/filesystems/efivarfs.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/Documentation/filesystems/efivarfs.rst b/Documentation/filesystems/efivarfs.rst
index 90ac656..6380336 100644
--- a/Documentation/filesystems/efivarfs.rst
+++ b/Documentation/filesystems/efivarfs.rst
@@ -24,3 +24,20 @@ files that are not well-known standardized variables are created
 as immutable files.  This doesn't prevent removal - "chattr -i" will work -
 but it does prevent this kind of failure from being accomplished
 accidentally.
+
+.. warning ::
+      When a content of an UEFI variable in ``/sys/firmware/efi/efivars`` is
+      displayed, for example using ``hexdump``, pay attention that the first
+      4 bytes of the output represent the UEFI variable attributes,
+      in little-endian format.
+
+      Practically the output of each ``efivar`` is composed of:
+
+          +-----------------------------------+
+          |4_bytes_of_attributes + efivar_data|
+          +-----------------------------------+
+
+*See also:*
+
+- ``Documentation/admin-guide/acpi/ssdt-overlays.rst``
+- ``Documentation/ABI/stable/sysfs-firmware-efi-vars``
-- 
2.7.4

[PATCH 2/2] docs: acpi: fix old http link and improve document format

[Flavio Suligoi]

The website:

    http://wiki.minnowboard.org

doesn't exist anymore. The same pages are moved to:

    https://www.elinux.org/Minnowboard

Other improvements concern the introduction of some rst
semantic markup in the document.

Signed-off-by: Flavio Suligoi <f.suligoi@asem.it>
---
 Documentation/admin-guide/acpi/ssdt-overlays.rst | 40 ++++++++++++------------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/Documentation/admin-guide/acpi/ssdt-overlays.rst b/Documentation/admin-guide/acpi/ssdt-overlays.rst
index da37455..5c090da 100644
--- a/Documentation/admin-guide/acpi/ssdt-overlays.rst
+++ b/Documentation/admin-guide/acpi/ssdt-overlays.rst
@@ -63,7 +63,7 @@ which can then be compiled to AML binary format::
     ASL Input:     minnomax.asl - 30 lines, 614 bytes, 7 keywords
     AML Output:    minnowmax.aml - 165 bytes, 6 named objects, 1 executable opcodes
 
-[1] http://wiki.minnowboard.org/MinnowBoard_MAX#Low_Speed_Expansion_Connector_.28Top.29
+[1] https://www.elinux.org/Minnowboard:MinnowMax#Low_Speed_Expansion_.28Top.29
 
 The resulting AML code can then be loaded by the kernel using one of the methods
 below.
@@ -76,9 +76,9 @@ when the system does not support EFI or when there is not enough EFI storage.
 
 It works in a similar way with initrd based ACPI tables override/upgrade: SSDT
 aml code must be placed in the first, uncompressed, initrd under the
-"kernel/firmware/acpi" path. Multiple files can be used and this will translate
-in loading multiple tables. Only SSDT and OEM tables are allowed. See
-initrd_table_override.txt for more details.
+``kernel/firmware/acpi`` path. Multiple files can be used and this will
+translate in loading multiple tables. Only SSDT and OEM tables are allowed. See
+``Documentation/admin-guide/acpi/initrd_table_override.rst`` for more details.
 
 Here is an example::
 
@@ -105,21 +105,21 @@ is also work underway to implement EFI support for loading user defined SSDTs
 and using this method will make it easier to convert to the EFI loading
 mechanism when that will arrive.
 
-In order to load SSDTs from an EFI variable the efivar_ssdt kernel command line
-parameter can be used. The argument for the option is the variable name to
+In order to load SSDTs from an EFI variable the ``efivar_ssdt`` kernel command
+line parameter can be used. The argument for the option is the variable name to
 use. If there are multiple variables with the same name but with different
 vendor GUIDs, all of them will be loaded.
 
 In order to store the AML code in an EFI variable the efivarfs filesystem can be
-used. It is enabled and mounted by default in /sys/firmware/efi/efivars in all
-recent distribution.
-
-Creating a new file in /sys/firmware/efi/efivars will automatically create a new
-EFI variable. Updating a file in /sys/firmware/efi/efivars will update the EFI
-variable. Please note that the file name needs to be specially formatted as
-"Name-GUID" and that the first 4 bytes in the file (little-endian format)
-represent the attributes of the EFI variable (see EFI_VARIABLE_MASK in
-include/linux/efi.h). Writing to the file must also be done with one write
+used. It is enabled and mounted by default in ``/sys/firmware/efi/efivars``
+in all recent distribution.
+
+Creating a new file in ``/sys/firmware/efi/efivars`` will automatically create
+a new EFI variable. Updating a file in ``/sys/firmware/efi/efivars`` will update
+the EFI variable. Please note that the file name needs to be specially formatted
+as "Name-GUID" and that the first 4 bytes in the file (little-endian format)
+represent the attributes of the EFI variable (see ``EFI_VARIABLE_MASK`` in
+``include/linux/efi.h``). Writing to the file must also be done with one write
 operation.
 
 For example, you can use the following bash script to create/update an EFI
@@ -168,12 +168,12 @@ Loading ACPI SSDTs from configfs
 ================================
 
 This option allows loading of user defined SSDTs from userspace via the configfs
-interface. The CONFIG_ACPI_CONFIGFS option must be select and configfs must be
-mounted. In the following examples, we assume that configfs has been mounted in
-/config.
+interface. The ``CONFIG_ACPI_CONFIGFS`` option must be select and configfs must
+be mounted. In the following examples, we assume that configfs has been mounted
+in ``/config``.
 
-New tables can be loading by creating new directories in /config/acpi/table/ and
-writing the SSDT aml code in the aml attribute::
+New tables can be loading by creating new directories in ``/config/acpi/table/``
+and writing the SSDT aml code in the aml attribute::
 
     cd /config/acpi/table
     mkdir my_ssdt
-- 
2.7.4

Re: [PATCH 2/2] docs: acpi: fix old http link and improve document format

[Jonathan Corbet]

On Tue, 5 May 2020 12:17:16 +0200
Flavio Suligoi <f.suligoi@asem.it> wrote:

> The website:
> 
>     http://wiki.minnowboard.org
> 
> doesn't exist anymore. The same pages are moved to:
> 
>     https://www.elinux.org/Minnowboard
> 
> Other improvements concern the introduction of some rst
> semantic markup in the document.
> 
> Signed-off-by: Flavio Suligoi <f.suligoi@asem.it>

Thanks for updating the URL.  The markup changes are a bit heavy-handed,
though; could I ask you to redo it without that.  In particular, there is
no real need to put file paths in ``literal text``, but that does clutter
up the reading experience significantly.

Thanks,

jon

[PATCH v1 1/2] docs: filesystems: add info about efivars content

[Flavio Suligoi]

When an EFI variable is reading from:

/sys/firmware/efi/efivars

(for example using "hexdump"), the first 4 bytes of the
output are not the real EFI variable data, but the variable
attributes (in little-endian format).

Signed-off-by: Flavio Suligoi <f.suligoi@asem.it>
---

v1:  remove added backquotes from pathname strings

 Documentation/filesystems/efivarfs.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/Documentation/filesystems/efivarfs.rst b/Documentation/filesystems/efivarfs.rst
index 90ac65683e7e..0551985821b8 100644
--- a/Documentation/filesystems/efivarfs.rst
+++ b/Documentation/filesystems/efivarfs.rst
@@ -24,3 +24,20 @@ files that are not well-known standardized variables are created
 as immutable files.  This doesn't prevent removal - "chattr -i" will work -
 but it does prevent this kind of failure from being accomplished
 accidentally.
+
+.. warning ::
+      When a content of an UEFI variable in /sys/firmware/efi/efivars is
+      displayed, for example using "hexdump", pay attention that the first
+      4 bytes of the output represent the UEFI variable attributes,
+      in little-endian format.
+
+      Practically the output of each efivar is composed of:
+
+          +-----------------------------------+
+          |4_bytes_of_attributes + efivar_data|
+          +-----------------------------------+
+
+*See also:*
+
+- Documentation/admin-guide/acpi/ssdt-overlays.rst
+- Documentation/ABI/stable/sysfs-firmware-efi-vars
-- 
2.17.1

[PATCH v1 2/2] docs: acpi: fix old http link and improve document format

[Flavio Suligoi]

The website:

    http://wiki.minnowboard.org

doesn't exist anymore. The same pages are moved to:

    https://www.elinux.org/Minnowboard

Other improvements concern the introduction of some rst
semantic markup in the document.

Signed-off-by: Flavio Suligoi <f.suligoi@asem.it>
---

v1:  remove added backquotes from pathname strings

 Documentation/admin-guide/acpi/ssdt-overlays.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/admin-guide/acpi/ssdt-overlays.rst b/Documentation/admin-guide/acpi/ssdt-overlays.rst
index da37455f96c9..5d7e25988085 100644
--- a/Documentation/admin-guide/acpi/ssdt-overlays.rst
+++ b/Documentation/admin-guide/acpi/ssdt-overlays.rst
@@ -63,7 +63,7 @@ which can then be compiled to AML binary format::
     ASL Input:     minnomax.asl - 30 lines, 614 bytes, 7 keywords
     AML Output:    minnowmax.aml - 165 bytes, 6 named objects, 1 executable opcodes
 
-[1] http://wiki.minnowboard.org/MinnowBoard_MAX#Low_Speed_Expansion_Connector_.28Top.29
+[1] https://www.elinux.org/Minnowboard:MinnowMax#Low_Speed_Expansion_.28Top.29
 
 The resulting AML code can then be loaded by the kernel using one of the methods
 below.
-- 
2.17.1

Re: [PATCH v1 1/2] docs: filesystems: add info about efivars content

[Jonathan Corbet]

On Tue, 19 May 2020 10:41:27 +0200
Flavio Suligoi <f.suligoi@asem.it> wrote:

> When an EFI variable is reading from:
> 
> /sys/firmware/efi/efivars
> 
> (for example using "hexdump"), the first 4 bytes of the
> output are not the real EFI variable data, but the variable
> attributes (in little-endian format).
> 
> Signed-off-by: Flavio Suligoi <f.suligoi@asem.it>

Both patches applied, thanks.

jon