VirtualBox

source: vbox/trunk/doc/manual/en_US/dita/topics/serialports.dita

Last change on this file was 107390, checked in by vboxsync, 5 weeks ago

Docs: bugref:10705. bugref: 10829. The docs build has been modified to split generated refentry dita files and the user manual files and the following commits from doc's team git repo has been applied:

0946136c74dda0483704db891345cb39548b4e28 Started consolidating known issues and troubleshooting information
845b847e6a8e778b38a57867e25ee5e086a73800 Added individual topics for list of known issues, integrated into Troubleshooting section.
bb574836aac775889bd61e4a72f489617fcb7d18 Removed EFI firmware from experimental features for 7.2
6d2e68b244869991e713d170ecd239739d99ba56 Moved known issues into Known Issues section
e2630c896561587718b5c3197c384a38d07014d5 Merge branch 'VBP-1461_experimental-features' into 'main'
0512e2cce51f49ccdc56f3381a2a0c924f2bd278 Feedback on known issues
a77d6c980f6ff5cad9d32b2fb9290990093a03fa Restructured host and guest OS topics
988af5cc9628f5de0806531bc98686f691a911fd Updates with feedbback from Jacob
982a61c9f25b22b745ec483e763e3d88efe59c40 Included feedback from Jacob
93181c8c6cc2d9a26bcccb1145cb0423c0d9f4c9 Updated known issues with feedback from Klaus
8bc369561c383f09b409fe5e44f507440b3735fb Created Legacy Guest OS section
d7932f55accdab7a03666302d58b8c941cd48be2 Moved known issues to more appropriate places for the info
2a4aa094ba8a7ac6894d2a777316eabf41746580 Further moving of known issues
baeabd5308c5519a4dc26b4197be9b00e419a85a Updated links to cli_topics

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette