xref: /titanic_41/usr/src/uts/common/sys/poll_impl.h (revision 7c478bd95313f5f23a4c958a745db2134aa03244)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License, Version 1.0 only
6  * (the "License").  You may not use this file except in compliance
7  * with the License.
8  *
9  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10  * or http://www.opensolaris.org/os/licensing.
11  * See the License for the specific language governing permissions
12  * and limitations under the License.
13  *
14  * When distributing Covered Code, include this CDDL HEADER in each
15  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16  * If applicable, add the following below this CDDL HEADER, with the
17  * fields enclosed by brackets "[]" replaced with your own identifying
18  * information: Portions Copyright [yyyy] [name of copyright owner]
19  *
20  * CDDL HEADER END
21  */
22 /*
23  * Copyright 2003 Sun Microsystems, Inc.  All rights reserved.
24  * Use is subject to license terms.
25  */
26 
27 #ifndef _SYS_POLL_IMPL_H
28 #define	_SYS_POLL_IMPL_H
29 
30 #pragma ident	"%Z%%M%	%I%	%E% SMI"
31 
32 /*
33  * Caching Poll Subsystem:
34  *
35  * Each kernel thread (1), if engaged in poll system call, has a reference to
36  * a pollstate_t (2), which contains relevant flags and locks.  The pollstate_t
37  * contains a pointer to a pcache_t (3), which caches the state of previous
38  * calls to poll.  A bitmap (4) is stored inside the poll cache, where each
39  * bit represents a file descriptor.  The bits are set if the corresponding
40  * device has a polled event pending.  Only fds with their bit set will be
41  * examined on the next poll invocation.  The pollstate_t also contains a list
42  * of fd sets (5), which are represented by the pollcacheset_t type.  These
43  * structures keep track of the pollfd_t arrays (6) passed in from userland.
44  * Each polled file descriptor has a corresponding polldat_t which can be
45  * chained onto a device's pollhead, and these are kept in a hash table (7)
46  * inside the pcache_t.  The hash table allows efficient conversion of a
47  * given fd to its corresponding polldat_t.
48  *
49  * (1)              (2)
50  * +-----------+    +-------------+
51  * | kthread_t |--->| pollstate_t |-->+-------------+  (6)
52  * +-----------+    +-------------+(5)| pcacheset_t |->[_][_][_][_] pollfd_t
53  *                          |         +-------------+
54  *                          |         | pcacheset_t |->[_][_][_][_] pollfd_t
55  * (1a)                     |         +-------------+
56  * +---------------+	    |
57  * | /dev/poll tbl |	    |
58  * +-v-------------+	    |
59  *   |			    |
60  *   +------------------+   |
61  * (7)              (3) V   v
62  * polldat hash     +-------------+    (4) bitmap representing fd space
63  * [_][_][_][_]<----|             |--->000010010010001010101010101010110
64  *  |  |  |  |      | pollcache_t |
65  *  .  v  .  .      |             |
66  *    [polldat_t]   +-------------+
67  *     |
68  *    [polldat_t]
69  *     |
70  *     v
71  *     NULL
72  *
73  *
74  * Both poll system call and /dev/poll use the pollcache_t structure
75  * definition and the routines managing the structure. But poll(2) and
76  * /dev/poll have their own copy of the structures. The /dev/poll driver
77  * table (1a) contains an array of pointers, each pointing at a pcache_t
78  * struct (3). A device minor number is used as an device table index.
79  *
80  */
81 #include <sys/poll.h>
82 
83 #if defined(_KERNEL) || defined(_KMEMUSER)
84 
85 #include <sys/thread.h>
86 #include <sys/file.h>
87 
88 #ifdef	__cplusplus
89 extern "C" {
90 #endif
91 
92 /*
93  * description of pollcacheset structure
94  */
95 typedef struct pollcacheset {
96 	uintptr_t	pcs_usradr;	/* usr pollfd array address */
97 	pollfd_t	*pcs_pollfd;	/* cached poll lists */
98 	size_t		pcs_nfds;	/* number of poll fd in cached list */
99 	ulong_t		pcs_count;	/* for LU replacement policy */
100 } pollcacheset_t;
101 
102 #define	POLLFDSETS	2
103 
104 /*
105  * State information kept by each polling thread
106  */
107 typedef struct pollstate {
108 	pollfd_t	*ps_pollfd;	/* hold the current poll list */
109 	size_t		ps_nfds;	/* size of ps_pollfd */
110 	kmutex_t	ps_lock;	/* mutex for sleep/wakeup */
111 	struct pollcache *ps_pcache;	/* cached poll fd set */
112 	pollcacheset_t	*ps_pcacheset;	/* cached poll lists */
113 	int		ps_nsets;	/* no. of cached poll sets */
114 	pollfd_t	*ps_dpbuf;	/* return pollfd buf used by devpoll */
115 	size_t		ps_dpbufsize;	/* size of ps_dpbuf */
116 } pollstate_t;
117 
118 /*
119  * poll cache size defines
120  */
121 #define	POLLCHUNKSHIFT		8	/* hash table increment size is 256 */
122 #define	POLLHASHCHUNKSZ		(1 << POLLCHUNKSHIFT)
123 #define	POLLHASHINC		2	/* poll hash table growth factor */
124 #define	POLLHASHTHRESHOLD	2	/* poll hash list length threshold */
125 #define	POLLHASH(x, y)	((y) % (x))	/* poll hash function */
126 
127 /*
128  * poll.c assumes the POLLMAPCHUNK is power of 2
129  */
130 #define	POLLMAPCHUNK	2048	/* bitmap inc -- each for 2K of polled fd's */
131 
132 /*
133  * used to refrence from watched fd back to the fd position in cached
134  * poll list for quick revents update.
135  */
136 typedef struct xref {
137 	ssize_t	xf_position;    /* xref fd position in poll fd list */
138 	short	xf_refcnt;	/* ref cnt of same fd in poll list */
139 } xref_t;
140 
141 #define	POLLPOSINVAL	(-1L)	/* xf_position is invalid */
142 #define	POLLPOSTRANS	(-2L)	/* xf_position is transient state */
143 
144 /*
145  * polldat is an entry for a cached poll fd. A polldat struct can be in
146  * poll cache table as well as on pollhead ph_list, which is used by
147  * pollwakeup to wake up a sleeping poller. There should be one polldat
148  * per polled fd hanging off pollstate struct.
149  */
150 typedef struct polldat {
151 	int		pd_fd;		/* cached poll fd */
152 	int		pd_events;	/* union of all polled events */
153 	file_t		*pd_fp;		/* used to detect fd reuse */
154 	pollhead_t	*pd_php;	/* used to undo poll registration */
155 	kthread_t	*pd_thread;	/* used for waking up a sleep thrd */
156 	struct pollcache *pd_pcache;	/* a ptr to the pollcache of this fd */
157 	struct polldat	*pd_next;	/* next on pollhead's ph_list */
158 	struct polldat	*pd_hashnext;	/* next on pollhead's ph_list */
159 	int		pd_count;	/* total count from all ref'ed sets */
160 	int		pd_nsets;	/* num of xref sets, used by poll(2) */
161 	xref_t		*pd_ref;	/* ptr to xref info, 1 for each set */
162 	struct port_kevent *pd_portev;	/* associated port event struct */
163 } polldat_t;
164 
165 /*
166  * One cache for each thread that polls. Points to a bitmap (used by pollwakeup)
167  * and a hash table of polldats.
168  * The offset of pc_lock field must be kept in sync with the pc_lock offset
169  * of port_fdcache_t, both structs implement pc_lock with offset 0 (see also
170  * pollrelock()).
171  */
172 typedef struct pollcache {
173 	kmutex_t	pc_lock;	/* lock to protect pollcache */
174 	ulong_t		*pc_bitmap;	/* point to poll fd bitmap */
175 	polldat_t	**pc_hash;	/* points to a hash table of ptrs */
176 	int		pc_mapend;	/* the largest fd encountered so far */
177 	int		pc_mapsize;	/* the size of current map */
178 	int		pc_hashsize;	/* the size of current hash table */
179 	int		pc_fdcount;	/* track how many fd's are hashed */
180 	int		pc_flag;	/* see pc_flag define below */
181 	int		pc_busy;	/* can only exit when its 0 */
182 	kmutex_t	pc_no_exit;	/* protects pc_busy*, can't be nested */
183 	kcondvar_t	pc_busy_cv;	/* cv to wait on if ps_busy != 0 */
184 	kcondvar_t	pc_cv;		/* cv to wait on if needed */
185 	pid_t		pc_pid;		/* for check acc rights, devpoll only */
186 	int		pc_mapstart;	/* where search start, devpoll only */
187 } pollcache_t;
188 
189 /* pc_flag */
190 #define	T_POLLWAKE	0x02	/* pollwakeup() occurred */
191 
192 #if defined(_KERNEL)
193 /*
194  * Internal routines.
195  */
196 extern void pollnotify(pollcache_t *, int);
197 
198 /*
199  * public poll head interfaces (see poll.h):
200  *
201  *  pollhead_clean      clean up all polldats on a pollhead list
202  */
203 extern void pollhead_clean(pollhead_t *);
204 
205 /*
206  * private poll head interfaces:
207  *
208  *  pollhead_insert     adds a polldat to a pollhead list
209  *  pollhead_delete     removes a polldat from a pollhead list
210  */
211 extern void pollhead_insert(pollhead_t *, polldat_t *);
212 extern void pollhead_delete(pollhead_t *, polldat_t *);
213 
214 /*
215  * poll state interfaces:
216  *
217  *  pollstate_create    creates per-thread pollstate
218  *  pollstate_destroy   cleans up per-thread pollstate
219  */
220 extern pollstate_t *pollstate_create(void);
221 extern void pollstate_destroy(pollstate_t *);
222 
223 /*
224  * public pcache interfaces:
225  *
226  *  pcache_alloc	allocate a poll cache skeleton
227  *  pcache_create       creates all poll cache supporting data struct
228  *  pcache_insert	cache a poll fd, calls pcache_insert_fd
229  *  pcache_lookup       given an fd list, returns a cookie
230  *  pcache_poll         polls the cache for fd's having events on them
231  *  pcache_clean        clean up all the pollhead and fpollinfo reference
232  *  pcache_destroy      destroys the pcache
233  */
234 extern pollcache_t *pcache_alloc();
235 extern void pcache_create(pollcache_t *, nfds_t);
236 extern int pcache_insert(pollstate_t *, file_t *, pollfd_t *, int *, ssize_t,
237     int);
238 extern int pcache_poll(pollfd_t *, pollstate_t *, nfds_t, int *, int);
239 extern void pcache_clean(pollcache_t *);
240 extern void pcache_destroy(pollcache_t *);
241 
242 /*
243  * private pcache interfaces:
244  *
245  *  pcache_lookup_fd	lookup an fd, returns a polldat
246  *  pcache_alloc_fd	allocates and returns a polldat
247  *  pcache_insert_fd	insert an fd into pcache (called by pcache_insert)
248  *  pcache_delete_fd	insert an fd into pcache (called by pcacheset_delete_fd)
249  *  pcache_grow_hashtbl	grows the pollcache hash table and rehash
250  *  pcache_grow_map	grows the pollcache bitmap
251  *  pcache_update_xref	update cross ref (from polldat back to cacheset) info
252  *  pcache_clean_entry	cleanup an entry in pcache and more...
253  */
254 extern polldat_t *pcache_lookup_fd(pollcache_t *, int);
255 extern polldat_t *pcache_alloc_fd(int);
256 extern void pcache_insert_fd(pollcache_t *, polldat_t *, nfds_t);
257 extern int pcache_delete_fd(pollstate_t *, int, size_t, int, uint_t);
258 extern void pcache_grow_hashtbl(pollcache_t *, nfds_t);
259 extern void pcache_grow_map(pollcache_t *, int);
260 extern void pcache_update_xref(pollcache_t *, int, ssize_t, int);
261 extern void pcache_clean_entry(pollstate_t *, int);
262 
263 /*
264  * pcacheset interfaces:
265  *
266  * pcacheset_create     creates new pcachesets (easier for dynamic pcachesets)
267  * pcacheset_destroy    destroys a pcacheset
268  * pcacheset_cache_list caches and polls a new poll list
269  * pcacheset_remove_list removes (usually a partial) cached poll list
270  * pcacheset_resolve    resolves extant pcacheset and fd list
271  * pcacheset_cmp        compares a pcacheset with an fd list
272  * pcacheset_invalidate invalidate entries in pcachesets
273  * pcacheset_reset_count resets the usage counter of pcachesets
274  * pcacheset_replace	selects a poll cacheset for replacement
275  */
276 extern pollcacheset_t *pcacheset_create(int);
277 extern void pcacheset_destroy(pollcacheset_t *, int);
278 extern int pcacheset_cache_list(pollstate_t *, pollfd_t *, int *, int);
279 extern void pcacheset_remove_list(pollstate_t *, pollfd_t *, int, int, int,
280     int);
281 extern int pcacheset_resolve(pollstate_t *, nfds_t, int *, int);
282 extern int pcacheset_cmp(pollfd_t *, pollfd_t *, pollfd_t *, int);
283 extern void pcacheset_invalidate(pollstate_t *, polldat_t *);
284 extern void pcacheset_reset_count(pollstate_t *, int);
285 extern int pcacheset_replace(pollstate_t *);
286 
287 #endif /* defined(_KERNEL) */
288 
289 #ifdef	__cplusplus
290 }
291 #endif
292 
293 #endif /* defined(_KERNEL) || defined(_KMEMUSER) */
294 
295 #endif	/* _SYS_POLL_IMPL_H */
296