VMware

VMware Workstation 4

Features | Documentation | Knowledge Base | Discussion Forums

previous Prev   Contents   Last   Next next

Keyboard Mapping on a Linux Host

Keyboard Mapping on a Linux Host

This section addresses the following issues and provides additional details on keyboard mapping in Linux:

  • My (language-specific) keyboard is not supported by VMware Workstation.
  • Some of the keys on my keyboard don't work right in the virtual machine.
  • My keyboard works fine when I run a virtual machine locally, but not when I run the same virtual machine with a remote X server.

This section contains the following:

Quick Answers

Quick Answers

If your keyboard works correctly with a local X server, and you just want the same behavior with a remote X server (which is also an XFree86 server running on a PC), just power off the virtual machine and close the VMware Workstation window, then add the line

xkeymap.usekeycodeMapIfXFree86 = true

to the virtual machine configuration file or to ~/.vmware/config. Make this change on the host machine, where you run the virtual machine, not on the machine with the remote X server.

If you are using an XFree86-based server that VMware Workstation does not recognize as an XFree86 server, use this instead:

xkeymap.usekeycodeMap = true

If you are using an XFree86 server running locally, and the keyboard does not work correctly, please report the problem to the VMware technical support department.

The Longer Story

The Longer Story

Unfortunately, keyboard support for the PC (virtual or otherwise) is a complex affair. To do it justice, we have to start with some background information - greatly simplified.

Pressing a key on the PC keyboard generates a scan code based roughly on the position of the key. For example, the Z key on a German keyboard generates the same code as the Y key on an English keyboard, because they are in the same position on the keyboard. Most keys have one-byte scan codes, but some keys have two-byte scan codes with prefix 0xe0.

Internally, VMware Workstation uses a simplified version of the PC scan code that is a single nine-bit numeric value, called a v-scan code. A v-scan code is written as a three-digit hexadecimal number. The first digit is 0 or 1. For example, the left-hand Ctrl key has a one-byte scan code (0x1d); its v-scan code is 0x01d. The right-hand Ctrl key scan code is two bytes (0xe0, 0x1d); its v-scan code is 0x11d.

An X server uses a two-level encoding of keys. An X key code is a one-byte value. The assignment of key codes to keys depends on the X server implementation and the physical keyboard. As a result, an X application normally cannot use key codes directly. Instead, the key codes are mapped into keysyms that have names like space, escape, x and 2. The mapping can be controlled by an X application via the function XChangeKeyboardMapping() or by the program xmodmap. To explore keyboard mappings, you can use xev, which shows the key codes and keysyms for keys typed into its window.

To recap, a key code corresponds roughly to a physical key, while a keysym corresponds to the symbol on the key top. For example, with an XFree86 server running on a PC, the Z key on the German keyboard has the same key code as the Y key on an English keyboard. The German Z keysym, however, is the same as the English Z keysym, and different from the English Y keysym.

For an XFree86 server on a PC, there is a one-to-one mapping from X key codes to PC scan codes (or v-scan codes, which is what VMware Workstation really uses). VMware Workstation takes advantage of this fact. When it is using an XFree86 server on the local host, it uses the built-in mapping from X key codes to v-scan codes. This mapping is keyboard independent and should be correct for most, if not all, languages. In other cases (not an XFree86 server or not a local server), VMware Workstation must map keysyms to v-scan codes, using a set of keyboard-specific tables.

Key code mapping is simple, automatic and foolproof. (Keysym mapping is more complex and described later.) However, because the program cannot tell whether a remote server is running on a PC or on some other kind of computer, it errs on the safe side and uses key code mapping only with local X servers. This is often too conservative and has undesirable effects. Luckily, this and other behavior related to key code-mapping can be controlled by powering off the virtual machine and closing the VMware Workstation window, then using a text editor to add configuration settings to the virtual machine's configuration file.

  • xkeymap.usekeycodeMapIfXFree86 = true
    Use key code mapping if you are using an XFree86 server, even if it is remote.
  • xkeymap.usekeycodeMap = true
    Always use key code mapping regardless of server type.
  • xkeymap.nokeycodeMap = true
    Never use key code mapping.
  • xkeymap.keycode.<code> = <v-scan code>
    If using key code mapping, map key code <code> to <v-scan code>. In this example, <code> must be a decimal number and <v-scan code> should be a C-syntax hexadecimal number (for example, 0x001).

