Loading...
Searching...
No Matches
Interrupt controller
Base API » Kernel Objects

The C Icu interface, see L4::Icu for the C++ interface. More...

Collaboration diagram for Interrupt controller:

## Data Structures

struct | l4_icu_info_t
| Info structure for an ICU. More...

## Typedefs

typedef struct l4_icu_info_t | l4_icu_info_t
| Info structure for an ICU.

## Enumerations

enum | L4_icu_flags { L4_ICU_FLAG_MSI }
| Flags for IRQ numbers used for the ICU. More...

## Functions

l4_msgtag_t | l4_icu_bind (l4_cap_idx_t icu, unsigned irqnum, l4_cap_idx_t irq) L4_NOTHROW
| Bind an interrupt line of an interrupt controller to an interrupt object.
l4_msgtag_t | l4_icu_bind_u (l4_cap_idx_t icu, unsigned irqnum, l4_cap_idx_t irq, l4_utcb_t *utcb) L4_NOTHROW
| Bind an interrupt line of an interrupt controller to an interrupt object.
l4_msgtag_t | l4_icu_unbind (l4_cap_idx_t icu, unsigned irqnum, l4_cap_idx_t irq) L4_NOTHROW
| Remove binding of an interrupt line from the interrupt controller object.
l4_msgtag_t | l4_icu_unbind_u (l4_cap_idx_t icu, unsigned irqnum, l4_cap_idx_t irq, l4_utcb_t *utcb) L4_NOTHROW
| Remove binding of an interrupt line from the interrupt controller object.
l4_msgtag_t | l4_icu_set_mode (l4_cap_idx_t icu, unsigned irqnum, l4_umword_t mode) L4_NOTHROW
| Set interrupt mode.
l4_msgtag_t | l4_icu_set_mode_u (l4_cap_idx_t icu, unsigned irqnum, l4_umword_t mode, l4_utcb_t *utcb) L4_NOTHROW
| Set interrupt mode.
l4_msgtag_t | l4_icu_info (l4_cap_idx_t icu, l4_icu_info_t *info) L4_NOTHROW
| Get information about the ICU features.
l4_msgtag_t | l4_icu_info_u (l4_cap_idx_t icu, l4_icu_info_t *info, l4_utcb_t *utcb) L4_NOTHROW
| Get information about the ICU features.
l4_msgtag_t | l4_icu_msi_info (l4_cap_idx_t icu, unsigned irqnum, l4_uint64_t source, l4_icu_msi_info_t *msi_info) L4_NOTHROW
| Get MSI info about IRQ.
l4_msgtag_t | l4_icu_msi_info_u (l4_cap_idx_t icu, unsigned irqnum, l4_uint64_t source, l4_icu_msi_info_t *msi_info, l4_utcb_t *utcb) L4_NOTHROW
| Get MSI info about IRQ.
l4_msgtag_t | l4_icu_unmask (l4_cap_idx_t icu, unsigned irqnum, l4_umword_t *label, l4_timeout_t to) L4_NOTHROW
| Unmask an IRQ line.
l4_msgtag_t | l4_icu_unmask_u (l4_cap_idx_t icu, unsigned irqnum, l4_umword_t *label, l4_timeout_t to, l4_utcb_t *utcb) L4_NOTHROW
| Unmask the given interrupt line.
l4_msgtag_t | l4_icu_mask (l4_cap_idx_t icu, unsigned irqnum, l4_umword_t *label, l4_timeout_t to) L4_NOTHROW
| Mask an IRQ line.
l4_msgtag_t | l4_icu_mask_u (l4_cap_idx_t icu, unsigned irqnum, l4_umword_t *label, l4_timeout_t to, l4_utcb_t *utcb) L4_NOTHROW
| Mask an IRQ line.

## Detailed Description

The C Icu interface, see L4::Icu for the C++ interface.

Note
  "ICU" is short for "interrupt control unit".

These functions define the interface for interrupt controllers, for binding IRQ objects to interrupt lines and other interrupt sources, as well as functions for masking and unmasking of interrupts.

To setup an IRQ line the following steps are required:

1. l4_icu_set_mode() (optional if IRQ has a default mode)
2. l4_rcv_ep_bind_thread() or l4_rcv_ep_bind_snd_destination() to attach the IRQ object to a thread object.
3. l4_icu_bind()
4. l4_icu_unmask() to receive the first IRQ

