sysfs abi documentation

Hi,

Greg asked us to provide an ABI documentation for the files creates in the sysfs tree. Since I am respsonsible for the sysfs stuff, I felt it was my turn to draft something. Please check the attachments and let me know whether you think we can send it or not.

Cheers,
Marek

What:           /sys/class/net/<mesh_iface>/mesh/aggregate_ogm
Date:           May 2010
Contact:        Marek Lindner <[email protected]>

Description:
Indicates whether the batman protocol messages of the mesh <mesh_iface> shall be aggregated or not.

What:           /sys/class/net/<mesh_iface>/mesh/orig_interval
Date:           May 2010
Contact:        Marek Lindner <[email protected]>

Description:
Defines the interval in milliseconds in which batman sends its protocol messages.

What:           /sys/class/net/<mesh_iface>/mesh/originators
Date:           May 2010
Contact:        Marek Lindner <[email protected]>

Description:
Displays the table of all batman nodes (in range) and the link quality towards them. Each line contains the following values:
1 - originator
2 - TQ (transmit quality) value of originator 3 - best next hop towards originator
4 - outgoing iface to reach best next hop 5 - list of alternative best next hops

What:           /sys/class/net/<mesh_iface>/mesh/transtable_global
Date:           May 2010
Contact:        Marek Lindner <[email protected]>

Description:
Displays the table of mesh-wide announced mac addresses. Each line contains the following values:
1 - announced mac address
2 - originator announcing the mac address

What:           /sys/class/net/<mesh_iface>/mesh/transtable_local
Date:           May 2010
Contact:        Marek Lindner <[email protected]>

Description:
Displays the table of mac addresses announced to the mesh network by this node. Each line contains the following values:
1 - announced mac address

What:           /sys/class/net/<mesh_iface>/mesh/vis_mode
Date:           May 2010
Contact:        Marek Lindner <[email protected]>

Description:
Each batman node only maintains information about its own local neighborhood, therefore generating graphs showing the topology of the entire mesh is not easily feasible without having a central instance to collect the local topologies from all nodes. This file allows to activate the collecting (server) mode. Once activated the topology can be retrieved by reading the vis_data file.

What:           /sys/class/net/<mesh_iface>/mesh/vis_data
Date:           May 2010
Contact:        Marek Lindner <[email protected]>

Description:
This file outputs the collected entire mesh topology information (if available) in a neutral (raw) format. Each line contains a set of identifiers. Values may or may not follow depending on their respective meanings:
* "mac" - mac address of an originator's source interface (each line begins with it)
* "TQ mac value" - src mac's link quality towards mac address of a neighbor originator's interface which is being used for routing
* "HNA mac" - HNA announced by source mac
* "PRIMARY" - this is a primary interface
* "SEC mac" - secondary mac address of source (requires preceding PRIMARY)

What:           /sys/class/net/<iface>/batman-adv/mesh_iface
Date:           May 2010
Contact:        Marek Lindner <[email protected]>

Description:
The /sys/class/net/<iface>/batman-adv/mesh_iface file displays the batman mesh interface this <iface> currently is associated with.

What:           /sys/class/net/<iface>/batman-adv/iface_status
Date:           May 2010
Contact:        Marek Lindner <[email protected]>

Description:
Indicates the status of <iface> as it is seen by batman.

Hi Marek

This is something i already said in private, but i think it is going to be a problem.

From Documentation/filesystems/sysfs.txt

Attributes
~~~~~~~~~~

Attributes can be exported for kobjects in the form of regular files in the filesystem. Sysfs forwards file I/O operations to methods defined for the attributes, providing a means to read and write kernel attributes.

Attributes should be ASCII text files, preferably with only one value per file. It is noted that it may not be efficient to contain only one value per file, so it is socially acceptable to express an array of values of the same type.

Mixing types, expressing multiple lines of data, and doing fancy formatting of data is heavily frowned upon. Doing these things may get you publically humiliated and your code rewritten without notice.

I expect that we have a problem here. My guess is some of these files are going to have to move back into proc. Use sysfs for configuration, where only single values are needed, and put all the tables of originators, HNA etc back in proc where fancy formatting of data is not frowned upon.

Andrew

Yes, you are probably right. Unfortunately, I'm not sure what is supposed to go where. AFAIK procfs is deprecated, sysfs does not seem suitable. Greg mentioned configfs, etc ..
The idea was to document what we have & need and let them (Greg et al.) figure out what the best location might be to avoid investing more time & energy in the "wrong" virtual filesystem. :-)

Cheers,
Marek

I've read a little bit through the different descriptions and it sound good... for the reading situation. The problem is that it is nearly never clear that you control the behavior of batman-adv through that specific file. For example /sys/class/net/<iface>/batman-adv/mesh_iface - I think it is especially important for GregKH to see that it needed is now associated to the iface and we attach it to the mesh_iface through that file when he should give us some advice what virtual fs should be used for what kind of information.

Best regards,
Sven

Thanks for the review.
Before writing these descriptions I looked up various examples that are available in the kernel tree. I had the feeling that our ABI docs are not too far off. But I know that this will not be enough to understand the meaning behind those settings which is why I created a wikipage explaining the connections between the various sysfs files. I intended to send this along with the sysfs ABI files:
http://www.open-mesh.org/wiki/tweaking-batman-adv

Regards,
Marek