From owner-svn-src-head@freebsd.org Sat Oct 20 20:41:26 2018 Return-Path: Delivered-To: svn-src-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id C94C3FF50D7; Sat, 20 Oct 2018 20:41:26 +0000 (UTC) (envelope-from cem@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 7F18E86FF6; Sat, 20 Oct 2018 20:41:26 +0000 (UTC) (envelope-from cem@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 611FA232AB; Sat, 20 Oct 2018 20:41:26 +0000 (UTC) (envelope-from cem@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id w9KKfQ2f009022; Sat, 20 Oct 2018 20:41:26 GMT (envelope-from cem@FreeBSD.org) Received: (from cem@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id w9KKfQ07009021; Sat, 20 Oct 2018 20:41:26 GMT (envelope-from cem@FreeBSD.org) Message-Id: <201810202041.w9KKfQ07009021@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: cem set sender to cem@FreeBSD.org using -f From: Conrad Meyer Date: Sat, 20 Oct 2018 20:41:26 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r339485 - head/share/man/man9 X-SVN-Group: head X-SVN-Commit-Author: cem X-SVN-Commit-Paths: head/share/man/man9 X-SVN-Commit-Revision: 339485 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 20 Oct 2018 20:41:27 -0000 Author: cem Date: Sat Oct 20 20:41:25 2018 New Revision: 339485 URL: https://svnweb.freebsd.org/changeset/base/339485 Log: Add a dev_refthread.9 document. Reviewed by: kib Sponsored by: Dell EMC Isilon Differential: https://reviews.freebsd.org/D16897 Added: head/share/man/man9/dev_refthread.9 (contents, props changed) Modified: head/share/man/man9/Makefile Modified: head/share/man/man9/Makefile ============================================================================== --- head/share/man/man9/Makefile Sat Oct 20 20:34:36 2018 (r339484) +++ head/share/man/man9/Makefile Sat Oct 20 20:41:25 2018 (r339485) @@ -113,6 +113,7 @@ MAN= accept_filter.9 \ device_set_flags.9 \ DEVICE_SHUTDOWN.9 \ DEV_MODULE.9 \ + dev_refthread.9 \ devstat.9 \ devtoname.9 \ disk.9 \ @@ -878,6 +879,8 @@ MLINKS+=DB_COMMAND.9 DB_SHOW_ALL_COMMAND.9 \ DB_COMMAND.9 DB_SHOW_COMMAND.9 MLINKS+=DECLARE_MODULE.9 DECLARE_MODULE_TIED.9 MLINKS+=dev_clone.9 drain_dev_clone_events.9 +MLINKS+=dev_refthread.9 devvn_refthread.9 \ + dev_refthread.9 dev_relthread.9 MLINKS+=devfs_set_cdevpriv.9 devfs_clear_cdevpriv.9 \ devfs_set_cdevpriv.9 devfs_get_cdevpriv.9 MLINKS+=device_add_child.9 device_add_child_ordered.9 Added: head/share/man/man9/dev_refthread.9 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man9/dev_refthread.9 Sat Oct 20 20:41:25 2018 (r339485) @@ -0,0 +1,153 @@ +.\" Copyright (c) 2018 Conrad Meyer +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 29, 2018 +.Dt DEV_REFTHREAD 9 +.Os +.Sh NAME +.Nm dev_refthread , +.Nm devvn_refthread , +.Nm dev_relthread +.Nd safely access device methods +.Sh SYNOPSIS +.In sys/param.h +.In sys/conf.h +.Ft "struct cdevsw *" +.Fn dev_refthread "struct cdev *dev" "int *ref" +.Ft "struct cdevsw *" +.Fn devvn_refthread "struct vnode *vp" "struct cdev **devp" "int *ref" +.Ft void +.Fn dev_relthread "struct cdev *dev" "int ref" +.Sh DESCRIPTION +The +.Fn dev_refthread +(or +.Fn devvn_refthread ) +and +.Fn dev_relthread +routines provide a safe way to access +.Xr devfs 5 +devices that may be concurrently destroyed by +.Fn destroy_dev +(e.g., removable media). +.Pp +If successful, +.Fn dev_refthread +and +.Fn devvn_refthread +acquire a "thread reference" to the associated +.Vt "struct cdev" +and return a non-NULL pointer to the cdev's +.Vt "struct cdevsw" +method table. +For the duration of that reference, the cdev's associated private data and +method table object are valid. +Destruction of the cdev sleeps until the thread reference is released. +.Pp +A reference cannot prevent media removal. +It is an implementation detail of individual drivers how method calls from +callers with +.Fn dev_refthread +references are handled when the device is +pending destruction. +A common behavior for disk devices is to return the +.Er ENXIO +status, but that is not required by this KPI. +.Pp +The +.Fn devvn_refthread +variant of +.Fn dev_refthread +extracts the +.Vt "struct cdev" +pointer out of the +.Dv VCHR +.Xr vnode 9 +automatically before performing the same actions as +.Fn dev_refthread . +Additionally, a pointer to the +.Vt "struct cdev" +is returned to the caller via +.Fa "*devp" . +.Fn devvn_refthread +correctly handles possible parallel reclamation of the vnode. +.Pp +.Fn dev_relthread +is used to release a reference to a +.Vt "struct cdev" . +.Fn dev_relthread +.Sy must +only be invoked when the associated invocation of +.Fn dev_refthread +or +.Fn devvn_refthread +returned a non-NULL +.Vt "struct cdevsw *" . +.Sh CONTEXT +.Vt struct cdev +objects have two reference counts, +.Va si_refcount +and +.Va si_threadcount . +The +.Fn dev_refthread , +.Fn devvn_refthread , +and +.Fn dev_relthread +functions manipulate the +.Va si_threadcount . +The +.Va si_threadcount +reference guarantees the liveness of the +.Vt struct cdev +object. +The other +.Va si_refcount +reference provides only the weaker guarantee that the memory backing the +.Vt struct cdev +has not been freed. +.Sh RETURN VALUES +If +.Fn dev_refthread +or +.Fn devvn_refthread +are unsuccessful, they return +.Dv NULL . +.Bf Em +If these routines are unsuccessful, they do not increment the +.Vt "struct cdev" +.Va si_threadcount +and do not initialize the value pointed to by the +.Fa "*ref" +parameter in any way. +.Ef +.Sh SEE ALSO +.Xr destroy_dev 9 , +.Xr devfs 5 +.Sh CAVEATS +Do not invoke +.Fn dev_relthread +unless the matching refthread routine succeeded!