serialports.dita@ 105482

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

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

Download in other formats:

Original Format