VMware

VMware Workstation 4

Features | Documentation | Knowledge Base | Discussion Forums

previous Prev   Contents   Last   Next next

Using Serial Ports

Using Serial Ports

The following sections describe how to use serial ports with VMware Workstation:

A VMware Workstation virtual machine can use up to four virtual serial ports. The virtual serial ports can be configured in several ways.

  • You can connect a virtual serial port to a physical serial port on the host computer.
  • You can connect a virtual serial port to a file on the host computer.
  • You can make a direct connection between two virtual machines or between a virtual machine and an application running on the host computer.

You can also select whether to connect the virtual serial port when you power on the virtual machine.

Using a Serial Port on the Host Computer

Using a Serial Port on the Host Computer

You can set up the virtual serial port in a virtual machine to use a physical serial port on the host computer. This is useful, for example, if you want to use an external modem or a hand-held device in your virtual machine.

To install a virtual serial port that connects to a physical serial port on the host computer, take the following steps:

  1. Open the Virtual Machine Control Panel (Edit > Virtual Machine Settings).
  2. Click Add to start the Add Hardware Wizard.
  3. Select Serial Port, then click Next.

  4. Select Use physical serial port on the host, then click Next.

  5. Choose the port on the host computer that you want to use for this serial connection. By default, the device status setting is Connect at power on. You may deselect this setting if you wish.

    Click Advanced if you want to configure this serial port to use polled mode. This option is of interest primarily to developers who are using debugging tools that communicate over a serial connection. For more information, see Special Configuration Options for Advanced Users.

  6. Click Finish, then click OK to close the Virtual Machine Control Panel.
  7. Power on the virtual machine.
Using a File on the Host Computer

Using a File on the Host Computer

You can set up the virtual serial port in a virtual machine to send its output to a file on the host computer. This is useful, for example, if you want to capture the data a program running in the virtual machine sends to the virtual serial port or if you need a quick way to transfer a file from the guest to the host.

To install a virtual serial port that connects to a file on the host computer, take the following steps:

  1. Open the Virtual Machine Control Panel (Edit > Virtual Machine Settings).
  2. Click Add to start the Add Hardware Wizard.
  3. Select Serial Port, then click Next.

  4. Select Output to file, then click Next.

  5. Browse to the file on the host computer that you want to use to store the output of the virtual serial port. By default, the device status setting is Connect at power on. You may deselect this setting if you wish.

    Click Advanced if you want to configure this serial port to use polled mode. This option is of interest primarily to developers who are using debugging tools that communicate over a serial connection. For more information, see Special Configuration Options for Advanced Users.

  6. Click Finish, then click OK to close the Virtual Machine Control Panel.
  7. Power on the virtual machine.
Connecting an Application on the Host to a Virtual Machine

Connecting an Application on the Host to a Virtual Machine

You can set up the virtual serial port in a virtual machine to connect to an application on the host computer. This is useful, for example, if you want to use an application on the host to capture debugging information sent from the virtual machine's serial port.

To install a direct serial connection between an application on the host and a virtual machine, take the following steps:

Windows Host

Windows Host

  1. Open the Virtual Machine Control Panel (Edit > Virtual Machine Settings).
  2. Click Add to start the Add Hardware Wizard.
  3. Select Serial Port, then click Next.

  4. Select Output to named pipe, then click Next.

  5. Use the default pipe name, or enter another pipe name of your choice. The pipe name must follow the form \\.\pipe\<namedpipe> - that is, it must begin with \\.\pipe\.
  6. Select This end is the server or This end is the client. In general, select This end is the server if you plan to start this end of the connection first.
  7. Select The other end is an application.
  8. By default, the device status setting is Connect at power on. You may deselect this setting if you wish.

    Click Advanced if you want to configure this serial port to use polled mode. This option is of interest primarily to developers who are using debugging tools that communicate over a serial connection. For more information, see Special Configuration Options for Advanced Users.

  9. Click Finish, then click OK to close the Virtual Machine Control Panel.
  10. On your host computer, configure the application that communicates with the virtual machine to use the same pipe name.
  11. Power on the virtual machine.
Linux Host

Linux Host

  1. Open the Virtual Machine Control Panel (Edit > Virtual Machine Settings).
  2. Click Add to start the Add Hardware Wizard.
  3. Select Serial Port, then click Next.
  4. Select Output to named pipe, then click Next.
  5. In the Path field, enter /tmp/<socket> or another Unix socket name of your choice.
  6. Select This end is the server or This end is the client. In general, select This end is the server if you plan to start this end of the connection first.
  7. Select The other end is an application.
  8. By default, the device status setting is Connect at power on. You may deselect this setting if you wish.

    Click Advanced if you want to configure this serial port to use polled mode. This option is of interest primarily to developers who are using debugging tools that communicate over a serial connection. For more information, see Special Configuration Options for Advanced Users.

  9. Click Finish.
  10. Click OK to save your configuration and close the Virtual Machine Control Panel.
  11. On your host computer, configure the application that communicates with the virtual machine to use the same Unix socket name.
  12. Power on the virtual machine.
