Initially I sorted these alphabetically, but I ended up growing them by functionality a bit: process events (exec/fork/exit), user thread creation, syscall argument handling, cpu_idle, cpu_proccontrol, cpu_switch/throw, cpu_sync_core, then the thread object lifecycle. I think we also have some other cpu_* functions in other headers? A few of these have callouts in the implementations (e.g. cpu_fork tends to have a similar comment in every vm_machdep.c). I haven't removed those. Possibly I should as the goal is to centralize the comments?

Not sure why the whitespace varies here.

It doesn't in the source, must be a weird phab issue.

Not sure how to formulate it, but when the function returns, it returns to the caller. I.e., it returns twice, immediately in the context of the thread switched to, and then in the context of the calling thread once returned to CPU.

The stack is copied by COWing the pages, but the user registers are certainly copied.

Hmm, it's not always kernel registers. User registers that aren't saved in the trapframe but saved in the PCB are also swapped here.

Yes, I'm not sure how to say it either. It's quite the same as "returns twice" the way setjmp is, it's more a matter of two different ways of looking at timelines. From a CPU-centric timeline, the function "returns" into the new thread (but not if it is a newborn thread). From a thread-centric timeline, the the function returns when the thread resumes execution.

s/stack/stack pointer/

May be, directly write there what you described as return from the PoV of current thread, and from the PoV of CPU.

I've tried to add something. The thought I had a week or so ago was to describe the caller's experience (what to think when you are in mi_switch() for example) vs the implementer's experience (how to think about it when working on an implementation of cpu_switch itself.

Hmmm, I think OS thread is perhaps not clear. The distinction I'm aiming to make here is between kernel threads (with a kernel stack, and a kernel-visible object) vs user-space threads as some language runtimes may still employ some version of green threads or coroutines or something to multiplex multiple user-space threads onto a single kernel thread. One could argue that an OS thread might mean the user threads provided by an OS thread library (like libpthread), or at least I feel that the term is ambiguous.