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 225