OpenTitan

Introduction to OpenTitan

OpenTitan is an open source silicon Root of Trust (RoT) project. OpenTitan will make the silicon RoT design and implementation more transparent, trustworthy, and secure for enterprises, platform providers, and chip manufacturers. OpenTitan is administered by lowRISC CIC as a collaborative project to produce high quality, open IP for instantiation as a full-featured product. This repository exists to enable collaboration across partners participating in the OpenTitan project.

Getting Started

To get started with OpenTitan, see the Getting Started page. For additional resources when working with OpenTitan, see the list of user guides. For details on coding styles or how to use our project-specific tooling, see the reference manuals. Lastly, the Hardware Dashboard page contains technical documentation on the SoC, the Ibex processor core, and the individual IP blocks. For questions about how the project is organized, see the project landing spot for more information.

Understanding OpenTitan

• Use Cases
• Threat Model
• Security

Datasheets

• OpenTitan Earl Grey Chip Datasheet

Documentation

• Hardware
• Software

Development

• Getting Started
• User Guides
• Reference Manuals
• Style Guides

Repository Structure

The underlying repo is set up as a monolithic repository to contain RTL, helper scripts, technical documentation, and other software necessary to produce our hardware designs.

Unless otherwise noted, everything in the repository is covered by the Apache License, Version 2.0. See the LICENSE file and repository README for more information on licensing and see the user guides below for more information on development methodology.

Hardware

This page serves as the landing spot for all hardware development within the OpenTitan project.

We start off by providing links to the results of various tool-flows run on all of our Comportable IPs. This includes DV simulations, FPV and lint, all of which are run with the dvsim tool which serves as the common frontend.

The Comportable IPs following it provides links to their design specifications and DV documents, and tracks their current stage of development. See the Hardware Development Stages for description of the hardware stages and how they are determined.

Next, we focus on all available processor cores and provide links to their design specifications, DV documents and the DV simulation results.

Finally, we provide the same set of information for all available top level designs.

Results of tool-flows

• DV simulation summary results, with coverage (nightly)
• FPV sec_cm results (weekly)
• FPV ip results (weekly)
• FPV prim results (weekly)
• AscentLint summary results (nightly)
• Verilator lint summary results (nightly)
• Style lint summary results (nightly)
• DV Style lint summary results (nightly)
• FPV Style lint summary results (nightly)

Comportable IPs

Processor cores

• core_ibex
  • User manual
  • DV document
  • DV simulation results, with coverage (nightly) (TBD)

Earl Grey chip-level results

• Datasheet
• Specification
• DV Document
• DV simulation results, with coverage (nightly)
• Connectivity results (nightly)
• AscentLint results (nightly)
• Verilator lint results (nightly)
• Style lint results (nightly)
• DV Style lint results (nightly)
• CDC results (nightly)

Earl Grey-specific comportable IPs

Hardware documentation overview

{{% sectionContent %}}

Top Earlgrey

Specification

The specification of Earlgrey is located here.

Tool: TopGen

Top Earlgrey is being generated by the integration tool, topgen (util/topgen.py). Please do not revise rtl/top_earlgrey.sv, the crossbar modules, and the interrupt controller directly. Those files are auto-generated and sit in the repository for browsing purpose.

How to create top module

Top module rtl/top_earlgrey.sv is created by topgen.py. Current top module is created with below command.

../../util/topgen.py -t data/top_earlgrey.hjson -o . -v

It generates files below:

• rtl/top_earlgrey.sv: Top module generated from the template data/top_earlgrey.sv.tpl with the configuration file data/top_earlgrey.hjson
• rtl/xbar_main.sv and rtl/tl_main_pkg.sv: Crossbar module. As of now, earlgrey has only one main crossbar. tlgen library is used to generate these files.
• rtl/rv_plic*.sv and data/rv_plic.hjson: Interrupt controller module. hw/ip/rv_plic/util/reg_rv_plic.py tool is used to create RV_PLIC having the number of interrupts specified in the hjson.

Adding new blocks into top level

Modify data/top_earlgrey.hjson to include new module

• If new block has interrupts, also add to the interrupt_module definition

Modify xbar_main.hjson for the host / device connectivity

Modify configurations

Main configuration for Top Earlgrey is in data/top_earlgrey.hjson. The users need to specify the list of peripherals, memories, crossbars, and the interrupts in the configuration file. The tool then reads relevant information from the each peripheral blocks’ configuration. For instance, if uart module is used, the tool reads hw/ip/uart/data/uart{_reg}.hjson and parses the information such as input/output, the size of its register space, and interrupts.

For the memories, the tool utilizes the type and instantiates relevant modules including the converter from TL-UL interface to the native interfaces (SRAM, ROM, eFlash). The user only needs to describe the base address and the memory size.

The crossbar should be defined in the separate file. Please take a look at data/xbar_main.hjson as an example. In the top configuration, it needs to define the xbar and the clock, then the tool calls tlgen library to create the crossbar design. Please remind that the instance name in the crossbar and that in the module field should be matched for topgen to create fields that tlgen uses.

Modify the template

Main top template file is data/top_earlgrey.sv.tpl. In most cases, it isn’t require to modify the template file. For instance, to add new IP into the top, the user just needs to add the IP to the module field and revise the crossbar connections in the crossbar configuration.

There might be some cases that needs to revise the template. As of now, a few modules are hard-coded such as RISC-V core and the debug module. If any of these modules need to be revised or some new modules not matching to the comportability spec, it needs to be manually instantiated in the template file.

OpenTitan Earl Grey Chip Datasheet

Overview

The OpenTitan Earl Grey chip is a low-power secure microcontroller that is designed for several use cases requiring hardware security. The block diagram is shown above and shows the system configuration, including the Ibex processor and all of the memories and comportable IPs.

As can be seen in the block diagram, the system is split into a fast processor core domain that runs on a 100MHz jittery clock, and a peripheral domain that runs at 24MHz. Further, a portion of the peripheral domain, the analog sensor top and the padring can stay always-on. The rest of the system can be shut off as part of the sleep mode.

The OpenTitan Earl Grey chip provides the following features:

Detailed Specification

For more detailed documentation including the pinout and system address map, see OpenTitan Earl Grey Chip Specification. The OpenTitan Earl Grey Chip DV Document describes the chip-level DV environment and contains the chip-level test plan.

OpenTitan Earl Grey Chip Specification

This document describes the OpenTitan Earl Grey chip functionality in detail. For an overview, refer to the OpenTitan Earl Grey Chip Datasheet.

Theory of Operations

The netlist chip_earlgrey_asic contains the features listed above and is intended for ASIC synthesis, whereas the netlist chip_earlgrey_cw310 provides an emulation environment for the cw310 FPGA board. The code for Ibex is developed in its own lowRISC repo, and is vendored in to this repository. Surrounding Ibex is a suite of Comportable peripherals that follow the Comportability Guidelines for lowRISC peripheral IP. Each of these IP has its own specification. See the table produced in the hardware documentation page for links to those specifications.

Design Details

This section provides some details for the processor and the peripherals. See their representative specifications for more information. This section also contains a brief overview of some of the features of the final product.

Clocking and Reset

Clocks and resets are supplied from the Analog Sensor Top, referred to as ast) from this point onwards in the document.

ast supplies a number of clocks into top_earlgrey.

• sys: main jittery system clock used for higher performance blocks and security (processory, memory and crypto blocks).
• io: a fixed clock used for peripheral blocks such as timers and I/O functionality, such as SPI or I2C.
• usb: a fixed clock used specifically for usb operations.
• aon: an always on, low frequency clock used for power management and low speed timers.

These clocks are then divided down and distributed to the rest of the system. See clock manager) for more details.

ast also supplies a number of power-okay signals to top_earlgrey, and these are used as asynchronous root resets.

• vcaon_pok: The always on domain of the system is ready.
• vcmain_pok: The main operating domain of the system is ready.

When one of these power-okay signals drop, the corresponding domain in top_earlgrey is reset. Please refer to reset manager) for more details. Resets throughout the design are asynchronous active low as per the Comportability specification.

Once reset, the reset vector begins in ROM, whose job is to validate code in the embedded flash before jumping to it. Valid code is assumed to have been instantiated into the flash, if not, the ROM shuts down the device unless prompted to bootstrap.

There are multiple avenues to load valid code into the flash:

1. JTAG initiated flash programming.
2. ROM bootstrap

AST Clocking and Reset Relationship

While the ast supplies clocks and resets to the top_earlgrey, it also contains additional functions that interact with the design. These include the RNG, ADC, jittery clock controls and an assortment of other sensors. The operating clocks and resets for these interfaces are supplied by the device in order to ensure correct synchronous operations. The clock mapping is shown below:

The reset clock domain is identical to the table above, and the power domain mapping is shown below

System Reset Handling and Flash

Since top_earlgrey contains flash, it is important to examine the memory’s relationship with resets.

For flash, resets that occur during a stateful operation (program or erase) must be carefully handled to ensure the flash memory is not damaged. There are three reset scenarios:

• Reset due to external supply lowering.
• Reset due to internal peripheral request.
• Reset due to lower power entry and exit.

Reset due to External Supply

Device resets due to supply dropping below a specific threshold are commonly known as “brown-out”. When this occurs, the flash memory must go through specialized sequencing to ensure the cells are not damaged. This process is handled exclusively between ast and the flash. Please see the relevant section for more details.

Reset due to Internal Request

When the device receives an internal request to reset (for example aon_timer), device power is kept on and the flash is directly reset. It is assumed that the flash device, when powered, will be able to correctly handle such a sequence and properly protect itself.

Reset due to Low Power Entry

When the device receives a low power entry request while flash activity is ongoing, the pwrmgr) is responsible for ensuring the entry request is aborted.

Main processor (core_ibex)

The main processor (core_ibex) is a small and efficient, 32-bit, in-order RISC-V core with a 2-stage pipeline that implements the RV32IMC instruction set architecture. It was initially developed as part of the PULP platform under the name “Zero-riscy” [1], and has been contributed to lowRISC who maintains it and develops it further. See the core_ibex specification for more details of the core. In addition to the standard RISC-V functionality, Ibex implements M (machine) and U (user) mode per the RISC-V standard. Attached to the Ibex core are a debug module (DM) and interrupt module (PLIC).

JTAG / Debug module

One feature available for Earl Grey processor core is debug access. By interfacing with JTAG pins, logic in the debug module allows the core to enter debug mode (per RISC-V 0.13 debug spec), and gives the design the ability to inject code either into the device - by emulating an instruction - or into memory. Full details can be found in the rv_dm specification.

Interrupt Controller

