tools headers UAPI: Sync drm/i915_drm.h with the kernel sources

+359 -34

1 changed file

expand all

tools

include

uapi

drm

i915_drm.h

+359 -34

tools/include/uapi/drm/i915_drm.h

··· 62 62 #define I915_ERROR_UEVENT "ERROR" 63 63 #define I915_RESET_UEVENT "RESET" 64 64 65 - /* 66 - * i915_user_extension: Base class for defining a chain of extensions 65 + /** 66 + * struct i915_user_extension - Base class for defining a chain of extensions 67 67 * 68 68 * Many interfaces need to grow over time. In most cases we can simply 69 69 * extend the struct and have userspace pass in more data. Another option, ··· 76 76 * increasing complexity, and for large parts of that interface to be 77 77 * entirely optional. The downside is more pointer chasing; chasing across 78 78 * the __user boundary with pointers encapsulated inside u64. 79 + * 80 + * Example chaining: 81 + * 82 + * .. code-block:: C 83 + * 84 + * struct i915_user_extension ext3 { 85 + * .next_extension = 0, // end 86 + * .name = ..., 87 + * }; 88 + * struct i915_user_extension ext2 { 89 + * .next_extension = (uintptr_t)&ext3, 90 + * .name = ..., 91 + * }; 92 + * struct i915_user_extension ext1 { 93 + * .next_extension = (uintptr_t)&ext2, 94 + * .name = ..., 95 + * }; 96 + * 97 + * Typically the struct i915_user_extension would be embedded in some uAPI 98 + * struct, and in this case we would feed it the head of the chain(i.e ext1), 99 + * which would then apply all of the above extensions. 100 + * 79 101 */ 80 102 struct i915_user_extension { 103 + /** 104 + * @next_extension: 105 + * 106 + * Pointer to the next struct i915_user_extension, or zero if the end. 107 + */ 81 108 __u64 next_extension; 109 + /** 110 + * @name: Name of the extension. 111 + * 112 + * Note that the name here is just some integer. 113 + * 114 + * Also note that the name space for this is not global for the whole 115 + * driver, but rather its scope/meaning is limited to the specific piece 116 + * of uAPI which has embedded the struct i915_user_extension. 117 + */ 82 118 __u32 name; 83 - __u32 flags; /* All undefined bits must be zero. */ 84 - __u32 rsvd[4]; /* Reserved for future use; must be zero. */ 119 + /** 120 + * @flags: MBZ 121 + * 122 + * All undefined bits must be zero. 123 + */ 124 + __u32 flags; 125 + /** 126 + * @rsvd: MBZ 127 + * 128 + * Reserved for future use; must be zero. 129 + */ 130 + __u32 rsvd[4]; 85 131 }; 86 132 87 133 /* ··· 406 360 #define DRM_I915_QUERY 0x39 407 361 #define DRM_I915_GEM_VM_CREATE 0x3a 408 362 #define DRM_I915_GEM_VM_DESTROY 0x3b 363 + #define DRM_I915_GEM_CREATE_EXT 0x3c 409 364 /* Must be kept compact -- no holes */ 410 365 411 366 #define DRM_IOCTL_I915_INIT DRM_IOW( DRM_COMMAND_BASE + DRM_I915_INIT, drm_i915_init_t) ··· 439 392 #define DRM_IOCTL_I915_GEM_ENTERVT DRM_IO(DRM_COMMAND_BASE + DRM_I915_GEM_ENTERVT) 440 393 #define DRM_IOCTL_I915_GEM_LEAVEVT DRM_IO(DRM_COMMAND_BASE + DRM_I915_GEM_LEAVEVT) 441 394 #define DRM_IOCTL_I915_GEM_CREATE DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_CREATE, struct drm_i915_gem_create) 395 + #define DRM_IOCTL_I915_GEM_CREATE_EXT DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_CREATE_EXT, struct drm_i915_gem_create_ext) 442 396 #define DRM_IOCTL_I915_GEM_PREAD DRM_IOW (DRM_COMMAND_BASE + DRM_I915_GEM_PREAD, struct drm_i915_gem_pread) 443 397 #define DRM_IOCTL_I915_GEM_PWRITE DRM_IOW (DRM_COMMAND_BASE + DRM_I915_GEM_PWRITE, struct drm_i915_gem_pwrite) 444 398 #define DRM_IOCTL_I915_GEM_MMAP DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_MMAP, struct drm_i915_gem_mmap) ··· 1102 1054 __u32 flags; 1103 1055 }; 1104 1056 1105 - /** 1057 + /* 1106 1058 * See drm_i915_gem_execbuffer_ext_timeline_fences. 1107 1059 */ 1108 1060 #define DRM_I915_GEM_EXECBUFFER_EXT_TIMELINE_FENCES 0 1109 1061 1110 - /** 1062 + /* 1111 1063 * This structure describes an array of drm_syncobj and associated points for 1112 1064 * timeline variants of drm_syncobj. It is invalid to append this structure to 1113 1065 * the execbuf if I915_EXEC_FENCE_ARRAY is set. ··· 1748 1700 __u64 value; 1749 1701 }; 1750 1702 1751 - /** 1703 + /* 1752 1704 * Context SSEU programming 1753 1705 * 1754 1706 * It may be necessary for either functional or performance reason to configure ··· 2115 2067 __u64 properties_ptr; 2116 2068 }; 2117 2069 2118 - /** 2070 + /* 2119 2071 * Enable data capture for a stream that was either opened in a disabled state 2120 2072 * via I915_PERF_FLAG_DISABLED or was later disabled via 2121 2073 * I915_PERF_IOCTL_DISABLE. ··· 2129 2081 */ 2130 2082 #define I915_PERF_IOCTL_ENABLE _IO('i', 0x0) 2131 2083 2132 - /** 2084 + /* 2133 2085 * Disable data capture for a stream. 2134 2086 * 2135 2087 * It is an error to try and read a stream that is disabled. ··· 2138 2090 */ 2139 2091 #define I915_PERF_IOCTL_DISABLE _IO('i', 0x1) 2140 2092 2141 - /** 2093 + /* 2142 2094 * Change metrics_set captured by a stream. 2143 2095 * 2144 2096 * If the stream is bound to a specific context, the configuration change ··· 2151 2103 */ 2152 2104 #define I915_PERF_IOCTL_CONFIG _IO('i', 0x2) 2153 2105 2154 - /** 2106 + /* 2155 2107 * Common to all i915 perf records 2156 2108 */ 2157 2109 struct drm_i915_perf_record_header { ··· 2199 2151 DRM_I915_PERF_RECORD_MAX /* non-ABI */ 2200 2152 }; 2201 2153 2202 - /** 2154 + /* 2203 2155 * Structure to upload perf dynamic configuration into the kernel. 2204 2156 */ 2205 2157 struct drm_i915_perf_oa_config { ··· 2220 2172 __u64 flex_regs_ptr; 2221 2173 }; 2222 2174 2175 + /** 2176 + * struct drm_i915_query_item - An individual query for the kernel to process. 2177 + * 2178 + * The behaviour is determined by the @query_id. Note that exactly what 2179 + * @data_ptr is also depends on the specific @query_id. 2180 + */ 2223 2181 struct drm_i915_query_item { 2182 + /** @query_id: The id for this query */ 2224 2183 __u64 query_id; 2225 2184 #define DRM_I915_QUERY_TOPOLOGY_INFO 1 2226 2185 #define DRM_I915_QUERY_ENGINE_INFO 2 2227 2186 #define DRM_I915_QUERY_PERF_CONFIG 3 2187 + #define DRM_I915_QUERY_MEMORY_REGIONS 4 2228 2188 /* Must be kept compact -- no holes and well documented */ 2229 2189 2230 - /* 2190 + /** 2191 + * @length: 2192 + * 2231 2193 * When set to zero by userspace, this is filled with the size of the 2232 - * data to be written at the data_ptr pointer. The kernel sets this 2194 + * data to be written at the @data_ptr pointer. The kernel sets this 2233 2195 * value to a negative value to signal an error on a particular query 2234 2196 * item. 2235 2197 */ 2236 2198 __s32 length; 2237 2199 2238 - /* 2200 + /** 2201 + * @flags: 2202 + * 2239 2203 * When query_id == DRM_I915_QUERY_TOPOLOGY_INFO, must be 0. 2240 2204 * 2241 2205 * When query_id == DRM_I915_QUERY_PERF_CONFIG, must be one of the 2242 - * following : 2243 - * - DRM_I915_QUERY_PERF_CONFIG_LIST 2244 - * - DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID 2245 - * - DRM_I915_QUERY_PERF_CONFIG_FOR_UUID 2206 + * following: 2207 + * 2208 + * - DRM_I915_QUERY_PERF_CONFIG_LIST 2209 + * - DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID 2210 + * - DRM_I915_QUERY_PERF_CONFIG_FOR_UUID 2246 2211 */ 2247 2212 __u32 flags; 2248 2213 #define DRM_I915_QUERY_PERF_CONFIG_LIST 1 2249 2214 #define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID 2 2250 2215 #define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_ID 3 2251 2216 2252 - /* 2253 - * Data will be written at the location pointed by data_ptr when the 2254 - * value of length matches the length of the data to be written by the 2217 + /** 2218 + * @data_ptr: 2219 + * 2220 + * Data will be written at the location pointed by @data_ptr when the 2221 + * value of @length matches the length of the data to be written by the 2255 2222 * kernel. 2256 2223 */ 2257 2224 __u64 data_ptr; 2258 2225 }; 2259 2226 2227 + /** 2228 + * struct drm_i915_query - Supply an array of struct drm_i915_query_item for the 2229 + * kernel to fill out. 2230 + * 2231 + * Note that this is generally a two step process for each struct 2232 + * drm_i915_query_item in the array: 2233 + * 2234 + * 1. Call the DRM_IOCTL_I915_QUERY, giving it our array of struct 2235 + * drm_i915_query_item, with &drm_i915_query_item.length set to zero. The 2236 + * kernel will then fill in the size, in bytes, which tells userspace how 2237 + * memory it needs to allocate for the blob(say for an array of properties). 2238 + * 2239 + * 2. Next we call DRM_IOCTL_I915_QUERY again, this time with the 2240 + * &drm_i915_query_item.data_ptr equal to our newly allocated blob. Note that 2241 + * the &drm_i915_query_item.length should still be the same as what the 2242 + * kernel previously set. At this point the kernel can fill in the blob. 2243 + * 2244 + * Note that for some query items it can make sense for userspace to just pass 2245 + * in a buffer/blob equal to or larger than the required size. In this case only 2246 + * a single ioctl call is needed. For some smaller query items this can work 2247 + * quite well. 2248 + * 2249 + */ 2260 2250 struct drm_i915_query { 2251 + /** @num_items: The number of elements in the @items_ptr array */ 2261 2252 __u32 num_items; 2262 2253 2263 - /* 2264 - * Unused for now. Must be cleared to zero. 2254 + /** 2255 + * @flags: Unused for now. Must be cleared to zero. 2265 2256 */ 2266 2257 __u32 flags; 2267 2258 2268 - /* 2269 - * This points to an array of num_items drm_i915_query_item structures. 2259 + /** 2260 + * @items_ptr: 2261 + * 2262 + * Pointer to an array of struct drm_i915_query_item. The number of 2263 + * array elements is @num_items. 2270 2264 */ 2271 2265 __u64 items_ptr; 2272 2266 }; ··· 2382 2292 * Describes one engine and it's capabilities as known to the driver. 2383 2293 */ 2384 2294 struct drm_i915_engine_info { 2385 - /** Engine class and instance. */ 2295 + /** @engine: Engine class and instance. */ 2386 2296 struct i915_engine_class_instance engine; 2387 2297 2388 - /** Reserved field. */ 2298 + /** @rsvd0: Reserved field. */ 2389 2299 __u32 rsvd0; 2390 2300 2391 - /** Engine flags. */ 2301 + /** @flags: Engine flags. */ 2392 2302 __u64 flags; 2393 2303 2394 - /** Capabilities of this engine. */ 2304 + /** @capabilities: Capabilities of this engine. */ 2395 2305 __u64 capabilities; 2396 2306 #define I915_VIDEO_CLASS_CAPABILITY_HEVC (1 << 0) 2397 2307 #define I915_VIDEO_AND_ENHANCE_CLASS_CAPABILITY_SFC (1 << 1) 2398 2308 2399 - /** Reserved fields. */ 2309 + /** @rsvd1: Reserved fields. */ 2400 2310 __u64 rsvd1[4]; 2401 2311 }; 2402 2312 ··· 2407 2317 * an array of struct drm_i915_engine_info structures. 2408 2318 */ 2409 2319 struct drm_i915_query_engine_info { 2410 - /** Number of struct drm_i915_engine_info structs following. */ 2320 + /** @num_engines: Number of struct drm_i915_engine_info structs following. */ 2411 2321 __u32 num_engines; 2412 2322 2413 - /** MBZ */ 2323 + /** @rsvd: MBZ */ 2414 2324 __u32 rsvd[3]; 2415 2325 2416 - /** Marker for drm_i915_engine_info structures. */ 2326 + /** @engines: Marker for drm_i915_engine_info structures. */ 2417 2327 struct drm_i915_engine_info engines[]; 2418 2328 }; 2419 2329 ··· 2465 2375 * - n_flex_regs 2466 2376 */ 2467 2377 __u8 data[]; 2378 + }; 2379 + 2380 + /** 2381 + * enum drm_i915_gem_memory_class - Supported memory classes 2382 + */ 2383 + enum drm_i915_gem_memory_class { 2384 + /** @I915_MEMORY_CLASS_SYSTEM: System memory */ 2385 + I915_MEMORY_CLASS_SYSTEM = 0, 2386 + /** @I915_MEMORY_CLASS_DEVICE: Device local-memory */ 2387 + I915_MEMORY_CLASS_DEVICE, 2388 + }; 2389 + 2390 + /** 2391 + * struct drm_i915_gem_memory_class_instance - Identify particular memory region 2392 + */ 2393 + struct drm_i915_gem_memory_class_instance { 2394 + /** @memory_class: See enum drm_i915_gem_memory_class */ 2395 + __u16 memory_class; 2396 + 2397 + /** @memory_instance: Which instance */ 2398 + __u16 memory_instance; 2399 + }; 2400 + 2401 + /** 2402 + * struct drm_i915_memory_region_info - Describes one region as known to the 2403 + * driver. 2404 + * 2405 + * Note that we reserve some stuff here for potential future work. As an example 2406 + * we might want expose the capabilities for a given region, which could include 2407 + * things like if the region is CPU mappable/accessible, what are the supported 2408 + * mapping types etc. 2409 + * 2410 + * Note that to extend struct drm_i915_memory_region_info and struct 2411 + * drm_i915_query_memory_regions in the future the plan is to do the following: 2412 + * 2413 + * .. code-block:: C 2414 + * 2415 + * struct drm_i915_memory_region_info { 2416 + * struct drm_i915_gem_memory_class_instance region; 2417 + * union { 2418 + * __u32 rsvd0; 2419 + * __u32 new_thing1; 2420 + * }; 2421 + * ... 2422 + * union { 2423 + * __u64 rsvd1[8]; 2424 + * struct { 2425 + * __u64 new_thing2; 2426 + * __u64 new_thing3; 2427 + * ... 2428 + * }; 2429 + * }; 2430 + * }; 2431 + * 2432 + * With this things should remain source compatible between versions for 2433 + * userspace, even as we add new fields. 2434 + * 2435 + * Note this is using both struct drm_i915_query_item and struct drm_i915_query. 2436 + * For this new query we are adding the new query id DRM_I915_QUERY_MEMORY_REGIONS 2437 + * at &drm_i915_query_item.query_id. 2438 + */ 2439 + struct drm_i915_memory_region_info { 2440 + /** @region: The class:instance pair encoding */ 2441 + struct drm_i915_gem_memory_class_instance region; 2442 + 2443 + /** @rsvd0: MBZ */ 2444 + __u32 rsvd0; 2445 + 2446 + /** @probed_size: Memory probed by the driver (-1 = unknown) */ 2447 + __u64 probed_size; 2448 + 2449 + /** @unallocated_size: Estimate of memory remaining (-1 = unknown) */ 2450 + __u64 unallocated_size; 2451 + 2452 + /** @rsvd1: MBZ */ 2453 + __u64 rsvd1[8]; 2454 + }; 2455 + 2456 + /** 2457 + * struct drm_i915_query_memory_regions 2458 + * 2459 + * The region info query enumerates all regions known to the driver by filling 2460 + * in an array of struct drm_i915_memory_region_info structures. 2461 + * 2462 + * Example for getting the list of supported regions: 2463 + * 2464 + * .. code-block:: C 2465 + * 2466 + * struct drm_i915_query_memory_regions *info; 2467 + * struct drm_i915_query_item item = { 2468 + * .query_id = DRM_I915_QUERY_MEMORY_REGIONS; 2469 + * }; 2470 + * struct drm_i915_query query = { 2471 + * .num_items = 1, 2472 + * .items_ptr = (uintptr_t)&item, 2473 + * }; 2474 + * int err, i; 2475 + * 2476 + * // First query the size of the blob we need, this needs to be large 2477 + * // enough to hold our array of regions. The kernel will fill out the 2478 + * // item.length for us, which is the number of bytes we need. 2479 + * err = ioctl(fd, DRM_IOCTL_I915_QUERY, &query); 2480 + * if (err) ... 2481 + * 2482 + * info = calloc(1, item.length); 2483 + * // Now that we allocated the required number of bytes, we call the ioctl 2484 + * // again, this time with the data_ptr pointing to our newly allocated 2485 + * // blob, which the kernel can then populate with the all the region info. 2486 + * item.data_ptr = (uintptr_t)&info, 2487 + * 2488 + * err = ioctl(fd, DRM_IOCTL_I915_QUERY, &query); 2489 + * if (err) ... 2490 + * 2491 + * // We can now access each region in the array 2492 + * for (i = 0; i < info->num_regions; i++) { 2493 + * struct drm_i915_memory_region_info mr = info->regions[i]; 2494 + * u16 class = mr.region.class; 2495 + * u16 instance = mr.region.instance; 2496 + * 2497 + * .... 2498 + * } 2499 + * 2500 + * free(info); 2501 + */ 2502 + struct drm_i915_query_memory_regions { 2503 + /** @num_regions: Number of supported regions */ 2504 + __u32 num_regions; 2505 + 2506 + /** @rsvd: MBZ */ 2507 + __u32 rsvd[3]; 2508 + 2509 + /** @regions: Info about each supported region */ 2510 + struct drm_i915_memory_region_info regions[]; 2511 + }; 2512 + 2513 + /** 2514 + * struct drm_i915_gem_create_ext - Existing gem_create behaviour, with added 2515 + * extension support using struct i915_user_extension. 2516 + * 2517 + * Note that in the future we want to have our buffer flags here, at least for 2518 + * the stuff that is immutable. Previously we would have two ioctls, one to 2519 + * create the object with gem_create, and another to apply various parameters, 2520 + * however this creates some ambiguity for the params which are considered 2521 + * immutable. Also in general we're phasing out the various SET/GET ioctls. 2522 + */ 2523 + struct drm_i915_gem_create_ext { 2524 + /** 2525 + * @size: Requested size for the object. 2526 + * 2527 + * The (page-aligned) allocated size for the object will be returned. 2528 + * 2529 + * Note that for some devices we have might have further minimum 2530 + * page-size restrictions(larger than 4K), like for device local-memory. 2531 + * However in general the final size here should always reflect any 2532 + * rounding up, if for example using the I915_GEM_CREATE_EXT_MEMORY_REGIONS 2533 + * extension to place the object in device local-memory. 2534 + */ 2535 + __u64 size; 2536 + /** 2537 + * @handle: Returned handle for the object. 2538 + * 2539 + * Object handles are nonzero. 2540 + */ 2541 + __u32 handle; 2542 + /** @flags: MBZ */ 2543 + __u32 flags; 2544 + /** 2545 + * @extensions: The chain of extensions to apply to this object. 2546 + * 2547 + * This will be useful in the future when we need to support several 2548 + * different extensions, and we need to apply more than one when 2549 + * creating the object. See struct i915_user_extension. 2550 + * 2551 + * If we don't supply any extensions then we get the same old gem_create 2552 + * behaviour. 2553 + * 2554 + * For I915_GEM_CREATE_EXT_MEMORY_REGIONS usage see 2555 + * struct drm_i915_gem_create_ext_memory_regions. 2556 + */ 2557 + #define I915_GEM_CREATE_EXT_MEMORY_REGIONS 0 2558 + __u64 extensions; 2559 + }; 2560 + 2561 + /** 2562 + * struct drm_i915_gem_create_ext_memory_regions - The 2563 + * I915_GEM_CREATE_EXT_MEMORY_REGIONS extension. 2564 + * 2565 + * Set the object with the desired set of placements/regions in priority 2566 + * order. Each entry must be unique and supported by the device. 2567 + * 2568 + * This is provided as an array of struct drm_i915_gem_memory_class_instance, or 2569 + * an equivalent layout of class:instance pair encodings. See struct 2570 + * drm_i915_query_memory_regions and DRM_I915_QUERY_MEMORY_REGIONS for how to 2571 + * query the supported regions for a device. 2572 + * 2573 + * As an example, on discrete devices, if we wish to set the placement as 2574 + * device local-memory we can do something like: 2575 + * 2576 + * .. code-block:: C 2577 + * 2578 + * struct drm_i915_gem_memory_class_instance region_lmem = { 2579 + * .memory_class = I915_MEMORY_CLASS_DEVICE, 2580 + * .memory_instance = 0, 2581 + * }; 2582 + * struct drm_i915_gem_create_ext_memory_regions regions = { 2583 + * .base = { .name = I915_GEM_CREATE_EXT_MEMORY_REGIONS }, 2584 + * .regions = (uintptr_t)&region_lmem, 2585 + * .num_regions = 1, 2586 + * }; 2587 + * struct drm_i915_gem_create_ext create_ext = { 2588 + * .size = 16 * PAGE_SIZE, 2589 + * .extensions = (uintptr_t)&regions, 2590 + * }; 2591 + * 2592 + * int err = ioctl(fd, DRM_IOCTL_I915_GEM_CREATE_EXT, &create_ext); 2593 + * if (err) ... 2594 + * 2595 + * At which point we get the object handle in &drm_i915_gem_create_ext.handle, 2596 + * along with the final object size in &drm_i915_gem_create_ext.size, which 2597 + * should account for any rounding up, if required. 2598 + */ 2599 + struct drm_i915_gem_create_ext_memory_regions { 2600 + /** @base: Extension link. See struct i915_user_extension. */ 2601 + struct i915_user_extension base; 2602 + 2603 + /** @pad: MBZ */ 2604 + __u32 pad; 2605 + /** @num_regions: Number of elements in the @regions array. */ 2606 + __u32 num_regions; 2607 + /** 2608 + * @regions: The regions/placements array. 2609 + * 2610 + * An array of struct drm_i915_gem_memory_class_instance. 2611 + */ 2612 + __u64 regions; 2468 2613 }; 2469 2614 2470 2615 #if defined(__cplusplus)

Configure Feed

Configure Feed