Clock Manager HWIP Technical Specification

Overview

This document specifies the functionality of the OpenTitan clock manager.

Features

  • Attribute based controls of OpenTitan clocks.
  • Minimal software clock controls to reduce risks in clock manipulation.
  • External clock switch support
  • Clock frequency measurement

Theory of Operation

Clock management in OpenTitan is divided into groups. Each group has specific attributes and controls whether software is allowed to influence individual clocks during the active power state. For low power states, please see power manager.

The grouping is derived from the chip partition and related security properties. For illustrative purposes, this document uses the following assumed chip partition

Example chip partition

The actual partition may differ per design, however the general principles are assumed to be the same. Each group can be made up of more than 1 source clock. The clocks themselves may be asynchronous - the grouping is thus a logical grouping instead of a physical one.

The grouping is summarized in the table below and described in more detail afterwards. The table shows the group name, the modules that belong to each group, and whether SW can directly (via register control) or indirectly (via wait-for-interrupt) influence the state of the clock in the form of clock gating.

Group Frequencies Modules Software Wait for Interrupt
Power-up 100~200KHz, 24MHz Clock Manager, Power Manager, Reset Manager, Pinmux No No
Transactional ~100MHz Aes, Kmac, Hmac, Key Manager, Otbn Yes (1) Yes (2)
Infrastructural 24MHz, ~100MHz Fabric, Fabric gaskets (iopmp), Memories No Yes (3)
Security 24MHz, ~100MHz Alert handler, Entropy, Life cycle, Plic, Sensors No No
Peripheral 24MHz, 48MHz, 96MHz I2c, Spi, Uart, Usb, others Yes Yes
Timers 100-200KHz, 24MHz AON timers, Timers, Watchdog No No
  • 1 - Transactional clock group’s software control is only a software hint.
  • 2 - Transactional clock group’s wait-for-interrupt control is only a hint.
  • 3 - May require additional complexity to handle multi-host (non-wait-for-interrupt) scenarios

Power-up Clock Group

The group refers to modules responsible for power up, such as power, reset and clock managers. Large portions of these modules operate to release clocks and resets for the rest of the design, thus cannot operate on gated versions of the clocks themselves. They are the only group running clocks directly from the source. All follow groups are derived after root clock gating. See block diagram for more details.

Transactional Clock Group

This group refers to the collection of modules that are transactional by nature (example: Hmac / Aes / Kmac). This means these modules perform specific tasks (for example encrypt, decrypt or hashing). While performing these tasks, it is unsafe to manipulate or change the clocks. Once these tasks are complete, the clocks can be safely shut-off.

To ensure such behavior on the clocks, The final clock enable is qualified with an Idle indication to signify that a transaction is ongoing and manipulation of the clock is not permitted. The Idle signal must be sourced from the transactional modules and sent to the clock manager.

For this group software can only express its intent to shut-off, and does not have full control over the final state. This intent is indicated with a register in the clock manager register file, see CLK_HINTS.

Wait-for-interrupt based control is already a software hint, it can thus be applied to this group with the same Idle requirement.

For modules in this group, each module can be individually influenced, and thus each has its own dedicated clock gating logic. The added benefit of allowing software control in this group is to save power, as some transactional modules can be both power and area hungry.

Infrastructure Clock Group

This group refers to the collection of modules that support infrastructure functions.

If the clocks to these modules are turned off, there may not be a way to turn them back on and could thus result in system deadlock. This includes but is not limited to:

  • Turning off fabric / gasket clocks, and thus having no way to access the fabric and resume the clock.
  • Turning off memory clocks such that there is no way to execute code that would resume the clocks.

For this group, there is no reason to allow software control over the clocks, as it could be used to create a system deadlock where after disabling infrastructure clocks there is no way to turn them back on. Wait-for-interrupt controls however can be used, as long as there is a way to break the processor out of wait-for-interrupt and handle other bus hosts, while also separating the functional portions from bus access. See Wait-for-interrupt clock gating for more details.

Security Clock Group

The security clock group is made up of security modules that either have background functions (entropy, alert manager, sensors) or perform critical security functions where disabling clocks could have unexpected side effects (life cycle, otp, pinmux, plic).

For this group, no software influence over the clock state is allowed during the active state. The clocks are always running as long as the source is on.

This group is not functionally identical to the power-up group. The power-up group is run on clocks directly from the clock source, while the security group is derived after root clock gating.

Timer Clock Group

