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_fixup:
  63          *
  64          * This callback is used to validate and adjust a mode. The paramater
  65          * mode is the display mode that should be fed to the next element in
  66          * the display chain, either the final &drm_connector or the next
  67          * &drm_bridge. The parameter adjusted_mode is the input mode the bridge
  68          * requires. It can be modified by this callback and does not need to
  69          * match mode.
  70          *
  71          * This is the only hook that allows a bridge to reject a modeset. If
  72          * this function passes all other callbacks must succeed for this
  73          * configuration.
  74          *
  75          * The mode_fixup callback is optional.
  76          *
  77          * NOTE:
  78          *
  79          * This function is called in the check phase of atomic modesets, which
  80          * can be aborted for any reason (including on userspace's request to
  81          * just check whether a configuration would be possible). Drivers MUST
  82          * NOT touch any persistent state (hardware or software) or data
  83          * structures except the passed in @state parameter.
  84          *
  85          * RETURNS:
  86          *
  87          * True if an acceptable configuration is possible, false if the modeset
  88          * operation should be rejected.
  89          */
  90         bool (*mode_fixup)(struct drm_bridge *bridge,
  91                            const struct drm_display_mode *mode,
  92                            struct drm_display_mode *adjusted_mode);
  93         /**
  94          * @disable:
  95          *
  96          * This callback should disable the bridge. It is called right before
  97          * the preceding element in the display pipe is disabled. If the
  98          * preceding element is a bridge this means it's called before that
  99          * bridge's @disable vfunc. If the preceding element is a &drm_encoder
 100          * it's called right before the &drm_encoder_helper_funcs.disable,
 101          * &drm_encoder_helper_funcs.prepare or &drm_encoder_helper_funcs.dpms
 102          * hook.
 103          *
 104          * The bridge can assume that the display pipe (i.e. clocks and timing
 105          * signals) feeding it is still running when this callback is called.
 106          *
 107          * The disable callback is optional.
 108          */
 109         void (*disable)(struct drm_bridge *bridge);
 110
 111         /**
 112          * @post_disable:
 113          *
 114          * This callback should disable the bridge. It is called right after the
 115          * preceding element in the display pipe is disabled. If the preceding
 116          * element is a bridge this means it's called after that bridge's
 117          * @post_disable function. If the preceding element is a &drm_encoder
 118          * it's called right after the encoder's
 119          * &drm_encoder_helper_funcs.disable, &drm_encoder_helper_funcs.prepare
 120          * or &drm_encoder_helper_funcs.dpms hook.
 121          *
 122          * The bridge must assume that the display pipe (i.e. clocks and timing
 123          * singals) feeding it is no longer running when this callback is
 124          * called.
 125          *
 126          * The post_disable callback is optional.
 127          */
 128         void (*post_disable)(struct drm_bridge *bridge);
 129
 130         /**
 131          * @mode_set:
 132          *
 133          * This callback should set the given mode on the bridge. It is called
 134          * after the @mode_set callback for the preceding element in the display
 135          * pipeline has been called already. If the bridge is the first element
 136          * then this would be &drm_encoder_helper_funcs.mode_set. The display
 137          * pipe (i.e.  clocks and timing signals) is off when this function is
 138          * called.
 139          */
 140         void (*mode_set)(struct drm_bridge *bridge,
 141                          struct drm_display_mode *mode,
 142                          struct drm_display_mode *adjusted_mode);
 143         /**
 144          * @pre_enable:
 145          *
 146          * This callback should enable the bridge. It is called right before
 147          * the preceding element in the display pipe is enabled. If the
 148          * preceding element is a bridge this means it's called before that
 149          * bridge's @pre_enable function. If the preceding element is a
 150          * &drm_encoder it's called right before the encoder's
 151          * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or
 152          * &drm_encoder_helper_funcs.dpms hook.
 153          *
 154          * The display pipe (i.e. clocks and timing signals) feeding this bridge
 155          * will not yet be running when this callback is called. The bridge must
 156          * not enable the display link feeding the next bridge in the chain (if
 157          * there is one) when this callback is called.
 158          *
 159          * The pre_enable callback is optional.
 160          */
 161         void (*pre_enable)(struct drm_bridge *bridge);
 162
 163         /**
 164          * @enable:
 165          *
 166          * This callback should enable the bridge. It is called right after
 167          * the preceding element in the display pipe is enabled. If the
 168          * preceding element is a bridge this means it's called after that
 169          * bridge's @enable function. If the preceding element is a
 170          * &drm_encoder it's called right after the encoder's
 171          * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or
 172          * &drm_encoder_helper_funcs.dpms hook.
 173          *
 174          * The bridge can assume that the display pipe (i.e. clocks and timing
 175          * signals) feeding it is running when this callback is called. This
 176          * callback must enable the display link feeding the next bridge in the
 177          * chain if there is one.
 178          *
 179          * The enable callback is optional.
 180          */
 181         void (*enable)(struct drm_bridge *bridge);
 182 };
 183
 184 /**
 185  * struct drm_bridge - central DRM bridge control structure
 186  * @dev: DRM device this bridge belongs to
 187  * @encoder: encoder to which this bridge is connected
 188  * @next: the next bridge in the encoder chain
 189  * @of_node: device node pointer to the bridge
 190  * @list: to keep track of all added bridges
 191  * @funcs: control functions
 192  * @driver_private: pointer to the bridge driver's internal context
 193  */
 194 struct drm_bridge {
 195         struct drm_device *dev;
 196         struct drm_encoder *encoder;
 197         struct drm_bridge *next;
 198 #ifdef CONFIG_OF
 199         struct device_node *of_node;
 200 #endif
 201         struct list_head list;
 202
 203         const struct drm_bridge_funcs *funcs;
 204         void *driver_private;
 205 };
 206
 207 int drm_bridge_add(struct drm_bridge *bridge);
 208 void drm_bridge_remove(struct drm_bridge *bridge);
 209 struct drm_bridge *of_drm_find_bridge(struct device_node *np);
 210 int drm_bridge_attach(struct drm_encoder *encoder, struct drm_bridge *bridge,
 211                       struct drm_bridge *previous);
 212
 213 bool drm_bridge_mode_fixup(struct drm_bridge *bridge,
 214                         const struct drm_display_mode *mode,
 215                         struct drm_display_mode *adjusted_mode);
 216 void drm_bridge_disable(struct drm_bridge *bridge);
 217 void drm_bridge_post_disable(struct drm_bridge *bridge);
 218 void drm_bridge_mode_set(struct drm_bridge *bridge,
 219                         struct drm_display_mode *mode,
 220                         struct drm_display_mode *adjusted_mode);
 221 void drm_bridge_pre_enable(struct drm_bridge *bridge);
 222 void drm_bridge_enable(struct drm_bridge *bridge);
 223
 224 #endif