summaryrefslogtreecommitdiffstats
path: root/include/uapi/drm/i915_drm.h
blob: 2ee338860b7e08c80fb9f0a65702dc1b18456b6b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
3847
3848
3849
3850
3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
3863
3864
/*
 * Copyright 2003 Tungsten Graphics, Inc., Cedar Park, Texas.
 * All Rights Reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, sub license, and/or sell copies of the Software, and to
 * permit persons to whom the Software is furnished to do so, subject to
 * the following conditions:
 *
 * The above copyright notice and this permission notice (including the
 * next paragraph) shall be included in all copies or substantial portions
 * of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
 * IN NO EVENT SHALL TUNGSTEN GRAPHICS AND/OR ITS SUPPLIERS BE LIABLE FOR
 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 *
 */

#ifndef _UAPI_I915_DRM_H_
#define _UAPI_I915_DRM_H_

#include "drm.h"

#if defined(__cplusplus)
extern "C" {
#endif

/* Please note that modifications to all structs defined here are
 * subject to backwards-compatibility constraints.
 */

/**
 * DOC: uevents generated by i915 on its device node
 *
 * I915_L3_PARITY_UEVENT - Generated when the driver receives a parity mismatch
 *	event from the GPU L3 cache. Additional information supplied is ROW,
 *	BANK, SUBBANK, SLICE of the affected cacheline. Userspace should keep
 *	track of these events, and if a specific cache-line seems to have a
 *	persistent error, remap it with the L3 remapping tool supplied in
 *	intel-gpu-tools.  The value supplied with the event is always 1.
 *
 * I915_ERROR_UEVENT - Generated upon error detection, currently only via
 *	hangcheck. The error detection event is a good indicator of when things
 *	began to go badly. The value supplied with the event is a 1 upon error
 *	detection, and a 0 upon reset completion, signifying no more error
 *	exists. NOTE: Disabling hangcheck or reset via module parameter will
 *	cause the related events to not be seen.
 *
 * I915_RESET_UEVENT - Event is generated just before an attempt to reset the
 *	GPU. The value supplied with the event is always 1. NOTE: Disable
 *	reset via module parameter will cause this event to not be seen.
 */
#define I915_L3_PARITY_UEVENT		"L3_PARITY_ERROR"
#define I915_ERROR_UEVENT		"ERROR"
#define I915_RESET_UEVENT		"RESET"

/**
 * struct i915_user_extension - Base class for defining a chain of extensions
 *
 * Many interfaces need to grow over time. In most cases we can simply
 * extend the struct and have userspace pass in more data. Another option,
 * as demonstrated by Vulkan's approach to providing extensions for forward
 * and backward compatibility, is to use a list of optional structs to
 * provide those extra details.
 *
 * The key advantage to using an extension chain is that it allows us to
 * redefine the interface more easily than an ever growing struct of
 * increasing complexity, and for large parts of that interface to be
 * entirely optional. The downside is more pointer chasing; chasing across
 * the __user boundary with pointers encapsulated inside u64.
 *
 * Example chaining:
 *
 * .. code-block:: C
 *
 *	struct i915_user_extension ext3 {
 *		.next_extension = 0, // end
 *		.name = ...,
 *	};
 *	struct i915_user_extension ext2 {
 *		.next_extension = (uintptr_t)&ext3,
 *		.name = ...,
 *	};
 *	struct i915_user_extension ext1 {
 *		.next_extension = (uintptr_t)&ext2,
 *		.name = ...,
 *	};
 *
 * Typically the struct i915_user_extension would be embedded in some uAPI
 * struct, and in this case we would feed it the head of the chain(i.e ext1),
 * which would then apply all of the above extensions.
 *
 */
struct i915_user_extension {
	/**
	 * @next_extension:
	 *
	 * Pointer to the next struct i915_user_extension, or zero if the end.
	 */
	__u64 next_extension;
	/**
	 * @name: Name of the extension.
	 *
	 * Note that the name here is just some integer.
	 *
	 * Also note that the name space for this is not global for the whole
	 * driver, but rather its scope/meaning is limited to the specific piece
	 * of uAPI which has embedded the struct i915_user_extension.
	 */
	__u32 name;
	/**
	 * @flags: MBZ
	 *
	 * All undefined bits must be zero.
	 */
	__u32 flags;
	/**
	 * @rsvd: MBZ
	 *
	 * Reserved for future use; must be zero.
	 */
	__u32 rsvd[4];
};

/*
 * MOCS indexes used for GPU surfaces, defining the cacheability of the
 * surface data and the coherency for this data wrt. CPU vs. GPU accesses.
 */
enum i915_mocs_table_index {
	/*
	 * Not cached anywhere, coherency between CPU and GPU accesses is
	 * guaranteed.
	 */
	I915_MOCS_UNCACHED,
	/*
	 * Cacheability and coherency controlled by the kernel automatically
	 * based on the DRM_I915_GEM_SET_CACHING IOCTL setting and the current
	 * usage of the surface (used for display scanout or not).
	 */
	I915_MOCS_PTE,
	/*
	 * Cached in all GPU caches available on the platform.
	 * Coherency between CPU and GPU accesses to the surface is not
	 * guaranteed without extra synchronization.
	 */
	I915_MOCS_CACHED,
};

/**
 * enum drm_i915_gem_engine_class - uapi engine type enumeration
 *
 * Different engines serve different roles, and there may be more than one
 * engine serving each role.  This enum provides a classification of the role
 * of the engine, which may be used when requesting operations to be performed
 * on a certain subset of engines, or for providing information about that
 * group.
 */
enum drm_i915_gem_engine_class {
	/**
	 * @I915_ENGINE_CLASS_RENDER:
	 *
	 * Render engines support instructions used for 3D, Compute (GPGPU),
	 * and programmable media workloads.  These instructions fetch data and
	 * dispatch individual work items to threads that operate in parallel.
	 * The threads run small programs (called "kernels" or "shaders") on
	 * the GPU's execution units (EUs).
	 */
	I915_ENGINE_CLASS_RENDER	= 0,

	/**
	 * @I915_ENGINE_CLASS_COPY:
	 *
	 * Copy engines (also referred to as "blitters") support instructions
	 * that move blocks of data from one location in memory to another,
	 * or that fill a specified location of memory with fixed data.
	 * Copy engines can perform pre-defined logical or bitwise operations
	 * on the source, destination, or pattern data.
	 */
	I915_ENGINE_CLASS_COPY		= 1,

	/**
	 * @I915_ENGINE_CLASS_VIDEO:
	 *
	 * Video engines (also referred to as "bit stream decode" (BSD) or
	 * "vdbox") support instructions that perform fixed-function media
	 * decode and encode.
	 */
	I915_ENGINE_CLASS_VIDEO		= 2,

	/**
	 * @I915_ENGINE_CLASS_VIDEO_ENHANCE:
	 *
	 * Video enhancement engines (also referred to as "vebox") support
	 * instructions related to image enhancement.
	 */
	I915_ENGINE_CLASS_VIDEO_ENHANCE	= 3,

	/**
	 * @I915_ENGINE_CLASS_COMPUTE:
	 *
	 * Compute engines support a subset of the instructions available
	 * on render engines:  compute engines support Compute (GPGPU) and
	 * programmable media workloads, but do not support the 3D pipeline.
	 */
	I915_ENGINE_CLASS_COMPUTE	= 4,

	/* Values in this enum should be kept compact. */

	/**
	 * @I915_ENGINE_CLASS_INVALID:
	 *
	 * Placeholder value to represent an invalid engine class assignment.
	 */
	I915_ENGINE_CLASS_INVALID	= -1
};

/**
 * struct i915_engine_class_instance - Engine class/instance identifier
 *
 * There may be more than one engine fulfilling any role within the system.
 * Each engine of a class is given a unique instance number and therefore
 * any engine can be specified by its class:instance tuplet. APIs that allow
 * access to any engine in the system will use struct i915_engine_class_instance
 * for this identification.
 */
struct i915_engine_class_instance {
	/**
	 * @engine_class:
	 *
	 * Engine class from enum drm_i915_gem_engine_class
	 */
	__u16 engine_class;
#define I915_ENGINE_CLASS_INVALID_NONE -1
#define I915_ENGINE_CLASS_INVALID_VIRTUAL -2

	/**
	 * @engine_instance:
	 *
	 * Engine instance.
	 */
	__u16 engine_instance;
};

/**
 * DOC: perf_events exposed by i915 through /sys/bus/event_sources/drivers/i915
 *
 */

enum drm_i915_pmu_engine_sample {
	I915_SAMPLE_BUSY = 0,
	I915_SAMPLE_WAIT = 1,
	I915_SAMPLE_SEMA = 2
};

#define I915_PMU_SAMPLE_BITS (4)
#define I915_PMU_SAMPLE_MASK (0xf)
#define I915_PMU_SAMPLE_INSTANCE_BITS (8)
#define I915_PMU_CLASS_SHIFT \
	(I915_PMU_SAMPLE_BITS + I915_PMU_SAMPLE_INSTANCE_BITS)

#define __I915_PMU_ENGINE(class, instance, sample) \
	((class) << I915_PMU_CLASS_SHIFT | \
	(instance) << I915_PMU_SAMPLE_BITS | \
	(sample))

#define I915_PMU_ENGINE_BUSY(class, instance) \
	__I915_PMU_ENGINE(class, instance, I915_SAMPLE_BUSY)

#define I915_PMU_ENGINE_WAIT(class, instance) \
	__I915_PMU_ENGINE(class, instance, I915_SAMPLE_WAIT)

#define I915_PMU_ENGINE_SEMA(class, instance) \
	__I915_PMU_ENGINE(class, instance, I915_SAMPLE_SEMA)

/*
 * Top 4 bits of every non-engine counter are GT id.
 */
#define __I915_PMU_GT_SHIFT (60)

#define ___I915_PMU_OTHER(gt, x) \
	(((__u64)__I915_PMU_ENGINE(0xff, 0xff, 0xf) + 1 + (x)) | \
	((__u64)(gt) << __I915_PMU_GT_SHIFT))

#define __I915_PMU_OTHER(x) ___I915_PMU_OTHER(0, x)

#define I915_PMU_ACTUAL_FREQUENCY	__I915_PMU_OTHER(0)
#define I915_PMU_REQUESTED_FREQUENCY	__I915_PMU_OTHER(1)
#define I915_PMU_INTERRUPTS		__I915_PMU_OTHER(2)
#define I915_PMU_RC6_RESIDENCY		__I915_PMU_OTHER(3)
#define I915_PMU_SOFTWARE_GT_AWAKE_TIME	__I915_PMU_OTHER(4)

#define I915_PMU_LAST /* Deprecated - do not use */ I915_PMU_RC6_RESIDENCY

#define __I915_PMU_ACTUAL_FREQUENCY(gt)		___I915_PMU_OTHER(gt, 0)
#define __I915_PMU_REQUESTED_FREQUENCY(gt)	___I915_PMU_OTHER(gt, 1)
#define __I915_PMU_INTERRUPTS(gt)		___I915_PMU_OTHER(gt, 2)
#define __I915_PMU_RC6_RESIDENCY(gt)		___I915_PMU_OTHER(gt, 3)
#define __I915_PMU_SOFTWARE_GT_AWAKE_TIME(gt)	___I915_PMU_OTHER(gt, 4)

/* Each region is a minimum of 16k, and there are at most 255 of them.
 */
#define I915_NR_TEX_REGIONS 255	/* table size 2k - maximum due to use
				 * of chars for next/prev indices */
#define I915_LOG_MIN_TEX_REGION_SIZE 14

typedef struct _drm_i915_init {
	enum {
		I915_INIT_DMA = 0x01,
		I915_CLEANUP_DMA = 0x02,
		I915_RESUME_DMA = 0x03
	} func;
	unsigned int mmio_offset;
	int sarea_priv_offset;
	unsigned int ring_start;
	unsigned int ring_end;
	unsigned int ring_size;
	unsigned int front_offset;
	unsigned int back_offset;
	unsigned int depth_offset;
	unsigned int w;
	unsigned int h;
	unsigned int pitch;
	unsigned int pitch_bits;
	unsigned int back_pitch;
	unsigned int depth_pitch;
	unsigned int cpp;
	unsigned int chipset;
} drm_i915_init_t;

typedef struct _drm_i915_sarea {
	struct drm_tex_region texList[I915_NR_TEX_REGIONS + 1];
	int last_upload;	/* last time texture was uploaded */
	int last_enqueue;	/* last time a buffer was enqueued */
	int last_dispatch;	/* age of the most recently dispatched buffer */
	int ctxOwner;		/* last context to upload state */
	int texAge;
	int pf_enabled;		/* is pageflipping allowed? */
	int pf_active;
	int pf_current_page;	/* which buffer is being displayed? */
	int perf_boxes;		/* performance boxes to be displayed */
	int width, height;      /* screen size in pixels */

	drm_handle_t front_handle;
	int front_offset;
	int front_size;

	drm_handle_t back_handle;
	int back_offset;
	int back_size;

	drm_handle_t depth_handle;
	int depth_offset;
	int depth_size;

	drm_handle_t tex_handle;
	int tex_offset;
	int tex_size;
	int log_tex_granularity;
	int pitch;
	int rotation;           /* 0, 90, 180 or 270 */
	int rotated_offset;
	int rotated_size;
	int rotated_pitch;
	int virtualX, virtualY;

	unsigned int front_tiled;
	unsigned int back_tiled;
	unsigned int depth_tiled;
	unsigned int rotated_tiled;
	unsigned int rotated2_tiled;

	int pipeA_x;
	int pipeA_y;
	int pipeA_w;
	int pipeA_h;
	int pipeB_x;
	int pipeB_y;
	int pipeB_w;
	int pipeB_h;

	/* fill out some space for old userspace triple buffer */
	drm_handle_t unused_handle;
	__u32 unused1, unused2, unused3;

	/* buffer object handles for static buffers. May change
	 * over the lifetime of the client.
	 */
	__u32 front_bo_handle;
	__u32 back_bo_handle;
	__u32 unused_bo_handle;
	__u32 depth_bo_handle;

} drm_i915_sarea_t;

/* due to userspace building against these headers we need some compat here */
#define planeA_x pipeA_x
#define planeA_y pipeA_y
#define planeA_w pipeA_w
#define planeA_h pipeA_h
#define planeB_x pipeB_x
#define planeB_y pipeB_y
#define planeB_w pipeB_w
#define planeB_h pipeB_h

/* Flags for perf_boxes
 */
#define I915_BOX_RING_EMPTY    0x1
#define I915_BOX_FLIP          0x2
#define I915_BOX_WAIT          0x4
#define I915_BOX_TEXTURE_LOAD  0x8
#define I915_BOX_LOST_CONTEXT  0x10

/*
 * i915 specific ioctls.
 *
 * The device specific ioctl range is [DRM_COMMAND_BASE, DRM_COMMAND_END) ie
 * [0x40, 0xa0) (a0 is excluded). The numbers below are defined as offset
 * against DRM_COMMAND_BASE and should be between [0x0, 0x60).
 */
#define DRM_I915_INIT		0x00
#define DRM_I915_FLUSH		0x01
#define DRM_I915_FLIP		0x02
#define DRM_I915_BATCHBUFFER	0x03
#define DRM_I915_IRQ_EMIT	0x04
#define DRM_I915_IRQ_WAIT	0x05
#define DRM_I915_GETPARAM	0x06
#define DRM_I915_SETPARAM	0x07
#define DRM_I915_ALLOC		0x08
#define DRM_I915_FREE		0x09
#define DRM_I915_INIT_HEAP	0x0a
#define DRM_I915_CMDBUFFER	0x0b
#define DRM_I915_DESTROY_HEAP	0x0c
#define DRM_I915_SET_VBLANK_PIPE	0x0d
#define DRM_I915_GET_VBLANK_PIPE	0x0e
#define DRM_I915_VBLANK_SWAP	0x0f
#define DRM_I915_HWS_ADDR	0x11
#define DRM_I915_GEM_INIT	0x13
#define DRM_I915_GEM_EXECBUFFER	0x14
#define DRM_I915_GEM_PIN	0x15
#define DRM_I915_GEM_UNPIN	0x16
#define DRM_I915_GEM_BUSY	0x17
#define DRM_I915_GEM_THROTTLE	0x18
#define DRM_I915_GEM_ENTERVT	0x19
#define DRM_I915_GEM_LEAVEVT	0x1a
#define DRM_I915_GEM_CREATE	0x1b
#define DRM_I915_GEM_PREAD	0x1c
#define DRM_I915_GEM_PWRITE	0x1d
#define DRM_I915_GEM_MMAP	0x1e
#define DRM_I915_GEM_SET_DOMAIN	0x1f
#define DRM_I915_GEM_SW_FINISH	0x20
#define DRM_I915_GEM_SET_TILING	0x21
#define DRM_I915_GEM_GET_TILING	0x22
#define DRM_I915_GEM_GET_APERTURE 0x23
#define DRM_I915_GEM_MMAP_GTT	0x24
#define DRM_I915_GET_PIPE_FROM_CRTC_ID	0x25
#define DRM_I915_GEM_MADVISE	0x26
#define DRM_I915_OVERLAY_PUT_IMAGE	0x27
#define DRM_I915_OVERLAY_ATTRS	0x28
#define DRM_I915_GEM_EXECBUFFER2	0x29
#define DRM_I915_GEM_EXECBUFFER2_WR	DRM_I915_GEM_EXECBUFFER2
#define DRM_I915_GET_SPRITE_COLORKEY	0x2a
#define DRM_I915_SET_SPRITE_COLORKEY	0x2b
#define DRM_I915_GEM_WAIT	0x2c
#define DRM_I915_GEM_CONTEXT_CREATE	0x2d
#define DRM_I915_GEM_CONTEXT_DESTROY	0x2e
#define DRM_I915_GEM_SET_CACHING	0x2f
#define DRM_I915_GEM_GET_CACHING	0x30
#define DRM_I915_REG_READ		0x31
#define DRM_I915_GET_RESET_STATS	0x32
#define DRM_I915_GEM_USERPTR		0x33
#define DRM_I915_GEM_CONTEXT_GETPARAM	0x34
#define DRM_I915_GEM_CONTEXT_SETPARAM	0x35
#define DRM_I915_PERF_OPEN		0x36
#define DRM_I915_PERF_ADD_CONFIG	0x37
#define DRM_I915_PERF_REMOVE_CONFIG	0x38
#define DRM_I915_QUERY			0x39
#define DRM_I915_GEM_VM_CREATE		0x3a
#define DRM_I915_GEM_VM_DESTROY		0x3b
#define DRM_I915_GEM_CREATE_EXT		0x3c
/* Must be kept compact -- no holes */

#define DRM_IOCTL_I915_INIT		DRM_IOW( DRM_COMMAND_BASE + DRM_I915_INIT, drm_i915_init_t)
#define DRM_IOCTL_I915_FLUSH		DRM_IO ( DRM_COMMAND_BASE + DRM_I915_FLUSH)
#define DRM_IOCTL_I915_FLIP		DRM_IO ( DRM_COMMAND_BASE + DRM_I915_FLIP)
#define DRM_IOCTL_I915_BATCHBUFFER	DRM_IOW( DRM_COMMAND_BASE + DRM_I915_BATCHBUFFER, drm_i915_batchbuffer_t)
#define DRM_IOCTL_I915_IRQ_EMIT         DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_IRQ_EMIT, drm_i915_irq_emit_t)
#define DRM_IOCTL_I915_IRQ_WAIT         DRM_IOW( DRM_COMMAND_BASE + DRM_I915_IRQ_WAIT, drm_i915_irq_wait_t)
#define DRM_IOCTL_I915_GETPARAM         DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GETPARAM, drm_i915_getparam_t)
#define DRM_IOCTL_I915_SETPARAM         DRM_IOW( DRM_COMMAND_BASE + DRM_I915_SETPARAM, drm_i915_setparam_t)
#define DRM_IOCTL_I915_ALLOC            DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_ALLOC, drm_i915_mem_alloc_t)
#define DRM_IOCTL_I915_FREE             DRM_IOW( DRM_COMMAND_BASE + DRM_I915_FREE, drm_i915_mem_free_t)
#define DRM_IOCTL_I915_INIT_HEAP        DRM_IOW( DRM_COMMAND_BASE + DRM_I915_INIT_HEAP, drm_i915_mem_init_heap_t)
#define DRM_IOCTL_I915_CMDBUFFER	DRM_IOW( DRM_COMMAND_BASE + DRM_I915_CMDBUFFER, drm_i915_cmdbuffer_t)
#define DRM_IOCTL_I915_DESTROY_HEAP	DRM_IOW( DRM_COMMAND_BASE + DRM_I915_DESTROY_HEAP, drm_i915_mem_destroy_heap_t)
#define DRM_IOCTL_I915_SET_VBLANK_PIPE	DRM_IOW( DRM_COMMAND_BASE + DRM_I915_SET_VBLANK_PIPE, drm_i915_vblank_pipe_t)
#define DRM_IOCTL_I915_GET_VBLANK_PIPE	DRM_IOR( DRM_COMMAND_BASE + DRM_I915_GET_VBLANK_PIPE, drm_i915_vblank_pipe_t)
#define DRM_IOCTL_I915_VBLANK_SWAP	DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_VBLANK_SWAP, drm_i915_vblank_swap_t)
#define DRM_IOCTL_I915_HWS_ADDR		DRM_IOW(DRM_COMMAND_BASE + DRM_I915_HWS_ADDR, struct drm_i915_gem_init)
#define DRM_IOCTL_I915_GEM_INIT		DRM_IOW(DRM_COMMAND_BASE + DRM_I915_GEM_INIT, struct drm_i915_gem_init)
#define DRM_IOCTL_I915_GEM_EXECBUFFER	DRM_IOW(DRM_COMMAND_BASE + DRM_I915_GEM_EXECBUFFER, struct drm_i915_gem_execbuffer)
#define DRM_IOCTL_I915_GEM_EXECBUFFER2	DRM_IOW(DRM_COMMAND_BASE + DRM_I915_GEM_EXECBUFFER2, struct drm_i915_gem_execbuffer2)
#define DRM_IOCTL_I915_GEM_EXECBUFFER2_WR	DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_EXECBUFFER2_WR, struct drm_i915_gem_execbuffer2)
#define DRM_IOCTL_I915_GEM_PIN		DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_PIN, struct drm_i915_gem_pin)
#define DRM_IOCTL_I915_GEM_UNPIN	DRM_IOW(DRM_COMMAND_BASE + DRM_I915_GEM_UNPIN, struct drm_i915_gem_unpin)
#define DRM_IOCTL_I915_GEM_BUSY		DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_BUSY, struct drm_i915_gem_busy)
#define DRM_IOCTL_I915_GEM_SET_CACHING		DRM_IOW(DRM_COMMAND_BASE + DRM_I915_GEM_SET_CACHING, struct drm_i915_gem_caching)
#define DRM_IOCTL_I915_GEM_GET_CACHING		DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_GET_CACHING, struct drm_i915_gem_caching)
#define DRM_IOCTL_I915_GEM_THROTTLE	DRM_IO ( DRM_COMMAND_BASE + DRM_I915_GEM_THROTTLE)
#define DRM_IOCTL_I915_GEM_ENTERVT	DRM_IO(DRM_COMMAND_BASE + DRM_I915_GEM_ENTERVT)
#define DRM_IOCTL_I915_GEM_LEAVEVT	DRM_IO(DRM_COMMAND_BASE + DRM_I915_GEM_LEAVEVT)
#define DRM_IOCTL_I915_GEM_CREATE	DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_CREATE, struct drm_i915_gem_create)
#define DRM_IOCTL_I915_GEM_CREATE_EXT	DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_CREATE_EXT, struct drm_i915_gem_create_ext)
#define DRM_IOCTL_I915_GEM_PREAD	DRM_IOW (DRM_COMMAND_BASE + DRM_I915_GEM_PREAD, struct drm_i915_gem_pread)
#define DRM_IOCTL_I915_GEM_PWRITE	DRM_IOW (DRM_COMMAND_BASE + DRM_I915_GEM_PWRITE, struct drm_i915_gem_pwrite)
#define DRM_IOCTL_I915_GEM_MMAP		DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_MMAP, struct drm_i915_gem_mmap)
#define DRM_IOCTL_I915_GEM_MMAP_GTT	DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_MMAP_GTT, struct drm_i915_gem_mmap_gtt)
#define DRM_IOCTL_I915_GEM_MMAP_OFFSET	DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_MMAP_GTT, struct drm_i915_gem_mmap_offset)
#define DRM_IOCTL_I915_GEM_SET_DOMAIN	DRM_IOW (DRM_COMMAND_BASE + DRM_I915_GEM_SET_DOMAIN, struct drm_i915_gem_set_domain)
#define DRM_IOCTL_I915_GEM_SW_FINISH	DRM_IOW (DRM_COMMAND_BASE + DRM_I915_GEM_SW_FINISH, struct drm_i915_gem_sw_finish)
#define DRM_IOCTL_I915_GEM_SET_TILING	DRM_IOWR (DRM_COMMAND_BASE + DRM_I915_GEM_SET_TILING, struct drm_i915_gem_set_tiling)
#define DRM_IOCTL_I915_GEM_GET_TILING	DRM_IOWR (DRM_COMMAND_BASE + DRM_I915_GEM_GET_TILING, struct drm_i915_gem_get_tiling)
#define DRM_IOCTL_I915_GEM_GET_APERTURE	DRM_IOR  (DRM_COMMAND_BASE + DRM_I915_GEM_GET_APERTURE, struct drm_i915_gem_get_aperture)
#define DRM_IOCTL_I915_GET_PIPE_FROM_CRTC_ID DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GET_PIPE_FROM_CRTC_ID, struct drm_i915_get_pipe_from_crtc_id)
#define DRM_IOCTL_I915_GEM_MADVISE	DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_MADVISE, struct drm_i915_gem_madvise)
#define DRM_IOCTL_I915_OVERLAY_PUT_IMAGE	DRM_IOW(DRM_COMMAND_BASE + DRM_I915_OVERLAY_PUT_IMAGE, struct drm_intel_overlay_put_image)
#define DRM_IOCTL_I915_OVERLAY_ATTRS	DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_OVERLAY_ATTRS, struct drm_intel_overlay_attrs)
#define DRM_IOCTL_I915_SET_SPRITE_COLORKEY DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_SET_SPRITE_COLORKEY, struct drm_intel_sprite_colorkey)
#define DRM_IOCTL_I915_GET_SPRITE_COLORKEY DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GET_SPRITE_COLORKEY, struct drm_intel_sprite_colorkey)
#define DRM_IOCTL_I915_GEM_WAIT		DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_WAIT, struct drm_i915_gem_wait)
#define DRM_IOCTL_I915_GEM_CONTEXT_CREATE	DRM_IOWR (DRM_COMMAND_BASE + DRM_I915_GEM_CONTEXT_CREATE, struct drm_i915_gem_context_create)
#define DRM_IOCTL_I915_GEM_CONTEXT_CREATE_EXT	DRM_IOWR (DRM_COMMAND_BASE + DRM_I915_GEM_CONTEXT_CREATE, struct drm_i915_gem_context_create_ext)
#define DRM_IOCTL_I915_GEM_CONTEXT_DESTROY	DRM_IOW (DRM_COMMAND_BASE + DRM_I915_GEM_CONTEXT_DESTROY, struct drm_i915_gem_context_destroy)
#define DRM_IOCTL_I915_REG_READ			DRM_IOWR (DRM_COMMAND_BASE + DRM_I915_REG_READ, struct drm_i915_reg_read)
#define DRM_IOCTL_I915_GET_RESET_STATS		DRM_IOWR (DRM_COMMAND_BASE + DRM_I915_GET_RESET_STATS, struct drm_i915_reset_stats)
#define DRM_IOCTL_I915_GEM_USERPTR			DRM_IOWR (DRM_COMMAND_BASE + DRM_I915_GEM_USERPTR, struct drm_i915_gem_userptr)
#define DRM_IOCTL_I915_GEM_CONTEXT_GETPARAM	DRM_IOWR (DRM_COMMAND_BASE + DRM_I915_GEM_CONTEXT_GETPARAM, struct drm_i915_gem_context_param)
#define DRM_IOCTL_I915_GEM_CONTEXT_SETPARAM	DRM_IOWR (DRM_COMMAND_BASE + DRM_I915_GEM_CONTEXT_SETPARAM, struct drm_i915_gem_context_param)
#define DRM_IOCTL_I915_PERF_OPEN	DRM_IOW(DRM_COMMAND_BASE + DRM_I915_PERF_OPEN, struct drm_i915_perf_open_param)
#define DRM_IOCTL_I915_PERF_ADD_CONFIG	DRM_IOW(DRM_COMMAND_BASE + DRM_I915_PERF_ADD_CONFIG, struct drm_i915_perf_oa_config)
#define DRM_IOCTL_I915_PERF_REMOVE_CONFIG	DRM_IOW(DRM_COMMAND_BASE + DRM_I915_PERF_REMOVE_CONFIG, __u64)
#define DRM_IOCTL_I915_QUERY			DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_QUERY, struct drm_i915_query)
#define DRM_IOCTL_I915_GEM_VM_CREATE	DRM_IOWR(DRM_COMMAND_BASE + DRM_I915_GEM_VM_CREATE, struct drm_i915_gem_vm_control)
#define DRM_IOCTL_I915_GEM_VM_DESTROY	DRM_IOW (DRM_COMMAND_BASE + DRM_I915_GEM_VM_DESTROY, struct drm_i915_gem_vm_control)

/* Allow drivers to submit batchbuffers directly to hardware, relying
 * on the security mechanisms provided by hardware.
 */
typedef struct drm_i915_batchbuffer {
	int start;		/* agp offset */
	int used;		/* nr bytes in use */
	int DR1;		/* hw flags for GFX_OP_DRAWRECT_INFO */
	int DR4;		/* window origin for GFX_OP_DRAWRECT_INFO */
	int num_cliprects;	/* mulitpass with multiple cliprects? */
	struct drm_clip_rect __user *cliprects;	/* pointer to userspace cliprects */
} drm_i915_batchbuffer_t;

/* As above, but pass a pointer to userspace buffer which can be
 * validated by the kernel prior to sending to hardware.
 */
typedef struct _drm_i915_cmdbuffer {
	char __user *buf;	/* pointer to userspace command buffer */
	int sz;			/* nr bytes in buf */
	int DR1;		/* hw flags for GFX_OP_DRAWRECT_INFO */
	int DR4;		/* window origin for GFX_OP_DRAWRECT_INFO */
	int num_cliprects;	/* mulitpass with multiple cliprects? */
	struct drm_clip_rect __user *cliprects;	/* pointer to userspace cliprects */
} drm_i915_cmdbuffer_t;

/* Userspace can request & wait on irq's:
 */
typedef struct drm_i915_irq_emit {
	int __user *irq_seq;
} drm_i915_irq_emit_t;

typedef struct drm_i915_irq_wait {
	int irq_seq;
} drm_i915_irq_wait_t;

/*
 * Different modes of per-process Graphics Translation Table,
 * see I915_PARAM_HAS_ALIASING_PPGTT
 */
#define I915_GEM_PPGTT_NONE	0
#define I915_GEM_PPGTT_ALIASING	1
#define I915_GEM_PPGTT_FULL	2

/* Ioctl to query kernel params:
 */
#define I915_PARAM_IRQ_ACTIVE            1
#define I915_PARAM_ALLOW_BATCHBUFFER     2
#define I915_PARAM_LAST_DISPATCH         3
#define I915_PARAM_CHIPSET_ID            4
#define I915_PARAM_HAS_GEM               5
#define I915_PARAM_NUM_FENCES_AVAIL      6
#define I915_PARAM_HAS_OVERLAY           7
#define I915_PARAM_HAS_PAGEFLIPPING	 8
#define I915_PARAM_HAS_EXECBUF2          9
#define I915_PARAM_HAS_BSD		 10
#define I915_PARAM_HAS_BLT		 11
#define I915_PARAM_HAS_RELAXED_FENCING	 12
#define I915_PARAM_HAS_COHERENT_RINGS	 13
#define I915_PARAM_HAS_EXEC_CONSTANTS	 14
#define I915_PARAM_HAS_RELAXED_DELTA	 15
#define I915_PARAM_HAS_GEN7_SOL_RESET	 16
#define I915_PARAM_HAS_LLC     	 	 17
#define I915_PARAM_HAS_ALIASING_PPGTT	 18
#define I915_PARAM_HAS_WAIT_TIMEOUT	 19
#define I915_PARAM_HAS_SEMAPHORES	 20
#define I915_PARAM_HAS_PRIME_VMAP_FLUSH	 21
#define I915_PARAM_HAS_VEBOX		 22
#define I915_PARAM_HAS_SECURE_BATCHES	 23
#define I915_PARAM_HAS_PINNED_BATCHES	 24
#define I915_PARAM_HAS_EXEC_NO_RELOC	 25
#define I915_PARAM_HAS_EXEC_HANDLE_LUT   26
#define I915_PARAM_HAS_WT     	 	 27
#define I915_PARAM_CMD_PARSER_VERSION	 28
#define I915_PARAM_HAS_COHERENT_PHYS_GTT 29
#define I915_PARAM_MMAP_VERSION          30
#define I915_PARAM_HAS_BSD2		 31
#define I915_PARAM_REVISION              32
#define I915_PARAM_SUBSLICE_TOTAL	 33
#define I915_PARAM_EU_TOTAL		 34
#define I915_PARAM_HAS_GPU_RESET	 35
#define I915_PARAM_HAS_RESOURCE_STREAMER 36
#define I915_PARAM_HAS_EXEC_SOFTPIN	 37
#define I915_PARAM_HAS_POOLED_EU	 38
#define I915_PARAM_MIN_EU_IN_POOL	 39
#define I915_PARAM_MMAP_GTT_VERSION	 40

/*
 * Query whether DRM_I915_GEM_EXECBUFFER2 supports user defined execution
 * priorities and the driver will attempt to execute batches in priority order.
 * The param returns a capability bitmask, nonzero implies that the scheduler
 * is enabled, with different features present according to the mask.
 *
 * The initial priority for each batch is supplied by the context and is
 * controlled via I915_CONTEXT_PARAM_PRIORITY.
 */
#define I915_PARAM_HAS_SCHEDULER	 41
#define   I915_SCHEDULER_CAP_ENABLED	(1ul << 0)
#define   I915_SCHEDULER_CAP_PRIORITY	(1ul << 1)
#define   I915_SCHEDULER_CAP_PREEMPTION	(1ul << 2)
#define   I915_SCHEDULER_CAP_SEMAPHORES	(1ul << 3)
#define   I915_SCHEDULER_CAP_ENGINE_BUSY_STATS	(1ul << 4)
/*
 * Indicates the 2k user priority levels are statically mapped into 3 buckets as
 * follows:
 *
 * -1k to -1	Low priority
 * 0		Normal priority
 * 1 to 1k	Highest priority
 */
#define   I915_SCHEDULER_CAP_STATIC_PRIORITY_MAP	(1ul << 5)

/*
 * Query the status of HuC load.
 *
 * The query can fail in the following scenarios with the listed error codes:
 *  -ENODEV if HuC is not present on this platform,
 *  -EOPNOTSUPP if HuC firmware usage is disabled,
 *  -ENOPKG if HuC firmware fetch failed,
 *  -ENOEXEC if HuC firmware is invalid or mismatched,
 *  -ENOMEM if i915 failed to prepare the FW objects for transfer to the uC,
 *  -EIO if the FW transfer or the FW authentication failed.
 *
 * If the IOCTL is successful, the returned parameter will be set to one of the
 * following values:
 *  * 0 if HuC firmware load is not complete,
 *  * 1 if HuC firmware is loaded and fully authenticated,
 *  * 2 if HuC firmware is loaded and authenticated for clear media only
 */
#define I915_PARAM_HUC_STATUS		 42

/* Query whether DRM_I915_GEM_EXECBUFFER2 supports the ability to opt-out of
 * synchronisation with implicit fencing on individual objects.
 * See EXEC_OBJECT_ASYNC.
 */
#define I915_PARAM_HAS_EXEC_ASYNC	 43

/* Query whether DRM_I915_GEM_EXECBUFFER2 supports explicit fence support -
 * both being able to pass in a sync_file fd to wait upon before executing,
 * and being able to return a new sync_file fd that is signaled when the
 * current request is complete. See I915_EXEC_FENCE_IN and I915_EXEC_FENCE_OUT.
 */
#define I915_PARAM_HAS_EXEC_FENCE	 44

/* Query whether DRM_I915_GEM_EXECBUFFER2 supports the ability to capture
 * user-specified buffers for post-mortem debugging of GPU hangs. See
 * EXEC_OBJECT_CAPTURE.
 */
#define I915_PARAM_HAS_EXEC_CAPTURE	 45

#define I915_PARAM_SLICE_MASK		 46

/* Assuming it's uniform for each slice, this queries the mask of subslices
 * per-slice for this system.
 */
#define I915_PARAM_SUBSLICE_MASK	 47

/*
 * Query whether DRM_I915_GEM_EXECBUFFER2 supports supplying the batch buffer
 * as the first execobject as opposed to the last. See I915_EXEC_BATCH_FIRST.
 */
#define I915_PARAM_HAS_EXEC_BATCH_FIRST	 48

/* Query whether DRM_I915_GEM_EXECBUFFER2 supports supplying an array of
 * drm_i915_gem_exec_fence structures.  See I915_EXEC_FENCE_ARRAY.
 */
#define I915_PARAM_HAS_EXEC_FENCE_ARRAY  49

/*
 * Query whether every context (both per-file default and user created) is
 * isolated (insofar as HW supports). If this parameter is not true, then
 * freshly created contexts may inherit values from an existing context,
 * rather than default HW values. If true, it also ensures (insofar as HW
 * supports) that all state set by this context will not leak to any other
 * context.
 *
 * As not every engine across every gen support contexts, the returned
 * value reports the support of context isolation for individual engines by
 * returning a bitmask of each engine class set to true if that class supports
 * isolation.
 */
#define I915_PARAM_HAS_CONTEXT_ISOLATION 50

/* Frequency of the command streamer timestamps given by the *_TIMESTAMP
 * registers. This used to be fixed per platform but from CNL onwards, this
 * might vary depending on the parts.
 */
#define I915_PARAM_CS_TIMESTAMP_FREQUENCY 51

/*
 * Once upon a time we supposed that writes through the GGTT would be
 * immediately in physical memory (once flushed out of the CPU path). However,
 * on a few different processors and chipsets, this is not necessarily the case
 * as the writes appear to be buffered internally. Thus a read of the backing
 * storage (physical memory) via a different path (with different physical tags
 * to the indirect write via the GGTT) will see stale values from before
 * the GGTT write. Inside the kernel, we can for the most part keep track of
 * the different read/write domains in use (e.g. set-domain), but the assumption
 * of coherency is baked into the ABI, hence reporting its true state in this
 * parameter.
 *
 * Reports true when writes via mmap_gtt are immediately visible following an
 * lfence to flush the WCB.
 *
 * Reports false when writes via mmap_gtt are indeterminately delayed in an in
 * internal buffer and are _not_ immediately visible to third parties accessing
 * directly via mmap_cpu/mmap_wc. Use of mmap_gtt as part of an IPC
 * communications channel when reporting false is strongly disadvised.
 */
#define I915_PARAM_MMAP_GTT_COHERENT	52

/*
 * Query whether DRM_I915_GEM_EXECBUFFER2 supports coordination of parallel
 * execution through use of explicit fence support.
 * See I915_EXEC_FENCE_OUT and I915_EXEC_FENCE_SUBMIT.
 */
#define I915_PARAM_HAS_EXEC_SUBMIT_FENCE 53

/*
 * Revision of the i915-perf uAPI. The value returned helps determine what
 * i915-perf features are available. See drm_i915_perf_property_id.
 */
#define I915_PARAM_PERF_REVISION	54

/* Query whether DRM_I915_GEM_EXECBUFFER2 supports supplying an array of
 * timeline syncobj through drm_i915_gem_execbuffer_ext_timeline_fences. See
 * I915_EXEC_USE_EXTENSIONS.
 */
#define I915_PARAM_HAS_EXEC_TIMELINE_FENCES 55

/* Query if the kernel supports the I915_USERPTR_PROBE flag. */
#define I915_PARAM_HAS_USERPTR_PROBE 56

/*
 * Frequency of the timestamps in OA reports. This used to be the same as the CS
 * timestamp frequency, but differs on some platforms.
 */
#define I915_PARAM_OA_TIMESTAMP_FREQUENCY 57

/*
 * Query the status of PXP support in i915.
 *
 * The query can fail in the following scenarios with the listed error codes:
 *     -ENODEV = PXP support is not available on the GPU device or in the
 *               kernel due to missing component drivers or kernel configs.
 *
 * If the IOCTL is successful, the returned parameter will be set to one of
 * the following values:
 *     1 = PXP feature is supported and is ready for use.
 *     2 = PXP feature is supported but should be ready soon (pending
 *         initialization of non-i915 system dependencies).
 *
 * NOTE: When param is supported (positive return values), user space should
 *       still refer to the GEM PXP context-creation UAPI header specs to be
 *       aware of possible failure due to system state machine at the time.
 */
#define I915_PARAM_PXP_STATUS		 58

/* Must be kept compact -- no holes and well documented */

/**
 * struct drm_i915_getparam - Driver parameter query structure.
 */
struct drm_i915_getparam {
	/** @param: Driver parameter to query. */
	__s32 param;

	/**
	 * @value: Address of memory where queried value should be put.
	 *
	 * WARNING: Using pointers instead of fixed-size u64 means we need to write
	 * compat32 code. Don't repeat this mistake.
	 */
	int __user *value;
};

/**
 * typedef drm_i915_getparam_t - Driver parameter query structure.
 * See struct drm_i915_getparam.
 */
typedef struct drm_i915_getparam drm_i915_getparam_t;

/* Ioctl to set kernel params:
 */
#define I915_SETPARAM_USE_MI_BATCHBUFFER_START            1
#define I915_SETPARAM_TEX_LRU_LOG_GRANULARITY             2
#define I915_SETPARAM_ALLOW_BATCHBUFFER                   3
#define I915_SETPARAM_NUM_USED_FENCES                     4
/* Must be kept compact -- no holes */

typedef struct drm_i915_setparam {
	int param;
	int value;
} drm_i915_setparam_t;

/* A memory manager for regions of shared memory:
 */
#define I915_MEM_REGION_AGP 1

typedef struct drm_i915_mem_alloc {
	int region;
	int alignment;
	int size;
	int __user *region_offset;	/* offset from start of fb or agp */
} drm_i915_mem_alloc_t;

typedef struct drm_i915_mem_free {
	int region;
	int region_offset;
} drm_i915_mem_free_t;

typedef struct drm_i915_mem_init_heap {
	int region;
	int size;
	int start;
} drm_i915_mem_init_heap_t;

/* Allow memory manager to be torn down and re-initialized (eg on
 * rotate):
 */
typedef struct drm_i915_mem_destroy_heap {
	int region;
} drm_i915_mem_destroy_heap_t;

/* Allow X server to configure which pipes to monitor for vblank signals
 */
#define	DRM_I915_VBLANK_PIPE_A	1
#define	DRM_I915_VBLANK_PIPE_B	2

typedef struct drm_i915_vblank_pipe {
	int pipe;
} drm_i915_vblank_pipe_t;

/* Schedule buffer swap at given vertical blank:
 */
typedef struct drm_i915_vblank_swap {
	drm_drawable_t drawable;
	enum drm_vblank_seq_type seqtype;
	unsigned int sequence;
} drm_i915_vblank_swap_t;

typedef struct drm_i915_hws_addr {
	__u64 addr;
} drm_i915_hws_addr_t;

struct drm_i915_gem_init {
	/**
	 * Beginning offset in the GTT to be managed by the DRM memory
	 * manager.
	 */
	__u64 gtt_start;
	/**
	 * Ending offset in the GTT to be managed by the DRM memory
	 * manager.
	 */
	__u64 gtt_end;
};

struct drm_i915_gem_create {
	/**
	 * Requested size for the object.
	 *
	 * The (page-aligned) allocated size for the object will be returned.
	 */
	__u64 size;
	/**
	 * Returned handle for the object.
	 *
	 * Object handles are nonzero.
	 */
	__u32 handle;
	__u32 pad;
};

struct drm_i915_gem_pread {
	/** Handle for the object being read. */
	__u32 handle;
	__u32 pad;
	/** Offset into the object to read from */
	__u64 offset;
	/** Length of data to read */
	__u64 size;
	/**
	 * Pointer to write the data into.
	 *
	 * This is a fixed-size type for 32/64 compatibility.
	 */
	__u64 data_ptr;
};

struct drm_i915_gem_pwrite {
	/** Handle for the object being written to. */
	__u32 handle;
	__u32 pad;
	/** Offset into the object to write to */
	__u64 offset;
	/** Length of data to write */
	__u64 size;
	/**
	 * Pointer to read the data from.
	 *
	 * This is a fixed-size type for 32/64 compatibility.
	 */
	__u64 data_ptr;
};

struct drm_i915_gem_mmap {
	/** Handle for the object being mapped. */
	__u32 handle;
	__u32 pad;
	/** Offset in the object to map. */
	__u64 offset;
	/**
	 * Length of data to map.
	 *
	 * The value will be page-aligned.
	 */
	__u64 size;
	/**
	 * Returned pointer the data was mapped at.
	 *
	 * This is a fixed-size type for 32/64 compatibility.
	 */
	__u64 addr_ptr;

	/**
	 * Flags for extended behaviour.
	 *
	 * Added in version 2.
	 */
	__u64 flags;
#define I915_MMAP_WC 0x1
};

struct drm_i915_gem_mmap_gtt {
	/** Handle for the object being mapped. */
	__u32 handle;
	__u32 pad;
	/**
	 * Fake offset to use for subsequent mmap call
	 *
	 * This is a fixed-size type for 32/64 compatibility.
	 */
	__u64 offset;
};

/**
 * struct drm_i915_gem_mmap_offset - Retrieve an offset so we can mmap this buffer object.
 *
 * This struct is passed as argument to the `DRM_IOCTL_I915_GEM_MMAP_OFFSET` ioctl,
 * and is used to retrieve the fake offset to mmap an object specified by &handle.
 *
 * The legacy way of using `DRM_IOCTL_I915_GEM_MMAP` is removed on gen12+.
 * `DRM_IOCTL_I915_GEM_MMAP_GTT` is an older supported alias to this struct, but will behave
 * as setting the &extensions to 0, and &flags to `I915_MMAP_OFFSET_GTT`.
 */
struct drm_i915_gem_mmap_offset {
	/** @handle: Handle for the object being mapped. */
	__u32 handle;
	/** @pad: Must be zero */
	__u32 pad;
	/**
	 * @offset: The fake offset to use for subsequent mmap call
	 *
	 * This is a fixed-size type for 32/64 compatibility.
	 */
	__u64 offset;

	/**
	 * @flags: Flags for extended behaviour.
	 *
	 * It is mandatory that one of the `MMAP_OFFSET` types
	 * should be included:
	 *
	 * - `I915_MMAP_OFFSET_GTT`: Use mmap with the object bound to GTT. (Write-Combined)
	 * - `I915_MMAP_OFFSET_WC`: Use Write-Combined caching.
	 * - `I915_MMAP_OFFSET_WB`: Use Write-Back caching.
	 * - `I915_MMAP_OFFSET_FIXED`: Use object placement to determine caching.
	 *
	 * On devices with local memory `I915_MMAP_OFFSET_FIXED` is the only valid
	 * type. On devices without local memory, this caching mode is invalid.
	 *
	 * As caching mode when specifying `I915_MMAP_OFFSET_FIXED`, WC or WB will
	 * be used, depending on the object placement on creation. WB will be used
	 * when the object can only exist in system memory, WC otherwise.
	 */
	__u64 flags;

#define I915_MMAP_OFFSET_GTT	0
#define I915_MMAP_OFFSET_WC	1
#define I915_MMAP_OFFSET_WB	2
#define I915_MMAP_OFFSET_UC	3
#define I915_MMAP_OFFSET_FIXED	4

	/**
	 * @extensions: Zero-terminated chain of extensions.
	 *
	 * No current extensions defined; mbz.
	 */
	__u64 extensions;
};

/**
 * struct drm_i915_gem_set_domain - Adjust the objects write or read domain, in
 * preparation for accessing the pages via some CPU domain.
 *
 * Specifying a new write or read domain will flush the object out of the
 * previous domain(if required), before then updating the objects domain
 * tracking with the new domain.
 *
 * Note this might involve waiting for the object first if it is still active on
 * the GPU.
 *
 * Supported values for @read_domains and @write_domain:
 *
 *	- I915_GEM_DOMAIN_WC: Uncached write-combined domain
 *	- I915_GEM_DOMAIN_CPU: CPU cache domain
 *	- I915_GEM_DOMAIN_GTT: Mappable aperture domain
 *
 * All other domains are rejected.
 *
 * Note that for discrete, starting from DG1, this is no longer supported, and
 * is instead rejected. On such platforms the CPU domain is effectively static,
 * where we also only support a single &drm_i915_gem_mmap_offset cache mode,
 * which can't be set explicitly and instead depends on the object placements,
 * as per the below.
 *
 * Implicit caching rules, starting from DG1:
 *
 *	- If any of the object placements (see &drm_i915_gem_create_ext_memory_regions)
 *	  contain I915_MEMORY_CLASS_DEVICE then the object will be allocated and
 *	  mapped as write-combined only.
 *
 *	- Everything else is always allocated and mapped as write-back, with the
 *	  guarantee that everything is also coherent with the GPU.
 *
 * Note that this is likely to change in the future again, where we might need
 * more flexibility on future devices, so making this all explicit as part of a
 * new &drm_i915_gem_create_ext extension is probable.
 */
struct drm_i915_gem_set_domain {
	/** @handle: Handle for the object. */
	__u32 handle;

	/** @read_domains: New read domains. */
	__u32 read_domains;

	/**
	 * @write_domain: New write domain.
	 *
	 * Note that having something in the write domain implies it's in the
	 * read domain, and only that read domain.
	 */
	__u32 write_domain;
};

struct drm_i915_gem_sw_finish {
	/** Handle for the object */
	__u32 handle;
};

struct drm_i915_gem_relocation_entry {
	/**
	 * Handle of the buffer being pointed to by this relocation entry.
	 *
	 * It's appealing to make this be an index into the mm_validate_entry
	 * list to refer to the buffer, but this allows the driver to create
	 * a relocation list for state buffers and not re-write it per
	 * exec using the buffer.
	 */
	__u32 target_handle;

	/**
	 * Value to be added to the offset of the target buffer to make up
	 * the relocation entry.
	 */
	__u32 delta;

	/** Offset in the buffer the relocation entry will be written into */
	__u64 offset;

	/**
	 * Offset value of the target buffer that the relocation entry was last
	 * written as.
	 *
	 * If the buffer has the same offset as last time, we can skip syncing
	 * and writing the relocation.  This value is written back out by
	 * the execbuffer ioctl when the relocation is written.
	 */
	__u64 presumed_offset;

	/**
	 * Target memory domains read by this operation.
	 */
	__u32 read_domains;

	/**
	 * Target memory domains written by this operation.
	 *
	 * Note that only one domain may be written by the whole
	 * execbuffer operation, so that where there are conflicts,
	 * the application will get -EINVAL back.
	 */
	__u32 write_domain;
};

/** @{
 * Intel memory domains
 *
 * Most of these just align with the various caches in
 * the system and are used to flush and invalidate as
 * objects end up cached in different domains.
 */
/** CPU cache */
#define I915_GEM_DOMAIN_CPU		0x00000001
/** Render cache, used by 2D and 3D drawing */
#define I915_GEM_DOMAIN_RENDER		0x00000002
/** Sampler cache, used by texture engine */
#define I915_GEM_DOMAIN_SAMPLER		0x00000004
/** Command queue, used to load batch buffers */
#define I915_GEM_DOMAIN_COMMAND		0x00000008
/** Instruction cache, used by shader programs */
#define I915_GEM_DOMAIN_INSTRUCTION	0x00000010
/** Vertex address cache */
#define I915_GEM_DOMAIN_VERTEX		0x00000020
/** GTT domain - aperture and scanout */
#define I915_GEM_DOMAIN_GTT		0x00000040
/** WC domain - uncached access */
#define I915_GEM_DOMAIN_WC		0x00000080
/** @} */

struct drm_i915_gem_exec_object {
	/**
	 * User's handle for a buffer to be bound into the GTT for this
	 * operation.
	 */
	__u32 handle;

	/** Number of relocations to be performed on this buffer */
	__u32 relocation_count;
	/**
	 * Pointer to array of struct drm_i915_gem_relocation_entry containing
	 * the relocations to be performed in this buffer.
	 */
	__u64 relocs_ptr;

	/** Required alignment in graphics aperture */
	__u64 alignment;

	/**
	 * Returned value of the updated offset of the object, for future
	 * presumed_offset writes.
	 */
	__u64 offset;
};

/* DRM_IOCTL_I915_GEM_EXECBUFFER was removed in Linux 5.13 */
struct drm_i915_gem_execbuffer {
	/**
	 * List of buffers to be validated with their relocations to be
	 * performend on them.
	 *
	 * This is a pointer to an array of struct drm_i915_gem_validate_entry.
	 *
	 * These buffers must be listed in an order such that all relocations
	 * a buffer is performing refer to buffers that have already appeared
	 * in the validate list.
	 */
	__u64 buffers_ptr;
	__u32 buffer_count;

	/** Offset in the batchbuffer to start execution from. */
	__u32 batch_start_offset;
	/** Bytes used in batchbuffer from batch_start_offset */
	__u32 batch_len;
	__u32 DR1;
	__u32 DR4;
	__u32 num_cliprects;
	/** This is a struct drm_clip_rect *cliprects */
	__u64 cliprects_ptr;
};

struct drm_i915_gem_exec_object2 {
	/**
	 * User's handle for a buffer to be bound into the GTT for this
	 * operation.
	 */
	__u32 handle;

	/** Number of relocations to be performed on this buffer */
	__u32 relocation_count;
	/**
	 * Pointer to array of struct drm_i915_gem_relocation_entry containing
	 * the relocations to be performed in this buffer.
	 */
	__u64 relocs_ptr;

	/** Required alignment in graphics aperture */
	__u64 alignment;

	/**
	 * When the EXEC_OBJECT_PINNED flag is specified this is populated by
	 * the user with the GTT offset at which this object will be pinned.
	 *
	 * When the I915_EXEC_NO_RELOC flag is specified this must contain the
	 * presumed_offset of the object.
	 *
	 * During execbuffer2 the kernel populates it with the value of the
	 * current GTT offset of the object, for future presumed_offset writes.
	 *
	 * See struct drm_i915_gem_create_ext for the rules when dealing with
	 * alignment restrictions with I915_MEMORY_CLASS_DEVICE, on devices with
	 * minimum page sizes, like DG2.
	 */
	__u64 offset;

#define EXEC_OBJECT_NEEDS_FENCE		 (1<<0)
#define EXEC_OBJECT_NEEDS_GTT		 (1<<1)
#define EXEC_OBJECT_WRITE		 (1<<2)
#define EXEC_OBJECT_SUPPORTS_48B_ADDRESS (1<<3)
#define EXEC_OBJECT_PINNED		 (1<<4)
#define EXEC_OBJECT_PAD_TO_SIZE		 (1<<5)
/* The kernel implicitly tracks GPU activity on all GEM objects, and
 * synchronises operations with outstanding rendering. This includes
 * rendering on other devices if exported via dma-buf. However, sometimes
 * this tracking is too coarse and the user knows better. For example,
 * if the object is split into non-overlapping ranges shared between different
 * clients or engines (i.e. suballocating objects), the implicit tracking
 * by kernel assumes that each operation affects the whole object rather
 * than an individual range, causing needless synchronisation between clients.
 * The kernel will also forgo any CPU cache flushes prior to rendering from
 * the object as the client is expected to be also handling such domain
 * tracking.
 *
 * The kernel maintains the implicit tracking in order to manage resources
 * used by the GPU - this flag only disables the synchronisation prior to
 * rendering with this object in this execbuf.
 *
 * Opting out of implicit synhronisation requires the user to do its own
 * explicit tracking to avoid rendering corruption. See, for example,
 * I915_PARAM_HAS_EXEC_FENCE to order execbufs and execute them asynchronously.
 */
#define EXEC_OBJECT_ASYNC		(1<<6)
/* Request that the contents of this execobject be copied into the error
 * state upon a GPU hang involving this batch for post-mortem debugging.
 * These buffers are recorded in no particular order as "user" in
 * /sys/class/drm/cardN/error. Query I915_PARAM_HAS_EXEC_CAPTURE to see
 * if the kernel supports this flag.
 */
#define EXEC_OBJECT_CAPTURE		(1<<7)
/* All remaining bits are MBZ and RESERVED FOR FUTURE USE */
#define __EXEC_OBJECT_UNKNOWN_FLAGS -(EXEC_OBJECT_CAPTURE<<1)
	__u64 flags;

	union {
		__u64 rsvd1;
		__u64 pad_to_size;
	};
	__u64 rsvd2;
};

/**
 * struct drm_i915_gem_exec_fence - An input or output fence for the execbuf
 * ioctl.
 *
 * The request will wait for input fence to signal before submission.
 *
 * The returned output fence will be signaled after the completion of the
 * request.
 */
struct drm_i915_gem_exec_fence {
	/** @handle: User's handle for a drm_syncobj to wait on or signal. */
	__u32 handle;

	/**
	 * @flags: Supported flags are:
	 *
	 * I915_EXEC_FENCE_WAIT:
	 * Wait for the input fence before request submission.
	 *
	 * I915_EXEC_FENCE_SIGNAL:
	 * Return request completion fence as output
	 */
	__u32 flags;
#define I915_EXEC_FENCE_WAIT            (1<<0)
#define I915_EXEC_FENCE_SIGNAL          (1<<1)
#define __I915_EXEC_FENCE_UNKNOWN_FLAGS (-(I915_EXEC_FENCE_SIGNAL << 1))
};

/**
 * struct drm_i915_gem_execbuffer_ext_timeline_fences - Timeline fences
 * for execbuf ioctl.
 *
 * This structure describes an array of drm_syncobj and associated points for
 * timeline variants of drm_syncobj. It is invalid to append this structure to
 * the execbuf if I915_EXEC_FENCE_ARRAY is set.
 */
struct drm_i915_gem_execbuffer_ext_timeline_fences {
#define DRM_I915_GEM_EXECBUFFER_EXT_TIMELINE_FENCES 0
	/** @base: Extension link. See struct i915_user_extension. */
	struct i915_user_extension base;

	/**
	 * @fence_count: Number of elements in the @handles_ptr & @value_ptr
	 * arrays.
	 */
	__u64 fence_count;

	/**
	 * @handles_ptr: Pointer to an array of struct drm_i915_gem_exec_fence
	 * of length @fence_count.
	 */
	__u64 handles_ptr;

	/**
	 * @values_ptr: Pointer to an array of u64 values of length
	 * @fence_count.
	 * Values must be 0 for a binary drm_syncobj. A Value of 0 for a
	 * timeline drm_syncobj is invalid as it turns a drm_syncobj into a
	 * binary one.
	 */
	__u64 values_ptr;
};

/**
 * struct drm_i915_gem_execbuffer2 - Structure for DRM_I915_GEM_EXECBUFFER2
 * ioctl.
 */
struct drm_i915_gem_execbuffer2 {
	/** @buffers_ptr: Pointer to a list of gem_exec_object2 structs */
	__u64 buffers_ptr;

	/** @buffer_count: Number of elements in @buffers_ptr array */
	__u32 buffer_count;

	/**
	 * @batch_start_offset: Offset in the batchbuffer to start execution
	 * from.
	 */
	__u32 batch_start_offset;

	/**
	 * @batch_len: Length in bytes of the batch buffer, starting from the
	 * @batch_start_offset. If 0, length is assumed to be the batch buffer
	 * object size.
	 */
	__u32 batch_len;

	/** @DR1: deprecated */
	__u32 DR1;

	/** @DR4: deprecated */
	__u32 DR4;

	/** @num_cliprects: See @cliprects_ptr */
	__u32 num_cliprects;

	/**
	 * @cliprects_ptr: Kernel clipping was a DRI1 misfeature.
	 *
	 * It is invalid to use this field if I915_EXEC_FENCE_ARRAY or
	 * I915_EXEC_USE_EXTENSIONS flags are not set.
	 *
	 * If I915_EXEC_FENCE_ARRAY is set, then this is a pointer to an array
	 * of &drm_i915_gem_exec_fence and @num_cliprects is the length of the
	 * array.
	 *
	 * If I915_EXEC_USE_EXTENSIONS is set, then this is a pointer to a
	 * single &i915_user_extension and num_cliprects is 0.
	 */
	__u64 cliprects_ptr;

	/** @flags: Execbuf flags */
	__u64 flags;
#define I915_EXEC_RING_MASK              (0x3f)
#define I915_EXEC_DEFAULT                (0<<0)
#define I915_EXEC_RENDER                 (1<<0)
#define I915_EXEC_BSD                    (2<<0)
#define I915_EXEC_BLT                    (3<<0)
#define I915_EXEC_VEBOX                  (4<<0)

/* Used for switching the constants addressing mode on gen4+ RENDER ring.
 * Gen6+ only supports relative addressing to dynamic state (default) and
 * absolute addressing.
 *
 * These flags are ignored for the BSD and BLT rings.
 */
#define I915_EXEC_CONSTANTS_MASK 	(3<<6)
#define I915_EXEC_CONSTANTS_REL_GENERAL (0<<6) /* default */
#define I915_EXEC_CONSTANTS_ABSOLUTE 	(1<<6)
#define I915_EXEC_CONSTANTS_REL_SURFACE (2<<6) /* gen4/5 only */

/** Resets the SO write offset registers for transform feedback on gen7. */
#define I915_EXEC_GEN7_SOL_RESET	(1<<8)

/** Request a privileged ("secure") batch buffer. Note only available for
 * DRM_ROOT_ONLY | DRM_MASTER processes.
 */
#define I915_EXEC_SECURE		(1<<9)

/** Inform the kernel that the batch is and will always be pinned. This
 * negates the requirement for a workaround to be performed to avoid
 * an incoherent CS (such as can be found on 830/845). If this flag is
 * not passed, the kernel will endeavour to make sure the batch is
 * coherent with the CS before execution. If this flag is passed,
 * userspace assumes the responsibility for ensuring the same.
 */
#define I915_EXEC_IS_PINNED		(1<<10)

/** Provide a hint to the kernel that the command stream and auxiliary
 * state buffers already holds the correct presumed addresses and so the
 * relocation process may be skipped if no buffers need to be moved in
 * preparation for the execbuffer.
 */
#define I915_EXEC_NO_RELOC		(1<<11)

/** Use the reloc.handle as an index into the exec object array rather
 * than as the per-file handle.
 */
#define I915_EXEC_HANDLE_LUT		(1<<12)

/** Used for switching BSD rings on the platforms with two BSD rings */
#define I915_EXEC_BSD_SHIFT	 (13)
#define I915_EXEC_BSD_MASK	 (3 << I915_EXEC_BSD_SHIFT)
/* default ping-pong mode */
#define I915_EXEC_BSD_DEFAULT	 (0 << I915_EXEC_BSD_SHIFT)
#define I915_EXEC_BSD_RING1	 (1 << I915_EXEC_BSD_SHIFT)
#define I915_EXEC_BSD_RING2	 (2 << I915_EXEC_BSD_SHIFT)

/** Tell the kernel that the batchbuffer is processed by
 *  the resource streamer.
 */
#define I915_EXEC_RESOURCE_STREAMER     (1<<15)

/* Setting I915_EXEC_FENCE_IN implies that lower_32_bits(rsvd2) represent
 * a sync_file fd to wait upon (in a nonblocking manner) prior to executing
 * the batch.
 *
 * Returns -EINVAL if the sync_file fd cannot be found.
 */
#define I915_EXEC_FENCE_IN		(1<<16)

/* Setting I915_EXEC_FENCE_OUT causes the ioctl to return a sync_file fd
 * in the upper_32_bits(rsvd2) upon success. Ownership of the fd is given
 * to the caller, and it should be close() after use. (The fd is a regular
 * file descriptor and will be cleaned up on process termination. It holds
 * a reference to the request, but nothing else.)
 *
 * The sync_file fd can be combined with other sync_file and passed either
 * to execbuf using I915_EXEC_FENCE_IN, to atomic KMS ioctls (so that a flip
 * will only occur after this request completes), or to other devices.
 *
 * Using I915_EXEC_FENCE_OUT requires use of
 * DRM_IOCTL_I915_GEM_EXECBUFFER2_WR ioctl so that the result is written
 * back to userspace. Failure to do so will cause the out-fence to always
 * be reported as zero, and the real fence fd to be leaked.
 */
#define I915_EXEC_FENCE_OUT		(1<<17)

/*
 * Traditionally the execbuf ioctl has only considered the final element in
 * the execobject[] to be the executable batch. Often though, the client
 * will known the batch object prior to construction and being able to place
 * it into the execobject[] array first can simplify the relocation tracking.
 * Setting I915_EXEC_BATCH_FIRST tells execbuf to use element 0 of the
 * execobject[] as the * batch instead (the default is to use the last
 * element).
 */
#define I915_EXEC_BATCH_FIRST		(1<<18)

/* Setting I915_FENCE_ARRAY implies that num_cliprects and cliprects_ptr
 * define an array of i915_gem_exec_fence structures which specify a set of
 * dma fences to wait upon or signal.
 */
#define I915_EXEC_FENCE_ARRAY   (1<<19)

/*
 * Setting I915_EXEC_FENCE_SUBMIT implies that lower_32_bits(rsvd2) represent
 * a sync_file fd to wait upon (in a nonblocking manner) prior to executing
 * the batch.
 *
 * Returns -EINVAL if the sync_file fd cannot be found.
 */
#define I915_EXEC_FENCE_SUBMIT		(1 << 20)

/*
 * Setting I915_EXEC_USE_EXTENSIONS implies that
 * drm_i915_gem_execbuffer2.cliprects_ptr is treated as a pointer to an linked
 * list of i915_user_extension. Each i915_user_extension node is the base of a
 * larger structure. The list of supported structures are listed in the
 * drm_i915_gem_execbuffer_ext enum.
 */
#define I915_EXEC_USE_EXTENSIONS	(1 << 21)
#define __I915_EXEC_UNKNOWN_FLAGS (-(I915_EXEC_USE_EXTENSIONS << 1))

	/** @rsvd1: Context id */
	__u64 rsvd1;

	/**
	 * @rsvd2: in and out sync_file file descriptors.
	 *
	 * When I915_EXEC_FENCE_IN or I915_EXEC_FENCE_SUBMIT flag is set, the
	 * lower 32 bits of this field will have the in sync_file fd (input).
	 *
	 * When I915_EXEC_FENCE_OUT flag is set, the upper 32 bits of this
	 * field will have the out sync_file fd (output).
	 */
	__u64 rsvd2;
};

#define I915_EXEC_CONTEXT_ID_MASK	(0xffffffff)
#define i915_execbuffer2_set_context_id(eb2, context) \
	(eb2).rsvd1 = context & I915_EXEC_CONTEXT_ID_MASK
#define i915_execbuffer2_get_context_id(eb2) \
	((eb2).rsvd1 & I915_EXEC_CONTEXT_ID_MASK)

struct drm_i915_gem_pin {
	/** Handle of the buffer to be pinned. */
	__u32 handle;
	__u32 pad;

	/** alignment required within the aperture */
	__u64 alignment;

	/** Returned GTT offset of the buffer. */
	__u64 offset;
};

struct drm_i915_gem_unpin {
	/** Handle of the buffer to be unpinned. */
	__u32 handle;
	__u32 pad;
};

struct drm_i915_gem_busy {
	/** Handle of the buffer to check for busy */
	__u32 handle;

	/** Return busy status
	 *
	 * A return of 0 implies that the object is idle (after
	 * having flushed any pending activity), and a non-zero return that
	 * the object is still in-flight on the GPU. (The GPU has not yet
	 * signaled completion for all pending requests that reference the
	 * object.) An object is guaranteed to become idle eventually (so
	 * long as no new GPU commands are executed upon it). Due to the
	 * asynchronous nature of the hardware, an object reported
	 * as busy may become idle before the ioctl is completed.
	 *
	 * Furthermore, if the object is busy, which engine is busy is only
	 * provided as a guide and only indirectly by reporting its class
	 * (there may be more than one engine in each class). There are race
	 * conditions which prevent the report of which engines are busy from
	 * being always accurate.  However, the converse is not true. If the
	 * object is idle, the result of the ioctl, that all engines are idle,
	 * is accurate.
	 *
	 * The returned dword is split into two fields to indicate both
	 * the engine classes on which the object is being read, and the
	 * engine class on which it is currently being written (if any).
	 *
	 * The low word (bits 0:15) indicate if the object is being written
	 * to by any engine (there can only be one, as the GEM implicit
	 * synchronisation rules force writes to be serialised). Only the
	 * engine class (offset by 1, I915_ENGINE_CLASS_RENDER is reported as
	 * 1 not 0 etc) for the last write is reported.
	 *
	 * The high word (bits 16:31) are a bitmask of which engines classes
	 * are currently reading from the object. Multiple engines may be
	 * reading from the object simultaneously.
	 *
	 * The value of each engine class is the same as specified in the
	 * I915_CONTEXT_PARAM_ENGINES context parameter and via perf, i.e.
	 * I915_ENGINE_CLASS_RENDER, I915_ENGINE_CLASS_COPY, etc.
	 * Some hardware may have parallel execution engines, e.g. multiple
	 * media engines, which are mapped to the same class identifier and so
	 * are not separately reported for busyness.
	 *
	 * Caveat emptor:
	 * Only the boolean result of this query is reliable; that is whether
	 * the object is idle or busy. The report of which engines are busy
	 * should be only used as a heuristic.
	 */
	__u32 busy;
};

/**
 * struct drm_i915_gem_caching - Set or get the caching for given object
 * handle.
 *
 * Allow userspace to control the GTT caching bits for a given object when the
 * object is later mapped through the ppGTT(or GGTT on older platforms lacking
 * ppGTT support, or if the object is used for scanout). Note that this might
 * require unbinding the object from the GTT first, if its current caching value
 * doesn't match.
 *
 * Note that this all changes on discrete platforms, starting from DG1, the
 * set/get caching is no longer supported, and is now rejected.  Instead the CPU
 * caching attributes(WB vs WC) will become an immutable creation time property
 * for the object, along with the GTT caching level. For now we don't expose any
 * new uAPI for this, instead on DG1 this is all implicit, although this largely
 * shouldn't matter since DG1 is coherent by default(without any way of
 * controlling it).
 *
 * Implicit caching rules, starting from DG1:
 *
 *     - If any of the object placements (see &drm_i915_gem_create_ext_memory_regions)
 *       contain I915_MEMORY_CLASS_DEVICE then the object will be allocated and
 *       mapped as write-combined only.
 *
 *     - Everything else is always allocated and mapped as write-back, with the
 *       guarantee that everything is also coherent with the GPU.
 *
 * Note that this is likely to change in the future again, where we might need
 * more flexibility on future devices, so making this all explicit as part of a
 * new &drm_i915_gem_create_ext extension is probable.
 *
 * Side note: Part of the reason for this is that changing the at-allocation-time CPU
 * caching attributes for the pages might be required(and is expensive) if we
 * need to then CPU map the pages later with different caching attributes. This
 * inconsistent caching behaviour, while supported on x86, is not universally
 * supported on other architectures. So for simplicity we opt for setting
 * everything at creation time, whilst also making it immutable, on discrete
 * platforms.
 */
struct drm_i915_gem_caching {
	/**
	 * @handle: Handle of the buffer to set/get the caching level.
	 */
	__u32 handle;

	/**
	 * @caching: The GTT caching level to apply or possible return value.
	 *
	 * The supported @caching values:
	 *
	 * I915_CACHING_NONE:
	 *
	 * GPU access is not coherent with CPU caches.  Default for machines
	 * without an LLC. This means manual flushing might be needed, if we
	 * want GPU access to be coherent.
	 *
	 * I915_CACHING_CACHED:
	 *
	 * GPU access is coherent with CPU caches and furthermore the data is
	 * cached in last-level caches shared between CPU cores and the GPU GT.
	 *
	 * I915_CACHING_DISPLAY:
	 *
	 * Special GPU caching mode which is coherent with the scanout engines.
	 * Transparently falls back to I915_CACHING_NONE on platforms where no
	 * special cache mode (like write-through or gfdt flushing) is
	 * available. The kernel automatically sets this mode when using a
	 * buffer as a scanout target.  Userspace can manually set this mode to
	 * avoid a costly stall and clflush in the hotpath of drawing the first
	 * frame.
	 */
#define I915_CACHING_NONE		0
#define I915_CACHING_CACHED		1
#define I915_CACHING_DISPLAY		2
	__u32 caching;
};

#define I915_TILING_NONE	0
#define I915_TILING_X		1
#define I915_TILING_Y		2
/*
 * Do not add new tiling types here.  The I915_TILING_* values are for
 * de-tiling fence registers that no longer exist on modern platforms.  Although
 * the hardware may support new types of tiling in general (e.g., Tile4), we
 * do not need to add them to the uapi that is specific to now-defunct ioctls.
 */
#define I915_TILING_LAST	I915_TILING_Y

#define I915_BIT_6_SWIZZLE_NONE		0
#define I915_BIT_6_SWIZZLE_9		1
#define I915_BIT_6_SWIZZLE_9_10		2
#define I915_BIT_6_SWIZZLE_9_11		3
#define I915_BIT_6_SWIZZLE_9_10_11	4
/* Not seen by userland */
#define I915_BIT_6_SWIZZLE_UNKNOWN	5
/* Seen by userland. */
#define I915_BIT_6_SWIZZLE_9_17		6
#define I915_BIT_6_SWIZZLE_9_10_17	7

struct drm_i915_gem_set_tiling {
	/** Handle of the buffer to have its tiling state updated */
	__u32 handle;

	/**
	 * Tiling mode for the object (I915_TILING_NONE, I915_TILING_X,
	 * I915_TILING_Y).
	 *
	 * This value is to be set on request, and will be updated by the
	 * kernel on successful return with the actual chosen tiling layout.
	 *
	 * The tiling mode may be demoted to I915_TILING_NONE when the system
	 * has bit 6 swizzling that can't be managed correctly by GEM.
	 *
	 * Buffer contents become undefined when changing tiling_mode.
	 */
	__u32 tiling_mode;

	/**
	 * Stride in bytes for the object when in I915_TILING_X or
	 * I915_TILING_Y.
	 */
	__u32 stride;

	/**
	 * Returned address bit 6 swizzling required for CPU access through
	 * mmap mapping.
	 */
	__u32 swizzle_mode;
};

struct drm_i915_gem_get_tiling {
	/** Handle of the buffer to get tiling state for. */
	__u32 handle;

	/**
	 * Current tiling mode for the object (I915_TILING_NONE, I915_TILING_X,
	 * I915_TILING_Y).
	 */
	__u32 tiling_mode;

	/**
	 * Returned address bit 6 swizzling required for CPU access through
	 * mmap mapping.
	 */
	__u32 swizzle_mode;

	/**
	 * Returned address bit 6 swizzling required for CPU access through
	 * mmap mapping whilst bound.
	 */
	__u32 phys_swizzle_mode;
};

struct drm_i915_gem_get_aperture {
	/** Total size of the aperture used by i915_gem_execbuffer, in bytes */
	__u64 aper_size;

	/**
	 * Available space in the aperture used by i915_gem_execbuffer, in
	 * bytes
	 */
	__u64 aper_available_size;
};

struct drm_i915_get_pipe_from_crtc_id {
	/** ID of CRTC being requested **/
	__u32 crtc_id;

	/** pipe of requested CRTC **/
	__u32 pipe;
};

#define I915_MADV_WILLNEED 0
#define I915_MADV_DONTNEED 1
#define __I915_MADV_PURGED 2 /* internal state */

struct drm_i915_gem_madvise {
	/** Handle of the buffer to change the backing store advice */
	__u32 handle;

	/* Advice: either the buffer will be needed again in the near future,
	 *         or won't be and could be discarded under memory pressure.
	 */
	__u32 madv;

	/** Whether the backing store still exists. */
	__u32 retained;
};

/* flags */
#define I915_OVERLAY_TYPE_MASK 		0xff
#define I915_OVERLAY_YUV_PLANAR 	0x01
#define I915_OVERLAY_YUV_PACKED 	0x02
#define I915_OVERLAY_RGB		0x03

#define I915_OVERLAY_DEPTH_MASK		0xff00
#define I915_OVERLAY_RGB24		0x1000
#define I915_OVERLAY_RGB16		0x2000
#define I915_OVERLAY_RGB15		0x3000
#define I915_OVERLAY_YUV422		0x0100
#define I915_OVERLAY_YUV411		0x0200
#define I915_OVERLAY_YUV420		0x0300
#define I915_OVERLAY_YUV410		0x0400

#define I915_OVERLAY_SWAP_MASK		0xff0000
#define I915_OVERLAY_NO_SWAP		0x000000
#define I915_OVERLAY_UV_SWAP		0x010000
#define I915_OVERLAY_Y_SWAP		0x020000
#define I915_OVERLAY_Y_AND_UV_SWAP	0x030000

#define I915_OVERLAY_FLAGS_MASK		0xff000000
#define I915_OVERLAY_ENABLE		0x01000000

struct drm_intel_overlay_put_image {
	/* various flags and src format description */
	__u32 flags;
	/* source picture description */
	__u32 bo_handle;
	/* stride values and offsets are in bytes, buffer relative */
	__u16 stride_Y; /* stride for packed formats */
	__u16 stride_UV;
	__u32 offset_Y; /* offset for packet formats */
	__u32 offset_U;
	__u32 offset_V;
	/* in pixels */
	__u16 src_width;
	__u16 src_height;
	/* to compensate the scaling factors for partially covered surfaces */
	__u16 src_scan_width;
	__u16 src_scan_height;
	/* output crtc description */
	__u32 crtc_id;
	__u16 dst_x;
	__u16 dst_y;
	__u16 dst_width;
	__u16 dst_height;
};

/* flags */
#define I915_OVERLAY_UPDATE_ATTRS	(1<<0)
#define I915_OVERLAY_UPDATE_GAMMA	(1<<1)
#define I915_OVERLAY_DISABLE_DEST_COLORKEY	(1<<2)
struct drm_intel_overlay_attrs {
	__u32 flags;
	__u32 color_key;
	__s32 brightness;
	__u32 contrast;
	__u32 saturation;
	__u32 gamma0;
	__u32 gamma1;
	__u32 gamma2;
	__u32 gamma3;
	__u32 gamma4;
	__u32 gamma5;
};

/*
 * Intel sprite handling
 *
 * Color keying works with a min/mask/max tuple.  Both source and destination
 * color keying is allowed.
 *
 * Source keying:
 * Sprite pixels within the min & max values, masked against the color channels
 * specified in the mask field, will be transparent.  All other pixels will
 * be displayed on top of the primary plane.  For RGB surfaces, only the min
 * and mask fields will be used; ranged compares are not allowed.
 *
 * Destination keying:
 * Primary plane pixels that match the min value, masked against the color
 * channels specified in the mask field, will be replaced by corresponding
 * pixels from the sprite plane.
 *
 * Note that source & destination keying are exclusive; only one can be
 * active on a given plane.
 */

#define I915_SET_COLORKEY_NONE		(1<<0) /* Deprecated. Instead set
						* flags==0 to disable colorkeying.
						*/
#define I915_SET_COLORKEY_DESTINATION	(1<<1)
#define I915_SET_COLORKEY_SOURCE	(1<<2)
struct drm_intel_sprite_colorkey {
	__u32 plane_id;
	__u32 min_value;
	__u32 channel_mask;
	__u32 max_value;
	__u32 flags;
};

struct drm_i915_gem_wait {
	/** Handle of BO we shall wait on */
	__u32 bo_handle;
	__u32 flags;
	/** Number of nanoseconds to wait, Returns time remaining. */
	__s64 timeout_ns;
};

struct drm_i915_gem_context_create {
	__u32 ctx_id; /* output: id of new context*/
	__u32 pad;
};

/**
 * struct drm_i915_gem_context_create_ext - Structure for creating contexts.
 */
struct drm_i915_gem_context_create_ext {
	/** @ctx_id: Id of the created context (output) */
	__u32 ctx_id;

	/**
	 * @flags: Supported flags are:
	 *
	 * I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS:
	 *
	 * Extensions may be appended to this structure and driver must check
	 * for those. See @extensions.
	 *
	 * I915_CONTEXT_CREATE_FLAGS_SINGLE_TIMELINE
	 *
	 * Created context will have single timeline.
	 */
	__u32 flags;
#define I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS	(1u << 0)
#define I915_CONTEXT_CREATE_FLAGS_SINGLE_TIMELINE	(1u << 1)
#define I915_CONTEXT_CREATE_FLAGS_UNKNOWN \
	(-(I915_CONTEXT_CREATE_FLAGS_SINGLE_TIMELINE << 1))

	/**
	 * @extensions: Zero-terminated chain of extensions.
	 *
	 * I915_CONTEXT_CREATE_EXT_SETPARAM:
	 * Context parameter to set or query during context creation.
	 * See struct drm_i915_gem_context_create_ext_setparam.
	 *
	 * I915_CONTEXT_CREATE_EXT_CLONE:
	 * This extension has been removed. On the off chance someone somewhere
	 * has attempted to use it, never re-use this extension number.
	 */
	__u64 extensions;
#define I915_CONTEXT_CREATE_EXT_SETPARAM 0
#define I915_CONTEXT_CREATE_EXT_CLONE 1
};

/**
 * struct drm_i915_gem_context_param - Context parameter to set or query.
 */
struct drm_i915_gem_context_param {
	/** @ctx_id: Context id */
	__u32 ctx_id;

	/** @size: Size of the parameter @value */
	__u32 size;

	/** @param: Parameter to set or query */
	__u64 param;
#define I915_CONTEXT_PARAM_BAN_PERIOD	0x1
/* I915_CONTEXT_PARAM_NO_ZEROMAP has been removed.  On the off chance
 * someone somewhere has attempted to use it, never re-use this context
 * param number.
 */
#define I915_CONTEXT_PARAM_NO_ZEROMAP	0x2
#define I915_CONTEXT_PARAM_GTT_SIZE	0x3
#define I915_CONTEXT_PARAM_NO_ERROR_CAPTURE	0x4
#define I915_CONTEXT_PARAM_BANNABLE	0x5
#define I915_CONTEXT_PARAM_PRIORITY	0x6
#define   I915_CONTEXT_MAX_USER_PRIORITY	1023 /* inclusive */
#define   I915_CONTEXT_DEFAULT_PRIORITY		0
#define   I915_CONTEXT_MIN_USER_PRIORITY	-1023 /* inclusive */
	/*
	 * When using the following param, value should be a pointer to
	 * drm_i915_gem_context_param_sseu.
	 */
#define I915_CONTEXT_PARAM_SSEU		0x7

/*
 * Not all clients may want to attempt automatic recover of a context after
 * a hang (for example, some clients may only submit very small incremental
 * batches relying on known logical state of previous batches which will never
 * recover correctly and each attempt will hang), and so would prefer that
 * the context is forever banned instead.
 *
 * If set to false (0), after a reset, subsequent (and in flight) rendering
 * from this context is discarded, and the client will need to create a new
 * context to use instead.
 *
 * If set to true (1), the kernel will automatically attempt to recover the
 * context by skipping the hanging batch and executing the next batch starting
 * from the default context state (discarding the incomplete logical context
 * state lost due to the reset).
 *
 * On creation, all new contexts are marked as recoverable.
 */
#define I915_CONTEXT_PARAM_RECOVERABLE	0x8

	/*
	 * The id of the associated virtual memory address space (ppGTT) of
	 * this context. Can be retrieved and passed to another context
	 * (on the same fd) for both to use the same ppGTT and so share
	 * address layouts, and avoid reloading the page tables on context
	 * switches between themselves.
	 *
	 * See DRM_I915_GEM_VM_CREATE and DRM_I915_GEM_VM_DESTROY.
	 */
#define I915_CONTEXT_PARAM_VM		0x9

/*
 * I915_CONTEXT_PARAM_ENGINES:
 *
 * Bind this context to operate on this subset of available engines. Henceforth,
 * the I915_EXEC_RING selector for DRM_IOCTL_I915_GEM_EXECBUFFER2 operates as
 * an index into this array of engines; I915_EXEC_DEFAULT selecting engine[0]
 * and upwards. Slots 0...N are filled in using the specified (class, instance).
 * Use
 *	engine_class: I915_ENGINE_CLASS_INVALID,
 *	engine_instance: I915_ENGINE_CLASS_INVALID_NONE
 * to specify a gap in the array that can be filled in later, e.g. by a
 * virtual engine used for load balancing.
 *
 * Setting the number of engines bound to the context to 0, by passing a zero
 * sized argument, will revert back to default settings.
 *
 * See struct i915_context_param_engines.
 *
 * Extensions:
 *   i915_context_engines_load_balance (I915_CONTEXT_ENGINES_EXT_LOAD_BALANCE)
 *   i915_context_engines_bond (I915_CONTEXT_ENGINES_EXT_BOND)
 *   i915_context_engines_parallel_submit (I915_CONTEXT_ENGINES_EXT_PARALLEL_SUBMIT)
 */
#define I915_CONTEXT_PARAM_ENGINES	0xa

/*
 * I915_CONTEXT_PARAM_PERSISTENCE:
 *
 * Allow the context and active rendering to survive the process until
 * completion. Persistence allows fire-and-forget clients to queue up a
 * bunch of work, hand the output over to a display server and then quit.
 * If the context is marked as not persistent, upon closing (either via
 * an explicit DRM_I915_GEM_CONTEXT_DESTROY or implicitly from file closure
 * or process termination), the context and any outstanding requests will be
 * cancelled (and exported fences for cancelled requests marked as -EIO).
 *
 * By default, new contexts allow persistence.
 */
#define I915_CONTEXT_PARAM_PERSISTENCE	0xb

/* This API has been removed.  On the off chance someone somewhere has
 * attempted to use it, never re-use this context param number.
 */
#define I915_CONTEXT_PARAM_RINGSIZE	0xc

/*
 * I915_CONTEXT_PARAM_PROTECTED_CONTENT:
 *
 * Mark that the context makes use of protected content, which will result
 * in the context being invalidated when the protected content session is.
 * Given that the protected content session is killed on suspend, the device
 * is kept awake for the lifetime of a protected context, so the user should
 * make sure to dispose of them once done.
 * This flag can only be set at context creation time and, when set to true,
 * must be preceded by an explicit setting of I915_CONTEXT_PARAM_RECOVERABLE
 * to false. This flag can't be set to true in conjunction with setting the
 * I915_CONTEXT_PARAM_BANNABLE flag to false. Creation example:
 *
 * .. code-block:: C
 *
 *	struct drm_i915_gem_context_create_ext_setparam p_protected = {
 *		.base = {
 *			.name = I915_CONTEXT_CREATE_EXT_SETPARAM,
 *		},
 *		.param = {
 *			.param = I915_CONTEXT_PARAM_PROTECTED_CONTENT,
 *			.value = 1,
 *		}
 *	};
 *	struct drm_i915_gem_context_create_ext_setparam p_norecover = {
 *		.base = {
 *			.name = I915_CONTEXT_CREATE_EXT_SETPARAM,
 *			.next_extension = to_user_pointer(&p_protected),
 *		},
 *		.param = {
 *			.param = I915_CONTEXT_PARAM_RECOVERABLE,
 *			.value = 0,
 *		}
 *	};
 *	struct drm_i915_gem_context_create_ext create = {
 *		.flags = I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS,
 *		.extensions = to_user_pointer(&p_norecover);
 *	};
 *
 *	ctx_id = gem_context_create_ext(drm_fd, &create);
 *
 * In addition to the normal failure cases, setting this flag during context
 * creation can result in the following errors:
 *
 * -ENODEV: feature not available
 * -EPERM: trying to mark a recoverable or not bannable context as protected
 * -ENXIO: A dependency such as a component driver or firmware is not yet
 *         loaded so user space may need to attempt again. Depending on the
 *         device, this error may be reported if protected context creation is
 *         attempted very early after kernel start because the internal timeout
 *         waiting for such dependencies is not guaranteed to be larger than
 *         required (numbers differ depending on system and kernel config):
 *            - ADL/RPL: dependencies may take up to 3 seconds from kernel start
 *                       while context creation internal timeout is 250 milisecs
 *            - MTL: dependencies may take up to 8 seconds from kernel start
 *                   while context creation internal timeout is 250 milisecs
 *         NOTE: such dependencies happen once, so a subsequent call to create a
 *         protected context after a prior successful call will not experience
 *         such timeouts and will not return -ENXIO (unless the driver is reloaded,
 *         or, depending on the device, resumes from a suspended state).
 * -EIO: The firmware did not succeed in creating the protected context.
 */
#define I915_CONTEXT_PARAM_PROTECTED_CONTENT    0xd
/* Must be kept compact -- no holes and well documented */

	/** @value: Context parameter value to be set or queried */
	__u64 value;
};

/*
 * Context SSEU programming
 *
 * It may be necessary for either functional or performance reason to configure
 * a context to run with a reduced number of SSEU (where SSEU stands for Slice/
 * Sub-slice/EU).
 *
 * This is done by configuring SSEU configuration using the below
 * @struct drm_i915_gem_context_param_sseu for every supported engine which
 * userspace intends to use.
 *
 * Not all GPUs or engines support this functionality in which case an error
 * code -ENODEV will be returned.
 *
 * Also, flexibility of possible SSEU configuration permutations varies between
 * GPU generations and software imposed limitations. Requesting such a
 * combination will return an error code of -EINVAL.
 *
 * NOTE: When perf/OA is active the context's SSEU configuration is ignored in
 * favour of a single global setting.
 */
struct drm_i915_gem_context_param_sseu {
	/*
	 * Engine class & instance to be configured or queried.
	 */
	struct i915_engine_class_instance engine;

	/*
	 * Unknown flags must be cleared to zero.
	 */
	__u32 flags;
#define I915_CONTEXT_SSEU_FLAG_ENGINE_INDEX (1u << 0)

	/*
	 * Mask of slices to enable for the context. Valid values are a subset
	 * of the bitmask value returned for I915_PARAM_SLICE_MASK.
	 */
	__u64 slice_mask;

	/*
	 * Mask of subslices to enable for the context. Valid values are a
	 * subset of the bitmask value return by I915_PARAM_SUBSLICE_MASK.
	 */
	__u64 subslice_mask;

	/*
	 * Minimum/Maximum number of EUs to enable per subslice for the
	 * context. min_eus_per_subslice must be inferior or equal to
	 * max_eus_per_subslice.
	 */
	__u16 min_eus_per_subslice;
	__u16 max_eus_per_subslice;

	/*
	 * Unused for now. Must be cleared to zero.
	 */
	__u32 rsvd;
};

/**
 * DOC: Virtual Engine uAPI
 *
 * Virtual engine is a concept where userspace is able to configure a set of
 * physical engines, submit a batch buffer, and let the driver execute it on any
 * engine from the set as it sees fit.
 *
 * This is primarily useful on parts which have multiple instances of a same
 * class engine, like for example GT3+ Skylake parts with their two VCS engines.
 *
 * For instance userspace can enumerate all engines of a certain class using the
 * previously described `Engine Discovery uAPI`_. After that userspace can
 * create a GEM context with a placeholder slot for the virtual engine (using
 * `I915_ENGINE_CLASS_INVALID` and `I915_ENGINE_CLASS_INVALID_NONE` for class
 * and instance respectively) and finally using the
 * `I915_CONTEXT_ENGINES_EXT_LOAD_BALANCE` extension place a virtual engine in
 * the same reserved slot.
 *
 * Example of creating a virtual engine and submitting a batch buffer to it:
 *
 * .. code-block:: C
 *
 * 	I915_DEFINE_CONTEXT_ENGINES_LOAD_BALANCE(virtual, 2) = {
 * 		.base.name = I915_CONTEXT_ENGINES_EXT_LOAD_BALANCE,
 * 		.engine_index = 0, // Place this virtual engine into engine map slot 0
 * 		.num_siblings = 2,
 * 		.engines = { { I915_ENGINE_CLASS_VIDEO, 0 },
 * 			     { I915_ENGINE_CLASS_VIDEO, 1 }, },
 * 	};
 * 	I915_DEFINE_CONTEXT_PARAM_ENGINES(engines, 1) = {
 * 		.engines = { { I915_ENGINE_CLASS_INVALID,
 * 			       I915_ENGINE_CLASS_INVALID_NONE } },
 * 		.extensions = to_user_pointer(&virtual), // Chains after load_balance extension
 * 	};
 * 	struct drm_i915_gem_context_create_ext_setparam p_engines = {
 * 		.base = {
 * 			.name = I915_CONTEXT_CREATE_EXT_SETPARAM,
 * 		},
 * 		.param = {
 * 			.param = I915_CONTEXT_PARAM_ENGINES,
 * 			.value = to_user_pointer(&engines),
 * 			.size = sizeof(engines),
 * 		},
 * 	};
 * 	struct drm_i915_gem_context_create_ext create = {
 * 		.flags = I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS,
 * 		.extensions = to_user_pointer(&p_engines);
 * 	};
 *
 * 	ctx_id = gem_context_create_ext(drm_fd, &create);
 *
 * 	// Now we have created a GEM context with its engine map containing a
 * 	// single virtual engine. Submissions to this slot can go either to
 * 	// vcs0 or vcs1, depending on the load balancing algorithm used inside
 * 	// the driver. The load balancing is dynamic from one batch buffer to
 * 	// another and transparent to userspace.
 *
 * 	...
 * 	execbuf.rsvd1 = ctx_id;
 * 	execbuf.flags = 0; // Submits to index 0 which is the virtual engine
 * 	gem_execbuf(drm_fd, &execbuf);
 */

/*
 * i915_context_engines_load_balance:
 *
 * Enable load balancing across this set of engines.
 *
 * Into the I915_EXEC_DEFAULT slot [0], a virtual engine is created that when
 * used will proxy the execbuffer request onto one of the set of engines
 * in such a way as to distribute the load evenly across the set.
 *
 * The set of engines must be compatible (e.g. the same HW class) as they
 * will share the same logical GPU context and ring.
 *
 * To intermix rendering with the virtual engine and direct rendering onto
 * the backing engines (bypassing the load balancing proxy), the context must
 * be defined to use a single timeline for all engines.
 */
struct i915_context_engines_load_balance {
	struct i915_user_extension base;

	__u16 engine_index;
	__u16 num_siblings;
	__u32 flags; /* all undefined flags must be zero */

	__u64 mbz64; /* reserved for future use; must be zero */

	struct i915_engine_class_instance engines[];
} __attribute__((packed));

#define I915_DEFINE_CONTEXT_ENGINES_LOAD_BALANCE(name__, N__) struct { \
	struct i915_user_extension base; \
	__u16 engine_index; \
	__u16 num_siblings; \
	__u32 flags; \
	__u64 mbz64; \
	struct i915_engine_class_instance engines[N__]; \
} __attribute__((packed)) name__

