1.\" $NetBSD: deviter.9,v 1.5 2014/03/18 18:20:40 riastradh Exp $ 2.\" 3.\" Copyright (c) 2009 David Young <dyoung@NetBSD.org> 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 David Young ``AS IS'' AND ANY EXPRESS 16.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 17.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL David Young BE LIABLE FOR ANY 19.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 21.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER 23.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 24.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN 25.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.\" NetBSD: pmf.9,v 1.12 2009/10/21 16:06:59 snj Exp 28.\" 29.\" Copyright (c) 2007 Jared D. McNeill <jmcneill@invisible.ca> 30.\" All rights reserved. 31.\" 32.\" Redistribution and use in source and binary forms, with or without 33.\" modification, are permitted provided that the following conditions 34.\" are met: 35.\" 1. Redistributions of source code must retain the above copyright 36.\" notice, this list of conditions and the following disclaimer. 37.\" 2. Redistributions in binary form must reproduce the above copyright 38.\" notice, this list of conditions and the following disclaimer in the 39.\" documentation and/or other materials provided with the distribution. 40.\" 41.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 42.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 43.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 44.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 45.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 46.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 47.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 48.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 49.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 50.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 51.\" POSSIBILITY OF SUCH DAMAGE. 52.\" 53.Dd November 4, 2009 54.Dt DEVITER 9 55.Os 56.Sh NAME 57.Nm deviter , 58.Nm deviter_first , 59.Nm deviter_init , 60.Nm deviter_next , 61.Nm deviter_release 62.Nd machine-independent device iteration API 63.Sh SYNOPSIS 64.In sys/device.h 65.Ft void 66.Fn deviter_init "deviter_t *di" "deviter_flags_t flags" 67.Ft device_t 68.Fn deviter_first "deviter_t *di" "deviter_flags_t flags" 69.Ft device_t 70.Fn deviter_next "deviter_t *di" 71.Ft void 72.Fn deviter_release "deviter_t *di" 73.Sh DESCRIPTION 74The machine-independent 75.Nm 76API lets interrupt handlers running at any priority level and kernel 77threads iterate over the devices attached to the kernel. 78Using 79.Nm , 80it is safe for an interrupt handler or a thread to iterate over 81devices attached to the kernel while another thread attaches or 82detaches the devices. 83.Sh DATA TYPES 84Kernel subsystems using 85.Nm 86may make use of the following data types: 87.Bl -tag -width compact 88.It Fa deviter_flags_t 89The kernel can iterate over devices for different purposes and in 90different orders. 91The following flags affect device iteration: 92.Bl -item -compact -offset indent 93.It 94.Dv DEVITER_F_RW 95.It 96.Dv DEVITER_F_SHUTDOWN 97.It 98.Dv DEVITER_F_LEAVES_FIRST 99.It 100.Dv DEVITER_F_ROOT_FIRST 101.El 102.It Fa deviter_t 103This is a device iteration 104.Dq cursor 105or 106.Dq iterator . 107It holds iteration state such as the next device to visit. 108.El 109.Sh FUNCTIONS 110.Bl -tag -width compact 111.It Fn deviter_init "di" "flags" 112Initialize the device iterator, 113.Fa di . 114Set bits in 115.Fa flags 116to affect the order of iteration. 117Set 118.Dv DEVITER_F_LEAVES_FIRST 119to visit each device only after visiting its children (visit the 120leaves of the device tree, first). 121Set 122.Dv DEVITER_F_ROOT_FIRST 123to visit each device before visiting its children (visit the root 124of the device tree, first). 125If you set neither 126.Dv DEVITER_F_LEAVES_FIRST 127nor 128.Dv DEVITER_F_ROOT_FIRST , 129.Nm 130returns devices in an arbitrary order. 131.Pp 132Set 133.Dv DEVITER_F_RW 134if your purpose for iterating over devices is to modify the device 135tree by attaching or detaching devices. 136Set 137.Dv DEVITER_F_SHUTDOWN 138if your purpose for iterating over devices is to detach all of 139the devices during system shutdown. 140.Dv DEVITER_F_SHUTDOWN 141implies 142.Dv DEVITER_F_RW . 143.It Fn deviter_next "di" 144Advance the iterator 145.Fa di 146to the next device. 147.Fn deviter_next 148returns the current device or 149.Dv NULL 150if there are no more devices. 151.Fn deviter_next 152is undefined if 153.Fa di 154has not been initialized using 155.Fn deviter_init 156or 157.Fn deviter_first . 158.It Fn deviter_first "di" "flags" 159Initialize the iterator 160.Fa di 161with 162.Fa flags . 163Return the first device according to the ordering 164indicated by 165.Fa flags 166and advance 167.Fa di 168to the second device, or 169return 170.Dv NULL 171if there are no devices. 172This is equivalent to calling 173.Fn deviter_init "di" "flags" 174and then 175.Fn deviter_next "di" . 176.It Fn deviter_release "di" 177Release all resources held by the iterator 178.Fa di . 179Every iterator that is initialized with 180.Fn deviter_first 181or 182.Fn deviter_init 183MUST be released. 184.El 185.Sh CODE REFERENCES 186Device iteration is implemented within the files 187.Pa sys/sys/device.h 188and 189.Pa sys/kern/subr_autoconf.c . 190.Sh SEE ALSO 191.Xr autoconf 9 , 192.Xr driver 9 193.Sh HISTORY 194.Nm 195appeared in 196.Nx 5.0 . 197.Sh AUTHORS 198.An David Young Aq Mt dyoung@NetBSD.org 199