Skip to contentSkip to conversation

Documentation requirements for drm/i915 feature work

RFC Daniel Vetter 2 participants 6 messages Mar 11, 2014 – Mar 14, 2014

lore
Share & tools
lore
#0 lore raw

Hi all,

So I guess people have seen the writing on the wall since a while ;-)

So with my latest drm kerneldoc series we'll have fairly nice interface docs for most of the still relevant drm core subsystems. Which means we can finally start to look at our own driver. I've already started with a very basic skeleton as part of my latest kerneldoc series, see

http://people.freedesktop.org/~danvet/drm/drmI915.html

Now we only need to flesh this out!

I see three areas where decent documentation provides good value:

1) High level overviews of a feature, i.e. what I've done thus far in my blog posts.

2) Detailed in-driver api documentation as kerneldoc.

3) Documentating userspace ABIs like ioctls structures&flags, properties and so on.

I have no idea how to do 3) well, see e.g. the discussion on documenting drm properties. And the drm core is completely undocumented in that area anyway afaik. So I think we can postpone this for now.

For now I want to concentrate on 1) and the essentials of 2). For the overview I think it's best to put that directly into the code as extended comments. To also have it in the DocBook we can pull it in as a "DOC:" section into a reference chapter. The overview section should explain key concepts of the feature and also mention relevant functions and interfaces. Not all of them of course, just some pointers to get the reader started with the more in-depth API documentation.

For the kerneldoc I think we should just document the important functions which are used all across the driver, or those functions which are central to the implemented code flow. Two examples:

- For the runtime pm functions all the generic get/put functions should be documented, plus maybe the core power domain structure.

- For full ppgtt the important piece is imo the overview documentation explaining vmas and surrounding concepts. Documenting the low-level platform specific ppgtt functions seems less useless. But the main vma_bind/unbind and pin/unpin functions could be used to explain some of the tricky details (like the PIN_* flags recently introduced). So that's the area I'd concentrate.

The kerneldoc must then be pulled into the DocBook next to the relevant overview section to have everything neatly tied together. The simplest way to accomplish this is to pull in all kerneldoc from a given file. Which means a sensible source code split will be even more important henceforth
- which is also why I've restructured our Makefile.

Note that the kerneldoc+DocBook tooling we have has one thing in common with every other documentation toolchain: It sucks. It sucks specifically (and imo more than necessary) in the following areas:

- DocBook is horrible, but unfortunately the only means to create tables and similar things. kerneldoc sections themselves don't really have any fancy formatting. Personally I'd love to see someone implement markdown support for it.

- There's no way to hyperlink other sections. Which sucks since people can't click onto the function names in the overview sections. It also doesn't work in any automatic fashion afaik when using DocBook directly instead of kerneldoc.

To sum my expectations about drm/i915 driver feature documentation:

1. Create a new section in the drm/i915 DocBook for your feature. Don't go deeper than sect2 - the kernel's DocBook stylesheet will not generate chapter listings for sect3 and deeper, which means no one will be able to find your function references :(

2. Write overview sections as kerneldoc directly in the code at suitable places (maybe split it up if it makes more sense) and pull this into your new DocBook section.

3. Write kerneldoc API headers for the key functions and again pull this into your new DocBook section as reference material.

Of course once we have a pile of such documentation I expect that patch series will keep them up to date.

The first two features I want to test-drive this with are full ppgtt and the rather recent runtime pm infrastructure. But this will be a general merge requirement in the future.

Comments, clarfications, ideas and general feedback highly welcome.

Cheers, Daniel

Signature · 3 lines
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch
#1 lore raw
Quoted 18 lines · On Tue, 11 Mar 2014 12:21:32 +0100 Daniel Vetter <[email protected]> wrote:

Hi all,

So I guess people have seen the writing on the wall since a while ;-)

So with my latest drm kerneldoc series we'll have fairly nice interface docs for most of the still relevant drm core subsystems. Which means we can finally start to look at our own driver. I've already started with a very basic skeleton as part of my latest kerneldoc series, see

http://people.freedesktop.org/~danvet/drm/drmI915.html

Now we only need to flesh this out!

I see three areas where decent documentation provides good value:

1) High level overviews of a feature, i.e. what I've done thus far in my blog posts.

Quoted 8 lines

2) Detailed in-driver api documentation as kerneldoc.

3) Documentating userspace ABIs like ioctls structures&flags, properties and so on.

I have no idea how to do 3) well, see e.g. the discussion on documenting drm properties. And the drm core is completely undocumented in that area anyway afaik. So I think we can postpone this for now.

IMO (3) very much belongs in libdrm as man page updates. We need to be good about catching this on review for new stuff.

For older stuff I think there was a bit of momentum awhile back, but it seems to have dissipated.

We could try to extract it from kernel source somehow, but for user API stuff, I think we really want man pages in libdrm, in addition to whatever web based documentation we make available.

Signature · 1 line
Jesse Barnes, Intel Open Source Technology Center
#2 lore raw
Quoted 10 lines · Jesse Barnes
Quoted 6 lines

