os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Editorial review and updating of Serial Console chapter.

Browse source 
Still need to review Tips section (next commit).
Update addresses PRs 101271 and 169544.
Add entity for boot.config(5).

Sponsored by:	iXsystems
This commit is contained in:
Dru Lavigne 2014-05-08 16:09:18 +00:00
parent 9a294a6fcc
commit 87ef42fb8c
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=44793
2 changed files with 49 additions and 327 deletions
en_US.ISO8859-1/books/handbook/serialcomms
chapter.xml
share/xml
man-refs.ent

375
en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml
View file

@ -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"' &gt;&gt; /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"</programlisting>
</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" unknown off secure</programlisting>
<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" unknown off secure</programlisting>
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">

1
share/xml/man-refs.ent
View file

@ -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>">