[{"id":1772176,"web_url":"http://patchwork.ozlabs.org/comment/1772176/","msgid":"<20170920165626.2b41a587@recife.lan>","list_archive_url":null,"date":"2017-09-20T19:56:48","subject":"Re: [RFC PATCH v5 3/6] i2c: add docs to clarify DMA handling","submitter":{"id":69764,"url":"http://patchwork.ozlabs.org/api/people/69764/","name":"Mauro Carvalho Chehab","email":"mchehab@s-opensource.com"},"content":"Em Wed, 20 Sep 2017 20:59:53 +0200\nWolfram Sang escreveu:\n\n> Signed-off-by: Wolfram Sang \n\nDocumentation looks OK on my eyes. So:\n\nReviewed-by: Mauro Carvalho Chehab \n\n> ---\n> Documentation/i2c/DMA-considerations | 58 ++++++++++++++++++++++++++++++++++++\n> 1 file changed, 58 insertions(+)\n> create mode 100644 Documentation/i2c/DMA-considerations\n> \n> diff --git a/Documentation/i2c/DMA-considerations b/Documentation/i2c/DMA-considerations\n> new file mode 100644\n> index 00000000000000..5a63355c6a9b6f\n> --- /dev/null\n> +++ b/Documentation/i2c/DMA-considerations\n> @@ -0,0 +1,58 @@\n> +=================\n> +Linux I2C and DMA\n> +=================\n> +\n> +Given that I2C is a low-speed bus where largely small messages are transferred,\n> +it is not considered a prime user of DMA access. At this time of writing, only\n> +10% of I2C bus master drivers have DMA support implemented. And the vast\n> +majority of transactions are so small that setting up DMA for it will likely\n> +add more overhead than a plain PIO transfer.\n> +\n> +Therefore, it is *not* mandatory that the buffer of an I2C message is DMA safe.\n> +It does not seem reasonable to apply additional burdens when the feature is so\n> +rarely used. However, it is recommended to use a DMA-safe buffer if your\n> +message size is likely applicable for DMA. Most drivers have this threshold\n> +around 8 bytes (as of today, this is mostly an educated guess, however). For\n> +any message of 16 byte or larger, it is probably a really good idea. Please\n> +note that other subsystems you use might add requirements. E.g., if your\n> +I2C bus master driver is using USB as a bridge, then you need to have DMA\n> +safe buffers always, because USB requires it.\n> +\n> +For clients, if you use a DMA safe buffer in i2c_msg, set the I2C_M_DMA_SAFE\n> +flag with it. Then, the I2C core and drivers know they can safely operate DMA\n> +on it. Note that using this flag is optional. I2C host drivers which are not\n> +updated to use this flag will work like before. And like before, they risk\n> +using an unsafe DMA buffer. To improve this situation, using I2C_M_DMA_SAFE in\n> +more and more clients and host drivers is the planned way forward. Note also\n> +that setting this flag makes only sense in kernel space. User space data is\n> +copied into kernel space anyhow. The I2C core makes sure the destination\n> +buffers in kernel space are always DMA capable.\n> +\n> +FIXME: Need to implement i2c_master_{send|receive}_dma and proper buffers for i2c_smbus_xfer_emulated.\n> +\n> +Drivers wishing to implement safe DMA can use helper functions from the I2C\n> +core. One gives you a DMA-safe buffer for a given i2c_msg as long as a certain\n> +threshold is met::\n> +\n> +\tdma_buf = i2c_get_dma_safe_msg_buf(msg, threshold_in_byte);\n> +\n> +If a buffer is returned, it is either msg->buf for the I2C_M_DMA_SAFE case or a\n> +bounce buffer. But you don't need to care about that detail, just use the\n> +returned buffer. If NULL is returned, the threshold was not met or a bounce\n> +buffer could not be allocated. Fall back to PIO in that case.\n> +\n> +In any case, a buffer obtained from above needs to be released. It ensures data\n> +is copied back to the message and a potentially used bounce buffer is freed::\n> +\n> +\ti2c_release_dma_safe_msg_buf(msg, dma_buf);\n> +\n> +The bounce buffer handling from the core is generic and simple. It will always\n> +allocate a new bounce buffer. If you want a more sophisticated handling (e.g.\n> +reusing pre-allocated buffers), you are free to implement your own.\n> +\n> +Please also check the in-kernel documentation for details. The i2c-sh_mobile\n> +driver can be used as a reference example how to use the above helpers.\n> +\n> +Final note: If you plan to use DMA with I2C (or with anything else, actually)\n> +make sure you have CONFIG_DMA_API_DEBUG enabled during development. It can help\n> +you find various issues which can be complex to debug otherwise.\n\n\n\nThanks,\nMauro","headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@bilbo.ozlabs.org","Authentication-Results":"ozlabs.org;\n\tspf=none (mailfrom) smtp.mailfrom=vger.kernel.org\n\t(client-ip=209.132.180.67; helo=vger.kernel.org;\n\tenvelope-from=linux-i2c-owner@vger.kernel.org;\n\treceiver=)","Received":["from vger.kernel.org (vger.kernel.org [209.132.180.67])\n\tby ozlabs.org (Postfix) with ESMTP id 3xy9WC5WZWz9sPm\n\tfor ;\n\tThu, 21 Sep 2017 05:56:59 +1000 (AEST)","(majordomo@vger.kernel.org) by vger.kernel.org via listexpand\n\tid S1751521AbdITT45 (ORCPT );\n\tWed, 20 Sep 2017 15:56:57 -0400","from ec2-52-27-115-49.us-west-2.compute.amazonaws.com\n\t([52.27.115.49]:50785\n\t\"EHLO osg.samsung.com\" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org\n\twith ESMTP id S1751307AbdITT44 (ORCPT\n\t); Wed, 20 Sep 2017 15:56:56 -0400","from localhost (localhost [127.0.0.1])\n\tby osg.samsung.com (Postfix) with ESMTP id E860FA0C9D;\n\tWed, 20 Sep 2017 19:57:23 +0000 (UTC)","from osg.samsung.com ([127.0.0.1])\n\tby localhost (s-opensource.com [127.0.0.1]) (amavisd-new, port 10024)\n\twith ESMTP id 1ZyR18XMiyQw; Wed, 20 Sep 2017 19:57:22 +0000 (UTC)","from recife.lan (unknown [179.183.111.11])\n\tby osg.samsung.com (Postfix) with ESMTPSA id AF331A05F0;\n\tWed, 20 Sep 2017 19:57:20 +0000 (UTC)"],"X-Virus-Scanned":"amavisd-new at osg.samsung.com","Date":"Wed, 20 Sep 2017 16:56:48 -0300","From":"Mauro Carvalho Chehab ","To":"Wolfram Sang ","Cc":"linux-i2c@vger.kernel.org, linux-kernel@vger.kernel.org,\n\tlinux-renesas-soc@vger.kernel.org, linux-iio@vger.kernel.org,\n\tlinux-input@vger.kernel.org, linux-media@vger.kernel.org,\n\tdri-devel@lists.freedesktop.org","Subject":"Re: [RFC PATCH v5 3/6] i2c: add docs to clarify DMA handling","Message-ID":"<20170920165626.2b41a587@recife.lan>","In-Reply-To":"<20170920185956.13874-4-wsa+renesas@sang-engineering.com>","References":"<20170920185956.13874-1-wsa+renesas@sang-engineering.com>\n\t<20170920185956.13874-4-wsa+renesas@sang-engineering.com>","Organization":"Samsung","X-Mailer":"Claws Mail 3.14.1 (GTK+ 2.24.31; x86_64-redhat-linux-gnu)","MIME-Version":"1.0","Content-Type":"text/plain; charset=US-ASCII","Content-Transfer-Encoding":"7bit","Sender":"linux-i2c-owner@vger.kernel.org","Precedence":"bulk","List-ID":"","X-Mailing-List":"linux-i2c@vger.kernel.org"}},{"id":1772825,"web_url":"http://patchwork.ozlabs.org/comment/1772825/","msgid":"<20170921150821.000036a3@huawei.com>","list_archive_url":null,"date":"2017-09-21T14:08:21","subject":"Re: [RFC PATCH v5 3/6] i2c: add docs to clarify DMA handling","submitter":{"id":71988,"url":"http://patchwork.ozlabs.org/api/people/71988/","name":"Jonathan Cameron","email":"Jonathan.Cameron@huawei.com"},"content":"On Wed, 20 Sep 2017 16:56:48 -0300\nMauro Carvalho Chehab wrote:\n\n> Em Wed, 20 Sep 2017 20:59:53 +0200\n> Wolfram Sang escreveu:\n> \n> > Signed-off-by: Wolfram Sang \n> \n> Documentation looks OK on my eyes. So:\n> \n> Reviewed-by: Mauro Carvalho Chehab \n\nReally minor suggestion inline. I don't really care either way as\nwhat you had is perfectly comprehensible. \n\nReviewed-by: Jonathan Cameron \n\n> \n> > ---\n> > Documentation/i2c/DMA-considerations | 58 ++++++++++++++++++++++++++++++++++++\n> > 1 file changed, 58 insertions(+)\n> > create mode 100644 Documentation/i2c/DMA-considerations\n> > \n> > diff --git a/Documentation/i2c/DMA-considerations b/Documentation/i2c/DMA-considerations\n> > new file mode 100644\n> > index 00000000000000..5a63355c6a9b6f\n> > --- /dev/null\n> > +++ b/Documentation/i2c/DMA-considerations\n> > @@ -0,0 +1,58 @@\n> > +=================\n> > +Linux I2C and DMA\n> > +=================\n> > +\n> > +Given that I2C is a low-speed bus where largely small messages are transferred,\n\nSlightly nicer as:\n\nGiven that i2c is a low-speed bus, over which the majority of messages transferred are small,\n\n> > +it is not considered a prime user of DMA access. At this time of writing, only\n> > +10% of I2C bus master drivers have DMA support implemented. And the vast\n> > +majority of transactions are so small that setting up DMA for it will likely\n> > +add more overhead than a plain PIO transfer.\n> > +\n> > +Therefore, it is *not* mandatory that the buffer of an I2C message is DMA safe.\n> > +It does not seem reasonable to apply additional burdens when the feature is so\n> > +rarely used. However, it is recommended to use a DMA-safe buffer if your\n> > +message size is likely applicable for DMA. Most drivers have this threshold\n> > +around 8 bytes (as of today, this is mostly an educated guess, however). For\n> > +any message of 16 byte or larger, it is probably a really good idea. Please\n> > +note that other subsystems you use might add requirements. E.g., if your\n> > +I2C bus master driver is using USB as a bridge, then you need to have DMA\n> > +safe buffers always, because USB requires it.\n> > +\n> > +For clients, if you use a DMA safe buffer in i2c_msg, set the I2C_M_DMA_SAFE\n> > +flag with it. Then, the I2C core and drivers know they can safely operate DMA\n> > +on it. Note that using this flag is optional. I2C host drivers which are not\n> > +updated to use this flag will work like before. And like before, they risk\n> > +using an unsafe DMA buffer. To improve this situation, using I2C_M_DMA_SAFE in\n> > +more and more clients and host drivers is the planned way forward. Note also\n> > +that setting this flag makes only sense in kernel space. User space data is\n> > +copied into kernel space anyhow. The I2C core makes sure the destination\n> > +buffers in kernel space are always DMA capable.\n> > +\n> > +FIXME: Need to implement i2c_master_{send|receive}_dma and proper buffers for i2c_smbus_xfer_emulated.\n> > +\n> > +Drivers wishing to implement safe DMA can use helper functions from the I2C\n> > +core. One gives you a DMA-safe buffer for a given i2c_msg as long as a certain\n> > +threshold is met::\n> > +\n> > +\tdma_buf = i2c_get_dma_safe_msg_buf(msg, threshold_in_byte);\n> > +\n> > +If a buffer is returned, it is either msg->buf for the I2C_M_DMA_SAFE case or a\n> > +bounce buffer. But you don't need to care about that detail, just use the\n> > +returned buffer. If NULL is returned, the threshold was not met or a bounce\n> > +buffer could not be allocated. Fall back to PIO in that case.\n> > +\n> > +In any case, a buffer obtained from above needs to be released. It ensures data\n> > +is copied back to the message and a potentially used bounce buffer is freed::\n> > +\n> > +\ti2c_release_dma_safe_msg_buf(msg, dma_buf);\n> > +\n> > +The bounce buffer handling from the core is generic and simple. It will always\n> > +allocate a new bounce buffer. If you want a more sophisticated handling (e.g.\n> > +reusing pre-allocated buffers), you are free to implement your own.\n> > +\n> > +Please also check the in-kernel documentation for details. The i2c-sh_mobile\n> > +driver can be used as a reference example how to use the above helpers.\n> > +\n> > +Final note: If you plan to use DMA with I2C (or with anything else, actually)\n> > +make sure you have CONFIG_DMA_API_DEBUG enabled during development. It can help\n> > +you find various issues which can be complex to debug otherwise. \n> \n> \n> \n> Thanks,\n> Mauro\n> --\n> To unsubscribe from this list: send the line \"unsubscribe linux-iio\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at http://vger.kernel.org/majordomo-info.html","headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@bilbo.ozlabs.org","Authentication-Results":"ozlabs.org;\n\tspf=none (mailfrom) smtp.mailfrom=vger.kernel.org\n\t(client-ip=209.132.180.67; helo=vger.kernel.org;\n\tenvelope-from=linux-i2c-owner@vger.kernel.org;\n\treceiver=)","Received":["from vger.kernel.org (vger.kernel.org [209.132.180.67])\n\tby ozlabs.org (Postfix) with ESMTP id 3xydlY2CPrz9s7g\n\tfor ;\n\tFri, 22 Sep 2017 00:09:29 +1000 (AEST)","(majordomo@vger.kernel.org) by vger.kernel.org via listexpand\n\tid S1751629AbdIUOIr (ORCPT );\n\tThu, 21 Sep 2017 10:08:47 -0400","from szxga04-in.huawei.com ([45.249.212.190]:6970 \"EHLO\n\tszxga04-in.huawei.com\" rhost-flags-OK-OK-OK-OK) by vger.kernel.org\n\twith ESMTP id S1751865AbdIUOIo (ORCPT\n\t); Thu, 21 Sep 2017 10:08:44 -0400","from 172.30.72.58 (EHLO DGGEMS406-HUB.china.huawei.com)\n\t([172.30.72.58])\n\tby dggrg04-dlp.huawei.com (MOS 4.4.6-GA FastPath queued)\n\twith ESMTP id DHR62415; Thu, 21 Sep 2017 22:08:38 +0800 (CST)","from localhost (10.206.48.115) by DGGEMS406-HUB.china.huawei.com\n\t(10.3.19.206) with Microsoft SMTP Server (TLS) id 14.3.301.0;\n\tThu, 21 Sep 2017 22:08:32 +0800"],"Date":"Thu, 21 Sep 2017 15:08:21 +0100","From":"Jonathan Cameron ","To":"Mauro Carvalho Chehab ","CC":"Wolfram Sang ,\n\t, ,\n\t, ,\n\t, ,\n\t","Subject":"Re: [RFC PATCH v5 3/6] i2c: add docs to clarify DMA handling","Message-ID":"<20170921150821.000036a3@huawei.com>","In-Reply-To":"<20170920165626.2b41a587@recife.lan>","References":"<20170920185956.13874-1-wsa+renesas@sang-engineering.com>\n\t<20170920185956.13874-4-wsa+renesas@sang-engineering.com>\n\t<20170920165626.2b41a587@recife.lan>","Organization":"Huawei","X-Mailer":"Claws Mail 3.15.0 (GTK+ 2.24.31; x86_64-w64-mingw32)","MIME-Version":"1.0","Content-Type":"text/plain; charset=\"US-ASCII\"","Content-Transfer-Encoding":"7bit","X-Originating-IP":"[10.206.48.115]","X-CFilter-Loop":"Reflected","X-Mirapoint-Virus-RAPID-Raw":"score=unknown(0),\n\trefid=str=0001.0A020202.59C3C7E6.0203, ss=1, re=0.000, recu=0.000,\n\treip=0.000, cl=1, cld=1, fgs=0, ip=0.0.0.0,\n\tso=2014-11-16 11:51:01, dmn=2013-03-21 17:37:32","X-Mirapoint-Loop-Id":"e78acd8237593e4a332191d705c96012","Sender":"linux-i2c-owner@vger.kernel.org","Precedence":"bulk","List-ID":"","X-Mailing-List":"linux-i2c@vger.kernel.org"}}]