Special care is needed when storage is shared between firmware and the OS. Add a chapter that discusses the issues and puts down the requirements for using shared storage.
Resolves: #19 Cc: Daniel Thompson <[email protected]> Signed-off-by: Grant Likely <[email protected]> --- source/chapter2-uefi.rst | 44 ------ source/chapter4-firmware-media.rst | 267 +++++++++++++++++++++++++++++++++++++ source/index.rst | 1 + 3 files changed, 268 insertions(+), 44 deletions(-) create mode 100644 source/chapter4-firmware-media.rst diff --git a/source/chapter2-uefi.rst b/source/chapter2-uefi.rst index 07426a4..05230d2 100644 --- a/source/chapter2-uefi.rst +++ b/source/chapter2-uefi.rst @@ -56,50 +56,6 @@ System Volume Format The system firmware must support all partitioning standards required by the UEFI specification. -On systems where the system firmware binaries reside on the System Volume then -the System Volume must be pre-configured with a partition table and include -protective partitions to reduce risk of accidental destruction of the system -firmware. - -All pre-installed partition tables must use GPT partitioning unless -some immutable feature of the platform (such as a mask programmed boot ROM) -makes this impossible; on such platforms MBR partitioning may be -used as an alternative. - -GPT partitioning -^^^^^^^^^^^^^^^^ - -Any pre-installed partition table must strictly conform to the UEFI -specification and include a protective MBR authored exactly as -described in UEFI specification (hybrid partitioning schemes are not -permitted). - -Pre-installed protective partitions must have the Platform Required -Attribute Flag set. - -It is recommended that automatic system disk partitioning utilities -preserve Platform Required partitions as is, and that manual disk -partitioning utilities provide warnings and/or other safe guards to -reduce risk of accidental removal. - -MBR partitioning -^^^^^^^^^^^^^^^^ - -Pre-installed protective partitions should have a partition type of 0xF8 -unless some immutable feature of the platform makes this impossible. - -It is recommended that disk partitioning utilities treat such -partitions in the same manner as GPT partitions with the Platform -Required Attribute Flag set. - -It is recommended that pre-installed protective partitions that are not -type 0xF8 be located wholly within 1MB of the start of the disk. - -Automatic disk partitioning utilities shall not create partitions -within 1MB of the start of the disk. Manual disk partitioning -utilities should avoid recommending that partitions start within -1MB of the start of the disk. - UEFI Boot Services ================== diff --git a/source/chapter4-firmware-media.rst b/source/chapter4-firmware-media.rst new file mode 100644 index 0000000..f8a03db --- /dev/null +++ b/source/chapter4-firmware-media.rst @@ -0,0 +1,267 @@ +**************** +Firmware Storage +**************** + +In general, it is recommended for all platforms to store firmware images +and data on a dedicated storage device which is not accessed by the operating +system. +It is common practice to boot firmware out of a dedicated SPI flash, +while the OS is loaded from another source, whether it be SATA, SD, USB, +Network boot, or something else. + +However, many embedded systems have size, cost, or usage constraints that +make separate firmware storage unfeasible. +On such systems, firmware and the OS reside on the same media. + +Some shared media provides dedicate boot regions, but in many cases +firmware needs to reside in a normal region of storage. +Care must be taken to ensure firmware kept in normal storage does not +conflict with normal usage of the media by an OS. + +* Firmware must be stored on the media in a way that does not conflict + with normal partitioning and usage by the operating system. +* Normal operation of the OS must not interfere with firmware files +* Firmware needs a method to modify variable storage at runtime while the + OS controls access to the device + +Partitioning of Shared Storage +============================== + +Shared storage must use GPT partitioning unless the storage media provides +device-native partitioning [#UFSparts]_, +or if an immutable property of the platform (ex. the masked boot ROM) +is incompatible with the SoC boot ROM). +MBR partitioning shall be used when the platform is incompatible with GPT. + +.. warning:: + + MBR partitioning is deprecated and only included for legacy support. + All new platforms are expected to use either GPT or device-native + partitioning. + + GPT partitioning supports a much larger number of partitions, and + has build in redundancy by storing two copies of the partition table. + + A future issue of this specification will remove the MBR allowance. + +All firmware images and data stored in normal media should be contained +in a regular partition, +which can either be a dedicated firmware partition, +or the UEFI System Partition (ESP). + +The system should locate firmware by reading the partition table. +Using a fixed offset into the storage media is deprecated and should not +be used for new SoC designs. +If a fixed offset is required by the hardware, then it is strongly recommended +for the firmware location to be covered by a protective partition to protect +against accidentally overwriting system firmware. + +.. warning:: + + Fixed offsets to firmware data is supported only for legacy reasons. + All new platforms are expected to use partitions to locate firmware files. + + A future issues of this specification will disallow the use of fixed + offsets. + +GPT partitioning +---------------- + +Any pre-installed partition table must strictly conform to the UEFI +specification and include a protective MBR authored exactly as +described in UEFI specification (hybrid partitioning schemes are not +permitted). + +Pre-installed protective partitions must have the Platform Required +Attribute Flag set. + +It is recommended that automatic system disk partitioning utilities +preserve Platform Required partitions as is, and that manual disk +partitioning utilities provide warnings and/or other safe guards to +reduce risk of accidental removal. + +The system should locate firmware images by searching for partitions with +the following UUIDs in order: + +.. table:: + + ==================================== ======== ======================== + UUID Priority Description + ==================================== ======== ======================== + Vendor defined UUID 1 (Not recommended) + Proprietary vendor + dedicated firmware + partition. Should only + be used if firmware + cannot use a FAT + filesystem. + TBD 2 EBBR compliant dedicated + firmware partition + C12A7328-F81F-11D2-BA4B-00A0C93EC93B 3 UEFI System Partition + as defined in + UEFI ยง 5.3.3 + ==================================== ======== ======================== + +.. note:: + + Should the vendor defined UUID be included in this table at all? + +MBR partitioning +^^^^^^^^^^^^^^^^ + +Pre-installed protective partitions should have a partition type of 0xF8 +unless some immutable feature of the platform makes this impossible. + +It is recommended that disk partitioning utilities treat such +partitions in the same manner as GPT partitions with the Platform +Required Attribute Flag set. + +It is recommended that pre-installed protective partitions that are not +type 0xF8 be located wholly within 1MB of the start of the disk. + +Automatic disk partitioning utilities shall not create partitions +within 1MB of the start of the disk. Manual disk partitioning +utilities should avoid recommending that partitions start within +1MB of the start of the disk. + +.. [#UFSParts] For example, Universal Flash Storage (UFS) provides + device-native partitioning and does not require a discrete MBR or + GPT partition table. + +Firmware Partition Filesystem +============================= + +Where possible, firmware images and data should be stored in a filesystem. +Firmware can be stored either in a dedicated firmware partition, +or in certain circumstances in the UEFI System Partition (ESP). +Using a filesystem makes it simpler to manage multiple firmware file and +makes it possible for a single disk image to contain firmware for multiple +platforms. + +Dedicated firmware partitions are recommended to be formatted with a FAT +filesystem as defined by the UEFI specification. +However, dedicated firmware partition must not be used as an ESP. +EFI binaries in a dedicated firmware partition should be ignored +by default. + +When firmware is stored in the ESP, the ESP must contain a partition named +``/FIRMWARE`` in the root directory. +Dedicated firmware partitions should use the same ``/FIRMWARE`` hierarchy. +All firmware images and data must be stored in platform vendor +subdirectories under ``/FIRMWARE``. + +Vendors may choose their own subdirectory name under ``/FIRMWARE``, +but must choose names the do not conflict with other vendors. +Normally the vendor name will be the name of the SoC vendor, because the +firmware directory name will be hard coded in the SoC's boot ROM. +Vendors are recommended to use their Devicetree vendor prefix as their +vendor subdirectory name. + +Vendors are free to decide how to structure subdirectories under their +own vendor directory, but they must use a naming convention that allows +multiple SoCs to be supported in the same filesystem. + +For example, a vendor named Acme with two SoCs, ACME100 & AM300, could +choose to use the SoC part number as a subdirectory in the firmware path:: + + /FIRMWARE + /ACME + /ACME100 + fw.img + /ACME300 + fw.img + +It is also recommended for dedicated firmware partitions to use the +``/FIRMWARE`` file hierarchy. + +The following is a sample directory structure for firmware files:: + + /FIRMWARE + /<Vendor 1 Directory> + /<SoC A Directory> + <Firmware image> + <Firmware data> + /<SoC B Directory> + <Firmware image> + <Firmware data> + /<Vendor 2 Directory> + <Common Firmware image> + <Common Firmware data> + /<Vendor 3 Directory> + /<SoC E Directory> + <Firmware image> + +Operating systems and installers should not manipulate any files in the +``/FIRMWARE`` hierarchy during normal operation. + +.. todo: + + * Recommend failover A/B image layout to protect against corrupted + firmware. + * Define firmware update procedure. In what circumstances could an + OS automatically update firmware files in ``/FIRMWARE``? + +The sections below discuss the requirements when using both fixed and +removable storage. +However, it should be noted that the recommended behaviour of firmware +should be identical regardless of storage type. +In both cases, the recommended boot sequence is to first search for firmware +in a dedicated firmware partition, and second search for firmware in the +ESP. +The only difference between fixed and removable storage is the recommended +factory settings for the platform. + + +Fixed Shared Storage +-------------------- + +Fixed storage is storage that is permanently attached to the platform, +and cannot be moved between systems. +eMMC and Universal Flash Storage (UFS) device are often used as +shared fixed storage for both firmware and the OS. + +Where possible, it is prefered for the system to boot from a dedicated boot +region on media that provides one (ex. eMMC) that is sufficiently large. +Otherwise, the platform storage should be pre-formatted in the factory with +a partition table, a dedicated firmware partition, and firmware binaries +installed. + +Operating systems must not use the dedicated firmware partition, +but shall instead create a normal ESP for installing the EFI applications +including the OS loader. +OS partitioning tools must take care not to modify or delete dedicated +firmware partitions. + +Removable Shared Storage +------------------------ + +Removable storage is any media that can be physically removed from +the system and moved to another machine as part of normal operation +(ex. SD cards, USB thumb drives, and CDs). + +There are two primary scenarios for storing firmware on removable media. + +1. Platforms that only have removable media (ex. The Raspberry Pi has an + SD card slot, but no fixed storage). +2. Recovery when on-board firmware has been corrupted. If firmware on + fixed media has been corrupted, some platforms support loading firmware + from removable media which can then be used to recover the platform. + +In both cases, it is desirable to start with a stock OS boot image, +copy it to the media (SD or USB), and then add the necessary firmware files +to make the platform bootable. +Typically, OS boot images won't include a dedicated firmware partition, +and it is inconvenient to repartition the media to add one. +It is simpler and easier for the user if they are able to copy +the required firmware files into the ``/FIRMWARE`` directory tree on the ESP +using the basic file manager tools provided by all desktop operating systems. + +On removable media, firmware should be stored in the ESP under the +``/FIRMWARE`` directory structure as described above. +Platform vendors should support their platform by providing a single +.zip file that places all the required firmware files in the correct +locations when extracted in the ESP ``/FIRMWARE`` directory. +For simplicity sake, it is expected the same .zip file will recover the +firmware files in a dedicated firmware partition. + + diff --git a/source/index.rst b/source/index.rst index 5ddd19f..8099ac6 100644 --- a/source/index.rst +++ b/source/index.rst @@ -37,5 +37,6 @@ Creative Commons, PO Box 1866, Mountain View, CA 94042, USA. chapter1-about chapter2-uefi chapter3-secureworld + chapter4-firmware-media appendix-a-uefi-features references -- 2.13.0 _______________________________________________ boot-architecture mailing list [email protected] https://lists.linaro.org/mailman/listinfo/boot-architecture
