xen/interface/grant_table.h

1 /* SPDX-License-Identifier: MIT */
6  * page-ownership transfers.
31  * This capability-based system allows shared-memory communications
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.
121      * GTF_permit_access: GFN that @domid is allowed to map and access. [GST]
124      *                         (non-translated guests only). [XEN]
131  * version changes and may be pre-populated at domain creation by tools.
139  *  GTF_invalid: This grant entry grants no privileges.
140  *  GTF_permit_access: Allow @domid to map/access @frame.
144  *                  @trans_grant in @trans_domid.  No mappings are allowed.
154  *  GTF_readonly: Restrict @domid to read-only mappings and accesses. [GST]
162  *                map it. [GST]
185  *  GTF_transfer_completed: It is safe for the guest to spin-wait on this flag
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.
282  * @args points to an array of a per-command data structure. The array
310  * GNTTABOP_map_grant_ref: Map the grant entry (<dom>,<ref>) for access
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
348  *  3. After executing a batch of unmaps, it is guaranteed that no stale
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.
403  * Note that, even if the transfer fails, the specified page no longer belongs
466  *  2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
480  * GNTTABOP_unmap_and_replace: Destroy one or more grant-reference mappings
487  *  2. After executing a batch of unmaps, it is guaranteed that no stale
505  * between different versions, but must be performed while no grants
526  *  2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
590  /* Map the grant entry for access by I/O devices. */
593  /* Map the grant entry for access by host CPUs. */
596  /* Accesses to the granted frame will be restricted to read-only access. */
609   *  0 => This map request contains a host virtual address.
610   *  1 => This map request contains the machine addess of the PTE to update.
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).           */
650     "no spare translation slot in the I/O MMU", \
664  * c-file-style: "BSD"
665  * c-basic-offset: 4
666  * tab-width: 4
667  * indent-tabs-mode: nil