reset_cause.h File Reference

Why the IOmcu last started, named from the registers its boot leaves behind. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures
struct	reset_regs_t
	The raw values, as read at boot. More...

Macros
#define	RESET_CHIP_HAD_POR   0x00010000u
#define	RESET_CHIP_HAD_BOR   0x00020000u
#define	RESET_CHIP_HAD_RUN_LOW   0x00040000u
#define	RESET_CHIP_HAD_DP_RESET_REQ   0x00080000u
#define	RESET_CHIP_HAD_RESCUE   0x00200000u
#define	RESET_CHIP_HAD_WATCHDOG_RESET_POWMAN_ASYNC   0x00400000u
#define	RESET_CHIP_HAD_WATCHDOG_RESET_POWMAN   0x00800000u
#define	RESET_CHIP_HAD_WATCHDOG_RESET_SWCORE   0x01000000u
#define	RESET_CHIP_HAD_SWCORE_PD   0x02000000u
#define	RESET_CHIP_HAD_GLITCH_DETECT   0x04000000u
#define	RESET_CHIP_HAD_HZD_SYS_RESET_REQ   0x08000000u
#define	RESET_CHIP_HAD_WATCHDOG_RESET_PSM   0x10000000u
#define	RESET_CHIP_HAD_WATCHDOG_ANY
	Every CHIP_RESET bit that names a watchdog reset.
#define	RESET_WD_REASON_TIMER   0x1u
#define	RESET_WD_REASON_FORCE   0x2u
#define	RESET_BOOT_TYPE_NORMAL   0x00u
#define	RESET_BOOT_TYPE_BOOTSEL   0x02u
#define	RESET_BOOT_TYPE_RAM_IMAGE   0x03u
#define	RESET_BOOT_TYPE_FLASH_UPDATE   0x04u
#define	RESET_BOOT_TYPE_PC_SP   0x0Du
#define	RESET_BOOT_TYPE_CHAINED_FLAG   0x80u
#define	RESET_PICOTOOL_P0   0xFFFFFFFFu
	SCRATCH2 and SCRATCH3 after picotool's reboot from BOOTSEL into the application: type NORMAL, p0 = BOOT_PARTITION_NONE (-1), p1 = 0.
#define	RESET_PICOTOOL_P1   0x00000000u
	SCRATCH3 after that reboot: p1 = 0.
#define	RESET_CAUSE_FULL_MAX   144u
	Bytes that hold the longest full form with its NUL.

Enumerations
enum	reset_cause_t {   RESET_CAUSE_UNKNOWN = 0 , RESET_CAUSE_POR , RESET_CAUSE_BOR , RESET_CAUSE_RUN_PIN ,   RESET_CAUSE_GLITCH , RESET_CAUSE_DEBUGGER , RESET_CAUSE_POWER_DOWN , RESET_CAUSE_FLASH_UPDATE ,   RESET_CAUSE_RAM_IMAGE , RESET_CAUSE_BOOTSEL_REBOOT , RESET_CAUSE_SW_RESET , RESET_CAUSE_WATCHDOG ,   RESET_CAUSE_COUNT }
	The causes reset_cause_decode() names. More...

Functions
reset_cause_t	reset_cause_decode (const reset_regs_t *r)
	Names the cause of the last start.
const char *	reset_cause_word (reset_cause_t c)
	The fixed word for a cause: POR, BOR, RUN_PIN, GLITCH, DEBUGGER, POWER_DOWN, FLASH_UPDATE, RAM_IMAGE, BOOTSEL_REBOOT, SW_RESET, WATCHDOG or UNKNOWN.
int	reset_cause_boot_type (const reset_regs_t *r)
	The boot type in the boot word, without the chained flag.
size_t	reset_cause_full (const reset_regs_t *r, char *out, size_t n)
	The text of the start-up line and the 3s line, every raw value in hex: POR (chip_reset 0x00010000 reason 0x0 boot 0x00000000 params 0x00000000 0x00000000 scratch 0x00000000 0x00000000), with boot none in place of the boot word and the params when rom_get_boot_info() failed.

Detailed Description

Why the IOmcu last started, named from the registers its boot leaves behind.

Three records survive a restart, and each is cleared by a different reset (RP2350 datasheet, sections 7.3, 7.4, 12.9.4 and 12.9.5):

• POWMAN CHIP_RESET latches the source of the last chip-level reset: POR, BOR, the RUN pin, a debugger, a glitch, a switched-core power-down, or a watchdog that POWMAN WDSEL lets reset the chip. Its HAD_* bits are RO (table 489), so software cannot clear them. A watchdog reset through PSM WDSEL alone is a system reset, not a chip-level one, and leaves CHIP_RESET as it was: after the boot ROM's reboot(), which sets PSM WDSEL = ~PROC_COLD and leaves POWMAN WDSEL at 0, CHIP_RESET still reads HAD_POR from the power-up before.
• WATCHDOG REASON names the last watchdog trigger, TIMER or FORCE. Every chip-level reset resets the watchdog, so REASON reads 0 after one. The boot ROM's reboot() runs the watchdog in timer mode, so a reboot it performs reads TIMER.
• WATCHDOG SCRATCH2 and SCRATCH3 hold p0 and p1 of the last reboot() of any type but PC_SP. A chip-level reset by the watchdog and the RUN pin or DVDD (digital core supply) cycling reset them.

The boot ROM's boot info (rom_get_boot_info()) gives the type of this boot; a type other than NORMAL comes only from a reboot() vector in the watchdog scratch registers. This file turns these raw values into one fixed word.

Pure C with no pico-sdk: the firmware reads the registers once at boot (firmware/iomcu/src/iomcu_report.c) and holds the bit values below equal to the SDK's with _Static_assert.

Bit names and positions are those of pico-sdk 2.3.0, src/rp2350/hardware_regs/include/hardware/regs/powman.h and watchdog.h, and the boot types of boot/bootrom_constants.h.

SPDX-License-Identifier: MIT

Macro Definition Documentation

RESET_BOOT_TYPE_BOOTSEL

#define RESET_BOOT_TYPE_BOOTSEL   0x02u

USB or UART boot

RESET_BOOT_TYPE_CHAINED_FLAG

#define RESET_BOOT_TYPE_CHAINED_FLAG   0x80u

a bootloader chained in

RESET_BOOT_TYPE_FLASH_UPDATE

#define RESET_BOOT_TYPE_FLASH_UPDATE   0x04u

after a flash write

RESET_BOOT_TYPE_NORMAL

#define RESET_BOOT_TYPE_NORMAL   0x00u

no one-shot boot type

RESET_BOOT_TYPE_PC_SP

#define RESET_BOOT_TYPE_PC_SP   0x0Du

a vector reboot

RESET_BOOT_TYPE_RAM_IMAGE

#define RESET_BOOT_TYPE_RAM_IMAGE   0x03u

an image in SRAM

RESET_CHIP_HAD_BOR

#define RESET_CHIP_HAD_BOR   0x00020000u

bit 17

RESET_CHIP_HAD_DP_RESET_REQ

#define RESET_CHIP_HAD_DP_RESET_REQ   0x00080000u

bit 19

RESET_CHIP_HAD_GLITCH_DETECT

#define RESET_CHIP_HAD_GLITCH_DETECT   0x04000000u

bit 26

RESET_CHIP_HAD_HZD_SYS_RESET_REQ

#define RESET_CHIP_HAD_HZD_SYS_RESET_REQ   0x08000000u

bit 27

RESET_CHIP_HAD_POR

#define RESET_CHIP_HAD_POR   0x00010000u

bit 16

RESET_CHIP_HAD_RESCUE

#define RESET_CHIP_HAD_RESCUE   0x00200000u

bit 21

RESET_CHIP_HAD_RUN_LOW

#define RESET_CHIP_HAD_RUN_LOW   0x00040000u

bit 18

RESET_CHIP_HAD_SWCORE_PD

#define RESET_CHIP_HAD_SWCORE_PD   0x02000000u

bit 25

RESET_CHIP_HAD_WATCHDOG_ANY

#define RESET_CHIP_HAD_WATCHDOG_ANY

Value:

(RESET_CHIP_HAD_WATCHDOG_RESET_POWMAN_ASYNC                             \
 | RESET_CHIP_HAD_WATCHDOG_RESET_POWMAN                                 \
 | RESET_CHIP_HAD_WATCHDOG_RESET_SWCORE                                 \
 | RESET_CHIP_HAD_WATCHDOG_RESET_PSM)

Every CHIP_RESET bit that names a watchdog reset.

RESET_CHIP_HAD_WATCHDOG_RESET_POWMAN

#define RESET_CHIP_HAD_WATCHDOG_RESET_POWMAN   0x00800000u

bit 23

RESET_CHIP_HAD_WATCHDOG_RESET_POWMAN_ASYNC

#define RESET_CHIP_HAD_WATCHDOG_RESET_POWMAN_ASYNC   0x00400000u

bit 22

RESET_CHIP_HAD_WATCHDOG_RESET_PSM

#define RESET_CHIP_HAD_WATCHDOG_RESET_PSM   0x10000000u

bit 28

RESET_CHIP_HAD_WATCHDOG_RESET_SWCORE

#define RESET_CHIP_HAD_WATCHDOG_RESET_SWCORE   0x01000000u

bit 24

RESET_PICOTOOL_P0

#define RESET_PICOTOOL_P0   0xFFFFFFFFu

SCRATCH2 and SCRATCH3 after picotool's reboot from BOOTSEL into the application: type NORMAL, p0 = BOOT_PARTITION_NONE (-1), p1 = 0.

