Add drm_modes_size_dumb(), a helper to calculate the dumb-buffer scanline pitch and allocation size. Implementations of struct drm_driver.dumb_create can call the new helper for their size computations. There is currently quite a bit of code duplication among DRM's memory managers. Each calculates scanline pitch and buffer size from the given arguments, but the implementations are inconsistent in how they treat alignment and format support. Later patches will unify this code on top of drm_mode_size_dumb() as much as possible. drm_mode_size_dumb() uses existing 4CC format helpers to interpret the given color mode. This makes the dumb-buffer interface behave similar the kernel's video= parameter. Current per-driver implementations again likely have subtle differences or bugs in how they support color modes. The dumb-buffer UAPI is only specified for known color modes. These values describe linear, single-plane RGB color formats or legacy index formats. Other values should not be specified. But some user space still does. So for unknown color modes, there are a number of known exceptions for which drm_mode_size_dumb() calculates the pitch from the bpp value, as before. All other values work the same but print an error. v6: - document additional use cases for DUMB_CREATE2 in TODO list (Tomi) - fix typos in documentation (Tomi) v5: - check for overflows with check_mul_overflow() (Tomi) v4: - use %u conversion specifier (Geert) - list DRM_FORMAT_Dn in UAPI docs (Geert) - avoid dmesg spamming with drm_warn_once() (Sima) - add more information about bpp special case (Sima) - clarify parameters for hardware alignment - add a TODO item for DUMB_CREATE2 v3: - document the UAPI semantics - compute scanline pitch from for unknown color modes (Andy, Tomi)
Showing the changes to include/uapi (1 of 4 files). Show all
Unified · Split
| @@ -1066,7 +1066,7 @@ struct drm_mode_crtc_page_flip_target { · 1065 unmodified lines | |||
| 1066 | * struct drm_mode_create_dumb - Create a KMS dumb buffer for scanout. | 1066 | * struct drm_mode_create_dumb - Create a KMS dumb buffer for scanout. |
| 1067 | * @height: buffer height in pixels | 1067 | * @height: buffer height in pixels |
| 1068 | * @width: buffer width in pixels | 1068 | * @width: buffer width in pixels |
| 1069 | * @bpp: bits per pixel | 1069 | * @bpp: color mode |
| 1070 | * @flags: must be zero | 1070 | * @flags: must be zero |
| 1071 | * @handle: buffer object handle | 1071 | * @handle: buffer object handle |
| 1072 | * @pitch: number of bytes between two consecutive lines | 1072 | * @pitch: number of bytes between two consecutive lines |
| @@ -1074,6 +1074,54 @@ struct drm_mode_crtc_page_flip_target { · 1 unmodified line | |||
| 1074 | * | 1074 | * |
| 1075 | * User-space fills @height, @width, @bpp and @flags. If the IOCTL succeeds, | 1075 | * User-space fills @height, @width, @bpp and @flags. If the IOCTL succeeds, |
| 1076 | * the kernel fills @handle, @pitch and @size. | 1076 | * the kernel fills @handle, @pitch and @size. |
| 1077 | * | ||
| 1078 | * The value of @bpp is a color-mode number describing a specific format | ||
| 1079 | * or a variant thereof. The value often corresponds to the number of bits | ||
| 1080 | * per pixel for most modes, although there are exceptions. Each color mode | ||
| 1081 | * maps to a DRM format plus a number of modes with similar pixel layout. | ||
| 1082 | * Framebuffer layout is always linear. | ||
| 1083 | * | ||
| 1084 | * Support for all modes and formats is optional. Even if dumb-buffer | ||
| 1085 | * creation with a certain color mode succeeds, it is not guaranteed that | ||
| 1086 | * the DRM driver supports any of the related formats. Most drivers support | ||
| 1087 | * a color mode of 32 with a format of DRM_FORMAT_XRGB8888 on their primary | ||
| 1088 | * plane. | ||
| 1089 | * | ||
| 1090 | * +------------+------------------------+------------------------+ | ||
| 1091 | * | Color mode | Framebuffer format | Compatible formats | | ||
| 1092 | * +============+========================+========================+ | ||
| 1093 | * | 32 | * DRM_FORMAT_XRGB8888 | * DRM_FORMAT_BGRX8888 | | ||
| 1094 | * | | | * DRM_FORMAT_RGBX8888 | | ||
| 1095 | * | | | * DRM_FORMAT_XBGR8888 | | ||
| 1096 | * +------------+------------------------+------------------------+ | ||
| 1097 | * | 24 | * DRM_FORMAT_RGB888 | * DRM_FORMAT_BGR888 | | ||
| 1098 | * +------------+------------------------+------------------------+ | ||
| 1099 | * | 16 | * DRM_FORMAT_RGB565 | * DRM_FORMAT_BGR565 | | ||
| 1100 | * +------------+------------------------+------------------------+ | ||
| 1101 | * | 15 | * DRM_FORMAT_XRGB1555 | * DRM_FORMAT_BGRX1555 | | ||
| 1102 | * | | | * DRM_FORMAT_RGBX1555 | | ||
| 1103 | * | | | * DRM_FORMAT_XBGR1555 | | ||
| 1104 | * +------------+------------------------+------------------------+ | ||
| 1105 | * | 8 | * DRM_FORMAT_C8 | * DRM_FORMAT_D8 | | ||
| 1106 | * | | | * DRM_FORMAT_R8 | | ||
| 1107 | * +------------+------------------------+------------------------+ | ||
| 1108 | * | 4 | * DRM_FORMAT_C4 | * DRM_FORMAT_D4 | | ||
| 1109 | * | | | * DRM_FORMAT_R4 | | ||
| 1110 | * +------------+------------------------+------------------------+ | ||
| 1111 | * | 2 | * DRM_FORMAT_C2 | * DRM_FORMAT_D2 | | ||
| 1112 | * | | | * DRM_FORMAT_R2 | | ||
| 1113 | * +------------+------------------------+------------------------+ | ||
| 1114 | * | 1 | * DRM_FORMAT_C1 | * DRM_FORMAT_D1 | | ||
| 1115 | * | | | * DRM_FORMAT_R1 | | ||
| 1116 | * +------------+------------------------+------------------------+ | ||
| 1117 | * | ||
| 1118 | * Color modes of 10, 12, 15, 30 and 64 are only supported for use by | ||
| 1119 | * legacy user space. Please don't use them in new code. Other modes | ||
| 1120 | * are not support. | ||
| 1121 | * | ||
| 1122 | * Do not attempt to allocate anything but linear framebuffer memory | ||
| 1123 | * with single-plane RGB data. Allocation of other framebuffer | ||
| 1124 | * layouts requires dedicated ioctls in the respective DRM driver. | ||
| 1077 | */ | 1125 | */ |
| 1078 | struct drm_mode_create_dumb { | 1126 | struct drm_mode_create_dumb { |
| 1079 | __u32 height; | 1127 | __u32 height; |