/*
 * i915_context_engines_bond:
 *
 * Constructed bonded pairs for execution within a virtual engine.
 *
 * All engines are equal, but some are more equal than others. Given
 * the distribution of resources in the HW, it may be preferable to run
 * a request on a given subset of engines in parallel to a request on a
 * specific engine. We enable this selection of engines within a virtual
 * engine by specifying bonding pairs, for any given master engine we will
 * only execute on one of the corresponding siblings within the virtual engine.
 *
 * To execute a request in parallel on the master engine and a sibling requires
 * coordination with a I915_EXEC_FENCE_SUBMIT.
 */
struct i915_context_engines_bond {
	struct i915_user_extension base;

	struct i915_engine_class_instance master;

	__u16 virtual_index; /* index of virtual engine in ctx->engines[] */
	__u16 num_bonds;

	__u64 flags; /* all undefined flags must be zero */
	__u64 mbz64[4]; /* reserved for future use; must be zero */

	struct i915_engine_class_instance engines[];
} __attribute__((packed));

#define I915_DEFINE_CONTEXT_ENGINES_BOND(name__, N__) struct { \
	struct i915_user_extension base; \
	struct i915_engine_class_instance master; \
	__u16 virtual_index; \
	__u16 num_bonds; \
	__u64 flags; \
	__u64 mbz64[4]; \
	struct i915_engine_class_instance engines[N__]; \
} __attribute__((packed)) name__

