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_fb_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 /** 155 * struct drm_simple_display_pipe - simple display pipeline 156 * @crtc: CRTC control structure 157 * @plane: Plane control structure 158 * @encoder: Encoder control structure 159 * @connector: Connector control structure 160 * @funcs: Pipeline control functions (optional) 161 * 162 * Simple display pipeline with plane, crtc and encoder collapsed into one 163 * entity. It should be initialized by calling drm_simple_display_pipe_init(). 164 */ 165 struct drm_simple_display_pipe { 166 struct drm_crtc crtc; 167 struct drm_plane plane; 168 struct drm_encoder encoder; 169 struct drm_connector *connector; 170 171 const struct drm_simple_display_pipe_funcs *funcs; 172 }; 173 174 int drm_simple_display_pipe_attach_bridge(struct drm_simple_display_pipe *pipe, 175 struct drm_bridge *bridge); 176 177 int drm_simple_display_pipe_init(struct drm_device *dev, 178 struct drm_simple_display_pipe *pipe, 179 const struct drm_simple_display_pipe_funcs *funcs, 180 const uint32_t *formats, unsigned int format_count, 181 const uint64_t *format_modifiers, 182 struct drm_connector *connector); 183 184 int drm_simple_encoder_init(struct drm_device *dev, 185 struct drm_encoder *encoder, 186 int encoder_type); 187 188 void *__drmm_simple_encoder_alloc(struct drm_device *dev, size_t size, 189 size_t offset, int encoder_type); 190 191 /** 192 * drmm_simple_encoder_alloc - Allocate and initialize an encoder with basic 193 * functionality. 194 * @dev: drm device 195 * @type: the type of the struct which contains struct &drm_encoder 196 * @member: the name of the &drm_encoder within @type. 197 * @encoder_type: user visible type of the encoder 198 * 199 * Allocates and initializes an encoder that has no further functionality. 200 * Settings for possible CRTC and clones are left to their initial values. 201 * Cleanup is automatically handled through registering drm_encoder_cleanup() 202 * with drmm_add_action(). 203 * 204 * Returns: 205 * Pointer to new encoder, or ERR_PTR on failure. 206 */ 207 #define drmm_simple_encoder_alloc(dev, type, member, encoder_type) \ 208 ((type *)__drmm_simple_encoder_alloc(dev, sizeof(type), \ 209 offsetof(type, member), \ 210 encoder_type)) 211 212 #endif /* __LINUX_DRM_SIMPLE_KMS_HELPER_H */ 213