Bootloader/DRI/MemMap

Created on November 29, 2022

Glossary


ItemRemarks
DRIDisaster Recovery Image
P-DRIPrimary DRI
B-DRIBackup DRI
PCI
OTPOne Time Programmable
RCURemote control Unit
DM-VerityDevice-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


SpecificationSpecification CategoryStatus
The bootloader MUST be signed and encrypted and only launched by the SoC firmware if validated.GeneralGeneric
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. GeneralGeneric
The bootloader MUST implement secure boot of PCI and DRI XSigned code images as per Comcast Code Integrity specificationGeneralComcast specific
The bootloader MUST support the launching of standard RDK monolithic code image format and DM-verity code image format. GeneralGeneric
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.GeneralGeneric
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.
GeneralGeneric
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.GeneralGeneric
The bootloader MUST maintain a separate retry count for each code image in a shared flash area.GeneralGeneric
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.GeneralGeneric
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.GeneralGeneric
The retry count for a code image MUST not be decremented when the code image is selected from the launch override screen.GeneralGeneric
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.GeneralGeneric
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.0GeneralComcast specific
Any reset process shall NOT affect the primary or backup values of codeSecureVersion and cvcAccessStart.GeneralComcast specific
The bootloader shall maintain a separate all code image retry count for the case where no code image is found to be valid.GeneralGeneric
If no code image can be validated, the bootloader shall decrement the all code image retry count and reboot.GeneralGeneric
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.GeneralGeneric
In the case where the all code image retry count reaches zero, the bootloader shall display the fatal error screen.GeneralGeneric
Bootloader MUST reset B-DRI retry counter to default on errorGeneralGeneric
The all code image retry count shall not be decremented when the code image is selected from the launch override screen.GeneralGeneric
All screens shall be 1920×1080 resolutionGeneralGeneric
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
GeneralGeneric
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.GeneralGeneric
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
GeneralGeneric
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.GeneralGeneric
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.GeneralGeneric
Bootloader MUST respond to a front panel button press of a predefined number of seconds to trigger force disaster recovery processGeneralGeneric
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.
GeneralGeneric
The forced DRI trigger shall be stored in flash to allow the DRI application to complete the required action.GeneralGeneric
The forced DRI trigger shall be cleared on boot if they are set when the bootloader launces.GeneralGeneric
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 sequencingGeneralGeneric
Bootloader menu MUST display the code image selection screen showing a list of PCI1, PCI2, PDRI, BDRI  and a reboot option.GeneralGeneric
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.GeneralGeneric
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.GeneralGeneric
Bootloader MUST display the LED feedback in a normal booting scenario as per boot LED patternLEDGeneric
Bootloader MUST start the boot LED pattern using the stored intensity valueLEDGeneric
LED intensity in the boot LED pattern MUST be configurable via updatable configuration by PCILEDGeneric
If stored LED intensity value is corrupted Bootloader must use a hardcoded default value for the intensity of the boot LED patternLEDGeneric
Bootloader MUST display the splash screen/startup screen when booting and while processing the code image selection logicUIGeneric
Bootloader MUST display the backup screen if primary splash screen is not validUIGeneric
Bootloader MUST display the error screen if unable to validate and launch any image – B-DRI, P-DRI, PCI1, PCI2UIGeneric
Bootloader MUST display the bootloader menu if boot sequence is interrupted via IR during bootup UIGeneric
Bootloader MUST use the upgradeable screens if valid, otherwise, the bootloader MUST use backup screen for displayUIGeneric
mTLS certificates for firmware download shouldn’t be allowed to changeUIGeneric
EMMC certificates should be encrypted and before usage chipset secure APIs should be used to verify themUIGeneric

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


SpecificationSpecification CategoryStatus
The DRI mechanism MUST validate the image in Disastor recovery memory areaGeneralGeneral
B-DRI and P-DRI MUST be stored in the soft locked upgradeable areaGeneralGeneric
NTP (Network Time Protocol) server URLs to be used MUST be limited to a pre-defined set of NTP serversGeneralGeneric
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>.binGeneralGeneric
The B-DRI and P-DRI MUST request the box to reboot immediately after successfully validating and writing a PCI to flash memoryGeneralGeneric
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 connectivityGeneralGeneral
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
GeneralGeneric
A Cold Factory Reset, Factory Reset MUST invalidate the stored Wi-Fi credentials in the B-DRI & P-DRI and RDK shared flash area.GeneralGeneric
The B-DRI and P-DRI MUST include IR remote control supportGeneralGeneric
B-DRI and P-DRI MAY support bluetooth paired remote. GeneralGeneric
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 receivedGeneralGeneric
B-DRI and P-DRI MUST display Remote reset screen if no paired data is found when DRI is launchedGeneralGeneric
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.GeneralGeneric
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.GeneralGeneric
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.GeneralComcast specific
B-DRI and P-DRI MAY choose to display at a fixed video resolution of 1080p GeneralComcast 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.GeneralComcast 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 interventionGeneralGeneric
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 GeneralGeneric
The DRI Cold Factory Reset trigger key/button sequence MUST be a pre-defined oneGeneralGeneric
The DRI Factory Reset trigger key/button sequence MUST be a pre-defined oneGeneralGeneric
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 sequenceGeneralGeneric
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 activeGeneralComcast specific
A Cold Factory Reset, Factory Reset MUST invalidate the stored video Wi-Fi SSID and Pwd in the RDK shared flash area.GeneralGeneric
B-DRI and P-DRI, MUST reboot after waiting a pre-defined time interval irrespective of current stateGeneralGeneric
B-DRI/P-DRI MUST support downloading images over Ethernet interfaceDownload RequirementsGeneric
B-DRI/P-DRI MUST support downloading images over Wi-Fi InterfaceDownload RequirementsGeneric
The B-DRI and P-DRI MUST perform pre-download verification using XSign Manifest Table, as per code integrity specDownload RequirementsComcast 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 RequirementsComcast 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 RequirementsComcast specific
The B-DRI and P-DRI MUST support device-initiated firmware download Download RequirementsGeneric
The B-DRI and P-DRI MUST support two modes of download operation as described in PCI Firmware UpdateDownload RequirementsGeneric
B-DRI and P-DRI MAY use the google.com, espn.com, speedtest.net for internet connectivity testDownload RequirementsGeneric

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