PASS(4)

💅 PASS(4) — the pass manual page, but make it make sense 🎀

okay so bestie, welcome to the pass(4) page — this is the Kernel Interfaces Manual entry for the CAM application passthrough driver, and honestly it's giving "backstage pass to the kernel" energy. let's get into it ✨

---

🌸 NAME 🌸

pass — the CAM application passthrough driver. that's it, that's the name, slay 💅

---

✨ SYNOPSIS ✨

device pass

one line. one vibe. periodt.

---

🦋 DESCRIPTION 🦋

so the pass driver is literally the plug that lets userland applications issue CAM CCBs to the kernel. like, your app gets to talk directly to the CAM subsystem. main character energy fr fr 🔥

⚠️ okay so listen — because the pass driver allows direct access to the CAM subsystem, system administrators should exercise caution when granting access to this driver. if used improperly, this driver can allow userland applications to crash a machine or cause data loss. not me telling you this is a loaded weapon but like... it's a loaded weapon, bestie 😭 handle with care.

the pass driver attaches to every SCSI and ATA device found in the system. the way that it attaches to every device means it provides a generic means of accessing SCSI and ATA devices, and it lets you access devices which have no "standard" peripheral driver associated with them. iconic behavior honestly 👑

---

🧚 KERNEL CONFIGURATION 🧚

you only need to configure one pass device in the kernel. that's right — just one, bestie. pass devices are automatically allocated as SCSI and ATA devices are found. the kernel handles the rest, no cap ✨

---

💜 IOCTLS 💜

okay this is the meat of the page, grab a snack 🍓

• CAMIOCOMMAND *union ccb ** — this ioctl takes most kinds of CAM CCBs and passes them through to the CAM transport layer for action.

🙈 heads up: some CCB types are not allowed through the passthrough device, and must be sent through the xpt(4) device instead. some examples of xpt-only CCBs are XPT_SCAN_BUS, XPT_DEV_MATCH, XPT_RESET_BUS, XPT_SCAN_LUN, XPT_ENG_INQ, and XPT_ENG_EXEC. these CCB types have various attributes that make it illogical or impossible to service them through the passthrough interface. so like... don't try it, it's not gonna work 💀

if you would like the kernel to do error recovery, the CAM_PASS_ERR_RECOVER flag must be set on the CCB, and the retry_count field set to the number of retries. yes, both. no, you can't skip one. 💅

• CAMGETPASSTHRU *union ccb ** — this ioctl takes an XPT_GDEVLIST CCB, and returns the passthrough device corresponding to the device in question.

ngl, even though this ioctl is available through the pass driver, it's of limited use — because the caller must already know that the device in question is a passthrough device if they're issuing this ioctl. like the joke writes itself 😭 it's probably more useful to issue this ioctl through the xpt(4) device.

• CAMIOQUEUE *union ccb ** — queue a CCB to the pass driver to be executed asynchronously. the caller may use select(2), poll(2) or kevent(2) to receive notification when the CCB has completed. async queen behavior 🦋

this ioctl takes most CAM CCBs, but (again, bestie) some CCB types are not allowed through the pass device, and must be sent through the xpt(4) device instead. some examples of xpt-only CCBs are XPT_SCAN_BUS, XPT_DEV_MATCH, XPT_RESET_BUS, XPT_SCAN_LUN, XPT_ENG_INQ, and XPT_ENG_EXEC. these CCB types have various attributes that make it illogical or impossible to service them through the passthrough interface. same list, same energy, go through xpt(4) bestie 🙏

okay so this part is a little unhinged but stay with me: although the CAMIOQUEUE ioctl is not defined to take an argument, it does require a pointer to a union ccb. it's not defined to take an argument to avoid an extra malloc and copy inside the generic ioctl(2) handler. quirky? yes. intentional? also yes 💅

the completed CCB will be returned via the CAMIOGET ioctl. an error will only be returned from the CAMIOQUEUE ioctl if there is an error allocating memory for the request or copying memory from userland. all other errors will be reported as standard CAM CCB status errors. and since the CCB is not copied back to the user process from the pass driver in the CAMIOQUEUE ioctl, the user's passed-in CCB will not be modified — this is the case even with immediate CCBs. instead, the completed CCB must be retrieved via the CAMIOGET ioctl and the status examined. so like... don't go looking at the CCB you sent in, it's not where the tea is ☕

multiple CCBs may be queued via the CAMIOQUEUE ioctl at any given time, and they may complete in a different order than the order that they were submitted. so the caller must take steps to identify CCBs that are queued and completed. the periph_priv structure inside struct ccb_hdr is available for userland use with the CAMIOQUEUE and CAMIOGET ioctls, and will be preserved across calls. also, the periph_links linked list pointers inside struct ccb_hdr are available for userland use with the CAMIOQUEUE and CAMIOGET ioctls and will be preserved across calls. use them, they're literally free real estate 🏠

if you would like the kernel to do error recovery, the CAM_PASS_ERR_RECOVER flag must be set on the CCB, and the retry_count field set to the number of retries. (yes, same as above — it bears repeating, okay 😤)

• CAMIOGET *union ccb ** — retrieve completed CAM CCBs queued via the CAMIOQUEUE ioctl. an error will only be returned from the CAMIOGET ioctl if the pass driver fails to copy data to the user process or if there are no completed CCBs available to retrieve. if no CCBs are available to retrieve, errno will be set to ENOENT. we love a specific error code 💖

all other errors will be reported as standard CAM CCB status errors.

and yes, the same chaotic caveat: although the CAMIOGET ioctl is not defined to take an argument, it does require a pointer to a union ccb. it is not defined to take an argument to avoid an extra malloc and copy inside the generic ioctl(2) handler. consistent iconic behavior 😌

the pass driver will report via select(2), poll(2) or kevent(2) when a CCB has completed. one CCB may be retrieved per CAMIOGET call. CCBs may be returned in an order different than the order they were submitted — so the caller should use the periph_priv area inside the CCB header to store pointers to identifying information. that's your little name tag system, bestie 🏷️

---

🎀 FILES 🎀

• /dev/passn — character device nodes for the pass driver. there should be one of these for each device accessed through the CAM subsystem. one per device, no sharing, we don't do that here ✨

---

🌈 DIAGNOSTICS 🌈

None. that's it. that's the whole section. not me hyping up a section with nothing in it 💀

---

👑 SEE ALSO 👑

kqueue(2), poll(2), select(2), cam(3), cam_cdbparse(3), cam(4), cd(4), ctl(4), da(4), sa(4), xpt(4), camcontrol(8), camdd(8) — go read these, they're the friends of the group chat 🫶

---

⭐ HISTORY ⭐

the CAM passthrough driver first appeared in FreeBSD 3.0. a legend was born ✨

---

💖 AUTHORS 💖

Kenneth Merry <ken@FreeBSD.org> — thank you for your service, king 👑

---

and that's the whole page, bestie! written under the Debian version, dated May 3, 2017, on the PASS(4) page — go forth and issue those CCBs responsibly 🦋💅🌷