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:
> > > 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:
>
> Kernel API documentation
> ------------------------
>
> That's the case of media, input, hwmon, and so many other subsystems.
> Yet, you're right: this implies that there will be some things
> to be done, as the long-term documentation should be like:
>
> Documentation/admin-guide/{media, input, hwmon, spi, ...}
> Documentation/userspace-api/{media, input, hwmon, spi, ...}
> Documentation/driver-api/{media, input, hwmon, spi, ...}
> 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? It feels very arbatrary and unhelpful for things
like spidev where theuser is going to be writing a program.
Attachment:
signature.asc
Description: PGP signature
