Attachment #192475 for bug #100803

View | Details | Raw Unified | Return to bug 100803
Collapse All | Expand All

Lines 38-43 Link Here

(-)ObsoleteFiles.inc (+8 lines)
38	# xargs -n1 \| sort \| uniq -d;	38	# xargs -n1 \| sort \| uniq -d;
39	# done	39	# done
40		40
		41	# 20180412: rewrite ithread man page
		42	OLD_FILES+=usr/share/man/man9/ithread_create.9.gz
		43	OLD_FILES+=usr/share/man/man9/ithread_add_handler.9.gz
		44	OLD_FILES+=usr/share/man/man9/ithread_create.9.gz
		45	OLD_FILES+=usr/share/man/man9/ithread_destroy.9.gz
		46	OLD_FILES+=usr/share/man/man9/ithread_priority.9.gz
		47	OLD_FILES+=usr/share/man/man9/ithread_remove_handler.9.gz
		48	OLD_FILES+=usr/share/man/man9/ithread_schedule.9.gz
41	# 20180409: remove FDDI support	49	# 20180409: remove FDDI support
42	OLD_FILES+=usr/include/net/fddi.h	50	OLD_FILES+=usr/include/net/fddi.h
43	OLD_FILES+=usr/share/man/man4/fpa.4.gz	51	OLD_FILES+=usr/share/man/man4/fpa.4.gz




	ifnet.9 ifunit.9 \
	ifnet.9 ifunit_ref.9
MLINKS+=insmntque.9 insmntque1.9
MLINKS+= ithread.9 intr_event.9 \
	ithread.9 intr_event_add_handler.9 \
	ithread.9 intr_event_create.9 \
	ithread.9 intr_event_destroy.9 \
	ithread.9 intr_event_remove_handler.9
	ithread.9 ithread_schedule.9
MLINKS+=kernacc.9 useracc.9
MLINKS+=kernel_mount.9 free_mntarg.9 \
	kernel_mount.9 kernel_vmount.9 \




.\"
.\" $FreeBSD$
.\"
.Dd April 12, 2018
.Dt ITHREAD 9
.Os
.Sh NAME
.Nm intr_event_add_handler ,
.Nm intr_event_create ,
.Nm intr_event_destroy ,
.Nm intr_event_remove_handler ,
.Nm intr_event_schedule_thread
.Nd "kernel event interrupt threads"
.Nd kernel interrupt threads
.Sh SYNOPSIS
.In sys/param.h
.In sys/bus.h
.In sys/interrupt.h
.Ft int
.Fo intr_event_add_handler
.Fa "struct intr_event *ie"
.Fa "const char *name"
.Fa "driver_intr_t handler"
.Fa "void *arg"

.Fa "void **cookiep"
.Fc
.Ft int
.Fo intr_event_create
.Fa "struct intr_event **event"
.Fa "void *source"
.Fa "int flags"
.Fa "void (*disable)(int)"
.Fa "void (*enable)(int)"
.Fa "const char *fmt"
.Fa "..."
.Fc
.Ft int
.Fn intr_event_destroy "struct intr_event *ie"
.Fn intr_event_remove_handler "void *cookie"
.Fn ithread_priority "enum intr_type flags"
.Ft int
.Fn intr_event_schedule_thread "struct intr_event *ie"
.Ft int
.Fn ithread_schedule "struct ithd *ithread" "int do_switch"
.Sh DESCRIPTION
Interrupt threads are kernel threads that run a list of handlers when
triggered by either a hardware or software interrupt.

represented as a vector number.
.Pp
The
.Fn intr_event_create
function creates a new interrupt thread.
The
.Fa source
argument points to a
.Vt struct entr_event event
pointer that will point to the newly created thread upon success.
The
.Fa vector
argument specifies the interrupt source to associate this thread with.
The
.Fa flags
argument is a mask of properties of this thread.
The only valid flag currently for
.Fn intr_event_create
is
.Dv IT_SOFT
to specify that this interrupt thread is a software interrupt.
The
.Fa enable
argument specify optional functions used to enable this
.Fa disable
arguments specify optional functions used to enable and disable this
interrupt thread's interrupt source.
The functions receive the vector corresponding to the thread's interrupt
source as their only argument.
The remaining arguments form a
.Xr printf 9
argument list that is used to build the base name of the new interrupt thread.
The full name of an interrupt thread is formed by concatenating the base
name of an interrupt thread with the names of all of its interrupt handlers.
.Pp
The
.Fn intr_event_destroy
function destroys a previously created interrupt thread by releasing its
resources and arranging for the backing kernel thread to terminate.
An interrupt thread can only be destroyed if it has no handlers remaining.
.Pp
The
.Fn intr_event_add_handler
function adds a new handler to an existing interrupt thread specified by
.Fa ithread .
The

