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 dcons
  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 interacts with
  59 .Xr dcons 4
  60 using
  61 .Xr kvm 3
  62 or
  63 .Xr firewire 4
  64 and interact with a 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 by
  70 .Fl t
  71 option.
  72 .Pp
  73 The
  74 .Nm
  75 and
  76 .Xr dcons 4
  77 communicate using 2 port, one for console port and the other for
  78 remote gdb port.
  79 Users are supposed to access
  80 .Nm
  81 using tty, telnet and gdb.
  82 You can specify listen ports for console and gdb port by
  83 .Fl C
  84 and
  85 .Fl G
  86 options respectively. The port number 0 has special meaning that
  87 current tty(stdin/out) is used instead of TCP/IP.
  88 A negative port number will disable the port.
  89 To quit dconschat, send a CR + '~' + '.' sequence to the console port
  90 or send signal to the process.
  91 .Pp
  92 By analogy with
  93 .Xr pty 4
  94 device, the
  95 .Xr dcons 4
  96 acts as a slave device and
  97 .Nm
  98 acts as a master device with
  99 .Xr telnetd 8 .
 100 .Pp
 101 .Bl -tag -width indent
 102 .It Fl b
 103 Translate Ctrl-C to ALT_BREAK(CR + '~' + Ctrl-B) on gdb port.
 104 .It Fl r
 105 Replay old buffer on connection.
 106 .It Fl v
 107 Verbose debug output. Multiple '-v' increase verbosity.
 108 .It Fl w
 109 Listen on wildcard address rather than localhost.
 110 .It Fl R
 111 Read-only. Don't write anything on dcons buffer.
 112 .It Fl T
 113 Enable ad hoc workaround for telnet protocol to
 114 remove unnecessary byte sequences.
 115 It should be set when you access dconschat using telnet.
 116 .It Fl 1
 117 One-Shot. Read available buffer then exit. This implies
 118 .Fl r
 119 option.
 120 .It Fl h Ar hz
 121 Specify polling rate. The default value is 100.
 122 .It Fl C Ar console_port
 123 Specify console port. The default value is 0(stdin/stdout).
 124 .It Fl G Ar gdb_port
 125 Specify gdb port.. The default value is -1(disabled).
 126 .It Fl M Ar core
 127 Specify core file.
 128 .It Fl N Ar system
 129 Specify system file such as /boot/kernel/kernel.
 130 .It Fl t Ar target_eui64
 131 Specify the 64bit extended unique identifier of the target and use FireWire to access remote
 132 .Xr dcons 4 .
 133 .It Fl a Ar address
 134 Specify the physical/IO address of the dcons buffer. See
 135 .Xr dcons 4
 136 for details.
 137 If this option is not specified,
 138 .Nm
 139 tries to get the address from the Configuration ROM on the target.
 140 You are supposed to enable
 141 .Xr dcons_crom 4
 142 on the target to omit this option.
 143 .It Fl u Ar bus_num
 144 Specify FireWire bus number. The default is 0.
 145 .El
 146 .Sh EXAMPLE
 147 To use
 148 .Nm
 149 with FireWire for remote
 150 .Xr dcons ,
 151 you have to specify the eui64 of the target.
 152 You can obtain EUI64 by running
 153 .Xr fwcontorl 4
 154 without options.
 155 The first EUI64 is of the host running fwcontrol and others on the
 156 bus follow.
 157 .Bd -literal -offset indent
 158 # fwcontrol
 159 2 devices (info_len=2)
 160 node           EUI64          status
 161    1  77-66-55-44-33-22-11-00      0
 162    0  00-11-22-33-44-55-66-77      1
 163 .Ed
 164 .Pp
 165 The EUI64 doesn't change unless you change the hardware
 166 as the ethernet address.
 167 .Pp
 168 Now we can run the
 169 .Nm .
 170 .Bd -literal -offset indent
 171 # dconschat -br -G 12345 -t 00-11-22-33-44-55-66-77
 172 .Ed
 173 .Pp
 174 You'll get console output of the target and login prompt if a getty is
 175 running on dcons. You can break to DDB with ALT_BREAK (CR + '~' + Ctrl-B)
 176 if DDB and ALT_BREAK_TO_DEBUGGER is enabled in the target kernel.
 177 To quit the session, type CR + '~' + '.' in the console port.
 178 .Pp
 179 Using gdb port is almost the same as remote gdb over serial line except
 180 using TCP/IP instead of /dev/cu*. See
 181 "On-line Kernel Debugging Using Remote GDB"
 182 section of The FreeBSD Developers Handbook and
 183 .Xr gdb 4
 184 for detail.
 185 .Bd -literal -offset indent
 186 % gdb -k kernel.debug
 187 (kgdb) target remote :12345
 188 .Ed
 189 .Pp
 190 Once gdb is attached and you specified '-b' option to dconschat,
 191 typing "Ctrl-C" on gdb causes break to debugger.
 192 .Pp
 193 The following command get console log from crash dump:
 194 .Bd -literal -offset indent
 195 # dconschat -1 -M vmcore.0 -N kernel.0
 196 .Ed
 197 .Pp
 198 If you want access to the console using telnet, try the following:
 199 .Bd -literal -offset indent
 200 # dconschat -rTC 5555 &
 201 # telnet localhost 5555
 202 .Ed
 203 .Pp
 204 You may want to keep logging console output of several machines. Conserve-com
 205 in the ports collection may help you. Insert the following lines
 206 in the conserver.cf.
 207 .Bd -literal -offset indent
 208 console local {
 209         master localhost;
 210         type exec;
 211         exec /usr/sbin/dconschat -rh 25;
 212 }
 213 console remote {
 214         master localhost;
 215         type exec;
 216         exec /usr/sbin/dconschat -rh 25 -t 00-11-22-33-44-55-66-77;
 217 }
 218 .Ed
 219 .Sh FILES
 220 .Bl -tag -width indent
 221 .It Pa /dev/fwmem0.0
 222 .It Pa /dev/mem
 223 .It Pa /dev/kmem
 224 .El
 225 .Sh SEE ALSO
 226 .Xr gdb 1 ,
 227 .Xr telnet 1 ,
 228 .Xr kvm 3 ,
 229 .Xr dcons 4 ,
 230 .Xr dcons_crom 4 ,
 231 .Xr ddb 4 ,
 232 .Xr firewire 4 ,
 233 .Xr fwohci 4 ,
 234 .Xr gdb 4 ,
 235 .Xr eui64 5 ,
 236 .Xr fwcontrol 8
 237 .Sh AUTHORS
 238 .An Hidetoshi Shimokawa Aq simokawa@FreeBSD.org
 239 .Sh BUGS
 240 This utility is still under development.
 241 .Pp