|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [Xen-changelog] [xen-unstable] hcall: markup the grant table hypercalls to improve generated docs
# HG changeset patch # User Ian Campbell <ian.campbell@xxxxxxxxxx> # Date 1332843238 -3600 # Node ID ed48258053aea953afd28b746b53af7b8b30531b # Parent 4bd752a4cdf323c41c50f8cd6286f566d67adeae hcall: markup the grant table hypercalls to improve generated docs As part of this I looked through the relevant chapter from interfaces.tex (from 4.1, deleted in unstable) to ensure no critical information was missing. Signed-off-by: Ian Campbell <ian.campbell@xxxxxxxxxx> Acked-by: Keir Fraser <keir@xxxxxxx> Acked-by: Ian Jackson <ian.jackson@xxxxxxxxxxxxx> Committed-by: Ian Campbell <ian.campbell@xxxxxxxxxx> --- diff -r 4bd752a4cdf3 -r ed48258053ae xen/include/public/grant_table.h --- a/xen/include/public/grant_table.h Fri Mar 23 20:51:48 2012 +0000 +++ b/xen/include/public/grant_table.h Tue Mar 27 11:13:58 2012 +0100 @@ -1,9 +1,9 @@ /****************************************************************************** * grant_table.h - * + * * Interface for granting foreign access to page frames, and receiving * page-ownership transfers. - * + * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to * deal in the Software without restriction, including without limitation the @@ -30,17 +30,41 @@ #include "xen.h" +/* + * `incontents 150 gnttab Grant Tables + * + * Xen's grant tables provide a generic mechanism to memory sharing + * between domains. This shared memory interface underpins the split + * device drivers for block and network IO. + * + * Each domain has its own grant table. This is a data structure that + * is shared with Xen; it allows the domain to tell Xen what kind of + * permissions other domains have on its pages. Entries in the grant + * table are identified by grant references. A grant reference is an + * integer, which indexes into the grant table. It acts as a + * capability which the grantee can use to perform operations on the + * granterâ??s memory. + * + * This capability-based system allows shared-memory communications + * between unprivileged domains. A grant reference also encapsulates + * the details of a shared page, removing the need for a domain to + * know the real machine address of a page it is sharing. This makes + * it possible to share memory correctly with domains running in + * fully virtualised memory. + */ + /*********************************** * GRANT TABLE REPRESENTATION */ /* Some rough guidelines on accessing and updating grant-table entries * in a concurrency-safe manner. For more information, Linux contains a - * reference implementation for guest OSes (arch/xen/kernel/grant_table.c). - * + * reference implementation for guest OSes (drivers/xen/grant_table.c, see + * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/xen/grant-table.c;hb=HEAD + * * NB. WMB is a no-op on current-generation x86 processors. However, a * compiler barrier will still be required. - * + * * Introducing a valid entry into the grant table: * 1. Write ent->domid. * 2. Write ent->frame: @@ -49,7 +73,7 @@ * frame, or zero if none. * 3. Write memory barrier (WMB). * 4. Write ent->flags, inc. valid type. - * + * * Invalidating an unused GTF_permit_access entry: * 1. flags = ent->flags. * 2. Observe that !(flags & (GTF_reading|GTF_writing)). @@ -61,7 +85,7 @@ * This cannot be done directly. Request assistance from the domain controller * which can set a timeout on the use of a grant entry and take necessary * action. (NB. This is not yet implemented!). - * + * * Invalidating an unused GTF_accept_transfer entry: * 1. flags = ent->flags. * 2. Observe that !(flags & GTF_transfer_committed). [*] @@ -79,7 +103,7 @@ * * Changing a GTF_permit_access from writable to read-only: * Use SMP-safe CMPXCHG to set GTF_readonly, while checking !GTF_writing. - * + * * Changing a GTF_permit_access from read-only to writable: * Use SMP-safe bit-setting instruction. */ @@ -261,6 +285,33 @@ typedef uint16_t grant_status_t; * GRANT TABLE QUERIES AND USES */ +/* ` enum neg_errnoval + * ` HYPERVISOR_grant_table_op(enum grant_table_op cmd, + * ` void *args, + * ` unsigned int count) + * ` + * + * @args points to an array of a per-command data structure. The array + * has @count members + */ + +/* ` enum grant_table_op { // GNTTABOP_* => struct gnttab_* */ +#define GNTTABOP_map_grant_ref 0 +#define GNTTABOP_unmap_grant_ref 1 +#define GNTTABOP_setup_table 2 +#define GNTTABOP_dump_table 3 +#define GNTTABOP_transfer 4 +#define GNTTABOP_copy 5 +#define GNTTABOP_query_size 6 +#define GNTTABOP_unmap_and_replace 7 +#if __XEN_INTERFACE_VERSION__ >= 0x0003020a +#define GNTTABOP_set_version 8 +#define GNTTABOP_get_status_frames 9 +#define GNTTABOP_get_version 10 +#define GNTTABOP_swap_grant_ref 11 +#endif /* __XEN_INTERFACE_VERSION__ */ +/* ` } */ + /* * Handle to track a mapping created via a grant reference. */ @@ -277,13 +328,12 @@ typedef uint32_t grant_handle_t; * 2. If GNTMAP_host_map is specified then a mapping will be added at * either a host virtual address in the current address space, or at * a PTE at the specified machine address. The type of mapping to - * perform is selected through the GNTMAP_contains_pte flag, and the + * perform is selected through the GNTMAP_contains_pte flag, and the * address is specified in <host_addr>. * 3. Mappings should only be destroyed via GNTTABOP_unmap_grant_ref. If a * host mapping is destroyed by other means then it is *NOT* guaranteed * to be accounted to the correct grant reference! */ -#define GNTTABOP_map_grant_ref 0 struct gnttab_map_grant_ref { /* IN parameters. */ uint64_t host_addr; @@ -291,7 +341,7 @@ struct gnttab_map_grant_ref { grant_ref_t ref; domid_t dom; /* OUT parameters. */ - int16_t status; /* GNTST_* */ + int16_t status; /* => enum grant_status */ grant_handle_t handle; uint64_t dev_bus_addr; }; @@ -309,14 +359,13 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_map_grant * 3. After executing a batch of unmaps, it is guaranteed that no stale * mappings will remain in the device or host TLBs. */ -#define GNTTABOP_unmap_grant_ref 1 struct gnttab_unmap_grant_ref { /* IN parameters. */ uint64_t host_addr; uint64_t dev_bus_addr; grant_handle_t handle; /* OUT parameters. */ - int16_t status; /* GNTST_* */ + int16_t status; /* => enum grant_status */ }; typedef struct gnttab_unmap_grant_ref gnttab_unmap_grant_ref_t; DEFINE_XEN_GUEST_HANDLE(gnttab_unmap_grant_ref_t); @@ -330,13 +379,12 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_unmap_gra * 2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF. * 3. Xen may not support more than a single grant-table page per domain. */ -#define GNTTABOP_setup_table 2 struct gnttab_setup_table { /* IN parameters. */ domid_t dom; uint32_t nr_frames; /* OUT parameters. */ - int16_t status; /* GNTST_* */ + int16_t status; /* => enum grant_status */ XEN_GUEST_HANDLE(ulong) frame_list; }; typedef struct gnttab_setup_table gnttab_setup_table_t; @@ -346,12 +394,11 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_setup_tab * GNTTABOP_dump_table: Dump the contents of the grant table to the * xen console. Debugging use only. */ -#define GNTTABOP_dump_table 3 struct gnttab_dump_table { /* IN parameters. */ domid_t dom; /* OUT parameters. */ - int16_t status; /* GNTST_* */ + int16_t status; /* => enum grant_status */ }; typedef struct gnttab_dump_table gnttab_dump_table_t; DEFINE_XEN_GUEST_HANDLE(gnttab_dump_table_t); @@ -360,11 +407,10 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_dump_tabl * GNTTABOP_transfer_grant_ref: Transfer <frame> to a foreign domain. The * foreign domain has previously registered its interest in the transfer via * <domid, ref>. - * + * * Note that, even if the transfer fails, the specified page no longer belongs * to the calling domain *unless* the error is GNTST_bad_page. */ -#define GNTTABOP_transfer 4 struct gnttab_transfer { /* IN parameters. */ xen_pfn_t mfn; @@ -400,10 +446,9 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_transfer_ #define _GNTCOPY_dest_gref (1) #define GNTCOPY_dest_gref (1<<_GNTCOPY_dest_gref) #define _GNTCOPY_can_fail (2) -#define GNTCOPY_can_fail (1<<_GNTCOPY_can_fail) +#define GNTCOPY_can_fail (1<<_GNTCOPY_can_fail) -#define GNTTABOP_copy 5 -typedef struct gnttab_copy { +struct gnttab_copy { /* IN parameters. */ struct { union { @@ -417,7 +462,8 @@ typedef struct gnttab_copy { uint16_t flags; /* GNTCOPY_* */ /* OUT parameters. */ int16_t status; -} gnttab_copy_t; +}; +typedef struct gnttab_copy gnttab_copy_t; DEFINE_XEN_GUEST_HANDLE(gnttab_copy_t); /* @@ -427,14 +473,13 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_copy_t); * 1. <dom> may be specified as DOMID_SELF. * 2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF. */ -#define GNTTABOP_query_size 6 struct gnttab_query_size { /* IN parameters. */ domid_t dom; /* OUT parameters. */ uint32_t nr_frames; uint32_t max_nr_frames; - int16_t status; /* GNTST_* */ + int16_t status; /* => enum grant_status */ }; typedef struct gnttab_query_size gnttab_query_size_t; DEFINE_XEN_GUEST_HANDLE(gnttab_query_size_t); @@ -450,14 +495,13 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_query_siz * 2. After executing a batch of unmaps, it is guaranteed that no stale * mappings will remain in the device or host TLBs. */ -#define GNTTABOP_unmap_and_replace 7 struct gnttab_unmap_and_replace { /* IN parameters. */ uint64_t host_addr; uint64_t new_addr; grant_handle_t handle; /* OUT parameters. */ - int16_t status; /* GNTST_* */ + int16_t status; /* => enum grant_status */ }; typedef struct gnttab_unmap_and_replace gnttab_unmap_and_replace_t; DEFINE_XEN_GUEST_HANDLE(gnttab_unmap_and_replace_t); @@ -470,7 +514,6 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_unmap_and * are activated; otherwise, the domain will be stuck with version 1. * The only defined versions are 1 and 2. */ -#define GNTTABOP_set_version 8 struct gnttab_set_version { /* IN/OUT parameters */ uint32_t version; @@ -491,13 +534,12 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_set_versi * 1. <dom> may be specified as DOMID_SELF. * 2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF. */ -#define GNTTABOP_get_status_frames 9 struct gnttab_get_status_frames { /* IN parameters. */ uint32_t nr_frames; domid_t dom; /* OUT parameters. */ - int16_t status; /* GNTST_* */ + int16_t status; /* => enum grant_status */ XEN_GUEST_HANDLE(uint64_t) frame_list; }; typedef struct gnttab_get_status_frames gnttab_get_status_frames_t; @@ -507,7 +549,6 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_get_statu * GNTTABOP_get_version: Get the grant table version which is in * effect for domain <dom>. */ -#define GNTTABOP_get_version 10 struct gnttab_get_version { /* IN parameters */ domid_t dom; @@ -518,16 +559,15 @@ struct gnttab_get_version { typedef struct gnttab_get_version gnttab_get_version_t; DEFINE_XEN_GUEST_HANDLE(gnttab_get_version_t); -/* +/* * GNTTABOP_swap_grant_ref: Swap the contents of two grant entries. */ -#define GNTTABOP_swap_grant_ref 11 struct gnttab_swap_grant_ref { /* IN parameters */ grant_ref_t ref_a; grant_ref_t ref_b; /* OUT parameters */ - int16_t status; /* GNTST_* */ + int16_t status; /* => enum grant_status */ }; typedef struct gnttab_swap_grant_ref gnttab_swap_grant_ref_t; DEFINE_XEN_GUEST_HANDLE(gnttab_swap_grant_ref_t); @@ -575,6 +615,7 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_swap_gran /* * Values for error status returns. All errors are -ve. */ +/* ` enum grant_status { */ #define GNTST_okay (0) /* Normal return. */ #define GNTST_general_error (-1) /* General undefined error. */ #define GNTST_bad_domain (-2) /* Unrecognsed domain id. */ @@ -588,6 +629,7 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_swap_gran #define GNTST_bad_copy_arg (-10) /* copy arguments cross page boundary. */ #define GNTST_address_too_big (-11) /* transfer page address too large. */ #define GNTST_eagain (-12) /* Operation not done; try again. */ +/* ` } */ #define GNTTABOP_error_msgs { \ "okay", \ _______________________________________________ Xen-changelog mailing list Xen-changelog@xxxxxxxxxxxxx http://lists.xensource.com/xen-changelog
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |