grant_table.h 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565
  1. /* SPDX-License-Identifier: MIT
  2. *
  3. * grant_table.h
  4. *
  5. * Interface for granting foreign access to page frames, and receiving
  6. * page-ownership transfers.
  7. *
  8. * Copyright (c) 2004, K A Fraser
  9. */
  10. #ifndef __XEN_PUBLIC_GRANT_TABLE_H__
  11. #define __XEN_PUBLIC_GRANT_TABLE_H__
  12. #include <xen/interface/xen.h>
  13. /***********************************
  14. * GRANT TABLE REPRESENTATION
  15. */
  16. /* Some rough guidelines on accessing and updating grant-table entries
  17. * in a concurrency-safe manner. For more information, Linux contains a
  18. * reference implementation for guest OSes (arch/xen/kernel/grant_table.c).
  19. *
  20. * NB. WMB is a no-op on current-generation x86 processors. However, a
  21. * compiler barrier will still be required.
  22. *
  23. * Introducing a valid entry into the grant table:
  24. * 1. Write ent->domid.
  25. * 2. Write ent->frame:
  26. * GTF_permit_access: Frame to which access is permitted.
  27. * GTF_accept_transfer: Pseudo-phys frame slot being filled by new
  28. * frame, or zero if none.
  29. * 3. Write memory barrier (WMB).
  30. * 4. Write ent->flags, inc. valid type.
  31. *
  32. * Invalidating an unused GTF_permit_access entry:
  33. * 1. flags = ent->flags.
  34. * 2. Observe that !(flags & (GTF_reading|GTF_writing)).
  35. * 3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).
  36. * NB. No need for WMB as reuse of entry is control-dependent on success of
  37. * step 3, and all architectures guarantee ordering of ctrl-dep writes.
  38. *
  39. * Invalidating an in-use GTF_permit_access entry:
  40. * This cannot be done directly. Request assistance from the domain controller
  41. * which can set a timeout on the use of a grant entry and take necessary
  42. * action. (NB. This is not yet implemented!).
  43. *
  44. * Invalidating an unused GTF_accept_transfer entry:
  45. * 1. flags = ent->flags.
  46. * 2. Observe that !(flags & GTF_transfer_committed). [*]
  47. * 3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).
  48. * NB. No need for WMB as reuse of entry is control-dependent on success of
  49. * step 3, and all architectures guarantee ordering of ctrl-dep writes.
  50. * [*] If GTF_transfer_committed is set then the grant entry is 'committed'.
  51. * The guest must /not/ modify the grant entry until the address of the
  52. * transferred frame is written. It is safe for the guest to spin waiting
  53. * for this to occur (detect by observing GTF_transfer_completed in
  54. * ent->flags).
  55. *
  56. * Invalidating a committed GTF_accept_transfer entry:
  57. * 1. Wait for (ent->flags & GTF_transfer_completed).
  58. *
  59. * Changing a GTF_permit_access from writable to read-only:
  60. * Use SMP-safe CMPXCHG to set GTF_readonly, while checking !GTF_writing.
  61. *
  62. * Changing a GTF_permit_access from read-only to writable:
  63. * Use SMP-safe bit-setting instruction.
  64. */
  65. /*
  66. * Reference to a grant entry in a specified domain's grant table.
  67. */
  68. typedef u32 grant_ref_t;
  69. /*
  70. * A grant table comprises a packed array of grant entries in one or more
  71. * page frames shared between Xen and a guest.
  72. * [XEN]: This field is written by Xen and read by the sharing guest.
  73. * [GST]: This field is written by the guest and read by Xen.
  74. */
  75. /*
  76. * Version 1 of the grant table entry structure is maintained purely
  77. * for backwards compatibility. New guests should use version 2.
  78. */
  79. struct grant_entry_v1 {
  80. /* GTF_xxx: various type and flag information. [XEN,GST] */
  81. u16 flags;
  82. /* The domain being granted foreign privileges. [GST] */
  83. domid_t domid;
  84. /*
  85. * GTF_permit_access: Frame that @domid is allowed to map and access. [GST]
  86. * GTF_accept_transfer: Frame whose ownership transferred by @domid. [XEN]
  87. */
  88. u32 frame;
  89. };
  90. /*
  91. * Type of grant entry.
  92. * GTF_invalid: This grant entry grants no privileges.
  93. * GTF_permit_access: Allow @domid to map/access @frame.
  94. * GTF_accept_transfer: Allow @domid to transfer ownership of one page frame
  95. * to this guest. Xen writes the page number to @frame.
  96. * GTF_transitive: Allow @domid to transitively access a subrange of
  97. * @trans_grant in @trans_domid. No mappings are allowed.
  98. */
  99. #define GTF_invalid (0U << 0)
  100. #define GTF_permit_access (1U << 0)
  101. #define GTF_accept_transfer (2U << 0)
  102. #define GTF_transitive (3U << 0)
  103. #define GTF_type_mask (3U << 0)
  104. /*
  105. * Subflags for GTF_permit_access.
  106. * GTF_readonly: Restrict @domid to read-only mappings and accesses. [GST]
  107. * GTF_reading: Grant entry is currently mapped for reading by @domid. [XEN]
  108. * GTF_writing: Grant entry is currently mapped for writing by @domid. [XEN]
  109. * GTF_sub_page: Grant access to only a subrange of the page. @domid
  110. * will only be allowed to copy from the grant, and not
  111. * map it. [GST]
  112. */
  113. #define _GTF_readonly (2)
  114. #define GTF_readonly (1U << _GTF_readonly)
  115. #define _GTF_reading (3)
  116. #define GTF_reading (1U << _GTF_reading)
  117. #define _GTF_writing (4)
  118. #define GTF_writing (1U << _GTF_writing)
  119. #define _GTF_sub_page (8)
  120. #define GTF_sub_page (1U << _GTF_sub_page)
  121. /*
  122. * Subflags for GTF_accept_transfer:
  123. * GTF_transfer_committed: Xen sets this flag to indicate that it is committed
  124. * to transferring ownership of a page frame. When a guest sees this flag
  125. * it must /not/ modify the grant entry until GTF_transfer_completed is
  126. * set by Xen.
  127. * GTF_transfer_completed: It is safe for the guest to spin-wait on this flag
  128. * after reading GTF_transfer_committed. Xen will always write the frame
  129. * address, followed by ORing this flag, in a timely manner.
  130. */
  131. #define _GTF_transfer_committed (2)
  132. #define GTF_transfer_committed (1U << _GTF_transfer_committed)
  133. #define _GTF_transfer_completed (3)
  134. #define GTF_transfer_completed (1U << _GTF_transfer_completed)
  135. /*
  136. * Version 2 grant table entries. These fulfil the same role as
  137. * version 1 entries, but can represent more complicated operations.
  138. * Any given domain will have either a version 1 or a version 2 table,
  139. * and every entry in the table will be the same version.
  140. *
  141. * The interface by which domains use grant references does not depend
  142. * on the grant table version in use by the other domain.
  143. */
  144. /*
  145. * Version 1 and version 2 grant entries share a common prefix. The
  146. * fields of the prefix are documented as part of struct
  147. * grant_entry_v1.
  148. */
  149. struct grant_entry_header {
  150. u16 flags;
  151. domid_t domid;
  152. };
  153. /*
  154. * Version 2 of the grant entry structure, here is a union because three
  155. * different types are suppotted: full_page, sub_page and transitive.
  156. */
  157. union grant_entry_v2 {
  158. struct grant_entry_header hdr;
  159. /*
  160. * This member is used for V1-style full page grants, where either:
  161. *
  162. * -- hdr.type is GTF_accept_transfer, or
  163. * -- hdr.type is GTF_permit_access and GTF_sub_page is not set.
  164. *
  165. * In that case, the frame field has the same semantics as the
  166. * field of the same name in the V1 entry structure.
  167. */
  168. struct {
  169. struct grant_entry_header hdr;
  170. u32 pad0;
  171. u64 frame;
  172. } full_page;
  173. /*
  174. * If the grant type is GTF_grant_access and GTF_sub_page is set,
  175. * @domid is allowed to access bytes [@page_off,@page_off+@length)
  176. * in frame @frame.
  177. */
  178. struct {
  179. struct grant_entry_header hdr;
  180. u16 page_off;
  181. u16 length;
  182. u64 frame;
  183. } sub_page;
  184. /*
  185. * If the grant is GTF_transitive, @domid is allowed to use the
  186. * grant @gref in domain @trans_domid, as if it was the local
  187. * domain. Obviously, the transitive access must be compatible
  188. * with the original grant.
  189. */
  190. struct {
  191. struct grant_entry_header hdr;
  192. domid_t trans_domid;
  193. u16 pad0;
  194. grant_ref_t gref;
  195. } transitive;
  196. u32 __spacer[4]; /* Pad to a power of two */
  197. };
  198. typedef u16 grant_status_t;
  199. /***********************************
  200. * GRANT TABLE QUERIES AND USES
  201. */
  202. /*
  203. * Handle to track a mapping created via a grant reference.
  204. */
  205. typedef u32 grant_handle_t;
  206. /*
  207. * GNTTABOP_map_grant_ref: Map the grant entry (<dom>,<ref>) for access
  208. * by devices and/or host CPUs. If successful, <handle> is a tracking number
  209. * that must be presented later to destroy the mapping(s). On error, <handle>
  210. * is a negative status code.
  211. * NOTES:
  212. * 1. If GNTMAP_device_map is specified then <dev_bus_addr> is the address
  213. * via which I/O devices may access the granted frame.
  214. * 2. If GNTMAP_host_map is specified then a mapping will be added at
  215. * either a host virtual address in the current address space, or at
  216. * a PTE at the specified machine address. The type of mapping to
  217. * perform is selected through the GNTMAP_contains_pte flag, and the
  218. * address is specified in <host_addr>.
  219. * 3. Mappings should only be destroyed via GNTTABOP_unmap_grant_ref. If a
  220. * host mapping is destroyed by other means then it is *NOT* guaranteed
  221. * to be accounted to the correct grant reference!
  222. */
  223. #define GNTTABOP_map_grant_ref 0
  224. struct gnttab_map_grant_ref {
  225. /* IN parameters. */
  226. u64 host_addr;
  227. u32 flags; /* GNTMAP_* */
  228. grant_ref_t ref;
  229. domid_t dom;
  230. /* OUT parameters. */
  231. s16 status; /* GNTST_* */
  232. grant_handle_t handle;
  233. u64 dev_bus_addr;
  234. };
  235. DEFINE_GUEST_HANDLE_STRUCT(gnttab_map_grant_ref);
  236. /*
  237. * GNTTABOP_unmap_grant_ref: Destroy one or more grant-reference mappings
  238. * tracked by <handle>. If <host_addr> or <dev_bus_addr> is zero, that
  239. * field is ignored. If non-zero, they must refer to a device/host mapping
  240. * that is tracked by <handle>
  241. * NOTES:
  242. * 1. The call may fail in an undefined manner if either mapping is not
  243. * tracked by <handle>.
  244. * 3. After executing a batch of unmaps, it is guaranteed that no stale
  245. * mappings will remain in the device or host TLBs.
  246. */
  247. #define GNTTABOP_unmap_grant_ref 1
  248. struct gnttab_unmap_grant_ref {
  249. /* IN parameters. */
  250. u64 host_addr;
  251. u64 dev_bus_addr;
  252. grant_handle_t handle;
  253. /* OUT parameters. */
  254. s16 status; /* GNTST_* */
  255. };
  256. DEFINE_GUEST_HANDLE_STRUCT(gnttab_unmap_grant_ref);
  257. /*
  258. * GNTTABOP_setup_table: Set up a grant table for <dom> comprising at least
  259. * <nr_frames> pages. The frame addresses are written to the <frame_list>.
  260. * Only <nr_frames> addresses are written, even if the table is larger.
  261. * NOTES:
  262. * 1. <dom> may be specified as DOMID_SELF.
  263. * 2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
  264. * 3. Xen may not support more than a single grant-table page per domain.
  265. */
  266. #define GNTTABOP_setup_table 2
  267. struct gnttab_setup_table {
  268. /* IN parameters. */
  269. domid_t dom;
  270. u32 nr_frames;
  271. /* OUT parameters. */
  272. s16 status; /* GNTST_* */
  273. GUEST_HANDLE(xen_pfn_t)frame_list;
  274. };
  275. DEFINE_GUEST_HANDLE_STRUCT(gnttab_setup_table);
  276. /*
  277. * GNTTABOP_dump_table: Dump the contents of the grant table to the
  278. * xen console. Debugging use only.
  279. */
  280. #define GNTTABOP_dump_table 3
  281. struct gnttab_dump_table {
  282. /* IN parameters. */
  283. domid_t dom;
  284. /* OUT parameters. */
  285. s16 status; /* GNTST_* */
  286. };
  287. DEFINE_GUEST_HANDLE_STRUCT(gnttab_dump_table);
  288. /*
  289. * GNTTABOP_transfer_grant_ref: Transfer <frame> to a foreign domain. The
  290. * foreign domain has previously registered its interest in the transfer via
  291. * <domid, ref>.
  292. *
  293. * Note that, even if the transfer fails, the specified page no longer belongs
  294. * to the calling domain *unless* the error is GNTST_bad_page.
  295. */
  296. #define GNTTABOP_transfer 4
  297. struct gnttab_transfer {
  298. /* IN parameters. */
  299. xen_pfn_t mfn;
  300. domid_t domid;
  301. grant_ref_t ref;
  302. /* OUT parameters. */
  303. s16 status;
  304. };
  305. DEFINE_GUEST_HANDLE_STRUCT(gnttab_transfer);
  306. /*
  307. * GNTTABOP_copy: Hypervisor based copy
  308. * source and destinations can be eithers MFNs or, for foreign domains,
  309. * grant references. the foreign domain has to grant read/write access
  310. * in its grant table.
  311. *
  312. * The flags specify what type source and destinations are (either MFN
  313. * or grant reference).
  314. *
  315. * Note that this can also be used to copy data between two domains
  316. * via a third party if the source and destination domains had previously
  317. * grant appropriate access to their pages to the third party.
  318. *
  319. * source_offset specifies an offset in the source frame, dest_offset
  320. * the offset in the target frame and len specifies the number of
  321. * bytes to be copied.
  322. */
  323. #define _GNTCOPY_source_gref (0)
  324. #define GNTCOPY_source_gref (1 << _GNTCOPY_source_gref)
  325. #define _GNTCOPY_dest_gref (1)
  326. #define GNTCOPY_dest_gref (1 << _GNTCOPY_dest_gref)
  327. #define GNTTABOP_copy 5
  328. struct gnttab_copy {
  329. /* IN parameters. */
  330. struct {
  331. union {
  332. grant_ref_t ref;
  333. xen_pfn_t gmfn;
  334. } u;
  335. domid_t domid;
  336. u16 offset;
  337. } source, dest;
  338. u16 len;
  339. u16 flags; /* GNTCOPY_* */
  340. /* OUT parameters. */
  341. s16 status;
  342. };
  343. DEFINE_GUEST_HANDLE_STRUCT(gnttab_copy);
  344. /*
  345. * GNTTABOP_query_size: Query the current and maximum sizes of the shared
  346. * grant table.
  347. * NOTES:
  348. * 1. <dom> may be specified as DOMID_SELF.
  349. * 2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
  350. */
  351. #define GNTTABOP_query_size 6
  352. struct gnttab_query_size {
  353. /* IN parameters. */
  354. domid_t dom;
  355. /* OUT parameters. */
  356. u32 nr_frames;
  357. u32 max_nr_frames;
  358. s16 status; /* GNTST_* */
  359. };
  360. DEFINE_GUEST_HANDLE_STRUCT(gnttab_query_size);
  361. /*
  362. * GNTTABOP_unmap_and_replace: Destroy one or more grant-reference mappings
  363. * tracked by <handle> but atomically replace the page table entry with one
  364. * pointing to the machine address under <new_addr>. <new_addr> will be
  365. * redirected to the null entry.
  366. * NOTES:
  367. * 1. The call may fail in an undefined manner if either mapping is not
  368. * tracked by <handle>.
  369. * 2. After executing a batch of unmaps, it is guaranteed that no stale
  370. * mappings will remain in the device or host TLBs.
  371. */
  372. #define GNTTABOP_unmap_and_replace 7
  373. struct gnttab_unmap_and_replace {
  374. /* IN parameters. */
  375. u64 host_addr;
  376. u64 new_addr;
  377. grant_handle_t handle;
  378. /* OUT parameters. */
  379. s16 status; /* GNTST_* */
  380. };
  381. DEFINE_GUEST_HANDLE_STRUCT(gnttab_unmap_and_replace);
  382. /*
  383. * GNTTABOP_set_version: Request a particular version of the grant
  384. * table shared table structure. This operation can only be performed
  385. * once in any given domain. It must be performed before any grants
  386. * are activated; otherwise, the domain will be stuck with version 1.
  387. * The only defined versions are 1 and 2.
  388. */
  389. #define GNTTABOP_set_version 8
  390. struct gnttab_set_version {
  391. /* IN parameters */
  392. u32 version;
  393. };
  394. DEFINE_GUEST_HANDLE_STRUCT(gnttab_set_version);
  395. /*
  396. * GNTTABOP_get_status_frames: Get the list of frames used to store grant
  397. * status for <dom>. In grant format version 2, the status is separated
  398. * from the other shared grant fields to allow more efficient synchronization
  399. * using barriers instead of atomic cmpexch operations.
  400. * <nr_frames> specify the size of vector <frame_list>.
  401. * The frame addresses are returned in the <frame_list>.
  402. * Only <nr_frames> addresses are returned, even if the table is larger.
  403. * NOTES:
  404. * 1. <dom> may be specified as DOMID_SELF.
  405. * 2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
  406. */
  407. #define GNTTABOP_get_status_frames 9
  408. struct gnttab_get_status_frames {
  409. /* IN parameters. */
  410. u32 nr_frames;
  411. domid_t dom;
  412. /* OUT parameters. */
  413. s16 status; /* GNTST_* */
  414. GUEST_HANDLE(u64)frame_list;
  415. };
  416. DEFINE_GUEST_HANDLE_STRUCT(gnttab_get_status_frames);
  417. /*
  418. * GNTTABOP_get_version: Get the grant table version which is in
  419. * effect for domain <dom>.
  420. */
  421. #define GNTTABOP_get_version 10
  422. struct gnttab_get_version {
  423. /* IN parameters */
  424. domid_t dom;
  425. u16 pad;
  426. /* OUT parameters */
  427. u32 version;
  428. };
  429. DEFINE_GUEST_HANDLE_STRUCT(gnttab_get_version);
  430. /*
  431. * Issue one or more cache maintenance operations on a portion of a
  432. * page granted to the calling domain by a foreign domain.
  433. */
  434. #define GNTTABOP_cache_flush 12
  435. struct gnttab_cache_flush {
  436. union {
  437. u64 dev_bus_addr;
  438. grant_ref_t ref;
  439. } a;
  440. u16 offset; /* offset from start of grant */
  441. u16 length; /* size within the grant */
  442. #define GNTTAB_CACHE_CLEAN (1 << 0)
  443. #define GNTTAB_CACHE_INVAL (1 << 1)
  444. #define GNTTAB_CACHE_SOURCE_GREF (1 << 31)
  445. u32 op;
  446. };
  447. DEFINE_GUEST_HANDLE_STRUCT(gnttab_cache_flush);
  448. /*
  449. * Bitfield values for update_pin_status.flags.
  450. */
  451. /* Map the grant entry for access by I/O devices. */
  452. #define _GNTMAP_device_map (0)
  453. #define GNTMAP_device_map (1 << _GNTMAP_device_map)
  454. /* Map the grant entry for access by host CPUs. */
  455. #define _GNTMAP_host_map (1)
  456. #define GNTMAP_host_map (1 << _GNTMAP_host_map)
  457. /* Accesses to the granted frame will be restricted to read-only access. */
  458. #define _GNTMAP_readonly (2)
  459. #define GNTMAP_readonly (1 << _GNTMAP_readonly)
  460. /*
  461. * GNTMAP_host_map subflag:
  462. * 0 => The host mapping is usable only by the guest OS.
  463. * 1 => The host mapping is usable by guest OS + current application.
  464. */
  465. #define _GNTMAP_application_map (3)
  466. #define GNTMAP_application_map (1 << _GNTMAP_application_map)
  467. /*
  468. * GNTMAP_contains_pte subflag:
  469. * 0 => This map request contains a host virtual address.
  470. * 1 => This map request contains the machine addess of the PTE to update.
  471. */
  472. #define _GNTMAP_contains_pte (4)
  473. #define GNTMAP_contains_pte (1 << _GNTMAP_contains_pte)
  474. /*
  475. * Bits to be placed in guest kernel available PTE bits (architecture
  476. * dependent; only supported when XENFEAT_gnttab_map_avail_bits is set).
  477. */
  478. #define _GNTMAP_guest_avail0 (16)
  479. #define GNTMAP_guest_avail_mask ((u32)~0 << _GNTMAP_guest_avail0)
  480. /*
  481. * Values for error status returns. All errors are -ve.
  482. */
  483. #define GNTST_okay (0) /* Normal return. */
  484. #define GNTST_general_error (-1) /* General undefined error. */
  485. #define GNTST_bad_domain (-2) /* Unrecognsed domain id. */
  486. #define GNTST_bad_gntref (-3) /* Unrecognised or inappropriate gntref. */
  487. #define GNTST_bad_handle (-4) /* Unrecognised or inappropriate handle. */
  488. #define GNTST_bad_virt_addr (-5) /* Inappropriate virtual address to map. */
  489. #define GNTST_bad_dev_addr (-6) /* Inappropriate device address to unmap.*/
  490. #define GNTST_no_device_space (-7) /* Out of space in I/O MMU. */
  491. #define GNTST_permission_denied (-8) /* Not enough privilege for operation. */
  492. #define GNTST_bad_page (-9) /* Specified page was invalid for op. */
  493. #define GNTST_bad_copy_arg (-10) /* copy arguments cross page boundary. */
  494. #define GNTST_address_too_big (-11) /* transfer page address too large. */
  495. #define GNTST_eagain (-12) /* Operation not done; try again. */
  496. #define GNTTABOP_error_msgs { \
  497. "okay", \
  498. "undefined error", \
  499. "unrecognised domain id", \
  500. "invalid grant reference", \
  501. "invalid mapping handle", \
  502. "invalid virtual address", \
  503. "invalid device address", \
  504. "no spare translation slot in the I/O MMU", \
  505. "permission denied", \
  506. "bad page", \
  507. "copy arguments cross page boundary", \
  508. "page address size too large", \
  509. "operation not done; try again" \
  510. }
  511. #endif /* __XEN_PUBLIC_GRANT_TABLE_H__ */