From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by smtp.lore.kernel.org (Postfix) with ESMTP id 7F9A0C77B7F for ; Tue, 24 Jun 2025 13:39:41 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id B63F88D0006; Tue, 24 Jun 2025 09:39:35 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id AEDC98D0001; Tue, 24 Jun 2025 09:39:35 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 9B60E8D0006; Tue, 24 Jun 2025 09:39:35 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0012.hostedemail.com [216.40.44.12]) by kanga.kvack.org (Postfix) with ESMTP id 83B0A8D0001 for ; Tue, 24 Jun 2025 09:39:35 -0400 (EDT) Received: from smtpin17.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay01.hostedemail.com (Postfix) with ESMTP id 2D3281D7941 for ; Tue, 24 Jun 2025 13:39:35 +0000 (UTC) X-FDA: 83590401510.17.082D026 Received: from mail-wr1-f54.google.com (mail-wr1-f54.google.com [209.85.221.54]) by imf13.hostedemail.com (Postfix) with ESMTP id 356D92000C for ; Tue, 24 Jun 2025 13:39:32 +0000 (UTC) Authentication-Results: imf13.hostedemail.com; dkim=pass header.d=suse.com header.s=google header.b="dowK/pWb"; spf=pass (imf13.hostedemail.com: domain of ptesarik@suse.com designates 209.85.221.54 as permitted sender) smtp.mailfrom=ptesarik@suse.com; dmarc=pass (policy=quarantine) header.from=suse.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1750772373; h=from:from:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=IHvhAvi5eCUp/ybstJnQHmjXO3pY/1hXWEhrYPlflFU=; b=4XStU9flKNq6LNQbaH66Xnay0APXAQ1ypMXy4XKq1CseUfn1mKahBN4gBPZed6Y1bvWgno 2+6rO7aFgc9gYfhIyvLUL6xaGDZY5UCwDzGCAmK2ueu0vs0oJkvxdwfq1AVLV/OWcHrsC3 v50bwS9l/duZE0HsfUT6cFKYA3c3QDE= ARC-Authentication-Results: i=1; imf13.hostedemail.com; dkim=pass header.d=suse.com header.s=google header.b="dowK/pWb"; spf=pass (imf13.hostedemail.com: domain of ptesarik@suse.com designates 209.85.221.54 as permitted sender) smtp.mailfrom=ptesarik@suse.com; dmarc=pass (policy=quarantine) header.from=suse.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1750772373; a=rsa-sha256; cv=none; b=4/QPIMj6UszLkf6CI1MTdnDw+jpv+HCEpIiJR0heQMYcbkmtWSUskT2VHU2cT0XUzextof FYP8CN0kKog1NB1MEsv6M9f69ttN96nMXdNMNy9xEPkGLox6dX0fJOV+ijAt19vRCgl0AI 5VgV/q7B3Bx1QoEQKVxE8jHNUsUFvmQ= Received: by mail-wr1-f54.google.com with SMTP id ffacd0b85a97d-3a4e749d7b2so946204f8f.0 for ; Tue, 24 Jun 2025 06:39:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.com; s=google; t=1750772372; x=1751377172; darn=kvack.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=IHvhAvi5eCUp/ybstJnQHmjXO3pY/1hXWEhrYPlflFU=; b=dowK/pWbt7GYXxOjTrSwmMX/Rtz5y47K4WwoQ/hg4B69C+RKUtGuzz9BbtqsYEFX9K Z//0oHhIMxCr2Gsrpkzqu0YTpbowmWdDasePwnwF35+Ek86IH5MaQkRWilzyhZLcnpxy /mOsejnshxe0m8Zlge/dx8Gv8h7YnFjF+Ukn9pcCnnr/dzgK90vEBZlnnu1dgCRrhV/O HzqNXrBYjrEBXWnVwfywnWFhBRzcU9F8TYduN2egwa+CUeVoF/8r+ERB16SFHhb+8hM3 Qenf8YvqVUbWIn/fPUsD2vUbAkrdh83660vKl0dM+YXlRXP+o2OyVh0JYcmdO2myKjP0 Oaig== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1750772372; x=1751377172; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=IHvhAvi5eCUp/ybstJnQHmjXO3pY/1hXWEhrYPlflFU=; b=QDdBkLYG7HMXqe2zRbSbXT2bRgPNVlIrVifDgZeidZJECKBSTwdPAa1a2/Bbe9I0ry 6sQj4rN4vqwyHxEuZ17zwZRblRMSq6XKyX2//J8rRBGq+XWFinAIgUbuQW1Uin91L38t To1KWmMF9YkDmG3tcbrrTHFQZVJMAN9HNVYM785hpxUekK09vYUp8jbRQAQBz0zdjfPH /zmZ/9PcxesCL0x+XInI9K1ZLjGSKSKW+neSsTIgXoYNjqvTlMpl+mGil4Vmn2VenkrD 7XPwAL5+HJUtJEC63CT5+F44/g8Peu2Hz5gLJf7cBaBkgou4ZLmiAN+nviHIaCHbGU4l lCjg== X-Forwarded-Encrypted: i=1; AJvYcCVdUv8cT3F2rn/c4+nLSF1Qig6xfxEYCu1GMm7bD1zv3xiNVaCa3isJkRgRTSNV0M2mntM8CUrr/Q==@kvack.org X-Gm-Message-State: AOJu0YyAC/kNnaW9TZL23uA/fzgOiIeXhLwR4h9cN/uNJLnqYhkFboYw xcK5aekkenSqz1sOxlJ/J2xzBdwYhzYhzKVDbubhhVOnDjQSsDx2UAYtaKf+RNGQBGyWVaT4qmz 8kDd0 X-Gm-Gg: ASbGnctPfvUl4klaXYtJitFahGQ31jNoLNwggDKpO956RlqAGvd/qIH7w8JBwJWZIuF RVbGj+uJoSBuD6sG/X4EfZv1XMWp/c4mDhoTQcXBrkPi5VCkk1Sdmrj1EQ7f47C5sdp+6ybKRyQ hL+Gald5iluuYcYeUUeBCte2hBvvG43+FsK8zbcDLvMO7ysBxHqXUsLB4q9wTJwqBE65BzSQheV V2Q6OGCUOeOHcTvFeEpwusoZjpJZjt8o4YOwtKug3qUFebYwR/s8+ibdhm6M6hfOWjh02V/mh0M sJFz0lyYERITlXPgLI/Vfplgijc+/uDOwjCGaznw9mZaCwmKOuPZAFtN7dAaHL0wf1S/UXt1rhl a+lYnp/8wdB4peHNt5F2gDf7N0hWGGvUS/pLQKtxiFwN7vmR/Qwos X-Google-Smtp-Source: AGHT+IHg37TDJn0ybirhMSzgiCvKi7BYNHT5VAEQ6KF0RJ85EgIsRWvQC3Z7Ra12tDoOlf0Dg9NQPA== X-Received: by 2002:a05:6000:2f83:b0:3a4:f7ea:a638 with SMTP id ffacd0b85a97d-3a6d128bc58mr4861104f8f.3.1750772371648; Tue, 24 Jun 2025 06:39:31 -0700 (PDT) Received: from localhost (dynamic-2a00-1028-83b8-1e7a-3010-3bd6-8521-caf1.ipv6.o2.cz. [2a00:1028:83b8:1e7a:3010:3bd6:8521:caf1]) by smtp.gmail.com with UTF8SMTPSA id 5b1f17b1804b1-4536fefd2b4sm84782955e9.36.2025.06.24.06.39.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 24 Jun 2025 06:39:31 -0700 (PDT) From: Petr Tesarik To: Jonathan Corbet , Morton Cc: Marek Szyprowski , Leon Romanovsky , Keith Busch , Caleb Sander Mateos , Sagi Grimberg , Jens Axboe , John Garry , linux-doc@vger.kernel.org (open list:DOCUMENTATION), linux-kernel@vger.kernel.org (open list), linux-mm@kvack.org (open list:MEMORY MANAGEMENT), Petr Tesarik Subject: [PATCH 3/8] docs: dma-api: remove remnants of PCI DMA API Date: Tue, 24 Jun 2025 15:39:18 +0200 Message-ID: <20250624133923.1140421-4-ptesarik@suse.com> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250624133923.1140421-1-ptesarik@suse.com> References: <20250624133923.1140421-1-ptesarik@suse.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Rspam-User: X-Rspamd-Server: rspam04 X-Rspamd-Queue-Id: 356D92000C X-Stat-Signature: 7j54zwq9ircnhjtx8q58trgedcqfiwe6 X-HE-Tag: 1750772372-712573 X-HE-Meta: U2FsdGVkX18A8TZia4m0zBO4SVu7tyiNvM6UNN7btzciqLFk42CVKBQIV7tDunQHtCYZWffYV0iHP9M8v1USimKs6nHC4ZArEPHy0fUf0GBWx9CtadjATY2L86IOR0SNL8NJH9ooy+RfzviAVszCkQgiKSnUuhovIZVkJr6IHppqY69qihgNQjMgdkZfi75pPoEe06eSpPJRpqJUHXNieNzE1rp3DiC8YZPc+sZI68mFadkGef+DTNTgLbdvNe87724LqpB3LYdWa00JYklpSMnJqhF0BB3HLnY2eWKg6NzSlOdn0ALsv5z9st03UTZfZ60wZwsps+Mevu0GLoHgbyzaluJTrHwaGVBT8n0650nW9Ab8gwYDcysLw9SC5cgNjiv9pjQq3uRGXBHJQh7s5VBpzkLoGKlvLVXswJgXiZpN5ejrP5d2mKhPB1k0YcB9n2cR0cs+VdrcRKvWWrmd+vd08UyXnEPdT/gY7G0gmpDeg53TdGIf3YSNONj2QEYI/nGTHHuU9DhCxYv4i9j5FmYAnAME6UfCmh3irIWaDVNZd/IH92xS1gNZvTty16GnOLrAzXtOXgj+7WLxrJPbvFK2KI6cSsuKbENjJvNghj5N+GwjjZy+XU6Bh4pbfwF80f8U0NU+PI2dgoo/+T31P66hm0AA7Qn1WY34276dsSATrJk6VHdWs4O05HrhaQmZi4yUSux7d0wbElEWWliJIBev7zWoLp+3t9wWZoOicnyedS/HtjDDXtNLyWP61wsBiqOMubdXxI/teTyx7tH0mvj1Ddf63tTdDQYDR/FaXsBj5dXOtcYPeULWBWS00QAfIfbykCozCQGxe9/RSXMIoXyuYOwf/EolhZHOYqQQPX58V9zAdRFNTP+BUJwCKP0lHDwKaKQ2JNIU3+oChkaUQXbaeqF7Cky82oRXEApO+hmO9S72kRizbZVs9PlXjWx7sN+6qUyzlgM/Xzl3Uxo Vtt6awC4 wekj2Iwa3RzFCwRObeX/TCW1Qt1RPyoteJVBnqBuoUZyhEpXUZtAwTthgvQnht6m6QzePzMtQBEnlbmxPYOeBRJXKBkhztLUl2mTtxJteyPQjJ5Bxvh8KH6G0Wl7ODk4vXMiA29EIvu+uNzDmX41/SCKFtnd+1IVl8P7OHJdGlPsJFfh0iojxuIJU5dxboB1bJHoyjYZ8NE8c1G1A1+eZEkXzh13EVpvYVbV7oy2e7e2cDBlNHSH3Qx0R0P8nJeGjf2e9BaIPdNlLTENZY/1xvzLSZGszL8PCabZpK3pUkPW0YxAZ8IR7t/LMRb41dtgiMJ6r X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: List-Subscribe: List-Unsubscribe: The wording sometimes suggests there are multiple functions for an operation. This was in fact the case before PCI DMA API was removed, but since there is only one API now, the documentation has become confusing. To improve readability: * Remove implicit references to the PCI DMA API (plurals, use of "both", etc.) * Where possible, refer to an actual function rather than a more generic description of the operation. Signed-off-by: Petr Tesarik --- Documentation/core-api/dma-api.rst | 25 ++++++++++--------------- 1 file changed, 10 insertions(+), 15 deletions(-) diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst index c0a2cc7d0b95..3e89e3b0ecfd 100644 --- a/Documentation/core-api/dma-api.rst +++ b/Documentation/core-api/dma-api.rst @@ -53,10 +53,9 @@ minimum allocation length may be as big as a page, so you should consolidate your requests for coherent memory as much as possible. The simplest way to do that is to use the dma_pool calls (see below). -The flag parameter (dma_alloc_coherent() only) allows the caller to -specify the ``GFP_`` flags (see kmalloc()) for the allocation (the -implementation may choose to ignore flags that affect the location of -the returned memory, like GFP_DMA). +The flag parameter allows the caller to specify the ``GFP_`` flags (see +kmalloc()) for the allocation (the implementation may ignore flags that affect +the location of the returned memory, like GFP_DMA). :: @@ -64,13 +63,12 @@ the returned memory, like GFP_DMA). dma_free_coherent(struct device *dev, size_t size, void *cpu_addr, dma_addr_t dma_handle) -Free a region of coherent memory you previously allocated. dev, -size and dma_handle must all be the same as those passed into -dma_alloc_coherent(). cpu_addr must be the virtual address returned by -the dma_alloc_coherent(). +Free a previously allocated region of coherent memory. dev, size and dma_handle +must all be the same as those passed into dma_alloc_coherent(). cpu_addr must +be the virtual address returned by dma_alloc_coherent(). -Note that unlike their sibling allocation calls, these routines -may only be called with IRQs enabled. +Note that unlike the sibling allocation call, this routine may only be called +with IRQs enabled. Part Ib - Using small DMA-coherent buffers @@ -246,9 +244,7 @@ Part Id - Streaming DMA mappings Maps a piece of processor virtual memory so it can be accessed by the device and returns the DMA address of the memory. -The direction for both APIs may be converted freely by casting. -However the DMA API uses a strongly typed enumerator for its -direction: +The DMA API uses a strongly typed enumerator for its direction: ======================= ============================================= DMA_NONE no direction (used for debugging) @@ -325,8 +321,7 @@ DMA_BIDIRECTIONAL direction isn't known enum dma_data_direction direction) Unmaps the region previously mapped. All the parameters passed in -must be identical to those passed in (and returned) by the mapping -API. +must be identical to those passed to (and returned by) dma_map_single(). :: -- 2.49.0