From joel@automatvapen.se  Tue Nov  2 18:32:25 2004
Return-Path: <joel@automatvapen.se>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id E414E16A4CE
	for <FreeBSD-gnats-submit@freebsd.org>; Tue,  2 Nov 2004 18:32:24 +0000 (GMT)
Received: from av12-1-sn2.hy.skanova.net (av12-1-sn2.hy.skanova.net [81.228.8.185])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 0F5B443D49
	for <FreeBSD-gnats-submit@freebsd.org>; Tue,  2 Nov 2004 18:32:24 +0000 (GMT)
	(envelope-from joel@automatvapen.se)
Received: by av12-1-sn2.hy.skanova.net (Postfix, from userid 502)
	id A5AD938512; Tue,  2 Nov 2004 19:32:22 +0100 (CET)
Received: from smtp4-2-sn2.hy.skanova.net (smtp4-2-sn2.hy.skanova.net [81.228.8.93])
	by av12-1-sn2.hy.skanova.net (Postfix) with ESMTP id 902D938517
	for <FreeBSD-gnats-submit@freebsd.org>; Tue,  2 Nov 2004 19:32:22 +0100 (CET)
Received: from dude.automatvapen.se (t9o955p20.telia.com [213.66.33.20])
	by smtp4-2-sn2.hy.skanova.net (Postfix) with SMTP id 53DCE37E7B
	for <FreeBSD-gnats-submit@freebsd.org>; Tue,  2 Nov 2004 19:32:20 +0100 (CET)
Received: by dude.automatvapen.se (sSMTP sendmail emulation); Tue,  2 Nov 2004 19:32:47 +0100
Message-Id: <20041102183220.53DCE37E7B@smtp4-2-sn2.hy.skanova.net>
Date: Tue,  2 Nov 2004 19:32:47 +0100
From: "Joel Dahl" <joel@automatvapen.se>
Reply-To: Joel Dahl <joel@automatvapen.se>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: [patch] Update Handbook, Chapter 8, kernel configuration
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         73429
>Category:       docs
>Synopsis:       [patch] Update Handbook, Chapter 8, kernel configuration
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    ceri
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Nov 02 18:40:29 GMT 2004
>Closed-Date:    Mon Nov 08 21:05:37 GMT 2004
>Last-Modified:  Mon Nov 08 21:05:37 GMT 2004
>Originator:     Joel Dahl
>Release:        FreeBSD 5.2.1-RELEASE-p9 i386
>Organization:
>Environment:
System: FreeBSD dude.automatvapen.se 5.2.1-RELEASE-p9 FreeBSD 5.2.1-RELEASE-p9 #2: Sat Oct 30 14:56:56 CEST 2004 joel@dude.automatvapen.se:/usr/obj/usr/src/sys/WORKSTATION i386

	
>Description:
[1] Update the weak description of ADAPTIVE_GIANT.

[2] Option SMP was removed from GENERIC in RELENG_5 and RELENG_5_3, so it
    should probably be removed here as well.

[3] Update description for apic since SMP is gone.

[4] Device hptmv now ships with RELENG_5 and RELENG_5_3, but it's missing
    in here, so let's add it.

See attached patch for suggested corrections.
	
>How-To-Repeat:
	
>Fix:

	

--- kernconf.diff begins here ---
--- chapter.sgml	Sun Oct 31 09:06:48 2004
+++ new.chapter.sgml	Tue Nov  2 19:04:34 2004
@@ -893,19 +893,26 @@
 
     <programlisting>options          ADAPTIVE_GIANT    # Giant mutex is adaptive.</programlisting>
 
-    <para>This option causes Giant to be included in the set of mutexes
-      adaptively spun on.</para>
+    <para>Giant is the name of a mutual exclusion mechanism (a sleep mutex)
+      that protects a large set of kernel resources.  Today, this is an
+      unacceptable performance bottleneck which is actively beeing replaced
+      with locks that protect individual resources.  The ADAPTIVE_GIANT
+      option causes Giant to be included in the set of mutexes adaptively
+      spun on.  That is, when a thread wants to lock the Giant mutex, but it
+      is already locked by a thread on another CPU, the first thread will
+      keep running and wait for the lock to be released.  Normally, the
+      thread would instead go back to sleep and wait for its next chance to
+      run.</para>
 
     <indexterm>
       <primary>kernel options</primary>
       <secondary>SMP</secondary>
     </indexterm>
-    <programlisting># To make an SMP kernel, the next two are needed
-options         SMP                # Symmetric MultiProcessor Kernel
-device          apic               # I/O APIC</programlisting>
+    <programlisting>device          apic               # I/O APIC</programlisting>
 
-    <para>The above are both required for SMP support, and can also be
-      safely enabled on uniprocessor systems.</para>
+    <para>The apic device enables the use of I/O APIC for interrupt
+      delivery.  The apic device can be used in both UP and SMP kernels, but
+      is required for SMP kernels.</para>
 
     <programlisting>device          isa</programlisting>
 
@@ -1026,6 +1033,7 @@
 device          asr        # DPT SmartRAID V, VI and Adaptec SCSI RAID
 device          ciss       # Compaq Smart RAID 5*
 device          dpt        # DPT Smartcache III, IV - See NOTES for options
