Em Mon, 22 Jul 2019 16:21:10 +0100
Mark Brown <broonie@xxxxxxxxxx> escreveu:
> On Mon, Jul 22, 2019 at 10:10:35AM -0300, Mauro Carvalho Chehab wrote:
> > Mark Brown <broonie@xxxxxxxxxx> escreveu:
>
> > > On Mon, Jul 22, 2019 at 08:07:31AM -0300, Mauro Carvalho Chehab wrote:
> > > > While there's one file there with briefily describes the uAPI,
> > > > the documentation was written just like most subsystems: focused
> > > > on kernel developers. So, add it together with driver-api books.
>
> > > Please use subject lines matching the style for the subsystem. This
> > > makes it easier for people to identify relevant patches.
>
> > Sure. Do you prefer this prefixed by:
>
> > spi: docs:
>
> > Or with something else?
>
> Anything starting with spi:
Ok.
>
> > > > Documentation/spi/{spidev => spidev.rst} | 30 +++--
> > >
> > > This is clearly a userspace focused document rather than a kernel
> > > internal one.
> >
> > True. What I've been doing so far is, for all drivers that I'm converting
> > with carries more than one documentation type (kABI, uABI and/or
> > admin-guide) is to keep the directory as-is, adding them under
> > this section at Documentation/index.rst:
...
> > Btw, if you look at spidev file, it contains stuff for both
> > userspace-api:
> >
> > "SPI devices have a limited userspace API, supporting basic half-duplex
> > read() and write() access to SPI slave devices. Using ioctl() requests,"
>
> > And for admin-guide:
>
> > "For a SPI device with chipselect C on bus B, you should see:
> >
> > /dev/spidevB.C ... character special device, major number 153 with
> > a dynamically chosen minor device number. "
>
> I think that split is higly artificial...
>
> > So, if we're willing to move it, the best is to do on a separate patch
> > with would split its contents into two files: admin-guide/spi-devices.rst and
> > userspace-api/spi-api.rst.
>
> ...
>
> > Ideally, we should split what's there at media/uapi into admin-guide
> > and userspace-api, but this would mean *a lot* of efforts. Not sure
> > if it is worth the effort.
>
> Is the admin/API stuff even sensible for things that are more embedded
> or desktop focused?
Yes. Btw, the plan is to add everything under Documentation/ABI at the
admin guide (parsed via some scripts).
> It feels very arbatrary and unhelpful for things
> like spidev where theuser is going to be writing a program.
I tend to agree with you. Doing such split may actually make things
worse for app developers, without providing much benefit for sysadmins.
I sent today an e-mail to the KS discussion ML about that, as, IMHO,
this is something that we should discuss at the Documentation track
there.
While the idea of having users/sysadmin-faced stuff at admin-guide
seems to be nice, doing it for driver-specific stuff could be overkill,
and will mean a lot of extra work.
Thanks,
Mauro
