Loading...
Searching...
No Matches
IRQs
Base API » Kernel Objects

C IRQ interface, see L4::Irq for the C++ interface. More...

Collaboration diagram for IRQs:

## Enumerations

enum

L4_irq_mode {
L4_IRQ_F_NONE = 0 , L4_IRQ_F_SET_MODE = 0x1 , L4_IRQ_F_LEVEL = 0x2 , L4_IRQ_F_EDGE = 0x0 ,
L4_IRQ_F_POS = 0x0 , L4_IRQ_F_NEG = 0x4 , L4_IRQ_F_BOTH = 0x8 , L4_IRQ_F_LEVEL_HIGH = L4_IRQ_F_SET_MODE | L4_IRQ_F_LEVEL | L4_IRQ_F_POS ,
L4_IRQ_F_LEVEL_LOW = L4_IRQ_F_SET_MODE | L4_IRQ_F_LEVEL | L4_IRQ_F_NEG , L4_IRQ_F_POS_EDGE = L4_IRQ_F_SET_MODE | L4_IRQ_F_EDGE | L4_IRQ_F_POS , L4_IRQ_F_NEG_EDGE = L4_IRQ_F_SET_MODE | L4_IRQ_F_EDGE | L4_IRQ_F_NEG , L4_IRQ_F_BOTH_EDGE = L4_IRQ_F_SET_MODE | L4_IRQ_F_EDGE | L4_IRQ_F_BOTH ,
L4_IRQ_F_MASK = 0xf , L4_IRQ_F_SET_WAKEUP = 0x10 , L4_IRQ_F_CLEAR_WAKEUP = 0x20
}

| Interrupt attributes. More...

## Functions

l4_msgtag_t | l4_irq_detach (l4_cap_idx_t irq) L4_NOTHROW
| Detach from an interrupt source.
l4_msgtag_t | l4_irq_detach_u (l4_cap_idx_t irq, l4_utcb_t *utcb) L4_NOTHROW
| Detach from this interrupt.
l4_msgtag_t | l4_irq_bind_vcpu (l4_cap_idx_t irq, l4_cap_idx_t thread, l4_umword_t cfg) L4_NOTHROW
| Bind a thread to this Irq for vCPU interrupt forwarding.
l4_msgtag_t | l4_irq_bind_vcpu_u (l4_cap_idx_t irq, l4_cap_idx_t thread, l4_umword_t cfg, l4_utcb_t *utcb) L4_NOTHROW
| Bind a thread to this Irq for vCPU interrupt forwarding.
l4_msgtag_t | l4_irq_trigger (l4_cap_idx_t irq) L4_NOTHROW
| Trigger an IRQ.
l4_msgtag_t | l4_irq_trigger_u (l4_cap_idx_t irq, l4_utcb_t *utcb) L4_NOTHROW
| Trigger the object.
l4_msgtag_t | l4_irq_receive (l4_cap_idx_t irq, l4_timeout_t to) L4_NOTHROW
| Unmask and wait for specified IRQ.
l4_msgtag_t | l4_irq_receive_u (l4_cap_idx_t irq, l4_timeout_t timeout, l4_utcb_t *utcb) L4_NOTHROW
| Unmask and wait for this IRQ.
l4_msgtag_t | l4_irq_wait (l4_cap_idx_t irq, l4_umword_t *label, l4_timeout_t to) L4_NOTHROW
| Unmask IRQ and wait for any message.
l4_msgtag_t | l4_irq_wait_u (l4_cap_idx_t irq, l4_umword_t *label, l4_timeout_t timeout, l4_utcb_t *utcb) L4_NOTHROW
| Unmask IRQ and (open) wait for any message.
l4_msgtag_t | l4_irq_unmask (l4_cap_idx_t irq) L4_NOTHROW
| Unmask IRQ.
l4_msgtag_t | l4_irq_unmask_u (l4_cap_idx_t irq, l4_utcb_t *utcb) L4_NOTHROW
| Unmask this IRQ.

## Detailed Description

C IRQ interface, see L4::Irq for the C++ interface.

The IRQ interface provides access to abstract interrupts provided by the microkernel. Interrupts may be

