satcat5/interrupts.h File Reference

Detailed Description

Platform-agnostic API for interrupt management.

This file defines a platform-agnostic interface for designating interrrupt handlers and responding to those interrupts.

By default, this system does nothing. However, when linked to a platform-specific interrupt controller, such as the ones defined in hal_samv71/interrupts.h or hal_ublaze/interrupts.h, then each irq::Handler object will be registered as an interrupt handler, calling irq_event() whenever a hardware interrupt is received.

This file also defines primitives for uninterruptible atomic operations. For now, the SatCat5 main-loop (see polling.h) is a single-threaded event loop that allows cooperative multitasking using an event queue. Except for hardware interrupts, event handling is sequential. The AtomicLock mutex defined here simply disables hardware interrupts to create uninterruptible critical sections. The AtomicLock mutex is reentrant (i.e., it is safe to lock twice, then unlock twice).

Each of the included primitives includes built-in tools for measuring elapsed time. Interrupt service routines and uninterruptible sections should always be VERY quick, so we track the worst offenders.

Note that the interrupt services here are intended for hardware interrupts, i.e., interrupt signals attached directly to a platform- specific hardware interrupt handler, such irq::ControllerMicroblaze or freertos::ControllerFreeRTOS. This includes the shared interrupt channel associated with a ConfigBus host, such as cfg::ConfigBusMmap. It is separate from the cfg::Interrupt handlers used for individual ConfigBus peripherals.

Definition in file satcat5/interrupts.h.

#include <satcat5/list.h>
#include <satcat5/timeref.h>
#include <satcat5/types.h>

Include dependency graph for satcat5/interrupts.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	satcat5::irq::AtomicLock
	Automatic lock or mutex. More...
class	satcat5::irq::Controller
	Platform-agnostic interrupt controller. More...
class	satcat5::irq::ControllerNull
	A do-nothing placeholder implementation of irq::Controller . More...
class	satcat5::irq::Handler
	Parent object for receiving interrupt-handler callbacks. More...
class	satcat5::irq::Adapter
	Adapter connects a hardware interrupt to any OnDemand object. More...
class	satcat5::irq::Shared
	Shared interrupt handler calls all children for any parent event. More...

Macros
#define	SATCAT5_IRQ_STATS   1

Functions
bool	satcat5::irq::pre_test_reset ()
	Hard-reset of global variables at the start of each unit test. More...

Variables
constexpr int	satcat5::irq::IRQ_NONE = -1
	Special index "-1" indicates a disabled or unconnected interrupt.
satcat5::util::RunningMax	satcat5::irq::worst_irq
	Statistics tracking for critical sections. More...
satcat5::util::RunningMax	satcat5::irq::worst_lock
	Statistics tracking for critical sections. More...
satcat5::util::RunningMax	satcat5::irq::worst_stack
	Statistics tracking for critical sections. More...

Function Documentation

pre_test_reset()

bool satcat5::irq::pre_test_reset

(

)

Hard-reset of global variables at the start of each unit test.

(Unit testing only, should not be called in production.)

A hard reset may leak memory but prevents contamination of global state across tests, which can be extremely difficult to debug. Returns true if globals were already in the expected state.

Definition at line 46 of file satcat5/interrupts.cc.

Variable Documentation

worst_irq

util::RunningMax satcat5::irq::worst_irq

extern

Statistics tracking for critical sections.

SatCat5 interrupt-API concepts.

For diagnostics purposes, these global objects track the worst offenders for excessive time spent in a critical section, slow interrupt handlers, and maximum observed stack depth.

Definition at line 18 of file satcat5/interrupts.cc.

worst_lock

util::RunningMax satcat5::irq::worst_lock

Statistics tracking for critical sections.

SatCat5 interrupt-API concepts.

For diagnostics purposes, these global objects track the worst offenders for excessive time spent in a critical section, slow interrupt handlers, and maximum observed stack depth.

Definition at line 268 of file satcat5/interrupts.h.

worst_stack

util::RunningMax satcat5::irq::worst_stack

Statistics tracking for critical sections.

SatCat5 interrupt-API concepts.

For diagnostics purposes, these global objects track the worst offenders for excessive time spent in a critical section, slow interrupt handlers, and maximum observed stack depth.

Definition at line 268 of file satcat5/interrupts.h.