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