Hardware Watchdog Timer (WDT)¶

The Hardware Watchdog Timer provides one or more independent watchdog instances. Each watchdog has a configurable prescaler and down-counter. Software must periodically kick a watchdog to prevent it from timing out. An optional windowed mode restricts valid kicks to a defined time window, catching both missing kicks (timeout) and runaway loops that kick too frequently (window violation).

Features¶

Configurable number of independent watchdog instances
Per-watchdog configurable counter width and prescaler width
Windowed mode: valid kick window defined by window_open threshold
Write-once lock bit: prevents disabling and configuration changes once armed
Self-disclosure register exposing all compile-time parameters
Per-watchdog interrupt controller with four independently maskable sources (two without windowed mode)
Single combined interrupt output — asserted when any enabled source fires

Interrupt Architecture¶

Each watchdog has four interrupt sources (two when windowed = false):

Bit 0: timeout → interrupt (recoverable notification)
Bit 1: timeout → error (non-recoverable; typically routed to reset controller)
Bit 2: window violation → interrupt (windowed mode only)
Bit 3: window violation → error (windowed mode only)

Bits 0 and 1 share the same underlying timeout event; bits 2 and 3 share the window violation event. This allows the SoC integrator to route each event independently to the interrupt controller, reset controller, or both.

All masked pending bits across all watchdog instances are OR-ed into a single interrupt output. In the interrupt service routine, software reads the per-watchdog irq_pending registers to identify the source, services the condition, then writes 1 to the pending bit to clear it.

Protocol¶

Setup:

Write prescaler to set the tick frequency: f_tick = f_clk / (prescaler + 1).
Write timeout to set the reload value. The watchdog fires after (timeout + 1) ticks.
If windowed mode is compiled in, write window_open to the counter value below which kicks are valid. A kick is valid when counter <= window_open.
Write irq_mask to enable the desired interrupt sources.
Optionally write bit 1 of control to lock the configuration.
Write bit 0 of control to enable the watchdog. The counter loads with timeout on the rising edge of the enable bit.

Operation:

Write any value to kick while the counter is within the window to reload the counter.
Writing kick outside the window (windowed mode) generates a window violation.
When the counter reaches zero a timeout fires; the counter reloads automatically.

Configuration¶

Available bus architectures:

APB3
TileLink
Wishbone

By default, all buses are defined with 12 bit address and 32 bit data width.

Parameter¶

WatchdogCtrl.Parameter¶
Name	Type	Description	Default
count	Int	Number of independent watchdog instances. Must be between 1 and 255.	1
width	Int	Counter bit width. Must be between 1 and 32.	32
prescalerWidth	Int	Prescaler bit width. Must be between 1 and 32.	16
windowed	Boolean	Enable windowed mode and `window_open` register.	false
locked	Boolean	Include write-once lock bit in the control register.	true

object Parameter {
  def default()  = Parameter()
  def small()    = Parameter(width = 16, prescalerWidth = 8)
  def windowed() = Parameter(windowed = true)
}

Register Mapping¶

IP Identification:

The register map starts with an IP Identification block to provide all information about the underlying IP core to software drivers. This allows to provide backwards compatible drivers.

IP Identification Registers¶
Address	Bit	Field	Default	Permission	Description
0x000	31 - 24	API	0x0	Rx	API version of the implemented IP Identification.
	23 - 16	Length	0x8	Rx	Length of the IP Identification block in Bytes.
	15 - 0	ID	0x15	Rx	IP value of this IP core.
0x004	31 - 24	Major Version	0x1	Rx	Major number if this IP core. Version schema is major.minor.patch.
	23 - 16	Minor Version	0x0	Rx	Minor number if this IP core. Version schema is major.minor.patch.
	15 - 0	Patch Version	0x0	Rx	Patch number if this IP core. Version schema is major.minor.patch.

Self Disclosure:

Info Register (0x008)¶
Address	Bit	Field	Default	Permission	Description
0x008	31 - 26	—	0	Rx	Reserved.
	25	locked		Rx	1 if the lock feature is compiled in.
	24	windowed		Rx	1 if windowed mode is compiled in.
	23 - 16	prescalerWidth		Rx	Prescaler bit width.
	15 - 8	width		Rx	Counter bit width.
7 - 0	count		Rx	Number of watchdog instances.

Per-Watchdog Registers:

One set per watchdog instance. Instance 0 starts at 0x00C; stride between instances is 0x20.

Per-Watchdog Registers (base = 0x00C + instance × 0x20)¶
Address	Bit	Field	Default	Permission	Description
base + 0x00	1	lock	0	RW	Write-once lock bit. Once set, disabling the watchdog and writes to `prescaler`, `timeout`, and `window_open` are ignored. Only present when `locked = true`; reads 0 otherwise.
base + 0x00	0	enable	0	RW	Enable the watchdog. Rising edge reloads the counter with `timeout`. Writing 0 is ignored when `lock` is set.
base + 0x04	width - 1 downto 0	prescaler	max	RW	Prescaler reload value. Tick frequency = `f_clk / (prescaler + 1)`. Write ignored when locked.
base + 0x08	width - 1 downto 0	timeout	max	RW	Counter reload value. Timeout fires after `(timeout + 1)` ticks. Write ignored when locked.
base + 0x0C	width - 1 downto 0	window_open	0	RW	Kick valid threshold. A kick is accepted when `counter <= window_open`. Reads 0 when `windowed = false`. Write ignored when locked.
base + 0x10	2	inWindow	0	Rx	High while the counter is within the kick window (`windowed` only).
	1	locked	0	Rx	Current lock state. Reads 0 when `locked = false`.
	0	enabled	0	Rx	Current enable state.
base + 0x14	irqCount - 1 downto 0	irq_pending	0	RW	Interrupt pending flags. Write `1` to clear a bit. Bit 0 = timeout interrupt, bit 1 = timeout error, bit 2 = violation interrupt, bit 3 = violation error (bits 2–3 only when `windowed = true`).
base + 0x18	irqCount - 1 downto 0	irq_mask	0	RW	Interrupt enable mask. Set a bit to enable the corresponding source. Same bit layout as `irq_pending`.
base + 0x1C	—	kick	—	xW	Write any value to kick the watchdog. Reloads the counter when within the window; raises a window violation when outside the window (windowed mode).