/**
 * struct i915_context_engines_parallel_submit - Configure engine for
 * parallel submission.
 *
 * Setup a slot in the context engine map to allow multiple BBs to be submitted
 * in a single execbuf IOCTL. Those BBs will then be scheduled to run on the GPU
 * in parallel. Multiple hardware contexts are created internally in the i915 to
 * run these BBs. Once a slot is configured for N BBs only N BBs can be
 * submitted in each execbuf IOCTL and this is implicit behavior e.g. The user
 * doesn't tell the execbuf IOCTL there are N BBs, the execbuf IOCTL knows how
 * many BBs there are based on the slot's configuration. The N BBs are the last
 * N buffer objects or first N if I915_EXEC_BATCH_FIRST is set.
 *
 * The default placement behavior is to create implicit bonds between each
 * context if each context maps to more than 1 physical engine (e.g. context is
 * a virtual engine). Also we only allow contexts of same engine class and these
 * contexts must be in logically contiguous order. Examples of the placement
 * behavior are described below. Lastly, the default is to not allow BBs to be
 * preempted mid-batch. Rather insert coordinated preemption points on all
 * hardware contexts between each set of BBs. Flags could be added in the future
 * to change both of these default behaviors.
 *
 * Returns -EINVAL if hardware context placement configuration is invalid or if
 * the placement configuration isn't supported on the platform / submission
 * interface.
 * Returns -ENODEV if extension isn't supported on the platform / submission
 * interface.
 *
 * .. code-block:: none
 *
 *	Examples syntax:
 *	CS[X] = generic engine of same class, logical instance X
 *	INVALID = I915_ENGINE_CLASS_INVALID, I915_ENGINE_CLASS_INVALID_NONE
 *
 *	Example 1 pseudo code:
 *	set_engines(INVALID)
 *	set_parallel(engine_index=0, width=2, num_siblings=1,
 *		     engines=CS[0],CS[1])
 *
 *	Results in the following valid placement:
 *	CS[0], CS[1]
 *
 *	Example 2 pseudo code:
 *	set_engines(INVALID)
 *	set_parallel(engine_index=0, width=2, num_siblings=2,
 *		     engines=CS[0],CS[2],CS[1],CS[3])
 *
 *	Results in the following valid placements:
 *	CS[0], CS[1]
 *	CS[2], CS[3]
 *
 *	This can be thought of as two virtual engines, each containing two
 *	engines thereby making a 2D array. However, there are bonds tying the
 *	entries together and placing restrictions on how they can be scheduled.
 *	Specifically, the scheduler can choose only vertical columns from the 2D
 *	array. That is, CS[0] is bonded to CS[1] and CS[2] to CS[3]. So if the
 *	scheduler wants to submit to CS[0], it must also choose CS[1] and vice
 *	versa. Same for CS[2] requires also using CS[3].
 *	VE[0] = CS[0], CS[2]
 *	VE[1] = CS[1], CS[3]
 *
 *	Example 3 pseudo code:
 *	set_engines(INVALID)
 *	set_parallel(engine_index=0, width=2, num_siblings=2,
 *		     engines=CS[0],CS[1],CS[1],CS[3])
 *
 *	Results in the following valid and invalid placements:
 *	CS[0], CS[1]
 *	CS[1], CS[3] - Not logically contiguous, return -EINVAL
 */
