OVERVIEW AND LIFETIME RULES(9)

🦋 overview and lifetime rules(9) 🦋

okay bestie, this is the Kernel API Manual page for overview and lifetime rules(9), and it's literally about how PRIME file descriptors and GEM buffer lifetimes work. no cap, it's giving "shared buffers but make it secure." 💅

Just like GEM global names, PRIME file descriptors are also used to share buffer objects across processes. They come with extra security too: because file descriptors must be explicitly sent over UNIX domain sockets to be shared between applications, they can't be guessed like the globally unique GEM names. slay for safety. 🔥

Drivers that support the PRIME API implement the drm_gem_object_funcs.export and drm_driver.gem_prime_import hooks. Also, dma_buf_ops implementations for drivers are all individually exported for drivers which need to overwrite or reimplement some of them. iykyk. ✨

🧮 Reference Counting for GEM Drivers 🧮

On the export, the dma_buf holds a reference to the exported buffer object, usually a drm_gem_object. It takes this reference in the PRIME_HANDLE_TO_FD IOCTL, when it first calls drm_gem_object_funcs.export and stores the exporting GEM object in the dma_buf.priv field. This reference needs to be released when the final reference to the dma_buf itself is dropped and its dma_buf_ops.release function is called. For GEM-based drivers, the dma_buf should be exported using drm_gem_dmabuf_export and then released by drm_gem_dmabuf_release. 🎀

So the chain of references always flows in one direction, avoiding loops: importing GEM object -> dma-buf -> exported GEM bo. periodt, no messy little reference cycles. 🌀

A further complication are the lookup caches for import and export. These are required to guarantee that any given object will always have only one unique userspace handle. This is required to allow userspace to detect duplicated imports, since some GEM drivers do fail command submissions if a given buffer object is listed more than once. These import and export caches in drm_prime_file_private only retain a weak reference, which is cleaned up when the corresponding object is released. weak refs doing their little cleanup moment 🧹✨

Self-importing: if userspace is using PRIME as a replacement for flink, then it will get a fd->handle request for a GEM object that it created. Drivers should detect this situation and return back the underlying object from the dma-buf private. For GEM based drivers this is handled in drm_gem_prime_import already. iconic, honestly 💖

👀 SEE ALSO 👀

Kernel file: ./drivers/gpu/drm/drm_prime.c

• 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)
• PRIME Helpers(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 page lives under ./drivers/gpu/drm and is dated October 2026. stay hydrated, bestie 🫶💖