uapi/xen/gntdev.h

0001 /* SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR MIT) */
0002 /******************************************************************************
0003  * gntdev.h
0004  *
0005  * Interface to /dev/xen/gntdev.
0006  *
0007  * Copyright (c) 2007, D G Murray
0008  * Copyright (c) 2018, Oleksandr Andrushchenko, EPAM Systems Inc.
0009  *
0010  * This program is free software; you can redistribute it and/or
0011  * modify it under the terms of the GNU General Public License version 2
0012  * as published by the Free Software Foundation; or, when distributed
0013  * separately from the Linux kernel or incorporated into other
0014  * software packages, subject to the following license:
0015  *
0016  * Permission is hereby granted, free of charge, to any person obtaining a copy
0017  * of this source file (the "Software"), to deal in the Software without
0018  * restriction, including without limitation the rights to use, copy, modify,
0019  * merge, publish, distribute, sublicense, and/or sell copies of the Software,
0020  * and to permit persons to whom the Software is furnished to do so, subject to
0021  * the following conditions:
0022  *
0023  * The above copyright notice and this permission notice shall be included in
0024  * all copies or substantial portions of the Software.
0025  *
0026  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
0027  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
0028  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
0029  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
0030  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
0031  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
0032  * IN THE SOFTWARE.
0033  */
0034
0035 #ifndef __LINUX_PUBLIC_GNTDEV_H__
0036 #define __LINUX_PUBLIC_GNTDEV_H__
0037
0038 #include <linux/types.h>
0039
0040 struct ioctl_gntdev_grant_ref {
0041     /* The domain ID of the grant to be mapped. */
0042     __u32 domid;
0043     /* The grant reference of the grant to be mapped. */
0044     __u32 ref;
0045 };
0046
0047 /*
0048  * Inserts the grant references into the mapping table of an instance
0049  * of gntdev. N.B. This does not perform the mapping, which is deferred
0050  * until mmap() is called with @index as the offset. @index should be
0051  * considered opaque to userspace, with one exception: if no grant
0052  * references have ever been inserted into the mapping table of this
0053  * instance, @index will be set to 0. This is necessary to use gntdev
0054  * with userspace APIs that expect a file descriptor that can be
0055  * mmap()'d at offset 0, such as Wayland. If @count is set to 0, this
0056  * ioctl will fail.
0057  */
0058 #define IOCTL_GNTDEV_MAP_GRANT_REF \
0059 _IOC(_IOC_NONE, 'G', 0, sizeof(struct ioctl_gntdev_map_grant_ref))
0060 struct ioctl_gntdev_map_grant_ref {
0061     /* IN parameters */
0062     /* The number of grants to be mapped. */
0063     __u32 count;
0064     __u32 pad;
0065     /* OUT parameters */
0066     /* The offset to be used on a subsequent call to mmap(). */
0067     __u64 index;
0068     /* Variable IN parameter. */
0069     /* Array of grant references, of size @count. */
0070     struct ioctl_gntdev_grant_ref refs[1];
0071 };
0072
0073 /*
0074  * Removes the grant references from the mapping table of an instance of
0075  * gntdev. N.B. munmap() must be called on the relevant virtual address(es)
0076  * before this ioctl is called, or an error will result.
0077  */
0078 #define IOCTL_GNTDEV_UNMAP_GRANT_REF \
0079 _IOC(_IOC_NONE, 'G', 1, sizeof(struct ioctl_gntdev_unmap_grant_ref))
0080 struct ioctl_gntdev_unmap_grant_ref {
0081     /* IN parameters */
0082     /* The offset was returned by the corresponding map operation. */
0083     __u64 index;
0084     /* The number of pages to be unmapped. */
0085     __u32 count;
0086     __u32 pad;
0087 };
0088
0089 /*
0090  * Returns the offset in the driver's address space that corresponds
0091  * to @vaddr. This can be used to perform a munmap(), followed by an
0092  * UNMAP_GRANT_REF ioctl, where no state about the offset is retained by
0093  * the caller. The number of pages that were allocated at the same time as
0094  * @vaddr is returned in @count.
0095  *
0096  * N.B. Where more than one page has been mapped into a contiguous range, the
0097  *      supplied @vaddr must correspond to the start of the range; otherwise
0098  *      an error will result. It is only possible to munmap() the entire
0099  *      contiguously-allocated range at once, and not any subrange thereof.
0100  */
0101 #define IOCTL_GNTDEV_GET_OFFSET_FOR_VADDR \
0102 _IOC(_IOC_NONE, 'G', 2, sizeof(struct ioctl_gntdev_get_offset_for_vaddr))
0103 struct ioctl_gntdev_get_offset_for_vaddr {
0104     /* IN parameters */
0105     /* The virtual address of the first mapped page in a range. */
0106     __u64 vaddr;
0107     /* OUT parameters */
0108     /* The offset that was used in the initial mmap() operation. */
0109     __u64 offset;
0110     /* The number of pages mapped in the VM area that begins at @vaddr. */
0111     __u32 count;
0112     __u32 pad;
0113 };
0114
0115 /*
0116  * Sets the maximum number of grants that may mapped at once by this gntdev
0117  * instance.
0118  *
0119  * N.B. This must be called before any other ioctl is performed on the device.
0120  */
0121 #define IOCTL_GNTDEV_SET_MAX_GRANTS \
0122 _IOC(_IOC_NONE, 'G', 3, sizeof(struct ioctl_gntdev_set_max_grants))
0123 struct ioctl_gntdev_set_max_grants {
0124     /* IN parameter */
0125     /* The maximum number of grants that may be mapped at once. */
0126     __u32 count;
0127 };
0128
0129 /*
0130  * Sets up an unmap notification within the page, so that the other side can do
0131  * cleanup if this side crashes. Required to implement cross-domain robust
0132  * mutexes or close notification on communication channels.
0133  *
0134  * Each mapped page only supports one notification; multiple calls referring to
0135  * the same page overwrite the previous notification. You must clear the
0136  * notification prior to the IOCTL_GNTALLOC_DEALLOC_GREF if you do not want it
0137  * to occur.
0138  */
0139 #define IOCTL_GNTDEV_SET_UNMAP_NOTIFY \
0140 _IOC(_IOC_NONE, 'G', 7, sizeof(struct ioctl_gntdev_unmap_notify))
0141 struct ioctl_gntdev_unmap_notify {
0142     /* IN parameters */
0143     /* Offset in the file descriptor for a byte within the page (same as
0144      * used in mmap). If using UNMAP_NOTIFY_CLEAR_BYTE, this is the byte to
0145      * be cleared. Otherwise, it can be any byte in the page whose
0146      * notification we are adjusting.
0147      */
0148     __u64 index;
0149     /* Action(s) to take on unmap */
0150     __u32 action;
0151     /* Event channel to notify */
0152     __u32 event_channel_port;
0153 };
0154
0155 struct gntdev_grant_copy_segment {
0156     union {
0157         void __user *virt;
0158         struct {
0159             grant_ref_t ref;
0160             __u16 offset;
0161             domid_t domid;
0162         } foreign;
0163     } source, dest;
0164     __u16 len;
0165
0166     __u16 flags;  /* GNTCOPY_* */
0167     __s16 status; /* GNTST_* */
0168 };
0169
0170 /*
0171  * Copy between grant references and local buffers.
0172  *
0173  * The copy is split into @count @segments, each of which can copy
0174  * to/from one grant reference.
0175  *
0176  * Each segment is similar to struct gnttab_copy in the hypervisor ABI
0177  * except the local buffer is specified using a virtual address
0178  * (instead of a GFN and offset).
0179  *
0180  * The local buffer may cross a Xen page boundary -- the driver will
0181  * split segments into multiple ops if required.
0182  *
0183  * Returns 0 if all segments have been processed and @status in each
0184  * segment is valid.  Note that one or more segments may have failed
0185  * (status != GNTST_okay).
0186  *
0187  * If the driver had to split a segment into two or more ops, @status
0188  * includes the status of the first failed op for that segment (or
0189  * GNTST_okay if all ops were successful).
0190  *
0191  * If -1 is returned, the status of all segments is undefined.
0192  *
0193  * EINVAL: A segment has local buffers for both source and
0194  *         destination.
0195  * EINVAL: A segment crosses the boundary of a foreign page.
0196  * EFAULT: A segment's local buffer is not accessible.
0197  */
0198 #define IOCTL_GNTDEV_GRANT_COPY \
0199     _IOC(_IOC_NONE, 'G', 8, sizeof(struct ioctl_gntdev_grant_copy))
0200 struct ioctl_gntdev_grant_copy {
0201     unsigned int count;
0202     struct gntdev_grant_copy_segment __user *segments;
0203 };
0204
0205 /* Clear (set to zero) the byte specified by index */
0206 #define UNMAP_NOTIFY_CLEAR_BYTE 0x1
0207 /* Send an interrupt on the indicated event channel */
0208 #define UNMAP_NOTIFY_SEND_EVENT 0x2
0209
0210 /*
0211  * Flags to be used while requesting memory mapping's backing storage
0212  * to be allocated with DMA API.
0213  */
0214
0215 /*
0216  * The buffer is backed with memory allocated with dma_alloc_wc.
0217  */
0218 #define GNTDEV_DMA_FLAG_WC      (1 << 0)
0219
0220 /*
0221  * The buffer is backed with memory allocated with dma_alloc_coherent.
0222  */
0223 #define GNTDEV_DMA_FLAG_COHERENT    (1 << 1)
0224
0225 /*
0226  * Create a dma-buf [1] from grant references @refs of count @count provided
0227  * by the foreign domain @domid with flags @flags.
0228  *
0229  * By default dma-buf is backed by system memory pages, but by providing
0230  * one of the GNTDEV_DMA_FLAG_XXX flags it can also be created as
0231  * a DMA write-combine or coherent buffer, e.g. allocated with dma_alloc_wc/
0232  * dma_alloc_coherent.
0233  *
0234  * Returns 0 if dma-buf was successfully created and the corresponding
0235  * dma-buf's file descriptor is returned in @fd.
0236  *
0237  * [1] Documentation/driver-api/dma-buf.rst
0238  */
0239
0240 #define IOCTL_GNTDEV_DMABUF_EXP_FROM_REFS \
0241     _IOC(_IOC_NONE, 'G', 9, \
0242          sizeof(struct ioctl_gntdev_dmabuf_exp_from_refs))
0243 struct ioctl_gntdev_dmabuf_exp_from_refs {
0244     /* IN parameters. */
0245     /* Specific options for this dma-buf: see GNTDEV_DMA_FLAG_XXX. */
0246     __u32 flags;
0247     /* Number of grant references in @refs array. */
0248     __u32 count;
0249     /* OUT parameters. */
0250     /* File descriptor of the dma-buf. */
0251     __u32 fd;
0252     /* The domain ID of the grant references to be mapped. */
0253     __u32 domid;
0254     /* Variable IN parameter. */
0255     /* Array of grant references of size @count. */
0256     __u32 refs[1];
0257 };
0258
0259 /*
0260  * This will block until the dma-buf with the file descriptor @fd is
0261  * released. This is only valid for buffers created with
0262  * IOCTL_GNTDEV_DMABUF_EXP_FROM_REFS.
0263  *
0264  * If within @wait_to_ms milliseconds the buffer is not released
0265  * then -ETIMEDOUT error is returned.
0266  * If the buffer with the file descriptor @fd does not exist or has already
0267  * been released, then -ENOENT is returned. For valid file descriptors
0268  * this must not be treated as error.
0269  */
0270 #define IOCTL_GNTDEV_DMABUF_EXP_WAIT_RELEASED \
0271     _IOC(_IOC_NONE, 'G', 10, \
0272          sizeof(struct ioctl_gntdev_dmabuf_exp_wait_released))
0273 struct ioctl_gntdev_dmabuf_exp_wait_released {
0274     /* IN parameters */
0275     __u32 fd;
0276     __u32 wait_to_ms;
0277 };
0278
0279 /*
0280  * Import a dma-buf with file descriptor @fd and export granted references
0281  * to the pages of that dma-buf into array @refs of size @count.
0282  */
0283 #define IOCTL_GNTDEV_DMABUF_IMP_TO_REFS \
0284     _IOC(_IOC_NONE, 'G', 11, \
0285          sizeof(struct ioctl_gntdev_dmabuf_imp_to_refs))
0286 struct ioctl_gntdev_dmabuf_imp_to_refs {
0287     /* IN parameters. */
0288     /* File descriptor of the dma-buf. */
0289     __u32 fd;
0290     /* Number of grant references in @refs array. */
0291     __u32 count;
0292     /* The domain ID for which references to be granted. */
0293     __u32 domid;
0294     /* Reserved - must be zero. */
0295     __u32 reserved;
0296     /* OUT parameters. */
0297     /* Array of grant references of size @count. */
0298     __u32 refs[1];
0299 };
0300
0301 /*
0302  * This will close all references to the imported buffer with file descriptor
0303  * @fd, so it can be released by the owner. This is only valid for buffers
0304  * created with IOCTL_GNTDEV_DMABUF_IMP_TO_REFS.
0305  */
0306 #define IOCTL_GNTDEV_DMABUF_IMP_RELEASE \
0307     _IOC(_IOC_NONE, 'G', 12, \
0308          sizeof(struct ioctl_gntdev_dmabuf_imp_release))
0309 struct ioctl_gntdev_dmabuf_imp_release {
0310     /* IN parameters */
0311     __u32 fd;
0312     __u32 reserved;
0313 };
0314
0315 #endif /* __LINUX_PUBLIC_GNTDEV_H__ */