For certain interrupt sources only some of these steps are necessary and supported, see Scheduler and Virtual Console.

At most one IRQs object can be bound to a certain interrupt source and a certain IRQs object can be bound to at most one interrupt source.

Include File
  #include <l4/sys/icu.h>
  icu.h
  Interrupt controller.

## Typedef Documentation

## l4_icu_info_t

typedef struct l4_icu_info_t l4_icu_info_t

Info structure for an ICU.

This structure contains information about the features of an ICU.

See also
  l4_icu_info().

## Enumeration Type Documentation

## L4_icu_flags

enum L4_icu_flags

Flags for IRQ numbers used for the ICU.

Enumerator
L4_ICU_FLAG_MSI | Flag to denote that the IRQ is actually an MSI. This flag may be used for l4_icu_bind() and l4_icu_unbind() functions to denote that the IRQ number is meant to be an MSI.

Definition at line 53 of file icu.h.

## Function Documentation

## l4_icu_bind()

l4_msgtag_t l4_icu_bind | ( | l4_cap_idx_t | icu,
|  | unsigned | irqnum,
|  | l4_cap_idx_t | irq )

inline

Bind an interrupt line of an interrupt controller to an interrupt object.

Parameters

  icu | ICU object to bind irq to.
  irqnum | IRQ line at the ICU.
  irq | IRQ object to bind to this ICU.

Returns
  Syscall return tag. The caller should check the return value using l4_error() to check for errors and to identify the correct method for unmasking the interrupt. Return values < 0 indicate an error. A return value of 0 means a direct unmask via the IRQ object using l4_irq_unmask(). A return value of 1 means that the interrupt has to be unmasked via the ICU using l4_icu_unmask().

Return values

  -L4_EINVAL | irq is bound to an interrupt source.
  -L4_EPERM | Insufficient permissions; see precondition.

Precondition
  The capability irq must have the permission L4_CAP_FPAGE_W.

In case the irq is already bound to an interrupt source, it is unbound first. In case the irq is bound and the interrupt source is bound to a different IRQ object, only the unbinding happens. An IRQ object that is bound to an interrupt source will get unbound if the IRQ object is deleted.

Examples
  examples/sys/isr/main.c.

Definition at line 496 of file icu.h.

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

Here is the call graph for this function:

## l4_icu_bind_u()

l4_msgtag_t l4_icu_bind_u | ( | l4_cap_idx_t | icu,
|  | unsigned | irqnum,
|  | l4_cap_idx_t | irq,
|  | l4_utcb_t * | utcb )

inline

Bind an interrupt line of an interrupt controller to an interrupt object.

Parameters

  icu | The ICU object to bind irq to.
  irqnum | IRQ line at the ICU.
  irq | IRQ object for the given IRQ line to bind to this ICU.
  utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.

Returns
  Syscall return tag. The caller should check the return value using l4_error() to check for errors and to identify the correct method for unmasking the interrupt. Return values < 0 indicate an error. A return value of 0 means a direct unmask via the IRQ object using L4::Irq::unmask. A return value of 1 means that the interrupt has to be unmasked via the ICU using L4::Icu::unmask.

Return values

  -L4_EINVAL | irq is bound to an interrupt source.
  -L4_EPERM | Insufficient permissions; see precondition.

Precondition
  The capability irq must have the permission L4_CAP_FPAGE_W.

In case the irq is already bound to an interrupt source, it is unbound first. In case the irq is bound and the interrupt source is bound to a different L4::Irq object, only the unbinding happens. An L4::Irq object that is bound to an interrupt source will get unbound if the L4::Irq object is deleted.

Definition at line 396 of file icu.h.

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

Referenced by L4::Icu::bind(), and l4_icu_bind().

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

## l4_icu_info()

l4_msgtag_t l4_icu_info | ( | l4_cap_idx_t | icu,
|  | l4_icu_info_t * | info )

inline

Get information about the ICU features.

Parameters

  | icu | The ICU object from which information shall be retrieved.
  [out] | info | Info structure to be filled with information.

Returns
  Syscall return tag

Definition at line 504 of file icu.h.

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

Here is the call graph for this function:

## l4_icu_info_u()

l4_msgtag_t l4_icu_info_u | ( | l4_cap_idx_t | icu,
|  | l4_icu_info_t * | info,
|  | l4_utcb_t * | utcb )

inline

Get information about the ICU features.

