share/man/man9/dev_refthread.9

   1 .\" Copyright (c) 2018 Conrad Meyer <cem@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd August 29, 2018
  28 .Dt DEV_REFTHREAD 9
  29 .Os
  30 .Sh NAME
  31 .Nm dev_refthread ,
  32 .Nm devvn_refthread ,
  33 .Nm dev_relthread
  34 .Nd safely access device methods
  35 .Sh SYNOPSIS
  36 .In sys/param.h
  37 .In sys/conf.h
  38 .Ft "struct cdevsw *"
  39 .Fn dev_refthread "struct cdev *dev" "int *ref"
  40 .Ft "struct cdevsw *"
  41 .Fn devvn_refthread "struct vnode *vp" "struct cdev **devp" "int *ref"
  42 .Ft void
  43 .Fn dev_relthread "struct cdev *dev" "int ref"
  44 .Sh DESCRIPTION
  45 The
  46 .Fn dev_refthread
  47 (or
  48 .Fn devvn_refthread )
  49 and
  50 .Fn dev_relthread
  51 routines provide a safe way to access
  52 .Xr devfs 5
  53 devices that may be concurrently destroyed by
  54 .Fn destroy_dev
  55 (e.g., removable media).
  56 .Pp
  57 If successful,
  58 .Fn dev_refthread
  59 and
  60 .Fn devvn_refthread
  61 acquire a "thread reference" to the associated
  62 .Vt "struct cdev"
  63 and return a non-NULL pointer to the cdev's
  64 .Vt "struct cdevsw"
  65 method table.
  66 For the duration of that reference, the cdev's associated private data and
  67 method table object are valid.
  68 Destruction of the cdev sleeps until the thread reference is released.
  69 .Pp
  70 A reference cannot prevent media removal.
  71 It is an implementation detail of individual drivers how method calls from
  72 callers with
  73 .Fn dev_refthread
  74 references are handled when the device is
  75 pending destruction.
  76 A common behavior for disk devices is to return the
  77 .Er ENXIO
  78 status, but that is not required by this KPI.
  79 .Pp
  80 The
  81 .Fn devvn_refthread
  82 variant of
  83 .Fn dev_refthread
  84 extracts the
  85 .Vt "struct cdev"
  86 pointer out of the
  87 .Dv VCHR
  88 .Xr vnode 9
  89 automatically before performing the same actions as
  90 .Fn dev_refthread .
  91 Additionally, a pointer to the
  92 .Vt "struct cdev"
  93 is returned to the caller via
  94 .Fa "*devp" .
  95 .Fn devvn_refthread
  96 correctly handles possible parallel reclamation of the vnode.
  97 .Pp
  98 .Fn dev_relthread
  99 is used to release a reference to a
 100 .Vt "struct cdev" .
 101 .Fn dev_relthread
 102 .Sy must
 103 only be invoked when the associated invocation of
 104 .Fn dev_refthread
 105 or
 106 .Fn devvn_refthread
 107 returned a non-NULL
 108 .Vt "struct cdevsw *" .
 109 .Sh CONTEXT
 110 .Vt struct cdev
 111 objects have two reference counts,
 112 .Va si_refcount
 113 and
 114 .Va si_threadcount .
 115 The
 116 .Fn dev_refthread ,
 117 .Fn devvn_refthread ,
 118 and
 119 .Fn dev_relthread
 120 functions manipulate the
 121 .Va si_threadcount .
 122 The
 123 .Va si_threadcount
 124 reference guarantees the liveness of the
 125 .Vt struct cdev
 126 object.
 127 The other
 128 .Va si_refcount
 129 reference provides only the weaker guarantee that the memory backing the
 130 .Vt struct cdev
 131 has not been freed.
 132 .Sh RETURN VALUES
 133 If
 134 .Fn dev_refthread
 135 or
 136 .Fn devvn_refthread
 137 are unsuccessful, they return
 138 .Dv NULL .
 139 .Bf Em
 140 If these routines are unsuccessful, they do not increment the
 141 .Vt "struct cdev"
 142 .Va si_threadcount
 143 and do not initialize the value pointed to by the
 144 .Fa "*ref"
 145 parameter in any way.
 146 .Ef
 147 .Sh SEE ALSO
 148 .Xr destroy_dev 9 ,
 149 .Xr devfs 5
 150 .Sh CAVEATS
 151 Do not invoke
 152 .Fn dev_relthread
 153 unless the matching refthread routine succeeded!