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