The timer clock group is composed of modules that track time for various purposes. As influencing time can change the perspective of software and potentially reveal security vulnerabilities, the clock state for these modules cannot be directly or indirectly influenced by software.

Functionally, this group is identical to the security group.

Peripheral Clock Group

The peripheral clock group is composed of I/O peripherals modules. By their nature, I/O peripherals are both transactional and most of the time not security critical - so long as proper care is taken to sandbox peripherals from the system.

These modules can be both directly and indirectly controlled by software. The controls can also be individual to each peripheral.

Wait-for-Interrupt (wfi) Gating

Wait-for-interrupt clock gating refers to the mechanism of using a processor’s sleep indication to actively gate off module clocks. Of the groups enumerated, only transactional, infrastructural and peripheral groups can be influenced by wfi.

As wfi is effectively a processor clock request, there are subtleties related to its use. The interaction with each clock group is briefly described below.

Transactional Clock Group

While wfi gating can be applied to this group, the modules in this category are already expected to be turned off and on by software depending on usage. Specifically, these modules are already completely managed by software when not in use, thus may not see significant benefit from wfi gating.

Peripheral Clock Group

Since peripherals, especially those in device mode, are often operated in an interrupt driven way, the peripheral’s core operating clock frequently must stay alive even if the processor is asleep. This implies that in order for peripherals to completely support wfi clock gating, they must be split between functional clocks and bus clocks.

The bus clocks represent the software interface and can be turned off based on wfi gating, while the functional clocks should be kept running to ensure outside activity can be captured and interrupts created. In this scenario, it is important to ensure the functional clocks are responsible for creating interrupts and not the bus clocks, as the latter may not be available during wfi.

This division may only be beneficial for peripherals where register and local fabric size is large relative to the functional component.

Infrastructural Clock Group

This clock group matches wfi functionality well. Most infrastructural components such as fabric, gaskets and memories, have no need to be clocked when the processor is idle. Some components such as flash controller however would also need to be split into bus and functional halves to support long, background activities while the processor is idle.

However, there are additional complications. In systems where the processor is not the only bus host, wfi can only be used as the software request and not final clock state decision. Hardware driven requests, such as those coming from a dma or any peripheral driven bus host, would also need to be included as part of the equation. Further, since it is possible hardware may issue requests at the boundary of a clock state changes, additional fabric gaskets would be required to protect hosts when destinations are temporarily clocked off. The bus requests themselves thus become dynamic clock request signals to help enable components in its path.

There is thus a moderate design and high verification cost to supporting wfi gating for the infrastructural group.

Block Diagram

The following is a high level block diagram of the clock manager.

Clock Manager Block Diagram

Design Details

Root Clock Gating and Interface with Power Manager

All clock groups except the power-up group run from gated source clocks. The source clocks are gated off during low power states as controlled by the power manager. When the power manager makes a clock enable request, the clock manager ensures all root clock gates are enabled before acknowledging. Likewise, when the power manager makes a clock disable request, the clock manager ensures all root clock gates off disabled before acknowledging.

Note, the power manager’s request to turn off clocks supersedes all other local controls in the clock manager. This means even if a particular clock is turned on by the clock manager (for example a transactional unit that is ongoing or a peripheral that is enabled), the power manager requests will still turn clocks on / off at the root.

This makes it software’s responsibility to ensure low power entry requests (which can only be initiated by software) do not conflict with any ongoing activities controlled by software. For example, software should ensure that Aes / Otbn activities have completed before initializing a low power entry process.

Clock Division

Not all clocks are the same frequency as the source. In cases where there is a frequency mismatch, the clock manager supports clock dividers to step down the frequency. The divided frequency is not assumed to be synchronous with its source and are thus treated like another asynchronous branch. Further, the clock dividers are hardwired and have no software control, this is to further ensure there are no simple paths for faulty or malicious software to tamper.

Wait-for-Interrupt Support

Given the marginal benefits and the increased complexity of wfi support, the first version of this design does not support wfi gating. All wfi CG modules in the block diagram are thus drawn with dashed lines to indicate it can be theoretically supported but currently not implemented.

It may be added for future more complex systems where there is a need to tightly control infrastructural power consumption as a result from clocks.

External Clock Switch Support

Clock manager supports the ability to request root clocks switch to an external clock. There are two occasions where this is required:

  • Life cycle transition from Raw / Test_locked to Test_unlocked states.
  • Software request for external clocks during normal functional mode.

