include/drm/drm_bridge.h

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