3) Documentating userspace ABIs like ioctls structures&flags, properties and so on.

I have no idea how to do 3) well, see e.g. the discussion on documenting drm properties. And the drm core is completely undocumented in that area anyway afaik. So I think we can postpone this for now.

IMO (3) very much belongs in libdrm as man page updates. We need to be good about catching this on review for new stuff.

Quoted 6 lines

For older stuff I think there was a bit of momentum awhile back, but it seems to have dissipated.

We could try to extract it from kernel source somehow, but for user API stuff, I think we really want man pages in libdrm, in addition to whatever web based documentation we make available.

Yeah, I think manpages are a nice form for documenting ioctls - they more easily allow grouping of related things and the layout lends it self well for specs imo. But for now I'm ok with just the documentation we have in the form of code as igt testcases. And I also think that internal driver docs (and igt test helper library docs fwiw) are the more immediately useful areas, so I won't pour effort into ioctls docs for now.

But if someone else wants to go wild I'll happily support such an effort. -Daniel

Signature · 3 lines
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch
#3 lore raw
Quoted 26 lines · On Fri, 14 Mar 2014 19:00:46 +0100 Daniel Vetter <[email protected]> wrote:
Quoted 10 lines · Jesse Barnes
Quoted 6 lines

3) Documentating userspace ABIs like ioctls structures&flags, properties and so on.

I have no idea how to do 3) well, see e.g. the discussion on documenting drm properties. And the drm core is completely undocumented in that area anyway afaik. So I think we can postpone this for now.

IMO (3) very much belongs in libdrm as man page updates. We need to be good about catching this on review for new stuff.

Quoted 6 lines

For older stuff I think there was a bit of momentum awhile back, but it seems to have dissipated.

We could try to extract it from kernel source somehow, but for user API stuff, I think we really want man pages in libdrm, in addition to whatever web based documentation we make available.

Yeah, I think manpages are a nice form for documenting ioctls - they more easily allow grouping of related things and the layout lends it self well for specs imo. But for now I'm ok with just the documentation we have in the form of code as igt testcases. And I also think that internal driver docs (and igt test helper library docs fwiw) are the more immediately useful areas, so I won't pour effort into ioctls docs for now.

Quoted 1 line

But if someone else wants to go wild I'll happily support such an effort.

Yeah just saying a man page should be required as part of any new ioctl.

Signature · 1 line
Jesse Barnes, Intel Open Source Technology Center
#4 lore raw
Quoted 2 lines · Jesse Barnes

Yeah just saying a man page should be required as part of any new ioctl.

Yeah I agree and long-term we'll get there. Otherwise I wouldn't have added it. But imo for a documentation requirement for merging features we need a few things ready first:
a) Have a somewhat useful skeleton. For drm core Laurent made this happen and then the details (mostly api docs) have been slowly filled out over the past 1-2 years). Now we're ready to crawl into drivers.
b) Have someone with good experience with the tooling. I've written and reviewed lots of kerneldoc api patches for drm, so I think we're covered.

Those are also the reasons why I'm writing piles of igt docs just now
- we need a bit a baseline so that people have lots of examples to follow and I'm learning the tooling to figure out what works and what doesn't. For ioctls we have a bit of manpages, but only for the libdrm functions and not the ioctls themselves, and only for drm core stuff.

Hence why I think ioctl docs aren't for the masses yet. But if someone digs in and lays that groundwork and is willing to review patches a bit at the beginnning I'll happily support that by rejecting new ioctls without such docs.
-Daniel

Signature · 3 lines
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch
#5 lore raw
Quoted 20 lines · On Fri, 14 Mar 2014 19:16:01 +0100 Daniel Vetter <[email protected]> wrote:
Quoted 2 lines · Jesse Barnes

Yeah just saying a man page should be required as part of any new ioctl.

Yeah I agree and long-term we'll get there. Otherwise I wouldn't have added it. But imo for a documentation requirement for merging features we need a few things ready first:
a) Have a somewhat useful skeleton. For drm core Laurent made this happen and then the details (mostly api docs) have been slowly filled out over the past 1-2 years). Now we're ready to crawl into drivers.
b) Have someone with good experience with the tooling. I've written and reviewed lots of kerneldoc api patches for drm, so I think we're covered.

Those are also the reasons why I'm writing piles of igt docs just now
- we need a bit a baseline so that people have lots of examples to follow and I'm learning the tooling to figure out what works and what doesn't. For ioctls we have a bit of manpages, but only for the libdrm functions and not the ioctls themselves, and only for drm core stuff.

Quoted 4 lines

Hence why I think ioctl docs aren't for the masses yet. But if someone digs in and lays that groundwork and is willing to review patches a bit at the beginnning I'll happily support that by rejecting new ioctls without such docs.

We have the groundwork in libdrm already, along with a couple of pages, that's where I'd expect them to land.

Signature · 1 line
Jesse Barnes, Intel Open Source Technology Center