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 15:43:43 +0100 Message-ID: <20141118144006.GA18586@ulmo> References: <1416320373-18445-1-git-send-email-thierry.reding@gmail.com> <20141118142727.GD25711@phenom.ffwll.local> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="===============1510063833==" Return-path: Received: from mail-wg0-f54.google.com (mail-wg0-f54.google.com [74.125.82.54]) by gabe.freedesktop.org (Postfix) with ESMTP id 742726E4F7 for ; Tue, 18 Nov 2014 06:43:47 -0800 (PST) Received: by mail-wg0-f54.google.com with SMTP id y10so6271845wgg.13 for ; Tue, 18 Nov 2014 06:43:46 -0800 (PST) In-Reply-To: <20141118142727.GD25711@phenom.ffwll.local> 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 , Laurent Pinchart , dri-devel@lists.freedesktop.org List-Id: dri-devel@lists.freedesktop.org --===============1510063833== Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="s/l3CgOIzMHHjg/5" Content-Disposition: inline --s/l3CgOIzMHHjg/5 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable 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 > >=20 > > 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. > >=20 > > 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. > >=20 > > Signed-off-by: Thierry Reding >=20 > 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. > 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. Thierry --s/l3CgOIzMHHjg/5 Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 iQIcBAEBAgAGBQJUa1scAAoJEN0jrNd/PrOh+fEP/0ElcDfi7SKPGoC9XTqENnnb gcaic6If16X06smxfW6v4s8Z+mgZ+aV1SSYsGtkarzwxSx8PLnBcaJJK6fm4Nk+m D1W8tM+PgKN2QRqL2Ho8wU4K3sgxhaclPsnsXXH3IWjl6lLm3eyS5TH2JGaVxd5F js+EuAw2jeO51/q5ue+r7CmeiyNUypkcvJk0C5LGioZAFbhZVF1QJ6l8xFaE+cPF mcKOugnDAdU/POAbg2RxpbeHB247/+0VMGXM7CeM4qI4z06pwm9mJFq5QIiViwOB W8E2o4zetFTGoUJryWCILCbtjWr42dYHpzYiXVAeZxVjKoIjKaJP6ValTF8epHpm AJKY6rbygbsJk7U9uMmTh7uXxn7lBMPaTYcq24SabZt87RUqVnCVm48cSffz5n9m VEaBi0NmyZ3fZqsT4hsjPpsC8R/b/SlqwQ3Jn1IXI9/jn5q8hSDEvK9YeAphRFgG QMUENzFt42g4be7LR4hrUWi0ZKQ4ba9B2LqSZMrojxDvJPD1W1QYK4Ua5jg9HtPH ZVpEGK8A6t5SZTFk8jSG0IfObz+/apId4Qy69HDQd2XtsJwMzKLnArlYDZkovwbf dFSHiqtX5L2vwoX/LMbLZtR7PdWztUqeqZzzzqra+yjykepM4uxLurwMZ2HSkUaR bpMv1hOtsoTB2uGuqRdB =4cLe -----END PGP SIGNATURE----- --s/l3CgOIzMHHjg/5-- --===============1510063833== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: base64 Content-Disposition: inline X19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX18KZHJpLWRldmVs IG1haWxpbmcgbGlzdApkcmktZGV2ZWxAbGlzdHMuZnJlZWRlc2t0b3Aub3JnCmh0dHA6Ly9saXN0 cy5mcmVlZGVza3RvcC5vcmcvbWFpbG1hbi9saXN0aW5mby9kcmktZGV2ZWwK --===============1510063833==--