From patchwork Wed Nov 13 06:34:25 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: anish kumar X-Patchwork-Id: 13873197 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 407CBD41C07 for ; Wed, 13 Nov 2024 06:34:37 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 660986B00BE; Wed, 13 Nov 2024 01:34:36 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id 623206B00BC; Wed, 13 Nov 2024 01:34:36 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 45F226B00BE; Wed, 13 Nov 2024 01:34:36 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0017.hostedemail.com [216.40.44.17]) by kanga.kvack.org (Postfix) with ESMTP id 234766B00A1 for ; Wed, 13 Nov 2024 01:34:36 -0500 (EST) Received: from smtpin05.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay04.hostedemail.com (Postfix) with ESMTP id C4D4D1A0818 for ; Wed, 13 Nov 2024 06:34:35 +0000 (UTC) X-FDA: 82780107144.05.4B42EF6 Received: from mail-pf1-f177.google.com (mail-pf1-f177.google.com [209.85.210.177]) by imf17.hostedemail.com (Postfix) with ESMTP id 4502540007 for ; Wed, 13 Nov 2024 06:34:01 +0000 (UTC) Authentication-Results: imf17.hostedemail.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=NOu8XoBz; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (imf17.hostedemail.com: domain of yesanishhere@gmail.com designates 209.85.210.177 as permitted sender) smtp.mailfrom=yesanishhere@gmail.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1731479586; 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=mhwi6lR5jSeMorI1q9+9/fyDjvgvyzKkd/GXuwiJiG4=; b=VsNUvb/jowHDk7wQKQ9g78u3o4b7x+lCBUcnJjF+ctZ/bRUZTDGpKiPqqK/8b+RM+pEliK bvvoRxyDm1JXi0upsbNIde3iLIjlZd6cb89AlhiNrczNhvy2INyo3YyCyoDM8HOcIjmPoA ULUnLzKlPHN2JP2QC2MZdmS341zlxEA= ARC-Authentication-Results: i=1; imf17.hostedemail.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=NOu8XoBz; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (imf17.hostedemail.com: domain of yesanishhere@gmail.com designates 209.85.210.177 as permitted sender) smtp.mailfrom=yesanishhere@gmail.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1731479586; a=rsa-sha256; cv=none; b=GE/hKrMx31J6I+ky6fQ6pWY4gsitYl5Gs+gXoufOFYd++fYsC3WFCZSe4xzRZHFz1R9xUE 7cEZ5w+EMwvEich0VLDI1esr9cMA+puP2PSheWlrvXf4ozEWaSrAh2HQ/tOv7gCmm0vNgq E1LBGmHCTxJvwiAZ12JdQeO9JOCcep8= Received: by mail-pf1-f177.google.com with SMTP id d2e1a72fcca58-7245a9d0e92so246112b3a.0 for ; Tue, 12 Nov 2024 22:34:33 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1731479673; x=1732084473; 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=mhwi6lR5jSeMorI1q9+9/fyDjvgvyzKkd/GXuwiJiG4=; b=NOu8XoBzXOFfJ/uJ2N0BgN+umGbiHqIiBhYy2UOJEhuVRTDP3baIOLEBWkMauLjfID FSNveKt7C6GjtfSkQOv8XufrP0Qti/rs1mrHaaxc2PxoD+HLCwhPdSln8XXi10SCPQtm 5eZurDxydi9aceuqsNyXrUJc+9x+6zrxXFRXk/yavvjkpDckuAC6ZtE9onadzpbiT2VJ 9rE3gEsDOwyrum1E4Lgyul6j1khyx66TqVmKO0idztjBINgkYx/G7LLR45zChlOjC5eS yZdRky/2a0p4rMeL8TAxxIAZPN0+lZwiV2SGvcjzpd7hCad9wn83CbisIiNVe7nqwAkM Pm0Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1731479673; x=1732084473; 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=mhwi6lR5jSeMorI1q9+9/fyDjvgvyzKkd/GXuwiJiG4=; b=gE7q3FRk1n8fRvXtU0ZUlUAn2ZzGypgvmfecJwmFRceSVxhr7ecGRrl1VLp+oxUy1z hmlLsKwXp6uf5ZK8kF6lNgss+fe8KnvqNo7mOm1QGP/u94Fmmr0D0t9j6OCMlvp7NB3V frbotVW6PfJFN2ouVD3Z2awx0uZlapareRJVLAj+c9JeG/yED6DOqexH1i6v8M0FiYLX U57wWQJLCheFm9CSQC0RXFMhDhjrD2tzVdhVDCaICD+r+s7ZtHdRsSTsbHWQwfesyQG0 lXlNnMDAKovhwazp1wr7U6QakT9xApHH/mGOYaAHk9CsZ1cACv+s/cCq7fLImN7BkdFl 3BvQ== X-Gm-Message-State: AOJu0Yx4s+k8qHdavg73vZ99L1rXmaAUv7Orp8w5Apa86UnM9lz0EKMu 6hxhTfmh0cBTs35Yfi+jhr3dV4IAeZfzUE5+nquc34bddfY7s+lz X-Google-Smtp-Source: AGHT+IFL6fOAF6QgANLZskZQw5gNajXV1ayjOAmlkn6RqV6YD9hZshkwFtAhkaV8MsatlC6dChbvcQ== X-Received: by 2002:a05:6a00:b86:b0:71e:60fc:ad11 with SMTP id d2e1a72fcca58-72457a2a33fmr2225412b3a.16.1731479672734; Tue, 12 Nov 2024 22:34:32 -0800 (PST) Received: from localhost.localdomain ([2600:1700:3bdc:8c10:a:e04f:e712:3f95]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-72458bab30asm747572b3a.190.2024.11.12.22.34.31 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Tue, 12 Nov 2024 22:34:31 -0800 (PST) From: anish kumar To: corbet@lwn.net, tj@kernel.org, akpm@linux-foundation.org, ptesarik@suse.com, xavier_qy@163.com, vbabka@suse.cz, tintinm2017@gmail.com Cc: linux-mm@kvack.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, anish kumar Subject: [RFC PATCH 2/2] dmapool: Documentation: use the kernel-doc comment Date: Tue, 12 Nov 2024 22:34:25 -0800 Message-Id: <20241113063425.21042-3-yesanishhere@gmail.com> X-Mailer: git-send-email 2.39.5 (Apple Git-154) In-Reply-To: <20241113063425.21042-1-yesanishhere@gmail.com> References: <20241113063425.21042-1-yesanishhere@gmail.com> MIME-Version: 1.0 X-Rspam-User: X-Rspamd-Server: rspam03 X-Rspamd-Queue-Id: 4502540007 X-Stat-Signature: 19n9nzxo55j4n3fj36daqy9ejdd85bb9 X-HE-Tag: 1731479641-549129 X-HE-Meta: U2FsdGVkX19arqbDCHOFsDJMlZcsN8SE66uGFGSgtTpJXk/d9CekijIhFxTQ3FQfYGi1q8Yo4ua56eyPQvJsge+vYzOd6Glt9NlIOuMiYhYdCxIGEd3a2fcot7x+/bNkWg881boPsBlcYTkbD1esPZUbohlKPOsqpifpJ7RVxJXHJESrdFHITc3z4YTNZM/8HWienjWHExDXKZ8xBp6Eq0I6jrcDkadVFA4jj3/4fMOqKvmkKU3ZJHI4at35kAIPZyh0kgNi6Jz1NYKo5HphJPyu5sIJe3skA8I4CmbzY9h7t0HVjhiXn3W74kXlhYe+kmqounIgXML1Zfg6LaXdLi5eoq7F/Q+9IPFajCrQ+19+k3BDrujk90x0/0Zqatusdc1I9vO9SLmN0Pu/s95LdANLyGoZA4Z7T5YC5J5SB/DV+g989U8+Xmqg/8KZyJZcJQyf1AKk6gFqhhGmECIo1m2BGyN9nhBC3OFltdSC/mmtIRIt3FPr6oYsaYeDET2crrMQaayDV9R7ziMy+NyiJIELETB/516DDbOhd3hX3TdbGHQ0lTM63WiGNYtYlWVInGY8erAIuiqM2LD4DseTy4b5cNNfrAfpKNd1Hd0QQlRKoFk1ajYJvJU9bJekPwWZctzqLEQj0wBqxa+8fJWpTQn8IPf0NURzZ/mA2HuhXX4kM49Xoph7m0W8YX8N9JfONPPCVGB+BgcWRg8XnZuZwGEF+Xsr4HQKhTiHO5Pmn05huLtb0mX7sDdjEWeq8aN+q2z0ZNVLBK6K/KaPKvA7FdW7blRhXS+WCPJ6qBbawnv0uzH1r4mFjk4yIkbFPwQStHSlReAmXjGtJ9DfhekGS3byqHthbJi+RSoANPxQfJEeUm17+r1YLOQ9hcRGPYjEJpZrtnlx3glTpF0aLufawyZSNO9IgE1WeuliDpnPFW8/aySwFrgRrdMwHrB1ngPOKakhyXkZai3MFNI+nEA 8tAU4ReN KPtGr6meMiSiXENnAFLlQ6OqmNq1GG2ZUhYOgx7URRjMRERq4FK8i7zjML7q02D67LfV1dkg3nka4fpz9apV7hMr4Wcv6WpMIqJIvr5jVo5m8jd6dFKdBfDkpGf70BMl3L6dNOm6V5D12hRT8YD4hkiANpP5SKhk3vBTuoDVms0ItvFjuIwb0HU2lu+UzvjRwito0Hu0ITvwYN3Fy5lQgeg8KlmJQWkOVyrzmJu9BBWAXW+QhqYWXdOK6GNBl5K92h48TEWu17t786IIfXpiw+8QR9GGaaggCFkLt59C//zkUDs234+sIGqXaPXaxyECUnYPIEfDcMw8wNrmFJDD4GKablFlf6x2xMWtYPzThKCtKWfCcUkIOlPbLws99uNyPOa1L 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: In an effort to modernize the documentation for dma api, move the api explanation to kernel-doc comment in the source code and use the kernel-doc here in the documentation. Signed-off-by: anish kumar --- Documentation/core-api/dma-api.rst | 66 ++++++------------------------ 1 file changed, 12 insertions(+), 54 deletions(-) diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst index 8e3cce3d0a23..8e89f328ba54 100644 --- a/Documentation/core-api/dma-api.rst +++ b/Documentation/core-api/dma-api.rst @@ -86,65 +86,23 @@ 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. - +.. kernel-doc:: mm/dmapool.c + :identifiers: dma_pool_create -:: - - 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. - -:: +.. kernel-doc:: mm/dmapool.c + :identifiers: dma_pool_alloc - void - dma_pool_free(struct dma_pool *pool, void *vaddr, - dma_addr_t addr); +dma_pool_zalloc wraps dma_pool_alloc() and also zeroes the returned memory +if the allocation attempt succeeded. -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. +.. kernel-doc:: mm/dmapool.c + :identifiers: dma_pool_create -:: - - void - dma_pool_destroy(struct dma_pool *pool); +.. kernel-doc:: mm/dmapool.c + :identifiers: dma_pool_free -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. +.. kernel-doc:: mm/dmapool.c + :identifiers: dma_pool_destroy Part Ic - DMA addressing limitations