Asahi Lina (朝日リナ) // nullptr::live on Nostr: I think people really don't appreciate just how incomplete Linux kernel API docs are, ...

I think people really don't appreciate just how incomplete Linux kernel API docs are, and how Rust solves the problem.

I wrote a pile of Rust abstractions for various subsystems. For practically every single one, I had to read the C source code to understand how to its API.

Simply reading the function signature and associated doc comment (if any) or explicit docs (if you're lucky and they exist) almost never fully tells you how to safely use the API. Do you need to hold a lock? Does a ref counted arg transfer the ref or does it take its own ref?

When a callback is called are any locks held or do you need to acquire your own? What about free callbacks, are they special? What's the intended locking order? Are there special cases where some operations might take locks in some cases but not others?

Is a NULL argument allowed and valid usage, or not? What happens to reference counts in the error case? Is a returned ref counted pointer already incremented, or is it an implied borrow from a reference owned by a passed argument?

Is the return value always a valid pointer? Can it be NULL? Or maybe it's an ERR_PTR? Maybe both? What about pointers returned via indirect arguments, are those cleared to NULL on error or left alone? Is it valid to pass a NULL ** if you don't need that return pointer?