Re: [RFC] Documentation: DRM framework documentation

[Laurent Pinchart <laurent.pinchart@ideasonboard.com>]

Hi Hans,

On Thursday 07 June 2012 11:13:30 Hans Verkuil wrote:
> Hi Laurent!
> 
> I completely missed this when you posted this a week ago, but thank you for
> doing this. One suggestion: cross-post the next version to linux-media as
> well: I think this is useful for V4L2 as well.

I didn't think it would be useful, but sure, I can do that?

> Some comments below:
> 
> On Wed 30 May 2012 15:13:29 Laurent Pinchart wrote:
> > Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> > ---
> > 
> >  Documentation/drm.txt | 1265 ++++++++++++++++++++++++++++++++++++++++++++
> >  1 files changed, 1265 insertions(+), 0 deletions(-)
> >  create mode 100644 Documentation/drm.txt
> > 
> > Hi everybody,
> > 
> > Here's the DRM kernel framework documentation I wrote while developing the
> > Renesas SH Mobile DRM driver. It hopefully covers most of what's needed to
> > write a simple DRM driver (although some areas are not documented, such as
> > properties or the fbdev compatibility layer).
> > 
> > I can convert the documentation to DocBook if needed and integrate it with
> > the existing "documentation stub". In that case I'm thinking of splitting
> > the DocBook documentation in two parts, userspace API documentation (that
> > someone would have to fill, any volunteer ? ;-)) and kernel API
> > documentation. Would that be fine ?
> > 
> > Last but not least, now that documentation exists (albeit in an incomplete
> > state), we need to make sure it won't get outdated too quickly. As nobody
> > will volunteer to maintain it (feel free to prove me wrong though), I'd
> > like to propose the same rule that we already follow in V4L: any patch
> > that touches the API won't get merged if it doesn't update the
> > documentation. Do you think this could work out ?
> 
> I strongly recommend that this policy is adopted. It is working out very
> well in V4L2. Documentation can be a pain, but if you do it when you add new
> functionality (and you still remember what it was you did :-) ), then it
> isn't too bad.

[snip]

> > +"A CRTC is an abstraction representing a part of the chip that contains a
> > +pointer to a scanout buffer.
> 
> A definition of a 'scanout buffer' would be useful here. Also: what does
> CRTC stand for?

I think it stands for cathode ray tube controller.
 
> In general, I think it would be good to explain abbreviations (DRM, GEM,
> KMS, etc.) That way the terminology is easier to understand.

Good point. I'll add a glossary.

[snip]

> Impressive work, you clearly have way too much time on your hands :-)

Thank you. I'm not sure I agree with you, having to allocate sleep time in my 
schedule isn't really a sign of having too much free time ;-)

-- 
Regards,

Laurent Pinchart