Bootloader/DRI/MemMap
Created on November 29, 2022
Glossary
Item | Remarks |
---|---|
DRI | Disaster Recovery Image |
P-DRI | Primary DRI |
B-DRI | Backup DRI |
PCI | |
OTP | One Time Programmable |
RCU | Remote control Unit |
DM-Verity | Device-Mapper verity ( A kernel feature ) |
Pre-requisites
A definition of ‘successful boot’ should be completed by vendor ( for eg: some app comes up successfully ) and define how the information can be passed to bootloader ( for eg: a pre-define new file is touched )
A decision to maitain a backup DRI or only the primary DRI ( If a B-DRI is not planned, all the requirements related to B-DRI could be ignored )
Bootloader: Recommendations
Specification | Specification Category | Status |
---|---|---|
The bootloader MUST be signed and encrypted and only launched by the SoC firmware if validated. | General | Generic |
More than one copy of bootloader MUST be stored in flash. The SoC firmware MUST fail over from one copy to the other in the event of a validation failure. | General | Generic |
The bootloader MUST implement secure boot of PCI and DRI XSigned code images as per Comcast Code Integrity specification | General | Comcast specific |
The bootloader MUST support the launching of standard RDK monolithic code image format and DM-verity code image format. | General | Generic |
The bootloader MUST check the signing certificate attached for a code image is valid in the certificate chain of trust.The certificate chain of trust MUST be hardware validated with values in SOC OTP. | General | Generic |
The BootLoader image execution priority criteria MUST be as follows: • Boot primary PCI Image based on last Image download flag (launch_bank) • If the max retries (default recommended is 3) is exhausted, load backup PCI • If max retries (default recommended is 3) is exhausted, launch PDRI Image. • If max retries (default recommended is 3) is exhausted, launch BDRI Image. | General | Generic |
Before the bootloader attempts to start a code image, the bootloader MUST set the hardware watchdog to time out and reboot in a pre-defined number of seconds. | General | Generic |
The bootloader MUST maintain a separate retry count for each code image in a shared flash area. | General | Generic |
The bootloader MUST decrement the retry count for that code image before launching the code image in a normal boot sequence. The code image MUST reset the retry counter on a successful bootup. | General | Generic |
If the retry count for a code image reaches zero, the bootloader MUST no longer attempt to start that code image in the case of the PCI1, PCI2, PDRI or BDRI until a new code image has been downloaded and the count has been reset by the downloading application or until a forced disaster recovery has been initiated. | General | Generic |
The retry count for a code image MUST not be decremented when the code image is selected from the launch override screen. | General | Generic |
The retry counts for each code image MUST be reset to the default value if a factory reset or force disaster recovery process is initiated. | General | Generic |
The bootloader MUST maintain a software locked data area where a primary minimum codeSecureVersion and cvcAccessStart shall be stored, as required by the Comcast XSign Code Integrity Specification V3.1.0 | General | Comcast specific |
Any reset process shall NOT affect the primary or backup values of codeSecureVersion and cvcAccessStart. | General | Comcast specific |
The bootloader shall maintain a separate all code image retry count for the case where no code image is found to be valid. | General | Generic |
If no code image can be validated, the bootloader shall decrement the all code image retry count and reboot. | General | Generic |
In the case where a valid code image is found, the all code image retry count shall be reset to default value it is not already at the default value. | General | Generic |
In the case where the all code image retry count reaches zero, the bootloader shall display the fatal error screen. | General | Generic |
Bootloader MUST reset B-DRI retry counter to default on error | General | Generic |
The all code image retry count shall not be decremented when the code image is selected from the launch override screen. | General | Generic |
All screens shall be 1920×1080 resolution | General | Generic |
Given the CPE has been powered when the bootloader is started then the bootloader shall select a code image to authenticate based on the following ordered rules: 1. PCI1: if the software version is the highest (of PCI0 and PCI1 version) AND PCI0 secure software version is higher than or equal to the minimum secure software version number for PCI supported by the device AND the PCI0 retry counter is not zero. 2. PCI2: if the software version is the highest (of PCI0 and PCI1 version) AND PCI1 secure software version is higher than or equal to the minimum secure software version number supported by the device AND the PCI1 retry counter is not zero. 3. PDRI: PDRI secure software version is higher than or equal to the minimum secure software version number for PDRI supported by the device AND if the PDRI retry counter is not zero. 4. BDRI: BDRI secure software version is higher than or equal to the minimum secure software version number for BDRI supported by the device AND if the BDRI retry counter is not zero | General | Generic |
Bootloader has selected a normal code image when the code selection logic is used then start the selected code image and leave the static code image start LED pattern visible until the code image has started. | General | Generic |
Given the bootloader has selected a disaster recovery code image when the code selection logic is used then · start the disaster recovery LED pattern for a pre-defined time; · start the selected disaster recovery code image and leave the static disaster recovery LED pattern visible until the code image has started | General | Generic |
Given the CPE has been powered when the bootloader is started and has selected a valid code image in a normal boot flow then the bootloader shall decrement the code image retry counter before starting the code image check. | General | Generic |
Given the CPE has been powered when the bootloader is unable to find a validated code image to start for a predefine number of consecutive power cycles then the bootloader shall show the error screen to the user to guide them to speak to the platform operator. | General | Generic |
Bootloader MUST respond to a front panel button press of a predefined number of seconds to trigger force disaster recovery process | General | Generic |
During force disaster recovery process: · start the Force DRI LED pattern for a pre-defined period of time; · set a signal to that DRI code image that Force DRI is required; · start a disaster recovery code image and leave the force DRI LED pattern visible until the code image has started. | General | Generic |
The forced DRI trigger shall be stored in flash to allow the DRI application to complete the required action. | General | Generic |
The forced DRI trigger shall be cleared on boot if they are set when the bootloader launces. | General | Generic |
The Bootloader MUST include the ability to force the device in bootloader menu from the remote control via the IR interface during boot up via a pre-defined RCU key sequencing | General | Generic |
Bootloader menu MUST display the code image selection screen showing a list of PCI1, PCI2, PDRI, BDRI and a reboot option. | General | Generic |
Bootloader showing bootloader menu with code image selection screen must validate the image selected and if it is valid launch the code image and MUST terminate the boot LED pattern. | General | Generic |
Bootloader showing bootloader menu with code image selection screen if fails to validate the selected code image MUST not start the code image and display LED error as per LED pattern and remain on bootloader menu. | General | Generic |
Bootloader MUST display the LED feedback in a normal booting scenario as per boot LED pattern | LED | Generic |
Bootloader MUST start the boot LED pattern using the stored intensity value | LED | Generic |
LED intensity in the boot LED pattern MUST be configurable via updatable configuration by PCI | LED | Generic |
If stored LED intensity value is corrupted Bootloader must use a hardcoded default value for the intensity of the boot LED pattern | LED | Generic |
Bootloader MUST display the splash screen/startup screen when booting and while processing the code image selection logic | UI | Generic |
Bootloader MUST display the backup screen if primary splash screen is not valid | UI | Generic |
Bootloader MUST display the error screen if unable to validate and launch any image – B-DRI, P-DRI, PCI1, PCI2 | UI | Generic |
Bootloader MUST display the bootloader menu if boot sequence is interrupted via IR during bootup | UI | Generic |
Bootloader MUST use the upgradeable screens if valid, otherwise, the bootloader MUST use backup screen for display | UI | Generic |
mTLS certificates for firmware download shouldn’t be allowed to change | UI | Generic |
EMMC certificates should be encrypted and before usage chipset secure APIs should be used to verify them | UI | Generic |
Accessing mTLS certificates during DRI
- The bootloader (BL) is completely handled by OEMs in collaboration with security vendors along with SoC as the basic bootloader will be given by SoC and OEM will only customize it.The downloader may need BL for firmware downloading.
- The certificates provided by security vendor are used to verify the authenticity of downloaded firmware. The certificates are verified by the chipset before using, and they are stored in a read-only partition in the EMMC. Only the downloader and main system can access it. There are two kinds of certificates: video provision used by Operator and firmware download.
- The certificates for firmware download are stored in a read-write location, preferably an EMMC partition, and are not allowed to be changed for security reasons. They need to be encrypted and, before using, the chipset secure APIs are called to verify them.
Disaster recovery: Recommendations
Specification | Specification Category | Status |
---|---|---|
The DRI mechanism MUST validate the image in Disastor recovery memory area | General | General |
B-DRI and P-DRI MUST be stored in the soft locked upgradeable area | General | Generic |
NTP (Network Time Protocol) server URLs to be used MUST be limited to a pre-defined set of NTP servers | General | Generic |
The P-DRI firmware Version MUST be available to the RDK via Manufacturing Library, so that the RDK can post the current P-DRI version to Xconf as part of P-DRI upgrade procedure while RDK is running. Suggested naming Convention: <DEVICE MODEL NAME> _ PDRI _ <VERSION>.bin | General | Generic |
The B-DRI and P-DRI MUST request the box to reboot immediately after successfully validating and writing a PCI to flash memory | General | Generic |
Ethernet Link is detected to be active B-DRI and P-DRI, MUST first attempt to perform DHCPv6 and SLAAC on Ethernet, and then DHCPv4 on the Ethernet if IPv6 address acquisition address fails, prior to attempting Wi-Fi connectivity | General | General |
The P-DRI and B-DRI MUST sequentially attempt to initialize the network interface using the following order of precedence: 1. IPv6 Gateway Discovery and IPv6 address acquisition via SLAAC and DHCPv6 2. IPv4 Gateway Discovery and IPv4 address acquisition via DHCP | General | Generic |
A Cold Factory Reset, Factory Reset MUST invalidate the stored Wi-Fi credentials in the B-DRI & P-DRI and RDK shared flash area. | General | Generic |
The B-DRI and P-DRI MUST include IR remote control support | General | Generic |
B-DRI and P-DRI MAY support bluetooth paired remote. | General | Generic |
If paired to Bluetooth RCU B-DRI/P-DRI continue to recognize RCU key press via IR from another IR remote if IR transmission is received | General | Generic |
B-DRI and P-DRI MUST display Remote reset screen if no paired data is found when DRI is launched | General | Generic |
The B-DRI MUST include the ability to perform a Cold Factory Reset from the remote control via the IR interface at any point in time during execution. | General | Generic |
The P-DRI MUST include the ability to perform a Cold Factory Reset and a Factory Reset from the remote control via the IR interface at any point in time during execution. | General | Generic |
After a device obtains an IP address, posts to Xconf, and then receives a valid Xconf response, the XClass device MUST NOT attempt to require the IP address until after a reboot timeout. | General | Comcast specific |
B-DRI and P-DRI MAY choose to display at a fixed video resolution of 1080p | General | Comcast specific |
A XClass device with 2.4 GHz and 5 GHz Wi-Fi MUST seamlessly support all SSID pairing at 2.4 GHz and 5 GHz with a preference for 5 GHz. | General | Comcast specific |
B-DRI and P-DRI if able to connect to internet via shared wi-fi credentials or ethernet interface MUST continue with download without any user intervention | General | Generic |
B-DRI and P-DRI when unable to connect to internet via shared wi-fi credentials or ethernet interface area MUST display the Remote Reset screen | General | Generic |
The DRI Cold Factory Reset trigger key/button sequence MUST be a pre-defined one | General | Generic |
The DRI Factory Reset trigger key/button sequence MUST be a pre-defined one | General | Generic |
The B-DRI and P-DRI MUST include the ability to go to the detailed diagnostic screen via IR interface when a pre-defined key is pressed for a predefine time period or by a pre-defined key sequence | General | Generic |
A XiOne device with Wi-Fi and Ethernet, MUST first attempt to perform DHCPv6 and SLAAC on Ethernet, and then DHCPv4 on the Ethernet if IPv6 address acquisition fails, prior to attempting Wi-Fi connectivity when the Ethernet Link is detected to be active | General | Comcast specific |
A Cold Factory Reset, Factory Reset MUST invalidate the stored video Wi-Fi SSID and Pwd in the RDK shared flash area. | General | Generic |
B-DRI and P-DRI, MUST reboot after waiting a pre-defined time interval irrespective of current state | General | Generic |
B-DRI/P-DRI MUST support downloading images over Ethernet interface | Download Requirements | Generic |
B-DRI/P-DRI MUST support downloading images over Wi-Fi Interface | Download Requirements | Generic |
The B-DRI and P-DRI MUST perform pre-download verification using XSign Manifest Table, as per code integrity spec | Download Requirements | Comcast specific |
The firmware download image MUST be validated for the specific device (Vendor (OEM), platform, class, and hardware revision) by: • An exact match of the <Model Number> PMI in the XClass Device OTP Serialization Data to the ModelNumber PMI field in the received image XSign Manifest Table v3 • The image size will fit into the flash memory regions designated for storing the image. | Download Requirements | Comcast specific |
After a successful download of the entire monolithic code image, the currently executing B-DRI or P-DRI MUST perform the following: • Validate the entire monolithic code image per [X Sign V3.0.0] • Validate per XSign Manifest Table [X Sign V3.0.0] • Validate the Linux kernel per [X Sign V3.0.0] • Validate the Boot Configuration Parameters per [X Sign V3.0.0] • Validate the root file system per [X Sign V3.0.0] | Download Requirements | Comcast specific |
The B-DRI and P-DRI MUST support device-initiated firmware download | Download Requirements | Generic |
The B-DRI and P-DRI MUST support two modes of download operation as described in PCI Firmware Update | Download Requirements | Generic |
B-DRI and P-DRI MAY use the google.com, espn.com, speedtest.net for internet connectivity test | Download Requirements | Generic |
Memory Map: Recommendations
The memory map requirements vary vastly due to the hardware capabilities of platform ( some vendors will prefer to have a single image whereas some vendors will prefer to have a backup image bank ). A sample Memory map is given below
Reference Flash Layout for Video Accelerator |
---|
flash0.macadr EMMC flash Data : 1024B flash0.nvram EMMC flash Data : 64KB flash0.recovery EMMC flash Data : 256MB flash0.vendor EMMC flash Data : 128MB flash0.kernel_a EMMC flash Data : 128MB flash0.kernel_b EMMC flash Data : 128MB flash0.rootfs_a EMMC flash Data : 1024MB flash0.rootfs_b EMMC flash Data : 1024MB flash0.rootdata EMMC flash Data : 2048MB flash0.rsvd EMMC flash Data : 10174MB |
DAC App size consideration in Memory Map
- The maximum RAM usage of an application can be defined in the appMetadataSchema.json file(https://github.com/rdkcentral/BundleGen/blob/master/bundlegen/schema/appMetadataSchema.json#L22).
- It is also possible to configure persistent storage usage and app bundle storage for each application, where there will be temporary storage for downloaded app bundles, a place to store app files, and a persistent storage to store app data.
- These should be defined per platform to use physical storage as per the platform.
- The downloaded app bundles will be part of the rootfs itself.
Go To Top