Ideas for a main man page update

[CPestka]

After the syscall man pages I recently had a look at the main man page.
Besides a couple of smaller things, I think it might be a good idea to make some bigger additions. For some of these additions I'm not entirely sure if they do belong in the man pages or not, hence this discussion :)

Why do I think some bigger additions would be a good idea?
Well mostly because some topics come up again and again either in issues here or in discussions etc. that i had with other people, where the misunderstanding (I think) is mostly related to not understanding the related internals of io_uring, that are not documented in the man pages or somewhere similar. I think the most notable ones here are all the things related to IO WQ async punt stuff and the general broad strokes of what needs to be done generally for each request on the kernel side. I think not having this somewhere documented where it is easy to find has lead to things that are most likely mistakes like e.g. people setting IOSQE_ASYNC for all requests to a e.g. blk dev or regular file, presumably thinking "I'm specifically using this async io api over a blocking one why would i want requests to sometimes not be async and thus presumably block. I use this flag to make io_uring to stop act stupid and always be async as promised unlike e.g. aio used to be.", or all the confusion about the taskrun related flags (what they actually do and what are compatible with each other and e.g. sq polling). Currently there are only bits of this scattered over the documentation, other info like how IO WQ pools etc. are shared among threads and processes can be found in random places on the internet (cloud flare blog), while other (IMO important) stuff relating to these "more internal" systems like IO WQ is completely undocumented, like that IO WQ workers are created lazily, which I only found out when i actually read the code.

I think it might be nice to have either a section in the main man page for each of these topics or (imo nicer) mention it briefly in the main man page and then have a separate man page for that topic.

If one would go with that, i think it would also be nice to make similar pages for some other topics that are documented, but not centrally, like registered fds, provided buffers, multi shot etc.. Those would be e.g. a nice place to also add some general information about these mechanisms like what is the actual optimization (e.g. reg fds -> it is avoiding fget and fput -> avoid the atomic refcounting overhead), which would be nice for non-kernel people to know to e.g. know how big of a deal using that feature is and that e.g. an interface is unofficially deprecated/discouraged to be used (and why) like with the two apis for provided buffers.

An incomplete list of these topics from the top of my head:

1. IO WQ / async punt
2. General workflow within the kernel / what needs to be done to each request at a high level
   • I think this one is not needed directly, but would be very helpful to explain the others e.g. the IO WQ stuff
3. "Organization of kernel threads" / what dedicated kernel threads exist in what situation, do what specific task and are shared in what way
4. SQ polling
5. registered fds
6. provided buffers
7. multi shot
8. zero copy
9. methods to enforce ordering - link, wait for completions, bundles
10. cancelations - sync, async, drain, all, all for fd, one....
11. notes on multi threading / multiple rings - implications regarding usage patterns (single_issuer, the per instance lock, per instance dedicated kthreads....)

Sry for the essay ^^

[axboe]

Fully agree! I've been saying for a while that we need to have more section 7 man pages, that explain full concepts.