From patchwork Mon Oct 17 17:22:27 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Dmitry Osipenko X-Patchwork-Id: 3643 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:4ac7:0:0:0:0:0 with SMTP id y7csp1562657wrs; Mon, 17 Oct 2022 10:29:03 -0700 (PDT) X-Google-Smtp-Source: AMsMyM5h3M+eSmTwK6P0UBRLQio/QIfF/WsBM9FbFwS+7Kk2TyOo6w/WpTLMnFmyJs7GA/fVogLj X-Received: by 2002:a05:6a00:23c6:b0:563:a1e9:eab8 with SMTP id g6-20020a056a0023c600b00563a1e9eab8mr13836306pfc.16.1666027743184; Mon, 17 Oct 2022 10:29:03 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1666027743; cv=none; d=google.com; s=arc-20160816; b=EzfzraLpv+TxSHYfiTD5YQtpeQMK1RU45SRVIxWJT5Xg7tQeZo2zAVGlOyZVQfkDH7 kBF36szug9eETkpkQAbSYpodqKJiNXwDMWPkewS6afWvMp/T6iyO5RbH+lMZXEpC1fIX ruG66cL6gujzooBTvwbZ8fjLn5FlLelP79vbWyUMPimNvcB9KYqJh5MS7wPGv7QyuPL4 AlyE/pUZLRNKLERy8r3mXkEkS3mxWix4UhogXzROkoYDmm058ou4T/RM1Q7dpeXknx7z zNwVPC1oyuThv9T1TFavDr+/40zhJoirToOZZmPr4/OucxQ7xFLYLyy+kRXZkOnE6big kFAA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature; bh=zcgno+MiI8oJBukmZ3pvg+LgPsqQ5hThvMhJ7/vHcT0=; b=UiKbJWGqXkKEDQoI8U9ivqd57C7IoOc9v9eHb6Tp36hM5eCHxHeYRPPZwO1951qzIQ UvRaaaBccoKh/N9329qkCB2kCQ7eA69pidRqwlFBxFK+CC7pRpWkgv8e0Ng3VvF9740a LaWyMSUh8KicOJr3k58jmMo+FYmDCDOBwLd9Ot17j+m39aw8lO7ReUXt6EbGJKVEVGUU Xiw0k2GgG54oojoj9RJy/Ar3kuF/z55edvIPKl4+0KUCFbmwa9Y8SJPIeiG+YgbFLR8w 3Ht+DPpSCjgKQ5BvXEB1EhH9GoAxe0q5vuysKZa+WAb4Fbi6upN2zZJr6N1Mx8CbUmLb z/Jg== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@collabora.com header.s=mail header.b=DBhhpfdy; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=collabora.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id l1-20020a170902f68100b0017844dd8503si14387006plg.402.2022.10.17.10.28.50; Mon, 17 Oct 2022 10:29:03 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@collabora.com header.s=mail header.b=DBhhpfdy; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=collabora.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230498AbiJQR10 (ORCPT + 99 others); Mon, 17 Oct 2022 13:27:26 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:55308 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230430AbiJQR0u (ORCPT ); Mon, 17 Oct 2022 13:26:50 -0400 Received: from madras.collabora.co.uk (madras.collabora.co.uk [46.235.227.172]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id E533C6AA38; Mon, 17 Oct 2022 10:25:53 -0700 (PDT) Received: from dimapc.. (109-252-119-114.nat.spd-mgts.ru [109.252.119.114]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) (Authenticated sender: dmitry.osipenko) by madras.collabora.co.uk (Postfix) with ESMTPSA id 73E466602397; Mon, 17 Oct 2022 18:25:22 +0100 (BST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=collabora.com; s=mail; t=1666027527; bh=mouc4GTDqkUUnIeyXbzcsBWDwfLa6ji9orHgrDtP/gg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=DBhhpfdyDasD8v4O86EXV7E7pvJlRCEBtgk3QNMSTgoiw+fKikVW8FXTEBDX8p/3u 34AXXBTlk9gmqong9FG3brHB5lpuq7fndYtuBemVTojXOlxgPia8S9kASa0mI0PX/s DinMsx4uI6r7g2GUvnnSglYFXvEfsyyeLrRwnFVXFm3EIix9dw2XPS9CDvFimbZHV8 pzwuTVEzORjQNbfNEy0KFiDHNmGiX0E3PpJ2fhIIedK6o8pomG90j+V8xv03U4dSe8 JsBgKquQcPOal16CmAJQ12RXqMITFDXFeWDGfu0Wh4D7Lfdq5ipfuXBzgMFsBvx6To ODhSmlO6WHA0Q== From: Dmitry Osipenko To: David Airlie , Gerd Hoffmann , Gurchetan Singh , Chia-I Wu , Daniel Vetter , Daniel Almeida , Gert Wollny , Gustavo Padovan , Daniel Stone , Tomeu Vizoso , Maarten Lankhorst , Maxime Ripard , Thomas Zimmermann , Rob Clark , Sumit Semwal , =?utf-8?q?Christian_K=C3=B6nig?= , "Pan, Xinhui" , Thierry Reding , Tomasz Figa , Marek Szyprowski , Mauro Carvalho Chehab , Alex Deucher , Jani Nikula , Joonas Lahtinen , Rodrigo Vivi , Tvrtko Ursulin , =?utf-8?q?Thomas_Hellstr?= =?utf-8?q?=C3=B6m?= , Qiang Yu , Srinivas Kandagatla , Amol Maheshwari , Jason Gunthorpe , Leon Romanovsky , Juergen Gross , Stefano Stabellini , Oleksandr Tyshchenko , Tomi Valkeinen , Russell King , Lucas Stach , Christian Gmeiner , Ruhl Michael J Cc: dri-devel@lists.freedesktop.org, linux-kernel@vger.kernel.org, Dmitry Osipenko , linux-media@vger.kernel.org, linaro-mm-sig@lists.linaro.org, amd-gfx@lists.freedesktop.org, intel-gfx@lists.freedesktop.org, kernel@collabora.com, virtualization@lists.linux-foundation.org, linux-rdma@vger.kernel.org, linux-arm-msm@vger.kernel.org Subject: [PATCH v7 19/21] dma-buf: Document dynamic locking convention Date: Mon, 17 Oct 2022 20:22:27 +0300 Message-Id: <20221017172229.42269-20-dmitry.osipenko@collabora.com> X-Mailer: git-send-email 2.37.3 In-Reply-To: <20221017172229.42269-1-dmitry.osipenko@collabora.com> References: <20221017172229.42269-1-dmitry.osipenko@collabora.com> MIME-Version: 1.0 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,SPF_HELO_NONE,SPF_PASS autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1746956706361945845?= X-GMAIL-MSGID: =?utf-8?q?1746956706361945845?= Add documentation for the dynamic locking convention. The documentation tells dma-buf API users when they should take the reservation lock and when not. Acked-by: Sumit Semwal Reviewed-by: Christian König Signed-off-by: Dmitry Osipenko --- Documentation/driver-api/dma-buf.rst | 6 +++ drivers/dma-buf/dma-buf.c | 64 ++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+) diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst index 36a76cbe9095..622b8156d212 100644 --- a/Documentation/driver-api/dma-buf.rst +++ b/Documentation/driver-api/dma-buf.rst @@ -119,6 +119,12 @@ DMA Buffer ioctls .. kernel-doc:: include/uapi/linux/dma-buf.h +DMA-BUF locking convention +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: drivers/dma-buf/dma-buf.c + :doc: locking convention + Kernel Functions and Structures Reference ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/drivers/dma-buf/dma-buf.c b/drivers/dma-buf/dma-buf.c index f149b384f4dd..f1d968e5bac4 100644 --- a/drivers/dma-buf/dma-buf.c +++ b/drivers/dma-buf/dma-buf.c @@ -795,6 +795,70 @@ static struct sg_table * __map_dma_buf(struct dma_buf_attachment *attach, return sg_table; } +/** + * DOC: locking convention + * + * In order to avoid deadlock situations between dma-buf exports and importers, + * all dma-buf API users must follow the common dma-buf locking convention. + * + * Convention for importers + * + * 1. Importers must hold the dma-buf reservation lock when calling these + * functions: + * + * - dma_buf_pin() + * - dma_buf_unpin() + * - dma_buf_map_attachment() + * - dma_buf_unmap_attachment() + * - dma_buf_vmap() + * - dma_buf_vunmap() + * + * 2. Importers must not hold the dma-buf reservation lock when calling these + * functions: + * + * - dma_buf_attach() + * - dma_buf_dynamic_attach() + * - dma_buf_detach() + * - dma_buf_export( + * - dma_buf_fd() + * - dma_buf_get() + * - dma_buf_put() + * - dma_buf_mmap() + * - dma_buf_begin_cpu_access() + * - dma_buf_end_cpu_access() + * - dma_buf_map_attachment_unlocked() + * - dma_buf_unmap_attachment_unlocked() + * - dma_buf_vmap_unlocked() + * - dma_buf_vunmap_unlocked() + * + * Convention for exporters + * + * 1. These &dma_buf_ops callbacks are invoked with unlocked dma-buf + * reservation and exporter can take the lock: + * + * - &dma_buf_ops.attach() + * - &dma_buf_ops.detach() + * - &dma_buf_ops.release() + * - &dma_buf_ops.begin_cpu_access() + * - &dma_buf_ops.end_cpu_access() + * + * 2. These &dma_buf_ops callbacks are invoked with locked dma-buf + * reservation and exporter can't take the lock: + * + * - &dma_buf_ops.pin() + * - &dma_buf_ops.unpin() + * - &dma_buf_ops.map_dma_buf() + * - &dma_buf_ops.unmap_dma_buf() + * - &dma_buf_ops.mmap() + * - &dma_buf_ops.vmap() + * - &dma_buf_ops.vunmap() + * + * 3. Exporters must hold the dma-buf reservation lock when calling these + * functions: + * + * - dma_buf_move_notify() + */ + /** * dma_buf_dynamic_attach - Add the device to dma_buf's attachments list * @dmabuf: [in] buffer to attach device to.