Adjacent to the Ibex core is an interrupt controller that implements the RISC-V PLIC standard. This accepts a vector of interrupt sources within the device, and assigns leveling and priority to them before sending to the core for handling. See the details in the rv_plic specification.

Performance

Ibex currently achieves a CoreMark per MHz of 2.36 on the earlgrey verilator system. Performance improvements are ongoing, including the following items being considered:

1. Adding a new ALU to calculate branch targets to remove a cycle of latency on taken conditional branches (currently the single ALU is used to compute the branch condition then the branch target the cycle following if the branch is taken).
2. A 3rd pipeline stage to perform register writeback, this will remove a cycle of latency from all loads and stores and prevent a pipeline stall where a response to a load or store is available the cycle after the request.
3. Implement a single-cycle multiplier.
4. Produce an imprecise exception on an error response to a store allowing Ibex to continue executing past a store without waiting for the response.

The method for including these features, e.g. whether they will be configurable options or not, is still being discussed.

The Ibex documentation has more details on the current pipeline operation, including stall behaviour for each instruction in the Pipeline Details section.

The CoreMark performance achieved relies in part on single-cycle access to instruction memory. An instruction cache is planned to help maintain this performance when using flash memory that will likely not have single-cycle access times.

CoreMark was compiled with GCC 9.2.0 with flags: -march=rv32imc -mabi=ilp32 -mcmodel=medany -mtune=sifive-3-series -O3 -falign-functions=16 -funroll-all-loops -finline-functions -falign-jumps=4 -mstrict-align

Memory

The device contains three memory address spaces for instruction and data.

Instruction ROM (32kB) is the target for the Ibex processor after release of external reset. The ROM contains hard-coded instructions whose purpose is to do a minimal subset of platform checking before checking the next stage of code. The next stage - a boot loader stored in embedded flash memory - is the first piece of code that is not hard-coded into the silicon of the device, and thus must be signature checked. The ROM executes this signature check by implementing a RSA-check algorithm on the full contents of the boot loader. The details of this check will come at a later date. For verification execute-time reasons, this RSA check will be overridable in the FPGA and verification platforms (details TBD). This is part of the Secure Boot Process that will be detailed in a security section in the future.

Earl Grey contains 1024kB of embedded-flash (e-flash) memory for code storage. This is intended to house the boot loader mentioned above, as well as the operating system and application that layers on top. At this time there is no operating system provided; applications are simple proof of concept code to show that the chip can do with a bare-metal framework.

Embedded-flash is the intended technology for a silicon design implementing the full OpenTitan device. It has interesting and challenging parameters that are unique to the technology that the silicon is implemented in. Earl Grey, as an FPGA proof of concept, will model these parameters in its emulation of the memory in order to prepare for the replacement with the silicon flash macros that will come. This includes the read-speeds, the page-sized erase and program interfaces, the two-bank update scheme, and the non-volatile nature of the memory. Since by definition these details can’t be finalized until a silicon technology node is chosen, these can only be emulated in the FPGA environment. We will choose parameters that are considered roughly equivalent of the state of the art embedded-flash macros on the market today.

Details on how e-flash memory is used by software will be detailed in future Secure Boot Process and Software sections over time.

The intent is for the contents of the embedded flash code to survive FPGA reset as it would as a NVM in silicon. Loading of the FPGA with initial content, or updating with new content, is described in other software specifications. The SPI device peripheral is provided as a method to bulk-load e-flash memory. The processor debug port (via JTAG) is also available for code loading. See those specifications for more details.

Also included is a 128kB of SRAM available for data storage (stack, heap, etc.) by the Ibex processor. It is also available for code storage, though that is not its intended purpose.

The base address of the ROM, Flash, and SRAM are given in the address map section later in this document.

Peripherals

Earl Grey contains a suite of “peripherals”, or subservient execution units connected to the Ibex processor by means of a bus interconnect. Each of these peripherals follows an interface scheme dictated in the Comportability Specification.. That specification details how the processor communicates with the peripheral (via TLUL interconnect); how the peripheral communicates with the chip IO (via fixed or multiplexable IO); how the peripheral communicates with the processor (interrupts); and how the peripheral communicates security events (via alerts). See that specification for generic details on this scheme.

Chip IO Peripherals

Pin Multiplexor Module (pinmux)

The pin multiplexor’s purpose is to route between peripherals and the available multiplexable IO of the chip. At this time, the pin multiplexor is provided, but it is not used to its full potential. In addition, the multiplexor device manages control or pad attributes like drive strength, technology (OD, OS, etc), pull up, pull down, etc., of the chip’s external IO. It is notable that there are many differences between an FPGA implementation of Earl Grey and an ASIC version when it comes to pins and pads. Some pad attributes with analog characteristics like drive strength, slew rate and Open Drain technology are not supported on all platforms.

The pin multiplexor is a peripheral on the TLUL bus, with collections of registers that provide software configurability. See the pinmux specification for how to connect peripheral IO to chip IO and for information on pad control features.

UART

The chip contains one UART peripheral that implement single-lane duplex UART functionality. The outputs and inputs can be configured to any chip IO via the pinmux.

See the UART specification for more details on this peripheral.

GPIO

The chip contains one GPIO peripheral that creates 32 bits of bidirectional communication with the outside world via the pinmux. Via pinmux any of the 32 pins of GPIO can be connected to any of the 32 MIO chip pins, in any direction. See the GPIO specification for more details on this peripheral. See the pinmux specification for how to connect peripheral IO to chip IO.

SPI device

The SPI device implements multiple modes:

• Firmware mode
• TPM mode
• Flash mode
• Passthrough mode

Firmware Mode is a generic data transfer mode. It can be used by software to construct a simple firmware upgrade mechanism for in-field devices.

TPM mode supports SPI transfers in compliance with the TPM PC Client Platform. The interface is single data lane and supports built-in data back pressuring.

Flash mode supports serial flash emulation. Typical commands such as read status, address mode, read data and program data are either natively supported or can be emulated.

Passthrough mode supports serial flash passthrough from an upstream SPI host to a downstream serial flash device.

See the SPI device specification for more details.

USB device

The chip contains a single module that supports USB device mode at full speed. In addition to normal functionality, USB suspend / resume is supported alongside the chip’s low power modes.

See the USB device specification for more details.

I2C host

In order to be able to command I2C devices on systems where Earl Grey will be included, I2C host functionality will be required. This will include standard, full, and fast mode, up to 1Mbaud. More details of the I2C host module will come in a later specification update. The pins of the I2C host will be available to connect to any of the multiplexable IO (MIO) of the Earl Grey device. More than one I2C host module might be instantiated in the top level.

Security Peripherals

AES

AES is the primary symmetric encryption and decryption mechanism used in OpenTitan protocols. AES runs with key sizes of 128b, 192b, or 256b. The module can select encryption or decryption of data that arrives in 16 byte quantities to be encrypted or decrypted using different block cipher modes of operation. It supports ECB mode, CBC mode, CFB mode, OFB mode and CTR mode.

The GCM mode is not implemented in hardware, but can be constructed using AES in counter mode. The integrity tag calculation can be implemented in Ibex and accelerated via bitmanip instructions.

Details on how to write key and data material into the peripheral, how to initiate encryption and decryption, and how to read out results, are available in the AES specification.

SHA-256/HMAC

SHA-256 is the primary hashing algorithm used in OpenTitan protocols. SHA-256 is a member of the SHA-2 family of hashing algorithms, where the digest (or hash output) is of 256b length, regardless of the data size of the input to be hashed. The data is sent into the SHA peripheral after declaring the beginning of a hash request (effectively zeroing out the internal state to initial conditions), 32b at a time. Once all data has been sent, the user can indicate the completion of the hash request (with optional partial-word final write). The peripheral produces the hash result available for register read by the user. All data transfer is processor-available, i.e. data is passed into the module via register writes.

HMAC is a message authentication protocol layered on top of a hashing function (in this case SHA-256), mixing in a secret key for cryptographic purposes. HMAC is a particular application of appending the secret key in a prescribed manner, twice, around the hashing (via SHA-256) of the message.

Details on how to write key and data material into the peripheral, how to initiate hashing / authentication, and how to read out results, are available in the SHA/HMAC specification.

Alert Handler

Alerts, as defined in the Comportability Specification, are defined as security-sensitive interrupts that need to be handled in a timely manner to respond to a security threat. Unlike standard interrupts, they are not solely handled by software. Alerts trigger a first-stage request to be handled by software in the standard mode as interrupts, but trigger a second-stage response by the alert handler if software is not able to respond. This ensures that the underlying concern is guaranteed to be addressed if the processor is busy, wedged, or itself under attack.

Each peripheral has an option to present a list of individual alerts, representing individual threats that require handling. These alerts are sent in a particular encoding method to the alert handler module, itself a peripheral on the system bus. See the details of the alert handler specification for more information.

TRNG entropy source

Randomness is a critical part of any security chip. It provides variations in execution that can keep attackers from predicting when the best time is to attack. It provides secret material used for identity and cryptographic purposes. It can be seeded into algorithmic computation to obscure sensitive data values. In short, it is a source of critical functionality that must be designed to be truly random, but also free from attack itself.

Most TRNGs (True Random Number Generators) are analog designs, taking advantage of some physical event or process that is non-deterministic. Example designs rely on metastability, electronic noise, timing variations, thermal noise, quantum variation, etc. These are then filtered and sent into a pool of entropy that the device can sample at any time, for whatever purposes are needed. The creation, filtering, storage, protection, and dissemination of the randomness are all deep topics of intense research in their own right.

The primary interface to the entropy pool is a read request of available random bits. The TRNG interface can indicate how many bits are available, and then software can read from this pool, if available. Reading of entropy that is not available should immediately trigger an interrupt or an alert.

Since silicon is required to contain an analog design tied to the final chosen silicon technology process, our FPGA implementation can only approximate the results. We however fully specify the software interface to the TRNG in a digital wrapper. In FPGA we emulate the randomness with something akin to a PRBS.

Other peripherals

Timer(s)

Timers are critical for operating systems to ensure guaranteed performance for users. To some level they are even required by the RISC-V specification. At this time, one timer is provided, a 64b free running timer with a guaranteed (within a certain percentage) frequency. A second one acting as a watchdog timer that can be used to backstop the processor in the case of it being unresponsive (usually due to development code that is wedged, rather than for instance due to security attack) will be provided in the future. The goal is for both of these to be satisfied with the same timer module.

The specification for the timer can be found here.

Flash Controller

The final peripheral discussed in this release of the netlist is an emulated flash controller. As mentioned in the memory section, up to 1024kB of emulated embedded flash is available for code and data storage. The primary read path for this data is in the standard memory address space. Writes to that address space are ignored, however, since one can not write to flash in a standard way. Instead, to write to flash, software must interact with the flash controller.

Flash functionality include three primary commands: read, erase, and program. Read, as mentioned above, is standard, and uses the chip memory address space. Erase is done at a page level, where the page size is parameterizable in the flash controller. Upon receiving an erase request, the flash controller wipes all contents of that page, rendering the data in all 1s state (0xFFFFFFFF per word). Afterwards, software can program individual words to any value. It is notable that software can continue to attempt to program words even before another erase, but it is not physically possible to return a flash bit back to a '1' state without another erase. So future content is in effect an AND of the current content and the written value.

next_value = AND(current_value, write_word)

Erase and program are slow. A typical erase time is measured in milliseconds, program times in microseconds. The flash controller peripheral in this release approximates those expected times.

Security is also a concern, since secret data can be stored in the flash. Some memory protection is provided by the flash controller. For more details see the flash controller module specification.

Interconnection

Interconnecting the processor and peripheral and memory units is a bus network built upon the TileLink-Uncached-Light protocol. See the OpenTitan bus specification for more details.

Topology

top_earlgrey has a two-level hierarchy for its bus network. Close to the CPU is the high-speed cluster, with low access latency. Farther from the CPU, through a low-speed bridge, is the low-speed cluster, with higher access latency.

Performance

The following table describes the typical number of CPU cycles from a transaction’s launch to its completion for a device in the specified cluster. Note that these values assume there is no bus contention.

Memory Map

The base addresses of the memory and peripherals are given in the table below.

The choice of memory, or lack thereof at location 0x0 confers two exclusive benefits:

• If there are no memories at location 0x0, then null pointers will immediately error and be noticed by software (the xbar will fail to decode and route)
• If SRAM is placed at 0, accesses to data located within 2KB of 0x0 can be accomplished with a single instruction and thus reduce code size.

For the purpose of top_earlgrey, the first option has been chosen to benefit software development and testing

Hardware Interfaces

Pinout

RTL Implementation Notes

At this time, the top-level netlist for earlgrey is a combination of hand-written SystemVerilog RTL with auto-generated sections for wiring of comportability interfaces. There is a script for this auto-generation, centered around the top-level descriptor file top_earlgrey.hjson found in the repository. A full definition of this descriptor file, its features, and related scripting is forthcoming. This tooling generates the interconnecting crossbar (via TLUL) as well as the instantiations at the top level. It also feeds into this document generation to ensure that the chosen address locations are documented automatically using the data in the source files.

Top Level vs Chip Targets

It should first be NOTED that there is some subtlety on the notion of hierarchy within the top level. There is netlist automation to create the module top_earlgrey as indicated in sections of this specification that follow. On top of that module, hierarchically in the repo, are chip level instantiation targets directed towards a particular use case. This includes chip_earlgrey_cw310 for use in FPGA, and chip_earlgrey_asic for use (eventually) in a silicon implementation. These chip level targets will include the actual pads as needed by the target platform. At the time of this writing the two are not in perfect synchronization, but the intention will be for them to be as identical as possible. Where appropriate, including the block diagram below, notes will be provided where the hierarchy subtleties are explained.

FPGA Platform

TODO: This section needs to be updated once pin updates are complete.

In the FPGA platform, the logic for the JTAG and the SPI device are multiplexed within chip_earlgrey_cw310. This is done for ease of programming by the external host.

References

1. Schiavone, Pasquale Davide, et al. “Slow and steady wins the race? A comparison of ultra-low-power RISC-V cores for Internet-of-Things applications.” 27th International Symposium on Power and Timing Modeling, Optimization and Simulation (PATMOS 2017)

OpenTitan Earl Grey Chip DV Document

Goals

• DV
  • Verify top_earlgrey features by running dynamic simulations with a SV/UVM based testbench.
  • Verify the integration of all pre-verified IPs instantiated in the chip.
  • Verify the integration and the internal design of non-pre-verified IPs instantiated in the chip.
  • Verify system level scenarios for correctness of our design assumptions and behavior.
  • Verify the full chip configuration and memory address space by running the automated tests.
  • Stress test the XBAR structures in the chip.
• FPV
  • Verify the connectivity of signals (that are excluded from functional DV above) from point A to point B.
  • Secure verification
    • Check for leakage of secure data into unsecure locations / paths and vice-versa using the Cadence SPV tool.

Current status

• Design & verification stage
  • HW development stages
• Simulation results

Design features

For detailed information on top_earlgrey design features, please see the Earl Grey Top Level Specification.

Testbench architecture

The top_earlgrey chip level testbench has been constructed based on the CIP testbench architecture.

Block diagram

TBD

Top level testbench

Top level testbench is located at hw/ip/top_earlgrey/dv/tb/tb.sv. It instantiates the top_earlgrey DUT module hw/top_earlgrey/rtl/autogen/chip_earlgrey_asic.sv. In addition, it instantiates the following interfaces, connects them to the DUT and sets their handle into uvm_config_db:

• Clock and reset interface
  • Main clock as well as USB clock
• TileLink host interface
  • This is connected to the CPU’s data port.
• JTAG interface
• SPI interface
• UART interface
• SW logger interface (for test boot ROM as well as the test SW)
• SW test status monitor
• Backdoor memory interfaces (for ROM, SRAM and the flask banks)
• Individual control pins:
  • Bootstrap
  • JTAG/SPI switch
  • SRST_N

Common DV utility components

The following utilities provide generic helper tasks and functions to perform activities that are common across the project:

• dv_utils_pkg
• csr_utils_pkg

Global types & methods

All common types and methods defined at the package level can be found in the chip_env_pkg. Some of them in use are:

[list a few parameters, types & methods; no need to mention all]

TL_agent

The full chip testbench instantiates (already handled in CIP base env) the tl_agent which provides the ability to drive and independently monitor random traffic via TL host interface into CHIP device.

UART Agent

[Describe here or add link to its README]

SPI Agent

[Describe here or add link to its README]

JTAG Agent

[Describe here or add link to its README]

I2C Agent

[Describe here or add link to its README]

USB20 Agent

[Describe here or add link to its README]

UVM RAL Model

The CHIP RAL model is created with the ralgen FuseSoC generator script automatically when the simulation is at the build stage.

It can be created manually (separately) by running make in the the hw/ area.

Reference models

Testbench configurations

Stub CPU mode

Bare-metal SW test mode

XBAR integration mode

Stimulus strategy

Test sequences

All test sequences reside in hw/ip/chip/dv/env/seq_lib. The chip_base_vseq virtual sequence is extended from cip_base_vseq and serves as a starting point. All test sequences are extended from chip_base_vseq. It provides commonly used handles, variables, functions and tasks that the test sequences can simple use / call. Some of the most commonly used tasks / functions are as follows:

• task 1:
• task 2:

Functional coverage

To ensure high quality constrained random stimulus, it is necessary to develop a functional coverage model. The following covergroups have been developed to prove that the test intent has been adequately met:

• cg1:
• cg2:

Self-checking strategy

Scoreboard

The chip_scoreboard is primarily used for end to end checking. It creates the following analysis ports to retrieve the data monitored by corresponding interface agents:

• analysis port1:
• analysis port2:

Assertions

• TLUL assertions: The tb/chip_bind.sv binds the tlul_assert assertions to the IP to ensure TileLink interface protocol compliance.
• Unknown checks on DUT outputs: The RTL has assertions to ensure all outputs are initialized to known values after coming out of reset.
• assert prop 1:
• assert prop 2:

Building and running tests

DV simulations for top_earlgrey are run with the dvsim tool. Please take a look at the link for detailed information on the usage, capabilities, features and known issues. The basic UART transmit and receive test can be run with the following command:

$ ./util/dvsim/dvsim.py hw/top_earlgrey/dv/chip_sim_cfg.hjson -i chip_sw_uart_tx_rx

For a list of available tests to run, please see the ‘Tests’ column in the testplan below.

Regressions

Sanity

SW access

Nightly

Testplan (RTL simulations)

Testplan

Testplan (Gate level simulations)

Note that the descriptions of the test below may be replicated from the table above. Testplan

Analog Sensor Top Technical Specification

Overview

AST, also known as the analog sensor top, is the OpenTitan analog and security companion. Within AST are various analog functions (such as clocks, regulators, random number generators) needed to make the device function, as well as physical security sensors necessary to protect the device from physical attacks or manipulation.

At a high level, AST communicates with a number of OpenTitan comportable modules. See diagram below.

In the following sections, each family of connection is briefly described and explained. Note, the analog connections to AST are not shown in the diagram, but will be explained as well.

Interface Signals Table

Table notes

Signal naming conventions used in this document

It complies with OpenTitan names and suffixes with some augmentations.

• Clock signals start with clk_*

• Inputs and outputs are marked with *_i/o

• Analog signals are marked with *_a

• Non-core level signals are marked with *_h

• Dual and negative polarity signals are marked with *_p/n

Clock domains column

• sys - system clock, mainly used for high performance and security modules. Up to 100MHz

• io - peripheral clock source, mainly used for peripherals and I/O related functionality. Up to 96MHz (divided by 4 by the clock manager)

• usb - USB module source clock. 48MHz

• aon - Always-on domain clock. The only active clock while chip is in deep-sleep power state, 200KHz

• async - when listed as async, it means it does not matter what domain drives the signal

• Input clocks: Each functional interface has a dedicated clock named after the interface.

Interfaces Description Note

The information below augments the Interface Signals Table. For further details, see the corresponding signals description in the table.

Power Connectivity

Note: Power signals may not appear in the verilog files, however, they are described for completeness.

External Supplies

AST has four external power supplies VCC, AVCC, VIOA and VIOB. VCC is the main supply, AVCC is an analog VCC supply. VIOA and VIOB are two additional I/O supplies.

Core Supplies

The core supplies are generated from the VCC supply. There are two core supply domains: VCMAIN and VCAON. VCAON, as its name implies, is the always-on core supply used to power components that stay active during device low power states. VCMAIN on the other hand, powers most chip logic such as RISC-V processor, crypto modules and almost all memories and peripherals. The VCMAIN supply can be turned off when requested, VCAON on the other hand, is active whenever VCC is active. AST core logic is powered by VCAON.

Power Control and Reset

Core Power Control and Indication

VCMAIN is the only supply that can be directly influenced by OpenTitan. The power manager can request VCMAIN to shutdown through main_pd_ni. The state of VCMAIN is reflected by the vcmain_pok_o signal.

IO Power Indication

IO power state is reflected to OpenTitan by vioa_pok_o and viob_pok_o signals

Main (VCC) Power Detection and Flash Protection

