gdt | The Linux kernel API, a user's view (Reply)

Rusty's blog on API design is timely, as I'm struggling with the API for Linux's Netfilter. There's no shortage of HOWTOs on the topic and no shortage of production code to examine.

The problem is bit rot. The API to establish connection tracking has been deprecated, but the official HOWTO on the Netfilter website hasn't been changed. There's no documentation of the new nf_ct_expect_alloc() at all. A reasonable QA process would have rejected a code change which didn't update the official documentation.

The API to register a connection tracking helper has also silently changed. nf_conntrack_helper_register() no longer accepts a bitmask. Again the official documentation and sample code hasn't been updated. The entirety of the documentation is a set of obscure commit comments and a short NetDev list discussion. Without finding those and understanding their significance you can't understand why the production code works.

The broader networking API also has a newish function: skb_header_pointer(). All of the original SKB manipulation functions have documentation in the header file. Somehow this new function appeared with no documentation in that header file.

I can read source. But let's not pretend that "Use the Source Luke" is ideal. The code for nf_conntrack_helper_register() is about adding entries to a list. The magic doesn't happen until a packet arrives, and that list is searched and acted upon, which is handled in other code in a galaxy far, far away.

Source code is also hard at explaining why. Why and when should skb_header_pointer() be used in preference to direct access to the SKB's data? The source won't tell you that unless you are already so immersed in the kernel that you half-know the answer anyway.

Source code can also mislead. For example, looking at existing Netfilter code in the kernel would give you the idea that a 64KB buffer is needed for incoming packets in a Netfilter modules. That's not true at all, it's just that all of the modules which have been accepted into the kernel have needed to do that as they want to search for IETF-style protocol text or to decode ASN.1.

After struggling through all of this, I'll lay odds that posting the finished module will result in at least one put-down e-mail about some misuse of some Linux API.

A final thought. Is there a kernel API at all? Can something permanently partially obscured be said to exist? Or is the API like the Loch Ness Monster. In place of blurry photographs we have Linux device drivers, where even those who closely track the kernel API can be misled by poor design and worse documentation such as with in_atomic().