ENUM DMA_RESIDUE_GRANULARITY(9)

💅 enum dma_residue_granularity — kernel API manual, but make it make sense

okay so bestie, this is page 9 of the kernel API manual, enum dma_residue_granularity(9), and it's literally all about how precisely a DMA channel can tell you how much of your transfer is left. that's the whole vibe. granularity = how fine-grained the tea is. 🎀

---

✨ NAME ✨

enum dma_residue_granularity — the granularity of the reported transfer residue 🦋

---

🌸 SYNOPSIS 🌸

enum dma_residue_granularity {
    DMA_RESIDUE_GRANULARITY_DESCRIPTOR ,
    DMA_RESIDUE_GRANULARITY_SEGMENT ,
    DMA_RESIDUE_GRANULARITY_BURST

};

like, that's the whole enum. three little members. iconic behavior honestly. ✨

---

👑 Constants 👑

🎀 DMA_RESIDUE_GRANULARITY_DESCRIPTOR

ok so residue reporting is not supported, periodt. the DMA channel can only tell you whether a descriptor has been completed or not — that's it, that's the whole update. which means residue reporting is not supported by this channel, and the residue field of the dma_tx_state field will always be 0. 😭 no cap, always zero.

🧚 DMA_RESIDUE_GRANULARITY_SEGMENT

residue gets updated after each successfully completed segment of the transfer — and for cyclic transfers, that's after each period, iykyk. 🌈

how's it implemented? typically by having the hardware fire an interrupt after each transferred segment, and then the driver updates the outstanding residue by the size of the segment. cute, right?

another possibility: if the hardware supports scatter-gather and the segment descriptor has a field that gets set after the segment has been completed, the driver then counts the number of segments without the flag set to compute the residue. lowkey clever. 💜

🔥 DMA_RESIDUE_GRANULARITY_BURST

residue gets updated after each transferred burst. 🫶

this is typically only supported if the hardware has a progress register of some sort — e.g. a register with the current read/write address, or a register with the amount of bursts/beats/bytes that have been transferred or still need to be transferred. if your hardware doesn't have that? sorry bestie, no burst-level residue for you. 💀

---

🌟 SEE ALSO 🌟

kernel file ./include/linux/dmaengine.h, plus the whole friend group:

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), enum dma_desc_metadata_mode(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), 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)

---

🫶 quick vibe check before you go: this page lives in ./include/linux, it's dated October 2026, and it's the enum dma_res..._granularity(9) page — go read the neighbours too, they ate. 💖

slay, you now understand DMA residue granularity. go forth and report your residue responsibly. 👑✨