grant_table.h revision 181624
1181624Skmacy/****************************************************************************** 2181624Skmacy * grant_table.h 3181624Skmacy * 4181624Skmacy * Interface for granting foreign access to page frames, and receiving 5181624Skmacy * page-ownership transfers. 6181624Skmacy * 7181624Skmacy * Permission is hereby granted, free of charge, to any person obtaining a copy 8181624Skmacy * of this software and associated documentation files (the "Software"), to 9181624Skmacy * deal in the Software without restriction, including without limitation the 10181624Skmacy * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 11181624Skmacy * sell copies of the Software, and to permit persons to whom the Software is 12181624Skmacy * furnished to do so, subject to the following conditions: 13181624Skmacy * 14181624Skmacy * The above copyright notice and this permission notice shall be included in 15181624Skmacy * all copies or substantial portions of the Software. 16181624Skmacy * 17181624Skmacy * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18181624Skmacy * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19181624Skmacy * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 20181624Skmacy * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21181624Skmacy * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 22181624Skmacy * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 23181624Skmacy * DEALINGS IN THE SOFTWARE. 24181624Skmacy * 25181624Skmacy * Copyright (c) 2004, K A Fraser 26181624Skmacy */ 27181624Skmacy 28181624Skmacy#ifndef __XEN_PUBLIC_GRANT_TABLE_H__ 29181624Skmacy#define __XEN_PUBLIC_GRANT_TABLE_H__ 30181624Skmacy 31181624Skmacy 32181624Skmacy/*********************************** 33181624Skmacy * GRANT TABLE REPRESENTATION 34181624Skmacy */ 35181624Skmacy 36181624Skmacy/* Some rough guidelines on accessing and updating grant-table entries 37181624Skmacy * in a concurrency-safe manner. For more information, Linux contains a 38181624Skmacy * reference implementation for guest OSes (arch/xen/kernel/grant_table.c). 39181624Skmacy * 40181624Skmacy * NB. WMB is a no-op on current-generation x86 processors. However, a 41181624Skmacy * compiler barrier will still be required. 42181624Skmacy * 43181624Skmacy * Introducing a valid entry into the grant table: 44181624Skmacy * 1. Write ent->domid. 45181624Skmacy * 2. Write ent->frame: 46181624Skmacy * GTF_permit_access: Frame to which access is permitted. 47181624Skmacy * GTF_accept_transfer: Pseudo-phys frame slot being filled by new 48181624Skmacy * frame, or zero if none. 49181624Skmacy * 3. Write memory barrier (WMB). 50181624Skmacy * 4. Write ent->flags, inc. valid type. 51181624Skmacy * 52181624Skmacy * Invalidating an unused GTF_permit_access entry: 53181624Skmacy * 1. flags = ent->flags. 54181624Skmacy * 2. Observe that !(flags & (GTF_reading|GTF_writing)). 55181624Skmacy * 3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0). 56181624Skmacy * NB. No need for WMB as reuse of entry is control-dependent on success of 57181624Skmacy * step 3, and all architectures guarantee ordering of ctrl-dep writes. 58181624Skmacy * 59181624Skmacy * Invalidating an in-use GTF_permit_access entry: 60181624Skmacy * This cannot be done directly. Request assistance from the domain controller 61181624Skmacy * which can set a timeout on the use of a grant entry and take necessary 62181624Skmacy * action. (NB. This is not yet implemented!). 63181624Skmacy * 64181624Skmacy * Invalidating an unused GTF_accept_transfer entry: 65181624Skmacy * 1. flags = ent->flags. 66181624Skmacy * 2. Observe that !(flags & GTF_transfer_committed). [*] 67181624Skmacy * 3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0). 68181624Skmacy * NB. No need for WMB as reuse of entry is control-dependent on success of 69181624Skmacy * step 3, and all architectures guarantee ordering of ctrl-dep writes. 70181624Skmacy * [*] If GTF_transfer_committed is set then the grant entry is 'committed'. 71181624Skmacy * The guest must /not/ modify the grant entry until the address of the 72181624Skmacy * transferred frame is written. It is safe for the guest to spin waiting 73181624Skmacy * for this to occur (detect by observing GTF_transfer_completed in 74181624Skmacy * ent->flags). 75181624Skmacy * 76181624Skmacy * Invalidating a committed GTF_accept_transfer entry: 77181624Skmacy * 1. Wait for (ent->flags & GTF_transfer_completed). 78181624Skmacy * 79181624Skmacy * Changing a GTF_permit_access from writable to read-only: 80181624Skmacy * Use SMP-safe CMPXCHG to set GTF_readonly, while checking !GTF_writing. 81181624Skmacy * 82181624Skmacy * Changing a GTF_permit_access from read-only to writable: 83181624Skmacy * Use SMP-safe bit-setting instruction. 84181624Skmacy */ 85181624Skmacy 86181624Skmacy/* 87181624Skmacy * A grant table comprises a packed array of grant entries in one or more 88181624Skmacy * page frames shared between Xen and a guest. 89181624Skmacy * [XEN]: This field is written by Xen and read by the sharing guest. 90181624Skmacy * [GST]: This field is written by the guest and read by Xen. 91181624Skmacy */ 92181624Skmacystruct grant_entry { 93181624Skmacy /* GTF_xxx: various type and flag information. [XEN,GST] */ 94181624Skmacy uint16_t flags; 95181624Skmacy /* The domain being granted foreign privileges. [GST] */ 96181624Skmacy domid_t domid; 97181624Skmacy /* 98181624Skmacy * GTF_permit_access: Frame that @domid is allowed to map and access. [GST] 99181624Skmacy * GTF_accept_transfer: Frame whose ownership transferred by @domid. [XEN] 100181624Skmacy */ 101181624Skmacy uint32_t frame; 102181624Skmacy}; 103181624Skmacytypedef struct grant_entry grant_entry_t; 104181624Skmacy 105181624Skmacy/* 106181624Skmacy * Type of grant entry. 107181624Skmacy * GTF_invalid: This grant entry grants no privileges. 108181624Skmacy * GTF_permit_access: Allow @domid to map/access @frame. 109181624Skmacy * GTF_accept_transfer: Allow @domid to transfer ownership of one page frame 110181624Skmacy * to this guest. Xen writes the page number to @frame. 111181624Skmacy */ 112181624Skmacy#define GTF_invalid (0U<<0) 113181624Skmacy#define GTF_permit_access (1U<<0) 114181624Skmacy#define GTF_accept_transfer (2U<<0) 115181624Skmacy#define GTF_type_mask (3U<<0) 116181624Skmacy 117181624Skmacy/* 118181624Skmacy * Subflags for GTF_permit_access. 119181624Skmacy * GTF_readonly: Restrict @domid to read-only mappings and accesses. [GST] 120181624Skmacy * GTF_reading: Grant entry is currently mapped for reading by @domid. [XEN] 121181624Skmacy * GTF_writing: Grant entry is currently mapped for writing by @domid. [XEN] 122181624Skmacy */ 123181624Skmacy#define _GTF_readonly (2) 124181624Skmacy#define GTF_readonly (1U<<_GTF_readonly) 125181624Skmacy#define _GTF_reading (3) 126181624Skmacy#define GTF_reading (1U<<_GTF_reading) 127181624Skmacy#define _GTF_writing (4) 128181624Skmacy#define GTF_writing (1U<<_GTF_writing) 129181624Skmacy 130181624Skmacy/* 131181624Skmacy * Subflags for GTF_accept_transfer: 132181624Skmacy * GTF_transfer_committed: Xen sets this flag to indicate that it is committed 133181624Skmacy * to transferring ownership of a page frame. When a guest sees this flag 134181624Skmacy * it must /not/ modify the grant entry until GTF_transfer_completed is 135181624Skmacy * set by Xen. 136181624Skmacy * GTF_transfer_completed: It is safe for the guest to spin-wait on this flag 137181624Skmacy * after reading GTF_transfer_committed. Xen will always write the frame 138181624Skmacy * address, followed by ORing this flag, in a timely manner. 139181624Skmacy */ 140181624Skmacy#define _GTF_transfer_committed (2) 141181624Skmacy#define GTF_transfer_committed (1U<<_GTF_transfer_committed) 142181624Skmacy#define _GTF_transfer_completed (3) 143181624Skmacy#define GTF_transfer_completed (1U<<_GTF_transfer_completed) 144181624Skmacy 145181624Skmacy 146181624Skmacy/*********************************** 147181624Skmacy * GRANT TABLE QUERIES AND USES 148181624Skmacy */ 149181624Skmacy 150181624Skmacy/* 151181624Skmacy * Reference to a grant entry in a specified domain's grant table. 152181624Skmacy */ 153181624Skmacytypedef uint32_t grant_ref_t; 154181624Skmacy 155181624Skmacy/* 156181624Skmacy * Handle to track a mapping created via a grant reference. 157181624Skmacy */ 158181624Skmacytypedef uint32_t grant_handle_t; 159181624Skmacy 160181624Skmacy/* 161181624Skmacy * GNTTABOP_map_grant_ref: Map the grant entry (<dom>,<ref>) for access 162181624Skmacy * by devices and/or host CPUs. If successful, <handle> is a tracking number 163181624Skmacy * that must be presented later to destroy the mapping(s). On error, <handle> 164181624Skmacy * is a negative status code. 165181624Skmacy * NOTES: 166181624Skmacy * 1. If GNTMAP_device_map is specified then <dev_bus_addr> is the address 167181624Skmacy * via which I/O devices may access the granted frame. 168181624Skmacy * 2. If GNTMAP_host_map is specified then a mapping will be added at 169181624Skmacy * either a host virtual address in the current address space, or at 170181624Skmacy * a PTE at the specified machine address. The type of mapping to 171181624Skmacy * perform is selected through the GNTMAP_contains_pte flag, and the 172181624Skmacy * address is specified in <host_addr>. 173181624Skmacy * 3. Mappings should only be destroyed via GNTTABOP_unmap_grant_ref. If a 174181624Skmacy * host mapping is destroyed by other means then it is *NOT* guaranteed 175181624Skmacy * to be accounted to the correct grant reference! 176181624Skmacy */ 177181624Skmacy#define GNTTABOP_map_grant_ref 0 178181624Skmacystruct gnttab_map_grant_ref { 179181624Skmacy /* IN parameters. */ 180181624Skmacy uint64_t host_addr; 181181624Skmacy uint32_t flags; /* GNTMAP_* */ 182181624Skmacy grant_ref_t ref; 183181624Skmacy domid_t dom; 184181624Skmacy /* OUT parameters. */ 185181624Skmacy int16_t status; /* GNTST_* */ 186181624Skmacy grant_handle_t handle; 187181624Skmacy uint64_t dev_bus_addr; 188181624Skmacy}; 189181624Skmacytypedef struct gnttab_map_grant_ref gnttab_map_grant_ref_t; 190181624SkmacyDEFINE_XEN_GUEST_HANDLE(gnttab_map_grant_ref_t); 191181624Skmacy 192181624Skmacy/* 193181624Skmacy * GNTTABOP_unmap_grant_ref: Destroy one or more grant-reference mappings 194181624Skmacy * tracked by <handle>. If <host_addr> or <dev_bus_addr> is zero, that 195181624Skmacy * field is ignored. If non-zero, they must refer to a device/host mapping 196181624Skmacy * that is tracked by <handle> 197181624Skmacy * NOTES: 198181624Skmacy * 1. The call may fail in an undefined manner if either mapping is not 199181624Skmacy * tracked by <handle>. 200181624Skmacy * 3. After executing a batch of unmaps, it is guaranteed that no stale 201181624Skmacy * mappings will remain in the device or host TLBs. 202181624Skmacy */ 203181624Skmacy#define GNTTABOP_unmap_grant_ref 1 204181624Skmacystruct gnttab_unmap_grant_ref { 205181624Skmacy /* IN parameters. */ 206181624Skmacy uint64_t host_addr; 207181624Skmacy uint64_t dev_bus_addr; 208181624Skmacy grant_handle_t handle; 209181624Skmacy /* OUT parameters. */ 210181624Skmacy int16_t status; /* GNTST_* */ 211181624Skmacy}; 212181624Skmacytypedef struct gnttab_unmap_grant_ref gnttab_unmap_grant_ref_t; 213181624SkmacyDEFINE_XEN_GUEST_HANDLE(gnttab_unmap_grant_ref_t); 214181624Skmacy 215181624Skmacy/* 216181624Skmacy * GNTTABOP_setup_table: Set up a grant table for <dom> comprising at least 217181624Skmacy * <nr_frames> pages. The frame addresses are written to the <frame_list>. 218181624Skmacy * Only <nr_frames> addresses are written, even if the table is larger. 219181624Skmacy * NOTES: 220181624Skmacy * 1. <dom> may be specified as DOMID_SELF. 221181624Skmacy * 2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF. 222181624Skmacy * 3. Xen may not support more than a single grant-table page per domain. 223181624Skmacy */ 224181624Skmacy#define GNTTABOP_setup_table 2 225181624Skmacystruct gnttab_setup_table { 226181624Skmacy /* IN parameters. */ 227181624Skmacy domid_t dom; 228181624Skmacy uint32_t nr_frames; 229181624Skmacy /* OUT parameters. */ 230181624Skmacy int16_t status; /* GNTST_* */ 231181624Skmacy XEN_GUEST_HANDLE(ulong) frame_list; 232181624Skmacy}; 233181624Skmacytypedef struct gnttab_setup_table gnttab_setup_table_t; 234181624SkmacyDEFINE_XEN_GUEST_HANDLE(gnttab_setup_table_t); 235181624Skmacy 236181624Skmacy/* 237181624Skmacy * GNTTABOP_dump_table: Dump the contents of the grant table to the 238181624Skmacy * xen console. Debugging use only. 239181624Skmacy */ 240181624Skmacy#define GNTTABOP_dump_table 3 241181624Skmacystruct gnttab_dump_table { 242181624Skmacy /* IN parameters. */ 243181624Skmacy domid_t dom; 244181624Skmacy /* OUT parameters. */ 245181624Skmacy int16_t status; /* GNTST_* */ 246181624Skmacy}; 247181624Skmacytypedef struct gnttab_dump_table gnttab_dump_table_t; 248181624SkmacyDEFINE_XEN_GUEST_HANDLE(gnttab_dump_table_t); 249181624Skmacy 250181624Skmacy/* 251181624Skmacy * GNTTABOP_transfer_grant_ref: Transfer <frame> to a foreign domain. The 252181624Skmacy * foreign domain has previously registered its interest in the transfer via 253181624Skmacy * <domid, ref>. 254181624Skmacy * 255181624Skmacy * Note that, even if the transfer fails, the specified page no longer belongs 256181624Skmacy * to the calling domain *unless* the error is GNTST_bad_page. 257181624Skmacy */ 258181624Skmacy#define GNTTABOP_transfer 4 259181624Skmacystruct gnttab_transfer { 260181624Skmacy /* IN parameters. */ 261181624Skmacy xen_pfn_t mfn; 262181624Skmacy domid_t domid; 263181624Skmacy grant_ref_t ref; 264181624Skmacy /* OUT parameters. */ 265181624Skmacy int16_t status; 266181624Skmacy}; 267181624Skmacytypedef struct gnttab_transfer gnttab_transfer_t; 268181624SkmacyDEFINE_XEN_GUEST_HANDLE(gnttab_transfer_t); 269181624Skmacy 270181624Skmacy 271181624Skmacy/* 272181624Skmacy * GNTTABOP_copy: Hypervisor based copy 273181624Skmacy * source and destinations can be eithers MFNs or, for foreign domains, 274181624Skmacy * grant references. the foreign domain has to grant read/write access 275181624Skmacy * in its grant table. 276181624Skmacy * 277181624Skmacy * The flags specify what type source and destinations are (either MFN 278181624Skmacy * or grant reference). 279181624Skmacy * 280181624Skmacy * Note that this can also be used to copy data between two domains 281181624Skmacy * via a third party if the source and destination domains had previously 282181624Skmacy * grant appropriate access to their pages to the third party. 283181624Skmacy * 284181624Skmacy * source_offset specifies an offset in the source frame, dest_offset 285181624Skmacy * the offset in the target frame and len specifies the number of 286181624Skmacy * bytes to be copied. 287181624Skmacy */ 288181624Skmacy 289181624Skmacy#define _GNTCOPY_source_gref (0) 290181624Skmacy#define GNTCOPY_source_gref (1<<_GNTCOPY_source_gref) 291181624Skmacy#define _GNTCOPY_dest_gref (1) 292181624Skmacy#define GNTCOPY_dest_gref (1<<_GNTCOPY_dest_gref) 293181624Skmacy 294181624Skmacy#define GNTTABOP_copy 5 295181624Skmacytypedef struct gnttab_copy { 296181624Skmacy /* IN parameters. */ 297181624Skmacy struct { 298181624Skmacy union { 299181624Skmacy grant_ref_t ref; 300181624Skmacy xen_pfn_t gmfn; 301181624Skmacy } u; 302181624Skmacy domid_t domid; 303181624Skmacy uint16_t offset; 304181624Skmacy } source, dest; 305181624Skmacy uint16_t len; 306181624Skmacy uint16_t flags; /* GNTCOPY_* */ 307181624Skmacy /* OUT parameters. */ 308181624Skmacy int16_t status; 309181624Skmacy} gnttab_copy_t; 310181624SkmacyDEFINE_XEN_GUEST_HANDLE(gnttab_copy_t); 311181624Skmacy 312181624Skmacy/* 313181624Skmacy * GNTTABOP_query_size: Query the current and maximum sizes of the shared 314181624Skmacy * grant table. 315181624Skmacy * NOTES: 316181624Skmacy * 1. <dom> may be specified as DOMID_SELF. 317181624Skmacy * 2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF. 318181624Skmacy */ 319181624Skmacy#define GNTTABOP_query_size 6 320181624Skmacystruct gnttab_query_size { 321181624Skmacy /* IN parameters. */ 322181624Skmacy domid_t dom; 323181624Skmacy /* OUT parameters. */ 324181624Skmacy uint32_t nr_frames; 325181624Skmacy uint32_t max_nr_frames; 326181624Skmacy int16_t status; /* GNTST_* */ 327181624Skmacy}; 328181624Skmacytypedef struct gnttab_query_size gnttab_query_size_t; 329181624SkmacyDEFINE_XEN_GUEST_HANDLE(gnttab_query_size_t); 330181624Skmacy 331181624Skmacy 332181624Skmacy/* 333181624Skmacy * Bitfield values for update_pin_status.flags. 334181624Skmacy */ 335181624Skmacy /* Map the grant entry for access by I/O devices. */ 336181624Skmacy#define _GNTMAP_device_map (0) 337181624Skmacy#define GNTMAP_device_map (1<<_GNTMAP_device_map) 338181624Skmacy /* Map the grant entry for access by host CPUs. */ 339181624Skmacy#define _GNTMAP_host_map (1) 340181624Skmacy#define GNTMAP_host_map (1<<_GNTMAP_host_map) 341181624Skmacy /* Accesses to the granted frame will be restricted to read-only access. */ 342181624Skmacy#define _GNTMAP_readonly (2) 343181624Skmacy#define GNTMAP_readonly (1<<_GNTMAP_readonly) 344181624Skmacy /* 345181624Skmacy * GNTMAP_host_map subflag: 346181624Skmacy * 0 => The host mapping is usable only by the guest OS. 347181624Skmacy * 1 => The host mapping is usable by guest OS + current application. 348181624Skmacy */ 349181624Skmacy#define _GNTMAP_application_map (3) 350181624Skmacy#define GNTMAP_application_map (1<<_GNTMAP_application_map) 351181624Skmacy 352181624Skmacy /* 353181624Skmacy * GNTMAP_contains_pte subflag: 354181624Skmacy * 0 => This map request contains a host virtual address. 355181624Skmacy * 1 => This map request contains the machine addess of the PTE to update. 356181624Skmacy */ 357181624Skmacy#define _GNTMAP_contains_pte (4) 358181624Skmacy#define GNTMAP_contains_pte (1<<_GNTMAP_contains_pte) 359181624Skmacy 360181624Skmacy/* 361181624Skmacy * Values for error status returns. All errors are -ve. 362181624Skmacy */ 363181624Skmacy#define GNTST_okay (0) /* Normal return. */ 364181624Skmacy#define GNTST_general_error (-1) /* General undefined error. */ 365181624Skmacy#define GNTST_bad_domain (-2) /* Unrecognsed domain id. */ 366181624Skmacy#define GNTST_bad_gntref (-3) /* Unrecognised or inappropriate gntref. */ 367181624Skmacy#define GNTST_bad_handle (-4) /* Unrecognised or inappropriate handle. */ 368181624Skmacy#define GNTST_bad_virt_addr (-5) /* Inappropriate virtual address to map. */ 369181624Skmacy#define GNTST_bad_dev_addr (-6) /* Inappropriate device address to unmap.*/ 370181624Skmacy#define GNTST_no_device_space (-7) /* Out of space in I/O MMU. */ 371181624Skmacy#define GNTST_permission_denied (-8) /* Not enough privilege for operation. */ 372181624Skmacy#define GNTST_bad_page (-9) /* Specified page was invalid for op. */ 373181624Skmacy#define GNTST_bad_copy_arg (-10) /* copy arguments cross page boundary. */ 374181624Skmacy#define GNTST_address_too_big (-11) /* transfer page address too large. */ 375181624Skmacy 376181624Skmacy#define GNTTABOP_error_msgs { \ 377181624Skmacy "okay", \ 378181624Skmacy "undefined error", \ 379181624Skmacy "unrecognised domain id", \ 380181624Skmacy "invalid grant reference", \ 381181624Skmacy "invalid mapping handle", \ 382181624Skmacy "invalid virtual address", \ 383181624Skmacy "invalid device address", \ 384181624Skmacy "no spare translation slot in the I/O MMU", \ 385181624Skmacy "permission denied", \ 386181624Skmacy "bad page", \ 387181624Skmacy "copy arguments cross page boundary", \ 388181624Skmacy "page address size too large" \ 389181624Skmacy} 390181624Skmacy 391181624Skmacy#endif /* __XEN_PUBLIC_GRANT_TABLE_H__ */ 392181624Skmacy 393181624Skmacy/* 394181624Skmacy * Local variables: 395181624Skmacy * mode: C 396181624Skmacy * c-set-style: "BSD" 397181624Skmacy * c-basic-offset: 4 398181624Skmacy * tab-width: 4 399181624Skmacy * indent-tabs-mode: nil 400181624Skmacy * End: 401181624Skmacy */ 402