The easiest way to find the X key code for a key is to run xev or xmodmap -pk. Most of the v-scan codes are covered in V-Scan Code Table. The keysym mapping tables described in this section are also helpful.

Use this feature to make small modifications to the mapping. For example, to swap left Ctrl and Caps Lock, use the following lines:

xkeymap.keycode.64 = 0x01d # X Caps_Lock -> VM left ctrl
xkeymap.keycode.37 = 0x03a # X Control_L -> VM caps lock

These configuration lines can be added to the individual virtual machine configuration, to your personal VMware Workstation configuration (~/.vmware/config), or even to the host-wide (/etc/vmware/config) or installation-wide (usually /usr/local/lib/vmware/config) configuration.

When key code mapping cannot be used (or is disabled), VMware Workstation maps keysyms to v-scan codes. It does this using one of the tables in the xkeymap directory in the VMware Workstation installation (usually /usr/local/lib/vmware).

Which table you should use depends on the keyboard layout. The normal distribution includes tables for PC keyboards for the United States and a number of European countries and languages. And for most of these, there are both the 101-key (or 102-key) and the 104-key (or 105-key) variants.

VMware Workstation automatically determines which table to use by examining the current X keymap. However, its decision-making process may sometimes fail. In addition, each mapping is fixed and may not be completely right for any given keyboard and X key code-to-keysym mapping. For example, a user may have swapped Ctrl and Caps Lock using xmodmap. This means the keys are swapped in the virtual machine when using a remote server (keysym mapping) but unswapped when using a local server (key code mapping).

Therefore, keysym mapping is necessarily imperfect. To make up for this defect, you can change most of the behavior using configuration settings:

  • xkeymap.language = <keyboard-type>
    Use this if VMware Workstation has a table in xkeymap for your keyboard but can't detect it. <keyboard-type> must be one of the tables in the xkeymap directory. (See above for location.) However, the failure to detect the keyboard probably means the table isn't completely correct for you.
  • xkeymap.keysym.<sym> = <v-scan code>
    If you use keysym mapping, map keysym <sym> to <v-scan code>. When you do, <sym> must be an X keysym name and <v-scan code> should be a C-syntax hexadecimal number (for example, 0x001).

    The easiest way to find the keysym name for a key is to run xev or
    xmodmap -pk.

    The X header file /usr/X11R6/include/X11/keysymdef.h has a complete list of keysyms. (The name of a keysym is the same as its C constant without the XK_ prefix.) Most v-scan codes are in V-Scan Code Table.

    The xkeymap tables themselves are also helpful. Use them to fix small errors in an existing mapping.

  • xkeymap.fileName = <file-path>
    Use the keysym mapping table in <file-path>. A table is a sequence of configuration lines of the form
    <sym> = <v-scan code>
    where <sym> is an X keysym name, and <v-scan code> is a C-syntax hexadecimal number (for example, 0x001). (See the explanation of xkeymap.keysym above for tips on finding the keysyms and v-scan codes for your keyboard.)

    Compiling a complete keysym mapping is difficult. It is best to start with an existing table and make small changes.

V-Scan Code Table

V-Scan Code Table

