CPU_SWITCHTO(9)

💅 CPU_SWITCHTO(9) — the kernel dev manual, bestie edition

okay so this is cpu_switchto, from section 9 of the Kernel Developer's Manual, and it's basically the machine-dependent LWP context switching interface. yes, that's a lot of words. we'll get through it together 🫶

---

✨ NAME ✨

cpu_switchto — the machine-dependent LWP context switching interface. it's the function that does the actual "ok you sit down, you stand up" of threads on a processor 💅

🦋 SYNOPSIS 🦋

#include <sys/cpu.h>

lwp_t *
cpu_switchto(lwp_t *oldlwp, lwp_t *newlwp, bool returning);

like, that's the whole signature. no cap, that's it 🌸

🎀 DESCRIPTION 🎀

so what does cpu_switchto() actually do? it saves the context of the LWP that's currently running on the processor, and it restores the context of the LWP you point at with newlwp. that's the entire personality. iconic behavior honestly ✨

now, the Remarks — and bestie, these matter, don't skip them:

1. cpu_switchto() does not switch address spaces. it's just not that kind of function. 🙅‍♀️
2. cpu_switchto() sets curlwp(9) to newlwp. and if the architecture does non-interlocked adaptive mutex release, then cpu_switchto() does an equivalent of membar_producer(3), before and after the modification of curlwp(9). yes, both sides. it's giving thorough 💀
3. cpu_switchto() should be called at IPL_SCHED. and when the function returns, the caller should lower the priority level as soon as possible. don't sit there vibing at high IPL, it's rude 😭
4. cpu_switchto() might be called with spin mutexes held. so like, heads up. 🫡

---

🌈 the arguments 🌈

the function takes the following arguments:

• oldlwp — specify the LWP from which the switch is going to be made, i.e. the calling LWP. and if it was NULL, then the context of the LWP currently running on this processor is not saved. so NULL = "no need to save me, i'm good" 🙈
• newlwp — specify the LWP to which to switch. it must not be NULL. periodt. 🚫
• returning — this one only means something if the architecture implements fast software interrupts. if true, it indicates that oldlwp is a soft interrupt LWP that is blocking. and that's a good indication that any kind of address space or user activity can be completely ignored. for example: ras_lookup(9), cache flushes, TLB wirings, adjusting lazy FPU state. all that's required is to restore the register state and stack, and return to the interrupted LWP. so basically true = "we're just popping back into the interrupted LWP, nothing else to see here" 🧚

🔥 RETURN VALUES 🔥

okay this is the fun part. cpu_switchto() does not return until another LWP calls cpu_switchto(). it just... doesn't come back. main character energy, honestly 👑

when it does finally return, it returns the oldlwp argument of the cpu_switchto() that was called to switch back to our LWP. and that value is either:

• a LWP which called cpu_switchto() to switch to us, or
• NULL, in case the LWP was exiting. 💀

⭐ SEE ALSO ⭐

membar_producer(3), swapcontext(3), intro(9), mutex(9), spl(9)

go read those next, i promise they're relevant, iykyk 🦋

---

🌸 quick vibe check reminder: call it at IPL_SCHED, lower that priority level ASAP on return, newlwp can never be NULL, and it does not switch address spaces. those are the rules, and we respect them 💖

---

and that's the page! this one's from Debian, dated June 2, 2011 — shoutout to the kernel devs who wrote it, and to you for reading all the way to the bottom. slay 🎀✨