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$ 26.\" 27.\" 28.Dd February 11, 2003 29.Dt DCONSCHAT 8 30.Os 31.Sh NAME 32.Nm dconschat 33.Nd user interface to 34.Xr dcons 4 35.Sh SYNOPSIS 36.Nm 37.Op Fl brvwRT1 38.Op Fl e Ar escape-char 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. Physical DMA should be enabled on the target machine for access 74via FireWire. 75.Pp 76The 77.Nm 78utility and the 79.Xr dcons 4 80driver communicate using 2 ports, one for the console port and another 81for remote 82.Xr gdb 1 83port. 84Users are supposed to access 85.Nm 86using TTY, 87.Xr telnet 1 88and 89.Xr gdb 1 . 90You can specify listen ports for console and 91.Xr gdb 1 92port using the 93.Fl C 94and 95.Fl G 96options respectively. 97The port number 0 has special meaning that 98current TTY (stdin/stdout) is used instead of TCP/IP. 99A negative port number will disable the port. 100By analogy with 101.Xr pty 4 102device, the 103.Xr dcons 4 104acts as a slave device and 105.Nm 106acts as a master device with 107.Xr telnetd 8 . 108.Pp 109Typed characters are normally transmitted directly to 110.Xr dcons 4 . 111A escape character (the default is 112.Ql ~ 113) appearing as the first character of a line is an escape signal; the 114following are recognized: 115.Bl -tag -width ident 116.It Ic ~. 117Drop the connection and exit. 118.It Ic ~^G 119Invoke kgdb on the terminal on which dconschat is running. 120.It Ic ~^R 121Reset the target over FireWire if a reset address is registered in Configuration ROM. 122.It Ic ~^Z 123Suspend the dconschat process. 124.El 125.Pp 126The following options are supported. 127.Pp 128.Bl -tag -width indent 129.It Fl b 130Translate Ctrl-C to ALT_BREAK (CR + 131.Ql ~ 132+ Ctrl-B) on 133.Xr gdb 1 134port. 135.It Fl r 136Replay old buffer on connection. 137.It Fl v 138Verbose debug output. 139Multiple 140.Fl v 141options increase verbosity. 142.It Fl w 143Listen on a wildcard address rather than localhost. 144.It Fl R 145Read-only. 146Do not write anything to the 147.Xr dcons 4 148buffer. 149.It Fl T 150Enable ad-hoc workaround for the TELNET protocol to 151remove unnecessary byte sequences. 152It should be set when you access 153.Nm 154using 155.Xr telnet 1 . 156.It Fl 1 157One-shot. 158Read available buffer, then exit. 159This implies the 160.Fl r 161option. 162.It Fl e Ar escape-char 163Specify escape character. 164The default is '~'. 165.It Fl h Ar hz 166Specify polling rate. 167The default value is 100. 168.It Fl C Ar console_port 169Specify the console port. 170The default value is 0 (stdin/stdout). 171.It Fl G Ar gdb_port 172Specify 173.Xr gdb 1 174port. 175The default value is \-1 (disabled). 176.It Fl M Ar core 177Specify core file. 178.It Fl N Ar system 179Specify system file such as 180.Pa /boot/kernel/kernel . 181.It Fl t Ar target_eui64 182Specify the 64-bit extended unique identifier of the target, 183and use FireWire to access remote 184.Xr dcons 4 . 185.It Fl a Ar address 186Specify the physical I/O address of the 187.Xr dcons 4 188buffer. 189See 190.Xr dcons 4 191for details. 192If this option is not specified, 193.Nm 194tries to get the address from the Configuration ROM on the target. 195You are supposed to enable 196.Xr dcons_crom 4 197on the target to omit this option. 198.It Fl u Ar bus_num 199Specify FireWire bus number. 200The default is 0. 201.El 202.Sh FILES 203.Bl -tag -width indent -compact 204.It Pa /dev/fwmem0.0 205.It Pa /dev/mem 206.It Pa /dev/kmem 207.El 208.Sh EXAMPLES 209To use 210.Nm 211with FireWire for remote 212.Xr dcons 4 , 213you have to specify the EUI64 of the target. 214You can obtain EUI64 by running 215.Xr fwcontrol 8 216without options. 217The first EUI64 is of the host running 218.Xr fwcontrol 8 219and others on the bus follow. 220.Bd -literal -offset indent 221# fwcontrol 2222 devices (info_len=2) 223node EUI64 status 224 1 77-66-55-44-33-22-11-00 0 225 0 00-11-22-33-44-55-66-77 1 226.Ed 227.Pp 228The EUI64 does not change unless you change the hardware 229as the ethernet address. 230.Pp 231Now we can run 232.Nm . 233.Bd -literal -offset indent 234# dconschat -br -G 12345 -t 00-11-22-33-44-55-66-77 235.Ed 236.Pp 237You will get console output of the target and login prompt if a 238.Xr getty 8 239is running on 240.Xr dcons 4 . 241You can break to DDB with ALT_BREAK (CR + 242.Ql ~ 243+ Ctrl-B) 244if 245.Dv DDB 246and 247.Dv ALT_BREAK_TO_DEBUGGER 248are enabled in the target kernel. 249To quit the session, type CR + 250.Ql ~ 251+ 252.Ql \&. 253in the console port. 254.Pp 255Using 256.Xr gdb 1 257port is almost the same as remote 258.Xr gdb 1 259over serial line except 260using TCP/IP instead of 261.Pa /dev/cu* . 262See 263.Sx "On-line Kernel Debugging Using Remote GDB" 264section of 265.%T "The FreeBSD Developers Handbook" 266and 267.Xr gdb 4 268for details. 269.Bd -literal -offset indent 270% gdb -k kernel.debug 271(kgdb) target remote :12345 272.Ed 273.Pp 274Once 275.Xr gdb 1 276is attached and you specified the 277.Fl b 278option to 279.Nm , 280typing Ctrl-C in 281.Xr gdb 1 282causes a break to debugger. 283.Pp 284The following command gets the console log from the crash dump: 285.Bd -literal -offset indent 286# dconschat -1 -M vmcore.0 -N kernel.0 287.Ed 288.Pp 289If you want access to the console using 290.Xr telnet 1 , 291try the following: 292.Bd -literal -offset indent 293# dconschat -rTC 5555 & 294# telnet localhost 5555 295.Ed 296.Pp 297You may want to keep logging console output of several machines. 298.Nm conserver-com 299in the Ports collection may help you. 300Insert the following lines in 301.Pa conserver.cf : 302.Bd -literal -offset indent 303console local { 304 master localhost; 305 type exec; 306 exec /usr/sbin/dconschat -rh 25; 307} 308console remote { 309 master localhost; 310 type exec; 311 exec /usr/sbin/dconschat -rh 25 -t 00-11-22-33-44-55-66-77; 312} 313.Ed 314.Sh SEE ALSO 315.Xr gdb 1 , 316.Xr telnet 1 , 317.Xr kvm 3 , 318.Xr dcons 4 , 319.Xr dcons_crom 4 , 320.Xr ddb 4 , 321.Xr firewire 4 , 322.Xr fwohci 4 , 323.Xr gdb 4 , 324.Xr eui64 5 , 325.Xr fwcontrol 8 326.Sh AUTHORS 327.An Hidetoshi Shimokawa Aq simokawa@FreeBSD.org 328.Sh BUGS 329This utility is 330.Ud . 331