PRIME HELPERS(9)

🦋 PRIME Helpers 🦋

okay so this is straight out of the Kernel API Manual (section 9, kernel-land bestie ✨) and it's literally all about PRIME helpers — the lil glue functions that make dma-buf exporting and importing not a total nightmare.

Here's the vibe 💅 Drivers can implement drm_gem_object_funcs.export and drm_driver.gem_prime_import in terms of simpler APIs by using the helper functions drm_gem_prime_export and drm_gem_prime_import. Those two implement dma-buf support in terms of some lower-level helpers, and those lower-level helpers are again exported so drivers can use them individually. iykyk 🫶

---

✨ Exporting buffers ✨

So like, optional pinning of buffers is handled at dma-buf attach and detach time, in drm_gem_map_attach and drm_gem_map_detach. The backing storage itself is handled by drm_gem_map_dma_buf and drm_gem_unmap_dma_buf, which relies on drm_gem_object_funcs.get_sg_table. 🎀

And heads up: if drm_gem_object_funcs.get_sg_table is unimplemented, exports into another device are rejected. 🚫 no cap, that's just how it is.

For kernel-internal access there's drm_gem_dmabuf_vmap and drm_gem_dmabuf_vunmap. Userspace mmap support is provided by drm_gem_dmabuf_mmap. slay 💅

⚠️ okay important: these export helpers can only be used if the underlying backing storage is fully coherent and either permanently pinned, or it's safe to pin it indefinitely. check that vibe first bestie, don't just send it 😭

🙈 FIXME: the underlying helper functions are named rather inconsistently. (not me side-eyeing the naming conventions… 💀 it's giving chaos but we move)

---

🎀 Importing buffers 🎀

Importing dma-bufs using drm_gem_prime_import relies on drm_driver.gem_prime_import_sg_table. that's the whole hinge of it 🔥

⚠️ and note — similarly to the export helpers, this permanently pins the underlying backing storage. Which is okay for scanout, but is not the best option for sharing lots of buffers for rendering. fr fr, keep that in mind before you go sharing everything 🌸

---

💅 SEE ALSO 💅

• Kernel file ./drivers/gpu/drm/drm_prime.c overview and lifetime rules(9)
• drm_gem_dmabuf_export(9)
• drm_gem_dmabuf_release(9)
• drm_gem_prime_fd_to_handle(9)
• drm_gem_prime_handle_to_dmabuf(9)
• drm_gem_prime_handle_to_fd(9)
• drm_gem_map_attach(9)
• drm_gem_map_detach(9)
• drm_gem_map_dma_buf(9)
• drm_gem_unmap_dma_buf(9)
• drm_gem_dmabuf_vmap(9)
• drm_gem_dmabuf_vunmap(9)
• drm_gem_prime_mmap(9)
• drm_gem_dmabuf_mmap(9)
• drm_prime_pages_to_sg(9)
• drm_prime_get_contiguous_size(9)
• drm_gem_prime_export(9)
• drm_gem_is_prime_exported_dma_buf(9)
• drm_gem_prime_import_dev(9)
• drm_gem_prime_import(9)
• drm_prime_sg_to_page_array(9)
• drm_prime_sg_to_dma_addr_array(9)
• drm_prime_gem_destroy(9)

---

mwah 💖 this whole page lives in ./drivers/gpu/drm, it's dated October 2026, and yeah — it's PRIME Helpers(9), periodt. go read the source bestie, it ate 🌈👑