From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-24.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,NICE_REPLY_A,SPF_HELO_NONE,SPF_PASS, USER_AGENT_SANE_1,USER_IN_DEF_DKIM_WL autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id EAE16C433E9 for ; Thu, 4 Mar 2021 21:37:41 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id C3A3F64FF4 for ; Thu, 4 Mar 2021 21:37:41 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S239832AbhCDVhK (ORCPT ); Thu, 4 Mar 2021 16:37:10 -0500 Received: from linux.microsoft.com ([13.77.154.182]:56800 "EHLO linux.microsoft.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S237752AbhCDVgk (ORCPT ); Thu, 4 Mar 2021 16:36:40 -0500 Received: from [10.0.0.178] (c-67-168-106-253.hsd1.wa.comcast.net [67.168.106.253]) by linux.microsoft.com (Postfix) with ESMTPSA id B046B20B83EA; Thu, 4 Mar 2021 13:35:59 -0800 (PST) DKIM-Filter: OpenDKIM Filter v2.11.0 linux.microsoft.com B046B20B83EA DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linux.microsoft.com; s=default; t=1614893759; bh=7mhngE8I/BbA3nTURuQYFVGs1sytzgPZq5C1GiVHzZI=; h=Subject:To:Cc:References:From:Date:In-Reply-To:From; b=TFSa9t/GFns08kzCTRG5KFgjlScburuHwonCqXjyv50X7Z50Kqg6vNwldhFFt6BQP gjTdOF09uGI5wnAzB2lPJpzK8cMZeV2miFArvyRS3isMH7vAnLTi8D9OHBFZLiUMPt CEipZ3OTvkfVBGiCaoB6lRV0uHmFztXmhFrNdKs8= Subject: Re: [RFC PATCH 04/18] virt/mshv: request version ioctl To: Michael Kelley , "linux-hyperv@vger.kernel.org" Cc: "virtualization@lists.linux-foundation.org" , "linux-kernel@vger.kernel.org" , "viremana@linux.microsoft.com" , Sunil Muthuswamy , "wei.liu@kernel.org" , Lillian Grassin-Drake , KY Srinivasan References: <1605918637-12192-1-git-send-email-nunodasneves@linux.microsoft.com> <1605918637-12192-5-git-send-email-nunodasneves@linux.microsoft.com> From: Nuno Das Neves Message-ID: Date: Thu, 4 Mar 2021 13:35:59 -0800 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:78.0) Gecko/20100101 Thunderbird/78.8.0 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On 2/8/2021 11:41 AM, Michael Kelley wrote: > From: Nuno Das Neves Sent: Friday, November 20, 2020 4:30 PM >> >> Reserve ioctl number in userpsace-api/ioctl/ioctl-number.rst >> Introduce MSHV_REQUEST_VERSION ioctl. >> Introduce documentation for /dev/mshv in Documentation/virt/mshv >> >> Signed-off-by: Nuno Das Neves >> --- >> .../userspace-api/ioctl/ioctl-number.rst | 2 + >> Documentation/virt/mshv/api.rst | 62 +++++++++++++++++++ >> include/linux/mshv.h | 11 ++++ >> include/uapi/linux/mshv.h | 19 ++++++ >> virt/mshv/mshv_main.c | 49 +++++++++++++++ >> 5 files changed, 143 insertions(+) >> create mode 100644 Documentation/virt/mshv/api.rst >> create mode 100644 include/linux/mshv.h >> create mode 100644 include/uapi/linux/mshv.h >> >> diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst >> b/Documentation/userspace-api/ioctl/ioctl-number.rst >> index 55a2d9b2ce33..13a4d3ecafca 100644 >> --- a/Documentation/userspace-api/ioctl/ioctl-number.rst >> +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst >> @@ -343,6 +343,8 @@ Code Seq# Include File Comments >> 0xB5 00-0F uapi/linux/rpmsg.h > remoteproc@vger.kernel.org> >> 0xB6 all linux/fpga-dfl.h >> 0xB7 all uapi/linux/remoteproc_cdev.h > remoteproc@vger.kernel.org> >> +0xB8 all uapi/linux/mshv.h Microsoft Hypervisor root partition APIs >> + >> 0xC0 00-0F linux/usb/iowarrior.h >> 0xCA 00-0F uapi/misc/cxl.h >> 0xCA 10-2F uapi/misc/ocxl.h >> diff --git a/Documentation/virt/mshv/api.rst b/Documentation/virt/mshv/api.rst >> new file mode 100644 >> index 000000000000..82e32de48d03 >> --- /dev/null >> +++ b/Documentation/virt/mshv/api.rst >> @@ -0,0 +1,62 @@ >> +.. SPDX-License-Identifier: GPL-2.0 >> + >> +===================================================== >> +Microsoft Hypervisor Root Partition API Documentation >> +===================================================== >> + >> +1. Overview >> +=========== >> + >> +This document describes APIs for creating and managing guest virtual machines >> +when running Linux as the root partition on the Microsoft Hypervisor. >> + >> +This API is not yet stable. >> + >> +2. Glossary/Terms >> +================= >> + >> +hv >> +-- >> +Short for Hyper-V. This name is used in the kernel to describe interfaces to >> +the Microsoft Hypervisor. >> + >> +mshv >> +---- >> +Short for Microsoft Hypervisor. This is the name of the userland API module >> +described in this document. >> + >> +Partition >> +--------- >> +A virtual machine running on the Microsoft Hypervisor. >> + >> +Root Partition >> +-------------- >> +The partition that is created and assumes control when the machine boots. The >> +root partition can use mshv APIs to create guest partitions. >> + >> +3. API description >> +================== >> + >> +The module is named mshv and can be configured with CONFIG_HYPERV_ROOT_API. >> + >> +Mshv is file descriptor-based, following a similar pattern to KVM. >> + >> +To get a handle to the mshv driver, use open("/dev/mshv"). >> + >> +3.1 MSHV_REQUEST_VERSION >> +------------------------ >> +:Type: /dev/mshv ioctl >> +:Parameters: pointer to a u32 >> +:Returns: 0 on success >> + >> +Before issuing any other ioctls, a MSHV_REQUEST_VERSION ioctl must be called to >> +establish the interface version with the kernel module. >> + >> +The caller should pass the MSHV_VERSION as an argument. >> + >> +The kernel module will check which interface versions it supports and return 0 >> +if one of them matches. >> + >> +This /dev/mshv file descriptor will remain 'locked' to that version as long as >> +it is open - this ioctl can only be called once per open. > > To clarify the wording: > > The caller should pass the requested version as an argument. If the requested > version is one that the kernel module supports, the ioctl will return 0. If the > requested version is not supported by the kernel module, the caller may try > the ioctl repeatedly to find a version that the caller supports and that the kernel > module supports. Once a match is found, the /dev/mshv file descriptor is > 'locked' to that version as long as it is open; i.e., the ioctl can succeed > only once per open. > Thanks, yes that's a bit clearer! >> + >> diff --git a/include/linux/mshv.h b/include/linux/mshv.h >> new file mode 100644 >> index 000000000000..a0982fe2c0b8 >> --- /dev/null >> +++ b/include/linux/mshv.h >> @@ -0,0 +1,11 @@ >> +/* SPDX-License-Identifier: GPL-2.0-only */ >> +#ifndef _LINUX_MSHV_H >> +#define _LINUX_MSHV_H >> + >> +/* >> + * Microsoft Hypervisor root partition driver for /dev/mshv >> + */ >> + >> +#include >> + >> +#endif >> diff --git a/include/uapi/linux/mshv.h b/include/uapi/linux/mshv.h >> new file mode 100644 >> index 000000000000..dd30fc2f0a80 >> --- /dev/null >> +++ b/include/uapi/linux/mshv.h >> @@ -0,0 +1,19 @@ >> +/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */ >> +#ifndef _UAPI_LINUX_MSHV_H >> +#define _UAPI_LINUX_MSHV_H >> + >> +/* >> + * Userspace interface for /dev/mshv >> + * Microsoft Hypervisor root partition APIs >> + */ >> + >> +#include >> + >> +#define MSHV_VERSION 0x0 >> + >> +#define MSHV_IOCTL 0xB8 >> + >> +/* mshv device */ >> +#define MSHV_REQUEST_VERSION _IOW(MSHV_IOCTL, 0x00, __u32) >> + >> +#endif >> diff --git a/virt/mshv/mshv_main.c b/virt/mshv/mshv_main.c >> index ecb9089761fe..62f631f85301 100644 >> --- a/virt/mshv/mshv_main.c >> +++ b/virt/mshv/mshv_main.c >> @@ -11,25 +11,74 @@ >> #include >> #include >> #include >> +#include >> +#include >> >> MODULE_AUTHOR("Microsoft"); >> MODULE_LICENSE("GPL"); >> >> +#define MSHV_INVALID_VERSION 0xFFFFFFFF >> +#define MSHV_CURRENT_VERSION MSHV_VERSION >> + >> +static u32 supported_versions[] = { >> + MSHV_CURRENT_VERSION, >> +}; > > I'm not sure that the concept of "CURRENT_VERSION" makes sense > as a fixed constant. We have an array of supported versions, any of > which are valid and supported by the kernel module. The array > should list individual versions. The current version is 0, which > might be labelled as MSHV_VERSION_PRERELEASE, or something > similar. Then later we might have MSHV_VERSION_RELEASE_1, > HSMV_VERSION_RELEASE_2, as needed. Or maybe the versions > are tied to releases of the Microsoft Hypervisor. > The idea was that CURRENT_VERSION matches the version in the shared header file, which would change each release. I can see how this would be confusing - I will change it as you suggest. >> + >> +static long >> +mshv_ioctl_request_version(u32 *version, void __user *user_arg) >> +{ >> + u32 arg; >> + int i; >> + >> + if (copy_from_user(&arg, user_arg, sizeof(arg))) >> + return -EFAULT; >> + >> + for (i = 0; i < ARRAY_SIZE(supported_versions); ++i) { >> + if (supported_versions[i] == arg) { >> + *version = supported_versions[i]; >> + return 0; >> + } >> + } >> + return -ENOTSUPP; >> +} >> + >> static long >> mshv_dev_ioctl(struct file *filp, unsigned int ioctl, unsigned long arg) >> { >> + u32 *version = (u32 *)filp->private_data; >> + >> + if (ioctl == MSHV_REQUEST_VERSION) { >> + /* Version can only be set once */ >> + if (*version != MSHV_INVALID_VERSION) >> + return -EBADFD; >> + >> + return mshv_ioctl_request_version(version, (void __user *)arg); >> + } >> + >> + /* Version must be set before other ioctls can be called */ >> + if (*version == MSHV_INVALID_VERSION) >> + return -EBADFD; >> + >> + /* TODO other ioctls */ >> + >> return -ENOTTY; >> } >> >> static int >> mshv_dev_open(struct inode *inode, struct file *filp) >> { >> + filp->private_data = kmalloc(sizeof(u32), GFP_KERNEL); >> + if (!filp->private_data) >> + return -ENOMEM; >> + *(u32 *)filp->private_data = MSHV_INVALID_VERSION; >> + >> return 0; >> } >> >> static int >> mshv_dev_release(struct inode *inode, struct file *filp) >> { >> + kfree(filp->private_data); >> return 0; >> } >> >> -- >> 2.25.1