usr.sbin/dconschat/dconschat.8

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