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