These are the v-scan codes for the 104-key U.S. keyboard:

 Symbol
  Shifted symbol
  Location
  V-scan code
 Esc
 
 
 0x001
 1
 !
 
 0x002
 2
 @
 
 0x003
 3
 #
 
 0x004
 4
 $
 
 0x005
 5
 %
 
 0x006
 6
 ^
 
 0x007
 7
 &
 
 0x008
 8
 *
 
 0x009
 9
 (
 
 0x00a
 0
 )
 
 0x00b
 -
 _
 
 0x00c
 =
 +
 
 0x00d
 Backspace
 
 
 0x00e
 Tab
 
 
 0x00f
 Q
 
 
 0x010
 W
 
 
 0x011
 E
 
 
 0x012
 R
 
 
 0x013
 T
 
 
 0x014
 Y
 
 
 0x015
 U
 
 
 0x016
 I
 
 
 0x017
 O
 
 
 0x018
 P
 
 
 0x019
 [
 {
 
 0x01a
 ]
 }
 
 0x01b
 Enter
 
 
 0x01c
 Ctrl
 
 left
 0x01d
 A
 
 
 0x01e
 S
 
 
 0x01f
 D
 
 
 0x020
 F
 
 
 0x021
 G
 
 
 0x022
 H
 
 
 0x023
 J
 
 
 0x024
 K
 
 
 0x025
 L
 
 
 0x026
 ;
 
 
 0x027
 '
 
 
 0x028
 `
 
 
 0x029
 Shift
 
 left
 0x02a
 \
 |
 
 0x02b
 Z
 
 
 0x02c
 X
 
 
 0x02d
 C
 
 
 0x02e
 V
 
 
 0x02f
 B
 
 
 0x030
 N
 
 
 0x031
 M
 
 
 0x032
 ,
 <
 
 0x033
 .
 >
 
 0x034
 /
 ?
 
 0x035
 Shift
 
 right
 0x036
 *
 
 numeric pad
 0x037
 Alt
 
 left
 0x038
 Space bar
 
 
 0x039
 Caps Lock
 
 
 0x03a
 F1
 
 
 0x03b
 F2
 
 
 0x03c
 F3
 
 
 0x03d
 F4
 
 
 0x03e
 F5
 
 
 0x03f
 F6
 
 
 0x040
 F7
 
 
 0x041
 F8
 
 
 0x042
 F9
 
 
 0x043
 F10
 
 
 0x044
 Num Lock
 
 numeric pad
 0x045
 Scroll Lock
 
 
 0x046
 Home
 7
 numeric pad
 0x047
 Up arrow
 8
 numeric pad
 0x048
 PgUp
 9
 numeric pad
 0x049
 -
 
 numeric pad
 0x04a
 Left arrow
 4
 numeric pad
 0x04b
 5
 
 numeric pad
 0x04c
 Right arrow
 6
 numeric pad
 0x04d
 +
 
 numeric pad
 0x04e
 End
 1
 numeric pad
 0x04f
 Down arrow
 2
 numeric pad
 0x050
 PgDn
 3
 numeric pad
 0x051
 Ins
 0
 numeric pad
 0x052
 Del
 
 numeric pad
 0x053
 F11
 
 
 0x057
 F12
 
 
 0x058
 Break
 Pause
 
 0x100
 Enter
 
 numeric pad
 0x11c
 Ctrl
 
 right
 0x11d
 /
 
 numeric pad
 0x135
 SysRq
 Print Scrn
 
 0x137
 Alt
 
 right
 0x138
 Home
 
 function pad
 0x147
 Up arrow
 
 function pad
 0x148
 Page Up
 
 function pad
 0x149
 Left arrow
 
 function pad
 0x14b
 Right arrow
 
 function pad
 0x14d
 End
 
 function pad
 0x14f
 Down arrow
 
 function pad
 0x150
 Page Down
 
 function pad
 0x151
 Insert
 
 function pad
 0x152
 Delete
 
 function pad
 0x153
 Windows
 
 left
 0x15b
 Windows
 
 right
 0x15c
 Menu
 
 
 0x15d

The 84-key keyboard has a Sys Req key on the numeric pad:

 Symbol
 Shifted symbol
 Location
 V-scan code
 Sys Req
 
 numeric pad
 0x054

Keyboards outside the U.S. usually have an extra key (often < > or < > | ) next to the left shift key:

 Symbol
 Shifted symbol
 Location
 V-scan code
 <
 >
 
 0x056

previous Prev   Contents   Last   Next next