Software request for external clocks is not always valid. Software is only able to request for external clocks when dft functions are allowed. When software requests the external clock switch, it also has the option to request whether the clock divider should be stepped down by a factor of 2.

When the life cycle controller requests external clock, a request signal lc_clk_byp_req_i is sent from lc_ctrl to clkmgr. clkmgr then forwards the request to ast through ast_clk_byp_req_o, which performs the actual clock switch. When the clock switch is complete, the clock dividers are stepped down by a factor of 2 and the life cycle controller is acknowledged through lc_clk_byp_ack_o.

When software requests external clock, the register bit EXTCLK_CTRL is written. If dft functions are allowed, the clkmgr sends a request signal ast_clk_byp_req_o to ast.

When the divider is stepped down, a divide-by-4 clock becomes divide-by-2 clock , and a divide-by-2 becomes a divide-by-1 clock. This allows external connection to be either nominal frequencies or nominal divided-by-2.

Clock Frequency Measurements

Clock manager can continuously measure root clock frequencies to see if any of the root clocks have deviated from the expected frequency. This feature can be enabled through the various measurement control registers such as IO_MEASURE_CTRL.

The root clocks, specifically the clocks supplied from ast and their divided variants, are constantly measured against the always on clock when this feature is enabled. Software sets both an expected maximum and minimum for each measured clock.

Clock manager then counts the number of relevant root clock cycles in each always-on clock period. If the resulting count differs from the programmed thresholds, a recoverable error is registered.

There are two types of errors:

  • Clock too fast error
  • Clock too slow error

Clock too fast is registered when the clock cycle count is greater than the software programmed max threshold. Clock too slow is registered when the clock cycle count is less than the software programmed min threshold.

As these are all software supplied values, the entire measurement control can be locked from further programming through MEASURE_CTRL_REGWEN.

Programmers Guide

There are in general only two software controllable functions in the clock manager.

Transactional Clock Hints

To enable a transactional clock, set the corresponding hint in CLK_HINTS to 1. To disable a transactional clock, set the corresponding hint in CLK_HINTS to 0. Note, a 0 does not indicate clock is actually disabled, software can thus check CLK_HINTS_STATUS for the actual state of the clock.

Peripheral Clock Controls

To control peripheral clocks, directly change the bits in CLK_ENABLES.

Register Table

CLKMGR.ALERT_TEST @ 0x0

Alert Test Register

Reset default = 0x0, mask 0x3
31302928272625242322212019181716
 
1514131211109876543210
  fatal_fault recov_fault
BitsTypeResetNameDescription
0wo0x0recov_fault

Write 1 to trigger one alert event of this kind.

1wo0x0fatal_fault

Write 1 to trigger one alert event of this kind.


CLKMGR.EXTCLK_CTRL_REGWEN @ 0x4

External clock control write enable

Reset default = 0x1, mask 0x1
31302928272625242322212019181716
 
1514131211109876543210
  EN
BitsTypeResetNameDescription
0rw0c0x1EN

When 1, the value of EXTCLK_CTRL can be set. When 0, writes to EXTCLK_CTRL have no effect.


CLKMGR.EXTCLK_CTRL @ 0x8

Select external clock

Reset default = 0x55, mask 0xff
Register enable = EXTCLK_CTRL_REGWEN
31302928272625242322212019181716
 
1514131211109876543210
  STEP_DOWN SEL
BitsTypeResetNameDescription
3:0rw0x5SEL

A value of b1010 selects external clock as clock for the system. While this register can always be programmed, it only takes effect when the system is in life cycle TEST or RMA states when DFT is enabled.

All other values are invalid and keep clocks on internal sources.

7:4rw0x5STEP_DOWN

A value of b1010 steps down the clock dividers by a factor of 2 if the EXTCLK_CTRL.SEL field is also set to b1010.

All other values have no effect.


CLKMGR.JITTER_ENABLE @ 0xc

Enable jittery clock

Reset default = 0x0, mask 0x1
31302928272625242322212019181716
 
1514131211109876543210
  VAL
BitsTypeResetNameDescription
0rw0x0VAL

Enable jittery clock


CLKMGR.CLK_ENABLES @ 0x10

Clock enable for software gateable clocks. These clocks are directly controlled by software.

Reset default = 0xf, mask 0xf
31302928272625242322212019181716
 
1514131211109876543210
  CLK_USB_PERI_EN CLK_IO_PERI_EN CLK_IO_DIV2_PERI_EN CLK_IO_DIV4_PERI_EN