On VCC power-down detection, ‘flash_power_ready_h_o’, is immediately negated. In addition, SYS clock, IO clock and USB clock are stopped. This means that negation of the VCC supply always triggers the flash brown-out (BOR) protection circuitry.

When entering deep-sleep mode, ‘flash_power_down_h_o’ is asserted before negating VCMAIN until VCMAIN is back up.

Resets

The AST supports the generation of the root reset for the reset manager. It is driven by ‘vcaon_pok_o’ which is generated inside AST. The ‘vcaon_pok_o’ is activated when the following conditions are met: VCC is detected, internal voltage regulator is active and ‘por_ni’ reset input is inactive. ‘por_ni’ is driven by an external chip reset pin. The following table and diagrams describe the AST sub-modules resets.

Clock Outputs

AST generates four clocks: System clock, IO clock, USB clock and Always-on clock. Most clocks have ‘enable’ inputs and a corresponding ‘valid’ output. When the enable is de-asserted, the corresponding clock stops and valid is dropped to 0. When the enable is asserted, the clocks begin outputting in a ‘glitchless’ manner and the valid is raised to 1. Unless noted otherwise, clocks duty cycle is 50% +/-5%. At boot time, clocks start toggling at a different (typically slower) frequency than their target. They are configured to their target frequency by the ROM code. Once configured, their frequency is maintained within +/-3% of their target as long as the chip remains in its intended operating conditions until the next boot.

The OpenTitan power and clock managers are responsible for manipulating the enables and observing the valids to know when clocks can be safely released to the system.

USB Clock Calibration

The USB clock requires an accuracy that cannot be achieved by the AST clocks natively. As a result, information from USB frames are used to calibrate the clock.

Clock and Reset Inputs

The root clocks and resets are generated inside AST. However, the clocks go through gating and optional division in the OpenTitan top level and propagate back into AST as feedback clocks, each with associated synchronized reset de-assertion to ensure it can synchronize with the various comportable modules. The input resets are used for the different AST interface functions. For further details about AST resets, see Resets section.

Note: There are several reasons for routing leaf clocks back into AST instead of using the root clocks directly

• The leaf clocks may be divided down from the root clock and that frequency is used to drive the interface. For example, clk_src_io_clk_o is 96MHz, but comportable modules use either 48MHz or 24MHz.

• The leaf clocks and root clocks have very different clock tree depths and may be difficult for timing closure if they interacted directly.

• Decouple AST internal design from OpenTitan top-level interfaces clock and reset selection.

Register Access Interface

AST registers can be accessed via TL-UL interface. These registers are used for test and calibration purposes and are not required for runtime operation. See the Interface Signals Table for more details.

AST registers initialization during boot.

In PROD*/DEV Lifecycle states, the ROM code must copy all AST REGA registers values from OTP to AST. During other Lifecycle states, the ROM code may also copy all AST REGA registers. It is recommended for the ROM code to condition the copy by a digest verification of the register values. If such a digest is too complicated, a simple tag can be used to condition the copy instead. The AST register copy operation must be performed in order and must include all REGA registers (starting from REGA0 and ending at the last REGA). AST sets the ast_init_done_o signal after the copy completion.

After the copy, ROM code can either poll for ast_init_done_o assertion with 100 us timeout (in practice, it should take way less) or ignore it and let the next SW layers handle it. It is recommended to set an OTP field for determining the ROM code action.

The boot code is expected to check all AST output alert signals before handing over the control to the next code layer (ROM_EXT). The ROM code response per alert should be defined in a dedicated OTP space. Recommended response types (per alert):

1. Do nothing and don’t clear the event

2. Do nothing (continue to the next SW layer) and clear the event

3. Log the event in some NV space and halt

4. Halt immediately

Note that in TEST_UNLOCK*/RMA state, the booter should always act per #1 regardless of the OTP setting.

It is recommended to redundantly code the OTP fields that control the ROM code branching and also to protect the branching code from fault injection.

ADC

AST contains an analog to digital converter that can be used to sample various input signals. For OpenTitan this will primarily be used for debug cable detection. To activate the ADC, the corresponding comportable module must first activate the ADC through ‘adc_pd_i’. Once activated, it should select the channel to sample. Channel transition from zero to non-zero value starts the ADC conversion. The ADC output is synchronous to the ADC controller.

ADC Usage Flow

1. Activate the ADC by negating ‘adc_pd_i’

2. Wait 30 uS for the ADC to wake up.

3. Select an analog channel to measure by setting the corresponding bit in ‘adc_chnsel_i’ bus. This triggers a measurement.

4. Wait until ‘adc_d_val’ is set and read the result via ‘adc_d_o’

5. Clear ‘adc_chnsel_i’ bus to 0. Note that adc_chnsel must be cleared to 0 before a new channel is selected.

6. Repeat steps 3-5 if more channels or more measurements are required

7. Deactivate the ADC by setting ‘adc_pd_i’ to save power.

Random Number Generator

AST contains a random number generator that outputs random number bitstreams whenever it is enabled. After enabled by the comportable controller through ‘rng_en_i’, the AST begins generating multiple independent four random bit streams. rng_b_o bit streams are valid and can be sampled whenever ‘rng_val_o’ is asserted according to the following diagram.

The expected rng_b_o valid output rate is about 50KHz. For more information on the RNG interface, please see the OpenTitan entropy source module.

Entropy Consumption

AST consumes entropy for defensive purposes. However, AST does not consume its raw entropy directly. Instead, AST receives entropy from the Entropy Distribution Network (EDN). Note that entropy_ack and entropy_i are packed into enropy_rsp_i in the interface. Also note that once entropy_req_o is set, it will remain set until ack or until reset.

Countermeasures and Alerts

Alert Events

AST’s sensors and detectors, when triggered, output alert events to a sensor controller. The event signals are level until acknowledged by the controller. Further, the events are differentially encoded to ensure they cannot be hard-wired or faulted to either ‘1’ or ‘0’.

Inside the sensor controller, the events are then converted into alerts as part of the wider OpenTitan alert handling system.

Alert Signaling

Outgoing alert events are level. Incoming event ack signals clear the alert event (similar to an interrupt). Outgoing alert events should be OR’d inside the sensor or power manager (depending on what level of deep sleep support is needed) to generate wakeup, that way AST does not need to do any additional handling for wakeups during low power mode.

The AST defines each alert signal in both positive (P) and negative (N) polarity (see ast_dif_t typedef with ‘p’ and ‘n’ signals), however, the P and N signals are not necessarily fully differential, for example, at times, it might occur that both P and N are at the same value. For alert_o case, the correct way to treat it is to propagate an alert signal if either P is high or N is low.

Countermeasures

Most countermeasure enablement is controlled by Nuvoton via the registers interface. Clock jitter is an exception because there is a reasoning for dynamically turning it on and off (security/performance tradeoff). Unless stated otherwise, countermeasures are active in all modes but deep-sleep.

Alert Handler Technical Specification

Overview

This document specifies the functionality of the alert handler mechanism. The alert handler is a module that is a peripheral on the chip interconnect bus, and thus follows the Comportability Specification. It gathers alerts - defined as interrupt-type signals from other peripherals that are designated as potential security threats - throughout the design, and converts them to interrupts that the processor can handle. If the processor does not handle them, the alert handler mechanism provides hardware responses to handle the threat.

Features

• Differentially-signaled, asynchronous alert inputs from NAlerts peripheral sources, where NAlerts is a function of the requirements of the peripherals.

• Ping testing of alert sources:

  • responder module requests periodic alert response from each source to ensure proper wiring.
  • reset-asserted and clock-gated information is used to temporarily pause the ping mechanism on alert channels that are in a low-power state.

• Register locking on all configuration registers.

  • Once locked, can not be modified by software until next system reset.

• Register-based assignment of alert to alert-class.

  • Four classes, can be individually disabled.
  • Each class generates one interrupt.
  • Disambiguation history for software to determine which alert caused the class interrupt.
  • Each class has configurable response time for escalation.
  • Disable allows for ignoring alerts, should only be used in cases when alerts are faulty. Undesirable access is enforced by locking the register state after initial configuration.

• Register-based escalation controls.

  • Number of alerts in class before escalation.
  • Timeout for unhandled alert IRQs can also trigger escalation.
  • Configurable escalation enables for 4 escalation signals.
    • Could map to NMI, wipe secrets signal, lower privilege, chip reset, etc.
    • Escalation signals differentially-signaled with heartbeat, will trigger response if differential or heartbeat failure at destination.
  • Configurable time in cycles between each escalation level.

• Two locally sourced hardware alerts.

  • Differential signaling from a source has failed.
  • Ping response from a source has failed.

Description

The alert handler module manages incoming alerts from throughout the system, classifies them, sends interrupts, and escalates interrupts to hardware responses if the processor does not respond to any interrupts. The intention is for this module to be a stand-in for security responses in the case where the processor can not handle the security alerts.

It is first notable that all security alerts are rare events. Module and top level designers should only designate events as alerts if they are expected to never happen, and if they have potential security consequences. Examples are parity errors (which might indicate an attack), illegal actions on cryptography or security modules, physical sensors of environmental modification (e.g. voltage, temperature), etc. Alerts will be routed through this module and initially converted to interrupts for the processor to handle. The expectation is that the secure operating system has a protocol for handling any such alert interrupt in software. The operating system should respond, then clear the interrupt. Since these are possible security attacks, the response is not always obvious, but the response is beyond the scope of this document.

This module is designed to help the full chip respond to security threats in the case where the processor is not trusted: either it has been attacked, or is not responding. It does this by escalating alerts beyond a processor interrupt. It provides four such escalation signals that can be routed to chip functions for attack responses. This could include such functions as wiping secret chip material, power down, reset, etc. It is beyond the scope of this document to specify what those escalation responses are at the chip level.

To ease software management of alerts, classification is provided whereby each alert can be classified into one of four classes. How the classification is done by software is beyond the scope of this document, but it is suggested that alerts of a similar profile (risk of occurring, level of security concern, frequency of false trigger, etc) are classed together. For each class a counter of alerts is kept, clearable by software. If that counter exceeds a programmable maximum value, then the escalation protocol for that class begins.

The details for alert signaling, classification, and escalation are all given in the Theory of Operations section.

Theory of Operation

Block Diagram

The figure below shows a block diagram of the alert handler module, as well as a few examples of alert senders in other peripheral modules. In this diagram, there are seven sources of alerts: three sources from external modules (two from periph0 and one from periph1), and four local sources (alert_ping_fail, alert_sig_int, esc_ping_fail, esc_sig_int). The local sources represent alerts that are created by this module itself. See the later section on special local alerts.

