1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2008 Sun Microsystems, Inc. All rights reserved. 13.\" Copyright 2016 Nexenta Systems, Inc. 14.\" 15.Dd July 26, 2016 16.Dt DEVFS_CLEAN 9F 17.Os 18.Sh NAME 19.Nm devfs_clean 20.Nd destroy unreferenced devfs nodes and detach devices 21.Sh SYNOPSIS 22.In sys/fs/dv_node.h 23.Ft int 24.Fo devfs_clean 25.Fa "dev_info_t *dip" 26.Fa "char *devnm" 27.Fa "uint_t flags" 28.Fc 29.Sh INTERFACE LEVEL 30.Sy Volatile - 31private DDI function 32.Pp 33This is a private function that is not part of the stable DDI. 34It may be removed or changed at any time. 35.Sh PARAMETERS 36.Bl -tag -width Ds 37.It Va dip 38A pointer to the device's 39.Vt dev_info 40structure. 41Clean up is rooted at this device. 42.It Va devnm 43An optional character string used to restrict the devfs nodes list. 44.It Va flags 45The following flag is supported: 46.Bl -tag -width "DV_CLEAN_FORCE" 47.It Sy DV_CLEAN_FORCE 48force clean of referenced directories, referenced empty directories are marked 49as stale to facilitate DR 50.Pq dynamic reconfiguration 51.El 52.El 53.Sh DESCRIPTION 54The 55.Fn devfs_clean 56function is used to clean up and detach devices from the system. 57While many device drivers may have one or more minor nodes created with 58.Xr ddi_create_minor_node 9F , 59some device drivers may have children devices with different device drivers 60attached. 61Each of these entries shows up in the file system of the global zone under 62.Pa /devices 63.Po see 64.Xr devfs 4FS 65.Pc . 66These nodes are referred to as a devfs nodes 67.Pq Vt dv_node . 68.Pp 69.Nm devfs 70caches unreferenced devfs nodes to speed up the performance of 71.Nm ls , 72.Nm find , 73etc. 74The 75.Fn devfs_clean 76function is used to cleanup cached nodes to reclaim memory as well as to 77facilitate device removal 78.Pq devfs nodes reference dev_info nodes, which prevents driver from detaching . 79.Pp 80The 81.Fn devfs_clean 82function starts searching the tree rooted at 83.Va dip . 84All directories encountered are recursed through. 85If 86.Va devnm 87is not NULL, then it is used to limit the nodes that it searches. 88It compares the name of the node, ignoring any part of the device's name that 89corresponds to a minor node. 90If 91.Va devnm 92has been specified, then cleanup stops immediately after a busy devfs node has 93been encountered. 94.Pp 95Not all nodes may be cleaned up when a driver calls the 96.Fn devfs_clean 97function. 98However, this is a non-fatal situation. 99Callers should continue trying to offline devices as many holds from userland 100processes may exist due to device contracts which will be released when the 101device is offlined. 102.Pp 103If a shell parks in a 104.Pa /devices 105directory, the devfs node will be held, preventing the corresponding device to 106be detached. 107This would be a denial of service against DR (dynamic reconfiguration). 108To prevent this, DR code calls 109.Fn devfs_clean 110with the 111.Sy DV_CLEAN_FORCE 112flag. 113.Sh CONTEXT 114This function may be called in user or kernel context. 115.Sh RETURN VALUES 116The 117.Fn devfs_clean 118function always succeeds and returns zero. 119.Sh SEE ALSO 120.Xr devfs 4FS 121