PHYSIO(9)

💖 PHYSIO(9) — the Kernel Developer's Manual glow-up 💖

okay bestie, sit down, hydrate, and let me tell you about physio from the Kernel Developer's Manual — aka the little helper that starts I/O on raw devices. she's giving backstage-pass energy for your character devices. ✨

---

🌸 NAME 🌸

physio — initiate I/O on raw devices 💅

---

✨ SYNOPSIS ✨

#include <sys/param.h>
#include <sys/systm.h>
#include <sys/bio.h>
#include <sys/buf.h>

int
physio(struct cdev *dev, struct uio *uio, int ioflag);

no cap, that's the whole signature. three args, one int coming back at you. 🫶

---

🦋 DESCRIPTION 🦋

So physio() is a helper function, right? She gets called, like, typically from your character device read() and write() routines, and her whole job is to start I/O on a user process buffer. main character behavior fr fr. 👑

The maximum amount of data you can transfer with each call is determined by dev->si_iosize_max. That's the ceiling, bestie. Don't test it.

Then physio() takes your I/O request, converts it into a strategy() request, and hands that shiny new request over to the driver's strategy() routine for processing. it's giving "middle manager who actually does the work". 😭

Now — plot twist — since uio normally describes user space addresses, physio() has to lock those pages into memory. She does this by calling vmapbuf() for the appropriate pages. locked in. literally. 🔒

And here's the thing: physio() always awaits the completion of the entire requested transfer before returning, unless an error condition gets detected earlier. she does NOT do half-jobs. she waits for the whole thing. periodt. 💅

---

🎀 a break-down of the arguments (the besties) 🎀

• dev — the device number identifying the device to interact with. like, which device are we pulling up on? that one. 🍓
• uio — the description of the entire transfer as requested by the user process. ⚠️ currently, the results of passing a uio structure with the uio_segflg set to anything other than UIO_USERSPACE are undefined. undefined behaviour, babe. we do not go there. 💀
• ioflag — the ioflag argument from the read() or write() function calling physio(). just pass it along, she knows what to do with it. 🦋

---

🌈 RETURN VALUES 🌈

If everything slays, physio() returns 0. ✅

EFAULT gets returned if the address range described by uio is not accessible by the requesting process. can't reach it? can't touch it. 🙈

physio() will also return any error resulting from calls to the device strategy routine — she figures that out by examining the B_ERROR buffer flag and the b_error field. detective mode. 🔍

👀 heads up bestie: the actual transfer size may be less than requested by uio if the device signals an “end of file” condition. so like, don't assume you got the whole snack. sometimes you get a bite. 🍪

---

💜 SEE ALSO 💜

• read(2)
• write(2)

---

⭐ HISTORY ⭐

The physio manual page is originally from NetBSD, with minor changes for applicability with FreeBSD. so she's got lore. 📜✨

And the physio call has been completely re-written for providing higher I/O and paging performance. glow-up of the century, honestly. 🔥

---

and that's the whole page, bestie!! this one came from Debian, dated January 19, 2012 — shoutout to the archives for keeping her iconic. mwah. 💋