Nuno Das Neves <nunodasneves@xxxxxxxxxxxxxxxxxxx> writes: > 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 <nunodasneves@xxxxxxxxxxxxxxxxxxx> > --- > .../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 <mailto:linux-remoteproc@xxxxxxxxxxxxxxx> > 0xB6 all linux/fpga-dfl.h > 0xB7 all uapi/linux/remoteproc_cdev.h <mailto:linux-remoteproc@xxxxxxxxxxxxxxx> > +0xB8 all uapi/linux/mshv.h Microsoft Hypervisor root partition APIs > + <mailto:linux-hyperv@xxxxxxxxxxxxxxx> > 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. > + KVM used to have KVM_GET_API_VERSION too but this turned out to be not very convenient so we use capabilities (KVM_CHECK_EXTENSION/KVM_ENABLE_CAP) instead. > 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 <uapi/linux/mshv.h> > + > +#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 <linux/types.h> > + > +#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 <linux/module.h> > #include <linux/fs.h> > #include <linux/miscdevice.h> > +#include <linux/slab.h> > +#include <linux/mshv.h> > > MODULE_AUTHOR("Microsoft"); > MODULE_LICENSE("GPL"); > > +#define MSHV_INVALID_VERSION 0xFFFFFFFF > +#define MSHV_CURRENT_VERSION MSHV_VERSION > + > +static u32 supported_versions[] = { > + MSHV_CURRENT_VERSION, > +}; > + > +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; > } -- Vitaly
