From mboxrd@z Thu Jan 1 00:00:00 1970 From: Thierry Reding Subject: Re: [PATCH 01/28] drm: Polish fbdev helper struct docs Date: Mon, 7 Dec 2015 11:45:22 +0100 Message-ID: <20151207104522.GD13177@ulmo> References: <1449218769-16577-1-git-send-email-daniel.vetter@ffwll.ch> <1449218769-16577-2-git-send-email-daniel.vetter@ffwll.ch> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="===============1526057741==" Return-path: In-Reply-To: <1449218769-16577-2-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: Daniel Vetter , Intel Graphics Development , DRI Development List-Id: dri-devel@lists.freedesktop.org --===============1526057741== Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="mJm6k4Vb/yFcL9ZU" Content-Disposition: inline --mJm6k4Vb/yFcL9ZU Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Fri, Dec 04, 2015 at 09:45:42AM +0100, Daniel Vetter wrote: > Mostly this is just adding extensive docs for the callbacks, but also > a few other additions. >=20 > v2: Use FIXME comments to annotate helper hooks that should be > replaced. >=20 > Signed-off-by: Daniel Vetter > --- > include/drm/drm_fb_helper.h | 92 ++++++++++++++++++++++++++++++++++++++-= ------ > 1 file changed, 79 insertions(+), 13 deletions(-) >=20 > diff --git a/include/drm/drm_fb_helper.h b/include/drm/drm_fb_helper.h > index 87b090c4b730..5ce033e36039 100644 > --- a/include/drm/drm_fb_helper.h > +++ b/include/drm/drm_fb_helper.h > @@ -74,25 +74,76 @@ struct drm_fb_helper_surface_size { > =20 > /** > * struct drm_fb_helper_funcs - driver callbacks for the fbdev emulation= library > - * @gamma_set: Set the given gamma lut register on the given crtc. > - * @gamma_get: Read the given gamma lut register on the given crtc, used= to > - * save the current lut when force-restoring the fbdev for e= =2Eg. > - * kdbg. > - * @fb_probe: Driver callback to allocate and initialize the fbdev info > - * structure. Furthermore it also needs to allocate the drm > - * framebuffer used to back the fbdev. > - * @initial_config: Setup an initial fbdev display configuration > * > * Driver callbacks used by the fbdev emulation helper library. > */ > struct drm_fb_helper_funcs { > + /** > + * @gamma_set: > + * > + * Set the given gamma lut register on the given crtc. > + * > + * This callback is optional. > + * > + * FIXME: > + * > + * This callback is functionally redundant with the core gamma table > + * support and simply exists because the fbdev hasn't yet been > + * refactored to use the core gamma table interfaces. > + */ > void (*gamma_set)(struct drm_crtc *crtc, u16 red, u16 green, > u16 blue, int regno); Pardon my ignorance, but is there a way to document parameters with this new syntax? > + /** > + * @gamma_get: > + * > + * Read the given gamma lut register on the given crtc, used to save the > + * current lut when force-restoring the fbdev for e.g. kdbg. > + * > + * This callback is optional. > + * > + * FIXME: > + * > + * This callback is functionally redundant with the core gamma table > + * support and simply exists because the fbdev hasn't yet been > + * refactored to use the core gamma table interfaces. > + */ > void (*gamma_get)(struct drm_crtc *crtc, u16 *red, u16 *green, > u16 *blue, int regno); Nit: While at it, perhaps (here and in the @gamma_set documentation): s/lut/LUT/ and s/crtc/CRTC/? > =20 > + /** > + * @fb_probe: > + * > + * Driver callback to allocate and initialize the fbdev info structure. > + * Furthermore it also needs to allocate the drm framebuffer used to > + * back the fbdev. > + * > + * This callback is mandatory. > + * > + * RETURNS: > + * > + * The driver should return 0 on success and a negative error code on > + * failure. > + */ > int (*fb_probe)(struct drm_fb_helper *helper, > struct drm_fb_helper_surface_size *sizes); Nit: s/drm/DRM/ > /** > - * struct drm_fb_helper - helper to emulate fbdev on top of kms > + * struct drm_fb_helper - main structure to emulate fbdev on top of kms s/kms/KMS > * @fb: Scanout framebuffer object > * @dev: DRM device There seems to be an extra space between the : and the description. That was already there, but maybe worth a follow-up. > * @crtc_count: number of possible CRTCs > * @crtc_info: per-CRTC helper state (mode, x/y offset, etc) > * @connector_count: number of connected connectors > * @connector_info_alloc_count: size of connector_info > + * @connector_info: array of per-connector information > * @funcs: driver callbacks for fb helper > * @fbdev: emulated fbdev device info struct > * @pseudo_palette: fake palette of 16 colors > - * @kernel_fb_list: list_head in kernel_fb_helper_list > - * @delayed_hotplug: was there a hotplug while kms master active? > + * > + * This is the main structure used by the fbdev helpers. Drivers support= ing > + * fbdev emulation should embedded this into their overall driver struct= ure. > + * Drivers must also fill out a struct &drm_fb_helper_funcs with a few > + * operations. > */ > struct drm_fb_helper { > struct drm_framebuffer *fb; > @@ -129,10 +184,21 @@ struct drm_fb_helper { > const struct drm_fb_helper_funcs *funcs; > struct fb_info *fbdev; > u32 pseudo_palette[17]; > + > + /** > + * @kernel_fb_list: > + * > + * Entry on the global kernel_fb_helper_list, used for kgdb entry/exit. > + */ > struct list_head kernel_fb_list; > =20 > - /* we got a hotplug but fbdev wasn't running the console > - delay until next set_par */ > + /** > + * @delayed_hotplug: > + * > + * A hotplug was received while fbdev wasn't in control of the drm > + * device, i.e. another kms master was active. The output configuration > + * needs to be reprobe when fbdev is in control again. s/drm/DRM/, s/kms/KMS/ Otherwise looks really good. Thierry --mJm6k4Vb/yFcL9ZU Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 iQIcBAABCAAGBQJWZWNCAAoJEN0jrNd/PrOhMZgP/1Fy0qWFe3A+tHVXYy4GoOyN qGn+D4Jx0Z2etaZqtVA/Kvcx4+mmGje8jXGhMbO0HfAm9fjpjCsHAFsI8pmRv3mR lnaJ1pyL5uzx6+ZiYHAT728sEEEng5TYjsPM7bncXazZCD6srFrYWfUQCyQU7q71 EXjIxxMcYLJJZeNDdj4SyRvYirNCoc0R3SJWz86Xz9UFQsqIgYU0hOoD2EHSxOhg xtqXPjpwSqnCQ95nCprZbF5Wj8F1D1A4eSQIUlAgFh9hK6ZXmmHNnjneNGbB/mJA 5FrcTutJc/yCz6SZnIWy5G9+H7A3sqrpDP4JPOckFCLnjAFdNi/AJjqzDr8Hl0i8 BWOqMUaVZWM0tZV22TYvTsQE3qG6T1dfuRQqtrGkRNJG0cnU0xV3sSQi/t1+jHoS xEwKY4S0hqc/NxDoirkqily8N/52ykUSIn8IQztqGBkwY9vvV6IwJD9rZN0ZUz4V +XKu19a/HAa3+yTHsL988byih5lDmr41+kEJUKGhC36bzENFI6VUqXOiOIpuZgCT OFnEZ99BDIiACbTo70UUvt37rlXvP8O/7VNg2fsNOgfPhqgHoDZ1zwMIxI6+lT1G 8nTssttSn/BH2iTORK2R5IFergVV6v4tWeocXdMQUGcltA0rIPcjR1dwwMCYj5vp 2a+oYn9ykKm+hni4weyw =5EPL -----END PGP SIGNATURE----- --mJm6k4Vb/yFcL9ZU-- --===============1526057741== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: base64 Content-Disposition: inline X19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX18KZHJpLWRldmVs IG1haWxpbmcgbGlzdApkcmktZGV2ZWxAbGlzdHMuZnJlZWRlc2t0b3Aub3JnCmh0dHA6Ly9saXN0 cy5mcmVlZGVza3RvcC5vcmcvbWFpbG1hbi9saXN0aW5mby9kcmktZGV2ZWwK --===============1526057741==--