Nice! A bag of assorted comments: 1. I share the same concern of duplicating info. If there are lots of duplication it may lead to failure of the whole effort since folks won't update these and/or they will get out of sync. If a syscall arg is e.g. umode_t, we already know that it's an integer of that enum type, and that it's an input arg. In syzkaller we have a Clang-tool: https://github.com/google/syzkaller/blob/master/tools/syz-declextract/clangtool/declextract.cpp that extracts a bunch of interfaces automatically: https://raw.githubusercontent.com/google/syzkaller/refs/heads/master/sys/linux/auto.txt Though, oviously that won't have user-readable string descriptions, can't be used as a source of truth, and may be challenging to integrate into kernel build process. Though, extracting some of that info automatically may be nice. 2. Does this framework ensure that the specified info about args is correct? E.g. number of syscall args, and their types match the actual ones? If such things are not tested/validated during build, I afraid they will be riddled with bugs over time. 3. To reduce duplication we could use more type information, e.g. I was always frustrated that close is just: SYSCALL_DEFINE1(close, unsigned int, fd) whereas if we would do: typedef int fd_t; SYSCALL_DEFINE1(close, fd_t, fd) then all semantic info about the arg is already in the code. 4. If we specify e.g. error return values here with descirptions, can that be used as the source of truth to generate man pages? That would eliminate some duplication. 5. We have a long standing dream that kernel developers add fuzzing descirpions along with new kernel interfaces. So far we got very few contributions to syzkaller from kernel developers. This framework can serve as the way to do it, which is nice. 6. What's the goal of validation of the input arguments? Kernel code must do this validation anyway, right. Any non-trivial validation is hard, e.g. even for open the validation function for file name would need to have access to flags and check file precense for some flags combinations. That may add significant amount of non-trivial code that duplicates main syscall logic, and that logic may also have bugs and memory leaks. 7. One of the most useful uses of this framework that I see if testing kernel behavior correctness. I wonder what properties we can test with these descirptions, and if we can add more useful info for that purpose. Argument validation does not help here (it's userspace bugs at best). Return values potentially may be useful, e.g. if we see a return value that's not specified, potentially it's a kernel bug. Side-effects specification potentially can be used to detect logical kernel bugs, e.g. if a syscall does not claim to change fs state, but it does, it's a bug. Though, a more useful check should be failure/concurrency atomicity. Namely, if a syscall claims to not alter state on failure, it shouldn't do so. Concurrency atomicity means linearizability of concurrent syscalls (side-effects match one of 2 possible orders of syscalls). But for these we would need to add additional flags to the descriptions that say that a syscall supports failure/concurrency atomicity. 8. It would be useful to have a mapping of file_operations to actual files in fs. Otherwise the exposed info is not very actionable, since there is no way to understand what actual file/fd the ioctl's can be applied to. 9. I see that syscalls and ioctls say: KAPI_CONTEXT(KAPI_CTX_PROCESS | KAPI_CTX_SLEEPABLE) Can't we make this implicit? Are there any other options? Similarly an ioctl description says it releases a mutex (.released = true,), all ioctls/syscalls must release all acquired mutexes, no? Generally, the less verbose the descriptions are, the higher chances of their survival. +Marco also works static compiler-enforced lock checking annotations, I wonder if they can be used to describe this in a more useful way.
