MIME-Version: 1.0
References: <20230123081905.27283-1-johan+linaro@kernel.org>
In-Reply-To: <20230123081905.27283-1-johan+linaro@kernel.org>
From:   Ard Biesheuvel <ardb@kernel.org>
Date:   Mon, 23 Jan 2023 09:39:41 +0100
Message-ID: <CAMj1kXGPo4-igHOseNhvoBuS0O2YLd+e=cqD8RJJYSgP0zTi0Q@mail.gmail.com>
Subject: Re: [PATCH v2] efi: drop obsolete efivars sysfs documentation
To:     Johan Hovold <johan+linaro@kernel.org>
Cc:     Jonathan Corbet <corbet@lwn.net>,
        kernel test robot <lkp@intel.com>, linux-efi@vger.kernel.org,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
Content-Type: text/plain; charset="UTF-8"
Precedence: bulk

On Mon, 23 Jan 2023 at 09:19, Johan Hovold <johan+linaro@kernel.org> wrote:
>
> The efivars sysfs interface was removed by commit 0f5b2c69a4cb ("efi:
> vars: Remove deprecated 'efivars' sysfs interface").
>
> Remove also the corresponding sysfs ABI documentation.
>
> Signed-off-by: Johan Hovold <johan+linaro@kernel.org>
> ---
>
> Changes in v2
>  - drop reference in gsmi sysfs documentation
>  - drop reference in efivarfs.rst (kernel test robot)
>

Ugh. So there is a remaining implementation of that interface. That is
a bit disappointing, tbh.

So for now, let's disregard this patch, and I will check internally
whether or not that sysfs gsmi interface is actually used. If it is,
the docs should be kept but updated to clarify that it only describes
gsmi sysfs. Otherwise, we can drop the whole thing, including the gsmi
sysfs pieces themselves.

>
>  .../ABI/stable/sysfs-firmware-efi-vars        | 79 -------------------
>  Documentation/ABI/testing/sysfs-firmware-gsmi |  8 --
>  Documentation/filesystems/efivarfs.rst        |  1 -
>  3 files changed, 88 deletions(-)
>  delete mode 100644 Documentation/ABI/stable/sysfs-firmware-efi-vars
>
> diff --git a/Documentation/ABI/stable/sysfs-firmware-efi-vars b/Documentation/ABI/stable/sysfs-firmware-efi-vars
> deleted file mode 100644
> index 46ccd233e359..000000000000
> --- a/Documentation/ABI/stable/sysfs-firmware-efi-vars
> +++ /dev/null
> @@ -1,79 +0,0 @@
> -What:          /sys/firmware/efi/vars
> -Date:          April 2004
> -Contact:       Matt Domsch <Matt_Domsch@dell.com>
> -Description:
> -               This directory exposes interfaces for interactive with
> -               EFI variables.  For more information on EFI variables,
> -               see 'Variable Services' in the UEFI specification
> -               (section 7.2 in specification version 2.3 Errata D).
> -
> -               In summary, EFI variables are named, and are classified
> -               into separate namespaces through the use of a vendor
> -               GUID.  They also have an arbitrary binary value
> -               associated with them.
> -
> -               The efivars module enumerates these variables and
> -               creates a separate directory for each one found.  Each
> -               directory has a name of the form "<key>-<vendor guid>"
> -               and contains the following files:
> -
> -               =============== ========================================
> -               attributes:     A read-only text file enumerating the
> -                               EFI variable flags.  Potential values
> -                               include:
> -
> -                               EFI_VARIABLE_NON_VOLATILE
> -                               EFI_VARIABLE_BOOTSERVICE_ACCESS
> -                               EFI_VARIABLE_RUNTIME_ACCESS
> -                               EFI_VARIABLE_HARDWARE_ERROR_RECORD
> -                               EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS
> -
> -                               See the EFI documentation for an
> -                               explanation of each of these variables.
> -
> -               data:           A read-only binary file that can be read
> -                               to attain the value of the EFI variable
> -
> -               guid:           The vendor GUID of the variable.  This
> -                               should always match the GUID in the
> -                               variable's name.
> -
> -               raw_var:        A binary file that can be read to obtain
> -                               a structure that contains everything
> -                               there is to know about the variable.
> -                               For structure definition see "struct
> -                               efi_variable" in the kernel sources.
> -
> -                               This file can also be written to in
> -                               order to update the value of a variable.
> -                               For this to work however, all fields of
> -                               the "struct efi_variable" passed must
> -                               match byte for byte with the structure
> -                               read out of the file, save for the value
> -                               portion.
> -
> -                               **Note** the efi_variable structure
> -                               read/written with this file contains a
> -                               'long' type that may change widths
> -                               depending on your underlying
> -                               architecture.
> -
> -               size:           As ASCII representation of the size of
> -                               the variable's value.
> -               =============== ========================================
> -
> -
> -               In addition, two other magic binary files are provided
> -               in the top-level directory and are used for adding and
> -               removing variables:
> -
> -               =============== ========================================
> -               new_var:        Takes a "struct efi_variable" and
> -                               instructs the EFI firmware to create a
> -                               new variable.
> -
> -               del_var:        Takes a "struct efi_variable" and
> -                               instructs the EFI firmware to remove any
> -                               variable that has a matching vendor GUID
> -                               and variable key name.
> -               =============== ========================================
> diff --git a/Documentation/ABI/testing/sysfs-firmware-gsmi b/Documentation/ABI/testing/sysfs-firmware-gsmi
> index 7a558354c1ee..60fe880b5b44 100644
> --- a/Documentation/ABI/testing/sysfs-firmware-gsmi
> +++ b/Documentation/ABI/testing/sysfs-firmware-gsmi
> @@ -16,14 +16,6 @@ Description:
>
>                 Layout:
>
> -               /sys/firmware/gsmi/vars:
> -
> -                       This directory has the same layout (and
> -                       underlying implementation as /sys/firmware/efi/vars.
> -                       See `Documentation/ABI/*/sysfs-firmware-efi-vars`
> -                       for more information on how to interact with
> -                       this structure.
> -
>                 /sys/firmware/gsmi/append_to_eventlog - write-only:
>
>                         This file takes a binary blob and passes it onto
> diff --git a/Documentation/filesystems/efivarfs.rst b/Documentation/filesystems/efivarfs.rst
> index 0551985821b8..164611ce6f2c 100644
> --- a/Documentation/filesystems/efivarfs.rst
> +++ b/Documentation/filesystems/efivarfs.rst
> @@ -40,4 +40,3 @@ accidentally.
>  *See also:*
>
>  - Documentation/admin-guide/acpi/ssdt-overlays.rst
> -- Documentation/ABI/stable/sysfs-firmware-efi-vars
> --
> 2.39.1
>