handler.
.Pp
The
.Fn intr_event_remove_handler
removes a handler from an interrupt thread.
The
.Fa cookie

argument specifies the handler to remove from its thread.
.Pp
The
.Fn intr_event_schedule_thread
function schedules an interrupt thread to run.
If the
.Fa ie
argument is non-zero and the interrupt thread is idle, then a context switch
will be forced after putting the interrupt thread on the run queue.
.Pp
The
.Fn ithread_priority
function translates the
.Dv INTR_TYPE_*
interrupt flags into interrupt handler priorities.
.Pp
The interrupt flags not related to the type of a particular interrupt
.Pq Dv INTR_TYPE_*
can be used to specify additional properties of both hardware and software
interrupt handlers.
The
.Dv INTR_EXCL
flag specifies that this handler cannot share an interrupt thread with
another handler.
The
.Dv INTR_MPSAFE
flag specifies that this handler is MP safe in that it does not need the
Giant mutex to be held while it is executed.
The
.Dv INTR_ENTROPY
flag specifies that the interrupt source this handler is tied to is a good
source of entropy, and thus that entropy should be gathered when an interrupt
from the handler's source triggers.
Presently, the
.Dv INTR_ENTROPY
flag is not valid for software interrupt handlers.
.Pp
It is not permitted to sleep in an interrupt thread; hence, any memory
or zone allocations in an interrupt thread should be specified with the
.Dv M_NOWAIT
flag set.
Any allocation errors must be handled thereafter.
.Sh RETURN VALUES
The
.Fn intr_event_add_handler ,
.Fn intr_event_create ,
.Fn intr_event_destroy ,
.Fn intr_event_remove_handler ,
and
.Fn intr_event_schedule_thread
functions return zero on success and non-zero on failure.
The
.Fn ithread_priority
function returns a process priority corresponding to the passed in interrupt
flags.
.Sh EXAMPLES
The
.Fn swi_add
function demonstrates the use of
.Fn intr_event_create
and
.Fn intr_event_add_handler .
.Bd -literal -offset indent
int
swi_add(struct ithd **ithdp, const char *name, driver_intr_t handler,

		if ((ithd->it_flags & IT_SOFT) == 0)
			return(EINVAL);
	} else {
		error = intr_event_create(&event, pri, IT_SOFT, NULL, NULL,
		    "swi%d:", pri);
		if (error)
			return (error);

		if (ithdp != NULL)
			*ithdp = ithd;
	}
	return (intr_event_add_handler(ie, name, handler, arg, pri + PI_SOFT,
		    flags, cookiep));
}
.Ed
.Sh ERRORS
The
.Fn intr_event_add_handler
function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Any of the
.Fa ie ,
.Fa handler ,
or
.Fa name

The
.Dv INTR_EXCL
flag is specified and the interrupt thread
.Fa ie
already has at least one handler, or the interrupt thread
.Fa ie
already has an exclusive handler.
.It Bq Er ENOMEM
Could not allocate needed memory for this handler.

.El
.Pp
The
.Fn intr_event_create
function will fail if:
.Bl -tag -width Er
.It Bq Er EAGAIN

.El
.Pp
The
.Fn intr_event_destroy
function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
The
.Fa ie
argument is
.Dv NULL .
.It Bq Er EINVAL
The interrupt thread pointed to by
.Fa ie
has at least one handler.
.El
.Pp
The
.Fn intr_event_remove_handler
function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL

.El
.Pp
The
.Fn intr_event_schedule_thread
function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
The
.Fa ie
argument is
.Dv NULL .
.It Bq Er EINVAL
The interrupt thread pointed to by
.Fa ie
has no interrupt handlers.
.El
.Sh SEE ALSO

