[block] Provide sandev_read() and sandev_write() as global symbols
[ipxe.git] / contrib / vm / serial-console.1
1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings.  \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 .    ds -- \(*W-
28 .    ds PI pi
29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
31 .    ds L" ""
32 .    ds R" ""
33 .    ds C` ""
34 .    ds C' ""
35 'br\}
36 .el\{\
37 .    ds -- \|\(em\|
38 .    ds PI \(*p
39 .    ds L" ``
40 .    ds R" ''
41 'br\}
42 .\"
43 .\" Escape single quotes in literal strings from groff's Unicode transform.
44 .ie \n(.g .ds Aq \(aq
45 .el       .ds Aq '
46 .\"
47 .\" If the F register is turned on, we'll generate index entries on stderr for
48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
50 .\" output yourself in some meaningful fashion.
51 .ie \nF \{\
52 .    de IX
53 .    tm Index:\\$1\t\\n%\t"\\$2"
54 ..
55 .    nr % 0
56 .    rr F
57 .\}
58 .el \{\
59 .    de IX
60 ..
61 .\}
62 .\"
63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
65 .    \" fudge factors for nroff and troff
66 .if n \{\
67 .    ds #H 0
68 .    ds #V .8m
69 .    ds #F .3m
70 .    ds #[ \f1
71 .    ds #] \fP
72 .\}
73 .if t \{\
74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75 .    ds #V .6m
76 .    ds #F 0
77 .    ds #[ \&
78 .    ds #] \&
79 .\}
80 .    \" simple accents for nroff and troff
81 .if n \{\
82 .    ds ' \&
83 .    ds ` \&
84 .    ds ^ \&
85 .    ds , \&
86 .    ds ~ ~
87 .    ds /
88 .\}
89 .if t \{\
90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
96 .\}
97 .    \" troff and (daisy-wheel) nroff accents
98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105 .ds ae a\h'-(\w'a'u*4/10)'e
106 .ds Ae A\h'-(\w'A'u*4/10)'E
107 .    \" corrections for vroff
108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110 .    \" for low resolution devices (crt and lpr)
111 .if \n(.H>23 .if \n(.V>19 \
112 \{\
113 .    ds : e
114 .    ds 8 ss
115 .    ds o a
116 .    ds d- d\h'-1'\(ga
117 .    ds D- D\h'-1'\(hy
118 .    ds th \o'bp'
119 .    ds Th \o'LP'
120 .    ds ae ae
121 .    ds Ae AE
122 .\}
123 .rm #[ #] #H #V #F C
124 .\" ========================================================================
125 .\"
126 .IX Title "SERIAL-CONSOLE 1"
127 .TH SERIAL-CONSOLE 1 "2010-09-22" "perl v5.10.1" "User Contributed Perl Documentation"
128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
129 .\" way too many mistakes in technical documents.
130 .if n .ad l
131 .nh
132 .SH "NAME"
133 serial\-console
134 .SH "SYNOPSIS"
135 .IX Header "SYNOPSIS"
136 serial-console [options]
137 .PP
138 Options:
139 .PP
140 .Vb 5
141 \&    \-h,\-\-help         Display brief help message
142 \&    \-v,\-\-verbose      Increase verbosity
143 \&    \-q,\-\-quiet        Decrease verbosity
144 \&    \-l,\-\-log FILE     Log output to file
145 \&    \-r,\-\-rcfile FILE  Modify specified bochsrc file
146 .Ve
147 .SH "DESCRIPTION"
148 .IX Header "DESCRIPTION"
149 \&\f(CW\*(C`serial\-console\*(C'\fR provides a virtual serial console for use with
150 Bochs.  Running \f(CW\*(C`serial\-console\*(C'\fR creates a pseudo-tty.  The master
151 side of this pty is made available to the user for interaction; the
152 slave device is written to the Bochs configuration file
153 (\f(CW\*(C`bochsrc.txt\*(C'\fR) for use by a subsequent Bochs session.
154 .SH "EXAMPLES"
155 .IX Header "EXAMPLES"
156 .ie n .IP """serial\-console""" 4
157 .el .IP "\f(CWserial\-console\fR" 4
158 .IX Item "serial-console"
159 Create a virtual serial console for Bochs, modify \f(CW\*(C`bochsrc.txt\*(C'\fR
160 appropriately.
161 .ie n .IP """serial\-console \-r ../.bochsrc \-l serial.log""" 4
162 .el .IP "\f(CWserial\-console \-r ../.bochsrc \-l serial.log\fR" 4
163 .IX Item "serial-console -r ../.bochsrc -l serial.log"
164 Create a virtual serial console for Bochs, modify \f(CW\*(C`../.bochsrc\*(C'\fR
165 appropriately, log output to \f(CW\*(C`serial.log\*(C'\fR.
166 .SH "INVOCATION"
167 .IX Header "INVOCATION"
168 Before starting Bochs, run \f(CW\*(C`serial\-console\*(C'\fR in a different session
169 (e.g. a different xterm window).  When you subsequently start Bochs,
170 anything that the emulated machine writes to its serial port will
171 appear in the window running \f(CW\*(C`serial\-console\*(C'\fR, and anything typed in
172 the \f(CW\*(C`serial\-console\*(C'\fR window will arrive on the emulated machine's
173 serial port.
174 .PP
175 You do \fBnot\fR need to rerun \f(CW\*(C`serial\-console\*(C'\fR afresh for each Bochs
176 session.
177 .SH "OPTIONS"
178 .IX Header "OPTIONS"
179 .IP "\fB\-l,\-\-log \s-1FILE\s0\fR" 4
180 .IX Item "-l,--log FILE"
181 Log all output (i.e. everything that is printed in the
182 \&\f(CW\*(C`serial\-console\*(C'\fR window) to the specified file.
183 .IP "\fB\-r,\-\-rcfile \s-1FILE\s0\fR" 4
184 .IX Item "-r,--rcfile FILE"
185 Modify the specified bochsrc file.  The file will be updated to
186 contain the path to the slave side of the psuedo tty that we create.
187 The original file will be restored when \f(CW\*(C`serial\-console\*(C'\fR exits.  The
188 default is to modify the file \f(CW\*(C`bochsrc.txt\*(C'\fR in the current directory.
189 .Sp
190 To avoid modifying any bochsrc file, use \f(CW\*(C`\-\-norcfile\*(C'\fR.