dma-considerations.rst (3649B)
1================= 2Linux I2C and DMA 3================= 4 5Given that I2C is a low-speed bus, over which the majority of messages 6transferred are small, it is not considered a prime user of DMA access. At this 7time of writing, only 10% of I2C bus master drivers have DMA support 8implemented. And the vast majority of transactions are so small that setting up 9DMA for it will likely add more overhead than a plain PIO transfer. 10 11Therefore, it is *not* mandatory that the buffer of an I2C message is DMA safe. 12It does not seem reasonable to apply additional burdens when the feature is so 13rarely used. However, it is recommended to use a DMA-safe buffer if your 14message size is likely applicable for DMA. Most drivers have this threshold 15around 8 bytes (as of today, this is mostly an educated guess, however). For 16any message of 16 byte or larger, it is probably a really good idea. Please 17note that other subsystems you use might add requirements. E.g., if your 18I2C bus master driver is using USB as a bridge, then you need to have DMA 19safe buffers always, because USB requires it. 20 21Clients 22------- 23 24For clients, if you use a DMA safe buffer in i2c_msg, set the I2C_M_DMA_SAFE 25flag with it. Then, the I2C core and drivers know they can safely operate DMA 26on it. Note that using this flag is optional. I2C host drivers which are not 27updated to use this flag will work like before. And like before, they risk 28using an unsafe DMA buffer. To improve this situation, using I2C_M_DMA_SAFE in 29more and more clients and host drivers is the planned way forward. Note also 30that setting this flag makes only sense in kernel space. User space data is 31copied into kernel space anyhow. The I2C core makes sure the destination 32buffers in kernel space are always DMA capable. Also, when the core emulates 33SMBus transactions via I2C, the buffers for block transfers are DMA safe. Users 34of i2c_master_send() and i2c_master_recv() functions can now use DMA safe 35variants (i2c_master_send_dmasafe() and i2c_master_recv_dmasafe()) once they 36know their buffers are DMA safe. Users of i2c_transfer() must set the 37I2C_M_DMA_SAFE flag manually. 38 39Masters 40------- 41 42Bus master drivers wishing to implement safe DMA can use helper functions from 43the I2C core. One gives you a DMA-safe buffer for a given i2c_msg as long as a 44certain threshold is met:: 45 46 dma_buf = i2c_get_dma_safe_msg_buf(msg, threshold_in_byte); 47 48If a buffer is returned, it is either msg->buf for the I2C_M_DMA_SAFE case or a 49bounce buffer. But you don't need to care about that detail, just use the 50returned buffer. If NULL is returned, the threshold was not met or a bounce 51buffer could not be allocated. Fall back to PIO in that case. 52 53In any case, a buffer obtained from above needs to be released. Another helper 54function ensures a potentially used bounce buffer is freed:: 55 56 i2c_put_dma_safe_msg_buf(dma_buf, msg, xferred); 57 58The last argument 'xferred' controls if the buffer is synced back to the 59message or not. No syncing is needed in cases setting up DMA had an error and 60there was no data transferred. 61 62The bounce buffer handling from the core is generic and simple. It will always 63allocate a new bounce buffer. If you want a more sophisticated handling (e.g. 64reusing pre-allocated buffers), you are free to implement your own. 65 66Please also check the in-kernel documentation for details. The i2c-sh_mobile 67driver can be used as a reference example how to use the above helpers. 68 69Final note: If you plan to use DMA with I2C (or with anything else, actually) 70make sure you have CONFIG_DMA_API_DEBUG enabled during development. It can help 71you find various issues which can be complex to debug otherwise.