From chris@redlinenetworks.com  Sat Sep 15 19:47:16 2001
Return-Path: <chris@redlinenetworks.com>
Received: from mail.redlinenetworks.com (226.camorphics.com [4.21.61.226])
	by hub.freebsd.org (Postfix) with SMTP id 00DF337B40D
	for <FreeBSD-gnats-submit@freebsd.org>; Sat, 15 Sep 2001 19:47:16 -0700 (PDT)
Received: from ltgreen.redlinenetworks.com (ltgreen.redlinenetworks.com [192.168.0.69])
	by mail.redlinenetworks.com (8.11.3/8.11.1) with ESMTP id f8G2lFD04728
	for <FreeBSD-gnats-submit@freebsd.org>; Sat, 15 Sep 2001 19:47:15 -0700 (PDT)
	(envelope-from chris@redlinenetworks.com)
Received: (from chris@localhost)
	by ltgreen.redlinenetworks.com (8.11.6/8.9.3) id f8G2lFH88941;
	Sat, 15 Sep 2001 19:47:15 -0700 (PDT)
	(envelope-from chris)
Message-Id: <200109160247.f8G2lFH88941@ltgreen.redlinenetworks.com>
Date: Sat, 15 Sep 2001 19:47:15 -0700 (PDT)
From: Chris Peiffer <chris@redlinenetworks.com>
Reply-To: Chris Peiffer <chris@redlinenetworks.com>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: physio(9) is internally inconsistent
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         30603
>Category:       docs
>Synopsis:       physio(9) is internally inconsistent
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sat Sep 15 19:50:01 PDT 2001
>Closed-Date:    Tue Feb 5 13:34:32 PST 2002
>Last-Modified:  Tue Feb 05 13:35:11 PST 2002
>Originator:     Chris Peiffer
>Release:        FreeBSD 4.4-RC i386
>Organization:
>Environment:
System: FreeBSD ltgreen.redlinenetworks.com 4.4-RC FreeBSD 4.4-RC #0: Thu Sep 13 15:13:37 PDT 2001 root@ltgreen.redlinenetworks.com:/usr/obj/mnt/d2/src/sys/RL i386


	
>Description:

In the man page physio(9), the synopsis at the top gives a function prototype
and argument list that do not match the arguments explained in detail in the
DESCRIPTION section. /usr/include/sys/buf.h seems to indicate that the top
definition is current/accurate, not the fully explained arguments.
>How-To-Repeat:
>Fix:
>Release-Note:
>Audit-Trail:

From: Hiten Pandya <hiten@uk.FreeBSD.org>
To: freebsd-gnats-submit@FreeBSD.org, chris@redlinenetworks.com
Cc:  
Subject: Re: docs/30603: physio(9) is internally inconsistent
Date: Fri, 18 Jan 2002 00:06:08 +0000

 I am currently having a look into this problem.  A patch should be 
 soon submitted.  This issue will take a bit time for me, but it will
 be fixed hopefully, before FreeBSD 4.5 is released.
 
 The structure of the physio() routine has been changed from:
 (as found in the src/sys/sys/buf.h header file)
 
 OLD: physio(void (*strategy)(struct buf *), struct buf *bp, dev_t dev, 
      int flags, u_int (*minphys)(struct buf *), struct uio *uio);
 
 NEW: int physio (dev_t dev, struct uio *uio, int ioflag);
 
 The initial change was done by phk@FreeBSD.org, as he refered to it 
 as "wash-and-clean of code".  In other words, this routine has been
 given a makeover since the 3.5.1 release..
 
 Saying that, this change was made 2 years ago!, and no-one noticed
 it till now.. thanks to chris..
 
 The following changes were made: (according to the cvs log of revision
 1.81)
 (I am refering to the src/sys/sys/buf.h file.. others had to be updated
 too..)
 
 o Let physio take read/write compatible args and have it use
   uio->uio_rw to determine the direction.
 
 o physread/physwrite are now #defines for physio
 
 o Remove the inversly name minphys() routine, dev->si_iosize_max
   takes over.
 
 o physio() always uses pbufs.
 
 o Fix the check for non page-aligned transfers, now only unaligned
   transfers largen than (MAXPHYS - PAGE_SIZE) get fragmented (only
   interesting for tapes using max blocksize).
 
 So, in a nutshell, the physio(9) man page needs a re-write, which I will
 do ASAP :)
 
 regards,
 - Hiten
 - <hiten@uk.FreeBSD.org>
 
 -- 
 SSH Fingerprint:
 1024 45:a5:9c:f2:fb:07:da:70:18:02:0b:f3:63:f1:7a:a6 hitenp@hpdi.ath.cx

