Message-ID: <20200307102028.539b7fc5@onda.lan>
Date:   Sat, 7 Mar 2020 10:20:28 +0100
From:   Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To:     Jonathan Corbet <corbet@....net>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        linux-kernel@...r.kernel.org, linux-media@...r.kernel.org
Subject: Re: [PATCH RFC 0/2] Move media uAPI and kAPI docs to a better place

Em Fri, 6 Mar 2020 15:48:53 -0700
Jonathan Corbet <corbet@....net> escreveu:

> On Wed,  4 Mar 2020 11:51:01 +0100
> Mauro Carvalho Chehab <mchehab+huawei@...nel.org> wrote:
> 
> > This is something that you always wanted: move uAPI and kAPI to
> > separate books.  
> 
> Oh goodie...Christmas is coming early this year...:)

:-)

> 
> > This RFC series start doing it for the media docs.
> > 
> > For now, this is just a RFC, being only an initial step for it. I'm sending
> > it on this early stage just to rise some discussions.
> > 
> > This changeset basically moves:
> > 
> >   - the media kAPI files to be under driver-api/media;
> >   - the media uAPI files to be under userspace-api/media.
> > 
> > This version keeps including both inside Documentation/media/index.rst.  
> 
> The moves make sense to me.  The including part I'm not so sure about.  It
> seems kind of strange to have the structure of the rendered docs be
> different from that of the plain-text docs; it suggests that one of the two
> placements is wrong.
> 
> My own choice (as you suggest later) would be to keep the structure the
> same in both domains, and to use cross-references to create paths where
> they are needed.

Ok. So, I would keep a Documentation/media/index.rst that will just
have cross-references for the documentation elsewhere, right?

Makes sense to me.

> 
> > The driver-specific information is messy, as each file there may contain
> > either one or more of the following items:
> > 
> > 	- driver-development information;
> > 	- on a few drivers, drivers-specific uAPI.
> > 	- modprobe parameters;
> > 	- List of devices supported by each driver;
> > 
> > The last two are probably contents for the admin-guide, but not sure
> > where to place driver-specific development information. Does it
> > belong to "driver-api" book too?
> > 
> > I guess that driver-specific uAPI could fit at the userspace-api, but I
> > don't want them to be at the same place as the core media API stuff.
> > 
> > Suggestions?  
> 
> That is a good question.  I've wondered for a bit if we need a separate
> hardware manual for documentation specific to a given device.  In cases
> like this, it could perhaps consist mostly of cross-references to the
> relevant documentation in the other manuals.  

There are a large number of Kernel drivers (not only on media) that have
"hardware manuals" inside Documentation.

-

Btw, I finished yesterday the split:

	https://git.linuxtv.org/mchehab/experimental.git/log/?h=media-docs

So, we can now see more concrete examples about how such change would
like.

I still intend to add some cross-references and toadd some extra entries at
MAINTAINERS for the newer files and do some cleanups (on this series,
I kept the contents pretty much untouched), but we can see already the big 
picture.

> It's hard to argue, for
> example, that "modprobe parameters" should be somewhere other than with all
> the other command-line parameters...

Well, on media, several modprobe parameters require a long explanation, 
as they're used to overcome some limitations of probing devices that
don't have any BIOSes and share a common PCI ID (or USB ID) for completely
different hardware. So, just blindly adding them at 
Documentation/admin-guide/kernel-parameters.txt may not be the best
(yet, we should do some efforts to place a short summary of them there,
as I'm pretty sure that some of those aren't refleced there).

One of the bad things on keeping kernel-parameters.txt as a text file
(and having a .rst including it as a literal doc) is that we can't
have cross-references there.

-

On this series, what I did with the driver information is that I placed:

1) drivers release notes:

	- https://git.linuxtv.org/mchehab/experimental.git/tree/Documentation/admin-guide/media?h=media-docs

The stuff there are all focused on explaining users about some
device-specific thing (supported cards, known problems, how to use drivers,
etc).

Those include modprobe parameters, and also other user-facing stuff, like
command line examples about how to do some things. Some still include
some (probably outdated) instructions about how to build a Kernel with
such driver.

2) Development-specific documentation:

	- https://git.linuxtv.org/mchehab/experimental.git/tree/Documentation/driver-api/media/drivers?h=media-docs 

A large part of that are related to things that the drivers' develpers
seem to had figured out themselves. Only useful if someone would need
to touch the source code. They work as some sort of  "Hardware manuals".

The name "driver-api" is not really appropriate for it, as they don't
define any API. They're pure "hardware API docs". Yet, developers
needing such info also needs to know media kAPI. So, while not a perfect
fit, it sounded better than placing them elsewhere.

3) Driver-specific uAPI:

	- https://git.linuxtv.org/mchehab/experimental.git/tree/Documentation/userspace-api/media/drivers?h=media-docs

It covers extensions of the media API to cover driver-specific stuff that
can't be generalized. This incudes some driver-specific formats, some
extra controls to control some hardware-specific parameters and meta-data
streaming (used by some image-enhancing algorithms for cellphone cameras).

Btw, I'm very happy on having a separate session with all driver-specific
APIs. As a maintainer, now I have a centralized place at the docs where I
can see all device-specific userpace APIs, with is a good thing.

Yet, for someone developing an application to work with some of those hardware
it may now need to read on two separate places.

For example, see the IMX driver documentation split:

	https://git.linuxtv.org/mchehab/experimental.git/commit/?h=media-docs&id=da5a18aa27c564cdb4fa6f84026be1c72c1a877c

Anyone working with such driver will need to be able to setup the hardware
pipelines, via the standard media controller API. This is done using
existing applications. So, the command line instructions and pipeline
examples are at the driver's release notes:

	https://git.linuxtv.org/mchehab/experimental.git/tree/Documentation/admin-guide/media/imx.rst?h=media-docs

Also, to fully control the hardware, the userspace application will
need to implement support for some device-specific controls and receive some
events. This is covered at:

	https://git.linuxtv.org/mchehab/experimental.git/tree/Documentation/userspace-api/media/drivers/imx-uapi.rst?h=media-docs

On this specific split[1], I added cross-references at the admin-guide to the
API documentation. Not sure if this is enough or if we would need more things
to cross-reference the docs that got split.

[1] I should do something similar to it with the other split documents.

Comments?

Regards,
Mauro

Powered by blists - more mailing lists