Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/816407/?format=api
{ "id": 816407, "url": "http://patchwork.ozlabs.org/api/patches/816407/?format=api", "web_url": "http://patchwork.ozlabs.org/project/linux-i2c/patch/20170920185956.13874-4-wsa+renesas@sang-engineering.com/", "project": { "id": 35, "url": "http://patchwork.ozlabs.org/api/projects/35/?format=api", "name": "Linux I2C development", "link_name": "linux-i2c", "list_id": "linux-i2c.vger.kernel.org", "list_email": "linux-i2c@vger.kernel.org", "web_url": "", "scm_url": "", "webscm_url": "", "list_archive_url": "", "list_archive_url_format": "", "commit_url_format": "" }, "msgid": "<20170920185956.13874-4-wsa+renesas@sang-engineering.com>", "list_archive_url": null, "date": "2017-09-20T18:59:53", "name": "[RFC,v5,3/6] i2c: add docs to clarify DMA handling", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": false, "hash": "5eb3021322c7415ae8e9cafdbd106999bc8e295f", "submitter": { "id": 69646, "url": "http://patchwork.ozlabs.org/api/people/69646/?format=api", "name": "Wolfram Sang", "email": "wsa+renesas@sang-engineering.com" }, "delegate": null, "mbox": "http://patchwork.ozlabs.org/project/linux-i2c/patch/20170920185956.13874-4-wsa+renesas@sang-engineering.com/mbox/", "series": [ { "id": 4199, "url": "http://patchwork.ozlabs.org/api/series/4199/?format=api", "web_url": "http://patchwork.ozlabs.org/project/linux-i2c/list/?series=4199", "date": "2017-09-20T18:59:56", "name": "i2c: document DMA handling and add helpers for it", "version": 5, "mbox": "http://patchwork.ozlabs.org/series/4199/mbox/" } ], "comments": "http://patchwork.ozlabs.org/api/patches/816407/comments/", "check": "pending", "checks": "http://patchwork.ozlabs.org/api/patches/816407/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<linux-i2c-owner@vger.kernel.org>", "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=<UNKNOWN>)", "Received": [ "from vger.kernel.org (vger.kernel.org [209.132.180.67])\n\tby ozlabs.org (Postfix) with ESMTP id 3xy8HB474vz9s4s\n\tfor <incoming@patchwork.ozlabs.org>;\n\tThu, 21 Sep 2017 05:01:42 +1000 (AEST)", "(majordomo@vger.kernel.org) by vger.kernel.org via listexpand\n\tid S1751779AbdITTB0 (ORCPT <rfc822;incoming@patchwork.ozlabs.org>);\n\tWed, 20 Sep 2017 15:01:26 -0400", "from sauhun.de ([88.99.104.3]:38838 \"EHLO pokefinder.org\"\n\trhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP\n\tid S1751485AbdITTAF (ORCPT <rfc822;linux-i2c@vger.kernel.org>);\n\tWed, 20 Sep 2017 15:00:05 -0400", "from localhost (p54B332E6.dip0.t-ipconnect.de [84.179.50.230])\n\tby pokefinder.org (Postfix) with ESMTPSA id EEA1F2C43A1;\n\tWed, 20 Sep 2017 21:00:02 +0200 (CEST)" ], "From": "Wolfram Sang <wsa+renesas@sang-engineering.com>", "To": "linux-i2c@vger.kernel.org", "Cc": "linux-kernel@vger.kernel.org, linux-renesas-soc@vger.kernel.org,\n\tlinux-iio@vger.kernel.org, linux-input@vger.kernel.org,\n\tlinux-media@vger.kernel.org, dri-devel@lists.freedesktop.org,\n\tWolfram Sang <wsa+renesas@sang-engineering.com>", "Subject": "[RFC PATCH v5 3/6] i2c: add docs to clarify DMA handling", "Date": "Wed, 20 Sep 2017 20:59:53 +0200", "Message-Id": "<20170920185956.13874-4-wsa+renesas@sang-engineering.com>", "X-Mailer": "git-send-email 2.11.0", "In-Reply-To": "<20170920185956.13874-1-wsa+renesas@sang-engineering.com>", "References": "<20170920185956.13874-1-wsa+renesas@sang-engineering.com>", "Sender": "linux-i2c-owner@vger.kernel.org", "Precedence": "bulk", "List-ID": "<linux-i2c.vger.kernel.org>", "X-Mailing-List": "linux-i2c@vger.kernel.org" }, "content": "Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>\n---\n Documentation/i2c/DMA-considerations | 58 ++++++++++++++++++++++++++++++++++++\n 1 file changed, 58 insertions(+)\n create mode 100644 Documentation/i2c/DMA-considerations", "diff": "diff --git a/Documentation/i2c/DMA-considerations b/Documentation/i2c/DMA-considerations\nnew file mode 100644\nindex 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", "prefixes": [ "RFC", "v5", "3/6" ] }