Linux dma driver dma_cap_set,dma_cap_zero

Question

I'm writing a linux device driver for an dma and while going across the source of dma drivers in LXR i came across the functions dma_cap_zero and dma_cap_set and whole family of dma_cap_* . What are these functions ? Also there a structure called dma_transaction_type

enum dma_transaction_type {
         DMA_MEMCPY,
          DMA_XOR,
          DMA_PQ,
          DMA_XOR_VAL,
         DMA_PQ_VAL,
          DMA_MEMSET,
         DMA_INTERRUPT,
          DMA_SG,
          DMA_PRIVATE,
          DMA_ASYNC_TX,
          DMA_SLAVE,
          DMA_CYCLIC,
          DMA_INTERLEAVE,
  /* last transaction type for creation of the capabilities mask */
          DMA_TX_TYPE_END,
  };

What do the enum types represent ?

Answer 1

These functions are actually preprocessor macro functions, and are used by slave DMA devices to configure and request DMA channels.

Here is an example of them being used:

dma_cap_mask_t mask;

dma_cap_zero(mask);
dma_cap_set(DMA_MEMCPY,mask);
dma_chan1 = dma_request_channel(mask,0,NULL);

This code is from http://ecourse.wikidot.com/dmatest.

First, there's the datatype dma_cap_mask_t defined in dmaengine.h, ~line 233. It is a type of bitfield where the bits indicate what kind of transfers a DMA channel is capable of.

In the code snippet above, which occurs in the linked code's __init routine, the mask is declared to be of the special dma_cap_mask_t datatype. Then the dma_cap_zero() function is called and mask is passed to it.

I believe dma_cap_zero is simply zeroing out the capability mask. It is defined in dmaengine.h, ~line 733. The function has returns void, and I think is zeroing the bitfield. I'm not entirely sure, though, because kernel code is a massive pile of macro magic that I have a hard time deciphering sometimes.

After the mask is zeroed, or initialized in some fashion by dma_cap_zero, the capabilities of the channel must be set. The dma_cap_set function accomplishes this. It takes the request channel type and sets the mask according to the capabilities required to perform that type of transaction. If you're confused about how the enumeration is being used, take a look at this page for a simple review of enums. In this case, it looks like the values in the enum are used to describe different types of DMA transactions, each of which need a different set of "capabilities". The dma_set_cap function sets the capabilities mask according to the capabilities required for the specified transaction type.

Once the mask is properly set for the type of DMA transactions you want to perform, you request the DMA channel.

The other dma_cap* macros are used to perform other types of manipulations on the DMA mask without really knowing what's going on behind the scenes. These types of macros are all over the place in the kernel code, for many more manipulations that just DMA. They allow device drivers to get things done in the kernel without having to worry about how the kernel does it.