OS-8007 want PORT_SOURCE_DEVICE for device-specific port events

usr/src/man/man3c/port_associate.3c

@@ -1,9 +1,10 @@
 '\" te
 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
+.\" Copyright 2019 Joyent, Inc.
 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
-.TH PORT_ASSOCIATE 3C "April 9, 2016"
+.TH PORT_ASSOCIATE 3C "September 26, 2019*"
 .SH NAME
 port_associate, port_dissociate \- associate or dissociate the object with the
 port
@@ -35,11 +36,12 @@ a port.
 .sp
 .LP
 The objects that can be associated with a port by way of the
-\fBport_associate()\fR function are objects of type \fBPORT_SOURCE_FD\fR and
-\fBPORT_SOURCE_FILE\fR. Objects of other types have type-specific association
-mechanisms. A \fBport_notify_t\fR structure, defined in \fB<port.h>\fR, is used
-to specify the event port and an application-defined cookie to associate with
-these event sources. See \fBport_create\fR(3C) and \fBsignal.h\fR(3HEAD).
+\fBport_associate()\fR function are objects of type \fBPORT_SOURCE_FD\fR,
+\fBPORT_SOURCE_FILE\fR, and \fBPORT_SOURCE_DEVICE\fR. Objects of other types
+have type-specific association mechanisms. A \fBport_notify_t\fR structure,
+defined in \fB<port.h>\fR, is used to specify the event port and an
+application-defined cookie to associate with these event sources. See
+\fBport_create\fR(3C) and \fBsignal.h\fR(3HEAD).
 .sp
 .LP
 The \fBport_notify_t\fR structure contains the following members:
@@ -149,6 +151,33 @@ owner of the association closes the port .
 .LP
 On NFS file systems, events from only the client side (local)
 access/modifications to files or directories will be delivered.
+.sp
+.LP
+Objects of type \fBPORT_SOURCE_DEVICE\fR are a pointer to the structure
+\fBdev_obj_t\fR defined in \fB<sys/port.h>\fR. This event source provides
+notification for device-specific events. A minor node of the device to receive
+events from must be opened and the file descriptor be set in in the
+\fBdev_obj_t\fR object before associating. The device driver may require
+additional data by using a device-specific object, which in this case usually
+embeds \fBdev_obj_t\fR as its first member. Detailed information about any
+device-specific object structure or the events supported by a device are
+described in the man page of the device in question.
+.sp
+.LP
+The current version 1 of the \fBdev_obj_t\fR object contains the following
+elements:
+.sp
+.in +2
+.nf
+int32_t	do_version;	/* PORT_SOURCE_DEVICE interface version */
+int32_t	do_fd;		/* file descriptor of device minor node */
+.fi
+.in -2
+.sp
+.LP
+PORT_DEVICE_VERSION_DEFAULT can be used to request the current version
+of the interface. Version 1 can be explicitly requested by using
+PORT_DEVICE_VERSION_1.
 .SH RETURN VALUES
 .LP
 Upon successful completion, 0 is returned. Otherwise, \(mi1 is returned and
@@ -172,7 +201,20 @@ The \fIport\fR identifier is not valid.
 .ad
 .RS 10n
 The \fIsource\fR argument is of type \fBPORT_SOURCE_FD\fR and the object
-argument is not a valid file descriptor.
+argument is not a valid file descriptor, or the \fIsource\fR argument is of type
+\fBPORT_SOURCE_DEVICE\fR and the object argument does not contain a valid file
+descriptor in the \fIdo_fd\fR element.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBENODEV\fR\fR
+.ad
+.RS 10n
+The \fIsource\fR argument is of type \fBPORT_SOURCE_DEVICE\fR and the
+\fIdo_fd\fR element of the object is not a file descriptor of an open device
+supporting PORT_SOURCE_DEVICE events.
 .RE
 
 .sp

usr/src/man/man3c/port_create.3c

@@ -1,9 +1,10 @@
 '\" te
 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
+.\" Copyright 2019 Joyent, Inc.
 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
-.TH PORT_CREATE 3C "April 9, 2016"
+.TH PORT_CREATE 3C "September 26, 2019"
 .SH NAME
 port_create \- create a port
 .SH SYNOPSIS
@@ -36,6 +37,7 @@ T}
 \fBPORT_SOURCE_USER\fR	\fBuintptr_t\fR	\fBport_send\fR(3C)
 \fBPORT_SOURCE_ALERT\fR	\fBuintptr_t\fR	\fBport_alert\fR(3C)
 \fBPORT_SOURCE_FILE\fR	\fBfile_obj_t\fR	\fBport_associate\fR(3C)
+\fBPORT_SOURCE_DEVICE\fR	\fBdev_obj_t\fR	\fBport_associate\fR(3C)
 .TE
 
 .sp
@@ -81,6 +83,13 @@ active. It has to be reassociated to activate. A file object is associated or
 reassociated with a port using the \fBport_associate\fR(3C).
 .sp
 .LP
+\fBPORT_SOURCE_DEVICE\fR events represent device-specific status changes. The
+device object is versioned, in the current version 1 the device is specified
+by a file descriptor of an open device minor node. Device drivers may expect
+additional data following the dev_obj_t, usually by requiring the use of a
+device-specific object that contains a dev_obj_t as first member.
+.sp
+.LP
 The \fBport_get\fR(3C) and \fBport_getn\fR(3C) functions retrieve events from a
 port. They ignore non retrievable events (non-own or non-shareable events).
 .sp
@@ -97,10 +106,10 @@ If a port is exported to other processes, the port is destroyed on last close.
 .sp
 .LP
 \fBPORT_SOURCE_USER\fR and \fBPORT_SOURCE_ALERT\fR events can be distributed
-across processes. \fBPORT_SOURCE_FD\fR events can only be shared between
-processes when child processes inherit opened file decriptors from the parent
-process. See \fBfork\fR(2). \fBPORT_SOURCE_TIMER\fR and \fBPORT_SOURCE_AIO\fR
-cannot be shared between processes.
+across processes. \fBPORT_SOURCE_FD\fR and \fBPORT_SOURCE_DEVICE\fR events can
+only be shared between processes when child processes inherit opened file
+decriptors from the parent process. See \fBfork\fR(2). \fBPORT_SOURCE_TIMER\fR
+and \fBPORT_SOURCE_AIO\fR cannot be shared between processes.
 .SH RETURN VALUES
 .LP
 Upon successful completion, the \fBport_create()\fR function returns a

usr/src/uts/common/fs/portfs/port.c

@@ -511,6 +511,7 @@ _init(void)
 	port_control.pc_cache = kmem_cache_create("port_cache",
 	    sizeof (port_kevent_t), 0, NULL, NULL, NULL, NULL, NULL, 0);
 
+	port_dev_init();		/* init PORT_SOURCE_DEVICE */
 	port_kstat_init();		/* init port kstats */
 	return (mod_install(&modlinkage));
 }
@@ -652,6 +653,10 @@ portfs(int opcode, uintptr_t a0, uintptr_t a1, uintptr_t a2, uintptr_t a3,
 			error = port_associate_fop(pp, (int)a1, (uintptr_t)a2,
 			    (int)a3, (void *)a4);
 			break;
+		case PORT_SOURCE_DEVICE:
+			error = port_associate_dev(pp, (int)a1, (uintptr_t)a2,
+			    (int)a3, (void *)a4);
+			break;
 		default:
 			error = EINVAL;
 			break;
@@ -688,6 +693,9 @@ portfs(int opcode, uintptr_t a0, uintptr_t a1, uintptr_t a2, uintptr_t a3,
 		case PORT_SOURCE_FILE:
 			error = port_dissociate_fop(pp, (uintptr_t)a2);
 			break;
+		case PORT_SOURCE_DEVICE:
+			error = port_dissociate_dev(pp, (uintptr_t)a2);
+			break;
 		default:
 			error = EINVAL;
 			break;