From owner-svn-doc-all@FreeBSD.ORG Thu May 8 16:09:19 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 5A9B4E5E; Thu, 8 May 2014 16:09:19 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 4670B1F8; Thu, 8 May 2014 16:09:19 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s48G9J7t007476; Thu, 8 May 2014 16:09:19 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s48G9IfU007455; Thu, 8 May 2014 16:09:18 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201405081609.s48G9IfU007455@svn.freebsd.org> From: Dru Lavigne Date: Thu, 8 May 2014 16:09:18 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 08 May 2014 16:09:19 -0000 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=^^ - - Setting Up the Serial Console + serial console @@ -1781,10 +1784,13 @@ raisechar=^^ Quick Serial Console Configuration - This section assumes the default setup and provides a fast - overview of setting up the serial console. + This section provides a fast overview of setting up the + serial console. This procedure can be used when the dumb + terminal is connected to COM1. + Configuring a Serial Console on + <filename>COM1</filename> Connect the serial cable to @@ -1793,7 +1799,7 @@ raisechar=^^ - To see all the boot messages on the serial console, + To configure boot messages to display on the serial console, issue the following command as the superuser: &prompt.root; echo 'console="comconsole"' >> /boot/loader.conf @@ -1822,7 +1828,12 @@ raisechar=^^ In-Depth Serial Console Configuration + This section provides a more detailed explanation of the + steps needed to setup a serial console in &os;. + + Configuring a Serial Console + Prepare a serial cable. @@ -1837,7 +1848,7 @@ raisechar=^^ Unplug the keyboard. - Many PC systems probe for the keyboard during the + Many systems probe for the keyboard during the Power-On Self-Test (POST) 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=^^ anyway, no further configuration is needed. 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 BIOS so that it + ignores this error. Consult the motherboard's manual for details on how to do this. Try setting the keyboard to Not - installed 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 - Not installed and the keyboard will still - work. If the above option is not present in the BIOS, + installed in the BIOS. This + setting tells the BIOS 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 BIOS, look for an Halt on Error option instead. - Setting this to All but Keyboard or even - to No Errors, will have the same + Setting this to All but Keyboard or + to No Errors will have the same effect. - - 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 + 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. - - Plug a dumb terminal into - COM1 - (sio0). - - If a dumb terminal is not available, use an old + Plug a dumb terminal, an old computer with a modem program, or the serial port on - another &unix; box. If there is no - COM1 - (sio0), get one. At this time, - there is no way to select a port other than - COM1 for the boot blocks without - recompiling the boot blocks. If - COM1 is being used by another - device, temporarily remove that device and install a new - boot block and kernel once &os; is up and running. + another &unix; box into the serial port. - Make sure the configuration file of the custom kernel - has appropriate flags set for - COM1 - (sio0). - - Relevant flags are: - - - - 0x10 - - - 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 as - described below, together with this flag. - - - - - 0x20 - - - Forces this unit to be the console, unless there - is another higher priority console, regardless of - as discussed below. The flag - 0x20 must be used together with - the flag. - - - - - 0x40 - - - Reserves this unit (in conjunction with - 0x10) 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 The - Developer's Handbook for more information on - remote debugging. - - - - - Here is an example setting: - - device sio0 flags 0x10 - - Refer to &man.sio.4; for more details. - - If the flags were not set, run UserConfig on a - different console or recompile the kernel. + Add the appropriate hint.sio.* + entries to /boot/device.hints 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. @@ -2024,18 +1963,16 @@ raisechar=^^ not be detected. Keyboards on some laptops may not be properly found because of this limitation. If this is the case, do not use - . Unfortunately there is no - workaround for this problem. + . Use either to select the - console automatically, or to - activate the serial console. - - Other options are described in &man.boot.8;. + console automatically or to + activate the serial console. Refer to &man.boot.8; and &man.boot.config.5; for more + details. The options, except for , are passed to the boot loader. The boot loader will @@ -2065,7 +2002,7 @@ Keyboard: no presence or absence of the keyboard. These messages go to either the serial or internal console, or both, depending on the option in - /boot.config. + /boot.config: @@ -2149,133 +2086,6 @@ boot: information. - - Summary - - The following tables provide a summary of the various - settings discussed in this section. - - - Case 1: Set the Flags to 0x10 for - <filename>sio0</filename> - - - - - Options in /boot.config - Console during boot blocks - Console during boot loader - Console in kernel - - - - - - nothing - internal - internal - internal - - - - - serial - serial - serial - - - - - serial and internal - internal - internal - - - - - serial and internal - serial - serial - - - - , keyboard present - internal - internal - internal - - - - , keyboard absent - serial and internal - serial - serial - - - -
- - - Case 2: Set the Flags to 0x30 for - <filename>sio0</filename> - - - - - Options in /boot.config - Console during boot blocks - Console during boot loader - Console in kernel - - - - - - nothing - internal - internal - serial - - - - - serial - serial - serial - - - - - serial and internal - internal - serial - - - - - serial and internal - serial - serial - - - - , keyboard present - internal - internal - serial - - - - , keyboard absent - serial and internal - serial - serial - - - -
- - Tips for the Serial Console @@ -2290,9 +2100,7 @@ boot: Recompile the boot blocks with BOOT_COMCONSOLE_SPEED set to the new - console speed. See - for detailed instructions about building and installing - new boot blocks. + console speed. If the serial console is configured in some other way than by booting with , or if the @@ -2330,69 +2138,6 @@ console="comconsole,vidconsole" - - Using a Serial Port Other Than - <filename>sio0</filename> for the Console - - Using a port other than sio0 as - the console requires the boot blocks, the boot loader, and - the kernel to be recompiled as follows. - - - - Get the kernel source as described in . - - - - Edit /etc/make.conf and set - BOOT_COMCONSOLE_PORT to the address - of the port to use: 0x3F8, 0x2F8, 0x3E8 or 0x2E8. Only - sio0 through - sio3 - (COM1 through - COM4) can be used as multiport - serial cards will not work. No interrupt setting is - needed. - - - - Create a custom kernel configuration file and add - appropriate flags for the serial port to use. For - example, to make sio1 - (COM2) the console: - - device sio1 flags 0x10 - - or - - device sio1 flags 0x30 - - The console flags for the other serial ports should - not be set. - - - - Recompile and install the boot blocks and the boot - loader: - - &prompt.root; cd /sys/boot -&prompt.root; make clean -&prompt.root; make -&prompt.root; make install - - - - Rebuild and install the kernel. - - - - Write the boot blocks to the boot disk with - &man.bsdlabel.8; and boot from the new kernel. - - - - Entering the DDB Debugger from the Serial Line @@ -2444,27 +2189,14 @@ ttyu3 "/usr/libexec/getty std.9600" unkn Changing Console from the Boot Loader - 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. - - - Setting Up the Serial Console - - The boot loader and the kernel to use the serial console - can be specified by writing one line in - /boot/loader.conf: + This line in /boot/loader.conf + configures the boot loader and the kernel to use the serial + console: console="comconsole" 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 + boot block discussed in the previous section. This line should be the first line of /boot/loader.conf so as to see boot messages on the serial console as early as possible. @@ -2490,17 +2222,6 @@ ttyu3 "/usr/libexec/getty std.9600" unkn console and the serial console based on the presence of the keyboard. - - - - Using a Serial Port Other Than - <filename>sio0</filename> for the Console - - The boot loader needs to be compiled in order to use a - serial port other than sio0 for the - serial console. Follow the procedure described in . - 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 @@ audit_warn5"> auth.conf5"> bluetooth.conf5"> +boot.config5"> bootparams5"> bootptab5"> cached.conf5">