Housekeeping SPI

The “housekeeping” SPI is an SPI responder that can be accessed from a remote host through a standard 4-pin serial interface. The SPI implementation is mode 0, with new data on SDI captured on the SCK rising edge, and output data presented on the falling edge of SCK (to be sampled on the next SCK rising edge). The SPI pins are shared with user area GPIO.

SPI protocol definition

All input is in groups of 8 bits. Each byte is input most-significant-bit first.

Every command sequence requires one command word (8 bits), followed by one address word (8 bits), followed by one or more data words (8 bits each), according to the data transfer modes described in Housekeeping SPI modes.

Housekeeping SPI signalling

Fig. 4 Housekeeping SPI signalling

Addresses are read in sequence from lower values to higher values.

Therefore groups of bits larger than 8 should be grouped such that the lowest bits are at the highest address. Any bits additional to an 8-bit boundary should be at the lowest address.

Data is captured from the register map in bytes on the falling edge of the last SCK before a data byte transfer. Multi-byte transfers should ensure that data do not change between byte reads.

CSB pin must be low to enable an SPI transmission. Data are clocked by pin SCK, with data valid on the rising edge of SCK. Output data is received on the SDO line. SDO is held high-impedance when CSB is high and at all times other than the transfer of data bits on a read command. SDO outputs become active on the falling edge of SCK, such that data are written and read on the same SCK rising edge.

After CSB is set low, the SPI is always in the “command” state, awaiting a new command.

The first transferred byte is the command word, interpreted according to the Housekeeping SPI command word definition.

Table 10 Housekeeping SPI command word definition




No operation


Write in streaming mode


Read in streaming mode


Simultaneous Read/Write in streaming mode


Pass-through (management) Read/Write in streaming mode


Pass-through (user) Read/Write in streaming mode


Write in n-byte mode (up to 7 bytes)


Read in n-byte mode (up to 7 bytes)


Simultaneous Read/Write in n-byte mode (up to 7 bytes)


All other words are reserved and act as no-operation if not defined by the SPI responder module.

Housekeeping SPI modes

The two basic modes of operation are streaming mode and n-byte mode.

In streaming mode operation, the data is sent or received continuously, one byte at a time, with the internal address incrementing for each byte. Streaming mode operation continues until CSB is raised to end the transfer.

In n-byte mode operation, the number of bytes to be read and/or written is encoded in the command word, and may have a value from 1 to 7 (note that a value of zero implies streaming mode). After n bytes have been read and/or written, the SPI returns to waiting for the next command. No toggling of CSB is required to end the command or to initiate the following command.

Pass-thru mode

The pass-thru mode puts the CPU into immediate reset, then sets FLASH_CSB low to initiate a data transfer to the QSPI flash. After the pass-thru command byte has been issued, all subsequent SPI signaling on SDI and SCK are applied directly to the QSPI flash (pins FLASH_IO0 and FLASH_CLK, respectively), and the QSPI flash data output (pin FLASH_IO1) is applied directly to SDO, until the CSB pin is raised. When CSB is raised, the FLASH_CSB is also raised, terminating the data transfer to the QSPI flash. The CPU is brought out of reset, and starts executing instructions at the program start address.

This mode allows the QSPI flash to be programmed from the same SPI communication channel as the housekeeping SPI, without the need for additional wiring to the QSPI flash chip.

There are two pass-thru modes. The first one corresponds to the primary SPI flash used by the management SoC. The second one corresponds to a secondary optional SPI flash that can be defined in the user project.

The pass-thru mode allows a communications chip external to the Caravel chip program either SPI flash chip from a host computer without requiring separate external access to the SPI flash. Both pass-thru modes only connect to I/O pins 0 and 1 of the SPI flash chips, and so must operate only in the 4-pin SPI mode. The user project may elect to operate the SPI flash in quad mode using a 6-pin interface.

Housekeeping SPI registers