Also shown are internal modules for classification, interrupt generation, accumulation, escalation, ping generation and alert-channel low-power control. These are described later in the document. Note that the differential alert sender and receiver blocks used for alert signaling support both asynchronous and synchronous clocking schemes, and hence peripherals able to raise alerts may be placed in clock domains different from that of the alert handler (Jittered clock domains are also supported in the asynchronous clocking scheme). Proper care must however be taken when formulating the timing constraints for the diff pairs, and when determining clock-dependent parameters (such as the ping timeout) of the design. On the escalation sender / receiver side, the differential signaling blocks employ a fully synchronous clocking scheme throughout.

Hardware Interfaces

Parameters

The following table lists the main parameters used throughout the alert handler design. Note that the alert handler is generated based on the system configuration, and hence these parameters are placed into a package as “localparams”. The parameterization rules are explained in more detail in the architectural description.

The next table lists free parameters in the prim_alert_sender and prim_alert receiver submodules.

Signals

• Interface Tables

The table below lists other alert handler module signals. The number of alert instances is parametric and hence alert and ping diff pairs are grouped together in packed arrays. The diff pair signals are indexed with the corresponding alert instance <number>.

Entropy Network Connections

The LFSR ping timer needs to be periodically reseeded. Therefore, the alert handler is connected to the entropy distribution network via the edn_i/o signals.

Alert Channels

For each alert, there is a pair of input and two pairs of output signals. These signals are connected to a differential sender module within the source, and a differential receiver module within the alert handler. Both of these modules are described in more detail in the following section. These signal pairs carry differentially encoded messages that enable two types of signaling: a native alert and a ping/response test of the alert mechanism. The latter is to ensure that all alert senders are always active and have not been the target of an attack.

Escalation Channels

For each escalation action in the system, there is a pair of input and a pair of output signals, encapsulated in the esc_rx_t and esc_tx_t types. These signals are connected to a differential sender module within the alert handler, and a differential receiver module within the module that performs a particular escalation action (for example the reset manager or life cycle controllers). The signal pairs carry differentially encoded messages that enable two types of signaling: a native escalation and a ping/response test of the escalation mechanism. The latter is to ensure that all escalation receivers are always active and have not been the target of an attack.

Low-power Indication Signals

The lpg_cg_en_i and lpg_rst_en_i are two arrays with multibit indication signals from the clock and reset managers. These indication signals convey whether a specific group of alert senders are either clock gated or in reset. As explained in more detail below, this information is used to temporarily halt the ping timer mechanism on channels that are in a low-power state in order to prevent false positives.

Crashdump Output

The crashdump_o struct outputs a snapshot of CSRs and alert handler state bits that can be read by hardware debugging circuitry:

  typedef struct packed {
    // alerts
    logic    [NAlerts-1:0] alert_cause;     // alert cause bits
    logic    [6:0]         loc_alert_cause; // local alert cause bits
    // class state
    logic    [3:0][15:0]   class_accum_cnt; // current accumulator value
    logic    [3:0][31:0]   class_esc_cnt;   // current escalation counter value
    cstate_e [3:0]         class_esc_state; // current escalation protocol state
  } alert_crashdump_t;

This can be useful for extracting more information about possible failures or bugs without having to use the tile-link bus interface (which may become unresponsive under certain circumstances). It is recommended for the top level to store this information in an always-on location.

Note that the crashdump state is continuously output via crashdump_o until the latching trigger condition is true for the first time (see CLASSA_CRASHDUMP_TRIGGER_SHADOWED). After that, the crashdump_o is held constant until all classes that have escalated are cleared. This is done so that it is possible to capture the true alert cause before spurious alert events start to pop up due to escalation countermeasures with excessive side effects (like life cycle scrapping for example). If classes that have escalated are not configured as clearable, then it is not possible to re-arm the crashdump latching mechanism at runtime and the alert handler has to be reset.

Design Details

This section gives the full design details of the alert handler module and its submodules.

Alert Definition

Alerts are defined as events that have security implications, and should be handled by the main processor, or escalated to other hardware modules to take action. Each peripheral has the option to define one or more alert signals. Those peripherals should instantiate one module (prim_alert_sender) to convert the event associated with that alert into a signal to the alert handler module. The alert handler instantiates one receiver module (prim_alert_receiver) per alert, then handles the classification, accumulation, and escalation of the received signal. The differential signaling submodules may either use a synchronous or asynchronous clocking scheme, since the message type to be transferred is a single discrete event.

Differential Alert Signaling

Each alert sender is connected to the corresponding alert receiver via the 3 differential pairs alert_tx_i/o.alert_p/n, alert_rx_i/o.ack_p/n and alert_rx_i/o.ping_p/n, as illustrated below:

Alerts are encoded differentially and signaled using a full handshake on the alert_tx_i/o.alert_p/n and alert_rx_i/o.ack_p/n wires. The use of a full handshake protocol allows this mechanism to be used with an asynchronous clocking strategy, where peripherals may reside in a different clock domain than the alert handler. The full handshake guarantees that alert messages are correctly back-pressured and no alert is “lost” at the asynchronous boundary due to (possibly variable) clock ratios greater or less than 1.0. The “native alert message” will be repeated on the output wires as long as the alert event is still true within the peripheral.

The wave pattern below illustrates differential full handshake mechanism.

The handshake pattern is repeated as long as the alert is true. The sender will wait for 2 cycles between handshakes.

Note that the alert is immediately propagated to alert_o once the initial level change on alert_tx_i.alert_p/n has been received and synchronized to the local clock on the receiver side. This ensures that the first occurrence of an alert is always propagated - even if the handshake lines have been manipulated to emulate backpressure. (In such a scenario, all subsequent alerts would be back-pressured and eventually the ping testing mechanism described in the next subsection would detect that the wires have been tampered with.)

The alert sender and receiver modules can either be used synchronously or asynchronously. The signaling protocol remains the same in both cases, but the additional synchronizer flops at the diff pair inputs may be omitted, which results in lower signaling latency.

Ping Testing

In order to ensure that the event sending modules have not been compromised, the alert receiver module prim_alert_receiver will “ping” or line-test the senders periodically every few microseconds. Pings timing is randomized so their appearance can not be predicted.

The ping timing is generated by a central LFSR-based timer within the alert handler that randomly asserts the ping_req_i signal of a particular prim_alert_receiver module. Once ping_req_i is asserted, the receiver module encodes the ping message as a level change on the differential alert_rx_o.ping_p/n output, and waits until the sender responds with a full handshake on the alert_tx_i.alert_p/n and alert_rx_o.ack_p/n lines. Once that handshake is complete, the ping_ok_o signal is asserted. The LFSR timer has a programmable ping timeout, after which it will automatically assert a “pingfail” alert. That timeout is a function of the clock ratios present in the system, and has to be programmed accordingly at system startup (as explained later in the LFSR timer subsection).

The following wave diagram illustrates a correct ping sequence, viewed from the receiver side:

In the unlikely case that a ping request collides with a native alert at the sender side, the native alert is held back until the ping handshake has been completed. This slightly delays the transmission of a native alert, but the alert will eventually be signaled. Further, if an alert is sent out right before a ping requests comes in at the sender side, the receiver will treat the alert as a ping response. However, the “true” ping response will be returned right after the alert handshake completed, and thus the alert will eventually be signaled with a slight delay.

Note that in both collision cases mentioned, the delay will be in the order of the handshake length, plus the constant amount of pause cycles between handshakes (2 sender cycles).

Monitoring of Signal Integrity Issues

All differential pairs are monitored for signal integrity issues, and if an encoding failure is detected, the receiver module asserts a signal integrity alert via integ_fail_o. In particular, this covers the following failure cases:

1. The alert_tx_i.alert_p/n pair is not correctly encoded on the receiver side. This can be directly flagged as an integrity failure on the receiver side.

2. The alert_rx_i.ping_p/n or the alert_rx_i.ack_p/n pairs are not correctly encoded on the sender side. This is signaled to the receiver by setting the alert_tx_o.alert_p/n wires to the same value, and that value will be continuously toggled. This implicitly triggers a signal integrity alert on the receiver side.

Some of these failure patterns are illustrated in the wave diagram below:

Note that if signal integrity failures occur during ping or alert handshaking, it is possible that the protocol state-machines lock up and the alert sender and receiver modules become unresponsive. However, the above mechanisms ensure that this will always trigger either a signal integrity alert or eventually a “pingfail” alert.

Skew on Asynchronous Differential Pairs

Note that there is likely a (small) skew present within each differential pair of the signaling mechanism above. Since these pairs cross clock domain boundaries, it may thus happen that a level change appears in staggered manner after resynchronization, as illustrated below:

This behavior is permissible, but needs to be accounted for in the protocol logic. Further, the skew within the differential pair should be constrained to be smaller than the shortest clock period in the system. This ensures that the staggered level changes appear at most 1 cycle apart from each other.

LFSR Timer

The ping_req_i inputs of all signaling modules (prim_alert_receiver, prim_esc_sender) instantiated within the alert handler are connected to a central ping timer that alternatingly pings either an alert line or an escalation line after waiting for a pseudo-random amount of clock cycles. Further, this ping timer also randomly selects a particular alert line to be pinged (escalation senders are always pinged in-order due to the ping monitoring mechanism on the escalation side). That should make it more difficult to predict the next ping occurrence based on past observations.

The ping timer is implemented using an LFSR-based PRNG of Galois type. This ping timer is reseeded with fresh entropy from EDN roughly every 500k cycles which corresponds to around 16 ping operations on average. The LFSR is 32bits wide, but only 24bits of its state are actually being used to generate the random timer count and select the alert line to be pinged. I.e., the 32bits first go through a fixed permutation function, and then bits [23:16] are used to determine which alert line to ping. The random cycle count is created by OR’ing bits [15:0] with the constant 3'b100 as follows:

cycle_cnt = permuted[15:0] | 3'b100;

This constant DC offset introduces a minimum ping spacing of 4 cycles (1 cycle + margin) to ensure that the handshake protocols of the sender/receiver pairs work.

After selecting one of the peripherals to ping, the LFSR timer waits until either the corresponding *_ping_ok[<number>] signal is asserted, or until the programmable ping timeout value is reached. In both cases, the LFSR timer proceeds with the next ping, but in the second case it will additionally raise a “pingfail” alert. The ping enable signal remains asserted during the time where the LFSR counter waits.

The timeout value is a function of the ratios between the alert handler clock and peripheral clocks present in the system, and can be programmed at startup time via the register PING_TIMEOUT_CYC_SHADOWED.

Note that the ping timer directly flags a “pingfail” alert if a spurious “ping ok” message comes in that has not been requested.

As described in the programmers guide below, the ping timer has to be enabled explicitly. Only alerts that have been enabled and locked will be pinged in order to avoid spurious alerts. Escalation channels are always enabled, and hence will always be pinged once this mechanism has been turned on.

