ref-manual: structure.rst: document missing tmp/ dirs

Document `hosttools/`, `pkgdata/` and add some more information on
`work-shared/`.

Adresses [YOCTO #14543].

Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
(From yocto-docs rev: 259fce03ffab9fb588676c1e150d999d54cf6d85)

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
(cherry picked from commit 372b5b4ca55819c294970b20aa8b8d8167144329)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Steve Sakoman <steve@sakoman.com>

1 files changed, 33 insertions, 2 deletions

diff --git a/documentation/ref-manual/structure.rst b/documentation/ref-manual/structure.rst
index 496fd6ae41..4cf23544db 100644
--- a/documentation/ref-manual/structure.rst
+++ b/documentation/ref-manual/structure.rst
@@ -476,6 +476,30 @@ the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
 section in the Yocto Project Application Development and the Extensible
 Software Development Kit (eSDK) manual.
 
+.. _structure-build-tmp-hosttools:
+
+``build/tmp/hosttools/``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The OpenEmbedded build system uses this directory to create symbolic links to
+some of the host components that are allowed to be called within tasks. These
+are basic components listed in the :ref:`ref-manual/system-requirements:required
+packages for the build host` section. These components are also listed in the
+:term:`HOSTTOOLS` variable and are limited to this list to prevent host
+contamination.
+
+.. _structure-build-tmp-pkgdata:
+
+``build/tmp/pkgdata/``
+~~~~~~~~~~~~~~~~~~~~~~
+
+The OpenEmbedded build system uses this directory to store package metadata
+generated during the :ref:`ref-tasks-packagedata` task. The files stored in this
+directory contain information about each output package produced by the
+OpenEmbedded build system, and are used in different ways by the build system
+such as ":ref:`dev-manual/debugging:viewing package information with
+\`\`oe-pkgdata-util\`\``".
+
 .. _structure-build-tmp-sstate-control:
 
 ``build/tmp/sstate-control/``
@@ -649,8 +673,15 @@ Here are key subdirectories within each recipe work directory:
 
 For efficiency, the OpenEmbedded build system creates and uses this
 directory to hold recipes that share a work directory with other
-recipes. In practice, this is only used for ``gcc`` and its variants
-(e.g. ``gcc-cross``, ``libgcc``, ``gcc-runtime``, and so forth).
+recipes. This is for example used for ``gcc`` and its variants (e.g.
+``gcc-cross``, ``libgcc``, ``gcc-runtime``, and so forth), or by the
+:ref:`ref-classes-kernel` class to make the kernel source code and kernel build
+artifacts available to out-of-tree kernel modules or other kernel-dependent
+recipes.
+
+In practice, only a few recipes make use of the ``work-shared`` directory. This
+directory is especially useful for recipes that would induce a lot of storage
+space if they were to be shared with the standard :term:`Sysroot` mechanism.
 
 .. _structure-meta: