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() function. If the preceding element is a
 100          * &drm_encoder it's called right before the encoder's ->disable(),
 101          * ->prepare() or ->dpms() hook from struct &drm_encoder_helper_funcs.
 102          *
 103          * The bridge can assume that the display pipe (i.e. clocks and timing
 104          * signals) feeding it is still running when this callback is called.
 105          *
 106          * The disable callback is optional.
 107          */
 108         void (*disable)(struct drm_bridge *bridge);
 109
 110         /**
 111          * @post_disable:
 112          *
 113          * This callback should disable the bridge. It is called right after
 114          * the preceding element in the display pipe is disabled. If the
 115          * preceding element is a bridge this means it's called after that
 116          * bridge's ->post_disable() function. If the preceding element is a
 117          * &drm_encoder it's called right after the encoder's ->disable(),
 118          * ->prepare() or ->dpms() hook from struct &drm_encoder_helper_funcs.
 119          *
 120          * The bridge must assume that the display pipe (i.e. clocks and timing
 121          * singals) feeding it is no longer running when this callback is
 122          * called.
 123          *
 124          * The post_disable callback is optional.
 125          */
 126         void (*post_disable)(struct drm_bridge *bridge);
 127
 128         /**
 129          * @mode_set:
 130          *
 131          * This callback should set the given mode on the bridge. It is called
 132          * after the ->mode_set() callback for the preceding element in the
 133          * display pipeline has been called already. The display pipe (i.e.
 134          * clocks and timing signals) is off when this function is called.
 135          */
 136         void (*mode_set)(struct drm_bridge *bridge,
 137                          struct drm_display_mode *mode,
 138                          struct drm_display_mode *adjusted_mode);
 139         /**
 140          * @pre_enable:
 141          *
 142          * This callback should enable the bridge. It is called right before
 143          * the preceding element in the display pipe is enabled. If the
 144          * preceding element is a bridge this means it's called before that
 145          * bridge's ->pre_enable() function. If the preceding element is a
 146          * &drm_encoder it's called right before the encoder's ->enable(),
 147          * ->commit() or ->dpms() hook from struct &drm_encoder_helper_funcs.
 148          *
 149          * The display pipe (i.e. clocks and timing signals) feeding this bridge
 150          * will not yet be running when this callback is called. The bridge must
 151          * not enable the display link feeding the next bridge in the chain (if
 152          * there is one) when this callback is called.
 153          *
 154          * The pre_enable callback is optional.
 155          */
 156         void (*pre_enable)(struct drm_bridge *bridge);
 157
 158         /**
 159          * @enable:
 160          *
 161          * This callback should enable the bridge. It is called right after
 162          * the preceding element in the display pipe is enabled. If the
 163          * preceding element is a bridge this means it's called after that
 164          * bridge's ->enable() function. If the preceding element is a
 165          * &drm_encoder it's called right after the encoder's ->enable(),
 166          * ->commit() or ->dpms() hook from struct &drm_encoder_helper_funcs.
 167          *
 168          * The bridge can assume that the display pipe (i.e. clocks and timing
 169          * signals) feeding it is running when this callback is called. This
 170          * callback must enable the display link feeding the next bridge in the
 171          * chain if there is one.
 172          *
 173          * The enable callback is optional.
 174          */
 175         void (*enable)(struct drm_bridge *bridge);
 176 };
 177
 178 /**
 179  * struct drm_bridge - central DRM bridge control structure
 180  * @dev: DRM device this bridge belongs to
 181  * @encoder: encoder to which this bridge is connected
 182  * @next: the next bridge in the encoder chain
 183  * @of_node: device node pointer to the bridge
 184  * @list: to keep track of all added bridges
 185  * @funcs: control functions
 186  * @driver_private: pointer to the bridge driver's internal context
 187  */
 188 struct drm_bridge {
 189         struct drm_device *dev;
 190         struct drm_encoder *encoder;
 191         struct drm_bridge *next;
 192 #ifdef CONFIG_OF
 193         struct device_node *of_node;
 194 #endif
 195         struct list_head list;
 196
 197         const struct drm_bridge_funcs *funcs;
 198         void *driver_private;
 199 };
 200
 201 int drm_bridge_add(struct drm_bridge *bridge);
 202 void drm_bridge_remove(struct drm_bridge *bridge);
 203 struct drm_bridge *of_drm_find_bridge(struct device_node *np);
 204 int drm_bridge_attach(struct drm_device *dev, struct drm_bridge *bridge);
 205 void drm_bridge_detach(struct drm_bridge *bridge);
 206
 207 bool drm_bridge_mode_fixup(struct drm_bridge *bridge,
 208                         const struct drm_display_mode *mode,
 209                         struct drm_display_mode *adjusted_mode);
 210 void drm_bridge_disable(struct drm_bridge *bridge);
 211 void drm_bridge_post_disable(struct drm_bridge *bridge);
 212 void drm_bridge_mode_set(struct drm_bridge *bridge,
 213                         struct drm_display_mode *mode,
 214                         struct drm_display_mode *adjusted_mode);
 215 void drm_bridge_pre_enable(struct drm_bridge *bridge);
 216 void drm_bridge_enable(struct drm_bridge *bridge);
 217
 218 #endif