1
/******************************************************************************
4
* Interface for granting foreign access to page frames, and receiving
5
* page-ownership transfers.
7
* Permission is hereby granted, free of charge, to any person obtaining a copy
8
* of this software and associated documentation files (the "Software"), to
9
* deal in the Software without restriction, including without limitation the
10
* rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
11
* sell copies of the Software, and to permit persons to whom the Software is
12
* furnished to do so, subject to the following conditions:
14
* The above copyright notice and this permission notice shall be included in
15
* all copies or substantial portions of the Software.
17
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
22
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
23
* DEALINGS IN THE SOFTWARE.
25
* Copyright (c) 2004, K A Fraser
28
#ifndef __XEN_PUBLIC_GRANT_TABLE_H__
29
#define __XEN_PUBLIC_GRANT_TABLE_H__
33
/***********************************
34
* GRANT TABLE REPRESENTATION
37
/* Some rough guidelines on accessing and updating grant-table entries
38
* in a concurrency-safe manner. For more information, Linux contains a
39
* reference implementation for guest OSes (arch/xen/kernel/grant_table.c).
41
* NB. WMB is a no-op on current-generation x86 processors. However, a
42
* compiler barrier will still be required.
44
* Introducing a valid entry into the grant table:
45
* 1. Write ent->domid.
46
* 2. Write ent->frame:
47
* GTF_permit_access: Frame to which access is permitted.
48
* GTF_accept_transfer: Pseudo-phys frame slot being filled by new
49
* frame, or zero if none.
50
* 3. Write memory barrier (WMB).
51
* 4. Write ent->flags, inc. valid type.
53
* Invalidating an unused GTF_permit_access entry:
54
* 1. flags = ent->flags.
55
* 2. Observe that !(flags & (GTF_reading|GTF_writing)).
56
* 3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).
57
* NB. No need for WMB as reuse of entry is control-dependent on success of
58
* step 3, and all architectures guarantee ordering of ctrl-dep writes.
60
* Invalidating an in-use GTF_permit_access entry:
61
* This cannot be done directly. Request assistance from the domain controller
62
* which can set a timeout on the use of a grant entry and take necessary
63
* action. (NB. This is not yet implemented!).
65
* Invalidating an unused GTF_accept_transfer entry:
66
* 1. flags = ent->flags.
67
* 2. Observe that !(flags & GTF_transfer_committed). [*]
68
* 3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).
69
* NB. No need for WMB as reuse of entry is control-dependent on success of
70
* step 3, and all architectures guarantee ordering of ctrl-dep writes.
71
* [*] If GTF_transfer_committed is set then the grant entry is 'committed'.
72
* The guest must /not/ modify the grant entry until the address of the
73
* transferred frame is written. It is safe for the guest to spin waiting
74
* for this to occur (detect by observing GTF_transfer_completed in
77
* Invalidating a committed GTF_accept_transfer entry:
78
* 1. Wait for (ent->flags & GTF_transfer_completed).
80
* Changing a GTF_permit_access from writable to read-only:
81
* Use SMP-safe CMPXCHG to set GTF_readonly, while checking !GTF_writing.
83
* Changing a GTF_permit_access from read-only to writable:
84
* Use SMP-safe bit-setting instruction.
88
* Reference to a grant entry in a specified domain's grant table.
90
typedef uint32_t grant_ref_t;
93
* A grant table comprises a packed array of grant entries in one or more
94
* page frames shared between Xen and a guest.
95
* [XEN]: This field is written by Xen and read by the sharing guest.
96
* [GST]: This field is written by the guest and read by Xen.
100
* Version 1 of the grant table entry structure is maintained purely
101
* for backwards compatibility. New guests should use version 2.
103
#if __XEN_INTERFACE_VERSION__ < 0x0003020a
104
#define grant_entry_v1 grant_entry
105
#define grant_entry_v1_t grant_entry_t
107
struct grant_entry_v1 {
108
/* GTF_xxx: various type and flag information. [XEN,GST] */
110
/* The domain being granted foreign privileges. [GST] */
113
* GTF_permit_access: Frame that @domid is allowed to map and access. [GST]
114
* GTF_accept_transfer: Frame whose ownership transferred by @domid. [XEN]
118
typedef struct grant_entry_v1 grant_entry_v1_t;
121
* Type of grant entry.
122
* GTF_invalid: This grant entry grants no privileges.
123
* GTF_permit_access: Allow @domid to map/access @frame.
124
* GTF_accept_transfer: Allow @domid to transfer ownership of one page frame
125
* to this guest. Xen writes the page number to @frame.
126
* GTF_transitive: Allow @domid to transitively access a subrange of
127
* @trans_grant in @trans_domid. No mappings are allowed.
129
#define GTF_invalid (0U<<0)
130
#define GTF_permit_access (1U<<0)
131
#define GTF_accept_transfer (2U<<0)
132
#define GTF_transitive (3U<<0)
133
#define GTF_type_mask (3U<<0)
136
* Subflags for GTF_permit_access.
137
* GTF_readonly: Restrict @domid to read-only mappings and accesses. [GST]
138
* GTF_reading: Grant entry is currently mapped for reading by @domid. [XEN]
139
* GTF_writing: Grant entry is currently mapped for writing by @domid. [XEN]
140
* GTF_PAT, GTF_PWT, GTF_PCD: (x86) cache attribute flags for the grant [GST]
141
* GTF_sub_page: Grant access to only a subrange of the page. @domid
142
* will only be allowed to copy from the grant, and not
145
#define _GTF_readonly (2)
146
#define GTF_readonly (1U<<_GTF_readonly)
147
#define _GTF_reading (3)
148
#define GTF_reading (1U<<_GTF_reading)
149
#define _GTF_writing (4)
150
#define GTF_writing (1U<<_GTF_writing)
152
#define GTF_PWT (1U<<_GTF_PWT)
154
#define GTF_PCD (1U<<_GTF_PCD)
156
#define GTF_PAT (1U<<_GTF_PAT)
157
#define _GTF_sub_page (8)
158
#define GTF_sub_page (1U<<_GTF_sub_page)
161
* Subflags for GTF_accept_transfer:
162
* GTF_transfer_committed: Xen sets this flag to indicate that it is committed
163
* to transferring ownership of a page frame. When a guest sees this flag
164
* it must /not/ modify the grant entry until GTF_transfer_completed is
166
* GTF_transfer_completed: It is safe for the guest to spin-wait on this flag
167
* after reading GTF_transfer_committed. Xen will always write the frame
168
* address, followed by ORing this flag, in a timely manner.
170
#define _GTF_transfer_committed (2)
171
#define GTF_transfer_committed (1U<<_GTF_transfer_committed)
172
#define _GTF_transfer_completed (3)
173
#define GTF_transfer_completed (1U<<_GTF_transfer_completed)
176
* Version 2 grant table entries. These fulfil the same role as
177
* version 1 entries, but can represent more complicated operations.
178
* Any given domain will have either a version 1 or a version 2 table,
179
* and every entry in the table will be the same version.
181
* The interface by which domains use grant references does not depend
182
* on the grant table version in use by the other domain.
184
#if __XEN_INTERFACE_VERSION__ >= 0x0003020a
186
* Version 1 and version 2 grant entries share a common prefix. The
187
* fields of the prefix are documented as part of struct
190
struct grant_entry_header {
194
typedef struct grant_entry_header grant_entry_header_t;
197
* Version 2 of the grant entry structure.
199
union grant_entry_v2 {
200
grant_entry_header_t hdr;
203
* This member is used for V1-style full page grants, where either:
205
* -- hdr.type is GTF_accept_transfer, or
206
* -- hdr.type is GTF_permit_access and GTF_sub_page is not set.
208
* In that case, the frame field has the same semantics as the
209
* field of the same name in the V1 entry structure.
212
grant_entry_header_t hdr;
218
* If the grant type is GTF_grant_access and GTF_sub_page is set,
219
* @domid is allowed to access bytes [@page_off,@page_off+@length)
223
grant_entry_header_t hdr;
230
* If the grant is GTF_transitive, @domid is allowed to use the
231
* grant @gref in domain @trans_domid, as if it was the local
232
* domain. Obviously, the transitive access must be compatible
233
* with the original grant.
235
* The current version of Xen does not allow transitive grants
239
grant_entry_header_t hdr;
245
uint32_t __spacer[4]; /* Pad to a power of two */
247
typedef union grant_entry_v2 grant_entry_v2_t;
249
typedef uint16_t grant_status_t;
251
#endif /* __XEN_INTERFACE_VERSION__ */
253
/***********************************
254
* GRANT TABLE QUERIES AND USES
258
* Handle to track a mapping created via a grant reference.
260
typedef uint32_t grant_handle_t;
263
* GNTTABOP_map_grant_ref: Map the grant entry (<dom>,<ref>) for access
264
* by devices and/or host CPUs. If successful, <handle> is a tracking number
265
* that must be presented later to destroy the mapping(s). On error, <handle>
266
* is a negative status code.
268
* 1. If GNTMAP_device_map is specified then <dev_bus_addr> is the address
269
* via which I/O devices may access the granted frame.
270
* 2. If GNTMAP_host_map is specified then a mapping will be added at
271
* either a host virtual address in the current address space, or at
272
* a PTE at the specified machine address. The type of mapping to
273
* perform is selected through the GNTMAP_contains_pte flag, and the
274
* address is specified in <host_addr>.
275
* 3. Mappings should only be destroyed via GNTTABOP_unmap_grant_ref. If a
276
* host mapping is destroyed by other means then it is *NOT* guaranteed
277
* to be accounted to the correct grant reference!
279
#define GNTTABOP_map_grant_ref 0
280
struct gnttab_map_grant_ref {
283
uint32_t flags; /* GNTMAP_* */
286
/* OUT parameters. */
287
int16_t status; /* GNTST_* */
288
grant_handle_t handle;
289
uint64_t dev_bus_addr;
291
typedef struct gnttab_map_grant_ref gnttab_map_grant_ref_t;
292
DEFINE_XEN_GUEST_HANDLE(gnttab_map_grant_ref_t);
295
* GNTTABOP_unmap_grant_ref: Destroy one or more grant-reference mappings
296
* tracked by <handle>. If <host_addr> or <dev_bus_addr> is zero, that
297
* field is ignored. If non-zero, they must refer to a device/host mapping
298
* that is tracked by <handle>
300
* 1. The call may fail in an undefined manner if either mapping is not
301
* tracked by <handle>.
302
* 3. After executing a batch of unmaps, it is guaranteed that no stale
303
* mappings will remain in the device or host TLBs.
305
#define GNTTABOP_unmap_grant_ref 1
306
struct gnttab_unmap_grant_ref {
309
uint64_t dev_bus_addr;
310
grant_handle_t handle;
311
/* OUT parameters. */
312
int16_t status; /* GNTST_* */
314
typedef struct gnttab_unmap_grant_ref gnttab_unmap_grant_ref_t;
315
DEFINE_XEN_GUEST_HANDLE(gnttab_unmap_grant_ref_t);
318
* GNTTABOP_setup_table: Set up a grant table for <dom> comprising at least
319
* <nr_frames> pages. The frame addresses are written to the <frame_list>.
320
* Only <nr_frames> addresses are written, even if the table is larger.
322
* 1. <dom> may be specified as DOMID_SELF.
323
* 2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
324
* 3. Xen may not support more than a single grant-table page per domain.
326
#define GNTTABOP_setup_table 2
327
struct gnttab_setup_table {
331
/* OUT parameters. */
332
int16_t status; /* GNTST_* */
333
XEN_GUEST_HANDLE(ulong) frame_list;
335
typedef struct gnttab_setup_table gnttab_setup_table_t;
336
DEFINE_XEN_GUEST_HANDLE(gnttab_setup_table_t);
339
* GNTTABOP_dump_table: Dump the contents of the grant table to the
340
* xen console. Debugging use only.
342
#define GNTTABOP_dump_table 3
343
struct gnttab_dump_table {
346
/* OUT parameters. */
347
int16_t status; /* GNTST_* */
349
typedef struct gnttab_dump_table gnttab_dump_table_t;
350
DEFINE_XEN_GUEST_HANDLE(gnttab_dump_table_t);
353
* GNTTABOP_transfer_grant_ref: Transfer <frame> to a foreign domain. The
354
* foreign domain has previously registered its interest in the transfer via
357
* Note that, even if the transfer fails, the specified page no longer belongs
358
* to the calling domain *unless* the error is GNTST_bad_page.
360
#define GNTTABOP_transfer 4
361
struct gnttab_transfer {
366
/* OUT parameters. */
369
typedef struct gnttab_transfer gnttab_transfer_t;
370
DEFINE_XEN_GUEST_HANDLE(gnttab_transfer_t);
374
* GNTTABOP_copy: Hypervisor based copy
375
* source and destinations can be eithers MFNs or, for foreign domains,
376
* grant references. the foreign domain has to grant read/write access
377
* in its grant table.
379
* The flags specify what type source and destinations are (either MFN
380
* or grant reference).
382
* Note that this can also be used to copy data between two domains
383
* via a third party if the source and destination domains had previously
384
* grant appropriate access to their pages to the third party.
386
* source_offset specifies an offset in the source frame, dest_offset
387
* the offset in the target frame and len specifies the number of
388
* bytes to be copied.
391
#define _GNTCOPY_source_gref (0)
392
#define GNTCOPY_source_gref (1<<_GNTCOPY_source_gref)
393
#define _GNTCOPY_dest_gref (1)
394
#define GNTCOPY_dest_gref (1<<_GNTCOPY_dest_gref)
395
#define _GNTCOPY_can_fail (2)
396
#define GNTCOPY_can_fail (1<<_GNTCOPY_can_fail)
398
#define GNTTABOP_copy 5
399
typedef struct gnttab_copy {
410
uint16_t flags; /* GNTCOPY_* */
411
/* OUT parameters. */
414
DEFINE_XEN_GUEST_HANDLE(gnttab_copy_t);
417
* GNTTABOP_query_size: Query the current and maximum sizes of the shared
420
* 1. <dom> may be specified as DOMID_SELF.
421
* 2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
423
#define GNTTABOP_query_size 6
424
struct gnttab_query_size {
427
/* OUT parameters. */
429
uint32_t max_nr_frames;
430
int16_t status; /* GNTST_* */
432
typedef struct gnttab_query_size gnttab_query_size_t;
433
DEFINE_XEN_GUEST_HANDLE(gnttab_query_size_t);
436
* GNTTABOP_unmap_and_replace: Destroy one or more grant-reference mappings
437
* tracked by <handle> but atomically replace the page table entry with one
438
* pointing to the machine address under <new_addr>. <new_addr> will be
439
* redirected to the null entry.
441
* 1. The call may fail in an undefined manner if either mapping is not
442
* tracked by <handle>.
443
* 2. After executing a batch of unmaps, it is guaranteed that no stale
444
* mappings will remain in the device or host TLBs.
446
#define GNTTABOP_unmap_and_replace 7
447
struct gnttab_unmap_and_replace {
451
grant_handle_t handle;
452
/* OUT parameters. */
453
int16_t status; /* GNTST_* */
455
typedef struct gnttab_unmap_and_replace gnttab_unmap_and_replace_t;
456
DEFINE_XEN_GUEST_HANDLE(gnttab_unmap_and_replace_t);
458
#if __XEN_INTERFACE_VERSION__ >= 0x0003020a
460
* GNTTABOP_set_version: Request a particular version of the grant
461
* table shared table structure. This operation can only be performed
462
* once in any given domain. It must be performed before any grants
463
* are activated; otherwise, the domain will be stuck with version 1.
464
* The only defined versions are 1 and 2.
466
#define GNTTABOP_set_version 8
467
struct gnttab_set_version {
468
/* IN/OUT parameters */
471
typedef struct gnttab_set_version gnttab_set_version_t;
472
DEFINE_XEN_GUEST_HANDLE(gnttab_set_version_t);
476
* GNTTABOP_get_status_frames: Get the list of frames used to store grant
477
* status for <dom>. In grant format version 2, the status is separated
478
* from the other shared grant fields to allow more efficient synchronization
479
* using barriers instead of atomic cmpexch operations.
480
* <nr_frames> specify the size of vector <frame_list>.
481
* The frame addresses are returned in the <frame_list>.
482
* Only <nr_frames> addresses are returned, even if the table is larger.
484
* 1. <dom> may be specified as DOMID_SELF.
485
* 2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
487
#define GNTTABOP_get_status_frames 9
488
struct gnttab_get_status_frames {
492
/* OUT parameters. */
493
int16_t status; /* GNTST_* */
494
XEN_GUEST_HANDLE(uint64_t) frame_list;
496
typedef struct gnttab_get_status_frames gnttab_get_status_frames_t;
497
DEFINE_XEN_GUEST_HANDLE(gnttab_get_status_frames_t);
500
* GNTTABOP_get_version: Get the grant table version which is in
501
* effect for domain <dom>.
503
#define GNTTABOP_get_version 10
504
struct gnttab_get_version {
511
typedef struct gnttab_get_version gnttab_get_version_t;
512
DEFINE_XEN_GUEST_HANDLE(gnttab_get_version_t);
514
#endif /* __XEN_INTERFACE_VERSION__ */
517
* Bitfield values for gnttab_map_grant_ref.flags.
519
/* Map the grant entry for access by I/O devices. */
520
#define _GNTMAP_device_map (0)
521
#define GNTMAP_device_map (1<<_GNTMAP_device_map)
522
/* Map the grant entry for access by host CPUs. */
523
#define _GNTMAP_host_map (1)
524
#define GNTMAP_host_map (1<<_GNTMAP_host_map)
525
/* Accesses to the granted frame will be restricted to read-only access. */
526
#define _GNTMAP_readonly (2)
527
#define GNTMAP_readonly (1<<_GNTMAP_readonly)
529
* GNTMAP_host_map subflag:
530
* 0 => The host mapping is usable only by the guest OS.
531
* 1 => The host mapping is usable by guest OS + current application.
533
#define _GNTMAP_application_map (3)
534
#define GNTMAP_application_map (1<<_GNTMAP_application_map)
537
* GNTMAP_contains_pte subflag:
538
* 0 => This map request contains a host virtual address.
539
* 1 => This map request contains the machine addess of the PTE to update.
541
#define _GNTMAP_contains_pte (4)
542
#define GNTMAP_contains_pte (1<<_GNTMAP_contains_pte)
544
#define _GNTMAP_can_fail (5)
545
#define GNTMAP_can_fail (1<<_GNTMAP_can_fail)
548
* Bits to be placed in guest kernel available PTE bits (architecture
549
* dependent; only supported when XENFEAT_gnttab_map_avail_bits is set).
551
#define _GNTMAP_guest_avail0 (16)
552
#define GNTMAP_guest_avail_mask ((uint32_t)~0 << _GNTMAP_guest_avail0)
555
* Values for error status returns. All errors are -ve.
557
#define GNTST_okay (0) /* Normal return. */
558
#define GNTST_general_error (-1) /* General undefined error. */
559
#define GNTST_bad_domain (-2) /* Unrecognsed domain id. */
560
#define GNTST_bad_gntref (-3) /* Unrecognised or inappropriate gntref. */
561
#define GNTST_bad_handle (-4) /* Unrecognised or inappropriate handle. */
562
#define GNTST_bad_virt_addr (-5) /* Inappropriate virtual address to map. */
563
#define GNTST_bad_dev_addr (-6) /* Inappropriate device address to unmap.*/
564
#define GNTST_no_device_space (-7) /* Out of space in I/O MMU. */
565
#define GNTST_permission_denied (-8) /* Not enough privilege for operation. */
566
#define GNTST_bad_page (-9) /* Specified page was invalid for op. */
567
#define GNTST_bad_copy_arg (-10) /* copy arguments cross page boundary. */
568
#define GNTST_address_too_big (-11) /* transfer page address too large. */
569
#define GNTST_eagain (-12) /* Could not map at the moment. Retry. */
571
#define GNTTABOP_error_msgs { \
574
"unrecognised domain id", \
575
"invalid grant reference", \
576
"invalid mapping handle", \
577
"invalid virtual address", \
578
"invalid device address", \
579
"no spare translation slot in the I/O MMU", \
580
"permission denied", \
582
"copy arguments cross page boundary", \
583
"page address size too large", \
584
"could not map at the moment, retry" \
587
#endif /* __XEN_PUBLIC_GRANT_TABLE_H__ */
595
* indent-tabs-mode: nil