git: 076e44839160 - main - uio.9: Document uiomove_fromphys()

The branch main has been updated by 0mp:

URL: https://cgit.FreeBSD.org/src/commit/?id=076e44839160f74f96fda83fa81c3acb41b9ebc8

commit 076e44839160f74f96fda83fa81c3acb41b9ebc8
Author:     Mateusz Piotrowski <0mp@FreeBSD.org>
AuthorDate: 2026-03-20 07:52:28 +0000
Commit:     Mateusz Piotrowski <0mp@FreeBSD.org>
CommitDate: 2026-05-08 09:05:57 +0000

    uio.9: Document uiomove_fromphys()
    
    Reviewed by:    kib
    Discussed with: markj, royger
    MFC after:      3 days
    Differential Revision:  https://reviews.freebsd.org/D54070
---
 share/man/man9/Makefile |  1 +
 share/man/man9/uio.9    | 45 ++++++++++++++++++++++++++++++++++-----------
 2 files changed, 35 insertions(+), 11 deletions(-)

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 29c822c10eb2..fbb981891ce4 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -2333,6 +2333,7 @@ MLINKS+=uidinfo.9 uifind.9 \
 	uidinfo.9 uihold.9
 MLINKS+=uio.9 uiomove.9 \
 	uio.9 uiomove_frombuf.9 \
+	uio.9 uiomove_fromphys.9 \
 	uio.9 uiomove_nofault.9
 MLINKS+=unr.9 alloc_unr.9 \
 	unr.9 alloc_unrl.9 \
diff --git a/share/man/man9/uio.9 b/share/man/man9/uio.9
index b143eb6e8e62..a7563125a351 100644
--- a/share/man/man9/uio.9
+++ b/share/man/man9/uio.9
@@ -23,13 +23,14 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd October 22, 2025
+.Dd May 7, 2026
 .Dt UIO 9
 .Os
 .Sh NAME
 .Nm uio ,
 .Nm uiomove ,
 .Nm uiomove_frombuf ,
+.Nm uiomove_fromphys ,
 .Nm uiomove_nofault
 .Nd device driver I/O routines
 .Sh SYNOPSIS
@@ -37,25 +38,29 @@
 .In sys/uio.h
 .Bd -literal
 struct uio {
-	struct	iovec *uio_iov;		/* scatter/gather list */
-	int	uio_iovcnt;		/* length of scatter/gather list */
-	off_t	uio_offset;		/* offset in target object */
-	ssize_t	uio_resid;		/* remaining bytes to copy */
-	enum	uio_seg uio_segflg;	/* address space */
-	enum	uio_rw uio_rw;		/* operation */
-	struct	thread *uio_td;		/* owner */
+	struct iovec	*uio_iov;	/* scatter/gather list */
+	int		 uio_iovcnt;	/* length of scatter/gather list */
+	off_t		 uio_offset;	/* offset in target object */
+	ssize_t		 uio_resid;	/* remaining bytes to process */
+	enum uio_seg	 uio_segflg;	/* address space */
+	enum uio_rw	 uio_rw;	/* operation */
+	struct thread	*uio_td;	/* owner */
 };
 .Ed
+.Pp
 .Ft int
 .Fn uiomove "void *buf" "int howmuch" "struct uio *uiop"
 .Ft int
 .Fn uiomove_frombuf "void *buf" "int howmuch" "struct uio *uiop"
 .Ft int
+.Fn uiomove_fromphys "vm_page_t ma[]" "vm_offset_t offset" "int howmuch" "struct uio *uiop"
+.Ft int
 .Fn uiomove_nofault "void *buf" "int howmuch" "struct uio *uiop"
 .Sh DESCRIPTION
 The functions
 .Fn uiomove ,
 .Fn uiomove_frombuf ,
+.Fn uiomove_fromphys ,
 and
 .Fn uiomove_nofault
 are used to transfer data between buffers and I/O vectors that might
@@ -152,10 +157,27 @@ When
 .Va uio_offset
 is greater than or equal to the buffer size, the result is success
 with no bytes transferred, effectively signaling EOF.
+.Pp
+The
+.Fn uiomove_fromphys
+function provides a machine-independent way to copy memory
+to and from the physical address space.
+The
+.Fa "ma[]"
+argument is an array of physical pages.
+Every physical page address in the array provides
+a page-sized chunk of the physical space.
+The
+.Fa "offset"
+argument is the offset into the
+.Fa "ma[]"
+array.
+In particular, the offset does not have to lie within the first page.
 .Sh RETURN VALUES
 On success
 .Fn uiomove ,
 .Fn uiomove_frombuf ,
+.Fn uiomove_fromphys ,
 and
 .Fn uiomove_nofault
 will return 0; on error they will return an appropriate error code.
@@ -168,7 +190,7 @@ will not work (the buffer pointer is not being advanced in case of a
 partial read), it is just here to demonstrate the
 .Nm
 handling.
-.Bd -literal
+.Bd -literal -offset 2n
 /* MIN() can be found there: */
 #include <sys/param.h>
 
@@ -200,7 +222,8 @@ fooread(struct cdev *dev, struct uio *uio, int flag)
 }
 .Ed
 .Sh ERRORS
-.Fn uiomove
+.Fn uiomove ,
+.Fn uiomove_fromphys
 and
 .Fn uiomove_nofault
 will fail and return the following error code if:
@@ -211,7 +234,7 @@ The invoked
 or
 .Xr copyout 9
 returned
-.Er EFAULT
+.Er EFAULT .
 .El
 .Pp
 In addition,