win-pvdrivers

annotate common/include/public/grant_table.h @ 62:edd4a2ad5b44

Removed old inf files
author James Harper <james.harper@bendigoit.com.au>
date Wed Dec 19 10:22:50 2007 +1100 (2007-12-19)
parents 5712dede5a1b
children
rev   line source
andy@12 1 /******************************************************************************
andy@12 2 * grant_table.h
andy@12 3 *
andy@12 4 * Interface for granting foreign access to page frames, and receiving
andy@12 5 * page-ownership transfers.
andy@12 6 *
andy@12 7 * Permission is hereby granted, free of charge, to any person obtaining a copy
andy@12 8 * of this software and associated documentation files (the "Software"), to
andy@12 9 * deal in the Software without restriction, including without limitation the
andy@12 10 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
andy@12 11 * sell copies of the Software, and to permit persons to whom the Software is
andy@12 12 * furnished to do so, subject to the following conditions:
andy@12 13 *
andy@12 14 * The above copyright notice and this permission notice shall be included in
andy@12 15 * all copies or substantial portions of the Software.
andy@12 16 *
andy@12 17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
andy@12 18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
andy@12 19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
andy@12 20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
andy@12 21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
andy@12 22 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
andy@12 23 * DEALINGS IN THE SOFTWARE.
andy@12 24 *
andy@12 25 * Copyright (c) 2004, K A Fraser
andy@12 26 */
andy@12 27
andy@12 28 #ifndef __XEN_PUBLIC_GRANT_TABLE_H__
andy@12 29 #define __XEN_PUBLIC_GRANT_TABLE_H__
andy@12 30
andy@12 31
andy@12 32 /***********************************
andy@12 33 * GRANT TABLE REPRESENTATION
andy@12 34 */
andy@12 35
andy@12 36 /* Some rough guidelines on accessing and updating grant-table entries
andy@12 37 * in a concurrency-safe manner. For more information, Linux contains a
andy@12 38 * reference implementation for guest OSes (arch/xen/kernel/grant_table.c).
andy@12 39 *
andy@12 40 * NB. WMB is a no-op on current-generation x86 processors. However, a
andy@12 41 * compiler barrier will still be required.
andy@12 42 *
andy@12 43 * Introducing a valid entry into the grant table:
andy@12 44 * 1. Write ent->domid.
andy@12 45 * 2. Write ent->frame:
andy@12 46 * GTF_permit_access: Frame to which access is permitted.
andy@12 47 * GTF_accept_transfer: Pseudo-phys frame slot being filled by new
andy@12 48 * frame, or zero if none.
andy@12 49 * 3. Write memory barrier (WMB).
andy@12 50 * 4. Write ent->flags, inc. valid type.
andy@12 51 *
andy@12 52 * Invalidating an unused GTF_permit_access entry:
andy@12 53 * 1. flags = ent->flags.
andy@12 54 * 2. Observe that !(flags & (GTF_reading|GTF_writing)).
andy@12 55 * 3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).
andy@12 56 * NB. No need for WMB as reuse of entry is control-dependent on success of
andy@12 57 * step 3, and all architectures guarantee ordering of ctrl-dep writes.
andy@12 58 *
andy@12 59 * Invalidating an in-use GTF_permit_access entry:
andy@12 60 * This cannot be done directly. Request assistance from the domain controller
andy@12 61 * which can set a timeout on the use of a grant entry and take necessary
andy@12 62 * action. (NB. This is not yet implemented!).
andy@12 63 *
andy@12 64 * Invalidating an unused GTF_accept_transfer entry:
andy@12 65 * 1. flags = ent->flags.
andy@12 66 * 2. Observe that !(flags & GTF_transfer_committed). [*]
andy@12 67 * 3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).
andy@12 68 * NB. No need for WMB as reuse of entry is control-dependent on success of
andy@12 69 * step 3, and all architectures guarantee ordering of ctrl-dep writes.
andy@12 70 * [*] If GTF_transfer_committed is set then the grant entry is 'committed'.
andy@12 71 * The guest must /not/ modify the grant entry until the address of the
andy@12 72 * transferred frame is written. It is safe for the guest to spin waiting
andy@12 73 * for this to occur (detect by observing GTF_transfer_completed in
andy@12 74 * ent->flags).
andy@12 75 *
andy@12 76 * Invalidating a committed GTF_accept_transfer entry:
andy@12 77 * 1. Wait for (ent->flags & GTF_transfer_completed).
andy@12 78 *
andy@12 79 * Changing a GTF_permit_access from writable to read-only:
andy@12 80 * Use SMP-safe CMPXCHG to set GTF_readonly, while checking !GTF_writing.
andy@12 81 *
andy@12 82 * Changing a GTF_permit_access from read-only to writable:
andy@12 83 * Use SMP-safe bit-setting instruction.
andy@12 84 */
andy@12 85
andy@12 86 /*
andy@12 87 * A grant table comprises a packed array of grant entries in one or more
andy@12 88 * page frames shared between Xen and a guest.
andy@12 89 * [XEN]: This field is written by Xen and read by the sharing guest.
andy@12 90 * [GST]: This field is written by the guest and read by Xen.
andy@12 91 */
andy@12 92 struct grant_entry {
andy@12 93 /* GTF_xxx: various type and flag information. [XEN,GST] */
andy@12 94 uint16_t flags;
andy@12 95 /* The domain being granted foreign privileges. [GST] */
andy@12 96 domid_t domid;
andy@12 97 /*
andy@12 98 * GTF_permit_access: Frame that @domid is allowed to map and access. [GST]
andy@12 99 * GTF_accept_transfer: Frame whose ownership transferred by @domid. [XEN]
andy@12 100 */
andy@12 101 uint32_t frame;
andy@12 102 };
andy@12 103 typedef struct grant_entry grant_entry_t;
andy@12 104
andy@12 105 /*
andy@12 106 * Type of grant entry.
andy@12 107 * GTF_invalid: This grant entry grants no privileges.
andy@12 108 * GTF_permit_access: Allow @domid to map/access @frame.
andy@12 109 * GTF_accept_transfer: Allow @domid to transfer ownership of one page frame
andy@12 110 * to this guest. Xen writes the page number to @frame.
andy@12 111 */
andy@12 112 #define GTF_invalid (0U<<0)
andy@12 113 #define GTF_permit_access (1U<<0)
andy@12 114 #define GTF_accept_transfer (2U<<0)
andy@12 115 #define GTF_type_mask (3U<<0)
andy@12 116
andy@12 117 /*
andy@12 118 * Subflags for GTF_permit_access.
andy@12 119 * GTF_readonly: Restrict @domid to read-only mappings and accesses. [GST]
andy@12 120 * GTF_reading: Grant entry is currently mapped for reading by @domid. [XEN]
andy@12 121 * GTF_writing: Grant entry is currently mapped for writing by @domid. [XEN]
andy@12 122 */
andy@12 123 #define _GTF_readonly (2)
andy@12 124 #define GTF_readonly (1U<<_GTF_readonly)
andy@12 125 #define _GTF_reading (3)
andy@12 126 #define GTF_reading (1U<<_GTF_reading)
andy@12 127 #define _GTF_writing (4)
andy@12 128 #define GTF_writing (1U<<_GTF_writing)
andy@12 129
andy@12 130 /*
andy@12 131 * Subflags for GTF_accept_transfer:
andy@12 132 * GTF_transfer_committed: Xen sets this flag to indicate that it is committed
andy@12 133 * to transferring ownership of a page frame. When a guest sees this flag
andy@12 134 * it must /not/ modify the grant entry until GTF_transfer_completed is
andy@12 135 * set by Xen.
andy@12 136 * GTF_transfer_completed: It is safe for the guest to spin-wait on this flag
andy@12 137 * after reading GTF_transfer_committed. Xen will always write the frame
andy@12 138 * address, followed by ORing this flag, in a timely manner.
andy@12 139 */
andy@12 140 #define _GTF_transfer_committed (2)
andy@12 141 #define GTF_transfer_committed (1U<<_GTF_transfer_committed)
andy@12 142 #define _GTF_transfer_completed (3)
andy@12 143 #define GTF_transfer_completed (1U<<_GTF_transfer_completed)
andy@12 144
andy@12 145
andy@12 146 /***********************************
andy@12 147 * GRANT TABLE QUERIES AND USES
andy@12 148 */
andy@12 149
andy@12 150 /*
andy@12 151 * Reference to a grant entry in a specified domain's grant table.
andy@12 152 */
andy@12 153 typedef uint32_t grant_ref_t;
andy@12 154
andy@12 155 /*
andy@12 156 * Handle to track a mapping created via a grant reference.
andy@12 157 */
andy@12 158 typedef uint32_t grant_handle_t;
andy@12 159
andy@12 160 /*
andy@12 161 * GNTTABOP_map_grant_ref: Map the grant entry (<dom>,<ref>) for access
andy@12 162 * by devices and/or host CPUs. If successful, <handle> is a tracking number
andy@12 163 * that must be presented later to destroy the mapping(s). On error, <handle>
andy@12 164 * is a negative status code.
andy@12 165 * NOTES:
andy@12 166 * 1. If GNTMAP_device_map is specified then <dev_bus_addr> is the address
andy@12 167 * via which I/O devices may access the granted frame.
andy@12 168 * 2. If GNTMAP_host_map is specified then a mapping will be added at
andy@12 169 * either a host virtual address in the current address space, or at
andy@12 170 * a PTE at the specified machine address. The type of mapping to
andy@12 171 * perform is selected through the GNTMAP_contains_pte flag, and the
andy@12 172 * address is specified in <host_addr>.
andy@12 173 * 3. Mappings should only be destroyed via GNTTABOP_unmap_grant_ref. If a
andy@12 174 * host mapping is destroyed by other means then it is *NOT* guaranteed
andy@12 175 * to be accounted to the correct grant reference!
andy@12 176 */
andy@12 177 #define GNTTABOP_map_grant_ref 0
andy@12 178 struct gnttab_map_grant_ref {
andy@12 179 /* IN parameters. */
andy@12 180 uint64_t host_addr;
andy@12 181 uint32_t flags; /* GNTMAP_* */
andy@12 182 grant_ref_t ref;
andy@12 183 domid_t dom;
andy@12 184 /* OUT parameters. */
andy@12 185 int16_t status; /* GNTST_* */
andy@12 186 grant_handle_t handle;
andy@12 187 uint64_t dev_bus_addr;
andy@12 188 };
andy@12 189 typedef struct gnttab_map_grant_ref gnttab_map_grant_ref_t;
andy@12 190 DEFINE_XEN_GUEST_HANDLE(gnttab_map_grant_ref_t);
andy@12 191
andy@12 192 /*
andy@12 193 * GNTTABOP_unmap_grant_ref: Destroy one or more grant-reference mappings
andy@12 194 * tracked by <handle>. If <host_addr> or <dev_bus_addr> is zero, that
andy@12 195 * field is ignored. If non-zero, they must refer to a device/host mapping
andy@12 196 * that is tracked by <handle>
andy@12 197 * NOTES:
andy@12 198 * 1. The call may fail in an undefined manner if either mapping is not
andy@12 199 * tracked by <handle>.
andy@12 200 * 3. After executing a batch of unmaps, it is guaranteed that no stale
andy@12 201 * mappings will remain in the device or host TLBs.
andy@12 202 */
andy@12 203 #define GNTTABOP_unmap_grant_ref 1
andy@12 204 struct gnttab_unmap_grant_ref {
andy@12 205 /* IN parameters. */
andy@12 206 uint64_t host_addr;
andy@12 207 uint64_t dev_bus_addr;
andy@12 208 grant_handle_t handle;
andy@12 209 /* OUT parameters. */
andy@12 210 int16_t status; /* GNTST_* */
andy@12 211 };
andy@12 212 typedef struct gnttab_unmap_grant_ref gnttab_unmap_grant_ref_t;
andy@12 213 DEFINE_XEN_GUEST_HANDLE(gnttab_unmap_grant_ref_t);
andy@12 214
andy@12 215 /*
andy@12 216 * GNTTABOP_setup_table: Set up a grant table for <dom> comprising at least
andy@12 217 * <nr_frames> pages. The frame addresses are written to the <frame_list>.
andy@12 218 * Only <nr_frames> addresses are written, even if the table is larger.
andy@12 219 * NOTES:
andy@12 220 * 1. <dom> may be specified as DOMID_SELF.
andy@12 221 * 2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
andy@12 222 * 3. Xen may not support more than a single grant-table page per domain.
andy@12 223 */
andy@12 224 #define GNTTABOP_setup_table 2
andy@12 225 struct gnttab_setup_table {
andy@12 226 /* IN parameters. */
andy@12 227 domid_t dom;
andy@12 228 uint32_t nr_frames;
andy@12 229 /* OUT parameters. */
andy@12 230 int16_t status; /* GNTST_* */
andy@12 231 XEN_GUEST_HANDLE(ulong) frame_list;
andy@12 232 };
andy@12 233 typedef struct gnttab_setup_table gnttab_setup_table_t;
andy@12 234 DEFINE_XEN_GUEST_HANDLE(gnttab_setup_table_t);
andy@12 235
andy@12 236 /*
andy@12 237 * GNTTABOP_dump_table: Dump the contents of the grant table to the
andy@12 238 * xen console. Debugging use only.
andy@12 239 */
andy@12 240 #define GNTTABOP_dump_table 3
andy@12 241 struct gnttab_dump_table {
andy@12 242 /* IN parameters. */
andy@12 243 domid_t dom;
andy@12 244 /* OUT parameters. */
andy@12 245 int16_t status; /* GNTST_* */
andy@12 246 };
andy@12 247 typedef struct gnttab_dump_table gnttab_dump_table_t;
andy@12 248 DEFINE_XEN_GUEST_HANDLE(gnttab_dump_table_t);
andy@12 249
andy@12 250 /*
andy@12 251 * GNTTABOP_transfer_grant_ref: Transfer <frame> to a foreign domain. The
andy@12 252 * foreign domain has previously registered its interest in the transfer via
andy@12 253 * <domid, ref>.
andy@12 254 *
andy@12 255 * Note that, even if the transfer fails, the specified page no longer belongs
andy@12 256 * to the calling domain *unless* the error is GNTST_bad_page.
andy@12 257 */
andy@12 258 #define GNTTABOP_transfer 4
andy@12 259 struct gnttab_transfer {
andy@12 260 /* IN parameters. */
andy@12 261 xen_pfn_t mfn;
andy@12 262 domid_t domid;
andy@12 263 grant_ref_t ref;
andy@12 264 /* OUT parameters. */
andy@12 265 int16_t status;
andy@12 266 };
andy@12 267 typedef struct gnttab_transfer gnttab_transfer_t;
andy@12 268 DEFINE_XEN_GUEST_HANDLE(gnttab_transfer_t);
andy@12 269
andy@12 270
andy@12 271 /*
andy@12 272 * GNTTABOP_copy: Hypervisor based copy
andy@12 273 * source and destinations can be eithers MFNs or, for foreign domains,
andy@12 274 * grant references. the foreign domain has to grant read/write access
andy@12 275 * in its grant table.
andy@12 276 *
andy@12 277 * The flags specify what type source and destinations are (either MFN
andy@12 278 * or grant reference).
andy@12 279 *
andy@12 280 * Note that this can also be used to copy data between two domains
andy@12 281 * via a third party if the source and destination domains had previously
andy@12 282 * grant appropriate access to their pages to the third party.
andy@12 283 *
andy@12 284 * source_offset specifies an offset in the source frame, dest_offset
andy@12 285 * the offset in the target frame and len specifies the number of
andy@12 286 * bytes to be copied.
andy@12 287 */
andy@12 288
andy@12 289 #define _GNTCOPY_source_gref (0)
andy@12 290 #define GNTCOPY_source_gref (1<<_GNTCOPY_source_gref)
andy@12 291 #define _GNTCOPY_dest_gref (1)
andy@12 292 #define GNTCOPY_dest_gref (1<<_GNTCOPY_dest_gref)
andy@12 293
andy@12 294 #define GNTTABOP_copy 5
andy@12 295 typedef struct gnttab_copy {
andy@12 296 /* IN parameters. */
andy@12 297 struct {
andy@12 298 union {
andy@12 299 grant_ref_t ref;
andy@12 300 xen_pfn_t gmfn;
andy@12 301 } u;
andy@12 302 domid_t domid;
andy@12 303 uint16_t offset;
andy@12 304 } source, dest;
andy@12 305 uint16_t len;
andy@12 306 uint16_t flags; /* GNTCOPY_* */
andy@12 307 /* OUT parameters. */
andy@12 308 int16_t status;
andy@12 309 } gnttab_copy_t;
andy@12 310 DEFINE_XEN_GUEST_HANDLE(gnttab_copy_t);
andy@12 311
andy@12 312 /*
andy@12 313 * GNTTABOP_query_size: Query the current and maximum sizes of the shared
andy@12 314 * grant table.
andy@12 315 * NOTES:
andy@12 316 * 1. <dom> may be specified as DOMID_SELF.
andy@12 317 * 2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
andy@12 318 */
andy@12 319 #define GNTTABOP_query_size 6
andy@12 320 struct gnttab_query_size {
andy@12 321 /* IN parameters. */
andy@12 322 domid_t dom;
andy@12 323 /* OUT parameters. */
andy@12 324 uint32_t nr_frames;
andy@12 325 uint32_t max_nr_frames;
andy@12 326 int16_t status; /* GNTST_* */
andy@12 327 };
andy@12 328 typedef struct gnttab_query_size gnttab_query_size_t;
andy@12 329 DEFINE_XEN_GUEST_HANDLE(gnttab_query_size_t);
andy@12 330
andy@12 331
andy@12 332 /*
andy@12 333 * Bitfield values for update_pin_status.flags.
andy@12 334 */
andy@12 335 /* Map the grant entry for access by I/O devices. */
andy@12 336 #define _GNTMAP_device_map (0)
andy@12 337 #define GNTMAP_device_map (1<<_GNTMAP_device_map)
andy@12 338 /* Map the grant entry for access by host CPUs. */
andy@12 339 #define _GNTMAP_host_map (1)
andy@12 340 #define GNTMAP_host_map (1<<_GNTMAP_host_map)
andy@12 341 /* Accesses to the granted frame will be restricted to read-only access. */
andy@12 342 #define _GNTMAP_readonly (2)
andy@12 343 #define GNTMAP_readonly (1<<_GNTMAP_readonly)
andy@12 344 /*
andy@12 345 * GNTMAP_host_map subflag:
andy@12 346 * 0 => The host mapping is usable only by the guest OS.
andy@12 347 * 1 => The host mapping is usable by guest OS + current application.
andy@12 348 */
andy@12 349 #define _GNTMAP_application_map (3)
andy@12 350 #define GNTMAP_application_map (1<<_GNTMAP_application_map)
andy@12 351
andy@12 352 /*
andy@12 353 * GNTMAP_contains_pte subflag:
andy@12 354 * 0 => This map request contains a host virtual address.
andy@12 355 * 1 => This map request contains the machine addess of the PTE to update.
andy@12 356 */
andy@12 357 #define _GNTMAP_contains_pte (4)
andy@12 358 #define GNTMAP_contains_pte (1<<_GNTMAP_contains_pte)
andy@12 359
andy@12 360 /*
andy@12 361 * Values for error status returns. All errors are -ve.
andy@12 362 */
andy@12 363 #define GNTST_okay (0) /* Normal return. */
andy@12 364 #define GNTST_general_error (-1) /* General undefined error. */
andy@12 365 #define GNTST_bad_domain (-2) /* Unrecognsed domain id. */
andy@12 366 #define GNTST_bad_gntref (-3) /* Unrecognised or inappropriate gntref. */
andy@12 367 #define GNTST_bad_handle (-4) /* Unrecognised or inappropriate handle. */
andy@12 368 #define GNTST_bad_virt_addr (-5) /* Inappropriate virtual address to map. */
andy@12 369 #define GNTST_bad_dev_addr (-6) /* Inappropriate device address to unmap.*/
andy@12 370 #define GNTST_no_device_space (-7) /* Out of space in I/O MMU. */
andy@12 371 #define GNTST_permission_denied (-8) /* Not enough privilege for operation. */
andy@12 372 #define GNTST_bad_page (-9) /* Specified page was invalid for op. */
andy@12 373 #define GNTST_bad_copy_arg (-10) /* copy arguments cross page boundary */
andy@12 374
andy@12 375 #define GNTTABOP_error_msgs { \
andy@12 376 "okay", \
andy@12 377 "undefined error", \
andy@12 378 "unrecognised domain id", \
andy@12 379 "invalid grant reference", \
andy@12 380 "invalid mapping handle", \
andy@12 381 "invalid virtual address", \
andy@12 382 "invalid device address", \
andy@12 383 "no spare translation slot in the I/O MMU", \
andy@12 384 "permission denied", \
andy@12 385 "bad page", \
andy@12 386 "copy arguments cross page boundary" \
andy@12 387 }
andy@12 388
andy@12 389 #endif /* __XEN_PUBLIC_GRANT_TABLE_H__ */
andy@12 390
andy@12 391 /*
andy@12 392 * Local variables:
andy@12 393 * mode: C
andy@12 394 * c-set-style: "BSD"
andy@12 395 * c-basic-offset: 4
andy@12 396 * tab-width: 4
andy@12 397 * indent-tabs-mode: nil
andy@12 398 * End:
andy@12 399 */