xen/interface/grant_table.h

1 /* SPDX-License-Identifier: MIT */
6  * page-ownership transfers.
20 /* Some rough guidelines on accessing and updating grant-table entries
21  * in a concurrency-safe manner. For more information, Linux contains a
23 …* http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/xen/grant-table.c;…
25  * NB. WMB is a no-op on current-generation x86 processors. However, a
29  *  1. Write ent->domid.
30  *  2. Write ent->frame:
32  *      GTF_accept_transfer: Pseudo-phys frame slot being filled by new
35  *  4. Write ent->flags, inc. valid type.
38  *  1. flags = ent->flags.
40  *  3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).
41  *  NB. No need for WMB as reuse of entry is control-dependent on success of
42  *      step 3, and all architectures guarantee ordering of ctrl-dep writes.
44  * Invalidating an in-use GTF_permit_access entry:
50  *  1. flags = ent->flags.
52  *  3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).
53  *  NB. No need for WMB as reuse of entry is control-dependent on success of
54  *      step 3, and all architectures guarantee ordering of ctrl-dep writes.
59  *      ent->flags).
62  *  1. Wait for (ent->flags & GTF_transfer_completed).
64  * Changing a GTF_permit_access from writable to read-only:
65  *  Use SMP-safe CMPXCHG to set GTF_readonly, while checking !GTF_writing.
67  * Changing a GTF_permit_access from read-only to writable:
68  *  Use SMP-safe bit-setting instruction.
97      *                         (non-translated guests only). [XEN]
103  * version changes and may be pre-populated at domain creation by tools.
126  *  GTF_readonly: Restrict @domid to read-only mappings and accesses. [GST]
157  *  GTF_transfer_completed: It is safe for the guest to spin-wait on this flag
193      * This member is used for V1-style full page grants, where either:
195      * -- hdr.type is GTF_accept_transfer, or
196      * -- hdr.type is GTF_permit_access and GTF_sub_page is not set.
269  * NOTES:
295  * GNTTABOP_unmap_grant_ref: Destroy one or more grant-reference mappings
297  * field is ignored. If non-zero, they must refer to a device/host mapping
299  * NOTES:
319  * NOTES:
321  *  2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
322  *  3. Xen may not support more than a single grant-table page per domain.
408  * NOTES:
410  *  2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
423  * GNTTABOP_unmap_and_replace: Destroy one or more grant-reference mappings
427  * NOTES:
463  * NOTES:
465  *  2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
529  /* Accesses to the granted frame will be restricted to read-only access. */
535   *  1 => The host mapping is usable by guest OS + current application.
556  * Values for error status returns. All errors are -ve.
559 #define GNTST_general_error    (-1) /* General undefined error.              */
560 #define GNTST_bad_domain       (-2) /* Unrecognsed domain id.                */
561 #define GNTST_bad_gntref       (-3) /* Unrecognised or inappropriate gntref. */
562 #define GNTST_bad_handle       (-4) /* Unrecognised or inappropriate handle. */
563 #define GNTST_bad_virt_addr    (-5) /* Inappropriate virtual address to map. */
564 #define GNTST_bad_dev_addr     (-6) /* Inappropriate device address to unmap.*/
565 #define GNTST_no_device_space  (-7) /* Out of space in I/O MMU.              */
566 #define GNTST_permission_denied (-8) /* Not enough privilege for operation.  */
567 #define GNTST_bad_page         (-9) /* Specified page was invalid for op.    */
568 #define GNTST_bad_copy_arg    (-10) /* copy arguments cross page boundary.   */
569 #define GNTST_address_too_big (-11) /* transfer page address too large.      */
570 #define GNTST_eagain          (-12) /* Operation not done; try again.        */
571 #define GNTST_no_space        (-13) /* Out of space (handles etc).           */