Linux Kernel  3.7.1
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
grant_table.h
Go to the documentation of this file.
1 /******************************************************************************
2  * grant_table.h
3  *
4  * Interface for granting foreign access to page frames, and receiving
5  * page-ownership transfers.
6  *
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:
13  *
14  * The above copyright notice and this permission notice shall be included in
15  * all copies or substantial portions of the Software.
16  *
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.
24  *
25  * Copyright (c) 2004, K A Fraser
26  */
27 
28 #ifndef __XEN_PUBLIC_GRANT_TABLE_H__
29 #define __XEN_PUBLIC_GRANT_TABLE_H__
30 
31 #include <xen/interface/xen.h>
32 
33 /***********************************
34  * GRANT TABLE REPRESENTATION
35  */
36 
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).
40  *
41  * NB. WMB is a no-op on current-generation x86 processors. However, a
42  * compiler barrier will still be required.
43  *
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.
52  *
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.
59  *
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!).
64  *
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
75  * ent->flags).
76  *
77  * Invalidating a committed GTF_accept_transfer entry:
78  * 1. Wait for (ent->flags & GTF_transfer_completed).
79  *
80  * Changing a GTF_permit_access from writable to read-only:
81  * Use SMP-safe CMPXCHG to set GTF_readonly, while checking !GTF_writing.
82  *
83  * Changing a GTF_permit_access from read-only to writable:
84  * Use SMP-safe bit-setting instruction.
85  */
86 
87 /*
88  * Reference to a grant entry in a specified domain's grant table.
89  */
91 
92 /*
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.
97  */
98 
99 /*
100  * Version 1 of the grant table entry structure is maintained purely
101  * for backwards compatibility. New guests should use version 2.
102  */
104  /* GTF_xxx: various type and flag information. [XEN,GST] */
106  /* The domain being granted foreign privileges. [GST] */
108  /*
109  * GTF_permit_access: Frame that @domid is allowed to map and access. [GST]
110  * GTF_accept_transfer: Frame whose ownership transferred by @domid. [XEN]
111  */
113 };
114 
115 /*
116  * Type of grant entry.
117  * GTF_invalid: This grant entry grants no privileges.
118  * GTF_permit_access: Allow @domid to map/access @frame.
119  * GTF_accept_transfer: Allow @domid to transfer ownership of one page frame
120  * to this guest. Xen writes the page number to @frame.
121  * GTF_transitive: Allow @domid to transitively access a subrange of
122  * @trans_grant in @trans_domid. No mappings are allowed.
123  */
124 #define GTF_invalid (0U<<0)
125 #define GTF_permit_access (1U<<0)
126 #define GTF_accept_transfer (2U<<0)
127 #define GTF_transitive (3U<<0)
128 #define GTF_type_mask (3U<<0)
129 
130 /*
131  * Subflags for GTF_permit_access.
132  * GTF_readonly: Restrict @domid to read-only mappings and accesses. [GST]
133  * GTF_reading: Grant entry is currently mapped for reading by @domid. [XEN]
134  * GTF_writing: Grant entry is currently mapped for writing by @domid. [XEN]
135  * GTF_sub_page: Grant access to only a subrange of the page. @domid
136  * will only be allowed to copy from the grant, and not
137  * map it. [GST]
138  */
139 #define _GTF_readonly (2)
140 #define GTF_readonly (1U<<_GTF_readonly)
141 #define _GTF_reading (3)
142 #define GTF_reading (1U<<_GTF_reading)
143 #define _GTF_writing (4)
144 #define GTF_writing (1U<<_GTF_writing)
145 #define _GTF_sub_page (8)
146 #define GTF_sub_page (1U<<_GTF_sub_page)
147 
148 /*
149  * Subflags for GTF_accept_transfer:
150  * GTF_transfer_committed: Xen sets this flag to indicate that it is committed
151  * to transferring ownership of a page frame. When a guest sees this flag
152  * it must /not/ modify the grant entry until GTF_transfer_completed is
153  * set by Xen.
154  * GTF_transfer_completed: It is safe for the guest to spin-wait on this flag
155  * after reading GTF_transfer_committed. Xen will always write the frame
156  * address, followed by ORing this flag, in a timely manner.
157  */
158 #define _GTF_transfer_committed (2)
159 #define GTF_transfer_committed (1U<<_GTF_transfer_committed)
160 #define _GTF_transfer_completed (3)
161 #define GTF_transfer_completed (1U<<_GTF_transfer_completed)
162 
163 /*
164  * Version 2 grant table entries. These fulfil the same role as
165  * version 1 entries, but can represent more complicated operations.
166  * Any given domain will have either a version 1 or a version 2 table,
167  * and every entry in the table will be the same version.
168  *
169  * The interface by which domains use grant references does not depend
170  * on the grant table version in use by the other domain.
171  */
172 
173 /*
174  * Version 1 and version 2 grant entries share a common prefix. The
175  * fields of the prefix are documented as part of struct
176  * grant_entry_v1.
177  */
181 };
182 
183 /*
184  * Version 2 of the grant entry structure, here is an union because three
185  * different types are suppotted: full_page, sub_page and transitive.
186  */
189 
190  /*
191  * This member is used for V1-style full page grants, where either:
192  *
193  * -- hdr.type is GTF_accept_transfer, or
194  * -- hdr.type is GTF_permit_access and GTF_sub_page is not set.
195  *
196  * In that case, the frame field has the same semantics as the
197  * field of the same name in the V1 entry structure.
198  */
199  struct {
200  struct grant_entry_header hdr;
203  } full_page;
204 
205  /*
206  * If the grant type is GTF_grant_access and GTF_sub_page is set,
207  * @domid is allowed to access bytes [@page_off,@page_off+@length)
208  * in frame @frame.
209  */
210  struct {
211  struct grant_entry_header hdr;
214  uint64_t frame;
215  } sub_page;
216 
217  /*
218  * If the grant is GTF_transitive, @domid is allowed to use the
219  * grant @gref in domain @trans_domid, as if it was the local
220  * domain. Obviously, the transitive access must be compatible
221  * with the original grant.
222  */
223  struct {
224  struct grant_entry_header hdr;
228  } transitive;
229 
230  uint32_t __spacer[4]; /* Pad to a power of two */
231 };
232 
234 
235 /***********************************
236  * GRANT TABLE QUERIES AND USES
237  */
238 
239 /*
240  * Handle to track a mapping created via a grant reference.
241  */
243 
244 /*
245  * GNTTABOP_map_grant_ref: Map the grant entry (<dom>,<ref>) for access
246  * by devices and/or host CPUs. If successful, <handle> is a tracking number
247  * that must be presented later to destroy the mapping(s). On error, <handle>
248  * is a negative status code.
249  * NOTES:
250  * 1. If GNTMAP_device_map is specified then <dev_bus_addr> is the address
251  * via which I/O devices may access the granted frame.
252  * 2. If GNTMAP_host_map is specified then a mapping will be added at
253  * either a host virtual address in the current address space, or at
254  * a PTE at the specified machine address. The type of mapping to
255  * perform is selected through the GNTMAP_contains_pte flag, and the
256  * address is specified in <host_addr>.
257  * 3. Mappings should only be destroyed via GNTTABOP_unmap_grant_ref. If a
258  * host mapping is destroyed by other means then it is *NOT* guaranteed
259  * to be accounted to the correct grant reference!
260  */
261 #define GNTTABOP_map_grant_ref 0
263  /* IN parameters. */
265  uint32_t flags; /* GNTMAP_* */
268  /* OUT parameters. */
269  int16_t status; /* GNTST_* */
272 };
274 
275 /*
276  * GNTTABOP_unmap_grant_ref: Destroy one or more grant-reference mappings
277  * tracked by <handle>. If <host_addr> or <dev_bus_addr> is zero, that
278  * field is ignored. If non-zero, they must refer to a device/host mapping
279  * that is tracked by <handle>
280  * NOTES:
281  * 1. The call may fail in an undefined manner if either mapping is not
282  * tracked by <handle>.
283  * 3. After executing a batch of unmaps, it is guaranteed that no stale
284  * mappings will remain in the device or host TLBs.
285  */
286 #define GNTTABOP_unmap_grant_ref 1
288  /* IN parameters. */
292  /* OUT parameters. */
293  int16_t status; /* GNTST_* */
294 };
296 
297 /*
298  * GNTTABOP_setup_table: Set up a grant table for <dom> comprising at least
299  * <nr_frames> pages. The frame addresses are written to the <frame_list>.
300  * Only <nr_frames> addresses are written, even if the table is larger.
301  * NOTES:
302  * 1. <dom> may be specified as DOMID_SELF.
303  * 2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
304  * 3. Xen may not support more than a single grant-table page per domain.
305  */
306 #define GNTTABOP_setup_table 2
308  /* IN parameters. */
311  /* OUT parameters. */
312  int16_t status; /* GNTST_* */
314 };
316 
317 /*
318  * GNTTABOP_dump_table: Dump the contents of the grant table to the
319  * xen console. Debugging use only.
320  */
321 #define GNTTABOP_dump_table 3
323  /* IN parameters. */
325  /* OUT parameters. */
326  int16_t status; /* GNTST_* */
327 };
329 
330 /*
331  * GNTTABOP_transfer_grant_ref: Transfer <frame> to a foreign domain. The
332  * foreign domain has previously registered its interest in the transfer via
333  * <domid, ref>.
334  *
335  * Note that, even if the transfer fails, the specified page no longer belongs
336  * to the calling domain *unless* the error is GNTST_bad_page.
337  */
338 #define GNTTABOP_transfer 4
340  /* IN parameters. */
344  /* OUT parameters. */
346 };
348 
349 /*
350  * GNTTABOP_copy: Hypervisor based copy
351  * source and destinations can be eithers MFNs or, for foreign domains,
352  * grant references. the foreign domain has to grant read/write access
353  * in its grant table.
354  *
355  * The flags specify what type source and destinations are (either MFN
356  * or grant reference).
357  *
358  * Note that this can also be used to copy data between two domains
359  * via a third party if the source and destination domains had previously
360  * grant appropriate access to their pages to the third party.
361  *
362  * source_offset specifies an offset in the source frame, dest_offset
363  * the offset in the target frame and len specifies the number of
364  * bytes to be copied.
365  */
366 
367 #define _GNTCOPY_source_gref (0)
368 #define GNTCOPY_source_gref (1<<_GNTCOPY_source_gref)
369 #define _GNTCOPY_dest_gref (1)
370 #define GNTCOPY_dest_gref (1<<_GNTCOPY_dest_gref)
371 
372 #define GNTTABOP_copy 5
373 struct gnttab_copy {
374  /* IN parameters. */
375  struct {
376  union {
379  } u;
382  } source, dest;
384  uint16_t flags; /* GNTCOPY_* */
385  /* OUT parameters. */
387 };
389 
390 /*
391  * GNTTABOP_query_size: Query the current and maximum sizes of the shared
392  * grant table.
393  * NOTES:
394  * 1. <dom> may be specified as DOMID_SELF.
395  * 2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
396  */
397 #define GNTTABOP_query_size 6
399  /* IN parameters. */
401  /* OUT parameters. */
404  int16_t status; /* GNTST_* */
405 };
407 
408 /*
409  * GNTTABOP_unmap_and_replace: Destroy one or more grant-reference mappings
410  * tracked by <handle> but atomically replace the page table entry with one
411  * pointing to the machine address under <new_addr>. <new_addr> will be
412  * redirected to the null entry.
413  * NOTES:
414  * 1. The call may fail in an undefined manner if either mapping is not
415  * tracked by <handle>.
416  * 2. After executing a batch of unmaps, it is guaranteed that no stale
417  * mappings will remain in the device or host TLBs.
418  */
419 #define GNTTABOP_unmap_and_replace 7
421  /* IN parameters. */
425  /* OUT parameters. */
426  int16_t status; /* GNTST_* */
427 };
429 
430 /*
431  * GNTTABOP_set_version: Request a particular version of the grant
432  * table shared table structure. This operation can only be performed
433  * once in any given domain. It must be performed before any grants
434  * are activated; otherwise, the domain will be stuck with version 1.
435  * The only defined versions are 1 and 2.
436  */
437 #define GNTTABOP_set_version 8
439  /* IN parameters */
441 };
443 
444 /*
445  * GNTTABOP_get_status_frames: Get the list of frames used to store grant
446  * status for <dom>. In grant format version 2, the status is separated
447  * from the other shared grant fields to allow more efficient synchronization
448  * using barriers instead of atomic cmpexch operations.
449  * <nr_frames> specify the size of vector <frame_list>.
450  * The frame addresses are returned in the <frame_list>.
451  * Only <nr_frames> addresses are returned, even if the table is larger.
452  * NOTES:
453  * 1. <dom> may be specified as DOMID_SELF.
454  * 2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
455  */
456 #define GNTTABOP_get_status_frames 9
458  /* IN parameters. */
461  /* OUT parameters. */
462  int16_t status; /* GNTST_* */
463  GUEST_HANDLE(uint64_t) frame_list;
464 };
466 
467 /*
468  * GNTTABOP_get_version: Get the grant table version which is in
469  * effect for domain <dom>.
470  */
471 #define GNTTABOP_get_version 10
473  /* IN parameters */
476  /* OUT parameters */
478 };
480 
481 /*
482  * Bitfield values for update_pin_status.flags.
483  */
484  /* Map the grant entry for access by I/O devices. */
485 #define _GNTMAP_device_map (0)
486 #define GNTMAP_device_map (1<<_GNTMAP_device_map)
487  /* Map the grant entry for access by host CPUs. */
488 #define _GNTMAP_host_map (1)
489 #define GNTMAP_host_map (1<<_GNTMAP_host_map)
490  /* Accesses to the granted frame will be restricted to read-only access. */
491 #define _GNTMAP_readonly (2)
492 #define GNTMAP_readonly (1<<_GNTMAP_readonly)
493  /*
494  * GNTMAP_host_map subflag:
495  * 0 => The host mapping is usable only by the guest OS.
496  * 1 => The host mapping is usable by guest OS + current application.
497  */
498 #define _GNTMAP_application_map (3)
499 #define GNTMAP_application_map (1<<_GNTMAP_application_map)
500 
501  /*
502  * GNTMAP_contains_pte subflag:
503  * 0 => This map request contains a host virtual address.
504  * 1 => This map request contains the machine addess of the PTE to update.
505  */
506 #define _GNTMAP_contains_pte (4)
507 #define GNTMAP_contains_pte (1<<_GNTMAP_contains_pte)
508 
509 /*
510  * Values for error status returns. All errors are -ve.
511  */
512 #define GNTST_okay (0) /* Normal return. */
513 #define GNTST_general_error (-1) /* General undefined error. */
514 #define GNTST_bad_domain (-2) /* Unrecognsed domain id. */
515 #define GNTST_bad_gntref (-3) /* Unrecognised or inappropriate gntref. */
516 #define GNTST_bad_handle (-4) /* Unrecognised or inappropriate handle. */
517 #define GNTST_bad_virt_addr (-5) /* Inappropriate virtual address to map. */
518 #define GNTST_bad_dev_addr (-6) /* Inappropriate device address to unmap.*/
519 #define GNTST_no_device_space (-7) /* Out of space in I/O MMU. */
520 #define GNTST_permission_denied (-8) /* Not enough privilege for operation. */
521 #define GNTST_bad_page (-9) /* Specified page was invalid for op. */
522 #define GNTST_bad_copy_arg (-10) /* copy arguments cross page boundary. */
523 #define GNTST_address_too_big (-11) /* transfer page address too large. */
524 #define GNTST_eagain (-12) /* Operation not done; try again. */
525 
526 #define GNTTABOP_error_msgs { \
527  "okay", \
528  "undefined error", \
529  "unrecognised domain id", \
530  "invalid grant reference", \
531  "invalid mapping handle", \
532  "invalid virtual address", \
533  "invalid device address", \
534  "no spare translation slot in the I/O MMU", \
535  "permission denied", \
536  "bad page", \
537  "copy arguments cross page boundary", \
538  "page address size too large", \
539  "operation not done; try again" \
540 }
541 
542 #endif /* __XEN_PUBLIC_GRANT_TABLE_H__ */