From a84852ac18a3184a1d6f6b447cce5e7dfdc1f178 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Tue, 26 Aug 2025 09:06:47 -0600 Subject: [PATCH 1/2] Add support for logos Provide a way to specify one or more logos so that the bootloader can present a nicer graphical menu for the OS. Support BMP as a baseline, with PNG and SVG as optional features. Add a note into the usage section about boot menus, with some recommendations for how a logo should be selected from the available options. Signed-off-by: Simon Glass --- source/chapter2-source-file-format.rst | 111 +++++++++++++++++++++++++ source/chapter3-usage.rst | 29 +++++++ source/references.rst | 6 ++ 3 files changed, 146 insertions(+) diff --git a/source/chapter2-source-file-format.rst b/source/chapter2-source-file-format.rst index 4b8bcba..c29459a 100644 --- a/source/chapter2-source-file-format.rst +++ b/source/chapter2-source-file-format.rst @@ -167,6 +167,7 @@ the '/images' node should have the following layout:: | o hash-1 {...} o hash-2 {...} + o logo-info {...} ... Mandatory properties @@ -198,6 +199,7 @@ description kernel Kernel Image kernel_noload Kernel Image (no loading done) kwbimage Kirkwood Boot Image + logo Logo or other graphical image lpc32xximage LPC32XX Boot Image mtk_image MediaTek BootROM loadable Image multi Multi-File Image @@ -393,6 +395,10 @@ signature-1 Each signature sub-node represents a separate signature calculated for node's data according to specified algorithm. +logo-info + Contains information about the logo image, to help describe characteristics + such as image dimensions. + .. index:: Hash nodes Hash nodes @@ -514,6 +520,100 @@ padding if no value is provided we assume pkcs-1.5 +.. _logos: + +Logo Information node +--------------------- + +This node is mandatory for images of type 'logo'. + +Graphical logos can be used in boot menus to provide a visual indication of +what is being booted. Logos are stored within the FIT as images, referred to +by the :ref:`logos_prop` property in the configuration node. + +For the image, compression may be used, but if the file format itself supports +compression this is not recommended. + +The 'logo-info' node has the following structure:: + + o logo-info + |- format = "bmp"; + |- width = <128>; + |- height = <128>; + |- depth-log2 = <4>; + |- colour = "rgb"; + |- alpha-channel; + + +Mandatory properties +~~~~~~~~~~~~~~~~~~~~ + +:index:`format` + File format of the graphical image. This must be provided for images of + type :index:`logo`. See :ref:`logos`. + + The following formats are defined. Support for logos is optional. If logos + are supported, BMP must be supported. Other formats are optional. + + ============== ========= ===================================== + Format type Support Meaning + ============== ========= ===================================== + bmp Mandatory Windows bitmap; see [windowsbmp]_ + png Optional Portable Network Graphics; see [png]_ + svg Optional Scalable Vector Graphics; see [svg]_ + ============== ========= ===================================== + + +Conditionally mandatory property +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +width: + Width of the logo in pixels. This property is mandatory for logos which + contain bitmaps, i.e. BMP and PNG. + +height + Height of the logo in pixels. This property is mandatory for logos which + contain bitmaps, i.e. BMP and PNG. + +depth-log2 + log (base 2) of the logo depth. For example, for a 32bpp images this should + be 5. This property is mandatory for logos which define a colour depth, + i.e. BMP and PNG. + +color + Type of color provided, as a string. This property is mandatory for logos + which contain bitmaps, i.e. BMP and PNG. + + Valid values are: + + ============== ============================================= + Color type Meaning + ============== ============================================= + indexed A palette is used to define colours + grayscale The image supports luminance only + rgb The image supports red/green/blue true colour + ============== ============================================= + +alpha-channel + Indicates that the image has an alpha channel, i.e. supports transparency. + This boolean property must be present if the image includes transparency + information. + +background + String indicateing the type of background the image targets. + + Valid values are: + + =============== =================================================== + Background type Meaning + =============== =================================================== + light The image looks best on a white or light background + dark The image looks best on a black or dark background + =============== =================================================== + +.. _os_info: + + '/configurations' node ---------------------- @@ -566,6 +666,7 @@ Each configuration has the following structure:: |- loadables = "loadables sub-node unit-name" [, ...]; |- script = "script sub-node unit-name"; |- compatible = "vendor,board-style device tree compatible string"; + |- logos = "log sub-node unit-name" [, ...]; o signature-1 {...} Mandatory properties @@ -621,6 +722,16 @@ compatible Note that U-Boot requires the :index:`CONFIG_FIT_BEST_MATCH` option to be enabled for this matching to work. +.. _logos_prop: + +logos + Unit names of the corresponding image blobs containing a logo for this + operating system. Logos are listed in order of preference. + + Multiple logos can be provided to ensure the widest possible bootloader + support. If any logos are provide, at least one must be in BMP format. + See :ref:`logos`. + The FDT blob is required to properly boot FDT-based kernel, so the minimal configuration for 2.6 FDT kernel is (kernel, fdt) pair. diff --git a/source/chapter3-usage.rst b/source/chapter3-usage.rst index 5b8ac4b..c02bc06 100644 --- a/source/chapter3-usage.rst +++ b/source/chapter3-usage.rst @@ -134,6 +134,35 @@ found, searching stops, using the best match found in the stage. Other suffixes may be added in future. +Boot menu +~~~~~~~~~ + +In some cases it may desirable to show a menu of boot options and wait for the +user to select one. The :ref:`logos_prop` property provides logos which can be +shown in the case of a graphical menu. + +The bootloader must support at least logos in BMP format, if it supports a +graphical display. + +Logos should be selected based on the following criteria: + + #. The logo format must be supported by the bootloader + + #. SVG is preferred (if supported), followed by PNG (also if supported) + and then BMP + + #. Larger logos are preferred, so long as they fit into the screen space + available to the bootloader + + #. Color is preferred to grayscale, unless the bootloader knows that + the display is not capable of showing color + + #. Logos with an alpha channel are preferred to those that lack one. + + #. Logos with a dark background are preferred when the background is + dark. Logos with a light background are preferred when the background + is light. + Load the images from the selected configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/references.rst b/source/references.rst index 4bf41b7..93b4f7d 100644 --- a/source/references.rst +++ b/source/references.rst @@ -7,3 +7,9 @@ References https://www.devicetree.org/specifications .. [VBE] Verified Boot for Embedded (VBE) https://docs.u-boot.org/en/latest/develop/vbe.html +.. [windowsbmp] Windows Bitmap file format + https://en.wikipedia.org/wiki/BMP_file_format +.. [png] Portable Network Graphics + https://libpng.org/pub/png/spec/1.2/PNG-Contents.html +.. [svg] Scalable Vector Graphics + https://www.w3.org/TR/SVG11/ From 8f7d9a899a432652b603a3a5ce94cb888b91e42e Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Tue, 26 Aug 2025 06:30:24 -0600 Subject: [PATCH 2/2] Support os-release information It is useful to have some information about an OS, e.g. to present to the user in a menu. Create a definition for this, making use of the os-release specification. Add a note into the usage section about this. Co-developed-by: Claude Signed-off-by: Simon Glass --- source/chapter2-source-file-format.rst | 310 +++++++++++++++++++++++++ source/chapter3-usage.rst | 8 +- source/references.rst | 4 + 3 files changed, 320 insertions(+), 2 deletions(-) diff --git a/source/chapter2-source-file-format.rst b/source/chapter2-source-file-format.rst index c29459a..2b2d317 100644 --- a/source/chapter2-source-file-format.rst +++ b/source/chapter2-source-file-format.rst @@ -168,6 +168,7 @@ the '/images' node should have the following layout:: o hash-1 {...} o hash-2 {...} o logo-info {...} + o os-info {...} ... Mandatory properties @@ -399,6 +400,11 @@ logo-info Contains information about the logo image, to help describe characteristics such as image dimensions. +os-info + Contains information about the OS image, to help identify it. This + can be useful for displaying a menu for the user. The information is + generally only useful for image nodes which contain an OS. + .. index:: Hash nodes Hash nodes @@ -613,6 +619,310 @@ background .. _os_info: +OS Information node +------------------- + +The 'os-info' node provides information about an image, specifically targeting +images which constitute an operation system. The properties are based on the +freedesktop.org os-release specification [osrelease]_. + +The 'os-info' node has the following structure:: + + o os-info + |- ansi-color = "OS console presentation color" + |- architecture = "OS userspace architecture" + |- bug-report-url = "OS bug report URL" + |- build-id = "OS build identifier" + |- confext-level = "OS configuration extensions level" + |- cpe-name = "OS Common Platform-Enumeration name" + |- default-hostname = "OS default hostname" + |- documentation-url = "OS documentation URL" + |- home-url = "OS homepage URL" + |- id = "OS identifier" + |- id-like = "OS inherited from", ... + |- image-id = "OS image identifier" + |- image-version = "OS image version" + |- logo-name = "OS logo icon name" + |- name = "OS name" + |- pretty-name = "OS pretty name" + |- privacy-policy-url = "OS privacy policy URL" + |- release-type = "OS release type" + |- support-end = "OS support end date" + |- support-url = "OS support URL" + |- sysext-level = "OS system extensions level" + |- variant = "OS variant" + |- variant-id = "variant identifier" + |- vendor-name = "OS vendor name" + |- vendor-url = "OS vendor URL" + |- version = "OS version" + |- version-codename = "OS version codename" + |- version-id = "OS version identifier" + +Mandatory properties +~~~~~~~~~~~~~~~~~~~~ + +If an 'os-info' node is included, these properties are mandatory: + +name + A string identifying the operating system, without a version component, + and suitable for presentation to the user. + + Examples:: + name = "Fedora Linux"; + + name = "Ubuntu"; + +version + A string identifying the operating system version, excluding any OS name + information, possibly including a release code name, and suitable for + presentation to the user. + + Examples:: + version = "32 (Workstation Edition)"; + + version = "20.04.1 LTS (Focal Fossa)"; + +Conditionally mandatory property +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +color + A suggested presentation color when showing the OS name on the console, in + the format 0x00bbggrr. This is mandatory if 'ansi-color' is provided. + +Optional properties +~~~~~~~~~~~~~~~~~~~ + +ansi-color + A suggested presentation color when showing the OS name on the console. + This should be specified as string suitable for inclusion in the ESC [ m + ANSI/ECMA-48 escape code for setting graphical rendition. See also color. + + Examples:: + // red + ansi-color = "0;31"; + + // light blue + ansi-color = "1;34"; + + // Fedora blue + ansi-color = "0;38;2;60;110;180"; + +architecture + A string that specifies the CPU architecture the userspace binaries + require. + + Examples:: + architecture = "x86_64"; + + architecture = "arm64"; + +bug-report-url + Link to the main bug reporting page for the operating system, if there + is one. + + Example:: + bug-report-url = "https://bugzilla.redhat.com/"; + +build-id + A string uniquely identifying the system image originally used as the + installation base. In most cases, VERSION_ID or IMAGE_ID are updated + when the entire system image is replaced during an update. BUILD_ID may + be used in distributions where the original installation image version + is important. + + Example:: + build-id = "2013-03-20.3"; + +confext-level + A lower-case string identifying the operating system configuration + extensions support level, used to specify extension-release + compatibility. + + Examples:: + confext-level = "2"; + + confext-level = "15.14"; + +cpe-name + A CPE name for the operating system, in URI binding syntax, following + the Common Platform Enumeration Specification. + + Example:: + cpe-name = "cpe:/o:fedoraproject:fedora:17"; + +default-hostname + A string specifying the hostname if hostname(5) is not present and no + other configuration source specifies the hostname. + + Example:: + default-hostname = "localhost"; + +documentation-url + Link to the main documentation page for this operating system. + + Example:: + documentation-url = "https://docs.fedoraproject.org/"; + +home-url + Link to the homepage for the operating system, or alternatively a + homepage of the specific version of the operating system. + + Example:: + home-url = "https://fedoraproject.org/"; + +id + A lower-case string identifying the operating system, excluding version + information and without spaces or other characters outside of 0-9, a-z, + ".", "_" and "-". + + Examples:: + id = "fedora"; + + id = "debian"; + +id-like + A list of operating system identifiers in the same syntax as id. This should + list identifiers of operating systems that are closely related to the local + operating system in regards to packaging and programming interfaces. + + Examples:: + id-like = "rhel", "centos", "fedora"; + + id-like = "debian"; + +image-id + A lower-case string identifying a specific image of the operating system. + + Examples:: + image-id = "vendorx-cashier-system"; + + image-id = "netbook-image"; + +image-version + A lower-case string identifying the OS image version. + + Example:: + image-version = "33"; + + image-version = "47.1rc1" + +logo-name + A string specifying the name of an icon suitable to represent this + operating system in a logo format. The file for the logo should be + available within the root file system used by the operating system. + + See the Icon Theme Specification [icontheme]_. + + Examples:: + logo-name = "fedora-logo-icon"; + + logo-name = "ubuntu-logo"; + +pretty-name + A pretty operating system name in a format suitable for presentation to + the user. May or may not contain a release code name or OS version of + some kind. + + Examples:: + pretty-name = "Fedora Linux 32 (Workstation Edition)"; + + pretty-name = "Ubuntu 20.04.1 LTS"; + +privacy-policy-url + Link to the privacy policy page for the operating system, if there is + one. + + Example:: + privacy-policy-url = "https://fedoraproject.org/wiki/Legal:PrivacyPolicy"; + +release-type + Describes the release type of the operating system. May be one of: + stable, lts, development, experiment. + + Examples:: + release-type = "stable"; + + release-type = "lts"; + + release-type = "development"; + +support-end + The time at which support for this version of the OS ends. When + specified, this should be in 64-bit Unix time format, i.e. the number of + seconds since 1.1.1970, 0:0:0. + + Example:: + support-end = /bits 64/ <1756212516>; + +support-url + Link to the main support page for the operating system, if there is one. + + Example:: + support-url = "https://fedoraproject.org/wiki/Communicating_and_getting_help"; + +sysext-level + A lower-case string identifying the operating system extensions support + level, used to specify extension-release compatibility. + + Examples:: + sysext-level = "2"; + + sysext-level = "15.14"; + +variant + A string identifying a specific variant or edition of the operating + system suitable for presentation to the user. + + Examples:: + variant = "Workstation Edition"; + + variant = "Server Edition"; + +variant-id + A lower-case string identifying a specific variant or edition of the + operating system. + + Examples:: + variant-id = "workstation"; + + variant-id = "server"; + +vendor-name + The name of the operating system vendor. + + Examples:: + vendor-name = "Fedora Project"; + + vendor-name = "Canonical Ltd."; + +vendor-url + Link to the vendor homepage. + + Examples:: + vendor-url = "https://fedoraproject.org/"; + + vendor-url = "https://canonical.com/"; + +version-codename + A lower-case string identifying the operating system release code name, + excluding any OS name information or release version, and suitable for + processing by scripts or usage in generated filenames. + + Examples:: + version-codename = "focal"; + + version-codename = "jammy"; + +version-id + A lower-case string identifying the operating system release, excluding + any OS name information or release code name, and suitable for processing + by scripts or usage in generated filenames. + + Examples:: + version-id = "32"; + + version-id = "20.04"; + '/configurations' node ---------------------- diff --git a/source/chapter3-usage.rst b/source/chapter3-usage.rst index c02bc06..329c173 100644 --- a/source/chapter3-usage.rst +++ b/source/chapter3-usage.rst @@ -138,8 +138,12 @@ Boot menu ~~~~~~~~~ In some cases it may desirable to show a menu of boot options and wait for the -user to select one. The :ref:`logos_prop` property provides logos which can be -shown in the case of a graphical menu. +user to select one. In this case the :ref:`os_info` provides information which +can be presented to the user to aid this choice. The :ref:`logos_prop` property +provides logos which can be shown in the case of a graphical menu. + +The OS Information can also be useful for a fully automated boot, such as to +select a particular version of the OS. The bootloader must support at least logos in BMP format, if it supports a graphical display. diff --git a/source/references.rst b/source/references.rst index 93b4f7d..be53c00 100644 --- a/source/references.rst +++ b/source/references.rst @@ -13,3 +13,7 @@ References https://libpng.org/pub/png/spec/1.2/PNG-Contents.html .. [svg] Scalable Vector Graphics https://www.w3.org/TR/SVG11/ +.. [osrelease] os-release - Operating system identification + https://www.freedesktop.org/software/systemd/man/latest/os-release.html +.. [icontheme] Icon Theme Specification + https://standards.freedesktop.org/icon-theme-spec/latest