In addition to the ping timer mechanism described above, the escalation receivers contain monitoring counters that monitor the liveness of the alert handler (described in more detail in this section. This mechanism requires that the maximum wait time between escalation receiver pings is bounded. To that end, escalation senders are pinged in-order every second ping operation (i.e., the wait time is randomized, but the selection of the escalation line is not).

Alert Receiving

The alert handler module contains one alert receiver module (prim_alert_receiver) per sending module. This receiver module has three outputs based upon the signaling of the input alert. Primary is the signal of a received native alert, shown in the top-level diagram as alert_triggered[<number>]. Also generated are two other outputs, one that signals a differential encoding error (alert_integ_fail[<number>]), and one that signals the receipt of a ping response (alert_ping_ok[<number>]). Each “triggered” alert received is sent into the classification block for individual configuration. All of the integ_fail signals are OR’ed together to create one alert for classification. The ping responses are fed to the LFSR timer, which determines whether a ping has correctly completed within the timeout window or not.

Alert Classification and Interrupts

Each of the incoming and local alert signals can be classified generically to one of four classes, or disabled for no classification at all. These are the classes A, B, C, and D. There is no pre-determined definition of a class, that is left to software. But for guidance, software can consider that some alert types are similar to others; some alert types are more “noisy” than others (i.e. when triggered they stay on for long periods of time); some are more critical than others, etc.

For each alert class (A-D), an interrupt is generally sent. Like all other peripheral interrupts, there is a triad of registers: enable, status, test. Thus like all other interrupts, software should handle the source of the interrupt (in this case, the original alert), then clear the state. Since the interrupt class is disassociated with the original alert (due to the classification process), software can access cause registers to determine which alerts have fired since the last clearing. Since alerts are expected to be rare (if ever) events, the complexity of dealing with multiple interrupts per class firing during the same time period should not be of concern. See the programming section on interrupt clearing.

Each of the four interrupts can optionally trigger a timeout counter that triggers escalation if the interrupt is not handled and cleared within a certain time frame. This feature is explained in more detail in the next subsection about escalation mechanisms.

Note that an interrupt always fires once an alert has been registered in the corresponding class. Interrupts are not dependent on escalation mechanisms like alert accumulation or timeout as described in the next subsection.

Escalation Mechanisms

There are two mechanisms per class that can trigger the corresponding escalation protocol:

1. The first consists of an accumulation counter that counts the amount of alert occurrences within a particular class. An alert classified to class A indicates that on every received alert trigger, the accumulation counter for class A is incremented. Note: since alerts are expected to be rare or never occur, the module does not attempt to count every alert per cycle, but rather all triggers per class are ORd before sending to the accumulation counter as an increment signal. Once the threshold has been reached, the next occurrence triggers the escalation escalation protocol for this particular class. The counter is a saturation counter, meaning that it will not wrap around once it hits the maximum representable count. This mechanism has two associated CSRs:

   • Accumulation max value. This is the total number (sum of all alerts classified in this group) of alerts required to enter escalation phase (see below). Example register is CLASSA_ACCUM_THRESH_SHADOWED.
   • Current accumulation register. This clearable register indicates how many alerts have been accumulated to date. Software should clear before it reaches the accumulation setting to avoid escalation. Example register is CLASSA_ACCUM_CNT.

2. The second way is an interrupt timeout counter which triggers escalation if an alert interrupt is not handled within the programmable timeout window. Once the counter hits the timeout threshold, the escalation protocol is triggered. The corresponding CSRs are:

   • Interrupt timeout value in cycles CLASSA_TIMEOUT_CYC_SHADOWED. The interrupt timeout is disabled if this is set to 0 (default).
   • The current interrupt timeout value can be read via CLASSA_ESC_CNT if CLASSA_STATE is in the Timeout state. Software should clear the corresponding interrupt state bit INTR_STATE.CLASSA before the timeout expires to avoid escalation.

Technically, the interrupt timeout feature (2. above) is implemented using the same counter used to time the escalation phases. This is possible since escalation phases or interrupt timeout periods are non-overlapping (escalation always takes precedence should it be triggered).

Programmable Escalation Protocol

There are four output escalation signals, 0, 1, 2, and 3. There is no predetermined definition of an escalation signal, that is left to the top-level integration. Examples could be processor Non Maskable Interrupt (NMI), privilege lowering, secret wiping, chip reset, etc. Typically the assumption is that escalation level 0 is the first to trigger, followed by 1, 2, and then 3, emulating a “fuse” that is lit that can’t be stopped once the first triggers (this is however not a requirement). See register section for discussion of counter clearing and register locking to determine the finality of accumulation triggers.

Each class can be programmed with its own escalation protocol. If one of the two mechanisms described above fires, a timer for that particular class is started. The timer can be programmed with up to 4 delays (e.g., CLASSA_PHASE0_CYC), each representing a distinct escalation phase (0 - 3). Each of the four escalation severity outputs (0 - 3) are by default configured to be asserted during the corresponding phase, e.g., severity 0 in phase 0, severity 1 in phase 1, etc. However, this mapping can be freely reassigned by modifying the corresponding enable/phase mappings (e.g., CLASSA_CTRL_SHADOWED.E0_MAP for enable bit 0 of class A). This mapping will be locked in together with the alert enable configuration after initial configuration.

SW can stop a triggered escalation protocol by clearing the corresponding escalation counter (e.g., CLASSA_ESC_CNT). Protection of this clearing is up to software, see the register control section that follows for CLASSA_CTRL_SHADOWED.LOCK.

It should be noted that each of the escalation phases have a duration of at least 1 clock cycle, even if the cycle count of a particular phase has been set to 0.

The next waveform shows the gathering of alerts of one class until eventually the escalation protocol is engaged. In this diagram, two different alerts are shown for class A, and the gathering and escalation configuration values are shown.

In this diagram, the first alert triggers an interrupt to class A. The assumption is that the processor is wedged or taken over, in which case it does not handle the interrupt. Once enough interrupts gather (16 in this case), the first escalation phase is entered, followed by three more (each phase has its own programmable length). Note that the accumulator threshold is set to 15 in order to trigger on the 16th occurrence. If escalation shall be triggered on the first occurrence within an alert class, the accumulation threshold shall be set to 0. Also note that it takes one cycle to activate escalation and enter phase 0.

The next wave shows a case where an interrupt remains unhandled and hence the interrupt timeout counter triggers escalation.

It should be noted here that the differential escalation signaling protocol distinguishes ‘true’ escalation conditions from mere pings by encoding them as pulses that are N + 1 cycles long. This is reflected in the two wave diagrams above. Refer to the subsequent section on escalation signaling for more details.

Escalation Signaling

For each of the four escalation severities, the alert handler instantiates a prim_esc_sender module and each of the four escalation countermeasures instantiates an prim_esc_receiver module. The signaling mechanism has similarities with the alert signaling mechanism - but it is a fully synchronous protocol. Hence, it must be ensured at the top-level that all escalation sender and receiver modules are using the same clock and reset signals.

As illustrated in the following block diagram, a sender-receiver pair is connected with two differential lines, one going from sender to receiver and the other going from receiver to sender.

Upon receiving an escalation enable pulse of width N > 0 at the esc_req_i input, the escalation sender encodes that signal as a differential pulse of width N+1 on esc_tx.esc_p/n. The receiver decodes that message and asserts the esc_req_o output after one cycle of delay. Further, it acknowledges the receipt of that message by continuously toggling the esc_rx.resp_p/n signals as long as the escalation signal is asserted. Any failure to respond correctly will trigger a integ_fail_o alert, as illustrated below:

Further, any differential signal mismatch on both the esc_tx_i.esc_p/n and esc_rx_i.resp_p/n lines will trigger an integ_fail_o alert. Mismatches on esc_rx_i.resp_p/n can be directly detected at the sender. Mismatches on the esc_tx_i.esc_p/n line will be signaled back to the sender by setting both the positive and negative response wires to the same value - and that value is being toggled each cycle. This implicitly triggers a signal integrity alert on the sender side. In addition to that, a signal integrity error on the esc_tx_i.esc_p/n lines will lead to assertion of the esc_req_o output, since it cannot be guaranteed that the back signalling mechanism always works when the sender / receiver pair is being tampered with.

This back-signaling mechanism can be leveraged to fast-track escalation and use another countermeasure in case it is detected that a particular escalation signaling path has been tampered with.

Some signal integrity failure cases are illustrated in the wave diagram below:

Ping Testing of the Escalation Signals

Similarly to the alert signaling scheme, the escalation signaling lines can be pinged / line tested in order to test whether the escalation receiver has been tampered with. This is achieved by asserting ping_req_i at the escalation sender module. A ping request is encoded as a single cycle pulse on the esc_tx_o.esc_p/n outputs. Hence, the receiver module will not decode this single cycle pulse as an escalation enable message, but it will respond to it with a “1010” pattern on the esc_rx_i.resp_p/n lines. The escalation sender module will assert ping_ok_o if that pattern is received correctly after one cycle of latency. Otherwise, the escalation sender will first assert integ_fail_o later, after the programmable ping timeout is reached, the LFSR timer will raise a “pingfail” alert. The integ_fail_o triggers in this case since “no ping response” and “wrong ping response” are ambiguous in this setting, and it has been decided to not suppress integrity failures when expecting a ping response.

This mechanism is illustrated below from the viewpoint of the sender module.

Note that the escalation signal always takes precedence, and the ping_req_i will just be acknowledged with ping_ok_o in case esc_req_i is already asserted. An ongoing ping sequence will be aborted immediately.

Another thing to note is that the ping and escalation response sequences have to start exactly one cycle after either a ping or escalation event has been signaled. Otherwise the escalation sender will assert integ_fail_o immediately.

Monitoring of Pings at the Escalation Receiver Side

Escalation receivers contain a mechanism to monitor the liveness of the alert handler itself. In particular, the receivers passively monitor the ping requests sent out by the alert handler using a timeout counter. If ping requests are absent for too long, the corresponding escalation action will be automatically asserted until reset.

The monitoring mechanism builds on top of the following properties of the alert handler system:

1. the ping mechanism can only be enabled, but not disabled. This allows us to start the timeout counter once the first ping request arrives at a particular escalation receiver.

2. the escalation receivers are in the same clock/reset domain as the alert handler. This ensures that we are seeing the same clock frequency, and the mechanism is properly reset together with the alert handler logic.

3. the maximum cycle count between subsequent pings on the same escalation line is bounded, even though the wait counts are randomized. This allows us to compute a safe and fixed timeout threshold based on design constants.

Low-power Management of Alert Channels

Due to the various clock and reset domains in the OpenTitan system, the alert handler ping mechanism needs to have additional logic to deal with alert senders that are either held in reset, or that are clock gated. This is needed to ensure that no false alarms are produced by the ping mechanism when an alert channel (sender / receiver pair) does not respond due to the sender being either in reset or clock gated.

Since the FSMs associated with an alert channel may end up in an inconsistent state when the sender is reset or gated while an asynchronous event handshake is in progress, this logic also needs to be able to re-initialize affected alert channels whenever the channels comes back from reset / clock gated state.

Assumptions

The following diagram shows a typical arrangement of alert sender (TX) and receiver (RX) pairs.

It is assumed that:

1. The alert handler clock domain cannot be gated by SW. This means that this clock domain is only ever disabled as part of the power-down sequence of the corresponding power domain.
2. The alert senders are in general located within different clock and reset domains than the alert receivers within the alert handler, and thus use the asynchronous event handshake mode.
3. Some alert senders may be located in an always-on (AON) power domain, within different clock and reset groups than the alert handler.
4. The alert handler may be located in an non-AON power domain, and may thus undergo a reset cycle where it cannot be guaranteed that all alert senders are reset as well (i.e., some alert senders may retain their state).

Further, we assume that we can get the following side-band information from the clock and reset managers in the system:

• All relevant reset signals pertaining to alert sender domains
• All relevant clock enable signals pertaining to alert sender domains

Scenarios

With the assumptions above, the following two problematic scenarios can occur.

Alert Handler in Reset

It may happen that the alert handler is reset while some alert senders (e.g. those located in the AON domain) are not. In general, if the associated alert channels are idle during an alert handler reset cycle, no problems arise.

However, if an alert channel is reset while it is handling a ping request or an alert event, the sender / receiver FSMs may end up in an inconsistent state upon deassertion of the alert handler reset. This can either lead to spurious alert or ping events, or a completely locked up alert channel which will be flagged eventually by the ping mechanism.

Alert Sender in Reset or Clock-gated

If any of the alert senders is either put into reset or its clock is disabled while the alert handler is operational, the ping mechanism inside the alert handler will eventually report a ping failure because of missing ping responses from the affected alert channel(s).

Further, if the alert sender is reset while the corresponding alert channel is handling a ping request or an alert event, the sender / receiver FSMs may end up in an inconsistent state after reset deassertion.

Employed Solution

As elaborated before, the side effects of resetting / clock gating either the alert handler or any of the alert senders are inconsistent FSM states, leading to locked up alert channels, or spurious alert or ping events. To address these issues, we have to:

1. make sure spurious events (alert and ping_ok outputs of the alert receivers) are suppressed if an alert channel is clock gated or in reset,
2. provide a mechanism for resetting an alert channel to an operational state once the associated clock is re-enabled, or the associated reset is released,
3. trigger this reset mechanism on all alert channels whenever the alert handler itself has been reset.

To attain this, the idea is to make use of side-band information available from the clock and reset managers to detect whether an alert channel (or a group of alert channels with the same clock and reset on the sender side) has to be put into a low-power state. In the following we will refer to such a clock / reset domain grouping as a low-power group (LPG).

The mechanism is illustrated below for a single LPG (in practice, this logic is replicated for each LPG that is identified in the system):

The clock gating enable (lpg_cg_en) and reset enable (lpg_rst_en) indications are routed as multibit signals to the alert handler, where they are synchronized to the alert handler clock and logically combined using an OR function to form a combined low-power indication signal that is multibit encoded.

This multibit indication signal is then routed to all alert receivers, where it is used to trigger re-initialization of each alert channel, and bypass the ping requests from the ping mechanism.

To that end, two extra init states are added to the alert receiver FSMs to perform this in-band reset, as indicated in the state diagram below:

Whenever the init_trig multibit signal of an LPG is asserted, all corresponding sender FSMs are moved into the InitReq state. In that state, the alert receivers immediately acknowledge ping requests from the ping mechanism, and ignore alert events from the sender side. In addition to that, the receivers intentionally place a signal integrity error onto the ping_p / ping_n, ack_p / ack_n lines going from receivers to the senders. This causes the senders to 1) move into the signal integrity error state, and 2) respond by placing a signal integrity error onto the alert_p / alert_n lines, which serves as an initialization “acknowledge” signal in this case. Since the sender FSMs fall back into the Idle state once the signal integrity error disappears, this procedure essentially implements an in-band reset mechanism with an acknowledgement handshake that can be used to determine whether the reset has been successful.

