serialports.dita@ 98549

Last change on this file since 98549 was 98549, checked in by vboxsync, 2 years ago
Docs: bugref:10302. Uploading .dita user manual files we received from the doc team on 25th Jan.
Property svn:eol-style set to `native`
File size: 8.8 KB

Line
1	<?xml version='1.0' encoding='UTF-8'?>
2	<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
3	<topic xml:lang="en-us" id="serialports">
4	<title>Serial Ports</title>
5
6	<body>
7	<p>
8	Oracle VM VirtualBox supports the use of virtual serial ports in a
9	virtual machine.
10	</p>
11	<p>
12	Ever since the original IBM PC, personal computers have been
13	equipped with one or two serial ports, also called COM ports by
14	DOS and Windows. Serial ports were commonly used with modems, and
15	some computer mice used to be connected to serial ports before USB
16	became commonplace.
17	</p>
18	<p>
19	While serial ports are no longer as common as they used to be,
20	there are still some important uses left for them. For example,
21	serial ports can be used to set up a primitive network over a
22	null-modem cable, in case Ethernet is not available. Also, serial
23	ports are indispensable for system programmers needing to do
24	kernel debugging, since kernel debugging software usually
25	interacts with developers over a serial port. With virtual serial
26	ports, system programmers can do kernel debugging on a virtual
27	machine instead of needing a real computer to connect to.
28	</p>
29	<p>
30	If a virtual serial port is enabled, the guest OS sees a standard
31	16550A compatible UART device. Other UART types can be configured
32	using the <userinput>VBoxManage modifyvm</userinput> command. Both
33	receiving and transmitting data is supported. How this virtual
34	serial port is then connected to the host is configurable, and the
35	details depend on your host OS.
36	</p>
37	<p>
38	You can use either the Settings tabs or the
39	<userinput>VBoxManage</userinput> command to set up virtual serial
40	ports. For the latter, see <xref href="man_VBoxManage-modifyvm.dita#vboxmanage-modifyvm"/>
41	for information on the <codeph>--uart</codeph>,
42	<codeph>--uart-mode</codeph> and <codeph>--uart-type</codeph>
43	options.
44	</p>
45	<p>
46	You can configure up to four virtual serial ports per virtual
47	machine. For each device, you must set the following:
48	</p>
49	<ol>
50	<li>
51	<p><b outputclass="bold">Port Number:</b> This determines
52	the serial port that the virtual machine should see. For best
53	results, use the traditional values as follows:
54	</p>
55	<ul>
56	<li>
57	<p>
58	COM1: I/O base 0x3F8, IRQ 4
59	</p>
60	</li>
61	<li>
62	<p>
63	COM2: I/O base 0x2F8, IRQ 3
64	</p>
65	</li>
66	<li>
67	<p>
68	COM3: I/O base 0x3E8, IRQ 4
69	</p>
70	</li>
71	<li>
72	<p>
73	COM4: I/O base 0x2E8, IRQ 3
74	</p>
75	</li>
76	</ul>
77	<p>
78	You can also configure a user-defined serial port. Enter an
79	I/O base address and interrupt (IRQ).
80	</p>
81	</li>
82	<li>
83	<p><b outputclass="bold">Port Mode:</b> What the virtual
84	port is connected to. For each virtual serial port, you have
85	the following options:
86	</p>
87	<ul>
88	<li>
89	<p><b outputclass="bold">Disconnected:</b> The guest
90	will see the device, but it will behave as if no cable had
91	been connected to it.
92	</p>
93	</li>
94	<li>
95	<p><b outputclass="bold">Host Device:</b> Connects the
96	virtual serial port to a physical serial port on your
97	host. On a Windows host, this will be a name like
98	<codeph>COM1</codeph>. On Linux or Oracle Solaris hosts,
99	it will be a device node like
100	<filepath>/dev/ttyS0</filepath>. Oracle VM VirtualBox will then
101	simply redirect all data received from and sent to the
102	virtual serial port to the physical device.
103	</p>
104	</li>
105	<li>
106	<p><b outputclass="bold">Host Pipe:</b> Configure
107	Oracle VM VirtualBox to connect the virtual serial port to a
108	software pipe on the host. This depends on your host OS,
109	as follows:
110	</p>
111	<ul>
112	<li>
113	<p>
114	On a Windows host, data will be sent and received
115	through a named pipe. The pipe name must be in the
116	format
117	<filepath>\\.\pipe\<varname>name</varname>
118	</filepath>
119	where <varname>name</varname> should identify
120	the virtual machine but may be freely chosen.
121	</p>
122	</li>
123	<li>
124	<p>
125	On a Mac OS, Linux, or Oracle Solaris host, a local
126	domain socket is used instead. The socket filename
127	must be chosen such that the user running
128	Oracle VM VirtualBox has sufficient privileges to create and
129	write to it. The <filepath>/tmp</filepath> directory
130	is often a good candidate.
131	</p>
132	<p>
133	On Linux there are various tools which can connect to
134	a local domain socket or create one in server mode.
135	The most flexible tool is <userinput>socat</userinput> and
136	is available as part of many distributions.
137	</p>
138	</li>
139	</ul>
140	<p>
141	In this case, you can configure whether Oracle VM VirtualBox
142	should create the named pipe, or the local domain socket
143	non-Windows hosts, itself or whether Oracle VM VirtualBox should
144	assume that the pipe or socket exists already. With the
145	<userinput>VBoxManage</userinput> command-line options, this
146	is referred to as server mode or client mode,
147	respectively.
148	</p>
149	<p>
150	For a direct connection between two virtual machines,
151	corresponding to a null-modem cable, simply configure one
152	VM to create a pipe or socket and another to attach to it.
153	</p>
154	</li>
155	<li>
156	<p><b outputclass="bold">Raw File:</b> Send the
157	virtual serial port output to a file. This option is very
158	useful for capturing diagnostic output from a guest. Any
159	file may be used for this purpose, as long as the user
160	running Oracle VM VirtualBox has sufficient privileges to create
161	and write to the file.
162	</p>
163	</li>
164	<li>
165	<p><b outputclass="bold">TCP:</b> Useful for
166	forwarding serial traffic over TCP/IP, acting as a server,
167	or it can act as a TCP client connecting to other servers.
168	This option enables a remote machine to directly connect
169	to the guest's serial port using TCP.
170	</p>
171	<ul>
172	<li>
173	<p><b outputclass="bold">TCP Server:</b> Deselect
174	the <b outputclass="bold">Connect to Existing
175	Pipe/Socket</b> check box and specify the port
176	number in the
177	<b outputclass="bold">Path/Address</b> field.
178	This is typically 23 or 2023. Note that on UNIX-like
179	systems you will have to use a port a number greater
180	than 1024 for regular users.
181	</p>
182	<p>
183	The client can use software such as
184	<userinput>PuTTY</userinput> or the
185	<userinput>telnet</userinput> command line tool to access
186	the TCP Server.
187	</p>
188	</li>
189	<li>
190	<p><b outputclass="bold">TCP Client:</b> To create
191	a virtual null-modem cable over the Internet or LAN,
192	the other side can connect using TCP by specifying
193	<codeph><varname>hostname</varname>:<varname>port</varname></codeph>
194	in the <b outputclass="bold">Path/Address</b>
195	field. The TCP socket will act in client mode if you
196	select the <b outputclass="bold">Connect to Existing
197	Pipe/Socket</b> check box.
198	</p>
199	</li>
200	</ul>
201	</li>
202	</ul>
203	</li>
204	</ol>
205	<p>
206	Up to four serial ports can be configured per virtual machine, but
207	you can pick any port numbers out of the above. However, serial
208	ports cannot reliably share interrupts. If both ports are to be
209	used at the same time, they must use different interrupt levels,
210	for example COM1 and COM2, but not COM1 and COM3.
211	</p>
212	</body>
213
214	</topic>

Note: See TracBrowser for help on using the repository browser.

Download in other formats:

Original Format