vCPU API

vCPU API. More...

Collaboration diagram for vCPU API:

Data Structures
struct	l4_vcpu_state_t
	State of a vCPU. More...
struct	l4_vcpu_regs_t
	vCPU registers. More...
struct	l4_vcpu_ipc_regs_t
	vCPU message registers. More...

Typedefs
typedef struct l4_vcpu_state_t	l4_vcpu_state_t
	State of a vCPU.
typedef struct l4_vcpu_regs_t	l4_vcpu_regs_t
	vCPU registers.
typedef struct l4_vcpu_ipc_regs_t	l4_vcpu_ipc_regs_t
	vCPU message registers.
typedef struct l4_vcpu_regs_t	l4_vcpu_regs_t
	vCPU registers.
typedef struct l4_vcpu_ipc_regs_t	l4_vcpu_ipc_regs_t
	vCPU message registers.
typedef struct l4_vcpu_regs_t	l4_vcpu_regs_t
	vCPU registers.
typedef struct l4_vcpu_ipc_regs_t	l4_vcpu_ipc_regs_t
	vCPU message registers.

Enumerations
enum	L4_vcpu_state_flags {   L4_VCPU_F_IRQ = 0x01 , L4_VCPU_F_PAGE_FAULTS = 0x02 , L4_VCPU_F_EXCEPTIONS = 0x04 , L4_VCPU_F_USER_MODE = 0x20 ,   L4_VCPU_F_FPU_ENABLED = 0x80 }
	State flags of a vCPU. More...
enum	L4_vcpu_sticky_flags { L4_VCPU_SF_IRQ_PENDING = 0x01 }
	Sticky flags of a vCPU. More...
enum	L4_vcpu_state_offset { L4_VCPU_OFFSET_EXT_STATE = 0x180 , L4_VCPU_OFFSET_EXT_INFOS = 0x100 }
	Offsets for vCPU state layouts. More...
enum	L4_vcpu_state_offset { L4_VCPU_OFFSET_EXT_STATE = 0x400 , L4_VCPU_OFFSET_EXT_INFOS = 0x200 }
	Offsets for vCPU state layouts. More...
enum	L4_vcpu_state_offset { L4_VCPU_OFFSET_EXT_STATE = 0x400 , L4_VCPU_OFFSET_EXT_INFOS = 0x200 }
	Offsets for vCPU state layouts. More...

Detailed Description

vCPU API.

The vCPU API in L4Re implements virtual processors (vCPUs) on top of L4::Thread. This API can be used for user level threading, operating system rehosting (see L4Linux) and virtualization.

You switch a thread into vCPU operation with L4::Thread::vcpu_control.

In vCPU mode, incoming IPC can be redirected to a handler function. If an IPC is sent to the vCPU, the thread's normal execution is interrupted and the handler called. Which kind of IPC is redirected is specified by the L4_vcpu_state_flags set in the l4_vcpu_state_t::state field of vcpu_state. All events enabled in the vcpu_state field are redirected to the handler. The handler is set via l4_vcpu_state_t::entry_ip and l4_vcpu_state_t::entry_sp. IPC redirection works independent of "kernel" and "user" mode, but see l4_vcpu_state_t::entry_sp. When the entry handler is called, the UTCB contains the result of the IPC and content normally found in CPU register is in l4_vcpu_state_t::i.

Furthermore, the thread can execute in the context of different tasks, called the "kernel" and the "user" mode. The kernel task is the one to which the thread was originally bound via L4::Thread::control(). Execution starts in the kernel task and it is always switched to when the asynchronous IPC handler is invoked. When returning from the handler via l4_thread_vcpu_resume_start() and l4_thread_vcpu_resume_commit(), a different user task can be specified by setting l4_vcpu_state_t::user_task and enabling the L4_VCPU_F_USER_MODE flag in l4_vcpu_state_t::state. Note that the kernel may cache the user task internally, see l4_thread_vcpu_resume_commit().

If the L4_VCPU_F_USER_MODE flag is enabled, the following flags will be automatically enabled in l4_vcpu_state_t::state on L4::Thread::vcpu_resume_commit():

• L4_VCPU_F_IRQ
• L4_VCPU_F_PAGE_FAULTS
• L4_VCPU_F_EXCEPTIONS

When the kernel mode is entered, the following flags will be automatically disabled in l4_vcpu_state_t::state:

• L4_VCPU_F_IRQ
• L4_VCPU_F_PAGE_FAULTS
• L4_VCPU_F_USER_MODE

Extended vCPU operation is used for hardware CPU virtualization. It can be enabled with L4::Thread::vcpu_control_ext().

vCPU Support Library defines a convenience API for working with vCPUs.

See also

vCPU Support Library

Enumeration Type Documentation

L4_vcpu_state_flags

enum L4_vcpu_state_flags

State flags of a vCPU.

Enumerator
L4_VCPU_F_IRQ	Receiving of IRQs and IPC enabled. While this flag is not set, the corresponding vCPU thread will not receive any IPC and threads attempting to send an IPC to this thread will block (according to the selected send timeout). Note On L4::Thread::vcpu_resume_commit() this flag is automatically enabled in l4_vcpu_state_t::state if L4_VCPU_F_USER_MODE is enabled. When the kernel mode is entered, this flags is automatically disabled in l4_vcpu_state_t::state.
L4_VCPU_F_PAGE_FAULTS	Page faults enabled. If this flag is set, a page fault switches to kernel mode (potentially causing a VM exit) and calls the entry handler. If this flag is not set, a page fault generates a page fault IPC to the pager of the vCPU thread. Note IPC redirection for page faults controlled by this flag works independent of "kernel" and "user" mode. On L4::Thread::vcpu_resume_commit() this flag is automatically enabled in l4_vcpu_state_t::state if L4_VCPU_F_USER_MODE is enabled. When the kernel mode is entered, this flags is automatically disabled in l4_vcpu_state_t::state.
L4_VCPU_F_EXCEPTIONS	Exceptions enabled. If this flag is set, then, on the event of an exception, the vCPU switches to kernel mode (potentially causing a VM exit) and calls the entry handler. If this flag is not set, an exception generates an exception IPC to the exception handler of the vCPU thread. Note IPC redirection for exceptions controlled by this flag works independent of "kernel" and "user" mode. On L4::Thread::vcpu_resume_commit() this flag is automatically enabled in l4_vcpu_state_t::state if L4_VCPU_F_USER_MODE is enabled.
L4_VCPU_F_USER_MODE	User task will be used. If set, the vCPU switches to user mode on next L4::Thread::vcpu_resume_commit(). If clear, the vCPU stays in "kernel" mode. Note When the kernel mode is entered, this flags is automatically disabled in l4_vcpu_state_t::state.
L4_VCPU_F_FPU_ENABLED	FPU enabled. This flag is only relevant if L4_VCPU_F_USER_MODE is set. Setting this flag allows code in vCPU mode to use the FPU. IF this flag is not set, any FPU operation will trigger a corresponding exception (FPU fault).

Definition at line 112 of file vcpu.h.

L4_vcpu_state_offset [1/3]

enum L4_vcpu_state_offset

Offsets for vCPU state layouts.

Enumerator
L4_VCPU_OFFSET_EXT_STATE	Offset where extended state begins.
L4_VCPU_OFFSET_EXT_INFOS	Offset where extended infos begin.

Definition at line 45 of file __vcpu-arch.h.

L4_vcpu_state_offset [2/3]

enum L4_vcpu_state_offset

Offsets for vCPU state layouts.

Enumerator
L4_VCPU_OFFSET_EXT_STATE	Offset where extended state begins.
L4_VCPU_OFFSET_EXT_INFOS	Offset where extended infos begin.

Definition at line 46 of file __vcpu-arch.h.

L4_vcpu_state_offset [3/3]

enum L4_vcpu_state_offset

Offsets for vCPU state layouts.

Enumerator
L4_VCPU_OFFSET_EXT_STATE	Offset where extended state begins.
L4_VCPU_OFFSET_EXT_INFOS	Offset where extended infos begin.

Definition at line 45 of file __vcpu-arch.h.

L4_vcpu_sticky_flags

enum L4_vcpu_sticky_flags

Sticky flags of a vCPU.

Enumerator
L4_VCPU_SF_IRQ_PENDING	An event is pending: Either an IRQ or another thread attempts to send an IPC to this vCPU thread.

Definition at line 178 of file vcpu.h.