Re: [docs] [PATCH v3 2/3] ref-manual: variables: add SIGGEN_LOCKEDSIGS* variables

Antonin Godard
2024-11-06T07:31:24Z

Hi Julien,

On Tue Nov 5, 2024 at 9:17 AM CET, Julien Stephan wrote:
> Variables SIGGEN_LOCKEDSIGS, SIGGEN_LOCKEDSIGS_TASKSIG_CHECK and
> SIGGEN_LOCKEDSIGS_TYPES are used to lock specific tasks to specific
> signatures. They are used by bitbake -S <lockedsigs> and bblock, so add
> documentation for them.
>
> Signed-off-by: Julien Stephan <jstephan@baylibre.com>
> ---
> documentation/ref-manual/variables.rst | 44 ++++++++++++++++++++++++++++++++++
> 1 file changed, 44 insertions(+)
>
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 07ed143ac5606617c720301ac6621355a341f90a..b24286813eafaa562f4ebd070190f1e97e0cf23c 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -7880,6 +7880,50 @@ system and gives an overview of their function and contents.
> might break at runtime if the interface of the recipe was changed
> after the other had been built.
>
> + :term:`SIGGEN_LOCKEDSIGS`
> + The list of locked taks, with the form::

s/taks/tasks/

> +
> + SIGGEN_LOCKEDSIGS += "<package>:<task>:<signature>"
> +
> + If ``<signature>`` exists for the specified ``<task>`` and ``<package>``
> + in sstate, BitBake will use the cached output instead of rebuilding the

s/in sstate/in the sstate cache/ to use "the sstate cache" everywhere.

> + ``<task>``. If it does not exist, BitBake will build the ``<task>`` and
> + the sstate will be used next time.

s/the sstate/the sstate cache/

> +
> + Example::
> +
> + SIGGEN_LOCKEDSIGS += "bc:do_compile:09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0"
> +
> + To obtain the signature, you can dump all ``bc``'s tasks signature using::

To avoid repeating "signature" here, what about:

"""
You can obtain the signature of all the tasks for the recipe ``bc`` using::
"""

> +
> + bitbake -S none bc
> +
> + Then you can look at files in ``build/stamps/<arch>/bc`` and search for the
> + file: ``<PV>.do_compile.sigdata.09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0``.
> +
> + :term:`SIGGEN_LOCKEDSIGS_TASKSIG_CHECK`
> + Specifies the debug level of task signature check. 3 levels are supported:
> +
> + * ``info``: displays a "Note" message to remind the user that a task is locked
> + and the current signature matches the locked one.
> + * ``warn``: displays a "Warning" message if a task is locked and the current
> + signature does not match the locked one.
> + * ``error``: same as warn but displays an “Error” message and aborts.

Nit but the quotes here are different from the ones above (“” != "").

> +
> + :term:`SIGGEN_LOCKEDSIGS_TYPES`
> + Allowed overrides for :term:`SIGGEN_LOCKEDSIGS`. This is mainly used
> + for architecture specific locks. A common value for
> + :term:`SIGGEN_LOCKEDSIGS_TYPES` is ``${PACKAGE_ARCHS}``::
> +
> + SIGGEN_LOCKEDSIGS_TYPES += "${PACKAGE_ARCHS}"
> +
> + SIGGEN_LOCKEDSIGS_core2-64 += "bc:do_compile:09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0"
> + SIGGEN_LOCKEDSIGS_cortexa57 += "bc:do_compile:12178eb6d55ef602a8fe638e49862fd247e07b228f0f08967697b655bfe4bb61"
> +
> + Here, the ``do_compile`` task from ``bc`` will be locked only for
> + ``core2-64`` and ``cortexa57`` but not for other architectures such as
> + ``mips32r2``.
> +
> :term:`SITEINFO_BITS`
> Specifies the number of bits for the target system CPU. The value
> should be either "32" or "64".

Thanks,
Antonin

--
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering