L4Re - L4 Runtime Environment

API related to the message tag data type. More...

+ Collaboration diagram for Message Tag:

Data Structures

struct  l4_msgtag_t
 Message tag data structure. More...
 

Typedefs

typedef struct l4_msgtag_t l4_msgtag_t
 Message tag data structure. More...
 

Enumerations

enum  L4_platform_ctl_proto { L4_PROTO_PLATFORM_CTL = 0 }
 Predefined protocol type for messages to platform-control objects. More...
 
enum  l4_msgtag_protocol {
  L4_PROTO_NONE = 0, L4_PROTO_ALLOW_SYSCALL = 1, L4_PROTO_PF_EXCEPTION = 1, L4_PROTO_IRQ = -1L,
  L4_PROTO_PAGE_FAULT = -2L, L4_PROTO_PREEMPTION = -3L, L4_PROTO_SYS_EXCEPTION = -4L, L4_PROTO_EXCEPTION = -5L,
  L4_PROTO_SIGMA0 = -6L, L4_PROTO_IO_PAGE_FAULT = -8L, L4_PROTO_KOBJECT = -10L, L4_PROTO_TASK = -11L,
  L4_PROTO_THREAD = -12L, L4_PROTO_LOG = -13L, L4_PROTO_SCHEDULER = -14L, L4_PROTO_FACTORY = -15L,
  L4_PROTO_VM = -16L, L4_PROTO_DMA_SPACE = -17L, L4_PROTO_IRQ_SENDER = -18L, L4_PROTO_IRQ_MUX = -19L,
  L4_PROTO_SEMAPHORE = -20L, L4_PROTO_META = -21L, L4_PROTO_IOMMU = -22L, L4_PROTO_DEBUGGER = -23L,
  L4_PROTO_SMCCC = -24L
}
 Message tag for IPC operations. More...
 
enum  l4_msgtag_flags {
  L4_MSGTAG_ERROR, L4_MSGTAG_TRANSFER_FPU, L4_MSGTAG_SCHEDULE, L4_MSGTAG_PROPAGATE,
  L4_MSGTAG_FLAGS
}
 Flags for message tags. More...
 

Functions

l4_msgtag_t l4_msgtag (long label, unsigned words, unsigned items, unsigned flags) L4_NOTHROW
 Create a message tag from the specified values. More...
 
long l4_msgtag_label (l4_msgtag_t t) L4_NOTHROW
 Get the protocol of tag. More...
 
unsigned l4_msgtag_words (l4_msgtag_t t) L4_NOTHROW
 Get the number of untyped words. More...
 
unsigned l4_msgtag_items (l4_msgtag_t t) L4_NOTHROW
 Get the number of typed items. More...
 
unsigned l4_msgtag_flags (l4_msgtag_t t) L4_NOTHROW
 Get the flags. More...
 
unsigned l4_msgtag_has_error (l4_msgtag_t t) L4_NOTHROW
 Test for error indicator flag. More...
 
unsigned l4_msgtag_is_page_fault (l4_msgtag_t t) L4_NOTHROW
 Test for page-fault protocol. More...
 
unsigned l4_msgtag_is_preemption (l4_msgtag_t t) L4_NOTHROW
 Test for preemption protocol. More...
 
unsigned l4_msgtag_is_sys_exception (l4_msgtag_t t) L4_NOTHROW
 Test for system-exception protocol. More...
 
unsigned l4_msgtag_is_exception (l4_msgtag_t t) L4_NOTHROW
 Test for exception protocol. More...
 
unsigned l4_msgtag_is_sigma0 (l4_msgtag_t t) L4_NOTHROW
 Test for sigma0 protocol. More...
 
unsigned l4_msgtag_is_io_page_fault (l4_msgtag_t t) L4_NOTHROW
 Test for IO-page-fault protocol. More...
 

Detailed Description

API related to the message tag data type.

Include File
#include <l4/sys/types.h>

Typedef Documentation

◆ l4_msgtag_t

typedef struct l4_msgtag_t l4_msgtag_t

Message tag data structure.

Include File
#include <l4/sys/types.h>

Describes the details of an IPC operation, in particular which parts of the UTCB have to be transmitted, and also flags to enable real-time and FPU extensions.

The message tag also contains a user-defined label that could be used to specify a protocol ID. Some negative values are reserved for kernel protocols such as page faults and exceptions.

The type must be treated completely opaque.

Enumeration Type Documentation

◆ l4_msgtag_flags

Flags for message tags.

Enumerator
L4_MSGTAG_ERROR 

Error indicator flag.

L4_MSGTAG_TRANSFER_FPU 

