1 /* $NetBSD: drm_crtc.h,v 1.9 2021/12/18 23:45:45 riastradh Exp $ */
2
3 /*
4 * Copyright © 2006 Keith Packard
5 * Copyright © 2007-2008 Dave Airlie
6 * Copyright © 2007-2008 Intel Corporation
7 * Jesse Barnes <jesse.barnes@intel.com>
8 *
9 * Permission is hereby granted, free of charge, to any person obtaining a
10 * copy of this software and associated documentation files (the "Software"),
11 * to deal in the Software without restriction, including without limitation
12 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
13 * and/or sell copies of the Software, and to permit persons to whom the
14 * Software is furnished to do so, subject to the following conditions:
15 *
16 * The above copyright notice and this permission notice shall be included in
17 * all copies or substantial portions of the Software.
18 *
19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
22 * THE COPYRIGHT HOLDER(S) OR AUTHOR(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR
23 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
24 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
25 * OTHER DEALINGS IN THE SOFTWARE.
26 */
27 #ifndef __DRM_CRTC_H__
28 #define __DRM_CRTC_H__
29
30 #include <linux/i2c.h>
31 #include <linux/spinlock.h>
32 #include <linux/types.h>
33 #include <linux/fb.h>
34 #include <linux/hdmi.h>
35 #include <linux/media-bus-format.h>
36 #include <linux/kref.h>
37 #include <linux/mutex.h>
38 #include <linux/workqueue.h>
39 #include <uapi/drm/drm_mode.h>
40 #include <uapi/drm/drm_fourcc.h>
41 #include <drm/drm_modeset_lock.h>
42 #include <drm/drm_rect.h>
43 #include <drm/drm_mode_object.h>
44 #include <drm/drm_framebuffer.h>
45 #include <drm/drm_modes.h>
46 #include <drm/drm_connector.h>
47 #include <drm/drm_device.h>
48 #include <drm/drm_property.h>
49 #include <drm/drm_edid.h>
50 #include <drm/drm_plane.h>
51 #include <drm/drm_blend.h>
52 #include <drm/drm_color_mgmt.h>
53 #include <drm/drm_debugfs_crc.h>
54 #include <drm/drm_mode_config.h>
55
56 struct drm_device;
57 struct drm_mode_set;
58 struct drm_file;
59 struct drm_clip_rect;
60 struct drm_printer;
61 struct drm_self_refresh_data;
62 struct device_node;
63 struct dma_fence;
64 struct edid;
65
U642I64(uint64_t val)66 static inline int64_t U642I64(uint64_t val)
67 {
68 return (int64_t)*((int64_t *)&val);
69 }
I642U64(int64_t val)70 static inline uint64_t I642U64(int64_t val)
71 {
72 return (uint64_t)*((uint64_t *)&val);
73 }
74
75 struct drm_crtc;
76 struct drm_pending_vblank_event;
77 struct drm_plane;
78 struct drm_bridge;
79 struct drm_atomic_state;
80
81 struct drm_crtc_helper_funcs;
82 struct drm_plane_helper_funcs;
83
84 /**
85 * struct drm_crtc_state - mutable CRTC state
86 *
87 * Note that the distinction between @enable and @active is rather subtle:
88 * Flipping @active while @enable is set without changing anything else may
89 * never return in a failure from the &drm_mode_config_funcs.atomic_check
90 * callback. Userspace assumes that a DPMS On will always succeed. In other
91 * words: @enable controls resource assignment, @active controls the actual
92 * hardware state.
93 *
94 * The three booleans active_changed, connectors_changed and mode_changed are
95 * intended to indicate whether a full modeset is needed, rather than strictly
96 * describing what has changed in a commit. See also:
97 * drm_atomic_crtc_needs_modeset()
98 *
99 * WARNING: Transitional helpers (like drm_helper_crtc_mode_set() or
100 * drm_helper_crtc_mode_set_base()) do not maintain many of the derived control
101 * state like @plane_mask so drivers not converted over to atomic helpers should
102 * not rely on these being accurate!
103 */
104 struct drm_crtc_state {
105 /** @crtc: backpointer to the CRTC */
106 struct drm_crtc *crtc;
107
108 /**
109 * @enable: Whether the CRTC should be enabled, gates all other state.
110 * This controls reservations of shared resources. Actual hardware state
111 * is controlled by @active.
112 */
113 bool enable;
114
115 /**
116 * @active: Whether the CRTC is actively displaying (used for DPMS).
117 * Implies that @enable is set. The driver must not release any shared
118 * resources if @active is set to false but @enable still true, because
119 * userspace expects that a DPMS ON always succeeds.
120 *
121 * Hence drivers must not consult @active in their various
122 * &drm_mode_config_funcs.atomic_check callback to reject an atomic
123 * commit. They can consult it to aid in the computation of derived
124 * hardware state, since even in the DPMS OFF state the display hardware
125 * should be as much powered down as when the CRTC is completely
126 * disabled through setting @enable to false.
127 */
128 bool active;
129
130 /**
131 * @planes_changed: Planes on this crtc are updated. Used by the atomic
132 * helpers and drivers to steer the atomic commit control flow.
133 */
134 bool planes_changed : 1;
135
136 /**
137 * @mode_changed: @mode or @enable has been changed. Used by the atomic
138 * helpers and drivers to steer the atomic commit control flow. See also
139 * drm_atomic_crtc_needs_modeset().
140 *
141 * Drivers are supposed to set this for any CRTC state changes that
142 * require a full modeset. They can also reset it to false if e.g. a
143 * @mode change can be done without a full modeset by only changing
144 * scaler settings.
145 */
146 bool mode_changed : 1;
147
148 /**
149 * @active_changed: @active has been toggled. Used by the atomic
150 * helpers and drivers to steer the atomic commit control flow. See also
151 * drm_atomic_crtc_needs_modeset().
152 */
153 bool active_changed : 1;
154
155 /**
156 * @connectors_changed: Connectors to this crtc have been updated,
157 * either in their state or routing. Used by the atomic
158 * helpers and drivers to steer the atomic commit control flow. See also
159 * drm_atomic_crtc_needs_modeset().
160 *
161 * Drivers are supposed to set this as-needed from their own atomic
162 * check code, e.g. from &drm_encoder_helper_funcs.atomic_check
163 */
164 bool connectors_changed : 1;
165 /**
166 * @zpos_changed: zpos values of planes on this crtc have been updated.
167 * Used by the atomic helpers and drivers to steer the atomic commit
168 * control flow.
169 */
170 bool zpos_changed : 1;
171 /**
172 * @color_mgmt_changed: Color management properties have changed
173 * (@gamma_lut, @degamma_lut or @ctm). Used by the atomic helpers and
174 * drivers to steer the atomic commit control flow.
175 */
176 bool color_mgmt_changed : 1;
177
178 /**
179 * @no_vblank:
180 *
181 * Reflects the ability of a CRTC to send VBLANK events. This state
182 * usually depends on the pipeline configuration, and the main usuage
183 * is CRTCs feeding a writeback connector operating in oneshot mode.
184 * In this case the VBLANK event is only generated when a job is queued
185 * to the writeback connector, and we want the core to fake VBLANK
186 * events when this part of the pipeline hasn't changed but others had
187 * or when the CRTC and connectors are being disabled.
188 *
189 * __drm_atomic_helper_crtc_duplicate_state() will not reset the value
190 * from the current state, the CRTC driver is then responsible for
191 * updating this field when needed.
192 *
193 * Note that the combination of &drm_crtc_state.event == NULL and
194 * &drm_crtc_state.no_blank == true is valid and usually used when the
195 * writeback connector attached to the CRTC has a new job queued. In
196 * this case the driver will send the VBLANK event on its own when the
197 * writeback job is complete.
198 */
199 bool no_vblank : 1;
200
201 /**
202 * @plane_mask: Bitmask of drm_plane_mask(plane) of planes attached to
203 * this CRTC.
204 */
205 u32 plane_mask;
206
207 /**
208 * @connector_mask: Bitmask of drm_connector_mask(connector) of
209 * connectors attached to this CRTC.
210 */
211 u32 connector_mask;
212
213 /**
214 * @encoder_mask: Bitmask of drm_encoder_mask(encoder) of encoders
215 * attached to this CRTC.
216 */
217 u32 encoder_mask;
218
219 /**
220 * @adjusted_mode:
221 *
222 * Internal display timings which can be used by the driver to handle
223 * differences between the mode requested by userspace in @mode and what
224 * is actually programmed into the hardware.
225 *
226 * For drivers using &drm_bridge, this stores hardware display timings
227 * used between the CRTC and the first bridge. For other drivers, the
228 * meaning of the adjusted_mode field is purely driver implementation
229 * defined information, and will usually be used to store the hardware
230 * display timings used between the CRTC and encoder blocks.
231 */
232 struct drm_display_mode adjusted_mode;
233
234 /**
235 * @mode:
236 *
237 * Display timings requested by userspace. The driver should try to
238 * match the refresh rate as close as possible (but note that it's
239 * undefined what exactly is close enough, e.g. some of the HDMI modes
240 * only differ in less than 1% of the refresh rate). The active width
241 * and height as observed by userspace for positioning planes must match
242 * exactly.
243 *
244 * For external connectors where the sink isn't fixed (like with a
245 * built-in panel), this mode here should match the physical mode on the
246 * wire to the last details (i.e. including sync polarities and
247 * everything).
248 */
249 struct drm_display_mode mode;
250
251 /**
252 * @mode_blob: &drm_property_blob for @mode, for exposing the mode to
253 * atomic userspace.
254 */
255 struct drm_property_blob *mode_blob;
256
257 /**
258 * @degamma_lut:
259 *
260 * Lookup table for converting framebuffer pixel data before apply the
261 * color conversion matrix @ctm. See drm_crtc_enable_color_mgmt(). The
262 * blob (if not NULL) is an array of &struct drm_color_lut.
263 */
264 struct drm_property_blob *degamma_lut;
265
266 /**
267 * @ctm:
268 *
269 * Color transformation matrix. See drm_crtc_enable_color_mgmt(). The
270 * blob (if not NULL) is a &struct drm_color_ctm.
271 */
272 struct drm_property_blob *ctm;
273
274 /**
275 * @gamma_lut:
276 *
277 * Lookup table for converting pixel data after the color conversion
278 * matrix @ctm. See drm_crtc_enable_color_mgmt(). The blob (if not
279 * NULL) is an array of &struct drm_color_lut.
280 */
281 struct drm_property_blob *gamma_lut;
282
283 /**
284 * @target_vblank:
285 *
286 * Target vertical blank period when a page flip
287 * should take effect.
288 */
289 u32 target_vblank;
290
291 /**
292 * @async_flip:
293 *
294 * This is set when DRM_MODE_PAGE_FLIP_ASYNC is set in the legacy
295 * PAGE_FLIP IOCTL. It's not wired up for the atomic IOCTL itself yet.
296 */
297 bool async_flip;
298
299 /**
300 * @vrr_enabled:
301 *
302 * Indicates if variable refresh rate should be enabled for the CRTC.
303 * Support for the requested vrr state will depend on driver and
304 * hardware capabiltiy - lacking support is not treated as failure.
305 */
306 bool vrr_enabled;
307
308 /**
309 * @self_refresh_active:
310 *
311 * Used by the self refresh helpers to denote when a self refresh
312 * transition is occurring. This will be set on enable/disable callbacks
313 * when self refresh is being enabled or disabled. In some cases, it may
314 * not be desirable to fully shut off the crtc during self refresh.
315 * CRTC's can inspect this flag and determine the best course of action.
316 */
317 bool self_refresh_active;
318
319 /**
320 * @event:
321 *
322 * Optional pointer to a DRM event to signal upon completion of the
323 * state update. The driver must send out the event when the atomic
324 * commit operation completes. There are two cases:
325 *
326 * - The event is for a CRTC which is being disabled through this
327 * atomic commit. In that case the event can be send out any time
328 * after the hardware has stopped scanning out the current
329 * framebuffers. It should contain the timestamp and counter for the
330 * last vblank before the display pipeline was shut off. The simplest
331 * way to achieve that is calling drm_crtc_send_vblank_event()
332 * somewhen after drm_crtc_vblank_off() has been called.
333 *
334 * - For a CRTC which is enabled at the end of the commit (even when it
335 * undergoes an full modeset) the vblank timestamp and counter must
336 * be for the vblank right before the first frame that scans out the
337 * new set of buffers. Again the event can only be sent out after the
338 * hardware has stopped scanning out the old buffers.
339 *
340 * - Events for disabled CRTCs are not allowed, and drivers can ignore
341 * that case.
342 *
343 * This can be handled by the drm_crtc_send_vblank_event() function,
344 * which the driver should call on the provided event upon completion of
345 * the atomic commit. Note that if the driver supports vblank signalling
346 * and timestamping the vblank counters and timestamps must agree with
347 * the ones returned from page flip events. With the current vblank
348 * helper infrastructure this can be achieved by holding a vblank
349 * reference while the page flip is pending, acquired through
350 * drm_crtc_vblank_get() and released with drm_crtc_vblank_put().
351 * Drivers are free to implement their own vblank counter and timestamp
352 * tracking though, e.g. if they have accurate timestamp registers in
353 * hardware.
354 *
355 * For hardware which supports some means to synchronize vblank
356 * interrupt delivery with committing display state there's also
357 * drm_crtc_arm_vblank_event(). See the documentation of that function
358 * for a detailed discussion of the constraints it needs to be used
359 * safely.
360 *
361 * If the device can't notify of flip completion in a race-free way
362 * at all, then the event should be armed just after the page flip is
363 * committed. In the worst case the driver will send the event to
364 * userspace one frame too late. This doesn't allow for a real atomic
365 * update, but it should avoid tearing.
366 */
367 struct drm_pending_vblank_event *event;
368
369 /**
370 * @commit:
371 *
372 * This tracks how the commit for this update proceeds through the
373 * various phases. This is never cleared, except when we destroy the
374 * state, so that subsequent commits can synchronize with previous ones.
375 */
376 struct drm_crtc_commit *commit;
377
378 /** @state: backpointer to global drm_atomic_state */
379 struct drm_atomic_state *state;
380 };
381
382 /**
383 * struct drm_crtc_funcs - control CRTCs for a given device
384 *
385 * The drm_crtc_funcs structure is the central CRTC management structure
386 * in the DRM. Each CRTC controls one or more connectors (note that the name
387 * CRTC is simply historical, a CRTC may control LVDS, VGA, DVI, TV out, etc.
388 * connectors, not just CRTs).
389 *
390 * Each driver is responsible for filling out this structure at startup time,
391 * in addition to providing other modesetting features, like i2c and DDC
392 * bus accessors.
393 */
394 struct drm_crtc_funcs {
395 /**
396 * @reset:
397 *
398 * Reset CRTC hardware and software state to off. This function isn't
399 * called by the core directly, only through drm_mode_config_reset().
400 * It's not a helper hook only for historical reasons.
401 *
402 * Atomic drivers can use drm_atomic_helper_crtc_reset() to reset
403 * atomic state using this hook.
404 */
405 void (*reset)(struct drm_crtc *crtc);
406
407 /**
408 * @cursor_set:
409 *
410 * Update the cursor image. The cursor position is relative to the CRTC
411 * and can be partially or fully outside of the visible area.
412 *
413 * Note that contrary to all other KMS functions the legacy cursor entry
414 * points don't take a framebuffer object, but instead take directly a
415 * raw buffer object id from the driver's buffer manager (which is
416 * either GEM or TTM for current drivers).
417 *
418 * This entry point is deprecated, drivers should instead implement
419 * universal plane support and register a proper cursor plane using
420 * drm_crtc_init_with_planes().
421 *
422 * This callback is optional
423 *
424 * RETURNS:
425 *
426 * 0 on success or a negative error code on failure.
427 */
428 int (*cursor_set)(struct drm_crtc *crtc, struct drm_file *file_priv,
429 uint32_t handle, uint32_t width, uint32_t height);
430
431 /**
432 * @cursor_set2:
433 *
434 * Update the cursor image, including hotspot information. The hotspot
435 * must not affect the cursor position in CRTC coordinates, but is only
436 * meant as a hint for virtualized display hardware to coordinate the
437 * guests and hosts cursor position. The cursor hotspot is relative to
438 * the cursor image. Otherwise this works exactly like @cursor_set.
439 *
440 * This entry point is deprecated, drivers should instead implement
441 * universal plane support and register a proper cursor plane using
442 * drm_crtc_init_with_planes().
443 *
444 * This callback is optional.
445 *
446 * RETURNS:
447 *
448 * 0 on success or a negative error code on failure.
449 */
450 int (*cursor_set2)(struct drm_crtc *crtc, struct drm_file *file_priv,
451 uint32_t handle, uint32_t width, uint32_t height,
452 int32_t hot_x, int32_t hot_y);
453
454 /**
455 * @cursor_move:
456 *
457 * Update the cursor position. The cursor does not need to be visible
458 * when this hook is called.
459 *
460 * This entry point is deprecated, drivers should instead implement
461 * universal plane support and register a proper cursor plane using
462 * drm_crtc_init_with_planes().
463 *
464 * This callback is optional.
465 *
466 * RETURNS:
467 *
468 * 0 on success or a negative error code on failure.
469 */
470 int (*cursor_move)(struct drm_crtc *crtc, int x, int y);
471
472 /**
473 * @gamma_set:
474 *
475 * Set gamma on the CRTC.
476 *
477 * This callback is optional.
478 *
479 * Atomic drivers who want to support gamma tables should implement the
480 * atomic color management support, enabled by calling
481 * drm_crtc_enable_color_mgmt(), which then supports the legacy gamma
482 * interface through the drm_atomic_helper_legacy_gamma_set()
483 * compatibility implementation.
484 */
485 int (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b,
486 uint32_t size,
487 struct drm_modeset_acquire_ctx *ctx);
488
489 /**
490 * @destroy:
491 *
492 * Clean up CRTC resources. This is only called at driver unload time
493 * through drm_mode_config_cleanup() since a CRTC cannot be hotplugged
494 * in DRM.
495 */
496 void (*destroy)(struct drm_crtc *crtc);
497
498 /**
499 * @set_config:
500 *
501 * This is the main legacy entry point to change the modeset state on a
502 * CRTC. All the details of the desired configuration are passed in a
503 * &struct drm_mode_set - see there for details.
504 *
505 * Drivers implementing atomic modeset should use
506 * drm_atomic_helper_set_config() to implement this hook.
507 *
508 * RETURNS:
509 *
510 * 0 on success or a negative error code on failure.
511 */
512 int (*set_config)(struct drm_mode_set *set,
513 struct drm_modeset_acquire_ctx *ctx);
514
515 /**
516 * @page_flip:
517 *
518 * Legacy entry point to schedule a flip to the given framebuffer.
519 *
520 * Page flipping is a synchronization mechanism that replaces the frame
521 * buffer being scanned out by the CRTC with a new frame buffer during
522 * vertical blanking, avoiding tearing (except when requested otherwise
523 * through the DRM_MODE_PAGE_FLIP_ASYNC flag). When an application
524 * requests a page flip the DRM core verifies that the new frame buffer
525 * is large enough to be scanned out by the CRTC in the currently
526 * configured mode and then calls this hook with a pointer to the new
527 * frame buffer.
528 *
529 * The driver must wait for any pending rendering to the new framebuffer
530 * to complete before executing the flip. It should also wait for any
531 * pending rendering from other drivers if the underlying buffer is a
532 * shared dma-buf.
533 *
534 * An application can request to be notified when the page flip has
535 * completed. The drm core will supply a &struct drm_event in the event
536 * parameter in this case. This can be handled by the
537 * drm_crtc_send_vblank_event() function, which the driver should call on
538 * the provided event upon completion of the flip. Note that if
539 * the driver supports vblank signalling and timestamping the vblank
540 * counters and timestamps must agree with the ones returned from page
541 * flip events. With the current vblank helper infrastructure this can
542 * be achieved by holding a vblank reference while the page flip is
543 * pending, acquired through drm_crtc_vblank_get() and released with
544 * drm_crtc_vblank_put(). Drivers are free to implement their own vblank
545 * counter and timestamp tracking though, e.g. if they have accurate
546 * timestamp registers in hardware.
547 *
548 * This callback is optional.
549 *
550 * NOTE:
551 *
552 * Very early versions of the KMS ABI mandated that the driver must
553 * block (but not reject) any rendering to the old framebuffer until the
554 * flip operation has completed and the old framebuffer is no longer
555 * visible. This requirement has been lifted, and userspace is instead
556 * expected to request delivery of an event and wait with recycling old
557 * buffers until such has been received.
558 *
559 * RETURNS:
560 *
561 * 0 on success or a negative error code on failure. Note that if a
562 * page flip operation is already pending the callback should return
563 * -EBUSY. Pageflips on a disabled CRTC (either by setting a NULL mode
564 * or just runtime disabled through DPMS respectively the new atomic
565 * "ACTIVE" state) should result in an -EINVAL error code. Note that
566 * drm_atomic_helper_page_flip() checks this already for atomic drivers.
567 */
568 int (*page_flip)(struct drm_crtc *crtc,
569 struct drm_framebuffer *fb,
570 struct drm_pending_vblank_event *event,
571 uint32_t flags,
572 struct drm_modeset_acquire_ctx *ctx);
573
574 /**
575 * @page_flip_target:
576 *
577 * Same as @page_flip but with an additional parameter specifying the
578 * absolute target vertical blank period (as reported by
579 * drm_crtc_vblank_count()) when the flip should take effect.
580 *
581 * Note that the core code calls drm_crtc_vblank_get before this entry
582 * point, and will call drm_crtc_vblank_put if this entry point returns
583 * any non-0 error code. It's the driver's responsibility to call
584 * drm_crtc_vblank_put after this entry point returns 0, typically when
585 * the flip completes.
586 */
587 int (*page_flip_target)(struct drm_crtc *crtc,
588 struct drm_framebuffer *fb,
589 struct drm_pending_vblank_event *event,
590 uint32_t flags, uint32_t target,
591 struct drm_modeset_acquire_ctx *ctx);
592
593 /**
594 * @set_property:
595 *
596 * This is the legacy entry point to update a property attached to the
597 * CRTC.
598 *
599 * This callback is optional if the driver does not support any legacy
600 * driver-private properties. For atomic drivers it is not used because
601 * property handling is done entirely in the DRM core.
602 *
603 * RETURNS:
604 *
605 * 0 on success or a negative error code on failure.
606 */
607 int (*set_property)(struct drm_crtc *crtc,
608 struct drm_property *property, uint64_t val);
609
610 /**
611 * @atomic_duplicate_state:
612 *
613 * Duplicate the current atomic state for this CRTC and return it.
614 * The core and helpers guarantee that any atomic state duplicated with
615 * this hook and still owned by the caller (i.e. not transferred to the
616 * driver by calling &drm_mode_config_funcs.atomic_commit) will be
617 * cleaned up by calling the @atomic_destroy_state hook in this
618 * structure.
619 *
620 * This callback is mandatory for atomic drivers.
621 *
622 * Atomic drivers which don't subclass &struct drm_crtc_state should use
623 * drm_atomic_helper_crtc_duplicate_state(). Drivers that subclass the
624 * state structure to extend it with driver-private state should use
625 * __drm_atomic_helper_crtc_duplicate_state() to make sure shared state is
626 * duplicated in a consistent fashion across drivers.
627 *
628 * It is an error to call this hook before &drm_crtc.state has been
629 * initialized correctly.
630 *
631 * NOTE:
632 *
633 * If the duplicate state references refcounted resources this hook must
634 * acquire a reference for each of them. The driver must release these
635 * references again in @atomic_destroy_state.
636 *
637 * RETURNS:
638 *
639 * Duplicated atomic state or NULL when the allocation failed.
640 */
641 struct drm_crtc_state *(*atomic_duplicate_state)(struct drm_crtc *crtc);
642
643 /**
644 * @atomic_destroy_state:
645 *
646 * Destroy a state duplicated with @atomic_duplicate_state and release
647 * or unreference all resources it references
648 *
649 * This callback is mandatory for atomic drivers.
650 */
651 void (*atomic_destroy_state)(struct drm_crtc *crtc,
652 struct drm_crtc_state *state);
653
654 /**
655 * @atomic_set_property:
656 *
657 * Decode a driver-private property value and store the decoded value
658 * into the passed-in state structure. Since the atomic core decodes all
659 * standardized properties (even for extensions beyond the core set of
660 * properties which might not be implemented by all drivers) this
661 * requires drivers to subclass the state structure.
662 *
663 * Such driver-private properties should really only be implemented for
664 * truly hardware/vendor specific state. Instead it is preferred to
665 * standardize atomic extension and decode the properties used to expose
666 * such an extension in the core.
667 *
668 * Do not call this function directly, use
669 * drm_atomic_crtc_set_property() instead.
670 *
671 * This callback is optional if the driver does not support any
672 * driver-private atomic properties.
673 *
674 * NOTE:
675 *
676 * This function is called in the state assembly phase of atomic
677 * modesets, which can be aborted for any reason (including on
678 * userspace's request to just check whether a configuration would be
679 * possible). Drivers MUST NOT touch any persistent state (hardware or
680 * software) or data structures except the passed in @state parameter.
681 *
682 * Also since userspace controls in which order properties are set this
683 * function must not do any input validation (since the state update is
684 * incomplete and hence likely inconsistent). Instead any such input
685 * validation must be done in the various atomic_check callbacks.
686 *
687 * RETURNS:
688 *
689 * 0 if the property has been found, -EINVAL if the property isn't
690 * implemented by the driver (which should never happen, the core only
691 * asks for properties attached to this CRTC). No other validation is
692 * allowed by the driver. The core already checks that the property
693 * value is within the range (integer, valid enum value, ...) the driver
694 * set when registering the property.
695 */
696 int (*atomic_set_property)(struct drm_crtc *crtc,
697 struct drm_crtc_state *state,
698 struct drm_property *property,
699 uint64_t val);
700 /**
701 * @atomic_get_property:
702 *
703 * Reads out the decoded driver-private property. This is used to
704 * implement the GETCRTC IOCTL.
705 *
706 * Do not call this function directly, use
707 * drm_atomic_crtc_get_property() instead.
708 *
709 * This callback is optional if the driver does not support any
710 * driver-private atomic properties.
711 *
712 * RETURNS:
713 *
714 * 0 on success, -EINVAL if the property isn't implemented by the
715 * driver (which should never happen, the core only asks for
716 * properties attached to this CRTC).
717 */
718 int (*atomic_get_property)(struct drm_crtc *crtc,
719 const struct drm_crtc_state *state,
720 struct drm_property *property,
721 uint64_t *val);
722
723 /**
724 * @late_register:
725 *
726 * This optional hook can be used to register additional userspace
727 * interfaces attached to the crtc like debugfs interfaces.
728 * It is called late in the driver load sequence from drm_dev_register().
729 * Everything added from this callback should be unregistered in
730 * the early_unregister callback.
731 *
732 * Returns:
733 *
734 * 0 on success, or a negative error code on failure.
735 */
736 int (*late_register)(struct drm_crtc *crtc);
737
738 /**
739 * @early_unregister:
740 *
741 * This optional hook should be used to unregister the additional
742 * userspace interfaces attached to the crtc from
743 * @late_register. It is called from drm_dev_unregister(),
744 * early in the driver unload sequence to disable userspace access
745 * before data structures are torndown.
746 */
747 void (*early_unregister)(struct drm_crtc *crtc);
748
749 /**
750 * @set_crc_source:
751 *
752 * Changes the source of CRC checksums of frames at the request of
753 * userspace, typically for testing purposes. The sources available are
754 * specific of each driver and a %NULL value indicates that CRC
755 * generation is to be switched off.
756 *
757 * When CRC generation is enabled, the driver should call
758 * drm_crtc_add_crc_entry() at each frame, providing any information
759 * that characterizes the frame contents in the crcN arguments, as
760 * provided from the configured source. Drivers must accept an "auto"
761 * source name that will select a default source for this CRTC.
762 *
763 * This may trigger an atomic modeset commit if necessary, to enable CRC
764 * generation.
765 *
766 * Note that "auto" can depend upon the current modeset configuration,
767 * e.g. it could pick an encoder or output specific CRC sampling point.
768 *
769 * This callback is optional if the driver does not support any CRC
770 * generation functionality.
771 *
772 * RETURNS:
773 *
774 * 0 on success or a negative error code on failure.
775 */
776 int (*set_crc_source)(struct drm_crtc *crtc, const char *source);
777
778 /**
779 * @verify_crc_source:
780 *
781 * verifies the source of CRC checksums of frames before setting the
782 * source for CRC and during crc open. Source parameter can be NULL
783 * while disabling crc source.
784 *
785 * This callback is optional if the driver does not support any CRC
786 * generation functionality.
787 *
788 * RETURNS:
789 *
790 * 0 on success or a negative error code on failure.
791 */
792 int (*verify_crc_source)(struct drm_crtc *crtc, const char *source,
793 size_t *values_cnt);
794 /**
795 * @get_crc_sources:
796 *
797 * Driver callback for getting a list of all the available sources for
798 * CRC generation. This callback depends upon verify_crc_source, So
799 * verify_crc_source callback should be implemented before implementing
800 * this. Driver can pass full list of available crc sources, this
801 * callback does the verification on each crc-source before passing it
802 * to userspace.
803 *
804 * This callback is optional if the driver does not support exporting of
805 * possible CRC sources list.
806 *
807 * RETURNS:
808 *
809 * a constant character pointer to the list of all the available CRC
810 * sources. On failure driver should return NULL. count should be
811 * updated with number of sources in list. if zero we don't process any
812 * source from the list.
813 */
814 const char *const *(*get_crc_sources)(struct drm_crtc *crtc,
815 size_t *count);
816
817 /**
818 * @atomic_print_state:
819 *
820 * If driver subclasses &struct drm_crtc_state, it should implement
821 * this optional hook for printing additional driver specific state.
822 *
823 * Do not call this directly, use drm_atomic_crtc_print_state()
824 * instead.
825 */
826 void (*atomic_print_state)(struct drm_printer *p,
827 const struct drm_crtc_state *state);
828
829 /**
830 * @get_vblank_counter:
831 *
832 * Driver callback for fetching a raw hardware vblank counter for the
833 * CRTC. It's meant to be used by new drivers as the replacement of
834 * &drm_driver.get_vblank_counter hook.
835 *
836 * This callback is optional. If a device doesn't have a hardware
837 * counter, the driver can simply leave the hook as NULL. The DRM core
838 * will account for missed vblank events while interrupts where disabled
839 * based on system timestamps.
840 *
841 * Wraparound handling and loss of events due to modesetting is dealt
842 * with in the DRM core code, as long as drivers call
843 * drm_crtc_vblank_off() and drm_crtc_vblank_on() when disabling or
844 * enabling a CRTC.
845 *
846 * See also &drm_device.vblank_disable_immediate and
847 * &drm_device.max_vblank_count.
848 *
849 * Returns:
850 *
851 * Raw vblank counter value.
852 */
853 u32 (*get_vblank_counter)(struct drm_crtc *crtc);
854
855 /**
856 * @enable_vblank:
857 *
858 * Enable vblank interrupts for the CRTC. It's meant to be used by
859 * new drivers as the replacement of &drm_driver.enable_vblank hook.
860 *
861 * Returns:
862 *
863 * Zero on success, appropriate errno if the vblank interrupt cannot
864 * be enabled.
865 */
866 int (*enable_vblank)(struct drm_crtc *crtc);
867
868 /**
869 * @disable_vblank:
870 *
871 * Disable vblank interrupts for the CRTC. It's meant to be used by
872 * new drivers as the replacement of &drm_driver.disable_vblank hook.
873 */
874 void (*disable_vblank)(struct drm_crtc *crtc);
875 };
876
877 /**
878 * struct drm_crtc - central CRTC control structure
879 *
880 * Each CRTC may have one or more connectors associated with it. This structure
881 * allows the CRTC to be controlled.
882 */
883 struct drm_crtc {
884 /** @dev: parent DRM device */
885 struct drm_device *dev;
886 /** @port: OF node used by drm_of_find_possible_crtcs(). */
887 struct device_node *port;
888 /**
889 * @head:
890 *
891 * List of all CRTCs on @dev, linked from &drm_mode_config.crtc_list.
892 * Invariant over the lifetime of @dev and therefore does not need
893 * locking.
894 */
895 struct list_head head;
896
897 /** @name: human readable name, can be overwritten by the driver */
898 char *name;
899
900 /**
901 * @mutex:
902 *
903 * This provides a read lock for the overall CRTC state (mode, dpms
904 * state, ...) and a write lock for everything which can be update
905 * without a full modeset (fb, cursor data, CRTC properties ...). A full
906 * modeset also need to grab &drm_mode_config.connection_mutex.
907 *
908 * For atomic drivers specifically this protects @state.
909 */
910 struct drm_modeset_lock mutex;
911
912 /** @base: base KMS object for ID tracking etc. */
913 struct drm_mode_object base;
914
915 /**
916 * @primary:
917 * Primary plane for this CRTC. Note that this is only
918 * relevant for legacy IOCTL, it specifies the plane implicitly used by
919 * the SETCRTC and PAGE_FLIP IOCTLs. It does not have any significance
920 * beyond that.
921 */
922 struct drm_plane *primary;
923
924 /**
925 * @cursor:
926 * Cursor plane for this CRTC. Note that this is only relevant for
927 * legacy IOCTL, it specifies the plane implicitly used by the SETCURSOR
928 * and SETCURSOR2 IOCTLs. It does not have any significance
929 * beyond that.
930 */
931 struct drm_plane *cursor;
932
933 /**
934 * @index: Position inside the mode_config.list, can be used as an array
935 * index. It is invariant over the lifetime of the CRTC.
936 */
937 unsigned index;
938
939 /**
940 * @cursor_x: Current x position of the cursor, used for universal
941 * cursor planes because the SETCURSOR IOCTL only can update the
942 * framebuffer without supplying the coordinates. Drivers should not use
943 * this directly, atomic drivers should look at &drm_plane_state.crtc_x
944 * of the cursor plane instead.
945 */
946 int cursor_x;
947 /**
948 * @cursor_y: Current y position of the cursor, used for universal
949 * cursor planes because the SETCURSOR IOCTL only can update the
950 * framebuffer without supplying the coordinates. Drivers should not use
951 * this directly, atomic drivers should look at &drm_plane_state.crtc_y
952 * of the cursor plane instead.
953 */
954 int cursor_y;
955
956 /**
957 * @enabled:
958 *
959 * Is this CRTC enabled? Should only be used by legacy drivers, atomic
960 * drivers should instead consult &drm_crtc_state.enable and
961 * &drm_crtc_state.active. Atomic drivers can update this by calling
962 * drm_atomic_helper_update_legacy_modeset_state().
963 */
964 bool enabled;
965
966 /**
967 * @mode:
968 *
969 * Current mode timings. Should only be used by legacy drivers, atomic
970 * drivers should instead consult &drm_crtc_state.mode. Atomic drivers
971 * can update this by calling
972 * drm_atomic_helper_update_legacy_modeset_state().
973 */
974 struct drm_display_mode mode;
975
976 /**
977 * @hwmode:
978 *
979 * Programmed mode in hw, after adjustments for encoders, crtc, panel
980 * scaling etc. Should only be used by legacy drivers, for high
981 * precision vblank timestamps in
982 * drm_calc_vbltimestamp_from_scanoutpos().
983 *
984 * Note that atomic drivers should not use this, but instead use
985 * &drm_crtc_state.adjusted_mode. And for high-precision timestamps
986 * drm_calc_vbltimestamp_from_scanoutpos() used &drm_vblank_crtc.hwmode,
987 * which is filled out by calling drm_calc_timestamping_constants().
988 */
989 struct drm_display_mode hwmode;
990
991 /**
992 * @x:
993 * x position on screen. Should only be used by legacy drivers, atomic
994 * drivers should look at &drm_plane_state.crtc_x of the primary plane
995 * instead. Updated by calling
996 * drm_atomic_helper_update_legacy_modeset_state().
997 */
998 int x;
999 /**
1000 * @y:
1001 * y position on screen. Should only be used by legacy drivers, atomic
1002 * drivers should look at &drm_plane_state.crtc_y of the primary plane
1003 * instead. Updated by calling
1004 * drm_atomic_helper_update_legacy_modeset_state().
1005 */
1006 int y;
1007
1008 /** @funcs: CRTC control functions */
1009 const struct drm_crtc_funcs *funcs;
1010
1011 /**
1012 * @gamma_size: Size of legacy gamma ramp reported to userspace. Set up
1013 * by calling drm_mode_crtc_set_gamma_size().
1014 */
1015 uint32_t gamma_size;
1016
1017 /**
1018 * @gamma_store: Gamma ramp values used by the legacy SETGAMMA and
1019 * GETGAMMA IOCTls. Set up by calling drm_mode_crtc_set_gamma_size().
1020 */
1021 uint16_t *gamma_store;
1022
1023 /** @helper_private: mid-layer private data */
1024 const struct drm_crtc_helper_funcs *helper_private;
1025
1026 /** @properties: property tracking for this CRTC */
1027 struct drm_object_properties properties;
1028
1029 /**
1030 * @state:
1031 *
1032 * Current atomic state for this CRTC.
1033 *
1034 * This is protected by @mutex. Note that nonblocking atomic commits
1035 * access the current CRTC state without taking locks. Either by going
1036 * through the &struct drm_atomic_state pointers, see
1037 * for_each_oldnew_crtc_in_state(), for_each_old_crtc_in_state() and
1038 * for_each_new_crtc_in_state(). Or through careful ordering of atomic
1039 * commit operations as implemented in the atomic helpers, see
1040 * &struct drm_crtc_commit.
1041 */
1042 struct drm_crtc_state *state;
1043
1044 /**
1045 * @commit_list:
1046 *
1047 * List of &drm_crtc_commit structures tracking pending commits.
1048 * Protected by @commit_lock. This list holds its own full reference,
1049 * as does the ongoing commit.
1050 *
1051 * "Note that the commit for a state change is also tracked in
1052 * &drm_crtc_state.commit. For accessing the immediately preceding
1053 * commit in an atomic update it is recommended to just use that
1054 * pointer in the old CRTC state, since accessing that doesn't need
1055 * any locking or list-walking. @commit_list should only be used to
1056 * stall for framebuffer cleanup that's signalled through
1057 * &drm_crtc_commit.cleanup_done."
1058 */
1059 struct list_head commit_list;
1060
1061 /**
1062 * @commit_lock:
1063 *
1064 * Spinlock to protect @commit_list.
1065 */
1066 spinlock_t commit_lock;
1067
1068 #ifdef CONFIG_DEBUG_FS
1069 /**
1070 * @debugfs_entry:
1071 *
1072 * Debugfs directory for this CRTC.
1073 */
1074 struct dentry *debugfs_entry;
1075 #endif
1076
1077 /**
1078 * @crc:
1079 *
1080 * Configuration settings of CRC capture.
1081 */
1082 struct drm_crtc_crc crc;
1083
1084 /**
1085 * @fence_context:
1086 *
1087 * timeline context used for fence operations.
1088 */
1089 unsigned int fence_context;
1090
1091 /**
1092 * @fence_lock:
1093 *
1094 * spinlock to protect the fences in the fence_context.
1095 */
1096 spinlock_t fence_lock;
1097 /**
1098 * @fence_seqno:
1099 *
1100 * Seqno variable used as monotonic counter for the fences
1101 * created on the CRTC's timeline.
1102 */
1103 unsigned long fence_seqno;
1104
1105 /**
1106 * @timeline_name:
1107 *
1108 * The name of the CRTC's fence timeline.
1109 */
1110 char timeline_name[32];
1111
1112 /**
1113 * @self_refresh_data: Holds the state for the self refresh helpers
1114 *
1115 * Initialized via drm_self_refresh_helper_init().
1116 */
1117 struct drm_self_refresh_data *self_refresh_data;
1118 };
1119
1120 /**
1121 * struct drm_mode_set - new values for a CRTC config change
1122 * @fb: framebuffer to use for new config
1123 * @crtc: CRTC whose configuration we're about to change
1124 * @mode: mode timings to use
1125 * @x: position of this CRTC relative to @fb
1126 * @y: position of this CRTC relative to @fb
1127 * @connectors: array of connectors to drive with this CRTC if possible
1128 * @num_connectors: size of @connectors array
1129 *
1130 * This represents a modeset configuration for the legacy SETCRTC ioctl and is
1131 * also used internally. Atomic drivers instead use &drm_atomic_state.
1132 */
1133 struct drm_mode_set {
1134 struct drm_framebuffer *fb;
1135 struct drm_crtc *crtc;
1136 struct drm_display_mode *mode;
1137
1138 uint32_t x;
1139 uint32_t y;
1140
1141 struct drm_connector **connectors;
1142 size_t num_connectors;
1143 };
1144
1145 #define obj_to_crtc(x) container_of(x, struct drm_crtc, base)
1146
1147 __printf(6, 7)
1148 int drm_crtc_init_with_planes(struct drm_device *dev,
1149 struct drm_crtc *crtc,
1150 struct drm_plane *primary,
1151 struct drm_plane *cursor,
1152 const struct drm_crtc_funcs *funcs,
1153 const char *name, ...);
1154 void drm_crtc_cleanup(struct drm_crtc *crtc);
1155
1156 /**
1157 * drm_crtc_index - find the index of a registered CRTC
1158 * @crtc: CRTC to find index for
1159 *
1160 * Given a registered CRTC, return the index of that CRTC within a DRM
1161 * device's list of CRTCs.
1162 */
drm_crtc_index(const struct drm_crtc * crtc)1163 static inline unsigned int drm_crtc_index(const struct drm_crtc *crtc)
1164 {
1165 return crtc->index;
1166 }
1167
1168 /**
1169 * drm_crtc_mask - find the mask of a registered CRTC
1170 * @crtc: CRTC to find mask for
1171 *
1172 * Given a registered CRTC, return the mask bit of that CRTC for the
1173 * &drm_encoder.possible_crtcs and &drm_plane.possible_crtcs fields.
1174 */
drm_crtc_mask(const struct drm_crtc * crtc)1175 static inline uint32_t drm_crtc_mask(const struct drm_crtc *crtc)
1176 {
1177 return 1 << drm_crtc_index(crtc);
1178 }
1179
1180 int drm_mode_set_config_internal(struct drm_mode_set *set);
1181 struct drm_crtc *drm_crtc_from_index(struct drm_device *dev, int idx);
1182
1183 /**
1184 * drm_crtc_find - look up a CRTC object from its ID
1185 * @dev: DRM device
1186 * @file_priv: drm file to check for lease against.
1187 * @id: &drm_mode_object ID
1188 *
1189 * This can be used to look up a CRTC from its userspace ID. Only used by
1190 * drivers for legacy IOCTLs and interface, nowadays extensions to the KMS
1191 * userspace interface should be done using &drm_property.
1192 */
drm_crtc_find(struct drm_device * dev,struct drm_file * file_priv,uint32_t id)1193 static inline struct drm_crtc *drm_crtc_find(struct drm_device *dev,
1194 struct drm_file *file_priv,
1195 uint32_t id)
1196 {
1197 struct drm_mode_object *mo;
1198 mo = drm_mode_object_find(dev, file_priv, id, DRM_MODE_OBJECT_CRTC);
1199 return mo ? obj_to_crtc(mo) : NULL;
1200 }
1201
1202 /**
1203 * drm_for_each_crtc - iterate over all CRTCs
1204 * @crtc: a &struct drm_crtc as the loop cursor
1205 * @dev: the &struct drm_device
1206 *
1207 * Iterate over all CRTCs of @dev.
1208 */
1209 #define drm_for_each_crtc(crtc, dev) \
1210 list_for_each_entry(crtc, &(dev)->mode_config.crtc_list, head)
1211
1212 #endif /* __DRM_CRTC_H__ */
1213