+device          hptmv      # Highpoint RocketRAID 182x
 device          iir        # Intel Integrated RAID
 device          ips        # IBM (Adaptec) ServeRAID
 device          mly        # Mylex AcceleRAID/eXtremeRAID
--- kernconf.diff ends here ---


>Release-Note:
>Audit-Trail:

From: John Baldwin <jhb@FreeBSD.org>
To: freebsd-doc@FreeBSD.org, Joel Dahl <joel@automatvapen.se>
Cc: FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/73429: [patch] Update Handbook, Chapter 8, kernel configuration
Date: Tue, 2 Nov 2004 16:02:37 -0500

 On Tuesday 02 November 2004 01:32 pm, Joel Dahl wrote:
 > >Number:         73429
 > >Category:       docs
 > >Synopsis:       [patch] Update Handbook, Chapter 8, kernel configuration
 > >Confidential:   no
 > >Severity:       non-critical
 > >Priority:       low
 > >Responsible:    freebsd-doc
 > >State:          open
 > >Quarter:
 > >Keywords:
 > >Date-Required:
 > >Class:          doc-bug
 > >Submitter-Id:   current-users
 > >Arrival-Date:   Tue Nov 02 18:40:29 GMT 2004
 > >Closed-Date:
 > >Last-Modified:
 > >Originator:     Joel Dahl
 > >Release:        FreeBSD 5.2.1-RELEASE-p9 i386
 > >Organization:
 > >Environment:
 >
 > System: FreeBSD dude.automatvapen.se 5.2.1-RELEASE-p9 FreeBSD
 > 5.2.1-RELEASE-p9 #2: Sat Oct 30 14:56:56 CEST 2004
 > joel@dude.automatvapen.se:/usr/obj/usr/src/sys/WORKSTATION i386
 >
 > >Description:
 >
 > [1] Update the weak description of ADAPTIVE_GIANT.
 >
 > [2] Option SMP was removed from GENERIC in RELENG_5 and RELENG_5_3, so it
 >     should probably be removed here as well.
 >
 > [3] Update description for apic since SMP is gone.
 >
 > [4] Device hptmv now ships with RELENG_5 and RELENG_5_3, but it's missing
 >     in here, so let's add it.
 >
 > See attached patch for suggested corrections.
 
 Only note I have (patch looks great!) is that instead of removing SMP, you 
 probably want to say that 'options SMP' should be added to include support 
 for multiple processors.  Note that SMP is present in GENERIC on other 
 architectures such as Alpha and sparc64.  There is also an 'SMP' kernel 
 config for i386 and amd64.
 
 -- 
 John Baldwin <jhb@FreeBSD.org>  <><  http://www.FreeBSD.org/~jhb/
 "Power Users Use the Power to Serve"  =  http://www.FreeBSD.org

From: Joel Dahl <joel@automatvapen.se>
To: John Baldwin <jhb@FreeBSD.org>
Cc: FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/73429: [patch] Update Handbook, Chapter 8, kernel
	configuration
Date: Wed, 03 Nov 2004 10:46:49 +0100

 --=-Z3klKU7JEj0sIP/n7gJo
 Content-Type: text/plain
 Content-Transfer-Encoding: 7bit
 
 On Tue, 2004-11-02 at 22:02, John Baldwin wrote:
 > Only note I have (patch looks great!) is that instead of removing SMP, you 
 > probably want to say that 'options SMP' should be added to include support 
 > for multiple processors.  Note that SMP is present in GENERIC on other 
 > architectures such as Alpha and sparc64.  There is also an 'SMP' kernel 
 > config for i386 and amd64.
 
 I've attached an updated patch that includes your suggestion, and I've
 improved the description of ADAPTIVE_GIANT. Thanks.
 
 --=-Z3klKU7JEj0sIP/n7gJo
 Content-Disposition: attachment; filename=kernconf2.diff
 Content-Type: text/x-patch; name=kernconf2.diff; charset=ISO-8859-1
 Content-Transfer-Encoding: 7bit
 
 --- chapter.sgml	Sun Oct 31 09:06:48 2004
 +++ new.chapter.sgml	Wed Nov  3 10:26:04 2004
 @@ -893,19 +893,28 @@
  
      <programlisting>options          ADAPTIVE_GIANT    # Giant mutex is adaptive.</programlisting>
  
 -    <para>This option causes Giant to be included in the set of mutexes
 -      adaptively spun on.</para>
 +    <para>Giant is the name of a mutual exclusion mechanism (a sleep mutex)
 +      that protects a large set of kernel resources.  Today, this is an
 +      unacceptable performance bottleneck which is actively beeing replaced
 +      with locks that protect individual resources.  The
 +      <literal>ADAPTIVE_GIANT</literal> option causes Giant to be included
 +      in the set of mutexes adaptively spun on.  That is, when a thread
 +      wants to lock the Giant mutex, but it is already locked by a thread
 +      on another CPU, the first thread will keep running and wait for the
 +      lock to be released.  Normally, the thread would instead go back to
 +      sleep and wait for its next chance to run.  If you are not sure,
 +      leave this in.</para>
  
      <indexterm>
        <primary>kernel options</primary>
        <secondary>SMP</secondary>
      </indexterm>
 -    <programlisting># To make an SMP kernel, the next two are needed
 -options         SMP                # Symmetric MultiProcessor Kernel
 -device          apic               # I/O APIC</programlisting>
 +    <programlisting>device          apic               # I/O APIC</programlisting>
  
 -    <para>The above are both required for SMP support, and can also be
 -      safely enabled on uniprocessor systems.</para>
 +    <para>The apic device enables the use of I/O APIC for interrupt
 +      delivery.  The apic device can be used in both UP and SMP kernels, but
 +      is required for SMP kernels.  Add <literal>options SMP</literal> to
 +      include support for multiple processors.</para>
  
      <programlisting>device          isa</programlisting>
  
 @@ -1026,6 +1035,7 @@
  device          asr        # DPT SmartRAID V, VI and Adaptec SCSI RAID
  device          ciss       # Compaq Smart RAID 5*
  device          dpt        # DPT Smartcache III, IV - See NOTES for options
 +device          hptmv      # Highpoint RocketRAID 182x
  device          iir        # Intel Integrated RAID
  device          ips        # IBM (Adaptec) ServeRAID
  device          mly        # Mylex AcceleRAID/eXtremeRAID
 
 --=-Z3klKU7JEj0sIP/n7gJo--
 

