1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
3 * Userspace interface for /dev/acrn_hsm - ACRN Hypervisor Service Module
5 * This file can be used by applications that need to communicate with the HSM
6 * via the ioctl interface.
8 * Copyright (C) 2021 Intel Corporation. All rights reserved.
14 #include <linux/types.h>
15 #include <linux/uuid.h>
17 #define ACRN_IO_REQUEST_MAX 16
19 #define ACRN_IOREQ_STATE_PENDING 0
20 #define ACRN_IOREQ_STATE_COMPLETE 1
21 #define ACRN_IOREQ_STATE_PROCESSING 2
22 #define ACRN_IOREQ_STATE_FREE 3
24 #define ACRN_IOREQ_TYPE_PORTIO 0
25 #define ACRN_IOREQ_TYPE_MMIO 1
26 #define ACRN_IOREQ_TYPE_PCICFG 2
28 #define ACRN_IOREQ_DIR_READ 0
29 #define ACRN_IOREQ_DIR_WRITE 1
32 * struct acrn_mmio_request - Info of a MMIO I/O request
33 * @direction: Access direction of this request (ACRN_IOREQ_DIR_*)
34 * @reserved: Reserved for alignment and should be 0
35 * @address: Access address of this MMIO I/O request
36 * @size: Access size of this MMIO I/O request
37 * @value: Read/write value of this MMIO I/O request
39 struct acrn_mmio_request {
48 * struct acrn_pio_request - Info of a PIO I/O request
49 * @direction: Access direction of this request (ACRN_IOREQ_DIR_*)
50 * @reserved: Reserved for alignment and should be 0
51 * @address: Access address of this PIO I/O request
52 * @size: Access size of this PIO I/O request
53 * @value: Read/write value of this PIO I/O request
55 struct acrn_pio_request {
64 * struct acrn_pci_request - Info of a PCI I/O request
65 * @direction: Access direction of this request (ACRN_IOREQ_DIR_*)
66 * @reserved: Reserved for alignment and should be 0
67 * @size: Access size of this PCI I/O request
68 * @value: Read/write value of this PIO I/O request
69 * @bus: PCI bus value of this PCI I/O request
70 * @dev: PCI device value of this PCI I/O request
71 * @func: PCI function value of this PCI I/O request
72 * @reg: PCI config space offset of this PCI I/O request
74 * Need keep same header layout with &struct acrn_pio_request.
76 struct acrn_pci_request {
88 * struct acrn_io_request - 256-byte ACRN I/O request
89 * @type: Type of this request (ACRN_IOREQ_TYPE_*).
90 * @completion_polling: Polling flag. Hypervisor will poll completion of the
91 * I/O request if this flag set.
92 * @reserved0: Reserved fields.
93 * @reqs: Union of different types of request. Byte offset: 64.
94 * @reqs.pio_request: PIO request data of the I/O request.
95 * @reqs.pci_request: PCI configuration space request data of the I/O request.
96 * @reqs.mmio_request: MMIO request data of the I/O request.
97 * @reqs.data: Raw data of the I/O request.
98 * @reserved1: Reserved fields.
99 * @kernel_handled: Flag indicates this request need be handled in kernel.
100 * @processed: The status of this request (ACRN_IOREQ_STATE_*).
102 * The state transitions of ACRN I/O request:
104 * FREE -> PENDING -> PROCESSING -> COMPLETE -> FREE -> ...
106 * An I/O request in COMPLETE or FREE state is owned by the hypervisor. HSM and
107 * ACRN userspace are in charge of processing the others.
109 * On basis of the states illustrated above, a typical lifecycle of ACRN IO
110 * request would look like:
112 * Flow (assume the initial state is FREE)
114 * | Service VM vCPU 0 Service VM vCPU x User vCPU y
117 * | fills in type, addr, etc.
118 * | pauses the User VM vCPU y
119 * | sets the state to PENDING (a)
120 * | fires an upcall to Service VM
123 * | scans for PENDING requests
124 * | sets the states to PROCESSING (b)
125 * | assigns the requests to clients (c)
128 * | scans for the assigned requests
129 * | handles the requests (d)
131 * | sets states to COMPLETE
132 * | notifies the hypervisor
135 * | resumes User VM vCPU y (e)
138 * | post handling (f)
139 * V sets states to FREE
141 * Note that the procedures (a) to (f) in the illustration above require to be
142 * strictly processed in the order. One vCPU cannot trigger another request of
143 * I/O emulation before completing the previous one.
145 * Atomic and barriers are required when HSM and hypervisor accessing the state
146 * of &struct acrn_io_request.
149 struct acrn_io_request {
151 __u32 completion_polling;
154 struct acrn_pio_request pio_request;
155 struct acrn_pci_request pci_request;
156 struct acrn_mmio_request mmio_request;
160 __u32 kernel_handled;
162 } __attribute__((aligned(256)));
164 struct acrn_io_request_buffer {
166 struct acrn_io_request req_slot[ACRN_IO_REQUEST_MAX];
172 * struct acrn_ioreq_notify - The structure of ioreq completion notification
174 * @reserved: Reserved and should be 0
177 struct acrn_ioreq_notify {
184 * struct acrn_vm_creation - Info to create a User VM
185 * @vmid: User VM ID returned from the hypervisor
186 * @reserved0: Reserved and must be 0
187 * @vcpu_num: Number of vCPU in the VM. Return from hypervisor.
188 * @reserved1: Reserved and must be 0
189 * @uuid: UUID of the VM. Pass to hypervisor directly.
190 * @vm_flag: Flag of the VM creating. Pass to hypervisor directly.
191 * @ioreq_buf: Service VM GPA of I/O request buffer. Pass to
192 * hypervisor directly.
193 * @cpu_affinity: CPU affinity of the VM. Pass to hypervisor directly.
194 * It's a bitmap which indicates CPUs used by the VM.
196 struct acrn_vm_creation {
208 * struct acrn_gp_regs - General registers of a User VM
209 * @rax: Value of register RAX
210 * @rcx: Value of register RCX
211 * @rdx: Value of register RDX
212 * @rbx: Value of register RBX
213 * @rsp: Value of register RSP
214 * @rbp: Value of register RBP
215 * @rsi: Value of register RSI
216 * @rdi: Value of register RDI
217 * @r8: Value of register R8
218 * @r9: Value of register R9
219 * @r10: Value of register R10
220 * @r11: Value of register R11
221 * @r12: Value of register R12
222 * @r13: Value of register R13
223 * @r14: Value of register R14
224 * @r15: Value of register R15
226 struct acrn_gp_regs {
246 * struct acrn_descriptor_ptr - Segment descriptor table of a User VM.
247 * @limit: Limit field.
249 * @reserved: Reserved and must be 0.
251 struct acrn_descriptor_ptr {
255 } __attribute__ ((__packed__));
258 * struct acrn_regs - Registers structure of a User VM
259 * @gprs: General registers
260 * @gdt: Global Descriptor Table
261 * @idt: Interrupt Descriptor Table
262 * @rip: Value of register RIP
263 * @cs_base: Base of code segment selector
264 * @cr0: Value of register CR0
265 * @cr4: Value of register CR4
266 * @cr3: Value of register CR3
267 * @ia32_efer: Value of IA32_EFER MSR
268 * @rflags: Value of regsiter RFLAGS
269 * @reserved_64: Reserved and must be 0
270 * @cs_ar: Attribute field of code segment selector
271 * @cs_limit: Limit field of code segment selector
272 * @reserved_32: Reserved and must be 0
273 * @cs_sel: Value of code segment selector
274 * @ss_sel: Value of stack segment selector
275 * @ds_sel: Value of data segment selector
276 * @es_sel: Value of extra segment selector
277 * @fs_sel: Value of FS selector
278 * @gs_sel: Value of GS selector
279 * @ldt_sel: Value of LDT descriptor selector
280 * @tr_sel: Value of TSS descriptor selector
283 struct acrn_gp_regs gprs;
284 struct acrn_descriptor_ptr gdt;
285 struct acrn_descriptor_ptr idt;
294 __le64 reserved_64[4];
298 __le32 reserved_32[3];
311 * struct acrn_vcpu_regs - Info of vCPU registers state
313 * @reserved: Reserved and must be 0
314 * @vcpu_regs: vCPU registers state
316 * This structure will be passed to hypervisor directly.
318 struct acrn_vcpu_regs {
321 struct acrn_regs vcpu_regs;
324 #define ACRN_MEM_ACCESS_RIGHT_MASK 0x00000007U
325 #define ACRN_MEM_ACCESS_READ 0x00000001U
326 #define ACRN_MEM_ACCESS_WRITE 0x00000002U
327 #define ACRN_MEM_ACCESS_EXEC 0x00000004U
328 #define ACRN_MEM_ACCESS_RWX (ACRN_MEM_ACCESS_READ | \
329 ACRN_MEM_ACCESS_WRITE | \
330 ACRN_MEM_ACCESS_EXEC)
332 #define ACRN_MEM_TYPE_MASK 0x000007C0U
333 #define ACRN_MEM_TYPE_WB 0x00000040U
334 #define ACRN_MEM_TYPE_WT 0x00000080U
335 #define ACRN_MEM_TYPE_UC 0x00000100U
336 #define ACRN_MEM_TYPE_WC 0x00000200U
337 #define ACRN_MEM_TYPE_WP 0x00000400U
339 /* Memory mapping types */
340 #define ACRN_MEMMAP_RAM 0
341 #define ACRN_MEMMAP_MMIO 1
344 * struct acrn_vm_memmap - A EPT memory mapping info for a User VM.
345 * @type: Type of the memory mapping (ACRM_MEMMAP_*).
346 * Pass to hypervisor directly.
347 * @attr: Attribute of the memory mapping.
348 * Pass to hypervisor directly.
349 * @user_vm_pa: Physical address of User VM.
350 * Pass to hypervisor directly.
351 * @service_vm_pa: Physical address of Service VM.
352 * Pass to hypervisor directly.
353 * @vma_base: VMA address of Service VM. Pass to hypervisor directly.
354 * @len: Length of the memory mapping.
355 * Pass to hypervisor directly.
357 struct acrn_vm_memmap {
368 /* Type of interrupt of a passthrough device */
369 #define ACRN_PTDEV_IRQ_INTX 0
370 #define ACRN_PTDEV_IRQ_MSI 1
371 #define ACRN_PTDEV_IRQ_MSIX 2
373 * struct acrn_ptdev_irq - Interrupt data of a passthrough device.
374 * @type: Type (ACRN_PTDEV_IRQ_*)
375 * @virt_bdf: Virtual Bus/Device/Function
376 * @phys_bdf: Physical Bus/Device/Function
377 * @intx: Info of interrupt
378 * @intx.virt_pin: Virtual IOAPIC pin
379 * @intx.phys_pin: Physical IOAPIC pin
380 * @intx.is_pic_pin: Is PIC pin or not
382 * This structure will be passed to hypervisor directly.
384 struct acrn_ptdev_irq {
396 /* Type of PCI device assignment */
397 #define ACRN_PTDEV_QUIRK_ASSIGN (1U << 0)
399 #define ACRN_PCI_NUM_BARS 6
401 * struct acrn_pcidev - Info for assigning or de-assigning a PCI device
402 * @type: Type of the assignment
403 * @virt_bdf: Virtual Bus/Device/Function
404 * @phys_bdf: Physical Bus/Device/Function
405 * @intr_line: PCI interrupt line
406 * @intr_pin: PCI interrupt pin
409 * This structure will be passed to hypervisor directly.
417 __u32 bar[ACRN_PCI_NUM_BARS];
421 * struct acrn_msi_entry - Info for injecting a MSI interrupt to a VM
422 * @msi_addr: MSI addr[19:12] with dest vCPU ID
423 * @msi_data: MSI data[7:0] with vector
425 struct acrn_msi_entry {
430 struct acrn_acpi_generic_address {
436 } __attribute__ ((__packed__));
439 * struct acrn_cstate_data - A C state package defined in ACPI
440 * @cx_reg: Register of the C state object
441 * @type: Type of the C state object
442 * @latency: The worst-case latency to enter and exit this C state
443 * @power: The average power consumption when in this C state
445 struct acrn_cstate_data {
446 struct acrn_acpi_generic_address cx_reg;
453 * struct acrn_pstate_data - A P state package defined in ACPI
454 * @core_frequency: CPU frequency (in MHz).
455 * @power: Power dissipation (in milliwatts).
456 * @transition_latency: The worst-case latency in microseconds that CPU is
457 * unavailable during a transition from any P state to
459 * @bus_master_latency: The worst-case latency in microseconds that Bus Masters
460 * are prevented from accessing memory during a transition
461 * from any P state to this P state.
462 * @control: The value to be written to Performance Control Register
463 * @status: Transition status.
465 struct acrn_pstate_data {
466 __u64 core_frequency;
468 __u64 transition_latency;
469 __u64 bus_master_latency;
474 #define PMCMD_TYPE_MASK 0x000000ff
475 enum acrn_pm_cmd_type {
476 ACRN_PMCMD_GET_PX_CNT,
477 ACRN_PMCMD_GET_PX_DATA,
478 ACRN_PMCMD_GET_CX_CNT,
479 ACRN_PMCMD_GET_CX_DATA,
482 #define ACRN_IOEVENTFD_FLAG_PIO 0x01
483 #define ACRN_IOEVENTFD_FLAG_DATAMATCH 0x02
484 #define ACRN_IOEVENTFD_FLAG_DEASSIGN 0x04
486 * struct acrn_ioeventfd - Data to operate a &struct hsm_ioeventfd
487 * @fd: The fd of eventfd associated with a hsm_ioeventfd
488 * @flags: Logical-OR of ACRN_IOEVENTFD_FLAG_*
489 * @addr: The start address of IO range of ioeventfd
490 * @len: The length of IO range of ioeventfd
491 * @reserved: Reserved and should be 0
492 * @data: Data for data matching
494 * Without flag ACRN_IOEVENTFD_FLAG_DEASSIGN, ioctl ACRN_IOCTL_IOEVENTFD
495 * creates a &struct hsm_ioeventfd with properties originated from &struct
496 * acrn_ioeventfd. With flag ACRN_IOEVENTFD_FLAG_DEASSIGN, ioctl
497 * ACRN_IOCTL_IOEVENTFD destroys the &struct hsm_ioeventfd matching the fd.
499 struct acrn_ioeventfd {
508 #define ACRN_IRQFD_FLAG_DEASSIGN 0x01
510 * struct acrn_irqfd - Data to operate a &struct hsm_irqfd
511 * @fd: The fd of eventfd associated with a hsm_irqfd
512 * @flags: Logical-OR of ACRN_IRQFD_FLAG_*
513 * @msi: Info of MSI associated with the irqfd
518 struct acrn_msi_entry msi;
521 /* The ioctl type, documented in ioctl-number.rst */
522 #define ACRN_IOCTL_TYPE 0xA2
525 * Common IOCTL IDs definition for ACRN userspace
527 #define ACRN_IOCTL_CREATE_VM \
528 _IOWR(ACRN_IOCTL_TYPE, 0x10, struct acrn_vm_creation)
529 #define ACRN_IOCTL_DESTROY_VM \
530 _IO(ACRN_IOCTL_TYPE, 0x11)
531 #define ACRN_IOCTL_START_VM \
532 _IO(ACRN_IOCTL_TYPE, 0x12)
533 #define ACRN_IOCTL_PAUSE_VM \
534 _IO(ACRN_IOCTL_TYPE, 0x13)
535 #define ACRN_IOCTL_RESET_VM \
536 _IO(ACRN_IOCTL_TYPE, 0x15)
537 #define ACRN_IOCTL_SET_VCPU_REGS \
538 _IOW(ACRN_IOCTL_TYPE, 0x16, struct acrn_vcpu_regs)
540 #define ACRN_IOCTL_INJECT_MSI \
541 _IOW(ACRN_IOCTL_TYPE, 0x23, struct acrn_msi_entry)
542 #define ACRN_IOCTL_VM_INTR_MONITOR \
543 _IOW(ACRN_IOCTL_TYPE, 0x24, unsigned long)
544 #define ACRN_IOCTL_SET_IRQLINE \
545 _IOW(ACRN_IOCTL_TYPE, 0x25, __u64)
547 #define ACRN_IOCTL_NOTIFY_REQUEST_FINISH \
548 _IOW(ACRN_IOCTL_TYPE, 0x31, struct acrn_ioreq_notify)
549 #define ACRN_IOCTL_CREATE_IOREQ_CLIENT \
550 _IO(ACRN_IOCTL_TYPE, 0x32)
551 #define ACRN_IOCTL_ATTACH_IOREQ_CLIENT \
552 _IO(ACRN_IOCTL_TYPE, 0x33)
553 #define ACRN_IOCTL_DESTROY_IOREQ_CLIENT \
554 _IO(ACRN_IOCTL_TYPE, 0x34)
555 #define ACRN_IOCTL_CLEAR_VM_IOREQ \
556 _IO(ACRN_IOCTL_TYPE, 0x35)
558 #define ACRN_IOCTL_SET_MEMSEG \
559 _IOW(ACRN_IOCTL_TYPE, 0x41, struct acrn_vm_memmap)
560 #define ACRN_IOCTL_UNSET_MEMSEG \
561 _IOW(ACRN_IOCTL_TYPE, 0x42, struct acrn_vm_memmap)
563 #define ACRN_IOCTL_SET_PTDEV_INTR \
564 _IOW(ACRN_IOCTL_TYPE, 0x53, struct acrn_ptdev_irq)
565 #define ACRN_IOCTL_RESET_PTDEV_INTR \
566 _IOW(ACRN_IOCTL_TYPE, 0x54, struct acrn_ptdev_irq)
567 #define ACRN_IOCTL_ASSIGN_PCIDEV \
568 _IOW(ACRN_IOCTL_TYPE, 0x55, struct acrn_pcidev)
569 #define ACRN_IOCTL_DEASSIGN_PCIDEV \
570 _IOW(ACRN_IOCTL_TYPE, 0x56, struct acrn_pcidev)
572 #define ACRN_IOCTL_PM_GET_CPU_STATE \
573 _IOWR(ACRN_IOCTL_TYPE, 0x60, __u64)
575 #define ACRN_IOCTL_IOEVENTFD \
576 _IOW(ACRN_IOCTL_TYPE, 0x70, struct acrn_ioeventfd)
577 #define ACRN_IOCTL_IRQFD \
578 _IOW(ACRN_IOCTL_TYPE, 0x71, struct acrn_irqfd)
580 #endif /* _UAPI_ACRN_H */