Parameters

  | icu | The ICU object from which MSI information shall be retrieved.
  [out] | info | Info structure to be filled with information.
  | 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 420 of file icu.h.

References L4_ICU_OP_INFO, l4_ipc_call(), L4_IPC_NEVER, l4_msgtag(), L4_NOTHROW, L4_PROTO_IRQ, and l4_msg_regs_t::mr.

Referenced by L4::Icu::info(), and l4_icu_info().

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

## l4_icu_mask()

l4_msgtag_t l4_icu_mask | ( | l4_cap_idx_t | icu,
|  | unsigned | irqnum,
|  | l4_umword_t * | label,
|  | l4_timeout_t | to )

inline

Mask an IRQ line.

Parameters

  icu | The ICU object where the IRQ line shall be masked.
  irqnum | IRQ line at the ICU.
  label | If non-NULL, the function also performs an open wait IPC operation waiting for the next message, and the received label is returned here.
  to | IPC timeout, if unsure use L4_IPC_NEVER.

Returns
  Syscall return tag. If label is NULL, this function performs an IPC send-only operation and there is no return value except L4_MSGTAG_ERROR indicating success or failure of the send operation. In this case use l4_ipc_error() to check for errors and do not use l4_error().

Definition at line 518 of file icu.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## l4_icu_mask_u()

l4_msgtag_t l4_icu_mask_u | ( | l4_cap_idx_t | icu,
|  | unsigned | irqnum,
|  | l4_umword_t * | label,
|  | l4_timeout_t | to,
|  | l4_utcb_t * | utcb )

inline

Mask an IRQ line.

Parameters

  icu | The ICU object where the IRQ line shall be masked.
  irqnum | IRQ line at the ICU.
  label | If NULL, this function is a send-only message to the ICU. If not NULL, this function will enter an open wait after sending the mask message and the received label is returned here.
  to | The timeout-pair (send and receive) that shall be used for this operation. The receive timeout is used with a non-NULL label only.
  utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.

Returns
  Syscall return tag. If label is NULL, this function performs an IPC send-only operation and there is no return value except L4_MSGTAG_ERROR indicating success or failure of the send operation. In this case use l4_ipc_error() to check for errors and do not use l4_error().

Definition at line 483 of file icu.h.

References L4_NOTHROW.

Referenced by L4::Icu::mask().

Here is the caller graph for this function:

## l4_icu_msi_info()

l4_msgtag_t l4_icu_msi_info | ( | l4_cap_idx_t | icu,
|  | unsigned | irqnum,
|  | l4_uint64_t | source,
|  | l4_icu_msi_info_t * | msi_info )

inline

Get MSI info about IRQ.

Parameters

  | icu | The ICU object from which MSI information shall be retrieved.
  | irqnum | IRQ line at the ICU.
  | source | Platform dependent requester ID for MSIs. On IA32 we use a 20bit source filter value as described in the Intel IRQ remapping specification.
  [out] | msi_info | A l4_icu_msi_info_t structure receiving the address and the data value to trigger this MSI.

Returns
  Syscall return tag

Definition at line 508 of file icu.h.

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

Here is the call graph for this function:

## l4_icu_msi_info_u()

l4_msgtag_t l4_icu_msi_info_u | ( | l4_cap_idx_t | icu,
|  | unsigned | irqnum,
|  | l4_uint64_t | source,
|  | l4_icu_msi_info_t * | msi_info,
|  | l4_utcb_t * | utcb )

inline

Get MSI info about IRQ.

Parameters

  | utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.
  | icu | The ICU object from which MSI information shall be retrieved.
  | irqnum | IRQ line at the ICU.
  | source | Platform dependent requester ID for MSIs. On IA32 we use a 20bit source filter value as described in the Intel IRQ remapping specification.
  [out] | msi_info | A l4_icu_msi_info_t structure receiving the address and the data value to trigger this MSI.

Returns
  Syscall return tag

Definition at line 434 of file icu.h.

References L4_ICU_OP_MSI_INFO, l4_ipc_call(), L4_IPC_NEVER, l4_msgtag(), l4_msgtag_has_error(), l4_msgtag_words(), L4_NOTHROW, L4_PROTO_IRQ, L4_UNLIKELY, l4_utcb_mr64_idx(), l4_msg_regs_t::mr, and l4_msg_regs_t::mr64.

Referenced by l4_icu_msi_info().

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

## l4_icu_set_mode()

