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

Julien Stephan
2024-11-05T08:17:57Z

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::
+
+ 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
+ ``<task>``. If it does not exist, BitBake will build the ``<task>`` and
+ the sstate will be used next time.
+
+ Example::
+
+ SIGGEN_LOCKEDSIGS += "bc:do_compile:09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0"
+
+ To obtain the signature, you can dump all ``bc``'s tasks signature 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.
+
+ :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".

--
2.47.0