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 B621AC77B7F for ; Wed, 25 Jun 2025 02:40:58 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 33CB66B00B3; Tue, 24 Jun 2025 22:40:58 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 2EDD96B00B4; Tue, 24 Jun 2025 22:40:58 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 1DCBD6B00B5; Tue, 24 Jun 2025 22:40:58 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0015.hostedemail.com [216.40.44.15]) by kanga.kvack.org (Postfix) with ESMTP id 0A7626B00B3 for ; Tue, 24 Jun 2025 22:40:58 -0400 (EDT) Received: from smtpin05.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay06.hostedemail.com (Postfix) with ESMTP id 6C6DC104B2C for ; Wed, 25 Jun 2025 02:40:57 +0000 (UTC) X-FDA: 83592370554.05.BAD9550 Received: from casper.infradead.org (casper.infradead.org [90.155.50.34]) by imf23.hostedemail.com (Postfix) with ESMTP id 47EED140008 for ; Wed, 25 Jun 2025 02:40:53 +0000 (UTC) Authentication-Results: imf23.hostedemail.com; dkim=pass header.d=infradead.org header.s=casper.20170209 header.b=V3AWpWLV ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1750819255; 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-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=QhOKuwEXUK6jChw5nZdyTrOBXqUWrLJ8kphrotwMKFI=; b=KoFAqMVrWsBkhO8v0cpwKxRB6FI6akGZ2Al+/vccC0hUmIeawIZMYb0rHVqTyKwm7rmaom 7kddxZlG2Sspblal7VNXBP5RUoz5nGco9Vp+2G8O0sfiDavREqdUlQc4b3d//P4w4sTvmZ FBQgRa15h+cPl2MUAMxPfNsCeCgIp2s= ARC-Authentication-Results: i=1; imf23.hostedemail.com; dkim=pass header.d=infradead.org header.s=casper.20170209 header.b=V3AWpWLV; spf=none (imf23.hostedemail.com: domain of rdunlap@infradead.org has no SPF policy when checking 90.155.50.34) smtp.mailfrom=rdunlap@infradead.org; dmarc=none ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1750819255; a=rsa-sha256; cv=none; b=ze4bcmLLzNOONtDuHO/8KJnRFJvmeUtpEoB6UPZFYf310IcfYJFd+sTkKh2DCft8HF2ZR6 jn+SYM+IWZW20Qg1PS6J89hOX0PoM94fQgG5ZQD+YNh25UBK8JkPyoeLuhDH92bvl9b4Aj 9Sw4DAdTxu7iz8RitoFXhq6j5bGP7nA= DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=casper.20170209; h=Content-Transfer-Encoding:Content-Type: In-Reply-To:From:References:Cc:To:Subject:MIME-Version:Date:Message-ID:Sender :Reply-To:Content-ID:Content-Description; bh=QhOKuwEXUK6jChw5nZdyTrOBXqUWrLJ8kphrotwMKFI=; b=V3AWpWLVWaDzC98R8eWDkEMmoz AivrGnORKy304ztblnzcBMPzXPxEKXGbdH99j4qF7S78JSwFp/LBJTkOJUcUr0az22YhbpTQ0EnFj M4v5NR7/fHmsLvQ8Efnak0zRQJWT2hIkvbsmV81xmvoZKIBBlYevYE09dT/LDqdcPM5d0HIKogOTU Oi+Dhq3ob5GW4Sb9eK7nGqnUXfDESXfJn28csgxoEOAPUebMAiw3Otb3c54ZV9BrnvS53zNflGn7k FFtoKWYgye7s2OhG3/9GybXhfOH1gljjpQmjG9p/cmUnOGPxbynQBMuW1/JItCzc4HEu4SrFFXgjw FFJDi9IQ==; Received: from [50.53.25.54] (helo=[192.168.254.17]) by casper.infradead.org with esmtpsa (Exim 4.98.2 #2 (Red Hat Linux)) id 1uUG40-00000008GCY-2IGy; Wed, 25 Jun 2025 02:40:40 +0000 Message-ID: <5ea93880-72fa-46c7-b69b-82e2021aa567@infradead.org> Date: Tue, 24 Jun 2025 19:40:37 -0700 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: [PATCH 5/8] docs: dma-api: remove duplicate description of the DMA pool API To: Petr Tesarik , Jonathan Corbet , Morton Cc: Marek Szyprowski , Leon Romanovsky , Keith Busch , Caleb Sander Mateos , Sagi Grimberg , Jens Axboe , John Garry , "open list:DOCUMENTATION" , open list , "open list:MEMORY MANAGEMENT" References: <20250624133923.1140421-1-ptesarik@suse.com> <20250624133923.1140421-6-ptesarik@suse.com> Content-Language: en-US From: Randy Dunlap In-Reply-To: <20250624133923.1140421-6-ptesarik@suse.com> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit X-Rspamd-Server: rspam03 X-Rspamd-Queue-Id: 47EED140008 X-Stat-Signature: 7cwh7sfs86j49nmeye8eitskcie975ua X-Rspam-User: X-HE-Tag: 1750819253-395789 X-HE-Meta: U2FsdGVkX1+aBqVD2k81l82KohkhM3XXShoOiI0gvttz+IcQzTuG5fLqP8Mm3WzfNUgyptmLutSTFytujsfSV0B1OAQaJzwPmMDoSFwSjUhcgq2WI4QhQfvIj91YcHlnHSsiF2UohplPB1sO+xr5LN/Oi3bq6grRa5HaLmEHLzoSmkKRm2WtBgusDR3NBwLo0ch1j2+kKvhyMcV0WyTYRQX+MYFCsK2ww5jsoMdx1XrPhNjMjBI2TkCSWvUlf/jcVsqY+436D7Es1kMMnyqBeZM4Ccx+isEzOca4bwdjX2YLCe1+MdHy2QksqBD0G0niC4XV3zjR9V//n6fZ3qCjY4/IMkfISeeaD8VDIqzZmM1h7Y1QPn/HWM35153Nx58e/iDSqVpYR61Hbiqy8T8krYPkYa1eeYljseDRZkCeL5R3FFfD9s5EkV/NmSiRbpjiB5cgstpmIbpHLP9rtGwWp4upJbRRrFVg0kKazhN7h8Z3gxqZQg2HK5f9xiPgh03olq0rvVteVK+eMczL9dvQ5S6B55YNNU4O6xcJu3oFduurOV1NSjAzZNuyjEzehGagQDlgURYI1raaKdeHT/i1XK24tyhf6dd6yuDcDirPgPWE40zsqQh1QpkC4hyyg0io3DNkKDrSz/UqQM4I+Z4UJdt77th2CXAVk512xEGMfFy2433Lm7w23nW04hwxIdfRGGVkLTJFoKiLVJy554UdNbVCjLde5L9grvUieUSDB/cnzfIySJVTmm8Kx2WoSbED9uPyZAFVDMglW3h208wEPn8PTcBWBNkDyF70gqjV80BdSuUAyu7J5ZNBOAu8fWuJwmJrJkOZDl2oERIVOWKfupkddiuMy8MCG/AT7MWozOSJ2sfRvXJBTFm7tP33PfTonBPPDEFEXWNOHL4k5H+LPomgO3DqkNyoNYicjuAzMl4jdhIDvvHgiuxqRyW0SgMw/dHxid35gaAD6kBlkVy 3p9F8BOx 9o7YT0Sa2NlP5QinmLGSQ6+GH3o13l6lmIwSFsE+d3gulZwrLSD4a6g/I2glOkqUCt0YkqEV6nKDmF4oIc/ww4mpcTWLCsqG4NF8Mm6EDBTZZKZmKKMNTSLxV3lnRH5teEmdc8Q3a9KB79wilC4OLTS8UyNVVFdolQGRku+KsfoKoBmuX722PS3FGrdEPUL2VeC7BVxdyguaIA3nbe3wNFXQzaifS3Zf+iRmm56j60yNA2zAUomYSDk8oSr2yEHUGmXfvjH85luM3izNX4d8sq5yUDg== 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: Hi, On 6/24/25 6:39 AM, Petr Tesarik wrote: > The DMA pool API is documented in Memory Management APIs. Do not duplicate > it in DMA API documentation. > This looks like it works (from just visual inspection), but I'm wondering why not just move all DMA API interfaces to dma-api.rst and don't have any in mm-api.rst... ? Thanks. > Signed-off-by: Petr Tesarik > --- > Documentation/core-api/dma-api.rst | 62 +----------------------------- > Documentation/core-api/mm-api.rst | 2 + > 2 files changed, 4 insertions(+), 60 deletions(-) > > diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst > index 3e89e3b0ecfd..f7fddaf7510c 100644 > --- a/Documentation/core-api/dma-api.rst > +++ b/Documentation/core-api/dma-api.rst > @@ -83,66 +83,8 @@ much like a struct kmem_cache, except that they use the DMA-coherent allocator, > not __get_free_pages(). Also, they understand common hardware constraints > for alignment, like queue heads needing to be aligned on N-byte boundaries. > > - > -:: > - > - struct dma_pool * > - dma_pool_create(const char *name, struct device *dev, > - size_t size, size_t align, size_t alloc); > - > -dma_pool_create() initializes a pool of DMA-coherent buffers > -for use with a given device. It must be called in a context which > -can sleep. > - > -The "name" is for diagnostics (like a struct kmem_cache name); dev and size > -are like what you'd pass to dma_alloc_coherent(). The device's hardware > -alignment requirement for this type of data is "align" (which is expressed > -in bytes, and must be a power of two). If your device has no boundary > -crossing restrictions, pass 0 for alloc; passing 4096 says memory allocated > -from this pool must not cross 4KByte boundaries. > - > -:: > - > - void * > - dma_pool_zalloc(struct dma_pool *pool, gfp_t mem_flags, > - dma_addr_t *handle) > - > -Wraps dma_pool_alloc() and also zeroes the returned memory if the > -allocation attempt succeeded. > - > - > -:: > - > - void * > - dma_pool_alloc(struct dma_pool *pool, gfp_t gfp_flags, > - dma_addr_t *dma_handle); > - > -This allocates memory from the pool; the returned memory will meet the > -size and alignment requirements specified at creation time. Pass > -GFP_ATOMIC to prevent blocking, or if it's permitted (not > -in_interrupt, not holding SMP locks), pass GFP_KERNEL to allow > -blocking. Like dma_alloc_coherent(), this returns two values: an > -address usable by the CPU, and the DMA address usable by the pool's > -device. > - > -:: > - > - void > - dma_pool_free(struct dma_pool *pool, void *vaddr, > - dma_addr_t addr); > - > -This puts memory back into the pool. The pool is what was passed to > -dma_pool_alloc(); the CPU (vaddr) and DMA addresses are what > -were returned when that routine allocated the memory being freed. > - > -:: > - > - void > - dma_pool_destroy(struct dma_pool *pool); > - > -dma_pool_destroy() frees the resources of the pool. It must be > -called in a context which can sleep. Make sure you've freed all allocated > -memory back to the pool before you destroy it. > +See :ref:`Documentation/core-api/mm-api.rst ` for a detailed > +description of the DMA pools API. > > > Part Ic - DMA addressing limitations > diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst > index a61766328ac0..de0bab6e3fdd 100644 > --- a/Documentation/core-api/mm-api.rst > +++ b/Documentation/core-api/mm-api.rst > @@ -91,6 +91,8 @@ Memory pools > .. kernel-doc:: mm/mempool.c > :export: > > +.. _dma_pools: > + > DMA pools > ========= > -- ~Randy