Messages in this thread | | | Date | Wed, 16 Jul 1997 23:58:39 +0300 | From | Kohtala Marko <> | Subject | Re: Kernel flow graphing (was Re: Take a deep breath...) |
| |
Keit Owens <kaos@ocs.com.au> wrote: > Unfortunately even something as "small" as > net/ipv4/*.[ch] generated a very wide, very flat graph. It was not > more than 6 levels deep but was about 50 functions wide. Took up a lot > of room on the wall :).
Thank you for the input. I am happy at the high quality of comments to my mail.
Seems like one really needs to have a point to make in drawing a graph. Perhaps graphs from the source are not often useful.
> Take function ipfw_device_event in ipv4/ip_fw.c (2.1.44). The only > reference to that is in structure ipfw_dev_notifier in the same source.
A good way to tell this to the one reading the source is to make the ipfw_device_event static, which it now is not.
... > To a human, all the above means that ipfw_device_event is called when > any network device comes up, goes down, changes address, changes MTU or > changes some interface flags.
I was hoping that a tool could dig up the values used to indicate the purpose of calls used (NETDEV_CHANGE, NETDEV_CHANGEMTU, NETDEV_CHANGEADDR, NETDEV_CHANGEADDR, NETDEV_DOWN, NETDEV_UP). Totally automated tool to dig out the fact that the function can receive only these values is difficult, as you say, because it is difficult to couple calls to register_netdevice_notifier and notifier_call_chain automatically.
However, they can be resolved by Linux source specific helping rules like "parameter 2 of call to function notifier_call_chain with first parameter &netdev_chain go to parameter 2 of member notifier_call in structures passed to register_netdevice_notifier". Distributing the values to all those functions that are assigned to the specified member would be part of the standard set of rules. So this is just a matter of querying the information extracted from the source to generate documentation that stays up to date with reasonable effort of updating the helping rules. I hope there are not too many of these quite impossibly difficult indirections.
> I suspect the real answer is the equivalent of short man pages for each > high level function. Something like :- ...
No and yes. Yes in the sense that pages for functions should be available. I dislike this for the reason that free form documentation easily omits important aspects of the function simply because the writer forgot that such feature should be documented too and expresses same feature in different ways. I'd rather have a tool to add a description of an aspect to the description of functions if a rule applies to the function. For example, add comment "Network device notification function" to those functions that are values of notifier_call member of structures passed to register_netdevice_notifier.
This way the documentation will have this information for all such functions even in the future by adding this one rule once. Also, it forces to keep a list of features that are worth documenting for a function and a standard way of expressing the feature so that it is easier to use the documentation.
Automated tool like this can make errors (like when the structure member receives the value through a variable), but still the errors could be fixed (and the example error could be detected automatically) by explicit rules and I suspect there would be fewer errors than if documented by hand.
As to the shortness of the page, a tool with which to select the features you want to see, would be nice, but let's think about it after we get the data extracted and queries working.
-- --- Marko Kohtala - Marko.Kohtala@ntc.nokia.com, Marko.Kohtala@hut.fi
| |