- hardware interrupts provided by the platform interrupt controller,
- virtual device interrupts provided by the microkernel's virtual devices (virtual serial or trace buffer) or
- virtual interrupts that can be triggered by user programs (IRQs) via l4_irq_trigger().

For hardware and virtual device interrupts the Irq object must be bound to an interrupt source, see Interrupt controller. To receive interrupts, the Irq object must be bound to a thread, see l4_rcv_ep_bind_thread() and l4_rcv_ep_bind_snd_destination().

IRQ objects can be created using a factory, see the Factory API (use l4_factory_create_irq()).

Include File
  #include <l4/sys/irq.h>
  irq.h
  C Irq interface.

For the C++ interface refer to the L4::Irq API for an overview.

## Enumeration Type Documentation

## L4_irq_mode

enum L4_irq_mode

Interrupt attributes.

Enumerator
L4_IRQ_F_NONE | Flow types. None
L4_IRQ_F_SET_MODE | Valid flag, if not set, the set_mode operation does nothing.
L4_IRQ_F_LEVEL | Level triggered.
L4_IRQ_F_EDGE | Edge triggered.
L4_IRQ_F_POS | Positive trigger.
L4_IRQ_F_NEG | Negative trigger.
L4_IRQ_F_BOTH | Both edges trigger.
L4_IRQ_F_LEVEL_HIGH | Level high trigger.
L4_IRQ_F_LEVEL_LOW | Level low trigger.
L4_IRQ_F_POS_EDGE | Positive edge trigger.
L4_IRQ_F_NEG_EDGE | Negative edge trigger.
L4_IRQ_F_BOTH_EDGE | Both edges trigger.
L4_IRQ_F_MASK | Mask.
L4_IRQ_F_SET_WAKEUP | Wakeup source? Use irq as wakeup source
L4_IRQ_F_CLEAR_WAKEUP | Do not use irq as wakeup source.

Definition at line 70 of file icu.h.

## Function Documentation

## l4_irq_bind_vcpu()

l4_msgtag_t l4_irq_bind_vcpu | ( | l4_cap_idx_t | irq,
|  | l4_cap_idx_t | thread,
|  | l4_umword_t | cfg )

inline

Bind a thread to this Irq for vCPU interrupt forwarding.

If the interrupt is triggered, the kernel will directly inject the interrupt into the guest. This requires that the thread is currently in extended vCPU user mode. Otherwise the interrupt will stay pending and gets injected on the next vCPU user mode transition. Optionally a doorbell Irq can be registered on the thread (see Thread::register_doorbell_irq()) that is triggered in this case.

If a guest has acknowledged the interrupt but has not yet issued an EOI (i.e. the interrupt is in "active" state), it is not possible to bind the Irq to a new thread object. Either wait for the guest to issue the EOI or detach() from the current thread. In this case the interrupt will stay active in the guest and it is the responsibility of the VMM to handle the eventual EOI of the guest.

Parameters

  irq | The IRQ object that shall be bound.
  thread | Thread object this Irq shall be bound to.
  cfg | Architecture specific interrupt configuration.

Returns
  Syscall return tag

Return values

  -L4_EPERM | Insufficient permissions; see precondition.
  -L4_EBUSY | Cannot bind to new thread because interrupt is active on previous thread and guest has to issue end-of-interrupt first.
  -L4_ENOSYS | The kernel does not support direct interrupt forwarding.

Precondition
  The capabilities irq and thread both must have the permission L4_CAP_FPAGE_S.

Definition at line 300 of file irq.h.

References l4_irq_bind_vcpu_u(), L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## l4_irq_bind_vcpu_u()

l4_msgtag_t l4_irq_bind_vcpu_u | ( | l4_cap_idx_t | irq,
|  | l4_cap_idx_t | thread,
|  | l4_umword_t | cfg,
|  | l4_utcb_t * | utcb )

inline

Bind a thread to this Irq for vCPU interrupt forwarding.

Parameters

  irq

  The IRQ object that shall be bound. If the interrupt is triggered, the kernel will directly inject the interrupt into the guest. This requires that the thread is currently in extended vCPU user mode. Otherwise the interrupt will stay pending and gets injected on the next vCPU user mode transition. Optionally a doorbell Irq can be registered on the thread (see Thread::register_doorbell_irq()) that is triggered in this case.

