On Tue, Aug 23, 2016 at 08:16:33AM -0600, Jonathan Corbet wrote: > On Tue, 23 Aug 2016 15:28:55 +0200 > Daniel Vetter <dan...@ffwll.ch> wrote: > > > I think the more interesting story is, what's your plan with all the > > other driver related subsystem? Especially the ones which already have > > full directories of their own, like e.g. Documentation/gpio/. I think > > those should be really part of the infrastructure section (or > > something equally high-level), together with other awesome servies > > like pwm, regman, irqchip, ... And then there's also the large-scale > > subsystems like media or gpu. What's the plan to tie them all > > together? Personally I'm leaning towards keeping the existing > > directories (where they exist already), but inserting links into the > > overall driver-api section. > > To say I have a plan is to overstate things somewhat... > > One objective I do have, though, is to declutter Documentation/. > Presenting people looking for docs with a 270-file directory is > unfriendly to say the least. We don't organize the code that way; the > average in the kernel is <... find | wc -l ... > about 15 > files/directory, which is rather more manageable. Someday I'd like > Documentation/ to look a lot more like the top-level directory. > > It seems to me that we have a few basic types of stuff here: > > - Driver API documentation, obviously, is a lot of it, and I would like > to organize it better and to move it out of the top-level directory. > > - Hardware usage information - module parameters, sysfs files, supported > hardware information, graphic descriptions of the ancestry of hardware > engineers, etc. The readership for this stuff is quite different, and > I think it should be separate; often it's intertwined with API > information at the moment. > > - Other usage information - a lot of what's under filesystems/ for > example, and more.
Hm yeah, I don't have a plan really for what to do with usage docs for users (as opposed to api docs for kernel developers). With DRM comparatively few people end up writing userspace for our apis, hence I think this is a lower priority issue for us. Definitely something I'd like to address eventually. I think for drivers a big part here is documenting the ioctls and all the other uapi bits&pieces. > - Core API documentation. Personally I'm very much interesting in dragging all the locking primitives into the rst/sphinx world. We already make heavy use fo ww_mutex, and we started to make rather heavy use of rcu in drm and drm/i915. I'd like to be able to directly reference these underlying primitives. For KS I'll try to convince Paul that this is an awesome idea ;-) > - Kernel development tools - the stuff I started pulling together into > the dev-tools/ subdirectory. > > - How to deal with this unruly mob - SubmittingPatches, CodingStyle, > development-process, etc. There's process stuff, and general > development documents like volatile-considered-harmful.txt or > memory-barriers.txt tbh I think the process stuff is important enough that we should imo leave it in the top-level Documentation/ directory. Maybe collated together into a contributing.rst index file (besides the top-level index.rst ofc). > We can go a long way by organizing this stuff within the formatted > documentation, but I really think we need to organize the directory > structure as well. I see that as a slow-moving process that will take > years, but I do think it's a direction we should go. Fully agreed on the larger-scale picture, and I think what I've seen thus far from you looks great. Was simply wondering whether you have a more concrete plane for drivers specifically already. I'm wondering whether we should have Documentation/drivers/(gpu|media|...) too, but otoh nesting things too deeply isn't great either. Starting out with a proper driver directory in there is definitely the right step forward though. We can shuffle the other bits into that later on anytime we like really. -Daniel -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch
