Loading...
Searching...
No Matches
vCPU API
Base API » Kernel Objects » Thread

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 l4_exc_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 = 0x280 , 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...
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 101 of file vcpu.h.

## L4_vcpu_state_offset [1/4]

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 34 of file __vcpu-arch.h.

## L4_vcpu_state_offset [2/4]

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 35 of file __vcpu-arch.h.

## L4_vcpu_state_offset [3/4]

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 36 of file __vcpu-arch.h.

## L4_vcpu_state_offset [4/4]

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