Loading...
1/*
2 * Copyright © 2006 Keith Packard
3 * Copyright © 2007-2008 Dave Airlie
4 * Copyright © 2007-2008 Intel Corporation
5 * Jesse Barnes <jesse.barnes@intel.com>
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining a
8 * copy of this software and associated documentation files (the "Software"),
9 * to deal in the Software without restriction, including without limitation
10 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
11 * and/or sell copies of the Software, and to permit persons to whom the
12 * Software is furnished to do so, subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
20 * THE COPYRIGHT HOLDER(S) OR AUTHOR(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR
21 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
22 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
23 * OTHER DEALINGS IN THE SOFTWARE.
24 */
25#ifndef __DRM_CRTC_H__
26#define __DRM_CRTC_H__
27
28#include <linux/i2c.h>
29#include <linux/spinlock.h>
30#include <linux/types.h>
31#include <linux/idr.h>
32#include <linux/fb.h>
33#include <linux/hdmi.h>
34#include <linux/media-bus-format.h>
35#include <uapi/drm/drm_mode.h>
36#include <uapi/drm/drm_fourcc.h>
37#include <drm/drm_modeset_lock.h>
38
39struct drm_device;
40struct drm_mode_set;
41struct drm_framebuffer;
42struct drm_object_properties;
43struct drm_file;
44struct drm_clip_rect;
45struct device_node;
46struct fence;
47
48#define DRM_MODE_OBJECT_CRTC 0xcccccccc
49#define DRM_MODE_OBJECT_CONNECTOR 0xc0c0c0c0
50#define DRM_MODE_OBJECT_ENCODER 0xe0e0e0e0
51#define DRM_MODE_OBJECT_MODE 0xdededede
52#define DRM_MODE_OBJECT_PROPERTY 0xb0b0b0b0
53#define DRM_MODE_OBJECT_FB 0xfbfbfbfb
54#define DRM_MODE_OBJECT_BLOB 0xbbbbbbbb
55#define DRM_MODE_OBJECT_PLANE 0xeeeeeeee
56#define DRM_MODE_OBJECT_ANY 0
57
58struct drm_mode_object {
59 uint32_t id;
60 uint32_t type;
61 struct drm_object_properties *properties;
62};
63
64#define DRM_OBJECT_MAX_PROPERTY 24
65struct drm_object_properties {
66 int count, atomic_count;
67 /* NOTE: if we ever start dynamically destroying properties (ie.
68 * not at drm_mode_config_cleanup() time), then we'd have to do
69 * a better job of detaching property from mode objects to avoid
70 * dangling property pointers:
71 */
72 struct drm_property *properties[DRM_OBJECT_MAX_PROPERTY];
73 /* do not read/write values directly, but use drm_object_property_get_value()
74 * and drm_object_property_set_value():
75 */
76 uint64_t values[DRM_OBJECT_MAX_PROPERTY];
77};
78
79static inline int64_t U642I64(uint64_t val)
80{
81 return (int64_t)*((int64_t *)&val);
82}
83static inline uint64_t I642U64(int64_t val)
84{
85 return (uint64_t)*((uint64_t *)&val);
86}
87
88/*
89 * Rotation property bits. DRM_ROTATE_<degrees> rotates the image by the
90 * specified amount in degrees in counter clockwise direction. DRM_REFLECT_X and
91 * DRM_REFLECT_Y reflects the image along the specified axis prior to rotation
92 */
93#define DRM_ROTATE_MASK 0x0f
94#define DRM_ROTATE_0 0
95#define DRM_ROTATE_90 1
96#define DRM_ROTATE_180 2
97#define DRM_ROTATE_270 3
98#define DRM_REFLECT_MASK (~DRM_ROTATE_MASK)
99#define DRM_REFLECT_X 4
100#define DRM_REFLECT_Y 5
101
102enum drm_connector_force {
103 DRM_FORCE_UNSPECIFIED,
104 DRM_FORCE_OFF,
105 DRM_FORCE_ON, /* force on analog part normally */
106 DRM_FORCE_ON_DIGITAL, /* for DVI-I use digital connector */
107};
108
109#include <drm/drm_modes.h>
110
111enum drm_connector_status {
112 connector_status_connected = 1,
113 connector_status_disconnected = 2,
114 connector_status_unknown = 3,
115};
116
117enum subpixel_order {
118 SubPixelUnknown = 0,
119 SubPixelHorizontalRGB,
120 SubPixelHorizontalBGR,
121 SubPixelVerticalRGB,
122 SubPixelVerticalBGR,
123 SubPixelNone,
124};
125
126#define DRM_COLOR_FORMAT_RGB444 (1<<0)
127#define DRM_COLOR_FORMAT_YCRCB444 (1<<1)
128#define DRM_COLOR_FORMAT_YCRCB422 (1<<2)
129/*
130 * Describes a given display (e.g. CRT or flat panel) and its limitations.
131 */
132struct drm_display_info {
133 char name[DRM_DISPLAY_INFO_LEN];
134
135 /* Physical size */
136 unsigned int width_mm;
137 unsigned int height_mm;
138
139 /* Clock limits FIXME: storage format */
140 unsigned int min_vfreq, max_vfreq;
141 unsigned int min_hfreq, max_hfreq;
142 unsigned int pixel_clock;
143 unsigned int bpc;
144
145 enum subpixel_order subpixel_order;
146 u32 color_formats;
147
148 const u32 *bus_formats;
149 unsigned int num_bus_formats;
150
151 /* Mask of supported hdmi deep color modes */
152 u8 edid_hdmi_dc_modes;
153
154 u8 cea_rev;
155};
156
157/* data corresponds to displayid vend/prod/serial */
158struct drm_tile_group {
159 struct kref refcount;
160 struct drm_device *dev;
161 int id;
162 u8 group_data[8];
163};
164
165/**
166 * struct drm_framebuffer_funcs - framebuffer hooks
167 */
168struct drm_framebuffer_funcs {
169 /**
170 * @destroy:
171 *
172 * Clean up framebuffer resources, specifically also unreference the
173 * backing storage. The core guarantees to call this function for every
174 * framebuffer successfully created by ->fb_create() in
175 * &drm_mode_config_funcs. Drivers must also call
176 * drm_framebuffer_cleanup() to release DRM core resources for this
177 * framebuffer.
178 */
179 void (*destroy)(struct drm_framebuffer *framebuffer);
180
181 /**
182 * @create_handle:
183 *
184 * Create a buffer handle in the driver-specific buffer manager (either
185 * GEM or TTM) valid for the passed-in struct &drm_file. This is used by
186 * the core to implement the GETFB IOCTL, which returns (for
187 * sufficiently priviledged user) also a native buffer handle. This can
188 * be used for seamless transitions between modesetting clients by
189 * copying the current screen contents to a private buffer and blending
190 * between that and the new contents.
191 *
192 * GEM based drivers should call drm_gem_handle_create() to create the
193 * handle.
194 *
195 * RETURNS:
196 *
197 * 0 on success or a negative error code on failure.
198 */
199 int (*create_handle)(struct drm_framebuffer *fb,
200 struct drm_file *file_priv,
201 unsigned int *handle);
202 /**
203 * @dirty:
204 *
205 * Optional callback for the dirty fb IOCTL.
206 *
207 * Userspace can notify the driver via this callback that an area of the
208 * framebuffer has changed and should be flushed to the display
209 * hardware. This can also be used internally, e.g. by the fbdev
210 * emulation, though that's not the case currently.
211 *
212 * See documentation in drm_mode.h for the struct drm_mode_fb_dirty_cmd
213 * for more information as all the semantics and arguments have a one to
214 * one mapping on this function.
215 *
216 * RETURNS:
217 *
218 * 0 on success or a negative error code on failure.
219 */
220 int (*dirty)(struct drm_framebuffer *framebuffer,
221 struct drm_file *file_priv, unsigned flags,
222 unsigned color, struct drm_clip_rect *clips,
223 unsigned num_clips);
224};
225
226struct drm_framebuffer {
227 struct drm_device *dev;
228 /*
229 * Note that the fb is refcounted for the benefit of driver internals,
230 * for example some hw, disabling a CRTC/plane is asynchronous, and
231 * scanout does not actually complete until the next vblank. So some
232 * cleanup (like releasing the reference(s) on the backing GEM bo(s))
233 * should be deferred. In cases like this, the driver would like to
234 * hold a ref to the fb even though it has already been removed from
235 * userspace perspective.
236 */
237 struct kref refcount;
238 /*
239 * Place on the dev->mode_config.fb_list, access protected by
240 * dev->mode_config.fb_lock.
241 */
242 struct list_head head;
243 struct drm_mode_object base;
244 const struct drm_framebuffer_funcs *funcs;
245 unsigned int pitches[4];
246 unsigned int offsets[4];
247 uint64_t modifier[4];
248 unsigned int width;
249 unsigned int height;
250 /* depth can be 15 or 16 */
251 unsigned int depth;
252 int bits_per_pixel;
253 int flags;
254 uint32_t pixel_format; /* fourcc format */
255 struct list_head filp_head;
256};
257
258struct drm_property_blob {
259 struct drm_mode_object base;
260 struct drm_device *dev;
261 struct kref refcount;
262 struct list_head head_global;
263 struct list_head head_file;
264 size_t length;
265 unsigned char data[];
266};
267
268struct drm_property_enum {
269 uint64_t value;
270 struct list_head head;
271 char name[DRM_PROP_NAME_LEN];
272};
273
274struct drm_property {
275 struct list_head head;
276 struct drm_mode_object base;
277 uint32_t flags;
278 char name[DRM_PROP_NAME_LEN];
279 uint32_t num_values;
280 uint64_t *values;
281 struct drm_device *dev;
282
283 struct list_head enum_list;
284};
285
286struct drm_crtc;
287struct drm_connector;
288struct drm_encoder;
289struct drm_pending_vblank_event;
290struct drm_plane;
291struct drm_bridge;
292struct drm_atomic_state;
293
294struct drm_crtc_helper_funcs;
295struct drm_encoder_helper_funcs;
296struct drm_connector_helper_funcs;
297struct drm_plane_helper_funcs;
298
299/**
300 * struct drm_crtc_state - mutable CRTC state
301 * @crtc: backpointer to the CRTC
302 * @enable: whether the CRTC should be enabled, gates all other state
303 * @active: whether the CRTC is actively displaying (used for DPMS)
304 * @planes_changed: planes on this crtc are updated
305 * @mode_changed: crtc_state->mode or crtc_state->enable has been changed
306 * @active_changed: crtc_state->active has been toggled.
307 * @connectors_changed: connectors to this crtc have been updated
308 * @color_mgmt_changed: color management properties have changed (degamma or
309 * gamma LUT or CSC matrix)
310 * @plane_mask: bitmask of (1 << drm_plane_index(plane)) of attached planes
311 * @connector_mask: bitmask of (1 << drm_connector_index(connector)) of attached connectors
312 * @encoder_mask: bitmask of (1 << drm_encoder_index(encoder)) of attached encoders
313 * @last_vblank_count: for helpers and drivers to capture the vblank of the
314 * update to ensure framebuffer cleanup isn't done too early
315 * @adjusted_mode: for use by helpers and drivers to compute adjusted mode timings
316 * @mode: current mode timings
317 * @degamma_lut: Lookup table for converting framebuffer pixel data
318 * before apply the conversion matrix
319 * @ctm: Transformation matrix
320 * @gamma_lut: Lookup table for converting pixel data after the
321 * conversion matrix
322 * @event: optional pointer to a DRM event to signal upon completion of the
323 * state update
324 * @state: backpointer to global drm_atomic_state
325 *
326 * Note that the distinction between @enable and @active is rather subtile:
327 * Flipping @active while @enable is set without changing anything else may
328 * never return in a failure from the ->atomic_check callback. Userspace assumes
329 * that a DPMS On will always succeed. In other words: @enable controls resource
330 * assignment, @active controls the actual hardware state.
331 */
332struct drm_crtc_state {
333 struct drm_crtc *crtc;
334
335 bool enable;
336 bool active;
337
338 /* computed state bits used by helpers and drivers */
339 bool planes_changed : 1;
340 bool mode_changed : 1;
341 bool active_changed : 1;
342 bool connectors_changed : 1;
343 bool color_mgmt_changed : 1;
344
345 /* attached planes bitmask:
346 * WARNING: transitional helpers do not maintain plane_mask so
347 * drivers not converted over to atomic helpers should not rely
348 * on plane_mask being accurate!
349 */
350 u32 plane_mask;
351
352 u32 connector_mask;
353 u32 encoder_mask;
354
355 /* last_vblank_count: for vblank waits before cleanup */
356 u32 last_vblank_count;
357
358 /* adjusted_mode: for use by helpers and drivers */
359 struct drm_display_mode adjusted_mode;
360
361 struct drm_display_mode mode;
362
363 /* blob property to expose current mode to atomic userspace */
364 struct drm_property_blob *mode_blob;
365
366 /* blob property to expose color management to userspace */
367 struct drm_property_blob *degamma_lut;
368 struct drm_property_blob *ctm;
369 struct drm_property_blob *gamma_lut;
370
371 struct drm_pending_vblank_event *event;
372
373 struct drm_atomic_state *state;
374};
375
376/**
377 * struct drm_crtc_funcs - control CRTCs for a given device
378 *
379 * The drm_crtc_funcs structure is the central CRTC management structure
380 * in the DRM. Each CRTC controls one or more connectors (note that the name
381 * CRTC is simply historical, a CRTC may control LVDS, VGA, DVI, TV out, etc.
382 * connectors, not just CRTs).
383 *
384 * Each driver is responsible for filling out this structure at startup time,
385 * in addition to providing other modesetting features, like i2c and DDC
386 * bus accessors.
387 */
388struct drm_crtc_funcs {
389 /**
390 * @reset:
391 *
392 * Reset CRTC hardware and software state to off. This function isn't
393 * called by the core directly, only through drm_mode_config_reset().
394 * It's not a helper hook only for historical reasons.
395 *
396 * Atomic drivers can use drm_atomic_helper_crtc_reset() to reset
397 * atomic state using this hook.
398 */
399 void (*reset)(struct drm_crtc *crtc);
400
401 /**
402 * @cursor_set:
403 *
404 * Update the cursor image. The cursor position is relative to the CRTC
405 * and can be partially or fully outside of the visible area.
406 *
407 * Note that contrary to all other KMS functions the legacy cursor entry
408 * points don't take a framebuffer object, but instead take directly a
409 * raw buffer object id from the driver's buffer manager (which is
410 * either GEM or TTM for current drivers).
411 *
412 * This entry point is deprecated, drivers should instead implement
413 * universal plane support and register a proper cursor plane using
414 * drm_crtc_init_with_planes().
415 *
416 * This callback is optional
417 *
418 * RETURNS:
419 *
420 * 0 on success or a negative error code on failure.
421 */
422 int (*cursor_set)(struct drm_crtc *crtc, struct drm_file *file_priv,
423 uint32_t handle, uint32_t width, uint32_t height);
424
425 /**
426 * @cursor_set2:
427 *
428 * Update the cursor image, including hotspot information. The hotspot
429 * must not affect the cursor position in CRTC coordinates, but is only
430 * meant as a hint for virtualized display hardware to coordinate the
431 * guests and hosts cursor position. The cursor hotspot is relative to
432 * the cursor image. Otherwise this works exactly like @cursor_set.
433 *
434 * This entry point is deprecated, drivers should instead implement
435 * universal plane support and register a proper cursor plane using
436 * drm_crtc_init_with_planes().
437 *
438 * This callback is optional.
439 *
440 * RETURNS:
441 *
442 * 0 on success or a negative error code on failure.
443 */
444 int (*cursor_set2)(struct drm_crtc *crtc, struct drm_file *file_priv,
445 uint32_t handle, uint32_t width, uint32_t height,
446 int32_t hot_x, int32_t hot_y);
447
448 /**
449 * @cursor_move:
450 *
451 * Update the cursor position. The cursor does not need to be visible
452 * when this hook is called.
453 *
454 * This entry point is deprecated, drivers should instead implement
455 * universal plane support and register a proper cursor plane using
456 * drm_crtc_init_with_planes().
457 *
458 * This callback is optional.
459 *
460 * RETURNS:
461 *
462 * 0 on success or a negative error code on failure.
463 */
464 int (*cursor_move)(struct drm_crtc *crtc, int x, int y);
465
466 /**
467 * @gamma_set:
468 *
469 * Set gamma on the CRTC.
470 *
471 * This callback is optional.
472 *
473 * NOTE:
474 *
475 * Drivers that support gamma tables and also fbdev emulation through
476 * the provided helper library need to take care to fill out the gamma
477 * hooks for both. Currently there's a bit an unfortunate duplication
478 * going on, which should eventually be unified to just one set of
479 * hooks.
480 */
481 void (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b,
482 uint32_t start, uint32_t size);
483
484 /**
485 * @destroy:
486 *
487 * Clean up plane resources. This is only called at driver unload time
488 * through drm_mode_config_cleanup() since a CRTC cannot be hotplugged
489 * in DRM.
490 */
491 void (*destroy)(struct drm_crtc *crtc);
492
493 /**
494 * @set_config:
495 *
496 * This is the main legacy entry point to change the modeset state on a
497 * CRTC. All the details of the desired configuration are passed in a
498 * struct &drm_mode_set - see there for details.
499 *
500 * Drivers implementing atomic modeset should use
501 * drm_atomic_helper_set_config() to implement this hook.
502 *
503 * RETURNS:
504 *
505 * 0 on success or a negative error code on failure.
506 */
507 int (*set_config)(struct drm_mode_set *set);
508
509 /**
510 * @page_flip:
511 *
512 * Legacy entry point to schedule a flip to the given framebuffer.
513 *
514 * Page flipping is a synchronization mechanism that replaces the frame
515 * buffer being scanned out by the CRTC with a new frame buffer during
516 * vertical blanking, avoiding tearing (except when requested otherwise
517 * through the DRM_MODE_PAGE_FLIP_ASYNC flag). When an application
518 * requests a page flip the DRM core verifies that the new frame buffer
519 * is large enough to be scanned out by the CRTC in the currently
520 * configured mode and then calls the CRTC ->page_flip() operation with a
521 * pointer to the new frame buffer.
522 *
523 * The driver must wait for any pending rendering to the new framebuffer
524 * to complete before executing the flip. It should also wait for any
525 * pending rendering from other drivers if the underlying buffer is a
526 * shared dma-buf.
527 *
528 * An application can request to be notified when the page flip has
529 * completed. The drm core will supply a struct &drm_event in the event
530 * parameter in this case. This can be handled by the
531 * drm_crtc_send_vblank_event() function, which the driver should call on
532 * the provided event upon completion of the flip. Note that if
533 * the driver supports vblank signalling and timestamping the vblank
534 * counters and timestamps must agree with the ones returned from page
535 * flip events. With the current vblank helper infrastructure this can
536 * be achieved by holding a vblank reference while the page flip is
537 * pending, acquired through drm_crtc_vblank_get() and released with
538 * drm_crtc_vblank_put(). Drivers are free to implement their own vblank
539 * counter and timestamp tracking though, e.g. if they have accurate
540 * timestamp registers in hardware.
541 *
542 * FIXME:
543 *
544 * Up to that point drivers need to manage events themselves and can use
545 * even->base.list freely for that. Specifically they need to ensure
546 * that they don't send out page flip (or vblank) events for which the
547 * corresponding drm file has been closed already. The drm core
548 * unfortunately does not (yet) take care of that. Therefore drivers
549 * currently must clean up and release pending events in their
550 * ->preclose driver function.
551 *
552 * This callback is optional.
553 *
554 * NOTE:
555 *
556 * Very early versions of the KMS ABI mandated that the driver must
557 * block (but not reject) any rendering to the old framebuffer until the
558 * flip operation has completed and the old framebuffer is no longer
559 * visible. This requirement has been lifted, and userspace is instead
560 * expected to request delivery of an event and wait with recycling old
561 * buffers until such has been received.
562 *
563 * RETURNS:
564 *
565 * 0 on success or a negative error code on failure. Note that if a
566 * ->page_flip() operation is already pending the callback should return
567 * -EBUSY. Pageflips on a disabled CRTC (either by setting a NULL mode
568 * or just runtime disabled through DPMS respectively the new atomic
569 * "ACTIVE" state) should result in an -EINVAL error code. Note that
570 * drm_atomic_helper_page_flip() checks this already for atomic drivers.
571 */
572 int (*page_flip)(struct drm_crtc *crtc,
573 struct drm_framebuffer *fb,
574 struct drm_pending_vblank_event *event,
575 uint32_t flags);
576
577 /**
578 * @set_property:
579 *
580 * This is the legacy entry point to update a property attached to the
581 * CRTC.
582 *
583 * Drivers implementing atomic modeset should use
584 * drm_atomic_helper_crtc_set_property() to implement this hook.
585 *
586 * This callback is optional if the driver does not support any legacy
587 * driver-private properties.
588 *
589 * RETURNS:
590 *
591 * 0 on success or a negative error code on failure.
592 */
593 int (*set_property)(struct drm_crtc *crtc,
594 struct drm_property *property, uint64_t val);
595
596 /**
597 * @atomic_duplicate_state:
598 *
599 * Duplicate the current atomic state for this CRTC and return it.
600 * The core and helpers gurantee that any atomic state duplicated with
601 * this hook and still owned by the caller (i.e. not transferred to the
602 * driver by calling ->atomic_commit() from struct
603 * &drm_mode_config_funcs) will be cleaned up by calling the
604 * @atomic_destroy_state hook in this structure.
605 *
606 * Atomic drivers which don't subclass struct &drm_crtc should use
607 * drm_atomic_helper_crtc_duplicate_state(). Drivers that subclass the
608 * state structure to extend it with driver-private state should use
609 * __drm_atomic_helper_crtc_duplicate_state() to make sure shared state is
610 * duplicated in a consistent fashion across drivers.
611 *
612 * It is an error to call this hook before crtc->state has been
613 * initialized correctly.
614 *
615 * NOTE:
616 *
617 * If the duplicate state references refcounted resources this hook must
618 * acquire a reference for each of them. The driver must release these
619 * references again in @atomic_destroy_state.
620 *
621 * RETURNS:
622 *
623 * Duplicated atomic state or NULL when the allocation failed.
624 */
625 struct drm_crtc_state *(*atomic_duplicate_state)(struct drm_crtc *crtc);
626
627 /**
628 * @atomic_destroy_state:
629 *
630 * Destroy a state duplicated with @atomic_duplicate_state and release
631 * or unreference all resources it references
632 */
633 void (*atomic_destroy_state)(struct drm_crtc *crtc,
634 struct drm_crtc_state *state);
635
636 /**
637 * @atomic_set_property:
638 *
639 * Decode a driver-private property value and store the decoded value
640 * into the passed-in state structure. Since the atomic core decodes all
641 * standardized properties (even for extensions beyond the core set of
642 * properties which might not be implemented by all drivers) this
643 * requires drivers to subclass the state structure.
644 *
645 * Such driver-private properties should really only be implemented for
646 * truly hardware/vendor specific state. Instead it is preferred to
647 * standardize atomic extension and decode the properties used to expose
648 * such an extension in the core.
649 *
650 * Do not call this function directly, use
651 * drm_atomic_crtc_set_property() instead.
652 *
653 * This callback is optional if the driver does not support any
654 * driver-private atomic properties.
655 *
656 * NOTE:
657 *
658 * This function is called in the state assembly phase of atomic
659 * modesets, which can be aborted for any reason (including on
660 * userspace's request to just check whether a configuration would be
661 * possible). Drivers MUST NOT touch any persistent state (hardware or
662 * software) or data structures except the passed in @state parameter.
663 *
664 * Also since userspace controls in which order properties are set this
665 * function must not do any input validation (since the state update is
666 * incomplete and hence likely inconsistent). Instead any such input
667 * validation must be done in the various atomic_check callbacks.
668 *
669 * RETURNS:
670 *
671 * 0 if the property has been found, -EINVAL if the property isn't
672 * implemented by the driver (which should never happen, the core only
673 * asks for properties attached to this CRTC). No other validation is
674 * allowed by the driver. The core already checks that the property
675 * value is within the range (integer, valid enum value, ...) the driver
676 * set when registering the property.
677 */
678 int (*atomic_set_property)(struct drm_crtc *crtc,
679 struct drm_crtc_state *state,
680 struct drm_property *property,
681 uint64_t val);
682 /**
683 * @atomic_get_property:
684 *
685 * Reads out the decoded driver-private property. This is used to
686 * implement the GETCRTC IOCTL.
687 *
688 * Do not call this function directly, use
689 * drm_atomic_crtc_get_property() instead.
690 *
691 * This callback is optional if the driver does not support any
692 * driver-private atomic properties.
693 *
694 * RETURNS:
695 *
696 * 0 on success, -EINVAL if the property isn't implemented by the
697 * driver (which should never happen, the core only asks for
698 * properties attached to this CRTC).
699 */
700 int (*atomic_get_property)(struct drm_crtc *crtc,
701 const struct drm_crtc_state *state,
702 struct drm_property *property,
703 uint64_t *val);
704};
705
706/**
707 * struct drm_crtc - central CRTC control structure
708 * @dev: parent DRM device
709 * @port: OF node used by drm_of_find_possible_crtcs()
710 * @head: list management
711 * @mutex: per-CRTC locking
712 * @base: base KMS object for ID tracking etc.
713 * @primary: primary plane for this CRTC
714 * @cursor: cursor plane for this CRTC
715 * @cursor_x: current x position of the cursor, used for universal cursor planes
716 * @cursor_y: current y position of the cursor, used for universal cursor planes
717 * @enabled: is this CRTC enabled?
718 * @mode: current mode timings
719 * @hwmode: mode timings as programmed to hw regs
720 * @x: x position on screen
721 * @y: y position on screen
722 * @funcs: CRTC control functions
723 * @gamma_size: size of gamma ramp
724 * @gamma_store: gamma ramp values
725 * @helper_private: mid-layer private data
726 * @properties: property tracking for this CRTC
727 * @state: current atomic state for this CRTC
728 * @acquire_ctx: per-CRTC implicit acquire context used by atomic drivers for
729 * legacy IOCTLs
730 *
731 * Each CRTC may have one or more connectors associated with it. This structure
732 * allows the CRTC to be controlled.
733 */
734struct drm_crtc {
735 struct drm_device *dev;
736 struct device_node *port;
737 struct list_head head;
738
739 char *name;
740
741 /*
742 * crtc mutex
743 *
744 * This provides a read lock for the overall crtc state (mode, dpms
745 * state, ...) and a write lock for everything which can be update
746 * without a full modeset (fb, cursor data, ...)
747 */
748 struct drm_modeset_lock mutex;
749
750 struct drm_mode_object base;
751
752 /* primary and cursor planes for CRTC */
753 struct drm_plane *primary;
754 struct drm_plane *cursor;
755
756 /* position of cursor plane on crtc */
757 int cursor_x;
758 int cursor_y;
759
760 bool enabled;
761
762 /* Requested mode from modesetting. */
763 struct drm_display_mode mode;
764
765 /* Programmed mode in hw, after adjustments for encoders,
766 * crtc, panel scaling etc. Needed for timestamping etc.
767 */
768 struct drm_display_mode hwmode;
769
770 int x, y;
771 const struct drm_crtc_funcs *funcs;
772
773 /* Legacy FB CRTC gamma size for reporting to userspace */
774 uint32_t gamma_size;
775 uint16_t *gamma_store;
776
777 /* if you are using the helper */
778 const struct drm_crtc_helper_funcs *helper_private;
779
780 struct drm_object_properties properties;
781
782 struct drm_crtc_state *state;
783
784 /*
785 * For legacy crtc IOCTLs so that atomic drivers can get at the locking
786 * acquire context.
787 */
788 struct drm_modeset_acquire_ctx *acquire_ctx;
789};
790
791/**
792 * struct drm_connector_state - mutable connector state
793 * @connector: backpointer to the connector
794 * @crtc: CRTC to connect connector to, NULL if disabled
795 * @best_encoder: can be used by helpers and drivers to select the encoder
796 * @state: backpointer to global drm_atomic_state
797 */
798struct drm_connector_state {
799 struct drm_connector *connector;
800
801 struct drm_crtc *crtc; /* do not write directly, use drm_atomic_set_crtc_for_connector() */
802
803 struct drm_encoder *best_encoder;
804
805 struct drm_atomic_state *state;
806};
807
808/**
809 * struct drm_connector_funcs - control connectors on a given device
810 *
811 * Each CRTC may have one or more connectors attached to it. The functions
812 * below allow the core DRM code to control connectors, enumerate available modes,
813 * etc.
814 */
815struct drm_connector_funcs {
816 /**
817 * @dpms:
818 *
819 * Legacy entry point to set the per-connector DPMS state. Legacy DPMS
820 * is exposed as a standard property on the connector, but diverted to
821 * this callback in the drm core. Note that atomic drivers don't
822 * implement the 4 level DPMS support on the connector any more, but
823 * instead only have an on/off "ACTIVE" property on the CRTC object.
824 *
825 * Drivers implementing atomic modeset should use
826 * drm_atomic_helper_connector_dpms() to implement this hook.
827 *
828 * RETURNS:
829 *
830 * 0 on success or a negative error code on failure.
831 */
832 int (*dpms)(struct drm_connector *connector, int mode);
833
834 /**
835 * @reset:
836 *
837 * Reset connector hardware and software state to off. This function isn't
838 * called by the core directly, only through drm_mode_config_reset().
839 * It's not a helper hook only for historical reasons.
840 *
841 * Atomic drivers can use drm_atomic_helper_connector_reset() to reset
842 * atomic state using this hook.
843 */
844 void (*reset)(struct drm_connector *connector);
845
846 /**
847 * @detect:
848 *
849 * Check to see if anything is attached to the connector. The parameter
850 * force is set to false whilst polling, true when checking the
851 * connector due to a user request. force can be used by the driver to
852 * avoid expensive, destructive operations during automated probing.
853 *
854 * FIXME:
855 *
856 * Note that this hook is only called by the probe helper. It's not in
857 * the helper library vtable purely for historical reasons. The only DRM
858 * core entry point to probe connector state is @fill_modes.
859 *
860 * RETURNS:
861 *
862 * drm_connector_status indicating the connector's status.
863 */
864 enum drm_connector_status (*detect)(struct drm_connector *connector,
865 bool force);
866
867 /**
868 * @force:
869 *
870 * This function is called to update internal encoder state when the
871 * connector is forced to a certain state by userspace, either through
872 * the sysfs interfaces or on the kernel cmdline. In that case the
873 * @detect callback isn't called.
874 *
875 * FIXME:
876 *
877 * Note that this hook is only called by the probe helper. It's not in
878 * the helper library vtable purely for historical reasons. The only DRM
879 * core entry point to probe connector state is @fill_modes.
880 */
881 void (*force)(struct drm_connector *connector);
882
883 /**
884 * @fill_modes:
885 *
886 * Entry point for output detection and basic mode validation. The
887 * driver should reprobe the output if needed (e.g. when hotplug
888 * handling is unreliable), add all detected modes to connector->modes
889 * and filter out any the device can't support in any configuration. It
890 * also needs to filter out any modes wider or higher than the
891 * parameters max_width and max_height indicate.
892 *
893 * The drivers must also prune any modes no longer valid from
894 * connector->modes. Furthermore it must update connector->status and
895 * connector->edid. If no EDID has been received for this output
896 * connector->edid must be NULL.
897 *
898 * Drivers using the probe helpers should use
899 * drm_helper_probe_single_connector_modes() or
900 * drm_helper_probe_single_connector_modes_nomerge() to implement this
901 * function.
902 *
903 * RETURNS:
904 *
905 * The number of modes detected and filled into connector->modes.
906 */
907 int (*fill_modes)(struct drm_connector *connector, uint32_t max_width, uint32_t max_height);
908
909 /**
910 * @set_property:
911 *
912 * This is the legacy entry point to update a property attached to the
913 * connector.
914 *
915 * Drivers implementing atomic modeset should use
916 * drm_atomic_helper_connector_set_property() to implement this hook.
917 *
918 * This callback is optional if the driver does not support any legacy
919 * driver-private properties.
920 *
921 * RETURNS:
922 *
923 * 0 on success or a negative error code on failure.
924 */
925 int (*set_property)(struct drm_connector *connector, struct drm_property *property,
926 uint64_t val);
927
928 /**
929 * @destroy:
930 *
931 * Clean up connector resources. This is called at driver unload time
932 * through drm_mode_config_cleanup(). It can also be called at runtime
933 * when a connector is being hot-unplugged for drivers that support
934 * connector hotplugging (e.g. DisplayPort MST).
935 */
936 void (*destroy)(struct drm_connector *connector);
937
938 /**
939 * @atomic_duplicate_state:
940 *
941 * Duplicate the current atomic state for this connector and return it.
942 * The core and helpers gurantee that any atomic state duplicated with
943 * this hook and still owned by the caller (i.e. not transferred to the
944 * driver by calling ->atomic_commit() from struct
945 * &drm_mode_config_funcs) will be cleaned up by calling the
946 * @atomic_destroy_state hook in this structure.
947 *
948 * Atomic drivers which don't subclass struct &drm_connector_state should use
949 * drm_atomic_helper_connector_duplicate_state(). Drivers that subclass the
950 * state structure to extend it with driver-private state should use
951 * __drm_atomic_helper_connector_duplicate_state() to make sure shared state is
952 * duplicated in a consistent fashion across drivers.
953 *
954 * It is an error to call this hook before connector->state has been
955 * initialized correctly.
956 *
957 * NOTE:
958 *
959 * If the duplicate state references refcounted resources this hook must
960 * acquire a reference for each of them. The driver must release these
961 * references again in @atomic_destroy_state.
962 *
963 * RETURNS:
964 *
965 * Duplicated atomic state or NULL when the allocation failed.
966 */
967 struct drm_connector_state *(*atomic_duplicate_state)(struct drm_connector *connector);
968
969 /**
970 * @atomic_destroy_state:
971 *
972 * Destroy a state duplicated with @atomic_duplicate_state and release
973 * or unreference all resources it references
974 */
975 void (*atomic_destroy_state)(struct drm_connector *connector,
976 struct drm_connector_state *state);
977
978 /**
979 * @atomic_set_property:
980 *
981 * Decode a driver-private property value and store the decoded value
982 * into the passed-in state structure. Since the atomic core decodes all
983 * standardized properties (even for extensions beyond the core set of
984 * properties which might not be implemented by all drivers) this
985 * requires drivers to subclass the state structure.
986 *
987 * Such driver-private properties should really only be implemented for
988 * truly hardware/vendor specific state. Instead it is preferred to
989 * standardize atomic extension and decode the properties used to expose
990 * such an extension in the core.
991 *
992 * Do not call this function directly, use
993 * drm_atomic_connector_set_property() instead.
994 *
995 * This callback is optional if the driver does not support any
996 * driver-private atomic properties.
997 *
998 * NOTE:
999 *
1000 * This function is called in the state assembly phase of atomic
1001 * modesets, which can be aborted for any reason (including on
1002 * userspace's request to just check whether a configuration would be
1003 * possible). Drivers MUST NOT touch any persistent state (hardware or
1004 * software) or data structures except the passed in @state parameter.
1005 *
1006 * Also since userspace controls in which order properties are set this
1007 * function must not do any input validation (since the state update is
1008 * incomplete and hence likely inconsistent). Instead any such input
1009 * validation must be done in the various atomic_check callbacks.
1010 *
1011 * RETURNS:
1012 *
1013 * 0 if the property has been found, -EINVAL if the property isn't
1014 * implemented by the driver (which shouldn't ever happen, the core only
1015 * asks for properties attached to this connector). No other validation
1016 * is allowed by the driver. The core already checks that the property
1017 * value is within the range (integer, valid enum value, ...) the driver
1018 * set when registering the property.
1019 */
1020 int (*atomic_set_property)(struct drm_connector *connector,
1021 struct drm_connector_state *state,
1022 struct drm_property *property,
1023 uint64_t val);
1024
1025 /**
1026 * @atomic_get_property:
1027 *
1028 * Reads out the decoded driver-private property. This is used to
1029 * implement the GETCONNECTOR IOCTL.
1030 *
1031 * Do not call this function directly, use
1032 * drm_atomic_connector_get_property() instead.
1033 *
1034 * This callback is optional if the driver does not support any
1035 * driver-private atomic properties.
1036 *
1037 * RETURNS:
1038 *
1039 * 0 on success, -EINVAL if the property isn't implemented by the
1040 * driver (which shouldn't ever happen, the core only asks for
1041 * properties attached to this connector).
1042 */
1043 int (*atomic_get_property)(struct drm_connector *connector,
1044 const struct drm_connector_state *state,
1045 struct drm_property *property,
1046 uint64_t *val);
1047};
1048
1049/**
1050 * struct drm_encoder_funcs - encoder controls
1051 *
1052 * Encoders sit between CRTCs and connectors.
1053 */
1054struct drm_encoder_funcs {
1055 /**
1056 * @reset:
1057 *
1058 * Reset encoder hardware and software state to off. This function isn't
1059 * called by the core directly, only through drm_mode_config_reset().
1060 * It's not a helper hook only for historical reasons.
1061 */
1062 void (*reset)(struct drm_encoder *encoder);
1063
1064 /**
1065 * @destroy:
1066 *
1067 * Clean up encoder resources. This is only called at driver unload time
1068 * through drm_mode_config_cleanup() since an encoder cannot be
1069 * hotplugged in DRM.
1070 */
1071 void (*destroy)(struct drm_encoder *encoder);
1072};
1073
1074#define DRM_CONNECTOR_MAX_ENCODER 3
1075
1076/**
1077 * struct drm_encoder - central DRM encoder structure
1078 * @dev: parent DRM device
1079 * @head: list management
1080 * @base: base KMS object
1081 * @name: encoder name
1082 * @encoder_type: one of the %DRM_MODE_ENCODER_<foo> types in drm_mode.h
1083 * @possible_crtcs: bitmask of potential CRTC bindings
1084 * @possible_clones: bitmask of potential sibling encoders for cloning
1085 * @crtc: currently bound CRTC
1086 * @bridge: bridge associated to the encoder
1087 * @funcs: control functions
1088 * @helper_private: mid-layer private data
1089 *
1090 * CRTCs drive pixels to encoders, which convert them into signals
1091 * appropriate for a given connector or set of connectors.
1092 */
1093struct drm_encoder {
1094 struct drm_device *dev;
1095 struct list_head head;
1096
1097 struct drm_mode_object base;
1098 char *name;
1099 int encoder_type;
1100 uint32_t possible_crtcs;
1101 uint32_t possible_clones;
1102
1103 struct drm_crtc *crtc;
1104 struct drm_bridge *bridge;
1105 const struct drm_encoder_funcs *funcs;
1106 const struct drm_encoder_helper_funcs *helper_private;
1107};
1108
1109/* should we poll this connector for connects and disconnects */
1110/* hot plug detectable */
1111#define DRM_CONNECTOR_POLL_HPD (1 << 0)
1112/* poll for connections */
1113#define DRM_CONNECTOR_POLL_CONNECT (1 << 1)
1114/* can cleanly poll for disconnections without flickering the screen */
1115/* DACs should rarely do this without a lot of testing */
1116#define DRM_CONNECTOR_POLL_DISCONNECT (1 << 2)
1117
1118#define MAX_ELD_BYTES 128
1119
1120/**
1121 * struct drm_connector - central DRM connector control structure
1122 * @dev: parent DRM device
1123 * @kdev: kernel device for sysfs attributes
1124 * @attr: sysfs attributes
1125 * @head: list management
1126 * @base: base KMS object
1127 * @name: connector name
1128 * @connector_type: one of the %DRM_MODE_CONNECTOR_<foo> types from drm_mode.h
1129 * @connector_type_id: index into connector type enum
1130 * @interlace_allowed: can this connector handle interlaced modes?
1131 * @doublescan_allowed: can this connector handle doublescan?
1132 * @stereo_allowed: can this connector handle stereo modes?
1133 * @modes: modes available on this connector (from fill_modes() + user)
1134 * @status: one of the drm_connector_status enums (connected, not, or unknown)
1135 * @probed_modes: list of modes derived directly from the display
1136 * @display_info: information about attached display (e.g. from EDID)
1137 * @funcs: connector control functions
1138 * @edid_blob_ptr: DRM property containing EDID if present
1139 * @properties: property tracking for this connector
1140 * @path_blob_ptr: DRM blob property data for the DP MST path property
1141 * @polled: a %DRM_CONNECTOR_POLL_<foo> value for core driven polling
1142 * @dpms: current dpms state
1143 * @helper_private: mid-layer private data
1144 * @cmdline_mode: mode line parsed from the kernel cmdline for this connector
1145 * @force: a %DRM_FORCE_<foo> state for forced mode sets
1146 * @override_edid: has the EDID been overwritten through debugfs for testing?
1147 * @encoder_ids: valid encoders for this connector
1148 * @encoder: encoder driving this connector, if any
1149 * @eld: EDID-like data, if present
1150 * @dvi_dual: dual link DVI, if found
1151 * @max_tmds_clock: max clock rate, if found
1152 * @latency_present: AV delay info from ELD, if found
1153 * @video_latency: video latency info from ELD, if found
1154 * @audio_latency: audio latency info from ELD, if found
1155 * @null_edid_counter: track sinks that give us all zeros for the EDID
1156 * @bad_edid_counter: track sinks that give us an EDID with invalid checksum
1157 * @edid_corrupt: indicates whether the last read EDID was corrupt
1158 * @debugfs_entry: debugfs directory for this connector
1159 * @state: current atomic state for this connector
1160 * @has_tile: is this connector connected to a tiled monitor
1161 * @tile_group: tile group for the connected monitor
1162 * @tile_is_single_monitor: whether the tile is one monitor housing
1163 * @num_h_tile: number of horizontal tiles in the tile group
1164 * @num_v_tile: number of vertical tiles in the tile group
1165 * @tile_h_loc: horizontal location of this tile
1166 * @tile_v_loc: vertical location of this tile
1167 * @tile_h_size: horizontal size of this tile.
1168 * @tile_v_size: vertical size of this tile.
1169 *
1170 * Each connector may be connected to one or more CRTCs, or may be clonable by
1171 * another connector if they can share a CRTC. Each connector also has a specific
1172 * position in the broader display (referred to as a 'screen' though it could
1173 * span multiple monitors).
1174 */
1175struct drm_connector {
1176 struct drm_device *dev;
1177 struct device *kdev;
1178 struct device_attribute *attr;
1179 struct list_head head;
1180
1181 struct drm_mode_object base;
1182
1183 char *name;
1184 int connector_id;
1185 int connector_type;
1186 int connector_type_id;
1187 bool interlace_allowed;
1188 bool doublescan_allowed;
1189 bool stereo_allowed;
1190 struct list_head modes; /* list of modes on this connector */
1191
1192 enum drm_connector_status status;
1193
1194 /* these are modes added by probing with DDC or the BIOS */
1195 struct list_head probed_modes;
1196
1197 struct drm_display_info display_info;
1198 const struct drm_connector_funcs *funcs;
1199
1200 struct drm_property_blob *edid_blob_ptr;
1201 struct drm_object_properties properties;
1202
1203 struct drm_property_blob *path_blob_ptr;
1204
1205 struct drm_property_blob *tile_blob_ptr;
1206
1207 uint8_t polled; /* DRM_CONNECTOR_POLL_* */
1208
1209 /* requested DPMS state */
1210 int dpms;
1211
1212 const struct drm_connector_helper_funcs *helper_private;
1213
1214 /* forced on connector */
1215 struct drm_cmdline_mode cmdline_mode;
1216 enum drm_connector_force force;
1217 bool override_edid;
1218 uint32_t encoder_ids[DRM_CONNECTOR_MAX_ENCODER];
1219 struct drm_encoder *encoder; /* currently active encoder */
1220
1221 /* EDID bits */
1222 uint8_t eld[MAX_ELD_BYTES];
1223 bool dvi_dual;
1224 int max_tmds_clock; /* in MHz */
1225 bool latency_present[2];
1226 int video_latency[2]; /* [0]: progressive, [1]: interlaced */
1227 int audio_latency[2];
1228 int null_edid_counter; /* needed to workaround some HW bugs where we get all 0s */
1229 unsigned bad_edid_counter;
1230
1231 /* Flag for raw EDID header corruption - used in Displayport
1232 * compliance testing - * Displayport Link CTS Core 1.2 rev1.1 4.2.2.6
1233 */
1234 bool edid_corrupt;
1235
1236 struct dentry *debugfs_entry;
1237
1238 struct drm_connector_state *state;
1239
1240 /* DisplayID bits */
1241 bool has_tile;
1242 struct drm_tile_group *tile_group;
1243 bool tile_is_single_monitor;
1244
1245 uint8_t num_h_tile, num_v_tile;
1246 uint8_t tile_h_loc, tile_v_loc;
1247 uint16_t tile_h_size, tile_v_size;
1248};
1249
1250/**
1251 * struct drm_plane_state - mutable plane state
1252 * @plane: backpointer to the plane
1253 * @crtc: currently bound CRTC, NULL if disabled
1254 * @fb: currently bound framebuffer
1255 * @fence: optional fence to wait for before scanning out @fb
1256 * @crtc_x: left position of visible portion of plane on crtc
1257 * @crtc_y: upper position of visible portion of plane on crtc
1258 * @crtc_w: width of visible portion of plane on crtc
1259 * @crtc_h: height of visible portion of plane on crtc
1260 * @src_x: left position of visible portion of plane within
1261 * plane (in 16.16)
1262 * @src_y: upper position of visible portion of plane within
1263 * plane (in 16.16)
1264 * @src_w: width of visible portion of plane (in 16.16)
1265 * @src_h: height of visible portion of plane (in 16.16)
1266 * @state: backpointer to global drm_atomic_state
1267 */
1268struct drm_plane_state {
1269 struct drm_plane *plane;
1270
1271 struct drm_crtc *crtc; /* do not write directly, use drm_atomic_set_crtc_for_plane() */
1272 struct drm_framebuffer *fb; /* do not write directly, use drm_atomic_set_fb_for_plane() */
1273 struct fence *fence;
1274
1275 /* Signed dest location allows it to be partially off screen */
1276 int32_t crtc_x, crtc_y;
1277 uint32_t crtc_w, crtc_h;
1278
1279 /* Source values are 16.16 fixed point */
1280 uint32_t src_x, src_y;
1281 uint32_t src_h, src_w;
1282
1283 /* Plane rotation */
1284 unsigned int rotation;
1285
1286 struct drm_atomic_state *state;
1287};
1288
1289
1290/**
1291 * struct drm_plane_funcs - driver plane control functions
1292 */
1293struct drm_plane_funcs {
1294 /**
1295 * @update_plane:
1296 *
1297 * This is the legacy entry point to enable and configure the plane for
1298 * the given CRTC and framebuffer. It is never called to disable the
1299 * plane, i.e. the passed-in crtc and fb paramters are never NULL.
1300 *
1301 * The source rectangle in frame buffer memory coordinates is given by
1302 * the src_x, src_y, src_w and src_h parameters (as 16.16 fixed point
1303 * values). Devices that don't support subpixel plane coordinates can
1304 * ignore the fractional part.
1305 *
1306 * The destination rectangle in CRTC coordinates is given by the
1307 * crtc_x, crtc_y, crtc_w and crtc_h parameters (as integer values).
1308 * Devices scale the source rectangle to the destination rectangle. If
1309 * scaling is not supported, and the source rectangle size doesn't match
1310 * the destination rectangle size, the driver must return a
1311 * -<errorname>EINVAL</errorname> error.
1312 *
1313 * Drivers implementing atomic modeset should use
1314 * drm_atomic_helper_update_plane() to implement this hook.
1315 *
1316 * RETURNS:
1317 *
1318 * 0 on success or a negative error code on failure.
1319 */
1320 int (*update_plane)(struct drm_plane *plane,
1321 struct drm_crtc *crtc, struct drm_framebuffer *fb,
1322 int crtc_x, int crtc_y,
1323 unsigned int crtc_w, unsigned int crtc_h,
1324 uint32_t src_x, uint32_t src_y,
1325 uint32_t src_w, uint32_t src_h);
1326
1327 /**
1328 * @disable_plane:
1329 *
1330 * This is the legacy entry point to disable the plane. The DRM core
1331 * calls this method in response to a DRM_IOCTL_MODE_SETPLANE IOCTL call
1332 * with the frame buffer ID set to 0. Disabled planes must not be
1333 * processed by the CRTC.
1334 *
1335 * Drivers implementing atomic modeset should use
1336 * drm_atomic_helper_disable_plane() to implement this hook.
1337 *
1338 * RETURNS:
1339 *
1340 * 0 on success or a negative error code on failure.
1341 */
1342 int (*disable_plane)(struct drm_plane *plane);
1343
1344 /**
1345 * @destroy:
1346 *
1347 * Clean up plane resources. This is only called at driver unload time
1348 * through drm_mode_config_cleanup() since a plane cannot be hotplugged
1349 * in DRM.
1350 */
1351 void (*destroy)(struct drm_plane *plane);
1352
1353 /**
1354 * @reset:
1355 *
1356 * Reset plane hardware and software state to off. This function isn't
1357 * called by the core directly, only through drm_mode_config_reset().
1358 * It's not a helper hook only for historical reasons.
1359 *
1360 * Atomic drivers can use drm_atomic_helper_plane_reset() to reset
1361 * atomic state using this hook.
1362 */
1363 void (*reset)(struct drm_plane *plane);
1364
1365 /**
1366 * @set_property:
1367 *
1368 * This is the legacy entry point to update a property attached to the
1369 * plane.
1370 *
1371 * Drivers implementing atomic modeset should use
1372 * drm_atomic_helper_plane_set_property() to implement this hook.
1373 *
1374 * This callback is optional if the driver does not support any legacy
1375 * driver-private properties.
1376 *
1377 * RETURNS:
1378 *
1379 * 0 on success or a negative error code on failure.
1380 */
1381 int (*set_property)(struct drm_plane *plane,
1382 struct drm_property *property, uint64_t val);
1383
1384 /**
1385 * @atomic_duplicate_state:
1386 *
1387 * Duplicate the current atomic state for this plane and return it.
1388 * The core and helpers gurantee that any atomic state duplicated with
1389 * this hook and still owned by the caller (i.e. not transferred to the
1390 * driver by calling ->atomic_commit() from struct
1391 * &drm_mode_config_funcs) will be cleaned up by calling the
1392 * @atomic_destroy_state hook in this structure.
1393 *
1394 * Atomic drivers which don't subclass struct &drm_plane_state should use
1395 * drm_atomic_helper_plane_duplicate_state(). Drivers that subclass the
1396 * state structure to extend it with driver-private state should use
1397 * __drm_atomic_helper_plane_duplicate_state() to make sure shared state is
1398 * duplicated in a consistent fashion across drivers.
1399 *
1400 * It is an error to call this hook before plane->state has been
1401 * initialized correctly.
1402 *
1403 * NOTE:
1404 *
1405 * If the duplicate state references refcounted resources this hook must
1406 * acquire a reference for each of them. The driver must release these
1407 * references again in @atomic_destroy_state.
1408 *
1409 * RETURNS:
1410 *
1411 * Duplicated atomic state or NULL when the allocation failed.
1412 */
1413 struct drm_plane_state *(*atomic_duplicate_state)(struct drm_plane *plane);
1414
1415 /**
1416 * @atomic_destroy_state:
1417 *
1418 * Destroy a state duplicated with @atomic_duplicate_state and release
1419 * or unreference all resources it references
1420 */
1421 void (*atomic_destroy_state)(struct drm_plane *plane,
1422 struct drm_plane_state *state);
1423
1424 /**
1425 * @atomic_set_property:
1426 *
1427 * Decode a driver-private property value and store the decoded value
1428 * into the passed-in state structure. Since the atomic core decodes all
1429 * standardized properties (even for extensions beyond the core set of
1430 * properties which might not be implemented by all drivers) this
1431 * requires drivers to subclass the state structure.
1432 *
1433 * Such driver-private properties should really only be implemented for
1434 * truly hardware/vendor specific state. Instead it is preferred to
1435 * standardize atomic extension and decode the properties used to expose
1436 * such an extension in the core.
1437 *
1438 * Do not call this function directly, use
1439 * drm_atomic_plane_set_property() instead.
1440 *
1441 * This callback is optional if the driver does not support any
1442 * driver-private atomic properties.
1443 *
1444 * NOTE:
1445 *
1446 * This function is called in the state assembly phase of atomic
1447 * modesets, which can be aborted for any reason (including on
1448 * userspace's request to just check whether a configuration would be
1449 * possible). Drivers MUST NOT touch any persistent state (hardware or
1450 * software) or data structures except the passed in @state parameter.
1451 *
1452 * Also since userspace controls in which order properties are set this
1453 * function must not do any input validation (since the state update is
1454 * incomplete and hence likely inconsistent). Instead any such input
1455 * validation must be done in the various atomic_check callbacks.
1456 *
1457 * RETURNS:
1458 *
1459 * 0 if the property has been found, -EINVAL if the property isn't
1460 * implemented by the driver (which shouldn't ever happen, the core only
1461 * asks for properties attached to this plane). No other validation is
1462 * allowed by the driver. The core already checks that the property
1463 * value is within the range (integer, valid enum value, ...) the driver
1464 * set when registering the property.
1465 */
1466 int (*atomic_set_property)(struct drm_plane *plane,
1467 struct drm_plane_state *state,
1468 struct drm_property *property,
1469 uint64_t val);
1470
1471 /**
1472 * @atomic_get_property:
1473 *
1474 * Reads out the decoded driver-private property. This is used to
1475 * implement the GETPLANE IOCTL.
1476 *
1477 * Do not call this function directly, use
1478 * drm_atomic_plane_get_property() instead.
1479 *
1480 * This callback is optional if the driver does not support any
1481 * driver-private atomic properties.
1482 *
1483 * RETURNS:
1484 *
1485 * 0 on success, -EINVAL if the property isn't implemented by the
1486 * driver (which should never happen, the core only asks for
1487 * properties attached to this plane).
1488 */
1489 int (*atomic_get_property)(struct drm_plane *plane,
1490 const struct drm_plane_state *state,
1491 struct drm_property *property,
1492 uint64_t *val);
1493};
1494
1495enum drm_plane_type {
1496 DRM_PLANE_TYPE_OVERLAY,
1497 DRM_PLANE_TYPE_PRIMARY,
1498 DRM_PLANE_TYPE_CURSOR,
1499};
1500
1501
1502/**
1503 * struct drm_plane - central DRM plane control structure
1504 * @dev: DRM device this plane belongs to
1505 * @head: for list management
1506 * @base: base mode object
1507 * @possible_crtcs: pipes this plane can be bound to
1508 * @format_types: array of formats supported by this plane
1509 * @format_count: number of formats supported
1510 * @format_default: driver hasn't supplied supported formats for the plane
1511 * @crtc: currently bound CRTC
1512 * @fb: currently bound fb
1513 * @old_fb: Temporary tracking of the old fb while a modeset is ongoing. Used by
1514 * drm_mode_set_config_internal() to implement correct refcounting.
1515 * @funcs: helper functions
1516 * @properties: property tracking for this plane
1517 * @type: type of plane (overlay, primary, cursor)
1518 * @state: current atomic state for this plane
1519 */
1520struct drm_plane {
1521 struct drm_device *dev;
1522 struct list_head head;
1523
1524 char *name;
1525
1526 struct drm_modeset_lock mutex;
1527
1528 struct drm_mode_object base;
1529
1530 uint32_t possible_crtcs;
1531 uint32_t *format_types;
1532 unsigned int format_count;
1533 bool format_default;
1534
1535 struct drm_crtc *crtc;
1536 struct drm_framebuffer *fb;
1537
1538 struct drm_framebuffer *old_fb;
1539
1540 const struct drm_plane_funcs *funcs;
1541
1542 struct drm_object_properties properties;
1543
1544 enum drm_plane_type type;
1545
1546 const struct drm_plane_helper_funcs *helper_private;
1547
1548 struct drm_plane_state *state;
1549};
1550
1551/**
1552 * struct drm_bridge_funcs - drm_bridge control functions
1553 * @attach: Called during drm_bridge_attach
1554 */
1555struct drm_bridge_funcs {
1556 int (*attach)(struct drm_bridge *bridge);
1557
1558 /**
1559 * @mode_fixup:
1560 *
1561 * This callback is used to validate and adjust a mode. The paramater
1562 * mode is the display mode that should be fed to the next element in
1563 * the display chain, either the final &drm_connector or the next
1564 * &drm_bridge. The parameter adjusted_mode is the input mode the bridge
1565 * requires. It can be modified by this callback and does not need to
1566 * match mode.
1567 *
1568 * This is the only hook that allows a bridge to reject a modeset. If
1569 * this function passes all other callbacks must succeed for this
1570 * configuration.
1571 *
1572 * NOTE:
1573 *
1574 * This function is called in the check phase of atomic modesets, which
1575 * can be aborted for any reason (including on userspace's request to
1576 * just check whether a configuration would be possible). Drivers MUST
1577 * NOT touch any persistent state (hardware or software) or data
1578 * structures except the passed in @state parameter.
1579 *
1580 * RETURNS:
1581 *
1582 * True if an acceptable configuration is possible, false if the modeset
1583 * operation should be rejected.
1584 */
1585 bool (*mode_fixup)(struct drm_bridge *bridge,
1586 const struct drm_display_mode *mode,
1587 struct drm_display_mode *adjusted_mode);
1588 /**
1589 * @disable:
1590 *
1591 * This callback should disable the bridge. It is called right before
1592 * the preceding element in the display pipe is disabled. If the
1593 * preceding element is a bridge this means it's called before that
1594 * bridge's ->disable() function. If the preceding element is a
1595 * &drm_encoder it's called right before the encoder's ->disable(),
1596 * ->prepare() or ->dpms() hook from struct &drm_encoder_helper_funcs.
1597 *
1598 * The bridge can assume that the display pipe (i.e. clocks and timing
1599 * signals) feeding it is still running when this callback is called.
1600 *
1601 * The disable callback is optional.
1602 */
1603 void (*disable)(struct drm_bridge *bridge);
1604
1605 /**
1606 * @post_disable:
1607 *
1608 * This callback should disable the bridge. It is called right after
1609 * the preceding element in the display pipe is disabled. If the
1610 * preceding element is a bridge this means it's called after that
1611 * bridge's ->post_disable() function. If the preceding element is a
1612 * &drm_encoder it's called right after the encoder's ->disable(),
1613 * ->prepare() or ->dpms() hook from struct &drm_encoder_helper_funcs.
1614 *
1615 * The bridge must assume that the display pipe (i.e. clocks and timing
1616 * singals) feeding it is no longer running when this callback is
1617 * called.
1618 *
1619 * The post_disable callback is optional.
1620 */
1621 void (*post_disable)(struct drm_bridge *bridge);
1622
1623 /**
1624 * @mode_set:
1625 *
1626 * This callback should set the given mode on the bridge. It is called
1627 * after the ->mode_set() callback for the preceding element in the
1628 * display pipeline has been called already. The display pipe (i.e.
1629 * clocks and timing signals) is off when this function is called.
1630 */
1631 void (*mode_set)(struct drm_bridge *bridge,
1632 struct drm_display_mode *mode,
1633 struct drm_display_mode *adjusted_mode);
1634 /**
1635 * @pre_enable:
1636 *
1637 * This callback should enable the bridge. It is called right before
1638 * the preceding element in the display pipe is enabled. If the
1639 * preceding element is a bridge this means it's called before that
1640 * bridge's ->pre_enable() function. If the preceding element is a
1641 * &drm_encoder it's called right before the encoder's ->enable(),
1642 * ->commit() or ->dpms() hook from struct &drm_encoder_helper_funcs.
1643 *
1644 * The display pipe (i.e. clocks and timing signals) feeding this bridge
1645 * will not yet be running when this callback is called. The bridge must
1646 * not enable the display link feeding the next bridge in the chain (if
1647 * there is one) when this callback is called.
1648 *
1649 * The pre_enable callback is optional.
1650 */
1651 void (*pre_enable)(struct drm_bridge *bridge);
1652
1653 /**
1654 * @enable:
1655 *
1656 * This callback should enable the bridge. It is called right after
1657 * the preceding element in the display pipe is enabled. If the
1658 * preceding element is a bridge this means it's called after that
1659 * bridge's ->enable() function. If the preceding element is a
1660 * &drm_encoder it's called right after the encoder's ->enable(),
1661 * ->commit() or ->dpms() hook from struct &drm_encoder_helper_funcs.
1662 *
1663 * The bridge can assume that the display pipe (i.e. clocks and timing
1664 * signals) feeding it is running when this callback is called. This
1665 * callback must enable the display link feeding the next bridge in the
1666 * chain if there is one.
1667 *
1668 * The enable callback is optional.
1669 */
1670 void (*enable)(struct drm_bridge *bridge);
1671};
1672
1673/**
1674 * struct drm_bridge - central DRM bridge control structure
1675 * @dev: DRM device this bridge belongs to
1676 * @encoder: encoder to which this bridge is connected
1677 * @next: the next bridge in the encoder chain
1678 * @of_node: device node pointer to the bridge
1679 * @list: to keep track of all added bridges
1680 * @funcs: control functions
1681 * @driver_private: pointer to the bridge driver's internal context
1682 */
1683struct drm_bridge {
1684 struct drm_device *dev;
1685 struct drm_encoder *encoder;
1686 struct drm_bridge *next;
1687#ifdef CONFIG_OF
1688 struct device_node *of_node;
1689#endif
1690 struct list_head list;
1691
1692 const struct drm_bridge_funcs *funcs;
1693 void *driver_private;
1694};
1695
1696/**
1697 * struct drm_atomic_state - the global state object for atomic updates
1698 * @dev: parent DRM device
1699 * @allow_modeset: allow full modeset
1700 * @legacy_cursor_update: hint to enforce legacy cursor IOCTL semantics
1701 * @legacy_set_config: Disable conflicting encoders instead of failing with -EINVAL.
1702 * @planes: pointer to array of plane pointers
1703 * @plane_states: pointer to array of plane states pointers
1704 * @crtcs: pointer to array of CRTC pointers
1705 * @crtc_states: pointer to array of CRTC states pointers
1706 * @num_connector: size of the @connectors and @connector_states arrays
1707 * @connectors: pointer to array of connector pointers
1708 * @connector_states: pointer to array of connector states pointers
1709 * @acquire_ctx: acquire context for this atomic modeset state update
1710 */
1711struct drm_atomic_state {
1712 struct drm_device *dev;
1713 bool allow_modeset : 1;
1714 bool legacy_cursor_update : 1;
1715 bool legacy_set_config : 1;
1716 struct drm_plane **planes;
1717 struct drm_plane_state **plane_states;
1718 struct drm_crtc **crtcs;
1719 struct drm_crtc_state **crtc_states;
1720 int num_connector;
1721 struct drm_connector **connectors;
1722 struct drm_connector_state **connector_states;
1723
1724 struct drm_modeset_acquire_ctx *acquire_ctx;
1725};
1726
1727
1728/**
1729 * struct drm_mode_set - new values for a CRTC config change
1730 * @fb: framebuffer to use for new config
1731 * @crtc: CRTC whose configuration we're about to change
1732 * @mode: mode timings to use
1733 * @x: position of this CRTC relative to @fb
1734 * @y: position of this CRTC relative to @fb
1735 * @connectors: array of connectors to drive with this CRTC if possible
1736 * @num_connectors: size of @connectors array
1737 *
1738 * Represents a single crtc the connectors that it drives with what mode
1739 * and from which framebuffer it scans out from.
1740 *
1741 * This is used to set modes.
1742 */
1743struct drm_mode_set {
1744 struct drm_framebuffer *fb;
1745 struct drm_crtc *crtc;
1746 struct drm_display_mode *mode;
1747
1748 uint32_t x;
1749 uint32_t y;
1750
1751 struct drm_connector **connectors;
1752 size_t num_connectors;
1753};
1754
1755/**
1756 * struct drm_mode_config_funcs - basic driver provided mode setting functions
1757 *
1758 * Some global (i.e. not per-CRTC, connector, etc) mode setting functions that
1759 * involve drivers.
1760 */
1761struct drm_mode_config_funcs {
1762 /**
1763 * @fb_create:
1764 *
1765 * Create a new framebuffer object. The core does basic checks on the
1766 * requested metadata, but most of that is left to the driver. See
1767 * struct &drm_mode_fb_cmd2 for details.
1768 *
1769 * If the parameters are deemed valid and the backing storage objects in
1770 * the underlying memory manager all exist, then the driver allocates
1771 * a new &drm_framebuffer structure, subclassed to contain
1772 * driver-specific information (like the internal native buffer object
1773 * references). It also needs to fill out all relevant metadata, which
1774 * should be done by calling drm_helper_mode_fill_fb_struct().
1775 *
1776 * The initialization is finalized by calling drm_framebuffer_init(),
1777 * which registers the framebuffer and makes it accessible to other
1778 * threads.
1779 *
1780 * RETURNS:
1781 *
1782 * A new framebuffer with an initial reference count of 1 or a negative
1783 * error code encoded with ERR_PTR().
1784 */
1785 struct drm_framebuffer *(*fb_create)(struct drm_device *dev,
1786 struct drm_file *file_priv,
1787 const struct drm_mode_fb_cmd2 *mode_cmd);
1788
1789 /**
1790 * @output_poll_changed:
1791 *
1792 * Callback used by helpers to inform the driver of output configuration
1793 * changes.
1794 *
1795 * Drivers implementing fbdev emulation with the helpers can call
1796 * drm_fb_helper_hotplug_changed from this hook to inform the fbdev
1797 * helper of output changes.
1798 *
1799 * FIXME:
1800 *
1801 * Except that there's no vtable for device-level helper callbacks
1802 * there's no reason this is a core function.
1803 */
1804 void (*output_poll_changed)(struct drm_device *dev);
1805
1806 /**
1807 * @atomic_check:
1808 *
1809 * This is the only hook to validate an atomic modeset update. This
1810 * function must reject any modeset and state changes which the hardware
1811 * or driver doesn't support. This includes but is of course not limited
1812 * to:
1813 *
1814 * - Checking that the modes, framebuffers, scaling and placement
1815 * requirements and so on are within the limits of the hardware.
1816 *
1817 * - Checking that any hidden shared resources are not oversubscribed.
1818 * This can be shared PLLs, shared lanes, overall memory bandwidth,
1819 * display fifo space (where shared between planes or maybe even
1820 * CRTCs).
1821 *
1822 * - Checking that virtualized resources exported to userspace are not
1823 * oversubscribed. For various reasons it can make sense to expose
1824 * more planes, crtcs or encoders than which are physically there. One
1825 * example is dual-pipe operations (which generally should be hidden
1826 * from userspace if when lockstepped in hardware, exposed otherwise),
1827 * where a plane might need 1 hardware plane (if it's just on one
1828 * pipe), 2 hardware planes (when it spans both pipes) or maybe even
1829 * shared a hardware plane with a 2nd plane (if there's a compatible
1830 * plane requested on the area handled by the other pipe).
1831 *
1832 * - Check that any transitional state is possible and that if
1833 * requested, the update can indeed be done in the vblank period
1834 * without temporarily disabling some functions.
1835 *
1836 * - Check any other constraints the driver or hardware might have.
1837 *
1838 * - This callback also needs to correctly fill out the &drm_crtc_state
1839 * in this update to make sure that drm_atomic_crtc_needs_modeset()
1840 * reflects the nature of the possible update and returns true if and
1841 * only if the update cannot be applied without tearing within one
1842 * vblank on that CRTC. The core uses that information to reject
1843 * updates which require a full modeset (i.e. blanking the screen, or
1844 * at least pausing updates for a substantial amount of time) if
1845 * userspace has disallowed that in its request.
1846 *
1847 * - The driver also does not need to repeat basic input validation
1848 * like done for the corresponding legacy entry points. The core does
1849 * that before calling this hook.
1850 *
1851 * See the documentation of @atomic_commit for an exhaustive list of
1852 * error conditions which don't have to be checked at the
1853 * ->atomic_check() stage?
1854 *
1855 * See the documentation for struct &drm_atomic_state for how exactly
1856 * an atomic modeset update is described.
1857 *
1858 * Drivers using the atomic helpers can implement this hook using
1859 * drm_atomic_helper_check(), or one of the exported sub-functions of
1860 * it.
1861 *
1862 * RETURNS:
1863 *
1864 * 0 on success or one of the below negative error codes:
1865 *
1866 * - -EINVAL, if any of the above constraints are violated.
1867 *
1868 * - -EDEADLK, when returned from an attempt to acquire an additional
1869 * &drm_modeset_lock through drm_modeset_lock().
1870 *
1871 * - -ENOMEM, if allocating additional state sub-structures failed due
1872 * to lack of memory.
1873 *
1874 * - -EINTR, -EAGAIN or -ERESTARTSYS, if the IOCTL should be restarted.
1875 * This can either be due to a pending signal, or because the driver
1876 * needs to completely bail out to recover from an exceptional
1877 * situation like a GPU hang. From a userspace point all errors are
1878 * treated equally.
1879 */
1880 int (*atomic_check)(struct drm_device *dev,
1881 struct drm_atomic_state *state);
1882
1883 /**
1884 * @atomic_commit:
1885 *
1886 * This is the only hook to commit an atomic modeset update. The core
1887 * guarantees that @atomic_check has been called successfully before
1888 * calling this function, and that nothing has been changed in the
1889 * interim.
1890 *
1891 * See the documentation for struct &drm_atomic_state for how exactly
1892 * an atomic modeset update is described.
1893 *
1894 * Drivers using the atomic helpers can implement this hook using
1895 * drm_atomic_helper_commit(), or one of the exported sub-functions of
1896 * it.
1897 *
1898 * Asynchronous commits (as indicated with the async parameter) must
1899 * do any preparatory work which might result in an unsuccessful commit
1900 * in the context of this callback. The only exceptions are hardware
1901 * errors resulting in -EIO. But even in that case the driver must
1902 * ensure that the display pipe is at least running, to avoid
1903 * compositors crashing when pageflips don't work. Anything else,
1904 * specifically committing the update to the hardware, should be done
1905 * without blocking the caller. For updates which do not require a
1906 * modeset this must be guaranteed.
1907 *
1908 * The driver must wait for any pending rendering to the new
1909 * framebuffers to complete before executing the flip. It should also
1910 * wait for any pending rendering from other drivers if the underlying
1911 * buffer is a shared dma-buf. Asynchronous commits must not wait for
1912 * rendering in the context of this callback.
1913 *
1914 * An application can request to be notified when the atomic commit has
1915 * completed. These events are per-CRTC and can be distinguished by the
1916 * CRTC index supplied in &drm_event to userspace.
1917 *
1918 * The drm core will supply a struct &drm_event in the event
1919 * member of each CRTC's &drm_crtc_state structure. This can be handled by the
1920 * drm_crtc_send_vblank_event() function, which the driver should call on
1921 * the provided event upon completion of the atomic commit. Note that if
1922 * the driver supports vblank signalling and timestamping the vblank
1923 * counters and timestamps must agree with the ones returned from page
1924 * flip events. With the current vblank helper infrastructure this can
1925 * be achieved by holding a vblank reference while the page flip is
1926 * pending, acquired through drm_crtc_vblank_get() and released with
1927 * drm_crtc_vblank_put(). Drivers are free to implement their own vblank
1928 * counter and timestamp tracking though, e.g. if they have accurate
1929 * timestamp registers in hardware.
1930 *
1931 * NOTE:
1932 *
1933 * Drivers are not allowed to shut down any display pipe successfully
1934 * enabled through an atomic commit on their own. Doing so can result in
1935 * compositors crashing if a page flip is suddenly rejected because the
1936 * pipe is off.
1937 *
1938 * RETURNS:
1939 *
1940 * 0 on success or one of the below negative error codes:
1941 *
1942 * - -EBUSY, if an asynchronous updated is requested and there is
1943 * an earlier updated pending. Drivers are allowed to support a queue
1944 * of outstanding updates, but currently no driver supports that.
1945 * Note that drivers must wait for preceding updates to complete if a
1946 * synchronous update is requested, they are not allowed to fail the
1947 * commit in that case.
1948 *
1949 * - -ENOMEM, if the driver failed to allocate memory. Specifically
1950 * this can happen when trying to pin framebuffers, which must only
1951 * be done when committing the state.
1952 *
1953 * - -ENOSPC, as a refinement of the more generic -ENOMEM to indicate
1954 * that the driver has run out of vram, iommu space or similar GPU
1955 * address space needed for framebuffer.
1956 *
1957 * - -EIO, if the hardware completely died.
1958 *
1959 * - -EINTR, -EAGAIN or -ERESTARTSYS, if the IOCTL should be restarted.
1960 * This can either be due to a pending signal, or because the driver
1961 * needs to completely bail out to recover from an exceptional
1962 * situation like a GPU hang. From a userspace point of view all errors are
1963 * treated equally.
1964 *
1965 * This list is exhaustive. Specifically this hook is not allowed to
1966 * return -EINVAL (any invalid requests should be caught in
1967 * @atomic_check) or -EDEADLK (this function must not acquire
1968 * additional modeset locks).
1969 */
1970 int (*atomic_commit)(struct drm_device *dev,
1971 struct drm_atomic_state *state,
1972 bool async);
1973
1974 /**
1975 * @atomic_state_alloc:
1976 *
1977 * This optional hook can be used by drivers that want to subclass struct
1978 * &drm_atomic_state to be able to track their own driver-private global
1979 * state easily. If this hook is implemented, drivers must also
1980 * implement @atomic_state_clear and @atomic_state_free.
1981 *
1982 * RETURNS:
1983 *
1984 * A new &drm_atomic_state on success or NULL on failure.
1985 */
1986 struct drm_atomic_state *(*atomic_state_alloc)(struct drm_device *dev);
1987
1988 /**
1989 * @atomic_state_clear:
1990 *
1991 * This hook must clear any driver private state duplicated into the
1992 * passed-in &drm_atomic_state. This hook is called when the caller
1993 * encountered a &drm_modeset_lock deadlock and needs to drop all
1994 * already acquired locks as part of the deadlock avoidance dance
1995 * implemented in drm_modeset_lock_backoff().
1996 *
1997 * Any duplicated state must be invalidated since a concurrent atomic
1998 * update might change it, and the drm atomic interfaces always apply
1999 * updates as relative changes to the current state.
2000 *
2001 * Drivers that implement this must call drm_atomic_state_default_clear()
2002 * to clear common state.
2003 */
2004 void (*atomic_state_clear)(struct drm_atomic_state *state);
2005
2006 /**
2007 * @atomic_state_free:
2008 *
2009 * This hook needs driver private resources and the &drm_atomic_state
2010 * itself. Note that the core first calls drm_atomic_state_clear() to
2011 * avoid code duplicate between the clear and free hooks.
2012 *
2013 * Drivers that implement this must call drm_atomic_state_default_free()
2014 * to release common resources.
2015 */
2016 void (*atomic_state_free)(struct drm_atomic_state *state);
2017};
2018
2019/**
2020 * struct drm_mode_config - Mode configuration control structure
2021 * @mutex: mutex protecting KMS related lists and structures
2022 * @connection_mutex: ww mutex protecting connector state and routing
2023 * @acquire_ctx: global implicit acquire context used by atomic drivers for
2024 * legacy IOCTLs
2025 * @idr_mutex: mutex for KMS ID allocation and management
2026 * @crtc_idr: main KMS ID tracking object
2027 * @fb_lock: mutex to protect fb state and lists
2028 * @num_fb: number of fbs available
2029 * @fb_list: list of framebuffers available
2030 * @num_connector: number of connectors on this device
2031 * @connector_list: list of connector objects
2032 * @num_encoder: number of encoders on this device
2033 * @encoder_list: list of encoder objects
2034 * @num_overlay_plane: number of overlay planes on this device
2035 * @num_total_plane: number of universal (i.e. with primary/curso) planes on this device
2036 * @plane_list: list of plane objects
2037 * @num_crtc: number of CRTCs on this device
2038 * @crtc_list: list of CRTC objects
2039 * @property_list: list of property objects
2040 * @min_width: minimum pixel width on this device
2041 * @min_height: minimum pixel height on this device
2042 * @max_width: maximum pixel width on this device
2043 * @max_height: maximum pixel height on this device
2044 * @funcs: core driver provided mode setting functions
2045 * @fb_base: base address of the framebuffer
2046 * @poll_enabled: track polling support for this device
2047 * @poll_running: track polling status for this device
2048 * @output_poll_work: delayed work for polling in process context
2049 * @property_blob_list: list of all the blob property objects
2050 * @blob_lock: mutex for blob property allocation and management
2051 * @*_property: core property tracking
2052 * @degamma_lut_property: LUT used to convert the framebuffer's colors to linear
2053 * gamma
2054 * @degamma_lut_size_property: size of the degamma LUT as supported by the
2055 * driver (read-only)
2056 * @ctm_property: Matrix used to convert colors after the lookup in the
2057 * degamma LUT
2058 * @gamma_lut_property: LUT used to convert the colors, after the CSC matrix, to
2059 * the gamma space of the connected screen (read-only)
2060 * @gamma_lut_size_property: size of the gamma LUT as supported by the driver
2061 * @preferred_depth: preferred RBG pixel depth, used by fb helpers
2062 * @prefer_shadow: hint to userspace to prefer shadow-fb rendering
2063 * @async_page_flip: does this device support async flips on the primary plane?
2064 * @cursor_width: hint to userspace for max cursor width
2065 * @cursor_height: hint to userspace for max cursor height
2066 *
2067 * Core mode resource tracking structure. All CRTC, encoders, and connectors
2068 * enumerated by the driver are added here, as are global properties. Some
2069 * global restrictions are also here, e.g. dimension restrictions.
2070 */
2071struct drm_mode_config {
2072 struct mutex mutex; /* protects configuration (mode lists etc.) */
2073 struct drm_modeset_lock connection_mutex; /* protects connector->encoder and encoder->crtc links */
2074 struct drm_modeset_acquire_ctx *acquire_ctx; /* for legacy _lock_all() / _unlock_all() */
2075 struct mutex idr_mutex; /* for IDR management */
2076 struct idr crtc_idr; /* use this idr for all IDs, fb, crtc, connector, modes - just makes life easier */
2077 struct idr tile_idr; /* use this idr for all IDs, fb, crtc, connector, modes - just makes life easier */
2078 /* this is limited to one for now */
2079
2080 struct mutex fb_lock; /* proctects global and per-file fb lists */
2081 int num_fb;
2082 struct list_head fb_list;
2083
2084 int num_connector;
2085 struct ida connector_ida;
2086 struct list_head connector_list;
2087 int num_encoder;
2088 struct list_head encoder_list;
2089
2090 /*
2091 * Track # of overlay planes separately from # of total planes. By
2092 * default we only advertise overlay planes to userspace; if userspace
2093 * sets the "universal plane" capability bit, we'll go ahead and
2094 * expose all planes.
2095 */
2096 int num_overlay_plane;
2097 int num_total_plane;
2098 struct list_head plane_list;
2099
2100 int num_crtc;
2101 struct list_head crtc_list;
2102
2103 struct list_head property_list;
2104
2105 int min_width, min_height;
2106 int max_width, max_height;
2107 const struct drm_mode_config_funcs *funcs;
2108 resource_size_t fb_base;
2109
2110 /* output poll support */
2111 bool poll_enabled;
2112 bool poll_running;
2113 bool delayed_event;
2114 struct delayed_work output_poll_work;
2115
2116 struct mutex blob_lock;
2117
2118 /* pointers to standard properties */
2119 struct list_head property_blob_list;
2120 struct drm_property *edid_property;
2121 struct drm_property *dpms_property;
2122 struct drm_property *path_property;
2123 struct drm_property *tile_property;
2124 struct drm_property *plane_type_property;
2125 struct drm_property *rotation_property;
2126 struct drm_property *prop_src_x;
2127 struct drm_property *prop_src_y;
2128 struct drm_property *prop_src_w;
2129 struct drm_property *prop_src_h;
2130 struct drm_property *prop_crtc_x;
2131 struct drm_property *prop_crtc_y;
2132 struct drm_property *prop_crtc_w;
2133 struct drm_property *prop_crtc_h;
2134 struct drm_property *prop_fb_id;
2135 struct drm_property *prop_crtc_id;
2136 struct drm_property *prop_active;
2137 struct drm_property *prop_mode_id;
2138
2139 /* DVI-I properties */
2140 struct drm_property *dvi_i_subconnector_property;
2141 struct drm_property *dvi_i_select_subconnector_property;
2142
2143 /* TV properties */
2144 struct drm_property *tv_subconnector_property;
2145 struct drm_property *tv_select_subconnector_property;
2146 struct drm_property *tv_mode_property;
2147 struct drm_property *tv_left_margin_property;
2148 struct drm_property *tv_right_margin_property;
2149 struct drm_property *tv_top_margin_property;
2150 struct drm_property *tv_bottom_margin_property;
2151 struct drm_property *tv_brightness_property;
2152 struct drm_property *tv_contrast_property;
2153 struct drm_property *tv_flicker_reduction_property;
2154 struct drm_property *tv_overscan_property;
2155 struct drm_property *tv_saturation_property;
2156 struct drm_property *tv_hue_property;
2157
2158 /* Optional properties */
2159 struct drm_property *scaling_mode_property;
2160 struct drm_property *aspect_ratio_property;
2161 struct drm_property *dirty_info_property;
2162
2163 /* Optional color correction properties */
2164 struct drm_property *degamma_lut_property;
2165 struct drm_property *degamma_lut_size_property;
2166 struct drm_property *ctm_property;
2167 struct drm_property *gamma_lut_property;
2168 struct drm_property *gamma_lut_size_property;
2169
2170 /* properties for virtual machine layout */
2171 struct drm_property *suggested_x_property;
2172 struct drm_property *suggested_y_property;
2173
2174 /* dumb ioctl parameters */
2175 uint32_t preferred_depth, prefer_shadow;
2176
2177 /* whether async page flip is supported or not */
2178 bool async_page_flip;
2179
2180 /* whether the driver supports fb modifiers */
2181 bool allow_fb_modifiers;
2182
2183 /* cursor size */
2184 uint32_t cursor_width, cursor_height;
2185};
2186
2187/**
2188 * drm_for_each_plane_mask - iterate over planes specified by bitmask
2189 * @plane: the loop cursor
2190 * @dev: the DRM device
2191 * @plane_mask: bitmask of plane indices
2192 *
2193 * Iterate over all planes specified by bitmask.
2194 */
2195#define drm_for_each_plane_mask(plane, dev, plane_mask) \
2196 list_for_each_entry((plane), &(dev)->mode_config.plane_list, head) \
2197 for_each_if ((plane_mask) & (1 << drm_plane_index(plane)))
2198
2199/**
2200 * drm_for_each_encoder_mask - iterate over encoders specified by bitmask
2201 * @encoder: the loop cursor
2202 * @dev: the DRM device
2203 * @encoder_mask: bitmask of encoder indices
2204 *
2205 * Iterate over all encoders specified by bitmask.
2206 */
2207#define drm_for_each_encoder_mask(encoder, dev, encoder_mask) \
2208 list_for_each_entry((encoder), &(dev)->mode_config.encoder_list, head) \
2209 for_each_if ((encoder_mask) & (1 << drm_encoder_index(encoder)))
2210
2211#define obj_to_crtc(x) container_of(x, struct drm_crtc, base)
2212#define obj_to_connector(x) container_of(x, struct drm_connector, base)
2213#define obj_to_encoder(x) container_of(x, struct drm_encoder, base)
2214#define obj_to_mode(x) container_of(x, struct drm_display_mode, base)
2215#define obj_to_fb(x) container_of(x, struct drm_framebuffer, base)
2216#define obj_to_property(x) container_of(x, struct drm_property, base)
2217#define obj_to_blob(x) container_of(x, struct drm_property_blob, base)
2218#define obj_to_plane(x) container_of(x, struct drm_plane, base)
2219
2220struct drm_prop_enum_list {
2221 int type;
2222 char *name;
2223};
2224
2225extern __printf(6, 7)
2226int drm_crtc_init_with_planes(struct drm_device *dev,
2227 struct drm_crtc *crtc,
2228 struct drm_plane *primary,
2229 struct drm_plane *cursor,
2230 const struct drm_crtc_funcs *funcs,
2231 const char *name, ...);
2232extern void drm_crtc_cleanup(struct drm_crtc *crtc);
2233extern unsigned int drm_crtc_index(struct drm_crtc *crtc);
2234
2235/**
2236 * drm_crtc_mask - find the mask of a registered CRTC
2237 * @crtc: CRTC to find mask for
2238 *
2239 * Given a registered CRTC, return the mask bit of that CRTC for an
2240 * encoder's possible_crtcs field.
2241 */
2242static inline uint32_t drm_crtc_mask(struct drm_crtc *crtc)
2243{
2244 return 1 << drm_crtc_index(crtc);
2245}
2246
2247extern void drm_connector_ida_init(void);
2248extern void drm_connector_ida_destroy(void);
2249extern int drm_connector_init(struct drm_device *dev,
2250 struct drm_connector *connector,
2251 const struct drm_connector_funcs *funcs,
2252 int connector_type);
2253int drm_connector_register(struct drm_connector *connector);
2254void drm_connector_unregister(struct drm_connector *connector);
2255
2256extern void drm_connector_cleanup(struct drm_connector *connector);
2257static inline unsigned drm_connector_index(struct drm_connector *connector)
2258{
2259 return connector->connector_id;
2260}
2261
2262/* helper to unplug all connectors from sysfs for device */
2263extern void drm_connector_unplug_all(struct drm_device *dev);
2264
2265extern int drm_bridge_add(struct drm_bridge *bridge);
2266extern void drm_bridge_remove(struct drm_bridge *bridge);
2267extern struct drm_bridge *of_drm_find_bridge(struct device_node *np);
2268extern int drm_bridge_attach(struct drm_device *dev, struct drm_bridge *bridge);
2269
2270bool drm_bridge_mode_fixup(struct drm_bridge *bridge,
2271 const struct drm_display_mode *mode,
2272 struct drm_display_mode *adjusted_mode);
2273void drm_bridge_disable(struct drm_bridge *bridge);
2274void drm_bridge_post_disable(struct drm_bridge *bridge);
2275void drm_bridge_mode_set(struct drm_bridge *bridge,
2276 struct drm_display_mode *mode,
2277 struct drm_display_mode *adjusted_mode);
2278void drm_bridge_pre_enable(struct drm_bridge *bridge);
2279void drm_bridge_enable(struct drm_bridge *bridge);
2280
2281extern __printf(5, 6)
2282int drm_encoder_init(struct drm_device *dev,
2283 struct drm_encoder *encoder,
2284 const struct drm_encoder_funcs *funcs,
2285 int encoder_type, const char *name, ...);
2286extern unsigned int drm_encoder_index(struct drm_encoder *encoder);
2287
2288/**
2289 * drm_encoder_crtc_ok - can a given crtc drive a given encoder?
2290 * @encoder: encoder to test
2291 * @crtc: crtc to test
2292 *
2293 * Return false if @encoder can't be driven by @crtc, true otherwise.
2294 */
2295static inline bool drm_encoder_crtc_ok(struct drm_encoder *encoder,
2296 struct drm_crtc *crtc)
2297{
2298 return !!(encoder->possible_crtcs & drm_crtc_mask(crtc));
2299}
2300
2301extern __printf(8, 9)
2302int drm_universal_plane_init(struct drm_device *dev,
2303 struct drm_plane *plane,
2304 unsigned long possible_crtcs,
2305 const struct drm_plane_funcs *funcs,
2306 const uint32_t *formats,
2307 unsigned int format_count,
2308 enum drm_plane_type type,
2309 const char *name, ...);
2310extern int drm_plane_init(struct drm_device *dev,
2311 struct drm_plane *plane,
2312 unsigned long possible_crtcs,
2313 const struct drm_plane_funcs *funcs,
2314 const uint32_t *formats, unsigned int format_count,
2315 bool is_primary);
2316extern void drm_plane_cleanup(struct drm_plane *plane);
2317extern unsigned int drm_plane_index(struct drm_plane *plane);
2318extern struct drm_plane * drm_plane_from_index(struct drm_device *dev, int idx);
2319extern void drm_plane_force_disable(struct drm_plane *plane);
2320extern int drm_plane_check_pixel_format(const struct drm_plane *plane,
2321 u32 format);
2322extern void drm_crtc_get_hv_timing(const struct drm_display_mode *mode,
2323 int *hdisplay, int *vdisplay);
2324extern int drm_crtc_check_viewport(const struct drm_crtc *crtc,
2325 int x, int y,
2326 const struct drm_display_mode *mode,
2327 const struct drm_framebuffer *fb);
2328
2329extern void drm_encoder_cleanup(struct drm_encoder *encoder);
2330
2331extern const char *drm_get_connector_status_name(enum drm_connector_status status);
2332extern const char *drm_get_subpixel_order_name(enum subpixel_order order);
2333extern const char *drm_get_dpms_name(int val);
2334extern const char *drm_get_dvi_i_subconnector_name(int val);
2335extern const char *drm_get_dvi_i_select_name(int val);
2336extern const char *drm_get_tv_subconnector_name(int val);
2337extern const char *drm_get_tv_select_name(int val);
2338extern void drm_fb_release(struct drm_file *file_priv);
2339extern void drm_property_destroy_user_blobs(struct drm_device *dev,
2340 struct drm_file *file_priv);
2341extern bool drm_probe_ddc(struct i2c_adapter *adapter);
2342extern struct edid *drm_get_edid(struct drm_connector *connector,
2343 struct i2c_adapter *adapter);
2344extern struct edid *drm_get_edid_switcheroo(struct drm_connector *connector,
2345 struct i2c_adapter *adapter);
2346extern struct edid *drm_edid_duplicate(const struct edid *edid);
2347extern int drm_add_edid_modes(struct drm_connector *connector, struct edid *edid);
2348extern void drm_mode_config_init(struct drm_device *dev);
2349extern void drm_mode_config_reset(struct drm_device *dev);
2350extern void drm_mode_config_cleanup(struct drm_device *dev);
2351
2352extern int drm_mode_connector_set_path_property(struct drm_connector *connector,
2353 const char *path);
2354int drm_mode_connector_set_tile_property(struct drm_connector *connector);
2355extern int drm_mode_connector_update_edid_property(struct drm_connector *connector,
2356 const struct edid *edid);
2357
2358extern int drm_display_info_set_bus_formats(struct drm_display_info *info,
2359 const u32 *formats,
2360 unsigned int num_formats);
2361
2362static inline bool drm_property_type_is(struct drm_property *property,
2363 uint32_t type)
2364{
2365 /* instanceof for props.. handles extended type vs original types: */
2366 if (property->flags & DRM_MODE_PROP_EXTENDED_TYPE)
2367 return (property->flags & DRM_MODE_PROP_EXTENDED_TYPE) == type;
2368 return property->flags & type;
2369}
2370
2371static inline bool drm_property_type_valid(struct drm_property *property)
2372{
2373 if (property->flags & DRM_MODE_PROP_EXTENDED_TYPE)
2374 return !(property->flags & DRM_MODE_PROP_LEGACY_TYPE);
2375 return !!(property->flags & DRM_MODE_PROP_LEGACY_TYPE);
2376}
2377
2378extern int drm_object_property_set_value(struct drm_mode_object *obj,
2379 struct drm_property *property,
2380 uint64_t val);
2381extern int drm_object_property_get_value(struct drm_mode_object *obj,
2382 struct drm_property *property,
2383 uint64_t *value);
2384extern int drm_framebuffer_init(struct drm_device *dev,
2385 struct drm_framebuffer *fb,
2386 const struct drm_framebuffer_funcs *funcs);
2387extern struct drm_framebuffer *drm_framebuffer_lookup(struct drm_device *dev,
2388 uint32_t id);
2389extern void drm_framebuffer_unreference(struct drm_framebuffer *fb);
2390extern void drm_framebuffer_reference(struct drm_framebuffer *fb);
2391extern void drm_framebuffer_remove(struct drm_framebuffer *fb);
2392extern void drm_framebuffer_cleanup(struct drm_framebuffer *fb);
2393extern void drm_framebuffer_unregister_private(struct drm_framebuffer *fb);
2394
2395extern void drm_object_attach_property(struct drm_mode_object *obj,
2396 struct drm_property *property,
2397 uint64_t init_val);
2398extern struct drm_property *drm_property_create(struct drm_device *dev, int flags,
2399 const char *name, int num_values);
2400extern struct drm_property *drm_property_create_enum(struct drm_device *dev, int flags,
2401 const char *name,
2402 const struct drm_prop_enum_list *props,
2403 int num_values);
2404struct drm_property *drm_property_create_bitmask(struct drm_device *dev,
2405 int flags, const char *name,
2406 const struct drm_prop_enum_list *props,
2407 int num_props,
2408 uint64_t supported_bits);
2409struct drm_property *drm_property_create_range(struct drm_device *dev, int flags,
2410 const char *name,
2411 uint64_t min, uint64_t max);
2412struct drm_property *drm_property_create_signed_range(struct drm_device *dev,
2413 int flags, const char *name,
2414 int64_t min, int64_t max);
2415struct drm_property *drm_property_create_object(struct drm_device *dev,
2416 int flags, const char *name, uint32_t type);
2417struct drm_property *drm_property_create_bool(struct drm_device *dev, int flags,
2418 const char *name);
2419struct drm_property_blob *drm_property_create_blob(struct drm_device *dev,
2420 size_t length,
2421 const void *data);
2422struct drm_property_blob *drm_property_lookup_blob(struct drm_device *dev,
2423 uint32_t id);
2424struct drm_property_blob *drm_property_reference_blob(struct drm_property_blob *blob);
2425void drm_property_unreference_blob(struct drm_property_blob *blob);
2426extern void drm_property_destroy(struct drm_device *dev, struct drm_property *property);
2427extern int drm_property_add_enum(struct drm_property *property, int index,
2428 uint64_t value, const char *name);
2429extern int drm_mode_create_dvi_i_properties(struct drm_device *dev);
2430extern int drm_mode_create_tv_properties(struct drm_device *dev,
2431 unsigned int num_modes,
2432 const char * const modes[]);
2433extern int drm_mode_create_scaling_mode_property(struct drm_device *dev);
2434extern int drm_mode_create_aspect_ratio_property(struct drm_device *dev);
2435extern int drm_mode_create_dirty_info_property(struct drm_device *dev);
2436extern int drm_mode_create_suggested_offset_properties(struct drm_device *dev);
2437extern bool drm_property_change_valid_get(struct drm_property *property,
2438 uint64_t value, struct drm_mode_object **ref);
2439extern void drm_property_change_valid_put(struct drm_property *property,
2440 struct drm_mode_object *ref);
2441
2442extern int drm_mode_connector_attach_encoder(struct drm_connector *connector,
2443 struct drm_encoder *encoder);
2444extern int drm_mode_crtc_set_gamma_size(struct drm_crtc *crtc,
2445 int gamma_size);
2446extern struct drm_mode_object *drm_mode_object_find(struct drm_device *dev,
2447 uint32_t id, uint32_t type);
2448
2449/* IOCTLs */
2450extern int drm_mode_getresources(struct drm_device *dev,
2451 void *data, struct drm_file *file_priv);
2452extern int drm_mode_getplane_res(struct drm_device *dev, void *data,
2453 struct drm_file *file_priv);
2454extern int drm_mode_getcrtc(struct drm_device *dev,
2455 void *data, struct drm_file *file_priv);
2456extern int drm_mode_getconnector(struct drm_device *dev,
2457 void *data, struct drm_file *file_priv);
2458extern int drm_mode_set_config_internal(struct drm_mode_set *set);
2459extern int drm_mode_setcrtc(struct drm_device *dev,
2460 void *data, struct drm_file *file_priv);
2461extern int drm_mode_getplane(struct drm_device *dev,
2462 void *data, struct drm_file *file_priv);
2463extern int drm_mode_setplane(struct drm_device *dev,
2464 void *data, struct drm_file *file_priv);
2465extern int drm_mode_cursor_ioctl(struct drm_device *dev,
2466 void *data, struct drm_file *file_priv);
2467extern int drm_mode_cursor2_ioctl(struct drm_device *dev,
2468 void *data, struct drm_file *file_priv);
2469extern int drm_mode_addfb(struct drm_device *dev,
2470 void *data, struct drm_file *file_priv);
2471extern int drm_mode_addfb2(struct drm_device *dev,
2472 void *data, struct drm_file *file_priv);
2473extern uint32_t drm_mode_legacy_fb_format(uint32_t bpp, uint32_t depth);
2474extern int drm_mode_rmfb(struct drm_device *dev,
2475 void *data, struct drm_file *file_priv);
2476extern int drm_mode_getfb(struct drm_device *dev,
2477 void *data, struct drm_file *file_priv);
2478extern int drm_mode_dirtyfb_ioctl(struct drm_device *dev,
2479 void *data, struct drm_file *file_priv);
2480
2481extern int drm_mode_getproperty_ioctl(struct drm_device *dev,
2482 void *data, struct drm_file *file_priv);
2483extern int drm_mode_getblob_ioctl(struct drm_device *dev,
2484 void *data, struct drm_file *file_priv);
2485extern int drm_mode_createblob_ioctl(struct drm_device *dev,
2486 void *data, struct drm_file *file_priv);
2487extern int drm_mode_destroyblob_ioctl(struct drm_device *dev,
2488 void *data, struct drm_file *file_priv);
2489extern int drm_mode_connector_property_set_ioctl(struct drm_device *dev,
2490 void *data, struct drm_file *file_priv);
2491extern int drm_mode_getencoder(struct drm_device *dev,
2492 void *data, struct drm_file *file_priv);
2493extern int drm_mode_gamma_get_ioctl(struct drm_device *dev,
2494 void *data, struct drm_file *file_priv);
2495extern int drm_mode_gamma_set_ioctl(struct drm_device *dev,
2496 void *data, struct drm_file *file_priv);
2497extern u8 drm_match_cea_mode(const struct drm_display_mode *to_match);
2498extern enum hdmi_picture_aspect drm_get_cea_aspect_ratio(const u8 video_code);
2499extern bool drm_detect_hdmi_monitor(struct edid *edid);
2500extern bool drm_detect_monitor_audio(struct edid *edid);
2501extern bool drm_rgb_quant_range_selectable(struct edid *edid);
2502extern int drm_mode_page_flip_ioctl(struct drm_device *dev,
2503 void *data, struct drm_file *file_priv);
2504extern int drm_add_modes_noedid(struct drm_connector *connector,
2505 int hdisplay, int vdisplay);
2506extern void drm_set_preferred_mode(struct drm_connector *connector,
2507 int hpref, int vpref);
2508
2509extern int drm_edid_header_is_valid(const u8 *raw_edid);
2510extern bool drm_edid_block_valid(u8 *raw_edid, int block, bool print_bad_edid,
2511 bool *edid_corrupt);
2512extern bool drm_edid_is_valid(struct edid *edid);
2513
2514extern struct drm_tile_group *drm_mode_create_tile_group(struct drm_device *dev,
2515 char topology[8]);
2516extern struct drm_tile_group *drm_mode_get_tile_group(struct drm_device *dev,
2517 char topology[8]);
2518extern void drm_mode_put_tile_group(struct drm_device *dev,
2519 struct drm_tile_group *tg);
2520struct drm_display_mode *drm_mode_find_dmt(struct drm_device *dev,
2521 int hsize, int vsize, int fresh,
2522 bool rb);
2523
2524extern int drm_mode_create_dumb_ioctl(struct drm_device *dev,
2525 void *data, struct drm_file *file_priv);
2526extern int drm_mode_mmap_dumb_ioctl(struct drm_device *dev,
2527 void *data, struct drm_file *file_priv);
2528extern int drm_mode_destroy_dumb_ioctl(struct drm_device *dev,
2529 void *data, struct drm_file *file_priv);
2530extern int drm_mode_obj_get_properties_ioctl(struct drm_device *dev, void *data,
2531 struct drm_file *file_priv);
2532extern int drm_mode_obj_set_property_ioctl(struct drm_device *dev, void *data,
2533 struct drm_file *file_priv);
2534extern int drm_mode_plane_set_obj_prop(struct drm_plane *plane,
2535 struct drm_property *property,
2536 uint64_t value);
2537extern int drm_mode_atomic_ioctl(struct drm_device *dev,
2538 void *data, struct drm_file *file_priv);
2539
2540extern void drm_fb_get_bpp_depth(uint32_t format, unsigned int *depth,
2541 int *bpp);
2542extern int drm_format_num_planes(uint32_t format);
2543extern int drm_format_plane_cpp(uint32_t format, int plane);
2544extern int drm_format_horz_chroma_subsampling(uint32_t format);
2545extern int drm_format_vert_chroma_subsampling(uint32_t format);
2546extern int drm_format_plane_width(int width, uint32_t format, int plane);
2547extern int drm_format_plane_height(int height, uint32_t format, int plane);
2548extern const char *drm_get_format_name(uint32_t format);
2549extern struct drm_property *drm_mode_create_rotation_property(struct drm_device *dev,
2550 unsigned int supported_rotations);
2551extern unsigned int drm_rotation_simplify(unsigned int rotation,
2552 unsigned int supported_rotations);
2553
2554/* Helpers */
2555
2556static inline struct drm_plane *drm_plane_find(struct drm_device *dev,
2557 uint32_t id)
2558{
2559 struct drm_mode_object *mo;
2560 mo = drm_mode_object_find(dev, id, DRM_MODE_OBJECT_PLANE);
2561 return mo ? obj_to_plane(mo) : NULL;
2562}
2563
2564static inline struct drm_crtc *drm_crtc_find(struct drm_device *dev,
2565 uint32_t id)
2566{
2567 struct drm_mode_object *mo;
2568 mo = drm_mode_object_find(dev, id, DRM_MODE_OBJECT_CRTC);
2569 return mo ? obj_to_crtc(mo) : NULL;
2570}
2571
2572static inline struct drm_encoder *drm_encoder_find(struct drm_device *dev,
2573 uint32_t id)
2574{
2575 struct drm_mode_object *mo;
2576 mo = drm_mode_object_find(dev, id, DRM_MODE_OBJECT_ENCODER);
2577 return mo ? obj_to_encoder(mo) : NULL;
2578}
2579
2580static inline struct drm_connector *drm_connector_find(struct drm_device *dev,
2581 uint32_t id)
2582{
2583 struct drm_mode_object *mo;
2584 mo = drm_mode_object_find(dev, id, DRM_MODE_OBJECT_CONNECTOR);
2585 return mo ? obj_to_connector(mo) : NULL;
2586}
2587
2588static inline struct drm_property *drm_property_find(struct drm_device *dev,
2589 uint32_t id)
2590{
2591 struct drm_mode_object *mo;
2592 mo = drm_mode_object_find(dev, id, DRM_MODE_OBJECT_PROPERTY);
2593 return mo ? obj_to_property(mo) : NULL;
2594}
2595
2596/*
2597 * Extract a degamma/gamma LUT value provided by user and round it to the
2598 * precision supported by the hardware.
2599 */
2600static inline uint32_t drm_color_lut_extract(uint32_t user_input,
2601 uint32_t bit_precision)
2602{
2603 uint32_t val = user_input + (1 << (16 - bit_precision - 1));
2604 uint32_t max = 0xffff >> (16 - bit_precision);
2605
2606 val >>= 16 - bit_precision;
2607
2608 return clamp_val(val, 0, max);
2609}
2610
2611/* Plane list iterator for legacy (overlay only) planes. */
2612#define drm_for_each_legacy_plane(plane, dev) \
2613 list_for_each_entry(plane, &(dev)->mode_config.plane_list, head) \
2614 for_each_if (plane->type == DRM_PLANE_TYPE_OVERLAY)
2615
2616#define drm_for_each_plane(plane, dev) \
2617 list_for_each_entry(plane, &(dev)->mode_config.plane_list, head)
2618
2619#define drm_for_each_crtc(crtc, dev) \
2620 list_for_each_entry(crtc, &(dev)->mode_config.crtc_list, head)
2621
2622static inline void
2623assert_drm_connector_list_read_locked(struct drm_mode_config *mode_config)
2624{
2625 /*
2626 * The connector hotadd/remove code currently grabs both locks when
2627 * updating lists. Hence readers need only hold either of them to be
2628 * safe and the check amounts to
2629 *
2630 * WARN_ON(not_holding(A) && not_holding(B)).
2631 */
2632 WARN_ON(!mutex_is_locked(&mode_config->mutex) &&
2633 !drm_modeset_is_locked(&mode_config->connection_mutex));
2634}
2635
2636#define drm_for_each_connector(connector, dev) \
2637 for (assert_drm_connector_list_read_locked(&(dev)->mode_config), \
2638 connector = list_first_entry(&(dev)->mode_config.connector_list, \
2639 struct drm_connector, head); \
2640 &connector->head != (&(dev)->mode_config.connector_list); \
2641 connector = list_next_entry(connector, head))
2642
2643#define drm_for_each_encoder(encoder, dev) \
2644 list_for_each_entry(encoder, &(dev)->mode_config.encoder_list, head)
2645
2646#define drm_for_each_fb(fb, dev) \
2647 for (WARN_ON(!mutex_is_locked(&(dev)->mode_config.fb_lock)), \
2648 fb = list_first_entry(&(dev)->mode_config.fb_list, \
2649 struct drm_framebuffer, head); \
2650 &fb->head != (&(dev)->mode_config.fb_list); \
2651 fb = list_next_entry(fb, head))
2652
2653#endif /* __DRM_CRTC_H__ */
1/*
2 * Copyright © 2006 Keith Packard
3 * Copyright © 2007-2008 Dave Airlie
4 * Copyright © 2007-2008 Intel Corporation
5 * Jesse Barnes <jesse.barnes@intel.com>
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining a
8 * copy of this software and associated documentation files (the "Software"),
9 * to deal in the Software without restriction, including without limitation
10 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
11 * and/or sell copies of the Software, and to permit persons to whom the
12 * Software is furnished to do so, subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
20 * THE COPYRIGHT HOLDER(S) OR AUTHOR(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR
21 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
22 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
23 * OTHER DEALINGS IN THE SOFTWARE.
24 */
25#ifndef __DRM_CRTC_H__
26#define __DRM_CRTC_H__
27
28#include <linux/i2c.h>
29#include <linux/spinlock.h>
30#include <linux/types.h>
31#include <linux/fb.h>
32#include <linux/hdmi.h>
33#include <linux/media-bus-format.h>
34#include <uapi/drm/drm_mode.h>
35#include <uapi/drm/drm_fourcc.h>
36#include <drm/drm_modeset_lock.h>
37#include <drm/drm_rect.h>
38#include <drm/drm_mode_object.h>
39#include <drm/drm_framebuffer.h>
40#include <drm/drm_modes.h>
41#include <drm/drm_connector.h>
42#include <drm/drm_encoder.h>
43#include <drm/drm_property.h>
44#include <drm/drm_bridge.h>
45#include <drm/drm_edid.h>
46#include <drm/drm_plane.h>
47#include <drm/drm_blend.h>
48#include <drm/drm_color_mgmt.h>
49#include <drm/drm_debugfs_crc.h>
50#include <drm/drm_mode_config.h>
51
52struct drm_device;
53struct drm_mode_set;
54struct drm_file;
55struct drm_clip_rect;
56struct drm_printer;
57struct device_node;
58struct dma_fence;
59struct edid;
60
61static inline int64_t U642I64(uint64_t val)
62{
63 return (int64_t)*((int64_t *)&val);
64}
65static inline uint64_t I642U64(int64_t val)
66{
67 return (uint64_t)*((uint64_t *)&val);
68}
69
70struct drm_crtc;
71struct drm_encoder;
72struct drm_pending_vblank_event;
73struct drm_plane;
74struct drm_bridge;
75struct drm_atomic_state;
76
77struct drm_crtc_helper_funcs;
78struct drm_encoder_helper_funcs;
79struct drm_plane_helper_funcs;
80
81/**
82 * struct drm_crtc_state - mutable CRTC state
83 * @crtc: backpointer to the CRTC
84 * @enable: whether the CRTC should be enabled, gates all other state
85 * @active: whether the CRTC is actively displaying (used for DPMS)
86 * @planes_changed: planes on this crtc are updated
87 * @mode_changed: crtc_state->mode or crtc_state->enable has been changed
88 * @active_changed: crtc_state->active has been toggled.
89 * @connectors_changed: connectors to this crtc have been updated
90 * @zpos_changed: zpos values of planes on this crtc have been updated
91 * @color_mgmt_changed: color management properties have changed (degamma or
92 * gamma LUT or CSC matrix)
93 * @plane_mask: bitmask of (1 << drm_plane_index(plane)) of attached planes
94 * @connector_mask: bitmask of (1 << drm_connector_index(connector)) of attached connectors
95 * @encoder_mask: bitmask of (1 << drm_encoder_index(encoder)) of attached encoders
96 * @last_vblank_count: for helpers and drivers to capture the vblank of the
97 * update to ensure framebuffer cleanup isn't done too early
98 * @adjusted_mode: for use by helpers and drivers to compute adjusted mode timings
99 * @mode: current mode timings
100 * @mode_blob: &drm_property_blob for @mode
101 * @degamma_lut: Lookup table for converting framebuffer pixel data
102 * before apply the conversion matrix
103 * @ctm: Transformation matrix
104 * @gamma_lut: Lookup table for converting pixel data after the
105 * conversion matrix
106 * @state: backpointer to global drm_atomic_state
107 *
108 * Note that the distinction between @enable and @active is rather subtile:
109 * Flipping @active while @enable is set without changing anything else may
110 * never return in a failure from the ->atomic_check callback. Userspace assumes
111 * that a DPMS On will always succeed. In other words: @enable controls resource
112 * assignment, @active controls the actual hardware state.
113 *
114 * The three booleans active_changed, connectors_changed and mode_changed are
115 * intended to indicate whether a full modeset is needed, rather than strictly
116 * describing what has changed in a commit.
117 * See also: drm_atomic_crtc_needs_modeset()
118 */
119struct drm_crtc_state {
120 struct drm_crtc *crtc;
121
122 bool enable;
123 bool active;
124
125 /* computed state bits used by helpers and drivers */
126 bool planes_changed : 1;
127 bool mode_changed : 1;
128 bool active_changed : 1;
129 bool connectors_changed : 1;
130 bool zpos_changed : 1;
131 bool color_mgmt_changed : 1;
132
133 /* attached planes bitmask:
134 * WARNING: transitional helpers do not maintain plane_mask so
135 * drivers not converted over to atomic helpers should not rely
136 * on plane_mask being accurate!
137 */
138 u32 plane_mask;
139
140 u32 connector_mask;
141 u32 encoder_mask;
142
143 /* last_vblank_count: for vblank waits before cleanup */
144 u32 last_vblank_count;
145
146 /* adjusted_mode: for use by helpers and drivers */
147 struct drm_display_mode adjusted_mode;
148
149 struct drm_display_mode mode;
150
151 /* blob property to expose current mode to atomic userspace */
152 struct drm_property_blob *mode_blob;
153
154 /* blob property to expose color management to userspace */
155 struct drm_property_blob *degamma_lut;
156 struct drm_property_blob *ctm;
157 struct drm_property_blob *gamma_lut;
158
159 /**
160 * @event:
161 *
162 * Optional pointer to a DRM event to signal upon completion of the
163 * state update. The driver must send out the event when the atomic
164 * commit operation completes. There are two cases:
165 *
166 * - The event is for a CRTC which is being disabled through this
167 * atomic commit. In that case the event can be send out any time
168 * after the hardware has stopped scanning out the current
169 * framebuffers. It should contain the timestamp and counter for the
170 * last vblank before the display pipeline was shut off.
171 *
172 * - For a CRTC which is enabled at the end of the commit (even when it
173 * undergoes an full modeset) the vblank timestamp and counter must
174 * be for the vblank right before the first frame that scans out the
175 * new set of buffers. Again the event can only be sent out after the
176 * hardware has stopped scanning out the old buffers.
177 *
178 * - Events for disabled CRTCs are not allowed, and drivers can ignore
179 * that case.
180 *
181 * This can be handled by the drm_crtc_send_vblank_event() function,
182 * which the driver should call on the provided event upon completion of
183 * the atomic commit. Note that if the driver supports vblank signalling
184 * and timestamping the vblank counters and timestamps must agree with
185 * the ones returned from page flip events. With the current vblank
186 * helper infrastructure this can be achieved by holding a vblank
187 * reference while the page flip is pending, acquired through
188 * drm_crtc_vblank_get() and released with drm_crtc_vblank_put().
189 * Drivers are free to implement their own vblank counter and timestamp
190 * tracking though, e.g. if they have accurate timestamp registers in
191 * hardware.
192 *
193 * For hardware which supports some means to synchronize vblank
194 * interrupt delivery with committing display state there's also
195 * drm_crtc_arm_vblank_event(). See the documentation of that function
196 * for a detailed discussion of the constraints it needs to be used
197 * safely.
198 */
199 struct drm_pending_vblank_event *event;
200
201 struct drm_atomic_state *state;
202};
203
204/**
205 * struct drm_crtc_funcs - control CRTCs for a given device
206 *
207 * The drm_crtc_funcs structure is the central CRTC management structure
208 * in the DRM. Each CRTC controls one or more connectors (note that the name
209 * CRTC is simply historical, a CRTC may control LVDS, VGA, DVI, TV out, etc.
210 * connectors, not just CRTs).
211 *
212 * Each driver is responsible for filling out this structure at startup time,
213 * in addition to providing other modesetting features, like i2c and DDC
214 * bus accessors.
215 */
216struct drm_crtc_funcs {
217 /**
218 * @reset:
219 *
220 * Reset CRTC hardware and software state to off. This function isn't
221 * called by the core directly, only through drm_mode_config_reset().
222 * It's not a helper hook only for historical reasons.
223 *
224 * Atomic drivers can use drm_atomic_helper_crtc_reset() to reset
225 * atomic state using this hook.
226 */
227 void (*reset)(struct drm_crtc *crtc);
228
229 /**
230 * @cursor_set:
231 *
232 * Update the cursor image. The cursor position is relative to the CRTC
233 * and can be partially or fully outside of the visible area.
234 *
235 * Note that contrary to all other KMS functions the legacy cursor entry
236 * points don't take a framebuffer object, but instead take directly a
237 * raw buffer object id from the driver's buffer manager (which is
238 * either GEM or TTM for current drivers).
239 *
240 * This entry point is deprecated, drivers should instead implement
241 * universal plane support and register a proper cursor plane using
242 * drm_crtc_init_with_planes().
243 *
244 * This callback is optional
245 *
246 * RETURNS:
247 *
248 * 0 on success or a negative error code on failure.
249 */
250 int (*cursor_set)(struct drm_crtc *crtc, struct drm_file *file_priv,
251 uint32_t handle, uint32_t width, uint32_t height);
252
253 /**
254 * @cursor_set2:
255 *
256 * Update the cursor image, including hotspot information. The hotspot
257 * must not affect the cursor position in CRTC coordinates, but is only
258 * meant as a hint for virtualized display hardware to coordinate the
259 * guests and hosts cursor position. The cursor hotspot is relative to
260 * the cursor image. Otherwise this works exactly like @cursor_set.
261 *
262 * This entry point is deprecated, drivers should instead implement
263 * universal plane support and register a proper cursor plane using
264 * drm_crtc_init_with_planes().
265 *
266 * This callback is optional.
267 *
268 * RETURNS:
269 *
270 * 0 on success or a negative error code on failure.
271 */
272 int (*cursor_set2)(struct drm_crtc *crtc, struct drm_file *file_priv,
273 uint32_t handle, uint32_t width, uint32_t height,
274 int32_t hot_x, int32_t hot_y);
275
276 /**
277 * @cursor_move:
278 *
279 * Update the cursor position. The cursor does not need to be visible
280 * when this hook is called.
281 *
282 * This entry point is deprecated, drivers should instead implement
283 * universal plane support and register a proper cursor plane using
284 * drm_crtc_init_with_planes().
285 *
286 * This callback is optional.
287 *
288 * RETURNS:
289 *
290 * 0 on success or a negative error code on failure.
291 */
292 int (*cursor_move)(struct drm_crtc *crtc, int x, int y);
293
294 /**
295 * @gamma_set:
296 *
297 * Set gamma on the CRTC.
298 *
299 * This callback is optional.
300 *
301 * NOTE:
302 *
303 * Drivers that support gamma tables and also fbdev emulation through
304 * the provided helper library need to take care to fill out the gamma
305 * hooks for both. Currently there's a bit an unfortunate duplication
306 * going on, which should eventually be unified to just one set of
307 * hooks.
308 */
309 int (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b,
310 uint32_t size);
311
312 /**
313 * @destroy:
314 *
315 * Clean up plane resources. This is only called at driver unload time
316 * through drm_mode_config_cleanup() since a CRTC cannot be hotplugged
317 * in DRM.
318 */
319 void (*destroy)(struct drm_crtc *crtc);
320
321 /**
322 * @set_config:
323 *
324 * This is the main legacy entry point to change the modeset state on a
325 * CRTC. All the details of the desired configuration are passed in a
326 * struct &drm_mode_set - see there for details.
327 *
328 * Drivers implementing atomic modeset should use
329 * drm_atomic_helper_set_config() to implement this hook.
330 *
331 * RETURNS:
332 *
333 * 0 on success or a negative error code on failure.
334 */
335 int (*set_config)(struct drm_mode_set *set);
336
337 /**
338 * @page_flip:
339 *
340 * Legacy entry point to schedule a flip to the given framebuffer.
341 *
342 * Page flipping is a synchronization mechanism that replaces the frame
343 * buffer being scanned out by the CRTC with a new frame buffer during
344 * vertical blanking, avoiding tearing (except when requested otherwise
345 * through the DRM_MODE_PAGE_FLIP_ASYNC flag). When an application
346 * requests a page flip the DRM core verifies that the new frame buffer
347 * is large enough to be scanned out by the CRTC in the currently
348 * configured mode and then calls the CRTC ->page_flip() operation with a
349 * pointer to the new frame buffer.
350 *
351 * The driver must wait for any pending rendering to the new framebuffer
352 * to complete before executing the flip. It should also wait for any
353 * pending rendering from other drivers if the underlying buffer is a
354 * shared dma-buf.
355 *
356 * An application can request to be notified when the page flip has
357 * completed. The drm core will supply a struct &drm_event in the event
358 * parameter in this case. This can be handled by the
359 * drm_crtc_send_vblank_event() function, which the driver should call on
360 * the provided event upon completion of the flip. Note that if
361 * the driver supports vblank signalling and timestamping the vblank
362 * counters and timestamps must agree with the ones returned from page
363 * flip events. With the current vblank helper infrastructure this can
364 * be achieved by holding a vblank reference while the page flip is
365 * pending, acquired through drm_crtc_vblank_get() and released with
366 * drm_crtc_vblank_put(). Drivers are free to implement their own vblank
367 * counter and timestamp tracking though, e.g. if they have accurate
368 * timestamp registers in hardware.
369 *
370 * This callback is optional.
371 *
372 * NOTE:
373 *
374 * Very early versions of the KMS ABI mandated that the driver must
375 * block (but not reject) any rendering to the old framebuffer until the
376 * flip operation has completed and the old framebuffer is no longer
377 * visible. This requirement has been lifted, and userspace is instead
378 * expected to request delivery of an event and wait with recycling old
379 * buffers until such has been received.
380 *
381 * RETURNS:
382 *
383 * 0 on success or a negative error code on failure. Note that if a
384 * ->page_flip() operation is already pending the callback should return
385 * -EBUSY. Pageflips on a disabled CRTC (either by setting a NULL mode
386 * or just runtime disabled through DPMS respectively the new atomic
387 * "ACTIVE" state) should result in an -EINVAL error code. Note that
388 * drm_atomic_helper_page_flip() checks this already for atomic drivers.
389 */
390 int (*page_flip)(struct drm_crtc *crtc,
391 struct drm_framebuffer *fb,
392 struct drm_pending_vblank_event *event,
393 uint32_t flags);
394
395 /**
396 * @page_flip_target:
397 *
398 * Same as @page_flip but with an additional parameter specifying the
399 * absolute target vertical blank period (as reported by
400 * drm_crtc_vblank_count()) when the flip should take effect.
401 *
402 * Note that the core code calls drm_crtc_vblank_get before this entry
403 * point, and will call drm_crtc_vblank_put if this entry point returns
404 * any non-0 error code. It's the driver's responsibility to call
405 * drm_crtc_vblank_put after this entry point returns 0, typically when
406 * the flip completes.
407 */
408 int (*page_flip_target)(struct drm_crtc *crtc,
409 struct drm_framebuffer *fb,
410 struct drm_pending_vblank_event *event,
411 uint32_t flags, uint32_t target);
412
413 /**
414 * @set_property:
415 *
416 * This is the legacy entry point to update a property attached to the
417 * CRTC.
418 *
419 * Drivers implementing atomic modeset should use
420 * drm_atomic_helper_crtc_set_property() to implement this hook.
421 *
422 * This callback is optional if the driver does not support any legacy
423 * driver-private properties.
424 *
425 * RETURNS:
426 *
427 * 0 on success or a negative error code on failure.
428 */
429 int (*set_property)(struct drm_crtc *crtc,
430 struct drm_property *property, uint64_t val);
431
432 /**
433 * @atomic_duplicate_state:
434 *
435 * Duplicate the current atomic state for this CRTC and return it.
436 * The core and helpers gurantee that any atomic state duplicated with
437 * this hook and still owned by the caller (i.e. not transferred to the
438 * driver by calling ->atomic_commit() from struct
439 * &drm_mode_config_funcs) will be cleaned up by calling the
440 * @atomic_destroy_state hook in this structure.
441 *
442 * Atomic drivers which don't subclass struct &drm_crtc should use
443 * drm_atomic_helper_crtc_duplicate_state(). Drivers that subclass the
444 * state structure to extend it with driver-private state should use
445 * __drm_atomic_helper_crtc_duplicate_state() to make sure shared state is
446 * duplicated in a consistent fashion across drivers.
447 *
448 * It is an error to call this hook before crtc->state has been
449 * initialized correctly.
450 *
451 * NOTE:
452 *
453 * If the duplicate state references refcounted resources this hook must
454 * acquire a reference for each of them. The driver must release these
455 * references again in @atomic_destroy_state.
456 *
457 * RETURNS:
458 *
459 * Duplicated atomic state or NULL when the allocation failed.
460 */
461 struct drm_crtc_state *(*atomic_duplicate_state)(struct drm_crtc *crtc);
462
463 /**
464 * @atomic_destroy_state:
465 *
466 * Destroy a state duplicated with @atomic_duplicate_state and release
467 * or unreference all resources it references
468 */
469 void (*atomic_destroy_state)(struct drm_crtc *crtc,
470 struct drm_crtc_state *state);
471
472 /**
473 * @atomic_set_property:
474 *
475 * Decode a driver-private property value and store the decoded value
476 * into the passed-in state structure. Since the atomic core decodes all
477 * standardized properties (even for extensions beyond the core set of
478 * properties which might not be implemented by all drivers) this
479 * requires drivers to subclass the state structure.
480 *
481 * Such driver-private properties should really only be implemented for
482 * truly hardware/vendor specific state. Instead it is preferred to
483 * standardize atomic extension and decode the properties used to expose
484 * such an extension in the core.
485 *
486 * Do not call this function directly, use
487 * drm_atomic_crtc_set_property() instead.
488 *
489 * This callback is optional if the driver does not support any
490 * driver-private atomic properties.
491 *
492 * NOTE:
493 *
494 * This function is called in the state assembly phase of atomic
495 * modesets, which can be aborted for any reason (including on
496 * userspace's request to just check whether a configuration would be
497 * possible). Drivers MUST NOT touch any persistent state (hardware or
498 * software) or data structures except the passed in @state parameter.
499 *
500 * Also since userspace controls in which order properties are set this
501 * function must not do any input validation (since the state update is
502 * incomplete and hence likely inconsistent). Instead any such input
503 * validation must be done in the various atomic_check callbacks.
504 *
505 * RETURNS:
506 *
507 * 0 if the property has been found, -EINVAL if the property isn't
508 * implemented by the driver (which should never happen, the core only
509 * asks for properties attached to this CRTC). No other validation is
510 * allowed by the driver. The core already checks that the property
511 * value is within the range (integer, valid enum value, ...) the driver
512 * set when registering the property.
513 */
514 int (*atomic_set_property)(struct drm_crtc *crtc,
515 struct drm_crtc_state *state,
516 struct drm_property *property,
517 uint64_t val);
518 /**
519 * @atomic_get_property:
520 *
521 * Reads out the decoded driver-private property. This is used to
522 * implement the GETCRTC IOCTL.
523 *
524 * Do not call this function directly, use
525 * drm_atomic_crtc_get_property() instead.
526 *
527 * This callback is optional if the driver does not support any
528 * driver-private atomic properties.
529 *
530 * RETURNS:
531 *
532 * 0 on success, -EINVAL if the property isn't implemented by the
533 * driver (which should never happen, the core only asks for
534 * properties attached to this CRTC).
535 */
536 int (*atomic_get_property)(struct drm_crtc *crtc,
537 const struct drm_crtc_state *state,
538 struct drm_property *property,
539 uint64_t *val);
540
541 /**
542 * @late_register:
543 *
544 * This optional hook can be used to register additional userspace
545 * interfaces attached to the crtc like debugfs interfaces.
546 * It is called late in the driver load sequence from drm_dev_register().
547 * Everything added from this callback should be unregistered in
548 * the early_unregister callback.
549 *
550 * Returns:
551 *
552 * 0 on success, or a negative error code on failure.
553 */
554 int (*late_register)(struct drm_crtc *crtc);
555
556 /**
557 * @early_unregister:
558 *
559 * This optional hook should be used to unregister the additional
560 * userspace interfaces attached to the crtc from
561 * late_unregister(). It is called from drm_dev_unregister(),
562 * early in the driver unload sequence to disable userspace access
563 * before data structures are torndown.
564 */
565 void (*early_unregister)(struct drm_crtc *crtc);
566
567 /**
568 * @set_crc_source:
569 *
570 * Changes the source of CRC checksums of frames at the request of
571 * userspace, typically for testing purposes. The sources available are
572 * specific of each driver and a %NULL value indicates that CRC
573 * generation is to be switched off.
574 *
575 * When CRC generation is enabled, the driver should call
576 * drm_crtc_add_crc_entry() at each frame, providing any information
577 * that characterizes the frame contents in the crcN arguments, as
578 * provided from the configured source. Drivers must accept a "auto"
579 * source name that will select a default source for this CRTC.
580 *
581 * This callback is optional if the driver does not support any CRC
582 * generation functionality.
583 *
584 * RETURNS:
585 *
586 * 0 on success or a negative error code on failure.
587 */
588 int (*set_crc_source)(struct drm_crtc *crtc, const char *source,
589 size_t *values_cnt);
590
591 /**
592 * @atomic_print_state:
593 *
594 * If driver subclasses struct &drm_crtc_state, it should implement
595 * this optional hook for printing additional driver specific state.
596 *
597 * Do not call this directly, use drm_atomic_crtc_print_state()
598 * instead.
599 */
600 void (*atomic_print_state)(struct drm_printer *p,
601 const struct drm_crtc_state *state);
602};
603
604/**
605 * struct drm_crtc - central CRTC control structure
606 * @dev: parent DRM device
607 * @port: OF node used by drm_of_find_possible_crtcs()
608 * @head: list management
609 * @name: human readable name, can be overwritten by the driver
610 * @mutex: per-CRTC locking
611 * @base: base KMS object for ID tracking etc.
612 * @primary: primary plane for this CRTC
613 * @cursor: cursor plane for this CRTC
614 * @cursor_x: current x position of the cursor, used for universal cursor planes
615 * @cursor_y: current y position of the cursor, used for universal cursor planes
616 * @enabled: is this CRTC enabled?
617 * @mode: current mode timings
618 * @hwmode: mode timings as programmed to hw regs
619 * @x: x position on screen
620 * @y: y position on screen
621 * @funcs: CRTC control functions
622 * @gamma_size: size of gamma ramp
623 * @gamma_store: gamma ramp values
624 * @helper_private: mid-layer private data
625 * @properties: property tracking for this CRTC
626 *
627 * Each CRTC may have one or more connectors associated with it. This structure
628 * allows the CRTC to be controlled.
629 */
630struct drm_crtc {
631 struct drm_device *dev;
632 struct device_node *port;
633 struct list_head head;
634
635 char *name;
636
637 /**
638 * @mutex:
639 *
640 * This provides a read lock for the overall crtc state (mode, dpms
641 * state, ...) and a write lock for everything which can be update
642 * without a full modeset (fb, cursor data, crtc properties ...). Full
643 * modeset also need to grab dev->mode_config.connection_mutex.
644 */
645 struct drm_modeset_lock mutex;
646
647 struct drm_mode_object base;
648
649 /* primary and cursor planes for CRTC */
650 struct drm_plane *primary;
651 struct drm_plane *cursor;
652
653 /**
654 * @index: Position inside the mode_config.list, can be used as an array
655 * index. It is invariant over the lifetime of the CRTC.
656 */
657 unsigned index;
658
659 /* position of cursor plane on crtc */
660 int cursor_x;
661 int cursor_y;
662
663 bool enabled;
664
665 /* Requested mode from modesetting. */
666 struct drm_display_mode mode;
667
668 /* Programmed mode in hw, after adjustments for encoders,
669 * crtc, panel scaling etc. Needed for timestamping etc.
670 */
671 struct drm_display_mode hwmode;
672
673 int x, y;
674 const struct drm_crtc_funcs *funcs;
675
676 /* Legacy FB CRTC gamma size for reporting to userspace */
677 uint32_t gamma_size;
678 uint16_t *gamma_store;
679
680 /* if you are using the helper */
681 const struct drm_crtc_helper_funcs *helper_private;
682
683 struct drm_object_properties properties;
684
685 /**
686 * @state:
687 *
688 * Current atomic state for this CRTC.
689 */
690 struct drm_crtc_state *state;
691
692 /**
693 * @commit_list:
694 *
695 * List of &drm_crtc_commit structures tracking pending commits.
696 * Protected by @commit_lock. This list doesn't hold its own full
697 * reference, but burrows it from the ongoing commit. Commit entries
698 * must be removed from this list once the commit is fully completed,
699 * but before it's correspoding &drm_atomic_state gets destroyed.
700 */
701 struct list_head commit_list;
702
703 /**
704 * @commit_lock:
705 *
706 * Spinlock to protect @commit_list.
707 */
708 spinlock_t commit_lock;
709
710 /**
711 * @acquire_ctx:
712 *
713 * Per-CRTC implicit acquire context used by atomic drivers for legacy
714 * IOCTLs, so that atomic drivers can get at the locking acquire
715 * context.
716 */
717 struct drm_modeset_acquire_ctx *acquire_ctx;
718
719#ifdef CONFIG_DEBUG_FS
720 /**
721 * @debugfs_entry:
722 *
723 * Debugfs directory for this CRTC.
724 */
725 struct dentry *debugfs_entry;
726
727 /**
728 * @crc:
729 *
730 * Configuration settings of CRC capture.
731 */
732 struct drm_crtc_crc crc;
733#endif
734
735 /**
736 * @fence_context:
737 *
738 * timeline context used for fence operations.
739 */
740 unsigned int fence_context;
741
742 /**
743 * @fence_lock:
744 *
745 * spinlock to protect the fences in the fence_context.
746 */
747
748 spinlock_t fence_lock;
749 /**
750 * @fence_seqno:
751 *
752 * Seqno variable used as monotonic counter for the fences
753 * created on the CRTC's timeline.
754 */
755 unsigned long fence_seqno;
756
757 /**
758 * @timeline_name:
759 *
760 * The name of the CRTC's fence timeline.
761 */
762 char timeline_name[32];
763};
764
765/**
766 * struct drm_mode_set - new values for a CRTC config change
767 * @fb: framebuffer to use for new config
768 * @crtc: CRTC whose configuration we're about to change
769 * @mode: mode timings to use
770 * @x: position of this CRTC relative to @fb
771 * @y: position of this CRTC relative to @fb
772 * @connectors: array of connectors to drive with this CRTC if possible
773 * @num_connectors: size of @connectors array
774 *
775 * Represents a single crtc the connectors that it drives with what mode
776 * and from which framebuffer it scans out from.
777 *
778 * This is used to set modes.
779 */
780struct drm_mode_set {
781 struct drm_framebuffer *fb;
782 struct drm_crtc *crtc;
783 struct drm_display_mode *mode;
784
785 uint32_t x;
786 uint32_t y;
787
788 struct drm_connector **connectors;
789 size_t num_connectors;
790};
791
792#define obj_to_crtc(x) container_of(x, struct drm_crtc, base)
793
794__printf(6, 7)
795int drm_crtc_init_with_planes(struct drm_device *dev,
796 struct drm_crtc *crtc,
797 struct drm_plane *primary,
798 struct drm_plane *cursor,
799 const struct drm_crtc_funcs *funcs,
800 const char *name, ...);
801void drm_crtc_cleanup(struct drm_crtc *crtc);
802
803/**
804 * drm_crtc_index - find the index of a registered CRTC
805 * @crtc: CRTC to find index for
806 *
807 * Given a registered CRTC, return the index of that CRTC within a DRM
808 * device's list of CRTCs.
809 */
810static inline unsigned int drm_crtc_index(const struct drm_crtc *crtc)
811{
812 return crtc->index;
813}
814
815/**
816 * drm_crtc_mask - find the mask of a registered CRTC
817 * @crtc: CRTC to find mask for
818 *
819 * Given a registered CRTC, return the mask bit of that CRTC for an
820 * encoder's possible_crtcs field.
821 */
822static inline uint32_t drm_crtc_mask(const struct drm_crtc *crtc)
823{
824 return 1 << drm_crtc_index(crtc);
825}
826
827void drm_crtc_get_hv_timing(const struct drm_display_mode *mode,
828 int *hdisplay, int *vdisplay);
829int drm_crtc_force_disable(struct drm_crtc *crtc);
830int drm_crtc_force_disable_all(struct drm_device *dev);
831
832int drm_mode_set_config_internal(struct drm_mode_set *set);
833
834/* Helpers */
835static inline struct drm_crtc *drm_crtc_find(struct drm_device *dev,
836 uint32_t id)
837{
838 struct drm_mode_object *mo;
839 mo = drm_mode_object_find(dev, id, DRM_MODE_OBJECT_CRTC);
840 return mo ? obj_to_crtc(mo) : NULL;
841}
842
843#define drm_for_each_crtc(crtc, dev) \
844 list_for_each_entry(crtc, &(dev)->mode_config.crtc_list, head)
845
846static inline void
847assert_drm_connector_list_read_locked(struct drm_mode_config *mode_config)
848{
849 /*
850 * The connector hotadd/remove code currently grabs both locks when
851 * updating lists. Hence readers need only hold either of them to be
852 * safe and the check amounts to
853 *
854 * WARN_ON(not_holding(A) && not_holding(B)).
855 */
856 WARN_ON(!mutex_is_locked(&mode_config->mutex) &&
857 !drm_modeset_is_locked(&mode_config->connection_mutex));
858}
859
860#endif /* __DRM_CRTC_H__ */