The splash screen documentation was written when the feature was first added and never kept up with it, so splashpos, splashdevpart, the CONFIG_VIDEO_LOGO fallback, the version banner, the built-in default_splash_locations table and the SPL variants of all of it are undocumented.
Describe them, so that the document covers what the code actually does. Signed-off-by: David Lechner <[email protected]> --- doc/develop/splash.rst | 85 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) diff --git a/doc/develop/splash.rst b/doc/develop/splash.rst index 8b8d9d3a8c4..994951dec4c 100644 --- a/doc/develop/splash.rst +++ b/doc/develop/splash.rst @@ -3,6 +3,27 @@ Splash screen ============= +Enabling the splash screen +-------------------------- + +CONFIG_SPLASH_SCREEN shows a BMP image on the display during boot. The image is +taken from the hexadecimal address given by the environment variable +*splashimage*. If *splashimage* is not set, no splash screen is displayed. + +Note that enabling this option also suppresses the compiled-in U-Boot logo (see +CONFIG_VIDEO_LOGO), whether or not *splashimage* is set, so a board that enables +CONFIG_SPLASH_SCREEN without setting *splashimage* shows nothing at all. + +Normally the U-Boot version string is shown on the display once the splash +screen is enabled, since video starts up after U-Boot has displayed the initial +banner and the banner is otherwise not visible. CONFIG_HIDE_LOGO_VERSION hides +this version information. + +Note that this version banner is only printed on the video console when the +splash image is left at its default position (0,0, see *splashpos* below). If +the image is moved away from 0,0, the banner is skipped regardless of +CONFIG_HIDE_LOGO_VERSION. + Preparing the splash image -------------------------- @@ -12,6 +33,11 @@ It gives the board an opportunity to prepare the splash image data before it is processed and sent to the frame buffer by U-Boot. Define your own version to use this feature. +If CONFIG_SPLASH_SOURCE is not enabled, the default splash_screen_prepare() +falls back to copying the compiled-in U-Boot logo (see CONFIG_VIDEO_LOGO) to the +address given by *splashimage*, so it is shown as the splash image instead of a +board-supplied one. + Selecting the splash image source --------------------------------- @@ -39,3 +65,62 @@ environment variable *splashfile*. In case the environment variable *splashfile* is not defined the default name ``splash.bmp`` will be used. + +For storage backed locations (MMC, SATA, USB, etc.) the device and partition to +read from can be overridden with the environment variable *splashdevpart*. Its +value follows the same ``<dev>[:<part>]`` or ``<dev>#<partition name>`` +conventions used by the load commands, e.g. ``0:1`` or ``0#splash``. When +*splashdevpart* is not set, the ``devpart`` field of the board's splash location +entry is used instead. + +The default weak splash_screen_prepare() passes the ``default_splash_locations`` +array, defined in ``common/splash.c``, to splash_source_load(). It provides the +following *splashsource* names out of the box: + +======== ============ ================== =============== +Name Storage Type devpart default +======== ============ ================== =============== +sf SPI flash raw, offset 0x0 n/a +mmc_fs MMC file system ``0:1`` +mmc_raw MMC raw ``0:1`` +usb_fs USB file system ``0:1`` +sata_fs SATA file system ``0:1`` +======== ============ ================== =============== + +A board that needs different locations, other storage backends (e.g. NAND, +UBI/UBIFS) or a different devpart default should provide its own array of +``struct splash_location`` entries (see ``include/splash.h``) and call +splash_source_load() from its own splash_screen_prepare() implementation +instead of relying on the default one. + +Positioning the splash image +---------------------------- + +If CONFIG_SPLASH_SCREEN_ALIGN is enabled, the splash image can be freely +positioned on the display using the environment variable *splashpos*, given as +``x,y``: + +* A positive number is the number of pixels from the left/top. +* A negative number is the number of pixels from the right/bottom. +* ``m`` centers the image on that axis. + +Examples:: + + setenv splashpos m,m + => image at center of screen + + setenv splashpos 30,20 + => image at x = 30 and y = 20 + + setenv splashpos -10,m + => vertically centered image + at x = dspWidth - bmpWidth - 9 + +Splash screen in SPL +-------------------- + +The splash screen feature is also available in SPL, controlled by the SPL +counterparts of the above options: CONFIG_SPL_SPLASH_SCREEN, +CONFIG_SPL_SPLASH_SCREEN_ALIGN and CONFIG_SPL_SPLASH_SOURCE. They behave the +same as their non-SPL equivalents, but apply only at the SPL stage, and are +selected and configured independently of the U-Boot proper options. -- 2.43.0
