From mboxrd@z Thu Jan 1 00:00:00 1970 From: Thierry Reding Subject: Re: [PATCH 27/28] drm: Document drm_encoder/crtc_helper_funcs Date: Mon, 7 Dec 2015 16:21:43 +0100 Message-ID: <20151207152143.GH13177@ulmo> References: <1449218769-16577-1-git-send-email-daniel.vetter@ffwll.ch> <1449218769-16577-28-git-send-email-daniel.vetter@ffwll.ch> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="===============0437771479==" Return-path: In-Reply-To: <1449218769-16577-28-git-send-email-daniel.vetter@ffwll.ch> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" To: Daniel Vetter Cc: Intel Graphics Development , DRI Development List-Id: intel-gfx@lists.freedesktop.org --===============0437771479== Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="BU7+kJFeeDlNltZg" Content-Disposition: inline --BU7+kJFeeDlNltZg Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Fri, Dec 04, 2015 at 09:46:08AM +0100, Daniel Vetter wrote: > Mostly this is about all the callbacks used to modesets by both legacy "used for modesets"? > CRTC helpers and atomic helpers and I figured it doesn't make all that > much sense to split this up. >=20 > Signed-off-by: Daniel Vetter > --- > include/drm/drm_modeset_helper_vtables.h | 447 +++++++++++++++++++++++++= ++---- > 1 file changed, 400 insertions(+), 47 deletions(-) >=20 > diff --git a/include/drm/drm_modeset_helper_vtables.h b/include/drm/drm_m= odeset_helper_vtables.h > index 22cc51b278fb..d776ef6dd00e 100644 > --- a/include/drm/drm_modeset_helper_vtables.h > +++ b/include/drm/drm_modeset_helper_vtables.h > @@ -46,58 +46,236 @@ enum mode_set_atomic; > =20 > /** > * struct drm_crtc_helper_funcs - helper operations for CRTCs > - * @dpms: set power state > - * @prepare: prepare the CRTC, called before @mode_set > - * @commit: commit changes to CRTC, called after @mode_set > - * @mode_fixup: try to fixup proposed mode for this CRTC > - * @mode_set: set this mode > - * @mode_set_nofb: set mode only (no scanout buffer attached) > - * @mode_set_base: update the scanout buffer > - * @mode_set_base_atomic: non-blocking mode set (used for kgdb support) > - * @load_lut: load color palette > - * @disable: disable CRTC when no longer in use > - * @enable: enable CRTC > * > - * The helper operations are called by the mid-layer CRTC helper. > - * > - * Note that with atomic helpers @dpms, @prepare and @commit hooks are > - * deprecated. Used @enable and @disable instead exclusively. > - * > - * With legacy crtc helpers there's a big semantic difference between @d= isable > - * and the other hooks: @disable also needs to release any resources acq= uired in > - * @mode_set (like shared PLLs). > + * These hooks are used by the legacy CRTC helpers, the transitional pla= ne > + * helpers and the new atomic modesetting helpers. > */ > struct drm_crtc_helper_funcs { > - /* > - * Control power levels on the CRTC. If the mode passed in is > - * unsupported, the provider must use the next lowest power level. > + /** > + * @dpms: > + * > + * Callback to control power levels on the CRTC. If the mode passed in > + * is unsupported, the provider must use the next lowest power level. > + * This is used by the legacy CRTC helpers to implement DPMS > + * functionality in drm_helper_connector_dpms(). > + * > + * This callback is also used to disable a CRTC by calling it with > + * DRM_MODE_DPMS_OFF if the @disable hook isn't used. > + * > + * This callback is used by the legacy CRTC helpers. Atomic helpers > + * also support using this hook for enabling and disabling a CRTC to > + * facilitate transitions to atomic, but it is deprecated. Instead > + * @enable and @disable should be used. > */ > void (*dpms)(struct drm_crtc *crtc, int mode); > + > + /** > + * @prepare: > + * > + * This callback should prepare the CRTC for a subsequent modeset, which > + * in practice means the driver should disable the CRTC if it is > + * running. Most drivers ended up implementing this by calling their > + * @dpms hook with DRM_MODE_DPMS_OFF. > + * > + * This callback is used by the legacy CRTC helpers. Atomic helpers > + * also support using this hook for disabling a CRTC to facilitate > + * transitions to atomic, but it is deprecated. Instead @disable should > + * be used. > + */ > void (*prepare)(struct drm_crtc *crtc); > + > + /** > + * @commit: > + * > + * This callback should commit the new mode on the CRTC after a modeset, > + * which in practice means the driver should enable the CRTC. Most > + * drivers ended up implementing this by calling their @dpms hook with > + * DRM_MODE_DPMS_ON. > + * > + * This callback is used by the legacy CRTC helpers. Atomic helpers > + * also support using this hook for enabling a CRTC to facilitate > + * transitions to atomic, but it is deprecated. Instead @enable should > + * be used. > + */ > void (*commit)(struct drm_crtc *crtc); > =20 > - /* Provider can fixup or change mode timings before modeset occurs */ > + /** > + * @mode_fixup: > + * > + * This callback is used to validate a mode. The paramater mode is the "parameter" [...] > + /** > + * @disable: > + * > + * This callback should be used to disable the CRTC. With the atomic > + * drivers it is called after all encoders connected to this CRTC have > + * been shut off already using their own ->disable hook. If that > + * sequence is too simple drivers can just add their own hooks and call > + * it from this CRTC callback here by looping over all encoders > + * connected to it using for_each_encoder_on_crtc(). > + * > + * This hook is used both by legacy CRTC helpers and atomic helpers. > + * Atomic drivers don't need to implement it if there's no need to > + * disable anything at the CRTC level. To ensure that runtime PM > + * handling (using either DPMS or the new "ACTIVE" property) works > + * @disable must be the inversve of @enable for atomic drivers. "inverse" > + * > + * NOTE: > + * > + * With legacy CRTC helpers there's a big semantic difference between > + * @disable other hooks (like @prepare or @dpms) used to shut down a "and other hooks" > + * CRTC: @disable is only called when also logically disabling the > + * display pipeline and needs to release any resources acquired in > + * @mode_set (like shared PLLs, or again release pinned framebuffers). > + * > + * Therefore @disable must be the inverse of @mode_set plus @commit for > + * drivers still using legacy CRTC helpers, which is different from the > + * rules under atomic. > + */ > void (*disable)(struct drm_crtc *crtc); [...] > struct drm_encoder_helper_funcs { > + /** > + * @dpms: > + * > + * Callback to control power levels on the encoder. If the mode passed= in > + * is unsupported, the provider must use the next lowest power level. > + * This is used by the legacy encoder helpers to implement DPMS > + * functionality in drm_helper_connector_dpms(). > + * > + * This callback is also used to disable a encoder by calling it with "disable an encoder" > + * DRM_MODE_DPMS_OFF if the @disable hook isn't used. > + * > + * This callback is used by the legacy CRTC helpers. Atomic helpers > + * also support using this hook for enabling and disabling a encoder to > + * facilitate transitions to atomic, but it is deprecated. Instead > + * @enable and @disable should be used. > + */ > void (*dpms)(struct drm_encoder *encoder, int mode); > =20 > + /** > + * @mode_fixup: > + * > + * This callback is used to validate and adjust a mode. The paramater "parameter" > + /** > + * @disable: > + * > + * This callback should be used to disable the encoder. With the atomic > + * drivers it is called before this encoder's CRTC has been shut off > + * using the CRTC's own ->disable hook. If that sequence is too simple > + * drivers can just add their own driver private encoder hooks and call > + * them from CRTC's callback by looping over all encoders connected to > + * it using for_each_encoder_on_crtc(). > + * > + * This hook is used both by legacy CRTC helpers and atomic helpers. > + * Atomic drivers don't need to implement it if there's no need to > + * disable anything at the encoder level. To ensure that runtime PM > + * handling (using either DPMS or the new "ACTIVE" property) works > + * @disable must be the inversve of @enable for atomic drivers. "inverse" > + * > + * NOTE: > + * > + * With legacy CRTC helpers there's a big semantic difference between > + * @disable other hooks (like @prepare or @dpms) used to shut down a "and other hooks", "an encoder" > + /** > + * @enable: > + * > + * This callback should be used to enable the encoder. With the atomic > + * drivers it is called after this encoder's CRTC has been enabled using > + * the CRTC's own ->enable hook. If that sequence is too simple drivers > + * can just add their own driver private encoder hooks and call them > + * from CRTC's callback by looping over all encoders connected to it > + * using for_each_encoder_on_crtc(). > + * > + * This hook is used only by atomic helpers, for symmetry with @disable. > + * Atomic drivers don't need to implement it if there's no need to > + * enable anything at the encoder level. To ensure that runtime PM hand= ling > + * (using either DPMS or the new "ACTIVE" property) works > + * @enable must be the inversve of @disable for atomic drivers. "inverse" > + */ > void (*enable)(struct drm_encoder *encoder); > =20 > - /* atomic helpers */ > + /** > + * @atomic_check: > + * > + * This callback is used to validate encoder state for atomic drivers. > + * Since the encoder is the object connecting the CRTC and connector it > + * gets passed both states, to be able to validate interactions and > + * update the CRTC to match what the encoder needs for the requested > + * connector. > + * > + * This function is used by the atomic helpers, but it is optional. > + * > + * NOTE: > + * > + * This function is called in the check phase of an atomic update. The > + * driver is not allowed to change anything outside of the free-standing > + * state objects passed-in or assembled in the overall &drm_atomic_state > + * update tracking structure. > + * > + * RETURNS: > + * > + * 0 on success, -EINVAL if the state or the transition can't be > + * support, -ENOMEM on memory allocation failure and -EDEADLK if an "supported" Thanks for writing this up, it's great documentation. Thierry --BU7+kJFeeDlNltZg Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 iQIcBAABCAAGBQJWZaQEAAoJEN0jrNd/PrOh6AkP/2qyeJbrBCwEJmIVm7cpy5qX wTNlNk/ndT/ZfmlzhFYMUTpGij6aBRwv6cLEDaQPzmlS9AOjVLg5+l3/Nq4W+UlW 3+rlz1XOaTx5a5bCfjkCRSyshXQpAvt4wSywT5v5nnaMSHkBpPEmWS9GB1dkl0D3 d6sce4e7bXNuT48UhnZi/xM014cPIW411CFBnL15Kwkgboy3NU9sgmZctHTi8D49 3DefB43Mgg2maBqIbfA7Ee3mvCXGLhoav4BTZv/LoOK5DKh1LpfvHpWdTRGXfkkQ jLSJY3WFHuTvGHdZKsNyeVT47v6ruPWLhaJyuygAy8PzJOnb6SPsMhPJVTlpZtp2 nfer5KJ3ydiByT95J9HvcJZ8l9cqGKvfnc6duCh9cD5tUlfkVMcohWSO7qbH6YXS jXh4bhr5lTXldOLw3cg9xjsg0ZXpeVvQzzSLR1WPYOTYMYTxPeALxbS2dTstm5Bk sCFRqBjy4wQOoNasclBUoplTTt9xb1coQQstLziY3F2jZldkkVn/UVFrx3P6JZ6M CEKZ9j9iIPEwuuQjgXCLATaiSrPcr97kQzL9Kvhj8Nu4DlzOF8ZK8ODaWCzdMIgg dy2zKohVVPVIxUcYlhSGeZCIiD+9Jpw0ZPYKBzO5k1df/Y84AxRDbuhd1mPOJ32k Lq8gyO5jGK6EiNJFhwZJ =OgSk -----END PGP SIGNATURE----- --BU7+kJFeeDlNltZg-- --===============0437771479== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: base64 Content-Disposition: inline X19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX18KZHJpLWRldmVs IG1haWxpbmcgbGlzdApkcmktZGV2ZWxAbGlzdHMuZnJlZWRlc2t0b3Aub3JnCmh0dHA6Ly9saXN0 cy5mcmVlZGVza3RvcC5vcmcvbWFpbG1hbi9saXN0aW5mby9kcmktZGV2ZWwK --===============0437771479==--