xen/interface/grant_table.h

1 /* SPDX-License-Identifier: MIT */
6  * page-ownership transfers.
20  * between domains. This shared memory interface underpins the split
25  * permissions other domains have on its pages. Entries in the grant
31  * This capability-based system allows shared-memory communications
32  * between unprivileged domains. A grant reference also encapsulates
35  * it possible to share memory correctly with domains running in
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:
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.
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
200  * The interface by which domains use grant references does not depend
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.
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.
422  * source and destinations can be eithers MFNs or, for foreign domains,
429  * Note that this can also be used to copy data between two domains
430  * via a third party if the source and destination domains had previously
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.
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).           */
664  * c-file-style: "BSD"
665  * c-basic-offset: 4
666  * tab-width: 4
667  * indent-tabs-mode: nil