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 * Drivers which always have their buffers pinned should use 120 * drm_gem_simple_display_pipe_prepare_fb() for this hook. 121 */ 122 int (*prepare_fb)(struct drm_simple_display_pipe *pipe, 123 struct drm_plane_state *plane_state); 124 125 /** 126 * @cleanup_fb: 127 * 128 * Optional, called by &drm_plane_helper_funcs.cleanup_fb. Please read 129 * the documentation for the &drm_plane_helper_funcs.cleanup_fb hook for 130 * more details. 131 */ 132 void (*cleanup_fb)(struct drm_simple_display_pipe *pipe, 133 struct drm_plane_state *plane_state); 134 135 /** 136 * @enable_vblank: 137 * 138 * Optional, called by &drm_crtc_funcs.enable_vblank. Please read 139 * the documentation for the &drm_crtc_funcs.enable_vblank hook for 140 * more details. 141 */ 142 int (*enable_vblank)(struct drm_simple_display_pipe *pipe); 143 144 /** 145 * @disable_vblank: 146 * 147 * Optional, called by &drm_crtc_funcs.disable_vblank. Please read 148 * the documentation for the &drm_crtc_funcs.disable_vblank hook for 149 * more details. 150 */ 151 void (*disable_vblank)(struct drm_simple_display_pipe *pipe); 152 153 /** 154 * @reset_plane: 155 * 156 * Optional, called by &drm_plane_funcs.reset. Please read the 157 * documentation for the &drm_plane_funcs.reset hook for more details. 158 */ 159 void (*reset_plane)(struct drm_simple_display_pipe *pipe); 160 161 /** 162 * @duplicate_plane_state: 163 * 164 * Optional, called by &drm_plane_funcs.atomic_duplicate_state. Please 165 * read the documentation for the &drm_plane_funcs.atomic_duplicate_state 166 * hook for more details. 167 */ 168 struct drm_plane_state * (*duplicate_plane_state)(struct drm_simple_display_pipe *pipe); 169 170 /** 171 * @destroy_plane_state: 172 * 173 * Optional, called by &drm_plane_funcs.atomic_destroy_state. Please 174 * read the documentation for the &drm_plane_funcs.atomic_destroy_state 175 * hook for more details. 176 */ 177 void (*destroy_plane_state)(struct drm_simple_display_pipe *pipe, 178 struct drm_plane_state *plane_state); 179 }; 180 181 /** 182 * struct drm_simple_display_pipe - simple display pipeline 183 * @crtc: CRTC control structure 184 * @plane: Plane control structure 185 * @encoder: Encoder control structure 186 * @connector: Connector control structure 187 * @funcs: Pipeline control functions (optional) 188 * 189 * Simple display pipeline with plane, crtc and encoder collapsed into one 190 * entity. It should be initialized by calling drm_simple_display_pipe_init(). 191 */ 192 struct drm_simple_display_pipe { 193 struct drm_crtc crtc; 194 struct drm_plane plane; 195 struct drm_encoder encoder; 196 struct drm_connector *connector; 197 198 const struct drm_simple_display_pipe_funcs *funcs; 199 }; 200 201 int drm_simple_display_pipe_attach_bridge(struct drm_simple_display_pipe *pipe, 202 struct drm_bridge *bridge); 203 204 int drm_simple_display_pipe_init(struct drm_device *dev, 205 struct drm_simple_display_pipe *pipe, 206 const struct drm_simple_display_pipe_funcs *funcs, 207 const uint32_t *formats, unsigned int format_count, 208 const uint64_t *format_modifiers, 209 struct drm_connector *connector); 210 211 int drm_simple_encoder_init(struct drm_device *dev, 212 struct drm_encoder *encoder, 213 int encoder_type); 214 215 void *__drmm_simple_encoder_alloc(struct drm_device *dev, size_t size, 216 size_t offset, int encoder_type); 217 218 /** 219 * drmm_simple_encoder_alloc - Allocate and initialize an encoder with basic 220 * functionality. 221 * @dev: drm device 222 * @type: the type of the struct which contains struct &drm_encoder 223 * @member: the name of the &drm_encoder within @type. 224 * @encoder_type: user visible type of the encoder 225 * 226 * Allocates and initializes an encoder that has no further functionality. 227 * Settings for possible CRTC and clones are left to their initial values. 228 * Cleanup is automatically handled through registering drm_encoder_cleanup() 229 * with drmm_add_action(). 230 * 231 * Returns: 232 * Pointer to new encoder, or ERR_PTR on failure. 233 */ 234 #define drmm_simple_encoder_alloc(dev, type, member, encoder_type) \ 235 ((type *)__drmm_simple_encoder_alloc(dev, sizeof(type), \ 236 offsetof(type, member), \ 237 encoder_type)) 238 239 #endif /* __LINUX_DRM_SIMPLE_KMS_HELPER_H */ 240