_base_build_nvme_prp(9)

✨ `_base_build_nvme_prp(9)` ✨

okay so bestie, this one is a Kernel API Manual situation and it's lowkey kind of iconic. It's all about NVMe end devices building a native SGL (aka an NVMe PRP). We're in the _base_build_nvme_prp function and honestly the whole thing is giving "I speak fluent hardware" energy. 💅

🦋 SYNOPSIS 🦋

void _base_build_nvme_prp (struct MPT3SAS_ADAPTER *ioc , u16 smid ,
Mpi26NVMeEncapsulatedRequest_t *nvme_encap_request , dma_addr_t
data_out_dma , size_t data_out_sz , dma_addr_t data_in_dma , size_t
data_in_sz );

Bestie this signature is long but it's fine, we're gonna go through every single parameter together, no skipping, no cap. 💖

🎀 ARGUMENTS 🎀

ioc — the per adapter object, like the main character of this whole operation tbh
smid — the system request message index, used for getting the associated SGL
nvme_encap_request — the NVMe request msg frame pointer, aka where the encapsulated request lives
data_out_dma — physical address for WRITES, periodt 💅
data_out_sz — the data xfer size for WRITES
data_in_dma — physical address for READS, yes queen
data_in_sz — the data xfer size for READS

🌸 DESCRIPTION 🌸

Alright so here's the tea. The native SGL gets built starting in the very first PRP entry of the NVMe message — that's PRP1 in case you were wondering — and the whole vibe depends on how much data we're describing. If the data buffer is small enough to be entirely described by PRP1, then PRP2 doesn't even get used, she gets to rest. If needed though, PRP2 steps in to describe a larger data buffer. And if the data buffer is too large to describe using the two PRP entries inside the NVMe message?? Then PRP1 describes the first data memory segment, and PRP2 contains a pointer to a PRP list located elsewhere in memory to describe the remaining data memory segments. And yes, that PRP list will be contiguous. Slay. ✨

So for NVMe devices, the native SGL is a Physical Region Page (PRP). A PRP is literally a list of PRP entries that describe a number of noncontiguous physical memory segments as a single memory buffer, just like a SGL does. BUT — and this is important bestie — this function is only used by the IOCTL call, so the memory given will be guaranteed to be contiguous. There is no need to translate non-contiguous SGL into a PRP in this case. All PRPs will describe contiguous space that is one page size each. No drama, no fragmentation, just vibes. 🫶

Every NVMe message contains two PRP entries, fyi:

The first one, PRP1, either contains a PRP list pointer or a PRP element — it depends on the command, main character energy honestly.
PRP2 contains the second PRP element if the memory being described fits within 2 PRP entries, or a PRP list pointer if the PRP spans more than two entries.

A PRP list pointer contains the address of a PRP list, structured as a linear array of PRP entries. Each PRP entry in this list describes a segment of physical memory. It's giving organized queen. 👑

Now, each 64-bit PRP entry comprises an address and an offset field. The address always points at the beginning of a 4KB physical memory page, and the offset describes where within that 4KB page the memory segment begins. Only the first element in a PRP list may contain a non-zero offset, implying that all memory segments following the first begin at the start of a 4KB page. Rules are rules. 🌈

Each PRP element normally describes 4KB of physical memory, with exceptions for the first and last elements in the list. If the memory being described by the list begins at a non-zero offset within the first 4KB page, then the first PRP element will contain a non-zero offset indicating where the region begins within the 4KB page. The last memory segment may end before the end of the 4KB segment, depending upon the overall size of the memory being described by the PRP list. It's giving "it depends" but make it hardware. 💀

And since PRP entries lack any indication of size, the overall data buffer length is used to determine where the end of the data memory buffer is located, and how many PRP entries are required to describe it. So basically the length does all the heavy lifting. Ngl that's kind of a slay design choice. 🔥

💜 SEE ALSO 💜

Okay so this function has so many friends, it's literally the most connected function in the driver. Here's the whole group chat:

Kernel file ./drivers/scsi/mpt3sas/mpt3sas_base.c

And the extended fam:

💡 tiny note bestie: this whole page is from ./drivers/scsi/mpt3sas and it's dated October 2026 — so like, future vibes but also very real kernel documentation. The mpt3sas squad is huge and they all live in this one driver. Respect. 🫡

Stay slay, stay contiguous, and remember: PRP1 is the first entry, PRP2 is the backup dancer, and the PRP list is the whole ensemble. Periodt. 💖✨🎀

📦 where this page comes from

nixpkgs unstable: linux-manual 7.3.1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

_base_build_nvme_prp(9)