From: Hiten Pandya <hiten@uk.FreeBSD.org>
To: bug-followup@FreeBSD.org
Cc: phk@FreeBSD.org
Subject: re: docs/30603 [PATCH]
Date: Thu, 31 Jan 2002 23:35:30 +0000

 I finally got time to fix this problem, and
 make a patch to the physio(9) man page. Well,
 hear it is.  I think this should do.
 
 I have made all the neccessary changes, as well
 as add a HISTORY section.
 
 A copy of this diff is also available at:
 http://www.pittgoth.com/~hiten/diffs/physio.9.diff
 
 If there is any problems with this diff, please
 do not hesitate to contact me. Feedback is also
 very much appreciated.
 
 Regards,
  - Hiten
  - <hiten@uk.FreeBSD.org>
  
 --- physio.9	Wed Dec 26 23:14:04 2001
 +++ physio.9.new	Wed Jan 30 06:45:02 2002
 @@ -54,16 +54,12 @@
  .Fn physio
  is a helper function typically called from character device read and write
  routines to start I/O on a user process buffer.
 -It calls back on the
 -provided
 -.Fa strategy
 -routine one or more times to complete the transfer described by
 -.Fa uio .
 -The maximum amount of data to transfer with each call to
 -.Fa strategy
 -is determined by the
 -.Fa minphys
 -routine.
 +The maximum amount of data to transfer with each call 
 +is determined by: 
 +.Bd -literal 
 +dev->si_iosize_max 
 +.Ed
 +.Pp
  Since
  .Fa uio
  normally describes user space addresses,
 @@ -74,38 +70,11 @@
  .Fn physio
  always awaits the completion of the entire requested transfer before
  returning, unless an error condition is detected earlier.
 -In all cases,
 -the buffer passed in
 -.Fa bp
 -is locked (marked as
 -.Dq busy )
 -for the duration of the entire transfer.
  .Pp
  A break-down of the arguments follows:
  .Bl -tag -width indent
 -.It Fa strategy
 -The device strategy routine to call for each chunk of data to initiate
 -device I/O.
 -.It Fa bp
 -The buffer to use with the strategy routine.
 -The buffer flags will have
 -.Dv B_BUSY ,
 -and
 -.Dv B_PHYS
 -set when passed to the strategy routine.
 -If
 -.Dv NULL ,
 -a buffer is allocated from a system pool.
  .It Fa dev
  The device number identifying the device to interact with.
 -.It Fa flags
 -Direction of transfer; the only valid settings are
 -.Dv B_READ
 -or
 -.Dv B_WRITE .
 -.It Fa minphys
 -A device specific routine called to determine the maximum transfer size
 -that the device's strategy routine can handle.
  .It Fa uio
  The description of the entire transfer as requested by the user process.
  Currently, the results of passing a
 @@ -139,3 +108,11 @@
  .Sh SEE ALSO
  .Xr read 2 ,
  .Xr write 2
 +.Sh HISTORY
 +The 
 +.Xr physio 9 
 +manual page is originally from NetBSD with minor changes for applicability 
 +with FreeBSD.
 +.Pp
 +The physio(9) call has been completely re-written for providing higher
 +I/O performance, and better paging performance.
State-Changed-From-To: open->closed 
State-Changed-By: joe 
State-Changed-When: Tue Feb 5 13:34:32 PST 2002 
State-Changed-Why:  
I've committed the updated man page to -current, will MFC in a few days. 

http://www.FreeBSD.org/cgi/query-pr.cgi?pr=30603 
>Unformatted:
