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