L4Re Operating System Framework – Interface and Usage Documentation
Loading...
Searching...
No Matches

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 = 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():

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

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

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

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 189 of file vcpu.h.

◆ 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.