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>
<sect1 xml:id="serialconsole-setup"> <sect1 xml:id="serialconsole-setup">
<!-- <info>
<sect1info> <title>Setting Up the Serial Console</title>
<authorgroup> <authorgroup>
<author> <author>
<personname>
<firstname>Kazutaka</firstname> <firstname>Kazutaka</firstname>
<surname>YOKOTA</surname> <surname>YOKOTA</surname>
</personname>
<contrib>Contributed by </contrib> <contrib>Contributed by </contrib>
</author> </author>
</authorgroup> </authorgroup>
<authorgroup> <authorgroup>
<author> <author>
<personname>
<firstname>Bill</firstname> <firstname>Bill</firstname>
<surname>Paul</surname> <surname>Paul</surname>
</personname>
<contrib>Based on a document by </contrib> <contrib>Based on a document by </contrib>
</author> </author>
</authorgroup> </authorgroup>
</sect1info> </info>
-->
<title>Setting Up the Serial Console</title>
<indexterm><primary>serial console</primary></indexterm> <indexterm><primary>serial console</primary></indexterm>
@ -1781,10 +1784,13 @@ raisechar=^^</programlisting>
<sect2 xml:id="serialconsole-howto-fast"> <sect2 xml:id="serialconsole-howto-fast">
<title>Quick Serial Console Configuration</title> <title>Quick Serial Console Configuration</title>
<para>This section assumes the default setup and provides a fast <para>This section provides a fast overview of setting up the
overview of setting up the serial console.</para> serial console. This procedure can be used when the dumb
terminal is connected to <filename>COM1</filename>.</para>
<procedure> <procedure>
<title>Configuring a Serial Console on
<filename>COM1</filename></title>
<step> <step>
<para>Connect the serial cable to <para>Connect the serial cable to
@ -1793,7 +1799,7 @@ raisechar=^^</programlisting>
</step> </step>
<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> issue the following command as the superuser:</para>
<screen>&prompt.root; echo 'console="comconsole"' &gt;&gt; /boot/loader.conf</screen> <screen>&prompt.root; echo 'console="comconsole"' &gt;&gt; /boot/loader.conf</screen>
@ -1822,7 +1828,12 @@ raisechar=^^</programlisting>
<sect2 xml:id="serialconsole-howto"> <sect2 xml:id="serialconsole-howto">
<title>In-Depth Serial Console Configuration</title> <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> <procedure>
<title>Configuring a Serial Console</title>
<step> <step>
<para>Prepare a serial cable.</para> <para>Prepare a serial cable.</para>
@ -1837,7 +1848,7 @@ raisechar=^^</programlisting>
<step> <step>
<para>Unplug the keyboard.</para> <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 Power-On Self-Test (<acronym>POST</acronym>) and will
generate an error if the keyboard is not detected. Some generate an error if the keyboard is not detected. Some
machines will refuse to boot until the keyboard is plugged machines will refuse to boot until the keyboard is plugged
@ -1847,114 +1858,42 @@ raisechar=^^</programlisting>
anyway, no further configuration is needed.</para> anyway, no further configuration is needed.</para>
<para>If the computer refuses to boot without a keyboard <para>If the computer refuses to boot without a keyboard
attached, the BIOS needs to be configured so that it attached, configure the <acronym>BIOS</acronym> so that it
ignores this error (if it can). Consult the motherboard's ignores this error. Consult the motherboard's
manual for details on how to do this.</para> manual for details on how to do this.</para>
<tip> <tip>
<para>Try setting the keyboard to <quote>Not <para>Try setting the keyboard to <quote>Not
installed</quote> in the BIOS. The keyboard can still installed</quote> in the <acronym>BIOS</acronym>. This
be used as this setting just tells the BIOS not to probe setting tells the <acronym>BIOS</acronym> not to probe
for a keyboard at power-on. The BIOS should not for a keyboard at power-on so it should not
complain if the keyboard is absent. You can leave the complain if the keyboard is absent. If that option is not present in the <acronym>BIOS</acronym>,
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,
look for an <quote>Halt on Error</quote> option instead. look for an <quote>Halt on Error</quote> option instead.
Setting this to <quote>All but Keyboard</quote> or even Setting this to <quote>All but Keyboard</quote> or
to <quote>No Errors</quote>, will have the same to <quote>No Errors</quote> will have the same
effect.</para> effect.</para>
</tip> </tip>
<note> <para>If the system has a &ps2; mouse, unplug it as well.
<para>If the system has a &ps2; mouse, chances are good &ps2; mice share some hardware with the
that both the mouse and keyboard need to be unplugged.
This is because &ps2; mice share some hardware with the
keyboard and leaving the mouse plugged in can fool the keyboard and leaving the mouse plugged in can fool the
keyboard probe into thinking the keyboard is still keyboard probe into thinking the keyboard is still
there.</para> there.</para>
</note>
</step> </step>
<step> <step>
<para>Plug a dumb terminal into <para>Plug a dumb terminal, an old
<filename>COM1</filename>
(<filename>sio0</filename>).</para>
<para>If a dumb terminal is not available, use an old
computer with a modem program, or the serial port on computer with a modem program, or the serial port on
another &unix; box. If there is no another &unix; box into the serial port.</para>
<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>
</step> </step>
<step> <step>
<para>Make sure the configuration file of the custom kernel <para>Add the appropriate <literal>hint.sio.*</literal>
has appropriate flags set for entries to <filename>/boot/device.hints</filename> for the
<filename>COM1</filename> serial port. Some multi-port cards also require kernel
(<filename>sio0</filename>).</para> configuration options. Refer to &man.sio.4; for the
required options and device hints for each supported
<para>Relevant flags are:</para> serial port.</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>
</step> </step>
<step> <step>
@ -2024,18 +1963,16 @@ raisechar=^^</programlisting>
not be detected. Keyboards on some laptops not be detected. Keyboards on some laptops
may not be properly found because of this may not be properly found because of this
limitation. If this is the case, do not use limitation. If this is the case, do not use
<option>-P</option>. Unfortunately there is no <option>-P</option>.</para>
workaround for this problem.</para>
</note> </note>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
<para>Use either <option>-P</option> to select the <para>Use either <option>-P</option> to select the
console automatically, or <option>-h</option> to console automatically or <option>-h</option> to
activate the serial console.</para> activate the serial console. Refer to &man.boot.8; and &man.boot.config.5; for more
details.</para>
<para>Other options are described in &man.boot.8;.</para>
<para>The options, except for <option>-P</option>, are <para>The options, except for <option>-P</option>, are
passed to the boot loader. The boot loader will 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 presence or absence of the keyboard. These messages go
to either the serial or internal console, or both, to either the serial or internal console, or both,
depending on the option in depending on the option in
<filename>/boot.config</filename>.</para> <filename>/boot.config</filename>:</para>
<informaltable frame="none" pgwide="1"> <informaltable frame="none" pgwide="1">
<tgroup cols="2"> <tgroup cols="2">
@ -2149,133 +2086,6 @@ boot:</screen>
information.</para> information.</para>
</sect2> </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"> <sect2 xml:id="serialconsole-tips">
<title>Tips for the Serial Console</title> <title>Tips for the Serial Console</title>
@ -2290,9 +2100,7 @@ boot:</screen>
<listitem> <listitem>
<para>Recompile the boot blocks with <para>Recompile the boot blocks with
<varname>BOOT_COMCONSOLE_SPEED</varname> set to the new <varname>BOOT_COMCONSOLE_SPEED</varname> set to the new
console speed. See <xref linkend="serialconsole-com2"/> console speed.</para>
for detailed instructions about building and installing
new boot blocks.</para>
<para>If the serial console is configured in some other <para>If the serial console is configured in some other
way than by booting with <option>-h</option>, or if the way than by booting with <option>-h</option>, or if the
@ -2330,69 +2138,6 @@ console="comconsole,vidconsole"</programlisting>
</itemizedlist> </itemizedlist>
</sect3> </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"> <sect3 xml:id="serialconsole-ddb">
<title>Entering the DDB Debugger from the Serial Line</title> <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"> <sect2 xml:id="serialconsole-loader">
<title>Changing Console from the Boot Loader</title> <title>Changing Console from the Boot Loader</title>
<para>Previous sections described how to set up the serial <para>This line in <filename>/boot/loader.conf</filename>
console by tweaking the boot block. This section shows how to configures the boot loader and the kernel to use the serial
specify the console by entering some commands and console:</para>
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>
<programlisting>console="comconsole"</programlisting> <programlisting>console="comconsole"</programlisting>
<para>This will take effect regardless of the settings in the <para>This will take effect regardless of the settings in the
boot block discussed in the previous section.</para> boot block discussed in the previous section. This line should be the first line of
<para>This line should be the first line of
<filename>/boot/loader.conf</filename> so as to see boot <filename>/boot/loader.conf</filename> so as to see boot
messages on the serial console as early as possible.</para> 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 console and the serial console based on the presence of
the keyboard.</para> the keyboard.</para>
</note> </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>
<sect2 xml:id="serialconsole-caveats"> <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.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.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.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.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.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>"> <!ENTITY man.cached.conf.5 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>cached.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>">