interrupt.h File Reference

This file describes the interfaces for compartments to wait for interrupts. More...

#include <compartment.h>
#include <stdbool.h>
#include "board-interrupts.h"

Go to the source code of this file.

Classes
struct	InterruptCapabilityState
	Structure for authorising access to a specific interrupt. More...

Macros
#define	DECLARE_INTERRUPT_CAPABILITY(name)
	Helper macro to forward declare an interrupt capability.
#define	DEFINE_INTERRUPT_CAPABILITY(name, number, mayWait, mayComplete)
	Helper macro to define an interrupt capability.
#define	DECLARE_AND_DEFINE_INTERRUPT_CAPABILITY( name, number, mayWait, mayComplete)
	Helper macro to define an interrupt capability without a separate declaration.

Functions
typedef	CHERI_SEALED (struct InterruptCapabilityState *) InterruptCapability
	Type for sealed capabilities that authorise access to interrupts.
const uint32_t *	interrupt_futex_get (InterruptCapability interruptcapability)
	Request the futex associated with an interrupt.
int	interrupt_complete (InterruptCapability interruptcapability)
	Acknowledge the end of handling an interrupt.

Detailed Description

This file describes the interfaces for compartments to wait for interrupts.

Interrupts are exposed to compartments as futexes that contain the count of the number of times that an interrupt has fired. This count can wrap but that should not be visible in practice (if will be observable only if one thread handles a specific interrupt 2^32 times in between another thread finishing handling that interrupt and waiting again).

The flow for waiting for an interrupt involves the following steps:

1. Request the futex word for a particular from the scheduler.
2. Wait on the futex.
3. Read the value of the futex word.
4. Handle whatever the interrupt was raised for.
5. Mark the interrupt as completed.
6. Loop from step 2, using the value read from step 3.

If the interrupt fires between steps 5 and 6 then the futex word will not match the value read in step 3 and the futex wait will return immediately.

The first time that step 2 is reached, the expected value for the futex should be 0. This ensures that you acknowledge any interrupt that happened in between the system starting and your registering interest in the interrupt.

Note that step 2 may use a multiwaiter, rather than a single futex_wait call, if you wish to wait for one of multiple event sources.

Both step 1 and 5 require an authorising capability, as described below.

Definition in file interrupt.h.

Macro Definition Documentation

DECLARE_AND_DEFINE_INTERRUPT_CAPABILITY

#define DECLARE_AND_DEFINE_INTERRUPT_CAPABILITY	(		name,
			number,
			mayWait,
			mayComplete )

Value:

DECLARE_INTERRUPT_CAPABILITY(name);                                        \
DEFINE_INTERRUPT_CAPABILITY(name, number, mayWait, mayComplete)

Helper macro to define an interrupt capability without a separate declaration.

The arguments are the same as those for DEFINE_INTERRUPT_CAPABILITY.

Definition at line 109 of file interrupt.h.

DECLARE_INTERRUPT_CAPABILITY

#define DECLARE_INTERRUPT_CAPABILITY

(

name

)

Value:

DECLARE_STATIC_SEALED_VALUE(                                               \
  struct InterruptCapabilityState, scheduler, InterruptKey, name);

Helper macro to forward declare an interrupt capability.

Definition at line 85 of file interrupt.h.

DEFINE_INTERRUPT_CAPABILITY

#define DEFINE_INTERRUPT_CAPABILITY	(		name,
			number,
			mayWait,
			mayComplete )

Value:

DEFINE_STATIC_SEALED_VALUE(struct InterruptCapabilityState,                \
                           scheduler,                                      \
                           InterruptKey,                                   \
                           name,                                           \
                           number,                                         \
                           mayWait,                                        \
                           mayComplete);

Helper macro to define an interrupt capability.

The three arguments after the name are the interrupt number and two boolean values indicating whether it may be used with interrupt_futex_get and with interrupt_complete, respectively.

Definition at line 95 of file interrupt.h.

Function Documentation

interrupt_complete()

int interrupt_complete

(

InterruptCapability

interruptcapability

)

Acknowledge the end of handling an interrupt.

The argument is a sealed capability to an InterruptCapabilityState structure that must have mayWait flag set to true. This is sealed with the InterruptKey type exposed from the scheduler compartment.

Returns 0 on success or -EPERM if the argument does not authorise this operation.

References interrupt_complete().

Referenced by interrupt_complete().

interrupt_futex_get()

const uint32_t * interrupt_futex_get

(

InterruptCapability

interruptcapability

)

Request the futex associated with an interrupt.

The argument is a sealed capability to an InterruptCapabilityState structure that must have mayWait flag set to true. This is sealed with the InterruptKey type exposed from the scheduler compartment.

Returns nullptr on failure.

References interrupt_futex_get().

Referenced by Ibex::HardwareRevoker< WordT, TCMBaseAddr >::init(), interrupt_futex_get(), Ksz8851Ethernet::Ksz8851Ethernet(), and KunyanEthernet::KunyanEthernet().