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

["Antonin Godard" <antonin.godard@bootlin.com>]

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
https://bootlin.com