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_encoder *encoder, struct drm_bridge *bridge, 205 struct drm_bridge *previous); 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 219