Earlgrey Utilities (earlgrey_util)

This package provides hardware-specific utility drivers, memory-mapped data structures, and protocol wrappers for the OpenTitan Earlgrey target. These utilities are used across the kernel and userspace processes to interact with target hardware and boot stage configurations.

Key Components

1. Hardware Timer & Clock (clock.rs, timer.rs)

  • EarlGreyTimer: A wrapper for the OpenTitan system timer (RvTimer). It implements an overflow-safe double-read logic for retrieving the 64-bit tick counter on the 32-bit RISC-V platform.
  • now_ticks(): A global convenience function to get the current tick count using a read-only static timer driver.

2. Retention RAM Layout (ret_ram.rs)

  • RetRam: Maps directly to the 4KiB physical Retention SRAM (0x4060_0000). This memory persists across warm resets and contains:
    • Layout version information.
    • Reset reasons.
    • Boot Services payload.
    • The Boot Log.
    • The last shutdown reason (RomError).
    • Owner-specific persistent storage space (2KiB).
  • mut_ref(): Unsafely retrieves a mutable reference to the physical Retention RAM address (requires identity mapping in system configuration).

3. Boot Stage Structures (boot_log.rs, boot_svc.rs, manifest.rs)

  • BootLog: Populated by ROM/ROM_EXT, providing details about the boot process (selected boot slot, versions, sizes, ownership states, and minimum security versions).
  • BootSvc: Structure for the Boot Services protocol. It allows the running application to request actions (like changing the next boot slot, upgrading minimum security versions, or unlocking/transferring ownership) that are executed upon the next reboot.
  • Manifest: Structure for flash boot stage images. Placed at the start of ROM_EXT and BL0 images to describe versions, security requirements, code region bounds, and cryptographic signatures (ECDSA-P256 and optional SPHINCS+).
  • CheckDigest: Trait implemented by BootLog and BootSvc to validate SHA256 integrity digests over their contents. OpenTitan uses a reversed-byte order for digests stored in these structures.
  • GetData<T>: Trait and helper macros to safely extract typed command and response payloads from the generic BootSvc structure's data region.

4. Provisioning & Personalization (perso_tlv.rs)

  • PersoCertificate: A Type-Length-Value (TLV) parser for retrieving manufacturing provisioning certificates (X.509, CWT, device seeds) stored in flash info pages. Handles the custom packed header format and 8-byte padding constraint.

5. Constants & Hardening (tags.rs, mubi.rs)

  • ManifestIdentifier, OwnershipState, BootSlot, UnlockMode, BootSvcKind, OwnershipKeyAlg: Type-safe wrappers around u32 constant magic tags used in the boot protocol.
  • HardenedBool & AsMubi: Support for Multi-bit Booleans (MuBi). Earlgrey hardware uses specific 4-bit sequences (0x6 for True, 0x9 for False) to protect critical boolean choices against single-bit fault injection attacks.

6. Diagnostics & Errors (rom_error.rs, error.rs)

  • RomError: Strongly-typed mapping of raw u32 bootloader error codes (e.g. signature verification failures, key manager faults, flash controller errors).
  • EG_ERROR: Target-specific userspace error module (ASCII 'FL') for logging utilities.

7. Flash Address Mapping (flash.rs)

  • EarlgreyFlashAddress: An extension trait for FlashAddress that implements Earlgrey-specific partition mapping.
    • Uses the most significant bit (MSB) of the 32-bit offset to distinguish between the main DATA partition (MSB=0) and auxiliary INFO partitions (MSB=1).
    • Provides constructors (data(), info()) and helpers to extract the bank, page, and relative offset from an encoded FlashAddress.