The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/xen/gntdev.h

Version: -  FREEBSD  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-2  -  FREEBSD-11-1  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-4  -  FREEBSD-10-3  -  FREEBSD-10-2  -  FREEBSD-10-1  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-3  -  FREEBSD-9-2  -  FREEBSD-9-1  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-4  -  FREEBSD-8-3  -  FREEBSD-8-2  -  FREEBSD-8-1  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-4  -  FREEBSD-7-3  -  FREEBSD-7-2  -  FREEBSD-7-1  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-4  -  FREEBSD-6-3  -  FREEBSD-6-2  -  FREEBSD-6-1  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-5  -  FREEBSD-5-4  -  FREEBSD-5-3  -  FREEBSD-5-2  -  FREEBSD-5-1  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  linux-2.6  -  linux-2.4.22  -  MK83  -  MK84  -  PLAN9  -  DFBSD  -  NETBSD  -  NETBSD5  -  NETBSD4  -  NETBSD3  -  NETBSD20  -  OPENBSD  -  xnu-517  -  xnu-792  -  xnu-792.6.70  -  xnu-1228  -  xnu-1456.1.26  -  xnu-1699.24.8  -  xnu-2050.18.24  -  OPENSOLARIS  -  minix-3-1-1 
SearchContext: -  none  -  3  -  10 

    1 /*-
    2  * Copyright (c) 2016 Akshay Jaggi <jaggi@FreeBSD.org>
    3  * All rights reserved.
    4  *
    5  * Redistribution and use in source and binary forms, with or without
    6  * modification, are permitted provided that the following conditions
    7  * are met:
    8  * 1. Redistributions of source code must retain the above copyright
    9  *    notice, this list of conditions and the following disclaimer.
   10  * 2. Redistributions in binary form must reproduce the above copyright
   11  *    notice, this list of conditions and the following disclaimer in the
   12  *    documentation and/or other materials provided with the distribution.
   13  *
   14  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
   15  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
   16  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
   17  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
   18  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
   19  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
   20  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
   21  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   22  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
   23  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   24  * SUCH DAMAGE.
   25  *
   26  * gntdev.h
   27  *
   28  * Interface to /dev/xen/gntdev.
   29  *
   30  * This device provides the user with two kinds of functionalities:
   31  * 1. Grant Allocation
   32  *    Allocate a page of our own memory, and share it with a foreign domain.
   33  * 2. Grant Mapping
   34  *    Map a grant allocated by a foreign domain, into our own memory.
   35  *
   36  *
   37  * Grant Allocation
   38  *
   39  * Steps to allocate a grant:
   40  * 1. Do an `IOCTL_GNTDEV_ALLOC_GREF ioctl`, with
   41  *     - `domid`, as the domain-id of the foreign domain
   42  *     - `flags`, ORed with GNTDEV_ALLOC_FLAG_WRITABLE if you want the foreign
   43  *       domain to have write access to the shared memory
   44  *     - `count`, with the number of pages to share with the foreign domain
   45  *
   46  *    Ensure that the structure you allocate has enough memory to store
   47  *    all the allocated grant-refs, i.e., you need to allocate
   48  *    (sizeof(struct ioctl_gntdev_alloc_gref) + (count - 1)*sizeof(uint32_t))
   49  *    bytes of memory.
   50  *
   51  * 2. Mmap the address given in `index` after a successful ioctl.
   52  *    This will give you access to the granted pages.
   53  *
   54  * Note:
   55  * 1. The grant is not removed until all three of the following conditions
   56  *    are met
   57  *     - The region is not mmaped. That is, munmap() has been called if
   58  *       the region was mmapped previously.
   59  *     - IOCTL_GNTDEV_DEALLOC_GREF ioctl has been performed. After you
   60  *       perform this ioctl, you can no longer mmap or set notify on
   61  *       the grant.
   62  *     - The foreign domain has stopped using the grant.
   63  * 2. Granted pages can only belong to one mmap region.
   64  * 3. Every page of granted memory is a unit in itself. What this means
   65  *    is that you can set a unmap notification for each of the granted
   66  *    pages, individually; you can mmap and dealloc-ioctl a contiguous
   67  *    range of allocated grants (even if alloc-ioctls were performed
   68  *    individually), etc.
   69  *
   70  *
   71  * Grant Mapping
   72  *
   73  * Steps to map a grant:
   74  * 1. Do a `IOCTL_GNTDEV_MAP_GRANT_REF` ioctl, with
   75  *     - `count`, as the number of foreign grants to map
   76  *     - `refs[i].domid`, as the domain id of the foreign domain
   77  *     - `refs[i].ref`, as the grant-ref for the grant to be mapped
   78  *
   79  * 2. Mmap the address given in `index` after a successful ioctl.
   80  *    This will give you access to the mapped pages.
   81  *
   82  * Note:
   83  * 1. The map hypercall is not made till the region is mmapped.
   84  * 2. The unit is defined by the map ioctl. This means that only one
   85  *    unmap notification can be set on a group of pages that were
   86  *    mapped together in one ioctl, and also no single mmaping of contiguous
   87  *    grant-maps is possible.
   88  * 3. You can mmap the same grant-map region multiple times.
   89  * 4. The grant is not unmapped until both of the following conditions are met
   90  *     - The region is not mmaped. That is, munmap() has been called for
   91  *       as many times as the grant was mmapped.
   92  *     - IOCTL_GNTDEV_UNMAP_GRANT_REF ioctl has been called.
   93  * 5. IOCTL_GNTDEV_GET_OFFSET_FOR_VADDR ioctl gives index and count of
   94  *    a grant-map from the virtual address of the location where the grant
   95  *    is mmapped.
   96  *
   97  *
   98  * IOCTL_GNTDEV_SET_UNMAP_NOTIFY
   99  * This ioctl allows us to set notifications to be made when the grant is
  100  * either unmapped (in case of a mapped grant), or when it is ready to be
  101  * deallocated by us, ie, the grant is no more mmapped, and the dealloc
  102  * ioctl has been called (in case of an allocated grant). OR `action` with
  103  * the required notification masks, and fill in the appropriate fields.
  104  *  - UNMAP_NOTIFY_CLEAR_BYTE clears the byte at `index`, where index is
  105  *    the address of the byte in file address space.
  106  *  - UNMAP_NOTIFY_SEND_EVENT sends an event channel notification on
  107  *    `event_channel_port`
  108  * In case of multiple notify ioctls, only the last one survives.
  109  *
  110  * $FreeBSD: releng/12.0/sys/xen/gntdev.h 333169 2018-05-02 10:19:17Z royger $
  111  */
  112 
  113 #ifndef __XEN_GNTDEV_H__
  114 #define __XEN_GNTDEV_H__
  115 
  116 #include <sys/types.h>
  117 
  118 #define IOCTL_GNTDEV_SET_UNMAP_NOTIFY                                   \
  119         _IOW('E', 0, struct ioctl_gntdev_unmap_notify)
  120 struct ioctl_gntdev_unmap_notify {
  121     /* IN parameters */
  122     uint64_t index;
  123     uint32_t action;
  124     uint32_t event_channel_port;
  125 };
  126 
  127 #define UNMAP_NOTIFY_CLEAR_BYTE 0x1
  128 #define UNMAP_NOTIFY_SEND_EVENT 0x2
  129 
  130 /*-------------------- Grant Allocation IOCTLs  ------------------------------*/
  131 
  132 #define IOCTL_GNTDEV_ALLOC_GREF                                         \
  133         _IOWR('E', 1, struct ioctl_gntdev_alloc_gref)
  134 struct ioctl_gntdev_alloc_gref {
  135     /* IN parameters */
  136     uint16_t domid;
  137     uint16_t flags;
  138     uint32_t count;
  139     /* OUT parameters */
  140     uint64_t index;
  141     /* Variable OUT parameter */
  142     uint32_t *gref_ids;
  143 };
  144 
  145 #define GNTDEV_ALLOC_FLAG_WRITABLE 1
  146 
  147 #define IOCTL_GNTDEV_DEALLOC_GREF                                       \
  148         _IOW('E', 2, struct ioctl_gntdev_dealloc_gref)
  149 struct ioctl_gntdev_dealloc_gref {
  150     /* IN parameters */
  151     uint64_t index;
  152     uint32_t count;
  153 };
  154 
  155 /*-------------------- Grant Mapping IOCTLs  ---------------------------------*/
  156 
  157 struct ioctl_gntdev_grant_ref {
  158     uint32_t domid;
  159     uint32_t ref;
  160 };
  161 
  162 #define IOCTL_GNTDEV_MAP_GRANT_REF                                      \
  163         _IOWR('E', 3, struct ioctl_gntdev_map_grant_ref)
  164 struct ioctl_gntdev_map_grant_ref {
  165     /* IN parameters */
  166     uint32_t count;
  167     uint32_t pad0;
  168     /* OUT parameters */
  169     uint64_t index;
  170     /* Variable IN parameter */
  171     struct ioctl_gntdev_grant_ref *refs;
  172 };
  173 
  174 #define IOCTL_GNTDEV_UNMAP_GRANT_REF                                    \
  175         _IOW('E', 4, struct ioctl_gntdev_unmap_grant_ref)
  176 struct ioctl_gntdev_unmap_grant_ref {
  177     /* IN parameters */
  178     uint64_t index;
  179     uint32_t count;
  180 };
  181 
  182 #define IOCTL_GNTDEV_GET_OFFSET_FOR_VADDR                               \
  183         _IOWR('E', 5, struct ioctl_gntdev_get_offset_for_vaddr)
  184 struct ioctl_gntdev_get_offset_for_vaddr {
  185     /* IN parameters */
  186     uint64_t vaddr;
  187     /* OUT parameters */
  188     uint64_t offset;
  189     uint32_t count;
  190 };
  191 
  192 #endif /* __XEN_GNTDEV_H__ */

Cache object: 223302d0e2f49ece563c2c8956e18c29


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.