struct i915_context_engines_parallel_submit {
	/**
	 * @base: base user extension.
	 */
	struct i915_user_extension base;

	/**
	 * @engine_index: slot for parallel engine
	 */
	__u16 engine_index;

	/**
	 * @width: number of contexts per parallel engine or in other words the
	 * number of batches in each submission
	 */
	__u16 width;

	/**
	 * @num_siblings: number of siblings per context or in other words the
	 * number of possible placements for each submission
	 */
	__u16 num_siblings;

	/**
	 * @mbz16: reserved for future use; must be zero
	 */
	__u16 mbz16;

	/**
	 * @flags: all undefined flags must be zero, currently not defined flags
	 */
	__u64 flags;

	/**
	 * @mbz64: reserved for future use; must be zero
	 */
	__u64 mbz64[3];

	/**
	 * @engines: 2-d array of engine instances to configure parallel engine
	 *
	 * length = width (i) * num_siblings (j)
	 * index = j + i * num_siblings
	 */
	struct i915_engine_class_instance engines[];

} __packed;

#define I915_DEFINE_CONTEXT_ENGINES_PARALLEL_SUBMIT(name__, N__) struct { \
	struct i915_user_extension base; \
	__u16 engine_index; \
	__u16 width; \
	__u16 num_siblings; \
	__u16 mbz16; \
	__u64 flags; \
	__u64 mbz64[3]; \
	struct i915_engine_class_instance engines[N__]; \
} __attribute__((packed)) name__