l4_msgtag_t l4_icu_set_mode | ( | l4_cap_idx_t | icu,
|  | unsigned | irqnum,
|  | l4_umword_t | mode )

inline

Set interrupt mode.

Parameters

  icu | The ICU object.
  irqnum | IRQ line at the ICU.
  mode | Mode, see L4_irq_mode.

Returns
  Syscall return tag

Definition at line 523 of file icu.h.

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

Here is the call graph for this function:

## l4_icu_set_mode_u()

l4_msgtag_t l4_icu_set_mode_u | ( | l4_cap_idx_t | icu,
|  | unsigned | irqnum,
|  | l4_umword_t | mode,
|  | l4_utcb_t * | utcb )

inline

Set interrupt mode.

Parameters

  icu | The ICU object.
  irqnum | IRQ line at the ICU.
  mode | Mode, see L4_irq_mode.
  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 457 of file icu.h.

References L4_ICU_OP_SET_MODE, l4_ipc_call(), L4_IPC_NEVER, l4_msgtag(), L4_NOTHROW, L4_PROTO_IRQ, and l4_msg_regs_t::mr.

Referenced by l4_icu_set_mode(), and L4::Icu::set_mode().

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

## l4_icu_unbind()

l4_msgtag_t l4_icu_unbind | ( | l4_cap_idx_t | icu,
|  | unsigned | irqnum,
|  | l4_cap_idx_t | irq )

inline

Remove binding of an interrupt line from the interrupt controller object.

Parameters

  icu | The ICU object from where the binding shall be removed.
  irqnum | IRQ line at the ICU.
  irq | IRQ object to remove from the ICU.

Returns
  Syscall return tag

Definition at line 500 of file icu.h.

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

Here is the call graph for this function:

## l4_icu_unbind_u()

l4_msgtag_t l4_icu_unbind_u | ( | l4_cap_idx_t | icu,
|  | unsigned | irqnum,
|  | l4_cap_idx_t | irq,
|  | l4_utcb_t * | utcb )

inline

Remove binding of an interrupt line from the interrupt controller object.

Parameters

  icu | The ICU object from where the binding shall be removed.
  irqnum | IRQ line at the ICU.
  irq | IRQ object to remove from the ICU.
  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 408 of file icu.h.

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

Referenced by l4_icu_unbind(), and L4::Icu::unbind().

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

## l4_icu_unmask()

l4_msgtag_t l4_icu_unmask | ( | l4_cap_idx_t | icu,
|  | unsigned | irqnum,
|  | l4_umword_t * | label,
|  | l4_timeout_t | to )

inline

Unmask an IRQ line.

Parameters

  icu | The ICU object where the IRQ line shall be unmasked.
  irqnum | IRQ line at the ICU.
  label | If non-NULL, the function also performs an open wait IPC operation waiting for the next message, and the received label is returned here.
  to | IPC timeout, if unsure use L4_IPC_NEVER.

Returns
  Syscall return tag. If label is NULL, this function performs an IPC send-only operation and there is no return value except L4_MSGTAG_ERROR indicating success or failure of the send operation. In this case use l4_ipc_error() to check for errors and do not use l4_error().

Definition at line 513 of file icu.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## l4_icu_unmask_u()

l4_msgtag_t l4_icu_unmask_u | ( | l4_cap_idx_t | icu,
|  | unsigned | irqnum,
|  | l4_umword_t * | label,
|  | l4_timeout_t | to,
|  | l4_utcb_t * | utcb )

inline

Unmask the given interrupt line.

Parameters

  icu | The ICU object where the IRQ line shall be unmasked. When the object is an IRQ, the given interrupt line is ignored and instead the line which the IRQ is bound to (if any) is unmasked.

Its counterpart for explicitly masking an interrupt line is L4::Icu::mask().

Parameters

  | irqnum | The interrupt line that shall be unmasked. Ignored if the object is an IRQ.
  [out] | label | If NULL, this is a send-only unmask. If not NULL, this operation enters an open wait and the protected label shall be received here.
  | to | The timeout-pair (send and receive) that shall be used for this operation. The receive timeout is used with a non-NULL label only.
  | utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.

Returns
  Syscall return tag. If label is NULL, this function performs an IPC send-only operation and there is no return value except L4_MSGTAG_ERROR indicating success or failure of the send operation. In this case use l4_ipc_error() to check for errors and do not use l4_error().

Definition at line 488 of file icu.h.

References L4_NOTHROW.