1 /* $NetBSD: drm_bridge.h,v 1.2 2021/12/18 23:45:45 riastradh Exp $ */ 2 3 /* 4 * Copyright (c) 2016 Intel Corporation 5 * 6 * Permission to use, copy, modify, distribute, and sell this software and its 7 * documentation for any purpose is hereby granted without fee, provided that 8 * the above copyright notice appear in all copies and that both that copyright 9 * notice and this permission notice appear in supporting documentation, and 10 * that the name of the copyright holders not be used in advertising or 11 * publicity pertaining to distribution of the software without specific, 12 * written prior permission. The copyright holders make no representations 13 * about the suitability of this software for any purpose. It is provided "as 14 * is" without express or implied warranty. 15 * 16 * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 17 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO 18 * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR 19 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, 20 * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER 21 * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 22 * OF THIS SOFTWARE. 23 */ 24 25 #ifndef __DRM_BRIDGE_H__ 26 #define __DRM_BRIDGE_H__ 27 28 #include <linux/list.h> 29 #include <linux/ctype.h> 30 #include <drm/drm_encoder.h> 31 #include <drm/drm_mode_object.h> 32 #include <drm/drm_modes.h> 33 34 struct drm_bridge; 35 struct drm_bridge_timings; 36 struct drm_panel; 37 38 /** 39 * struct drm_bridge_funcs - drm_bridge control functions 40 */ 41 struct drm_bridge_funcs { 42 /** 43 * @attach: 44 * 45 * This callback is invoked whenever our bridge is being attached to a 46 * &drm_encoder. 47 * 48 * The @attach callback is optional. 49 * 50 * RETURNS: 51 * 52 * Zero on success, error code on failure. 53 */ 54 int (*attach)(struct drm_bridge *bridge); 55 56 /** 57 * @detach: 58 * 59 * This callback is invoked whenever our bridge is being detached from a 60 * &drm_encoder. 61 * 62 * The @detach callback is optional. 63 */ 64 void (*detach)(struct drm_bridge *bridge); 65 66 /** 67 * @mode_valid: 68 * 69 * This callback is used to check if a specific mode is valid in this 70 * bridge. This should be implemented if the bridge has some sort of 71 * restriction in the modes it can display. For example, a given bridge 72 * may be responsible to set a clock value. If the clock can not 73 * produce all the values for the available modes then this callback 74 * can be used to restrict the number of modes to only the ones that 75 * can be displayed. 76 * 77 * This hook is used by the probe helpers to filter the mode list in 78 * drm_helper_probe_single_connector_modes(), and it is used by the 79 * atomic helpers to validate modes supplied by userspace in 80 * drm_atomic_helper_check_modeset(). 81 * 82 * The @mode_valid callback is optional. 83 * 84 * NOTE: 85 * 86 * Since this function is both called from the check phase of an atomic 87 * commit, and the mode validation in the probe paths it is not allowed 88 * to look at anything else but the passed-in mode, and validate it 89 * against configuration-invariant hardward constraints. Any further 90 * limits which depend upon the configuration can only be checked in 91 * @mode_fixup. 92 * 93 * RETURNS: 94 * 95 * drm_mode_status Enum 96 */ 97 enum drm_mode_status (*mode_valid)(struct drm_bridge *bridge, 98 const struct drm_display_mode *mode); 99 100 /** 101 * @mode_fixup: 102 * 103 * This callback is used to validate and adjust a mode. The parameter 104 * mode is the display mode that should be fed to the next element in 105 * the display chain, either the final &drm_connector or the next 106 * &drm_bridge. The parameter adjusted_mode is the input mode the bridge 107 * requires. It can be modified by this callback and does not need to 108 * match mode. See also &drm_crtc_state.adjusted_mode for more details. 109 * 110 * This is the only hook that allows a bridge to reject a modeset. If 111 * this function passes all other callbacks must succeed for this 112 * configuration. 113 * 114 * The @mode_fixup callback is optional. 115 * 116 * NOTE: 117 * 118 * This function is called in the check phase of atomic modesets, which 119 * can be aborted for any reason (including on userspace's request to 120 * just check whether a configuration would be possible). Drivers MUST 121 * NOT touch any persistent state (hardware or software) or data 122 * structures except the passed in @state parameter. 123 * 124 * Also beware that userspace can request its own custom modes, neither 125 * core nor helpers filter modes to the list of probe modes reported by 126 * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure 127 * that modes are filtered consistently put any bridge constraints and 128 * limits checks into @mode_valid. 129 * 130 * RETURNS: 131 * 132 * True if an acceptable configuration is possible, false if the modeset 133 * operation should be rejected. 134 */ 135 bool (*mode_fixup)(struct drm_bridge *bridge, 136 const struct drm_display_mode *mode, 137 struct drm_display_mode *adjusted_mode); 138 /** 139 * @disable: 140 * 141 * This callback should disable the bridge. It is called right before 142 * the preceding element in the display pipe is disabled. If the 143 * preceding element is a bridge this means it's called before that 144 * bridge's @disable vfunc. If the preceding element is a &drm_encoder 145 * it's called right before the &drm_encoder_helper_funcs.disable, 146 * &drm_encoder_helper_funcs.prepare or &drm_encoder_helper_funcs.dpms 147 * hook. 148 * 149 * The bridge can assume that the display pipe (i.e. clocks and timing 150 * signals) feeding it is still running when this callback is called. 151 * 152 * The @disable callback is optional. 153 */ 154 void (*disable)(struct drm_bridge *bridge); 155 156 /** 157 * @post_disable: 158 * 159 * This callback should disable the bridge. It is called right after the 160 * preceding element in the display pipe is disabled. If the preceding 161 * element is a bridge this means it's called after that bridge's 162 * @post_disable function. If the preceding element is a &drm_encoder 163 * it's called right after the encoder's 164 * &drm_encoder_helper_funcs.disable, &drm_encoder_helper_funcs.prepare 165 * or &drm_encoder_helper_funcs.dpms hook. 166 * 167 * The bridge must assume that the display pipe (i.e. clocks and timing 168 * singals) feeding it is no longer running when this callback is 169 * called. 170 * 171 * The @post_disable callback is optional. 172 */ 173 void (*post_disable)(struct drm_bridge *bridge); 174 175 /** 176 * @mode_set: 177 * 178 * This callback should set the given mode on the bridge. It is called 179 * after the @mode_set callback for the preceding element in the display 180 * pipeline has been called already. If the bridge is the first element 181 * then this would be &drm_encoder_helper_funcs.mode_set. The display 182 * pipe (i.e. clocks and timing signals) is off when this function is 183 * called. 184 * 185 * The adjusted_mode parameter is the mode output by the CRTC for the 186 * first bridge in the chain. It can be different from the mode 187 * parameter that contains the desired mode for the connector at the end 188 * of the bridges chain, for instance when the first bridge in the chain 189 * performs scaling. The adjusted mode is mostly useful for the first 190 * bridge in the chain and is likely irrelevant for the other bridges. 191 * 192 * For atomic drivers the adjusted_mode is the mode stored in 193 * &drm_crtc_state.adjusted_mode. 194 * 195 * NOTE: 196 * 197 * If a need arises to store and access modes adjusted for other 198 * locations than the connection between the CRTC and the first bridge, 199 * the DRM framework will have to be extended with DRM bridge states. 200 */ 201 void (*mode_set)(struct drm_bridge *bridge, 202 const struct drm_display_mode *mode, 203 const struct drm_display_mode *adjusted_mode); 204 /** 205 * @pre_enable: 206 * 207 * This callback should enable the bridge. It is called right before 208 * the preceding element in the display pipe is enabled. If the 209 * preceding element is a bridge this means it's called before that 210 * bridge's @pre_enable function. If the preceding element is a 211 * &drm_encoder it's called right before the encoder's 212 * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or 213 * &drm_encoder_helper_funcs.dpms hook. 214 * 215 * The display pipe (i.e. clocks and timing signals) feeding this bridge 216 * will not yet be running when this callback is called. The bridge must 217 * not enable the display link feeding the next bridge in the chain (if 218 * there is one) when this callback is called. 219 * 220 * The @pre_enable callback is optional. 221 */ 222 void (*pre_enable)(struct drm_bridge *bridge); 223 224 /** 225 * @enable: 226 * 227 * This callback should enable the bridge. It is called right after 228 * the preceding element in the display pipe is enabled. If the 229 * preceding element is a bridge this means it's called after that 230 * bridge's @enable function. If the preceding element is a 231 * &drm_encoder it's called right after the encoder's 232 * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or 233 * &drm_encoder_helper_funcs.dpms hook. 234 * 235 * The bridge can assume that the display pipe (i.e. clocks and timing 236 * signals) feeding it is running when this callback is called. This 237 * callback must enable the display link feeding the next bridge in the 238 * chain if there is one. 239 * 240 * The @enable callback is optional. 241 */ 242 void (*enable)(struct drm_bridge *bridge); 243 244 /** 245 * @atomic_pre_enable: 246 * 247 * This callback should enable the bridge. It is called right before 248 * the preceding element in the display pipe is enabled. If the 249 * preceding element is a bridge this means it's called before that 250 * bridge's @atomic_pre_enable or @pre_enable function. If the preceding 251 * element is a &drm_encoder it's called right before the encoder's 252 * &drm_encoder_helper_funcs.atomic_enable hook. 253 * 254 * The display pipe (i.e. clocks and timing signals) feeding this bridge 255 * will not yet be running when this callback is called. The bridge must 256 * not enable the display link feeding the next bridge in the chain (if 257 * there is one) when this callback is called. 258 * 259 * Note that this function will only be invoked in the context of an 260 * atomic commit. It will not be invoked from 261 * &drm_bridge_chain_pre_enable. It would be prudent to also provide an 262 * implementation of @pre_enable if you are expecting driver calls into 263 * &drm_bridge_chain_pre_enable. 264 * 265 * The @atomic_pre_enable callback is optional. 266 */ 267 void (*atomic_pre_enable)(struct drm_bridge *bridge, 268 struct drm_atomic_state *old_state); 269 270 /** 271 * @atomic_enable: 272 * 273 * This callback should enable the bridge. It is called right after 274 * the preceding element in the display pipe is enabled. If the 275 * preceding element is a bridge this means it's called after that 276 * bridge's @atomic_enable or @enable function. If the preceding element 277 * is a &drm_encoder it's called right after the encoder's 278 * &drm_encoder_helper_funcs.atomic_enable hook. 279 * 280 * The bridge can assume that the display pipe (i.e. clocks and timing 281 * signals) feeding it is running when this callback is called. This 282 * callback must enable the display link feeding the next bridge in the 283 * chain if there is one. 284 * 285 * Note that this function will only be invoked in the context of an 286 * atomic commit. It will not be invoked from &drm_bridge_chain_enable. 287 * It would be prudent to also provide an implementation of @enable if 288 * you are expecting driver calls into &drm_bridge_chain_enable. 289 * 290 * The @atomic_enable callback is optional. 291 */ 292 void (*atomic_enable)(struct drm_bridge *bridge, 293 struct drm_atomic_state *old_state); 294 /** 295 * @atomic_disable: 296 * 297 * This callback should disable the bridge. It is called right before 298 * the preceding element in the display pipe is disabled. If the 299 * preceding element is a bridge this means it's called before that 300 * bridge's @atomic_disable or @disable vfunc. If the preceding element 301 * is a &drm_encoder it's called right before the 302 * &drm_encoder_helper_funcs.atomic_disable hook. 303 * 304 * The bridge can assume that the display pipe (i.e. clocks and timing 305 * signals) feeding it is still running when this callback is called. 306 * 307 * Note that this function will only be invoked in the context of an 308 * atomic commit. It will not be invoked from 309 * &drm_bridge_chain_disable. It would be prudent to also provide an 310 * implementation of @disable if you are expecting driver calls into 311 * &drm_bridge_chain_disable. 312 * 313 * The @atomic_disable callback is optional. 314 */ 315 void (*atomic_disable)(struct drm_bridge *bridge, 316 struct drm_atomic_state *old_state); 317 318 /** 319 * @atomic_post_disable: 320 * 321 * This callback should disable the bridge. It is called right after the 322 * preceding element in the display pipe is disabled. If the preceding 323 * element is a bridge this means it's called after that bridge's 324 * @atomic_post_disable or @post_disable function. If the preceding 325 * element is a &drm_encoder it's called right after the encoder's 326 * &drm_encoder_helper_funcs.atomic_disable hook. 327 * 328 * The bridge must assume that the display pipe (i.e. clocks and timing 329 * signals) feeding it is no longer running when this callback is 330 * called. 331 * 332 * Note that this function will only be invoked in the context of an 333 * atomic commit. It will not be invoked from 334 * &drm_bridge_chain_post_disable. 335 * It would be prudent to also provide an implementation of 336 * @post_disable if you are expecting driver calls into 337 * &drm_bridge_chain_post_disable. 338 * 339 * The @atomic_post_disable callback is optional. 340 */ 341 void (*atomic_post_disable)(struct drm_bridge *bridge, 342 struct drm_atomic_state *old_state); 343 }; 344 345 /** 346 * struct drm_bridge_timings - timing information for the bridge 347 */ 348 struct drm_bridge_timings { 349 /** 350 * @input_bus_flags: 351 * 352 * Tells what additional settings for the pixel data on the bus 353 * this bridge requires (like pixel signal polarity). See also 354 * &drm_display_info->bus_flags. 355 */ 356 u32 input_bus_flags; 357 /** 358 * @setup_time_ps: 359 * 360 * Defines the time in picoseconds the input data lines must be 361 * stable before the clock edge. 362 */ 363 u32 setup_time_ps; 364 /** 365 * @hold_time_ps: 366 * 367 * Defines the time in picoseconds taken for the bridge to sample the 368 * input signal after the clock edge. 369 */ 370 u32 hold_time_ps; 371 /** 372 * @dual_link: 373 * 374 * True if the bus operates in dual-link mode. The exact meaning is 375 * dependent on the bus type. For LVDS buses, this indicates that even- 376 * and odd-numbered pixels are received on separate links. 377 */ 378 bool dual_link; 379 }; 380 381 /** 382 * struct drm_bridge - central DRM bridge control structure 383 */ 384 struct drm_bridge { 385 /** @dev: DRM device this bridge belongs to */ 386 struct drm_device *dev; 387 /** @encoder: encoder to which this bridge is connected */ 388 struct drm_encoder *encoder; 389 /** @chain_node: used to form a bridge chain */ 390 struct list_head chain_node; 391 #ifdef CONFIG_OF 392 /** @of_node: device node pointer to the bridge */ 393 struct device_node *of_node; 394 #endif 395 /** @list: to keep track of all added bridges */ 396 struct list_head list; 397 /** 398 * @timings: 399 * 400 * the timing specification for the bridge, if any (may be NULL) 401 */ 402 const struct drm_bridge_timings *timings; 403 /** @funcs: control functions */ 404 const struct drm_bridge_funcs *funcs; 405 /** @driver_private: pointer to the bridge driver's internal context */ 406 void *driver_private; 407 }; 408 409 void drm_bridge_add(struct drm_bridge *bridge); 410 void drm_bridge_remove(struct drm_bridge *bridge); 411 struct drm_bridge *of_drm_find_bridge(struct device_node *np); 412 int drm_bridge_attach(struct drm_encoder *encoder, struct drm_bridge *bridge, 413 struct drm_bridge *previous); 414 415 /** 416 * drm_bridge_get_next_bridge() - Get the next bridge in the chain 417 * @bridge: bridge object 418 * 419 * RETURNS: 420 * the next bridge in the chain after @bridge, or NULL if @bridge is the last. 421 */ 422 static inline struct drm_bridge * 423 drm_bridge_get_next_bridge(struct drm_bridge *bridge) 424 { 425 if (list_is_last(&bridge->chain_node, &bridge->encoder->bridge_chain)) 426 return NULL; 427 428 return list_next_entry(bridge, chain_node); 429 } 430 431 /** 432 * drm_bridge_get_prev_bridge() - Get the previous bridge in the chain 433 * @bridge: bridge object 434 * 435 * RETURNS: 436 * the previous bridge in the chain, or NULL if @bridge is the first. 437 */ 438 static inline struct drm_bridge * 439 drm_bridge_get_prev_bridge(struct drm_bridge *bridge) 440 { 441 if (list_is_first(&bridge->chain_node, &bridge->encoder->bridge_chain)) 442 return NULL; 443 444 return list_prev_entry(bridge, chain_node); 445 } 446 447 /** 448 * drm_bridge_chain_get_first_bridge() - Get the first bridge in the chain 449 * @encoder: encoder object 450 * 451 * RETURNS: 452 * the first bridge in the chain, or NULL if @encoder has no bridge attached 453 * to it. 454 */ 455 static inline struct drm_bridge * 456 drm_bridge_chain_get_first_bridge(struct drm_encoder *encoder) 457 { 458 return list_first_entry_or_null(&encoder->bridge_chain, 459 struct drm_bridge, chain_node); 460 } 461 462 /** 463 * drm_for_each_bridge_in_chain() - Iterate over all bridges present in a chain 464 * @encoder: the encoder to iterate bridges on 465 * @bridge: a bridge pointer updated to point to the current bridge at each 466 * iteration 467 * 468 * Iterate over all bridges present in the bridge chain attached to @encoder. 469 */ 470 #define drm_for_each_bridge_in_chain(encoder, bridge) \ 471 list_for_each_entry(bridge, &(encoder)->bridge_chain, chain_node) 472 473 bool drm_bridge_chain_mode_fixup(struct drm_bridge *bridge, 474 const struct drm_display_mode *mode, 475 struct drm_display_mode *adjusted_mode); 476 enum drm_mode_status 477 drm_bridge_chain_mode_valid(struct drm_bridge *bridge, 478 const struct drm_display_mode *mode); 479 void drm_bridge_chain_disable(struct drm_bridge *bridge); 480 void drm_bridge_chain_post_disable(struct drm_bridge *bridge); 481 void drm_bridge_chain_mode_set(struct drm_bridge *bridge, 482 const struct drm_display_mode *mode, 483 const struct drm_display_mode *adjusted_mode); 484 void drm_bridge_chain_pre_enable(struct drm_bridge *bridge); 485 void drm_bridge_chain_enable(struct drm_bridge *bridge); 486 487 void drm_atomic_bridge_chain_disable(struct drm_bridge *bridge, 488 struct drm_atomic_state *state); 489 void drm_atomic_bridge_chain_post_disable(struct drm_bridge *bridge, 490 struct drm_atomic_state *state); 491 void drm_atomic_bridge_chain_pre_enable(struct drm_bridge *bridge, 492 struct drm_atomic_state *state); 493 void drm_atomic_bridge_chain_enable(struct drm_bridge *bridge, 494 struct drm_atomic_state *state); 495 496 #ifdef CONFIG_DRM_PANEL_BRIDGE 497 struct drm_bridge *drm_panel_bridge_add(struct drm_panel *panel); 498 struct drm_bridge *drm_panel_bridge_add_typed(struct drm_panel *panel, 499 u32 connector_type); 500 void drm_panel_bridge_remove(struct drm_bridge *bridge); 501 struct drm_bridge *devm_drm_panel_bridge_add(struct device *dev, 502 struct drm_panel *panel); 503 struct drm_bridge *devm_drm_panel_bridge_add_typed(struct device *dev, 504 struct drm_panel *panel, 505 u32 connector_type); 506 struct drm_connector *drm_panel_bridge_connector(struct drm_bridge *bridge); 507 #endif 508 509 #ifdef __NetBSD__ 510 extern void drm_bridge_init_lock(void); 511 extern void drm_bridge_fini_lock(void); 512 #endif 513 514 #endif 515