Finish editorial review of Serial Console section.

Some reshuffling to avoid redundancy.
Should undergo a tech review to make sure all the details are correct and
updated for the supported versions of FreeBSD.

Sponsored by:	iXsystems

1 files changed, 79 insertions, 122 deletions

diff --git a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml
index b30aef41d1..bb0e655f38 100644
--- a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml
@@ -1879,6 +1879,19 @@ raisechar=^^</programlisting>
 	      keyboard and leaving the mouse plugged in can fool the
 	      keyboard probe into thinking the keyboard is still
 	      there.</para>
+
+          <note>
+	    <para>While most systems will boot without a keyboard, quite a
+	few will not boot without a graphics adapter.  Some systems
+	can be configured to  boot with no graphics adapter
+	by changing the <quote>graphics adapter</quote>
+	setting in the <acronym>BIOS</acronym> configuration to <quote>Not
+	  installed</quote>.  Other systems do not support this option and will
+	refuse to boot if there is no display hardware in the system.
+	With these machines, leave some kind of graphics card plugged
+	in, even if it is just a junky mono board.  A monitor does not
+	need to be attached.</para>
+	  </note>
 	</step>
 
 	<step>
@@ -2082,164 +2095,108 @@ boot:</screen>
       <para>During the third stage of the boot process, one can still
 	switch between the internal console and the serial console by
 	setting appropriate environment variables in the boot loader.
-	See <xref linkend="serialconsole-loader"/> for more
+	See &man.loader.8; for more
 	information.</para>
-    </sect2>
 
-    <sect2 xml:id="serialconsole-tips">
-      <title>Tips for the Serial Console</title>
+      <note>
+	<para>This line in <filename>/boot/loader.conf</filename> or
+	  <filename>/boot/loader.conf.local</filename>
+	  configures the boot loader and the kernel to send their boot messages to the serial
+	  console, regardless of the options in <filename>/boot.config</filename>:</para>
+
+	<programlisting>console="comconsole"</programlisting>
+
+	<para>That line should be the first line of
+	  <filename>/boot/loader.conf</filename> so that boot
+	  messages are displayed on the serial console as early as possible.</para>
+
+	<para>If that line does not exist, or if it is set to
+	  <literal>console="vidconsole"</literal>, the boot loader and
+	  the kernel will use whichever console is
+	  indicated by <option>-h</option> in the boot block.  See
+	  &man.loader.conf.5; for more information.</para>
+
+	  <para>At the moment, the boot loader has no option
+	    equivalent to <option>-P</option> in the boot block, and
+	    there is no provision to automatically select the internal
+	    console and the serial console based on the presence of
+	    the keyboard.</para>
+	</note>
+
+      <tip>
+	<para>While it is not required, it is possible to provide a
+	  <command>login</command> prompt over the serial line.  To
+	  configure this, edit the entry for the serial port in
+	  <filename>/etc/ttys</filename> using the instructions in
+	  <xref linkend="term-config"/>.  If the speed of the serial port has been
+	  changed, change <literal>std.9600</literal> to match the
+	  new setting.</para>
+      </tip>
+    </sect2>
 
-      <sect3>
+      <sect2>
 	<title>Setting a Faster Serial Port Speed</title>
 
 	<para>By default, the serial port settings are 9600 baud, 8
 	  bits, no parity, and 1 stop bit.  To change the default
-	  console speed, the following options are available:</para>
+	  console speed, use one of the following options:</para>
 
 	<itemizedlist>
 	  <listitem>
-	    <para>Recompile the boot blocks with
-	      <varname>BOOT_COMCONSOLE_SPEED</varname> set to the new
-	      console speed.</para>
+	    <para>Edit <filename>/etc/make.conf</filename> and set
+	      <varname>BOOT_COMCONSOLE_SPEED</varname> to the new
+	      console speed.  Then, recompile and install the boot
+	      blocks and the boot loader:</para>
+
+	    <screen>&prompt.root; <userinput>cd /sys/boot</userinput>
+&prompt.root; <userinput>make clean</userinput>
+&prompt.root; <userinput>make</userinput>
+&prompt.root; <userinput>make install</userinput></screen>
 
 	    <para>If the serial console is configured in some other
 	      way than by booting with <option>-h</option>, or if the
 	      serial console used by the kernel is different from the
-	      one used by the boot blocks, add the following option
+	      one used by the boot blocks, add the following option, with the desired speed,
 	      to a custom kernel configuration file and compile a
 	      new kernel:</para>
 
-	    <programlisting>options CONSPEED=19200</programlisting>
+	    <programlisting>options CONSPEED=<replaceable>19200</replaceable></programlisting>
 	  </listitem>
 
 	  <listitem>
-	    <para>Add the <option>-S</option> boot option to
-	      <filename>/boot.config</filename>.  See &man.boot.8; for
-	      a description of how to add options to
-	      <filename>/boot.config</filename> and a list of the
-	      supported options.</para>
+	    <para>Add the <option>-S <replaceable>19200</replaceable></option> boot option to
+	      <filename>/boot.config</filename>, replacing
+	      <replaceable>19200</replaceable> with the speed to use.</para>
 	  </listitem>
 
 	  <listitem>