Connecting Two Virtual Machines

Connecting Two Virtual Machines

You can set up the virtual serial ports in two virtual machines to connect to each other. This is useful, for example, if you want to use an application in one virtual machine to capture debugging information sent from the other virtual machine's serial port.

To install a direct serial connection between two virtual machines (a server and a client), take the following steps:

Windows Host

Windows Host

In the server virtual machine

In the server virtual machine

  1. Open the Virtual Machine Control Panel (Edit > Virtual Machine Settings).
  2. Click Add to start the Add Hardware Wizard.
  3. Select Serial Port, then click Next.

  4. Select Output to named pipe, then click Next.

  5. Use the default pipe name, or enter another pipe name of your choice. The pipe name must follow the form \\.\pipe\<namedpipe> - that is, it must begin with \\.\pipe\.
  6. Select This end is the server.
  7. Select The other end is a virtual machine.
  8. By default, the device status setting is Connect at power on. You may deselect this setting if you wish.

    Click Advanced if you want to configure this serial port to use polled mode. This option is of interest primarily to developers who are using debugging tools that communicate over a serial connection. For more information, see Special Configuration Options for Advanced Users.

  9. Click Finish, then click OK to close the Virtual Machine Control Panel.
In the client virtual machine

In the client virtual machine

  1. Open the Virtual Machine Control Panel (Edit > Virtual Machine Settings).
  2. Click Add to start the Add Hardware Wizard.
  3. Select Serial Port, then click Next.

  4. Select Use named pipe.
  5. Use the default name, or enter another pipe name of your choice. The pipe name must follow the form \\.\pipe\<namedpipe> - that is, it must begin with \\.\pipe\. The pipe name must be the same on both server and client.
  6. Select This end is the client.
  7. Select The other end is a virtual machine.
  8. By default, the device status setting is Connect at power on. You may deselect this setting if you wish.

    Click Advanced if you want to configure this serial port to use polled mode. This option is of interest primarily to developers who are using debugging tools that communicate over a serial connection. For more information, see Special Configuration Options for Advanced Users.

  9. Click Finish, then click OK to close the Virtual Machine Control Panel.
Linux Host

Linux Host

In the server virtual machine

In the server virtual machine

  1. Open the Virtual Machine Control Panel (Edit > Virtual Machine Settings).
  2. Click Add to start the Add Hardware Wizard.
  3. Select Serial Port, then click Next.
  4. Select Output to named pipe, then click Next.
  5. In the Path field, enter /tmp/<socket> or another Unix socket name of your choice.
  6. Select This end is the server.
  7. Select The other end is a virtual machine.
  8. By default, the device status setting is Connect at power on. You may deselect this setting if you wish.

    Click Advanced if you want to configure this serial port to use polled mode. This option is of interest primarily to developers who are using debugging tools that communicate over a serial connection. For more information, see Special Configuration Options for Advanced Users.

  9. Click Finish, then click OK to save your configuration and close the Virtual Machine Control Panel.
In the client virtual machine

In the client virtual machine

  1. Open the Virtual Machine Control Panel (Edit > Virtual Machine Settings).
  2. Click Add to start the Add Hardware Wizard.
  3. Select Serial Port, then click Next.
  4. Select Output to named pipe, then click Next.
  5. In the Path field, enter /tmp/<socket> or another Unix socket name of your choice. The pipe name must be the same on both server and client.
  6. Select This end is the client.
  7. Select The other end is a virtual machine.
  8. By default, the device status setting is Connect at power on. You may deselect this setting if you wish.

    Click Advanced if you want to configure this serial port to use polled mode. This option is of interest primarily to developers who are using debugging tools that communicate over a serial connection. For more information, see Special Configuration Options for Advanced Users.

  9. Click Finish, then click OK to save your configuration and close the Virtual Machine Control Panel.
Special Configuration Options for Advanced Users

Special Configuration Options for Advanced Users

Two special configuration options are available for serial connections between a virtual machine and the host or between two virtual machines. These options are of interest primarily to developers who are using debugging tools that communicate over a serial connection.

Improving CPU Performance when Debugging

Improving CPU Performance when Debugging

The first option must be set in the Virtual Machine Control Panel. This option is useful when the serial port is being used by the guest operating system in polled mode as opposed to interrupt mode. Polled mode causes the virtual machine to consume a disproportionate share of CPU time. This makes the host and other guests run sluggishly.

To restore performance for applications on the host, in the Virtual Machine Control Panel, select the virtual serial port, and check the Yield CPU on poll check box. This configuration option forces the affected virtual machine to yield processor time if the only task it is trying to do is poll the virtual serial port.

