From nobody@FreeBSD.org  Tue Jul 25 09:54:21 2006
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 3106B16A4DE
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 25 Jul 2006 09:54:21 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (www.freebsd.org [216.136.204.117])
	by mx1.FreeBSD.org (Postfix) with ESMTP id E85D743D46
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 25 Jul 2006 09:54:20 +0000 (GMT)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (localhost [127.0.0.1])
	by www.freebsd.org (8.13.1/8.13.1) with ESMTP id k6P9sKnQ006860
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 25 Jul 2006 09:54:20 GMT
	(envelope-from nobody@www.freebsd.org)
Received: (from nobody@localhost)
	by www.freebsd.org (8.13.1/8.13.1/Submit) id k6P9sK7b006859;
	Tue, 25 Jul 2006 09:54:20 GMT
	(envelope-from nobody)
Message-Id: <200607250954.k6P9sK7b006859@www.freebsd.org>
Date: Tue, 25 Jul 2006 09:54:20 GMT
From: mirnshi <mirnshi@gmail.com>
To: freebsd-gnats-submit@FreeBSD.org
Subject: the man page about ithread is expired.
X-Send-Pr-Version: www-2.3

>Number:         100803
>Category:       docs
>Synopsis:       [patch] the man page about ithread is expired.
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    jhb
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Jul 25 10:00:29 GMT 2006
>Closed-Date:    
>Last-Modified:  Thu May 17 14:13:32 GMT 2007
>Originator:     mirnshi
>Release:        6.1
>Organization:
>Environment:
FreeBSD test 6.1-RELEASE FreeBSD 6.1-RELEASE #0: Wed Jun  7 14:30:54 UTC 2006     root@test:/BDG  i386

>Description:
The code about ithread was changed, but the man page is 5.x.

ithread_create was replaced with intr_event_create. 

The header file: /sys/sys/interrupt.h
>How-To-Repeat:

>Fix:

>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-bugs->freebsd-doc 
Responsible-Changed-By: linimon 
Responsible-Changed-When: Tue Jul 25 10:15:12 UTC 2006 
Responsible-Changed-Why:  
Over to maintainer(s). 

http://www.freebsd.org/cgi/query-pr.cgi?pr=100803 
Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Sun Oct 8 17:55:51 UTC 2006 
Responsible-Changed-Why:  
Very large patch sent to John for review. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=100803 

