Re: [PATCH 26/29] docs: fix references for DMA*.txt files

From: Paul E. McKenney
Date: Mon Jun 15 2020 - 16:37:30 EST

Next message: Nick Desaulniers: "Re: net/sched/sch_fq.c:966:12: warning: stack frame size of 1400 bytes in function 'fq_dump'"
Previous message: Heinrich Schuchardt: "[PATCH 1/1] doc: x86/speculation: length of underlines"
In reply to: Mauro Carvalho Chehab: "[PATCH 26/29] docs: fix references for DMA*.txt files"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

On Mon, Jun 15, 2020 at 08:47:05AM +0200, Mauro Carvalho Chehab wrote:
> As we moved those files to core-api, fix references to point
> to their newer locations.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
> ---
> Documentation/PCI/pci.rst | 6 +++---
> Documentation/block/biodoc.rst | 2 +-
> Documentation/core-api/bus-virt-phys-mapping.rst | 2 +-
> Documentation/core-api/dma-api.rst | 6 +++---
> Documentation/core-api/dma-isa-lpc.rst | 2 +-
> Documentation/driver-api/usb/dma.rst | 6 +++---
> Documentation/memory-barriers.txt | 6 +++---

I grabbed this Documentation/memory-barriers.txt, but can drop it if
Jon takes the whole batch, in which case:

Acked-by: Paul E. McKenney <paulmck@xxxxxxxxxx> # from LKMM perspective

