From 09247921e52c4e85ef46e3fbca85382ab6b8cc5c Mon Sep 17 00:00:00 2001 From: Mike Smith Date: Fri, 20 Apr 2001 22:48:12 +0000 Subject: [PATCH] Add a manpage for libdevinfo. --- lib/libdevinfo/Makefile | 2 +- lib/libdevinfo/devinfo.3 | 237 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 238 insertions(+), 1 deletion(-) create mode 100644 lib/libdevinfo/devinfo.3 diff --git a/lib/libdevinfo/Makefile b/lib/libdevinfo/Makefile index 1be5c91c4353..e1260dbc297f 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 diff --git a/lib/libdevinfo/devinfo.3 b/lib/libdevinfo/devinfo.3 new file mode 100644 index 000000000000..c2f80b0f5974 --- /dev/null +++ b/lib/libdevinfo/devinfo.3 @@ -0,0 +1,237 @@ +.\" +.\" Copyright (c) 2001 Michael Smith +.\" 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 +.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.