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 * The @mode_valid callback 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 * @atomic_pre_enable: 243 * 244 * This callback should enable the bridge. It is called right before 245 * the preceding element in the display pipe is enabled. If the 246 * preceding element is a bridge this means it's called before that 247 * bridge's @atomic_pre_enable or @pre_enable function. If the preceding 248 * element is a &drm_encoder it's called right before the encoder's 249 * &drm_encoder_helper_funcs.atomic_enable hook. 250 * 251 * The display pipe (i.e. clocks and timing signals) feeding this bridge 252 * will not yet be running when this callback is called. The bridge must 253 * not enable the display link feeding the next bridge in the chain (if 254 * there is one) when this callback is called. 255 * 256 * Note that this function will only be invoked in the context of an 257 * atomic commit. It will not be invoked from &drm_bridge_pre_enable. It 258 * would be prudent to also provide an implementation of @pre_enable if 259 * you are expecting driver calls into &drm_bridge_pre_enable. 260 * 261 * The @atomic_pre_enable callback is optional. 262 */ 263 void (*atomic_pre_enable)(struct drm_bridge *bridge, 264 struct drm_atomic_state *state); 265 266 /** 267 * @atomic_enable: 268 * 269 * This callback should enable the bridge. It is called right after 270 * the preceding element in the display pipe is enabled. If the 271 * preceding element is a bridge this means it's called after that 272 * bridge's @atomic_enable or @enable function. If the preceding element 273 * is a &drm_encoder it's called right after the encoder's 274 * &drm_encoder_helper_funcs.atomic_enable hook. 275 * 276 * The bridge can assume that the display pipe (i.e. clocks and timing 277 * signals) feeding it is running when this callback is called. This 278 * callback must enable the display link feeding the next bridge in the 279 * chain if there is one. 280 * 281 * Note that this function will only be invoked in the context of an 282 * atomic commit. It will not be invoked from &drm_bridge_enable. It 283 * would be prudent to also provide an implementation of @enable if 284 * you are expecting driver calls into &drm_bridge_enable. 285 * 286 * The @atomic_enable callback is optional. 287 */ 288 void (*atomic_enable)(struct drm_bridge *bridge, 289 struct drm_atomic_state *state); 290 /** 291 * @atomic_disable: 292 * 293 * This callback should disable the bridge. It is called right before 294 * the preceding element in the display pipe is disabled. If the 295 * preceding element is a bridge this means it's called before that 296 * bridge's @atomic_disable or @disable vfunc. If the preceding element 297 * is a &drm_encoder it's called right before the 298 * &drm_encoder_helper_funcs.atomic_disable hook. 299 * 300 * The bridge can assume that the display pipe (i.e. clocks and timing 301 * signals) feeding it is still running when this callback is called. 302 * 303 * Note that this function will only be invoked in the context of an 304 * atomic commit. It will not be invoked from &drm_bridge_disable. It 305 * would be prudent to also provide an implementation of @disable if 306 * you are expecting driver calls into &drm_bridge_disable. 307 * 308 * The @atomic_disable callback is optional. 309 */ 310 void (*atomic_disable)(struct drm_bridge *bridge, 311 struct drm_atomic_state *state); 312 313 /** 314 * @atomic_post_disable: 315 * 316 * This callback should disable the bridge. It is called right after the 317 * preceding element in the display pipe is disabled. If the preceding 318 * element is a bridge this means it's called after that bridge's 319 * @atomic_post_disable or @post_disable function. If the preceding 320 * element is a &drm_encoder it's called right after the encoder's 321 * &drm_encoder_helper_funcs.atomic_disable hook. 322 * 323 * The bridge must assume that the display pipe (i.e. clocks and timing 324 * signals) feeding it is no longer running when this callback is 325 * called. 326 * 327 * Note that this function will only be invoked in the context of an 328 * atomic commit. It will not be invoked from &drm_bridge_post_disable. 329 * It would be prudent to also provide an implementation of 330 * @post_disable if you are expecting driver calls into 331 * &drm_bridge_post_disable. 332 * 333 * The @atomic_post_disable callback is optional. 334 */ 335 void (*atomic_post_disable)(struct drm_bridge *bridge, 336 struct drm_atomic_state *state); 337 }; 338 339 /** 340 * struct drm_bridge_timings - timing information for the bridge 341 */ 342 struct drm_bridge_timings { 343 /** 344 * @input_bus_flags: 345 * 346 * Tells what additional settings for the pixel data on the bus 347 * this bridge requires (like pixel signal polarity). See also 348 * &drm_display_info->bus_flags. 349 */ 350 u32 input_bus_flags; 351 /** 352 * @setup_time_ps: 353 * 354 * Defines the time in picoseconds the input data lines must be 355 * stable before the clock edge. 356 */ 357 u32 setup_time_ps; 358 /** 359 * @hold_time_ps: 360 * 361 * Defines the time in picoseconds taken for the bridge to sample the 362 * input signal after the clock edge. 363 */ 364 u32 hold_time_ps; 365 /** 366 * @dual_link: 367 * 368 * True if the bus operates in dual-link mode. The exact meaning is 369 * dependent on the bus type. For LVDS buses, this indicates that even- 370 * and odd-numbered pixels are received on separate links. 371 */ 372 bool dual_link; 373 }; 374 375 /** 376 * struct drm_bridge - central DRM bridge control structure 377 */ 378 struct drm_bridge { 379 /** @dev: DRM device this bridge belongs to */ 380 struct drm_device *dev; 381 /** @encoder: encoder to which this bridge is connected */ 382 struct drm_encoder *encoder; 383 /** @next: the next bridge in the encoder chain */ 384 struct drm_bridge *next; 385 #ifdef CONFIG_OF 386 /** @of_node: device node pointer to the bridge */ 387 struct device_node *of_node; 388 #endif 389 /** @list: to keep track of all added bridges */ 390 struct list_head list; 391 /** 392 * @timings: 393 * 394 * the timing specification for the bridge, if any (may be NULL) 395 */ 396 const struct drm_bridge_timings *timings; 397 /** @funcs: control functions */ 398 const struct drm_bridge_funcs *funcs; 399 /** @driver_private: pointer to the bridge driver's internal context */ 400 void *driver_private; 401 }; 402 403 void drm_bridge_add(struct drm_bridge *bridge); 404 void drm_bridge_remove(struct drm_bridge *bridge); 405 struct drm_bridge *of_drm_find_bridge(struct device_node *np); 406 int drm_bridge_attach(struct drm_encoder *encoder, struct drm_bridge *bridge, 407 struct drm_bridge *previous); 408 409 bool drm_bridge_mode_fixup(struct drm_bridge *bridge, 410 const struct drm_display_mode *mode, 411 struct drm_display_mode *adjusted_mode); 412 enum drm_mode_status drm_bridge_mode_valid(struct drm_bridge *bridge, 413 const struct drm_display_mode *mode); 414 void drm_bridge_disable(struct drm_bridge *bridge); 415 void drm_bridge_post_disable(struct drm_bridge *bridge); 416 void drm_bridge_mode_set(struct drm_bridge *bridge, 417 const struct drm_display_mode *mode, 418 const struct drm_display_mode *adjusted_mode); 419 void drm_bridge_pre_enable(struct drm_bridge *bridge); 420 void drm_bridge_enable(struct drm_bridge *bridge); 421 422 void drm_atomic_bridge_disable(struct drm_bridge *bridge, 423 struct drm_atomic_state *state); 424 void drm_atomic_bridge_post_disable(struct drm_bridge *bridge, 425 struct drm_atomic_state *state); 426 void drm_atomic_bridge_pre_enable(struct drm_bridge *bridge, 427 struct drm_atomic_state *state); 428 void drm_atomic_bridge_enable(struct drm_bridge *bridge, 429 struct drm_atomic_state *state); 430 431 #ifdef CONFIG_DRM_PANEL_BRIDGE 432 struct drm_bridge *drm_panel_bridge_add(struct drm_panel *panel); 433 struct drm_bridge *drm_panel_bridge_add_typed(struct drm_panel *panel, 434 u32 connector_type); 435 void drm_panel_bridge_remove(struct drm_bridge *bridge); 436 struct drm_bridge *devm_drm_panel_bridge_add(struct device *dev, 437 struct drm_panel *panel); 438 struct drm_bridge *devm_drm_panel_bridge_add_typed(struct device *dev, 439 struct drm_panel *panel, 440 u32 connector_type); 441 #endif 442 443 #endif 444