Merge tag 'drm-misc-fixes-2017-12-14' of git://anongit.freedesktop.org/drm/drm-misc
[sfrench/cifs-2.6.git] / include / drm / drm_connector.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_CONNECTOR_H__
24 #define __DRM_CONNECTOR_H__
25
26 #include <linux/list.h>
27 #include <linux/llist.h>
28 #include <linux/ctype.h>
29 #include <linux/hdmi.h>
30 #include <drm/drm_mode_object.h>
31
32 #include <uapi/drm/drm_mode.h>
33
34 struct drm_connector_helper_funcs;
35 struct drm_modeset_acquire_ctx;
36 struct drm_device;
37 struct drm_crtc;
38 struct drm_encoder;
39 struct drm_property;
40 struct drm_property_blob;
41 struct drm_printer;
42 struct edid;
43
44 enum drm_connector_force {
45         DRM_FORCE_UNSPECIFIED,
46         DRM_FORCE_OFF,
47         DRM_FORCE_ON,         /* force on analog part normally */
48         DRM_FORCE_ON_DIGITAL, /* for DVI-I use digital connector */
49 };
50
51 /**
52  * enum drm_connector_status - status for a &drm_connector
53  *
54  * This enum is used to track the connector status. There are no separate
55  * #defines for the uapi!
56  */
57 enum drm_connector_status {
58         /**
59          * @connector_status_connected: The connector is definitely connected to
60          * a sink device, and can be enabled.
61          */
62         connector_status_connected = 1,
63         /**
64          * @connector_status_disconnected: The connector isn't connected to a
65          * sink device which can be autodetect. For digital outputs like DP or
66          * HDMI (which can be realiable probed) this means there's really
67          * nothing there. It is driver-dependent whether a connector with this
68          * status can be lit up or not.
69          */
70         connector_status_disconnected = 2,
71         /**
72          * @connector_status_unknown: The connector's status could not be
73          * reliably detected. This happens when probing would either cause
74          * flicker (like load-detection when the connector is in use), or when a
75          * hardware resource isn't available (like when load-detection needs a
76          * free CRTC). It should be possible to light up the connector with one
77          * of the listed fallback modes. For default configuration userspace
78          * should only try to light up connectors with unknown status when
79          * there's not connector with @connector_status_connected.
80          */
81         connector_status_unknown = 3,
82 };
83
84 enum subpixel_order {
85         SubPixelUnknown = 0,
86         SubPixelHorizontalRGB,
87         SubPixelHorizontalBGR,
88         SubPixelVerticalRGB,
89         SubPixelVerticalBGR,
90         SubPixelNone,
91
92 };
93
94 /**
95  * struct drm_scrambling: sink's scrambling support.
96  */
97 struct drm_scrambling {
98         /**
99          * @supported: scrambling supported for rates > 340 Mhz.
100          */
101         bool supported;
102         /**
103          * @low_rates: scrambling supported for rates <= 340 Mhz.
104          */
105         bool low_rates;
106 };
107
108 /*
109  * struct drm_scdc - Information about scdc capabilities of a HDMI 2.0 sink
110  *
111  * Provides SCDC register support and capabilities related information on a
112  * HDMI 2.0 sink. In case of a HDMI 1.4 sink, all parameter must be 0.
113  */
114 struct drm_scdc {
115         /**
116          * @supported: status control & data channel present.
117          */
118         bool supported;
119         /**
120          * @read_request: sink is capable of generating scdc read request.
121          */
122         bool read_request;
123         /**
124          * @scrambling: sink's scrambling capabilities
125          */
126         struct drm_scrambling scrambling;
127 };
128
129
130 /**
131  * struct drm_hdmi_info - runtime information about the connected HDMI sink
132  *
133  * Describes if a given display supports advanced HDMI 2.0 features.
134  * This information is available in CEA-861-F extension blocks (like HF-VSDB).
135  */
136 struct drm_hdmi_info {
137         /** @scdc: sink's scdc support and capabilities */
138         struct drm_scdc scdc;
139
140         /**
141          * @y420_vdb_modes: bitmap of modes which can support ycbcr420
142          * output only (not normal RGB/YCBCR444/422 outputs). There are total
143          * 107 VICs defined by CEA-861-F spec, so the size is 128 bits to map
144          * upto 128 VICs;
145          */
146         unsigned long y420_vdb_modes[BITS_TO_LONGS(128)];
147
148         /**
149          * @y420_cmdb_modes: bitmap of modes which can support ycbcr420
150          * output also, along with normal HDMI outputs. There are total 107
151          * VICs defined by CEA-861-F spec, so the size is 128 bits to map upto
152          * 128 VICs;
153          */
154         unsigned long y420_cmdb_modes[BITS_TO_LONGS(128)];
155
156         /** @y420_cmdb_map: bitmap of SVD index, to extraxt vcb modes */
157         u64 y420_cmdb_map;
158
159         /** @y420_dc_modes: bitmap of deep color support index */
160         u8 y420_dc_modes;
161 };
162
163 /**
164  * enum drm_link_status - connector's link_status property value
165  *
166  * This enum is used as the connector's link status property value.
167  * It is set to the values defined in uapi.
168  *
169  * @DRM_LINK_STATUS_GOOD: DP Link is Good as a result of successful
170  *                        link training
171  * @DRM_LINK_STATUS_BAD: DP Link is BAD as a result of link training
172  *                       failure
173  */
174 enum drm_link_status {
175         DRM_LINK_STATUS_GOOD = DRM_MODE_LINK_STATUS_GOOD,
176         DRM_LINK_STATUS_BAD = DRM_MODE_LINK_STATUS_BAD,
177 };
178
179 /**
180  * struct drm_display_info - runtime data about the connected sink
181  *
182  * Describes a given display (e.g. CRT or flat panel) and its limitations. For
183  * fixed display sinks like built-in panels there's not much difference between
184  * this and &struct drm_connector. But for sinks with a real cable this
185  * structure is meant to describe all the things at the other end of the cable.
186  *
187  * For sinks which provide an EDID this can be filled out by calling
188  * drm_add_edid_modes().
189  */
190 struct drm_display_info {
191         /**
192          * @name: Name of the display.
193          */
194         char name[DRM_DISPLAY_INFO_LEN];
195
196         /**
197          * @width_mm: Physical width in mm.
198          */
199         unsigned int width_mm;
200         /**
201          * @height_mm: Physical height in mm.
202          */
203         unsigned int height_mm;
204
205         /**
206          * @pixel_clock: Maximum pixel clock supported by the sink, in units of
207          * 100Hz. This mismatches the clock in &drm_display_mode (which is in
208          * kHZ), because that's what the EDID uses as base unit.
209          */
210         unsigned int pixel_clock;
211         /**
212          * @bpc: Maximum bits per color channel. Used by HDMI and DP outputs.
213          */
214         unsigned int bpc;
215
216         /**
217          * @subpixel_order: Subpixel order of LCD panels.
218          */
219         enum subpixel_order subpixel_order;
220
221 #define DRM_COLOR_FORMAT_RGB444         (1<<0)
222 #define DRM_COLOR_FORMAT_YCRCB444       (1<<1)
223 #define DRM_COLOR_FORMAT_YCRCB422       (1<<2)
224 #define DRM_COLOR_FORMAT_YCRCB420       (1<<3)
225
226         /**
227          * @color_formats: HDMI Color formats, selects between RGB and YCrCb
228          * modes. Used DRM_COLOR_FORMAT\_ defines, which are _not_ the same ones
229          * as used to describe the pixel format in framebuffers, and also don't
230          * match the formats in @bus_formats which are shared with v4l.
231          */
232         u32 color_formats;
233
234         /**
235          * @bus_formats: Pixel data format on the wire, somewhat redundant with
236          * @color_formats. Array of size @num_bus_formats encoded using
237          * MEDIA_BUS_FMT\_ defines shared with v4l and media drivers.
238          */
239         const u32 *bus_formats;
240         /**
241          * @num_bus_formats: Size of @bus_formats array.
242          */
243         unsigned int num_bus_formats;
244
245 #define DRM_BUS_FLAG_DE_LOW             (1<<0)
246 #define DRM_BUS_FLAG_DE_HIGH            (1<<1)
247 /* drive data on pos. edge */
248 #define DRM_BUS_FLAG_PIXDATA_POSEDGE    (1<<2)
249 /* drive data on neg. edge */
250 #define DRM_BUS_FLAG_PIXDATA_NEGEDGE    (1<<3)
251 /* data is transmitted MSB to LSB on the bus */
252 #define DRM_BUS_FLAG_DATA_MSB_TO_LSB    (1<<4)
253 /* data is transmitted LSB to MSB on the bus */
254 #define DRM_BUS_FLAG_DATA_LSB_TO_MSB    (1<<5)
255
256         /**
257          * @bus_flags: Additional information (like pixel signal polarity) for
258          * the pixel data on the bus, using DRM_BUS_FLAGS\_ defines.
259          */
260         u32 bus_flags;
261
262         /**
263          * @max_tmds_clock: Maximum TMDS clock rate supported by the
264          * sink in kHz. 0 means undefined.
265          */
266         int max_tmds_clock;
267
268         /**
269          * @dvi_dual: Dual-link DVI sink?
270          */
271         bool dvi_dual;
272
273         /**
274          * @edid_hdmi_dc_modes: Mask of supported hdmi deep color modes. Even
275          * more stuff redundant with @bus_formats.
276          */
277         u8 edid_hdmi_dc_modes;
278
279         /**
280          * @cea_rev: CEA revision of the HDMI sink.
281          */
282         u8 cea_rev;
283
284         /**
285          * @hdmi: advance features of a HDMI sink.
286          */
287         struct drm_hdmi_info hdmi;
288
289         /**
290          * @non_desktop: Non desktop display (HMD).
291          */
292         bool non_desktop;
293 };
294
295 int drm_display_info_set_bus_formats(struct drm_display_info *info,
296                                      const u32 *formats,
297                                      unsigned int num_formats);
298
299 /**
300  * struct drm_tv_connector_state - TV connector related states
301  * @subconnector: selected subconnector
302  * @margins: left/right/top/bottom margins
303  * @mode: TV mode
304  * @brightness: brightness in percent
305  * @contrast: contrast in percent
306  * @flicker_reduction: flicker reduction in percent
307  * @overscan: overscan in percent
308  * @saturation: saturation in percent
309  * @hue: hue in percent
310  */
311 struct drm_tv_connector_state {
312         enum drm_mode_subconnector subconnector;
313         struct {
314                 unsigned int left;
315                 unsigned int right;
316                 unsigned int top;
317                 unsigned int bottom;
318         } margins;
319         unsigned int mode;
320         unsigned int brightness;
321         unsigned int contrast;
322         unsigned int flicker_reduction;
323         unsigned int overscan;
324         unsigned int saturation;
325         unsigned int hue;
326 };
327
328 /**
329  * struct drm_connector_state - mutable connector state
330  * @connector: backpointer to the connector
331  * @best_encoder: can be used by helpers and drivers to select the encoder
332  * @state: backpointer to global drm_atomic_state
333  * @tv: TV connector state
334  */
335 struct drm_connector_state {
336         struct drm_connector *connector;
337
338         /**
339          * @crtc: CRTC to connect connector to, NULL if disabled.
340          *
341          * Do not change this directly, use drm_atomic_set_crtc_for_connector()
342          * instead.
343          */
344         struct drm_crtc *crtc;
345
346         struct drm_encoder *best_encoder;
347
348         /**
349          * @link_status: Connector link_status to keep track of whether link is
350          * GOOD or BAD to notify userspace if retraining is necessary.
351          */
352         enum drm_link_status link_status;
353
354         struct drm_atomic_state *state;
355
356         /**
357          * @commit: Tracks the pending commit to prevent use-after-free conditions.
358          *
359          * Is only set when @crtc is NULL.
360          */
361         struct drm_crtc_commit *commit;
362
363         struct drm_tv_connector_state tv;
364
365         /**
366          * @picture_aspect_ratio: Connector property to control the
367          * HDMI infoframe aspect ratio setting.
368          *
369          * The %DRM_MODE_PICTURE_ASPECT_\* values much match the
370          * values for &enum hdmi_picture_aspect
371          */
372         enum hdmi_picture_aspect picture_aspect_ratio;
373
374         /**
375          * @scaling_mode: Connector property to control the
376          * upscaling, mostly used for built-in panels.
377          */
378         unsigned int scaling_mode;
379 };
380
381 /**
382  * struct drm_connector_funcs - control connectors on a given device
383  *
384  * Each CRTC may have one or more connectors attached to it.  The functions
385  * below allow the core DRM code to control connectors, enumerate available modes,
386  * etc.
387  */
388 struct drm_connector_funcs {
389         /**
390          * @dpms:
391          *
392          * Legacy entry point to set the per-connector DPMS state. Legacy DPMS
393          * is exposed as a standard property on the connector, but diverted to
394          * this callback in the drm core. Note that atomic drivers don't
395          * implement the 4 level DPMS support on the connector any more, but
396          * instead only have an on/off "ACTIVE" property on the CRTC object.
397          *
398          * This hook is not used by atomic drivers, remapping of the legacy DPMS
399          * property is entirely handled in the DRM core.
400          *
401          * RETURNS:
402          *
403          * 0 on success or a negative error code on failure.
404          */
405         int (*dpms)(struct drm_connector *connector, int mode);
406
407         /**
408          * @reset:
409          *
410          * Reset connector hardware and software state to off. This function isn't
411          * called by the core directly, only through drm_mode_config_reset().
412          * It's not a helper hook only for historical reasons.
413          *
414          * Atomic drivers can use drm_atomic_helper_connector_reset() to reset
415          * atomic state using this hook.
416          */
417         void (*reset)(struct drm_connector *connector);
418
419         /**
420          * @detect:
421          *
422          * Check to see if anything is attached to the connector. The parameter
423          * force is set to false whilst polling, true when checking the
424          * connector due to a user request. force can be used by the driver to
425          * avoid expensive, destructive operations during automated probing.
426          *
427          * This callback is optional, if not implemented the connector will be
428          * considered as always being attached.
429          *
430          * FIXME:
431          *
432          * Note that this hook is only called by the probe helper. It's not in
433          * the helper library vtable purely for historical reasons. The only DRM
434          * core entry point to probe connector state is @fill_modes.
435          *
436          * Note that the helper library will already hold
437          * &drm_mode_config.connection_mutex. Drivers which need to grab additional
438          * locks to avoid races with concurrent modeset changes need to use
439          * &drm_connector_helper_funcs.detect_ctx instead.
440          *
441          * RETURNS:
442          *
443          * drm_connector_status indicating the connector's status.
444          */
445         enum drm_connector_status (*detect)(struct drm_connector *connector,
446                                             bool force);
447
448         /**
449          * @force:
450          *
451          * This function is called to update internal encoder state when the
452          * connector is forced to a certain state by userspace, either through
453          * the sysfs interfaces or on the kernel cmdline. In that case the
454          * @detect callback isn't called.
455          *
456          * FIXME:
457          *
458          * Note that this hook is only called by the probe helper. It's not in
459          * the helper library vtable purely for historical reasons. The only DRM
460          * core entry point to probe connector state is @fill_modes.
461          */
462         void (*force)(struct drm_connector *connector);
463
464         /**
465          * @fill_modes:
466          *
467          * Entry point for output detection and basic mode validation. The
468          * driver should reprobe the output if needed (e.g. when hotplug
469          * handling is unreliable), add all detected modes to &drm_connector.modes
470          * and filter out any the device can't support in any configuration. It
471          * also needs to filter out any modes wider or higher than the
472          * parameters max_width and max_height indicate.
473          *
474          * The drivers must also prune any modes no longer valid from
475          * &drm_connector.modes. Furthermore it must update
476          * &drm_connector.status and &drm_connector.edid.  If no EDID has been
477          * received for this output connector->edid must be NULL.
478          *
479          * Drivers using the probe helpers should use
480          * drm_helper_probe_single_connector_modes() or
481          * drm_helper_probe_single_connector_modes_nomerge() to implement this
482          * function.
483          *
484          * RETURNS:
485          *
486          * The number of modes detected and filled into &drm_connector.modes.
487          */
488         int (*fill_modes)(struct drm_connector *connector, uint32_t max_width, uint32_t max_height);
489
490         /**
491          * @set_property:
492          *
493          * This is the legacy entry point to update a property attached to the
494          * connector.
495          *
496          * This callback is optional if the driver does not support any legacy
497          * driver-private properties. For atomic drivers it is not used because
498          * property handling is done entirely in the DRM core.
499          *
500          * RETURNS:
501          *
502          * 0 on success or a negative error code on failure.
503          */
504         int (*set_property)(struct drm_connector *connector, struct drm_property *property,
505                              uint64_t val);
506
507         /**
508          * @late_register:
509          *
510          * This optional hook can be used to register additional userspace
511          * interfaces attached to the connector, light backlight control, i2c,
512          * DP aux or similar interfaces. It is called late in the driver load
513          * sequence from drm_connector_register() when registering all the
514          * core drm connector interfaces. Everything added from this callback
515          * should be unregistered in the early_unregister callback.
516          *
517          * This is called while holding &drm_connector.mutex.
518          *
519          * Returns:
520          *
521          * 0 on success, or a negative error code on failure.
522          */
523         int (*late_register)(struct drm_connector *connector);
524
525         /**
526          * @early_unregister:
527          *
528          * This optional hook should be used to unregister the additional
529          * userspace interfaces attached to the connector from
530          * late_register(). It is called from drm_connector_unregister(),
531          * early in the driver unload sequence to disable userspace access
532          * before data structures are torndown.
533          *
534          * This is called while holding &drm_connector.mutex.
535          */
536         void (*early_unregister)(struct drm_connector *connector);
537
538         /**
539          * @destroy:
540          *
541          * Clean up connector resources. This is called at driver unload time
542          * through drm_mode_config_cleanup(). It can also be called at runtime
543          * when a connector is being hot-unplugged for drivers that support
544          * connector hotplugging (e.g. DisplayPort MST).
545          */
546         void (*destroy)(struct drm_connector *connector);
547
548         /**
549          * @atomic_duplicate_state:
550          *
551          * Duplicate the current atomic state for this connector and return it.
552          * The core and helpers guarantee that any atomic state duplicated with
553          * this hook and still owned by the caller (i.e. not transferred to the
554          * driver by calling &drm_mode_config_funcs.atomic_commit) will be
555          * cleaned up by calling the @atomic_destroy_state hook in this
556          * structure.
557          *
558          * Atomic drivers which don't subclass &struct drm_connector_state should use
559          * drm_atomic_helper_connector_duplicate_state(). Drivers that subclass the
560          * state structure to extend it with driver-private state should use
561          * __drm_atomic_helper_connector_duplicate_state() to make sure shared state is
562          * duplicated in a consistent fashion across drivers.
563          *
564          * It is an error to call this hook before &drm_connector.state has been
565          * initialized correctly.
566          *
567          * NOTE:
568          *
569          * If the duplicate state references refcounted resources this hook must
570          * acquire a reference for each of them. The driver must release these
571          * references again in @atomic_destroy_state.
572          *
573          * RETURNS:
574          *
575          * Duplicated atomic state or NULL when the allocation failed.
576          */
577         struct drm_connector_state *(*atomic_duplicate_state)(struct drm_connector *connector);
578
579         /**
580          * @atomic_destroy_state:
581          *
582          * Destroy a state duplicated with @atomic_duplicate_state and release
583          * or unreference all resources it references
584          */
585         void (*atomic_destroy_state)(struct drm_connector *connector,
586                                      struct drm_connector_state *state);
587
588         /**
589          * @atomic_set_property:
590          *
591          * Decode a driver-private property value and store the decoded value
592          * into the passed-in state structure. Since the atomic core decodes all
593          * standardized properties (even for extensions beyond the core set of
594          * properties which might not be implemented by all drivers) this
595          * requires drivers to subclass the state structure.
596          *
597          * Such driver-private properties should really only be implemented for
598          * truly hardware/vendor specific state. Instead it is preferred to
599          * standardize atomic extension and decode the properties used to expose
600          * such an extension in the core.
601          *
602          * Do not call this function directly, use
603          * drm_atomic_connector_set_property() instead.
604          *
605          * This callback is optional if the driver does not support any
606          * driver-private atomic properties.
607          *
608          * NOTE:
609          *
610          * This function is called in the state assembly phase of atomic
611          * modesets, which can be aborted for any reason (including on
612          * userspace's request to just check whether a configuration would be
613          * possible). Drivers MUST NOT touch any persistent state (hardware or
614          * software) or data structures except the passed in @state parameter.
615          *
616          * Also since userspace controls in which order properties are set this
617          * function must not do any input validation (since the state update is
618          * incomplete and hence likely inconsistent). Instead any such input
619          * validation must be done in the various atomic_check callbacks.
620          *
621          * RETURNS:
622          *
623          * 0 if the property has been found, -EINVAL if the property isn't
624          * implemented by the driver (which shouldn't ever happen, the core only
625          * asks for properties attached to this connector). No other validation
626          * is allowed by the driver. The core already checks that the property
627          * value is within the range (integer, valid enum value, ...) the driver
628          * set when registering the property.
629          */
630         int (*atomic_set_property)(struct drm_connector *connector,
631                                    struct drm_connector_state *state,
632                                    struct drm_property *property,
633                                    uint64_t val);
634
635         /**
636          * @atomic_get_property:
637          *
638          * Reads out the decoded driver-private property. This is used to
639          * implement the GETCONNECTOR IOCTL.
640          *
641          * Do not call this function directly, use
642          * drm_atomic_connector_get_property() instead.
643          *
644          * This callback is optional if the driver does not support any
645          * driver-private atomic properties.
646          *
647          * RETURNS:
648          *
649          * 0 on success, -EINVAL if the property isn't implemented by the
650          * driver (which shouldn't ever happen, the core only asks for
651          * properties attached to this connector).
652          */
653         int (*atomic_get_property)(struct drm_connector *connector,
654                                    const struct drm_connector_state *state,
655                                    struct drm_property *property,
656                                    uint64_t *val);
657
658         /**
659          * @atomic_print_state:
660          *
661          * If driver subclasses &struct drm_connector_state, it should implement
662          * this optional hook for printing additional driver specific state.
663          *
664          * Do not call this directly, use drm_atomic_connector_print_state()
665          * instead.
666          */
667         void (*atomic_print_state)(struct drm_printer *p,
668                                    const struct drm_connector_state *state);
669 };
670
671 /* mode specified on the command line */
672 struct drm_cmdline_mode {
673         bool specified;
674         bool refresh_specified;
675         bool bpp_specified;
676         int xres, yres;
677         int bpp;
678         int refresh;
679         bool rb;
680         bool interlace;
681         bool cvt;
682         bool margins;
683         enum drm_connector_force force;
684 };
685
686 /**
687  * struct drm_connector - central DRM connector control structure
688  * @dev: parent DRM device
689  * @kdev: kernel device for sysfs attributes
690  * @attr: sysfs attributes
691  * @head: list management
692  * @base: base KMS object
693  * @name: human readable name, can be overwritten by the driver
694  * @connector_type: one of the DRM_MODE_CONNECTOR_<foo> types from drm_mode.h
695  * @connector_type_id: index into connector type enum
696  * @interlace_allowed: can this connector handle interlaced modes?
697  * @doublescan_allowed: can this connector handle doublescan?
698  * @stereo_allowed: can this connector handle stereo modes?
699  * @funcs: connector control functions
700  * @edid_blob_ptr: DRM property containing EDID if present
701  * @properties: property tracking for this connector
702  * @dpms: current dpms state
703  * @helper_private: mid-layer private data
704  * @cmdline_mode: mode line parsed from the kernel cmdline for this connector
705  * @force: a DRM_FORCE_<foo> state for forced mode sets
706  * @override_edid: has the EDID been overwritten through debugfs for testing?
707  * @encoder_ids: valid encoders for this connector
708  * @encoder: encoder driving this connector, if any
709  * @eld: EDID-like data, if present
710  * @latency_present: AV delay info from ELD, if found
711  * @video_latency: video latency info from ELD, if found
712  * @audio_latency: audio latency info from ELD, if found
713  * @null_edid_counter: track sinks that give us all zeros for the EDID
714  * @bad_edid_counter: track sinks that give us an EDID with invalid checksum
715  * @edid_corrupt: indicates whether the last read EDID was corrupt
716  * @debugfs_entry: debugfs directory for this connector
717  * @has_tile: is this connector connected to a tiled monitor
718  * @tile_group: tile group for the connected monitor
719  * @tile_is_single_monitor: whether the tile is one monitor housing
720  * @num_h_tile: number of horizontal tiles in the tile group
721  * @num_v_tile: number of vertical tiles in the tile group
722  * @tile_h_loc: horizontal location of this tile
723  * @tile_v_loc: vertical location of this tile
724  * @tile_h_size: horizontal size of this tile.
725  * @tile_v_size: vertical size of this tile.
726  * @scaling_mode_property:  Optional atomic property to control the upscaling.
727  *
728  * Each connector may be connected to one or more CRTCs, or may be clonable by
729  * another connector if they can share a CRTC.  Each connector also has a specific
730  * position in the broader display (referred to as a 'screen' though it could
731  * span multiple monitors).
732  */
733 struct drm_connector {
734         struct drm_device *dev;
735         struct device *kdev;
736         struct device_attribute *attr;
737         struct list_head head;
738
739         struct drm_mode_object base;
740
741         char *name;
742
743         /**
744          * @mutex: Lock for general connector state, but currently only protects
745          * @registered. Most of the connector state is still protected by
746          * &drm_mode_config.mutex.
747          */
748         struct mutex mutex;
749
750         /**
751          * @index: Compacted connector index, which matches the position inside
752          * the mode_config.list for drivers not supporting hot-add/removing. Can
753          * be used as an array index. It is invariant over the lifetime of the
754          * connector.
755          */
756         unsigned index;
757
758         int connector_type;
759         int connector_type_id;
760         bool interlace_allowed;
761         bool doublescan_allowed;
762         bool stereo_allowed;
763
764         /**
765          * @ycbcr_420_allowed : This bool indicates if this connector is
766          * capable of handling YCBCR 420 output. While parsing the EDID
767          * blocks, its very helpful to know, if the source is capable of
768          * handling YCBCR 420 outputs.
769          */
770         bool ycbcr_420_allowed;
771
772         /**
773          * @registered: Is this connector exposed (registered) with userspace?
774          * Protected by @mutex.
775          */
776         bool registered;
777
778         /**
779          * @modes:
780          * Modes available on this connector (from fill_modes() + user).
781          * Protected by &drm_mode_config.mutex.
782          */
783         struct list_head modes;
784
785         /**
786          * @status:
787          * One of the drm_connector_status enums (connected, not, or unknown).
788          * Protected by &drm_mode_config.mutex.
789          */
790         enum drm_connector_status status;
791
792         /**
793          * @probed_modes:
794          * These are modes added by probing with DDC or the BIOS, before
795          * filtering is applied. Used by the probe helpers. Protected by
796          * &drm_mode_config.mutex.
797          */
798         struct list_head probed_modes;
799
800         /**
801          * @display_info: Display information is filled from EDID information
802          * when a display is detected. For non hot-pluggable displays such as
803          * flat panels in embedded systems, the driver should initialize the
804          * &drm_display_info.width_mm and &drm_display_info.height_mm fields
805          * with the physical size of the display.
806          *
807          * Protected by &drm_mode_config.mutex.
808          */
809         struct drm_display_info display_info;
810         const struct drm_connector_funcs *funcs;
811
812         struct drm_property_blob *edid_blob_ptr;
813         struct drm_object_properties properties;
814
815         struct drm_property *scaling_mode_property;
816
817         /**
818          * @path_blob_ptr:
819          *
820          * DRM blob property data for the DP MST path property.
821          */
822         struct drm_property_blob *path_blob_ptr;
823
824         /**
825          * @tile_blob_ptr:
826          *
827          * DRM blob property data for the tile property (used mostly by DP MST).
828          * This is meant for screens which are driven through separate display
829          * pipelines represented by &drm_crtc, which might not be running with
830          * genlocked clocks. For tiled panels which are genlocked, like
831          * dual-link LVDS or dual-link DSI, the driver should try to not expose
832          * the tiling and virtualize both &drm_crtc and &drm_plane if needed.
833          */
834         struct drm_property_blob *tile_blob_ptr;
835
836 /* should we poll this connector for connects and disconnects */
837 /* hot plug detectable */
838 #define DRM_CONNECTOR_POLL_HPD (1 << 0)
839 /* poll for connections */
840 #define DRM_CONNECTOR_POLL_CONNECT (1 << 1)
841 /* can cleanly poll for disconnections without flickering the screen */
842 /* DACs should rarely do this without a lot of testing */
843 #define DRM_CONNECTOR_POLL_DISCONNECT (1 << 2)
844
845         /**
846          * @polled:
847          *
848          * Connector polling mode, a combination of
849          *
850          * DRM_CONNECTOR_POLL_HPD
851          *     The connector generates hotplug events and doesn't need to be
852          *     periodically polled. The CONNECT and DISCONNECT flags must not
853          *     be set together with the HPD flag.
854          *
855          * DRM_CONNECTOR_POLL_CONNECT
856          *     Periodically poll the connector for connection.
857          *
858          * DRM_CONNECTOR_POLL_DISCONNECT
859          *     Periodically poll the connector for disconnection.
860          *
861          * Set to 0 for connectors that don't support connection status
862          * discovery.
863          */
864         uint8_t polled;
865
866         /* requested DPMS state */
867         int dpms;
868
869         const struct drm_connector_helper_funcs *helper_private;
870
871         /* forced on connector */
872         struct drm_cmdline_mode cmdline_mode;
873         enum drm_connector_force force;
874         bool override_edid;
875
876 #define DRM_CONNECTOR_MAX_ENCODER 3
877         uint32_t encoder_ids[DRM_CONNECTOR_MAX_ENCODER];
878         struct drm_encoder *encoder; /* currently active encoder */
879
880 #define MAX_ELD_BYTES   128
881         /* EDID bits */
882         uint8_t eld[MAX_ELD_BYTES];
883         bool latency_present[2];
884         int video_latency[2];   /* [0]: progressive, [1]: interlaced */
885         int audio_latency[2];
886         int null_edid_counter; /* needed to workaround some HW bugs where we get all 0s */
887         unsigned bad_edid_counter;
888
889         /* Flag for raw EDID header corruption - used in Displayport
890          * compliance testing - * Displayport Link CTS Core 1.2 rev1.1 4.2.2.6
891          */
892         bool edid_corrupt;
893
894         struct dentry *debugfs_entry;
895
896         /**
897          * @state:
898          *
899          * Current atomic state for this connector.
900          *
901          * This is protected by @drm_mode_config.connection_mutex. Note that
902          * nonblocking atomic commits access the current connector state without
903          * taking locks. Either by going through the &struct drm_atomic_state
904          * pointers, see for_each_oldnew_connector_in_state(),
905          * for_each_old_connector_in_state() and
906          * for_each_new_connector_in_state(). Or through careful ordering of
907          * atomic commit operations as implemented in the atomic helpers, see
908          * &struct drm_crtc_commit.
909          */
910         struct drm_connector_state *state;
911
912         /* DisplayID bits */
913         bool has_tile;
914         struct drm_tile_group *tile_group;
915         bool tile_is_single_monitor;
916
917         uint8_t num_h_tile, num_v_tile;
918         uint8_t tile_h_loc, tile_v_loc;
919         uint16_t tile_h_size, tile_v_size;
920
921         /**
922          * @free_node:
923          *
924          * List used only by &drm_connector_iter to be able to clean up a
925          * connector from any context, in conjunction with
926          * &drm_mode_config.connector_free_work.
927          */
928         struct llist_node free_node;
929 };
930
931 #define obj_to_connector(x) container_of(x, struct drm_connector, base)
932
933 int drm_connector_init(struct drm_device *dev,
934                        struct drm_connector *connector,
935                        const struct drm_connector_funcs *funcs,
936                        int connector_type);
937 int drm_connector_register(struct drm_connector *connector);
938 void drm_connector_unregister(struct drm_connector *connector);
939 int drm_mode_connector_attach_encoder(struct drm_connector *connector,
940                                       struct drm_encoder *encoder);
941
942 void drm_connector_cleanup(struct drm_connector *connector);
943 static inline unsigned drm_connector_index(struct drm_connector *connector)
944 {
945         return connector->index;
946 }
947
948 /**
949  * drm_connector_lookup - lookup connector object
950  * @dev: DRM device
951  * @file_priv: drm file to check for lease against.
952  * @id: connector object id
953  *
954  * This function looks up the connector object specified by id
955  * add takes a reference to it.
956  */
957 static inline struct drm_connector *drm_connector_lookup(struct drm_device *dev,
958                 struct drm_file *file_priv,
959                 uint32_t id)
960 {
961         struct drm_mode_object *mo;
962         mo = drm_mode_object_find(dev, file_priv, id, DRM_MODE_OBJECT_CONNECTOR);
963         return mo ? obj_to_connector(mo) : NULL;
964 }
965
966 /**
967  * drm_connector_get - acquire a connector reference
968  * @connector: DRM connector
969  *
970  * This function increments the connector's refcount.
971  */
972 static inline void drm_connector_get(struct drm_connector *connector)
973 {
974         drm_mode_object_get(&connector->base);
975 }
976
977 /**
978  * drm_connector_put - release a connector reference
979  * @connector: DRM connector
980  *
981  * This function decrements the connector's reference count and frees the
982  * object if the reference count drops to zero.
983  */
984 static inline void drm_connector_put(struct drm_connector *connector)
985 {
986         drm_mode_object_put(&connector->base);
987 }
988
989 /**
990  * drm_connector_reference - acquire a connector reference
991  * @connector: DRM connector
992  *
993  * This is a compatibility alias for drm_connector_get() and should not be
994  * used by new code.
995  */
996 static inline void drm_connector_reference(struct drm_connector *connector)
997 {
998         drm_connector_get(connector);
999 }
1000
1001 /**
1002  * drm_connector_unreference - release a connector reference
1003  * @connector: DRM connector
1004  *
1005  * This is a compatibility alias for drm_connector_put() and should not be
1006  * used by new code.
1007  */
1008 static inline void drm_connector_unreference(struct drm_connector *connector)
1009 {
1010         drm_connector_put(connector);
1011 }
1012
1013 const char *drm_get_connector_status_name(enum drm_connector_status status);
1014 const char *drm_get_subpixel_order_name(enum subpixel_order order);
1015 const char *drm_get_dpms_name(int val);
1016 const char *drm_get_dvi_i_subconnector_name(int val);
1017 const char *drm_get_dvi_i_select_name(int val);
1018 const char *drm_get_tv_subconnector_name(int val);
1019 const char *drm_get_tv_select_name(int val);
1020
1021 int drm_mode_create_dvi_i_properties(struct drm_device *dev);
1022 int drm_mode_create_tv_properties(struct drm_device *dev,
1023                                   unsigned int num_modes,
1024                                   const char * const modes[]);
1025 int drm_mode_create_scaling_mode_property(struct drm_device *dev);
1026 int drm_connector_attach_scaling_mode_property(struct drm_connector *connector,
1027                                                u32 scaling_mode_mask);
1028 int drm_mode_create_aspect_ratio_property(struct drm_device *dev);
1029 int drm_mode_create_suggested_offset_properties(struct drm_device *dev);
1030
1031 int drm_mode_connector_set_path_property(struct drm_connector *connector,
1032                                          const char *path);
1033 int drm_mode_connector_set_tile_property(struct drm_connector *connector);
1034 int drm_mode_connector_update_edid_property(struct drm_connector *connector,
1035                                             const struct edid *edid);
1036 void drm_mode_connector_set_link_status_property(struct drm_connector *connector,
1037                                                  uint64_t link_status);
1038
1039 /**
1040  * struct drm_tile_group - Tile group metadata
1041  * @refcount: reference count
1042  * @dev: DRM device
1043  * @id: tile group id exposed to userspace
1044  * @group_data: Sink-private data identifying this group
1045  *
1046  * @group_data corresponds to displayid vend/prod/serial for external screens
1047  * with an EDID.
1048  */
1049 struct drm_tile_group {
1050         struct kref refcount;
1051         struct drm_device *dev;
1052         int id;
1053         u8 group_data[8];
1054 };
1055
1056 struct drm_tile_group *drm_mode_create_tile_group(struct drm_device *dev,
1057                                                   char topology[8]);
1058 struct drm_tile_group *drm_mode_get_tile_group(struct drm_device *dev,
1059                                                char topology[8]);
1060 void drm_mode_put_tile_group(struct drm_device *dev,
1061                              struct drm_tile_group *tg);
1062
1063 /**
1064  * struct drm_connector_list_iter - connector_list iterator
1065  *
1066  * This iterator tracks state needed to be able to walk the connector_list
1067  * within struct drm_mode_config. Only use together with
1068  * drm_connector_list_iter_begin(), drm_connector_list_iter_end() and
1069  * drm_connector_list_iter_next() respectively the convenience macro
1070  * drm_for_each_connector_iter().
1071  */
1072 struct drm_connector_list_iter {
1073 /* private: */
1074         struct drm_device *dev;
1075         struct drm_connector *conn;
1076 };
1077
1078 void drm_connector_list_iter_begin(struct drm_device *dev,
1079                                    struct drm_connector_list_iter *iter);
1080 struct drm_connector *
1081 drm_connector_list_iter_next(struct drm_connector_list_iter *iter);
1082 void drm_connector_list_iter_end(struct drm_connector_list_iter *iter);
1083
1084 /**
1085  * drm_for_each_connector_iter - connector_list iterator macro
1086  * @connector: &struct drm_connector pointer used as cursor
1087  * @iter: &struct drm_connector_list_iter
1088  *
1089  * Note that @connector is only valid within the list body, if you want to use
1090  * @connector after calling drm_connector_list_iter_end() then you need to grab
1091  * your own reference first using drm_connector_get().
1092  */
1093 #define drm_for_each_connector_iter(connector, iter) \
1094         while ((connector = drm_connector_list_iter_next(iter)))
1095
1096 #endif