3.10. Serial ports

Oracle VM VirtualBox

previous page next page

3.10. Serial ports

VirtualBox fully supports virtual serial ports in a virtual machine in an easy-to-use manner.[16]

Ever since the original IBM PC, personal computers have been equipped with one or two serial ports (also called COM ports by DOS and Windows). Serial ports were commonly used with modems, and some computer mice used to be connected to serial ports before USB became commonplace.

While serial ports are no longer as ubiquitous as they used to be, there are still some important uses left for them. For example, serial ports can be used to set up a primitive network over a null-modem cable, in case Ethernet is not available. Also, serial ports are indispensable for system programmers needing to do kernel debugging, since kernel debugging software usually interacts with developers over a serial port. With virtual serial ports, system programmers can do kernel debugging on a virtual machine instead of needing a real computer to connect to.

If a virtual serial port is enabled, the guest operating system sees a standard 16550A compatible UART device. Both receiving and transmitting data is supported. How this virtual serial port is then connected to the host is configurable, and the details depend on your host operating system.

You can use either the graphical user interface or the command-line VBoxManage tool to set up virtual serial ports. For the latter, please refer to Section 8.8, “VBoxManage modifyvm”; in that section, look for the --uart and --uartmode options.

In either case, you can configure up to four virtual serial ports per virtual machine. For each such device, you will need to determine

  1. what kind of serial port the virtual machine should see by selecting an I/O base address and interrupt (IRQ). For these, we recommend to use the traditional values[17], which are:

    1. COM1: I/O base 0x3F8, IRQ 4

    2. COM2: I/O base 0x2F8, IRQ 3

    3. COM3: I/O base 0x3E8, IRQ 4

    4. COM4: I/O base 0x2E8, IRQ 3

  2. Then, you will need to determine what this virtual port should be connected to. For each virtual serial port, you have the following options:

    • You can elect to have the virtual serial port "disconnected", which means that the guest will see the device, but it will behave as if no cable had been connected to it.

    • You can connect the virtual serial port to a physical serial port on your host. (On a Windows host, this will be a name like COM1; on Linux or Solaris hosts, it will be a device node like /dev/ttyS0). VirtualBox will then simply redirect all data received from and sent to the virtual serial port to the physical device.

    • You can tell VirtualBox to connect the virtual serial port to a software pipe on the host. This depends on your host operating system:

      • On a Windows host, data will be sent and received through a named pipe. The pipe name must be in the format \\.\pipe\<name> where <name> should identify the virtual machine but may be freely chosen.

      • On a Mac, Linux or Solaris host, a local domain socket is used instead. The socket filename must be chosen such that the user running VirtualBox has sufficient privileges to create and write to it. The /tmp directory is often a good candidate.

        On Linux there are various tools which can connect to a local domain socket or create one in server mode. The most flexible tool is socat and is available as part of many distributions.

      In this case, you can configure whether VirtualBox should create the named pipe (or, on non-Windows hosts, the local domain socket) itself or whether VirtualBox should assume that the pipe (or socket) exists already. With the VBoxManage command-line options, this is referred to as "server" or "client" mode, respectively.

      For a direct connection between two virtual machines (corresponding to a null-modem cable), simply configure one VM to create a pipe/socket and another to attach to it.

    • You can send the virtual serial port output to a file. This option is very useful for capturing diagnostic output from a guest. Any file may be used for this purpose, as long as the user running VirtualBox has sufficient privileges to create and write to the file.

    • TCP Socket: Useful for forwarding serial traffic over TCP/IP, acting as a server, or it can act as a TCP client connecting to other servers. It allows a remote machine to directly connect to the guest's serial port via TCP.

      • TCP Server: Uncheck the Connect to existing pipe/socket checkbox and specify the port number. Typically 23 or 2023. Note that on UNIX-like systems you will have to use a port a number greater than 1024 for regular users.

        The client can use software such as PuTTY or the telnet command line tool to access the TCP Server.

      • TCP Client: To create a virtual null-modem cable over the Internet or LAN, the other side can connect via TCP by specifying hostname:port. The TCP socket will act in client mode if check the Connect to existing pipe/socket checkbox.

Up to four serial ports can be configured per virtual machine, but you can pick any port numbers out of the above. However, serial ports cannot reliably share interrupts; if both ports are to be used at the same time, they must use different interrupt levels, for example COM1 and COM2, but not COM1 and COM3.

[16] Serial port support was added with VirtualBox 1.5.

[17] See, for example, http://en.wikipedia.org/wiki/COM_(hardware_interface).

previous page start next page