/**
 * DOC: Context Engine Map uAPI
 *
 * Context engine map is a new way of addressing engines when submitting batch-
 * buffers, replacing the existing way of using identifiers like `I915_EXEC_BLT`
 * inside the flags field of `struct drm_i915_gem_execbuffer2`.
 *
 * To use it created GEM contexts need to be configured with a list of engines
 * the user is intending to submit to. This is accomplished using the
 * `I915_CONTEXT_PARAM_ENGINES` parameter and `struct
 * i915_context_param_engines`.
 *
 * For such contexts the `I915_EXEC_RING_MASK` field becomes an index into the
 * configured map.
 *
 * Example of creating such context and submitting against it:
 *
 * .. code-block:: C
 *
 * 	I915_DEFINE_CONTEXT_PARAM_ENGINES(engines, 2) = {
 * 		.engines = { { I915_ENGINE_CLASS_RENDER, 0 },
 * 			     { I915_ENGINE_CLASS_COPY, 0 } }
 * 	};
 * 	struct drm_i915_gem_context_create_ext_setparam p_engines = {
 * 		.base = {
 * 			.name = I915_CONTEXT_CREATE_EXT_SETPARAM,
 * 		},
 * 		.param = {
 * 			.param = I915_CONTEXT_PARAM_ENGINES,
 * 			.value = to_user_pointer(&engines),
 * 			.size = sizeof(engines),
 * 		},
 * 	};
 * 	struct drm_i915_gem_context_create_ext create = {
 * 		.flags = I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS,
 * 		.extensions = to_user_pointer(&p_engines);
 * 	};
 *
 * 	ctx_id = gem_context_create_ext(drm_fd, &create);
 *
 * 	// We have now created a GEM context with two engines in the map:
 * 	// Index 0 points to rcs0 while index 1 points to bcs0. Other engines
 * 	// will not be accessible from this context.
 *
 * 	...
 * 	execbuf.rsvd1 = ctx_id;
 * 	execbuf.flags = 0; // Submits to index 0, which is rcs0 for this context
 * 	gem_execbuf(drm_fd, &execbuf);
 *
 * 	...
 * 	execbuf.rsvd1 = ctx_id;
 * 	execbuf.flags = 1; // Submits to index 0, which is bcs0 for this context
 * 	gem_execbuf(drm_fd, &execbuf);
 */

