Bug 166864
| Summary: | the swi_add prototype is not updated in swi(9) | ||
|---|---|---|---|
| Product: | Documentation | Reporter: | fuzhli <fuzl> |
| Component: | Books & Articles | Assignee: | Sergey Kandaurov <pluknet> |
| Status: | Closed FIXED | ||
| Severity: | Affects Only Me | ||
| Priority: | Normal | ||
| Version: | Latest | ||
| Hardware: | Any | ||
| OS: | Any | ||
Responsible Changed From-To: freebsd-doc->pluknet I will look at it. Author: pluknet Date: Thu Apr 12 16:02:45 2012 New Revision: 234188 URL: http://svn.freebsd.org/changeset/base/234188 Log: Update the swi_add prototype after struct ithd was split up into struct intr_event and struct intr_thread. PR: docs/166864 Reviewed by: jhb (older version) MFC after: 1 week Modified: head/share/man/man9/swi.9 Modified: head/share/man/man9/swi.9 ============================================================================== --- head/share/man/man9/swi.9 Thu Apr 12 15:56:04 2012 (r234187) +++ head/share/man/man9/swi.9 Thu Apr 12 16:02:45 2012 (r234188) @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd October 30, 2000 +.Dd April 12, 2012 .Dt SWI 9 .Os .Sh NAME @@ -42,7 +42,7 @@ .Vt "extern void *vm_ih" ; .Ft int .Fo swi_add -.Fa "struct ithd **ithdp" +.Fa "struct intr_event **eventp" .Fa "const char *name" .Fa "driver_intr_t handler" .Fa "void *arg" @@ -67,20 +67,21 @@ time, and that they can be run via a lig .Pp The .Fn swi_add -function is used to register a new software interrupt handler. +function is used to add a new software interrupt handler to a specified +interrupt event. The -.Fa ithdp +.Fa eventp argument is an optional pointer to a -.Vt struct ithd +.Vt struct intr_event pointer. -If this argument points to an existing software interrupt thread, then this -handler will be attached to that thread. -Otherwise a new thread will be created, and if -.Fa ithdp +If this argument points to an existing event that holds a list of +interrupt handlers, then this handler will be attached to that event. +Otherwise a new event will be created, and if +.Fa eventp is not .Dv NULL , then the pointer at that address to will be modified to point to the -newly created thread. +newly created event. The .Fa name argument is used to associate a name with a specific handler. @@ -99,7 +100,7 @@ The .Fa pri value specifies the priority of this interrupt handler relative to other software interrupt handlers. -If an interrupt thread is created, then this value is used as the vector, +If an interrupt event is created, then this value is used as the vector, and the .Fa flags argument is used to specify the attributes of a handler such as @@ -183,7 +184,7 @@ argument specifies .Dv INTR_ENTROPY . .It Bq Er EINVAL The -.Fa ithdp +.Fa eventp argument points to a hardware interrupt thread. .It Bq Er EINVAL Either of the @@ -195,9 +196,9 @@ arguments are .It Bq Er EINVAL The .Dv INTR_EXCL -flag is specified and the interrupt thread pointed to by -.Fa ithdp -already has at least one handler, or the interrupt thread already has an +flag is specified and the interrupt event pointed to by +.Fa eventp +already has at least one handler, or the interrupt event already has an exclusive handler. .El .Sh SEE ALSO _______________________________________________ svn-src-all@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/svn-src-all To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org" State Changed From-To: open->patched Committed to HEAD. Thanks for the report! Author: pluknet Date: Wed Jun 13 14:47:03 2012 New Revision: 237007 URL: http://svn.freebsd.org/changeset/base/237007 Log: MFC r234188,r234463,r234465: - Update the swi_add prototype after struct ithd was split up into struct intr_event and struct intr_thread. [1] - Update the rest of struct ithd references. - net_ih and softclock_ih cookies have gone away. - Document swi_remove(9). PR: docs/166864 [1] Modified: stable/9/share/man/man9/Makefile stable/9/share/man/man9/swi.9 Directory Properties: stable/9/share/man/man9/ (props changed) Modified: stable/9/share/man/man9/Makefile ============================================================================== --- stable/9/share/man/man9/Makefile Wed Jun 13 11:59:47 2012 (r237006) +++ stable/9/share/man/man9/Makefile Wed Jun 13 14:47:03 2012 (r237007) @@ -1245,6 +1245,7 @@ MLINKS+=store.9 subyte.9 \ store.9 suword32.9 \ store.9 suword64.9 MLINKS+=swi.9 swi_add.9 \ + swi.9 swi_remove.9 \ swi.9 swi_sched.9 MLINKS+=sx.9 sx_assert.9 \ sx.9 sx_destroy.9 \ Modified: stable/9/share/man/man9/swi.9 ============================================================================== --- stable/9/share/man/man9/swi.9 Wed Jun 13 11:59:47 2012 (r237006) +++ stable/9/share/man/man9/swi.9 Wed Jun 13 14:47:03 2012 (r237007) @@ -24,25 +24,24 @@ .\" .\" $FreeBSD$ .\" -.Dd October 30, 2000 +.Dd April 19, 2012 .Dt SWI 9 .Os .Sh NAME .Nm swi_add , +.Nm swi_remove , .Nm swi_sched .Nd register and schedule software interrupt handlers .Sh SYNOPSIS .In sys/param.h .In sys/bus.h .In sys/interrupt.h -.Vt "extern struct ithd *tty_ithd" ; -.Vt "extern struct ithd *clk_ithd" ; -.Vt "extern void *net_ih" ; -.Vt "extern void *softclock_ih" ; +.Vt "extern struct intr_event *tty_intr_event" ; +.Vt "extern struct intr_event *clk_intr_event" ; .Vt "extern void *vm_ih" ; .Ft int .Fo swi_add -.Fa "struct ithd **ithdp" +.Fa "struct intr_event **eventp" .Fa "const char *name" .Fa "driver_intr_t handler" .Fa "void *arg" @@ -50,6 +49,8 @@ .Fa "enum intr_type flags" .Fa "void **cookiep" .Fc +.Ft int +.Fn swi_remove "void *cookie" .Ft void .Fn swi_sched "void *cookie" "int flags" .Sh DESCRIPTION @@ -67,20 +68,21 @@ time, and that they can be run via a lig .Pp The .Fn swi_add -function is used to register a new software interrupt handler. +function is used to add a new software interrupt handler to a specified +interrupt event. The -.Fa ithdp +.Fa eventp argument is an optional pointer to a -.Vt struct ithd +.Vt struct intr_event pointer. -If this argument points to an existing software interrupt thread, then this -handler will be attached to that thread. -Otherwise a new thread will be created, and if -.Fa ithdp +If this argument points to an existing event that holds a list of +interrupt handlers, then this handler will be attached to that event. +Otherwise a new event will be created, and if +.Fa eventp is not .Dv NULL , then the pointer at that address to will be modified to point to the -newly created thread. +newly created event. The .Fa name argument is used to associate a name with a specific handler. @@ -99,7 +101,7 @@ The .Fa pri value specifies the priority of this interrupt handler relative to other software interrupt handlers. -If an interrupt thread is created, then this value is used as the vector, +If an interrupt event is created, then this value is used as the vector, and the .Fa flags argument is used to specify the attributes of a handler such as @@ -113,6 +115,14 @@ This cookie will be set to a value that and is used to schedule the handler for execution later on. .Pp The +.Fn swi_remove +function is used to teardown an interrupt handler pointed to by the +.Fa cookie +argument. +It detaches the interrupt handler from the associated interrupt event +and frees its memory. +.Pp +The .Fn swi_sched function is used to schedule an interrupt handler and its associated thread to run. @@ -140,30 +150,29 @@ in earlier versions of .El .Pp The -.Va tty_ithd +.Va tty_intr_event and -.Va clk_ithd -variables contain pointers to the software interrupt threads for the tty and +.Va clk_intr_event +variables contain pointers to the software interrupt handlers for the tty and clock software interrupts, respectively. -.Va tty_ithd +.Va tty_intr_event is used to hang tty software interrupt handlers off of the same thread. -.Va clk_ithd +.Va clk_intr_event is used to hang delayed handlers off of the clock software interrupt thread so that the functionality of .Fn setdelayed can be obtained in conjunction with .Dv SWI_DELAY . The -.Va net_ih , -.Va softclock_ih , -and .Va vm_ih -handler cookies are used to schedule software interrupt threads to run for the -networking stack, clock interrupt, and VM subsystem respectively. +handler cookie is used to schedule software interrupt threads to run for the +VM subsystem. .Sh RETURN VALUES The .Fn swi_add -function returns zero on success and non-zero on failure. +and +.Fn swi_remove +functions return zero on success and non-zero on failure. .Sh ERRORS The .Fn swi_add @@ -183,7 +192,7 @@ argument specifies .Dv INTR_ENTROPY . .It Bq Er EINVAL The -.Fa ithdp +.Fa eventp argument points to a hardware interrupt thread. .It Bq Er EINVAL Either of the @@ -195,11 +204,22 @@ arguments are .It Bq Er EINVAL The .Dv INTR_EXCL -flag is specified and the interrupt thread pointed to by -.Fa ithdp -already has at least one handler, or the interrupt thread already has an +flag is specified and the interrupt event pointed to by +.Fa eventp +already has at least one handler, or the interrupt event already has an exclusive handler. .El +.Pp +The +.Fn swi_remove +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +A software interrupt handler pointed to by +.Fa cookie +is +.Dv NULL . +.El .Sh SEE ALSO .Xr ithread 9 , .Xr taskqueue 9 @@ -220,6 +240,10 @@ and .Fn schedsoft* functions which date back to at least .Bx 4.4 . +The +.Fn swi_remove +function first appeared in +.Fx 6.1 . .Sh BUGS Most of the global variables described in this manual page should not be global, or at the very least should not be declared in _______________________________________________ svn-src-all@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/svn-src-all To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org" Author: pluknet Date: Thu Jun 14 11:21:21 2012 New Revision: 237059 URL: http://svn.freebsd.org/changeset/base/237059 Log: MFC r234188,r234463,r234465: - Update the swi_add prototype after struct ithd was split up into struct intr_event and struct intr_thread. [1] - Update the rest of struct ithd references. - net_ih and softclock_ih cookies have gone away. - Document swi_remove(9). PR: docs/166864 [1] Modified: stable/8/share/man/man9/Makefile stable/8/share/man/man9/swi.9 Directory Properties: stable/8/share/man/man9/ (props changed) Modified: stable/8/share/man/man9/Makefile ============================================================================== --- stable/8/share/man/man9/Makefile Thu Jun 14 11:20:22 2012 (r237058) +++ stable/8/share/man/man9/Makefile Thu Jun 14 11:21:21 2012 (r237059) @@ -1206,6 +1206,7 @@ MLINKS+=store.9 subyte.9 \ store.9 suword32.9 \ store.9 suword64.9 MLINKS+=swi.9 swi_add.9 \ + swi.9 swi_remove.9 \ swi.9 swi_sched.9 MLINKS+=sx.9 sx_assert.9 \ sx.9 sx_destroy.9 \ Modified: stable/8/share/man/man9/swi.9 ============================================================================== --- stable/8/share/man/man9/swi.9 Thu Jun 14 11:20:22 2012 (r237058) +++ stable/8/share/man/man9/swi.9 Thu Jun 14 11:21:21 2012 (r237059) @@ -24,25 +24,24 @@ .\" .\" $FreeBSD$ .\" -.Dd October 30, 2000 +.Dd April 19, 2012 .Dt SWI 9 .Os .Sh NAME .Nm swi_add , +.Nm swi_remove , .Nm swi_sched .Nd register and schedule software interrupt handlers .Sh SYNOPSIS .In sys/param.h .In sys/bus.h .In sys/interrupt.h -.Vt "extern struct ithd *tty_ithd" ; -.Vt "extern struct ithd *clk_ithd" ; -.Vt "extern void *net_ih" ; -.Vt "extern void *softclock_ih" ; +.Vt "extern struct intr_event *tty_intr_event" ; +.Vt "extern struct intr_event *clk_intr_event" ; .Vt "extern void *vm_ih" ; .Ft int .Fo swi_add -.Fa "struct ithd **ithdp" +.Fa "struct intr_event **eventp" .Fa "const char *name" .Fa "driver_intr_t handler" .Fa "void *arg" @@ -50,6 +49,8 @@ .Fa "enum intr_type flags" .Fa "void **cookiep" .Fc +.Ft int +.Fn swi_remove "void *cookie" .Ft void .Fn swi_sched "void *cookie" "int flags" .Sh DESCRIPTION @@ -67,20 +68,21 @@ time, and that they can be run via a lig .Pp The .Fn swi_add -function is used to register a new software interrupt handler. +function is used to add a new software interrupt handler to a specified +interrupt event. The -.Fa ithdp +.Fa eventp argument is an optional pointer to a -.Vt struct ithd +.Vt struct intr_event pointer. -If this argument points to an existing software interrupt thread, then this -handler will be attached to that thread. -Otherwise a new thread will be created, and if -.Fa ithdp +If this argument points to an existing event that holds a list of +interrupt handlers, then this handler will be attached to that event. +Otherwise a new event will be created, and if +.Fa eventp is not .Dv NULL , then the pointer at that address to will be modified to point to the -newly created thread. +newly created event. The .Fa name argument is used to associate a name with a specific handler. @@ -99,7 +101,7 @@ The .Fa pri value specifies the priority of this interrupt handler relative to other software interrupt handlers. -If an interrupt thread is created, then this value is used as the vector, +If an interrupt event is created, then this value is used as the vector, and the .Fa flags argument is used to specify the attributes of a handler such as @@ -113,6 +115,14 @@ This cookie will be set to a value that and is used to schedule the handler for execution later on. .Pp The +.Fn swi_remove +function is used to teardown an interrupt handler pointed to by the +.Fa cookie +argument. +It detaches the interrupt handler from the associated interrupt event +and frees its memory. +.Pp +The .Fn swi_sched function is used to schedule an interrupt handler and its associated thread to run. @@ -140,30 +150,29 @@ in earlier versions of .El .Pp The -.Va tty_ithd +.Va tty_intr_event and -.Va clk_ithd -variables contain pointers to the software interrupt threads for the tty and +.Va clk_intr_event +variables contain pointers to the software interrupt handlers for the tty and clock software interrupts, respectively. -.Va tty_ithd +.Va tty_intr_event is used to hang tty software interrupt handlers off of the same thread. -.Va clk_ithd +.Va clk_intr_event is used to hang delayed handlers off of the clock software interrupt thread so that the functionality of .Fn setdelayed can be obtained in conjunction with .Dv SWI_DELAY . The -.Va net_ih , -.Va softclock_ih , -and .Va vm_ih -handler cookies are used to schedule software interrupt threads to run for the -networking stack, clock interrupt, and VM subsystem respectively. +handler cookie is used to schedule software interrupt threads to run for the +VM subsystem. .Sh RETURN VALUES The .Fn swi_add -function returns zero on success and non-zero on failure. +and +.Fn swi_remove +functions return zero on success and non-zero on failure. .Sh ERRORS The .Fn swi_add @@ -185,7 +194,7 @@ or .Dv INTR_FAST . .It Bq Er EINVAL The -.Fa ithdp +.Fa eventp argument points to a hardware interrupt thread. .It Bq Er EINVAL Either of the @@ -197,11 +206,22 @@ arguments are .It Bq Er EINVAL The .Dv INTR_EXCL -flag is specified and the interrupt thread pointed to by -.Fa ithdp -already has at least one handler, or the interrupt thread already has an +flag is specified and the interrupt event pointed to by +.Fa eventp +already has at least one handler, or the interrupt event already has an exclusive handler. .El +.Pp +The +.Fn swi_remove +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +A software interrupt handler pointed to by +.Fa cookie +is +.Dv NULL . +.El .Sh SEE ALSO .Xr ithread 9 , .Xr taskqueue 9 @@ -222,6 +242,10 @@ and .Fn schedsoft* functions which date back to at least .Bx 4.4 . +The +.Fn swi_remove +function first appeared in +.Fx 6.1 . .Sh BUGS Most of the global variables described in this manual page should not be global, or at the very least should not be declared in _______________________________________________ svn-src-all@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/svn-src-all To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org" Author: pluknet Date: Thu Jun 14 11:39:43 2012 New Revision: 237060 URL: http://svn.freebsd.org/changeset/base/237060 Log: MFC r234188, r234463, r234465 (partially, except softclock_ih): - Update the swi_add prototype after struct ithd was split up into struct intr_event and struct intr_thread. [1] - Update the rest of struct ithd references. - net_ih cookie has gone away. - Document swi_remove(9). PR: docs/166864 [1] Modified: stable/7/share/man/man9/Makefile stable/7/share/man/man9/swi.9 Directory Properties: stable/7/share/man/man9/ (props changed) Modified: stable/7/share/man/man9/Makefile ============================================================================== --- stable/7/share/man/man9/Makefile Thu Jun 14 11:21:21 2012 (r237059) +++ stable/7/share/man/man9/Makefile Thu Jun 14 11:39:43 2012 (r237060) @@ -1096,6 +1096,7 @@ MLINKS+=store.9 subyte.9 \ store.9 suword.9 MLINKS+=suser.9 suser_cred.9 MLINKS+=swi.9 swi_add.9 \ + swi.9 swi_remove.9 \ swi.9 swi_sched.9 MLINKS+=sx.9 sx_assert.9 \ sx.9 sx_destroy.9 \ Modified: stable/7/share/man/man9/swi.9 ============================================================================== --- stable/7/share/man/man9/swi.9 Thu Jun 14 11:21:21 2012 (r237059) +++ stable/7/share/man/man9/swi.9 Thu Jun 14 11:39:43 2012 (r237060) @@ -24,25 +24,25 @@ .\" .\" $FreeBSD$ .\" -.Dd October 30, 2000 +.Dd April 19, 2012 .Dt SWI 9 .Os .Sh NAME .Nm swi_add , +.Nm swi_remove , .Nm swi_sched .Nd register and schedule software interrupt handlers .Sh SYNOPSIS .In sys/param.h .In sys/bus.h .In sys/interrupt.h -.Vt "extern struct ithd *tty_ithd" ; -.Vt "extern struct ithd *clk_ithd" ; -.Vt "extern void *net_ih" ; +.Vt "extern struct intr_event *tty_intr_event" ; +.Vt "extern struct intr_event *clk_intr_event" ; .Vt "extern void *softclock_ih" ; .Vt "extern void *vm_ih" ; .Ft int .Fo swi_add -.Fa "struct ithd **ithdp" +.Fa "struct intr_event **eventp" .Fa "const char *name" .Fa "driver_intr_t handler" .Fa "void *arg" @@ -50,6 +50,8 @@ .Fa "enum intr_type flags" .Fa "void **cookiep" .Fc +.Ft int +.Fn swi_remove "void *cookie" .Ft void .Fn swi_sched "void *cookie" "int flags" .Sh DESCRIPTION @@ -67,20 +69,21 @@ time, and that they can be run via a lig .Pp The .Fn swi_add -function is used to register a new software interrupt handler. +function is used to add a new software interrupt handler to a specified +interrupt event. The -.Fa ithdp +.Fa eventp argument is an optional pointer to a -.Vt struct ithd +.Vt struct intr_event pointer. -If this argument points to an existing software interrupt thread, then this -handler will be attached to that thread. -Otherwise a new thread will be created, and if -.Fa ithdp +If this argument points to an existing event that holds a list of +interrupt handlers, then this handler will be attached to that event. +Otherwise a new event will be created, and if +.Fa eventp is not .Dv NULL , then the pointer at that address to will be modified to point to the -newly created thread. +newly created event. The .Fa name argument is used to associate a name with a specific handler. @@ -99,7 +102,7 @@ The .Fa pri value specifies the priority of this interrupt handler relative to other software interrupt handlers. -If an interrupt thread is created, then this value is used as the vector, +If an interrupt event is created, then this value is used as the vector, and the .Fa flags argument is used to specify the attributes of a handler such as @@ -113,6 +116,14 @@ This cookie will be set to a value that and is used to schedule the handler for execution later on. .Pp The +.Fn swi_remove +function is used to teardown an interrupt handler pointed to by the +.Fa cookie +argument. +It detaches the interrupt handler from the associated interrupt event +and frees its memory. +.Pp +The .Fn swi_sched function is used to schedule an interrupt handler and its associated thread to run. @@ -140,30 +151,31 @@ in earlier versions of .El .Pp The -.Va tty_ithd +.Va tty_intr_event and -.Va clk_ithd -variables contain pointers to the software interrupt threads for the tty and +.Va clk_intr_event +variables contain pointers to the software interrupt handlers for the tty and clock software interrupts, respectively. -.Va tty_ithd +.Va tty_intr_event is used to hang tty software interrupt handlers off of the same thread. -.Va clk_ithd +.Va clk_intr_event is used to hang delayed handlers off of the clock software interrupt thread so that the functionality of .Fn setdelayed can be obtained in conjunction with .Dv SWI_DELAY . The -.Va net_ih , -.Va softclock_ih , +.Va softclock_ih and .Va vm_ih handler cookies are used to schedule software interrupt threads to run for the -networking stack, clock interrupt, and VM subsystem respectively. +clock interrupt and VM subsystem respectively. .Sh RETURN VALUES The .Fn swi_add -function returns zero on success and non-zero on failure. +and +.Fn swi_remove +functions return zero on success and non-zero on failure. .Sh ERRORS The .Fn swi_add @@ -185,7 +197,7 @@ or .Dv INTR_FAST . .It Bq Er EINVAL The -.Fa ithdp +.Fa eventp argument points to a hardware interrupt thread. .It Bq Er EINVAL Either of the @@ -197,11 +209,22 @@ arguments are .It Bq Er EINVAL The .Dv INTR_EXCL -flag is specified and the interrupt thread pointed to by -.Fa ithdp -already has at least one handler, or the interrupt thread already has an +flag is specified and the interrupt event pointed to by +.Fa eventp +already has at least one handler, or the interrupt event already has an exclusive handler. .El +.Pp +The +.Fn swi_remove +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +A software interrupt handler pointed to by +.Fa cookie +is +.Dv NULL . +.El .Sh SEE ALSO .Xr ithread 9 , .Xr taskqueue 9 @@ -222,6 +245,10 @@ and .Fn schedsoft* functions which date back to at least .Bx 4.4 . +The +.Fn swi_remove +function first appeared in +.Fx 6.1 . .Sh BUGS Most of the global variables described in this manual page should not be global, or at the very least should not be declared in _______________________________________________ svn-src-all@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/svn-src-all To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org" State Changed From-To: patched->closed Merged to all supported branches together with other changes. |
From FreeBSD7.0, the prototype of function swi_add() is changed: the first parameter is "struct intr_event **eventp", not the "struct ithd **ithdp". But the mannual docs not update this change till the latest FreeBSD9.0. How-To-Repeat: %man 9 swi SWI(9) FreeBSD Kernel Developer's Manual SWI(9) NAME swi_add, swi_sched -- register and schedule software interrupt handlers SYNOPSIS #include <sys/param.h> #include <sys/bus.h> #include <sys/interrupt.h> extern struct ithd *tty_ithd; extern struct ithd *clk_ithd; extern void *net_ih; extern void *softclock_ih; extern void *vm_ih; int swi_add(struct ithd **ithdp, const char *name, driver_intr_t handler, void *arg, int pri, enum intr_type flags, void **cookiep); void swi_sched(void *cookie, int flags);