[PATCH 1/2] ref-manual: document SPLASH variable

[PATCH 1/2] ref-manual: document SPLASH variable

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/ref-manual/features.rst  | 2 +-
 documentation/ref-manual/variables.rst | 6 ++++++
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/documentation/ref-manual/features.rst b/documentation/ref-manual/features.rst
index 5a064329f1..d6307f1a2f 100644
--- a/documentation/ref-manual/features.rst
+++ b/documentation/ref-manual/features.rst
@@ -344,7 +344,7 @@ Here are the image features available for all images:
 -  *splash:* Enables showing a splash screen during boot. By default,
    this screen is provided by ``psplash``, which does allow
    customization. If you prefer to use an alternative splash screen
-   package, you can do so by setting the ``SPLASH`` variable to a
+   package, you can do so by setting the :term:`SPLASH` variable to a
    different package name (or names) within the image recipe or at the
    distro configuration level.
 
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index e213478326..6680322f4c 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -7820,6 +7820,12 @@ system and gives an overview of their function and contents.
       certificate stored in the :term:`SPL_SIGN_KEYDIR` directory, you will 
       have to set :term:`SPL_SIGN_KEYNAME` to ``dev``.
 
+   :term:`SPLASH`
+      This variable, used by the :ref:`ref-classes-image` class, allows
+      to choose splashscreen applications. Set it to the names of packages
+      for such applications to use. This variable is set by default to
+      ``psplash``.
+
    :term:`SRCREV_FORMAT`
       See :term:`bitbake:SRCREV_FORMAT` in the BitBake manual.
 
-- 
2.34.1

[PATCH 2/2] manuals: document SPLASH_IMAGES variable

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 .../dev-manual/custom-distribution.rst        |  9 +++---
 documentation/ref-manual/variables.rst        | 32 +++++++++++++++++++
 2 files changed, 37 insertions(+), 4 deletions(-)

diff --git a/documentation/dev-manual/custom-distribution.rst b/documentation/dev-manual/custom-distribution.rst
index e5b1ad777a..47faed0d04 100644
--- a/documentation/dev-manual/custom-distribution.rst
+++ b/documentation/dev-manual/custom-distribution.rst
@@ -98,11 +98,12 @@ layer. The following steps provide some more detail:
 
    -  Add any image recipes that are specific to your distribution.
 
-   -  Add a ``psplash`` append file for a branded splash screen. For
-      information on append files, see the
-      ":ref:`dev-manual/layers:appending other layers metadata with your layer`"
-      section.
+   -  Add a ``psplash`` append file for a branded splash screen, using
+      the :term:`SPLASH_IMAGES` variable.
 
    -  Add any other append files to make custom changes that are
       specific to individual recipes.
 
+   For information on append files, see the
+   ":ref:`dev-manual/layers:appending other layers metadata with your layer`"
+   section.
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 6680322f4c..6a7888ab47 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -7826,6 +7826,38 @@ system and gives an overview of their function and contents.
       for such applications to use. This variable is set by default to
       ``psplash``.
 
+   :term:`SPLASH_IMAGES`
+      This variable, used by the ``psplash`` recipe, allows to customize
+      the default splashscreen image.
+
+      Specified images in PNG format are converted to ``.h`` files by the recipe,
+      and are included in the ``psplash`` binary, so you won't find them in
+      the root filesystem.
+
+      To make such a change, it is recommended to customize the
+      ``psplash`` recipe in a custom layer. Here is an example structure for
+      an ``ACME`` board::
+
+          meta-acme/recipes-core/psplash
+          ├── files
+          │   └── logo-acme.png
+          └── psplash_%.bbappend
+
+      And here are the contents of the ``psplash_%.bbappend`` file in
+      this example::
+
+          SPLASH_IMAGES = "file://logo-acme.png;outsuffix=default"
+          FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
+
+      You could even add specific configuration options for ``psplash``,
+      for example::
+
+          EXTRA_OECONF += "--disable-startup-msg --enable-img-fullscreen"
+
+      For information on append files, see the                                                                            
+      ":ref:`dev-manual/layers:appending other layers metadata with your layer`"
+      section.
+
    :term:`SRCREV_FORMAT`
       See :term:`bitbake:SRCREV_FORMAT` in the BitBake manual.
 
-- 
2.34.1