usr/src/man/man9f/devfs_clean.9f

   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 -
  31 private DDI function
  32 .Pp
  33 This is a private function that is not part of the stable DDI.
  34 It may be removed or changed at any time.
  35 .Sh PARAMETERS
  36 .Bl -tag -width Ds
  37 .It Va dip
  38 A pointer to the device's
  39 .Vt dev_info
  40 structure.
  41 Clean up is rooted at this device.
  42 .It Va devnm
  43 An optional character string used to restrict the devfs nodes list.
  44 .It Va flags
  45 The following flag is supported:
  46 .Bl -tag -width "DV_CLEAN_FORCE"
  47 .It Sy DV_CLEAN_FORCE
  48 force clean of referenced directories, referenced empty directories are marked
  49 as stale to facilitate DR
  50 .Pq dynamic reconfiguration
  51 .El
  52 .El
  53 .Sh DESCRIPTION
  54 The
  55 .Fn devfs_clean
  56 function is used to clean up and detach devices from the system.
  57 While many device drivers may have one or more minor nodes created with
  58 .Xr ddi_create_minor_node 9F ,
  59 some device drivers may have children devices with different device drivers
  60 attached.
  61 Each of these entries shows up in the file system of the global zone under
  62 .Pa /devices
  63 .Po see
  64 .Xr devfs 7FS
  65 .Pc .
  66 These nodes are referred to as a devfs nodes
  67 .Pq Vt dv_node .
  68 .Pp
  69 .Nm devfs
  70 caches unreferenced devfs nodes to speed up the performance of
  71 .Nm ls ,
  72 .Nm find ,
  73 etc.
  74 The
  75 .Fn devfs_clean
  76 function is used to cleanup cached nodes to reclaim memory as well as to
  77 facilitate device removal
  78 .Pq devfs nodes reference dev_info nodes, which prevents driver from detaching .
  79 .Pp
  80 The
  81 .Fn devfs_clean
  82 function starts searching the tree rooted at
  83 .Va dip .
  84 All directories encountered are recursed through.
  85 If
  86 .Va devnm
  87 is not NULL, then it is used to limit the nodes that it searches.
  88 It compares the name of the node, ignoring any part of the device's name that
  89 corresponds to a minor node.
  90 If
  91 .Va devnm
  92 has been specified, then cleanup stops immediately after a busy devfs node has
  93 been encountered.
  94 .Pp
  95 Not all nodes may be cleaned up when a driver calls the
  96 .Fn devfs_clean
  97 function.
  98 However, this is a non-fatal situation.
  99 Callers should continue trying to offline devices as many holds from userland
 100 processes may exist due to device contracts which will be released when the
 101 device is offlined.
 102 .Pp
 103 If a shell parks in a
 104 .Pa /devices
 105 directory, the devfs node will be held, preventing the corresponding device to
 106 be detached.
 107 This would be a denial of service against DR (dynamic reconfiguration).
 108 To prevent this, DR code calls
 109 .Fn devfs_clean
 110 with the
 111 .Sy DV_CLEAN_FORCE
 112 flag.
 113 .Sh CONTEXT
 114 This function may be called in user or kernel context.
 115 .Sh RETURN VALUES
 116 The
 117 .Fn devfs_clean
 118 function always succeeds and returns zero.
 119 .Sh SEE ALSO
 120 .Xr devfs 7FS