From 9194e8e1d8487310e321f969093a7ccf85e40e32 Mon Sep 17 00:00:00 2001
From: Alexey Zelkin <phantom@FreeBSD.org>
Date: Wed, 17 Nov 1999 21:54:53 +0000
Subject: MFC: rev. 1.4, Document the new generic memory range management
 ioctls

---
 share/man/man4/mem.4 | 110 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 110 insertions(+)

(limited to 'share/man')

diff --git a/share/man/man4/mem.4 b/share/man/man4/mem.4
index d4cd30c41033..58d019cea00a 100644
--- a/share/man/man4/mem.4
+++ b/share/man/man4/mem.4
@@ -70,14 +70,124 @@ is
 .Dv UPAGES
 long, and ends at virtual
 address 0xf0000000.
+.Sh IOCTL INTERFACE
+Several architectures allow attributes to be associated with ranges of physical
+memory.  These attributes can be manipulated via
+.Fn ioctl
+calls performed on
+.Nm /dev/mem .
+Declarations and data types are to be found in
+.Pa <memrange.h>
+.Pp
+The specific attributes, and number of programmable ranges may vary between
+architectures.  The full set of supported attributes is:
+.Bl -tag -width 10
+.It MDF_UNCACHEABLE
+The region is not cached.
+.It MDF_WRITECOMBINE
+Writes to the region may be combined or performed out of order.
+.It MDF_WRITETHROUGH
+Writes to the region are committed synchronously.
+.It MDF_WRITEBACK
+Writes to the region are committed asynchronously.
+.It MDF_WRITEPROTECT
+The region cannot be written to.
+.El
+.Pp
+Memory ranges are described by
+.Fa struct mem_range_desc :
+.Bd -literal -offset indent
+u_int64_t	mr_base;	/\(** physical base address \(**/
+u_int64_t	mr_len;		/\(** physical length of region \(**/
+int		mr_flags;	/\(** attributes of region \(**/
+char		mr_owner[8];
+.Ed
+.Pp
+In addition to the region attributes listed above, the following flags
+may also be set in the
+.Fa mr_flags
+field:
+.Bl -tag -width 10
+.It MDF_FIXBASE
+The region's base address cannot be changed.
+.It MDF_FIXLEN
+The region's length cannot be changed.
+.It MDF_FIRMWARE
+The region is believed to have been established by the system firmare.
+.It MDF_ACTIVE
+The region is currently active.
+.It MDF_BOGUS
+We believe the region to be invalid or otherwise erroneous.
+.It MDF_FIXACTIVE
+The region cannot be disabled.
+.It MDF_BUSY
+The region is currently owned by another process and may not be 
+altered.
+.El
+.Pp
+Operations are performed using
+.Fa struct mem_range_op :
+.Bd -literal -offset indent
+struct mem_range_desc	*mo_desc;
+int			mo_arg[2];
+.Ed
+.Pp
+The
+.Fa MEMRANGE_GET
+ioctl is used to retrieve current memory range attributes. If
+.Fa mo_arg[0]
+is set to 0, it will be updated with the total number of memory range
+descriptors.  If greater than 0, the array at
+.Fa mo_desc
+will be filled with a corresponding number of descriptor structures,
+or the maximum, whichever is less.
+.Pp
+The 
+.Fa MEMRANGE_SET
+ioctl is used to add, alter and remove memory range attributes.  A range
+with the MDF_FIXACTIVE flag may not be removed; a range with the MDF_BUSY
+flag may not be removed or updated.
+.Pp
+.Fa mo_arg[0] 
+should be set to MEMRANGE_SET_UPDATE to update an existing
+or establish a new range, or to MEMRANGE_SET_REMOVE to remove a range.
+.Pp
+.Sh RETURN VALUES
+.Bl -tag -width 10
+.It EOPNOTSUPP
+Memory range operations are not supported on this architecture.
+.It ENXIO
+No memory range descriptors are available (eg. firmware has not enabled
+any).
+.It EINVAL
+The memory range supplied as an argument is invalid or overlaps another
+range in a fashion not supported by this architecture.
+.It EBUSY
+An attempt to remove or update a range failed because the range is busy.
+.It ENOSPC
+An attempt to create a new range failed due to a shortage of hardware
+resources (eg. descriptor slots).
+.It ENOENT
+An attempt to remove a range failed because no range matches the descriptor
+base/length supplued.
+.It EPERM
+An attempt to remove a range failed because the range is permanently
+enabled.
+.El
+.Sh BUGS
+Busy range attributes are not yet managed correctly.
 .Sh FILES
 .Bl -tag -width Pa -compact
 .It Pa /dev/mem
 .It Pa /dev/kmem
 .El
+.Sh SEE ALSO
+.Xr memcontrol 8
 .Sh HISTORY
 The
 .Nm mem ,
 .Nm kmem
 files appeared in
 .At v6 .
+The ioctl interface for memory range attributes was added in
+.Fx 3.2 .
-- 
cgit v1.3