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