The main motivation is to repeat that dumb buffers should not be abused for anything else than basic software rendering with KMS. User-space devs are more likely to look at the IOCTL docs than to actively search for the driver-oriented "Dumb Buffer Objects" section. v2: reference DRM_CAP_DUMB_BUFFER, DRM_CAP_DUMB_PREFERRED_DEPTH and DRM_CAP_DUMB_PREFER_SHADOW (Pekka)
Showing the changes to include/uapi (2 of 3 files). Show all
Unified · Split
| @@ -1134,6 +1134,26 @@ extern "C" { · 1133 unmodified lines | |||
| 1134 | #define DRM_IOCTL_MODE_PAGE_FLIP DRM_IOWR(0xB0, struct drm_mode_crtc_page_flip) | 1134 | #define DRM_IOCTL_MODE_PAGE_FLIP DRM_IOWR(0xB0, struct drm_mode_crtc_page_flip) |
| 1135 | #define DRM_IOCTL_MODE_DIRTYFB DRM_IOWR(0xB1, struct drm_mode_fb_dirty_cmd) | 1135 | #define DRM_IOCTL_MODE_DIRTYFB DRM_IOWR(0xB1, struct drm_mode_fb_dirty_cmd) |
| 1136 | 1136 | ||
| 1137 | /** | ||
| 1138 | * DRM_IOCTL_MODE_CREATE_DUMB - Create a new dumb buffer object. | ||
| 1139 | * | ||
| 1140 | * KMS dumb buffers provide a very primitive way to allocate a buffer object | ||
| 1141 | * suitable for scanout and map it for software rendering. KMS dumb buffers are | ||
| 1142 | * not suitable for hardware-accelerated rendering nor video decoding. KMS dumb | ||
| 1143 | * buffers are not suitable to be displayed on any other device than the KMS | ||
| 1144 | * device where they were allocated from. Also see | ||
| 1145 | * :ref:`kms_dumb_buffer_objects`. | ||
| 1146 | * | ||
| 1147 | * The IOCTL argument is a struct drm_mode_create_dumb. | ||
| 1148 | * | ||
| 1149 | * User-space is expected to create a KMS dumb buffer via this IOCTL, then add | ||
| 1150 | * it as a KMS framebuffer via &DRM_IOCTL_MODE_ADDFB and map it via | ||
| 1151 | * &DRM_IOCTL_MODE_MAP_DUMB. | ||
| 1152 | * | ||
| 1153 | * &DRM_CAP_DUMB_BUFFER indicates whether this IOCTL is supported. | ||
| 1154 | * &DRM_CAP_DUMB_PREFERRED_DEPTH and &DRM_CAP_DUMB_PREFER_SHADOW indicate | ||
| 1155 | * driver preferences for dumb buffers. | ||
| 1156 | */ | ||
| 1137 | #define DRM_IOCTL_MODE_CREATE_DUMB DRM_IOWR(0xB2, struct drm_mode_create_dumb) | 1157 | #define DRM_IOCTL_MODE_CREATE_DUMB DRM_IOWR(0xB2, struct drm_mode_create_dumb) |
| 1138 | #define DRM_IOCTL_MODE_MAP_DUMB DRM_IOWR(0xB3, struct drm_mode_map_dumb) | 1158 | #define DRM_IOCTL_MODE_MAP_DUMB DRM_IOWR(0xB3, struct drm_mode_map_dumb) |
| 1139 | #define DRM_IOCTL_MODE_DESTROY_DUMB DRM_IOWR(0xB4, struct drm_mode_destroy_dumb) | 1159 | #define DRM_IOCTL_MODE_DESTROY_DUMB DRM_IOWR(0xB4, struct drm_mode_destroy_dumb) |
| @@ -1032,13 +1032,25 @@ struct drm_mode_crtc_page_flip_target { · 1031 unmodified lines | |||
| 1032 | __u64 user_data; | 1032 | __u64 user_data; |
| 1033 | }; | 1033 | }; |
| 1034 | 1034 | ||
| 1035 | /* create a dumb scanout buffer */ | 1035 | /** |
| 1036 | * struct drm_mode_create_dumb - Create a KMS dumb buffer for scanout. | ||
| 1037 | * @height: buffer height in pixels | ||
| 1038 | * @width: buffer width in pixels | ||
| 1039 | * @bpp: bits per pixel | ||
| 1040 | * @flags: must be zero | ||
| 1041 | * @handle: buffer object handle | ||
| 1042 | * @pitch: number of bytes between two consecutive lines | ||
| 1043 | * @size: size of the whole buffer in bytes | ||
| 1044 | * | ||
| 1045 | * User-space fills @height, @width, @bpp and @flags. If the IOCTL succeeds, | ||
| 1046 | * the kernel fills @handle, @pitch and @size. | ||
| 1047 | */ | ||
| 1036 | struct drm_mode_create_dumb { | 1048 | struct drm_mode_create_dumb { |
| 1037 | __u32 height; | 1049 | __u32 height; |
| 1038 | __u32 width; | 1050 | __u32 width; |
| 1039 | __u32 bpp; | 1051 | __u32 bpp; |
| 1040 | __u32 flags; | 1052 | __u32 flags; |
| 1041 | /* handle, pitch, size will be returned */ | 1053 | |
| 1042 | __u32 handle; | 1054 | __u32 handle; |
| 1043 | __u32 pitch; | 1055 | __u32 pitch; |
| 1044 | __u64 size; | 1056 | __u64 size; |