diff mbox series

[v6,7/8] doc: uefi: add firmware versioning documentation

Message ID 20230519103214.1239656-8-masahisa.kojima@linaro.org
State New
Headers show
Series FMP versioning support | expand

Commit Message

Masahisa Kojima May 19, 2023, 10:32 a.m. UTC
This commit describes the procedure to add the firmware version
into the capsule file.

Signed-off-by: Masahisa Kojima <masahisa.kojima@linaro.org>
---
Newly created in v6

 doc/develop/uefi/uefi.rst | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

Comments

AKASHI Takahiro May 22, 2023, 12:35 a.m. UTC | #1
On Fri, May 19, 2023 at 07:32:13PM +0900, Masahisa Kojima wrote:
> This commit describes the procedure to add the firmware version
> into the capsule file.
> 
> Signed-off-by: Masahisa Kojima <masahisa.kojima@linaro.org>
> ---
> Newly created in v6
> 
>  doc/develop/uefi/uefi.rst | 29 +++++++++++++++++++++++++++++
>  1 file changed, 29 insertions(+)
> 
> diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst
> index ffe25ca231..efab0fc7b1 100644
> --- a/doc/develop/uefi/uefi.rst
> +++ b/doc/develop/uefi/uefi.rst
> @@ -510,6 +510,35 @@ where signature.dts looks like::
>              };
>      };
>  
> +Enabling Firmware Versioning
> +****************************
> +
> +The UEFI specification does not define the firmware versioning mechanism.
> +EDK II reference implementation inserts the FMP Payload Header right before
> +the payload. It coutains the fw_version and lowest supported version,
> +EDK II reference implementation uses these information to implement the
> +firmware versioning and anti-rollback protection, the firmware version and
> +lowest supported version is stored into EFI non-volatile variable.
> +
> +In U-Boot, the firmware versioning is implemented utilizing
> +the FMP Payload Header same as EDK II reference implementation,
> +reads the FMP Payload Header and stores the firmware version into
> +"FmpStateXXXX" EFI non-volatile variable. XXXX indicates the image index,
> +since FMP protocol handles multiple image indexes.

I suggested that you should use "FmState" with the firmware's own guid
as a vendor guid of the variable.
In theory, UEFI may have different FMP drivers, then "index id" may
have the same value for different firmwares.

> +
> +1. Run the following command to add firmware version into the capsule file

Anyhow, you'd better clearly mention that an user needs to specify
"--fw-version" option and what happens (or not happen) if the option
is not there.
I think all the text here can be simply merged in "Creating a capsule file".

-Takahiro Akashi


> +.. code-block:: console
> +
> +    $ mkeficapsule --monotonic-count 1 \
> +      --private-key CRT.key \
> +      --certificate CRT.crt \
> +      --index 1 --instance 0 \
> +      --fw-version 5 \
> +      [--fit | --raw | --guid <guid-string] \
> +      <image_blob> <capsule_file_name>
> +
>  Executing the boot manager
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
> -- 
> 2.17.1
>
Masahisa Kojima May 22, 2023, 4:25 a.m. UTC | #2
Hi Akashi-san,

On Mon, 22 May 2023 at 09:35, Takahiro Akashi
<takahiro.akashi@linaro.org> wrote:
>
> On Fri, May 19, 2023 at 07:32:13PM +0900, Masahisa Kojima wrote:
> > This commit describes the procedure to add the firmware version
> > into the capsule file.
> >
> > Signed-off-by: Masahisa Kojima <masahisa.kojima@linaro.org>
> > ---
> > Newly created in v6
> >
> >  doc/develop/uefi/uefi.rst | 29 +++++++++++++++++++++++++++++
> >  1 file changed, 29 insertions(+)
> >
> > diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst
> > index ffe25ca231..efab0fc7b1 100644
> > --- a/doc/develop/uefi/uefi.rst
> > +++ b/doc/develop/uefi/uefi.rst
> > @@ -510,6 +510,35 @@ where signature.dts looks like::
> >              };
> >      };
> >
> > +Enabling Firmware Versioning
> > +****************************
> > +
> > +The UEFI specification does not define the firmware versioning mechanism.
> > +EDK II reference implementation inserts the FMP Payload Header right before
> > +the payload. It coutains the fw_version and lowest supported version,
> > +EDK II reference implementation uses these information to implement the
> > +firmware versioning and anti-rollback protection, the firmware version and
> > +lowest supported version is stored into EFI non-volatile variable.
> > +
> > +In U-Boot, the firmware versioning is implemented utilizing
> > +the FMP Payload Header same as EDK II reference implementation,
> > +reads the FMP Payload Header and stores the firmware version into
> > +"FmpStateXXXX" EFI non-volatile variable. XXXX indicates the image index,
> > +since FMP protocol handles multiple image indexes.
>
> I suggested that you should use "FmState" with the firmware's own guid
> as a vendor guid of the variable.

Yes, this series uses firmware"s image_type_id as a vendor
guid of the "FmpStateXXXX" variable.

> In theory, UEFI may have different FMP drivers, then "index id" may
> have the same value for different firmwares.
>
> > +
> > +1. Run the following command to add firmware version into the capsule file
>
> Anyhow, you'd better clearly mention that an user needs to specify
> "--fw-version" option and what happens (or not happen) if the option
> is not there.
> I think all the text here can be simply merged in "Creating a capsule file".

OK, I will update.

Thanks,
Masahisa Kojima

>
> -Takahiro Akashi
>
>
> > +.. code-block:: console
> > +
> > +    $ mkeficapsule --monotonic-count 1 \
> > +      --private-key CRT.key \
> > +      --certificate CRT.crt \
> > +      --index 1 --instance 0 \
> > +      --fw-version 5 \
> > +      [--fit | --raw | --guid <guid-string] \
> > +      <image_blob> <capsule_file_name>
> > +
> >  Executing the boot manager
> >  ~~~~~~~~~~~~~~~~~~~~~~~~~~
> >
> > --
> > 2.17.1
> >
diff mbox series

Patch

diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst
index ffe25ca231..efab0fc7b1 100644
--- a/doc/develop/uefi/uefi.rst
+++ b/doc/develop/uefi/uefi.rst
@@ -510,6 +510,35 @@  where signature.dts looks like::
             };
     };
 
+Enabling Firmware Versioning
+****************************
+
+The UEFI specification does not define the firmware versioning mechanism.
+EDK II reference implementation inserts the FMP Payload Header right before
+the payload. It coutains the fw_version and lowest supported version,
+EDK II reference implementation uses these information to implement the
+firmware versioning and anti-rollback protection, the firmware version and
+lowest supported version is stored into EFI non-volatile variable.
+
+In U-Boot, the firmware versioning is implemented utilizing
+the FMP Payload Header same as EDK II reference implementation,
+reads the FMP Payload Header and stores the firmware version into
+"FmpStateXXXX" EFI non-volatile variable. XXXX indicates the image index,
+since FMP protocol handles multiple image indexes.
+
+
+1. Run the following command to add firmware version into the capsule file
+
+.. code-block:: console
+
+    $ mkeficapsule --monotonic-count 1 \
+      --private-key CRT.key \
+      --certificate CRT.crt \
+      --index 1 --instance 0 \
+      --fw-version 5 \
+      [--fit | --raw | --guid <guid-string] \
+      <image_blob> <capsule_file_name>
+
 Executing the boot manager
 ~~~~~~~~~~~~~~~~~~~~~~~~~~