BitsTypeResetNameDescription
0rw0x1CLK_IO_DIV4_PERI_EN

0 CLK_IO_DIV4_PERI is disabled. 1 CLK_IO_DIV4_PERI is enabled.

1rw0x1CLK_IO_DIV2_PERI_EN

0 CLK_IO_DIV2_PERI is disabled. 1 CLK_IO_DIV2_PERI is enabled.

2rw0x1CLK_IO_PERI_EN

0 CLK_IO_PERI is disabled. 1 CLK_IO_PERI is enabled.

3rw0x1CLK_USB_PERI_EN

0 CLK_USB_PERI is disabled. 1 CLK_USB_PERI is enabled.


CLKMGR.CLK_HINTS @ 0x14

Clock hint for software gateable transactional clocks during active mode. During low power mode, all clocks are gated off regardless of the software hint.

Reset default = 0x1f, mask 0x1f

Transactional clocks are not fully controlled by software. Instead software provides only a disable hint.

When software provides a disable hint, the clock manager checks to see if the associated hardware block is idle. If the hardware block is idle, then the clock is disabled. If the hardware block is not idle, the clock is kept on.

For the enable case, the software hint is immediately honored and the clock turned on. Hardware does not provide any feedback in this case.

31302928272625242322212019181716
 
1514131211109876543210
  CLK_MAIN_OTBN_HINT CLK_IO_DIV4_OTBN_HINT CLK_MAIN_KMAC_HINT CLK_MAIN_HMAC_HINT CLK_MAIN_AES_HINT
BitsTypeResetNameDescription
0rw0x1CLK_MAIN_AES_HINT

0 CLK_MAIN_AES can be disabled. 1 CLK_MAIN_AES is enabled.

1rw0x1CLK_MAIN_HMAC_HINT

0 CLK_MAIN_HMAC can be disabled. 1 CLK_MAIN_HMAC is enabled.

2rw0x1CLK_MAIN_KMAC_HINT

0 CLK_MAIN_KMAC can be disabled. 1 CLK_MAIN_KMAC is enabled.

3rw0x1CLK_IO_DIV4_OTBN_HINT

0 CLK_IO_DIV4_OTBN can be disabled. 1 CLK_IO_DIV4_OTBN is enabled.

4rw0x1CLK_MAIN_OTBN_HINT

0 CLK_MAIN_OTBN can be disabled. 1 CLK_MAIN_OTBN is enabled.


CLKMGR.CLK_HINTS_STATUS @ 0x18

Since the final state of CLK_HINTS is not always determined by software, this register provides read feedback for the current clock state.

Reset default = 0x1f, mask 0x1f
31302928272625242322212019181716
 
1514131211109876543210
  CLK_MAIN_OTBN_VAL CLK_IO_DIV4_OTBN_VAL CLK_MAIN_KMAC_VAL CLK_MAIN_HMAC_VAL CLK_MAIN_AES_VAL
BitsTypeResetNameDescription
0ro0x1CLK_MAIN_AES_VAL

0 CLK_MAIN_AES is disabled. 1 CLK_MAIN_AES is enabled.

1ro0x1CLK_MAIN_HMAC_VAL

0 CLK_MAIN_HMAC is disabled. 1 CLK_MAIN_HMAC is enabled.

2ro0x1CLK_MAIN_KMAC_VAL

0 CLK_MAIN_KMAC is disabled. 1 CLK_MAIN_KMAC is enabled.

3ro0x1CLK_IO_DIV4_OTBN_VAL

0 CLK_IO_DIV4_OTBN is disabled. 1 CLK_IO_DIV4_OTBN is enabled.

4ro0x1CLK_MAIN_OTBN_VAL

0 CLK_MAIN_OTBN is disabled. 1 CLK_MAIN_OTBN is enabled.


CLKMGR.MEASURE_CTRL_REGWEN @ 0x1c

Measurement control write enable

Reset default = 0x1, mask 0x1
31302928272625242322212019181716
 
1514131211109876543210
  EN
BitsTypeResetNameDescription
0rw0c0x1EN

When 1, the value of the measurement control can be set. When 0, writes have no effect.


CLKMGR.IO_MEASURE_CTRL @ 0x20

Configuration controls for io measurement.

Reset default = 0x759ea0, mask 0xfffff1
Register enable = MEASURE_CTRL_REGWEN

The threshold fields are made wider than required (by 1 bit) to ensure there is room to adjust for measurement inaccuracies.

31302928272625242322212019181716
  MIN_THRESH...