struct i915_context_param_engines {
	__u64 extensions; /* linked chain of extension blocks, 0 terminates */
#define I915_CONTEXT_ENGINES_EXT_LOAD_BALANCE 0 /* see i915_context_engines_load_balance */
#define I915_CONTEXT_ENGINES_EXT_BOND 1 /* see i915_context_engines_bond */
#define I915_CONTEXT_ENGINES_EXT_PARALLEL_SUBMIT 2 /* see i915_context_engines_parallel_submit */
	struct i915_engine_class_instance engines[];
} __attribute__((packed));

#define I915_DEFINE_CONTEXT_PARAM_ENGINES(name__, N__) struct { \
	__u64 extensions; \
	struct i915_engine_class_instance engines[N__]; \
} __attribute__((packed)) name__

/**
 * struct drm_i915_gem_context_create_ext_setparam - Context parameter
 * to set or query during context creation.
 */
struct drm_i915_gem_context_create_ext_setparam {
	/** @base: Extension link. See struct i915_user_extension. */
	struct i915_user_extension base;

	/**
	 * @param: Context parameter to set or query.
	 * See struct drm_i915_gem_context_param.
	 */
	struct drm_i915_gem_context_param param;
};

struct drm_i915_gem_context_destroy {
	__u32 ctx_id;
	__u32 pad;
};

/**
 * struct drm_i915_gem_vm_control - Structure to create or destroy VM.
 *
 * DRM_I915_GEM_VM_CREATE -
 *
 * Create a new virtual memory address space (ppGTT) for use within a context
 * on the same file. Extensions can be provided to configure exactly how the
 * address space is setup upon creation.
 *
 * The id of new VM (bound to the fd) for use with I915_CONTEXT_PARAM_VM is
 * returned in the outparam @id.
 *
 * An extension chain maybe provided, starting with @extensions, and terminated
 * by the @next_extension being 0. Currently, no extensions are defined.
 *
 * DRM_I915_GEM_VM_DESTROY -
 *
 * Destroys a previously created VM id, specified in @vm_id.
 *
 * No extensions or flags are allowed currently, and so must be zero.
 */
struct drm_i915_gem_vm_control {
	/** @extensions: Zero-terminated chain of extensions. */
	__u64 extensions;

	/** @flags: reserved for future usage, currently MBZ */
	__u32 flags;

	/** @vm_id: Id of the VM created or to be destroyed */
	__u32 vm_id;
};

struct drm_i915_reg_read {
	/*
	 * Register offset.
	 * For 64bit wide registers where the upper 32bits don't immediately
	 * follow the lower 32bits, the offset of the lower 32bits must
	 * be specified
	 */
	__u64 offset;
#define I915_REG_READ_8B_WA (1ul << 0)

	__u64 val; /* Return value */
};

/* Known registers:
 *
 * Render engine timestamp - 0x2358 + 64bit - gen7+
 * - Note this register returns an invalid value if using the default
 *   single instruction 8byte read, in order to workaround that pass
 *   flag I915_REG_READ_8B_WA in offset field.
 *
 */

struct drm_i915_reset_stats {
	__u32 ctx_id;
	__u32 flags;

	/* All resets since boot/module reload, for all contexts */
	__u32 reset_count;

	/* Number of batches lost when active in GPU, for this context */
	__u32 batch_active;

	/* Number of batches lost pending for execution, for this context */
	__u32 batch_pending;

	__u32 pad;
};

/**
 * struct drm_i915_gem_userptr - Create GEM object from user allocated memory.
 *
 * Userptr objects have several restrictions on what ioctls can be used with the
 * object handle.
 */
struct drm_i915_gem_userptr {
	/**
	 * @user_ptr: The pointer to the allocated memory.
	 *
	 * Needs to be aligned to PAGE_SIZE.
	 */
	__u64 user_ptr;

	/**
	 * @user_size:
	 *
	 * The size in bytes for the allocated memory. This will also become the
	 * object size.
	 *
	 * Needs to be aligned to PAGE_SIZE, and should be at least PAGE_SIZE,
	 * or larger.
	 */
	__u64 user_size;

	/**
	 * @flags:
	 *
	 * Supported flags:
	 *
	 * I915_USERPTR_READ_ONLY:
	 *
	 * Mark the object as readonly, this also means GPU access can only be
	 * readonly. This is only supported on HW which supports readonly access
	 * through the GTT. If the HW can't support readonly access, an error is
	 * returned.
	 *
	 * I915_USERPTR_PROBE:
	 *
	 * Probe the provided @user_ptr range and validate that the @user_ptr is
	 * indeed pointing to normal memory and that the range is also valid.
	 * For example if some garbage address is given to the kernel, then this
	 * should complain.
	 *
	 * Returns -EFAULT if the probe failed.
	 *
	 * Note that this doesn't populate the backing pages, and also doesn't
	 * guarantee that the object will remain valid when the object is
	 * eventually used.
	 *
	 * The kernel supports this feature if I915_PARAM_HAS_USERPTR_PROBE
	 * returns a non-zero value.
	 *
	 * I915_USERPTR_UNSYNCHRONIZED:
	 *
	 * NOT USED. Setting this flag will result in an error.
	 */
	__u32 flags;
#define I915_USERPTR_READ_ONLY 0x1
#define I915_USERPTR_PROBE 0x2
#define I915_USERPTR_UNSYNCHRONIZED 0x80000000
	/**
	 * @handle: Returned handle for the object.
	 *
	 * Object handles are nonzero.
	 */
	__u32 handle;
};

enum drm_i915_oa_format {
	I915_OA_FORMAT_A13 = 1,	    /* HSW only */
	I915_OA_FORMAT_A29,	    /* HSW only */
	I915_OA_FORMAT_A13_B8_C8,   /* HSW only */
	I915_OA_FORMAT_B4_C8,	    /* HSW only */
	I915_OA_FORMAT_A45_B8_C8,   /* HSW only */
	I915_OA_FORMAT_B4_C8_A16,   /* HSW only */
	I915_OA_FORMAT_C4_B8,	    /* HSW+ */

	/* Gen8+ */
	I915_OA_FORMAT_A12,
	I915_OA_FORMAT_A12_B8_C8,
	I915_OA_FORMAT_A32u40_A4u32_B8_C8,

	/* DG2 */
	I915_OAR_FORMAT_A32u40_A4u32_B8_C8,
	I915_OA_FORMAT_A24u40_A14u32_B8_C8,

	/* MTL OAM */
	I915_OAM_FORMAT_MPEC8u64_B8_C8,
	I915_OAM_FORMAT_MPEC8u32_B8_C8,

	I915_OA_FORMAT_MAX	    /* non-ABI */
};

enum drm_i915_perf_property_id {
	/**
	 * Open the stream for a specific context handle (as used with
	 * execbuffer2). A stream opened for a specific context this way
	 * won't typically require root privileges.
	 *
	 * This property is available in perf revision 1.
	 */
	DRM_I915_PERF_PROP_CTX_HANDLE = 1,

	/**
	 * A value of 1 requests the inclusion of raw OA unit reports as
	 * part of stream samples.
	 *
	 * This property is available in perf revision 1.
	 */
	DRM_I915_PERF_PROP_SAMPLE_OA,

	/**
	 * The value specifies which set of OA unit metrics should be
	 * configured, defining the contents of any OA unit reports.
	 *
	 * This property is available in perf revision 1.
	 */
	DRM_I915_PERF_PROP_OA_METRICS_SET,

	/**
	 * The value specifies the size and layout of OA unit reports.
	 *
	 * This property is available in perf revision 1.
	 */
	DRM_I915_PERF_PROP_OA_FORMAT,

	/**
	 * Specifying this property implicitly requests periodic OA unit
	 * sampling and (at least on Haswell) the sampling frequency is derived
	 * from this exponent as follows:
	 *
	 *   80ns * 2^(period_exponent + 1)
	 *
	 * This property is available in perf revision 1.
	 */
	DRM_I915_PERF_PROP_OA_EXPONENT,

	/**
	 * Specifying this property is only valid when specify a context to
	 * filter with DRM_I915_PERF_PROP_CTX_HANDLE. Specifying this property
	 * will hold preemption of the particular context we want to gather
	 * performance data about. The execbuf2 submissions must include a
	 * drm_i915_gem_execbuffer_ext_perf parameter for this to apply.
	 *
	 * This property is available in perf revision 3.
	 */
	DRM_I915_PERF_PROP_HOLD_PREEMPTION,

