Linux I2C and DMA

Given that I2C is a low-speed bus, over which the majority of messagestransferred are small, it is not considered a prime user of DMA access. At thistime of writing, only 10% of I2C bus master drivers have DMA supportimplemented. And the vast majority of transactions are so small that setting upDMA for it will likely add more overhead than a plain PIO transfer.

Therefore, it isnot mandatory that the buffer of an I2C message is DMA safe.It does not seem reasonable to apply additional burdens when the feature is sorarely used. However, it is recommended to use a DMA-safe buffer if yourmessage size is likely applicable for DMA. Most drivers have this thresholdaround 8 bytes (as of today, this is mostly an educated guess, however). Forany message of 16 byte or larger, it is probably a really good idea. Pleasenote that other subsystems you use might add requirements. E.g., if yourI2C bus master driver is using USB as a bridge, then you need to have DMAsafe buffers always, because USB requires it.

Clients

For clients, if you use a DMA safe buffer in i2c_msg, set the I2C_M_DMA_SAFEflag with it. Then, the I2C core and drivers know they can safely operate DMAon it. Note that using this flag is optional. I2C host drivers which are notupdated to use this flag will work like before. And like before, they riskusing an unsafe DMA buffer. To improve this situation, using I2C_M_DMA_SAFE inmore and more clients and host drivers is the planned way forward. Note alsothat setting this flag makes only sense in kernel space. User space data iscopied into kernel space anyhow. The I2C core makes sure the destinationbuffers in kernel space are always DMA capable. Also, when the core emulatesSMBus transactions via I2C, the buffers for block transfers are DMA safe. Usersofi2c_master_send() andi2c_master_recv() functions can now use DMA safevariants (i2c_master_send_dmasafe() andi2c_master_recv_dmasafe()) once theyknow their buffers are DMA safe. Users ofi2c_transfer() must set theI2C_M_DMA_SAFE flag manually.

Masters

Bus master drivers wishing to implement safe DMA can use helper functions fromthe I2C core. One gives you a DMA-safe buffer for a given i2c_msg as long as acertain threshold is met:

dma_buf = i2c_get_dma_safe_msg_buf(msg, threshold_in_byte);

If a buffer is returned, it is either msg->buf for the I2C_M_DMA_SAFE case or abounce buffer. But you don’t need to care about that detail, just use thereturned buffer. If NULL is returned, the threshold was not met or a bouncebuffer could not be allocated. Fall back to PIO in that case.

In any case, a buffer obtained from above needs to be released. Another helperfunction ensures a potentially used bounce buffer is freed:

i2c_put_dma_safe_msg_buf(dma_buf, msg, xferred);

The last argument ‘xferred’ controls if the buffer is synced back to themessage or not. No syncing is needed in cases setting up DMA had an error andthere was no data transferred.

The bounce buffer handling from the core is generic and simple. It will alwaysallocate a new bounce buffer. If you want a more sophisticated handling (e.g.reusing pre-allocated buffers), you are free to implement your own.

Please also check the in-kernel documentation for details. The i2c-sh_mobiledriver can be used as a reference example how to use the above helpers.

Final note: If you plan to use DMA with I2C (or with anything else, actually)make sure you have CONFIG_DMA_API_DEBUG enabled during development. It can helpyou find various issues which can be complex to debug otherwise.