1514131211109876543210
...MIN_THRESH MAX_THRESH   EN
BitsTypeResetNameDescription
0rw0x0EN

Enable measurement for io

3:1Reserved
13:4rw0x1eaMAX_THRESH

Max threshold for io measurement

23:14rw0x1d6MIN_THRESH

Min threshold for io measurement


CLKMGR.IO_DIV2_MEASURE_CTRL @ 0x24

Configuration controls for io_div2 measurement.

Reset default = 0x1ccfa0, mask 0x3ffff1
Register enable = MEASURE_CTRL_REGWEN

The threshold fields are made wider than required (by 1 bit) to ensure there is room to adjust for measurement inaccuracies.

31302928272625242322212019181716
  MIN_THRESH...
1514131211109876543210
...MIN_THRESH MAX_THRESH   EN
BitsTypeResetNameDescription
0rw0x0EN

Enable measurement for io_div2

3:1Reserved
12:4rw0xfaMAX_THRESH

Max threshold for io_div2 measurement

21:13rw0xe6MIN_THRESH

Min threshold for io_div2 measurement


CLKMGR.IO_DIV4_MEASURE_CTRL @ 0x28

Configuration controls for io_div4 measurement.

Reset default = 0x6e820, mask 0xffff1
Register enable = MEASURE_CTRL_REGWEN

The threshold fields are made wider than required (by 1 bit) to ensure there is room to adjust for measurement inaccuracies.

31302928272625242322212019181716
  MIN_THRESH...
1514131211109876543210
...MIN_THRESH MAX_THRESH   EN
BitsTypeResetNameDescription
0rw0x0EN

Enable measurement for io_div4

3:1Reserved
11:4rw0x82MAX_THRESH

Max threshold for io_div4 measurement

19:12rw0x6eMIN_THRESH

Min threshold for io_div4 measurement


CLKMGR.MAIN_MEASURE_CTRL @ 0x2c

Configuration controls for main measurement.

Reset default = 0x7a9fe0, mask 0xfffff1
Register enable = MEASURE_CTRL_REGWEN

The threshold fields are made wider than required (by 1 bit) to ensure there is room to adjust for measurement inaccuracies.

31302928272625242322212019181716
  MIN_THRESH...
1514131211109876543210
...MIN_THRESH MAX_THRESH   EN
BitsTypeResetNameDescription
0rw0x0EN

Enable measurement for main

3:1Reserved
13:4rw0x1feMAX_THRESH

Max threshold for main measurement

23:14rw0x1eaMIN_THRESH

Min threshold for main measurement


CLKMGR.USB_MEASURE_CTRL @ 0x30

Configuration controls for usb measurement.

Reset default = 0x1ccfa0, mask 0x3ffff1
Register enable = MEASURE_CTRL_REGWEN

The threshold fields are made wider than required (by 1 bit) to ensure there is room to adjust for measurement inaccuracies.

31302928272625242322212019181716
  MIN_THRESH...
1514131211109876543210
...MIN_THRESH MAX_THRESH   EN
BitsTypeResetNameDescription
0rw0x0EN

Enable measurement for usb

3:1Reserved
12:4rw0xfaMAX_THRESH

Max threshold for usb measurement

21:13rw0xe6MIN_THRESH

Min threshold for usb measurement


CLKMGR.RECOV_ERR_CODE @ 0x34

Recoverable Error code

Reset default = 0x0, mask 0x1f
31302928272625242322212019181716
 
1514131211109876543210
  USB_MEASURE_ERR MAIN_MEASURE_ERR IO_DIV4_MEASURE_ERR IO_DIV2_MEASURE_ERR IO_MEASURE_ERR
BitsTypeResetNameDescription
0rw1c0x0IO_MEASURE_ERR

io has encountered a measurement error.

1rw1c0x0IO_DIV2_MEASURE_ERR

io_div2 has encountered a measurement error.

2rw1c0x0IO_DIV4_MEASURE_ERR

io_div4 has encountered a measurement error.

3rw1c0x0MAIN_MEASURE_ERR

main has encountered a measurement error.

4rw1c0x0USB_MEASURE_ERR

usb has encountered a measurement error.


CLKMGR.FATAL_ERR_CODE @ 0x38

Error code

Reset default = 0x0, mask 0x1
31302928272625242322212019181716
 
1514131211109876543210
  REG_INTG
BitsTypeResetNameDescription
0ro0x0REG_INTG

Register file has experienced a fatal integrity error.