Changing the Input Speed of the Serial Connection

Changing the Input Speed of the Serial Connection

To use the second option, power off the virtual machine and close the VMware Workstation window, then use a text editor to add the following line to your virtual machine's configuration file:

serial<n>.pipe.charTimePercent = <x>

This option is useful if you want to squeeze every possible bit of speed from your serial connection over a pipe to the virtual machine. In principle, there is no limit on the output speed - the speed at which the virtual machine sends data through the virtual serial port. In practice, the output speed depends on how fast the application at the other end of the pipe reads data inbound to it.

<n> is the number of the serial port, starting from 0. So the first serial port is serial0.

<x> is any positive integer. It specifies the time taken to transmit a character, expressed as a percentage of the default speed set for the serial port in the guest operating system. For example, a setting of 200 forces the port to take twice as long per character, or send data at half the default speed. A setting of 50 forces the port to take only half as long per character, or send data at twice the default speed.

You should first use the guest operating system to configure the serial port for the highest setting supported by the application you are running in the virtual machine.

Once the serial port speed is set appropriately in the guest operating system, experiment with this setting. Start with a value of 100 and gradually decrease it until you find the highest speed at which your connection works reliably.

Examples: Debugging over a Virtual Serial Port

Examples: Debugging over a Virtual Serial Port

You can use Debugging Tools for Windows (WinDbg) or Kernel Debugger (KD) to debug kernel code in a virtual machine over a virtual serial port. You can download Debugging Tools for Windows from the Windows DDK Web site at www.microsoft.com/whdc/ddk/debugging/default.mspx.

The following two examples illustrate how to use a virtual serial port to debug kernel code in a virtual machine:

  • With the debugging application on the VMware Workstation host (Windows hosts only)
  • With the debugging application in another virtual machine on the same VMware Workstation host (useful on a Linux host and can also be done on a Windows host)

Using either of these methods lets you debug kernel code on one system, without the need for two physical computers, a modem or serial cable.

Debugging an Application in a Virtual Machine from the Windows Host

Debugging an Application in a Virtual Machine from the Windows Host

In this example, you have kernel code to debug in a virtual machine (called the target virtual machine) and are running WinDbg or KD on your Windows host.

To prepare the target virtual machine, follow the steps for a Windows host in Connecting an Application on the Host to a Virtual Machine. Make sure you configure the virtual machine's virtual serial port as follows:

  • Select This end is the server
  • Under I/O Mode, select the Yield CPU on poll check box, as the kernel in the target virtual machine uses the virtual serial port in polled mode, not interrupt mode

To prepare the host, make sure you have downloaded the correct version of Debugging Tools for Windows. You need version 4.0.18.0, dated December 21, 2001, as it supports debugging over a pipe.

Note: Pipe support is not documented in the WinDbg and KD in-product help or on Microsoft's Web site.

When you are ready to begin, complete the following steps:

  1. Power on the virtual machine.
  2. Check to make sure the serial port is connected. Choose choose Edit > Removable Devices. On that menu, serial<n> should be reported as \\.\pipe\<namedpipe> (on Windows hosts) or /tmp/<socket> (on Linux hosts). If the serial port is not connected, choose the virtual serial port, then Connect.
  3. On the host, open a Command Prompt window and do one of the following:
    • If you are using WinDbg, type the following:
windbg -k com:port=\\.\pipe\<namedpipe>,pipe
    • If you are using KD, type the following:
kd -k com:port=\\.\pipe\<namedpipe>,pipe

Then press Enter to start debugging.

Debugging an Application in a Virtual Machine from another Virtual Machine

Debugging an Application in a Virtual Machine from another Virtual Machine

In this situation, you have kernel code to debug in a virtual machine (called the target virtual machine) and are running Debugging Tools for Windows (WinDbg) or Kernel Debugger (KD) in another virtual machine (called the debugger virtual machine) on the same host.

This is useful if you are running VMware Workstation on a Linux host. The debugger virtual machine must be running Debugging Tools for Windows (WinDbg) or Kernel Debugger (KD) in a Windows guest operating system.

To prepare the target virtual machine, follow the steps for the server virtual machine for the appropriate host in Connecting Two Virtual Machines. Make sure when you configure the target virtual machine's virtual serial port that you select the Yield CPU on poll check box, as the kernel in the target virtual machine uses the virtual serial port in polled mode, not interrupt mode.

To prepare the debugger virtual machine, make sure you have downloaded Debugging Tools for Windows. Then follow the steps for the client virtual machine in Connecting Two Virtual Machines.

When you are ready to begin, complete the following steps:

  1. Power on both virtual machines.
  2. Check to make sure the serial port is connected. Choose choose Edit > Removable Devices. If the serial port is not connected, choose the virtual serial port, then Connect.
  3. In the debugger virtual machine, start debugging with WinDbg or KD normally.

previous Prev   Contents   Last   Next next