drm_modeset_helper_vtables.h 55 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411
  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. * Copyright © 2011-2013 Intel Corporation
  7. * Copyright © 2015 Intel Corporation
  8. * Daniel Vetter <daniel.vetter@ffwll.ch>
  9. *
  10. * Permission is hereby granted, free of charge, to any person obtaining a
  11. * copy of this software and associated documentation files (the "Software"),
  12. * to deal in the Software without restriction, including without limitation
  13. * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  14. * and/or sell copies of the Software, and to permit persons to whom the
  15. * Software is furnished to do so, subject to the following conditions:
  16. *
  17. * The above copyright notice and this permission notice shall be included in
  18. * all copies or substantial portions of the Software.
  19. *
  20. * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  21. * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  22. * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  23. * THE COPYRIGHT HOLDER(S) OR AUTHOR(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR
  24. * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  25. * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  26. * OTHER DEALINGS IN THE SOFTWARE.
  27. */
  28. #ifndef __DRM_MODESET_HELPER_VTABLES_H__
  29. #define __DRM_MODESET_HELPER_VTABLES_H__
  30. #include <drm/drm_crtc.h>
  31. #include <drm/drm_encoder.h>
  32. /**
  33. * DOC: overview
  34. *
  35. * The DRM mode setting helper functions are common code for drivers to use if
  36. * they wish. Drivers are not forced to use this code in their
  37. * implementations but it would be useful if the code they do use at least
  38. * provides a consistent interface and operation to userspace. Therefore it is
  39. * highly recommended to use the provided helpers as much as possible.
  40. *
  41. * Because there is only one pointer per modeset object to hold a vfunc table
  42. * for helper libraries they are by necessity shared among the different
  43. * helpers.
  44. *
  45. * To make this clear all the helper vtables are pulled together in this location here.
  46. */
  47. enum mode_set_atomic;
  48. struct drm_writeback_connector;
  49. struct drm_writeback_job;
  50. /**
  51. * struct drm_crtc_helper_funcs - helper operations for CRTCs
  52. *
  53. * These hooks are used by the legacy CRTC helpers, the transitional plane
  54. * helpers and the new atomic modesetting helpers.
  55. */
  56. struct drm_crtc_helper_funcs {
  57. /**
  58. * @dpms:
  59. *
  60. * Callback to control power levels on the CRTC. If the mode passed in
  61. * is unsupported, the provider must use the next lowest power level.
  62. * This is used by the legacy CRTC helpers to implement DPMS
  63. * functionality in drm_helper_connector_dpms().
  64. *
  65. * This callback is also used to disable a CRTC by calling it with
  66. * DRM_MODE_DPMS_OFF if the @disable hook isn't used.
  67. *
  68. * This callback is used by the legacy CRTC helpers. Atomic helpers
  69. * also support using this hook for enabling and disabling a CRTC to
  70. * facilitate transitions to atomic, but it is deprecated. Instead
  71. * @atomic_enable and @atomic_disable should be used.
  72. */
  73. void (*dpms)(struct drm_crtc *crtc, int mode);
  74. /**
  75. * @prepare:
  76. *
  77. * This callback should prepare the CRTC for a subsequent modeset, which
  78. * in practice means the driver should disable the CRTC if it is
  79. * running. Most drivers ended up implementing this by calling their
  80. * @dpms hook with DRM_MODE_DPMS_OFF.
  81. *
  82. * This callback is used by the legacy CRTC helpers. Atomic helpers
  83. * also support using this hook for disabling a CRTC to facilitate
  84. * transitions to atomic, but it is deprecated. Instead @atomic_disable
  85. * should be used.
  86. */
  87. void (*prepare)(struct drm_crtc *crtc);
  88. /**
  89. * @commit:
  90. *
  91. * This callback should commit the new mode on the CRTC after a modeset,
  92. * which in practice means the driver should enable the CRTC. Most
  93. * drivers ended up implementing this by calling their @dpms hook with
  94. * DRM_MODE_DPMS_ON.
  95. *
  96. * This callback is used by the legacy CRTC helpers. Atomic helpers
  97. * also support using this hook for enabling a CRTC to facilitate
  98. * transitions to atomic, but it is deprecated. Instead @atomic_enable
  99. * should be used.
  100. */
  101. void (*commit)(struct drm_crtc *crtc);
  102. /**
  103. * @mode_valid:
  104. *
  105. * This callback is used to check if a specific mode is valid in this
  106. * crtc. This should be implemented if the crtc has some sort of
  107. * restriction in the modes it can display. For example, a given crtc
  108. * may be responsible to set a clock value. If the clock can not
  109. * produce all the values for the available modes then this callback
  110. * can be used to restrict the number of modes to only the ones that
  111. * can be displayed.
  112. *
  113. * This hook is used by the probe helpers to filter the mode list in
  114. * drm_helper_probe_single_connector_modes(), and it is used by the
  115. * atomic helpers to validate modes supplied by userspace in
  116. * drm_atomic_helper_check_modeset().
  117. *
  118. * This function is optional.
  119. *
  120. * NOTE:
  121. *
  122. * Since this function is both called from the check phase of an atomic
  123. * commit, and the mode validation in the probe paths it is not allowed
  124. * to look at anything else but the passed-in mode, and validate it
  125. * against configuration-invariant hardward constraints. Any further
  126. * limits which depend upon the configuration can only be checked in
  127. * @mode_fixup or @atomic_check.
  128. *
  129. * RETURNS:
  130. *
  131. * drm_mode_status Enum
  132. */
  133. enum drm_mode_status (*mode_valid)(struct drm_crtc *crtc,
  134. const struct drm_display_mode *mode);
  135. /**
  136. * @mode_fixup:
  137. *
  138. * This callback is used to validate a mode. The parameter mode is the
  139. * display mode that userspace requested, adjusted_mode is the mode the
  140. * encoders need to be fed with. Note that this is the inverse semantics
  141. * of the meaning for the &drm_encoder and &drm_bridge_funcs.mode_fixup
  142. * vfunc. If the CRTC cannot support the requested conversion from mode
  143. * to adjusted_mode it should reject the modeset. See also
  144. * &drm_crtc_state.adjusted_mode for more details.
  145. *
  146. * This function is used by both legacy CRTC helpers and atomic helpers.
  147. * With atomic helpers it is optional.
  148. *
  149. * NOTE:
  150. *
  151. * This function is called in the check phase of atomic modesets, which
  152. * can be aborted for any reason (including on userspace's request to
  153. * just check whether a configuration would be possible). Atomic drivers
  154. * MUST NOT touch any persistent state (hardware or software) or data
  155. * structures except the passed in adjusted_mode parameter.
  156. *
  157. * This is in contrast to the legacy CRTC helpers where this was
  158. * allowed.
  159. *
  160. * Atomic drivers which need to inspect and adjust more state should
  161. * instead use the @atomic_check callback, but note that they're not
  162. * perfectly equivalent: @mode_valid is called from
  163. * drm_atomic_helper_check_modeset(), but @atomic_check is called from
  164. * drm_atomic_helper_check_planes(), because originally it was meant for
  165. * plane update checks only.
  166. *
  167. * Also beware that userspace can request its own custom modes, neither
  168. * core nor helpers filter modes to the list of probe modes reported by
  169. * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure
  170. * that modes are filtered consistently put any CRTC constraints and
  171. * limits checks into @mode_valid.
  172. *
  173. * RETURNS:
  174. *
  175. * True if an acceptable configuration is possible, false if the modeset
  176. * operation should be rejected.
  177. */
  178. bool (*mode_fixup)(struct drm_crtc *crtc,
  179. const struct drm_display_mode *mode,
  180. struct drm_display_mode *adjusted_mode);
  181. /**
  182. * @mode_set:
  183. *
  184. * This callback is used by the legacy CRTC helpers to set a new mode,
  185. * position and framebuffer. Since it ties the primary plane to every
  186. * mode change it is incompatible with universal plane support. And
  187. * since it can't update other planes it's incompatible with atomic
  188. * modeset support.
  189. *
  190. * This callback is only used by CRTC helpers and deprecated.
  191. *
  192. * RETURNS:
  193. *
  194. * 0 on success or a negative error code on failure.
  195. */
  196. int (*mode_set)(struct drm_crtc *crtc, struct drm_display_mode *mode,
  197. struct drm_display_mode *adjusted_mode, int x, int y,
  198. struct drm_framebuffer *old_fb);
  199. /**
  200. * @mode_set_nofb:
  201. *
  202. * This callback is used to update the display mode of a CRTC without
  203. * changing anything of the primary plane configuration. This fits the
  204. * requirement of atomic and hence is used by the atomic helpers. It is
  205. * also used by the transitional plane helpers to implement a
  206. * @mode_set hook in drm_helper_crtc_mode_set().
  207. *
  208. * Note that the display pipe is completely off when this function is
  209. * called. Atomic drivers which need hardware to be running before they
  210. * program the new display mode (e.g. because they implement runtime PM)
  211. * should not use this hook. This is because the helper library calls
  212. * this hook only once per mode change and not every time the display
  213. * pipeline is suspended using either DPMS or the new "ACTIVE" property.
  214. * Which means register values set in this callback might get reset when
  215. * the CRTC is suspended, but not restored. Such drivers should instead
  216. * move all their CRTC setup into the @atomic_enable callback.
  217. *
  218. * This callback is optional.
  219. */
  220. void (*mode_set_nofb)(struct drm_crtc *crtc);
  221. /**
  222. * @mode_set_base:
  223. *
  224. * This callback is used by the legacy CRTC helpers to set a new
  225. * framebuffer and scanout position. It is optional and used as an
  226. * optimized fast-path instead of a full mode set operation with all the
  227. * resulting flickering. If it is not present
  228. * drm_crtc_helper_set_config() will fall back to a full modeset, using
  229. * the @mode_set callback. Since it can't update other planes it's
  230. * incompatible with atomic modeset support.
  231. *
  232. * This callback is only used by the CRTC helpers and deprecated.
  233. *
  234. * RETURNS:
  235. *
  236. * 0 on success or a negative error code on failure.
  237. */
  238. int (*mode_set_base)(struct drm_crtc *crtc, int x, int y,
  239. struct drm_framebuffer *old_fb);
  240. /**
  241. * @mode_set_base_atomic:
  242. *
  243. * This callback is used by the fbdev helpers to set a new framebuffer
  244. * and scanout without sleeping, i.e. from an atomic calling context. It
  245. * is only used to implement kgdb support.
  246. *
  247. * This callback is optional and only needed for kgdb support in the fbdev
  248. * helpers.
  249. *
  250. * RETURNS:
  251. *
  252. * 0 on success or a negative error code on failure.
  253. */
  254. int (*mode_set_base_atomic)(struct drm_crtc *crtc,
  255. struct drm_framebuffer *fb, int x, int y,
  256. enum mode_set_atomic);
  257. /**
  258. * @disable:
  259. *
  260. * This callback should be used to disable the CRTC. With the atomic
  261. * drivers it is called after all encoders connected to this CRTC have
  262. * been shut off already using their own
  263. * &drm_encoder_helper_funcs.disable hook. If that sequence is too
  264. * simple drivers can just add their own hooks and call it from this
  265. * CRTC callback here by looping over all encoders connected to it using
  266. * for_each_encoder_on_crtc().
  267. *
  268. * This hook is used both by legacy CRTC helpers and atomic helpers.
  269. * Atomic drivers don't need to implement it if there's no need to
  270. * disable anything at the CRTC level. To ensure that runtime PM
  271. * handling (using either DPMS or the new "ACTIVE" property) works
  272. * @disable must be the inverse of @atomic_enable for atomic drivers.
  273. * Atomic drivers should consider to use @atomic_disable instead of
  274. * this one.
  275. *
  276. * NOTE:
  277. *
  278. * With legacy CRTC helpers there's a big semantic difference between
  279. * @disable and other hooks (like @prepare or @dpms) used to shut down a
  280. * CRTC: @disable is only called when also logically disabling the
  281. * display pipeline and needs to release any resources acquired in
  282. * @mode_set (like shared PLLs, or again release pinned framebuffers).
  283. *
  284. * Therefore @disable must be the inverse of @mode_set plus @commit for
  285. * drivers still using legacy CRTC helpers, which is different from the
  286. * rules under atomic.
  287. */
  288. void (*disable)(struct drm_crtc *crtc);
  289. /**
  290. * @atomic_check:
  291. *
  292. * Drivers should check plane-update related CRTC constraints in this
  293. * hook. They can also check mode related limitations but need to be
  294. * aware of the calling order, since this hook is used by
  295. * drm_atomic_helper_check_planes() whereas the preparations needed to
  296. * check output routing and the display mode is done in
  297. * drm_atomic_helper_check_modeset(). Therefore drivers that want to
  298. * check output routing and display mode constraints in this callback
  299. * must ensure that drm_atomic_helper_check_modeset() has been called
  300. * beforehand. This is calling order used by the default helper
  301. * implementation in drm_atomic_helper_check().
  302. *
  303. * When using drm_atomic_helper_check_planes() this hook is called
  304. * after the &drm_plane_helper_funcs.atomic_check hook for planes, which
  305. * allows drivers to assign shared resources requested by planes in this
  306. * callback here. For more complicated dependencies the driver can call
  307. * the provided check helpers multiple times until the computed state
  308. * has a final configuration and everything has been checked.
  309. *
  310. * This function is also allowed to inspect any other object's state and
  311. * can add more state objects to the atomic commit if needed. Care must
  312. * be taken though to ensure that state check and compute functions for
  313. * these added states are all called, and derived state in other objects
  314. * all updated. Again the recommendation is to just call check helpers
  315. * until a maximal configuration is reached.
  316. *
  317. * This callback is used by the atomic modeset helpers and by the
  318. * transitional plane helpers, but it is optional.
  319. *
  320. * NOTE:
  321. *
  322. * This function is called in the check phase of an atomic update. The
  323. * driver is not allowed to change anything outside of the free-standing
  324. * state objects passed-in or assembled in the overall &drm_atomic_state
  325. * update tracking structure.
  326. *
  327. * Also beware that userspace can request its own custom modes, neither
  328. * core nor helpers filter modes to the list of probe modes reported by
  329. * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure
  330. * that modes are filtered consistently put any CRTC constraints and
  331. * limits checks into @mode_valid.
  332. *
  333. * RETURNS:
  334. *
  335. * 0 on success, -EINVAL if the state or the transition can't be
  336. * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
  337. * attempt to obtain another state object ran into a &drm_modeset_lock
  338. * deadlock.
  339. */
  340. int (*atomic_check)(struct drm_crtc *crtc,
  341. struct drm_crtc_state *state);
  342. /**
  343. * @atomic_begin:
  344. *
  345. * Drivers should prepare for an atomic update of multiple planes on
  346. * a CRTC in this hook. Depending upon hardware this might be vblank
  347. * evasion, blocking updates by setting bits or doing preparatory work
  348. * for e.g. manual update display.
  349. *
  350. * This hook is called before any plane commit functions are called.
  351. *
  352. * Note that the power state of the display pipe when this function is
  353. * called depends upon the exact helpers and calling sequence the driver
  354. * has picked. See drm_atomic_helper_commit_planes() for a discussion of
  355. * the tradeoffs and variants of plane commit helpers.
  356. *
  357. * This callback is used by the atomic modeset helpers and by the
  358. * transitional plane helpers, but it is optional.
  359. */
  360. void (*atomic_begin)(struct drm_crtc *crtc,
  361. struct drm_crtc_state *old_crtc_state);
  362. /**
  363. * @atomic_flush:
  364. *
  365. * Drivers should finalize an atomic update of multiple planes on
  366. * a CRTC in this hook. Depending upon hardware this might include
  367. * checking that vblank evasion was successful, unblocking updates by
  368. * setting bits or setting the GO bit to flush out all updates.
  369. *
  370. * Simple hardware or hardware with special requirements can commit and
  371. * flush out all updates for all planes from this hook and forgo all the
  372. * other commit hooks for plane updates.
  373. *
  374. * This hook is called after any plane commit functions are called.
  375. *
  376. * Note that the power state of the display pipe when this function is
  377. * called depends upon the exact helpers and calling sequence the driver
  378. * has picked. See drm_atomic_helper_commit_planes() for a discussion of
  379. * the tradeoffs and variants of plane commit helpers.
  380. *
  381. * This callback is used by the atomic modeset helpers and by the
  382. * transitional plane helpers, but it is optional.
  383. */
  384. void (*atomic_flush)(struct drm_crtc *crtc,
  385. struct drm_crtc_state *old_crtc_state);
  386. /**
  387. * @atomic_enable:
  388. *
  389. * This callback should be used to enable the CRTC. With the atomic
  390. * drivers it is called before all encoders connected to this CRTC are
  391. * enabled through the encoder's own &drm_encoder_helper_funcs.enable
  392. * hook. If that sequence is too simple drivers can just add their own
  393. * hooks and call it from this CRTC callback here by looping over all
  394. * encoders connected to it using for_each_encoder_on_crtc().
  395. *
  396. * This hook is used only by atomic helpers, for symmetry with
  397. * @atomic_disable. Atomic drivers don't need to implement it if there's
  398. * no need to enable anything at the CRTC level. To ensure that runtime
  399. * PM handling (using either DPMS or the new "ACTIVE" property) works
  400. * @atomic_enable must be the inverse of @atomic_disable for atomic
  401. * drivers.
  402. *
  403. * Drivers can use the @old_crtc_state input parameter if the operations
  404. * needed to enable the CRTC don't depend solely on the new state but
  405. * also on the transition between the old state and the new state.
  406. *
  407. * This function is optional.
  408. */
  409. void (*atomic_enable)(struct drm_crtc *crtc,
  410. struct drm_crtc_state *old_crtc_state);
  411. /**
  412. * @atomic_disable:
  413. *
  414. * This callback should be used to disable the CRTC. With the atomic
  415. * drivers it is called after all encoders connected to this CRTC have
  416. * been shut off already using their own
  417. * &drm_encoder_helper_funcs.disable hook. If that sequence is too
  418. * simple drivers can just add their own hooks and call it from this
  419. * CRTC callback here by looping over all encoders connected to it using
  420. * for_each_encoder_on_crtc().
  421. *
  422. * This hook is used only by atomic helpers. Atomic drivers don't
  423. * need to implement it if there's no need to disable anything at the
  424. * CRTC level.
  425. *
  426. * Comparing to @disable, this one provides the additional input
  427. * parameter @old_crtc_state which could be used to access the old
  428. * state. Atomic drivers should consider to use this one instead
  429. * of @disable.
  430. *
  431. * This function is optional.
  432. */
  433. void (*atomic_disable)(struct drm_crtc *crtc,
  434. struct drm_crtc_state *old_crtc_state);
  435. /**
  436. * @get_scanout_position:
  437. *
  438. * Called by vblank timestamping code.
  439. *
  440. * Returns the current display scanout position from a CRTC and an
  441. * optional accurate ktime_get() timestamp of when the position was
  442. * measured. Note that this is a helper callback which is only used
  443. * if a driver uses drm_crtc_vblank_helper_get_vblank_timestamp()
  444. * for the @drm_crtc_funcs.get_vblank_timestamp callback.
  445. *
  446. * Parameters:
  447. *
  448. * crtc:
  449. * The CRTC.
  450. * in_vblank_irq:
  451. * True when called from drm_crtc_handle_vblank(). Some drivers
  452. * need to apply some workarounds for gpu-specific vblank irq
  453. * quirks if the flag is set.
  454. * vpos:
  455. * Target location for current vertical scanout position.
  456. * hpos:
  457. * Target location for current horizontal scanout position.
  458. * stime:
  459. * Target location for timestamp taken immediately before
  460. * scanout position query. Can be NULL to skip timestamp.
  461. * etime:
  462. * Target location for timestamp taken immediately after
  463. * scanout position query. Can be NULL to skip timestamp.
  464. * mode:
  465. * Current display timings.
  466. *
  467. * Returns vpos as a positive number while in active scanout area.
  468. * Returns vpos as a negative number inside vblank, counting the number
  469. * of scanlines to go until end of vblank, e.g., -1 means "one scanline
  470. * until start of active scanout / end of vblank."
  471. *
  472. * Returns:
  473. *
  474. * True on success, false if a reliable scanout position counter could
  475. * not be read out.
  476. */
  477. bool (*get_scanout_position)(struct drm_crtc *crtc,
  478. bool in_vblank_irq, int *vpos, int *hpos,
  479. ktime_t *stime, ktime_t *etime,
  480. const struct drm_display_mode *mode);
  481. };
  482. /**
  483. * drm_crtc_helper_add - sets the helper vtable for a crtc
  484. * @crtc: DRM CRTC
  485. * @funcs: helper vtable to set for @crtc
  486. */
  487. static inline void drm_crtc_helper_add(struct drm_crtc *crtc,
  488. const struct drm_crtc_helper_funcs *funcs)
  489. {
  490. crtc->helper_private = funcs;
  491. }
  492. /**
  493. * struct drm_encoder_helper_funcs - helper operations for encoders
  494. *
  495. * These hooks are used by the legacy CRTC helpers, the transitional plane
  496. * helpers and the new atomic modesetting helpers.
  497. */
  498. struct drm_encoder_helper_funcs {
  499. /**
  500. * @dpms:
  501. *
  502. * Callback to control power levels on the encoder. If the mode passed in
  503. * is unsupported, the provider must use the next lowest power level.
  504. * This is used by the legacy encoder helpers to implement DPMS
  505. * functionality in drm_helper_connector_dpms().
  506. *
  507. * This callback is also used to disable an encoder by calling it with
  508. * DRM_MODE_DPMS_OFF if the @disable hook isn't used.
  509. *
  510. * This callback is used by the legacy CRTC helpers. Atomic helpers
  511. * also support using this hook for enabling and disabling an encoder to
  512. * facilitate transitions to atomic, but it is deprecated. Instead
  513. * @enable and @disable should be used.
  514. */
  515. void (*dpms)(struct drm_encoder *encoder, int mode);
  516. /**
  517. * @mode_valid:
  518. *
  519. * This callback is used to check if a specific mode is valid in this
  520. * encoder. This should be implemented if the encoder has some sort
  521. * of restriction in the modes it can display. For example, a given
  522. * encoder may be responsible to set a clock value. If the clock can
  523. * not produce all the values for the available modes then this callback
  524. * can be used to restrict the number of modes to only the ones that
  525. * can be displayed.
  526. *
  527. * This hook is used by the probe helpers to filter the mode list in
  528. * drm_helper_probe_single_connector_modes(), and it is used by the
  529. * atomic helpers to validate modes supplied by userspace in
  530. * drm_atomic_helper_check_modeset().
  531. *
  532. * This function is optional.
  533. *
  534. * NOTE:
  535. *
  536. * Since this function is both called from the check phase of an atomic
  537. * commit, and the mode validation in the probe paths it is not allowed
  538. * to look at anything else but the passed-in mode, and validate it
  539. * against configuration-invariant hardward constraints. Any further
  540. * limits which depend upon the configuration can only be checked in
  541. * @mode_fixup or @atomic_check.
  542. *
  543. * RETURNS:
  544. *
  545. * drm_mode_status Enum
  546. */
  547. enum drm_mode_status (*mode_valid)(struct drm_encoder *crtc,
  548. const struct drm_display_mode *mode);
  549. /**
  550. * @mode_fixup:
  551. *
  552. * This callback is used to validate and adjust a mode. The parameter
  553. * mode is the display mode that should be fed to the next element in
  554. * the display chain, either the final &drm_connector or a &drm_bridge.
  555. * The parameter adjusted_mode is the input mode the encoder requires. It
  556. * can be modified by this callback and does not need to match mode. See
  557. * also &drm_crtc_state.adjusted_mode for more details.
  558. *
  559. * This function is used by both legacy CRTC helpers and atomic helpers.
  560. * This hook is optional.
  561. *
  562. * NOTE:
  563. *
  564. * This function is called in the check phase of atomic modesets, which
  565. * can be aborted for any reason (including on userspace's request to
  566. * just check whether a configuration would be possible). Atomic drivers
  567. * MUST NOT touch any persistent state (hardware or software) or data
  568. * structures except the passed in adjusted_mode parameter.
  569. *
  570. * This is in contrast to the legacy CRTC helpers where this was
  571. * allowed.
  572. *
  573. * Atomic drivers which need to inspect and adjust more state should
  574. * instead use the @atomic_check callback. If @atomic_check is used,
  575. * this hook isn't called since @atomic_check allows a strict superset
  576. * of the functionality of @mode_fixup.
  577. *
  578. * Also beware that userspace can request its own custom modes, neither
  579. * core nor helpers filter modes to the list of probe modes reported by
  580. * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure
  581. * that modes are filtered consistently put any encoder constraints and
  582. * limits checks into @mode_valid.
  583. *
  584. * RETURNS:
  585. *
  586. * True if an acceptable configuration is possible, false if the modeset
  587. * operation should be rejected.
  588. */
  589. bool (*mode_fixup)(struct drm_encoder *encoder,
  590. const struct drm_display_mode *mode,
  591. struct drm_display_mode *adjusted_mode);
  592. /**
  593. * @prepare:
  594. *
  595. * This callback should prepare the encoder for a subsequent modeset,
  596. * which in practice means the driver should disable the encoder if it
  597. * is running. Most drivers ended up implementing this by calling their
  598. * @dpms hook with DRM_MODE_DPMS_OFF.
  599. *
  600. * This callback is used by the legacy CRTC helpers. Atomic helpers
  601. * also support using this hook for disabling an encoder to facilitate
  602. * transitions to atomic, but it is deprecated. Instead @disable should
  603. * be used.
  604. */
  605. void (*prepare)(struct drm_encoder *encoder);
  606. /**
  607. * @commit:
  608. *
  609. * This callback should commit the new mode on the encoder after a modeset,
  610. * which in practice means the driver should enable the encoder. Most
  611. * drivers ended up implementing this by calling their @dpms hook with
  612. * DRM_MODE_DPMS_ON.
  613. *
  614. * This callback is used by the legacy CRTC helpers. Atomic helpers
  615. * also support using this hook for enabling an encoder to facilitate
  616. * transitions to atomic, but it is deprecated. Instead @enable should
  617. * be used.
  618. */
  619. void (*commit)(struct drm_encoder *encoder);
  620. /**
  621. * @mode_set:
  622. *
  623. * This callback is used to update the display mode of an encoder.
  624. *
  625. * Note that the display pipe is completely off when this function is
  626. * called. Drivers which need hardware to be running before they program
  627. * the new display mode (because they implement runtime PM) should not
  628. * use this hook, because the helper library calls it only once and not
  629. * every time the display pipeline is suspend using either DPMS or the
  630. * new "ACTIVE" property. Such drivers should instead move all their
  631. * encoder setup into the @enable callback.
  632. *
  633. * This callback is used both by the legacy CRTC helpers and the atomic
  634. * modeset helpers. It is optional in the atomic helpers.
  635. *
  636. * NOTE:
  637. *
  638. * If the driver uses the atomic modeset helpers and needs to inspect
  639. * the connector state or connector display info during mode setting,
  640. * @atomic_mode_set can be used instead.
  641. */
  642. void (*mode_set)(struct drm_encoder *encoder,
  643. struct drm_display_mode *mode,
  644. struct drm_display_mode *adjusted_mode);
  645. /**
  646. * @atomic_mode_set:
  647. *
  648. * This callback is used to update the display mode of an encoder.
  649. *
  650. * Note that the display pipe is completely off when this function is
  651. * called. Drivers which need hardware to be running before they program
  652. * the new display mode (because they implement runtime PM) should not
  653. * use this hook, because the helper library calls it only once and not
  654. * every time the display pipeline is suspended using either DPMS or the
  655. * new "ACTIVE" property. Such drivers should instead move all their
  656. * encoder setup into the @enable callback.
  657. *
  658. * This callback is used by the atomic modeset helpers in place of the
  659. * @mode_set callback, if set by the driver. It is optional and should
  660. * be used instead of @mode_set if the driver needs to inspect the
  661. * connector state or display info, since there is no direct way to
  662. * go from the encoder to the current connector.
  663. */
  664. void (*atomic_mode_set)(struct drm_encoder *encoder,
  665. struct drm_crtc_state *crtc_state,
  666. struct drm_connector_state *conn_state);
  667. /**
  668. * @detect:
  669. *
  670. * This callback can be used by drivers who want to do detection on the
  671. * encoder object instead of in connector functions.
  672. *
  673. * It is not used by any helper and therefore has purely driver-specific
  674. * semantics. New drivers shouldn't use this and instead just implement
  675. * their own private callbacks.
  676. *
  677. * FIXME:
  678. *
  679. * This should just be converted into a pile of driver vfuncs.
  680. * Currently radeon, amdgpu and nouveau are using it.
  681. */
  682. enum drm_connector_status (*detect)(struct drm_encoder *encoder,
  683. struct drm_connector *connector);
  684. /**
  685. * @atomic_disable:
  686. *
  687. * This callback should be used to disable the encoder. With the atomic
  688. * drivers it is called before this encoder's CRTC has been shut off
  689. * using their own &drm_crtc_helper_funcs.atomic_disable hook. If that
  690. * sequence is too simple drivers can just add their own driver private
  691. * encoder hooks and call them from CRTC's callback by looping over all
  692. * encoders connected to it using for_each_encoder_on_crtc().
  693. *
  694. * This callback is a variant of @disable that provides the atomic state
  695. * to the driver. If @atomic_disable is implemented, @disable is not
  696. * called by the helpers.
  697. *
  698. * This hook is only used by atomic helpers. Atomic drivers don't need
  699. * to implement it if there's no need to disable anything at the encoder
  700. * level. To ensure that runtime PM handling (using either DPMS or the
  701. * new "ACTIVE" property) works @atomic_disable must be the inverse of
  702. * @atomic_enable.
  703. */
  704. void (*atomic_disable)(struct drm_encoder *encoder,
  705. struct drm_atomic_state *state);
  706. /**
  707. * @atomic_enable:
  708. *
  709. * This callback should be used to enable the encoder. It is called
  710. * after this encoder's CRTC has been enabled using their own
  711. * &drm_crtc_helper_funcs.atomic_enable hook. If that sequence is
  712. * too simple drivers can just add their own driver private encoder
  713. * hooks and call them from CRTC's callback by looping over all encoders
  714. * connected to it using for_each_encoder_on_crtc().
  715. *
  716. * This callback is a variant of @enable that provides the atomic state
  717. * to the driver. If @atomic_enable is implemented, @enable is not
  718. * called by the helpers.
  719. *
  720. * This hook is only used by atomic helpers, it is the opposite of
  721. * @atomic_disable. Atomic drivers don't need to implement it if there's
  722. * no need to enable anything at the encoder level. To ensure that
  723. * runtime PM handling works @atomic_enable must be the inverse of
  724. * @atomic_disable.
  725. */
  726. void (*atomic_enable)(struct drm_encoder *encoder,
  727. struct drm_atomic_state *state);
  728. /**
  729. * @disable:
  730. *
  731. * This callback should be used to disable the encoder. With the atomic
  732. * drivers it is called before this encoder's CRTC has been shut off
  733. * using their own &drm_crtc_helper_funcs.disable hook. If that
  734. * sequence is too simple drivers can just add their own driver private
  735. * encoder hooks and call them from CRTC's callback by looping over all
  736. * encoders connected to it using for_each_encoder_on_crtc().
  737. *
  738. * This hook is used both by legacy CRTC helpers and atomic helpers.
  739. * Atomic drivers don't need to implement it if there's no need to
  740. * disable anything at the encoder level. To ensure that runtime PM
  741. * handling (using either DPMS or the new "ACTIVE" property) works
  742. * @disable must be the inverse of @enable for atomic drivers.
  743. *
  744. * For atomic drivers also consider @atomic_disable and save yourself
  745. * from having to read the NOTE below!
  746. *
  747. * NOTE:
  748. *
  749. * With legacy CRTC helpers there's a big semantic difference between
  750. * @disable and other hooks (like @prepare or @dpms) used to shut down a
  751. * encoder: @disable is only called when also logically disabling the
  752. * display pipeline and needs to release any resources acquired in
  753. * @mode_set (like shared PLLs, or again release pinned framebuffers).
  754. *
  755. * Therefore @disable must be the inverse of @mode_set plus @commit for
  756. * drivers still using legacy CRTC helpers, which is different from the
  757. * rules under atomic.
  758. */
  759. void (*disable)(struct drm_encoder *encoder);
  760. /**
  761. * @enable:
  762. *
  763. * This callback should be used to enable the encoder. With the atomic
  764. * drivers it is called after this encoder's CRTC has been enabled using
  765. * their own &drm_crtc_helper_funcs.enable hook. If that sequence is
  766. * too simple drivers can just add their own driver private encoder
  767. * hooks and call them from CRTC's callback by looping over all encoders
  768. * connected to it using for_each_encoder_on_crtc().
  769. *
  770. * This hook is only used by atomic helpers, it is the opposite of
  771. * @disable. Atomic drivers don't need to implement it if there's no
  772. * need to enable anything at the encoder level. To ensure that
  773. * runtime PM handling (using either DPMS or the new "ACTIVE" property)
  774. * works @enable must be the inverse of @disable for atomic drivers.
  775. */
  776. void (*enable)(struct drm_encoder *encoder);
  777. /**
  778. * @atomic_check:
  779. *
  780. * This callback is used to validate encoder state for atomic drivers.
  781. * Since the encoder is the object connecting the CRTC and connector it
  782. * gets passed both states, to be able to validate interactions and
  783. * update the CRTC to match what the encoder needs for the requested
  784. * connector.
  785. *
  786. * Since this provides a strict superset of the functionality of
  787. * @mode_fixup (the requested and adjusted modes are both available
  788. * through the passed in &struct drm_crtc_state) @mode_fixup is not
  789. * called when @atomic_check is implemented.
  790. *
  791. * This function is used by the atomic helpers, but it is optional.
  792. *
  793. * NOTE:
  794. *
  795. * This function is called in the check phase of an atomic update. The
  796. * driver is not allowed to change anything outside of the free-standing
  797. * state objects passed-in or assembled in the overall &drm_atomic_state
  798. * update tracking structure.
  799. *
  800. * Also beware that userspace can request its own custom modes, neither
  801. * core nor helpers filter modes to the list of probe modes reported by
  802. * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure
  803. * that modes are filtered consistently put any encoder constraints and
  804. * limits checks into @mode_valid.
  805. *
  806. * RETURNS:
  807. *
  808. * 0 on success, -EINVAL if the state or the transition can't be
  809. * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
  810. * attempt to obtain another state object ran into a &drm_modeset_lock
  811. * deadlock.
  812. */
  813. int (*atomic_check)(struct drm_encoder *encoder,
  814. struct drm_crtc_state *crtc_state,
  815. struct drm_connector_state *conn_state);
  816. };
  817. /**
  818. * drm_encoder_helper_add - sets the helper vtable for an encoder
  819. * @encoder: DRM encoder
  820. * @funcs: helper vtable to set for @encoder
  821. */
  822. static inline void drm_encoder_helper_add(struct drm_encoder *encoder,
  823. const struct drm_encoder_helper_funcs *funcs)
  824. {
  825. encoder->helper_private = funcs;
  826. }
  827. /**
  828. * struct drm_connector_helper_funcs - helper operations for connectors
  829. *
  830. * These functions are used by the atomic and legacy modeset helpers and by the
  831. * probe helpers.
  832. */
  833. struct drm_connector_helper_funcs {
  834. /**
  835. * @get_modes:
  836. *
  837. * This function should fill in all modes currently valid for the sink
  838. * into the &drm_connector.probed_modes list. It should also update the
  839. * EDID property by calling drm_connector_update_edid_property().
  840. *
  841. * The usual way to implement this is to cache the EDID retrieved in the
  842. * probe callback somewhere in the driver-private connector structure.
  843. * In this function drivers then parse the modes in the EDID and add
  844. * them by calling drm_add_edid_modes(). But connectors that driver a
  845. * fixed panel can also manually add specific modes using
  846. * drm_mode_probed_add(). Drivers which manually add modes should also
  847. * make sure that the &drm_connector.display_info,
  848. * &drm_connector.width_mm and &drm_connector.height_mm fields are
  849. * filled in.
  850. *
  851. * Virtual drivers that just want some standard VESA mode with a given
  852. * resolution can call drm_add_modes_noedid(), and mark the preferred
  853. * one using drm_set_preferred_mode().
  854. *
  855. * This function is only called after the @detect hook has indicated
  856. * that a sink is connected and when the EDID isn't overridden through
  857. * sysfs or the kernel commandline.
  858. *
  859. * This callback is used by the probe helpers in e.g.
  860. * drm_helper_probe_single_connector_modes().
  861. *
  862. * To avoid races with concurrent connector state updates, the helper
  863. * libraries always call this with the &drm_mode_config.connection_mutex
  864. * held. Because of this it's safe to inspect &drm_connector->state.
  865. *
  866. * RETURNS:
  867. *
  868. * The number of modes added by calling drm_mode_probed_add().
  869. */
  870. int (*get_modes)(struct drm_connector *connector);
  871. /**
  872. * @detect_ctx:
  873. *
  874. * Check to see if anything is attached to the connector. The parameter
  875. * force is set to false whilst polling, true when checking the
  876. * connector due to a user request. force can be used by the driver to
  877. * avoid expensive, destructive operations during automated probing.
  878. *
  879. * This callback is optional, if not implemented the connector will be
  880. * considered as always being attached.
  881. *
  882. * This is the atomic version of &drm_connector_funcs.detect.
  883. *
  884. * To avoid races against concurrent connector state updates, the
  885. * helper libraries always call this with ctx set to a valid context,
  886. * and &drm_mode_config.connection_mutex will always be locked with
  887. * the ctx parameter set to this ctx. This allows taking additional
  888. * locks as required.
  889. *
  890. * RETURNS:
  891. *
  892. * &drm_connector_status indicating the connector's status,
  893. * or the error code returned by drm_modeset_lock(), -EDEADLK.
  894. */
  895. int (*detect_ctx)(struct drm_connector *connector,
  896. struct drm_modeset_acquire_ctx *ctx,
  897. bool force);
  898. /**
  899. * @mode_valid:
  900. *
  901. * Callback to validate a mode for a connector, irrespective of the
  902. * specific display configuration.
  903. *
  904. * This callback is used by the probe helpers to filter the mode list
  905. * (which is usually derived from the EDID data block from the sink).
  906. * See e.g. drm_helper_probe_single_connector_modes().
  907. *
  908. * This function is optional.
  909. *
  910. * NOTE:
  911. *
  912. * This only filters the mode list supplied to userspace in the
  913. * GETCONNECTOR IOCTL. Compared to &drm_encoder_helper_funcs.mode_valid,
  914. * &drm_crtc_helper_funcs.mode_valid and &drm_bridge_funcs.mode_valid,
  915. * which are also called by the atomic helpers from
  916. * drm_atomic_helper_check_modeset(). This allows userspace to force and
  917. * ignore sink constraint (like the pixel clock limits in the screen's
  918. * EDID), which is useful for e.g. testing, or working around a broken
  919. * EDID. Any source hardware constraint (which always need to be
  920. * enforced) therefore should be checked in one of the above callbacks,
  921. * and not this one here.
  922. *
  923. * To avoid races with concurrent connector state updates, the helper
  924. * libraries always call this with the &drm_mode_config.connection_mutex
  925. * held. Because of this it's safe to inspect &drm_connector->state.
  926. *
  927. * RETURNS:
  928. *
  929. * Either &drm_mode_status.MODE_OK or one of the failure reasons in &enum
  930. * drm_mode_status.
  931. */
  932. enum drm_mode_status (*mode_valid)(struct drm_connector *connector,
  933. struct drm_display_mode *mode);
  934. /**
  935. * @mode_valid_ctx:
  936. *
  937. * Callback to validate a mode for a connector, irrespective of the
  938. * specific display configuration.
  939. *
  940. * This callback is used by the probe helpers to filter the mode list
  941. * (which is usually derived from the EDID data block from the sink).
  942. * See e.g. drm_helper_probe_single_connector_modes().
  943. *
  944. * This function is optional, and is the atomic version of
  945. * &drm_connector_helper_funcs.mode_valid.
  946. *
  947. * To allow for accessing the atomic state of modesetting objects, the
  948. * helper libraries always call this with ctx set to a valid context,
  949. * and &drm_mode_config.connection_mutex will always be locked with
  950. * the ctx parameter set to @ctx. This allows for taking additional
  951. * locks as required.
  952. *
  953. * Even though additional locks may be acquired, this callback is
  954. * still expected not to take any constraints into account which would
  955. * be influenced by the currently set display state - such constraints
  956. * should be handled in the driver's atomic check. For example, if a
  957. * connector shares display bandwidth with other connectors then it
  958. * would be ok to validate the minimum bandwidth requirement of a mode
  959. * against the maximum possible bandwidth of the connector. But it
  960. * wouldn't be ok to take the current bandwidth usage of other
  961. * connectors into account, as this would change depending on the
  962. * display state.
  963. *
  964. * Returns:
  965. * 0 if &drm_connector_helper_funcs.mode_valid_ctx succeeded and wrote
  966. * the &enum drm_mode_status value to @status, or a negative error
  967. * code otherwise.
  968. *
  969. */
  970. int (*mode_valid_ctx)(struct drm_connector *connector,
  971. struct drm_display_mode *mode,
  972. struct drm_modeset_acquire_ctx *ctx,
  973. enum drm_mode_status *status);
  974. /**
  975. * @best_encoder:
  976. *
  977. * This function should select the best encoder for the given connector.
  978. *
  979. * This function is used by both the atomic helpers (in the
  980. * drm_atomic_helper_check_modeset() function) and in the legacy CRTC
  981. * helpers.
  982. *
  983. * NOTE:
  984. *
  985. * In atomic drivers this function is called in the check phase of an
  986. * atomic update. The driver is not allowed to change or inspect
  987. * anything outside of arguments passed-in. Atomic drivers which need to
  988. * inspect dynamic configuration state should instead use
  989. * @atomic_best_encoder.
  990. *
  991. * You can leave this function to NULL if the connector is only
  992. * attached to a single encoder. In this case, the core will call
  993. * drm_connector_get_single_encoder() for you.
  994. *
  995. * RETURNS:
  996. *
  997. * Encoder that should be used for the given connector and connector
  998. * state, or NULL if no suitable encoder exists. Note that the helpers
  999. * will ensure that encoders aren't used twice, drivers should not check
  1000. * for this.
  1001. */
  1002. struct drm_encoder *(*best_encoder)(struct drm_connector *connector);
  1003. /**
  1004. * @atomic_best_encoder:
  1005. *
  1006. * This is the atomic version of @best_encoder for atomic drivers which
  1007. * need to select the best encoder depending upon the desired
  1008. * configuration and can't select it statically.
  1009. *
  1010. * This function is used by drm_atomic_helper_check_modeset().
  1011. * If it is not implemented, the core will fallback to @best_encoder
  1012. * (or drm_connector_get_single_encoder() if @best_encoder is NULL).
  1013. *
  1014. * NOTE:
  1015. *
  1016. * This function is called in the check phase of an atomic update. The
  1017. * driver is not allowed to change anything outside of the free-standing
  1018. * state objects passed-in or assembled in the overall &drm_atomic_state
  1019. * update tracking structure.
  1020. *
  1021. * RETURNS:
  1022. *
  1023. * Encoder that should be used for the given connector and connector
  1024. * state, or NULL if no suitable encoder exists. Note that the helpers
  1025. * will ensure that encoders aren't used twice, drivers should not check
  1026. * for this.
  1027. */
  1028. struct drm_encoder *(*atomic_best_encoder)(struct drm_connector *connector,
  1029. struct drm_connector_state *connector_state);
  1030. /**
  1031. * @atomic_check:
  1032. *
  1033. * This hook is used to validate connector state. This function is
  1034. * called from &drm_atomic_helper_check_modeset, and is called when
  1035. * a connector property is set, or a modeset on the crtc is forced.
  1036. *
  1037. * Because &drm_atomic_helper_check_modeset may be called multiple times,
  1038. * this function should handle being called multiple times as well.
  1039. *
  1040. * This function is also allowed to inspect any other object's state and
  1041. * can add more state objects to the atomic commit if needed. Care must
  1042. * be taken though to ensure that state check and compute functions for
  1043. * these added states are all called, and derived state in other objects
  1044. * all updated. Again the recommendation is to just call check helpers
  1045. * until a maximal configuration is reached.
  1046. *
  1047. * NOTE:
  1048. *
  1049. * This function is called in the check phase of an atomic update. The
  1050. * driver is not allowed to change anything outside of the free-standing
  1051. * state objects passed-in or assembled in the overall &drm_atomic_state
  1052. * update tracking structure.
  1053. *
  1054. * RETURNS:
  1055. *
  1056. * 0 on success, -EINVAL if the state or the transition can't be
  1057. * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
  1058. * attempt to obtain another state object ran into a &drm_modeset_lock
  1059. * deadlock.
  1060. */
  1061. int (*atomic_check)(struct drm_connector *connector,
  1062. struct drm_atomic_state *state);
  1063. /**
  1064. * @atomic_commit:
  1065. *
  1066. * This hook is to be used by drivers implementing writeback connectors
  1067. * that need a point when to commit the writeback job to the hardware.
  1068. * The writeback_job to commit is available in
  1069. * &drm_connector_state.writeback_job.
  1070. *
  1071. * This hook is optional.
  1072. *
  1073. * This callback is used by the atomic modeset helpers.
  1074. */
  1075. void (*atomic_commit)(struct drm_connector *connector,
  1076. struct drm_connector_state *state);
  1077. /**
  1078. * @prepare_writeback_job:
  1079. *
  1080. * As writeback jobs contain a framebuffer, drivers may need to
  1081. * prepare and clean them up the same way they can prepare and
  1082. * clean up framebuffers for planes. This optional connector operation
  1083. * is used to support the preparation of writeback jobs. The job
  1084. * prepare operation is called from drm_atomic_helper_prepare_planes()
  1085. * for struct &drm_writeback_connector connectors only.
  1086. *
  1087. * This operation is optional.
  1088. *
  1089. * This callback is used by the atomic modeset helpers.
  1090. */
  1091. int (*prepare_writeback_job)(struct drm_writeback_connector *connector,
  1092. struct drm_writeback_job *job);
  1093. /**
  1094. * @cleanup_writeback_job:
  1095. *
  1096. * This optional connector operation is used to support the
  1097. * cleanup of writeback jobs. The job cleanup operation is called
  1098. * from the existing drm_writeback_cleanup_job() function, invoked
  1099. * both when destroying the job as part of an aborted commit, or when
  1100. * the job completes.
  1101. *
  1102. * This operation is optional.
  1103. *
  1104. * This callback is used by the atomic modeset helpers.
  1105. */
  1106. void (*cleanup_writeback_job)(struct drm_writeback_connector *connector,
  1107. struct drm_writeback_job *job);
  1108. };
  1109. /**
  1110. * drm_connector_helper_add - sets the helper vtable for a connector
  1111. * @connector: DRM connector
  1112. * @funcs: helper vtable to set for @connector
  1113. */
  1114. static inline void drm_connector_helper_add(struct drm_connector *connector,
  1115. const struct drm_connector_helper_funcs *funcs)
  1116. {
  1117. connector->helper_private = funcs;
  1118. }
  1119. /**
  1120. * struct drm_plane_helper_funcs - helper operations for planes
  1121. *
  1122. * These functions are used by the atomic helpers and by the transitional plane
  1123. * helpers.
  1124. */
  1125. struct drm_plane_helper_funcs {
  1126. /**
  1127. * @prepare_fb:
  1128. *
  1129. * This hook is to prepare a framebuffer for scanout by e.g. pinning
  1130. * its backing storage or relocating it into a contiguous block of
  1131. * VRAM. Other possible preparatory work includes flushing caches.
  1132. *
  1133. * This function must not block for outstanding rendering, since it is
  1134. * called in the context of the atomic IOCTL even for async commits to
  1135. * be able to return any errors to userspace. Instead the recommended
  1136. * way is to fill out the &drm_plane_state.fence of the passed-in
  1137. * &drm_plane_state. If the driver doesn't support native fences then
  1138. * equivalent functionality should be implemented through private
  1139. * members in the plane structure.
  1140. *
  1141. * Drivers which always have their buffers pinned should use
  1142. * drm_gem_fb_prepare_fb() for this hook.
  1143. *
  1144. * The helpers will call @cleanup_fb with matching arguments for every
  1145. * successful call to this hook.
  1146. *
  1147. * This callback is used by the atomic modeset helpers and by the
  1148. * transitional plane helpers, but it is optional.
  1149. *
  1150. * RETURNS:
  1151. *
  1152. * 0 on success or one of the following negative error codes allowed by
  1153. * the &drm_mode_config_funcs.atomic_commit vfunc. When using helpers
  1154. * this callback is the only one which can fail an atomic commit,
  1155. * everything else must complete successfully.
  1156. */
  1157. int (*prepare_fb)(struct drm_plane *plane,
  1158. struct drm_plane_state *new_state);
  1159. /**
  1160. * @cleanup_fb:
  1161. *
  1162. * This hook is called to clean up any resources allocated for the given
  1163. * framebuffer and plane configuration in @prepare_fb.
  1164. *
  1165. * This callback is used by the atomic modeset helpers and by the
  1166. * transitional plane helpers, but it is optional.
  1167. */
  1168. void (*cleanup_fb)(struct drm_plane *plane,
  1169. struct drm_plane_state *old_state);
  1170. /**
  1171. * @atomic_check:
  1172. *
  1173. * Drivers should check plane specific constraints in this hook.
  1174. *
  1175. * When using drm_atomic_helper_check_planes() plane's @atomic_check
  1176. * hooks are called before the ones for CRTCs, which allows drivers to
  1177. * request shared resources that the CRTC controls here. For more
  1178. * complicated dependencies the driver can call the provided check helpers
  1179. * multiple times until the computed state has a final configuration and
  1180. * everything has been checked.
  1181. *
  1182. * This function is also allowed to inspect any other object's state and
  1183. * can add more state objects to the atomic commit if needed. Care must
  1184. * be taken though to ensure that state check and compute functions for
  1185. * these added states are all called, and derived state in other objects
  1186. * all updated. Again the recommendation is to just call check helpers
  1187. * until a maximal configuration is reached.
  1188. *
  1189. * This callback is used by the atomic modeset helpers and by the
  1190. * transitional plane helpers, but it is optional.
  1191. *
  1192. * NOTE:
  1193. *
  1194. * This function is called in the check phase of an atomic update. The
  1195. * driver is not allowed to change anything outside of the free-standing
  1196. * state objects passed-in or assembled in the overall &drm_atomic_state
  1197. * update tracking structure.
  1198. *
  1199. * RETURNS:
  1200. *
  1201. * 0 on success, -EINVAL if the state or the transition can't be
  1202. * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
  1203. * attempt to obtain another state object ran into a &drm_modeset_lock
  1204. * deadlock.
  1205. */
  1206. int (*atomic_check)(struct drm_plane *plane,
  1207. struct drm_plane_state *state);
  1208. /**
  1209. * @atomic_update:
  1210. *
  1211. * Drivers should use this function to update the plane state. This
  1212. * hook is called in-between the &drm_crtc_helper_funcs.atomic_begin and
  1213. * drm_crtc_helper_funcs.atomic_flush callbacks.
  1214. *
  1215. * Note that the power state of the display pipe when this function is
  1216. * called depends upon the exact helpers and calling sequence the driver
  1217. * has picked. See drm_atomic_helper_commit_planes() for a discussion of
  1218. * the tradeoffs and variants of plane commit helpers.
  1219. *
  1220. * This callback is used by the atomic modeset helpers and by the
  1221. * transitional plane helpers, but it is optional.
  1222. */
  1223. void (*atomic_update)(struct drm_plane *plane,
  1224. struct drm_plane_state *old_state);
  1225. /**
  1226. * @atomic_disable:
  1227. *
  1228. * Drivers should use this function to unconditionally disable a plane.
  1229. * This hook is called in-between the
  1230. * &drm_crtc_helper_funcs.atomic_begin and
  1231. * drm_crtc_helper_funcs.atomic_flush callbacks. It is an alternative to
  1232. * @atomic_update, which will be called for disabling planes, too, if
  1233. * the @atomic_disable hook isn't implemented.
  1234. *
  1235. * This hook is also useful to disable planes in preparation of a modeset,
  1236. * by calling drm_atomic_helper_disable_planes_on_crtc() from the
  1237. * &drm_crtc_helper_funcs.disable hook.
  1238. *
  1239. * Note that the power state of the display pipe when this function is
  1240. * called depends upon the exact helpers and calling sequence the driver
  1241. * has picked. See drm_atomic_helper_commit_planes() for a discussion of
  1242. * the tradeoffs and variants of plane commit helpers.
  1243. *
  1244. * This callback is used by the atomic modeset helpers and by the
  1245. * transitional plane helpers, but it is optional.
  1246. */
  1247. void (*atomic_disable)(struct drm_plane *plane,
  1248. struct drm_plane_state *old_state);
  1249. /**
  1250. * @atomic_async_check:
  1251. *
  1252. * Drivers should set this function pointer to check if the plane state
  1253. * can be updated in a async fashion. Here async means "not vblank
  1254. * synchronized".
  1255. *
  1256. * This hook is called by drm_atomic_async_check() to establish if a
  1257. * given update can be committed asynchronously, that is, if it can
  1258. * jump ahead of the state currently queued for update.
  1259. *
  1260. * RETURNS:
  1261. *
  1262. * Return 0 on success and any error returned indicates that the update
  1263. * can not be applied in asynchronous manner.
  1264. */
  1265. int (*atomic_async_check)(struct drm_plane *plane,
  1266. struct drm_plane_state *state);
  1267. /**
  1268. * @atomic_async_update:
  1269. *
  1270. * Drivers should set this function pointer to perform asynchronous
  1271. * updates of planes, that is, jump ahead of the currently queued
  1272. * state and update the plane. Here async means "not vblank
  1273. * synchronized".
  1274. *
  1275. * This hook is called by drm_atomic_helper_async_commit().
  1276. *
  1277. * An async update will happen on legacy cursor updates. An async
  1278. * update won't happen if there is an outstanding commit modifying
  1279. * the same plane.
  1280. *
  1281. * Note that unlike &drm_plane_helper_funcs.atomic_update this hook
  1282. * takes the new &drm_plane_state as parameter. When doing async_update
  1283. * drivers shouldn't replace the &drm_plane_state but update the
  1284. * current one with the new plane configurations in the new
  1285. * plane_state.
  1286. *
  1287. * Drivers should also swap the framebuffers between current plane
  1288. * state (&drm_plane.state) and new_state.
  1289. * This is required since cleanup for async commits is performed on
  1290. * the new state, rather than old state like for traditional commits.
  1291. * Since we want to give up the reference on the current (old) fb
  1292. * instead of our brand new one, swap them in the driver during the
  1293. * async commit.
  1294. *
  1295. * FIXME:
  1296. * - It only works for single plane updates
  1297. * - Async Pageflips are not supported yet
  1298. * - Some hw might still scan out the old buffer until the next
  1299. * vblank, however we let go of the fb references as soon as
  1300. * we run this hook. For now drivers must implement their own workers
  1301. * for deferring if needed, until a common solution is created.
  1302. */
  1303. void (*atomic_async_update)(struct drm_plane *plane,
  1304. struct drm_plane_state *new_state);
  1305. };
  1306. /**
  1307. * drm_plane_helper_add - sets the helper vtable for a plane
  1308. * @plane: DRM plane
  1309. * @funcs: helper vtable to set for @plane
  1310. */
  1311. static inline void drm_plane_helper_add(struct drm_plane *plane,
  1312. const struct drm_plane_helper_funcs *funcs)
  1313. {
  1314. plane->helper_private = funcs;
  1315. }
  1316. /**
  1317. * struct drm_mode_config_helper_funcs - global modeset helper operations
  1318. *
  1319. * These helper functions are used by the atomic helpers.
  1320. */
  1321. struct drm_mode_config_helper_funcs {
  1322. /**
  1323. * @atomic_commit_tail:
  1324. *
  1325. * This hook is used by the default atomic_commit() hook implemented in
  1326. * drm_atomic_helper_commit() together with the nonblocking commit
  1327. * helpers (see drm_atomic_helper_setup_commit() for a starting point)
  1328. * to implement blocking and nonblocking commits easily. It is not used
  1329. * by the atomic helpers
  1330. *
  1331. * This function is called when the new atomic state has already been
  1332. * swapped into the various state pointers. The passed in state
  1333. * therefore contains copies of the old/previous state. This hook should
  1334. * commit the new state into hardware. Note that the helpers have
  1335. * already waited for preceeding atomic commits and fences, but drivers
  1336. * can add more waiting calls at the start of their implementation, e.g.
  1337. * to wait for driver-internal request for implicit syncing, before
  1338. * starting to commit the update to the hardware.
  1339. *
  1340. * After the atomic update is committed to the hardware this hook needs
  1341. * to call drm_atomic_helper_commit_hw_done(). Then wait for the upate
  1342. * to be executed by the hardware, for example using
  1343. * drm_atomic_helper_wait_for_vblanks() or
  1344. * drm_atomic_helper_wait_for_flip_done(), and then clean up the old
  1345. * framebuffers using drm_atomic_helper_cleanup_planes().
  1346. *
  1347. * When disabling a CRTC this hook _must_ stall for the commit to
  1348. * complete. Vblank waits don't work on disabled CRTC, hence the core
  1349. * can't take care of this. And it also can't rely on the vblank event,
  1350. * since that can be signalled already when the screen shows black,
  1351. * which can happen much earlier than the last hardware access needed to
  1352. * shut off the display pipeline completely.
  1353. *
  1354. * This hook is optional, the default implementation is
  1355. * drm_atomic_helper_commit_tail().
  1356. */
  1357. void (*atomic_commit_tail)(struct drm_atomic_state *state);
  1358. };
  1359. #endif