drm_plane.h 27 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865
  1. /*
  2. * Copyright (c) 2016 Intel Corporation
  3. *
  4. * Permission to use, copy, modify, distribute, and sell this software and its
  5. * documentation for any purpose is hereby granted without fee, provided that
  6. * the above copyright notice appear in all copies and that both that copyright
  7. * notice and this permission notice appear in supporting documentation, and
  8. * that the name of the copyright holders not be used in advertising or
  9. * publicity pertaining to distribution of the software without specific,
  10. * written prior permission. The copyright holders make no representations
  11. * about the suitability of this software for any purpose. It is provided "as
  12. * is" without express or implied warranty.
  13. *
  14. * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
  15. * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
  16. * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  17. * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
  18. * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  19. * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  20. * OF THIS SOFTWARE.
  21. */
  22. #ifndef __DRM_PLANE_H__
  23. #define __DRM_PLANE_H__
  24. #include <linux/list.h>
  25. #include <linux/ctype.h>
  26. #include <drm/drm_mode_object.h>
  27. #include <drm/drm_color_mgmt.h>
  28. #include <drm/drm_rect.h>
  29. #include <drm/drm_modeset_lock.h>
  30. #include <drm/drm_util.h>
  31. struct drm_crtc;
  32. struct drm_printer;
  33. struct drm_modeset_acquire_ctx;
  34. /**
  35. * struct drm_plane_state - mutable plane state
  36. *
  37. * Please not that the destination coordinates @crtc_x, @crtc_y, @crtc_h and
  38. * @crtc_w and the source coordinates @src_x, @src_y, @src_h and @src_w are the
  39. * raw coordinates provided by userspace. Drivers should use
  40. * drm_atomic_helper_check_plane_state() and only use the derived rectangles in
  41. * @src and @dst to program the hardware.
  42. */
  43. struct drm_plane_state {
  44. /** @plane: backpointer to the plane */
  45. struct drm_plane *plane;
  46. /**
  47. * @crtc:
  48. *
  49. * Currently bound CRTC, NULL if disabled. Do not this write directly,
  50. * use drm_atomic_set_crtc_for_plane()
  51. */
  52. struct drm_crtc *crtc;
  53. /**
  54. * @fb:
  55. *
  56. * Currently bound framebuffer. Do not write this directly, use
  57. * drm_atomic_set_fb_for_plane()
  58. */
  59. struct drm_framebuffer *fb;
  60. /**
  61. * @fence:
  62. *
  63. * Optional fence to wait for before scanning out @fb. The core atomic
  64. * code will set this when userspace is using explicit fencing. Do not
  65. * write this field directly for a driver's implicit fence, use
  66. * drm_atomic_set_fence_for_plane() to ensure that an explicit fence is
  67. * preserved.
  68. *
  69. * Drivers should store any implicit fence in this from their
  70. * &drm_plane_helper_funcs.prepare_fb callback. See drm_gem_fb_prepare_fb()
  71. * and drm_gem_fb_simple_display_pipe_prepare_fb() for suitable helpers.
  72. */
  73. struct dma_fence *fence;
  74. /**
  75. * @crtc_x:
  76. *
  77. * Left position of visible portion of plane on crtc, signed dest
  78. * location allows it to be partially off screen.
  79. */
  80. int32_t crtc_x;
  81. /**
  82. * @crtc_y:
  83. *
  84. * Upper position of visible portion of plane on crtc, signed dest
  85. * location allows it to be partially off screen.
  86. */
  87. int32_t crtc_y;
  88. /** @crtc_w: width of visible portion of plane on crtc */
  89. /** @crtc_h: height of visible portion of plane on crtc */
  90. uint32_t crtc_w, crtc_h;
  91. /**
  92. * @src_x: left position of visible portion of plane within plane (in
  93. * 16.16 fixed point).
  94. */
  95. uint32_t src_x;
  96. /**
  97. * @src_y: upper position of visible portion of plane within plane (in
  98. * 16.16 fixed point).
  99. */
  100. uint32_t src_y;
  101. /** @src_w: width of visible portion of plane (in 16.16) */
  102. /** @src_h: height of visible portion of plane (in 16.16) */
  103. uint32_t src_h, src_w;
  104. /**
  105. * @alpha:
  106. * Opacity of the plane with 0 as completely transparent and 0xffff as
  107. * completely opaque. See drm_plane_create_alpha_property() for more
  108. * details.
  109. */
  110. u16 alpha;
  111. /**
  112. * @pixel_blend_mode:
  113. * The alpha blending equation selection, describing how the pixels from
  114. * the current plane are composited with the background. Value can be
  115. * one of DRM_MODE_BLEND_*
  116. */
  117. uint16_t pixel_blend_mode;
  118. /**
  119. * @rotation:
  120. * Rotation of the plane. See drm_plane_create_rotation_property() for
  121. * more details.
  122. */
  123. unsigned int rotation;
  124. /**
  125. * @zpos:
  126. * Priority of the given plane on crtc (optional).
  127. *
  128. * User-space may set mutable zpos properties so that multiple active
  129. * planes on the same CRTC have identical zpos values. This is a
  130. * user-space bug, but drivers can solve the conflict by comparing the
  131. * plane object IDs; the plane with a higher ID is stacked on top of a
  132. * plane with a lower ID.
  133. *
  134. * See drm_plane_create_zpos_property() and
  135. * drm_plane_create_zpos_immutable_property() for more details.
  136. */
  137. unsigned int zpos;
  138. /**
  139. * @normalized_zpos:
  140. * Normalized value of zpos: unique, range from 0 to N-1 where N is the
  141. * number of active planes for given crtc. Note that the driver must set
  142. * &drm_mode_config.normalize_zpos or call drm_atomic_normalize_zpos() to
  143. * update this before it can be trusted.
  144. */
  145. unsigned int normalized_zpos;
  146. /**
  147. * @color_encoding:
  148. *
  149. * Color encoding for non RGB formats
  150. */
  151. enum drm_color_encoding color_encoding;
  152. /**
  153. * @color_range:
  154. *
  155. * Color range for non RGB formats
  156. */
  157. enum drm_color_range color_range;
  158. /**
  159. * @fb_damage_clips:
  160. *
  161. * Blob representing damage (area in plane framebuffer that changed
  162. * since last plane update) as an array of &drm_mode_rect in framebuffer
  163. * coodinates of the attached framebuffer. Note that unlike plane src,
  164. * damage clips are not in 16.16 fixed point.
  165. */
  166. struct drm_property_blob *fb_damage_clips;
  167. /**
  168. * @src:
  169. *
  170. * source coordinates of the plane (in 16.16).
  171. *
  172. * When using drm_atomic_helper_check_plane_state(),
  173. * the coordinates are clipped, but the driver may choose
  174. * to use unclipped coordinates instead when the hardware
  175. * performs the clipping automatically.
  176. */
  177. /**
  178. * @dst:
  179. *
  180. * clipped destination coordinates of the plane.
  181. *
  182. * When using drm_atomic_helper_check_plane_state(),
  183. * the coordinates are clipped, but the driver may choose
  184. * to use unclipped coordinates instead when the hardware
  185. * performs the clipping automatically.
  186. */
  187. struct drm_rect src, dst;
  188. /**
  189. * @visible:
  190. *
  191. * Visibility of the plane. This can be false even if fb!=NULL and
  192. * crtc!=NULL, due to clipping.
  193. */
  194. bool visible;
  195. /**
  196. * @commit: Tracks the pending commit to prevent use-after-free conditions,
  197. * and for async plane updates.
  198. *
  199. * May be NULL.
  200. */
  201. struct drm_crtc_commit *commit;
  202. /** @state: backpointer to global drm_atomic_state */
  203. struct drm_atomic_state *state;
  204. };
  205. static inline struct drm_rect
  206. drm_plane_state_src(const struct drm_plane_state *state)
  207. {
  208. struct drm_rect src = {
  209. .x1 = state->src_x,
  210. .y1 = state->src_y,
  211. .x2 = state->src_x + state->src_w,
  212. .y2 = state->src_y + state->src_h,
  213. };
  214. return src;
  215. }
  216. static inline struct drm_rect
  217. drm_plane_state_dest(const struct drm_plane_state *state)
  218. {
  219. struct drm_rect dest = {
  220. .x1 = state->crtc_x,
  221. .y1 = state->crtc_y,
  222. .x2 = state->crtc_x + state->crtc_w,
  223. .y2 = state->crtc_y + state->crtc_h,
  224. };
  225. return dest;
  226. }
  227. /**
  228. * struct drm_plane_funcs - driver plane control functions
  229. */
  230. struct drm_plane_funcs {
  231. /**
  232. * @update_plane:
  233. *
  234. * This is the legacy entry point to enable and configure the plane for
  235. * the given CRTC and framebuffer. It is never called to disable the
  236. * plane, i.e. the passed-in crtc and fb paramters are never NULL.
  237. *
  238. * The source rectangle in frame buffer memory coordinates is given by
  239. * the src_x, src_y, src_w and src_h parameters (as 16.16 fixed point
  240. * values). Devices that don't support subpixel plane coordinates can
  241. * ignore the fractional part.
  242. *
  243. * The destination rectangle in CRTC coordinates is given by the
  244. * crtc_x, crtc_y, crtc_w and crtc_h parameters (as integer values).
  245. * Devices scale the source rectangle to the destination rectangle. If
  246. * scaling is not supported, and the source rectangle size doesn't match
  247. * the destination rectangle size, the driver must return a
  248. * -<errorname>EINVAL</errorname> error.
  249. *
  250. * Drivers implementing atomic modeset should use
  251. * drm_atomic_helper_update_plane() to implement this hook.
  252. *
  253. * RETURNS:
  254. *
  255. * 0 on success or a negative error code on failure.
  256. */
  257. int (*update_plane)(struct drm_plane *plane,
  258. struct drm_crtc *crtc, struct drm_framebuffer *fb,
  259. int crtc_x, int crtc_y,
  260. unsigned int crtc_w, unsigned int crtc_h,
  261. uint32_t src_x, uint32_t src_y,
  262. uint32_t src_w, uint32_t src_h,
  263. struct drm_modeset_acquire_ctx *ctx);
  264. /**
  265. * @disable_plane:
  266. *
  267. * This is the legacy entry point to disable the plane. The DRM core
  268. * calls this method in response to a DRM_IOCTL_MODE_SETPLANE IOCTL call
  269. * with the frame buffer ID set to 0. Disabled planes must not be
  270. * processed by the CRTC.
  271. *
  272. * Drivers implementing atomic modeset should use
  273. * drm_atomic_helper_disable_plane() to implement this hook.
  274. *
  275. * RETURNS:
  276. *
  277. * 0 on success or a negative error code on failure.
  278. */
  279. int (*disable_plane)(struct drm_plane *plane,
  280. struct drm_modeset_acquire_ctx *ctx);
  281. /**
  282. * @destroy:
  283. *
  284. * Clean up plane resources. This is only called at driver unload time
  285. * through drm_mode_config_cleanup() since a plane cannot be hotplugged
  286. * in DRM.
  287. */
  288. void (*destroy)(struct drm_plane *plane);
  289. /**
  290. * @reset:
  291. *
  292. * Reset plane hardware and software state to off. This function isn't
  293. * called by the core directly, only through drm_mode_config_reset().
  294. * It's not a helper hook only for historical reasons.
  295. *
  296. * Atomic drivers can use drm_atomic_helper_plane_reset() to reset
  297. * atomic state using this hook.
  298. */
  299. void (*reset)(struct drm_plane *plane);
  300. /**
  301. * @set_property:
  302. *
  303. * This is the legacy entry point to update a property attached to the
  304. * plane.
  305. *
  306. * This callback is optional if the driver does not support any legacy
  307. * driver-private properties. For atomic drivers it is not used because
  308. * property handling is done entirely in the DRM core.
  309. *
  310. * RETURNS:
  311. *
  312. * 0 on success or a negative error code on failure.
  313. */
  314. int (*set_property)(struct drm_plane *plane,
  315. struct drm_property *property, uint64_t val);
  316. /**
  317. * @atomic_duplicate_state:
  318. *
  319. * Duplicate the current atomic state for this plane and return it.
  320. * The core and helpers guarantee that any atomic state duplicated with
  321. * this hook and still owned by the caller (i.e. not transferred to the
  322. * driver by calling &drm_mode_config_funcs.atomic_commit) will be
  323. * cleaned up by calling the @atomic_destroy_state hook in this
  324. * structure.
  325. *
  326. * This callback is mandatory for atomic drivers.
  327. *
  328. * Atomic drivers which don't subclass &struct drm_plane_state should use
  329. * drm_atomic_helper_plane_duplicate_state(). Drivers that subclass the
  330. * state structure to extend it with driver-private state should use
  331. * __drm_atomic_helper_plane_duplicate_state() to make sure shared state is
  332. * duplicated in a consistent fashion across drivers.
  333. *
  334. * It is an error to call this hook before &drm_plane.state has been
  335. * initialized correctly.
  336. *
  337. * NOTE:
  338. *
  339. * If the duplicate state references refcounted resources this hook must
  340. * acquire a reference for each of them. The driver must release these
  341. * references again in @atomic_destroy_state.
  342. *
  343. * RETURNS:
  344. *
  345. * Duplicated atomic state or NULL when the allocation failed.
  346. */
  347. struct drm_plane_state *(*atomic_duplicate_state)(struct drm_plane *plane);
  348. /**
  349. * @atomic_destroy_state:
  350. *
  351. * Destroy a state duplicated with @atomic_duplicate_state and release
  352. * or unreference all resources it references
  353. *
  354. * This callback is mandatory for atomic drivers.
  355. */
  356. void (*atomic_destroy_state)(struct drm_plane *plane,
  357. struct drm_plane_state *state);
  358. /**
  359. * @atomic_set_property:
  360. *
  361. * Decode a driver-private property value and store the decoded value
  362. * into the passed-in state structure. Since the atomic core decodes all
  363. * standardized properties (even for extensions beyond the core set of
  364. * properties which might not be implemented by all drivers) this
  365. * requires drivers to subclass the state structure.
  366. *
  367. * Such driver-private properties should really only be implemented for
  368. * truly hardware/vendor specific state. Instead it is preferred to
  369. * standardize atomic extension and decode the properties used to expose
  370. * such an extension in the core.
  371. *
  372. * Do not call this function directly, use
  373. * drm_atomic_plane_set_property() instead.
  374. *
  375. * This callback is optional if the driver does not support any
  376. * driver-private atomic properties.
  377. *
  378. * NOTE:
  379. *
  380. * This function is called in the state assembly phase of atomic
  381. * modesets, which can be aborted for any reason (including on
  382. * userspace's request to just check whether a configuration would be
  383. * possible). Drivers MUST NOT touch any persistent state (hardware or
  384. * software) or data structures except the passed in @state parameter.
  385. *
  386. * Also since userspace controls in which order properties are set this
  387. * function must not do any input validation (since the state update is
  388. * incomplete and hence likely inconsistent). Instead any such input
  389. * validation must be done in the various atomic_check callbacks.
  390. *
  391. * RETURNS:
  392. *
  393. * 0 if the property has been found, -EINVAL if the property isn't
  394. * implemented by the driver (which shouldn't ever happen, the core only
  395. * asks for properties attached to this plane). No other validation is
  396. * allowed by the driver. The core already checks that the property
  397. * value is within the range (integer, valid enum value, ...) the driver
  398. * set when registering the property.
  399. */
  400. int (*atomic_set_property)(struct drm_plane *plane,
  401. struct drm_plane_state *state,
  402. struct drm_property *property,
  403. uint64_t val);
  404. /**
  405. * @atomic_get_property:
  406. *
  407. * Reads out the decoded driver-private property. This is used to
  408. * implement the GETPLANE IOCTL.
  409. *
  410. * Do not call this function directly, use
  411. * drm_atomic_plane_get_property() instead.
  412. *
  413. * This callback is optional if the driver does not support any
  414. * driver-private atomic properties.
  415. *
  416. * RETURNS:
  417. *
  418. * 0 on success, -EINVAL if the property isn't implemented by the
  419. * driver (which should never happen, the core only asks for
  420. * properties attached to this plane).
  421. */
  422. int (*atomic_get_property)(struct drm_plane *plane,
  423. const struct drm_plane_state *state,
  424. struct drm_property *property,
  425. uint64_t *val);
  426. /**
  427. * @late_register:
  428. *
  429. * This optional hook can be used to register additional userspace
  430. * interfaces attached to the plane like debugfs interfaces.
  431. * It is called late in the driver load sequence from drm_dev_register().
  432. * Everything added from this callback should be unregistered in
  433. * the early_unregister callback.
  434. *
  435. * Returns:
  436. *
  437. * 0 on success, or a negative error code on failure.
  438. */
  439. int (*late_register)(struct drm_plane *plane);
  440. /**
  441. * @early_unregister:
  442. *
  443. * This optional hook should be used to unregister the additional
  444. * userspace interfaces attached to the plane from
  445. * @late_register. It is called from drm_dev_unregister(),
  446. * early in the driver unload sequence to disable userspace access
  447. * before data structures are torndown.
  448. */
  449. void (*early_unregister)(struct drm_plane *plane);
  450. /**
  451. * @atomic_print_state:
  452. *
  453. * If driver subclasses &struct drm_plane_state, it should implement
  454. * this optional hook for printing additional driver specific state.
  455. *
  456. * Do not call this directly, use drm_atomic_plane_print_state()
  457. * instead.
  458. */
  459. void (*atomic_print_state)(struct drm_printer *p,
  460. const struct drm_plane_state *state);
  461. /**
  462. * @format_mod_supported:
  463. *
  464. * This optional hook is used for the DRM to determine if the given
  465. * format/modifier combination is valid for the plane. This allows the
  466. * DRM to generate the correct format bitmask (which formats apply to
  467. * which modifier), and to valdiate modifiers at atomic_check time.
  468. *
  469. * If not present, then any modifier in the plane's modifier
  470. * list is allowed with any of the plane's formats.
  471. *
  472. * Returns:
  473. *
  474. * True if the given modifier is valid for that format on the plane.
  475. * False otherwise.
  476. */
  477. bool (*format_mod_supported)(struct drm_plane *plane, uint32_t format,
  478. uint64_t modifier);
  479. };
  480. /**
  481. * enum drm_plane_type - uapi plane type enumeration
  482. *
  483. * For historical reasons not all planes are made the same. This enumeration is
  484. * used to tell the different types of planes apart to implement the different
  485. * uapi semantics for them. For userspace which is universal plane aware and
  486. * which is using that atomic IOCTL there's no difference between these planes
  487. * (beyong what the driver and hardware can support of course).
  488. *
  489. * For compatibility with legacy userspace, only overlay planes are made
  490. * available to userspace by default. Userspace clients may set the
  491. * DRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate that they
  492. * wish to receive a universal plane list containing all plane types. See also
  493. * drm_for_each_legacy_plane().
  494. *
  495. * WARNING: The values of this enum is UABI since they're exposed in the "type"
  496. * property.
  497. */
  498. enum drm_plane_type {
  499. /**
  500. * @DRM_PLANE_TYPE_OVERLAY:
  501. *
  502. * Overlay planes represent all non-primary, non-cursor planes. Some
  503. * drivers refer to these types of planes as "sprites" internally.
  504. */
  505. DRM_PLANE_TYPE_OVERLAY,
  506. /**
  507. * @DRM_PLANE_TYPE_PRIMARY:
  508. *
  509. * Primary planes represent a "main" plane for a CRTC. Primary planes
  510. * are the planes operated upon by CRTC modesetting and flipping
  511. * operations described in the &drm_crtc_funcs.page_flip and
  512. * &drm_crtc_funcs.set_config hooks.
  513. */
  514. DRM_PLANE_TYPE_PRIMARY,
  515. /**
  516. * @DRM_PLANE_TYPE_CURSOR:
  517. *
  518. * Cursor planes represent a "cursor" plane for a CRTC. Cursor planes
  519. * are the planes operated upon by the DRM_IOCTL_MODE_CURSOR and
  520. * DRM_IOCTL_MODE_CURSOR2 IOCTLs.
  521. */
  522. DRM_PLANE_TYPE_CURSOR,
  523. };
  524. /**
  525. * struct drm_plane - central DRM plane control structure
  526. *
  527. * Planes represent the scanout hardware of a display block. They receive their
  528. * input data from a &drm_framebuffer and feed it to a &drm_crtc. Planes control
  529. * the color conversion, see `Plane Composition Properties`_ for more details,
  530. * and are also involved in the color conversion of input pixels, see `Color
  531. * Management Properties`_ for details on that.
  532. */
  533. struct drm_plane {
  534. /** @dev: DRM device this plane belongs to */
  535. struct drm_device *dev;
  536. /**
  537. * @head:
  538. *
  539. * List of all planes on @dev, linked from &drm_mode_config.plane_list.
  540. * Invariant over the lifetime of @dev and therefore does not need
  541. * locking.
  542. */
  543. struct list_head head;
  544. /** @name: human readable name, can be overwritten by the driver */
  545. char *name;
  546. /**
  547. * @mutex:
  548. *
  549. * Protects modeset plane state, together with the &drm_crtc.mutex of
  550. * CRTC this plane is linked to (when active, getting activated or
  551. * getting disabled).
  552. *
  553. * For atomic drivers specifically this protects @state.
  554. */
  555. struct drm_modeset_lock mutex;
  556. /** @base: base mode object */
  557. struct drm_mode_object base;
  558. /**
  559. * @possible_crtcs: pipes this plane can be bound to constructed from
  560. * drm_crtc_mask()
  561. */
  562. uint32_t possible_crtcs;
  563. /** @format_types: array of formats supported by this plane */
  564. uint32_t *format_types;
  565. /** @format_count: Size of the array pointed at by @format_types. */
  566. unsigned int format_count;
  567. /**
  568. * @format_default: driver hasn't supplied supported formats for the
  569. * plane. Used by the drm_plane_init compatibility wrapper only.
  570. */
  571. bool format_default;
  572. /** @modifiers: array of modifiers supported by this plane */
  573. uint64_t *modifiers;
  574. /** @modifier_count: Size of the array pointed at by @modifier_count. */
  575. unsigned int modifier_count;
  576. /**
  577. * @crtc:
  578. *
  579. * Currently bound CRTC, only meaningful for non-atomic drivers. For
  580. * atomic drivers this is forced to be NULL, atomic drivers should
  581. * instead check &drm_plane_state.crtc.
  582. */
  583. struct drm_crtc *crtc;
  584. /**
  585. * @fb:
  586. *
  587. * Currently bound framebuffer, only meaningful for non-atomic drivers.
  588. * For atomic drivers this is forced to be NULL, atomic drivers should
  589. * instead check &drm_plane_state.fb.
  590. */
  591. struct drm_framebuffer *fb;
  592. /**
  593. * @old_fb:
  594. *
  595. * Temporary tracking of the old fb while a modeset is ongoing. Only
  596. * used by non-atomic drivers, forced to be NULL for atomic drivers.
  597. */
  598. struct drm_framebuffer *old_fb;
  599. /** @funcs: plane control functions */
  600. const struct drm_plane_funcs *funcs;
  601. /** @properties: property tracking for this plane */
  602. struct drm_object_properties properties;
  603. /** @type: Type of plane, see &enum drm_plane_type for details. */
  604. enum drm_plane_type type;
  605. /**
  606. * @index: Position inside the mode_config.list, can be used as an array
  607. * index. It is invariant over the lifetime of the plane.
  608. */
  609. unsigned index;
  610. /** @helper_private: mid-layer private data */
  611. const struct drm_plane_helper_funcs *helper_private;
  612. /**
  613. * @state:
  614. *
  615. * Current atomic state for this plane.
  616. *
  617. * This is protected by @mutex. Note that nonblocking atomic commits
  618. * access the current plane state without taking locks. Either by going
  619. * through the &struct drm_atomic_state pointers, see
  620. * for_each_oldnew_plane_in_state(), for_each_old_plane_in_state() and
  621. * for_each_new_plane_in_state(). Or through careful ordering of atomic
  622. * commit operations as implemented in the atomic helpers, see
  623. * &struct drm_crtc_commit.
  624. */
  625. struct drm_plane_state *state;
  626. /**
  627. * @alpha_property:
  628. * Optional alpha property for this plane. See
  629. * drm_plane_create_alpha_property().
  630. */
  631. struct drm_property *alpha_property;
  632. /**
  633. * @zpos_property:
  634. * Optional zpos property for this plane. See
  635. * drm_plane_create_zpos_property().
  636. */
  637. struct drm_property *zpos_property;
  638. /**
  639. * @rotation_property:
  640. * Optional rotation property for this plane. See
  641. * drm_plane_create_rotation_property().
  642. */
  643. struct drm_property *rotation_property;
  644. /**
  645. * @blend_mode_property:
  646. * Optional "pixel blend mode" enum property for this plane.
  647. * Blend mode property represents the alpha blending equation selection,
  648. * describing how the pixels from the current plane are composited with
  649. * the background.
  650. */
  651. struct drm_property *blend_mode_property;
  652. /**
  653. * @color_encoding_property:
  654. *
  655. * Optional "COLOR_ENCODING" enum property for specifying
  656. * color encoding for non RGB formats.
  657. * See drm_plane_create_color_properties().
  658. */
  659. struct drm_property *color_encoding_property;
  660. /**
  661. * @color_range_property:
  662. *
  663. * Optional "COLOR_RANGE" enum property for specifying
  664. * color range for non RGB formats.
  665. * See drm_plane_create_color_properties().
  666. */
  667. struct drm_property *color_range_property;
  668. };
  669. #define obj_to_plane(x) container_of(x, struct drm_plane, base)
  670. __printf(9, 10)
  671. int drm_universal_plane_init(struct drm_device *dev,
  672. struct drm_plane *plane,
  673. uint32_t possible_crtcs,
  674. const struct drm_plane_funcs *funcs,
  675. const uint32_t *formats,
  676. unsigned int format_count,
  677. const uint64_t *format_modifiers,
  678. enum drm_plane_type type,
  679. const char *name, ...);
  680. int drm_plane_init(struct drm_device *dev,
  681. struct drm_plane *plane,
  682. uint32_t possible_crtcs,
  683. const struct drm_plane_funcs *funcs,
  684. const uint32_t *formats, unsigned int format_count,
  685. bool is_primary);
  686. void drm_plane_cleanup(struct drm_plane *plane);
  687. /**
  688. * drm_plane_index - find the index of a registered plane
  689. * @plane: plane to find index for
  690. *
  691. * Given a registered plane, return the index of that plane within a DRM
  692. * device's list of planes.
  693. */
  694. static inline unsigned int drm_plane_index(const struct drm_plane *plane)
  695. {
  696. return plane->index;
  697. }
  698. /**
  699. * drm_plane_mask - find the mask of a registered plane
  700. * @plane: plane to find mask for
  701. */
  702. static inline u32 drm_plane_mask(const struct drm_plane *plane)
  703. {
  704. return 1 << drm_plane_index(plane);
  705. }
  706. struct drm_plane * drm_plane_from_index(struct drm_device *dev, int idx);
  707. void drm_plane_force_disable(struct drm_plane *plane);
  708. int drm_mode_plane_set_obj_prop(struct drm_plane *plane,
  709. struct drm_property *property,
  710. uint64_t value);
  711. /**
  712. * drm_plane_find - find a &drm_plane
  713. * @dev: DRM device
  714. * @file_priv: drm file to check for lease against.
  715. * @id: plane id
  716. *
  717. * Returns the plane with @id, NULL if it doesn't exist. Simple wrapper around
  718. * drm_mode_object_find().
  719. */
  720. static inline struct drm_plane *drm_plane_find(struct drm_device *dev,
  721. struct drm_file *file_priv,
  722. uint32_t id)
  723. {
  724. struct drm_mode_object *mo;
  725. mo = drm_mode_object_find(dev, file_priv, id, DRM_MODE_OBJECT_PLANE);
  726. return mo ? obj_to_plane(mo) : NULL;
  727. }
  728. /**
  729. * drm_for_each_plane_mask - iterate over planes specified by bitmask
  730. * @plane: the loop cursor
  731. * @dev: the DRM device
  732. * @plane_mask: bitmask of plane indices
  733. *
  734. * Iterate over all planes specified by bitmask.
  735. */
  736. #define drm_for_each_plane_mask(plane, dev, plane_mask) \
  737. list_for_each_entry((plane), &(dev)->mode_config.plane_list, head) \
  738. for_each_if ((plane_mask) & drm_plane_mask(plane))
  739. /**
  740. * drm_for_each_legacy_plane - iterate over all planes for legacy userspace
  741. * @plane: the loop cursor
  742. * @dev: the DRM device
  743. *
  744. * Iterate over all legacy planes of @dev, excluding primary and cursor planes.
  745. * This is useful for implementing userspace apis when userspace is not
  746. * universal plane aware. See also &enum drm_plane_type.
  747. */
  748. #define drm_for_each_legacy_plane(plane, dev) \
  749. list_for_each_entry(plane, &(dev)->mode_config.plane_list, head) \
  750. for_each_if (plane->type == DRM_PLANE_TYPE_OVERLAY)
  751. /**
  752. * drm_for_each_plane - iterate over all planes
  753. * @plane: the loop cursor
  754. * @dev: the DRM device
  755. *
  756. * Iterate over all planes of @dev, include primary and cursor planes.
  757. */
  758. #define drm_for_each_plane(plane, dev) \
  759. list_for_each_entry(plane, &(dev)->mode_config.plane_list, head)
  760. bool drm_any_plane_has_format(struct drm_device *dev,
  761. u32 format, u64 modifier);
  762. /**
  763. * drm_plane_get_damage_clips_count - Returns damage clips count.
  764. * @state: Plane state.
  765. *
  766. * Simple helper to get the number of &drm_mode_rect clips set by user-space
  767. * during plane update.
  768. *
  769. * Return: Number of clips in plane fb_damage_clips blob property.
  770. */
  771. static inline unsigned int
  772. drm_plane_get_damage_clips_count(const struct drm_plane_state *state)
  773. {
  774. return (state && state->fb_damage_clips) ?
  775. state->fb_damage_clips->length/sizeof(struct drm_mode_rect) : 0;
  776. }
  777. /**
  778. * drm_plane_get_damage_clips - Returns damage clips.
  779. * @state: Plane state.
  780. *
  781. * Note that this function returns uapi type &drm_mode_rect. Drivers might
  782. * instead be interested in internal &drm_rect which can be obtained by calling
  783. * drm_helper_get_plane_damage_clips().
  784. *
  785. * Return: Damage clips in plane fb_damage_clips blob property.
  786. */
  787. static inline struct drm_mode_rect *
  788. drm_plane_get_damage_clips(const struct drm_plane_state *state)
  789. {
  790. return (struct drm_mode_rect *)((state && state->fb_damage_clips) ?
  791. state->fb_damage_clips->data : NULL);
  792. }
  793. #endif