0001 =================
0002 Linux I2C and DMA
0003 =================
0004
0005 Given that I2C is a low-speed bus, over which the majority of messages
0006 transferred are small, it is not considered a prime user of DMA access. At this
0007 time of writing, only 10% of I2C bus master drivers have DMA support
0008 implemented. And the vast majority of transactions are so small that setting up
0009 DMA for it will likely add more overhead than a plain PIO transfer.
0010
0011 Therefore, it is *not* mandatory that the buffer of an I2C message is DMA safe.
0012 It does not seem reasonable to apply additional burdens when the feature is so
0013 rarely used. However, it is recommended to use a DMA-safe buffer if your
0014 message size is likely applicable for DMA. Most drivers have this threshold
0015 around 8 bytes (as of today, this is mostly an educated guess, however). For
0016 any message of 16 byte or larger, it is probably a really good idea. Please
0017 note that other subsystems you use might add requirements. E.g., if your
0018 I2C bus master driver is using USB as a bridge, then you need to have DMA
0019 safe buffers always, because USB requires it.
0020
0021 Clients
0022 -------
0023
0024 For clients, if you use a DMA safe buffer in i2c_msg, set the I2C_M_DMA_SAFE
0025 flag with it. Then, the I2C core and drivers know they can safely operate DMA
0026 on it. Note that using this flag is optional. I2C host drivers which are not
0027 updated to use this flag will work like before. And like before, they risk
0028 using an unsafe DMA buffer. To improve this situation, using I2C_M_DMA_SAFE in
0029 more and more clients and host drivers is the planned way forward. Note also
0030 that setting this flag makes only sense in kernel space. User space data is
0031 copied into kernel space anyhow. The I2C core makes sure the destination
0032 buffers in kernel space are always DMA capable. Also, when the core emulates
0033 SMBus transactions via I2C, the buffers for block transfers are DMA safe. Users
0034 of i2c_master_send() and i2c_master_recv() functions can now use DMA safe
0035 variants (i2c_master_send_dmasafe() and i2c_master_recv_dmasafe()) once they
0036 know their buffers are DMA safe. Users of i2c_transfer() must set the
0037 I2C_M_DMA_SAFE flag manually.
0038
0039 Masters
0040 -------
0041
0042 Bus master drivers wishing to implement safe DMA can use helper functions from
0043 the I2C core. One gives you a DMA-safe buffer for a given i2c_msg as long as a
0044 certain threshold is met::
0045
0046 dma_buf = i2c_get_dma_safe_msg_buf(msg, threshold_in_byte);
0047
0048 If a buffer is returned, it is either msg->buf for the I2C_M_DMA_SAFE case or a
0049 bounce buffer. But you don't need to care about that detail, just use the
0050 returned buffer. If NULL is returned, the threshold was not met or a bounce
0051 buffer could not be allocated. Fall back to PIO in that case.
0052
0053 In any case, a buffer obtained from above needs to be released. Another helper
0054 function ensures a potentially used bounce buffer is freed::
0055
0056 i2c_put_dma_safe_msg_buf(dma_buf, msg, xferred);
0057
0058 The last argument 'xferred' controls if the buffer is synced back to the
0059 message or not. No syncing is needed in cases setting up DMA had an error and
0060 there was no data transferred.
0061
0062 The bounce buffer handling from the core is generic and simple. It will always
0063 allocate a new bounce buffer. If you want a more sophisticated handling (e.g.
0064 reusing pre-allocated buffers), you are free to implement your own.
0065
0066 Please also check the in-kernel documentation for details. The i2c-sh_mobile
0067 driver can be used as a reference example how to use the above helpers.
0068
0069 Final note: If you plan to use DMA with I2C (or with anything else, actually)
0070 make sure you have CONFIG_DMA_API_DEBUG enabled during development. It can help
0071 you find various issues which can be complex to debug otherwise.
