1 /* SPDX-License-Identifier: GPL-2.0-or-later */ 2 /* 3 * Copyright (C) 2016 Noralf Trønnes 4 */ 5 6 #ifndef __LINUX_DRM_SIMPLE_KMS_HELPER_H 7 #define __LINUX_DRM_SIMPLE_KMS_HELPER_H 8 9 #include <drm/drm_crtc.h> 10 #include <drm/drm_encoder.h> 11 #include <drm/drm_plane.h> 12 13 struct drm_simple_display_pipe; 14 15 /** 16 * struct drm_simple_display_pipe_funcs - helper operations for a simple 17 * display pipeline 18 */ 19 struct drm_simple_display_pipe_funcs { 20 /** 21 * @mode_valid: 22 * 23 * This callback is used to check if a specific mode is valid in the 24 * crtc used in this simple display pipe. This should be implemented 25 * if the display pipe has some sort of restriction in the modes 26 * it can display. For example, a given display pipe may be responsible 27 * to set a clock value. If the clock can not produce all the values 28 * for the available modes then this callback can be used to restrict 29 * the number of modes to only the ones that can be displayed. Another 30 * reason can be bandwidth mitigation: the memory port on the display 31 * controller can have bandwidth limitations not allowing pixel data 32 * to be fetched at any rate. 33 * 34 * This hook is used by the probe helpers to filter the mode list in 35 * drm_helper_probe_single_connector_modes(), and it is used by the 36 * atomic helpers to validate modes supplied by userspace in 37 * drm_atomic_helper_check_modeset(). 38 * 39 * This function is optional. 40 * 41 * NOTE: 42 * 43 * Since this function is both called from the check phase of an atomic 44 * commit, and the mode validation in the probe paths it is not allowed 45 * to look at anything else but the passed-in mode, and validate it 46 * against configuration-invariant hardware constraints. 47 * 48 * RETURNS: 49 * 50 * drm_mode_status Enum 51 */ 52 enum drm_mode_status (*mode_valid)(struct drm_simple_display_pipe *pipe, 53 const struct drm_display_mode *mode); 54 55 /** 56 * @enable: 57 * 58 * This function should be used to enable the pipeline. 59 * It is called when the underlying crtc is enabled. 60 * This hook is optional. 61 */ 62 void (*enable)(struct drm_simple_display_pipe *pipe, 63 struct drm_crtc_state *crtc_state, 64 struct drm_plane_state *plane_state); 65 /** 66 * @disable: 67 * 68 * This function should be used to disable the pipeline. 69 * It is called when the underlying crtc is disabled. 70 * This hook is optional. 71 */ 72 void (*disable)(struct drm_simple_display_pipe *pipe); 73 74 /** 75 * @check: 76 * 77 * This function is called in the check phase of an atomic update, 78 * specifically when the underlying plane is checked. 79 * The simple display pipeline helpers already check that the plane is 80 * not scaled, fills the entire visible area and is always enabled 81 * when the crtc is also enabled. 82 * This hook is optional. 83 * 84 * RETURNS: 85 * 86 * 0 on success, -EINVAL if the state or the transition can't be 87 * supported, -ENOMEM on memory allocation failure and -EDEADLK if an 88 * attempt to obtain another state object ran into a &drm_modeset_lock 89 * deadlock. 90 */ 91 int (*check)(struct drm_simple_display_pipe *pipe, 92 struct drm_plane_state *plane_state, 93 struct drm_crtc_state *crtc_state); 94 /** 95 * @update: 96 * 97 * This function is called when the underlying plane state is updated. 98 * This hook is optional. 99 * 100 * This is the function drivers should submit the 101 * &drm_pending_vblank_event from. Using either 102 * drm_crtc_arm_vblank_event(), when the driver supports vblank 103 * interrupt handling, or drm_crtc_send_vblank_event() for more 104 * complex case. In case the hardware lacks vblank support entirely, 105 * drivers can set &struct drm_crtc_state.no_vblank in 106 * &struct drm_simple_display_pipe_funcs.check and let DRM's 107 * atomic helper fake a vblank event. 108 */ 109 void (*update)(struct drm_simple_display_pipe *pipe, 110 struct drm_plane_state *old_plane_state); 111 112 /** 113 * @prepare_fb: 114 * 115 * Optional, called by &drm_plane_helper_funcs.prepare_fb. Please read 116 * the documentation for the &drm_plane_helper_funcs.prepare_fb hook for 117 * more details. 118 * 119 * For GEM drivers who neither have a @prepare_fb nor @cleanup_fb hook 120 * set drm_gem_simple_display_pipe_prepare_fb() is called automatically 121 * to implement this. Other drivers which need additional plane 122 * processing can call drm_gem_simple_display_pipe_prepare_fb() from 123 * their @prepare_fb hook. 124 */ 125 int (*prepare_fb)(struct drm_simple_display_pipe *pipe, 126 struct drm_plane_state *plane_state); 127 128 /** 129 * @cleanup_fb: 130 * 131 * Optional, called by &drm_plane_helper_funcs.cleanup_fb. Please read 132 * the documentation for the &drm_plane_helper_funcs.cleanup_fb hook for 133 * more details. 134 */ 135 void (*cleanup_fb)(struct drm_simple_display_pipe *pipe, 136 struct drm_plane_state *plane_state); 137 138 /** 139 * @begin_fb_access: 140 * 141 * Optional, called by &drm_plane_helper_funcs.begin_fb_access. Please read 142 * the documentation for the &drm_plane_helper_funcs.begin_fb_access hook for 143 * more details. 144 */ 145 int (*begin_fb_access)(struct drm_simple_display_pipe *pipe, 146 struct drm_plane_state *new_plane_state); 147 148 /** 149 * @end_fb_access: 150 * 151 * Optional, called by &drm_plane_helper_funcs.end_fb_access. Please read 152 * the documentation for the &drm_plane_helper_funcs.end_fb_access hook for 153 * more details. 154 */ 155 void (*end_fb_access)(struct drm_simple_display_pipe *pipe, 156 struct drm_plane_state *plane_state); 157 158 /** 159 * @enable_vblank: 160 * 161 * Optional, called by &drm_crtc_funcs.enable_vblank. Please read 162 * the documentation for the &drm_crtc_funcs.enable_vblank hook for 163 * more details. 164 */ 165 int (*enable_vblank)(struct drm_simple_display_pipe *pipe); 166 167 /** 168 * @disable_vblank: 169 * 170 * Optional, called by &drm_crtc_funcs.disable_vblank. Please read 171 * the documentation for the &drm_crtc_funcs.disable_vblank hook for 172 * more details. 173 */ 174 void (*disable_vblank)(struct drm_simple_display_pipe *pipe); 175 176 /** 177 * @reset_crtc: 178 * 179 * Optional, called by &drm_crtc_funcs.reset. Please read the 180 * documentation for the &drm_crtc_funcs.reset hook for more details. 181 */ 182 void (*reset_crtc)(struct drm_simple_display_pipe *pipe); 183 184 /** 185 * @duplicate_crtc_state: 186 * 187 * Optional, called by &drm_crtc_funcs.atomic_duplicate_state. Please 188 * read the documentation for the &drm_crtc_funcs.atomic_duplicate_state 189 * hook for more details. 190 */ 191 struct drm_crtc_state * (*duplicate_crtc_state)(struct drm_simple_display_pipe *pipe); 192 193 /** 194 * @destroy_crtc_state: 195 * 196 * Optional, called by &drm_crtc_funcs.atomic_destroy_state. Please 197 * read the documentation for the &drm_crtc_funcs.atomic_destroy_state 198 * hook for more details. 199 */ 200 void (*destroy_crtc_state)(struct drm_simple_display_pipe *pipe, 201 struct drm_crtc_state *crtc_state); 202 203 /** 204 * @reset_plane: 205 * 206 * Optional, called by &drm_plane_funcs.reset. Please read the 207 * documentation for the &drm_plane_funcs.reset hook for more details. 208 */ 209 void (*reset_plane)(struct drm_simple_display_pipe *pipe); 210 211 /** 212 * @duplicate_plane_state: 213 * 214 * Optional, called by &drm_plane_funcs.atomic_duplicate_state. Please 215 * read the documentation for the &drm_plane_funcs.atomic_duplicate_state 216 * hook for more details. 217 */ 218 struct drm_plane_state * (*duplicate_plane_state)(struct drm_simple_display_pipe *pipe); 219 220 /** 221 * @destroy_plane_state: 222 * 223 * Optional, called by &drm_plane_funcs.atomic_destroy_state. Please 224 * read the documentation for the &drm_plane_funcs.atomic_destroy_state 225 * hook for more details. 226 */ 227 void (*destroy_plane_state)(struct drm_simple_display_pipe *pipe, 228 struct drm_plane_state *plane_state); 229 }; 230 231 /** 232 * struct drm_simple_display_pipe - simple display pipeline 233 * @crtc: CRTC control structure 234 * @plane: Plane control structure 235 * @encoder: Encoder control structure 236 * @connector: Connector control structure 237 * @funcs: Pipeline control functions (optional) 238 * 239 * Simple display pipeline with plane, crtc and encoder collapsed into one 240 * entity. It should be initialized by calling drm_simple_display_pipe_init(). 241 */ 242 struct drm_simple_display_pipe { 243 struct drm_crtc crtc; 244 struct drm_plane plane; 245 struct drm_encoder encoder; 246 struct drm_connector *connector; 247 248 const struct drm_simple_display_pipe_funcs *funcs; 249 }; 250 251 int drm_simple_display_pipe_attach_bridge(struct drm_simple_display_pipe *pipe, 252 struct drm_bridge *bridge); 253 254 int drm_simple_display_pipe_init(struct drm_device *dev, 255 struct drm_simple_display_pipe *pipe, 256 const struct drm_simple_display_pipe_funcs *funcs, 257 const uint32_t *formats, unsigned int format_count, 258 const uint64_t *format_modifiers, 259 struct drm_connector *connector); 260 261 int drm_simple_encoder_init(struct drm_device *dev, 262 struct drm_encoder *encoder, 263 int encoder_type); 264 265 void *__drmm_simple_encoder_alloc(struct drm_device *dev, size_t size, 266 size_t offset, int encoder_type); 267 268 /** 269 * drmm_simple_encoder_alloc - Allocate and initialize an encoder with basic 270 * functionality. 271 * @dev: drm device 272 * @type: the type of the struct which contains struct &drm_encoder 273 * @member: the name of the &drm_encoder within @type. 274 * @encoder_type: user visible type of the encoder 275 * 276 * Allocates and initializes an encoder that has no further functionality. 277 * Settings for possible CRTC and clones are left to their initial values. 278 * Cleanup is automatically handled through registering drm_encoder_cleanup() 279 * with drmm_add_action(). 280 * 281 * Returns: 282 * Pointer to new encoder, or ERR_PTR on failure. 283 */ 284 #define drmm_simple_encoder_alloc(dev, type, member, encoder_type) \ 285 ((type *)__drmm_simple_encoder_alloc(dev, sizeof(type), \ 286 offsetof(type, member), \ 287 encoder_type)) 288 289 #endif /* __LINUX_DRM_SIMPLE_KMS_HELPER_H */ 290