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