Date: Thu, 8 May 2014 16:09:18 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44793 - in head: en_US.ISO8859-1/books/handbook/serialcomms share/xml Message-ID: <201405081609.s48G9IfU007455@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>">;
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201405081609.s48G9IfU007455>