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.\" $FreeBSD$ 30.\" 31.Dd February 11, 2018 32.Dt DEVICE_ADD_CHILD 9 33.Os 34.Sh NAME 35.Nm device_add_child , 36.Nm device_add_child_ordered 37.Nd "add a new device as a child of an existing device" 38.Sh SYNOPSIS 39.In sys/param.h 40.In sys/bus.h 41.Ft device_t 42.Fn device_add_child "device_t dev" "const char *name" "int unit" 43.Ft device_t 44.Fn device_add_child_ordered "device_t dev" "int order" "const char *name" "int unit" 45.Sh DESCRIPTION 46Create a new child device of 47.Fa dev . 48The 49.Fa name 50and 51.Fa unit 52arguments specify the name and unit number of the device. 53If the name is unknown then the caller should pass 54.Dv NULL . 55If the unit is unknown then the caller should pass 56.Dv -1 57and the system will choose the next available unit number. 58.Pp 59The name of the device is used to determine which drivers might be 60appropriate for the device. 61If a name is specified then only drivers of that name are probed. 62If no name is given then all drivers for the owning bus are probed. 63In any event, only the name of the device is stored so that one may 64safely unload/load a driver bound to that name. 65.Pp 66This allows buses which can uniquely identify device instances (such 67as PCI) to allow each driver to check each device instance for a 68match. 69For buses which rely on supplied probe hints where only one 70driver can have a chance of probing the device, the driver name should 71be specified as the device name. 72.Pp 73Normally unit numbers will be chosen automatically by the system and a 74unit number of 75.Dv -1 76should be given. 77When a specific unit number is desired (e.g.,\& for wiring a particular 78piece of hardware to a pre-configured unit number), that unit should 79be passed. 80If the specified unit number is already allocated, a new 81unit will be allocated and a diagnostic message printed. 82.Pp 83If the devices attached to a bus must be probed in a specific order 84(e.g.,\& for the ISA bus some devices are sensitive to failed probe attempts 85of unrelated drivers and therefore must be probed first), 86the 87.Fa order 88argument of 89.Fn device_add_child_ordered 90should be used to specify a partial ordering. 91The new device will be added before any existing device with a greater 92order. 93If 94.Fn device_add_child 95is used, then the new child will be added as if its order was zero. 96.Pp 97When adding a device in the context of 98.Xr DEVICE_IDENTIFY 9 99routine, the 100.Xr device_find_child 9 101routine should be used to ensure that the device has not already been 102added to the tree. 103Because the device name and 104.Vt devclass_t 105are associated at probe time (not child addition time), previous 106instances of the driver (say in a module that was later unloaded) may 107have already added the instance. 108Authors of bus drivers must likewise be careful when adding children 109when they are loaded and unloaded to avoid duplication of children 110devices. 111.Pp 112When adding a child to another device node, such as in an identify 113routine, use 114.Xr BUS_ADD_CHILD 9 115instead of 116.Xr device_add_child 9 . 117.Xr BUS_ADD_CHILD 9 118will call 119.Xr device_add_child 9 120and add the proper bus-specific data to the new child. 121.Fn device_add_child 122does not call 123.Xr BUS_ADD_CHILD 9 . 124.Sh RETURN VALUES 125The new device if successful, NULL otherwise. 126.Sh SEE ALSO 127.Xr BUS_ADD_CHILD 9 , 128.Xr device 9 , 129.Xr device_delete_child 9 , 130.Xr device_find_child 9 , 131.Xr DEVICE_IDENTIFY 9 132.Sh AUTHORS 133This manual page was written by 134.An Doug Rabson . 135