Add man page for usbd_ref_incr(9), usbd_ref_decr(9), and usbd_ref_wait(9).

ok mpi

2 files changed, 67 insertions, 3 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 0edc0122a93..a580ae1d73a 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.276 2016/04/25 19:24:42 tedu Exp $
+#	$OpenBSD: Makefile,v 1.277 2016/06/17 13:23:21 mglocker Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -32,8 +32,8 @@ MAN=	aml_evalnode.9 atomic_add_int.9 atomic_cas_uint.9 \
 	spl.9 srp_enter.9 srpl_rc_init.9 startuphook_establish.9 \
 	socreate.9 sosplice.9 style.9 syscall.9 sysctl_int.9 \
 	task_add.9 tc_init.9 time_second.9 timeout.9 tsleep.9 tvtohz.9 \
-	uiomove.9 uvm.9 usbd_close_pipe.9 usbd_open_pipe.9 usbd_transfer.9 \
-	vfs.9 vfs_busy.9 \
+	uiomove.9 uvm.9 usbd_close_pipe.9 usbd_open_pipe.9 usbd_ref_wait.9 \
+	usbd_transfer.9 vfs.9 vfs_busy.9 \
 	vfs_cache.9 vaccess.9 vclean.9 vcount.9 vdevgone.9 vfinddev.9 vflush.9 \
 	vflushbuf.9 vget.9 vgone.9 vhold.9 vinvalbuf.9 vnode.9 vnsubr.9 \
 	VOP_LOOKUP.9 vput.9 vrecycle.9 vref.9 vrele.9 \
diff --git a/share/man/man9/usbd_ref_wait.9 b/share/man/man9/usbd_ref_wait.9
new file mode 100644
index 00000000000..479f842dd44
--- /dev/null
+++ b/share/man/man9/usbd_ref_wait.9
@@ -0,0 +1,64 @@
+.\" $OpenBSD: usbd_ref_wait.9,v 1.1 2016/06/17 13:23:21 mglocker Exp $
+.\"
+.\" Copyright (c) 2016 Marcus Glocker <mglocker@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: June 17 2016 $
+.Dt USBD_REF_WAIT 9
+.Os
+.Sh NAME
+.Nm usbd_ref_incr , usbd_ref_decr , usbd_ref_wait
+.Nd wait for all references to complete
+.Sh SYNOPSIS
+.In dev/usb/usb.h
+.In dev/usb/usbdi.h
+.Ft void
+.Fn usbd_ref_incr "struct usbd_device *dev"
+.Ft void
+.Fn usbd_ref_decr "struct usbd_device *dev"
+.Ft void
+.Fn usbd_ref_wait "struct usbd_device *dev"
+.Sh DESCRIPTION
+The
+.Fn usbd_ref_wait
+function is used on a device level to
+.Fn tsleep
+until the reference counter has reached zero.
+.Pp
+To increase the reference counter use
+.Fn usbd_ref_incr .
+To decrease the reference counter use
+.Fn usbd_ref_decr .
+Once the reference counter has been decreased to zero,
+.Fn usbd_ref_decr
+will call
+.Fn wakeup
+to interrupt the
+.Fn tsleep
+at the point where you have set the
+.Fn usbd_ref_wait
+before.
+.Pp
+Typical use cases to wait for tasks to complete is at device closing
+or detachment.
+.Sh CONTEXT
+.Fn usbd_ref_incr ,
+.Fn usbd_ref_decr ,
+and
+.Fn usbd_ref_wait
+can be called during autoconf or from process context.
+.Sh SEE ALSO
+.Xr tsleep 9 ,
+.Xr usb 4 ,
+.Xr wakeup 9