	/**
	 * Specifying this pins all contexts to the specified SSEU power
	 * configuration for the duration of the recording.
	 *
	 * This parameter's value is a pointer to a struct
	 * drm_i915_gem_context_param_sseu.
	 *
	 * This property is available in perf revision 4.
	 */
	DRM_I915_PERF_PROP_GLOBAL_SSEU,

	/**
	 * This optional parameter specifies the timer interval in nanoseconds
	 * at which the i915 driver will check the OA buffer for available data.
	 * Minimum allowed value is 100 microseconds. A default value is used by
	 * the driver if this parameter is not specified. Note that larger timer
	 * values will reduce cpu consumption during OA perf captures. However,
	 * excessively large values would potentially result in OA buffer
	 * overwrites as captures reach end of the OA buffer.
	 *
	 * This property is available in perf revision 5.
	 */
	DRM_I915_PERF_PROP_POLL_OA_PERIOD,

	/**
	 * Multiple engines may be mapped to the same OA unit. The OA unit is
	 * identified by class:instance of any engine mapped to it.
	 *
	 * This parameter specifies the engine class and must be passed along
	 * with DRM_I915_PERF_PROP_OA_ENGINE_INSTANCE.
	 *
	 * This property is available in perf revision 6.
	 */
	DRM_I915_PERF_PROP_OA_ENGINE_CLASS,

	/**
	 * This parameter specifies the engine instance and must be passed along
	 * with DRM_I915_PERF_PROP_OA_ENGINE_CLASS.
	 *
	 * This property is available in perf revision 6.
	 */
	DRM_I915_PERF_PROP_OA_ENGINE_INSTANCE,

	DRM_I915_PERF_PROP_MAX /* non-ABI */
};

struct drm_i915_perf_open_param {
	__u32 flags;
#define I915_PERF_FLAG_FD_CLOEXEC	(1<<0)
#define I915_PERF_FLAG_FD_NONBLOCK	(1<<1)
#define I915_PERF_FLAG_DISABLED		(1<<2)

	/** The number of u64 (id, value) pairs */
	__u32 num_properties;

	/**
	 * Pointer to array of u64 (id, value) pairs configuring the stream
	 * to open.
	 */
	__u64 properties_ptr;
};

/*
 * Enable data capture for a stream that was either opened in a disabled state
 * via I915_PERF_FLAG_DISABLED or was later disabled via
 * I915_PERF_IOCTL_DISABLE.
 *
 * It is intended to be cheaper to disable and enable a stream than it may be
 * to close and re-open a stream with the same configuration.
 *
 * It's undefined whether any pending data for the stream will be lost.
 *
 * This ioctl is available in perf revision 1.
 */
#define I915_PERF_IOCTL_ENABLE	_IO('i', 0x0)

/*
 * Disable data capture for a stream.
 *
 * It is an error to try and read a stream that is disabled.
 *
 * This ioctl is available in perf revision 1.
 */
#define I915_PERF_IOCTL_DISABLE	_IO('i', 0x1)

/*
 * Change metrics_set captured by a stream.
 *
 * If the stream is bound to a specific context, the configuration change
 * will performed inline with that context such that it takes effect before
 * the next execbuf submission.
 *
 * Returns the previously bound metrics set id, or a negative error code.
 *
 * This ioctl is available in perf revision 2.
 */
#define I915_PERF_IOCTL_CONFIG	_IO('i', 0x2)

/*
 * Common to all i915 perf records
 */
struct drm_i915_perf_record_header {
	__u32 type;
	__u16 pad;
	__u16 size;
};

enum drm_i915_perf_record_type {

	/**
	 * Samples are the work horse record type whose contents are extensible
	 * and defined when opening an i915 perf stream based on the given
	 * properties.
	 *
	 * Boolean properties following the naming convention
	 * DRM_I915_PERF_SAMPLE_xyz_PROP request the inclusion of 'xyz' data in
	 * every sample.
	 *
	 * The order of these sample properties given by userspace has no
	 * affect on the ordering of data within a sample. The order is
	 * documented here.
	 *
	 * struct {
	 *     struct drm_i915_perf_record_header header;
	 *
	 *     { u32 oa_report[]; } && DRM_I915_PERF_PROP_SAMPLE_OA
	 * };
	 */
	DRM_I915_PERF_RECORD_SAMPLE = 1,

	/*
	 * Indicates that one or more OA reports were not written by the
	 * hardware. This can happen for example if an MI_REPORT_PERF_COUNT
	 * command collides with periodic sampling - which would be more likely
	 * at higher sampling frequencies.
	 */
	DRM_I915_PERF_RECORD_OA_REPORT_LOST = 2,

	/**
	 * An error occurred that resulted in all pending OA reports being lost.
	 */
	DRM_I915_PERF_RECORD_OA_BUFFER_LOST = 3,

	DRM_I915_PERF_RECORD_MAX /* non-ABI */
};

/**
 * struct drm_i915_perf_oa_config
 *
 * Structure to upload perf dynamic configuration into the kernel.
 */
struct drm_i915_perf_oa_config {
	/**
	 * @uuid:
	 *
	 * String formatted like "%\08x-%\04x-%\04x-%\04x-%\012x"
	 */
	char uuid[36];

	/**
	 * @n_mux_regs:
	 *
	 * Number of mux regs in &mux_regs_ptr.
	 */
	__u32 n_mux_regs;

	/**
	 * @n_boolean_regs:
	 *
	 * Number of boolean regs in &boolean_regs_ptr.
	 */
	__u32 n_boolean_regs;

	/**
	 * @n_flex_regs:
	 *
	 * Number of flex regs in &flex_regs_ptr.
	 */
	__u32 n_flex_regs;

	/**
	 * @mux_regs_ptr:
	 *
	 * Pointer to tuples of u32 values (register address, value) for mux
	 * registers.  Expected length of buffer is (2 * sizeof(u32) *
	 * &n_mux_regs).
	 */
	__u64 mux_regs_ptr;

	/**
	 * @boolean_regs_ptr:
	 *
	 * Pointer to tuples of u32 values (register address, value) for mux
	 * registers.  Expected length of buffer is (2 * sizeof(u32) *
	 * &n_boolean_regs).
	 */
	__u64 boolean_regs_ptr;

	/**
	 * @flex_regs_ptr:
	 *
	 * Pointer to tuples of u32 values (register address, value) for mux
	 * registers.  Expected length of buffer is (2 * sizeof(u32) *
	 * &n_flex_regs).
	 */
	__u64 flex_regs_ptr;
};

/**
 * struct drm_i915_query_item - An individual query for the kernel to process.
 *
 * The behaviour is determined by the @query_id. Note that exactly what
 * @data_ptr is also depends on the specific @query_id.
 */
struct drm_i915_query_item {
	/**
	 * @query_id:
	 *
	 * The id for this query.  Currently accepted query IDs are:
	 *  - %DRM_I915_QUERY_TOPOLOGY_INFO (see struct drm_i915_query_topology_info)
	 *  - %DRM_I915_QUERY_ENGINE_INFO (see struct drm_i915_engine_info)
	 *  - %DRM_I915_QUERY_PERF_CONFIG (see struct drm_i915_query_perf_config)
	 *  - %DRM_I915_QUERY_MEMORY_REGIONS (see struct drm_i915_query_memory_regions)
	 *  - %DRM_I915_QUERY_HWCONFIG_BLOB (see `GuC HWCONFIG blob uAPI`)
	 *  - %DRM_I915_QUERY_GEOMETRY_SUBSLICES (see struct drm_i915_query_topology_info)
	 *  - %DRM_I915_QUERY_GUC_SUBMISSION_VERSION (see struct drm_i915_query_guc_submission_version)
	 */
	__u64 query_id;
#define DRM_I915_QUERY_TOPOLOGY_INFO		1
#define DRM_I915_QUERY_ENGINE_INFO		2
#define DRM_I915_QUERY_PERF_CONFIG		3
#define DRM_I915_QUERY_MEMORY_REGIONS		4
#define DRM_I915_QUERY_HWCONFIG_BLOB		5
#define DRM_I915_QUERY_GEOMETRY_SUBSLICES	6
#define DRM_I915_QUERY_GUC_SUBMISSION_VERSION	7
/* Must be kept compact -- no holes and well documented */

	/**
	 * @length:
	 *
	 * When set to zero by userspace, this is filled with the size of the
	 * data to be written at the @data_ptr pointer. The kernel sets this
	 * value to a negative value to signal an error on a particular query
	 * item.
	 */
	__s32 length;

	/**
	 * @flags:
	 *
	 * When &query_id == %DRM_I915_QUERY_TOPOLOGY_INFO, must be 0.
	 *
	 * When &query_id == %DRM_I915_QUERY_PERF_CONFIG, must be one of the
	 * following:
	 *
	 *	- %DRM_I915_QUERY_PERF_CONFIG_LIST
	 *      - %DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID
	 *      - %DRM_I915_QUERY_PERF_CONFIG_FOR_UUID
	 *
	 * When &query_id == %DRM_I915_QUERY_GEOMETRY_SUBSLICES must contain
	 * a struct i915_engine_class_instance that references a render engine.
	 */
	__u32 flags;
#define DRM_I915_QUERY_PERF_CONFIG_LIST          1
#define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID 2
#define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_ID   3

	/**
	 * @data_ptr:
	 *
	 * Data will be written at the location pointed by @data_ptr when the
	 * value of @length matches the length of the data to be written by the
	 * kernel.
	 */
	__u64 data_ptr;
};

/**
 * struct drm_i915_query - Supply an array of struct drm_i915_query_item for the
 * kernel to fill out.
 *
 * Note that this is generally a two step process for each struct
 * drm_i915_query_item in the array:
 *
 * 1. Call the DRM_IOCTL_I915_QUERY, giving it our array of struct
 *    drm_i915_query_item, with &drm_i915_query_item.length set to zero. The
 *    kernel will then fill in the size, in bytes, which tells userspace how
 *    memory it needs to allocate for the blob(say for an array of properties).
 *
 * 2. Next we call DRM_IOCTL_I915_QUERY again, this time with the
 *    &drm_i915_query_item.data_ptr equal to our newly allocated blob. Note that
 *    the &drm_i915_query_item.length should still be the same as what the
 *    kernel previously set. At this point the kernel can fill in the blob.
 *
 * Note that for some query items it can make sense for userspace to just pass
 * in a buffer/blob equal to or larger than the required size. In this case only
 * a single ioctl call is needed. For some smaller query items this can work
 * quite well.
 *
 */
struct drm_i915_query {
	/** @num_items: The number of elements in the @items_ptr array */
	__u32 num_items;

	/**
	 * @flags: Unused for now. Must be cleared to zero.
	 */
	__u32 flags;

	/**
	 * @items_ptr:
	 *
	 * Pointer to an array of struct drm_i915_query_item. The number of
	 * array elements is @num_items.
	 */
	__u64 items_ptr;
};

/**
 * struct drm_i915_query_topology_info
 *
 * Describes slice/subslice/EU information queried by
 * %DRM_I915_QUERY_TOPOLOGY_INFO
 */
struct drm_i915_query_topology_info {
	/**
	 * @flags:
	 *
	 * Unused for now. Must be cleared to zero.
	 */
	__u16 flags;

	/**
	 * @max_slices:
	 *
	 * The number of bits used to express the slice mask.
	 */
	__u16 max_slices;

	/**
	 * @max_subslices:
	 *
	 * The number of bits used to express the subslice mask.
	 */
	__u16 max_subslices;

	/**
	 * @max_eus_per_subslice:
	 *
	 * The number of bits in the EU mask that correspond to a single
	 * subslice's EUs.
	 */
	__u16 max_eus_per_subslice;

	/**
	 * @subslice_offset:
	 *
	 * Offset in data[] at which the subslice masks are stored.
	 */
	__u16 subslice_offset;

	/**
	 * @subslice_stride:
	 *
	 * Stride at which each of the subslice masks for each slice are
	 * stored.
	 */
	__u16 subslice_stride;

	/**
	 * @eu_offset:
	 *
	 * Offset in data[] at which the EU masks are stored.
	 */
	__u16 eu_offset;

	/**
	 * @eu_stride:
	 *
	 * Stride at which each of the EU masks for each subslice are stored.
	 */
	__u16 eu_stride;

	/**
	 * @data:
	 *
	 * Contains 3 pieces of information :
	 *
	 * - The slice mask with one bit per slice telling whether a slice is
	 *   available. The availability of slice X can be queried with the
	 *   following formula :
	 *
	 *   .. code:: c
	 *
	 *      (data[X / 8] >> (X % 8)) & 1
	 *
	 *   Starting with Xe_HP platforms, Intel hardware no longer has
	 *   traditional slices so i915 will always report a single slice
	 *   (hardcoded slicemask = 0x1) which contains all of the platform's
	 *   subslices.  I.e., the mask here does not reflect any of the newer
	 *   hardware concepts such as "gslices" or "cslices" since userspace
	 *   is capable of inferring those from the subslice mask.
	 *
	 * - The subslice mask for each slice with one bit per subslice telling
	 *   whether a subslice is available.  Starting with Gen12 we use the
	 *   term "subslice" to refer to what the hardware documentation
	 *   describes as a "dual-subslices."  The availability of subslice Y
	 *   in slice X can be queried with the following formula :
	 *
	 *   .. code:: c
	 *
	 *      (data[subslice_offset + X * subslice_stride + Y / 8] >> (Y % 8)) & 1
	 *
	 * - The EU mask for each subslice in each slice, with one bit per EU
	 *   telling whether an EU is available. The availability of EU Z in
	 *   subslice Y in slice X can be queried with the following formula :
	 *
	 *   .. code:: c
	 *
	 *      (data[eu_offset +
	 *            (X * max_subslices + Y) * eu_stride +
	 *            Z / 8
	 *       ] >> (Z % 8)) & 1
	 */
	__u8 data[];
};

/**
 * DOC: Engine Discovery uAPI
 *
 * Engine discovery uAPI is a way of enumerating physical engines present in a
 * GPU associated with an open i915 DRM file descriptor. This supersedes the old
 * way of using `DRM_IOCTL_I915_GETPARAM` and engine identifiers like
 * `I915_PARAM_HAS_BLT`.
 *
 * The need for this interface came starting with Icelake and newer GPUs, which
 * started to establish a pattern of having multiple engines of a same class,
 * where not all instances were always completely functionally equivalent.
 *
 * Entry point for this uapi is `DRM_IOCTL_I915_QUERY` with the
 * `DRM_I915_QUERY_ENGINE_INFO` as the queried item id.
 *
 * Example for getting the list of engines:
 *
 * .. code-block:: C
 *
 * 	struct drm_i915_query_engine_info *info;
 * 	struct drm_i915_query_item item = {
 * 		.query_id = DRM_I915_QUERY_ENGINE_INFO;
 * 	};
 * 	struct drm_i915_query query = {
 * 		.num_items = 1,
 * 		.items_ptr = (uintptr_t)&item,
 * 	};
 * 	int err, i;
 *
 * 	// First query the size of the blob we need, this needs to be large
 * 	// enough to hold our array of engines. The kernel will fill out the
 * 	// item.length for us, which is the number of bytes we need.
 * 	//
 *	// Alternatively a large buffer can be allocated straightaway enabling
 * 	// querying in one pass, in which case item.length should contain the
 * 	// length of the provided buffer.
 * 	err = ioctl(fd, DRM_IOCTL_I915_QUERY, &query);
 * 	if (err) ...
 *
 * 	info = calloc(1, item.length);
 * 	// Now that we allocated the required number of bytes, we call the ioctl
 * 	// again, this time with the data_ptr pointing to our newly allocated
 * 	// blob, which the kernel can then populate with info on all engines.
 *	item.data_ptr = (uintptr_t)&info;
 *
 * 	err = ioctl(fd, DRM_IOCTL_I915_QUERY, &query);
 * 	if (err) ...
 *
 * 	// We can now access each engine in the array
 * 	for (i = 0; i < info->num_engines; i++) {
 * 		struct drm_i915_engine_info einfo = info->engines[i];
 * 		u16 class = einfo.engine.class;
 * 		u16 instance = einfo.engine.instance;
 * 		....
 * 	}
 *
 * 	free(info);
 *
 * Each of the enumerated engines, apart from being defined by its class and
 * instance (see `struct i915_engine_class_instance`), also can have flags and
 * capabilities defined as documented in i915_drm.h.
 *
 * For instance video engines which support HEVC encoding will have the
 * `I915_VIDEO_CLASS_CAPABILITY_HEVC` capability bit set.
 *
 * Engine discovery only fully comes to its own when combined with the new way
 * of addressing engines when submitting batch buffers using contexts with
 * engine maps configured.
 */

/**
 * struct drm_i915_engine_info
 *
 * Describes one engine and its capabilities as known to the driver.
 */
struct drm_i915_engine_info {
	/** @engine: Engine class and instance. */
	struct i915_engine_class_instance engine;

	/** @rsvd0: Reserved field. */
	__u32 rsvd0;

	/** @flags: Engine flags. */
	__u64 flags;
#define I915_ENGINE_INFO_HAS_LOGICAL_INSTANCE		(1 << 0)

	/** @capabilities: Capabilities of this engine. */
	__u64 capabilities;
#define I915_VIDEO_CLASS_CAPABILITY_HEVC		(1 << 0)
#define I915_VIDEO_AND_ENHANCE_CLASS_CAPABILITY_SFC	(1 << 1)

	/** @logical_instance: Logical instance of engine */
	__u16 logical_instance;

	/** @rsvd1: Reserved fields. */
	__u16 rsvd1[3];
	/** @rsvd2: Reserved fields. */
	__u64 rsvd2[3];
};

/**
 * struct drm_i915_query_engine_info
 *
 * Engine info query enumerates all engines known to the driver by filling in
 * an array of struct drm_i915_engine_info structures.
 */
struct drm_i915_query_engine_info {
	/** @num_engines: Number of struct drm_i915_engine_info structs following. */
	__u32 num_engines;

	/** @rsvd: MBZ */
	__u32 rsvd[3];

	/** @engines: Marker for drm_i915_engine_info structures. */
	struct drm_i915_engine_info engines[];
};

/**
 * struct drm_i915_query_perf_config
 *
 * Data written by the kernel with query %DRM_I915_QUERY_PERF_CONFIG and
 * %DRM_I915_QUERY_GEOMETRY_SUBSLICES.
 */
struct drm_i915_query_perf_config {
	union {
		/**
		 * @n_configs:
		 *
		 * When &drm_i915_query_item.flags ==
		 * %DRM_I915_QUERY_PERF_CONFIG_LIST, i915 sets this fields to
		 * the number of configurations available.
		 */
		__u64 n_configs;