-	    <para>Enable <varname>comconsole_speed</varname> in
-	      <filename>/boot/loader.conf</filename>.  This option
-	      depends on <varname>console</varname>,
-	      <varname>boot_serial</varname>, and
-	      <varname>boot_multicons</varname> being set in
-	      <filename>/boot/loader.conf</filename> too.  An example
-	      of using <varname>comconsole_speed</varname> to change
-	      the serial console speed is:</para>
+	    <para>Add the following options to
+	      <filename>/boot/loader.conf</filename>.  Replace
+	      <replaceable>115200</replaceable> with the speed to
+	      use.</para>
 
 	    <programlisting>boot_multicons="YES"
 boot_serial="YES"
-comconsole_speed="115200"
+comconsole_speed="<replaceable>115200</replaceable>"
 console="comconsole,vidconsole"</programlisting>
 	  </listitem>
 	</itemizedlist>
-      </sect3>
+      </sect2>
 
-      <sect3 xml:id="serialconsole-ddb">
+      <sect2 xml:id="serialconsole-ddb">
 	<title>Entering the DDB Debugger from the Serial Line</title>
 
-	<para>To drop into the kernel debugger from the serial
-	  console, compile a custom kernel with the following options.
+	<para>To configure the ability to drop into the kernel debugger from the serial
+	  console, add the following options to a custom kernel
+	  configuration file and compile the kernel using the
+	  instructions in <xref linkend="kernelconfig"/>.
 	  Note that while this is useful for remote diagnostics, it is
 	  also dangerous if a spurious BREAK is generated on the
-	  serial port.</para>
+	  serial port.  Refer to &man.ddb.4; and &man.ddb.8; for more
+	  information about the kernel debugger.</para>
 
 	<programlisting>options BREAK_TO_DEBUGGER
 options DDB</programlisting>
-      </sect3>
-
-      <sect3>
-	<title>Getting a Login Prompt on the Serial Console</title>
-
-	<para>While this is not required, it is possible to get a
-	  <emphasis>login</emphasis> prompt over the serial line.
-	  First, make sure that the boot messages are displayed and it
-	  is possible to enter the kernel debugging session through
-	  the serial console.</para>
-
-	<para>Open <filename>/etc/ttys</filename> with a text editor
-	  and locate the lines:</para>
-
-	<programlisting>ttyu0 "/usr/libexec/getty std.9600" unknown off secure
-ttyu1 "/usr/libexec/getty std.9600" unknown off secure
-ttyu2 "/usr/libexec/getty std.9600" unknown off secure
-ttyu3 "/usr/libexec/getty std.9600" unknown off secure</programlisting>
-
-	<para><filename>ttyu0</filename> through
-	  <filename>ttyu3</filename> correspond to
-	  <filename>COM1</filename> through
-	  <filename>COM4</filename>.  Change
-	  <literal>off</literal> to <literal>on</literal> for the
-	  desired port.  If the speed of the serial port has been
-	  changed, change <literal>std.9600</literal> to match the
-	  new setting.</para>
-
-	<para>The terminal type can also be changed from
-	  <literal>unknown</literal> to the actual type of the serial
-	  terminal.</para>
-
-	<para>After editing the file, type <command>kill -HUP
-	    1</command> to make this change take effect.</para>
-      </sect3>
-    </sect2>
-
-    <sect2 xml:id="serialconsole-loader">
-      <title>Changing Console from the Boot Loader</title>
-
-	<para>This line in <filename>/boot/loader.conf</filename>
-	  configures the boot loader and the kernel to use the serial
-	  console:</para>
-
-	<programlisting>console="comconsole"</programlisting>
-
-	<para>This will take effect regardless of the settings in the
-	  boot block discussed in the previous section.  This line should be the first line of
-	  <filename>/boot/loader.conf</filename> so as to see boot
-	  messages on the serial console as early as possible.</para>
-
-	<para>Likewise, to specify the internal console:</para>
-
-	<programlisting>console="vidconsole"</programlisting>
-
-	<para>If the boot loader environment variable
-	  <envar>console</envar> is not set, the boot loader, and
-	  subsequently the kernel, will use whichever console is
-	  indicated by <option>-h</option> in the  boot block.</para>
-
-	<para>The console can be specified in
-	  <filename>/boot/loader.conf.local</filename> or in
-	  <filename>/boot/loader.conf</filename>.</para>
-
-	<para>See &man.loader.conf.5; for more information.</para>
-
-	<note>
-	  <para>At the moment, the boot loader has no option
-	    equivalent to <option>-P</option> in the boot block, and
-	    there is no provision to automatically select the internal
-	    console and the serial console based on the presence of
-	    the keyboard.</para>
-	</note>
-    </sect2>
-
-    <sect2 xml:id="serialconsole-caveats">
-      <title>Caveats</title>
-
-      <para>While most systems will boot without a keyboard, quite a
-	few will not boot without a graphics adapter.  Machines with
-	AMI BIOSes can be configured to  boot with no graphics adapter
-	installed by changing the <quote>graphics adapter</quote>
-	setting in the CMOS configuration to <quote>Not
-	  installed.</quote></para>
-
-      <para>However, many machines do not support this option and will
-	refuse to boot if there is no display hardware in the system.
-	With these machines, leave some kind of graphics card plugged
-	in, even if it is just a junky mono board.  A monitor does not
-	need to be attached.  One might also try installing an AMI
-	BIOS.</para>
-    </sect2>
+      </sect2>
   </sect1>
 </chapter>