include/uapi/xen/gntdev.h

   1 /* SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR MIT) */
   2 /******************************************************************************
   3  * gntdev.h
   4  *
   5  * Interface to /dev/xen/gntdev.
   6  *
   7  * Copyright (c) 2007, D G Murray
   8  * Copyright (c) 2018, Oleksandr Andrushchenko, EPAM Systems Inc.
   9  *
  10  * This program is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU General Public License version 2
  12  * as published by the Free Software Foundation; or, when distributed
  13  * separately from the Linux kernel or incorporated into other
  14  * software packages, subject to the following license:
  15  *
  16  * Permission is hereby granted, free of charge, to any person obtaining a copy
  17  * of this source file (the "Software"), to deal in the Software without
  18  * restriction, including without limitation the rights to use, copy, modify,
  19  * merge, publish, distribute, sublicense, and/or sell copies of the Software,
  20  * and to permit persons to whom the Software is furnished to do so, subject to
  21  * the following conditions:
  22  *
  23  * The above copyright notice and this permission notice shall be included in
  24  * all copies or substantial portions of the Software.
  25  *
  26  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  27  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  28  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  29  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  30  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  31  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  32  * IN THE SOFTWARE.
  33  */
  34
  35 #ifndef __LINUX_PUBLIC_GNTDEV_H__
  36 #define __LINUX_PUBLIC_GNTDEV_H__
  37
  38 #include <linux/types.h>
  39
  40 struct ioctl_gntdev_grant_ref {
  41         /* The domain ID of the grant to be mapped. */
  42         __u32 domid;
  43         /* The grant reference of the grant to be mapped. */
  44         __u32 ref;
  45 };
  46
  47 /*
  48  * Inserts the grant references into the mapping table of an instance
  49  * of gntdev. N.B. This does not perform the mapping, which is deferred
  50  * until mmap() is called with @index as the offset. @index should be
  51  * considered opaque to userspace, with one exception: if no grant
  52  * references have ever been inserted into the mapping table of this
  53  * instance, @index will be set to 0. This is necessary to use gntdev
  54  * with userspace APIs that expect a file descriptor that can be
  55  * mmap()'d at offset 0, such as Wayland. If @count is set to 0, this
  56  * ioctl will fail.
  57  */
  58 #define IOCTL_GNTDEV_MAP_GRANT_REF \
  59 _IOC(_IOC_NONE, 'G', 0, sizeof(struct ioctl_gntdev_map_grant_ref))
  60 struct ioctl_gntdev_map_grant_ref {
  61         /* IN parameters */
  62         /* The number of grants to be mapped. */
  63         __u32 count;
  64         __u32 pad;
  65         /* OUT parameters */
  66         /* The offset to be used on a subsequent call to mmap(). */
  67         __u64 index;
  68         /* Variable IN parameter. */
  69         /* Array of grant references, of size @count. */
  70         struct ioctl_gntdev_grant_ref refs[1];
  71 };
  72
  73 /*
  74  * Removes the grant references from the mapping table of an instance of
  75  * gntdev. N.B. munmap() must be called on the relevant virtual address(es)
  76  * before this ioctl is called, or an error will result.
  77  */
  78 #define IOCTL_GNTDEV_UNMAP_GRANT_REF \
  79 _IOC(_IOC_NONE, 'G', 1, sizeof(struct ioctl_gntdev_unmap_grant_ref))
  80 struct ioctl_gntdev_unmap_grant_ref {
  81         /* IN parameters */
  82         /* The offset was returned by the corresponding map operation. */
  83         __u64 index;
  84         /* The number of pages to be unmapped. */
  85         __u32 count;
  86         __u32 pad;
  87 };
  88
  89 /*
  90  * Returns the offset in the driver's address space that corresponds
  91  * to @vaddr. This can be used to perform a munmap(), followed by an
  92  * UNMAP_GRANT_REF ioctl, where no state about the offset is retained by
  93  * the caller. The number of pages that were allocated at the same time as
  94  * @vaddr is returned in @count.
  95  *
  96  * N.B. Where more than one page has been mapped into a contiguous range, the
  97  *      supplied @vaddr must correspond to the start of the range; otherwise
  98  *      an error will result. It is only possible to munmap() the entire
  99  *      contiguously-allocated range at once, and not any subrange thereof.
 100  */
 101 #define IOCTL_GNTDEV_GET_OFFSET_FOR_VADDR \
 102 _IOC(_IOC_NONE, 'G', 2, sizeof(struct ioctl_gntdev_get_offset_for_vaddr))
 103 struct ioctl_gntdev_get_offset_for_vaddr {
 104         /* IN parameters */
 105         /* The virtual address of the first mapped page in a range. */
 106         __u64 vaddr;
 107         /* OUT parameters */
 108         /* The offset that was used in the initial mmap() operation. */
 109         __u64 offset;
 110         /* The number of pages mapped in the VM area that begins at @vaddr. */
 111         __u32 count;
 112         __u32 pad;
 113 };
 114
 115 /*
 116  * Sets the maximum number of grants that may mapped at once by this gntdev
 117  * instance.
 118  *
 119  * N.B. This must be called before any other ioctl is performed on the device.
 120  */
 121 #define IOCTL_GNTDEV_SET_MAX_GRANTS \
 122 _IOC(_IOC_NONE, 'G', 3, sizeof(struct ioctl_gntdev_set_max_grants))
 123 struct ioctl_gntdev_set_max_grants {
 124         /* IN parameter */
 125         /* The maximum number of grants that may be mapped at once. */
 126         __u32 count;
 127 };
 128
 129 /*
 130  * Sets up an unmap notification within the page, so that the other side can do
 131  * cleanup if this side crashes. Required to implement cross-domain robust
 132  * mutexes or close notification on communication channels.
 133  *
 134  * Each mapped page only supports one notification; multiple calls referring to
 135  * the same page overwrite the previous notification. You must clear the
 136  * notification prior to the IOCTL_GNTALLOC_DEALLOC_GREF if you do not want it
 137  * to occur.
 138  */
 139 #define IOCTL_GNTDEV_SET_UNMAP_NOTIFY \
 140 _IOC(_IOC_NONE, 'G', 7, sizeof(struct ioctl_gntdev_unmap_notify))
 141 struct ioctl_gntdev_unmap_notify {
 142         /* IN parameters */
 143         /* Offset in the file descriptor for a byte within the page (same as
 144          * used in mmap). If using UNMAP_NOTIFY_CLEAR_BYTE, this is the byte to
 145          * be cleared. Otherwise, it can be any byte in the page whose
 146          * notification we are adjusting.
 147          */
 148         __u64 index;
 149         /* Action(s) to take on unmap */
 150         __u32 action;
 151         /* Event channel to notify */
 152         __u32 event_channel_port;
 153 };
 154
 155 struct gntdev_grant_copy_segment {
 156         union {
 157                 void __user *virt;
 158                 struct {
 159                         grant_ref_t ref;
 160                         __u16 offset;
 161                         domid_t domid;
 162                 } foreign;
 163         } source, dest;
 164         __u16 len;
 165
 166         __u16 flags;  /* GNTCOPY_* */
 167         __s16 status; /* GNTST_* */
 168 };
 169
 170 /*
 171  * Copy between grant references and local buffers.
 172  *
 173  * The copy is split into @count @segments, each of which can copy
 174  * to/from one grant reference.
 175  *
 176  * Each segment is similar to struct gnttab_copy in the hypervisor ABI
 177  * except the local buffer is specified using a virtual address
 178  * (instead of a GFN and offset).
 179  *
 180  * The local buffer may cross a Xen page boundary -- the driver will
 181  * split segments into multiple ops if required.
 182  *
 183  * Returns 0 if all segments have been processed and @status in each
 184  * segment is valid.  Note that one or more segments may have failed
 185  * (status != GNTST_okay).
 186  *
 187  * If the driver had to split a segment into two or more ops, @status
 188  * includes the status of the first failed op for that segment (or
 189  * GNTST_okay if all ops were successful).
 190  *
 191  * If -1 is returned, the status of all segments is undefined.
 192  *
 193  * EINVAL: A segment has local buffers for both source and
 194  *         destination.
 195  * EINVAL: A segment crosses the boundary of a foreign page.
 196  * EFAULT: A segment's local buffer is not accessible.
 197  */
 198 #define IOCTL_GNTDEV_GRANT_COPY \
 199         _IOC(_IOC_NONE, 'G', 8, sizeof(struct ioctl_gntdev_grant_copy))
 200 struct ioctl_gntdev_grant_copy {
 201         unsigned int count;
 202         struct gntdev_grant_copy_segment __user *segments;
 203 };
 204
 205 /* Clear (set to zero) the byte specified by index */
 206 #define UNMAP_NOTIFY_CLEAR_BYTE 0x1
 207 /* Send an interrupt on the indicated event channel */
 208 #define UNMAP_NOTIFY_SEND_EVENT 0x2
 209
 210 /*
 211  * Flags to be used while requesting memory mapping's backing storage
 212  * to be allocated with DMA API.
 213  */
 214
 215 /*
 216  * The buffer is backed with memory allocated with dma_alloc_wc.
 217  */
 218 #define GNTDEV_DMA_FLAG_WC              (1 << 0)
 219
 220 /*
 221  * The buffer is backed with memory allocated with dma_alloc_coherent.
 222  */
 223 #define GNTDEV_DMA_FLAG_COHERENT        (1 << 1)
 224
 225 /*
 226  * Create a dma-buf [1] from grant references @refs of count @count provided
 227  * by the foreign domain @domid with flags @flags.
 228  *
 229  * By default dma-buf is backed by system memory pages, but by providing
 230  * one of the GNTDEV_DMA_FLAG_XXX flags it can also be created as
 231  * a DMA write-combine or coherent buffer, e.g. allocated with dma_alloc_wc/
 232  * dma_alloc_coherent.
 233  *
 234  * Returns 0 if dma-buf was successfully created and the corresponding
 235  * dma-buf's file descriptor is returned in @fd.
 236  *
 237  * [1] Documentation/driver-api/dma-buf.rst
 238  */
 239
 240 #define IOCTL_GNTDEV_DMABUF_EXP_FROM_REFS \
 241         _IOC(_IOC_NONE, 'G', 9, \
 242              sizeof(struct ioctl_gntdev_dmabuf_exp_from_refs))
 243 struct ioctl_gntdev_dmabuf_exp_from_refs {
 244         /* IN parameters. */
 245         /* Specific options for this dma-buf: see GNTDEV_DMA_FLAG_XXX. */
 246         __u32 flags;
 247         /* Number of grant references in @refs array. */
 248         __u32 count;
 249         /* OUT parameters. */
 250         /* File descriptor of the dma-buf. */
 251         __u32 fd;
 252         /* The domain ID of the grant references to be mapped. */
 253         __u32 domid;
 254         /* Variable IN parameter. */
 255         /* Array of grant references of size @count. */
 256         __u32 refs[1];
 257 };
 258
 259 /*
 260  * This will block until the dma-buf with the file descriptor @fd is
 261  * released. This is only valid for buffers created with
 262  * IOCTL_GNTDEV_DMABUF_EXP_FROM_REFS.
 263  *
 264  * If within @wait_to_ms milliseconds the buffer is not released
 265  * then -ETIMEDOUT error is returned.
 266  * If the buffer with the file descriptor @fd does not exist or has already
 267  * been released, then -ENOENT is returned. For valid file descriptors
 268  * this must not be treated as error.
 269  */
 270 #define IOCTL_GNTDEV_DMABUF_EXP_WAIT_RELEASED \
 271         _IOC(_IOC_NONE, 'G', 10, \
 272              sizeof(struct ioctl_gntdev_dmabuf_exp_wait_released))
 273 struct ioctl_gntdev_dmabuf_exp_wait_released {
 274         /* IN parameters */
 275         __u32 fd;
 276         __u32 wait_to_ms;
 277 };
 278
 279 /*
 280  * Import a dma-buf with file descriptor @fd and export granted references
 281  * to the pages of that dma-buf into array @refs of size @count.
 282  */
 283 #define IOCTL_GNTDEV_DMABUF_IMP_TO_REFS \
 284         _IOC(_IOC_NONE, 'G', 11, \
 285              sizeof(struct ioctl_gntdev_dmabuf_imp_to_refs))
 286 struct ioctl_gntdev_dmabuf_imp_to_refs {
 287         /* IN parameters. */
 288         /* File descriptor of the dma-buf. */
 289         __u32 fd;
 290         /* Number of grant references in @refs array. */
 291         __u32 count;
 292         /* The domain ID for which references to be granted. */
 293         __u32 domid;
 294         /* Reserved - must be zero. */
 295         __u32 reserved;
 296         /* OUT parameters. */
 297         /* Array of grant references of size @count. */
 298         __u32 refs[1];
 299 };
 300
 301 /*
 302  * This will close all references to the imported buffer with file descriptor
 303  * @fd, so it can be released by the owner. This is only valid for buffers
 304  * created with IOCTL_GNTDEV_DMABUF_IMP_TO_REFS.
 305  */
 306 #define IOCTL_GNTDEV_DMABUF_IMP_RELEASE \
 307         _IOC(_IOC_NONE, 'G', 12, \
 308              sizeof(struct ioctl_gntdev_dmabuf_imp_release))
 309 struct ioctl_gntdev_dmabuf_imp_release {
 310         /* IN parameters */
 311         __u32 fd;
 312         __u32 reserved;
 313 };
 314
 315 #endif /* __LINUX_PUBLIC_GNTDEV_H__ */