1 /* 2 * Copyright (c) 2016 Intel Corporation 3 * 4 * Permission to use, copy, modify, distribute, and sell this software and its 5 * documentation for any purpose is hereby granted without fee, provided that 6 * the above copyright notice appear in all copies and that both that copyright 7 * notice and this permission notice appear in supporting documentation, and 8 * that the name of the copyright holders not be used in advertising or 9 * publicity pertaining to distribution of the software without specific, 10 * written prior permission. The copyright holders make no representations 11 * about the suitability of this software for any purpose. It is provided "as 12 * is" without express or implied warranty. 13 * 14 * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 15 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO 16 * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR 17 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, 18 * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER 19 * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 20 * OF THIS SOFTWARE. 21 */ 22 23 #ifndef __DRM_BRIDGE_H__ 24 #define __DRM_BRIDGE_H__ 25 26 #include <linux/list.h> 27 #include <linux/ctype.h> 28 #include <drm/drm_mode_object.h> 29 #include <drm/drm_modes.h> 30 31 struct drm_bridge; 32 struct drm_bridge_timings; 33 struct drm_panel; 34 35 /** 36 * struct drm_bridge_funcs - drm_bridge control functions 37 */ 38 struct drm_bridge_funcs { 39 /** 40 * @attach: 41 * 42 * This callback is invoked whenever our bridge is being attached to a 43 * &drm_encoder. 44 * 45 * The attach callback is optional. 46 * 47 * RETURNS: 48 * 49 * Zero on success, error code on failure. 50 */ 51 int (*attach)(struct drm_bridge *bridge); 52 53 /** 54 * @detach: 55 * 56 * This callback is invoked whenever our bridge is being detached from a 57 * &drm_encoder. 58 * 59 * The detach callback is optional. 60 */ 61 void (*detach)(struct drm_bridge *bridge); 62 63 /** 64 * @mode_valid: 65 * 66 * This callback is used to check if a specific mode is valid in this 67 * bridge. This should be implemented if the bridge has some sort of 68 * restriction in the modes it can display. For example, a given bridge 69 * may be responsible to set a clock value. If the clock can not 70 * produce all the values for the available modes then this callback 71 * can be used to restrict the number of modes to only the ones that 72 * can be displayed. 73 * 74 * This hook is used by the probe helpers to filter the mode list in 75 * drm_helper_probe_single_connector_modes(), and it is used by the 76 * atomic helpers to validate modes supplied by userspace in 77 * drm_atomic_helper_check_modeset(). 78 * 79 * This function is optional. 80 * 81 * NOTE: 82 * 83 * Since this function is both called from the check phase of an atomic 84 * commit, and the mode validation in the probe paths it is not allowed 85 * to look at anything else but the passed-in mode, and validate it 86 * against configuration-invariant hardward constraints. Any further 87 * limits which depend upon the configuration can only be checked in 88 * @mode_fixup. 89 * 90 * RETURNS: 91 * 92 * drm_mode_status Enum 93 */ 94 enum drm_mode_status (*mode_valid)(struct drm_bridge *bridge, 95 const struct drm_display_mode *mode); 96 97 /** 98 * @mode_fixup: 99 * 100 * This callback is used to validate and adjust a mode. The parameter 101 * mode is the display mode that should be fed to the next element in 102 * the display chain, either the final &drm_connector or the next 103 * &drm_bridge. The parameter adjusted_mode is the input mode the bridge 104 * requires. It can be modified by this callback and does not need to 105 * match mode. See also &drm_crtc_state.adjusted_mode for more details. 106 * 107 * This is the only hook that allows a bridge to reject a modeset. If 108 * this function passes all other callbacks must succeed for this 109 * configuration. 110 * 111 * The mode_fixup callback is optional. 112 * 113 * NOTE: 114 * 115 * This function is called in the check phase of atomic modesets, which 116 * can be aborted for any reason (including on userspace's request to 117 * just check whether a configuration would be possible). Drivers MUST 118 * NOT touch any persistent state (hardware or software) or data 119 * structures except the passed in @state parameter. 120 * 121 * Also beware that userspace can request its own custom modes, neither 122 * core nor helpers filter modes to the list of probe modes reported by 123 * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure 124 * that modes are filtered consistently put any bridge constraints and 125 * limits checks into @mode_valid. 126 * 127 * RETURNS: 128 * 129 * True if an acceptable configuration is possible, false if the modeset 130 * operation should be rejected. 131 */ 132 bool (*mode_fixup)(struct drm_bridge *bridge, 133 const struct drm_display_mode *mode, 134 struct drm_display_mode *adjusted_mode); 135 /** 136 * @disable: 137 * 138 * This callback should disable the bridge. It is called right before 139 * the preceding element in the display pipe is disabled. If the 140 * preceding element is a bridge this means it's called before that 141 * bridge's @disable vfunc. If the preceding element is a &drm_encoder 142 * it's called right before the &drm_encoder_helper_funcs.disable, 143 * &drm_encoder_helper_funcs.prepare or &drm_encoder_helper_funcs.dpms 144 * hook. 145 * 146 * The bridge can assume that the display pipe (i.e. clocks and timing 147 * signals) feeding it is still running when this callback is called. 148 * 149 * The disable callback is optional. 150 */ 151 void (*disable)(struct drm_bridge *bridge); 152 153 /** 154 * @post_disable: 155 * 156 * This callback should disable the bridge. It is called right after the 157 * preceding element in the display pipe is disabled. If the preceding 158 * element is a bridge this means it's called after that bridge's 159 * @post_disable function. If the preceding element is a &drm_encoder 160 * it's called right after the encoder's 161 * &drm_encoder_helper_funcs.disable, &drm_encoder_helper_funcs.prepare 162 * or &drm_encoder_helper_funcs.dpms hook. 163 * 164 * The bridge must assume that the display pipe (i.e. clocks and timing 165 * singals) feeding it is no longer running when this callback is 166 * called. 167 * 168 * The post_disable callback is optional. 169 */ 170 void (*post_disable)(struct drm_bridge *bridge); 171 172 /** 173 * @mode_set: 174 * 175 * This callback should set the given mode on the bridge. It is called 176 * after the @mode_set callback for the preceding element in the display 177 * pipeline has been called already. If the bridge is the first element 178 * then this would be &drm_encoder_helper_funcs.mode_set. The display 179 * pipe (i.e. clocks and timing signals) is off when this function is 180 * called. 181 * 182 * The adjusted_mode parameter is the mode output by the CRTC for the 183 * first bridge in the chain. It can be different from the mode 184 * parameter that contains the desired mode for the connector at the end 185 * of the bridges chain, for instance when the first bridge in the chain 186 * performs scaling. The adjusted mode is mostly useful for the first 187 * bridge in the chain and is likely irrelevant for the other bridges. 188 * 189 * For atomic drivers the adjusted_mode is the mode stored in 190 * &drm_crtc_state.adjusted_mode. 191 * 192 * NOTE: 193 * 194 * If a need arises to store and access modes adjusted for other 195 * locations than the connection between the CRTC and the first bridge, 196 * the DRM framework will have to be extended with DRM bridge states. 197 */ 198 void (*mode_set)(struct drm_bridge *bridge, 199 const struct drm_display_mode *mode, 200 const struct drm_display_mode *adjusted_mode); 201 /** 202 * @pre_enable: 203 * 204 * This callback should enable the bridge. It is called right before 205 * the preceding element in the display pipe is enabled. If the 206 * preceding element is a bridge this means it's called before that 207 * bridge's @pre_enable function. If the preceding element is a 208 * &drm_encoder it's called right before the encoder's 209 * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or 210 * &drm_encoder_helper_funcs.dpms hook. 211 * 212 * The display pipe (i.e. clocks and timing signals) feeding this bridge 213 * will not yet be running when this callback is called. The bridge must 214 * not enable the display link feeding the next bridge in the chain (if 215 * there is one) when this callback is called. 216 * 217 * The pre_enable callback is optional. 218 */ 219 void (*pre_enable)(struct drm_bridge *bridge); 220 221 /** 222 * @enable: 223 * 224 * This callback should enable the bridge. It is called right after 225 * the preceding element in the display pipe is enabled. If the 226 * preceding element is a bridge this means it's called after that 227 * bridge's @enable function. If the preceding element is a 228 * &drm_encoder it's called right after the encoder's 229 * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or 230 * &drm_encoder_helper_funcs.dpms hook. 231 * 232 * The bridge can assume that the display pipe (i.e. clocks and timing 233 * signals) feeding it is running when this callback is called. This 234 * callback must enable the display link feeding the next bridge in the 235 * chain if there is one. 236 * 237 * The enable callback is optional. 238 */ 239 void (*enable)(struct drm_bridge *bridge); 240 }; 241 242 /** 243 * struct drm_bridge_timings - timing information for the bridge 244 */ 245 struct drm_bridge_timings { 246 /** 247 * @input_bus_flags: 248 * 249 * Tells what additional settings for the pixel data on the bus 250 * this bridge requires (like pixel signal polarity). See also 251 * &drm_display_info->bus_flags. 252 */ 253 u32 input_bus_flags; 254 /** 255 * @setup_time_ps: 256 * 257 * Defines the time in picoseconds the input data lines must be 258 * stable before the clock edge. 259 */ 260 u32 setup_time_ps; 261 /** 262 * @hold_time_ps: 263 * 264 * Defines the time in picoseconds taken for the bridge to sample the 265 * input signal after the clock edge. 266 */ 267 u32 hold_time_ps; 268 }; 269 270 /** 271 * struct drm_bridge - central DRM bridge control structure 272 */ 273 struct drm_bridge { 274 /** @dev: DRM device this bridge belongs to */ 275 struct drm_device *dev; 276 /** @encoder: encoder to which this bridge is connected */ 277 struct drm_encoder *encoder; 278 /** @next: the next bridge in the encoder chain */ 279 struct drm_bridge *next; 280 #ifdef CONFIG_OF 281 /** @of_node: device node pointer to the bridge */ 282 struct device_node *of_node; 283 #endif 284 /** @list: to keep track of all added bridges */ 285 struct list_head list; 286 /** 287 * @timings: 288 * 289 * the timing specification for the bridge, if any (may be NULL) 290 */ 291 const struct drm_bridge_timings *timings; 292 /** @funcs: control functions */ 293 const struct drm_bridge_funcs *funcs; 294 /** @driver_private: pointer to the bridge driver's internal context */ 295 void *driver_private; 296 }; 297 298 void drm_bridge_add(struct drm_bridge *bridge); 299 void drm_bridge_remove(struct drm_bridge *bridge); 300 struct drm_bridge *of_drm_find_bridge(struct device_node *np); 301 int drm_bridge_attach(struct drm_encoder *encoder, struct drm_bridge *bridge, 302 struct drm_bridge *previous); 303 304 bool drm_bridge_mode_fixup(struct drm_bridge *bridge, 305 const struct drm_display_mode *mode, 306 struct drm_display_mode *adjusted_mode); 307 enum drm_mode_status drm_bridge_mode_valid(struct drm_bridge *bridge, 308 const struct drm_display_mode *mode); 309 void drm_bridge_disable(struct drm_bridge *bridge); 310 void drm_bridge_post_disable(struct drm_bridge *bridge); 311 void drm_bridge_mode_set(struct drm_bridge *bridge, 312 const struct drm_display_mode *mode, 313 const struct drm_display_mode *adjusted_mode); 314 void drm_bridge_pre_enable(struct drm_bridge *bridge); 315 void drm_bridge_enable(struct drm_bridge *bridge); 316 317 #ifdef CONFIG_DRM_PANEL_BRIDGE 318 struct drm_bridge *drm_panel_bridge_add(struct drm_panel *panel, 319 u32 connector_type); 320 void drm_panel_bridge_remove(struct drm_bridge *bridge); 321 struct drm_bridge *devm_drm_panel_bridge_add(struct device *dev, 322 struct drm_panel *panel, 323 u32 connector_type); 324 #endif 325 326 #endif 327