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>, <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 v7 20/20] docs: gunyah: Document Gunyah VM Manager Date: Mon, 21 Nov 2022 06:00:09 -0800 [thread overview] Message-ID: <20221121140009.2353512-21-quic_eberman@quicinc.com> (raw) In-Reply-To: <20221121140009.2353512-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 | 91 ++++++++++++++++++++++++ 2 files changed, 92 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..16fb2b98c371 --- /dev/null +++ b/Documentation/virt/gunyah/vm-manager.rst @@ -0,0 +1,91 @@ +.. 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. + +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>, <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 v7 20/20] docs: gunyah: Document Gunyah VM Manager Date: Mon, 21 Nov 2022 06:00:09 -0800 [thread overview] Message-ID: <20221121140009.2353512-21-quic_eberman@quicinc.com> (raw) In-Reply-To: <20221121140009.2353512-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 | 91 ++++++++++++++++++++++++ 2 files changed, 92 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..16fb2b98c371 --- /dev/null +++ b/Documentation/virt/gunyah/vm-manager.rst @@ -0,0 +1,91 @@ +.. 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. + +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-11-21 14:06 UTC|newest] Thread overview: 66+ messages / expand[flat|nested] mbox.gz Atom feed top 2022-11-21 13:59 [PATCH v7 00/20] Drivers for gunyah hypervisor Elliot Berman 2022-11-21 13:59 ` Elliot Berman 2022-11-21 13:59 ` [PATCH v7 01/20] docs: gunyah: Introduce Gunyah Hypervisor Elliot Berman 2022-11-21 13:59 ` Elliot Berman 2022-11-21 13:59 ` [PATCH v7 02/20] dt-bindings: Add binding for gunyah hypervisor Elliot Berman 2022-11-21 13:59 ` Elliot Berman 2022-12-05 19:42 ` Rob Herring 2022-12-05 19:42 ` Rob Herring 2022-11-21 13:59 ` [PATCH v7 03/20] gunyah: Common types and error codes for Gunyah hypercalls Elliot Berman 2022-11-21 13:59 ` Elliot Berman 2022-11-21 13:59 ` [PATCH v7 04/20] arm64: smccc: Include alternative-macros.h Elliot Berman 2022-11-21 13:59 ` Elliot Berman 2022-11-21 13:59 ` [PATCH v7 05/20] virt: gunyah: Add hypercalls to identify Gunyah Elliot Berman 2022-11-21 13:59 ` Elliot Berman 2022-11-21 13:59 ` [PATCH v7 06/20] virt: gunyah: Identify hypervisor version Elliot Berman 2022-11-21 13:59 ` Elliot Berman 2022-11-21 13:59 ` [PATCH v7 07/20] mailbox: Allow direct registration to a channel Elliot Berman 2022-11-21 13:59 ` Elliot Berman 2022-11-22 4:34 ` kernel test robot 2022-11-21 13:59 ` [PATCH v7 08/20] virt: gunyah: msgq: Add hypercalls to send and receive messages Elliot Berman 2022-11-21 13:59 ` Elliot Berman 2022-11-21 13:59 ` [PATCH v7 09/20] mailbox: Add Gunyah message queue mailbox Elliot Berman 2022-11-21 13:59 ` Elliot Berman 2022-11-21 13:59 ` [PATCH v7 10/20] gunyah: rsc_mgr: Add resource manager RPC core Elliot Berman 2022-11-21 13:59 ` Elliot Berman 2022-11-21 15:23 ` Greg Kroah-Hartman 2022-11-21 15:23 ` Greg Kroah-Hartman 2022-12-12 23:46 ` Elliot Berman 2022-12-12 23:46 ` Elliot Berman 2022-12-13 6:25 ` Greg Kroah-Hartman 2022-12-13 6:25 ` Greg Kroah-Hartman 2022-11-21 15:24 ` Greg Kroah-Hartman 2022-11-21 15:24 ` Greg Kroah-Hartman 2022-12-12 23:46 ` Elliot Berman 2022-12-12 23:46 ` Elliot Berman 2022-12-13 6:26 ` Greg Kroah-Hartman 2022-12-13 6:26 ` Greg Kroah-Hartman 2022-12-16 2:25 ` Elliot Berman 2022-12-16 2:25 ` Elliot Berman 2023-01-26 21:27 ` Elliot Berman 2023-01-26 21:27 ` Elliot Berman 2022-11-21 14:00 ` [PATCH v7 11/20] gunyah: rsc_mgr: Add VM lifecycle RPC Elliot Berman 2022-11-21 14:00 ` Elliot Berman 2022-11-21 14:00 ` [PATCH v7 12/20] gunyah: vm_mgr: Introduce basic VM Manager Elliot Berman 2022-11-21 14:00 ` Elliot Berman 2022-11-21 14:00 ` [PATCH v7 13/20] gunyah: rsc_mgr: Add RPC for sharing memory Elliot Berman 2022-11-21 14:00 ` Elliot Berman 2022-11-21 14:00 ` [PATCH v7 14/20] gunyah: vm_mgr: Add/remove user memory regions Elliot Berman 2022-11-21 14:00 ` Elliot Berman 2022-11-21 14:00 ` [PATCH v7 15/20] gunyah: vm_mgr: Add ioctls to support basic non-proxy VM boot Elliot Berman 2022-11-21 14:00 ` Elliot Berman 2022-11-21 14:00 ` [PATCH v7 16/20] samples: Add sample userspace Gunyah VM Manager Elliot Berman 2022-11-21 14:00 ` Elliot Berman 2022-11-21 14:00 ` [PATCH v7 17/20] gunyah: rsc_mgr: Add platform ops on mem_lend/mem_reclaim Elliot Berman 2022-11-21 14:00 ` Elliot Berman 2022-11-21 14:00 ` [PATCH v7 18/20] firmware: qcom_scm: Use fixed width src vm bitmap Elliot Berman 2022-11-21 14:00 ` Elliot Berman 2022-11-21 14:00 ` Elliot Berman 2022-11-21 15:59 ` Kalle Valo 2022-11-21 15:59 ` Kalle Valo 2022-11-21 15:59 ` Kalle Valo 2022-11-21 14:00 ` [PATCH v7 19/20] firmware: qcom_scm: Register Gunyah platform ops Elliot Berman 2022-11-21 14:00 ` Elliot Berman 2022-12-02 16:55 ` kernel test robot 2022-11-21 14:00 ` Elliot Berman [this message] 2022-11-21 14:00 ` [PATCH v7 20/20] docs: gunyah: Document Gunyah VM Manager Elliot Berman
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=20221121140009.2353512-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=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.