linux-kernel - Re: [PATCH 4/5] doc: ABI: bone

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <20150513120854.GA1516@kroah.com>
Date:	Wed, 13 May 2015 05:08:54 -0700
From:	Greg Kroah-Hartman <gregkh@...uxfoundation.org>
To:	Pantelis Antoniou <pantelis.antoniou@...sulko.com>
Cc:	Matt Porter <mporter@...sulko.com>,
	Koen Kooi <koen@...inion.thruhere.net>,
	Robert Nelson <robertcnelson@...il.com>,
	Rob Herring <robherring2@...il.com>,
	Grant Likely <grant.likely@...retlab.ca>,
	Jonathan Corbet <corbet@....net>,
	Srinivas Kandagatla <srinivas.kandagatla@...aro.org>,
	Guenter Roeck <linux@...ck-us.net>,
	Geert Uytterhoeven <geert+renesas@...der.be>,
	Benoît Cousso <bcousson@...libre.com>,
	linux-api@...r.kernel.org, linux-doc@...r.kernel.org,
	devicetree <devicetree@...r.kernel.org>,
	linux-kernel@...r.kernel.org
Subject: Re: [PATCH 4/5] doc: ABI: bone_capemgr sysfs API

On Wed, May 13, 2015 at 02:56:49PM +0300, Pantelis Antoniou wrote:
> Hi Greg,
> 
> > On May 13, 2015, at 14:52 , Greg Kroah-Hartman <gregkh@...uxfoundation.org> wrote:
> > 
> > On Wed, May 13, 2015 at 10:59:44AM +0300, Pantelis Antoniou wrote:
> >> Document the beaglebone's capemgr sysfs API
> >> 
> >> Signed-off-by: Pantelis Antoniou <pantelis.antoniou@...sulko.com>
> >> ---
> >> .../testing/sysfs-devices-platform-bone_capemgr    | 63 ++++++++++++++++++++++
> >> 1 file changed, 63 insertions(+)
> >> create mode 100644 Documentation/ABI/testing/sysfs-devices-platform-bone_capemgr
> >> 
> >> diff --git a/Documentation/ABI/testing/sysfs-devices-platform-bone_capemgr b/Documentation/ABI/testing/sysfs-devices-platform-bone_capemgr
> >> new file mode 100644
> >> index 0000000..e2df613
> >> --- /dev/null
> >> +++ b/Documentation/ABI/testing/sysfs-devices-platform-bone_capemgr
> >> @@ -0,0 +1,63 @@
> >> +What:		/sys/devices/platform/bone_capemgr/slots
> >> +Date:		May 2015
> >> +KernelVersion:	4.0
> > 
> > I don't think that version is correct :)
> > 
> 
> Bah, ++
> 
> >> +Contact:	Pantelis Antoniou <pantelis.antoniou@...sulko.com>
> >> +Description:
> >> +		READ:
> >> +		  Describe the state of all the slots of the beaglebone capemgr.
> >> +		  Each line of the output describes a slot:
> > 
> > sysfs files are "one value per file", so a sysfs file that displays
> > multiple lines like this is not allowed at all, sorry.
> > 
> > Please either make it a debugfs file (if this is only for debugging, or
> > split it out into individual files, one per slot (hint, one per slot is
> > probably best.)
> > 
> 
> Well, it’s a status file. And it’s been used as is for a couple of years
> so it was worth a shot for backward compatibility.

There is not "backwards compatiblity" for when you do things wrong in
the first place, you can't claim that here, sorry.

And don't "try" to introduce things you know is wrong, that just makes
maintainers _very_ suspicious of everything else you are doing here...

> >> +		  The slot format is as following:
> >> +		  <slot-id>: [P-][F-][O-][l-][L-][D-] \
> >> +			  <overlay-id> <board-name>,<version>,
> >> +			  <manufacturer>,<part-number>
> >> +
> >> +		Where the flags are:
> >> +		P: Slot has been probed
> >> +		F: Slot has failed probing (i.e. no EEPROM detected)
> >> +		O: Slot has been overridden by the user
> >> +		l: Slot is current loading
> >> +		L: Slot has completed loading and is ready
> >> +		D: Slot has been disabled
> >> +
> >> +		Example:
> >> +		0: P---L-  -1 BeagleBone RS232 CAPE,00A1,Beagleboardtoys,BB-BONE-SERL-03
> >> +		1: PF----  -1
> >> +		2: PF----  -1
> >> +		3: PF----  -1
> >> +
> >> +		WRITE:
> >> +		  Writing a string of the form <part-number>[:version] issues a request to
> >> +		  load a firmware blob containing an overlay. The name of the firmware blob
> >> +		  is <part-number>-[version|00A0].dtbo. This act is defined as a slot override.
> >> +
> >> +		  Writing a negative slot id removes the slot if it was an overridden one, or
> >> +		  unloads a slot that was probed.
> >> +
> >> +What:		/sys/devices/platform/bone_capemgr/baseboard/<eeprom-field>
> >> +Date:		May 2015
> >> +KernelVersion:	4.0
> >> +Contact:	Pantelis Antoniou <pantelis.antoniou@...sulko.com>
> >> +Description:	Contains the probed base board EEPROM field; one of:
> >> +		board-name		- board-name as stored in cape EEPROM
> >> +		dc-supplied		- whether the cape draws or supplies DC
> >> +		eeprom-format-revision	- EEPROM format rev, only 00A0 supported
> >> +		header			- header; should be 'aa 55 33 ee'
> > 
> > If it's always this value, why have the file?
> > 
> 
> These are the contents of the EEPROM. If the format of the EEPROM changes then the
> header information will change.

Then don't say "should be", because what happens in the future if it is
not.

> >> +		manufacturer		- manufacturer string
> >> +		part-number		- part-number of the cape
> >> +		serial-number		- serial number of the cape
> >> +		version			- version of the cape, i.e. 00A0
> >> +		number-of-pins		- displayed but ignored
> >> +		pin-usage		- displayed but ignored
> >> +		sys-5v			- displayed but ignored
> >> +		vdd-3v3exp		- displayed but ignored
> >> +		vdd-5v			- displayed but ignored
> > 
> > Are these all individual different files?
> > 
> 
> Yes

Then write out the individual files please as different entries.

Also, the "displayed but ignored" doesn't make sense, please fix that
up.

greg k-h
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/