7207 properly document pollhead_clean()

Reviewed by: Robert Mustacchi <rm@joyent.com>
Reviewed by: Richard Lowe <richlowe@richlowe.net>
Approved by: Matthew Ahrens <mahrens@delphix.com>

4 files changed, 93 insertions, 0 deletions

diff --git a/usr/src/man/man9e/chpoll.9e b/usr/src/man/man9e/chpoll.9e
index 468ef7b53f..7b4b3edf0b 100644
--- a/usr/src/man/man9e/chpoll.9e
+++ b/usr/src/man/man9e/chpoll.9e
@@ -214,6 +214,38 @@ hold any mutex across the call to \fBpollwakeup\fR(9F) that is acquired in its
 the time of the call to \fBchpoll()\fR.
 
 .RE
+.RS +4
+.TP
+4.
+In the \fBclose\fR(9E) entry point, the driver should call \fBpollwakeup()\fR
+on the \fBpollhead\fR structure that corresponds to the closing software
+state, specifying \fBPOLLERR\fR for the events.  Further, upon return from
+\fBpollwakeup()\fR, the driver's \fBclose\fR(9E) entry point should call
+the \fBpollhead_clean\fR(9F) function, specifying the \fBpollhead\fR that
+corresponds to the structure that will be deallocated:
+
+.sp
+.in +2
+.nf
+static int
+mydriver_close(dev_t dev, int flag, int otyp, cred_t *cp)
+{
+      minor_t minor = getminor(dev);
+      mydriver_state_t *state;
+
+      state = ddi_get_soft_state(mydriver_softstate, minor);
+
+      pollwakeup(&state->mydriver_pollhd, POLLERR);
+      pollhead_clean(&state->mydriver_pollhd);
+      ...
+.fi
+.in -2
+
+This step is necessary to inform other kernel subsystems that the memory
+associated with the \fBpollhead\fR is about to be deallocated by the
+\fBclose\fR(9E) entry point.
+
+.RE
 .SH RETURN VALUES
 .LP
 \fBchpoll()\fR should return \fB0\fR for success, or the appropriate error
diff --git a/usr/src/man/man9f/Makefile b/usr/src/man/man9f/Makefile
index ffd15b5778..9e5f5f2b52 100644
--- a/usr/src/man/man9f/Makefile
+++ b/usr/src/man/man9f/Makefile
@@ -395,6 +395,7 @@ MANFILES= 	ASSERT.9f				\
 	 	pm_power_has_changed.9f			\
 	 	pm_raise_power.9f			\
 	 	pm_trans_check.9f			\
+		pollhead_clean.9f			\
 	 	pollwakeup.9f				\
 	 	priv_getbyname.9f			\
 	 	priv_policy.9f				\
diff --git a/usr/src/man/man9f/pollhead_clean.9f b/usr/src/man/man9f/pollhead_clean.9f
new file mode 100644
index 0000000000..2823bd71aa
--- /dev/null
+++ b/usr/src/man/man9f/pollhead_clean.9f
@@ -0,0 +1,59 @@
+'\" te
+.\"  Copyright (c) 2015, Joyent, Inc. All Rights Reserved.
+.\"  This file and its contents are supplied under the terms of the
+.\"  Common Development and Distribution License ("CDDL"), version 1.0.
+.\"  You may only use this file in accordance with the terms of version
+.\"  1.0 of the CDDL.
+.\" 
+.\"  A full copy of the text of the CDDL should have accompanied this
+.\"  source.  A copy of the CDDL is also available via the Internet at
+.\"  http://www.illumos.org/license/CDDL.
+.TH POLLHEAD_CLEAN 9F "Jun 12, 1998"
+.\"
+.\" A little inside joke with the above date: that's the date that the
+.\" devpoll work integrated (under bug 1265897).  The original work included
+.\" pollhead_clean() -- but didn't bother to document it!  With the date,
+.\" we are therefore giving this man page the date it should have had in an
+.\" attempt to right an historical wrong -- albeit nearly two decades after
+.\" the fact.
+.\"
+.SH NAME
+pollhead_clean \- inform the kernel that a pollhead is being deallocated
+.SH SYNOPSIS
+.LP
+.nf
+#include <sys/poll.h>
+
+
+
+\fBvoid\fR \fBpollhead_clean\fR(\fBstruct pollhead *\fR\fIphp\fR);
+.fi
+
+.SH INTERFACE LEVEL
+.LP
+Architecture independent level 1 (DDI/DKI).
+.SH PARAMETERS
+.ne 2
+.na
+\fB\fIphp\fR\fR
+.ad
+.RS 9n
+Pointer to a \fBpollhead\fR structure.
+.RE
+
+.SH DESCRIPTION
+.LP
+The \fBpollhead_clean()\fR function informs the kernel that a driver's
+\fBpollhead\fR structure is about to be deallocated, usually as part of
+the driver's \fBclose\fR(9E) entry point before the software state that
+contains the \fBpollhead\fR is deallocated via \fBddi_soft_state_free\fR(9F).
+See \fBchpoll\fR(9E), \fBpollwakeup\fR(9E) and \fBpoll\fR(2) for more detail.
+.SH CONTEXT
+.LP
+The \fBpollhead_clean()\fR function is generally called from the context
+of a \fBclose\fR(9E) entry point, but may be called from user or kernel
+context.
+.SH SEE ALSO
+.LP
+\fBpoll\fR(2), \fBchpoll\fR(9E), \fBpollwakeup\fR(9E)
+
diff --git a/usr/src/pkg/manifests/system-kernel.man9f.inc b/usr/src/pkg/manifests/system-kernel.man9f.inc
index a9046569c0..1d5056b298 100644
--- a/usr/src/pkg/manifests/system-kernel.man9f.inc
+++ b/usr/src/pkg/manifests/system-kernel.man9f.inc
@@ -390,6 +390,7 @@ file path=usr/share/man/man9f/pm_busy_component.9f
 file path=usr/share/man/man9f/pm_power_has_changed.9f
 file path=usr/share/man/man9f/pm_raise_power.9f
 file path=usr/share/man/man9f/pm_trans_check.9f
+file path=usr/share/man/man9f/pollhead_clean.9f
 file path=usr/share/man/man9f/pollwakeup.9f
 file path=usr/share/man/man9f/priv_getbyname.9f
 file path=usr/share/man/man9f/priv_policy.9f