On Wed, Jun 12, 2019 at 7:40 PM Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx> wrote: > > Em Tue, 11 Jun 2019 09:37:01 -0600 > Jonathan Corbet <corbet@xxxxxxx> escreveu: > > > On Tue, 11 Jun 2019 06:02:15 -0300 > > Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx> wrote: > > > > > Jon, please correct me if I' wrong, bu I guess the plan is to place them > > > somewhere under Documentation/admin-guide/. > > > > That makes sense to me. > > > > > If so, perhaps creating a Documentation/admin-guide/drm dir there and > > > place docs like EDID/HOWTO.txt, svga.txt, etc would work. > > > > Maybe "graphics" or "display" rather than "drm", which may not entirely > > applicable to all of those docs or as familiar to all admins? > > It is up to Daniel/David to decide. Personally, I agree with you that > either "graphics" or "display" would be better at the admin guide. We use Documentation/gpu already for the developer guide, I think going with "gpu" on the admin guide for consistency would be good. I do personally think that splitting out the admin guide makes sense, we could also put some recommendations about access rights for drm device nodes and stuff like that in there. > > > Btw, that's one of the reasons[1] why I opted to keep the files where they > > > are: properly organizing the converted documents call for such kind > > > of discussions. On my experience, discussing names and directory locations > > > can generate warm discussions and take a lot of time to reach consensus. > > > > Moving docs is a pain; my life would certainly be easier if I were happy > > to just let everything lie where it fell :) But it's far from the hardest > > problem we solve in kernel development, I assume we can figure it out. > > Yeah, it is doable. I'm happy to write the rename patches and even try > to split some documents at the places I'm more familiar with, but, IMHO, > we should do some discussions before some of such renames. > > For example, Daniel said that: > > > > > Yeah atm we're doing a bad job of keeping the kapi and uapi parts > > > > separate. But the plan at least is to move all the gpu related uapi stuff > > > > into Documentation/gpu/drm-uapi.rst. Not sure there's value in moving that > > > > out of the gpu folder ... > > From the conversions I've made so far, almost all driver subsystems > put everything under Documentation/<subsystem: kAPI, uAPI, admin info, > driver-specific technical info. > > It should be doable to place kAPI and uAPI on different books, but there > will be lots of cross-reference links between them, on properly-written > docs. I'm not sure it makes sense to split out the kapi and uapi sides of the docs complete. For the admin guide I think one overall book covering all subsystems is good. But someone creating a drm/kms compositor is not going to be interested much into some special options for networking protocol I think. For those I think focusing more on the specific subsystem makes more sense (and easier to share common concepts/diagrams between uapi and kapi of a given subsystem). I do think for a given subsystem the uapi side should be clearly split out (otherwise it's impossible to find for non-kernel people). And currently drm falls short really badly on this. So maybe a good argument for a uapi kernel directory would be to force that, but not sure that's good enough of a reason. -Daniel > However, other admin-guide stuff under drivers are usually in the middle > of the documents. For example, on media, we have some at the uAPI guide, > like the Device Naming item: > > https://linuxtv.org/downloads/v4l-dvb-apis-new/uapi/v4l/open.html#device-naming > > But splitting it from uAPI guide is not an easy task. > > At the driver's specific documentation is even messier. > > Ok, splitting is doable, but require lots of dedication, and I'm not > convinced if it would make much difference in practice. > > Thanks, > Mauro -- Daniel Vetter Software Engineer, Intel Corporation +41 (0) 79 365 57 48 - http://blog.ffwll.ch