> .../translations/ko_KR/memory-barriers.txt | 6 +++---
> arch/ia64/hp/common/sba_iommu.c | 12 ++++++------
> arch/parisc/kernel/pci-dma.c | 2 +-
> arch/x86/include/asm/dma-mapping.h | 4 ++--
> arch/x86/kernel/amd_gart_64.c | 2 +-
> drivers/parisc/sba_iommu.c | 14 +++++++-------
> include/linux/dma-mapping.h | 2 +-
> include/media/videobuf-dma-sg.h | 2 +-
> kernel/dma/debug.c | 2 +-
> 16 files changed, 38 insertions(+), 38 deletions(-)
>
> diff --git a/Documentation/PCI/pci.rst b/Documentation/PCI/pci.rst
> index 8c016d8c9862..d10d3fe604c5 100644
> --- a/Documentation/PCI/pci.rst
> +++ b/Documentation/PCI/pci.rst
> @@ -265,7 +265,7 @@ Set the DMA mask size
> ---------------------
> .. note::
> If anything below doesn't make sense, please refer to
> - Documentation/DMA-API.txt. This section is just a reminder that
> + :doc:`/core-api/dma-api`. This section is just a reminder that
> drivers need to indicate DMA capabilities of the device and is not
> an authoritative source for DMA interfaces.
>
> @@ -291,7 +291,7 @@ Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
> Setup shared control data
> -------------------------
> Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
> -memory. See Documentation/DMA-API.txt for a full description of
> +memory. See :doc:`/core-api/dma-api` for a full description of
> the DMA APIs. This section is just a reminder that it needs to be done
> before enabling DMA on the device.
>
> @@ -421,7 +421,7 @@ owners if there is one.
>
> Then clean up "consistent" buffers which contain the control data.
>
> -See Documentation/DMA-API.txt for details on unmapping interfaces.
> +See :doc:`/core-api/dma-api` for details on unmapping interfaces.
>
>
> Unregister from other subsystems
> diff --git a/Documentation/block/biodoc.rst b/Documentation/block/biodoc.rst
> index b964796ec9c7..ba7f45d0271c 100644
> --- a/Documentation/block/biodoc.rst
> +++ b/Documentation/block/biodoc.rst
> @@ -196,7 +196,7 @@ a virtual address mapping (unlike the earlier scheme of virtual address
> do not have a corresponding kernel virtual address space mapping) and
> low-memory pages.
>
> -Note: Please refer to Documentation/DMA-API-HOWTO.txt for a discussion
> +Note: Please refer to :doc:`/core-api/dma-api-howto` for a discussion
> on PCI high mem DMA aspects and mapping of scatter gather lists, and support
> for 64 bit PCI.
>
> diff --git a/Documentation/core-api/bus-virt-phys-mapping.rst b/Documentation/core-api/bus-virt-phys-mapping.rst
> index 4bb07c2f3e7d..c7bc99cd2e21 100644
> --- a/Documentation/core-api/bus-virt-phys-mapping.rst
> +++ b/Documentation/core-api/bus-virt-phys-mapping.rst
> @@ -8,7 +8,7 @@ How to access I/O mapped memory from within device drivers
>
> The virt_to_bus() and bus_to_virt() functions have been
> superseded by the functionality provided by the PCI DMA interface
> - (see Documentation/DMA-API-HOWTO.txt). They continue
> + (see :doc:`/core-api/dma-api-howto`). They continue
> to be documented below for historical purposes, but new code
> must not use them. --davidm 00/12/12
>
> diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
> index 2d8d2fed7317..63b4a2f20867 100644
> --- a/Documentation/core-api/dma-api.rst
> +++ b/Documentation/core-api/dma-api.rst
> @@ -5,7 +5,7 @@ Dynamic DMA mapping using the generic device
> :Author: James E.J. Bottomley <James.Bottomley@xxxxxxxxxxxxxxxxxxxxx>
>
> This document describes the DMA API. For a more gentle introduction
> -of the API (and actual examples), see Documentation/DMA-API-HOWTO.txt.
> +of the API (and actual examples), see :doc:`/core-api/dma-api-howto`.
>
> This API is split into two pieces. Part I describes the basic API.
> Part II describes extensions for supporting non-consistent memory
> @@ -471,7 +471,7 @@ without the _attrs suffixes, except that they pass an optional
> dma_attrs.
>
> The interpretation of DMA attributes is architecture-specific, and
> -each attribute should be documented in Documentation/DMA-attributes.txt.
> +each attribute should be documented in :doc:`/core-api/dma-attributes`.
>
> If dma_attrs are 0, the semantics of each of these functions
> is identical to those of the corresponding function
> @@ -484,7 +484,7 @@ for DMA::
>
> #include <linux/dma-mapping.h>
> /* DMA_ATTR_FOO should be defined in linux/dma-mapping.h and
> - * documented in Documentation/DMA-attributes.txt */
> + * documented in Documentation/core-api/dma-attributes.rst */
> ...
>
> unsigned long attr;
> diff --git a/Documentation/core-api/dma-isa-lpc.rst b/Documentation/core-api/dma-isa-lpc.rst
> index b1ec7b16c21f..e59a3d35a93d 100644
> --- a/Documentation/core-api/dma-isa-lpc.rst
> +++ b/Documentation/core-api/dma-isa-lpc.rst
> @@ -17,7 +17,7 @@ To do ISA style DMA you need to include two headers::
> #include <asm/dma.h>
>
> The first is the generic DMA API used to convert virtual addresses to
> -bus addresses (see Documentation/DMA-API.txt for details).
> +bus addresses (see :doc:`/core-api/dma-api` for details).
>
> The second contains the routines specific to ISA DMA transfers. Since
> this is not present on all platforms make sure you construct your
> diff --git a/Documentation/driver-api/usb/dma.rst b/Documentation/driver-api/usb/dma.rst
> index 59d5aee89e37..2b3dbd3265b4 100644
> --- a/Documentation/driver-api/usb/dma.rst
> +++ b/Documentation/driver-api/usb/dma.rst
> @@ -10,7 +10,7 @@ API overview
>
> The big picture is that USB drivers can continue to ignore most DMA issues,
> though they still must provide DMA-ready buffers (see
> -``Documentation/DMA-API-HOWTO.txt``). That's how they've worked through
> +:doc:`/core-api/dma-api-howto`). That's how they've worked through
> the 2.4 (and earlier) kernels, or they can now be DMA-aware.
>
> DMA-aware usb drivers:
> @@ -60,7 +60,7 @@ and effects like cache-trashing can impose subtle penalties.
> force a consistent memory access ordering by using memory barriers. It's
> not using a streaming DMA mapping, so it's good for small transfers on
> systems where the I/O would otherwise thrash an IOMMU mapping. (See
> - ``Documentation/DMA-API-HOWTO.txt`` for definitions of "coherent" and
> + :doc:`/core-api/dma-api-howto` for definitions of "coherent" and
> "streaming" DMA mappings.)
>
> Asking for 1/Nth of a page (as well as asking for N pages) is reasonably
> @@ -91,7 +91,7 @@ Working with existing buffers
> Existing buffers aren't usable for DMA without first being mapped into the
> DMA address space of the device. However, most buffers passed to your
> driver can safely be used with such DMA mapping. (See the first section
> -of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?")
> +of :doc:`/core-api/dma-api-howto`, titled "What memory is DMA-able?")
>
> - When you're using scatterlists, you can map everything at once. On some
> systems, this kicks in an IOMMU and turns the scatterlists into single
> diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt
> index eaabc3134294..0e4947a8282d 100644
> --- a/Documentation/memory-barriers.txt
> +++ b/Documentation/memory-barriers.txt
> @@ -546,8 +546,8 @@ There are certain things that the Linux kernel memory barriers do not guarantee:
> [*] For information on bus mastering DMA and coherency please read:
>
> Documentation/driver-api/pci/pci.rst
> - Documentation/DMA-API-HOWTO.txt
> - Documentation/DMA-API.txt
> + Documentation/core-api/dma-api-howto.rst
> + Documentation/core-api/dma-api.rst
>
>
> DATA DEPENDENCY BARRIERS (HISTORICAL)
> @@ -1932,7 +1932,7 @@ There are some more advanced barrier functions:
> here.
>
> See the subsection "Kernel I/O barrier effects" for more information on
> - relaxed I/O accessors and the Documentation/DMA-API.txt file for more
> + relaxed I/O accessors and the Documentation/core-api/dma-api.rst file for more
> information on consistent memory.
>
>
> diff --git a/Documentation/translations/ko_KR/memory-barriers.txt b/Documentation/translations/ko_KR/memory-barriers.txt
> index 34d041d68f78..604cee350e53 100644
> --- a/Documentation/translations/ko_KR/memory-barriers.txt
> +++ b/Documentation/translations/ko_KR/memory-barriers.txt
> @@ -570,8 +570,8 @@ ACQUIRE ë íë ìíëììì ëë ëëìë ììëê RELEASE
> [*] ëì ëìíë DMA ì ìêìì ëíìë ëìì ìêíìê ëëëë:
>
> Documentation/driver-api/pci/pci.rst
> - Documentation/DMA-API-HOWTO.txt
> - Documentation/DMA-API.txt
> + Documentation/core-api/dma-api-howto.rst
> + Documentation/core-api/dma-api.rst
>
>
> ëìí ììì ëëì (ììì)
> @@ -1907,7 +1907,7 @@ Mandatory ëëìëì SMP ììíììë UP ììíììë SMP í
>
> writel_relaxed() ì êì ìíë I/O ìêìëì ëí ììí ëìì ìíìë
> "ìë I/O ëëìì íê" ììì, consistent memory ì ëí ììí ëìì
> - ìíì Documentation/DMA-API.txt ëìë ìêíìì.
> + ìíì Documentation/core-api/dma-api.rst ëìë ìêíìì.
>
>
> =========================
> diff --git a/arch/ia64/hp/common/sba_iommu.c b/arch/ia64/hp/common/sba_iommu.c
> index a806227c1fad..656a4888c300 100644
> --- a/arch/ia64/hp/common/sba_iommu.c
> +++ b/arch/ia64/hp/common/sba_iommu.c
> @@ -907,7 +907,7 @@ sba_mark_invalid(struct ioc *ioc, dma_addr_t iova, size_t byte_cnt)
> * @dir: dma direction
> * @attrs: optional dma attributes
> *
> - * See Documentation/DMA-API-HOWTO.txt
> + * See Documentation/core-api/dma-api-howto.rst
> */
> static dma_addr_t sba_map_page(struct device *dev, struct page *page,
> unsigned long poff, size_t size,
> @@ -1028,7 +1028,7 @@ sba_mark_clean(struct ioc *ioc, dma_addr_t iova, size_t size)
> * @dir: R/W or both.
> * @attrs: optional dma attributes
> *
> - * See Documentation/DMA-API-HOWTO.txt
> + * See Documentation/core-api/dma-api-howto.rst
> */
> static void sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
> enum dma_data_direction dir, unsigned long attrs)
> @@ -1105,7 +1105,7 @@ static void sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
> * @size: number of bytes mapped in driver buffer.
> * @dma_handle: IOVA of new buffer.
> *
> - * See Documentation/DMA-API-HOWTO.txt
> + * See Documentation/core-api/dma-api-howto.rst
> */
> static void *
> sba_alloc_coherent(struct device *dev, size_t size, dma_addr_t *dma_handle,
> @@ -1162,7 +1162,7 @@ sba_alloc_coherent(struct device *dev, size_t size, dma_addr_t *dma_handle,
> * @vaddr: virtual address IOVA of "consistent" buffer.
> * @dma_handler: IO virtual address of "consistent" buffer.
> *
> - * See Documentation/DMA-API-HOWTO.txt
> + * See Documentation/core-api/dma-api-howto.rst
> */
> static void sba_free_coherent(struct device *dev, size_t size, void *vaddr,
> dma_addr_t dma_handle, unsigned long attrs)
> @@ -1425,7 +1425,7 @@ static void sba_unmap_sg_attrs(struct device *dev, struct scatterlist *sglist,
> * @dir: R/W or both.
> * @attrs: optional dma attributes
> *
> - * See Documentation/DMA-API-HOWTO.txt
> + * See Documentation/core-api/dma-api-howto.rst
> */
> static int sba_map_sg_attrs(struct device *dev, struct scatterlist *sglist,
> int nents, enum dma_data_direction dir,
> @@ -1524,7 +1524,7 @@ static int sba_map_sg_attrs(struct device *dev, struct scatterlist *sglist,
> * @dir: R/W or both.
> * @attrs: optional dma attributes
> *
> - * See Documentation/DMA-API-HOWTO.txt
> + * See Documentation/core-api/dma-api-howto.rst
> */
> static void sba_unmap_sg_attrs(struct device *dev, struct scatterlist *sglist,
> int nents, enum dma_data_direction dir,
> diff --git a/arch/parisc/kernel/pci-dma.c b/arch/parisc/kernel/pci-dma.c
> index 70cd24bdcfec..4f1596bb1936 100644
> --- a/arch/parisc/kernel/pci-dma.c
> +++ b/arch/parisc/kernel/pci-dma.c
> @@ -3,7 +3,7 @@
> ** PARISC 1.1 Dynamic DMA mapping support.
> ** This implementation is for PA-RISC platforms that do not support
> ** I/O TLBs (aka DMA address translation hardware).
> -** See Documentation/DMA-API-HOWTO.txt for interface definitions.
> +** See Documentation/core-api/dma-api-howto.rst for interface definitions.
> **
> ** (c) Copyright 1999,2000 Hewlett-Packard Company
> ** (c) Copyright 2000 Grant Grundler
> diff --git a/arch/x86/include/asm/dma-mapping.h b/arch/x86/include/asm/dma-mapping.h
> index 6b15a24930e0..fed67eafcacc 100644
> --- a/arch/x86/include/asm/dma-mapping.h
> +++ b/arch/x86/include/asm/dma-mapping.h
> @@ -3,8 +3,8 @@
> #define _ASM_X86_DMA_MAPPING_H
>
> /*
> - * IOMMU interface. See Documentation/DMA-API-HOWTO.txt and
> - * Documentation/DMA-API.txt for documentation.
> + * IOMMU interface. See Documentation/core-api/dma-api-howto.rst and
> + * Documentation/core-api/dma-api.rst for documentation.
> */
>
> #include <linux/scatterlist.h>
> diff --git a/arch/x86/kernel/amd_gart_64.c b/arch/x86/kernel/amd_gart_64.c
> index 17cb5b933dcf..e89031e9c847 100644
> --- a/arch/x86/kernel/amd_gart_64.c
> +++ b/arch/x86/kernel/amd_gart_64.c
> @@ -6,7 +6,7 @@
> * This allows to use PCI devices that only support 32bit addresses on systems
> * with more than 4GB.
> *
> - * See Documentation/DMA-API-HOWTO.txt for the interface specification.
> + * See Documentation/core-api/dma-api-howto.rst for the interface specification.
> *
> * Copyright 2002 Andi Kleen, SuSE Labs.
> */
> diff --git a/drivers/parisc/sba_iommu.c b/drivers/parisc/sba_iommu.c
> index 7e112829d250..5368452eb5a6 100644
> --- a/drivers/parisc/sba_iommu.c
> +++ b/drivers/parisc/sba_iommu.c
> @@ -666,7 +666,7 @@ sba_mark_invalid(struct ioc *ioc, dma_addr_t iova, size_t byte_cnt)
> * @dev: instance of PCI owned by the driver that's asking
> * @mask: number of address bits this PCI device can handle
> *
> - * See Documentation/DMA-API-HOWTO.txt
> + * See Documentation/core-api/dma-api-howto.rst
> */
> static int sba_dma_supported( struct device *dev, u64 mask)
> {
> @@ -698,7 +698,7 @@ static int sba_dma_supported( struct device *dev, u64 mask)
> * @size: number of bytes to map in driver buffer.
> * @direction: R/W or both.
> *
> - * See Documentation/DMA-API-HOWTO.txt
> + * See Documentation/core-api/dma-api-howto.rst
> */
> static dma_addr_t
> sba_map_single(struct device *dev, void *addr, size_t size,
> @@ -788,7 +788,7 @@ sba_map_page(struct device *dev, struct page *page, unsigned long offset,
> * @size: number of bytes mapped in driver buffer.
> * @direction: R/W or both.
> *
> - * See Documentation/DMA-API-HOWTO.txt
> + * See Documentation/core-api/dma-api-howto.rst
> */
> static void
> sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
> @@ -867,7 +867,7 @@ sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
> * @size: number of bytes mapped in driver buffer.
> * @dma_handle: IOVA of new buffer.
> *
> - * See Documentation/DMA-API-HOWTO.txt
> + * See Documentation/core-api/dma-api-howto.rst
> */
> static void *sba_alloc(struct device *hwdev, size_t size, dma_addr_t *dma_handle,
> gfp_t gfp, unsigned long attrs)
> @@ -898,7 +898,7 @@ static void *sba_alloc(struct device *hwdev, size_t size, dma_addr_t *dma_handle
> * @vaddr: virtual address IOVA of "consistent" buffer.
> * @dma_handler: IO virtual address of "consistent" buffer.
> *
> - * See Documentation/DMA-API-HOWTO.txt
> + * See Documentation/core-api/dma-api-howto.rst
> */
> static void
> sba_free(struct device *hwdev, size_t size, void *vaddr,
> @@ -933,7 +933,7 @@ int dump_run_sg = 0;
> * @nents: number of entries in list
> * @direction: R/W or both.
> *
> - * See Documentation/DMA-API-HOWTO.txt
> + * See Documentation/core-api/dma-api-howto.rst
> */
> static int
> sba_map_sg(struct device *dev, struct scatterlist *sglist, int nents,
> @@ -1017,7 +1017,7 @@ sba_map_sg(struct device *dev, struct scatterlist *sglist, int nents,
> * @nents: number of entries in list
> * @direction: R/W or both.
> *
> - * See Documentation/DMA-API-HOWTO.txt
> + * See Documentation/core-api/dma-api-howto.rst
> */
> static void
> sba_unmap_sg(struct device *dev, struct scatterlist *sglist, int nents,
> diff --git a/include/linux/dma-mapping.h b/include/linux/dma-mapping.h
> index 78f677cf45ab..ef2b153ddbd9 100644
> --- a/include/linux/dma-mapping.h
> +++ b/include/linux/dma-mapping.h
> @@ -14,7 +14,7 @@
>
> /**
> * List of possible attributes associated with a DMA mapping. The semantics
> - * of each attribute should be defined in Documentation/DMA-attributes.txt.
> + * of each attribute should be defined in Documentation/core-api/dma-attributes.rst.
> */
>
> /*
> diff --git a/include/media/videobuf-dma-sg.h b/include/media/videobuf-dma-sg.h
> index b89d5e31f172..34450f7ad510 100644
> --- a/include/media/videobuf-dma-sg.h
> +++ b/include/media/videobuf-dma-sg.h
> @@ -31,7 +31,7 @@
> * does memory allocation too using vmalloc_32().
> *
> * videobuf_dma_*()
> - * see Documentation/DMA-API-HOWTO.txt, these functions to
> + * see Documentation/core-api/dma-api-howto.rst, these functions to
> * basically the same. The map function does also build a
> * scatterlist for the buffer (and unmap frees it ...)
> *
> diff --git a/kernel/dma/debug.c b/kernel/dma/debug.c
> index 36c962a86bf2..f97f088ace7e 100644
> --- a/kernel/dma/debug.c
> +++ b/kernel/dma/debug.c
> @@ -1071,7 +1071,7 @@ static void check_unmap(struct dma_debug_entry *ref)
> /*
> * Drivers should use dma_mapping_error() to check the returned
> * addresses of dma_map_single() and dma_map_page().
> - * If not, print this warning message. See Documentation/DMA-API.txt.
> + * If not, print this warning message. See Documentation/core-api/dma-api.rst.
> */
> if (entry->map_err_type == MAP_ERR_NOT_CHECKED) {
> err_printk(ref->dev, entry,
> --
> 2.26.2
>

Next message: Nick Desaulniers: "Re: net/sched/sch_fq.c:966:12: warning: stack frame size of 1400 bytes in function 'fq_dump'"
Previous message: Heinrich Schuchardt: "[PATCH 1/1] doc: x86/speculation: length of underlines"
In reply to: Mauro Carvalho Chehab: "[PATCH 26/29] docs: fix references for DMA*.txt files"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]