1/******************************************************************************
2 * vm_event.h
3 *
4 * Memory event common structures.
5 *
6 * Copyright (c) 2009 by Citrix Systems, Inc. (Patrick Colp)
7 *
8 * Permission is hereby granted, free of charge, to any person obtaining a copy
9 * of this software and associated documentation files (the "Software"), to
10 * deal in the Software without restriction, including without limitation the
11 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
12 * sell copies of the Software, and to permit persons to whom the Software is
13 * furnished to do so, subject to the following conditions:
14 *
15 * The above copyright notice and this permission notice shall be included in
16 * all copies or substantial portions of the Software.
17 *
18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
23 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
24 * DEALINGS IN THE SOFTWARE.
25 */
26
27#ifndef _XEN_PUBLIC_VM_EVENT_H
28#define _XEN_PUBLIC_VM_EVENT_H
29
30#include "xen.h"
31
32#define VM_EVENT_INTERFACE_VERSION 0x00000001
33
34#if defined(__XEN__) || defined(__XEN_TOOLS__)
35
36#include "io/ring.h"
37
38/*
39 * Memory event flags
40 */
41
42/*
43 * VCPU_PAUSED in a request signals that the vCPU triggering the event has been
44 *  paused
45 * VCPU_PAUSED in a response signals to unpause the vCPU
46 */
47#define VM_EVENT_FLAG_VCPU_PAUSED        (1 << 0)
48/* Flags to aid debugging vm_event */
49#define VM_EVENT_FLAG_FOREIGN            (1 << 1)
50/*
51 * The following flags can be set in response to a mem_access event.
52 *
53 * Emulate the fault-causing instruction (if set in the event response flags).
54 * This will allow the guest to continue execution without lifting the page
55 * access restrictions.
56 */
57#define VM_EVENT_FLAG_EMULATE            (1 << 2)
58/*
59 * Same as VM_EVENT_FLAG_EMULATE, but with write operations or operations
60 * potentially having side effects (like memory mapped or port I/O) disabled.
61 */
62#define VM_EVENT_FLAG_EMULATE_NOWRITE    (1 << 3)
63/*
64 * Toggle singlestepping on vm_event response.
65 * Requires the vCPU to be paused already (synchronous events only).
66 */
67#define VM_EVENT_FLAG_TOGGLE_SINGLESTEP  (1 << 4)
68/*
69 * Data is being sent back to the hypervisor in the event response, to be
70 * returned by the read function when emulating an instruction.
71 * This flag is only useful when combined with VM_EVENT_FLAG_EMULATE
72 * and takes precedence if combined with VM_EVENT_FLAG_EMULATE_NOWRITE
73 * (i.e. if both VM_EVENT_FLAG_EMULATE_NOWRITE and
74 * VM_EVENT_FLAG_SET_EMUL_READ_DATA are set, only the latter will be honored).
75 */
76#define VM_EVENT_FLAG_SET_EMUL_READ_DATA (1 << 5)
77 /*
78  * Deny completion of the operation that triggered the event.
79  * Currently only useful for MSR, CR0, CR3 and CR4 write events.
80  */
81#define VM_EVENT_FLAG_DENY               (1 << 6)
82/*
83 * This flag can be set in a request or a response
84 *
85 * On a request, indicates that the event occurred in the alternate p2m specified by
86 * the altp2m_idx request field.
87 *
88 * On a response, indicates that the VCPU should resume in the alternate p2m specified
89 * by the altp2m_idx response field if possible.
90 */
91#define VM_EVENT_FLAG_ALTERNATE_P2M      (1 << 7)
92
93/*
94 * Reasons for the vm event request
95 */
96
97/* Default case */
98#define VM_EVENT_REASON_UNKNOWN                 0
99/* Memory access violation */
100#define VM_EVENT_REASON_MEM_ACCESS              1
101/* Memory sharing event */
102#define VM_EVENT_REASON_MEM_SHARING             2
103/* Memory paging event */
104#define VM_EVENT_REASON_MEM_PAGING              3
105/* A control register was updated */
106#define VM_EVENT_REASON_WRITE_CTRLREG           4
107/* An MSR was updated. */
108#define VM_EVENT_REASON_MOV_TO_MSR              5
109/* Debug operation executed (e.g. int3) */
110#define VM_EVENT_REASON_SOFTWARE_BREAKPOINT     6
111/* Single-step (e.g. MTF) */
112#define VM_EVENT_REASON_SINGLESTEP              7
113/* An event has been requested via HVMOP_guest_request_vm_event. */
114#define VM_EVENT_REASON_GUEST_REQUEST           8
115
116/* Supported values for the vm_event_write_ctrlreg index. */
117#define VM_EVENT_X86_CR0    0
118#define VM_EVENT_X86_CR3    1
119#define VM_EVENT_X86_CR4    2
120#define VM_EVENT_X86_XCR0   3
121
122/*
123 * Using a custom struct (not hvm_hw_cpu) so as to not fill
124 * the vm_event ring buffer too quickly.
125 */
126struct vm_event_regs_x86 {
127    uint64_t rax;
128    uint64_t rcx;
129    uint64_t rdx;
130    uint64_t rbx;
131    uint64_t rsp;
132    uint64_t rbp;
133    uint64_t rsi;
134    uint64_t rdi;
135    uint64_t r8;
136    uint64_t r9;
137    uint64_t r10;
138    uint64_t r11;
139    uint64_t r12;
140    uint64_t r13;
141    uint64_t r14;
142    uint64_t r15;
143    uint64_t rflags;
144    uint64_t dr7;
145    uint64_t rip;
146    uint64_t cr0;
147    uint64_t cr2;
148    uint64_t cr3;
149    uint64_t cr4;
150    uint64_t sysenter_cs;
151    uint64_t sysenter_esp;
152    uint64_t sysenter_eip;
153    uint64_t msr_efer;
154    uint64_t msr_star;
155    uint64_t msr_lstar;
156    uint64_t fs_base;
157    uint64_t gs_base;
158    uint32_t cs_arbytes;
159    uint32_t _pad;
160};
161
162/*
163 * mem_access flag definitions
164 *
165 * These flags are set only as part of a mem_event request.
166 *
167 * R/W/X: Defines the type of violation that has triggered the event
168 *        Multiple types can be set in a single violation!
169 * GLA_VALID: If the gla field holds a guest VA associated with the event
170 * FAULT_WITH_GLA: If the violation was triggered by accessing gla
171 * FAULT_IN_GPT: If the violation was triggered during translating gla
172 */
173#define MEM_ACCESS_R                    (1 << 0)
174#define MEM_ACCESS_W                    (1 << 1)
175#define MEM_ACCESS_X                    (1 << 2)
176#define MEM_ACCESS_RWX                  (MEM_ACCESS_R | MEM_ACCESS_W | MEM_ACCESS_X)
177#define MEM_ACCESS_RW                   (MEM_ACCESS_R | MEM_ACCESS_W)
178#define MEM_ACCESS_RX                   (MEM_ACCESS_R | MEM_ACCESS_X)
179#define MEM_ACCESS_WX                   (MEM_ACCESS_W | MEM_ACCESS_X)
180#define MEM_ACCESS_GLA_VALID            (1 << 3)
181#define MEM_ACCESS_FAULT_WITH_GLA       (1 << 4)
182#define MEM_ACCESS_FAULT_IN_GPT         (1 << 5)
183
184struct vm_event_mem_access {
185    uint64_t gfn;
186    uint64_t offset;
187    uint64_t gla;   /* if flags has MEM_ACCESS_GLA_VALID set */
188    uint32_t flags; /* MEM_ACCESS_* */
189    uint32_t _pad;
190};
191
192struct vm_event_write_ctrlreg {
193    uint32_t index;
194    uint32_t _pad;
195    uint64_t new_value;
196    uint64_t old_value;
197};
198
199struct vm_event_debug {
200    uint64_t gfn;
201};
202
203struct vm_event_mov_to_msr {
204    uint64_t msr;
205    uint64_t value;
206};
207
208#define MEM_PAGING_DROP_PAGE       (1 << 0)
209#define MEM_PAGING_EVICT_FAIL      (1 << 1)
210
211struct vm_event_paging {
212    uint64_t gfn;
213    uint32_t p2mt;
214    uint32_t flags;
215};
216
217struct vm_event_sharing {
218    uint64_t gfn;
219    uint32_t p2mt;
220    uint32_t _pad;
221};
222
223struct vm_event_emul_read_data {
224    uint32_t size;
225    /* The struct is used in a union with vm_event_regs_x86. */
226    uint8_t  data[sizeof(struct vm_event_regs_x86) - sizeof(uint32_t)];
227};
228
229typedef struct vm_event_st {
230    uint32_t version;   /* VM_EVENT_INTERFACE_VERSION */
231    uint32_t flags;     /* VM_EVENT_FLAG_* */
232    uint32_t reason;    /* VM_EVENT_REASON_* */
233    uint32_t vcpu_id;
234    uint16_t altp2m_idx; /* may be used during request and response */
235    uint16_t _pad[3];
236
237    union {
238        struct vm_event_paging                mem_paging;
239        struct vm_event_sharing               mem_sharing;
240        struct vm_event_mem_access            mem_access;
241        struct vm_event_write_ctrlreg         write_ctrlreg;
242        struct vm_event_mov_to_msr            mov_to_msr;
243        struct vm_event_debug                 software_breakpoint;
244        struct vm_event_debug                 singlestep;
245    } u;
246
247    union {
248        union {
249            struct vm_event_regs_x86 x86;
250        } regs;
251
252        struct vm_event_emul_read_data emul_read_data;
253    } data;
254} vm_event_request_t, vm_event_response_t;
255
256DEFINE_RING_TYPES(vm_event, vm_event_request_t, vm_event_response_t);
257
258#endif /* defined(__XEN__) || defined(__XEN_TOOLS__) */
259#endif /* _XEN_PUBLIC_VM_EVENT_H */
260
261/*
262 * Local variables:
263 * mode: C
264 * c-file-style: "BSD"
265 * c-basic-offset: 4
266 * tab-width: 4
267 * indent-tabs-mode: nil
268 * End:
269 */
270