If a guest has acknowledged the interrupt but has not yet issued an EOI (i.e. the interrupt is in "active" state), it is not possible to bind the Irq to a new thread object. Either wait for the guest to issue the EOI or detach() from the current thread. In this case the interrupt will stay active in the guest and it is the responsibility of the VMM to handle the eventual EOI of the guest.

Parameters

  thread | Thread object this Irq shall be bound to.
  cfg | Architecture specific interrupt configuration.
  utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.

Returns
  Syscall return tag

Return values

  -L4_EPERM | Insufficient permissions; see precondition.
  -L4_EBUSY | Cannot bind to the new thread because interrupt is active on previous thread and guest has to issue end-of-interrupt first.
  -L4_ENOSYS | The kernel does not support direct interrupt forwarding.

Precondition
  The invoked Irq capability and the capability thread both must have the permission L4_CAP_FPAGE_S.

Definition at line 250 of file irq.h.

References L4_CAP_FPAGE_RWS, l4_ipc_call(), L4_IPC_NEVER, l4_map_obj_control(), l4_msgtag(), L4_NOTHROW, l4_obj_fpage(), L4_PROTO_IRQ_SENDER, l4_msg_regs_t::mr, and l4_fpage_t::raw.

Referenced by L4::Irq::bind_vcpu(), and l4_irq_bind_vcpu().

Here is the call graph for this function:
Here is the caller graph for this function:

## l4_irq_detach()

l4_msgtag_t l4_irq_detach | ( | l4_cap_idx_t | irq | ) |

inline

Detach from an interrupt source.

Parameters

  irq | The IRQ object that shall be detached.

Returns
  Syscall return tag

Return values

  0 | Successfully detached, there was no interrupt pending.
  1 | Successfully detached, there was an interrupt pending.
  2 | Successfully detached, an active vIRQ was abandoned.
  -L4_EPERM | Insufficient permissions; see precondition.

Precondition
  The capability irq must have the permission L4_CAP_FPAGE_S.

Examples
  examples/sys/isr/main.c.

Definition at line 294 of file irq.h.

References l4_irq_detach_u(), L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## l4_irq_detach_u()

l4_msgtag_t l4_irq_detach_u | ( | l4_cap_idx_t | irq,
|  | l4_utcb_t * | utcb )

inline

Detach from this interrupt.

Parameters

  irq | The IRQ object that shall be detached.
  utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.

Returns
  Syscall return tag

Return values

  0 | Successfully detached, there was no interrupt pending.
  1 | Successfully detached, there was an interrupt pending.
  2 | Successfully detached, an active vIRQ was abandoned.
  -L4_EPERM | Insufficient permissions; see precondition.

Precondition
  The invoked Irq capability must have the permission L4_CAP_FPAGE_S.

Definition at line 242 of file irq.h.

References l4_ipc_call(), L4_IPC_NEVER, l4_msgtag(), L4_NOTHROW, and L4_PROTO_IRQ_SENDER.

Referenced by L4::Irq::detach(), and l4_irq_detach().

Here is the call graph for this function:
Here is the caller graph for this function:

## l4_irq_receive()

l4_msgtag_t l4_irq_receive | ( | l4_cap_idx_t | irq,
|  | l4_timeout_t | to )

inline

Unmask and wait for specified IRQ.

Parameters

  irq | The IRQ object that shall be unmasked.
  to | Timeout.

Returns
  Syscall return tag

Definition at line 313 of file irq.h.

References l4_irq_receive_u(), L4_NOTHROW, and l4_utcb().

Referenced by L4Re::Util::Event_buffer_consumer_t< Default_event_payload >::process().

Here is the call graph for this function:
Here is the caller graph for this function:

## l4_irq_receive_u()

l4_msgtag_t l4_irq_receive_u | ( | l4_cap_idx_t | irq,
|  | l4_timeout_t | timeout,
|  | l4_utcb_t * | utcb )

inline

Unmask and wait for this IRQ.

Parameters

  irq | The IRQ object that shall be unmasked.
  timeout | Timeout.
  utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.

Returns
  Syscall return tag

Note
  If this is the function normally used for your IRQs consider using L4::Semaphore instead of L4::Irq.

Definition at line 270 of file irq.h.

References l4_ipc_call(), l4_msgtag(), L4_NOTHROW, and L4_PROTO_IRQ.