From: Joel Dahl <joel@automatvapen.se>
To: FreeBSD-gnats-submit@FreeBSD.org
Cc:  
Subject: Re: docs/73429: [patch] Update Handbook, Chapter 8, kernel
	configuration
Date: Wed, 03 Nov 2004 18:36:11 +0100

 --=-cLxltz3tFX6dKS+oVxU2
 Content-Type: text/plain
 Content-Transfer-Encoding: 7bit
 
 Fix small spelling error. New patch attached.
 
 --=-cLxltz3tFX6dKS+oVxU2
 Content-Disposition: attachment; filename=kernconf3.diff
 Content-Type: text/x-patch; name=kernconf3.diff; charset=ISO-8859-1
 Content-Transfer-Encoding: 7bit
 
 --- chapter.sgml	Sun Oct 31 09:06:48 2004
 +++ new.chapter.sgml	Wed Nov  3 18:33:43 2004
 @@ -893,19 +893,28 @@
  
      <programlisting>options          ADAPTIVE_GIANT    # Giant mutex is adaptive.</programlisting>
  
 -    <para>This option causes Giant to be included in the set of mutexes
 -      adaptively spun on.</para>
 +    <para>Giant is the name of a mutual exclusion mechanism (a sleep mutex)
 +      that protects a large set of kernel resources.  Today, this is an
 +      unacceptable performance bottleneck which is actively being replaced
 +      with locks that protect individual resources.  The
 +      <literal>ADAPTIVE_GIANT</literal> option causes Giant to be included
 +      in the set of mutexes adaptively spun on.  That is, when a thread
 +      wants to lock the Giant mutex, but it is already locked by a thread
 +      on another CPU, the first thread will keep running and wait for the
 +      lock to be released.  Normally, the thread would instead go back to
 +      sleep and wait for its next chance to run.  If you are not sure,
 +      leave this in.</para>
  
      <indexterm>
        <primary>kernel options</primary>
        <secondary>SMP</secondary>
      </indexterm>
 -    <programlisting># To make an SMP kernel, the next two are needed
 -options         SMP                # Symmetric MultiProcessor Kernel
 -device          apic               # I/O APIC</programlisting>
 +    <programlisting>device          apic               # I/O APIC</programlisting>
  
 -    <para>The above are both required for SMP support, and can also be
 -      safely enabled on uniprocessor systems.</para>
 +    <para>The apic device enables the use of I/O APIC for interrupt
 +      delivery.  The apic device can be used in both UP and SMP kernels, but
 +      is required for SMP kernels.  Add <literal>options SMP</literal> to
 +      include support for multiple processors.</para>
  
      <programlisting>device          isa</programlisting>
  
 @@ -1026,6 +1035,7 @@
  device          asr        # DPT SmartRAID V, VI and Adaptec SCSI RAID
  device          ciss       # Compaq Smart RAID 5*
  device          dpt        # DPT Smartcache III, IV - See NOTES for options
 +device          hptmv      # Highpoint RocketRAID 182x
  device          iir        # Intel Integrated RAID
  device          ips        # IBM (Adaptec) ServeRAID
  device          mly        # Mylex AcceleRAID/eXtremeRAID
 
 --=-cLxltz3tFX6dKS+oVxU2--
 
Responsible-Changed-From-To: freebsd-doc->ceri 
Responsible-Changed-By: ceri 
Responsible-Changed-When: Mon Nov 8 20:09:10 GMT 2004 
Responsible-Changed-Why:  
Take this one too. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=73429 
State-Changed-From-To: open->closed 
State-Changed-By: ceri 
State-Changed-When: Mon Nov 8 21:00:36 GMT 2004 
State-Changed-Why:  
Committed, thanks. 

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