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)