phyr: Add basic definition

Add the data structure and the documentation.

Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>

diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index 77eb775b8b4273d200de4033d06e73d7e7ba1bbe..32da56f76a53ee3647db339c69c6af8ac6ccafd3 100644 (file)
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -104,6 +104,7 @@ more memory-management documentation in Documentation/mm/index.rst.
    dma-isa-lpc
    mm-api
    genalloc
+   phyr
    pin_user_pages
    boot-time-mm
    gfp_mask-from-fs-io

diff --git a/Documentation/core-api/phyr.rst b/Documentation/core-api/phyr.rst
new file mode 100644 (file)
index 0000000..01062e4
--- /dev/null
+++ b/Documentation/core-api/phyr.rst
@@ -0,0 +1,23 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+===============
+Physical Ranges
+===============
+
+:Author: Matthew Wilcox
+
+Overview
+========
+
+The Physical Range (abbreviated as phyr) is a data structure which
+represents a contiguous range of memory which is typically used for I/O.
+The memory is physically addressable by the CPU, although there may not
+be a virtual address assigned to that memory.  The phyr can be used to
+obtain a DMA mapping for any part of the range.  Usually we use an array
+of phyr to represent a logical (or virtual) range which is physically
+discontiguous.
+
+Functions and structures
+========================
+
+.. kernel-doc:: include/linux/phyr.h

diff --git a/include/linux/phyr.h b/include/linux/phyr.h
new file mode 100644 (file)
index 0000000..bf30373
--- /dev/null
+++ b/include/linux/phyr.h
@@ -0,0 +1,31 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+#ifndef _LINUX_PHYR_H
+#define _LINUX_PHYR_H
+
+#include <linux/scatterlist.h>
+
+/**
+ * struct phyr - A descriptor for a physical range.
+ * @phyr_addr: The lowest address of the range.
+ * @phyr_size: The number of bytes in the range.
+ *
+ * The phyr represents a range of CPU-addressable memory.  If HIGHMEM is
+ * in use, the phyr may not have a virtual address associated with it.
+ * There may not be a struct page for the physical addresses.  The phyr
+ * is intended for use primarily to describe a range that will be used
+ * for I/O; use struct resource to represent an arbitrary range of
+ * physical addresses.
+ *
+ * This structure is 8 bytes on 32-bit machines without HIGHMEM, 12
+ * bytes on 32-bit machines with HIGHMEM and 16 bytes on 64-bit machines.
+ */
+struct phyr {
+       phys_addr_t     phyr_addr;
+       size_t          phyr_size;
+};
+
+int get_user_phyr(struct sg_append_table *sgt_append, unsigned long cur_base,
+                size_t max_seg_size, unsigned long npages,
+                unsigned int gup_flags);
+
+#endif /* _LINUX_PHYR_H */