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