Add a manpage for libdevinfo.

2 files changed, 238 insertions, 1 deletions

diff --git a/lib/libdevinfo/Makefile b/lib/libdevinfo/Makefile
index 1be5c91..e1260db 100644
--- a/lib/libdevinfo/Makefile
+++ b/lib/libdevinfo/Makefile
@@ -4,6 +4,6 @@ LIB=	devinfo
 SRCS=	devinfo.c
 INCS=	devinfo.h devinfo_var.h
 
-NOMAN=	yes
+MAN3=	devinfo.3
 
 .include <bsd.lib.mk>
diff --git a/lib/libdevinfo/devinfo.3 b/lib/libdevinfo/devinfo.3
new file mode 100644
index 0000000..c2f80b0
--- /dev/null
+++ b/lib/libdevinfo/devinfo.3
@@ -0,0 +1,237 @@
+.\"
+.\" Copyright (c) 2001 Michael Smith <msmith@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd April 19, 2001
+.Dt DEVINFO 3
+.Os FreeBSD
+.Sh NAME
+.Nm devinfo ,
+.Nm devinfo_init ,
+.Nm devinfo_free ,
+.Nm devinfo_handle_to_device ,
+.Nm devinfo_handle_to_resource ,
+.Nm devinfo_handle_to_rman ,
+.Nm devinfo_foreach_device_child ,
+.Nm devinfo_foreach_device_resource ,
+.Nm devinfo_foreach_rman_resource ,
+.Nm devinfo_foreach_rman
+.Nd device and resource information utility library
+.Sh LIBRARY
+.Lb libdevinfo
+.Sh SYNOPSIS
+.Fd #include <devinfo.h>
+.Ft int
+.Fn devinfo_init "void"
+.Ft void
+.Fn devinfo_free "void"
+.Ft struct devinfo_dev *
+.Fn devinfo_handle_to_device "devinfo_handle_t handle"
+.Ft struct devinfo_res *
+.Fn devinfo_handle_to_resource "devinfo_handle_t handle"
+.Ft struct devinfo_rman *
+.Fn devinfo_handle_to_rman "devinfo_handle_t handle"
+.Ft int
+.Fo devinfo_foreach_device_child
+.Fa "struct devinfo_dev *parent" 
+.Fa "int (* fn)(struct devinfo_dev *child, void *arg)"
+.Fa "void *arg"
+.Fc
+.Ft int
+.Fo devinfo_foreach_device_resource
+.Fa "struct devinfo_dev *dev"
+.Fa "int (* fn)(struct devinfo_dev *dev, struct devinfo_res *res, void *arg)"
+.Fa "void *arg"
+.Fc
+.Ft int
+.Fo devinfo_foreach_rman_resource
+.Fa "struct devinfo_rman *rman"
+.Fa "int (* fn)(struct devinfo_res *res, void *arg)"
+.Fa "void *arg"
+.Fc
+.Ft int
+.Fo devinfo_foreach_rman
+.Fa "int (* fn)(struct devinfo_rman *rman, void *arg)"
+.Fa "void *arg"
+.Fc
+.Sh DESCRIPTION
+The
+.Nm
+library provides access to the kernel's internal device hierarchy
+and to the I/O resource manager.
+The library uses a
+.Xr sysctl 3
+interface to obtain a snapshot of the kernel's state,
+which is then made available to the application.
+.Pp
+Due to the fact that the information may be logically arranged
+in a number of different fashions,
+the library does not attempt to impose any structure on the data.
+.Pp
+Device, resource, and resource manager information is returned in
+datastructures defined in
+.Aq Pa devinfo.h :
+.Bd -literal -offset indent
+struct devinfo_dev {
+    devinfo_handle_t	dd_handle;	/* device handle */
+    devinfo_handle_t	dd_parent;	/* parent handle */
+    char		*dd_name;	/* name of device */
+    char		*dd_desc;	/* device description */
+    char		*dd_drivername;	/* name of attached driver */
+};
+
+struct devinfo_rman {
+    devinfo_handle_t	dm_handle;	/* resource manager handle */
+    u_long		dm_start;	/* resource start */
+    u_long		dm_size;	/* resource size */
+    char		*dm_desc;	/* resource description */
+};
+
+struct devinfo_res {
+    devinfo_handle_t	dr_handle;	/* resource handle */
+    devinfo_handle_t	dr_rman;	/* resource manager handle */
+    devinfo_handle_t	dr_device;	/* owning device */
+    u_long		dr_start;	/* region start */
+    u_long		dr_size;	/* region size */
+};
+.Ed
+.Pp
+The
+.Va devinfo_handle_t
+values can be used to look up the correspondingly referenced structures.
+.Pp
+.Fn devinfo_init
+takes a snapshot of the kernel's internal device and resource state.
+It returns nonzero
+if after a number of retries a consistent snapshot cannot be obtained.
+.Fn devinfo_init
+must be called before any other functions can be used.
+.Pp
+.Fn devinfo_free
+releases the memory associated with the snapshot.
+Any pointers returned by other functions are invalidated by this,
+and
+.Fn devinfo_init
+must be called again before using any other functions.
+.Pp
+.Fn devinfo_handle_to_device ,
+.Fn devinfo_handle_to_resource
+and
+.Fn devinfo_handle_to_rman
+return pointers to 
+.Va devinfo_dev ,
+.Va devinfo_res
+and
+.Va devinfo_rman
+structures respectively based on the
+.Va devinfo_handle_t
+passed to them.
+These functions can be used to traverse the tree from any node to any
+other node.
+If
+.Fn devinfo_handle_to_device
+is passed the constant
+.Dv DEVINFO_ROOT_DEVICE
+it will return the handle to the root of the device tree.
+.Pp
+.Fn devinfo_foreach_device_child
+invokes its callback argument
+.Ar fn
+on every device which is an immediate child of
+.Ar device .
+.Ar fn
+is also passed
+.Ar arg ,
+allowing state to be passed to the callback function.
+If
+.Ar fn
+returns a nonzero error value the traversal is halted,
+and
+.Fn devinfo_foreach_device_child
+returns the error value to its caller.
+.Pp
+.Fr devinfo_foreach_device_resource
+invokes its callback argument
+.Ar fn
+on every resource which is owned by
+.Ar device .
+.Ar fn
+is also passed
+.Ar device
+and
+.Ar arg ,
+allowing state to be passed to the callback function.
+If
+.Ar fn
+returns a nonzero error value the traversal is halted,
+and
+.Fn devinfo_foreach_device_resource
+returns the error value to its caller.
+.Pp
+.Fn devinfo_foreach_rman_resource
+invokes its callback argument
+.Ar fn
+on every resource within the resource manager
+.Ar rman .
+.Ar fn
+is also passed
+.Ar arg ,
+allowing state to be passed to the callback function.
+If
+.Ar fn
+returns a nonzero error value the traversal is halted,
+and
+.Fn devinfo_foreach_rman_resource
+returns the error value to its caller.
+.Pp
+.Fn devinfo_foreach_rman
+invokes its callback argument
+.Ar fn
+on every resource manager.
+.Ar fn is also passed
+.Ar arg ,
+allowing state to be passed to the callback function.
+If
+.Ar fn
+returns a nonzero error value the traversal is halted,
+and
+.Fn devinfo_foreach_rman
+returns the error value to its caller.
+.Sh SEE ALSO
+.Xr devstat 3
+.Sh HISTORY
+.Nm
+first appeared in
+.Os
+version 5.0
+.Sh AUTHORS
+.An Michael Smith Aq msmith@FreeBSD.org
+.Sh BUGS
+This is the first implementation of the library,
+and the interface is still subject to refinement.
+.Pp
+The interface does not report device classes or drivers,
+making it hard to sort by class or driver.