Enable FPU transfer flag for IPC.

By enabling this flag when sending IPC, the sender indicates that the contents of the FPU shall be transfered to the receiving thread. However, the receiver has to indicate its willingness to receive FPU context in its buffer descriptor register (BDR).

L4_MSGTAG_SCHEDULE 

Enable schedule in IPC flag.

Usually IPC operations donate the remaining time slice of a thread to the called thread. Enabling this flag when sending IPC does a real scheduling decision. However, this flag decreases IPC performance.

L4_MSGTAG_PROPAGATE 

Enable IPC propagation.

This flag enables IPC propagation, which means an IPC reply-connection from the current caller will be propagated to the new IPC receiver. This makes it possible to propagate an IPC call to a third thread, which may then directly answer to the caller.

L4_MSGTAG_FLAGS 

Mask for all flags.

Definition at line 95 of file types.h.

◆ l4_msgtag_protocol

Message tag for IPC operations.

All predefined protocols used by the kernel.

Enumerator
L4_PROTO_NONE 

Default protocol tag to reply to kernel.

L4_PROTO_ALLOW_SYSCALL 

Allow an alien the system call.

L4_PROTO_PF_EXCEPTION 

Make an exception out of a page fault.

L4_PROTO_IRQ 

IRQ message.

L4_PROTO_PAGE_FAULT 

Page fault message.

L4_PROTO_PREEMPTION 

Preemption message.

L4_PROTO_SYS_EXCEPTION 

System exception.

L4_PROTO_EXCEPTION 

Exception.

L4_PROTO_SIGMA0 

Sigma0 protocol.

L4_PROTO_IO_PAGE_FAULT 

I/O page fault message.

L4_PROTO_KOBJECT 

Protocol for messages to a a generic kobject.

L4_PROTO_TASK 

Protocol for messages to a task object.

L4_PROTO_THREAD 

Protocol for messages to a thread object.

L4_PROTO_LOG 

Protocol for messages to a log object.

L4_PROTO_SCHEDULER 

Protocol for messages to a scheduler object.

L4_PROTO_FACTORY 

Protocol for messages to a factory object.

L4_PROTO_VM 

Protocol for messages to a virtual machine object.

L4_PROTO_DMA_SPACE 

Protocol for (creating) kernel DMA space objects.

L4_PROTO_IRQ_SENDER 

Protocol for IRQ senders (IRQ -> IPC)

L4_PROTO_IRQ_MUX 

Protocol for IRQ mux (IRQ -> n x IRQ)

L4_PROTO_SEMAPHORE 

Protocol for semaphore objects.

L4_PROTO_META 

Meta information protocol.

L4_PROTO_IOMMU 

Protocol ID for IO-MMUs.

L4_PROTO_DEBUGGER 

Protocol ID for the ddebugger.

L4_PROTO_SMCCC 

Protocol ID for ARM SMCCC calls.

Definition at line 49 of file types.h.

◆ L4_platform_ctl_proto

Predefined protocol type for messages to platform-control objects.

Enumerator
L4_PROTO_PLATFORM_CTL 

Protocol messages to a platform control object.

See L4_platform_ctl_ops for allowed operations.

Definition at line 147 of file platform_control.h.

Function Documentation

◆ l4_msgtag()

l4_msgtag_t l4_msgtag ( long  label,
unsigned  words,
unsigned  items,
unsigned  flags 
)
inline

Create a message tag from the specified values.

Message tag functions.

Parameters
labelThe user-defined label
wordsThe number of untyped words within the UTCB
itemsThe number of typed items (e.g., flex pages) within the UTCB
flagsThe IPC flags for realtime and FPU extensions
Returns
Message tag
Examples:
examples/sys/aliens/main.c, examples/sys/ipc/ipc_example.c, examples/sys/singlestep/main.c, examples/sys/start-with-exc/main.c, and examples/sys/utcb-ipc/main.c.

Definition at line 408 of file types.h.

Referenced by l4_msgtag_t::has_error(), l4_irq_trigger_u(), and l4util_ioport_map().

+ Here is the caller graph for this function:

◆ l4_msgtag_flags()

unsigned l4_msgtag_flags ( l4_msgtag_t  t)
inline

Get the flags.

The flag are defined by l4_msgtag_flags.

Parameters
tThe tag
Returns
Flags

Definition at line 431 of file types.h.

References l4_msgtag_t::raw.

◆ l4_msgtag_has_error()

unsigned l4_msgtag_has_error ( l4_msgtag_t  t)
inline

Test for error indicator flag.

Parameters
tThe tag
Returns
>0 for yes, 0 for no

Return whether the kernel operation caused a communication error, e.g. with IPC. if true: utcb->error is valid, otherwise utcb->error is not valid

Examples:
examples/sys/aliens/main.c, examples/sys/singlestep/main.c, and examples/sys/utcb-ipc/main.c.

Definition at line 436 of file types.h.

References L4_MSGTAG_ERROR, and l4_msgtag_t::raw.

Referenced by l4_msgtag_t::has_error(), l4_ipc_error(), l4_vcon_write_u(), and l4vcpu_irq_disable_save().

+ Here is the caller graph for this function:

◆ l4_msgtag_is_exception()

unsigned l4_msgtag_is_exception ( l4_msgtag_t  t)
inline

Test for exception protocol.

Parameters
tThe tag
Returns
Boolean value
Examples:
examples/sys/aliens/main.c, examples/sys/singlestep/main.c, and examples/sys/start-with-exc/main.c.

Definition at line 450 of file types.h.

References l4_msgtag_label(), and L4_PROTO_EXCEPTION.

Referenced by l4_msgtag_t::has_error().

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

◆ l4_msgtag_is_io_page_fault()

unsigned l4_msgtag_is_io_page_fault ( l4_msgtag_t  t)
inline

Test for IO-page-fault protocol.

Parameters
tThe tag
Returns
Boolean value

Definition at line 456 of file types.h.

References l4_msgtag_label(), and L4_PROTO_IO_PAGE_FAULT.

Referenced by l4_msgtag_t::has_error().

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

◆ l4_msgtag_is_page_fault()

unsigned l4_msgtag_is_page_fault ( l4_msgtag_t  t)
inline

Test for page-fault protocol.

Parameters
tThe tag
Returns
Boolean value

Definition at line 441 of file types.h.

References l4_msgtag_label(), and L4_PROTO_PAGE_FAULT.

Referenced by l4_msgtag_t::has_error().

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

◆ l4_msgtag_is_preemption()

unsigned l4_msgtag_is_preemption ( l4_msgtag_t  t)
inline

Test for preemption protocol.

Parameters
tThe tag
Returns
Boolean value

Definition at line 444 of file types.h.

References l4_msgtag_label(), and L4_PROTO_PREEMPTION.

Referenced by l4_msgtag_t::has_error().

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

◆ l4_msgtag_is_sigma0()

unsigned l4_msgtag_is_sigma0 ( l4_msgtag_t  t)
inline

Test for sigma0 protocol.

Parameters
tThe tag
Returns
Boolean value

Definition at line 453 of file types.h.

References l4_msgtag_label(), and L4_PROTO_SIGMA0.

Referenced by l4_msgtag_t::has_error().

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

◆ l4_msgtag_is_sys_exception()

unsigned l4_msgtag_is_sys_exception ( l4_msgtag_t  t)
inline

Test for system-exception protocol.

Parameters
tThe tag
Returns
Boolean value

Definition at line 447 of file types.h.

References l4_msgtag_label(), and L4_PROTO_SYS_EXCEPTION.

Referenced by l4_msgtag_t::has_error().

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

◆ l4_msgtag_items()

unsigned l4_msgtag_items ( l4_msgtag_t  t)
inline

Get the number of typed items.

Parameters
tThe tag
Returns
Number of items.

Definition at line 427 of file types.h.

References l4_msgtag_t::raw.

Referenced by l4_msgtag_t::has_error(), and l4util_ioport_map().

+ Here is the caller graph for this function:

◆ l4_msgtag_label()

long l4_msgtag_label ( l4_msgtag_t  t)
inline

Get the protocol of tag.

Parameters
tThe tag
Returns
Label
Examples:
examples/sys/singlestep/main.c, and examples/sys/start-with-exc/main.c.

Definition at line 419 of file types.h.

References l4_msgtag_t::raw.

Referenced by l4_msgtag_t::has_error(), l4_msgtag_is_exception(), l4_msgtag_is_io_page_fault(), l4_msgtag_is_page_fault(), l4_msgtag_is_preemption(), l4_msgtag_is_sigma0(), and l4_msgtag_is_sys_exception().

+ Here is the caller graph for this function:

◆ l4_msgtag_words()

unsigned l4_msgtag_words ( l4_msgtag_t  t)
inline

Get the number of untyped words.

Parameters
tThe tag
Returns
Number of words
Examples:
examples/sys/utcb-ipc/main.c.

Definition at line 423 of file types.h.

References l4_msgtag_t::raw.

Referenced by l4_msgtag_t::has_error().

+ Here is the caller graph for this function: