include/xen/interface/grant_table.h

Source file repositories/reference/linux-study-clean/include/xen/interface/grant_table.h

File Facts

System: Linux kernel
Corpus path: include/xen/interface/grant_table.h
Extension: .h
Size: 21568 bytes
Lines: 591
Domain: Repository Root And Misc
Bucket: include
Inferred role: Repository Root And Misc: implementation source
Status: source implementation candidate

Why This File Exists

Top-level or miscellaneous repository surface. Use this as map coverage unless a later manual pass promotes the file into a deeper subsystem dossier.

Top-level or miscellaneous repository surface. Use this as map coverage unless a later manual pass promotes the file into a deeper subsystem dossier.
Defines or uses C structs; map object ownership, embedded links, reference counts, and lock ownership.

Dependency Surface

xen/interface/xen.h

Detected Declarations

struct grant_entry_v1
struct grant_entry_header
struct gnttab_map_grant_ref
struct gnttab_unmap_grant_ref
struct gnttab_setup_table
struct gnttab_dump_table
struct gnttab_transfer
struct gnttab_copy
struct gnttab_copy_ptr
struct gnttab_query_size
struct gnttab_unmap_and_replace
struct gnttab_set_version
struct gnttab_get_status_frames
struct gnttab_get_version
struct gnttab_swap_grant_ref
struct gnttab_cache_flush

Annotated Snippet

struct grant_entry_v1 {
    /* GTF_xxx: various type and flag information.  [XEN,GST] */
    uint16_t flags;
    /* The domain being granted foreign privileges. [GST] */
    domid_t  domid;
    /*
     * GTF_permit_access: GFN that @domid is allowed to map and access. [GST]
     * GTF_accept_transfer: GFN that @domid is allowed to transfer into. [GST]
     * GTF_transfer_completed: MFN whose ownership transferred by @domid
     *                         (non-translated guests only). [XEN]
     */
    uint32_t frame;
};

/* The first few grant table entries will be preserved across grant table
 * version changes and may be pre-populated at domain creation by tools.
 */
#define GNTTAB_NR_RESERVED_ENTRIES     8
#define GNTTAB_RESERVED_CONSOLE        0
#define GNTTAB_RESERVED_XENSTORE       1

/*
 * Type of grant entry.
 *  GTF_invalid: This grant entry grants no privileges.
 *  GTF_permit_access: Allow @domid to map/access @frame.
 *  GTF_accept_transfer: Allow @domid to transfer ownership of one page frame
 *                       to this guest. Xen writes the page number to @frame.
 *  GTF_transitive: Allow @domid to transitively access a subrange of
 *                  @trans_grant in @trans_domid.  No mappings are allowed.
 */
#define GTF_invalid         (0U<<0)
#define GTF_permit_access   (1U<<0)
#define GTF_accept_transfer (2U<<0)
#define GTF_transitive      (3U<<0)
#define GTF_type_mask       (3U<<0)

/*
 * Subflags for GTF_permit_access and GTF_transitive.
 *  GTF_readonly: Restrict @domid to read-only mappings and accesses. [GST]
 *  GTF_reading: Grant entry is currently mapped for reading by @domid. [XEN]
 *  GTF_writing: Grant entry is currently mapped for writing by @domid. [XEN]
 * Further subflags for GTF_permit_access only.
 *  GTF_PAT, GTF_PWT, GTF_PCD: (x86) cache attribute flags to be used for
 *                             mappings of the grant [GST]
 *  GTF_sub_page: Grant access to only a subrange of the page.  @domid
 *                will only be allowed to copy from the grant, and not
 *                map it. [GST]
 */
#define _GTF_readonly       (2)
#define GTF_readonly        (1U<<_GTF_readonly)
#define _GTF_reading        (3)
#define GTF_reading         (1U<<_GTF_reading)
#define _GTF_writing        (4)
#define GTF_writing         (1U<<_GTF_writing)
#define _GTF_PWT            (5)
#define GTF_PWT             (1U<<_GTF_PWT)
#define _GTF_PCD            (6)
#define GTF_PCD             (1U<<_GTF_PCD)
#define _GTF_PAT            (7)
#define GTF_PAT             (1U<<_GTF_PAT)
#define _GTF_sub_page       (8)
#define GTF_sub_page        (1U<<_GTF_sub_page)

/*
 * Subflags for GTF_accept_transfer:
 *  GTF_transfer_committed: Xen sets this flag to indicate that it is committed
 *      to transferring ownership of a page frame. When a guest sees this flag
 *      it must /not/ modify the grant entry until GTF_transfer_completed is
 *      set by Xen.
 *  GTF_transfer_completed: It is safe for the guest to spin-wait on this flag
 *      after reading GTF_transfer_committed. Xen will always write the frame
 *      address, followed by ORing this flag, in a timely manner.
 */
#define _GTF_transfer_committed (2)
#define GTF_transfer_committed  (1U<<_GTF_transfer_committed)
#define _GTF_transfer_completed (3)
#define GTF_transfer_completed  (1U<<_GTF_transfer_completed)

/*
 * Version 2 grant table entries.  These fulfil the same role as
 * version 1 entries, but can represent more complicated operations.
 * Any given domain will have either a version 1 or a version 2 table,
 * and every entry in the table will be the same version.
 *
 * The interface by which domains use grant references does not depend
 * on the grant table version in use by the other domain.
 */

/*
 * Version 1 and version 2 grant entries share a common prefix.  The

Annotation

Immediate include surface: `xen/interface/xen.h`.
Detected declarations: `struct grant_entry_v1`, `struct grant_entry_header`, `struct gnttab_map_grant_ref`, `struct gnttab_unmap_grant_ref`, `struct gnttab_setup_table`, `struct gnttab_dump_table`, `struct gnttab_transfer`, `struct gnttab_copy`, `struct gnttab_copy_ptr`, `struct gnttab_query_size`.
Atlas domain: Repository Root And Misc / include.
Implementation status: source implementation candidate.

Implementation Notes

This generated page is the file-by-file coverage layer; curated subsystem chapters should link here when they synthesize a multi-file control flow.
Core OS pages should be promoted from atlas-only to deep-reviewed when they explain data structures, invariants, locking, lifecycle, and C implementation snippets.
Driver-family pages are intentionally pattern-oriented unless they are part of the selected PCIe/NVMe representative device path.