xen/interface/grant_table.h

1 /* SPDX-License-Identifier: MIT */
6  * page-ownership transfers.
23  * Each domain has its own grant table. This is a data structure that
24  * is shared with Xen; it allows the domain to tell Xen what kind of
31  * This capability-based system allows shared-memory communications
33  * the details of a shared page, removing the need for a domain to
43 /* Some rough guidelines on accessing and updating grant-table entries
44  * in a concurrency-safe manner. For more information, Linux contains a
46 …* http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/xen/grant-table.c;…
48  * NB. WMB is a no-op on current-generation x86 processors. However, a
52  *  1. Write ent->domid.
53  *  2. Write ent->frame:
55  *      GTF_accept_transfer: Pseudo-phys frame slot being filled by new
58  *  4. Write ent->flags, inc. valid type.
61  *  1. flags = ent->flags.
63  *  3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).
64  *  NB. No need for WMB as reuse of entry is control-dependent on success of
65  *      step 3, and all architectures guarantee ordering of ctrl-dep writes.
67  * Invalidating an in-use GTF_permit_access entry:
68  *  This cannot be done directly. Request assistance from the domain controller
73  *  1. flags = ent->flags.
75  *  3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).
76  *  NB. No need for WMB as reuse of entry is control-dependent on success of
77  *      step 3, and all architectures guarantee ordering of ctrl-dep writes.
82  *      ent->flags).
85  *  1. Wait for (ent->flags & GTF_transfer_completed).
87  * Changing a GTF_permit_access from writable to read-only:
88  *  Use SMP-safe CMPXCHG to set GTF_readonly, while checking !GTF_writing.
90  * Changing a GTF_permit_access from read-only to writable:
91  *  Use SMP-safe bit-setting instruction.
95  * Reference to a grant entry in a specified domain's grant table.
118     /* The domain being granted foreign privileges. [GST] */
124      *                         (non-translated guests only). [XEN]
131  * version changes and may be pre-populated at domain creation by tools.
154  *  GTF_readonly: Restrict @domid to read-only mappings and accesses. [GST]
185  *  GTF_transfer_completed: It is safe for the guest to spin-wait on this flag
197  * Any given domain will have either a version 1 or a version 2 table,
201  * on the grant table version in use by the other domain.
222      * This member is used for V1-style full page grants, where either:
224      * -- hdr.type is GTF_accept_transfer, or
225      * -- hdr.type is GTF_permit_access and GTF_sub_page is not set.
250      * grant @gref in domain @trans_domid, as if it was the local
251      * domain.  Obviously, the transitive access must be compatible
264     uint32_t __spacer[4]; /* Pad to a power of two */
282  * @args points to an array of a per-command data structure. The array
341  * GNTTABOP_unmap_grant_ref: Destroy one or more grant-reference mappings
343  * field is ignored. If non-zero, they must refer to a device/host mapping
368  *  2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
369  *  3. Xen may not support more than a single grant-table page per domain.
400  * GNTTABOP_transfer: Transfer <frame> to a foreign domain. The foreign domain
404  * to the calling domain *unless* the error is GNTST_bad_page.
423  * grant references. the foreign domain has to grant read/write access
466  *  2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
480  * GNTTABOP_unmap_and_replace: Destroy one or more grant-reference mappings
526  *  2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
541  * effect for domain <dom>.
568  * page granted to the calling domain by a foreign domain.
596  /* Accesses to the granted frame will be restricted to read-only access. */
623  * Values for error status returns. All errors are -ve.
627 #define GNTST_general_error    (-1) /* General undefined error.              */
628 #define GNTST_bad_domain       (-2) /* Unrecognsed domain id.                */
629 #define GNTST_bad_gntref       (-3) /* Unrecognised or inappropriate gntref. */
630 #define GNTST_bad_handle       (-4) /* Unrecognised or inappropriate handle. */
631 #define GNTST_bad_virt_addr    (-5) /* Inappropriate virtual address to map. */
632 #define GNTST_bad_dev_addr     (-6) /* Inappropriate device address to unmap.*/
633 #define GNTST_no_device_space  (-7) /* Out of space in I/O MMU.              */
634 #define GNTST_permission_denied (-8) /* Not enough privilege for operation.  */
635 #define GNTST_bad_page         (-9) /* Specified page was invalid for op.    */
636 #define GNTST_bad_copy_arg    (-10) /* copy arguments cross page boundary.   */
637 #define GNTST_address_too_big (-11) /* transfer page address too large.      */
638 #define GNTST_eagain          (-12) /* Operation not done; try again.        */
639 #define GNTST_no_space        (-13) /* Out of space (handles etc).           */
645     "unrecognised domain id",                   \
664  * c-file-style: "BSD"
665  * c-basic-offset: 4
666  * tab-width: 4
667  * indent-tabs-mode: nil