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