Implementation Aspects

Ping Mechanism Bypass

Note that the ping bypass mechanism is to be implemented in a way that pings are only ack’ed immediately if 1) the FSM is in the InitReq state, and 2) the init_trig signal is still asserted.

This allows to subject the initialization process of each alert channel to the ping mechanism for channels that are recovering from a reset or clock gated cycle on the sender side. I.e., alert channels that get stuck during the initialization process can be detected by the ping mechanism since ping requests are not immediately ack’ed anymore once init_trig is deasserted.

FSM Encoding

Since there are many alert channels in the design, the receiver and sender FSMs themselves are not sparsely encoded. Instead, we rely on the ping mechanism to detect alert channels that are in a bad state. The specific implementation of the ping bypass mentioned in the previous subsection ensures that the ping mechanism can also be used to monitor the initialization sequence of alert channels.

Latency / Skew Considerations

Due to asynchronous transitions and different path latencies in the system, a change in reset or clock gating state will experience a different latency through the alert channels than through the indication signals (rst_n and clk_en) that are connected to the low-power control logic.

It is consequently possible for a group of alert senders to already be in reset or clock gated state, while the corresponding LPG logic does not yet know about this state change - and vice versa.

In practice, this means that ping requests may be pending for several cycles until the LPG logic detects a reset or clock-gated condition and disables the corresponding alert channel(s). Fortunately, such delay can be tolerated by setting the ping timeout to a sufficiently large value (see CLASSA_TIMEOUT_CYC_SHADOWED).

As for alert events, this latency difference should not pose a problem. Alert events may get stuck in the alert sender due to a reset or clock-gated condition - but this is to be expected.

Integration Considerations

Note that due to the aforementioned latency tolerance built into the ping timer, it is permissible to connect any reset or clock enable indication signal from the relevant clock group to the LPG logic. I.e., the only requirement is that the indication signals are logically related to the resets and clocks routed to the alert senders, and that the skew between reset / clock state changes and the indication signals is bounded.

The topgen script is extended so that it can identify all LPGs and the associated alert channels. This information is then used to parameterize the alert handler design, and make the necessary top-level connections from the reset and clock management controllers to the alert handler.

Hardening Against Glitch Attacks

In addition to the differential alert and escalation signalling scheme, the internal state machines and counters are hardened against glitch attacks as described bellow:

1. Ping Timer:

• The FSM is sparsely encoded.
• The LFSR and the counter are duplicated.
• If the FSM or counter are glitched into an invalid state, all internal ping fail alerts will be permanently asserted.

2. Escalation Timers:

• The escalation timer FSMs are sparsely encoded.
• The escalation timer counters are duplicated.
• The escalation accumulators are duplicated.
• If one of these FSMs, counters or accumulators are glitched into an invalid state, all escalation actions will be triggered and the affected FSM goes into a terminal FsmError state.

3. CSRs:

• Critical configuration CSRs are shadowed.
• The shadow CSRs can trigger additional internal alerts for CSR storage and update failures. These internal alerts are fed back into the alert classifier in the same manner as the ping and integrity failure alerts.

4. LPGs:

• Clock-gated and reset-asserted indication signals that are routed from clock and reset managers to the alert handler are encoded with multibit signals.

ALERT_HANDLER DV document

Goals

• DV
  • Verify all ALERT_HANDLER IP features by running dynamic simulations with a SV/UVM based testbench
  • Develop and run all tests based on the testplan below towards closing code and functional coverage on the IP and all of its sub-modules
  • Verify transmitter and receiver pairs for alert (/hw/ip/prim/dv/prim_alert) and escalation (/hw/ip/prim/dv/prim_esc) via direct stimulus.
• FPV
  • Verify TileLink device protocol compliance with an SVA based testbench
  • Verify transmitter and receiver pairs for alert and escalator
  • Verify alert_handler_esc_timer and alert_handler_ping_timer

Current status

• Design & verification stage
  • HW development stages
• Simulation results

Design features

For detailed information on ALERT_HANDLER design features, please see the ALERT_HANDLER HWIP technical specification.

Testbench architecture

ALERT_HANDLER testbench has been constructed based on the CIP testbench architecture.

Block diagram

Top level testbench

Top level testbench is located at hw/ip/alert_handler/dv/tb/tb.sv. It instantiates the ALERT_HANDLER DUT module hw/ip/alert_handler/rtl/alert_handler.sv. In addition, it instantiates the following interfaces, connects them to the DUT and sets their handle into uvm_config_db:

• Clock and reset interface
• TileLink host interface
• ALERT_HANDLER IOs
• Alerts and escalations(alert_esc_if)
• Interrupts (pins_if)
• Devmode (pins_if)

The alert_handler testbench environment can be reused in chip level testing.

Common DV utility components

The following utilities provide generic helper tasks and functions to perform activities that are common across the project:

• dv_utils_pkg
• csr_utils_pkg

Global types & methods

All common types and methods defined at the package level can be found in alert_handler_env_pkg. Some of them in use are:

  parameter uint NUM_MAX_ESC_SEV = 8;

TL_agent

ALERT_HANDLER testbench instantiates (already handled in CIP base env) tl_agent which provides the ability to drive and independently monitor random traffic via TL host interface into ALERT_HANDLER device.

ALERT_ESC Agent

ALERT_ESC agent is used to drive and monitor transmitter and receiver pairs for the alerts and escalators. Alert_handler DUT includes alert_receivers and esc_senders, so the alert_esc agent will drive output signals of the alert_senders and esc_receivers.

UVM RAL Model

The ALERT_HANDLER RAL model is created with the ralgen FuseSoC generator script automatically when the simulation is at the build stage.

It can be created manually by invoking regtool.

Stimulus strategy

Test sequences

All test sequences reside in hw/ip/alert_handler/dv/env/seq_lib. The alert_handler_base_vseq virtual sequence is extended from cip_base_vseq and serves as a starting point. All test sequences are extended from alert_handler_base_vseq. It provides commonly used handles, variables, functions and tasks that the test sequences can simple use / call. Some of the most commonly used tasks / functions are as follows:

