16b621f9581234eb01d988f9715172e635345b192Anthony PERARD/****************************************************************************** 26b621f9581234eb01d988f9715172e635345b192Anthony PERARD * grant_table.h 36b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 46b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Interface for granting foreign access to page frames, and receiving 56b621f9581234eb01d988f9715172e635345b192Anthony PERARD * page-ownership transfers. 66b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 76b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Permission is hereby granted, free of charge, to any person obtaining a copy 86b621f9581234eb01d988f9715172e635345b192Anthony PERARD * of this software and associated documentation files (the "Software"), to 96b621f9581234eb01d988f9715172e635345b192Anthony PERARD * deal in the Software without restriction, including without limitation the 106b621f9581234eb01d988f9715172e635345b192Anthony PERARD * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 116b621f9581234eb01d988f9715172e635345b192Anthony PERARD * sell copies of the Software, and to permit persons to whom the Software is 126b621f9581234eb01d988f9715172e635345b192Anthony PERARD * furnished to do so, subject to the following conditions: 136b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 146b621f9581234eb01d988f9715172e635345b192Anthony PERARD * The above copyright notice and this permission notice shall be included in 156b621f9581234eb01d988f9715172e635345b192Anthony PERARD * all copies or substantial portions of the Software. 166b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 176b621f9581234eb01d988f9715172e635345b192Anthony PERARD * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 186b621f9581234eb01d988f9715172e635345b192Anthony PERARD * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 196b621f9581234eb01d988f9715172e635345b192Anthony PERARD * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 206b621f9581234eb01d988f9715172e635345b192Anthony PERARD * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 216b621f9581234eb01d988f9715172e635345b192Anthony PERARD * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 226b621f9581234eb01d988f9715172e635345b192Anthony PERARD * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 236b621f9581234eb01d988f9715172e635345b192Anthony PERARD * DEALINGS IN THE SOFTWARE. 246b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 256b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Copyright (c) 2004, K A Fraser 266b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 276b621f9581234eb01d988f9715172e635345b192Anthony PERARD 286b621f9581234eb01d988f9715172e635345b192Anthony PERARD#ifndef __XEN_PUBLIC_GRANT_TABLE_H__ 296b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define __XEN_PUBLIC_GRANT_TABLE_H__ 306b621f9581234eb01d988f9715172e635345b192Anthony PERARD 316b621f9581234eb01d988f9715172e635345b192Anthony PERARD#include "xen.h" 326b621f9581234eb01d988f9715172e635345b192Anthony PERARD 336b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* 346b621f9581234eb01d988f9715172e635345b192Anthony PERARD * `incontents 150 gnttab Grant Tables 356b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 366b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Xen's grant tables provide a generic mechanism to memory sharing 376b621f9581234eb01d988f9715172e635345b192Anthony PERARD * between domains. This shared memory interface underpins the split 386b621f9581234eb01d988f9715172e635345b192Anthony PERARD * device drivers for block and network IO. 396b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 406b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Each domain has its own grant table. This is a data structure that 416b621f9581234eb01d988f9715172e635345b192Anthony PERARD * is shared with Xen; it allows the domain to tell Xen what kind of 426b621f9581234eb01d988f9715172e635345b192Anthony PERARD * permissions other domains have on its pages. Entries in the grant 436b621f9581234eb01d988f9715172e635345b192Anthony PERARD * table are identified by grant references. A grant reference is an 446b621f9581234eb01d988f9715172e635345b192Anthony PERARD * integer, which indexes into the grant table. It acts as a 456b621f9581234eb01d988f9715172e635345b192Anthony PERARD * capability which the grantee can use to perform operations on the 466b621f9581234eb01d988f9715172e635345b192Anthony PERARD * granter’s memory. 476b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 486b621f9581234eb01d988f9715172e635345b192Anthony PERARD * This capability-based system allows shared-memory communications 496b621f9581234eb01d988f9715172e635345b192Anthony PERARD * between unprivileged domains. A grant reference also encapsulates 506b621f9581234eb01d988f9715172e635345b192Anthony PERARD * the details of a shared page, removing the need for a domain to 516b621f9581234eb01d988f9715172e635345b192Anthony PERARD * know the real machine address of a page it is sharing. This makes 526b621f9581234eb01d988f9715172e635345b192Anthony PERARD * it possible to share memory correctly with domains running in 536b621f9581234eb01d988f9715172e635345b192Anthony PERARD * fully virtualised memory. 546b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 556b621f9581234eb01d988f9715172e635345b192Anthony PERARD 566b621f9581234eb01d988f9715172e635345b192Anthony PERARD/*********************************** 576b621f9581234eb01d988f9715172e635345b192Anthony PERARD * GRANT TABLE REPRESENTATION 586b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 596b621f9581234eb01d988f9715172e635345b192Anthony PERARD 606b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* Some rough guidelines on accessing and updating grant-table entries 616b621f9581234eb01d988f9715172e635345b192Anthony PERARD * in a concurrency-safe manner. For more information, Linux contains a 626b621f9581234eb01d988f9715172e635345b192Anthony PERARD * reference implementation for guest OSes (drivers/xen/grant_table.c, see 636b621f9581234eb01d988f9715172e635345b192Anthony PERARD * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/xen/grant-table.c;hb=HEAD 646b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 656b621f9581234eb01d988f9715172e635345b192Anthony PERARD * NB. WMB is a no-op on current-generation x86 processors. However, a 666b621f9581234eb01d988f9715172e635345b192Anthony PERARD * compiler barrier will still be required. 676b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 686b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Introducing a valid entry into the grant table: 696b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 1. Write ent->domid. 706b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 2. Write ent->frame: 716b621f9581234eb01d988f9715172e635345b192Anthony PERARD * GTF_permit_access: Frame to which access is permitted. 726b621f9581234eb01d988f9715172e635345b192Anthony PERARD * GTF_accept_transfer: Pseudo-phys frame slot being filled by new 736b621f9581234eb01d988f9715172e635345b192Anthony PERARD * frame, or zero if none. 746b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 3. Write memory barrier (WMB). 756b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 4. Write ent->flags, inc. valid type. 766b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 776b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Invalidating an unused GTF_permit_access entry: 786b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 1. flags = ent->flags. 796b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 2. Observe that !(flags & (GTF_reading|GTF_writing)). 806b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0). 816b621f9581234eb01d988f9715172e635345b192Anthony PERARD * NB. No need for WMB as reuse of entry is control-dependent on success of 826b621f9581234eb01d988f9715172e635345b192Anthony PERARD * step 3, and all architectures guarantee ordering of ctrl-dep writes. 836b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 846b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Invalidating an in-use GTF_permit_access entry: 856b621f9581234eb01d988f9715172e635345b192Anthony PERARD * This cannot be done directly. Request assistance from the domain controller 866b621f9581234eb01d988f9715172e635345b192Anthony PERARD * which can set a timeout on the use of a grant entry and take necessary 876b621f9581234eb01d988f9715172e635345b192Anthony PERARD * action. (NB. This is not yet implemented!). 886b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 896b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Invalidating an unused GTF_accept_transfer entry: 906b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 1. flags = ent->flags. 916b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 2. Observe that !(flags & GTF_transfer_committed). [*] 926b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0). 936b621f9581234eb01d988f9715172e635345b192Anthony PERARD * NB. No need for WMB as reuse of entry is control-dependent on success of 946b621f9581234eb01d988f9715172e635345b192Anthony PERARD * step 3, and all architectures guarantee ordering of ctrl-dep writes. 956b621f9581234eb01d988f9715172e635345b192Anthony PERARD * [*] If GTF_transfer_committed is set then the grant entry is 'committed'. 966b621f9581234eb01d988f9715172e635345b192Anthony PERARD * The guest must /not/ modify the grant entry until the address of the 976b621f9581234eb01d988f9715172e635345b192Anthony PERARD * transferred frame is written. It is safe for the guest to spin waiting 986b621f9581234eb01d988f9715172e635345b192Anthony PERARD * for this to occur (detect by observing GTF_transfer_completed in 996b621f9581234eb01d988f9715172e635345b192Anthony PERARD * ent->flags). 1006b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 1016b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Invalidating a committed GTF_accept_transfer entry: 1026b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 1. Wait for (ent->flags & GTF_transfer_completed). 1036b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 1046b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Changing a GTF_permit_access from writable to read-only: 1056b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Use SMP-safe CMPXCHG to set GTF_readonly, while checking !GTF_writing. 1066b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 1076b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Changing a GTF_permit_access from read-only to writable: 1086b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Use SMP-safe bit-setting instruction. 1096b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 1106b621f9581234eb01d988f9715172e635345b192Anthony PERARD 1116b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* 1126b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Reference to a grant entry in a specified domain's grant table. 1136b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 1146b621f9581234eb01d988f9715172e635345b192Anthony PERARDtypedef UINT32 grant_ref_t; 1156b621f9581234eb01d988f9715172e635345b192Anthony PERARD 1166b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* 1176b621f9581234eb01d988f9715172e635345b192Anthony PERARD * A grant table comprises a packed array of grant entries in one or more 1186b621f9581234eb01d988f9715172e635345b192Anthony PERARD * page frames shared between Xen and a guest. 1196b621f9581234eb01d988f9715172e635345b192Anthony PERARD * [XEN]: This field is written by Xen and read by the sharing guest. 1206b621f9581234eb01d988f9715172e635345b192Anthony PERARD * [GST]: This field is written by the guest and read by Xen. 1216b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 1226b621f9581234eb01d988f9715172e635345b192Anthony PERARD 1236b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* 1246b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Version 1 of the grant table entry structure is maintained purely 1256b621f9581234eb01d988f9715172e635345b192Anthony PERARD * for backwards compatibility. New guests should use version 2. 1266b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 1276b621f9581234eb01d988f9715172e635345b192Anthony PERARD#if __XEN_INTERFACE_VERSION__ < 0x0003020a 1286b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define grant_entry_v1 grant_entry 1296b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define grant_entry_v1_t grant_entry_t 1306b621f9581234eb01d988f9715172e635345b192Anthony PERARD#endif 1316b621f9581234eb01d988f9715172e635345b192Anthony PERARDstruct grant_entry_v1 { 1326b621f9581234eb01d988f9715172e635345b192Anthony PERARD /* GTF_xxx: various type and flag information. [XEN,GST] */ 1336b621f9581234eb01d988f9715172e635345b192Anthony PERARD UINT16 flags; 1346b621f9581234eb01d988f9715172e635345b192Anthony PERARD /* The domain being granted foreign privileges. [GST] */ 1356b621f9581234eb01d988f9715172e635345b192Anthony PERARD domid_t domid; 1366b621f9581234eb01d988f9715172e635345b192Anthony PERARD /* 1376b621f9581234eb01d988f9715172e635345b192Anthony PERARD * GTF_permit_access: Frame that @domid is allowed to map and access. [GST] 1386b621f9581234eb01d988f9715172e635345b192Anthony PERARD * GTF_accept_transfer: Frame whose ownership transferred by @domid. [XEN] 1396b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 1406b621f9581234eb01d988f9715172e635345b192Anthony PERARD UINT32 frame; 1416b621f9581234eb01d988f9715172e635345b192Anthony PERARD}; 1426b621f9581234eb01d988f9715172e635345b192Anthony PERARDtypedef struct grant_entry_v1 grant_entry_v1_t; 1436b621f9581234eb01d988f9715172e635345b192Anthony PERARD 1446b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* The first few grant table entries will be preserved across grant table 1456b621f9581234eb01d988f9715172e635345b192Anthony PERARD * version changes and may be pre-populated at domain creation by tools. 1466b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 1476b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTTAB_NR_RESERVED_ENTRIES 8 1486b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTTAB_RESERVED_CONSOLE 0 1496b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTTAB_RESERVED_XENSTORE 1 1506b621f9581234eb01d988f9715172e635345b192Anthony PERARD 1516b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* 1526b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Type of grant entry. 1536b621f9581234eb01d988f9715172e635345b192Anthony PERARD * GTF_invalid: This grant entry grants no privileges. 1546b621f9581234eb01d988f9715172e635345b192Anthony PERARD * GTF_permit_access: Allow @domid to map/access @frame. 1556b621f9581234eb01d988f9715172e635345b192Anthony PERARD * GTF_accept_transfer: Allow @domid to transfer ownership of one page frame 1566b621f9581234eb01d988f9715172e635345b192Anthony PERARD * to this guest. Xen writes the page number to @frame. 1576b621f9581234eb01d988f9715172e635345b192Anthony PERARD * GTF_transitive: Allow @domid to transitively access a subrange of 1586b621f9581234eb01d988f9715172e635345b192Anthony PERARD * @trans_grant in @trans_domid. No mappings are allowed. 1596b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 1606b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GTF_invalid (0U<<0) 1616b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GTF_permit_access (1U<<0) 1626b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GTF_accept_transfer (2U<<0) 1636b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GTF_transitive (3U<<0) 1646b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GTF_type_mask (3U<<0) 1656b621f9581234eb01d988f9715172e635345b192Anthony PERARD 1666b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* 1676b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Subflags for GTF_permit_access. 1686b621f9581234eb01d988f9715172e635345b192Anthony PERARD * GTF_readonly: Restrict @domid to read-only mappings and accesses. [GST] 1696b621f9581234eb01d988f9715172e635345b192Anthony PERARD * GTF_reading: Grant entry is currently mapped for reading by @domid. [XEN] 1706b621f9581234eb01d988f9715172e635345b192Anthony PERARD * GTF_writing: Grant entry is currently mapped for writing by @domid. [XEN] 1716b621f9581234eb01d988f9715172e635345b192Anthony PERARD * GTF_PAT, GTF_PWT, GTF_PCD: (x86) cache attribute flags for the grant [GST] 1726b621f9581234eb01d988f9715172e635345b192Anthony PERARD * GTF_sub_page: Grant access to only a subrange of the page. @domid 1736b621f9581234eb01d988f9715172e635345b192Anthony PERARD * will only be allowed to copy from the grant, and not 1746b621f9581234eb01d988f9715172e635345b192Anthony PERARD * map it. [GST] 1756b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 1766b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define _GTF_readonly (2) 1776b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GTF_readonly (1U<<_GTF_readonly) 1786b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define _GTF_reading (3) 1796b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GTF_reading (1U<<_GTF_reading) 1806b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define _GTF_writing (4) 1816b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GTF_writing (1U<<_GTF_writing) 1826b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define _GTF_PWT (5) 1836b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GTF_PWT (1U<<_GTF_PWT) 1846b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define _GTF_PCD (6) 1856b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GTF_PCD (1U<<_GTF_PCD) 1866b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define _GTF_PAT (7) 1876b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GTF_PAT (1U<<_GTF_PAT) 1886b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define _GTF_sub_page (8) 1896b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GTF_sub_page (1U<<_GTF_sub_page) 1906b621f9581234eb01d988f9715172e635345b192Anthony PERARD 1916b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* 1926b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Subflags for GTF_accept_transfer: 1936b621f9581234eb01d988f9715172e635345b192Anthony PERARD * GTF_transfer_committed: Xen sets this flag to indicate that it is committed 1946b621f9581234eb01d988f9715172e635345b192Anthony PERARD * to transferring ownership of a page frame. When a guest sees this flag 1956b621f9581234eb01d988f9715172e635345b192Anthony PERARD * it must /not/ modify the grant entry until GTF_transfer_completed is 1966b621f9581234eb01d988f9715172e635345b192Anthony PERARD * set by Xen. 1976b621f9581234eb01d988f9715172e635345b192Anthony PERARD * GTF_transfer_completed: It is safe for the guest to spin-wait on this flag 1986b621f9581234eb01d988f9715172e635345b192Anthony PERARD * after reading GTF_transfer_committed. Xen will always write the frame 1996b621f9581234eb01d988f9715172e635345b192Anthony PERARD * address, followed by ORing this flag, in a timely manner. 2006b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 2016b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define _GTF_transfer_committed (2) 2026b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GTF_transfer_committed (1U<<_GTF_transfer_committed) 2036b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define _GTF_transfer_completed (3) 2046b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GTF_transfer_completed (1U<<_GTF_transfer_completed) 2056b621f9581234eb01d988f9715172e635345b192Anthony PERARD 2066b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* 2076b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Version 2 grant table entries. These fulfil the same role as 2086b621f9581234eb01d988f9715172e635345b192Anthony PERARD * version 1 entries, but can represent more complicated operations. 2096b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Any given domain will have either a version 1 or a version 2 table, 2106b621f9581234eb01d988f9715172e635345b192Anthony PERARD * and every entry in the table will be the same version. 2116b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 2126b621f9581234eb01d988f9715172e635345b192Anthony PERARD * The interface by which domains use grant references does not depend 2136b621f9581234eb01d988f9715172e635345b192Anthony PERARD * on the grant table version in use by the other domain. 2146b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 2156b621f9581234eb01d988f9715172e635345b192Anthony PERARD#if __XEN_INTERFACE_VERSION__ >= 0x0003020a 2166b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* 2176b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Version 1 and version 2 grant entries share a common prefix. The 2186b621f9581234eb01d988f9715172e635345b192Anthony PERARD * fields of the prefix are documented as part of struct 2196b621f9581234eb01d988f9715172e635345b192Anthony PERARD * grant_entry_v1. 2206b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 2216b621f9581234eb01d988f9715172e635345b192Anthony PERARDstruct grant_entry_header { 2226b621f9581234eb01d988f9715172e635345b192Anthony PERARD UINT16 flags; 2236b621f9581234eb01d988f9715172e635345b192Anthony PERARD domid_t domid; 2246b621f9581234eb01d988f9715172e635345b192Anthony PERARD}; 2256b621f9581234eb01d988f9715172e635345b192Anthony PERARDtypedef struct grant_entry_header grant_entry_header_t; 2266b621f9581234eb01d988f9715172e635345b192Anthony PERARD 2276b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* 2286b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Version 2 of the grant entry structure. 2296b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 2306b621f9581234eb01d988f9715172e635345b192Anthony PERARDunion grant_entry_v2 { 2316b621f9581234eb01d988f9715172e635345b192Anthony PERARD grant_entry_header_t hdr; 2326b621f9581234eb01d988f9715172e635345b192Anthony PERARD 2336b621f9581234eb01d988f9715172e635345b192Anthony PERARD /* 2346b621f9581234eb01d988f9715172e635345b192Anthony PERARD * This member is used for V1-style full page grants, where either: 2356b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 2366b621f9581234eb01d988f9715172e635345b192Anthony PERARD * -- hdr.type is GTF_accept_transfer, or 2376b621f9581234eb01d988f9715172e635345b192Anthony PERARD * -- hdr.type is GTF_permit_access and GTF_sub_page is not set. 2386b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 2396b621f9581234eb01d988f9715172e635345b192Anthony PERARD * In that case, the frame field has the same semantics as the 2406b621f9581234eb01d988f9715172e635345b192Anthony PERARD * field of the same name in the V1 entry structure. 2416b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 2426b621f9581234eb01d988f9715172e635345b192Anthony PERARD struct { 2436b621f9581234eb01d988f9715172e635345b192Anthony PERARD grant_entry_header_t hdr; 2446b621f9581234eb01d988f9715172e635345b192Anthony PERARD UINT32 pad0; 2456b621f9581234eb01d988f9715172e635345b192Anthony PERARD UINT64 frame; 2466b621f9581234eb01d988f9715172e635345b192Anthony PERARD } full_page; 2476b621f9581234eb01d988f9715172e635345b192Anthony PERARD 2486b621f9581234eb01d988f9715172e635345b192Anthony PERARD /* 2496b621f9581234eb01d988f9715172e635345b192Anthony PERARD * If the grant type is GTF_grant_access and GTF_sub_page is set, 2506b621f9581234eb01d988f9715172e635345b192Anthony PERARD * @domid is allowed to access bytes [@page_off,@page_off+@length) 2516b621f9581234eb01d988f9715172e635345b192Anthony PERARD * in frame @frame. 2526b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 2536b621f9581234eb01d988f9715172e635345b192Anthony PERARD struct { 2546b621f9581234eb01d988f9715172e635345b192Anthony PERARD grant_entry_header_t hdr; 2556b621f9581234eb01d988f9715172e635345b192Anthony PERARD UINT16 page_off; 2566b621f9581234eb01d988f9715172e635345b192Anthony PERARD UINT16 length; 2576b621f9581234eb01d988f9715172e635345b192Anthony PERARD UINT64 frame; 2586b621f9581234eb01d988f9715172e635345b192Anthony PERARD } sub_page; 2596b621f9581234eb01d988f9715172e635345b192Anthony PERARD 2606b621f9581234eb01d988f9715172e635345b192Anthony PERARD /* 2616b621f9581234eb01d988f9715172e635345b192Anthony PERARD * If the grant is GTF_transitive, @domid is allowed to use the 2626b621f9581234eb01d988f9715172e635345b192Anthony PERARD * grant @gref in domain @trans_domid, as if it was the local 2636b621f9581234eb01d988f9715172e635345b192Anthony PERARD * domain. Obviously, the transitive access must be compatible 2646b621f9581234eb01d988f9715172e635345b192Anthony PERARD * with the original grant. 2656b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 2666b621f9581234eb01d988f9715172e635345b192Anthony PERARD * The current version of Xen does not allow transitive grants 2676b621f9581234eb01d988f9715172e635345b192Anthony PERARD * to be mapped. 2686b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 2696b621f9581234eb01d988f9715172e635345b192Anthony PERARD struct { 2706b621f9581234eb01d988f9715172e635345b192Anthony PERARD grant_entry_header_t hdr; 2716b621f9581234eb01d988f9715172e635345b192Anthony PERARD domid_t trans_domid; 2726b621f9581234eb01d988f9715172e635345b192Anthony PERARD UINT16 pad0; 2736b621f9581234eb01d988f9715172e635345b192Anthony PERARD grant_ref_t gref; 2746b621f9581234eb01d988f9715172e635345b192Anthony PERARD } transitive; 2756b621f9581234eb01d988f9715172e635345b192Anthony PERARD 2766b621f9581234eb01d988f9715172e635345b192Anthony PERARD UINT32 __spacer[4]; /* Pad to a power of two */ 2776b621f9581234eb01d988f9715172e635345b192Anthony PERARD}; 2786b621f9581234eb01d988f9715172e635345b192Anthony PERARDtypedef union grant_entry_v2 grant_entry_v2_t; 2796b621f9581234eb01d988f9715172e635345b192Anthony PERARD 2806b621f9581234eb01d988f9715172e635345b192Anthony PERARDtypedef UINT16 grant_status_t; 2816b621f9581234eb01d988f9715172e635345b192Anthony PERARD 2826b621f9581234eb01d988f9715172e635345b192Anthony PERARD#endif /* __XEN_INTERFACE_VERSION__ */ 2836b621f9581234eb01d988f9715172e635345b192Anthony PERARD 2846b621f9581234eb01d988f9715172e635345b192Anthony PERARD/*********************************** 2856b621f9581234eb01d988f9715172e635345b192Anthony PERARD * GRANT TABLE QUERIES AND USES 2866b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 2876b621f9581234eb01d988f9715172e635345b192Anthony PERARD 2886b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* ` enum neg_errnoval 2896b621f9581234eb01d988f9715172e635345b192Anthony PERARD * ` HYPERVISOR_grant_table_op(enum grant_table_op cmd, 2906b621f9581234eb01d988f9715172e635345b192Anthony PERARD * ` VOID *args, 2916b621f9581234eb01d988f9715172e635345b192Anthony PERARD * ` UINT32 count) 2926b621f9581234eb01d988f9715172e635345b192Anthony PERARD * ` 2936b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 2946b621f9581234eb01d988f9715172e635345b192Anthony PERARD * @args points to an array of a per-command data structure. The array 2956b621f9581234eb01d988f9715172e635345b192Anthony PERARD * has @count members 2966b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 2976b621f9581234eb01d988f9715172e635345b192Anthony PERARD 2986b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* ` enum grant_table_op { // GNTTABOP_* => struct gnttab_* */ 2996b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTTABOP_map_grant_ref 0 3006b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTTABOP_unmap_grant_ref 1 3016b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* ` } */ 3026b621f9581234eb01d988f9715172e635345b192Anthony PERARD 3036b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* 3046b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Handle to track a mapping created via a grant reference. 3056b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 3066b621f9581234eb01d988f9715172e635345b192Anthony PERARDtypedef UINT32 grant_handle_t; 3076b621f9581234eb01d988f9715172e635345b192Anthony PERARD 3086b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* 3096b621f9581234eb01d988f9715172e635345b192Anthony PERARD * GNTTABOP_map_grant_ref: Map the grant entry (<dom>,<ref>) for access 3106b621f9581234eb01d988f9715172e635345b192Anthony PERARD * by devices and/or host CPUs. If successful, <handle> is a tracking number 3116b621f9581234eb01d988f9715172e635345b192Anthony PERARD * that must be presented later to destroy the mapping(s). On error, <handle> 3126b621f9581234eb01d988f9715172e635345b192Anthony PERARD * is a negative status code. 3136b621f9581234eb01d988f9715172e635345b192Anthony PERARD * NOTES: 3146b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 1. If GNTMAP_device_map is specified then <dev_bus_addr> is the address 3156b621f9581234eb01d988f9715172e635345b192Anthony PERARD * via which I/O devices may access the granted frame. 3166b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 2. If GNTMAP_host_map is specified then a mapping will be added at 3176b621f9581234eb01d988f9715172e635345b192Anthony PERARD * either a host virtual address in the current address space, or at 3186b621f9581234eb01d988f9715172e635345b192Anthony PERARD * a PTE at the specified machine address. The type of mapping to 3196b621f9581234eb01d988f9715172e635345b192Anthony PERARD * perform is selected through the GNTMAP_contains_pte flag, and the 3206b621f9581234eb01d988f9715172e635345b192Anthony PERARD * address is specified in <host_addr>. 3216b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 3. Mappings should only be destroyed via GNTTABOP_unmap_grant_ref. If a 3226b621f9581234eb01d988f9715172e635345b192Anthony PERARD * host mapping is destroyed by other means then it is *NOT* guaranteed 3236b621f9581234eb01d988f9715172e635345b192Anthony PERARD * to be accounted to the correct grant reference! 3246b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 3256b621f9581234eb01d988f9715172e635345b192Anthony PERARDstruct gnttab_map_grant_ref { 3266b621f9581234eb01d988f9715172e635345b192Anthony PERARD /* IN parameters. */ 3276b621f9581234eb01d988f9715172e635345b192Anthony PERARD UINT64 host_addr; 3286b621f9581234eb01d988f9715172e635345b192Anthony PERARD UINT32 flags; /* GNTMAP_* */ 3296b621f9581234eb01d988f9715172e635345b192Anthony PERARD grant_ref_t ref; 3306b621f9581234eb01d988f9715172e635345b192Anthony PERARD domid_t dom; 3316b621f9581234eb01d988f9715172e635345b192Anthony PERARD /* OUT parameters. */ 3326b621f9581234eb01d988f9715172e635345b192Anthony PERARD INT16 status; /* => enum grant_status */ 3336b621f9581234eb01d988f9715172e635345b192Anthony PERARD grant_handle_t handle; 3346b621f9581234eb01d988f9715172e635345b192Anthony PERARD UINT64 dev_bus_addr; 3356b621f9581234eb01d988f9715172e635345b192Anthony PERARD}; 3366b621f9581234eb01d988f9715172e635345b192Anthony PERARDtypedef struct gnttab_map_grant_ref gnttab_map_grant_ref_t; 3376b621f9581234eb01d988f9715172e635345b192Anthony PERARDDEFINE_XEN_GUEST_HANDLE(gnttab_map_grant_ref_t); 3386b621f9581234eb01d988f9715172e635345b192Anthony PERARD 3396b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* 3406b621f9581234eb01d988f9715172e635345b192Anthony PERARD * GNTTABOP_unmap_grant_ref: Destroy one or more grant-reference mappings 3416b621f9581234eb01d988f9715172e635345b192Anthony PERARD * tracked by <handle>. If <host_addr> or <dev_bus_addr> is zero, that 3426b621f9581234eb01d988f9715172e635345b192Anthony PERARD * field is ignored. If non-zero, they must refer to a device/host mapping 3436b621f9581234eb01d988f9715172e635345b192Anthony PERARD * that is tracked by <handle> 3446b621f9581234eb01d988f9715172e635345b192Anthony PERARD * NOTES: 3456b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 1. The call may fail in an undefined manner if either mapping is not 3466b621f9581234eb01d988f9715172e635345b192Anthony PERARD * tracked by <handle>. 3476b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 3. After executing a batch of unmaps, it is guaranteed that no stale 3486b621f9581234eb01d988f9715172e635345b192Anthony PERARD * mappings will remain in the device or host TLBs. 3496b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 3506b621f9581234eb01d988f9715172e635345b192Anthony PERARDstruct gnttab_unmap_grant_ref { 3516b621f9581234eb01d988f9715172e635345b192Anthony PERARD /* IN parameters. */ 3526b621f9581234eb01d988f9715172e635345b192Anthony PERARD UINT64 host_addr; 3536b621f9581234eb01d988f9715172e635345b192Anthony PERARD UINT64 dev_bus_addr; 3546b621f9581234eb01d988f9715172e635345b192Anthony PERARD grant_handle_t handle; 3556b621f9581234eb01d988f9715172e635345b192Anthony PERARD /* OUT parameters. */ 3566b621f9581234eb01d988f9715172e635345b192Anthony PERARD INT16 status; /* => enum grant_status */ 3576b621f9581234eb01d988f9715172e635345b192Anthony PERARD}; 3586b621f9581234eb01d988f9715172e635345b192Anthony PERARDtypedef struct gnttab_unmap_grant_ref gnttab_unmap_grant_ref_t; 3596b621f9581234eb01d988f9715172e635345b192Anthony PERARDDEFINE_XEN_GUEST_HANDLE(gnttab_unmap_grant_ref_t); 3606b621f9581234eb01d988f9715172e635345b192Anthony PERARD 3616b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* 3626b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Bitfield values for gnttab_map_grant_ref.flags. 3636b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 3646b621f9581234eb01d988f9715172e635345b192Anthony PERARD /* Map the grant entry for access by I/O devices. */ 3656b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define _GNTMAP_device_map (0) 3666b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTMAP_device_map (1<<_GNTMAP_device_map) 3676b621f9581234eb01d988f9715172e635345b192Anthony PERARD /* Map the grant entry for access by host CPUs. */ 3686b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define _GNTMAP_host_map (1) 3696b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTMAP_host_map (1<<_GNTMAP_host_map) 3706b621f9581234eb01d988f9715172e635345b192Anthony PERARD /* Accesses to the granted frame will be restricted to read-only access. */ 3716b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define _GNTMAP_readonly (2) 3726b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTMAP_readonly (1<<_GNTMAP_readonly) 3736b621f9581234eb01d988f9715172e635345b192Anthony PERARD /* 3746b621f9581234eb01d988f9715172e635345b192Anthony PERARD * GNTMAP_host_map subflag: 3756b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 0 => The host mapping is usable only by the guest OS. 3766b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 1 => The host mapping is usable by guest OS + current application. 3776b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 3786b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define _GNTMAP_application_map (3) 3796b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTMAP_application_map (1<<_GNTMAP_application_map) 3806b621f9581234eb01d988f9715172e635345b192Anthony PERARD 3816b621f9581234eb01d988f9715172e635345b192Anthony PERARD /* 3826b621f9581234eb01d988f9715172e635345b192Anthony PERARD * GNTMAP_contains_pte subflag: 3836b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 0 => This map request contains a host virtual address. 3846b621f9581234eb01d988f9715172e635345b192Anthony PERARD * 1 => This map request contains the machine addess of the PTE to update. 3856b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 3866b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define _GNTMAP_contains_pte (4) 3876b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTMAP_contains_pte (1<<_GNTMAP_contains_pte) 3886b621f9581234eb01d988f9715172e635345b192Anthony PERARD 3896b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define _GNTMAP_can_fail (5) 3906b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTMAP_can_fail (1<<_GNTMAP_can_fail) 3916b621f9581234eb01d988f9715172e635345b192Anthony PERARD 3926b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* 3936b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Bits to be placed in guest kernel available PTE bits (architecture 3946b621f9581234eb01d988f9715172e635345b192Anthony PERARD * dependent; only supported when XENFEAT_gnttab_map_avail_bits is set). 3956b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 3966b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define _GNTMAP_guest_avail0 (16) 3976b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTMAP_guest_avail_mask ((UINT32)~0 << _GNTMAP_guest_avail0) 3986b621f9581234eb01d988f9715172e635345b192Anthony PERARD 3996b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* 4006b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Values for error status returns. All errors are -ve. 4016b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 4026b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* ` enum grant_status { */ 4036b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTST_okay (0) /* Normal return. */ 4046b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTST_general_error (-1) /* General undefined error. */ 4056b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTST_bad_domain (-2) /* Unrecognsed domain id. */ 4066b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTST_bad_gntref (-3) /* Unrecognised or inappropriate gntref. */ 4076b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTST_bad_handle (-4) /* Unrecognised or inappropriate handle. */ 4086b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTST_bad_virt_addr (-5) /* Inappropriate virtual address to map. */ 4096b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTST_bad_dev_addr (-6) /* Inappropriate device address to unmap.*/ 4106b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTST_no_device_space (-7) /* Out of space in I/O MMU. */ 4116b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTST_permission_denied (-8) /* Not enough privilege for operation. */ 4126b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTST_bad_page (-9) /* Specified page was invalid for op. */ 4136b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTST_bad_copy_arg (-10) /* copy arguments cross page boundary. */ 4146b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTST_address_too_big (-11) /* transfer page address too large. */ 4156b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTST_eagain (-12) /* Operation not done; try again. */ 4166b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* ` } */ 4176b621f9581234eb01d988f9715172e635345b192Anthony PERARD 4186b621f9581234eb01d988f9715172e635345b192Anthony PERARD#define GNTTABOP_error_msgs { \ 4196b621f9581234eb01d988f9715172e635345b192Anthony PERARD "okay", \ 4206b621f9581234eb01d988f9715172e635345b192Anthony PERARD "undefined error", \ 4216b621f9581234eb01d988f9715172e635345b192Anthony PERARD "unrecognised domain id", \ 4226b621f9581234eb01d988f9715172e635345b192Anthony PERARD "invalid grant reference", \ 4236b621f9581234eb01d988f9715172e635345b192Anthony PERARD "invalid mapping handle", \ 4246b621f9581234eb01d988f9715172e635345b192Anthony PERARD "invalid virtual address", \ 4256b621f9581234eb01d988f9715172e635345b192Anthony PERARD "invalid device address", \ 4266b621f9581234eb01d988f9715172e635345b192Anthony PERARD "no spare translation slot in the I/O MMU", \ 4276b621f9581234eb01d988f9715172e635345b192Anthony PERARD "permission denied", \ 4286b621f9581234eb01d988f9715172e635345b192Anthony PERARD "bad page", \ 4296b621f9581234eb01d988f9715172e635345b192Anthony PERARD "copy arguments cross page boundary", \ 4306b621f9581234eb01d988f9715172e635345b192Anthony PERARD "page address size too large", \ 4316b621f9581234eb01d988f9715172e635345b192Anthony PERARD "operation not done; try again" \ 4326b621f9581234eb01d988f9715172e635345b192Anthony PERARD} 4336b621f9581234eb01d988f9715172e635345b192Anthony PERARD 4346b621f9581234eb01d988f9715172e635345b192Anthony PERARD#endif /* __XEN_PUBLIC_GRANT_TABLE_H__ */ 4356b621f9581234eb01d988f9715172e635345b192Anthony PERARD 4366b621f9581234eb01d988f9715172e635345b192Anthony PERARD/* 4376b621f9581234eb01d988f9715172e635345b192Anthony PERARD * Local variables: 4386b621f9581234eb01d988f9715172e635345b192Anthony PERARD * mode: C 4396b621f9581234eb01d988f9715172e635345b192Anthony PERARD * c-file-style: "BSD" 4406b621f9581234eb01d988f9715172e635345b192Anthony PERARD * c-basic-offset: 4 4416b621f9581234eb01d988f9715172e635345b192Anthony PERARD * tab-width: 4 4426b621f9581234eb01d988f9715172e635345b192Anthony PERARD * indent-tabs-mode: nil 4436b621f9581234eb01d988f9715172e635345b192Anthony PERARD * End: 4446b621f9581234eb01d988f9715172e635345b192Anthony PERARD */ 445