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_mode_object.h>
  29 #include <drm/drm_modes.h>
  30
  31 struct drm_bridge;
  32
  33 /**
  34  * struct drm_bridge_funcs - drm_bridge control functions
  35  */
  36 struct drm_bridge_funcs {
  37         /**
  38          * @attach:
  39          *
  40          * This callback is invoked whenever our bridge is being attached to a
  41          * &drm_encoder.
  42          *
  43          * The attach callback is optional.
  44          *
  45          * RETURNS:
  46          *
  47          * Zero on success, error code on failure.
  48          */
  49         int (*attach)(struct drm_bridge *bridge);
  50
  51         /**
  52          * @detach:
  53          *
  54          * This callback is invoked whenever our bridge is being detached from a
  55          * &drm_encoder.
  56          *
  57          * The detach callback is optional.
  58          */
  59         void (*detach)(struct drm_bridge *bridge);
  60
  61         /**
  62          * @mode_valid:
  63          *
  64          * This callback is used to check if a specific mode is valid in this
  65          * bridge. This should be implemented if the bridge has some sort of
  66          * restriction in the modes it can display. For example, a given bridge
  67          * may be responsible to set a clock value. If the clock can not
  68          * produce all the values for the available modes then this callback
  69          * can be used to restrict the number of modes to only the ones that
  70          * can be displayed.
  71          *
  72          * This hook is used by the probe helpers to filter the mode list in
  73          * drm_helper_probe_single_connector_modes(), and it is used by the
  74          * atomic helpers to validate modes supplied by userspace in
  75          * drm_atomic_helper_check_modeset().
  76          *
  77          * This function is optional.
  78          *
  79          * NOTE:
  80          *
  81          * Since this function is both called from the check phase of an atomic
  82          * commit, and the mode validation in the probe paths it is not allowed
  83          * to look at anything else but the passed-in mode, and validate it
  84          * against configuration-invariant hardward constraints. Any further
  85          * limits which depend upon the configuration can only be checked in
  86          * @mode_fixup.
  87          *
  88          * RETURNS:
  89          *
  90          * drm_mode_status Enum
  91          */
  92         enum drm_mode_status (*mode_valid)(struct drm_bridge *crtc,
  93                                            const struct drm_display_mode *mode);
  94
  95         /**
  96          * @mode_fixup:
  97          *
  98          * This callback is used to validate and adjust a mode. The paramater
  99          * mode is the display mode that should be fed to the next element in
 100          * the display chain, either the final &drm_connector or the next
 101          * &drm_bridge. The parameter adjusted_mode is the input mode the bridge
 102          * requires. It can be modified by this callback and does not need to
 103          * match mode.
 104          *
 105          * This is the only hook that allows a bridge to reject a modeset. If
 106          * this function passes all other callbacks must succeed for this
 107          * configuration.
 108          *
 109          * The mode_fixup callback is optional.
 110          *
 111          * NOTE:
 112          *
 113          * This function is called in the check phase of atomic modesets, which
 114          * can be aborted for any reason (including on userspace's request to
 115          * just check whether a configuration would be possible). Drivers MUST
 116          * NOT touch any persistent state (hardware or software) or data
 117          * structures except the passed in @state parameter.
 118          *
 119          * Also beware that userspace can request its own custom modes, neither
 120          * core nor helpers filter modes to the list of probe modes reported by
 121          * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure
 122          * that modes are filtered consistently put any bridge constraints and
 123          * limits checks into @mode_valid.
 124          *
 125          * RETURNS:
 126          *
 127          * True if an acceptable configuration is possible, false if the modeset
 128          * operation should be rejected.
 129          */
 130         bool (*mode_fixup)(struct drm_bridge *bridge,
 131                            const struct drm_display_mode *mode,
 132                            struct drm_display_mode *adjusted_mode);
 133         /**
 134          * @disable:
 135          *
 136          * This callback should disable the bridge. It is called right before
 137          * the preceding element in the display pipe is disabled. If the
 138          * preceding element is a bridge this means it's called before that
 139          * bridge's @disable vfunc. If the preceding element is a &drm_encoder
 140          * it's called right before the &drm_encoder_helper_funcs.disable,
 141          * &drm_encoder_helper_funcs.prepare or &drm_encoder_helper_funcs.dpms
 142          * hook.
 143          *
 144          * The bridge can assume that the display pipe (i.e. clocks and timing
 145          * signals) feeding it is still running when this callback is called.
 146          *
 147          * The disable callback is optional.
 148          */
 149         void (*disable)(struct drm_bridge *bridge);
 150
 151         /**
 152          * @post_disable:
 153          *
 154          * This callback should disable the bridge. It is called right after the
 155          * preceding element in the display pipe is disabled. If the preceding
 156          * element is a bridge this means it's called after that bridge's
 157          * @post_disable function. If the preceding element is a &drm_encoder
 158          * it's called right after the encoder's
 159          * &drm_encoder_helper_funcs.disable, &drm_encoder_helper_funcs.prepare
 160          * or &drm_encoder_helper_funcs.dpms hook.
 161          *
 162          * The bridge must assume that the display pipe (i.e. clocks and timing
 163          * singals) feeding it is no longer running when this callback is
 164          * called.
 165          *
 166          * The post_disable callback is optional.
 167          */
 168         void (*post_disable)(struct drm_bridge *bridge);
 169
 170         /**
 171          * @mode_set:
 172          *
 173          * This callback should set the given mode on the bridge. It is called
 174          * after the @mode_set callback for the preceding element in the display
 175          * pipeline has been called already. If the bridge is the first element
 176          * then this would be &drm_encoder_helper_funcs.mode_set. The display
 177          * pipe (i.e.  clocks and timing signals) is off when this function is
 178          * called.
 179          */
 180         void (*mode_set)(struct drm_bridge *bridge,
 181                          struct drm_display_mode *mode,
 182                          struct drm_display_mode *adjusted_mode);
 183         /**
 184          * @pre_enable:
 185          *
 186          * This callback should enable the bridge. It is called right before
 187          * the preceding element in the display pipe is enabled. If the
 188          * preceding element is a bridge this means it's called before that
 189          * bridge's @pre_enable function. If the preceding element is a
 190          * &drm_encoder it's called right before the encoder's
 191          * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or
 192          * &drm_encoder_helper_funcs.dpms hook.
 193          *
 194          * The display pipe (i.e. clocks and timing signals) feeding this bridge
 195          * will not yet be running when this callback is called. The bridge must
 196          * not enable the display link feeding the next bridge in the chain (if
 197          * there is one) when this callback is called.
 198          *
 199          * The pre_enable callback is optional.
 200          */
 201         void (*pre_enable)(struct drm_bridge *bridge);
 202
 203         /**
 204          * @enable:
 205          *
 206          * This callback should enable the bridge. It is called right after
 207          * the preceding element in the display pipe is enabled. If the
 208          * preceding element is a bridge this means it's called after that
 209          * bridge's @enable function. If the preceding element is a
 210          * &drm_encoder it's called right after the encoder's
 211          * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or
 212          * &drm_encoder_helper_funcs.dpms hook.
 213          *
 214          * The bridge can assume that the display pipe (i.e. clocks and timing
 215          * signals) feeding it is running when this callback is called. This
 216          * callback must enable the display link feeding the next bridge in the
 217          * chain if there is one.
 218          *
 219          * The enable callback is optional.
 220          */
 221         void (*enable)(struct drm_bridge *bridge);
 222 };
 223
 224 /**
 225  * struct drm_bridge - central DRM bridge control structure
 226  * @dev: DRM device this bridge belongs to
 227  * @encoder: encoder to which this bridge is connected
 228  * @next: the next bridge in the encoder chain
 229  * @of_node: device node pointer to the bridge
 230  * @list: to keep track of all added bridges
 231  * @funcs: control functions
 232  * @driver_private: pointer to the bridge driver's internal context
 233  */
 234 struct drm_bridge {
 235         struct drm_device *dev;
 236         struct drm_encoder *encoder;
 237         struct drm_bridge *next;
 238 #ifdef CONFIG_OF
 239         struct device_node *of_node;
 240 #endif
 241         struct list_head list;
 242
 243         const struct drm_bridge_funcs *funcs;
 244         void *driver_private;
 245 };
 246
 247 int drm_bridge_add(struct drm_bridge *bridge);
 248 void drm_bridge_remove(struct drm_bridge *bridge);
 249 struct drm_bridge *of_drm_find_bridge(struct device_node *np);
 250 int drm_bridge_attach(struct drm_encoder *encoder, struct drm_bridge *bridge,
 251                       struct drm_bridge *previous);
 252
 253 bool drm_bridge_mode_fixup(struct drm_bridge *bridge,
 254                         const struct drm_display_mode *mode,
 255                         struct drm_display_mode *adjusted_mode);
 256 void drm_bridge_disable(struct drm_bridge *bridge);
 257 void drm_bridge_post_disable(struct drm_bridge *bridge);
 258 void drm_bridge_mode_set(struct drm_bridge *bridge,
 259                         struct drm_display_mode *mode,
 260                         struct drm_display_mode *adjusted_mode);
 261 void drm_bridge_pre_enable(struct drm_bridge *bridge);
 262 void drm_bridge_enable(struct drm_bridge *bridge);
 263
 264 #endif