		/**
		 * @config:
		 *
		 * When &drm_i915_query_item.flags ==
		 * %DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_ID, i915 will use the
		 * value in this field as configuration identifier to decide
		 * what data to write into config_ptr.
		 */
		__u64 config;

		/**
		 * @uuid:
		 *
		 * When &drm_i915_query_item.flags ==
		 * %DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID, i915 will use the
		 * value in this field as configuration identifier to decide
		 * what data to write into config_ptr.
		 *
		 * String formatted like "%08x-%04x-%04x-%04x-%012x"
		 */
		char uuid[36];
	};

	/**
	 * @flags:
	 *
	 * Unused for now. Must be cleared to zero.
	 */
	__u32 flags;

	/**
	 * @data:
	 *
	 * When &drm_i915_query_item.flags == %DRM_I915_QUERY_PERF_CONFIG_LIST,
	 * i915 will write an array of __u64 of configuration identifiers.
	 *
	 * When &drm_i915_query_item.flags == %DRM_I915_QUERY_PERF_CONFIG_DATA,
	 * i915 will write a struct drm_i915_perf_oa_config. If the following
	 * fields of struct drm_i915_perf_oa_config are not set to 0, i915 will
	 * write into the associated pointers the values of submitted when the
	 * configuration was created :
	 *
	 *  - &drm_i915_perf_oa_config.n_mux_regs
	 *  - &drm_i915_perf_oa_config.n_boolean_regs
	 *  - &drm_i915_perf_oa_config.n_flex_regs
	 */
	__u8 data[];
};

/**
 * enum drm_i915_gem_memory_class - Supported memory classes
 */
enum drm_i915_gem_memory_class {
	/** @I915_MEMORY_CLASS_SYSTEM: System memory */
	I915_MEMORY_CLASS_SYSTEM = 0,
	/** @I915_MEMORY_CLASS_DEVICE: Device local-memory */
	I915_MEMORY_CLASS_DEVICE,
};

/**
 * struct drm_i915_gem_memory_class_instance - Identify particular memory region
 */
struct drm_i915_gem_memory_class_instance {
	/** @memory_class: See enum drm_i915_gem_memory_class */
	__u16 memory_class;

	/** @memory_instance: Which instance */
	__u16 memory_instance;
};

/**
 * struct drm_i915_memory_region_info - Describes one region as known to the
 * driver.
 *
 * Note this is using both struct drm_i915_query_item and struct drm_i915_query.
 * For this new query we are adding the new query id DRM_I915_QUERY_MEMORY_REGIONS
 * at &drm_i915_query_item.query_id.
 */
struct drm_i915_memory_region_info {
	/** @region: The class:instance pair encoding */
	struct drm_i915_gem_memory_class_instance region;

	/** @rsvd0: MBZ */
	__u32 rsvd0;

	/**
	 * @probed_size: Memory probed by the driver
	 *
	 * Note that it should not be possible to ever encounter a zero value
	 * here, also note that no current region type will ever return -1 here.
	 * Although for future region types, this might be a possibility. The
	 * same applies to the other size fields.
	 */
	__u64 probed_size;

	/**
	 * @unallocated_size: Estimate of memory remaining
	 *
	 * Requires CAP_PERFMON or CAP_SYS_ADMIN to get reliable accounting.
	 * Without this (or if this is an older kernel) the value here will
	 * always equal the @probed_size. Note this is only currently tracked
	 * for I915_MEMORY_CLASS_DEVICE regions (for other types the value here
	 * will always equal the @probed_size).
	 */
	__u64 unallocated_size;

	union {
		/** @rsvd1: MBZ */
		__u64 rsvd1[8];
		struct {
			/**
			 * @probed_cpu_visible_size: Memory probed by the driver
			 * that is CPU accessible.
			 *
			 * This will be always be <= @probed_size, and the
			 * remainder (if there is any) will not be CPU
			 * accessible.
			 *
			 * On systems without small BAR, the @probed_size will
			 * always equal the @probed_cpu_visible_size, since all
			 * of it will be CPU accessible.
			 *
			 * Note this is only tracked for
			 * I915_MEMORY_CLASS_DEVICE regions (for other types the
			 * value here will always equal the @probed_size).
			 *
			 * Note that if the value returned here is zero, then
			 * this must be an old kernel which lacks the relevant
			 * small-bar uAPI support (including
			 * I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS), but on
			 * such systems we should never actually end up with a
			 * small BAR configuration, assuming we are able to load
			 * the kernel module. Hence it should be safe to treat
			 * this the same as when @probed_cpu_visible_size ==
			 * @probed_size.
			 */
			__u64 probed_cpu_visible_size;

			/**
			 * @unallocated_cpu_visible_size: Estimate of CPU
			 * visible memory remaining.
			 *
			 * Note this is only tracked for
			 * I915_MEMORY_CLASS_DEVICE regions (for other types the
			 * value here will always equal the
			 * @probed_cpu_visible_size).
			 *
			 * Requires CAP_PERFMON or CAP_SYS_ADMIN to get reliable
			 * accounting.  Without this the value here will always
			 * equal the @probed_cpu_visible_size. Note this is only
			 * currently tracked for I915_MEMORY_CLASS_DEVICE
			 * regions (for other types the value here will also
			 * always equal the @probed_cpu_visible_size).
			 *
			 * If this is an older kernel the value here will be
			 * zero, see also @probed_cpu_visible_size.
			 */
			__u64 unallocated_cpu_visible_size;
		};
	};
};

/**
 * struct drm_i915_query_memory_regions
 *
 * The region info query enumerates all regions known to the driver by filling
 * in an array of struct drm_i915_memory_region_info structures.
 *
 * Example for getting the list of supported regions:
 *
 * .. code-block:: C
 *
 *	struct drm_i915_query_memory_regions *info;
 *	struct drm_i915_query_item item = {
 *		.query_id = DRM_I915_QUERY_MEMORY_REGIONS;
 *	};
 *	struct drm_i915_query query = {
 *		.num_items = 1,
 *		.items_ptr = (uintptr_t)&item,
 *	};
 *	int err, i;
 *
 *	// First query the size of the blob we need, this needs to be large
 *	// enough to hold our array of regions. The kernel will fill out the
 *	// item.length for us, which is the number of bytes we need.
 *	err = ioctl(fd, DRM_IOCTL_I915_QUERY, &query);
 *	if (err) ...
 *
 *	info = calloc(1, item.length);
 *	// Now that we allocated the required number of bytes, we call the ioctl
 *	// again, this time with the data_ptr pointing to our newly allocated
 *	// blob, which the kernel can then populate with the all the region info.
 *	item.data_ptr = (uintptr_t)&info,
 *
 *	err = ioctl(fd, DRM_IOCTL_I915_QUERY, &query);
 *	if (err) ...
 *
 *	// We can now access each region in the array
 *	for (i = 0; i < info->num_regions; i++) {
 *		struct drm_i915_memory_region_info mr = info->regions[i];
 *		u16 class = mr.region.class;
 *		u16 instance = mr.region.instance;
 *
 *		....
 *	}
 *
 *	free(info);
 */
struct drm_i915_query_memory_regions {
	/** @num_regions: Number of supported regions */
	__u32 num_regions;

	/** @rsvd: MBZ */
	__u32 rsvd[3];

	/** @regions: Info about each supported region */
	struct drm_i915_memory_region_info regions[];
};

/**
 * struct drm_i915_query_guc_submission_version - query GuC submission interface version
 */
struct drm_i915_query_guc_submission_version {
	/** @branch: Firmware branch version. */
	__u32 branch;
	/** @major: Firmware major version. */
	__u32 major;
	/** @minor: Firmware minor version. */
	__u32 minor;
	/** @patch: Firmware patch version. */
	__u32 patch;
};

/**
 * DOC: GuC HWCONFIG blob uAPI
 *
 * The GuC produces a blob with information about the current device.
 * i915 reads this blob from GuC and makes it available via this uAPI.
 *
 * The format and meaning of the blob content are documented in the
 * Programmer's Reference Manual.
 */

/**
 * struct drm_i915_gem_create_ext - Existing gem_create behaviour, with added
 * extension support using struct i915_user_extension.
 *
 * Note that new buffer flags should be added here, at least for the stuff that
 * is immutable. Previously we would have two ioctls, one to create the object
 * with gem_create, and another to apply various parameters, however this
 * creates some ambiguity for the params which are considered immutable. Also in
 * general we're phasing out the various SET/GET ioctls.
 */
struct drm_i915_gem_create_ext {
	/**
	 * @size: Requested size for the object.
	 *
	 * The (page-aligned) allocated size for the object will be returned.
	 *
	 * On platforms like DG2/ATS the kernel will always use 64K or larger
	 * pages for I915_MEMORY_CLASS_DEVICE. The kernel also requires a
	 * minimum of 64K GTT alignment for such objects.
	 *
	 * NOTE: Previously the ABI here required a minimum GTT alignment of 2M
	 * on DG2/ATS, due to how the hardware implemented 64K GTT page support,
	 * where we had the following complications:
	 *
	 *   1) The entire PDE (which covers a 2MB virtual address range), must
	 *   contain only 64K PTEs, i.e mixing 4K and 64K PTEs in the same
	 *   PDE is forbidden by the hardware.
	 *
	 *   2) We still need to support 4K PTEs for I915_MEMORY_CLASS_SYSTEM
	 *   objects.
	 *
	 * However on actual production HW this was completely changed to now
	 * allow setting a TLB hint at the PTE level (see PS64), which is a lot
	 * more flexible than the above. With this the 2M restriction was
	 * dropped where we now only require 64K.
	 */
	__u64 size;

	/**
	 * @handle: Returned handle for the object.
	 *
	 * Object handles are nonzero.
	 */
	__u32 handle;

	/**
	 * @flags: Optional flags.
	 *
	 * Supported values:
	 *
	 * I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS - Signal to the kernel that
	 * the object will need to be accessed via the CPU.
	 *
	 * Only valid when placing objects in I915_MEMORY_CLASS_DEVICE, and only
	 * strictly required on configurations where some subset of the device
	 * memory is directly visible/mappable through the CPU (which we also
	 * call small BAR), like on some DG2+ systems. Note that this is quite
	 * undesirable, but due to various factors like the client CPU, BIOS etc
	 * it's something we can expect to see in the wild. See
	 * &drm_i915_memory_region_info.probed_cpu_visible_size for how to
	 * determine if this system applies.
	 *
	 * Note that one of the placements MUST be I915_MEMORY_CLASS_SYSTEM, to
	 * ensure the kernel can always spill the allocation to system memory,
	 * if the object can't be allocated in the mappable part of
	 * I915_MEMORY_CLASS_DEVICE.
	 *
	 * Also note that since the kernel only supports flat-CCS on objects
	 * that can *only* be placed in I915_MEMORY_CLASS_DEVICE, we therefore
	 * don't support I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS together with
	 * flat-CCS.
	 *
	 * Without this hint, the kernel will assume that non-mappable
	 * I915_MEMORY_CLASS_DEVICE is preferred for this object. Note that the
	 * kernel can still migrate the object to the mappable part, as a last
	 * resort, if userspace ever CPU faults this object, but this might be
	 * expensive, and so ideally should be avoided.
	 *
	 * On older kernels which lack the relevant small-bar uAPI support (see
	 * also &drm_i915_memory_region_info.probed_cpu_visible_size),
	 * usage of the flag will result in an error, but it should NEVER be
	 * possible to end up with a small BAR configuration, assuming we can
	 * also successfully load the i915 kernel module. In such cases the
	 * entire I915_MEMORY_CLASS_DEVICE region will be CPU accessible, and as
	 * such there are zero restrictions on where the object can be placed.
	 */
#define I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS (1 << 0)
	__u32 flags;

	/**
	 * @extensions: The chain of extensions to apply to this object.
	 *
	 * This will be useful in the future when we need to support several
	 * different extensions, and we need to apply more than one when
	 * creating the object. See struct i915_user_extension.
	 *
	 * If we don't supply any extensions then we get the same old gem_create
	 * behaviour.
	 *
	 * For I915_GEM_CREATE_EXT_MEMORY_REGIONS usage see
	 * struct drm_i915_gem_create_ext_memory_regions.
	 *
	 * For I915_GEM_CREATE_EXT_PROTECTED_CONTENT usage see
	 * struct drm_i915_gem_create_ext_protected_content.
	 *
	 * For I915_GEM_CREATE_EXT_SET_PAT usage see
	 * struct drm_i915_gem_create_ext_set_pat.
	 */
#define I915_GEM_CREATE_EXT_MEMORY_REGIONS 0
#define I915_GEM_CREATE_EXT_PROTECTED_CONTENT 1
#define I915_GEM_CREATE_EXT_SET_PAT 2
	__u64 extensions;
};

/**
 * struct drm_i915_gem_create_ext_memory_regions - The
 * I915_GEM_CREATE_EXT_MEMORY_REGIONS extension.
 *
 * Set the object with the desired set of placements/regions in priority
 * order. Each entry must be unique and supported by the device.
 *
 * This is provided as an array of struct drm_i915_gem_memory_class_instance, or
 * an equivalent layout of class:instance pair encodings. See struct
 * drm_i915_query_memory_regions and DRM_I915_QUERY_MEMORY_REGIONS for how to
 * query the supported regions for a device.
 *
 * As an example, on discrete devices, if we wish to set the placement as
 * device local-memory we can do something like:
 *
 * .. code-block:: C
 *
 *	struct drm_i915_gem_memory_class_instance region_lmem = {
 *              .memory_class = I915_MEMORY_CLASS_DEVICE,
 *              .memory_instance = 0,
 *      };
 *      struct drm_i915_gem_create_ext_memory_regions regions = {
 *              .base = { .name = I915_GEM_CREATE_EXT_MEMORY_REGIONS },
 *              .regions = (uintptr_t)&region_lmem,
 *              .num_regions = 1,
 *      };
 *      struct drm_i915_gem_create_ext create_ext = {
 *              .size = 16 * PAGE_SIZE,
 *              .extensions = (uintptr_t)&regions,
 *      };
 *
 *      int err = ioctl(fd, DRM_IOCTL_I915_GEM_CREATE_EXT, &create_ext);
 *      if (err) ...
 *
 * At which point we get the object handle in &drm_i915_gem_create_ext.handle,
 * along with the final object size in &drm_i915_gem_create_ext.size, which
 * should account for any rounding up, if required.
 *
 * Note that userspace has no means of knowing the current backing region
 * for objects where @num_regions is larger than one. The kernel will only
 * ensure that the priority order of the @regions array is honoured, either
 * when initially placing the object, or when moving memory around due to
 * memory pressure
 *
 * On Flat-CCS capable HW, compression is supported for the objects residing
 * in I915_MEMORY_CLASS_DEVICE. When such objects (compressed) have other
 * memory class in @regions and migrated (by i915, due to memory
 * constraints) to the non I915_MEMORY_CLASS_DEVICE region, then i915 needs to
 * decompress the content. But i915 doesn't have the required information to
 * decompress the userspace compressed objects.
 *
 * So i915 supports Flat-CCS, on the objects which can reside only on
 * I915_MEMORY_CLASS_DEVICE regions.
 */
struct drm_i915_gem_create_ext_memory_regions {
	/** @base: Extension link. See struct i915_user_extension. */
	struct i915_user_extension base;

	/** @pad: MBZ */
	__u32 pad;
	/** @num_regions: Number of elements in the @regions array. */
	__u32 num_regions;
	/**
	 * @regions: The regions/placements array.
	 *
	 * An array of struct drm_i915_gem_memory_class_instance.
	 */
	__u64 regions;
};

/**
 * struct drm_i915_gem_create_ext_protected_content - The
 * I915_OBJECT_PARAM_PROTECTED_CONTENT extension.
 *
 * If this extension is provided, buffer contents are expected to be protected
 * by PXP encryption and require decryption for scan out and processing. This
 * is only possible on platforms that have PXP enabled, on all other scenarios
 * using this extension will cause the ioctl to fail and return -ENODEV. The
 * flags parameter is reserved for future expansion and must currently be set
 * to zero.
 *
 * The buffer contents are considered invalid after a PXP session teardown.
 *
 * The encryption is guaranteed to be processed correctly only if the object
 * is submitted with a context created using the
 * I915_CONTEXT_PARAM_PROTECTED_CONTENT flag. This will also enable extra checks
 * at submission time on the validity of the objects involved.
 *
 * Below is an example on how to create a protected object:
 *
 * .. code-block:: C
 *
 *      struct drm_i915_gem_create_ext_protected_content protected_ext = {
 *              .base = { .name = I915_GEM_CREATE_EXT_PROTECTED_CONTENT },
 *              .flags = 0,
 *      };
 *      struct drm_i915_gem_create_ext create_ext = {
 *              .size = PAGE_SIZE,
 *              .extensions = (uintptr_t)&protected_ext,
 *      };
 *
 *      int err = ioctl(fd, DRM_IOCTL_I915_GEM_CREATE_EXT, &create_ext);
 *      if (err) ...
 */
struct drm_i915_gem_create_ext_protected_content {
	/** @base: Extension link. See struct i915_user_extension. */
	struct i915_user_extension base;
	/** @flags: reserved for future usage, currently MBZ */
	__u32 flags;
};

/**
 * struct drm_i915_gem_create_ext_set_pat - The
 * I915_GEM_CREATE_EXT_SET_PAT extension.
 *
 * If this extension is provided, the specified caching policy (PAT index) is
 * applied to the buffer object.
 *
 * Below is an example on how to create an object with specific caching policy:
 *
 * .. code-block:: C
 *
 *      struct drm_i915_gem_create_ext_set_pat set_pat_ext = {
 *              .base = { .name = I915_GEM_CREATE_EXT_SET_PAT },
 *              .pat_index = 0,
 *      };
 *      struct drm_i915_gem_create_ext create_ext = {
 *              .size = PAGE_SIZE,
 *              .extensions = (uintptr_t)&set_pat_ext,
 *      };
 *
 *      int err = ioctl(fd, DRM_IOCTL_I915_GEM_CREATE_EXT, &create_ext);
 *      if (err) ...
 */
struct drm_i915_gem_create_ext_set_pat {
	/** @base: Extension link. See struct i915_user_extension. */
	struct i915_user_extension base;
	/**
	 * @pat_index: PAT index to be set
	 * PAT index is a bit field in Page Table Entry to control caching
	 * behaviors for GPU accesses. The definition of PAT index is
	 * platform dependent and can be found in hardware specifications,
	 */
	__u32 pat_index;
	/** @rsvd: reserved for future use */
	__u32 rsvd;
};

/* ID of the protected content session managed by i915 when PXP is active */
#define I915_PROTECTED_CONTENT_DEFAULT_SESSION 0xf

#if defined(__cplusplus)
}
#endif

#endif /* _UAPI_I915_DRM_H_ */