drm_gem_dma_..._with_handle(9)

📦 version 7.3.1, in nixpkgs unstable

💅 drm_gem_dma_create_with_handle — Kernel API Manual ✨

okay bestie, welcome to the drm_gem_dma_..._with_handle(9) page (yes the title got shortened with ... and no we will not be discussing it, it's giving mysterious). this is the Kernel API Manual and today we're learning how GEM objects get born and handed a little name tag 🎀

🌸 NAME 🌸

drm_gem_dma_create_with_handle — allocate an object with the given size and return a GEM handle to it. that's it, that's the whole vibe. allocate, register, hand back a handle. iconic behavior honestly 👑

✨ SYNOPSIS ✨

struct drm_gem_dma_object * drm_gem_dma_create_with_handle (struct
drm_file *file_priv , struct drm_device *drm , size_t size , uint32_t
*handle );

like, structure-wise: it hands you back a struct drm_gem_dma_object *, and it takes four things. we'll go through them one by one, don't worry 🫶

🦋 ARGUMENTS 🦋

  • file_priv — the DRM file-private structure you're registering the handle for. it's the "whose name tag is this" of it all 💖
  • drm — the DRM device. the main character, the whole device, the icon 🎀
  • size — size of the object to allocate. how much memory we're claiming, fr fr 📏
  • handle — return location for the GEM handle. this is where the shiny new handle gets dropped off for you 🌈

💜 DESCRIPTION 💜

so what does this thing actually do? it creates a DMA GEM object, allocating a chunk of memory as backing store. literally building the whole thing from scratch, no cap ✨

then — and this is the slay part — the GEM object gets added to the list of objects associated with the given file, and a handle to it is returned. it's registered, it's official, it's in the group chat now 💅

and listen: the allocated memory will occupy a contiguous chunk of bus address space. contiguous. one chunk. no gaps. that's the whole point bestie 🔥

for more details, go see drm_gem_dma_create. it's got the lore iykyk 📖

⭐ RETURN ⭐

on success you get a struct drm_gem_dma_object * — yay 🎉

on failure you get a ERR_PTR-encoded negative error code. so like, it's still a pointer, but it's a pointer that's screaming an error at you through encoding. check it, bestie, always check it 😭

🌈 SEE ALSO 🌈

Kernel file ./drivers/gpu/drm/drm_gem_dma_helper.c — that's the home base 🏠

and the whole friend group:

and that's the page!! 🫶 this whole thing lives under ./drivers/gpu/drm, dated October 2026, and the page itself is drm_gem_dma_..._with_handle(9) — go off, kernel docs, you ate 💅💖✨
📦 where this page comes from