drm_plane.h 30 KB

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