On 12/27/17 7:15 AM, Jiri Pirko wrote: > Wed, Dec 27, 2017 at 02:08:03PM CET, and...@lunn.ch wrote: >>> This is misunderstanding I believe. This is not about ABI. That is well >>> defined by the netlink attributes. This is about meaning of particular >>> ASIC-specific internal resources. >> >> I would agree that the netlink attributed are clearly defined. But the >> meta information, what this ASIC specific internal resource means when >> you combine these attributes, is unclear. This meta information is >> also part of the ABI, and documenting giving users a hit what it >> means, and why they should change it, would be good practice. >> >> Look at sysfs. open/read/write are clearly defined, which is the >> equivalent of the netlink attributes. The meta information we document >> in Documentation/ABI/, what a file name means, what a value means, >> what other values it can take, etc. > > Hmm. That documents mainly sysfs. No mention of Netlink at all. But > maybe I missed it. Also, that defines the interface as is. However we > are talking about the data exchanged over the interface, not the > interface itself. I don't see how ASIC/HW specific thing, like for > example KVD in our case could be part of kernel ABI. That makes 0 sense > to me, sorry. >
IMO, kernel documentation is not much better than vendor docs. A general networking admin may not have access to a kernel tree or have vendor docs at their finger tips. As I mentioned in the previous response, devlink attributes have self-documenting capabilities making that information available inline. That to me is the right place for a short, but reasonably sized description. For in-depth details users can cross-reference vendor docs.
