Message-item-related functionality. More...

Collaboration diagram for Message Items:

Data Structures
struct	l4_snd_fpage_t
	Send-flexpage types. More...

Enumerations
enum	L4_obj_fpage_ctl { L4_FPAGE_C_REF_CNT = 0x00 , L4_FPAGE_C_NO_REF_CNT = 0x10 , L4_FPAGE_C_OBJ_RIGHT1 = 0x20 , L4_FPAGE_C_OBJ_RIGHT2 = 0x40 , L4_FPAGE_C_OBJ_RIGHT3 = 0x80 , L4_FPAGE_C_OBJ_RIGHTS = 0xe0 , L4_FPAGE_C_IPCGATE_SVR = L4_FPAGE_C_OBJ_RIGHT1 }
	Attributes and additional permissions for object send items. More...

enum	l4_fpage_cacheability_opt_t { L4_FPAGE_CACHE_OPT = 0x1 , L4_FPAGE_CACHEABLE = 0x3 , L4_FPAGE_BUFFERABLE = 0x5 , L4_FPAGE_UNCACHEABLE = 0x1 }
	Cacheability options for memory send items. More...

enum	l4_msg_item_consts_t { L4_ITEM_MAP = 8 , L4_ITEM_CONT = 1 , L4_MAP_ITEM_GRANT = 2 , L4_MAP_ITEM_MAP = 0 , L4_RCV_ITEM_FORWARD_MAPPINGS = 1 , L4_RCV_ITEM_SINGLE_CAP = L4_ITEM_MAP \| 2 , L4_RCV_ITEM_LOCAL_ID = 4 }
	Constants for message items. More...

Functions
l4_umword_t	l4_map_control (l4_umword_t spot, unsigned char cache, unsigned grant) L4_NOTHROW
	Create the first word for a map item that is a send item for the memory space.

l4_umword_t	l4_map_obj_control (l4_umword_t spot, unsigned grant) L4_NOTHROW
	Create the first word for a map item that is a send item for the object space.

Detailed Description

Message-item-related functionality.

Message items are typed items that are used for transferring capabilities during IPC. There are three sub-types of typed message items with variations in the layout:

Typed message items set by the sender in its message registers (MRs) of the UTCB for specifying what shall be sent.
Typed message items set by the receiver in its buffer registers (BRs) of the UTCB for specifying which types of capabilities may be received at which addresses.
Typed message items set by the kernel in the receiver’s message registers (MRs) of the UTCB for providing information about the transfer to the receiver.

They are abbreviated by send item, receive item, and return item, respectively.

A typed message item in the message registers (case 1 and case 3) always consists of two words (even if it is a void item). The size of a typed message item in the buffer registers (case 2) is determined by its first word. The size is up to three words (see L4_RCV_ITEM_SINGLE_CAP and L4_RCV_ITEM_FORWARD_MAPPINGS). A void item in the buffer registers consists of a single word.

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

types.h
Common L4 ABI Data Types.

Enumeration Type Documentation

◆ l4_fpage_cacheability_opt_t

enum l4_fpage_cacheability_opt_t

Cacheability options for memory send items.

Enumerator
L4_FPAGE_CACHE_OPT	Enable the cacheability option in a memory send item. Without this flag, the options are copied from the sender.
L4_FPAGE_CACHEABLE	Cacheability option to enable caches for the mapping. Implies L4_FPAGE_CACHE_OPT.
L4_FPAGE_BUFFERABLE	Cacheability option to enable buffered writes for the mapping. Implies L4_FPAGE_CACHE_OPT.
L4_FPAGE_UNCACHEABLE	Cacheability option to disable caching for the mapping. Implies L4_FPAGE_CACHE_OPT.

Definition at line 284 of file __l4_fpage.h.

◆ l4_msg_item_consts_t

enum l4_msg_item_consts_t

Constants for message items.

Enumerator
L4_ITEM_MAP	Identify a message item as map item.
L4_ITEM_CONT	Denote that the following item shall be put into the same receive item as this one.
L4_MAP_ITEM_GRANT	Flag as grant instead of map operation. This means, the sender delegates access to the receiver and the kernel removes the rights from the sender (basically a move operation). The mapping in the receiver gets the new parent of any child mappings of the mapping of the sender. Rights revocation via send item/flexpage is not guaranteed to be applied to descendant mappings in case of grant. See Spaces and Mappings for more details on map/grant. Note The grant operation is not performed if the resulting rights of the receiver mapping would not contain the L4_CAP_FPAGE_R bit (for object capabilities) or none of the L4_FPAGE_RWX bits (memory and IO ports). In that case, the mapping is not created in the receiver space and not removed from the sender space. If the removal of the whole mapping from the sender is not possible because the size of the mapped frame at the sender exceeds the size defined by the send or receive flexpage, the grant operation is turned into a regular map operation and the mapping is not removed from the sender. This would happen if, for example, a smaller part of an L4 superpage mapping shall be granted.
L4_MAP_ITEM_MAP	Flag as usual map operation.
L4_RCV_ITEM_FORWARD_MAPPINGS	This flag specifies if received capabilities shall be mapped to a particular task instead of the invoking task. This flag may be used only if L4_RCV_ITEM_LOCAL_ID is unset. Setting this flag increases the size of the buffer item by one word. This word is used to specify a capability index for the task that shall receive the mappings.
L4_RCV_ITEM_SINGLE_CAP	Mark the receive buffer to be a small receive item that describes a buffer for a single object capability. A receive item needs to specify a receive window. The receive window determines which kind of capabilities (object, memory, I/O ports) may be received where in the respective space. If this flag is unset, the receive window is specified in the second word of the receive item via a flexpage. If this flag is set, the receive window consists of a single capability index in the object space and the capability index is specified in the most significant bits of the first word of the receive item (see L4_CAP_SHIFT).
L4_RCV_ITEM_LOCAL_ID	The receiver requests to receive a local ID instead of a mapping whenever possible. This flag may be used only if L4_RCV_ITEM_SINGLE_CAP is set and L4_RCV_ITEM_FORWARD_MAPPINGS is unset. When this flag is set, then, when sender and receiver are bound to the same task, then no mapping is done for this item and just the raw flexpage (l4_fpage_t) is transferred, otherwise, when the sender specified an IPC gate for transfer that is bound to a thread that is bound to the same task as the receiving thread, then no mapping is done for this item and just the bitwise OR (`\|`) of the label and the L4_CAP_FPAGE_W and L4_CAP_FPAGE_S permissions that would have been mapped is transferred, otherwise a regular mapping is done for this item.

Definition at line 216 of file consts.h.

◆ L4_obj_fpage_ctl

enum L4_obj_fpage_ctl

Attributes and additional permissions for object send items.

These rights need to be added to the snd_base when mapping and control internal behavior. The exact meaning depends on the type of capability (currently used only with IPC gates).

Enumerator
L4_FPAGE_C_REF_CNT	Mapping is reference-counted (default).
L4_FPAGE_C_NO_REF_CNT	Don't increase the reference counter.
L4_FPAGE_C_OBJ_RIGHT1	Object-type specific right.
L4_FPAGE_C_OBJ_RIGHT2	Object-type specific right.
L4_FPAGE_C_OBJ_RIGHT3	Object-type specific right.
L4_FPAGE_C_OBJ_RIGHTS	All Object-type specific right bits.
L4_FPAGE_C_IPCGATE_SVR	The receiver may invoke IPC-gate-specific functions on the capability, e.g. bind a thread to the gate and modify the label. Needed if the receiver implements the server side of an IPC gate.

Definition at line 262 of file __l4_fpage.h.

Function Documentation

◆ l4_map_control()

l4_umword_t l4_map_control	(	l4_umword_t	spot,
		unsigned char	cache,
		unsigned	grant
	)

inline

Create the first word for a map item that is a send item for the memory space.

Parameters

spot	Hot spot address, used to determine what is actually mapped when send and receive flexpage have differing sizes.
cache	Cacheability hints for memory flexpages. See Cacheability options.
grant	Indicates if it is a map or a grant item. Allowed values: L4_MAP_ITEM_MAP, L4_MAP_ITEM_GRANT.

Returns: The value to be used as first word in a send item for memory.

Definition at line 723 of file __l4_fpage.h.

References L4_FPAGE_CONTROL_MASK, and L4_ITEM_MAP.

Referenced by l4_map_obj_control().

Here is the caller graph for this function:

◆ l4_map_obj_control()

l4_umword_t l4_map_obj_control	(	l4_umword_t	spot,
		unsigned	grant
	)

inline

Create the first word for a map item that is a send item for the object space.

Parameters

spot	Hot spot address, used to determine what is actually mapped when send and receive flexpages have different size.
grant	Indicates if it is a map item or a grant item. Allowed values: L4_MAP_ITEM_MAP, L4_MAP_ITEM_GRANT.

Returns: The value to be used as first word in a send item for kernel objects or IO-ports.

Definition at line 730 of file __l4_fpage.h.

References l4_map_control().

Referenced by l4_icu_bind_u(), l4_icu_unbind_u(), l4_irq_bind_vcpu_u(), and L4::Cap_base::snd_base().

Here is the call graph for this function: