1 /*
2 * (c) 2009 Adam Lackorzynski <adam@os.inf.tu-dresden.de>,
3 * Alexander Warg <warg@os.inf.tu-dresden.de>
4 * economic rights: Technische Universität Dresden (Germany)
5 *
6 * This file is part of TUD:OS and distributed under the terms of the
7 * GNU General Public License 2.
8 * Please see the COPYING-GPL-2 file for details.
9 *
10 * As a special exception, you may use this file as part of a free software
11 * library without restriction. Specifically, if other files instantiate
12 * templates or use macros or inline functions from this file, or you compile
13 * this file and link it with other files to produce an executable, this
14 * file does not by itself cause the resulting executable to be covered by
15 * the GNU General Public License. This exception does not however
16 * invalidate any other reasons why the executable file might be covered by
17 * the GNU General Public License.
18 */
19 #pragma once
20
21 #include <l4/sys/types.h>
22 #include <l4/sys/__vcpu-arch.h>
23
24 /**
25 * \defgroup l4_vcpu_api vCPU API
26 * \ingroup l4_thread_api
27 * vCPU API
28 *
29 * The vCPU API in L4Re implements virtual processors (vCPUs) on top of
30 * L4::Thread. This API can be used for user level threading, operating system
31 * rehosting (see L4Linux) and virtualization.
32 *
33 * You switch a thread into `vCPU` operation with L4::Thread::vcpu_control.
34 *
35 * In vCPU mode, incoming IPC can be redirected to a handler function. If an
36 * IPC is sent to the vCPU, the thread's normal execution is interrupted and the
37 * handler called. Which kind of IPC is redirected is specified by the
38 * #L4_vcpu_state_flags set in the l4_vcpu_state_t::state field of `vcpu_state`.
39 * All events enabled in the `vcpu_state` field are redirected to the handler.
40 * The handler is set via l4_vcpu_state_t::entry_ip and
41 * l4_vcpu_state_t::entry_sp.
42 *
43 * Furthermore, the thread can execute in the context of different tasks,
44 * called the "kernel" and the "user" mode. The kernel task is the one to
45 * which the thread was originally bound via L4::Thread::control(). Execution
46 * starts in the kernel task and it is always switched to when the
47 * asynchronous IPC handler is invoked. When returning from the handler via
48 * vcpu_resume_start() and vcpu_resume_commit(), a different user task can
49 * be specified by setting l4_vcpu_state_t::user_task and enabling the
50 * #L4_VCPU_F_USER_MODE flag in l4_vcpu_state_t::state.
51 *
52 * Extended vCPU operation is used for hardware CPU virtualization. It can
53 * be enabled with L4::Thread::vcpu_control_ext.
54 *
55 * \ref api_libvcpu defines a convenience API for working with vCPUs.
56 *
57 * \see api_libvcpu
58 */
59
60 /**
61 * State of a vCPU
62 * \ingroup l4_vcpu_api
63 */
64 typedef struct l4_vcpu_state_t
65 {
66 l4_umword_t version;
67 l4_umword_t user_data[7];
68 l4_vcpu_regs_t r; ///< Register state
69 l4_vcpu_ipc_regs_t i; ///< IPC state
70
71 l4_uint16_t state; ///< Current vCPU state
72 l4_uint16_t saved_state; ///< Saved vCPU state
73 l4_uint16_t sticky_flags; ///< Pending flags
74 l4_uint16_t _reserved; ///< \internal
75
76 l4_cap_idx_t user_task; ///< User task to use
77
78 l4_umword_t entry_sp; ///< Stack pointer for entry (when coming from user task)
79 l4_umword_t entry_ip; ///< IP for entry
80 l4_umword_t reserved_sp; ///< \internal
81 l4_vcpu_arch_state_t arch_state;
82 } l4_vcpu_state_t;
83
84 /**
85 * State flags of a vCPU
86 * \ingroup l4_vcpu_api
87 */
88 enum L4_vcpu_state_flags
89 {
90 L4_VCPU_F_IRQ = 0x01, ///< IRQs (events) enabled
91 L4_VCPU_F_PAGE_FAULTS = 0x02, ///< Page faults enabled
92 L4_VCPU_F_EXCEPTIONS = 0x04, ///< Exception enabled
93 L4_VCPU_F_DEBUG_EXC = 0x08, ///< Debug exception enabled
94 L4_VCPU_F_USER_MODE = 0x20, ///< User task will be used
95 L4_VCPU_F_FPU_ENABLED = 0x80, ///< FPU enabled
96 };
97
98 /**
99 * Sticky flags of a vCPU
100 * \ingroup l4_vcpu_api
101 */
102 enum L4_vcpu_sticky_flags
103 {
104 L4_VCPU_SF_IRQ_PENDING = 0x01, ///< An event (e.g. IRQ) is pending
105 };
106
107 /**
108 * Offsets for vCPU state layouts
109 * \ingroup l4_vcpu_api
110 */
111 enum L4_vcpu_state_offset
112 {
113 L4_VCPU_OFFSET_EXT_STATE = 0x400, ///< Offset where extended state begins
114 L4_VCPU_OFFSET_EXT_INFOS = 0x200, ///< Offset where extended infos begin
115 };
116
117 /**
118 * Check if a vCPU state has the right version.
119 *
120 * \param vcpu A pointer to an initialized vCPU state.
121 *
122 * \retval 1 If the vCPU state has a matching version ID for the current
123 * vCPU user-level structures.
124 * \retval 0 If the vCPU state has a different (incompatible) version ID than
125 * the current vCPU user-level structures.
126 *
127 */
128 L4_INLINE int
129 l4_vcpu_check_version(l4_vcpu_state_t const *vcpu) L4_NOTHROW;
130
131 /* IMPLEMENTATION: ------------------------------------------------*/
132
133 L4_INLINE int
l4_vcpu_check_version(l4_vcpu_state_t const * vcpu)134 l4_vcpu_check_version(l4_vcpu_state_t const *vcpu) L4_NOTHROW
135 {
136 return vcpu->version == L4_VCPU_STATE_VERSION;
137 }
138