ENUM DMA_DESC_METADATA_MODE(9)

🌸 enum dma_desc_metadata_mode(9) 🌸

okay so real talk, this one is from the Kernel API Manual and it's all about how a DMA descriptor handles its metadata bestie. lowkey important, highkey under-documented. let's get into it 💅

---

✨ NAME ✨

enum dma_desc_metadata_mode — the per-descriptor metadata mode types that are supported, and btw @DESC_METADATA_CLIENT means the metadata buffer is allocated/provided by the client driver and it's attached (via the dmaengine_desc_attach_metadata() helper) to the descriptor. that's it, that's the vibe 🫶

---

🎀 SYNOPSIS 🎀

enum dma_desc_metadata_mode {
    DESC_METADATA_NONE ,
    DESC_METADATA_CLIENT ,
    DESC_METADATA_ENGINE

};

---

⭐ Constants ⭐

• DESC_METADATA_NONE — -- undescribed -- (yes literally, the docs did not come through for us here 😭)
• DESC_METADATA_CLIENT — -- undescribed -- (same, no cap, that's what it says 🙈)
• DESC_METADATA_ENGINE — -- undescribed -- (again 🩷)

---

🦋 Description 🦋

so if you're a client driver and you're interested in using this mode, here's the little routine you can follow, per the docs ✨

💖 DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:

1. prepare the descriptor (dmaengine_prep_*), then construct the metadata in the client's buffer — yes both, in that order, don't @ me
2. use dmaengine_desc_attach_metadata to attach the buffer to the descriptor
3. submit the transfer

💖 DMA_DEV_TO_MEM:

1. prepare the descriptor (dmaengine_prep_*)
2. use dmaengine_desc_attach_metadata to attach the buffer to the descriptor
3. submit the transfer
4. when the transfer is completed, the metadata should be available in the attached buffer 👑

then we got DESC_METADATA_ENGINE — in this one the metadata buffer is allocated/managed by the DMA driver. the client driver can ask for the pointer, the maximum size, and the currently used size of the metadata, and can directly update or read it. dmaengine_desc_get_metadata_ptr and dmaengine_desc_set_metadata_len are provided as helper functions for exactly this. iconic of them fr fr 💅

---

💀 Note 💀

⚠️ big one: the metadata area for the descriptor is no longer valid after the transfer has been completed (it's valid up to the point when the completion callback returns, if that's how you're using it). like, the window closes, bestie 😭

client drivers interested in using this mode can follow this lil recipe:

🌈 DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:

1. prepare the descriptor (dmaengine_prep_*)
2. use dmaengine_desc_get_metadata_ptr to get the pointer to the engine's metadata area
3. update the metadata at the pointer
4. use dmaengine_desc_set_metadata_len to tell the DMA engine the amount of data the client has placed into the metadata buffer
5. submit the transfer

🌈 DMA_DEV_TO_MEM:

1. prepare the descriptor (dmaengine_prep_*)
2. submit the transfer
3. on transfer completion, use dmaengine_desc_get_metadata_ptr to get the pointer to the engine's metadata area
4. Read out the metadata from the pointer (yes, Read with a capital R, we respect the original ✨)

🚨 Warning: the two modes are not compatible and clients must use one mode for a descriptor. one. not both. pick a lane 🫶

---

👑 SEE ALSO 👑

kernel file ./include/linux/dmaengine.h, and also all of these cuties:

dma_cookie_t(9), enum dma_status(9), enum dma_transaction_type(9), enum dma_transfer_direction(9), struct data_chunk(9), struct dma_interleaved_template(9), struct dma_vec(9), enum dma_ctrl_flags(9), enum sum_check_bits(9), enum sum_check_flags(9), struct dma_chan_percpu(9), struct dma_router(9), struct dma_chan(9), struct dma_chan_dev(9), enum dma_slave_buswidth(9), struct dma_slave_config(9), enum dma_residue_granularity(9), struct dma_slave_caps(9), dma_filter_fn(9), struct dma_async_tx_descriptor(9), struct dma_tx_state(9), enum dmaengine_alignment(9), struct dma_slave_map(9), struct dma_filter(9), struct dma_device(9), dmaengine_prep_peripheral_dma_vec(9), dmaengine_prep_config_sg_safe(9), dmaengine_prep_config_single_safe(9), dmaengine_prep_dma_memset(9), dmaengine_terminate_all(9), dmaengine_terminate_async(9), dmaengine_synchronize(9), dmaengine_terminate_sync(9), dma_async_issue_pending(9), dma_async_is_tx_complete(9), dma_async_is_complete(9)

---

kisses from ./include/linux, dated October 2026, signed off as enum dma_desc_metadata_mode(9) — catch you in the next transfer, bestie 🧚‍♀️💜