From mboxrd@z Thu Jan 1 00:00:00 1970 From: Thierry Reding Subject: Re: [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers Date: Tue, 13 May 2014 11:05:37 +0200 Message-ID: <20140513090535.GM6754@ulmo> References: <1394016990-5218-1-git-send-email-sagar.a.kamble@intel.com> <2919182.UBDg5nOr7Z@avalon> <1394622965.18918.12.camel@sagar-desktop> <3136468.2PAlK4Gq8k@avalon> <20140510103937.GC18465@intel.com> <1399874873.15218.32.camel@sagar-desktop> <20140512080355.GB25056@phenom.ffwll.local> <20140513071741.GB6754@ulmo> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="===============0178369256==" Return-path: In-Reply-To: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: intel-gfx-bounces@lists.freedesktop.org Sender: "Intel-gfx" To: Daniel Vetter Cc: Laurent Pinchart , linux-doc@vger.kernel.org, intel-gfx , "Hiremath, Shashidhar" , "dri-devel@lists.freedesktop.org" , Laurent Pinchart , Rob Landley , Alex Deucher , Dave Airlie , Sagar Arun Kamble List-Id: intel-gfx@lists.freedesktop.org --===============0178369256== Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="t5NgoZwlhlUmGr82" Content-Disposition: inline --t5NgoZwlhlUmGr82 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Tue, May 13, 2014 at 09:34:45AM +0200, Daniel Vetter wrote: > On Tue, May 13, 2014 at 9:17 AM, Thierry Reding > wrote: > > On Mon, May 12, 2014 at 10:03:55AM +0200, Daniel Vetter wrote: > >> On Mon, May 12, 2014 at 11:37:53AM +0530, Sagar Arun Kamble wrote: > >> > I support approach using docbook to start since there are not lot of > >> > properties. Laurent has ack'ed this one. Can we go ahead with this? > >> > http://lists.freedesktop.org/archives/intel-gfx/2014-March/041527.ht= ml > >> > > >> > Adding description of new property is not very complex (assuming tab= le > >> > format is understood and being comfortable with HTML row/table > >> > manipulation). > >> > > >> > Adding description of each property in their source might be time > >> > consuming task. > >> > >> Yeah I'm ok with docbook for the time being. My long-term plan is to f= ix > >> up kerneldoc to support markdown and then we can move such neat tables > >> into the code. There's lots other places that would benefit from proper > >> list formatting and tables. So Ack from my side on both the docbook pa= tch > >> and the no-more-props-without-doc-patch rule (which is kinda what I've > >> been doing thus far). > > > > What happened to the proposal to add this to the Documentation/ABI > > directory? That already contains a bunch of files describing userspace > > ABI (although most of it is sysfs-related). > > > > The objection that I have to including property documentation in docbook > > is that the DRM docbook is documentation targetted at driver developers, > > but properties are userspace ABI. Therefore I think we should be using > > mechanisms that have been used to document other userspace ABI before to > > make it easier for people to find (and for consistency). > > > > One big advantage in using Documentation/ABI is that there's a fairly > > well documented process of how to add, deprecate and remove ABI. There's > > also a template that should be followed when writing these files. People > > have obviously put some thought into this before, so it would be a bit > > of a waste trying to come up with our own. > > > > The README file has some good information about all of this and I think > > it matches what we need fairly well. In particular I like the concept of > > the "Users" section, which could save us a lot of work trying to track > > potential users of crufty ABI retrospectively. >=20 > Not really sold on this, since in the end if we break userspace we > have to fix it up anyway. And all these properties are meant to be > used by userspace after all. It's precisely because they are used by userspace that I think it's a good idea to have them documented in a place where userspace developers would look for them. I don't think anyone will look at the DRM docbook because it's targetted at driver developers. That said there is a tiny section called "Userland interfaces", so perhaps adding code to that and pointing everyone at it would be an option. In which case I still think we should follow some of the same guidelines as outlined in the ABI documentation about deprecating and versioning properties. Keeping a list of known users would also be great to have in case we ever need to modify or want to remove ABI. > I think for properties it's more important to keep them all grouped > together so that if new driver writes look for something to use they > don't reinvent a slight variation of something existing again. > Documentation/ABI otoh seems to split things up per-knob, even across > stable/testing/deprecated directories. I guess that's mostly a matter of convention. We could easily add a "drm" subdirectory that contains the DRM property documentation. And in my opinion having to scan a list of file names, such as: drm-connector-property-foo drm-plane-property-bar drm-plane-property-baz isn't any more difficult than scanning the same list in docbook format. So either way people will have to know where to look and then bother to look in order for this to work. Whether it's in Documentation/ABI or docbook is irrelevant. Also there's a good reason for having the stable/testing/deprecated split. That could also give additional hints as to whether it's a good idea to add some property or not. If somebody were to add a property to their driver that's been deprecated or removed for some other driver, a look at the corresponding file should indicate why it was removed. That could be valuable in pointing people in the right direction. Similarly, if some property was documented in the stable subdirectory, that would indicate that it's been deemed ready for prime time and give more credibility. It also means that more userspace is likely to use it and therefore might be higher priority to implement in new drivers. > Also eventually I want to pull these tables directly out of source > code comments - everything else tends to never get updated when the > code changes. There are no guarantees that people will keep code comments up-to-date either. The only way you can make sure of that is by reviewing patches carefully. And if you do that, the same applies to external documentation. I agree, though, that it's slightly easier to update code comments, so if we can make this work together with some of the stricter requirements for ABI as given above I think I could be happy as well. Thierry --t5NgoZwlhlUmGr82 Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.22 (GNU/Linux) iQIcBAEBAgAGBQJTceBfAAoJEN0jrNd/PrOhKeEQAK1OWTCpiLXAgQVpep37OKZR V5JfQfHUs4OlniMsbAPYbwkfwvtjMBzqNh1iZIuzqLGQzCW0Y+oKC639Ldq2srtV dvUL7xC6XZ3LbFBuvn1LzsS3XpXZ4vAydOdRfVBr2Ag2TkOR3aS6BHRn3g5lsPEs EBvBH+g6ii83jEWzIQvBLcnc+7/citKhsOwDh7ZcvagN+0zhGNhoiDkvU9Q2x7Y3 yMxPa9AooculEiyH85BOAcCvNH/zA7CaC17C9kPPXDAe/N4iDtHYYsS0KApDvjgl 0Klxw4QA6y7lvvGWvDBCoLCGuUV24yWlnxi6A6zRZVI151lLF6XRGDOq3bZX0aMi p4nAKLaj3EniH2J9iRHKeDwXeXr4lG0YTypLvXzCiXO5x7whcrnXIxTvIfHByKIL Yi9uYTBZagTCbBN8FLfeOj7Cirvafxxzt4yFKuKPHC/gOTK3ibQCi6jmGS8r50cF vpwHiraPs9Xcuj6pSzdp5NpnU9wWQgpWNussW/hM+8MOfuXm6s6QAsqZWQJ7O+lu 3BSYIAefO1Cl06VIaRMZO2V/PnX07jIy4J3uAm/DFymL+qhmQt9F+DUxBnjXF4Mx CAytKnLmAXhHK+43aX9WAUWzVafr7BY/Iqk0xar1lYZklh8Teiwx6iJzDTIr4gx0 DnpHEEHGVPX4Zg1kZe/4 =GDav -----END PGP SIGNATURE----- --t5NgoZwlhlUmGr82-- --===============0178369256== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx --===============0178369256==--