svn commit: r44793 - in head: en_US.ISO8859-1/books/handbook/serialcomms share/xml
Dru Lavigne
dru at FreeBSD.org
Thu May 8 16:09:19 UTC 2014
Author: dru
Date: Thu May 8 16:09:18 2014
New Revision: 44793
URL: http://svnweb.freebsd.org/changeset/doc/44793
Log:
Editorial review and updating of Serial Console chapter.
Still need to review Tips section (next commit).
Update addresses PRs 101271 and 169544.
Add entity for boot.config(5).
Sponsored by: iXsystems
Modified:
head/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml
head/share/xml/man-refs.ent
Modified: head/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml Thu May 8 10:46:22 2014 (r44792)
+++ head/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml Thu May 8 16:09:18 2014 (r44793)
@@ -1739,25 +1739,28 @@ raisechar=^^</programlisting>
</sect1>
<sect1 xml:id="serialconsole-setup">
- <!--
- <sect1info>
+ <info>
+ <title>Setting Up the Serial Console</title>
+
<authorgroup>
<author>
+ <personname>
<firstname>Kazutaka</firstname>
<surname>YOKOTA</surname>
+ </personname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
<authorgroup>
<author>
+ <personname>
<firstname>Bill</firstname>
<surname>Paul</surname>
+ </personname>
<contrib>Based on a document by </contrib>
</author>
</authorgroup>
- </sect1info>
- -->
- <title>Setting Up the Serial Console</title>
+ </info>
<indexterm><primary>serial console</primary></indexterm>
@@ -1781,10 +1784,13 @@ raisechar=^^</programlisting>
<sect2 xml:id="serialconsole-howto-fast">
<title>Quick Serial Console Configuration</title>
- <para>This section assumes the default setup and provides a fast
- overview of setting up the serial console.</para>
+ <para>This section provides a fast overview of setting up the
+ serial console. This procedure can be used when the dumb
+ terminal is connected to <filename>COM1</filename>.</para>
<procedure>
+ <title>Configuring a Serial Console on
+ <filename>COM1</filename></title>
<step>
<para>Connect the serial cable to
@@ -1793,7 +1799,7 @@ raisechar=^^</programlisting>
</step>
<step>
- <para>To see all the boot messages on the serial console,
+ <para>To configure boot messages to display on the serial console,
issue the following command as the superuser:</para>
<screen>&prompt.root; echo 'console="comconsole"' >> /boot/loader.conf</screen>
@@ -1822,7 +1828,12 @@ raisechar=^^</programlisting>
<sect2 xml:id="serialconsole-howto">
<title>In-Depth Serial Console Configuration</title>
+ <para>This section provides a more detailed explanation of the
+ steps needed to setup a serial console in &os;.</para>
+
<procedure>
+ <title>Configuring a Serial Console</title>
+
<step>
<para>Prepare a serial cable.</para>
@@ -1837,7 +1848,7 @@ raisechar=^^</programlisting>
<step>
<para>Unplug the keyboard.</para>
- <para>Many PC systems probe for the keyboard during the
+ <para>Many systems probe for the keyboard during the
Power-On Self-Test (<acronym>POST</acronym>) and will
generate an error if the keyboard is not detected. Some
machines will refuse to boot until the keyboard is plugged
@@ -1847,114 +1858,42 @@ raisechar=^^</programlisting>
anyway, no further configuration is needed.</para>
<para>If the computer refuses to boot without a keyboard
- attached, the BIOS needs to be configured so that it
- ignores this error (if it can). Consult the motherboard's
+ attached, configure the <acronym>BIOS</acronym> so that it
+ ignores this error. Consult the motherboard's
manual for details on how to do this.</para>
<tip>
<para>Try setting the keyboard to <quote>Not
- installed</quote> in the BIOS. The keyboard can still
- be used as this setting just tells the BIOS not to probe
- for a keyboard at power-on. The BIOS should not
- complain if the keyboard is absent. You can leave the
- keyboard plugged in even with this flag set to
- <quote>Not installed</quote> and the keyboard will still
- work. If the above option is not present in the BIOS,
+ installed</quote> in the <acronym>BIOS</acronym>. This
+ setting tells the <acronym>BIOS</acronym> not to probe
+ for a keyboard at power-on so it should not
+ complain if the keyboard is absent. If that option is not present in the <acronym>BIOS</acronym>,
look for an <quote>Halt on Error</quote> option instead.
- Setting this to <quote>All but Keyboard</quote> or even
- to <quote>No Errors</quote>, will have the same
+ Setting this to <quote>All but Keyboard</quote> or
+ to <quote>No Errors</quote> will have the same
effect.</para>
</tip>
- <note>
- <para>If the system has a &ps2; mouse, chances are good
- that both the mouse and keyboard need to be unplugged.
- This is because &ps2; mice share some hardware with the
+ <para>If the system has a &ps2; mouse, unplug it as well.
+ &ps2; mice share some hardware with the
keyboard and leaving the mouse plugged in can fool the
keyboard probe into thinking the keyboard is still
there.</para>
- </note>
</step>
<step>
- <para>Plug a dumb terminal into
- <filename>COM1</filename>
- (<filename>sio0</filename>).</para>
-
- <para>If a dumb terminal is not available, use an old
+ <para>Plug a dumb terminal, an old
computer with a modem program, or the serial port on
- another &unix; box. If there is no
- <filename>COM1</filename>
- (<filename>sio0</filename>), get one. At this time,
- there is no way to select a port other than
- <filename>COM1</filename> for the boot blocks without
- recompiling the boot blocks. If
- <filename>COM1</filename> is being used by another
- device, temporarily remove that device and install a new
- boot block and kernel once &os; is up and running.</para>
+ another &unix; box into the serial port.</para>
</step>
<step>
- <para>Make sure the configuration file of the custom kernel
- has appropriate flags set for
- <filename>COM1</filename>
- (<filename>sio0</filename>).</para>
-
- <para>Relevant flags are:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>0x10</literal></term>
-
- <listitem>
- <para>Enables console support for this unit. The
- other console flags are ignored unless this is set.
- Currently, at most one unit can have console
- support. The first one, in config file order, with
- this flag set is preferred. This option alone will
- not make the serial port the console. Set the
- following flag or use <option>-h</option> as
- described below, together with this flag.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>0x20</literal></term>
-
- <listitem>
- <para>Forces this unit to be the console, unless there
- is another higher priority console, regardless of
- <option>-h</option> as discussed below. The flag
- <literal>0x20</literal> must be used together with
- the <option>0x10</option> flag.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>0x40</literal></term>
-
- <listitem>
- <para>Reserves this unit (in conjunction with
- <literal>0x10</literal>) and makes the unit
- unavailable for normal access. This flag should
- not be set to the serial port to use as the serial
- console. The only use of this flag is to designate
- the unit for kernel remote debugging. See <link
- xlink:href="&url.books.developers-handbook;/index.html">The
- Developer's Handbook</link> for more information on
- remote debugging.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>Here is an example setting:</para>
-
- <programlisting>device sio0 flags 0x10</programlisting>
-
- <para>Refer to &man.sio.4; for more details.</para>
-
- <para>If the flags were not set, run UserConfig on a
- different console or recompile the kernel.</para>
+ <para>Add the appropriate <literal>hint.sio.*</literal>
+ entries to <filename>/boot/device.hints</filename> for the
+ serial port. Some multi-port cards also require kernel
+ configuration options. Refer to &man.sio.4; for the
+ required options and device hints for each supported
+ serial port.</para>
</step>
<step>
@@ -2024,18 +1963,16 @@ raisechar=^^</programlisting>
not be detected. Keyboards on some laptops
may not be properly found because of this
limitation. If this is the case, do not use
- <option>-P</option>. Unfortunately there is no
- workaround for this problem.</para>
+ <option>-P</option>.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
<para>Use either <option>-P</option> to select the
- console automatically, or <option>-h</option> to
- activate the serial console.</para>
-
- <para>Other options are described in &man.boot.8;.</para>
+ console automatically or <option>-h</option> to
+ activate the serial console. Refer to &man.boot.8; and &man.boot.config.5; for more
+ details.</para>
<para>The options, except for <option>-P</option>, are
passed to the boot loader. The boot loader will
@@ -2065,7 +2002,7 @@ Keyboard: no</screen>
presence or absence of the keyboard. These messages go
to either the serial or internal console, or both,
depending on the option in
- <filename>/boot.config</filename>.</para>
+ <filename>/boot.config</filename>:</para>
<informaltable frame="none" pgwide="1">
<tgroup cols="2">
@@ -2149,133 +2086,6 @@ boot:</screen>
information.</para>
</sect2>
- <sect2 xml:id="serialconsole-summary">
- <title>Summary</title>
-
- <para>The following tables provide a summary of the various
- settings discussed in this section.</para>
-
- <table frame="none" pgwide="1">
- <title>Case 1: Set the Flags to 0x10 for
- <filename>sio0</filename></title>
-
- <tgroup cols="4">
- <thead>
- <row>
- <entry align="left">Options in /boot.config</entry>
- <entry align="left">Console during boot blocks</entry>
- <entry align="left">Console during boot loader</entry>
- <entry align="left">Console in kernel</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>nothing</entry>
- <entry>internal</entry>
- <entry>internal</entry>
- <entry>internal</entry>
- </row>
-
- <row>
- <entry><option>-h</option></entry>
- <entry>serial</entry>
- <entry>serial</entry>
- <entry>serial</entry>
- </row>
-
- <row>
- <entry><option>-D</option></entry>
- <entry>serial and internal</entry>
- <entry>internal</entry>
- <entry>internal</entry>
- </row>
-
- <row>
- <entry><option>-Dh</option></entry>
- <entry>serial and internal</entry>
- <entry>serial</entry>
- <entry>serial</entry>
- </row>
-
- <row>
- <entry><option>-P</option>, keyboard present</entry>
- <entry>internal</entry>
- <entry>internal</entry>
- <entry>internal</entry>
- </row>
-
- <row>
- <entry><option>-P</option>, keyboard absent</entry>
- <entry>serial and internal</entry>
- <entry>serial</entry>
- <entry>serial</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1">
- <title>Case 2: Set the Flags to 0x30 for
- <filename>sio0</filename></title>
-
- <tgroup cols="4">
- <thead>
- <row>
- <entry align="left">Options in /boot.config</entry>
- <entry align="left">Console during boot blocks</entry>
- <entry align="left">Console during boot loader</entry>
- <entry align="left">Console in kernel</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>nothing</entry>
- <entry>internal</entry>
- <entry>internal</entry>
- <entry>serial</entry>
- </row>
-
- <row>
- <entry><option>-h</option></entry>
- <entry>serial</entry>
- <entry>serial</entry>
- <entry>serial</entry>
- </row>
-
- <row>
- <entry><option>-D</option></entry>
- <entry>serial and internal</entry>
- <entry>internal</entry>
- <entry>serial</entry>
- </row>
-
- <row>
- <entry><option>-Dh</option></entry>
- <entry>serial and internal</entry>
- <entry>serial</entry>
- <entry>serial</entry>
- </row>
-
- <row>
- <entry><option>-P</option>, keyboard present</entry>
- <entry>internal</entry>
- <entry>internal</entry>
- <entry>serial</entry>
- </row>
-
- <row>
- <entry><option>-P</option>, keyboard absent</entry>
- <entry>serial and internal</entry>
- <entry>serial</entry>
- <entry>serial</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </sect2>
-
<sect2 xml:id="serialconsole-tips">
<title>Tips for the Serial Console</title>
@@ -2290,9 +2100,7 @@ boot:</screen>
<listitem>
<para>Recompile the boot blocks with
<varname>BOOT_COMCONSOLE_SPEED</varname> set to the new
- console speed. See <xref linkend="serialconsole-com2"/>
- for detailed instructions about building and installing
- new boot blocks.</para>
+ console speed.</para>
<para>If the serial console is configured in some other
way than by booting with <option>-h</option>, or if the
@@ -2330,69 +2138,6 @@ console="comconsole,vidconsole"</program
</itemizedlist>
</sect3>
- <sect3 xml:id="serialconsole-com2">
- <title>Using a Serial Port Other Than
- <filename>sio0</filename> for the Console</title>
-
- <para>Using a port other than <filename>sio0</filename> as
- the console requires the boot blocks, the boot loader, and
- the kernel to be recompiled as follows.</para>
-
- <procedure>
- <step>
- <para>Get the kernel source as described in <xref
- linkend="updating-upgrading"/>.</para>
- </step>
-
- <step>
- <para>Edit <filename>/etc/make.conf</filename> and set
- <literal>BOOT_COMCONSOLE_PORT</literal> to the address
- of the port to use: 0x3F8, 0x2F8, 0x3E8 or 0x2E8. Only
- <filename>sio0</filename> through
- <filename>sio3</filename>
- (<filename>COM1</filename> through
- <filename>COM4</filename>) can be used as multiport
- serial cards will not work. No interrupt setting is
- needed.</para>
- </step>
-
- <step>
- <para>Create a custom kernel configuration file and add
- appropriate flags for the serial port to use. For
- example, to make <filename>sio1</filename>
- (<filename>COM2</filename>) the console:</para>
-
- <programlisting>device sio1 flags 0x10</programlisting>
-
- <para>or</para>
-
- <programlisting>device sio1 flags 0x30</programlisting>
-
- <para>The console flags for the other serial ports should
- not be set.</para>
- </step>
-
- <step>
- <para>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>
- </step>
-
- <step>
- <para>Rebuild and install the kernel.</para>
- </step>
-
- <step>
- <para>Write the boot blocks to the boot disk with
- &man.bsdlabel.8; and boot from the new kernel.</para>
- </step>
- </procedure>
- </sect3>
-
<sect3 xml:id="serialconsole-ddb">
<title>Entering the DDB Debugger from the Serial Line</title>
@@ -2444,27 +2189,14 @@ ttyu3 "/usr/libexec/getty std.9600" unkn
<sect2 xml:id="serialconsole-loader">
<title>Changing Console from the Boot Loader</title>
- <para>Previous sections described how to set up the serial
- console by tweaking the boot block. This section shows how to
- specify the console by entering some commands and
- environment variables in the boot loader. As the boot loader
- is invoked at the third stage of the boot process, the
- settings in the boot loader will override the settings in the
- boot block.</para>
-
- <sect3>
- <title>Setting Up the Serial Console</title>
-
- <para>The boot loader and the kernel to use the serial console
- can be specified by writing one line in
- <filename>/boot/loader.conf</filename>:</para>
+ <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.</para>
-
- <para>This line should be the first line of
+ 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>
@@ -2490,17 +2222,6 @@ ttyu3 "/usr/libexec/getty std.9600" unkn
console and the serial console based on the presence of
the keyboard.</para>
</note>
- </sect3>
-
- <sect3>
- <title>Using a Serial Port Other Than
- <filename>sio0</filename> for the Console</title>
-
- <para>The boot loader needs to be compiled in order to use a
- serial port other than <filename>sio0</filename> for the
- serial console. Follow the procedure described in <xref
- linkend="serialconsole-com2"/>.</para>
- </sect3>
</sect2>
<sect2 xml:id="serialconsole-caveats">
Modified: head/share/xml/man-refs.ent
==============================================================================
--- head/share/xml/man-refs.ent Thu May 8 10:46:22 2014 (r44792)
+++ head/share/xml/man-refs.ent Thu May 8 16:09:18 2014 (r44793)
@@ -3992,6 +3992,7 @@
<!ENTITY man.audit.warn.5 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>audit_warn</refentrytitle><manvolnum>5</manvolnum></citerefentry>">
<!ENTITY man.auth.conf.5 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>auth.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>">
<!ENTITY man.bluetooth.conf.5 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>bluetooth.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>">
+<!ENTITY man.boot.config.5 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>boot.config</refentrytitle><manvolnum>5</manvolnum></citerefentry>">
<!ENTITY man.bootparams.5 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>bootparams</refentrytitle><manvolnum>5</manvolnum></citerefentry>">
<!ENTITY man.bootptab.5 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>bootptab</refentrytitle><manvolnum>5</manvolnum></citerefentry>">
<!ENTITY man.cached.conf.5 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>cached.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>">
More information about the svn-doc-all
mailing list