L4Re - L4 Runtime Environment
Interrupt controller

The C Icu 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. More...
 

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. More...
 
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. More...
 
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. More...
 
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. More...
 
l4_msgtag_t l4_icu_set_mode (l4_cap_idx_t icu, unsigned irqnum, l4_umword_t mode) L4_NOTHROW
 Set interrupt mode. More...
 
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. More...
 
l4_msgtag_t l4_icu_info (l4_cap_idx_t icu, l4_icu_info_t *info) L4_NOTHROW
 Get information about the capabilites of the ICU. More...
 
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 capabilities of the ICU. More...
 
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. More...
 
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. More...
 
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. More...
 
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
 Acknowledge the given interrupt line. More...
 
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. More...
 
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. More...
 

Detailed Description

The C Icu interface.

To setup an IRQ line the following steps are required:

  1. l4_icu_set_mode() (optional if IRQ has a default mode)
  2. l4_irq_attach() to attach the IRQ capability to a thread
  3. l4_icu_bind()
  4. l4_icu_unmask() to receive the first IRQ
Include File
#include <l4/sys/icu.h>

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

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 50 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
icuICU object to bind irq to.
irqnumIRQ line at the ICU.
irqIRQ 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().
Examples:
examples/sys/isr/main.c.

Definition at line 473 of file icu.h.

References l4_icu_bind_u(), 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
icuThe ICU objecte to bind irq to.
irqnumIRQ line at the ICU.
irqIRQ object for the given IRQ line to bind to this ICU.
utcbUTCB to be used for this operation, usually the UTCB of the calling thread.
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.

Definition at line 373 of file icu.h.

Referenced by l4_icu_bind().

+ 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 capabilites of the ICU.

Parameters
icuThe ICU object from which information shall be retrieved.
[out]infoPointer to an info structure to be filled with information. The memory for this structure has to be allocated by the caller.
Returns
Syscall return tag

Definition at line 481 of file icu.h.

References l4_icu_info_u(), 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 capabilities of the ICU.

Parameters
icuThe ICU object from which MSI information shall be retrieved.
[out]infoInfo structure to be filled with information.
utcbUTCB to be used for this operation, usually the UTCB of the calling thread.
Returns
Syscall return tag

Definition at line 397 of file icu.h.

Referenced by l4_icu_info().

+ 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
icuThe ICU object where the IRQ line 'irqnum' shall be masked.
irqnumIRQ line at the ICU.
labelIf non-NULL the function also waits for the next message.
toTimeout for message to ICU, if unsure use L4_IPC_NEVER.
Returns
Syscall return tag

Definition at line 495 of file icu.h.

◆ 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
icuThe ICU object where the IRQ line 'irqnum' shall be masked.
irqnumIRQ line at the ICU.
labelIf 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.
toThe timeout-pair (send and receive) that shall be used for this operation. The receive timeout is used with a non-NULL label only.
utcbUTCB to be used for this operation, usually the UTCB of the calling thread.
Returns
Syscall return tag

Definition at line 460 of file icu.h.

◆ 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
icuThe ICU object from which MSI information shall be retrieved.
irqnumIRQ line at the ICU.
sourcePlatform dependent requester ID for MSIs. On IA32 we use a 20bit source filter value as described in the Intel IRQ remapping specification.
[out]msi_infoA l4_icu_msi_info_t structure receiving the address and the data value to trigger this MSI.
Returns
Syscall return tag

Definition at line 485 of file icu.h.

References l4_icu_msi_info_u(), 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
utcbUTCB to be used for this operation, usually the UTCB of the calling thread.
icuThe ICU object from which MSI information shall be retrieved.
irqnumIRQ line at the ICU.
sourcePlatform dependent requester ID for MSIs. On IA32 we use a 20bit source filter value as described in the Intel IRQ remapping specification.
[out]msi_infoA l4_icu_msi_info_t structure receiving the address and the data value to trigger this MSI.
Returns
Syscall return tag

Definition at line 411 of file icu.h.

Referenced by l4_icu_msi_info().

+ 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
icuThe ICU object.
irqnumIRQ line at the ICU.
modeMode, see L4_irq_mode.
Returns
Syscall return tag

Definition at line 500 of file icu.h.

References l4_icu_set_mode_u(), 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
icuThe ICU object.
irqnumIRQ line at the ICU.
modeMode, see L4_irq_mode.
utcbUTCB to be used for this operation, usually the UTCB of the calling thread.
Returns
Syscall return tag

Definition at line 434 of file icu.h.

Referenced by l4_icu_set_mode().

+ 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
icuThe ICU object from where the binding shall be removed.
irqnumIRQ line at the ICU.
irqIRQ object to remove from the ICU.
Returns
Syscall return tag

Definition at line 477 of file icu.h.

References l4_icu_unbind_u(), 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
icuThe ICU object from where the binding shall be removed.
irqnumIRQ line at the ICU.
irqIRQ object to remove from the ICU.
utcbUTCB to be used for this operation, usually the UTCB of the calling thread.
Returns
Syscall return tag

Definition at line 385 of file icu.h.

Referenced by l4_icu_unbind().

+ 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
icuThe ICU object where the IRQ line shall be unmasked.
irqnumIRQ line at the ICU.
labelIf non-NULL the function also waits for the next message.
toTimeout for message to ICU, if unsure use L4_IPC_NEVER.
Returns
Syscall return tag, the error values therein are undefined because l4_icu_unmask() is a sender-only IPC.

Definition at line 490 of file icu.h.

◆ 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

Acknowledge the given interrupt line.

Parameters
icuThe ICU object where the IRQ line shall be unmasked.
irqnumThe interrupt line that shall be acknowledged.
[out]labelIf NULL this is a send-only unmask, if not NULL then this operation enters an open wait and the protected label shall be received here.
toThe timeout-pair (send and receive) that shall be used for this operation. The receive timeout is used with a non-NULL label only.
utcbUTCB to be used for this operation, usually the UTCB of the calling thread.
Returns
Syscall return tag.
Note
If label is NULL this function is a send-only operation and there is no return value except for a failed send operation. In this case use l4_ipc_error() to check for errors, do not use l4_error(), because l4_error() will always return an error.

Definition at line 465 of file icu.h.