1 ================= 1 =================
2 Linux I2C and DMA 2 Linux I2C and DMA
3 ================= 3 =================
4 4
5 Given that I2C is a low-speed bus, over which 5 Given that I2C is a low-speed bus, over which the majority of messages
6 transferred are small, it is not considered a 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 dr 7 time of writing, only 10% of I2C bus master drivers have DMA support
8 implemented. And the vast majority of transact 8 implemented. And the vast majority of transactions are so small that setting up
9 DMA for it will likely add more overhead than 9 DMA for it will likely add more overhead than a plain PIO transfer.
10 10
11 Therefore, it is *not* mandatory that the buff 11 Therefore, it is *not* mandatory that the buffer of an I2C message is DMA safe.
12 It does not seem reasonable to apply additiona 12 It does not seem reasonable to apply additional burdens when the feature is so
13 rarely used. However, it is recommended to use 13 rarely used. However, it is recommended to use a DMA-safe buffer if your
14 message size is likely applicable for DMA. Mos 14 message size is likely applicable for DMA. Most drivers have this threshold
15 around 8 bytes (as of today, this is mostly an 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 probab 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 r 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 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. 19 safe buffers always, because USB requires it.
20 20
21 Clients 21 Clients
22 ------- 22 -------
23 23
24 For clients, if you use a DMA safe buffer in i 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 k 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. 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 27 updated to use this flag will work like before. And like before, they risk
28 using an unsafe DMA buffer. To improve this si 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 29 more and more clients and host drivers is the planned way forward. Note also
30 that setting this flag makes only sense in ker 30 that setting this flag makes only sense in kernel space. User space data is
31 copied into kernel space anyhow. The I2C core 31 copied into kernel space anyhow. The I2C core makes sure the destination
32 buffers in kernel space are always DMA capable 32 buffers in kernel space are always DMA capable. Also, when the core emulates
33 SMBus transactions via I2C, the buffers for bl 33 SMBus transactions via I2C, the buffers for block transfers are DMA safe. Users
34 of i2c_master_send() and i2c_master_recv() fun 34 of i2c_master_send() and i2c_master_recv() functions can now use DMA safe
35 variants (i2c_master_send_dmasafe() and i2c_ma 35 variants (i2c_master_send_dmasafe() and i2c_master_recv_dmasafe()) once they
36 know their buffers are DMA safe. Users of i2c_ 36 know their buffers are DMA safe. Users of i2c_transfer() must set the
37 I2C_M_DMA_SAFE flag manually. 37 I2C_M_DMA_SAFE flag manually.
38 38
39 Masters 39 Masters
40 ------- 40 -------
41 41
42 Bus master drivers wishing to implement safe D 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 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:: 44 certain threshold is met::
45 45
46 dma_buf = i2c_get_dma_safe_msg_buf(msg 46 dma_buf = i2c_get_dma_safe_msg_buf(msg, threshold_in_byte);
47 47
48 If a buffer is returned, it is either msg->buf 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 abou 49 bounce buffer. But you don't need to care about that detail, just use the
50 returned buffer. If NULL is returned, the thre 50 returned buffer. If NULL is returned, the threshold was not met or a bounce
51 buffer could not be allocated. Fall back to PI 51 buffer could not be allocated. Fall back to PIO in that case.
52 52
53 In any case, a buffer obtained from above need 53 In any case, a buffer obtained from above needs to be released. Another helper
54 function ensures a potentially used bounce buf 54 function ensures a potentially used bounce buffer is freed::
55 55
56 i2c_put_dma_safe_msg_buf(dma_buf, msg, 56 i2c_put_dma_safe_msg_buf(dma_buf, msg, xferred);
57 57
58 The last argument 'xferred' controls if the bu 58 The last argument 'xferred' controls if the buffer is synced back to the
59 message or not. No syncing is needed in cases 59 message or not. No syncing is needed in cases setting up DMA had an error and
60 there was no data transferred. 60 there was no data transferred.
61 61
62 The bounce buffer handling from the core is ge 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 mo 63 allocate a new bounce buffer. If you want a more sophisticated handling (e.g.
64 reusing pre-allocated buffers), you are free t 64 reusing pre-allocated buffers), you are free to implement your own.
65 65
66 Please also check the in-kernel documentation 66 Please also check the in-kernel documentation for details. The i2c-sh_mobile
67 driver can be used as a reference example how 67 driver can be used as a reference example how to use the above helpers.
68 68
69 Final note: If you plan to use DMA with I2C (o 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 enable 70 make sure you have CONFIG_DMA_API_DEBUG enabled during development. It can help
71 you find various issues which can be complex t 71 you find various issues which can be complex to debug otherwise.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.