Re: [PATCH 3/3] doc-rst: add an ABI book

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On Fri, Oct 28, 2016 at 11:33:51AM -0200, Mauro Carvalho Chehab wrote:
> Em Fri, 28 Oct 2016 08:49:12 -0400
> Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx> escreveu:
> 
> > On Fri, Oct 28, 2016 at 08:31:57AM -0400, Greg Kroah-Hartman wrote:
> > > On Fri, Oct 28, 2016 at 10:19:47AM -0200, Mauro Carvalho Chehab wrote:  
> > > > Use a script to parse the Documenation/ABI directory and output
> > > > it at the admin-guide.
> > > > 
> > > > Signed-off-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>
> > > > ---
> > > >  Documentation/admin-guide/abi.rst   |   5 +
> > > >  Documentation/admin-guide/index.rst |   1 +
> > > >  Documentation/sphinx/abi_book.pl    | 208 ++++++++++++++++++++++++++++++++++++
> > > >  3 files changed, 214 insertions(+)
> > > >  create mode 100644 Documentation/admin-guide/abi.rst
> > > >  create mode 100755 Documentation/sphinx/abi_book.pl  
> > > 
> > > Any hint as to what the output of this actually looks like?  
> > 
> > Doh, you already showed it in patch 0/3, that's what I get for never
> > reading cover letters...
> 
> :-)
> 
> > sorry for the noise,
> 
> No problem. 
> 
> Btw, looking at the output of the script, I noticed a
> few files where "What" doesn't point to configfs/sysfs/procfs:
> 
> - Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration
> 	What:           Attribute for calibrating ST-Ericsson AB8500 Real Time Clock
> 
> This is probably a sysfs interface, so, IMHO, "What" here is wrong.
> 
> From the name of the file, I suspect that it should be, instead:
> 	What:		/sysfs/class/rtc/rtc0/device/rtc_calibration
> 			^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Looks right, but the original authors would know more.

> - Documentation/ABI/stable/thermal-notification
> 	What:           A notification mechanism for thermal related events
> 
> Not sure what kind of interface this is referring to. Perhaps a
> sysctl interface?

It's a netlink api, odd, haven't seen that before.

> - Documentation/ABI/stable/syscalls
> 	What:		The kernel syscall interface
> 
> This sounds OK, although it probably makes sense to document
> each system call.

Heh, that's the whole man page project, I don't think we want to suck
that into the kernel just yet :)

> - Documentation/ABI/testing/sysfs-devices-system-ibm-rtl
> 	What:           state
> 	What:           version
> 
> According with their descriptions, both are needed for the
> "ibm-prtm" userspace daemon, but it provides no glue where
> this should be located. Looking at its source file, it seems
> that they should be located at [1]:
> 
> 		/sys/devices/system/ibm_rtl/state
> 	and
> 		/proc/version
> 
> Btw, IMHO, it doesn't make much sense to document /proc/version
> inside sysfs-devices-system-ibm-rtl.

That might be a sysfs version file, not /proc/version, as it doesn't
look like /proc/version is described that way.

thanks,

greg k-h
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html



[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux