include/asm-xen/xen-public/grant_table.h

   1 /******************************************************************************
   2  * grant_table.h
   3  *
   4  * Interface for granting foreign access to page frames, and receiving
   5  * page-ownership transfers.
   6  *
   7  * Copyright (c) 2004, K A Fraser
   8  */
   9
  10 #ifndef __XEN_PUBLIC_GRANT_TABLE_H__
  11 #define __XEN_PUBLIC_GRANT_TABLE_H__
  12
  13
  14 /***********************************
  15  * GRANT TABLE REPRESENTATION
  16  */
  17
  18 /* Some rough guidelines on accessing and updating grant-table entries
  19  * in a concurrency-safe manner. For more information, Linux contains a
  20  * reference implementation for guest OSes (arch/xen/kernel/grant_table.c).
  21  *
  22  * NB. WMB is a no-op on current-generation x86 processors. However, a
  23  *     compiler barrier will still be required.
  24  *
  25  * Introducing a valid entry into the grant table:
  26  *  1. Write ent->domid.
  27  *  2. Write ent->frame:
  28  *      GTF_permit_access:   Frame to which access is permitted.
  29  *      GTF_accept_transfer: Pseudo-phys frame slot being filled by new
  30  *                           frame, or zero if none.
  31  *  3. Write memory barrier (WMB).
  32  *  4. Write ent->flags, inc. valid type.
  33  *
  34  * Invalidating an unused GTF_permit_access entry:
  35  *  1. flags = ent->flags.
  36  *  2. Observe that !(flags & (GTF_reading|GTF_writing)).
  37  *  3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).
  38  *  NB. No need for WMB as reuse of entry is control-dependent on success of
  39  *      step 3, and all architectures guarantee ordering of ctrl-dep writes.
  40  *
  41  * Invalidating an in-use GTF_permit_access entry:
  42  *  This cannot be done directly. Request assistance from the domain controller
  43  *  which can set a timeout on the use of a grant entry and take necessary
  44  *  action. (NB. This is not yet implemented!).
  45  *
  46  * Invalidating an unused GTF_accept_transfer entry:
  47  *  1. flags = ent->flags.
  48  *  2. Observe that !(flags & GTF_transfer_committed). [*]
  49  *  3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).
  50  *  NB. No need for WMB as reuse of entry is control-dependent on success of
  51  *      step 3, and all architectures guarantee ordering of ctrl-dep writes.
  52  *  [*] If GTF_transfer_committed is set then the grant entry is 'committed'.
  53  *      The guest must /not/ modify the grant entry until the address of the
  54  *      transferred frame is written. It is safe for the guest to spin waiting
  55  *      for this to occur (detect by observing GTF_transfer_completed in
  56  *      ent->flags).
  57  *
  58  * Invalidating a committed GTF_accept_transfer entry:
  59  *  1. Wait for (ent->flags & GTF_transfer_completed).
  60  *
  61  * Changing a GTF_permit_access from writable to read-only:
  62  *  Use SMP-safe CMPXCHG to set GTF_readonly, while checking !GTF_writing.
  63  *
  64  * Changing a GTF_permit_access from read-only to writable:
  65  *  Use SMP-safe bit-setting instruction.
  66  */
  67
  68 /*
  69  * A grant table comprises a packed array of grant entries in one or more
  70  * page frames shared between Xen and a guest.
  71  * [XEN]: This field is written by Xen and read by the sharing guest.
  72  * [GST]: This field is written by the guest and read by Xen.
  73  */
  74 typedef struct {
  75     /* GTF_xxx: various type and flag information.  [XEN,GST] */
  76     u16     flags;      /* 0 */
  77     /* The domain being granted foreign privileges. [GST] */
  78     domid_t domid;      /* 2 */
  79     /*
  80      * GTF_permit_access: Frame that @domid is allowed to map and access. [GST]
  81      * GTF_accept_transfer: Frame whose ownership transferred by @domid. [XEN]
  82      */
  83     u32     frame;      /* 4 */
  84 } PACKED grant_entry_t; /* 8 bytes */
  85
  86 /*
  87  * Type of grant entry.
  88  *  GTF_invalid: This grant entry grants no privileges.
  89  *  GTF_permit_access: Allow @domid to map/access @frame.
  90  *  GTF_accept_transfer: Allow @domid to transfer ownership of one page frame
  91  *                       to this guest. Xen writes the page number to @frame.
  92  */
  93 #define GTF_invalid         (0U<<0)
  94 #define GTF_permit_access   (1U<<0)
  95 #define GTF_accept_transfer (2U<<0)
  96 #define GTF_type_mask       (3U<<0)
  97
  98 /*
  99  * Subflags for GTF_permit_access.
 100  *  GTF_readonly: Restrict @domid to read-only mappings and accesses. [GST]
 101  *  GTF_reading: Grant entry is currently mapped for reading by @domid. [XEN]
 102  *  GTF_writing: Grant entry is currently mapped for writing by @domid. [XEN]
 103  */
 104 #define _GTF_readonly       (2)
 105 #define GTF_readonly        (1U<<_GTF_readonly)
 106 #define _GTF_reading        (3)
 107 #define GTF_reading         (1U<<_GTF_reading)
 108 #define _GTF_writing        (4)
 109 #define GTF_writing         (1U<<_GTF_writing)
 110
 111 /*
 112  * Subflags for GTF_accept_transfer:
 113  *  GTF_transfer_committed: Xen sets this flag to indicate that it is committed
 114  *      to transferring ownership of a page frame. When a guest sees this flag
 115  *      it must /not/ modify the grant entry until GTF_transfer_completed is
 116  *      set by Xen.
 117  *  GTF_transfer_completed: It is safe for the guest to spin-wait on this flag
 118  *      after reading GTF_transfer_committed. Xen will always write the frame
 119  *      address, followed by ORing this flag, in a timely manner.
 120  */
 121 #define _GTF_transfer_committed (2)
 122 #define GTF_transfer_committed  (1U<<_GTF_transfer_committed)
 123 #define _GTF_transfer_completed (3)
 124 #define GTF_transfer_completed  (1U<<_GTF_transfer_completed)
 125
 126
 127 /***********************************
 128  * GRANT TABLE QUERIES AND USES
 129  */
 130
 131 /*
 132  * Reference to a grant entry in a specified domain's grant table.
 133  */
 134 typedef u16 grant_ref_t;
 135
 136 /*
 137  * GNTTABOP_map_grant_ref: Map the grant entry (<dom>,<ref>) for access
 138  * by devices and/or host CPUs. If successful, <handle> is a tracking number
 139  * that must be presented later to destroy the mapping(s). On error, <handle>
 140  * is a negative status code.
 141  * NOTES:
 142  *  1. If GNTPIN_map_for_dev is specified then <dev_bus_addr> is the address
 143  *     via which I/O devices may access the granted frame.
 144  *  2. If GNTPIN_map_for_host is specified then a mapping will be added at
 145  *     virtual address <host_virt_addr> in the current address space.
 146  *  3. Mappings should only be destroyed via GNTTABOP_unmap_grant_ref. If a
 147  *     host mapping is destroyed by other means then it is *NOT* guaranteed
 148  *     to be accounted to the correct grant reference!
 149  */
 150 #define GNTTABOP_map_grant_ref        0
 151 typedef struct {
 152     /* IN parameters. */
 153     memory_t    host_virt_addr;       /*  0 */
 154     MEMORY_PADDING;
 155     domid_t     dom;                  /*  8 */
 156     grant_ref_t ref;                  /* 10 */
 157     u16         flags;                /* 12: GNTMAP_* */
 158     /* OUT parameters. */
 159     s16         handle;               /* 14: +ve: handle; -ve: GNTST_* */
 160     memory_t    dev_bus_addr;         /* 16 */
 161     MEMORY_PADDING;
 162 } PACKED gnttab_map_grant_ref_t; /* 24 bytes */
 163
 164 /*
 165  * GNTTABOP_unmap_grant_ref: Destroy one or more grant-reference mappings
 166  * tracked by <handle>. If <host_virt_addr> or <dev_bus_addr> is zero, that
 167  * field is ignored. If non-zero, they must refer to a device/host mapping
 168  * that is tracked by <handle>
 169  * NOTES:
 170  *  1. The call may fail in an undefined manner if either mapping is not
 171  *     tracked by <handle>.
 172  *  3. After executing a batch of unmaps, it is guaranteed that no stale
 173  *     mappings will remain in the device or host TLBs.
 174  */
 175 #define GNTTABOP_unmap_grant_ref      1
 176 typedef struct {
 177     /* IN parameters. */
 178     memory_t    host_virt_addr;       /*  0 */
 179     MEMORY_PADDING;
 180     memory_t    dev_bus_addr;         /*  8 */
 181     MEMORY_PADDING;
 182     u16         handle;               /* 16 */
 183     /* OUT parameters. */
 184     s16         status;               /* 18: GNTST_* */
 185     u32         __pad;
 186 } PACKED gnttab_unmap_grant_ref_t; /* 24 bytes */
 187
 188 #define GNTUNMAP_DEV_FROM_VIRT (~0U)
 189
 190 /*
 191  * GNTTABOP_setup_table: Set up a grant table for <dom> comprising at least
 192  * <nr_frames> pages. The frame addresses are written to the <frame_list>.
 193  * Only <nr_frames> addresses are written, even if the table is larger.
 194  * NOTES:
 195  *  1. <dom> may be specified as DOMID_SELF.
 196  *  2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
 197  *  3. Xen may not support more than a single grant-table page per domain.
 198  */
 199 #define GNTTABOP_setup_table          2
 200 typedef struct {
 201     /* IN parameters. */
 202     domid_t     dom;                  /*  0 */
 203     u16         nr_frames;            /*  2 */
 204     u16         __pad;
 205     /* OUT parameters. */
 206     s16         status;               /*  6: GNTST_* */
 207     unsigned long *frame_list;        /*  8 */
 208     MEMORY_PADDING;
 209 } PACKED gnttab_setup_table_t; /* 16 bytes */
 210
 211 /*
 212  * GNTTABOP_dump_table: Dump the contents of the grant table to the
 213  * xen console. Debugging use only.
 214  */
 215 #define GNTTABOP_dump_table           3
 216 typedef struct {
 217     /* IN parameters. */
 218     domid_t     dom;                  /*  0 */
 219     /* OUT parameters. */
 220     s16         status;               /* 2: GNTST_* */
 221 } PACKED gnttab_dump_table_t; /* 4 bytes */
 222
 223
 224 /*
 225  * Bitfield values for update_pin_status.flags.
 226  */
 227  /* Map the grant entry for access by I/O devices. */
 228 #define _GNTMAP_device_map      (0)
 229 #define GNTMAP_device_map       (1<<_GNTMAP_device_map)
 230  /* Map the grant entry for access by host CPUs. */
 231 #define _GNTMAP_host_map        (1)
 232 #define GNTMAP_host_map         (1<<_GNTMAP_host_map)
 233  /* Accesses to the granted frame will be restricted to read-only access. */
 234 #define _GNTMAP_readonly        (2)
 235 #define GNTMAP_readonly         (1<<_GNTMAP_readonly)
 236  /*
 237   * GNTMAP_host_map subflag:
 238   *  0 => The host mapping is usable only by the guest OS.
 239   *  1 => The host mapping is usable by guest OS + current application.
 240   */
 241 #define _GNTMAP_application_map (3)
 242 #define GNTMAP_application_map  (1<<_GNTMAP_application_map)
 243
 244 /*
 245  * Values for error status returns. All errors are -ve.
 246  */
 247 #define GNTST_okay             (0)
 248 #define GNTST_general_error    (-1) /* General undefined error.              */
 249 #define GNTST_bad_domain       (-2) /* Unrecognsed domain id.                */
 250 #define GNTST_bad_gntref       (-3) /* Unrecognised or inappropriate gntref. */
 251 #define GNTST_bad_handle       (-4) /* Unrecognised or inappropriate handle. */
 252 #define GNTST_bad_virt_addr    (-5) /* Inappropriate virtual address to map. */
 253 #define GNTST_bad_dev_addr     (-6) /* Inappropriate device address to unmap.*/
 254 #define GNTST_no_device_space  (-7) /* Out of space in I/O MMU.              */
 255 #define GNTST_permission_denied (-8) /* Not enough privilege for operation.  */
 256
 257 #define GNTTABOP_error_msgs {                   \
 258     "okay",                                     \
 259     "undefined error",                          \
 260     "unrecognised domain id",                   \
 261     "invalid grant reference",                  \
 262     "invalid mapping handle",                   \
 263     "invalid virtual address",                  \
 264     "invalid device address",                   \
 265     "no spare translation slot in the I/O MMU", \
 266     "permission denied"                         \
 267 }
 268
 269
 270 typedef struct {
 271     union {                           /*  0 */
 272         gnttab_map_grant_ref_t    map_grant_ref;
 273         gnttab_unmap_grant_ref_t  unmap_grant_ref;
 274         gnttab_setup_table_t      setup_table;
 275         gnttab_dump_table_t       dump_table;
 276         u8                        __dummy[24];
 277     } PACKED u;
 278 } PACKED gnttab_op_t; /* 32 bytes */
 279
 280 #endif /* __XEN_PUBLIC_GRANT_TABLE_H__ */