Referenced by l4_irq_receive(), and L4::Irq::receive().

Here is the call graph for this function:
Here is the caller graph for this function:

## l4_irq_trigger()

l4_msgtag_t l4_irq_trigger | ( | l4_cap_idx_t | irq | ) |

inline

Trigger an IRQ.

Parameters

  irq | The IRQ object that shall be triggered.

Returns
  Syscall return tag.

Note that this function is a send only operation, i.e. there is no return value except for a failed send operation. Especially l4_error() will return an error value from the message tag which still contains the IRQ protocol used for the send operation.

Use l4_ipc_error() to check for (send) errors.

Definition at line 307 of file irq.h.

References l4_irq_trigger_u(), L4_NOTHROW, and l4_utcb().

Referenced by l4_semaphore_up().

Here is the call graph for this function:
Here is the caller graph for this function:

## l4_irq_trigger_u()

l4_msgtag_t l4_irq_trigger_u | ( | l4_cap_idx_t | irq,
|  | l4_utcb_t * | utcb )

inline

Trigger the object.

Parameters

  irq | The IRQ object that shall be triggered.
  utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.

Returns
  Syscall return tag for a send-only operation, this means there is no return value except L4_MSGTAG_ERROR indicating success or failure of the send operation. Use l4_ipc_error() to check for errors and do not use l4_error().

Definition at line 263 of file irq.h.

References L4_IPC_BOTH_TIMEOUT_0, l4_ipc_send(), l4_msgtag(), L4_NOTHROW, and L4_PROTO_IRQ.

Referenced by l4_irq_trigger(), and L4::Triggerable::trigger().

Here is the call graph for this function:
Here is the caller graph for this function:

## l4_irq_unmask()

l4_msgtag_t l4_irq_unmask | ( | l4_cap_idx_t | irq | ) |

inline

Unmask IRQ.

Parameters

  irq | The IRQ object that shall be unmasked.

Returns
  Syscall return tag

Note
  l4_irq_wait() and l4_irq_receive() are doing the unmask themselves.

Definition at line 326 of file irq.h.

References l4_irq_unmask_u(), L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## l4_irq_unmask_u()

l4_msgtag_t l4_irq_unmask_u | ( | l4_cap_idx_t | irq,
|  | l4_utcb_t * | utcb )

inline

Unmask this IRQ.

Parameters

  irq | The IRQ object that shall be unmasked.
  utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.

Returns
  Syscall return tag for a send-only operation, this means there is no return value except L4_MSGTAG_ERROR indicating success or failure of the send operation. Use l4_ipc_error() to check for errors and do not use l4_error().

Irq::wait() and Irq::receive() operations already include an unmask(), do not use an extra unmask() in these cases.

Definition at line 286 of file irq.h.

References L4_IPC_NEVER, l4_ipc_send(), l4_msgtag(), L4_NOTHROW, and L4_PROTO_IRQ.

Referenced by l4_irq_unmask().

Here is the call graph for this function:
Here is the caller graph for this function:

## l4_irq_wait()

l4_msgtag_t l4_irq_wait | ( | l4_cap_idx_t | irq,
|  | l4_umword_t * | label,
|  | l4_timeout_t | to )

inline

Unmask IRQ and wait for any message.

Parameters

  irq | The IRQ object that shall be unmasked.
  label | Receive label.
  to | Timeout.

Returns
  Syscall return tag

Examples
  examples/sys/isr/main.c.

Definition at line 319 of file irq.h.

References l4_irq_wait_u(), L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## l4_irq_wait_u()

l4_msgtag_t l4_irq_wait_u | ( | l4_cap_idx_t | irq,
|  | l4_umword_t * | label,
|  | l4_timeout_t | timeout,
|  | l4_utcb_t * | utcb )

inline

Unmask IRQ and (open) wait for any message.

Parameters

  irq | The IRQ object that shall be unmasked.
  label | The protected label shall be received here.
  timeout | Timeout.
  utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.

Returns
  Syscall return tag

Definition at line 277 of file irq.h.

References l4_ipc_send_and_wait(), l4_msgtag(), L4_NOTHROW, and L4_PROTO_IRQ.

Referenced by l4_irq_wait().

Here is the call graph for this function:
Here is the caller graph for this function: