From patchwork Wed Nov 13 06:34:24 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: anish kumar X-Patchwork-Id: 13873196 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 8E9F6D41C08 for ; Wed, 13 Nov 2024 06:34:35 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id F10566B00BB; Wed, 13 Nov 2024 01:34:34 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id EBD896B00BC; Wed, 13 Nov 2024 01:34:34 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id D38256B00BE; Wed, 13 Nov 2024 01:34:34 -0500 (EST) 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 B1E5B6B00BB for ; Wed, 13 Nov 2024 01:34:34 -0500 (EST) Received: from smtpin16.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay02.hostedemail.com (Postfix) with ESMTP id 02C59120390 for ; Wed, 13 Nov 2024 06:34:33 +0000 (UTC) X-FDA: 82780107186.16.7D74EBD Received: from mail-pf1-f175.google.com (mail-pf1-f175.google.com [209.85.210.175]) by imf21.hostedemail.com (Postfix) with ESMTP id 7C0651C0009 for ; Wed, 13 Nov 2024 06:33:11 +0000 (UTC) Authentication-Results: imf21.hostedemail.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=ky6fRY6e; spf=pass (imf21.hostedemail.com: domain of yesanishhere@gmail.com designates 209.85.210.175 as permitted sender) smtp.mailfrom=yesanishhere@gmail.com; dmarc=pass (policy=none) header.from=gmail.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1731479529; 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=3mOVTHykOcvikJTDU2tzo0bBXcz8e9l/HyWBKYXvXrc=; b=K4nDDbKwyB0VSAJkqAGz4hWwcz5gXKbAQR2TFqMeETwrAuBdWG2LAxA8TlDjtVVlhVkxc1 B5etNSsgLKVQ0sPDGTsZKultDyl+dh/g6ojS3gOXwFtj8/ouLk6H5AKIegzZGbKkG/8XAr m7YkbBHnsn+WEjxjcIuHYFQ8vTd7SjQ= ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1731479529; a=rsa-sha256; cv=none; b=XJiXFxjLm6I+nf+qCobWov2XlHGl0awai3CsYKlUGUivrvx8ap93eOiqH96rAH5Y4tPN7T SKOydZl43eZOjR2rsmcc9r1MeqXmdAKWhz8zUh1FjH3PH6JQkvVjCKZP/xzI5DKoUgfxOK o0DsuZz2VFcfb0IocwYija0d5zqvRbc= ARC-Authentication-Results: i=1; imf21.hostedemail.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=ky6fRY6e; spf=pass (imf21.hostedemail.com: domain of yesanishhere@gmail.com designates 209.85.210.175 as permitted sender) smtp.mailfrom=yesanishhere@gmail.com; dmarc=pass (policy=none) header.from=gmail.com Received: by mail-pf1-f175.google.com with SMTP id d2e1a72fcca58-72041ff06a0so5313478b3a.2 for ; Tue, 12 Nov 2024 22:34:31 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1731479671; x=1732084471; 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=3mOVTHykOcvikJTDU2tzo0bBXcz8e9l/HyWBKYXvXrc=; b=ky6fRY6eovabeEN8HiFRz+fcTnj5fjXerf0KaVVoToA00lUKCRn9RYcB02X53Jiq9C kqYll5yHHuxydQ9TZ/+LOOaFPIkwqGn7itVED4dJKvTMHhryWSn9vtfdUN2tVuHXSk9N J/I2ke3PCINXJRQV3DgEaySyRf8xhlc2yYk6p1M7TRZXWzlRfDpTAys18ZoglpJeHTzI gawRgT8CNszZEtGFvPOC9Nl+79reyqbQ7t8Yy4YYg04CjYqjdY1iDOXhtY6yd2IyR5XR 5JTPTaklYZJZbfFPwn8t2tYvpuqbnwt3uJtphN8uYtlo6N8HS7mNm5LW4A8EjAiIITsa cnVA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1731479671; x=1732084471; 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=3mOVTHykOcvikJTDU2tzo0bBXcz8e9l/HyWBKYXvXrc=; b=II7nmM91Cc2SrJN4whgJC8N/Em7bW/kF+QTAwt8PXnNldgvDOgnsnlS+ZHWJzNv9Ze Rg//T6CrETP+RUnjKnkE1lm1g/wq8E1kxFarLlGdaHFa60iaFAZJNbAOuNnPKWUDcjwJ +hnlQZVAwcjQTlw/3Dp5dZxi0D2M74aJOUdm0rMwPigg5oS6pTPEv0JwZNvBUKMhZdZL oXWL00Ph1LfY1DXfMAolqxyzFnm0r7YtD/XVKKIfziYUp4eon7ArkOxnZjb5tchoYqf5 E4Aw8Au9S0aKziXwrxNL3Zdyu+zVL3XqoPaYy9zR+aW2r35s+t1ZQZ6Ql4AMcmF/jrHy qPZg== X-Gm-Message-State: AOJu0YxV80ztkCeVBin8gk0FXpshL2EkEWatoB/TLfdiIyrSSoxLbMu8 8HH0j5/2L4jfjEg6n58M8E4w1FuHAZ1bj5BLFeaic7nE9wwmD71d X-Google-Smtp-Source: AGHT+IGo6AnEUeeQERM8eGIbcsc4sk0h9fnmY1pHTDcq32vu2oL2fudCT+Ti39A9/93PNahND16a+A== X-Received: by 2002:a05:6a00:3a14:b0:70d:2a88:a483 with SMTP id d2e1a72fcca58-7241313d95emr27792105b3a.0.1731479670861; Tue, 12 Nov 2024 22:34:30 -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.29 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Tue, 12 Nov 2024 22:34:30 -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 1/2] dmapool: Improve dma api kernel-doc comments Date: Tue, 12 Nov 2024 22:34:24 -0800 Message-Id: <20241113063425.21042-2-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: rspam12 X-Rspamd-Queue-Id: 7C0651C0009 X-Stat-Signature: frdeubop7fsn8kx8nsxsckfcuawq3qp4 X-HE-Tag: 1731479591-581958 X-HE-Meta: U2FsdGVkX18YGrIJRfaLU0u60MKfloI5yjtZmbN0R71hMZPI79e4x8/s8HMiJMC0x5jOFylhojVS7fmZWCzOJwkGTL0R0Cp4LSxfTKRbJn25/KNnSVil+cG9rAGSwlwpzYsm58XKfLm7zu3vJ+tlDYKAWLZepxmw8VIBM7H1gRMzchCssMJ5V/27zuG0ly0Stsu2cHbQxooPsYQYA+B+fuBZ0EkSjsKlAowygKXzRI28NlftKcFPMdr5CdnPg9lQbkGz3JxGu0FhSODrEeoec4pW++5Y8d5oA2lj3gc8t+E9cdTNqmNWpp/0nvBUrpkwAUTUJe6Zo38oKvumkPoTgyfWvDOh9VyE55DmF7qrID5J4bNIVDpIAbEECVCP72OO0vU7TPF/825LnD2GhFDnDHq26bDwil9J6SQAsUxZpraXKGfxv8yngZAiFhifD21GCIWBepyOOnEdCwclPji/Co0yZGejogmWVhIGvtwnxF2TZof+Lzl1K3Am9vq8JxllbEyBcADDm9F/TYKhEGtrw39T/tP2xXcsAPYbu8KJ+ymA4Kt2LgSth0xHJZsqG7IKxh01J2adF76Ra+aR+Y1U8QxWFyg2ZOReSFazJGaCJ3fghgHsvQwaT6SmjqWpeu76wgqRDLTN0eWjZZOpsLGGjnlNZrkR0AhVYlW39GWUehBuM976LLzYAT1oiFESApB3m1X36AtyzdHreYnfJWjhtmbpWUA6/FvyxkIH7oEZrp3FDcHXZ2VuSIBDYPPmtr2QZkIRtqRwtKZLg2hNO0PTaEwYDzSvON6x0to26skF8OiBT4Ous9F4p3oslpgnMcDDaia9FFNcFb8PngoBKClTOEsivRIZWG1Y0adhB0E/0/mzSsJPKPiv2FlxRf7VSZ59o8cl0mTPkSkaIhduxrw21WaNK0gH54TILTrM1UByBwo+tBMTtyRvEnx+TJjuI1kCx2g4q4P+kTFSKCU6aQk PpqQ0ikl eP9UVmfnGv1nLlP2fEMWW1GA9tZNrAijCR6NN/hnpsDy5aoKn6eofGzXJcl04ClYtHlDj4SgICRa9kH+ELvB6UXr3YF5f2Y0S2CiN5sAWiHgIfGkE6+27WEcRp0f6J47wLzmBg+8dhyHQduh23Thx+Hensf5Dm4e+T74J1pBU/BVRKVt/Dq1ih+O/M5tRQ3ThCeErGGs9vjC8awC8oWzbMR9qn0+5jb9yuxmv0iBur5Z3VqmlW68kjiOQ3jDCR9NpaRzqEOOqfzHby0zhAhNkhLcXEIaWQ8DpJyXJ1H1YqoBndknxNRY5wjC+BsbDGeFWv9+aUbyUG9HsRkQPrNRAJ1bPbOAB6/kkKGI+8vID9i9gztud0dV6xpQ8dVDmyn/rfRUy 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: Move explanatory content from the documentation to source code comment written in kernel-doc format. This allows kernel-doc to generate more comprehensive and accurate documentation. Additionally, improving the kernel-doc comment describes the api behaviour and usage better. Signed-off-by: anish kumar --- mm/dmapool.c | 40 ++++++++++++++++++++++++++++------------ 1 file changed, 28 insertions(+), 12 deletions(-) diff --git a/mm/dmapool.c b/mm/dmapool.c index f0bfc6c490f4..8b32a52becd6 100644 --- a/mm/dmapool.c +++ b/mm/dmapool.c @@ -207,11 +207,16 @@ static void pool_block_push(struct dma_pool *pool, struct dma_block *block, * @boundary: returned blocks won't cross this power of two boundary * Context: not in_interrupt() * - * Given one of these pools, dma_pool_alloc() - * may be used to allocate memory. Such memory will all have "consistent" - * DMA mappings, accessible by the device and its driver without using - * cache flushing primitives. The actual size of blocks allocated may be - * larger than requested because of alignment. + * This api initializes a pool of DMA-coherent buffers for use with a given + * device. It must be called in a context which can sleep. The device's + * hardware alignment requirement for this type of data is "align". 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. + * + * Given one of these pools, dma_pool_alloc() may be used to allocate memory. + * Such memory will all have "consistent" DMA mappings, accessible by the + * device and its driver without using cache flushing primitives. The actual + * size of blocks allocated may be larger than requested because of alignment. * * If @boundary is nonzero, objects returned from dma_pool_alloc() won't * cross that size boundary. This is useful for devices which have @@ -356,6 +361,7 @@ static struct dma_page *pool_alloc_page(struct dma_pool *pool, gfp_t mem_flags) * * Caller guarantees that no more memory from the pool is in use, * and that nothing will try to use the pool after this call. + * It must be called in a context which can sleep. */ void dma_pool_destroy(struct dma_pool *pool) { @@ -392,14 +398,24 @@ void dma_pool_destroy(struct dma_pool *pool) EXPORT_SYMBOL(dma_pool_destroy); /** - * dma_pool_alloc - get a block of consistent memory - * @pool: dma pool that will produce the block - * @mem_flags: GFP_* bitmask - * @handle: pointer to dma address of block + * dma_pool_alloc - Get a block of consistent memory from a DMA pool + * @pool: DMA pool that will produce the block + * @mem_flags: GFP_* bitmask specifying memory allocation flags + * @handle: Pointer to a DMA address that will hold the address of the block + * + * Return: The kernel virtual address of a currently unused block of memory, + * and reports its DMA address through the handle. If such a memory + * block can't be allocated, %NULL is returned. + * + * This function allocates memory from the specified DMA pool. The returned + * memory will meet the size and alignment requirements specified when the + * pool was created. Pass GFP_ATOMIC to prevent blocking, or if permitted + * (not in interrupt context, and not holding SMP locks), pass GFP_KERNEL + * to allow blocking. * - * Return: the kernel virtual address of a currently unused block, - * and reports its dma address through the handle. - * If such a memory block can't be allocated, %NULL is returned. + * Similar to dma_alloc_coherent(), this function returns two addresses: + * - A CPU-accessible virtual address + * - A DMA address usable by the pool's associated device. */ void *dma_pool_alloc(struct dma_pool *pool, gfp_t mem_flags, dma_addr_t *handle) 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