From mboxrd@z Thu Jan 1 00:00:00 1970 From: Thierry Reding Subject: Re: [RFC] drm: Start documenting userspace ABI Date: Tue, 18 Nov 2014 16:24:39 +0100 Message-ID: <20141118152438.GB19426@ulmo> References: <1416320373-18445-1-git-send-email-thierry.reding@gmail.com> <20141118142727.GD25711@phenom.ffwll.local> <20141118144006.GA18586@ulmo> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="===============0761205681==" Return-path: Received: from mail-wi0-f174.google.com (mail-wi0-f174.google.com [209.85.212.174]) by gabe.freedesktop.org (Postfix) with ESMTP id 960B66E0F2 for ; Tue, 18 Nov 2014 07:24:41 -0800 (PST) Received: by mail-wi0-f174.google.com with SMTP id h11so2204249wiw.13 for ; Tue, 18 Nov 2014 07:24:41 -0800 (PST) In-Reply-To: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" To: David Herrmann Cc: Daniel Vetter , Laurent Pinchart , "dri-devel@lists.freedesktop.org" List-Id: dri-devel@lists.freedesktop.org --===============0761205681== Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="wzJLGUyc3ArbnUjN" Content-Disposition: inline --wzJLGUyc3ArbnUjN Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Tue, Nov 18, 2014 at 04:05:08PM +0100, David Herrmann wrote: > Hi >=20 > On Tue, Nov 18, 2014 at 3:43 PM, Thierry Reding > wrote: > > On Tue, Nov 18, 2014 at 03:27:27PM +0100, Daniel Vetter wrote: > >> On Tue, Nov 18, 2014 at 03:19:33PM +0100, Thierry Reding wrote: > >> > From: Thierry Reding > >> > > >> > After seeing how the DRM_IOCTL_MODE_CREATE_DUMB was implemented with > >> > different semantics on different drivers it seems like a good idea to > >> > start to more rigorously document userspace ABI to avoid these things > >> > in the future. > >> > > >> > This is a first draft of what such documentation could look like. Not > >> > all IOCTLs are documented and some explanation about the other system > >> > calls (mmap(), poll(), read(), ...) would be good too. But I wanted = to > >> > send this out for early review to see if the direction is reasonable. > >> > If so my plan is to continue to chip away at this as I find time. > >> > > >> > Signed-off-by: Thierry Reding > >> > >> Imo for ioctls the right thing to do is having proper manpages, not > >> kerneldoc or DocBook sections. manpages really lend themselves well to > >> specify all the different facets of a single interface. > > > > I don't think I've ever seen manpages document IOCTLs at this level of > > detail. The intention of this is to add documentation about the IOCTLs > > at the kernel/userspace transition. Keeping this in the kernel has the > > advantage that it's a whole lot easier to keep updated, much like what > > we do with the other kerneldoc. > > > > That doesn't mean we shouldn't have manpages, but I think both are for > > the most part orthogonal, even though they may describe various facets > > of the same interfaces. >=20 > tty_ioctl(4) > console_ioctl(4) >=20 > I think a similar man-page ala drm_ioctl(4) makes a lot of sense. >=20 > >> Also, we already have some skeleton of that in libdrm, so I think > >> extending that would be best. > > > > One other reason why I don't think libdrm is the best fit for this is > > that libdrm is just one userspace implementation abstracting away the > > interfaces that this describes. Not everyone will use libdrm. So in my > > opinion its great if libdrm documents the API that it exposes, but I > > don't think it should document the kernel interfaces that it uses. The > > kernel exposes them, so it should provide the documentation for it as > > well. >=20 > I don't mind documenting this in the kernel-doc. But if we start > something like drm_ioctl(4) (I pushed some more generic man-pages to > libdrm a few years ago), we have this documented in 2 places, which is > always annoying for updates. I wonder if it would somehow be possible to generate manpages from the DocBook to avoid this duplication. One of the things that DRM_IOCTL_MODE_CREATE_DUMB showed is that both drivers and userspace can interpret things wrongly, and I fear that if all we have is a manpage to document the IOCTLs, people writing the drivers may not be tempted enough to read that manpage. So I think we want documentation for both driver and userspace developers. Documenting this within the kernel is also pretty easy. I know that I'll be much more tempted to do it within the kernel than if I have to switch to some other repository, build system and whatnot. Perhaps in this case having two places where it's documented isn't all that bad. It's ABI after all, so the documentation never needs to change. Theoretically. > And even if people don't use libdrm, I think it's totally acceptable > to ship man-pages with libdrm. Distributions are free to provide > drm-man-pages as stand-alone package (which is _really_ easy to > generate from libdrm). I guess one other home for these could be the man-pages project on kernel.org. It's what carries most (all?) of the Linux kernel-specific man-pages (like the tty_ioctl and console_ioctl ones that you referred to). Thierry --wzJLGUyc3ArbnUjN Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 iQIcBAEBAgAGBQJUa2S2AAoJEN0jrNd/PrOh+2QP/RFJswYygTjhGSgFwjQ7N4XO lE4W8G94o1p/ep39Oq+9IiIyIUO2lR0fVFyAOi297U6vOfHuci9KfRAlO3jkljfz OqA8Z+xLmnQhIuouGOKFg2z9ORQUuN2GqrBgVbVKUDy7lwVzxTxwiz4f828DZ7NK dOe6TIoMxl5CYIhARF3K/ghSy4wzTKgBHwQXe9XWwgd73wRXHo5WBBBqkn79nJAJ ZqJALlr+HEx58SUDCh1HTQsNURmT/Jp+ldues4pQ5XCojY2gKYRKLlvfrFLJap/h B/yOpvrO99jWU3zmiRlmTHTgGrfdZZJFmOqWiU6eEC424NmrsPt0GfmJNHuwOlBP d3k5+V+AAaUduIF5L3WpJdu5Lcm3bJXfc4OpOqvRieXtdeDWQTYicZ61mDZhy5CE ZxiN5TfdtG1RGRxgZkdJFBnn6G9cAxK4/kXfY06lLXkDrHK43Rd/kRFyzwx0zrIl KrZfwW1MZ27jDYzeI0U0JOclUmw4/LqTmZ9k/DOwAjLbtC/K4ZlLXe3F6fe0ZLvK XWceL6v8vAtW3DY7dQQY3VWW/m04BPEWlGgIAHstt+PWAiYvrJgkOC3GIQ+aVA7E 4yIefst8jXvtl7xkMimlCXVoiKEfzKQzo5Yfxgxs32csYOCFdW0v+hcTGJKHoXE+ 19JTim7gVVCZxIewK/93 =yHS1 -----END PGP SIGNATURE----- --wzJLGUyc3ArbnUjN-- --===============0761205681== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: base64 Content-Disposition: inline X19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX18KZHJpLWRldmVs IG1haWxpbmcgbGlzdApkcmktZGV2ZWxAbGlzdHMuZnJlZWRlc2t0b3Aub3JnCmh0dHA6Ly9saXN0 cy5mcmVlZGVza3RvcC5vcmcvbWFpbG1hbi9saXN0aW5mby9kcmktZGV2ZWwK --===============0761205681==--