| Message ID | 20241105-add-bblock-documentation-v3-2-b870ded39a2d@baylibre.com |
|---|---|
| State | New |
| Headers | show |
| Series | Add bblock documentation | expand |
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
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".
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(+)