include/xen/gntdev.h

   1 /******************************************************************************
   2  * gntdev.h
   3  *
   4  * Interface to /dev/xen/gntdev.
   5  *
   6  * Copyright (c) 2007, D G Murray
   7  *
   8  * This program is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU General Public License version 2
  10  * as published by the Free Software Foundation; or, when distributed
  11  * separately from the Linux kernel or incorporated into other
  12  * software packages, subject to the following license:
  13  *
  14  * Permission is hereby granted, free of charge, to any person obtaining a copy
  15  * of this source file (the "Software"), to deal in the Software without
  16  * restriction, including without limitation the rights to use, copy, modify,
  17  * merge, publish, distribute, sublicense, and/or sell copies of the Software,
  18  * and to permit persons to whom the Software is furnished to do so, subject to
  19  * the following conditions:
  20  *
  21  * The above copyright notice and this permission notice shall be included in
  22  * all copies or substantial portions of the Software.
  23  *
  24  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  25  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  26  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  27  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  28  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  29  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  30  * IN THE SOFTWARE.
  31  */
  32
  33 #ifndef __LINUX_PUBLIC_GNTDEV_H__
  34 #define __LINUX_PUBLIC_GNTDEV_H__
  35
  36 struct ioctl_gntdev_grant_ref {
  37         /* The domain ID of the grant to be mapped. */
  38         uint32_t domid;
  39         /* The grant reference of the grant to be mapped. */
  40         uint32_t ref;
  41 };
  42
  43 /*
  44  * Inserts the grant references into the mapping table of an instance
  45  * of gntdev. N.B. This does not perform the mapping, which is deferred
  46  * until mmap() is called with @index as the offset.
  47  */
  48 #define IOCTL_GNTDEV_MAP_GRANT_REF \
  49 _IOC(_IOC_NONE, 'G', 0, sizeof(struct ioctl_gntdev_map_grant_ref))
  50 struct ioctl_gntdev_map_grant_ref {
  51         /* IN parameters */
  52         /* The number of grants to be mapped. */
  53         uint32_t count;
  54         uint32_t pad;
  55         /* OUT parameters */
  56         /* The offset to be used on a subsequent call to mmap(). */
  57         uint64_t index;
  58         /* Variable IN parameter. */
  59         /* Array of grant references, of size @count. */
  60         struct ioctl_gntdev_grant_ref refs[1];
  61 };
  62
  63 /*
  64  * Removes the grant references from the mapping table of an instance of
  65  * of gntdev. N.B. munmap() must be called on the relevant virtual address(es)
  66  * before this ioctl is called, or an error will result.
  67  */
  68 #define IOCTL_GNTDEV_UNMAP_GRANT_REF \
  69 _IOC(_IOC_NONE, 'G', 1, sizeof(struct ioctl_gntdev_unmap_grant_ref))
  70 struct ioctl_gntdev_unmap_grant_ref {
  71         /* IN parameters */
  72         /* The offset was returned by the corresponding map operation. */
  73         uint64_t index;
  74         /* The number of pages to be unmapped. */
  75         uint32_t count;
  76         uint32_t pad;
  77 };
  78
  79 /*
  80  * Returns the offset in the driver's address space that corresponds
  81  * to @vaddr. This can be used to perform a munmap(), followed by an
  82  * UNMAP_GRANT_REF ioctl, where no state about the offset is retained by
  83  * the caller. The number of pages that were allocated at the same time as
  84  * @vaddr is returned in @count.
  85  *
  86  * N.B. Where more than one page has been mapped into a contiguous range, the
  87  *      supplied @vaddr must correspond to the start of the range; otherwise
  88  *      an error will result. It is only possible to munmap() the entire
  89  *      contiguously-allocated range at once, and not any subrange thereof.
  90  */
  91 #define IOCTL_GNTDEV_GET_OFFSET_FOR_VADDR \
  92 _IOC(_IOC_NONE, 'G', 2, sizeof(struct ioctl_gntdev_get_offset_for_vaddr))
  93 struct ioctl_gntdev_get_offset_for_vaddr {
  94         /* IN parameters */
  95         /* The virtual address of the first mapped page in a range. */
  96         uint64_t vaddr;
  97         /* OUT parameters */
  98         /* The offset that was used in the initial mmap() operation. */
  99         uint64_t offset;
 100         /* The number of pages mapped in the VM area that begins at @vaddr. */
 101         uint32_t count;
 102         uint32_t pad;
 103 };
 104
 105 /*
 106  * Sets the maximum number of grants that may mapped at once by this gntdev
 107  * instance.
 108  *
 109  * N.B. This must be called before any other ioctl is performed on the device.
 110  */
 111 #define IOCTL_GNTDEV_SET_MAX_GRANTS \
 112 _IOC(_IOC_NONE, 'G', 3, sizeof(struct ioctl_gntdev_set_max_grants))
 113 struct ioctl_gntdev_set_max_grants {
 114         /* IN parameter */
 115         /* The maximum number of grants that may be mapped at once. */
 116         uint32_t count;
 117 };
 118
 119 /*
 120  * Sets up an unmap notification within the page, so that the other side can do
 121  * cleanup if this side crashes. Required to implement cross-domain robust
 122  * mutexes or close notification on communication channels.
 123  *
 124  * Each mapped page only supports one notification; multiple calls referring to
 125  * the same page overwrite the previous notification. You must clear the
 126  * notification prior to the IOCTL_GNTALLOC_DEALLOC_GREF if you do not want it
 127  * to occur.
 128  */
 129 #define IOCTL_GNTDEV_SET_UNMAP_NOTIFY \
 130 _IOC(_IOC_NONE, 'G', 7, sizeof(struct ioctl_gntdev_unmap_notify))
 131 struct ioctl_gntdev_unmap_notify {
 132         /* IN parameters */
 133         /* Offset in the file descriptor for a byte within the page (same as
 134          * used in mmap). If using UNMAP_NOTIFY_CLEAR_BYTE, this is the byte to
 135          * be cleared. Otherwise, it can be any byte in the page whose
 136          * notification we are adjusting.
 137          */
 138         uint64_t index;
 139         /* Action(s) to take on unmap */
 140         uint32_t action;
 141         /* Event channel to notify */
 142         uint32_t event_channel_port;
 143 };
 144
 145 /* Clear (set to zero) the byte specified by index */
 146 #define UNMAP_NOTIFY_CLEAR_BYTE 0x1
 147 /* Send an interrupt on the indicated event channel */
 148 #define UNMAP_NOTIFY_SEND_EVENT 0x2
 149
 150 #endif /* __LINUX_PUBLIC_GNTDEV_H__ */