OvmfPkg/Include/IndustryStandard/Xen/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  * SPDX-License-Identifier: MIT
   8  *
   9  * Copyright (c) 2004, K A Fraser
  10  */
  11
  12 #ifndef __XEN_PUBLIC_GRANT_TABLE_H__
  13 #define __XEN_PUBLIC_GRANT_TABLE_H__
  14
  15 #include "xen.h"
  16
  17 /*
  18  * `incontents 150 gnttab Grant Tables
  19  *
  20  * Xen's grant tables provide a generic mechanism to memory sharing
  21  * between domains. This shared memory interface underpins the split
  22  * device drivers for block and network IO.
  23  *
  24  * Each domain has its own grant table. This is a data structure that
  25  * is shared with Xen; it allows the domain to tell Xen what kind of
  26  * permissions other domains have on its pages. Entries in the grant
  27  * table are identified by grant references. A grant reference is an
  28  * integer, which indexes into the grant table. It acts as a
  29  * capability which the grantee can use to perform operations on the
  30  * granter's memory.
  31  *
  32  * This capability-based system allows shared-memory communications
  33  * between unprivileged domains. A grant reference also encapsulates
  34  * the details of a shared page, removing the need for a domain to
  35  * know the real machine address of a page it is sharing. This makes
  36  * it possible to share memory correctly with domains running in
  37  * fully virtualised memory.
  38  */
  39
  40 /***********************************
  41  * GRANT TABLE REPRESENTATION
  42  */
  43
  44 /* Some rough guidelines on accessing and updating grant-table entries
  45  * in a concurrency-safe manner. For more information, Linux contains a
  46  * reference implementation for guest OSes (drivers/xen/grant_table.c, see
  47  * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/xen/grant-table.c;hb=HEAD
  48  *
  49  * NB. WMB is a no-op on current-generation x86 processors. However, a
  50  *     compiler barrier will still be required.
  51  *
  52  * Introducing a valid entry into the grant table:
  53  *  1. Write ent->domid.
  54  *  2. Write ent->frame:
  55  *      GTF_permit_access:   Frame to which access is permitted.
  56  *      GTF_accept_transfer: Pseudo-phys frame slot being filled by new
  57  *                           frame, or zero if none.
  58  *  3. Write memory barrier (WMB).
  59  *  4. Write ent->flags, inc. valid type.
  60  *
  61  * Invalidating an unused GTF_permit_access entry:
  62  *  1. flags = ent->flags.
  63  *  2. Observe that !(flags & (GTF_reading|GTF_writing)).
  64  *  3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).
  65  *  NB. No need for WMB as reuse of entry is control-dependent on success of
  66  *      step 3, and all architectures guarantee ordering of ctrl-dep writes.
  67  *
  68  * Invalidating an in-use GTF_permit_access entry:
  69  *  This cannot be done directly. Request assistance from the domain controller
  70  *  which can set a timeout on the use of a grant entry and take necessary
  71  *  action. (NB. This is not yet implemented!).
  72  *
  73  * Invalidating an unused GTF_accept_transfer entry:
  74  *  1. flags = ent->flags.
  75  *  2. Observe that !(flags & GTF_transfer_committed). [*]
  76  *  3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).
  77  *  NB. No need for WMB as reuse of entry is control-dependent on success of
  78  *      step 3, and all architectures guarantee ordering of ctrl-dep writes.
  79  *  [*] If GTF_transfer_committed is set then the grant entry is 'committed'.
  80  *      The guest must /not/ modify the grant entry until the address of the
  81  *      transferred frame is written. It is safe for the guest to spin waiting
  82  *      for this to occur (detect by observing GTF_transfer_completed in
  83  *      ent->flags).
  84  *
  85  * Invalidating a committed GTF_accept_transfer entry:
  86  *  1. Wait for (ent->flags & GTF_transfer_completed).
  87  *
  88  * Changing a GTF_permit_access from writable to read-only:
  89  *  Use SMP-safe CMPXCHG to set GTF_readonly, while checking !GTF_writing.
  90  *
  91  * Changing a GTF_permit_access from read-only to writable:
  92  *  Use SMP-safe bit-setting instruction.
  93  */
  94
  95 /*
  96  * Reference to a grant entry in a specified domain's grant table.
  97  */
  98 typedef UINT32 grant_ref_t;
  99
 100 /*
 101  * A grant table comprises a packed array of grant entries in one or more
 102  * page frames shared between Xen and a guest.
 103  * [XEN]: This field is written by Xen and read by the sharing guest.
 104  * [GST]: This field is written by the guest and read by Xen.
 105  */
 106
 107 /*
 108  * Version 1 of the grant table entry structure is maintained purely
 109  * for backwards compatibility.  New guests should use version 2.
 110  */
 111 #if __XEN_INTERFACE_VERSION__ < 0x0003020a
 112 #define grant_entry_v1    grant_entry
 113 #define grant_entry_v1_t  grant_entry_t
 114 #endif
 115 struct grant_entry_v1 {
 116   /* GTF_xxx: various type and flag information.  [XEN,GST] */
 117   UINT16     flags;
 118   /* The domain being granted foreign privileges. [GST] */
 119   domid_t    domid;
 120
 121   /*
 122    * GTF_permit_access: Frame that @domid is allowed to map and access. [GST]
 123    * GTF_accept_transfer: Frame whose ownership transferred by @domid. [XEN]
 124    */
 125   UINT32     frame;
 126 };
 127
 128 typedef struct grant_entry_v1 grant_entry_v1_t;
 129
 130 /* The first few grant table entries will be preserved across grant table
 131  * version changes and may be pre-populated at domain creation by tools.
 132  */
 133 #define GNTTAB_NR_RESERVED_ENTRIES  8
 134 #define GNTTAB_RESERVED_CONSOLE     0
 135 #define GNTTAB_RESERVED_XENSTORE    1
 136
 137 /*
 138  * Type of grant entry.
 139  *  GTF_invalid: This grant entry grants no privileges.
 140  *  GTF_permit_access: Allow @domid to map/access @frame.
 141  *  GTF_accept_transfer: Allow @domid to transfer ownership of one page frame
 142  *                       to this guest. Xen writes the page number to @frame.
 143  *  GTF_transitive: Allow @domid to transitively access a subrange of
 144  *                  @trans_grant in @trans_domid.  No mappings are allowed.
 145  */
 146 #define GTF_invalid          (0U<<0)
 147 #define GTF_permit_access    (1U<<0)
 148 #define GTF_accept_transfer  (2U<<0)
 149 #define GTF_transitive       (3U<<0)
 150 #define GTF_type_mask        (3U<<0)
 151
 152 /*
 153  * Subflags for GTF_permit_access.
 154  *  GTF_readonly: Restrict @domid to read-only mappings and accesses. [GST]
 155  *  GTF_reading: Grant entry is currently mapped for reading by @domid. [XEN]
 156  *  GTF_writing: Grant entry is currently mapped for writing by @domid. [XEN]
 157  *  GTF_PAT, GTF_PWT, GTF_PCD: (x86) cache attribute flags for the grant [GST]
 158  *  GTF_sub_page: Grant access to only a subrange of the page.  @domid
 159  *                will only be allowed to copy from the grant, and not
 160  *                map it. [GST]
 161  */
 162 #define _GTF_readonly  (2)
 163 #define GTF_readonly   (1U<<_GTF_readonly)
 164 #define _GTF_reading   (3)
 165 #define GTF_reading    (1U<<_GTF_reading)
 166 #define _GTF_writing   (4)
 167 #define GTF_writing    (1U<<_GTF_writing)
 168 #define _GTF_PWT       (5)
 169 #define GTF_PWT        (1U<<_GTF_PWT)
 170 #define _GTF_PCD       (6)
 171 #define GTF_PCD        (1U<<_GTF_PCD)
 172 #define _GTF_PAT       (7)
 173 #define GTF_PAT        (1U<<_GTF_PAT)
 174 #define _GTF_sub_page  (8)
 175 #define GTF_sub_page   (1U<<_GTF_sub_page)
 176
 177 /*
 178  * Subflags for GTF_accept_transfer:
 179  *  GTF_transfer_committed: Xen sets this flag to indicate that it is committed
 180  *      to transferring ownership of a page frame. When a guest sees this flag
 181  *      it must /not/ modify the grant entry until GTF_transfer_completed is
 182  *      set by Xen.
 183  *  GTF_transfer_completed: It is safe for the guest to spin-wait on this flag
 184  *      after reading GTF_transfer_committed. Xen will always write the frame
 185  *      address, followed by ORing this flag, in a timely manner.
 186  */
 187 #define _GTF_transfer_committed  (2)
 188 #define GTF_transfer_committed   (1U<<_GTF_transfer_committed)
 189 #define _GTF_transfer_completed  (3)
 190 #define GTF_transfer_completed   (1U<<_GTF_transfer_completed)
 191
 192 /*
 193  * Version 2 grant table entries.  These fulfil the same role as
 194  * version 1 entries, but can represent more complicated operations.
 195  * Any given domain will have either a version 1 or a version 2 table,
 196  * and every entry in the table will be the same version.
 197  *
 198  * The interface by which domains use grant references does not depend
 199  * on the grant table version in use by the other domain.
 200  */
 201 #if __XEN_INTERFACE_VERSION__ >= 0x0003020a
 202
 203 /*
 204  * Version 1 and version 2 grant entries share a common prefix.  The
 205  * fields of the prefix are documented as part of struct
 206  * grant_entry_v1.
 207  */
 208 struct grant_entry_header {
 209   UINT16     flags;
 210   domid_t    domid;
 211 };
 212
 213 typedef struct grant_entry_header grant_entry_header_t;
 214
 215 /*
 216  * Version 2 of the grant entry structure.
 217  */
 218 union grant_entry_v2 {
 219   grant_entry_header_t    hdr;
 220
 221   /*
 222    * This member is used for V1-style full page grants, where either:
 223    *
 224    * -- hdr.type is GTF_accept_transfer, or
 225    * -- hdr.type is GTF_permit_access and GTF_sub_page is not set.
 226    *
 227    * In that case, the frame field has the same semantics as the
 228    * field of the same name in the V1 entry structure.
 229    */
 230   struct {
 231     grant_entry_header_t    hdr;
 232     UINT32                  pad0;
 233     UINT64                  frame;
 234   } full_page;
 235
 236   /*
 237    * If the grant type is GTF_grant_access and GTF_sub_page is set,
 238    * @domid is allowed to access bytes [@page_off,@page_off+@length)
 239    * in frame @frame.
 240    */
 241   struct {
 242     grant_entry_header_t    hdr;
 243     UINT16                  page_off;
 244     UINT16                  length;
 245     UINT64                  frame;
 246   } sub_page;
 247
 248   /*
 249    * If the grant is GTF_transitive, @domid is allowed to use the
 250    * grant @gref in domain @trans_domid, as if it was the local
 251    * domain.  Obviously, the transitive access must be compatible
 252    * with the original grant.
 253    *
 254    * The current version of Xen does not allow transitive grants
 255    * to be mapped.
 256    */
 257   struct {
 258     grant_entry_header_t    hdr;
 259     domid_t                 trans_domid;
 260     UINT16                  pad0;
 261     grant_ref_t             gref;
 262   } transitive;
 263
 264   UINT32    __spacer[4]; /* Pad to a power of two */
 265 };
 266
 267 typedef union grant_entry_v2 grant_entry_v2_t;
 268
 269 typedef UINT16 grant_status_t;
 270
 271 #endif /* __XEN_INTERFACE_VERSION__ */
 272
 273 /***********************************
 274  * GRANT TABLE QUERIES AND USES
 275  */
 276
 277 /* ` enum neg_errnoval
 278  * ` HYPERVISOR_grant_table_op(enum grant_table_op cmd,
 279  * `                           VOID *args,
 280  * `                           UINT32 count)
 281  * `
 282  *
 283  * @args points to an array of a per-command data structure. The array
 284  * has @count members
 285  */
 286
 287 /* ` enum grant_table_op { // GNTTABOP_* => struct gnttab_* */
 288 #define GNTTABOP_map_grant_ref    0
 289 #define GNTTABOP_unmap_grant_ref  1
 290 /* ` } */
 291
 292 /*
 293  * Handle to track a mapping created via a grant reference.
 294  */
 295 typedef UINT32 grant_handle_t;
 296
 297 /*
 298  * GNTTABOP_map_grant_ref: Map the grant entry (<dom>,<ref>) for access
 299  * by devices and/or host CPUs. If successful, <handle> is a tracking number
 300  * that must be presented later to destroy the mapping(s). On error, <handle>
 301  * is a negative status code.
 302  * NOTES:
 303  *  1. If GNTMAP_device_map is specified then <dev_bus_addr> is the address
 304  *     via which I/O devices may access the granted frame.
 305  *  2. If GNTMAP_host_map is specified then a mapping will be added at
 306  *     either a host virtual address in the current address space, or at
 307  *     a PTE at the specified machine address.  The type of mapping to
 308  *     perform is selected through the GNTMAP_contains_pte flag, and the
 309  *     address is specified in <host_addr>.
 310  *  3. Mappings should only be destroyed via GNTTABOP_unmap_grant_ref. If a
 311  *     host mapping is destroyed by other means then it is *NOT* guaranteed
 312  *     to be accounted to the correct grant reference!
 313  */
 314 struct gnttab_map_grant_ref {
 315   /* IN parameters. */
 316   UINT64            host_addr;
 317   UINT32            flags;      /* GNTMAP_* */
 318   grant_ref_t       ref;
 319   domid_t           dom;
 320   /* OUT parameters. */
 321   INT16             status;     /* => enum grant_status */
 322   grant_handle_t    handle;
 323   UINT64            dev_bus_addr;
 324 };
 325
 326 typedef struct gnttab_map_grant_ref gnttab_map_grant_ref_t;
 327 DEFINE_XEN_GUEST_HANDLE (gnttab_map_grant_ref_t);
 328
 329 /*
 330  * GNTTABOP_unmap_grant_ref: Destroy one or more grant-reference mappings
 331  * tracked by <handle>. If <host_addr> or <dev_bus_addr> is zero, that
 332  * field is ignored. If non-zero, they must refer to a device/host mapping
 333  * that is tracked by <handle>
 334  * NOTES:
 335  *  1. The call may fail in an undefined manner if either mapping is not
 336  *     tracked by <handle>.
 337  *  3. After executing a batch of unmaps, it is guaranteed that no stale
 338  *     mappings will remain in the device or host TLBs.
 339  */
 340 struct gnttab_unmap_grant_ref {
 341   /* IN parameters. */
 342   UINT64            host_addr;
 343   UINT64            dev_bus_addr;
 344   grant_handle_t    handle;
 345   /* OUT parameters. */
 346   INT16             status;     /* => enum grant_status */
 347 };
 348
 349 typedef struct gnttab_unmap_grant_ref gnttab_unmap_grant_ref_t;
 350 DEFINE_XEN_GUEST_HANDLE (gnttab_unmap_grant_ref_t);
 351
 352 /*
 353  * Bitfield values for gnttab_map_grant_ref.flags.
 354  */
 355 /* Map the grant entry for access by I/O devices. */
 356 #define _GNTMAP_device_map  (0)
 357 #define GNTMAP_device_map   (1<<_GNTMAP_device_map)
 358 /* Map the grant entry for access by host CPUs. */
 359 #define _GNTMAP_host_map  (1)
 360 #define GNTMAP_host_map   (1<<_GNTMAP_host_map)
 361 /* Accesses to the granted frame will be restricted to read-only access. */
 362 #define _GNTMAP_readonly  (2)
 363 #define GNTMAP_readonly   (1<<_GNTMAP_readonly)
 364
 365 /*
 366  * GNTMAP_host_map subflag:
 367  *  0 => The host mapping is usable only by the guest OS.
 368  *  1 => The host mapping is usable by guest OS + current application.
 369  */
 370 #define _GNTMAP_application_map  (3)
 371 #define GNTMAP_application_map   (1<<_GNTMAP_application_map)
 372
 373 /*
 374  * GNTMAP_contains_pte subflag:
 375  *  0 => This map request contains a host virtual address.
 376  *  1 => This map request contains the machine address of the PTE to update.
 377  */
 378 #define _GNTMAP_contains_pte  (4)
 379 #define GNTMAP_contains_pte   (1<<_GNTMAP_contains_pte)
 380
 381 #define _GNTMAP_can_fail  (5)
 382 #define GNTMAP_can_fail   (1<<_GNTMAP_can_fail)
 383
 384 /*
 385  * Bits to be placed in guest kernel available PTE bits (architecture
 386  * dependent; only supported when XENFEAT_gnttab_map_avail_bits is set).
 387  */
 388 #define _GNTMAP_guest_avail0     (16)
 389 #define GNTMAP_guest_avail_mask  ((UINT32)~0 << _GNTMAP_guest_avail0)
 390
 391 /*
 392  * Values for error status returns. All errors are -ve.
 393  */
 394 /* ` enum grant_status { */
 395 #define GNTST_okay               (0)   /* Normal return.                        */
 396 #define GNTST_general_error      (-1)  /* General undefined error.              */
 397 #define GNTST_bad_domain         (-2)  /* Unrecognised domain id.               */
 398 #define GNTST_bad_gntref         (-3)  /* Unrecognised or inappropriate gntref. */
 399 #define GNTST_bad_handle         (-4)  /* Unrecognised or inappropriate handle. */
 400 #define GNTST_bad_virt_addr      (-5)  /* Inappropriate virtual address to map. */
 401 #define GNTST_bad_dev_addr       (-6)  /* Inappropriate device address to unmap.*/
 402 #define GNTST_no_device_space    (-7)  /* Out of space in I/O MMU.              */
 403 #define GNTST_permission_denied  (-8)  /* Not enough privilege for operation.  */
 404 #define GNTST_bad_page           (-9)  /* Specified page was invalid for op.    */
 405 #define GNTST_bad_copy_arg       (-10) /* copy arguments cross page boundary.   */
 406 #define GNTST_address_too_big    (-11) /* transfer page address too large.      */
 407 #define GNTST_eagain             (-12) /* Operation not done; try again.        */
 408 /* ` } */
 409
 410 #define GNTTABOP_error_msgs  {                  \
 411     "okay",                                     \
 412     "undefined error",                          \
 413     "unrecognised domain id",                   \
 414     "invalid grant reference",                  \
 415     "invalid mapping handle",                   \
 416     "invalid virtual address",                  \
 417     "invalid device address",                   \
 418     "no spare translation slot in the I/O MMU", \
 419     "permission denied",                        \
 420     "bad page",                                 \
 421     "copy arguments cross page boundary",       \
 422     "page address size too large",              \
 423     "operation not done; try again"             \
 424 }
 425
 426 #endif /* __XEN_PUBLIC_GRANT_TABLE_H__ */
 427
 428 /*
 429  * Local variables:
 430  * mode: C
 431  * c-file-style: "BSD"
 432  * c-basic-offset: 4
 433  * tab-width: 4
 434  * indent-tabs-mode: nil
 435  * End:
 436  */