From: Elliot Berman <quic_eberman@quicinc.com> To: Bjorn Andersson <quic_bjorande@quicinc.com>, Jonathan Corbet <corbet@lwn.net>, Bagas Sanjaya <bagasdotme@gmail.com>, Elliot Berman <quic_eberman@quicinc.com>, Murali Nalajala <quic_mnalajal@quicinc.com> Cc: Trilok Soni <quic_tsoni@quicinc.com>, Srivatsa Vaddagiri <quic_svaddagi@quicinc.com>, Carl van Schaik <quic_cvanscha@quicinc.com>, Prakruthi Deepak Heragu <quic_pheragu@quicinc.com>, Arnd Bergmann <arnd@arndb.de>, Greg Kroah-Hartman <gregkh@linuxfoundation.org>, Rob Herring <robh+dt@kernel.org>, Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>, Catalin Marinas <catalin.marinas@arm.com>, Will Deacon <will@kernel.org>, Jassi Brar <jassisinghbrar@gmail.com>, Sudeep Holla <sudeep.holla@arm.com>, Mark Rutland <mark.rutland@arm.com>, Lorenzo Pieralisi <lpieralisi@kernel.org>, "Dmitry Baryshkov" <dmitry.baryshkov@linaro.org>, <linux-arm-msm@vger.kernel.org>, <devicetree@vger.kernel.org>, <linux-kernel@vger.kernel.org>, <linux-doc@vger.kernel.org>, <linux-arm-kernel@lists.infradead.org>, <linux-acpi@vger.kernel.org> Subject: [PATCH v8 20/28] docs: gunyah: Document Gunyah VM Manager Date: Mon, 19 Dec 2022 14:58:41 -0800 [thread overview] Message-ID: <20221219225850.2397345-21-quic_eberman@quicinc.com> (raw) In-Reply-To: <20221219225850.2397345-1-quic_eberman@quicinc.com> Document the ioctls and usage of Gunyah VM Manager driver. Signed-off-by: Elliot Berman <quic_eberman@quicinc.com> --- Documentation/virt/gunyah/index.rst | 1 + Documentation/virt/gunyah/vm-manager.rst | 100 +++++++++++++++++++++++ 2 files changed, 101 insertions(+) create mode 100644 Documentation/virt/gunyah/vm-manager.rst diff --git a/Documentation/virt/gunyah/index.rst b/Documentation/virt/gunyah/index.rst index fbadbdd24da7..9019a03b6f3e 100644 --- a/Documentation/virt/gunyah/index.rst +++ b/Documentation/virt/gunyah/index.rst @@ -7,6 +7,7 @@ Gunyah Hypervisor .. toctree:: :maxdepth: 1 + vm-manager message-queue Gunyah is a Type-1 hypervisor which is independent of any OS kernel, and runs in diff --git a/Documentation/virt/gunyah/vm-manager.rst b/Documentation/virt/gunyah/vm-manager.rst new file mode 100644 index 000000000000..62513af09cbf --- /dev/null +++ b/Documentation/virt/gunyah/vm-manager.rst @@ -0,0 +1,100 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================= +Virtual Machine Manager +======================= + +The Gunyah Virtual Machine Manager is a Linux driver to support launching +virtual machines using Gunyah. It presently supports launching non-proxy +scheduled Linux-like virtual machines. + +Except for some basic information about the location of initial binaries, +most of the configuration about a Gunyah virtual machine is described in the +VM's devicetree. The devicetree is generated by userspace. Interacting with the +virtual machine is still done via the kernel and VM configuration requires some +of the corresponding functionality to be set up in the kernel. For instance, +sharing userspace memory with a VM is done via the GH_VM_SET_USER_MEM_REGION +ioctl. The VM itself is configured to use the memory region via the +devicetree. + +Sample Userspace VMM +==================== + +A sample userspace VMM is included in samples/gunyah/ along with a minimal +devicetree that can be used to launch a VM. To build this sample, enable +CONFIG_SAMPLE_GUNYAH. + +IOCTLs and userspace VMM flows +============================== + +The kernel exposes a char device interface at /dev/gunyah. + +To create a VM, use the GH_CREATE_VM ioctl. A successful call will return a +"Gunyah VM" file descriptor. + +/dev/gunyah API Descriptions +---------------------------- + +GH_CREATE_VM +~~~~~~~~~~~~ + +Creates a Gunyah VM. The argument is reserved for future use and must be 0. + +Gunyah VM API Descriptions +-------------------------- + +GH_VM_SET_USER_MEM_REGION +~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + struct gh_userspace_memory_region { + __u32 label; + __u32 flags; + __u64 guest_phys_addr; + __u64 memory_size; + __u64 userspace_addr; + }; + +This ioctl allows the user to create or delete a memory parcel for a guest +virtual machine. Each memory region is uniquely identified by a label; +attempting to create two regions with the same label is not allowed. + +While VMM is guest-agnostic and allows runtime addition of memory regions, +Linux guest virtual machines do not support accepting memory regions at runtime. +Thus, memory regions should be provided before starting the VM and the VM must +be configured to accept these at boot-up. + +The guest physical address is used by Linux kernel to check that the requested +user regions do not overlap and to help find the corresponding memory region +for calls like GH_VM_SET_DTB_CONFIG. + +To delete a memory region, call GH_VM_SET_USER_MEM_REGION with label set to the +desired region and memory_size set to 0. + +The flags field of gh_userspace_memory_region accepts the following bits. All +other bits must be 0 and are reserved for future use. The ioctl will return +-EINVAL if an unsupported bit is detected. + + - GH_MEM_ALLOW_READ/GH_MEM_ALLOW_WRITE/GH_MEM_ALLOW_EXEC sets read/write/exec + permissions for the guest, respectively. + - GH_MEM_LENT means that the memory will be unmapped from the host and be + unaccessible by the host while the guest has the region. + +GH_VM_SET_DTB_CONFIG +~~~~~~~~~~~~~~~~~~~~ + +:: + + struct gh_vm_dtb_config { + __u64 gpa; + __u64 size; + }; + +This ioctl sets the location of the VM's devicetree blob and is used by Gunyah +Resource Manager to allocate resources. + +GH_VM_START +~~~~~~~~~~~ + +This ioctl starts the VM. -- 2.25.1
WARNING: multiple messages have this Message-ID (diff)
From: Elliot Berman <quic_eberman@quicinc.com> To: Bjorn Andersson <quic_bjorande@quicinc.com>, Jonathan Corbet <corbet@lwn.net>, Bagas Sanjaya <bagasdotme@gmail.com>, Elliot Berman <quic_eberman@quicinc.com>, Murali Nalajala <quic_mnalajal@quicinc.com> Cc: Trilok Soni <quic_tsoni@quicinc.com>, Srivatsa Vaddagiri <quic_svaddagi@quicinc.com>, Carl van Schaik <quic_cvanscha@quicinc.com>, Prakruthi Deepak Heragu <quic_pheragu@quicinc.com>, Arnd Bergmann <arnd@arndb.de>, Greg Kroah-Hartman <gregkh@linuxfoundation.org>, Rob Herring <robh+dt@kernel.org>, Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>, Catalin Marinas <catalin.marinas@arm.com>, Will Deacon <will@kernel.org>, Jassi Brar <jassisinghbrar@gmail.com>, Sudeep Holla <sudeep.holla@arm.com>, Mark Rutland <mark.rutland@arm.com>, Lorenzo Pieralisi <lpieralisi@kernel.org>, "Dmitry Baryshkov" <dmitry.baryshkov@linaro.org>, <linux-arm-msm@vger.kernel.org>, <devicetree@vger.kernel.org>, <linux-kernel@vger.kernel.org>, <linux-doc@vger.kernel.org>, <linux-arm-kernel@lists.infradead.org>, <linux-acpi@vger.kernel.org> Subject: [PATCH v8 20/28] docs: gunyah: Document Gunyah VM Manager Date: Mon, 19 Dec 2022 14:58:41 -0800 [thread overview] Message-ID: <20221219225850.2397345-21-quic_eberman@quicinc.com> (raw) In-Reply-To: <20221219225850.2397345-1-quic_eberman@quicinc.com> Document the ioctls and usage of Gunyah VM Manager driver. Signed-off-by: Elliot Berman <quic_eberman@quicinc.com> --- Documentation/virt/gunyah/index.rst | 1 + Documentation/virt/gunyah/vm-manager.rst | 100 +++++++++++++++++++++++ 2 files changed, 101 insertions(+) create mode 100644 Documentation/virt/gunyah/vm-manager.rst diff --git a/Documentation/virt/gunyah/index.rst b/Documentation/virt/gunyah/index.rst index fbadbdd24da7..9019a03b6f3e 100644 --- a/Documentation/virt/gunyah/index.rst +++ b/Documentation/virt/gunyah/index.rst @@ -7,6 +7,7 @@ Gunyah Hypervisor .. toctree:: :maxdepth: 1 + vm-manager message-queue Gunyah is a Type-1 hypervisor which is independent of any OS kernel, and runs in diff --git a/Documentation/virt/gunyah/vm-manager.rst b/Documentation/virt/gunyah/vm-manager.rst new file mode 100644 index 000000000000..62513af09cbf --- /dev/null +++ b/Documentation/virt/gunyah/vm-manager.rst @@ -0,0 +1,100 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================= +Virtual Machine Manager +======================= + +The Gunyah Virtual Machine Manager is a Linux driver to support launching +virtual machines using Gunyah. It presently supports launching non-proxy +scheduled Linux-like virtual machines. + +Except for some basic information about the location of initial binaries, +most of the configuration about a Gunyah virtual machine is described in the +VM's devicetree. The devicetree is generated by userspace. Interacting with the +virtual machine is still done via the kernel and VM configuration requires some +of the corresponding functionality to be set up in the kernel. For instance, +sharing userspace memory with a VM is done via the GH_VM_SET_USER_MEM_REGION +ioctl. The VM itself is configured to use the memory region via the +devicetree. + +Sample Userspace VMM +==================== + +A sample userspace VMM is included in samples/gunyah/ along with a minimal +devicetree that can be used to launch a VM. To build this sample, enable +CONFIG_SAMPLE_GUNYAH. + +IOCTLs and userspace VMM flows +============================== + +The kernel exposes a char device interface at /dev/gunyah. + +To create a VM, use the GH_CREATE_VM ioctl. A successful call will return a +"Gunyah VM" file descriptor. + +/dev/gunyah API Descriptions +---------------------------- + +GH_CREATE_VM +~~~~~~~~~~~~ + +Creates a Gunyah VM. The argument is reserved for future use and must be 0. + +Gunyah VM API Descriptions +-------------------------- + +GH_VM_SET_USER_MEM_REGION +~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + struct gh_userspace_memory_region { + __u32 label; + __u32 flags; + __u64 guest_phys_addr; + __u64 memory_size; + __u64 userspace_addr; + }; + +This ioctl allows the user to create or delete a memory parcel for a guest +virtual machine. Each memory region is uniquely identified by a label; +attempting to create two regions with the same label is not allowed. + +While VMM is guest-agnostic and allows runtime addition of memory regions, +Linux guest virtual machines do not support accepting memory regions at runtime. +Thus, memory regions should be provided before starting the VM and the VM must +be configured to accept these at boot-up. + +The guest physical address is used by Linux kernel to check that the requested +user regions do not overlap and to help find the corresponding memory region +for calls like GH_VM_SET_DTB_CONFIG. + +To delete a memory region, call GH_VM_SET_USER_MEM_REGION with label set to the +desired region and memory_size set to 0. + +The flags field of gh_userspace_memory_region accepts the following bits. All +other bits must be 0 and are reserved for future use. The ioctl will return +-EINVAL if an unsupported bit is detected. + + - GH_MEM_ALLOW_READ/GH_MEM_ALLOW_WRITE/GH_MEM_ALLOW_EXEC sets read/write/exec + permissions for the guest, respectively. + - GH_MEM_LENT means that the memory will be unmapped from the host and be + unaccessible by the host while the guest has the region. + +GH_VM_SET_DTB_CONFIG +~~~~~~~~~~~~~~~~~~~~ + +:: + + struct gh_vm_dtb_config { + __u64 gpa; + __u64 size; + }; + +This ioctl sets the location of the VM's devicetree blob and is used by Gunyah +Resource Manager to allocate resources. + +GH_VM_START +~~~~~~~~~~~ + +This ioctl starts the VM. -- 2.25.1 _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
next prev parent reply other threads:[~2022-12-19 23:07 UTC|newest] Thread overview: 137+ messages / expand[flat|nested] mbox.gz Atom feed top 2022-12-19 22:58 [PATCH v8 00/28] Drivers for gunyah hypervisor Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2022-12-19 22:58 ` [PATCH v8 01/28] docs: gunyah: Introduce Gunyah Hypervisor Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2023-01-09 21:34 ` Alex Elder 2023-01-09 21:34 ` Alex Elder 2023-01-10 17:54 ` Elliot Berman 2023-01-10 17:54 ` Elliot Berman 2022-12-19 22:58 ` [PATCH v8 02/28] dt-bindings: Add binding for gunyah hypervisor Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2023-01-09 21:34 ` Alex Elder 2023-01-09 21:34 ` Alex Elder 2022-12-19 22:58 ` [PATCH v8 03/28] gunyah: Common types and error codes for Gunyah hypercalls Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2023-01-09 21:34 ` Alex Elder 2023-01-09 21:34 ` Alex Elder 2023-01-10 17:55 ` Elliot Berman 2023-01-10 17:55 ` Elliot Berman 2022-12-19 22:58 ` [PATCH v8 04/28] arm64: smccc: Include alternative-macros.h Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2023-01-09 21:34 ` Alex Elder 2023-01-09 21:34 ` Alex Elder 2023-01-10 22:55 ` Elliot Berman 2023-01-10 22:55 ` Elliot Berman 2022-12-19 22:58 ` [PATCH v8 05/28] virt: gunyah: Add hypercalls to identify Gunyah Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2023-01-09 21:34 ` Alex Elder 2023-01-09 21:34 ` Alex Elder 2023-01-10 17:56 ` Elliot Berman 2023-01-10 17:56 ` Elliot Berman 2023-01-17 19:20 ` Alex Elder 2023-01-17 19:20 ` Alex Elder 2023-01-17 19:20 ` Alex Elder 2023-01-17 19:20 ` Alex Elder 2023-01-17 22:29 ` Elliot Berman 2023-01-17 22:29 ` Elliot Berman 2022-12-19 22:58 ` [PATCH v8 06/28] virt: gunyah: Identify hypervisor version Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2023-01-09 21:34 ` Alex Elder 2023-01-09 21:34 ` Alex Elder 2023-01-10 17:56 ` Elliot Berman 2023-01-10 17:56 ` Elliot Berman 2023-01-17 19:21 ` Alex Elder 2023-01-17 19:21 ` Alex Elder 2023-01-17 22:29 ` Elliot Berman 2023-01-17 22:29 ` Elliot Berman 2022-12-19 22:58 ` [PATCH v8 07/28] mailbox: Allow direct registration to a channel Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2023-01-09 21:34 ` Alex Elder 2023-01-09 21:34 ` Alex Elder 2023-01-10 17:57 ` Elliot Berman 2023-01-10 17:57 ` Elliot Berman 2023-01-17 19:21 ` Alex Elder 2023-01-17 19:21 ` Alex Elder 2022-12-19 22:58 ` [PATCH v8 08/28] virt: gunyah: msgq: Add hypercalls to send and receive messages Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2022-12-19 22:58 ` [PATCH v8 09/28] mailbox: Add Gunyah message queue mailbox Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2023-01-02 6:13 ` Srivatsa Vaddagiri 2023-01-02 6:13 ` Srivatsa Vaddagiri 2023-01-04 0:32 ` Elliot Berman 2023-01-04 0:32 ` Elliot Berman 2023-01-09 21:34 ` Alex Elder 2023-01-09 21:34 ` Alex Elder 2023-01-10 18:16 ` Elliot Berman 2023-01-10 18:16 ` Elliot Berman 2023-01-17 19:21 ` Alex Elder 2023-01-17 19:21 ` Alex Elder 2022-12-19 22:58 ` [PATCH v8 10/28] gunyah: rsc_mgr: Add resource manager RPC core Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2023-01-17 22:33 ` Alex Elder 2023-01-17 22:33 ` Alex Elder 2023-01-20 23:18 ` Elliot Berman 2023-01-20 23:18 ` Elliot Berman 2022-12-19 22:58 ` [PATCH v8 11/28] gunyah: rsc_mgr: Add VM lifecycle RPC Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2023-01-09 7:13 ` Srivatsa Vaddagiri 2023-01-09 7:13 ` Srivatsa Vaddagiri 2023-01-09 18:51 ` Elliot Berman 2023-01-09 18:51 ` Elliot Berman 2023-01-18 18:26 ` Alex Elder 2023-01-18 18:26 ` Alex Elder 2023-01-20 1:31 ` Elliot Berman 2023-01-20 1:31 ` Elliot Berman 2022-12-19 22:58 ` [PATCH v8 12/28] gunyah: vm_mgr: Introduce basic VM Manager Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2023-01-09 9:05 ` Srivatsa Vaddagiri 2023-01-09 9:05 ` Srivatsa Vaddagiri 2023-01-09 19:38 ` Elliot Berman 2023-01-09 19:38 ` Elliot Berman 2022-12-19 22:58 ` [PATCH v8 13/28] gunyah: rsc_mgr: Add RPC for sharing memory Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2023-01-16 8:45 ` Srivatsa Vaddagiri 2023-01-16 8:45 ` Srivatsa Vaddagiri 2022-12-19 22:58 ` [PATCH v8 14/28] gunyah: vm_mgr: Add/remove user memory regions Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2023-01-20 5:34 ` Srivatsa Vaddagiri 2023-01-20 5:34 ` Srivatsa Vaddagiri 2022-12-19 22:58 ` [PATCH v8 15/28] gunyah: vm_mgr: Add ioctls to support basic non-proxy VM boot Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2022-12-19 22:58 ` [PATCH v8 16/28] samples: Add sample userspace Gunyah VM Manager Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2022-12-19 22:58 ` [PATCH v8 17/28] gunyah: rsc_mgr: Add platform ops on mem_lend/mem_reclaim Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2022-12-19 22:58 ` [PATCH v8 18/28] firmware: qcom_scm: Use fixed width src vm bitmap Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2022-12-19 22:58 ` [PATCH v8 19/28] firmware: qcom_scm: Register Gunyah platform ops Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2022-12-23 17:21 ` kernel test robot 2022-12-19 22:58 ` Elliot Berman [this message] 2022-12-19 22:58 ` [PATCH v8 20/28] docs: gunyah: Document Gunyah VM Manager Elliot Berman 2022-12-19 22:58 ` [PATCH v8 21/28] virt: gunyah: Translate gh_rm_hyp_resource into gunyah_resource Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2022-12-19 22:58 ` [PATCH v8 22/28] gunyah: vm_mgr: Add framework to add VM Functions Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2022-12-19 22:58 ` [PATCH v8 23/28] virt: gunyah: Add resource tickets Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2022-12-19 22:58 ` [PATCH v8 24/28] virt: gunyah: Add IO handlers Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2022-12-19 22:58 ` [PATCH v8 25/28] virt: gunyah: Add proxy-scheduled vCPUs Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2022-12-19 22:58 ` [PATCH v8 26/28] virt: gunyah: Add hypercalls for sending doorbell Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2022-12-19 22:58 ` [PATCH v8 27/28] virt: gunyah: Add irqfd interface Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2022-12-21 17:00 ` kernel test robot 2022-12-19 22:58 ` [PATCH v8 28/28] virt: gunyah: Add ioeventfd Elliot Berman 2022-12-19 22:58 ` Elliot Berman 2023-01-09 21:34 ` [PATCH v8 00/28] Drivers for gunyah hypervisor Alex Elder 2023-01-09 21:34 ` Alex Elder 2023-01-10 17:54 ` Elliot Berman 2023-01-10 17:54 ` Elliot Berman 2023-01-10 21:47 ` Elliot Berman 2023-01-10 21:47 ` Elliot Berman 2023-01-17 19:20 ` Alex Elder 2023-01-17 19:20 ` Alex Elder
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20221219225850.2397345-21-quic_eberman@quicinc.com \ --to=quic_eberman@quicinc.com \ --cc=arnd@arndb.de \ --cc=bagasdotme@gmail.com \ --cc=catalin.marinas@arm.com \ --cc=corbet@lwn.net \ --cc=devicetree@vger.kernel.org \ --cc=dmitry.baryshkov@linaro.org \ --cc=gregkh@linuxfoundation.org \ --cc=jassisinghbrar@gmail.com \ --cc=krzysztof.kozlowski+dt@linaro.org \ --cc=linux-acpi@vger.kernel.org \ --cc=linux-arm-kernel@lists.infradead.org \ --cc=linux-arm-msm@vger.kernel.org \ --cc=linux-doc@vger.kernel.org \ --cc=linux-kernel@vger.kernel.org \ --cc=lpieralisi@kernel.org \ --cc=mark.rutland@arm.com \ --cc=quic_bjorande@quicinc.com \ --cc=quic_cvanscha@quicinc.com \ --cc=quic_mnalajal@quicinc.com \ --cc=quic_pheragu@quicinc.com \ --cc=quic_svaddagi@quicinc.com \ --cc=quic_tsoni@quicinc.com \ --cc=robh+dt@kernel.org \ --cc=sudeep.holla@arm.com \ --cc=will@kernel.org \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.