picotool 2.x sends this after every command run with -f, and for picotool reboot. This firmware calls reboot() with type FLASH_UPDATE only.

RESET_WD_REASON_FORCE

#define RESET_WD_REASON_FORCE   0x2u

CTRL.TRIGGER was written

RESET_WD_REASON_TIMER

#define RESET_WD_REASON_TIMER   0x1u

the watchdog counted down to zero

Enumeration Type Documentation

reset_cause_t

enum reset_cause_t

The causes reset_cause_decode() names.

Enumerator
RESET_CAUSE_UNKNOWN	no cause recorded
RESET_CAUSE_POR	power-on reset
RESET_CAUSE_BOR	brown-out detector
RESET_CAUSE_RUN_PIN	RUN pin held low
RESET_CAUSE_GLITCH	supply glitch detector
RESET_CAUSE_DEBUGGER	Arm debugger, rescue or hazard debugger
RESET_CAUSE_POWER_DOWN	switched-core power-down
RESET_CAUSE_FLASH_UPDATE	a reboot() into a FLASH_UPDATE boot
RESET_CAUSE_RAM_IMAGE	a reboot() into a RAM image boot
RESET_CAUSE_BOOTSEL_REBOOT	back from BOOTSEL by picotool
RESET_CAUSE_SW_RESET	watchdog triggered at once
RESET_CAUSE_WATCHDOG	watchdog counted down, NORMAL boot

Function Documentation

reset_cause_boot_type()

int reset_cause_boot_type

(

const reset_regs_t *

r

)

The boot type in the boot word, without the chained flag.

Parameters

r	The raw values.

Returns

The boot type, or -1 when rom_get_boot_info() failed.

reset_cause_decode()

reset_cause_t reset_cause_decode

(

const reset_regs_t *

r

)

Names the cause of the last start.

First match wins:

1. The boot type: FLASH_UPDATE (this firmware's update over CAN, a UF2 copied to the BOOTSEL drive, picotool load -x), RAM_IMAGE, BOOTSEL (the boot ROM reports this type only while it stays in BOOTSEL; decoded for completeness).
2. REASON TIMER or FORCE: a watchdog system reset, and CHIP_RESET is the record of an older reset. SCRATCH2/SCRATCH3 at RESET_PICOTOOL_P0/P1 with a NORMAL boot: BOOTSEL_REBOOT. The 1200 baud request and picotool's -f enter BOOTSEL through reboot() with p0 = interface flags and p1 = the activity LED pin (0xFFFFFFFF for none); the reboot out of BOOTSEL overwrites both. The firmware zeroes both registers after it reads them. Else FORCE: SW_RESET (the SDK's watchdog_reboot() with no delay). Else WATCHDOG: the boot ROM's 16.7s TBYB (try before you buy) timer after an update that was not bought, a reboot() with type NORMAL and other parameters, or the SDK's watchdog_reboot() with a delay.
3. REASON 0, so CHIP_RESET holds this start's chip-level reset: HAD_POR, HAD_BOR, HAD_RUN_LOW, HAD_GLITCH_DETECT, in that order; then HAD_DP_RESET_REQ, HAD_RESCUE or HAD_HZD_SYS_RESET_REQ as DEBUGGER; HAD_SWCORE_PD as POWER_DOWN; a HAD_WATCHDOG_* bit as WATCHDOG.
4. Nothing set: UNKNOWN.

A debugger's warm reset of a core clears REASON (datasheet, WATCHDOG REASON) without a chip-level reset; the start after one reads as the chip-level reset before it.

Parameters

r	The raw values; NULL reads as UNKNOWN.

Returns

The cause.

reset_cause_full()

size_t reset_cause_full	(	const reset_regs_t *	r,
		char *	out,
		size_t	n )

The text of the start-up line and the 3s line, every raw value in hex: POR (chip_reset 0x00010000 reason 0x0 boot 0x00000000 params 0x00000000 0x00000000 scratch 0x00000000 0x00000000), with boot none in place of the boot word and the params when rom_get_boot_info() failed.

Parameters

r	The raw values.
out	Receives the text, NUL-terminated and cut to fit.
n	Size of out in bytes; RESET_CAUSE_FULL_MAX holds it.

Returns

The length the whole text needs, without the NUL, as snprintf().

reset_cause_word()

const char * reset_cause_word

(

reset_cause_t

c

)

The fixed word for a cause: POR, BOR, RUN_PIN, GLITCH, DEBUGGER, POWER_DOWN, FLASH_UPDATE, RAM_IMAGE, BOOTSEL_REBOOT, SW_RESET, WATCHDOG or UNKNOWN.

Parameters

c	The cause; a value out of range reads as UNKNOWN.

Returns

The word, a static string of at most 14 characters.