| blob | 6e423cb8fb8fd593c829e3ec191f7fc7f318d8b4 |
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