| /* SPDX-License-Identifier: GPL-2.0-only WITH Linux-syscall-note */ | |
| /* | |
| * Copyright (c) 2022-2023 Qualcomm Innovation Center, Inc. All rights reserved. | |
| */ | |
| #ifndef _UAPI_LINUX_GUNYAH_H | |
| #define _UAPI_LINUX_GUNYAH_H | |
| /* | |
| * Userspace interface for /dev/gunyah - gunyah based virtual machine | |
| */ | |
| #include <linux/types.h> | |
| #include <linux/ioctl.h> | |
| #define GH_IOCTL_TYPE 'G' | |
| /* | |
| * ioctls for /dev/gunyah fds: | |
| */ | |
| #define GH_CREATE_VM _IO(GH_IOCTL_TYPE, 0x0) /* Returns a Gunyah VM fd */ | |
| /* | |
| * ioctls for VM fds | |
| */ | |
| /** | |
| * enum gh_mem_flags - Possible flags on &struct gh_userspace_memory_region | |
| * @GH_MEM_ALLOW_READ: Allow guest to read the memory | |
| * @GH_MEM_ALLOW_WRITE: Allow guest to write to the memory | |
| * @GH_MEM_ALLOW_EXEC: Allow guest to execute instructions in the memory | |
| */ | |
| enum gh_mem_flags { | |
| GH_MEM_ALLOW_READ = 1UL << 0, | |
| GH_MEM_ALLOW_WRITE = 1UL << 1, | |
| GH_MEM_ALLOW_EXEC = 1UL << 2, | |
| }; | |
| /** | |
| * struct gh_userspace_memory_region - Userspace memory descripion for GH_VM_SET_USER_MEM_REGION | |
| * @label: Identifer to the region which is unique to the VM. | |
| * @flags: Flags for memory parcel behavior. See &enum gh_mem_flags. | |
| * @guest_phys_addr: Location of the memory region in guest's memory space (page-aligned) | |
| * @memory_size: Size of the region (page-aligned) | |
| * @userspace_addr: Location of the memory region in caller (userspace)'s memory | |
| * | |
| * See Documentation/virt/gunyah/vm-manager.rst for further details. | |
| */ | |
| struct gh_userspace_memory_region { | |
| __u32 label; | |
| __u32 flags; | |
| __u64 guest_phys_addr; | |
| __u64 memory_size; | |
| __u64 userspace_addr; | |
| }; | |
| #define GH_VM_SET_USER_MEM_REGION _IOW(GH_IOCTL_TYPE, 0x1, \ | |
| struct gh_userspace_memory_region) | |
| /** | |
| * struct gh_vm_dtb_config - Set the location of the VM's devicetree blob | |
| * @guest_phys_addr: Address of the VM's devicetree in guest memory. | |
| * @size: Maximum size of the devicetree including space for overlays. | |
| * Resource manager applies an overlay to the DTB and dtb_size should | |
| * include room for the overlay. A page of memory is typicaly plenty. | |
| */ | |
| struct gh_vm_dtb_config { | |
| __u64 guest_phys_addr; | |
| __u64 size; | |
| }; | |
| #define GH_VM_SET_DTB_CONFIG _IOW(GH_IOCTL_TYPE, 0x2, struct gh_vm_dtb_config) | |
| #define GH_VM_START _IO(GH_IOCTL_TYPE, 0x3) | |
| /** | |
| * enum gh_fn_type - Valid types of Gunyah VM functions | |
| * @GH_FN_VCPU: create a vCPU instance to control a vCPU | |
| * &struct gh_fn_desc.arg is a pointer to &struct gh_fn_vcpu_arg | |
| * Return: file descriptor to manipulate the vcpu. | |
| * @GH_FN_IRQFD: register eventfd to assert a Gunyah doorbell | |
| * &struct gh_fn_desc.arg is a pointer to &struct gh_fn_irqfd_arg | |
| * @GH_FN_IOEVENTFD: register ioeventfd to trigger when VM faults on parameter | |
| * &struct gh_fn_desc.arg is a pointer to &struct gh_fn_ioeventfd_arg | |
| */ | |
| enum gh_fn_type { | |
| GH_FN_VCPU = 1, | |
| GH_FN_IRQFD, | |
| GH_FN_IOEVENTFD, | |
| }; | |
| #define GH_FN_MAX_ARG_SIZE 256 | |
| /** | |
| * struct gh_fn_vcpu_arg - Arguments to create a vCPU. | |
| * @id: vcpu id | |
| * | |
| * Create this function with &GH_VM_ADD_FUNCTION using type &GH_FN_VCPU. | |
| * | |
| * The vcpu type will register with the VM Manager to expect to control | |
| * vCPU number `vcpu_id`. It returns a file descriptor allowing interaction with | |
| * the vCPU. See the Gunyah vCPU API description sections for interacting with | |
| * the Gunyah vCPU file descriptors. | |
| */ | |
| struct gh_fn_vcpu_arg { | |
| __u32 id; | |
| }; | |
| /** | |
| * enum gh_irqfd_flags - flags for use in gh_fn_irqfd_arg | |
| * @GH_IRQFD_FLAGS_LEVEL: make the interrupt operate like a level triggered | |
| * interrupt on guest side. Triggering IRQFD before | |
| * guest handles the interrupt causes interrupt to | |
| * stay asserted. | |
| */ | |
| enum gh_irqfd_flags { | |
| GH_IRQFD_FLAGS_LEVEL = 1UL << 0, | |
| }; | |
| /** | |
| * struct gh_fn_irqfd_arg - Arguments to create an irqfd function. | |
| * | |
| * Create this function with &GH_VM_ADD_FUNCTION using type &GH_FN_IRQFD. | |
| * | |
| * Allows setting an eventfd to directly trigger a guest interrupt. | |
| * irqfd.fd specifies the file descriptor to use as the eventfd. | |
| * irqfd.label corresponds to the doorbell label used in the guest VM's devicetree. | |
| * | |
| * @fd: an eventfd which when written to will raise a doorbell | |
| * @label: Label of the doorbell created on the guest VM | |
| * @flags: see &enum gh_irqfd_flags | |
| * @padding: padding bytes | |
| */ | |
| struct gh_fn_irqfd_arg { | |
| __u32 fd; | |
| __u32 label; | |
| __u32 flags; | |
| __u32 padding; | |
| }; | |
| /** | |
| * enum gh_ioeventfd_flags - flags for use in gh_fn_ioeventfd_arg | |
| * @GH_IOEVENTFD_FLAGS_DATAMATCH: the event will be signaled only if the | |
| * written value to the registered address is | |
| * equal to &struct gh_fn_ioeventfd_arg.datamatch | |
| */ | |
| enum gh_ioeventfd_flags { | |
| GH_IOEVENTFD_FLAGS_DATAMATCH = 1UL << 0, | |
| }; | |
| /** | |
| * struct gh_fn_ioeventfd_arg - Arguments to create an ioeventfd function | |
| * @datamatch: data used when GH_IOEVENTFD_DATAMATCH is set | |
| * @addr: Address in guest memory | |
| * @len: Length of access | |
| * @fd: When ioeventfd is matched, this eventfd is written | |
| * @flags: See &enum gh_ioeventfd_flags | |
| * @padding: padding bytes | |
| * | |
| * Create this function with &GH_VM_ADD_FUNCTION using type &GH_FN_IOEVENTFD. | |
| * | |
| * Attaches an ioeventfd to a legal mmio address within the guest. A guest write | |
| * in the registered address will signal the provided event instead of triggering | |
| * an exit on the GH_VCPU_RUN ioctl. | |
| */ | |
| struct gh_fn_ioeventfd_arg { | |
| __u64 datamatch; | |
| __u64 addr; /* legal mmio address */ | |
| __u32 len; /* 1, 2, 4, or 8 bytes; or 0 to ignore length */ | |
| __s32 fd; | |
| __u32 flags; | |
| __u32 padding; | |
| }; | |
| /** | |
| * struct gh_fn_desc - Arguments to create a VM function | |
| * @type: Type of the function. See &enum gh_fn_type. | |
| * @arg_size: Size of argument to pass to the function. arg_size <= GH_FN_MAX_ARG_SIZE | |
| * @arg: Pointer to argument given to the function. See &enum gh_fn_type for expected | |
| * arguments for a function type. | |
| */ | |
| struct gh_fn_desc { | |
| __u32 type; | |
| __u32 arg_size; | |
| __u64 arg; | |
| }; | |
| #define GH_VM_ADD_FUNCTION _IOW(GH_IOCTL_TYPE, 0x4, struct gh_fn_desc) | |
| #define GH_VM_REMOVE_FUNCTION _IOW(GH_IOCTL_TYPE, 0x7, struct gh_fn_desc) | |
| /* | |
| * ioctls for vCPU fds | |
| */ | |
| /** | |
| * enum gh_vm_status - Stores status reason why VM is not runnable (exited). | |
| * @GH_VM_STATUS_LOAD_FAILED: VM didn't start because it couldn't be loaded. | |
| * @GH_VM_STATUS_EXITED: VM requested shutdown/reboot. | |
| * Use &struct gh_vm_exit_info.reason for further details. | |
| * @GH_VM_STATUS_CRASHED: VM state is unknown and has crashed. | |
| */ | |
| enum gh_vm_status { | |
| GH_VM_STATUS_LOAD_FAILED = 1, | |
| GH_VM_STATUS_EXITED = 2, | |
| GH_VM_STATUS_CRASHED = 3, | |
| }; | |
| /* | |
| * Gunyah presently sends max 4 bytes of exit_reason. | |
| * If that changes, this macro can be safely increased without breaking | |
| * userspace so long as struct gh_vcpu_run < PAGE_SIZE. | |
| */ | |
| #define GH_VM_MAX_EXIT_REASON_SIZE 8u | |
| /** | |
| * struct gh_vm_exit_info - Reason for VM exit as reported by Gunyah | |
| * See Gunyah documentation for values. | |
| * @type: Describes how VM exited | |
| * @padding: padding bytes | |
| * @reason_size: Number of bytes valid for `reason` | |
| * @reason: See Gunyah documentation for interpretation. Note: these values are | |
| * not interpreted by Linux and need to be converted from little-endian | |
| * as applicable. | |
| */ | |
| struct gh_vm_exit_info { | |
| __u16 type; | |
| __u16 padding; | |
| __u32 reason_size; | |
| __u8 reason[GH_VM_MAX_EXIT_REASON_SIZE]; | |
| }; | |
| /** | |
| * enum gh_vcpu_exit - Stores reason why &GH_VCPU_RUN ioctl recently exited with status 0 | |
| * @GH_VCPU_EXIT_UNKNOWN: Not used, status != 0 | |
| * @GH_VCPU_EXIT_MMIO: vCPU performed a read or write that could not be handled | |
| * by hypervisor or Linux. Use @struct gh_vcpu_run.mmio for | |
| * details of the read/write. | |
| * @GH_VCPU_EXIT_STATUS: vCPU not able to run because the VM has exited. | |
| * Use @struct gh_vcpu_run.status for why VM has exited. | |
| */ | |
| enum gh_vcpu_exit { | |
| GH_VCPU_EXIT_UNKNOWN, | |
| GH_VCPU_EXIT_MMIO, | |
| GH_VCPU_EXIT_STATUS, | |
| }; | |
| /** | |
| * struct gh_vcpu_run - Application code obtains a pointer to the gh_vcpu_run | |
| * structure by mmap()ing a vcpu fd. | |
| * @immediate_exit: polled when scheduling the vcpu. If set, immediately returns -EINTR. | |
| * @padding: padding bytes | |
| * @exit_reason: Set when GH_VCPU_RUN returns successfully and gives reason why | |
| * GH_VCPU_RUN has stopped running the vCPU. See &enum gh_vcpu_exit. | |
| * @mmio: Used when exit_reason == GH_VCPU_EXIT_MMIO | |
| * The guest has faulted on an memory-mapped I/O instruction that | |
| * couldn't be satisfied by gunyah. | |
| * @mmio.phys_addr: Address guest tried to access | |
| * @mmio.data: the value that was written if `is_write == 1`. Filled by | |
| * user for reads (`is_write == 0`). | |
| * @mmio.len: Length of write. Only the first `len` bytes of `data` | |
| * are considered by Gunyah. | |
| * @mmio.is_write: 1 if VM tried to perform a write, 0 for a read | |
| * @status: Used when exit_reason == GH_VCPU_EXIT_STATUS. | |
| * The guest VM is no longer runnable. This struct informs why. | |
| * @status.status: See &enum gh_vm_status for possible values | |
| * @status.exit_info: Used when status == GH_VM_STATUS_EXITED | |
| */ | |
| struct gh_vcpu_run { | |
| /* in */ | |
| __u8 immediate_exit; | |
| __u8 padding[7]; | |
| /* out */ | |
| __u32 exit_reason; | |
| union { | |
| struct { | |
| __u64 phys_addr; | |
| __u8 data[8]; | |
| __u32 len; | |
| __u8 is_write; | |
| } mmio; | |
| struct { | |
| enum gh_vm_status status; | |
| struct gh_vm_exit_info exit_info; | |
| } status; | |
| }; | |
| }; | |
| #define GH_VCPU_RUN _IO(GH_IOCTL_TYPE, 0x5) | |
| #define GH_VCPU_MMAP_SIZE _IO(GH_IOCTL_TYPE, 0x6) | |
| /** | |
| * ANDROID: android14-6.1 unfortunately contains UAPI that won't be carried | |
| * in kernel.org. Expose orthogonal ioctls that will never conflict with | |
| * kernel.org for these UAPIs. See b/268234781. | |
| */ | |
| #define GH_ANDROID_IOCTL_TYPE 'A' | |
| #define GH_VM_ANDROID_LEND_USER_MEM _IOW(GH_ANDROID_IOCTL_TYPE, 0x11, \ | |
| struct gh_userspace_memory_region) | |
| struct gh_vm_firmware_config { | |
| __u64 guest_phys_addr; | |
| __u64 size; | |
| }; | |
| #define GH_VM_ANDROID_SET_FW_CONFIG _IOW(GH_ANDROID_IOCTL_TYPE, 0x12, \ | |
| struct gh_vm_firmware_config) | |
| #endif |