.Sh HISTORY
Interrupt threads and their corresponding API first appeared in
.Fx 5.0 .
.Sh BUGS
Currently
.Vt struct ithd
represents both an interrupt source and an interrupt thread.
There should be a separate
.Vt struct isrc
that contains a vector number, enable and disable functions, etc.\& that
an ithread holds a reference to.

Return to bug 100803

Lines 1188-1199 Link Here

(-)share/man/man9/Makefile (-6 / +5 lines)
1188	ifnet.9 ifunit.9 \	1188	ifnet.9 ifunit.9 \
1189	ifnet.9 ifunit_ref.9	1189	ifnet.9 ifunit_ref.9
1190	MLINKS+=insmntque.9 insmntque1.9	1190	MLINKS+=insmntque.9 insmntque1.9
1191	MLINKS+=ithread.9 ithread_add_handler.9 \	1191	MLINKS+= ithread.9 intr_event.9 \
1192	ithread.9 ithread_create.9 \	1192	ithread.9 intr_event_add_handler.9 \
1193	ithread.9 ithread_destroy.9 \	1193	ithread.9 intr_event_create.9 \
1194	ithread.9 ithread_priority.9 \	1194	ithread.9 intr_event_destroy.9 \
1195	ithread.9 ithread_remove_handler.9 \	1195	ithread.9 intr_event_remove_handler.9
1196	ithread.9 ithread_schedule.9
1197	MLINKS+=kernacc.9 useracc.9	1196	MLINKS+=kernacc.9 useracc.9
1198	MLINKS+=kernel_mount.9 free_mntarg.9 \	1197	MLINKS+=kernel_mount.9 free_mntarg.9 \
1199	kernel_mount.9 kernel_vmount.9 \	1198	kernel_mount.9 kernel_vmount.9 \

Lines 24-47 Link Here

