From marck@woozle.rinet.ru  Sun May 19 06:44:09 2002
Return-Path: <marck@woozle.rinet.ru>
Received: from woozle.rinet.ru (woozle.rinet.ru [195.54.192.68])
	by hub.freebsd.org (Postfix) with ESMTP id 3392837B403
	for <FreeBSD-gnats-submit@freebsd.org>; Sun, 19 May 2002 06:44:07 -0700 (PDT)
Received: (from marck@localhost)
	by woozle.rinet.ru (8.11.6/8.11.6) id g4JDi4s55991;
	Sun, 19 May 2002 17:44:04 +0400 (MSD)
	(envelope-from marck)
Message-Id: <200205191344.g4JDi4s55991@woozle.rinet.ru>
Date: Sun, 19 May 2002 17:44:04 +0400 (MSD)
From: Dmitry Morozovsky <marck@rinet.ru>
Reply-To: Dmitry Morozovsky <marck@rinet.ru>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: Update to ata(4) manpage (broken ata tags for now)
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         38289
>Category:       docs
>Synopsis:       Update to ata(4) manpage (broken ata tags for now)
>Confidential:   no
>Severity:       serious
>Priority:       high
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          sw-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sun May 19 06:50:01 PDT 2002
>Closed-Date:    Mon Jun 10 17:40:25 PDT 2002
>Last-Modified:  Mon Jun 10 17:40:25 PDT 2002
>Originator:     Dmitry Morozovsky
>Release:        FreeBSD 4-STABLE i386
>Organization:
Cronyx Plus LLC (RiNet ISP)
>Environment:
System: FreeBSD 4-STABLE 


>Description:

	Current state of ata(4) subsystem is not compatible with ata tagged
support. I suppose we're not able to fix this in 4.6 release cycle, so it
would be wise at least to document this.
	
>How-To-Repeat:

>Fix:
--- ata.4.orig  Sun May 19 17:32:19 2002
+++ ata.4       Sun May 19 17:38:53 2002
@@ -76,7 +76,9 @@
 (WARNING might cause data loss on power failures)
 .It Va hw.ata.tags
 set to 1 to enable Tagged Queuing support, 0 to disable (default is disabled)
 (only IBM DPTA and DTLA drives support that)
+.Pp
+XXX THIS FEATURE IS CURRENTLY BROKEN -- Do not try to enable it! XXX
 .El
 .Sh DESCRIPTION
 This driver provides access to disk drives, ATAPI CD-ROM and DVD drives,

>Release-Note:
>Audit-Trail:

From: Giorgos Keramidas <keramida@FreeBSD.ORG>
To: Dmitry Morozovsky <marck@rinet.ru>
Cc: bug-followup@FreeBSD.ORG
Subject: Re: docs/38289: Update to ata(4) manpage (broken ata tags for now)
Date: Tue, 21 May 2002 18:31:06 +0300

 On 2002-05-19 17:44, Dmitry Morozovsky wrote:
 > --- ata.4.orig  Sun May 19 17:32:19 2002
 > +++ ata.4       Sun May 19 17:38:53 2002
 > @@ -76,7 +76,9 @@
 >  (WARNING might cause data loss on power failures)
 >  .It Va hw.ata.tags
 >  set to 1 to enable Tagged Queuing support, 0 to disable (default is disabled)
 >  (only IBM DPTA and DTLA drives support that)
 > +.Pp
 > +XXX THIS FEATURE IS CURRENTLY BROKEN -- Do not try to enable it! XXX
 >  .El
 >  .Sh DESCRIPTION
 >  This driver provides access to disk drives, ATAPI CD-ROM and DVD drives,
 
 I don't think "XXX" is a nice thing to have in running text.  I tend
 to view the manpages as text that can be part of a typeset document,
 printed in PostScript form by a local printer.  Moreover, the manpages
 should not document brokenness that can be fixed, for fear that they
 will continue to document brokenness long after the bug has been
 fixed, if the author of the code doesn't know that the manpage states
 the code is broken.  A comment in LINT should be enough to let the
 users know that this particular feature might be the source of
 problems, when they're editing their kernel configuration and enabling
 the option.
 
 Of course, this is my humble opinion ;-)
 
 -- 
 Giorgos Keramidas    - http://www.FreeBSD.org
 keramida@FreeBSD.org - The Power to Serve

From: Dmitry Morozovsky <marck@rinet.ru>
To: Giorgos Keramidas <keramida@FreeBSD.ORG>
Cc: bug-followup@FreeBSD.ORG
Subject: Re: docs/38289: Update to ata(4) manpage (broken ata tags for now)
Date: Wed, 22 May 2002 13:02:27 +0400 (MSD)

 On Tue, 21 May 2002, Giorgos Keramidas wrote:
 
 [snip]
 GK> > +.Pp
 GK> > +XXX THIS FEATURE IS CURRENTLY BROKEN -- Do not try to enable it! XXX
 GK> >  .El
 GK> >  .Sh DESCRIPTION
 GK> >  This driver provides access to disk drives, ATAPI CD-ROM and DVD drives,
 GK>
 GK> I don't think "XXX" is a nice thing to have in running text.  I tend
 GK> to view the manpages as text that can be part of a typeset document,
 GK> printed in PostScript form by a local printer.  Moreover, the manpages
 GK> should not document brokenness that can be fixed, for fear that they
 GK> will continue to document brokenness long after the bug has been
 GK> fixed, if the author of the code doesn't know that the manpage states
 GK> the code is broken.  A comment in LINT should be enough to let the
 GK> users know that this particular feature might be the source of
 GK> problems, when they're editing their kernel configuration and enabling
 GK> the option.
 
 Well, then I tend to agree ;-) Maybe just comment this section out from
 the manpage? Adding comment to LINT is not a good idea for me as long as
 ATA tags are no longer kernel compile-time option.
 
 Anyway, I think it should be documented some way.
 
 Sincerely,
 D.Marck                                   [DM5020, DM268-RIPE, DM3-RIPN]
 ------------------------------------------------------------------------
 *** Dmitry Morozovsky --- D.Marck --- Wild Woozle --- marck@rinet.ru ***
 ------------------------------------------------------------------------
 

From: Giorgos Keramidas <keramida@FreeBSD.ORG>
To: Dmitry Morozovsky <marck@rinet.ru>
Cc: bug-followup@FreeBSD.ORG
Subject: Re: docs/38289: Update to ata(4) manpage (broken ata tags for now)
Date: Wed, 22 May 2002 16:37:22 +0300

 On 2002-05-22 02:10, Dmitry Morozovsky wrote:
 > The following reply was made to PR docs/38289; it has been noted by GNATS.
 >
 >  Well, then I tend to agree ;-) Maybe just comment this section out from
 >  the manpage? Adding comment to LINT is not a good idea for me as long as
 >  ATA tags are no longer kernel compile-time option.
 
 It is a sysctl in CURRENT.
 
 	% sysctl -a | grep tags
 	hw.ata.tags: 0
 
 It's a sysctl in RELENG_4 too, and it is documented in the manpage as
 being disabled by default.
 
 - Giorgos
State-Changed-From-To: open->closed 
State-Changed-By: bmah 
State-Changed-When: Mon Jun 10 17:38:35 PDT 2002 
State-Changed-Why:  
The fact that some users have experienced problems with ATA tagged 
queueing has been documented in the release notes. 


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