| Message ID | 20240419065542.1160527-3-sughosh.ganu@linaro.org |
|---|---|
| State | New |
| Headers | show |
| Series | Generate capsules from config files | expand |
On 19.04.24 08:55, Sughosh Ganu wrote: > The UEFI capsule can now be generated by specifying the capsule > parameters through a config file. Highlight these changes in the > documentation. > > Signed-off-by: Sughosh Ganu <sughosh.ganu@linaro.org> > --- > doc/develop/uefi/uefi.rst | 70 +++++++++++++++++++++++++++++++++++++++ > 1 file changed, 70 insertions(+) > > diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst > index 0389b269c0..8586127a83 100644 > --- a/doc/develop/uefi/uefi.rst > +++ b/doc/develop/uefi/uefi.rst > @@ -318,6 +318,76 @@ Run the following command > --guid <image GUID> \ > <capsule_file_name> The users deserve a man-page mkeficapsule.1 that can be installed by distros as /usr/share/doc/man/man1/mkeficapsule.1. Do not expect the user to look up the information online. > > +Alternatively, the capsules can be generated through a config > +file. When generating the capsules through a config file, the Kconfig > +symbol CONFIG_EFI_CAPSULE_CFG_FILE is to be used for specifying the > +path to the config file. Why do we need CONFIG_EFI_CAPSULE_CFG_FILE? You could use a fixed path or an environment parameter. > + > +The config file describes the parameters that are used for generating > +one or more capsules. The parameters for a given capsule file are > +specified within curly braces, in the form of "key:value" pairs. All > +the parameters that are currently supported by the mkeficapsule tool > +can be specified through the config file. > + > +The following are some example payload parameters specified through > +the config file. > + > +.. code-block:: none > + > + { > + image-guid: 02f4d760-cfd5-43bd-8e2d-a42acb33c660 > + hardware-instance: 0 > + monotonic-count: 1 > + payload: u-boot.bin > + image-index: 1 > + fw-version: 2 > + private-key: /path/to/priv/key > + pub-key-cert: /path/to/pub/key > + capsule: u-boot.capsule > + } > + { > + image-guid: 4ce292da-1dd8-428d-a1c2-77743ef8b96e > + hardware-instance: 0 > + payload: u-boot.itb > + image-index: 2 > + fw-version: 7 > + oemflags: 0x8000 > + capsule: fit.capsule > + } > + { > + capsule-type: accept > + image-guid: 4ce292da-1dd8-428d-a1c2-77743ef8b96e > + capsule: accept.capsule > + } > + { > + capsule-type: revert > + capsule: revert.capsule > + } Is this one file? Are these multiple files? If these are multiple files, please, put them in different code blocks. What are the curly braces good for? Please, use an established file format like YAML or JSON. > + > +The following are the keys that specify the capsule parameters > + > +..code-block:: none > + > + image-guid: Image GUID Please use the following formatting: image-guid Image GUID fw-version Image version > + image-index: Image index value > + fw-version: Image version > + private-key: Path to the private key file used for capsule signing > + pub-key-cert: Path to the public key crt file used for capsule signing > + payload: Path to the capsule payload file > + capsule: Path to the output capsule file that is generated > + hardware-instance: Hardware Instance value Please, explain what a hardware instance is. > + monotonic-count: Monotonic count value Please, explain what it is used for. > + capsule-type: Specifies capsule type. normal(default), accept or revert ditto > + oemflags: 16bit Oemflags value to be used(populated in capsule header) ditto > + > +When generating capsules through a config file, the command would look > +like > + > +.. code-block:: console > + > + $ mkeficapsule --cfg-file </path/to/the/config/file> All available command line parameters of mkeficapsule should be described in one place. Best regards Heinrich > + > + > Capsule with firmware version > ***************************** >
hi Heinrich, On Fri, 19 Apr 2024 at 13:01, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote: > > On 19.04.24 08:55, Sughosh Ganu wrote: > > The UEFI capsule can now be generated by specifying the capsule > > parameters through a config file. Highlight these changes in the > > documentation. > > > > Signed-off-by: Sughosh Ganu <sughosh.ganu@linaro.org> > > --- > > doc/develop/uefi/uefi.rst | 70 +++++++++++++++++++++++++++++++++++++++ > > 1 file changed, 70 insertions(+) > > > > diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst > > index 0389b269c0..8586127a83 100644 > > --- a/doc/develop/uefi/uefi.rst > > +++ b/doc/develop/uefi/uefi.rst > > @@ -318,6 +318,76 @@ Run the following command > > --guid <image GUID> \ > > <capsule_file_name> > > The users deserve a man-page mkeficapsule.1 that can be installed by > distros as /usr/share/doc/man/man1/mkeficapsule.1. > > Do not expect the user to look up the information online. Will add a man-page. > > > > > +Alternatively, the capsules can be generated through a config > > +file. When generating the capsules through a config file, the Kconfig > > +symbol CONFIG_EFI_CAPSULE_CFG_FILE is to be used for specifying the > > +path to the config file. > > Why do we need CONFIG_EFI_CAPSULE_CFG_FILE? You could use a fixed path > or an environment parameter. Will remove the config flags. > > > + > > +The config file describes the parameters that are used for generating > > +one or more capsules. The parameters for a given capsule file are > > +specified within curly braces, in the form of "key:value" pairs. All > > +the parameters that are currently supported by the mkeficapsule tool > > +can be specified through the config file. > > + > > +The following are some example payload parameters specified through > > +the config file. > > + > > +.. code-block:: none > > + > > + { > > + image-guid: 02f4d760-cfd5-43bd-8e2d-a42acb33c660 > > + hardware-instance: 0 > > + monotonic-count: 1 > > + payload: u-boot.bin > > + image-index: 1 > > + fw-version: 2 > > + private-key: /path/to/priv/key > > + pub-key-cert: /path/to/pub/key > > + capsule: u-boot.capsule > > + } > > + { > > + image-guid: 4ce292da-1dd8-428d-a1c2-77743ef8b96e > > + hardware-instance: 0 > > + payload: u-boot.itb > > + image-index: 2 > > + fw-version: 7 > > + oemflags: 0x8000 > > + capsule: fit.capsule > > + } > > + { > > + capsule-type: accept > > + image-guid: 4ce292da-1dd8-428d-a1c2-77743ef8b96e > > + capsule: accept.capsule > > + } > > + { > > + capsule-type: revert > > + capsule: revert.capsule > > + } > > Is this one file? Are these multiple files? If these are multiple files, > please, put them in different code blocks. These are multiple files. But eventually, we will be using this feature to generate a multi-payload capsule. Again, this is on similar lines to how this is done with the EDKII script. > > What are the curly braces good for? Please, use an established file > format like YAML or JSON. As discussed over IRC, I will check if I can use the YAML format and keep the format similar to the one used above -- in key:value pairs. I would prefer keeping the format similar to what is used in the EDKII capsule generation tool. But if I can use the mapping node type in YAML for providing this information, I will explore using YAML with the libcyaml library for parsing the configs. > > > + > > +The following are the keys that specify the capsule parameters > > + > > +..code-block:: none > > + > > + image-guid: Image GUID > > Please use the following formatting: > > image-guid > Image GUID > > fw-version > Image version I have kept the format similar to what is used in EDKII. > > > + image-index: Image index value > > + fw-version: Image version > > + private-key: Path to the private key file used for capsule signing > > + pub-key-cert: Path to the public key crt file used for capsule signing > > + payload: Path to the capsule payload file > > + capsule: Path to the output capsule file that is generated > > + hardware-instance: Hardware Instance value > > Please, explain what a hardware instance is. Okay > > > + monotonic-count: Monotonic count value > > Please, explain what it is used for. Okay > > > + capsule-type: Specifies capsule type. normal(default), accept or revert > > ditto > > > + oemflags: 16bit Oemflags value to be used(populated in capsule header) > > ditto > > > + > > +When generating capsules through a config file, the command would look > > +like > > + > > +.. code-block:: console > > + > > + $ mkeficapsule --cfg-file </path/to/the/config/file> > > All available command line parameters of mkeficapsule should be > described in one place. Will fix -sughosh > > Best regards > > Heinrich > > > + > > + > > Capsule with firmware version > > ***************************** > > >
diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst index 0389b269c0..8586127a83 100644 --- a/doc/develop/uefi/uefi.rst +++ b/doc/develop/uefi/uefi.rst @@ -318,6 +318,76 @@ Run the following command --guid <image GUID> \ <capsule_file_name> +Alternatively, the capsules can be generated through a config +file. When generating the capsules through a config file, the Kconfig +symbol CONFIG_EFI_CAPSULE_CFG_FILE is to be used for specifying the +path to the config file. + +The config file describes the parameters that are used for generating +one or more capsules. The parameters for a given capsule file are +specified within curly braces, in the form of "key:value" pairs. All +the parameters that are currently supported by the mkeficapsule tool +can be specified through the config file. + +The following are some example payload parameters specified through +the config file. + +.. code-block:: none + + { + image-guid: 02f4d760-cfd5-43bd-8e2d-a42acb33c660 + hardware-instance: 0 + monotonic-count: 1 + payload: u-boot.bin + image-index: 1 + fw-version: 2 + private-key: /path/to/priv/key + pub-key-cert: /path/to/pub/key + capsule: u-boot.capsule + } + { + image-guid: 4ce292da-1dd8-428d-a1c2-77743ef8b96e + hardware-instance: 0 + payload: u-boot.itb + image-index: 2 + fw-version: 7 + oemflags: 0x8000 + capsule: fit.capsule + } + { + capsule-type: accept + image-guid: 4ce292da-1dd8-428d-a1c2-77743ef8b96e + capsule: accept.capsule + } + { + capsule-type: revert + capsule: revert.capsule + } + +The following are the keys that specify the capsule parameters + +..code-block:: none + + image-guid: Image GUID + image-index: Image index value + fw-version: Image version + private-key: Path to the private key file used for capsule signing + pub-key-cert: Path to the public key crt file used for capsule signing + payload: Path to the capsule payload file + capsule: Path to the output capsule file that is generated + hardware-instance: Hardware Instance value + monotonic-count: Monotonic count value + capsule-type: Specifies capsule type. normal(default), accept or revert + oemflags: 16bit Oemflags value to be used(populated in capsule header) + +When generating capsules through a config file, the command would look +like + +.. code-block:: console + + $ mkeficapsule --cfg-file </path/to/the/config/file> + + Capsule with firmware version *****************************
The UEFI capsule can now be generated by specifying the capsule parameters through a config file. Highlight these changes in the documentation. Signed-off-by: Sughosh Ganu <sughosh.ganu@linaro.org> --- doc/develop/uefi/uefi.rst | 70 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+)