• alert_handler_init: Configure alert_handler DUT by writing to intr_en, alert_en_shadowed_*, alert_class_shadowed_*, loc_alert_en_shadowed_*, loc_alert_class_shadowed_* registers.
• drive_alert: Drive alert_tx signal pairs through alert_sender_driver.
• drive_esc_rsp: Drive esc_rx signal pairs through esc_receiver_driver.
• read_ecs_status: Readout registers that reflect escalation status, including classa/b/c/d_accum_cnt, classa/b/c/d_esc_cnt, and classa/b/c/d_state.
• wait_alert_handshake_done: Wait for alert_rx/tx handshake to finish. If the alert’s low-power-group(LPG) is enabled, immediately return.
• wait_esc_handshake_done: Wait for esc_rx/tx handshake to finish by reading class*_state registers and check esc_rx/tx signals.
• set_alert_lpg: Given alert index, find the linked LPG group and enabled the LPG group by driving lpg_cg_en or lpg_rst_en to Mubi4True.
• run_esc_rsp_seq_nonblocking: A non-blocking sequence to drive esc_tx when received escalation or escalation-ping requests.
• run_alert_ping_rsp_seq_nonblocking: A non-blocking sequence to drive alert_rx when received alert-ping requests.

Functional coverage

To ensure high quality constrained random stimulus, it is necessary to develop a functional coverage model. The detailed covergroups are documented under alert_handler testplan.

Self-checking strategy

Scoreboard

The alert_handler_scoreboard is primarily used for end to end checking. It creates the following analysis ports to retrieve the data monitored by corresponding interface agents:

• tl_a_chan_fifo: tl address channel
• tl_d_chan_fifo: tl data channel
• alert_fifo: An array of alert_fifo that connects to corresponding alert_monitors
• esc_fifo: An array of esc_fifo that connects to corresponding esc_monitors

Alert_handler scoreboard monitors all valid CSR registers, alert handshakes, and escalation handshakes. To ensure certain alert, interrupt, or escalation signals are triggered at the expected time, the alert_handler scoreboard implemented a few counters:

• intr_cnter_per_class[NUM_ALERT_HANDLER_CLASSES]: Count number of clock cycles that the interrupt bit stays high. If the stored number is larger than the timeout_cyc registers, the corresponding escalation is expected to be triggered
• accum_cnter_per_class[NUM_ALERT_HANDLER_CLASSES]: Count number of alerts triggered under the same class. If the stored number is larger than the accum_threshold registers, the corresponding escalation is expected to be triggered
• esc_cnter_per_signal[NUM_ESC_SIGNALS]: Count number of clock cycles that each escalation signal stays high. Compare the counter against phase_cyc registers

The alert_handler scoreboard is parameterized to support different number of classes, alert pairs, and escalation pairs.

Assertions

• TLUL assertions: The tb/alert_handler_bind.sv binds the tlul_assert assertions to the IP to ensure TileLink interface protocol compliance.
• Unknown checks on DUT outputs: The RTL has assertions to ensure all outputs are initialized to known values after coming out of reset.

Building and running tests

We are using our in-house developed regression tool for building and running our tests and regressions. Please take a look at the link for detailed information on the usage, capabilities, features and known issues. Here’s how to run a smoke test:

$ $REPO_TOP/util/dvsim/dvsim.py $REPO_TOP/hw/$CHIP/ip_autogen/alert_handler/dv/alert_handler_sim_cfg.hjson -i alert_handler_smoke

In this run command, $CHIP can be top_earlgrey, etc.

Testplan

Testplan

Testpoints

Covergroups

Programmer’s Guide

Power-up and Reset Considerations

False alerts during power-up and reset are not possible since the alerts are disabled by default, and need to be configured and locked in by the firmware. The ping timer won’t start until initial configuration is over and the registers are locked in.

The low-power state management of alert channels is handled entirely by hardware and hence this is transparent to software. Note however that the LPGs inherit the security properties of the associated clock groups and resets. This means that the low-power state of certain alerts can be controlled by SW by means of clock gating or block reset. For example, certain crypto blocks are located in a transactional clock group which can be clock gated by SW - and this also affects the associated alerts of these crypto blocks. See clock and reset managers for more detail.

Initialization

To initialize the block, software running at a high privilege levels (early in the security settings process) should do the following:

1. For each alert and each local alert:

   • Determine if alert is enabled (should only be false if alert is known to be faulty). Set ALERT_EN_SHADOWED_0.EN_A_0 and LOC_ALERT_EN_SHADOWED_0.EN_LA_0 accordingly.

   • Determine which class (A..D) the alert is associated with. Set ALERT_CLASS_SHADOWED_0.CLASS_A_0 and LOC_ALERT_CLASS_SHADOWED_0.CLASS_LA_0 accordingly.

   • Optionally lock each alert configuration by writing 0 to ALERT_REGWEN_0.EN_0 or LOC_ALERT_REGWEN_0.EN_0. Note however that only locked and enabled alerts are going to be pinged using the ping mechanism. This ensures that spurious ping failures cannot occur when previously enabled alerts are being disabled again (before locking).

2. Set the ping timeout value PING_TIMEOUT_CYC_SHADOWED. This value is dependent on the clock ratios present in the system.

3. For each class (A..D):

   • Determine whether to enable escalation mechanisms (accumulation / interrupt timeout) for this particular class. Set CLASSA_CTRL_SHADOWED.EN accordingly.

   • Determine if this class of alerts allows clearing of escalation once it has begun. Set CLASSA_CTRL_SHADOWED.LOCK to true if clearing should be disabled. If true, once escalation protocol begins, it can not be stopped, the assumption being that it ends in a chip reset else it will be rendered useless thenceforth.

   • Determine the number of alerts required to be accumulated before escalation protocol kicks in. Set CLASSA_ACCUM_THRESH accordingly.

   • Determine whether the interrupt associated with that class needs a timeout. If yes, set CLASSA_TIMEOUT_CYC_SHADOWED to an appropriate value greater than zero (zero corresponds to an infinite timeout and disables the mechanism).

   • For each escalation phase (0..3):

     • Determine length of each escalation phase by setting CLASSA_PHASE0_CYC accordingly

   • For each escalation signal (0..3):

     • Determine whether to enable the escalation signal, and set the CLASSA_CTRL_SHADOWED.E0_EN bit accordingly (default is enabled). Note that setting all of the E*_EN bits to 0 within a class has the same effect of disabling the entire class by setting CLASSA_CTRL_SHADOWED.EN to zero.
     • Determine the phase -> escalation mapping of this class and program it via the CLASSA_CTRL_SHADOWED.E0_MAP values if it needs to be changed from the default mapping (0->0, 1->1, 2->2, 3->3).

   • Optionally lock the class configuration by writing 0 to CLASSA_CTRL_SHADOWED.REGWEN.

4. After initial configuration at startup, enable the ping timer mechanism by writing 1 to PING_TIMER_EN. It is also recommended to lock the ping timer configuration by clearing PING_TIMER_REGWEN. Note that only locked and enabled alerts are going to be pinged using the ping mechanism. This ensures that spurious ping failures cannot occur when previously enabled alerts are being disabled again (before locking).

Interrupt Handling

For every alert that is enabled, an interrupt will be triggered on class A, B, C, or D. To handle an interrupt of a particular class, software should execute the following steps:

1. If needed, check the escalation state of this class by reading CLASSA_STATE. This reveals whether escalation protocol has been triggered and in which escalation phase the class is. In case interrupt timeouts are enabled the class will be in timeout state unless escalation has already been triggered. The current interrupt or escalation cycle counter can be read via CLASSA_ESC_CNT.

2. Since the interrupt does not indicate which alert triggered, SW must read the cause registers LOC_ALERT_CAUSE and ALERT_CAUSE etc. The cause bits of all alerts are concatenated and chunked into 32bit words. Hence the register file contains as many cause words as needed to cover all alerts present in the system. Each cause register contains a sticky bit that is set by the incoming alert, and is clearable with a write by software. This should only be cleared after software has cleared the event trigger, if applicable. It is possible that the event requires no clearing (e.g. a parity error), or can’t be cleared (a breach in the metal mesh protecting the chip).

   Note that in the rare case when multiple events are triggered at or about the same time, all events should be cleared before proceeding.

3. After the event is cleared (if needed or possible), software should handle the interrupt as follows:

   • Resetting the accumulation register for the class by writing CLASSA_CLR. This also aborts the escalation protocol if it has been triggered. If for some reason it is desired to never allow the accumulator or escalation to be cleared, software can initialize the CLASSA_CLR_REGWEN register to zero. If CLASSA_CLR_REGWEN is already false when an alert interrupt is detected (either due to software control or hardware trigger via CLASSA_CTRL_SHADOWED.LOCK), then the accumulation counter can not be cleared and this step has no effect.

   • After the accumulation counter is reset (if applicable), software should clear the class A interrupt state bit INTR_STATE.CLASSA. Clearing the class A interrupt state bit also clears and stops the interrupt timeout counter (if enabled).

Note that testing interrupts by writing to the interrupt test registers does also trigger the internal interrupt timeout (if enabled), since the interrupt state is used as enable signal for the timer. However, alert accumulation will not be triggered by this testing mechanism.

Device Interface Functions (DIFs)

• Device Interface Functions

Register Table

• Register Table

Additional Notes

Timing Constraints

The skew within all differential signal pairs must be constrained to be smaller than the period of the fastest clock operating the alert handler receivers. The maximum propagation delay of differential pair should also be constrained (although it may be longer than the clock periods involved).

Fast-track Alerts

Note that it is possible to program a certain class to provide a fast-track response for critical alerts by setting its accumulation trigger value to 1, and configuring the escalation protocol such that the appropriate escalation measure is triggered within escalation phase 0. This results in a minimal escalation latency of 4 clock cycles from alert sender input to escalation receiver output in the case where all involved signaling modules are completely synchronous with the alert handler. In case the alert sender is asynchronous w.r.t. to the alert handler, the actual latency depends on the clock periods involved. Assuming both clocks have the same frequency alert propagation takes at least 6-8 clock alert handler clock cycles.

For alerts that mandate an asynchronous response (i.e. without requiring a clock to be active), it is highly recommended to build a separate network at the top-level. That network should OR’ the critical sources together and route the asynchronous alert signal directly to the highest severity countermeasure device. Examples for alert conditions of this sort would be attacks on the secure clock.

Hardware Interfaces and Registers

Interfaces

Referring to the Comportable guideline for peripheral device functionality, the module alert_handler has the following hardware interfaces defined.

Primary Clock: clk_i

Other Clocks: clk_edn_i

Bus Device Interfaces (TL-UL): tl

Bus Host Interfaces (TL-UL): none

Peripheral Pins for Chip IO: none

Inter-Module Signals: Reference

Interrupts:

Security Alerts: none

Security Countermeasures:

Registers