The purpose of the housekeeping SPI is to give access to certain system values and controls independently of the CPU. The housekeeping SPI can be accessed even when the CPU is in full reset. Some control registers in the housekeeping SPI affect the behaviour of the CPU in a way that can be potentially detrimental to the CPU operation, such as adjusting the trim value of the digital frequency-locked loop generating the CPU core clock.

Under normal working conditions, the SPI should not need to be accessed unless it is to adjust the clock speed of the CPU. All other functions are purely for test and debug.

The housekeeping SPI can be accessed by the CPU from a running program by enabling the SPI controller, and enabling the bit that connects the internal SPI controller directly to the housekeeping SPI. This configuration then allows a program to read, for example, the user project ID of the chip. See the SPI controller description for details.

Housekeeping SPI register map

Fig. 5 Housekeeping SPI register map

Table 11 Housekeeping SPI registers


Register address



0x01 (low 4 bits) and 0x02

The 12-bit manufacturer ID for efabless is 0x456



The product ID for the Caravel harness chip is 0x10


0x04 to 0x07

The 4-byte (32bit) user project ID is metal-mask programmed on each project before tapeout, with a unique number given to each user project.

PLL enable

0x08 bit 0

This bit enables the digital frequency-locked-loop clock multiplier. The enable should be applied prior to turning off the PLL bypass to allow the PLL time to stabilize before using it to drive the CPU clock.

PLL DCO enable

0x08 bit 1

The PLL can be run in DCO mode, in which the feedback loop to the driving clock is removed, and the system operates in free-running mode, driven by the ring oscillator which can be tuned between approximately 90 to 200MHz by setting the trim bits (check PLL trim)

PLL bypass

0x09 bit 0

When enabled, the PLL bypass switches the clock source of the CPU from the PLL output to the external CMOS clock (pin C9). The default value is 0x1 (CPU clock source is the external CMOS clock).


0x0A bit 0

This is a dedicated manual interrupt driving the CPU IRQ channel 6. The bit is not self-resetting, so while the rising edge will trigger an interrupt, the signal must be manually set to zero before it can trigger another interrupt.

CPU reset

0x0B bit 0

The CPU reset bit puts the entire CPU into a reset state. This bit is not self-resetting and must be set back to zero manually to clear the reset state

CPU trap

0x0C bit 0

If the CPU has stopped after encountering an error, it will raise the trap signal. The trap signal can be configured to be read from a GPIO pin, but as the GPIO state is potentially unknowable, the housekeeping SPI can be used to determine the true trap state.

PLL trim

0x0D (all bits) to 0x10 (lower two bits)

The 26-bit trim value can adjust the DCO frequency over a factor of about two from the slowest (trim value 0x3ffffff) to the fastest (trim value 0x0). Default value is 0x3ffefff (slow trim, -1). Note that this is a thermometer-code trim, where each bit provides an additional (approximately) 250ps delay (on top of a fixed delay of 4.67ns). The fastest output frequency is approximately 215MHz while the slowest output frequency is approximately 90MHz.

PLL output divider

0x11 bits 2-0

The PLL output can be divided down by an integer divider to provide the core clock frequency. This 3-bit divider can generate a clock divided by 2 to 7. Values 0 and 1 both pass the undivided PLL clock directly to the core (and should not be used, as the processor does not operate at these frequencies).

PLL output divider (2)

0x11 bits 5-3

The PLL 90-degree phase output is passed through an independent 3-bit integer clock divider and provided to the user project space as a secondary clock. Values 0 and 1 both pass the undivided PLL clock, while values 2 to 7 pass the clock divided by 2 to 7, respectively.

PLL feedback divider

0x12 bits 4-0

The PLL operates by comparing the input clock (pin C9) rate to the rate of the PLL clock divided by the feedback divider value (when running in PLL mode, not DCO mode). The feedback divider must be set such that the external clock rate multiplied by the feedback divider value falls between 90 and 214 MHz (preferably centered on this range, or approximately 150 MHz). For example, when using an 8 MHz external clock, the divider should be set to 19 (19 * 8 = 152). The DCO range and the number of bits of the feedback divider implies that the external clock should be no slower than around 4 to 5 MHz.