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