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

@@ -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 \

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 */
+	struct iovec	*uio_iov;	/* scatter/gather list */
-	int	uio_iovcnt;		/* length of scatter/gather list */
+	int		 uio_iovcnt;	/* length of scatter/gather list */
-	off_t	uio_offset;		/* offset in target object */
+	off_t		 uio_offset;	/* offset in target object */
-	ssize_t	uio_resid;		/* remaining bytes to copy */
+	ssize_t		 uio_resid;	/* remaining bytes to process */
-	enum	uio_seg uio_segflg;	/* address space */
+	enum uio_seg	 uio_segflg;	/* address space */
-	enum	uio_rw uio_rw;		/* operation */
+	enum uio_rw	 uio_rw;	/* operation */
-	struct	thread *uio_td;		/* owner */
+	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,