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)
Unified · Split
| @@ -360,6 +360,8 @@ Format Functions Reference · 359 unmodified lines | ||
| 360 | 360 | .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c |
| 361 | 361 | :export: |
| 362 | 362 | |
| 363 | +.. _kms_dumb_buffer_objects: | |
| 364 | + | |
| 363 | 365 | Dumb Buffer Objects |
| 364 | 366 | =================== |
| 365 | 367 | |
| @@ -1134,6 +1134,26 @@ extern "C" { · 1133 unmodified lines | ||
| 1134 | 1134 | #define DRM_IOCTL_MODE_PAGE_FLIP DRM_IOWR(0xB0, struct drm_mode_crtc_page_flip) |
| 1135 | 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 | 1157 | #define DRM_IOCTL_MODE_CREATE_DUMB DRM_IOWR(0xB2, struct drm_mode_create_dumb) |
| 1138 | 1158 | #define DRM_IOCTL_MODE_MAP_DUMB DRM_IOWR(0xB3, struct drm_mode_map_dumb) |
| 1139 | 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 | 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 | 1048 | struct drm_mode_create_dumb { |
| 1037 | 1049 | __u32 height; |
| 1038 | 1050 | __u32 width; |
| 1039 | 1051 | __u32 bpp; |
| 1040 | 1052 | __u32 flags; |
| 1041 | − /* handle, pitch, size will be returned */ | |
| 1053 | + | |
| 1042 | 1054 | __u32 handle; |
| 1043 | 1055 | __u32 pitch; |
| 1044 | 1056 | __u64 size; |