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 * @enable_vblank: 140 * 141 * Optional, called by &drm_crtc_funcs.enable_vblank. Please read 142 * the documentation for the &drm_crtc_funcs.enable_vblank hook for 143 * more details. 144 */ 145 int (*enable_vblank)(struct drm_simple_display_pipe *pipe); 146 147 /** 148 * @disable_vblank: 149 * 150 * Optional, called by &drm_crtc_funcs.disable_vblank. Please read 151 * the documentation for the &drm_crtc_funcs.disable_vblank hook for 152 * more details. 153 */ 154 void (*disable_vblank)(struct drm_simple_display_pipe *pipe); 155 156 /** 157 * @reset_crtc: 158 * 159 * Optional, called by &drm_crtc_funcs.reset. Please read the 160 * documentation for the &drm_crtc_funcs.reset hook for more details. 161 */ 162 void (*reset_crtc)(struct drm_simple_display_pipe *pipe); 163 164 /** 165 * @duplicate_crtc_state: 166 * 167 * Optional, called by &drm_crtc_funcs.atomic_duplicate_state. Please 168 * read the documentation for the &drm_crtc_funcs.atomic_duplicate_state 169 * hook for more details. 170 */ 171 struct drm_crtc_state * (*duplicate_crtc_state)(struct drm_simple_display_pipe *pipe); 172 173 /** 174 * @destroy_crtc_state: 175 * 176 * Optional, called by &drm_crtc_funcs.atomic_destroy_state. Please 177 * read the documentation for the &drm_crtc_funcs.atomic_destroy_state 178 * hook for more details. 179 */ 180 void (*destroy_crtc_state)(struct drm_simple_display_pipe *pipe, 181 struct drm_crtc_state *crtc_state); 182 183 /** 184 * @reset_plane: 185 * 186 * Optional, called by &drm_plane_funcs.reset. Please read the 187 * documentation for the &drm_plane_funcs.reset hook for more details. 188 */ 189 void (*reset_plane)(struct drm_simple_display_pipe *pipe); 190 191 /** 192 * @duplicate_plane_state: 193 * 194 * Optional, called by &drm_plane_funcs.atomic_duplicate_state. Please 195 * read the documentation for the &drm_plane_funcs.atomic_duplicate_state 196 * hook for more details. 197 */ 198 struct drm_plane_state * (*duplicate_plane_state)(struct drm_simple_display_pipe *pipe); 199 200 /** 201 * @destroy_plane_state: 202 * 203 * Optional, called by &drm_plane_funcs.atomic_destroy_state. Please 204 * read the documentation for the &drm_plane_funcs.atomic_destroy_state 205 * hook for more details. 206 */ 207 void (*destroy_plane_state)(struct drm_simple_display_pipe *pipe, 208 struct drm_plane_state *plane_state); 209 }; 210 211 /** 212 * struct drm_simple_display_pipe - simple display pipeline 213 * @crtc: CRTC control structure 214 * @plane: Plane control structure 215 * @encoder: Encoder control structure 216 * @connector: Connector control structure 217 * @funcs: Pipeline control functions (optional) 218 * 219 * Simple display pipeline with plane, crtc and encoder collapsed into one 220 * entity. It should be initialized by calling drm_simple_display_pipe_init(). 221 */ 222 struct drm_simple_display_pipe { 223 struct drm_crtc crtc; 224 struct drm_plane plane; 225 struct drm_encoder encoder; 226 struct drm_connector *connector; 227 228 const struct drm_simple_display_pipe_funcs *funcs; 229 }; 230 231 int drm_simple_display_pipe_attach_bridge(struct drm_simple_display_pipe *pipe, 232 struct drm_bridge *bridge); 233 234 int drm_simple_display_pipe_init(struct drm_device *dev, 235 struct drm_simple_display_pipe *pipe, 236 const struct drm_simple_display_pipe_funcs *funcs, 237 const uint32_t *formats, unsigned int format_count, 238 const uint64_t *format_modifiers, 239 struct drm_connector *connector); 240 241 int drm_simple_encoder_init(struct drm_device *dev, 242 struct drm_encoder *encoder, 243 int encoder_type); 244 245 void *__drmm_simple_encoder_alloc(struct drm_device *dev, size_t size, 246 size_t offset, int encoder_type); 247 248 /** 249 * drmm_simple_encoder_alloc - Allocate and initialize an encoder with basic 250 * functionality. 251 * @dev: drm device 252 * @type: the type of the struct which contains struct &drm_encoder 253 * @member: the name of the &drm_encoder within @type. 254 * @encoder_type: user visible type of the encoder 255 * 256 * Allocates and initializes an encoder that has no further functionality. 257 * Settings for possible CRTC and clones are left to their initial values. 258 * Cleanup is automatically handled through registering drm_encoder_cleanup() 259 * with drmm_add_action(). 260 * 261 * Returns: 262 * Pointer to new encoder, or ERR_PTR on failure. 263 */ 264 #define drmm_simple_encoder_alloc(dev, type, member, encoder_type) \ 265 ((type *)__drmm_simple_encoder_alloc(dev, sizeof(type), \ 266 offsetof(type, member), \ 267 encoder_type)) 268 269 #endif /* __LINUX_DRM_SIMPLE_KMS_HELPER_H */ 270