1.\" Copyright (c) 2003 Hidetoshi Shimokawa 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 14.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 15.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 16.\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, 17.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 18.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 19.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 21.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 22.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 23.\" POSSIBILITY OF SUCH DAMAGE. 24.\" 25.\" $FreeBSD: src/usr.sbin/dconschat/dconschat.8,v 1.5 2004/06/13 18:03:42 ru Exp $ 26.\" $DragonFly: src/usr.sbin/dconschat/dconschat.8,v 1.2 2004/12/20 14:21:19 swildner Exp $ 27.\" 28.\" 29.Dd February 11, 2003 30.Dt DCONSCHAT 8 31.Os 32.Sh NAME 33.Nm dconschat 34.Nd user interface to 35.Xr dcons 4 36.Sh SYNOPSIS 37.Nm 38.Op Fl brvwRT1 39.Op Fl h Ar hz 40.Op Fl C Ar console_port 41.Op Fl G Ar gdb_port 42.Op Fl M Ar core 43.Op Fl N Ar system 44.Nm 45.Op Fl brvwR1 46.Op Fl h Ar hz 47.Op Fl C Ar console_port 48.Op Fl G Ar gdb_port 49.Op Fl a Ar address 50.Op Fl u Ar bus_num 51.Fl t Ar target_eui64 52.Sh DESCRIPTION 53The 54.Nm 55utility is designed to provide a way for users to access 56.Xr dcons 4 57(dumb console device) on a local or remote system. 58The 59.Nm 60utility interacts with 61.Xr dcons 4 62using 63.Xr kvm 3 64or 65.Xr firewire 4 , 66and interacts with the user over TTY or TCP/IP. 67To access remote 68.Xr dcons 4 69using 70.Xr firewire 4 , 71you have to specify target EUI64 address using the 72.Fl t 73option. 74.Pp 75The 76.Nm 77utility and the 78.Xr dcons 4 79driver communicate using 2 ports, one for the console port and another 80for remote 81.Xr gdb 1 82port. 83Users are supposed to access 84.Nm 85using TTY, 86.Xr telnet 1 87and 88.Xr gdb 1 . 89You can specify listen ports for console and 90.Xr gdb 1 91port using the 92.Fl C 93and 94.Fl G 95options respectively. 96The port number 0 has special meaning that 97current TTY (stdin/stdout) is used instead of TCP/IP. 98A negative port number will disable the port. 99To quit 100.Nm , 101send a CR + 102.Ql ~ 103+ 104.Ql \&. 105sequence to the console port, 106or send signal to the process. 107.Pp 108By analogy with 109.Xr pty 4 110device, the 111.Xr dcons 4 112acts as a slave device and 113.Nm 114acts as a master device with 115.Xr telnetd 8 . 116.Bl -tag -width indent 117.It Fl b 118Translate Ctrl-C to ALT_BREAK (CR + 119.Ql ~ 120+ Ctrl-B) on 121.Xr gdb 1 122port. 123.It Fl r 124Replay old buffer on connection. 125.It Fl v 126Verbose debug output. 127Multiple 128.Fl v 129options increase verbosity. 130.It Fl w 131Listen on a wildcard address rather than localhost. 132.It Fl R 133Read-only. 134Do not write anything to the 135.Xr dcons 4 136buffer. 137.It Fl T 138Enable ad-hoc workaround for the TELNET protocol to 139remove unnecessary byte sequences. 140It should be set when you access 141.Nm 142using 143.Xr telnet 1 . 144.It Fl 1 145One-shot. 146Read available buffer, then exit. 147This implies the 148.Fl r 149option. 150.It Fl h Ar hz 151Specify polling rate. 152The default value is 100. 153.It Fl C Ar console_port 154Specify the console port. 155The default value is 0 (stdin/stdout). 156.It Fl G Ar gdb_port 157Specify 158.Xr gdb 1 159port. 160The default value is \-1 (disabled). 161.It Fl M Ar core 162Specify core file. 163.It Fl N Ar system 164Specify system file such as 165.Pa /kernel . 166.It Fl t Ar target_eui64 167Specify the 64-bit extended unique identifier of the target, 168and use FireWire to access remote 169.Xr dcons 4 . 170.It Fl a Ar address 171Specify the physical I/O address of the 172.Xr dcons 4 173buffer. 174See 175.Xr dcons 4 176for details. 177If this option is not specified, 178.Nm 179tries to get the address from the Configuration ROM on the target. 180You are supposed to enable 181.Xr dcons_crom 4 182on the target to omit this option. 183.It Fl u Ar bus_num 184Specify FireWire bus number. 185The default is 0. 186.El 187.Sh EXAMPLES 188To use 189.Nm 190with FireWire for remote 191.Xr dcons 4 , 192you have to specify the EUI64 of the target. 193You can obtain EUI64 by running 194.Xr fwcontrol 8 195without options. 196The first EUI64 is of the host running 197.Xr fwcontrol 8 198and others on the bus follow. 199.Bd -literal -offset indent 200# fwcontrol 2012 devices (info_len=2) 202node EUI64 status 203 1 77-66-55-44-33-22-11-00 0 204 0 00-11-22-33-44-55-66-77 1 205.Ed 206.Pp 207The EUI64 does not change unless you change the hardware 208as the ethernet address. 209.Pp 210Now we can run 211.Nm . 212.Bd -literal -offset indent 213# dconschat -br -G 12345 -t 00-11-22-33-44-55-66-77 214.Ed 215.Pp 216You will get console output of the target and login prompt if a 217.Xr getty 8 218is running on 219.Xr dcons 4 . 220You can break to DDB with ALT_BREAK (CR + 221.Ql ~ 222+ Ctrl-B) 223if 224.Dv DDB 225and 226.Dv ALT_BREAK_TO_DEBUGGER 227are enabled in the target kernel. 228To quit the session, type CR + 229.Ql ~ 230+ 231.Ql \&. 232in the console port. 233.Pp 234Using 235.Xr gdb 1 236port is almost the same as remote 237.Xr gdb 1 238over serial line except 239using TCP/IP instead of 240.Pa /dev/cu* . 241See 242.Sx "On-line Kernel Debugging Using Remote GDB" 243section of 244.%T "The FreeBSD Developers Handbook" 245and 246.Xr gdb 4 247for details. 248.Bd -literal -offset indent 249% gdb -k kernel.debug 250(kgdb) target remote :12345 251.Ed 252.Pp 253Once 254.Xr gdb 1 255is attached and you specified the 256.Fl b 257option to 258.Nm , 259typing Ctrl-C in 260.Xr gdb 1 261causes a break to debugger. 262.Pp 263The following command gets the console log from the crash dump: 264.Bd -literal -offset indent 265# dconschat -1 -M vmcore.0 -N kernel.0 266.Ed 267.Pp 268If you want access to the console using 269.Xr telnet 1 , 270try the following: 271.Bd -literal -offset indent 272# dconschat -rTC 5555 & 273# telnet localhost 5555 274.Ed 275.Pp 276You may want to keep logging console output of several machines. 277.Nm conserver-com 278in the Ports collection may help you. 279Insert the following lines in 280.Pa conserver.cf : 281.Bd -literal -offset indent 282console local { 283 master localhost; 284 type exec; 285 exec /usr/sbin/dconschat -rh 25; 286} 287console remote { 288 master localhost; 289 type exec; 290 exec /usr/sbin/dconschat -rh 25 -t 00-11-22-33-44-55-66-77; 291} 292.Ed 293.Sh FILES 294.Bl -tag -width indent -compact 295.It Pa /dev/fwmem0.0 296.It Pa /dev/mem 297.It Pa /dev/kmem 298.El 299.Sh SEE ALSO 300.Xr gdb 1 , 301.Xr telnet 1 , 302.Xr kvm 3 , 303.Xr dcons 4 , 304.Xr dcons_crom 4 , 305.Xr ddb 4 , 306.Xr firewire 4 , 307.Xr fwohci 4 , 308.Xr gdb 4 , 309.Xr eui64 5 , 310.Xr fwcontrol 8 311.Sh AUTHORS 312.An Hidetoshi Shimokawa Aq simokawa@FreeBSD.org 313.Sh BUGS 314This utility is 315.Ud . 316