The devinfo(3) library provides userspace access to the internal device
[dragonfly.git] / lib / libdevinfo / devinfo.h
1 /*-
2  * Copyright (c) 2000 Michael Smith
3  * Copyright (c) 2000 BSDi
4  * All rights reserved.
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions
8  * are met:
9  * 1. Redistributions of source code must retain the above copyright
10  *    notice, this list of conditions and the following disclaimer.
11  * 2. Redistributions in binary form must reproduce the above copyright
12  *    notice, this list of conditions and the following disclaimer in the
13  *    documentation and/or other materials provided with the distribution.
14  *
15  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25  * SUCH DAMAGE.
26  *
27  * $FreeBSD: src/lib/libdevinfo/devinfo.h,v 1.5 2005/08/31 14:57:39 rodrigc Exp $
28  * $DragonFly: src/lib/libdevinfo/devinfo.h,v 1.1 2008/09/30 12:20:29 hasso Exp $
29  */
30
31 #ifndef _DEVINFO_H_INCLUDED
32 #define _DEVINFO_H_INCLUDED
33
34 #include <sys/cdefs.h>
35 #include <sys/types.h>
36
37 typedef __uintptr_t     devinfo_handle_t;
38 #define DEVINFO_ROOT_DEVICE     ((devinfo_handle_t)0)
39
40 /*
41  * State of the device.
42  */
43 /* XXX not sure if I want a copy here, or expose sys/bus.h */
44 typedef enum devinfo_state {
45         DIS_NOTPRESENT,                 /* not probed or probe failed */
46         DIS_ALIVE,                      /* probe succeeded */
47         DIS_ATTACHED,                   /* attach method called */
48         DIS_BUSY                        /* device is open */
49 } devinfo_state_t;
50
51 struct devinfo_dev {
52         devinfo_handle_t        dd_handle;      /* device handle */
53         devinfo_handle_t        dd_parent;      /* parent handle */
54
55         char                    *dd_name;       /* name of device */
56         char                    *dd_desc;       /* device description */
57         char                    *dd_drivername; /* name of attached driver*/
58         char                    *dd_pnpinfo;    /* pnp info from parent bus */
59         char                    *dd_location;   /* Where bus thinks dev at */
60         uint32_t                dd_devflags;    /* API flags */
61         uint16_t                dd_flags;       /* internal dev flags */
62         devinfo_state_t         dd_state;       /* attacement state of dev */
63 };
64
65 struct devinfo_rman {
66         devinfo_handle_t        dm_handle;      /* resource manager handle */
67
68         unsigned long           dm_start;       /* resource start */
69         unsigned long           dm_size;        /* resource size */
70     
71         char                    *dm_desc;       /* resource description */
72 };
73
74 struct devinfo_res {
75         devinfo_handle_t        dr_handle;      /* resource handle */
76         devinfo_handle_t        dr_rman;        /* resource manager handle */
77         devinfo_handle_t        dr_device;      /* owning device */
78
79         unsigned long           dr_start;       /* region start */
80         unsigned long           dr_size;        /* region size */
81         /* XXX add flags */
82 };
83
84 __BEGIN_DECLS
85
86 /*
87  * Acquire a coherent copy of the kernel's device and resource tables.
88  * This must return success (zero) before any other interfaces will
89  * function.  Sets errno on failure.
90  */
91 extern int      devinfo_init(void);
92
93 /*
94  * Release the storage associated with the internal copy of the device
95  * and resource tables. devinfo_init must be called before any attempt
96  * is made to use any other interfaces.
97  */
98 extern void     devinfo_free(void);
99
100 /*
101  * Find a device/resource/resource manager by its handle.
102  */
103 extern struct devinfo_dev
104         *devinfo_handle_to_device(devinfo_handle_t handle);
105 extern struct devinfo_res
106         *devinfo_handle_to_resource(devinfo_handle_t handle);
107 extern struct devinfo_rman
108         *devinfo_handle_to_rman(devinfo_handle_t handle);
109
110 /*
111  * Iterate over the children of a device, calling (fn) on each.  If
112  * (fn) returns nonzero, abort the scan and return.
113  */
114 extern int
115         devinfo_foreach_device_child(struct devinfo_dev *parent, 
116             int (* fn)(struct devinfo_dev *child, void *arg), 
117             void *arg);
118
119 /*
120  * Iterate over all the resources owned by a device, calling (fn) on each.
121  * If (fn) returns nonzero, abort the scan and return.
122  */
123 extern int
124         devinfo_foreach_device_resource(struct devinfo_dev *dev,
125             int (* fn)(struct devinfo_dev *dev, 
126             struct devinfo_res *res, void *arg),
127             void *arg);
128
129 /*
130  * Iterate over all the resources owned by a resource manager, calling (fn)
131  * on each.  If (fn) returns nonzero, abort the scan and return.
132  */
133 extern int
134         devinfo_foreach_rman_resource(struct devinfo_rman *rman,
135             int (* fn)(struct devinfo_res *res, void *arg),
136             void *arg);
137
138 /*
139  * Iterate over all the resource managers, calling (fn) on each.  If (fn)
140  * returns nonzero, abort the scan and return.
141  */
142 extern int
143         devinfo_foreach_rman(int (* fn)(struct devinfo_rman *rman, void *arg),
144             void *arg);
145
146 __END_DECLS
147
148 #endif /* ! _DEVINFO_H_INCLUDED */