serialports.dita@ 105289

Last change on this file since 105289 was 105289, checked in by vboxsync, 6 months ago
Docs: bugref:10705. Merging current changes to dita files from docs team's repo. (r6123, r6120, r6117)
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 8.6 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	<ph conkeyref="vbox-conkeyref-phrases/product-name"/> 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 <userinput>VBoxManage</userinput> command to set
39	up virtual serial ports. For the latter, see <xref href="vboxmanage-modifyvm.dita"/> for
40	information on the <codeph>--uart</codeph>, <codeph>--uart-mode</codeph> and
41	<codeph>--uart-type</codeph> options.
42	</p>
43	<p>
44	You can configure up to four virtual serial ports per virtual
45	machine. For each device, you must set the following:
46	</p>
47	<ol>
48	<li>
49	<p><b outputclass="bold">Port Number:</b> This determines
50	the serial port that the virtual machine should see. For best
51	results, use the traditional values as follows:
52	</p>
53	<ul>
54	<li>
55	<p>
56	COM1: I/O base 0x3F8, IRQ 4
57	</p>
58	</li>
59	<li>
60	<p>
61	COM2: I/O base 0x2F8, IRQ 3
62	</p>
63	</li>
64	<li>
65	<p>
66	COM3: I/O base 0x3E8, IRQ 4
67	</p>
68	</li>
69	<li>
70	<p>
71	COM4: I/O base 0x2E8, IRQ 3
72	</p>
73	</li>
74	</ul>
75	<p>
76	You can also configure a user-defined serial port. Enter an
77	I/O base address and interrupt (IRQ).
78	</p>
79	</li>
80	<li>
81	<p><b outputclass="bold">Port Mode:</b> What the virtual
82	port is connected to. For each virtual serial port, you have
83	the following options:
84	</p>
85	<ul>
86	<li>
87	<p><b outputclass="bold">Disconnected:</b> The guest
88	will see the device, but it will behave as if no cable had
89	been connected to it.
90	</p>
91	</li>
92	<li>
93	<p><b outputclass="bold">Host Device:</b> Connects the
94	virtual serial port to a physical serial port on your
95	host. On a Windows host, this will be a name like
96	<codeph>COM1</codeph>. On Linux or Oracle Solaris hosts,
97	it will be a device node like
98	<filepath>/dev/ttyS0</filepath>. <ph conkeyref="vbox-conkeyref-phrases/product-name"/> will then
99	simply redirect all data received from and sent to the
100	virtual serial port to the physical device.
101	</p>
102	</li>
103	<li>
104	<p><b outputclass="bold">Host Pipe:</b> Configure
105	<ph conkeyref="vbox-conkeyref-phrases/product-name"/> to connect the virtual serial port to a
106	software pipe on the host. This depends on your host OS,
107	as follows:
108	</p>
109	<ul>
110	<li>
111	<p>On a Windows host, data will be sent and received through a named pipe. The pipe name must be in the
112	format <filepath>\\.\pipe\<varname>name</varname>
113	</filepath> where <varname>name</varname> should identify the virtual machine but may be freely
114	chosen. </p>
115	</li>
116	<li>
117	<p>On a Mac OS, Linux, or Oracle Solaris host, a local domain socket is used instead. The socket
118	filename must be chosen such that the user running <ph conkeyref="vbox-conkeyref-phrases/product-name"
119	/> has sufficient privileges to create and write to it. The <filepath>/tmp</filepath> directory is
120	often a good candidate. </p>
121	<p>On Linux there are various tools which can connect to a local domain socket or create one in server
122	mode. The most flexible tool is <userinput>socat</userinput> and is available as part of many
123	distributions. </p>
124	</li>
125	</ul>
126	<p>In this case, you can configure whether <ph conkeyref="vbox-conkeyref-phrases/product-name"/> should
127	create the named pipe, or the local domain socket on non-Windows hosts, itself or whether <ph
128	conkeyref="vbox-conkeyref-phrases/product-name"/> should assume that the pipe or socket exists already.
129	With the <userinput>VBoxManage</userinput> command-line options, this is referred to as server mode or
130	client mode, respectively. </p>
131	<p>For a direct connection between two virtual machines, corresponding to a null-modem cable, simply
132	configure one VM to create a pipe or socket and another to attach to it. </p>
133	</li>
134	<li>
135	<p><b outputclass="bold">Raw File:</b> Send the
136	virtual serial port output to a file. This option is very
137	useful for capturing diagnostic output from a guest. Any
138	file may be used for this purpose, as long as the user
139	running <ph conkeyref="vbox-conkeyref-phrases/product-name"/> has sufficient privileges to create
140	and write to the file.
141	</p>
142	</li>
143	<li>
144	<p><b outputclass="bold">TCP:</b> Useful for
145	forwarding serial traffic over TCP/IP, acting as a server,
146	or it can act as a TCP client connecting to other servers.
147	This option enables a remote machine to directly connect
148	to the guest's serial port using TCP.
149	</p>
150	<ul>
151	<li>
152	<p><b outputclass="bold">TCP Server:</b> Deselect
153	the <b outputclass="bold">Connect to Existing
154	Pipe/Socket</b> check box and specify the port
155	number in the
156	<b outputclass="bold">Path/Address</b> field.
157	This is typically 23 or 2023. Note that on UNIX-like
158	systems you will have to use a port a number greater
159	than 1024 for regular users.
160	</p>
161	<p>The client can use software such as <userinput>PuTTY</userinput> or the <userinput>telnet</userinput>
162	command line tool to access the TCP Server. </p>
163	</li>
164	<li>
165	<p><b outputclass="bold">TCP Client:</b> To create
166	a virtual null-modem cable over the Internet or LAN,
167	the other side can connect using TCP by specifying
168	<codeph><varname>hostname</varname>:<varname>port</varname></codeph>
169	in the <b outputclass="bold">Path/Address</b>
170	field. The TCP socket will act in client mode if you
171	select the <b outputclass="bold">Connect to Existing
172	Pipe/Socket</b> check box.
173	</p>
174	</li>
175	</ul>
176	</li>
177	</ul>
178	</li>
179	</ol>
180	<p>Up to four serial ports can be configured per virtual machine, but you can pick any port numbers out of the
181	above. However, serial ports cannot reliably share interrupts. If both ports are to be used at the same time, they
182	must use different interrupt levels, for example COM1 and COM2, but not COM1 and COM3. </p>
183	</body>
184
185	</topic>

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

Download in other formats:

Original Format