From: Tom Rhodes <trhodes@FreeBSD.org>
To: bug-followup@FreeBSD.org
Cc: mirnshi@gmail.com
Subject: Re: docs/100803: [PATCH]: the man page about ithread is expired
Date: Sun, 8 Oct 2006 13:51:45 -0400

 Hi,
 
 I've sent the following patch to John Baldwin for review:
 
 Index: ithread.9
 ===================================================================
 RCS file: /home/ncvs/src/share/man/man9/ithread.9,v
 retrieving revision 1.12
 diff -u -r1.12 ithread.9
 --- ithread.9	25 Aug 2006 19:04:42 -0000	1.12
 +++ ithread.9	8 Oct 2006 17:47:16 -0000
 @@ -28,20 +28,19 @@
  .Dt ITHREAD 9
  .Os
  .Sh NAME
 -.Nm ithread_add_handler ,
 -.Nm ithread_create ,
 -.Nm ithread_destroy ,
 -.Nm ithread_priority ,
 -.Nm ithread_remove_handler ,
 -.Nm ithread_schedule
 -.Nd kernel interrupt threads
 +.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"
  .Sh SYNOPSIS
  .In sys/param.h
  .In sys/bus.h
  .In sys/interrupt.h
  .Ft int
 -.Fo ithread_add_handler
 -.Fa "struct ithd *ithread"
 +.Fo intr_add_handler
 +.Fa "struct intr_event *ie"
  .Fa "const char *name"
  .Fa "driver_intr_t handler"
  .Fa "void *arg"
 @@ -50,23 +49,19 @@
  .Fa "void **cookiep"
  .Fc
  .Ft int
 -.Fo ithread_create
 -.Fa "struct ithd **ithread"
 -.Fa "int vector"
 +.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 ithread_destroy "struct ithd *ithread"
 -.Ft u_char
 -.Fn ithread_priority "enum intr_type flags"
 +.Fn intr_event_destroy "struct intr_event *ie"
 +.Fn intr_event_remove_handler "void *cookie"
  .Ft int
 -.Fn ithread_remove_handler "void *cookie"
 -.Ft int
 -.Fn ithread_schedule "struct ithd *ithread" "int do_switch"
 +.Fn intr_event_schedule_thread "struct intr_event *ie"
  .Sh DESCRIPTION
  Interrupt threads are kernel threads that run a list of handlers when
  triggered by either a hardware or software interrupt.
 @@ -83,46 +78,39 @@
  represented as a vector number.
  .Pp
  The
 -.Fn ithread_create
 +.Fn intr_event_create
  function creates a new interrupt thread.
  The
 -.Fa ithread
 -argument points to an
 -.Vt struct ithd
 +.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 ithread_create
 +.Fn intr_event_create
  is
  .Dv IT_SOFT
  to specify that this interrupt thread is a software interrupt.
  The
  .Fa enable
 -and
 -.Fa disable
 -arguments specify optional functions used to enable and disable this
 +argument specify optional functions used to enable 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 ithread.
 +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 ithread_destroy
 +.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 ithread_add_handler
 +.Fn intr_event_add_handler
  function adds a new handler to an existing interrupt thread specified by
  .Fa ithread .
  The
 @@ -151,83 +139,36 @@
  handler.
  .Pp
  The
 -.Fn ithread_remove_handler
 +.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 ithread_schedule
 +.Fn intr_event_schedule_thread
  function schedules an interrupt thread to run.
  If the
 -.Fa do_switch
 +.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_FAST
 -flag specifies that when this handler is executed, it should be run immediately
 -rather than being run asynchronously when its interrupt thread is scheduled to
 -run.
 -The
 -.Dv INTR_FAST
 -flag implies
 -.Dv INTR_EXCL .
 -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_FAST
 -and
 -.Dv INTR_ENTROPY
 -flags are 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 ithread_add_handler ,
 -.Fn ithread_create ,
 -.Fn ithread_destroy ,
 -.Fn ithread_remove_handler ,
 +.Fn intr_event_add_handler ,
 +.Fn intr_event_create ,
 +.Fn intr_event_destroy ,
 +.Fn intr_event_remove_handler ,
  and
 -.Fn ithread_schedule
 +.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 ithread_create
 +.Fn intr_event_create
  and
 -.Fn ithread_add_handler .
 +.Fn intr_event_add_handler .
  .Bd -literal -offset indent
  int
  swi_add(struct ithd **ithdp, const char *name, driver_intr_t handler,
 @@ -246,7 +187,7 @@
  		if ((ithd->it_flags & IT_SOFT) == 0)
  			return(EINVAL);
  	} else {
 -		error = ithread_create(&ithd, pri, IT_SOFT, NULL, NULL,
 +		error = intr_event_create(&event, pri, IT_SOFT, NULL, NULL,
  		    "swi%d:", pri);
  		if (error)
  			return (error);
 @@ -254,18 +195,18 @@
  		if (ithdp != NULL)
  			*ithdp = ithd;
  	}
 -	return (ithread_add_handler(ithd, name, handler, arg, pri + PI_SOFT,
 +	return (intr_event_add_handler(ie, name, handler, arg, pri + PI_SOFT,
  		    flags, cookiep));
  }
  .Ed
  .Sh ERRORS
  The
 -.Fn ithread_add_handler
 +.Fn intr_event_add_handler
  function will fail if:
  .Bl -tag -width Er
  .It Bq Er EINVAL
  Any of the
 -.Fa ithread ,
 +.Fa ie ,
  .Fa handler ,
  or
  .Fa name
 @@ -275,16 +216,16 @@
  The
  .Dv INTR_EXCL
  flag is specified and the interrupt thread
 -.Fa ithread
 +.Fa ie
  already has at least one handler, or the interrupt thread
 -.Fa ithread
 +.Fa ie
  already has an exclusive handler.
  .It Bq Er ENOMEM
  Could not allocate needed memory for this handler.
  .El
  .Pp
  The
 -.Fn ithread_create
 +.Fn intr_event_create
  function will fail if:
  .Bl -tag -width Er
  .It Bq Er EAGAIN
 @@ -305,22 +246,22 @@
  .El
  .Pp
  The
 -.Fn ithread_destroy
 +.Fn intr_event_destroy
  function will fail if:
  .Bl -tag -width Er
  .It Bq Er EINVAL
  The
 -.Fa ithread
 +.Fa ie
  argument is
  .Dv NULL .
  .It Bq Er EINVAL
  The interrupt thread pointed to by
 -.Fa ithread
 +.Fa ie
  has at least one handler.
  .El
  .Pp
  The
 -.Fn ithread_remove_handler
 +.Fn intr_event_remove_handler
  function will fail if:
  .Bl -tag -width Er
  .It Bq Er EINVAL
 @@ -331,17 +272,17 @@
  .El
  .Pp
  The
 -.Fn ithread_schedule
 +.Fn intr_event_schedule_thread
  function will fail if:
  .Bl -tag -width Er
  .It Bq Er EINVAL
  The
 -.Fa ithread
 +.Fa ie
  argument is
  .Dv NULL .
  .It Bq Er EINVAL
  The interrupt thread pointed to by
 -.Fa ithread
 +.Fa ie
  has no interrupt handlers.
  .El
  .Sh SEE ALSO
 @@ -352,11 +293,3 @@
  .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.
 
 Perhaps this should be renamed to intr_event.9 and ithread.9 should
 go away?  Not sure, I asked for his opinion.  Thanks!
 
 -- 
 Tom Rhodes
Responsible-Changed-From-To: trhodes->jhb 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Fri Nov 3 10:51:26 UTC 2006 
Responsible-Changed-Why:  
Over to John who discussed this with me.  Thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=100803 
>Unformatted:
