cp_prefetch(9)

📦 version 7.3.1, in nixpkgs unstable

💅 cp_prefetch(9) — the Kernel API Manual glow-up ✨

okay so bestie, welcome to cp_prefetch(9) from the Kernel API Manual (section 9, kernel land, we love a low-level moment) 🌸

✨ NAME ✨

cp_prefetch — translates a guest physical address channel program into a real-device runnable channel program 🎀

🦋 SYNOPSIS 🦋

int cp_prefetch (struct channel_program *cp );

💖 ARGUMENTS 💖

  • cp — the channel_program we're doing the operation on 🫶

👑 DESCRIPTION 👑

So basically this function translates the guest-physical-address channel program and stores the result into the ccwchain list. Iconic, honestly.

⚠️ Real talk though: cp must have been initialized by a previous call with cp_init. If it wasn't? Undefined behavior occurs. Not a vibe. Not a slay. Please init your structs, bestie 😭

For each chain that composes the channel program:

  • On entry, ch_len holds the count of CCWs to be translated 🔥
  • On exit, ch_len is adjusted to the count of successfully translated CCWs. This is the whole point — it lets cp_free find, in ch_len, the count of CCWs to free in a chain 💀 (a little bookkeeping moment, but we respect it)

The S/390 CCW Translation APIS (prefixed by cp_, iykyk) were introduced as helpers to do ccw chain translation inside the kernel. Basically: they accept a channel program issued by a virtual machine, and translate that channel program into a real-device runnable channel program 🌈

These APIs will copy the ccws into kernel-space buffers, and update the guest physical addresses with their corresponding host physical addresses. Then channel I/O device drivers could issue the translated channel program to real devices to perform an I/O operation ⭐

These interfaces are designed to support translation only for channel programs that are generated and formatted by a guest. Which is literally what makes it possible for things like VFIO to leverage the interfaces to passthrough a channel I/O mediated device in QEMU 🧚

And last but not least: we support direct ccw chaining by translating them to idal ccws 💜

🔥 RETURN 🔥

0 on success, and a negative error value on failure ✨

🌸 SEE ALSO 🌸

Kernel file ./drivers/s390/cio/vfio_ccw_cp.c, plus these besties:

that's the whole page, bestie — go translate some channel programs 💅✨

🫶 cute lil sign-off: this one lives under ./drivers/s390/cio, dated October 2026, and yes ma'am, cp_prefetch(9) again because we always close the loop 🎀

📦 where this page comes from