(-)share/man/man9/ithread.9 (-104 / +48 lines)
24	.\"	24	.\"
25	.\" $FreeBSD$	25	.\" $FreeBSD$
26	.\"	26	.\"
27	.Dd August 25, 2006	27	.Dd April 12, 2018
28	.Dt ITHREAD 9	28	.Dt ITHREAD 9
29	.Os	29	.Os
30	.Sh NAME	30	.Sh NAME
31	.Nm ithread_add_handler ,	31	.Nm intr_event_add_handler ,
32	.Nm ithread_create ,	32	.Nm intr_event_create ,
33	.Nm ithread_destroy ,	33	.Nm intr_event_destroy ,
34	.Nm ithread_priority ,	34	.Nm intr_event_remove_handler ,
35	.Nm ithread_remove_handler ,	35	.Nm intr_event_schedule_thread
36	.Nm ithread_schedule	36	.Nd "kernel event interrupt threads"
37	.Nd kernel interrupt threads
38	.Sh SYNOPSIS	37	.Sh SYNOPSIS
39	.In sys/param.h	38	.In sys/param.h
40	.In sys/bus.h	39	.In sys/bus.h
41	.In sys/interrupt.h	40	.In sys/interrupt.h
42	.Ft int	41	.Ft int
43	.Fo ithread_add_handler	42	.Fo intr_event_add_handler
44	.Fa "struct ithd *ithread"	43	.Fa "struct intr_event *ie"
45	.Fa "const char *name"	44	.Fa "const char *name"
46	.Fa "driver_intr_t handler"	45	.Fa "driver_intr_t handler"
47	.Fa "void *arg"	46	.Fa "void *arg"
Lines 50-72 Link Here
50	.Fa "void **cookiep"	49	.Fa "void **cookiep"
51	.Fc	50	.Fc
52	.Ft int	51	.Ft int
53	.Fo ithread_create	52	.Fo intr_event_create
54	.Fa "struct ithd **ithread"	53	.Fa "struct intr_event **event"
55	.Fa "int vector"	54	.Fa "void *source"
56	.Fa "int flags"	55	.Fa "int flags"
57	.Fa "void (*disable)(int)"
58	.Fa "void (*enable)(int)"	56	.Fa "void (*enable)(int)"
59	.Fa "const char *fmt"	57	.Fa "const char *fmt"
60	.Fa "..."	58	.Fa "..."
61	.Fc	59	.Fc
62	.Ft int	60	.Ft int
63	.Fn ithread_destroy "struct ithd *ithread"	61	.Fn intr_event_destroy "struct intr_event *ie"
64	.Ft u_char	62	.Fn intr_event_remove_handler "void *cookie"
65	.Fn ithread_priority "enum intr_type flags"
66	.Ft int	63	.Ft int
67	.Fn ithread_remove_handler "void *cookie"	64	.Fn intr_event_schedule_thread "struct intr_event *ie"
68	.Ft int
69	.Fn ithread_schedule "struct ithd *ithread" "int do_switch"
70	.Sh DESCRIPTION	65	.Sh DESCRIPTION
71	Interrupt threads are kernel threads that run a list of handlers when	66	Interrupt threads are kernel threads that run a list of handlers when
72	triggered by either a hardware or software interrupt.	67	triggered by either a hardware or software interrupt.
Lines 83-128 Link Here
83	represented as a vector number.	78	represented as a vector number.
84	.Pp	79	.Pp
85	The	80	The
86	.Fn ithread_create	81	.Fn intr_event_create
87	function creates a new interrupt thread.	82	function creates a new interrupt thread.
88	The	83	The
89	.Fa ithread	84	.Fa source
90	argument points to an	85	argument points to a
91	.Vt struct ithd	86	.Vt struct entr_event event
92	pointer that will point to the newly created thread upon success.	87	pointer that will point to the newly created thread upon success.
93	The	88	The
94	.Fa vector
95	argument specifies the interrupt source to associate this thread with.
96	The
97	.Fa flags	89	.Fa flags
98	argument is a mask of properties of this thread.	90	argument is a mask of properties of this thread.
99	The only valid flag currently for	91	The only valid flag currently for
100	.Fn ithread_create	92	.Fn intr_event_create
101	is	93	is
102	.Dv IT_SOFT	94	.Dv IT_SOFT
103	to specify that this interrupt thread is a software interrupt.	95	to specify that this interrupt thread is a software interrupt.
104	The	96	The
105	.Fa enable	97	.Fa enable
106	and	98	argument specify optional functions used to enable this
107	.Fa disable
108	arguments specify optional functions used to enable and disable this
109	interrupt thread's interrupt source.	99	interrupt thread's interrupt source.
110	The functions receive the vector corresponding to the thread's interrupt
111	source as their only argument.
112	The remaining arguments form a	100	The remaining arguments form a
113	.Xr printf 9	101	.Xr printf 9
114	argument list that is used to build the base name of the new ithread.	102	argument list that is used to build the base name of the new interrupt thread.
115	The full name of an interrupt thread is formed by concatenating the base	103	The full name of an interrupt thread is formed by concatenating the base
116	name of an interrupt thread with the names of all of its interrupt handlers.	104	name of an interrupt thread with the names of all of its interrupt handlers.
117	.Pp	105	.Pp
118	The	106	The
119	.Fn ithread_destroy	107	.Fn intr_event_destroy
120	function destroys a previously created interrupt thread by releasing its	108	function destroys a previously created interrupt thread by releasing its
121	resources and arranging for the backing kernel thread to terminate.	109	resources and arranging for the backing kernel thread to terminate.
122	An interrupt thread can only be destroyed if it has no handlers remaining.	110	An interrupt thread can only be destroyed if it has no handlers remaining.
123	.Pp	111	.Pp
124	The	112	The
125	.Fn ithread_add_handler	113	.Fn intr_event_add_handler
126	function adds a new handler to an existing interrupt thread specified by	114	function adds a new handler to an existing interrupt thread specified by
127	.Fa ithread .	115	.Fa ithread .
128	The	116	The
Lines 151-157 Link Here
151	handler.	139	handler.
152	.Pp	140	.Pp
153	The	141	The
154	.Fn ithread_remove_handler	142	.Fn intr_event_remove_handler
155	removes a handler from an interrupt thread.	143	removes a handler from an interrupt thread.
156	The	144	The
157	.Fa cookie	145	.Fa cookie
Lines 158-222 Link Here
158	argument specifies the handler to remove from its thread.	146	argument specifies the handler to remove from its thread.
159	.Pp	147	.Pp
160	The	148	The
161	.Fn ithread_schedule	149	.Fn intr_event_schedule_thread
162	function schedules an interrupt thread to run.	150	function schedules an interrupt thread to run.
163	If the	151	If the
164	.Fa do_switch	152	.Fa ie
165	argument is non-zero and the interrupt thread is idle, then a context switch	153	argument is non-zero and the interrupt thread is idle, then a context switch
166	will be forced after putting the interrupt thread on the run queue.	154	will be forced after putting the interrupt thread on the run queue.
167	.Pp
168	The
169	.Fn ithread_priority
170	function translates the
171	.Dv INTR_TYPE_*
172	interrupt flags into interrupt handler priorities.
173	.Pp
174	The interrupt flags not related to the type of a particular interrupt
175	.Pq Dv INTR_TYPE_*
176	can be used to specify additional properties of both hardware and software
177	interrupt handlers.
178	The
179	.Dv INTR_EXCL
180	flag specifies that this handler cannot share an interrupt thread with
181	another handler.
182	The
183	.Dv INTR_MPSAFE
184	flag specifies that this handler is MP safe in that it does not need the
185	Giant mutex to be held while it is executed.
186	The
187	.Dv INTR_ENTROPY
188	flag specifies that the interrupt source this handler is tied to is a good
189	source of entropy, and thus that entropy should be gathered when an interrupt
190	from the handler's source triggers.
191	Presently, the
192	.Dv INTR_ENTROPY
193	flag is not valid for software interrupt handlers.
194	.Pp
195	It is not permitted to sleep in an interrupt thread; hence, any memory
196	or zone allocations in an interrupt thread should be specified with the
197	.Dv M_NOWAIT
198	flag set.
199	Any allocation errors must be handled thereafter.
200	.Sh RETURN VALUES	155	.Sh RETURN VALUES
201	The	156	The
202	.Fn ithread_add_handler ,	157	.Fn intr_event_add_handler ,
203	.Fn ithread_create ,	158	.Fn intr_event_create ,
204	.Fn ithread_destroy ,	159	.Fn intr_event_destroy ,
205	.Fn ithread_remove_handler ,	160	.Fn intr_event_remove_handler ,
206	and	161	and
207	.Fn ithread_schedule	162	.Fn intr_event_schedule_thread
208	functions return zero on success and non-zero on failure.	163	functions return zero on success and non-zero on failure.
209	The	164	The
210	.Fn ithread_priority
211	function returns a process priority corresponding to the passed in interrupt
212	flags.
213	.Sh EXAMPLES	165	.Sh EXAMPLES
214	The	166	The
215	.Fn swi_add	167	.Fn swi_add
216	function demonstrates the use of	168	function demonstrates the use of
217	.Fn ithread_create	169	.Fn intr_event_create
218	and	170	and
219	.Fn ithread_add_handler .	171	.Fn intr_event_add_handler .
220	.Bd -literal -offset indent	172	.Bd -literal -offset indent
221	int	173	int
222	swi_add(struct ithd *ithdp, const char name, driver_intr_t handler,	174	swi_add(struct ithd *ithdp, const char name, driver_intr_t handler,
Lines 235-241 Link Here
235	if ((ithd->it_flags & IT_SOFT) == 0)	187	if ((ithd->it_flags & IT_SOFT) == 0)
236	return(EINVAL);	188	return(EINVAL);
237	} else {	189	} else {
238	error = ithread_create(&ithd, pri, IT_SOFT, NULL, NULL,	190	error = intr_event_create(&event, pri, IT_SOFT, NULL, NULL,
239	"swi%d:", pri);	191	"swi%d:", pri);
240	if (error)	192	if (error)
241	return (error);	193	return (error);
Lines 243-260 Link Here
243	if (ithdp != NULL)	195	if (ithdp != NULL)
244	*ithdp = ithd;	196	*ithdp = ithd;
245	}	197	}
246	return (ithread_add_handler(ithd, name, handler, arg, pri + PI_SOFT,	198	return (intr_event_add_handler(ie, name, handler, arg, pri + PI_SOFT,
247	flags, cookiep));	199	flags, cookiep));
248	}	200	}
249	.Ed	201	.Ed
250	.Sh ERRORS	202	.Sh ERRORS
251	The	203	The
252	.Fn ithread_add_handler	204	.Fn intr_event_add_handler
253	function will fail if:	205	function will fail if:
254	.Bl -tag -width Er	206	.Bl -tag -width Er
255	.It Bq Er EINVAL	207	.It Bq Er EINVAL
256	Any of the	208	Any of the
257	.Fa ithread ,	209	.Fa ie ,
258	.Fa handler ,	210	.Fa handler ,
259	or	211	or
260	.Fa name	212	.Fa name
Lines 264-272 Link Here
264	The	216	The
265	.Dv INTR_EXCL	217	.Dv INTR_EXCL
266	flag is specified and the interrupt thread	218	flag is specified and the interrupt thread
267	.Fa ithread	219	.Fa ie
268	already has at least one handler, or the interrupt thread	220	already has at least one handler, or the interrupt thread
269	.Fa ithread	221	.Fa ie
270	already has an exclusive handler.	222	already has an exclusive handler.
271	.It Bq Er ENOMEM	223	.It Bq Er ENOMEM
272	Could not allocate needed memory for this handler.	224	Could not allocate needed memory for this handler.
Lines 273-279 Link Here
273	.El	225	.El
274	.Pp	226	.Pp
275	The	227	The
276	.Fn ithread_create	228	.Fn intr_event_create
277	function will fail if:	229	function will fail if:
278	.Bl -tag -width Er	230	.Bl -tag -width Er
279	.It Bq Er EAGAIN	231	.It Bq Er EAGAIN
Lines 294-315 Link Here
294	.El	246	.El
295	.Pp	247	.Pp
296	The	248	The
297	.Fn ithread_destroy	249	.Fn intr_event_destroy
298	function will fail if:	250	function will fail if:
299	.Bl -tag -width Er	251	.Bl -tag -width Er
300	.It Bq Er EINVAL	252	.It Bq Er EINVAL
301	The	253	The
302	.Fa ithread	254	.Fa ie
303	argument is	255	argument is
304	.Dv NULL .	256	.Dv NULL .
305	.It Bq Er EINVAL	257	.It Bq Er EINVAL
306	The interrupt thread pointed to by	258	The interrupt thread pointed to by
307	.Fa ithread	259	.Fa ie
308	has at least one handler.	260	has at least one handler.
309	.El	261	.El
310	.Pp	262	.Pp
311	The	263	The
312	.Fn ithread_remove_handler	264	.Fn intr_event_remove_handler
313	function will fail if:	265	function will fail if:
314	.Bl -tag -width Er	266	.Bl -tag -width Er
315	.It Bq Er EINVAL	267	.It Bq Er EINVAL
Lines 320-336 Link Here
320	.El	272	.El
321	.Pp	273	.Pp
322	The	274	The
323	.Fn ithread_schedule	275	.Fn intr_event_schedule_thread
324	function will fail if:	276	function will fail if:
325	.Bl -tag -width Er	277	.Bl -tag -width Er
326	.It Bq Er EINVAL	278	.It Bq Er EINVAL
327	The	279	The
328	.Fa ithread	280	.Fa ie
329	argument is	281	argument is
330	.Dv NULL .	282	.Dv NULL .
331	.It Bq Er EINVAL	283	.It Bq Er EINVAL
332	The interrupt thread pointed to by	284	The interrupt thread pointed to by
333	.Fa ithread	285	.Fa ie
334	has no interrupt handlers.	286	has no interrupt handlers.
335	.El	287	.El
336	.Sh SEE ALSO	288	.Sh SEE ALSO
Lines 341-351 Link Here
341	.Sh HISTORY	293	.Sh HISTORY
342	Interrupt threads and their corresponding API first appeared in	294	Interrupt threads and their corresponding API first appeared in
343	.Fx 5.0 .	295	.Fx 5.0 .
344	.Sh BUGS
345	Currently
346	.Vt struct ithd
347	represents both an interrupt source and an interrupt thread.
348	There should be a separate
349	.Vt struct isrc
350	that contains a vector number, enable and disable functions, etc.\& that
351	an ithread holds a reference to.