Picking the changes from: 6068771673a38efc ("drm: document DRM_IOCTL_PRIME_HANDLE_TO_FD and PRIME_FD_TO_HANDLE") 61a55f8b1ebcde68 ("drm: document expectations for GETFB2 handles") 158350aae16a4e66 ("drm: document DRM_IOCTL_GEM_CLOSE") Silencing these perf build warnings: Warning: Kernel ABI header at 'tools/include/uapi/drm/drm.h' differs from latest version at 'include/uapi/drm/drm.h' diff -u tools/include/uapi/drm/drm.h include/uapi/drm/drm.h No changes in tooling as these are just C comment documentation changes.
Showing the changes to tools/include/uapi (1 of 1 file). Show all
Unified · Split
| @@ -972,6 +972,19 @@ extern "C" { · 971 unmodified lines | |||
| 972 | #define DRM_IOCTL_GET_STATS DRM_IOR( 0x06, struct drm_stats) | 972 | #define DRM_IOCTL_GET_STATS DRM_IOR( 0x06, struct drm_stats) |
| 973 | #define DRM_IOCTL_SET_VERSION DRM_IOWR(0x07, struct drm_set_version) | 973 | #define DRM_IOCTL_SET_VERSION DRM_IOWR(0x07, struct drm_set_version) |
| 974 | #define DRM_IOCTL_MODESET_CTL DRM_IOW(0x08, struct drm_modeset_ctl) | 974 | #define DRM_IOCTL_MODESET_CTL DRM_IOW(0x08, struct drm_modeset_ctl) |
| 975 | /** | ||
| 976 | * DRM_IOCTL_GEM_CLOSE - Close a GEM handle. | ||
| 977 | * | ||
| 978 | * GEM handles are not reference-counted by the kernel. User-space is | ||
| 979 | * responsible for managing their lifetime. For example, if user-space imports | ||
| 980 | * the same memory object twice on the same DRM file description, the same GEM | ||
| 981 | * handle is returned by both imports, and user-space needs to ensure | ||
| 982 | * &DRM_IOCTL_GEM_CLOSE is performed once only. The same situation can happen | ||
| 983 | * when a memory object is allocated, then exported and imported again on the | ||
| 984 | * same DRM file description. The &DRM_IOCTL_MODE_GETFB2 IOCTL is an exception | ||
| 985 | * and always returns fresh new GEM handles even if an existing GEM handle | ||
| 986 | * already refers to the same memory object before the IOCTL is performed. | ||
| 987 | */ | ||
| 975 | #define DRM_IOCTL_GEM_CLOSE DRM_IOW (0x09, struct drm_gem_close) | 988 | #define DRM_IOCTL_GEM_CLOSE DRM_IOW (0x09, struct drm_gem_close) |
| 976 | #define DRM_IOCTL_GEM_FLINK DRM_IOWR(0x0a, struct drm_gem_flink) | 989 | #define DRM_IOCTL_GEM_FLINK DRM_IOWR(0x0a, struct drm_gem_flink) |
| 977 | #define DRM_IOCTL_GEM_OPEN DRM_IOWR(0x0b, struct drm_gem_open) | 990 | #define DRM_IOCTL_GEM_OPEN DRM_IOWR(0x0b, struct drm_gem_open) |
| @@ -1012,7 +1025,37 @@ extern "C" { · 34 unmodified lines | |||
| 1012 | #define DRM_IOCTL_UNLOCK DRM_IOW( 0x2b, struct drm_lock) | 1025 | #define DRM_IOCTL_UNLOCK DRM_IOW( 0x2b, struct drm_lock) |
| 1013 | #define DRM_IOCTL_FINISH DRM_IOW( 0x2c, struct drm_lock) | 1026 | #define DRM_IOCTL_FINISH DRM_IOW( 0x2c, struct drm_lock) |
| 1014 | 1027 | ||
| 1028 | /** | ||
| 1029 | * DRM_IOCTL_PRIME_HANDLE_TO_FD - Convert a GEM handle to a DMA-BUF FD. | ||
| 1030 | * | ||
| 1031 | * User-space sets &drm_prime_handle.handle with the GEM handle to export and | ||
| 1032 | * &drm_prime_handle.flags, and gets back a DMA-BUF file descriptor in | ||
| 1033 | * &drm_prime_handle.fd. | ||
| 1034 | * | ||
| 1035 | * The export can fail for any driver-specific reason, e.g. because export is | ||
| 1036 | * not supported for this specific GEM handle (but might be for others). | ||
| 1037 | * | ||
| 1038 | * Support for exporting DMA-BUFs is advertised via &DRM_PRIME_CAP_EXPORT. | ||
| 1039 | */ | ||
| 1015 | #define DRM_IOCTL_PRIME_HANDLE_TO_FD DRM_IOWR(0x2d, struct drm_prime_handle) | 1040 | #define DRM_IOCTL_PRIME_HANDLE_TO_FD DRM_IOWR(0x2d, struct drm_prime_handle) |
| 1041 | /** | ||
| 1042 | * DRM_IOCTL_PRIME_FD_TO_HANDLE - Convert a DMA-BUF FD to a GEM handle. | ||
| 1043 | * | ||
| 1044 | * User-space sets &drm_prime_handle.fd with a DMA-BUF file descriptor to | ||
| 1045 | * import, and gets back a GEM handle in &drm_prime_handle.handle. | ||
| 1046 | * &drm_prime_handle.flags is unused. | ||
| 1047 | * | ||
| 1048 | * If an existing GEM handle refers to the memory object backing the DMA-BUF, | ||
| 1049 | * that GEM handle is returned. Therefore user-space which needs to handle | ||
| 1050 | * arbitrary DMA-BUFs must have a user-space lookup data structure to manually | ||
| 1051 | * reference-count duplicated GEM handles. For more information see | ||
| 1052 | * &DRM_IOCTL_GEM_CLOSE. | ||
| 1053 | * | ||
| 1054 | * The import can fail for any driver-specific reason, e.g. because import is | ||
| 1055 | * only supported for DMA-BUFs allocated on this DRM device. | ||
| 1056 | * | ||
| 1057 | * Support for importing DMA-BUFs is advertised via &DRM_PRIME_CAP_IMPORT. | ||
| 1058 | */ | ||
| 1016 | #define DRM_IOCTL_PRIME_FD_TO_HANDLE DRM_IOWR(0x2e, struct drm_prime_handle) | 1059 | #define DRM_IOCTL_PRIME_FD_TO_HANDLE DRM_IOWR(0x2e, struct drm_prime_handle) |
| 1017 | 1060 | ||
| 1018 | #define DRM_IOCTL_AGP_ACQUIRE DRM_IO( 0x30) | 1061 | #define DRM_IOCTL_AGP_ACQUIRE DRM_IO( 0x30) |
| @@ -1104,8 +1147,13 @@ extern "C" { · 85 unmodified lines | |||
| 1104 | * struct as the output. | 1147 | * struct as the output. |
| 1105 | * | 1148 | * |
| 1106 | * If the client is DRM master or has &CAP_SYS_ADMIN, &drm_mode_fb_cmd2.handles | 1149 | * If the client is DRM master or has &CAP_SYS_ADMIN, &drm_mode_fb_cmd2.handles |
| 1107 | * will be filled with GEM buffer handles. Planes are valid until one has a | 1150 | * will be filled with GEM buffer handles. Fresh new GEM handles are always |
| 1108 | * zero handle -- this can be used to compute the number of planes. | 1151 | * returned, even if another GEM handle referring to the same memory object |
| 1152 | * already exists on the DRM file description. The caller is responsible for | ||
| 1153 | * removing the new handles, e.g. via the &DRM_IOCTL_GEM_CLOSE IOCTL. The same | ||
| 1154 | * new handle will be returned for multiple planes in case they use the same | ||
| 1155 | * memory object. Planes are valid until one has a zero handle -- this can be | ||
| 1156 | * used to compute the number of planes. | ||
| 1109 | * | 1157 | * |
| 1110 | * Otherwise, &drm_mode_fb_cmd2.handles will be zeroed and planes are valid | 1158 | * Otherwise, &drm_mode_fb_cmd2.handles will be zeroed and planes are valid |
| 1111 | * until one has a zero &drm_mode_fb_cmd2.pitches. | 1159 | * until one has a zero &drm_mode_fb_cmd2.pitches. |
| @@ -1113,6 +1161,11 @@ extern "C" { · 1 unmodified line | |||
| 1113 | * If the framebuffer has a format modifier, &DRM_MODE_FB_MODIFIERS will be set | 1161 | * If the framebuffer has a format modifier, &DRM_MODE_FB_MODIFIERS will be set |
| 1114 | * in &drm_mode_fb_cmd2.flags and &drm_mode_fb_cmd2.modifier will contain the | 1162 | * in &drm_mode_fb_cmd2.flags and &drm_mode_fb_cmd2.modifier will contain the |
| 1115 | * modifier. Otherwise, user-space must ignore &drm_mode_fb_cmd2.modifier. | 1163 | * modifier. Otherwise, user-space must ignore &drm_mode_fb_cmd2.modifier. |
| 1164 | * | ||
| 1165 | * To obtain DMA-BUF FDs for each plane without leaking GEM handles, user-space | ||
| 1166 | * can export each handle via &DRM_IOCTL_PRIME_HANDLE_TO_FD, then immediately | ||
| 1167 | * close each unique handle via &DRM_IOCTL_GEM_CLOSE, making sure to not | ||
| 1168 | * double-close handles which are specified multiple times in the array. | ||
| 1116 | */ | 1169 | */ |
| 1117 | #define DRM_IOCTL_MODE_GETFB2 DRM_IOWR(0xCE, struct drm_mode_fb_cmd2) | 1170 | #define DRM_IOCTL_MODE_GETFB2 DRM_IOWR(0xCE, struct drm_mode_fb_cmd2) |
| 1118 | 1171 | ||