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 1EFF6C77B7C for ; Tue, 24 Jun 2025 13:39:48 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 9685D8D000B; Tue, 24 Jun 2025 09:39:38 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 8CA8B8D0001; Tue, 24 Jun 2025 09:39:38 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 792A08D000B; Tue, 24 Jun 2025 09:39:38 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0010.hostedemail.com [216.40.44.10]) by kanga.kvack.org (Postfix) with ESMTP id 5A1BA8D0001 for ; Tue, 24 Jun 2025 09:39:38 -0400 (EDT) Received: from smtpin10.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay10.hostedemail.com (Postfix) with ESMTP id 1A599C08F3 for ; Tue, 24 Jun 2025 13:39:38 +0000 (UTC) X-FDA: 83590401636.10.12087E6 Received: from mail-wm1-f50.google.com (mail-wm1-f50.google.com [209.85.128.50]) by imf09.hostedemail.com (Postfix) with ESMTP id 2E05C140007 for ; Tue, 24 Jun 2025 13:39:35 +0000 (UTC) Authentication-Results: imf09.hostedemail.com; dkim=pass header.d=suse.com header.s=google header.b=dLEHHiz6; spf=pass (imf09.hostedemail.com: domain of ptesarik@suse.com designates 209.85.128.50 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=1750772376; 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=SMoobju51S3yheRJ4nJb50lwjewYooD5+oD7p0lsIPI=; b=P/OZq914ygpWlZhnL/vjsbJjJYsllWb78q3mvVqxy6WnNp1fmFQfg/S6xeckUKnoOhyGmv q2HOZNayBntHi8U0EW6lT49nH4T0ikGVLm9otevZDE0AigvBDn/L75vW/4J36Z4vHhDn5K RGLDOLkC6DawBKIMm3eE5Cd4mujKRAM= ARC-Authentication-Results: i=1; imf09.hostedemail.com; dkim=pass header.d=suse.com header.s=google header.b=dLEHHiz6; spf=pass (imf09.hostedemail.com: domain of ptesarik@suse.com designates 209.85.128.50 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=1750772376; a=rsa-sha256; cv=none; b=0zjxqrLZhwbshUujkNE4EBpxintGcH4HtyyIURPAhoMO1RhRdKG7Ic8TrVV05p3HMufahk ld3wSMhyvrii/OTCuwqzFnLye+Texz8ZS8LGD0WbmmeXa4EV2hTIbjwvzS/GGqBQFkCEbR pSmxgEWCDMkFdyUgk7iyP+PAzd5b5HA= Received: by mail-wm1-f50.google.com with SMTP id 5b1f17b1804b1-45306976410so1905725e9.3 for ; Tue, 24 Jun 2025 06:39:35 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.com; s=google; t=1750772374; x=1751377174; 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=SMoobju51S3yheRJ4nJb50lwjewYooD5+oD7p0lsIPI=; b=dLEHHiz6vL6uoHcCs5XRDqeWS9wILBxcRsfocHHmzlf44K4kyFb430VMjRSB1WNyw1 bNzCSy3i+T9rhlSuVEs6G9gtw13//JdIJoe8j8/5OWwXRpjgBJlm3jqwOYLSWcB33ryd WoaH+g1CgLtIiUzfE5wvARRdyNAS8pHGGQ4gU/PynEdbqzJPTjxaaB1u6BskNkBu/fct h7+biarvL5mAHevYpWIqJCGgYpQe+jnJTC+9qpqCIVMLJO04J4GAyh1SodDfY4nxBfb+ kXvV56xaIerKBoyTafOi/j9iWvnBQdQ0kOkn+Tm9sCHKw63IVRJDlyFhSggVaa6qddAo 2oFg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1750772374; x=1751377174; 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=SMoobju51S3yheRJ4nJb50lwjewYooD5+oD7p0lsIPI=; b=SGioPAxVBwcqyDZRIcu0KhOjiwSDYS4fEv2+nYsf2q4r9Mylw/4JceIJUWKpX4oGfx umkI8VcXwXI56kWOoXqqCV5DGBUFgxXNoooDL51UTXr80defMRJKKmyFFgibPXfq0RjX AYaw0CM1YY2YBftO3g6JZwP46QOnNtFv2RwYGTkQHqUWlPGnKO/AvRdbFl3HC7dYUH0q tPQ5uuMjAfXP8GlMLrdVF3yxODKGBpHG1i2UYktjDPiOm1/l0PqMPmyKgam0vvFYLJL6 upAd2U3NskYvWTdec+K40Bkm14NNkudpd0hxo5SEs1IDX5hce/37MXiWWX+IhpEv7zZJ Gpqg== X-Forwarded-Encrypted: i=1; AJvYcCURUa5AzMQ9VWdBl7gMyZwrJxUNtkZCJOCuX06LgHTwHoXmfmFNmsGYXmy1pY89+Cu/8rrkRC6vJQ==@kvack.org X-Gm-Message-State: AOJu0YwW4IeoEsp1rJDoGmZh+A9quYm06nGBJ/qPZVkDG4+XC/oGNCaE bFwXlGnAlWUIa0wGlP09HmL3X1mQ0FMfk2h49qGupUtBXzUCNuNwRWuWZrFm1AMQVFM= X-Gm-Gg: ASbGncv/xZwoSWuNIMe1MyBC8CV6FEQdRpwy/1moZl3I62OWOZma1jD8hXqkALDAaUU vmm1xx08pt+Q1LJ+fO0IMGMhMB0DgT87R36GB0LBOOkxGtTX8OwhL0/VGyshcO8KgEjHT4Gpuyb xcCpTQiECIioghE0jRt0rMm04Es8uy0RT9NdSTHnb0fbgXaPbxvkuXLIb+8meylB9YfFNWAkA+j qYX8j59zCFZJ5G3S40s1pvtXXeGPOyYQiwfY+LYum6NErDE/LjkI/Vn3Rghu7j29dQ0j/8BN2i0 y+zZTM/Wdkl6n7YFtNLkLi3X+kf5sNtpMoZ4JM8ucqGIJqIMCeX4rRBNgGxjxkHguhwMCvuYUki D+4YbpInaoSvNMLlQH81eSnBoGi5xm7Rong36Q7kAtFBML7INtcZU X-Google-Smtp-Source: AGHT+IEJyYo9lnu2Mk5wM3vEKd7mlfp5WCsbwymCeOMIaa9JZYjSHQ3akdWqQqS/IC1aMCHvKzNu3w== X-Received: by 2002:a05:600c:4747:b0:441:b397:e324 with SMTP id 5b1f17b1804b1-453659ca904mr62554965e9.9.1750772374485; Tue, 24 Jun 2025 06:39:34 -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-4535eac8e19sm175941015e9.21.2025.06.24.06.39.34 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 24 Jun 2025 06:39:34 -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 5/8] docs: dma-api: remove duplicate description of the DMA pool API Date: Tue, 24 Jun 2025 15:39:20 +0200 Message-ID: <20250624133923.1140421-6-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-Rspamd-Queue-Id: 2E05C140007 X-Rspam-User: X-Rspamd-Server: rspam07 X-Stat-Signature: 6mq5e7mn9rnztp8dt3jswhaidm7eu479 X-HE-Tag: 1750772375-375387 X-HE-Meta: U2FsdGVkX1+BDGCxTv/v9Pi3du3Amy7xK704kOENAOUxr59Ft/pXgJO1Kq0fVuACo7DtTSiLK0MIYsphNNh/G2iORgtXSZ5wQCfvuomQubVnruvMsFzHke+OIm2WLFKrh9j2EefHMdL9r2krLZ/yCcty8gd74XaXJHUoVj6h3Cb/4qeCXdUrwPLU4VnIItNW8nq8ssVdyteDo8w7W7GPzxnzxi8P5I80/SnhgnmIVjS4leEl1qAUPb3bzvGShtDzCujxuO2qBYCoMSzEAopbL3DOeuSn6Etg2+WU+JH8lGKT/+We2hkQBqbz79oHYZ+XJXJiDjCrPyDIICwxj4WSzbTrtkPpm4Yhl6zci7AQ+FQ955oD0YL2OZOEcv9gmp95AUD/9sX2tCq/kjZGNRbSfh3mZH+/LWs3SkyivNm428jNtpyLHmuPMWeYfqFBaDDMuVCylGp9IPhS5xOX4Dwrv3Sv0hnkUIuHc6jXvVsKwyYasC/wT0U2xKKZGO3PNB+vMRHFAS/ejTQQmftYQHyr7LN3E22uKKWVU3oD8xCz4wq+WmC9iJfHqIYF7NURrvKDVQhmMp2QB1p7LVj2jetIitoVOhH+Ia3xhdGkSHksSCOT03xb47DFZoSKyUXTPKNXA7AN2wMry2QR9NWD6HvWgroEx4RVKx9F1DRxfYf5vrSL/nAueNsR8MvooHANfIrP87EeCCyOW7UZz6EDI/y4nFTKyKtwP8dnexgXyCmhuINv+W0XUognTqIFqPUXOhoMeo4OlvU5jdUBzw68yjdo92O7jIaih1w4A60i01PyOengcKX0gxVpMxHHk2HuM5Wst9ilXADJmM4JmiSCDWnXHRmYTLKY6a7p9DIw7znpkzpK0nSds3r7xHkoq5EIDCw/dg3io2WTXcajq0WvSUh96jV2xddeNaxMjJybp23NYIB23+sIPOVDE8JhtsyxrT3yfbMRvpL6XxHxkleqvWn Gf2SM0eE tpiDSrVn62HGe5hgBKXWWrNVMG98DipH8HfVgMfwNbXrUE+Zht1ak2mWTG/qXLO+LqeTcnnNhmSVQxz+3pbwcODPib52vgHzxBck5WymRQB6ycAbTySPMlEJEANSfINVYKa/InqS59b+KSwOqAF2g/bO2i34/9vP9/oEpTUP9DgXUPSJyykEsUhamulXdCNJBEcUgUlu1sYM/wN1TLxnaBycJ7rrhZdreK7hOK11LfzaXkjkn/tuJbyLxXOpMqQjLykhw+uD20pGPf7frrtNhrf7ZF2EDrvBEbSQeqIO4gbCD974rjJ/pmcU/kT++Rrxvbrie 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 DMA pool API is documented in Memory Management APIs. Do not duplicate it in DMA API documentation. 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 ========= -- 2.49.0