1.\" -*- nroff -*- 2.\" 3.\" Copyright (c) 1998 Doug Rabson 4.\" 5.\" All rights reserved. 6.\" 7.\" This program is free software. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 19.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 20.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 21.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 23.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 27.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28.\" 29.Dd February 11, 2018 30.Dt DEVICE_ADD_CHILD 9 31.Os 32.Sh NAME 33.Nm device_add_child , 34.Nm device_add_child_ordered 35.Nd "add a new device as a child of an existing device" 36.Sh SYNOPSIS 37.In sys/param.h 38.In sys/bus.h 39.Ft device_t 40.Fn device_add_child "device_t dev" "const char *name" "int unit" 41.Ft device_t 42.Fn device_add_child_ordered "device_t dev" "int order" "const char *name" "int unit" 43.Sh DESCRIPTION 44Create a new child device of 45.Fa dev . 46The 47.Fa name 48and 49.Fa unit 50arguments specify the name and unit number of the device. 51If the name is unknown then the caller should pass 52.Dv NULL . 53If the unit is unknown then the caller should pass 54.Dv -1 55and the system will choose the next available unit number. 56.Pp 57The name of the device is used to determine which drivers might be 58appropriate for the device. 59If a name is specified then only drivers of that name are probed. 60If no name is given then all drivers for the owning bus are probed. 61In any event, only the name of the device is stored so that one may 62safely unload/load a driver bound to that name. 63.Pp 64This allows buses which can uniquely identify device instances (such 65as PCI) to allow each driver to check each device instance for a 66match. 67For buses which rely on supplied probe hints where only one 68driver can have a chance of probing the device, the driver name should 69be specified as the device name. 70.Pp 71Normally unit numbers will be chosen automatically by the system and a 72unit number of 73.Dv -1 74should be given. 75When a specific unit number is desired (e.g.,\& for wiring a particular 76piece of hardware to a pre-configured unit number), that unit should 77be passed. 78If the specified unit number is already allocated, a new 79unit will be allocated and a diagnostic message printed. 80.Pp 81If the devices attached to a bus must be probed in a specific order 82(e.g.,\& for the ISA bus some devices are sensitive to failed probe attempts 83of unrelated drivers and therefore must be probed first), 84the 85.Fa order 86argument of 87.Fn device_add_child_ordered 88should be used to specify a partial ordering. 89The new device will be added before any existing device with a greater 90order. 91If 92.Fn device_add_child 93is used, then the new child will be added as if its order was zero. 94.Pp 95When adding a device in the context of 96.Xr DEVICE_IDENTIFY 9 97routine, the 98.Xr device_find_child 9 99routine should be used to ensure that the device has not already been 100added to the tree. 101Because the device name and 102.Vt devclass_t 103are associated at probe time (not child addition time), previous 104instances of the driver (say in a module that was later unloaded) may 105have already added the instance. 106Authors of bus drivers must likewise be careful when adding children 107when they are loaded and unloaded to avoid duplication of children 108devices. 109.Pp 110When adding a child to another device node, such as in an identify 111routine, use 112.Xr BUS_ADD_CHILD 9 113instead of 114.Xr device_add_child 9 . 115.Xr BUS_ADD_CHILD 9 116will call 117.Xr device_add_child 9 118and add the proper bus-specific data to the new child. 119.Fn device_add_child 120does not call 121.Xr BUS_ADD_CHILD 9 . 122.Sh RETURN VALUES 123The new device if successful, NULL otherwise. 124.Sh SEE ALSO 125.Xr BUS_ADD_CHILD 9 , 126.Xr device 9 , 127.Xr device_delete_child 9 , 128.Xr device_find_child 9 , 129.Xr DEVICE_IDENTIFY 9 130.Sh AUTHORS 131This manual page was written by 132.An Doug Rabson . 133