Workstation User’s Manual : Connecting Devices : Configuring Keyboard Features : Keyboard Mapping on a Linux Host

Keyboard Mapping on a Linux Host
Several situations might require you to set properties in a virtual machine’s configuration file (.vmx file) to change the way a key is mapped.
Configure Keyboard Mapping for a Remote X Server
Sometimes the keyboard works correctly with a local X server but not when you run the same virtual machine with a remote X server. You need to set additional properties in the configuration (.vmx) file.
Before you begin, verify that the remote X server is an XFree86 server running on a PC.
If the keyboard does not work correctly on an XFree86 server running locally, report the problem to VMware technical support.
For local X servers, Workstation maps X key codes to PC scan codes to correctly identify a key. Workstation uses this key code map only for local X servers because it cannot tell whether a remote X server is running on a PC or on some other kind of computer. In this case, you can set a property to tell Workstation to use key code mapping. For a description of key code mapping, see X Key Codes Compared to Keysyms.
To configure keyboard mapping for a remote X server
1
2
On the machine that hosts the virtual machine, add one of the following lines to the virtual machine configuration (.vmx) file or to ~/.vmware/config:
xkeymap.usekeycodeMap = "TRUE"
This property tells Workstation to always use key code mapping regardless of server type.
xkeymap.usekeycodeMapIfXFree86 = "TRUE"
This property tells Workstation to use key code mapping if you are using an XFree86 server, even if it is remote.
3
Change How a Specific Key Is Mapped
If some keys on the keyboard do not work correctly in a virtual machine, you can set a property that makes a modification to the map.
Before you begin, perform the following tasks:
Determine the X key code and the corresponding v-scan code for the key. To find the X key code for a key, run xev or xmodmap -pk. Most v-scan codes are listed in V-Scan Code Table.
To change how a specific key is mapped
1
2
On the machine that hosts the virtual machine, add the following line to the virtual machine configuration (.vmx) file or to ~/.vmware/config:
xkeymap.keycode.<code> = "<v-scan_code>"
The <code> value must be a decimal number and <v-scan_code> must be a C-syntax hexadecimal number (for example, 0x001).
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"
3
X Key Codes Compared to Keysyms
Pressing a key on the PC keyboard generates a PC 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, 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 Ctrl key on the left side of the keyboard has a one-byte scan code (0x1d). Its v-scan code is 0x01d. The Ctrl key scan code on the right side of the keyboard is two bytes (0xe0, 0x1d). Its v-scan code is 0x11d.
An XFree86 server on a PC has a one-to-one mapping from X key codes to PC scan codes, or v-scan codes, which is what Workstation uses. When Workstation is hosted on an XFree86 server and runs a local virtual machine, 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 languages. In other cases (not an XFree86 server or not a local server), Workstation must map keysyms to v-scan codes by using a set of keyboard-specific tables.
An X server uses a two-level encoding of keys, which includes the X key code and the keysym. 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. You can use an X application to control the mapping by using the function XChangeKeyboardMapping() or by the program xmodmap. To explore keyboard mappings, you can use the xev command, which shows the key codes and keysyms for keys typed into its window.
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.
Configure How Keysyms Are Mapped
When key code mapping cannot be used or is disabled, Workstation maps keysyms to v-scan codes. If a language-specific keyboard does not appear to be supported by Workstation, you might need to set a property that tells Workstation which keysym table to use.
Before you begin, perform the following tasks:
The easiest way to find the keysym name for a key is to run the xev or xmodmap -pk commands. The X header file /usr/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.
The tables are located in the xkeymap directory in the Workstation installation directory (usually /usr/lib/vmware). The table you must 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. For most of these, both the 101-key (or 102-key) and the 104-key (or 105-key) variants are available.
If none of the mapping tables is completely correct, find one that works best, copy it to a new location, and change the individual keysym mappings.
Workstation determines which table to use by examining the current X keymap. However, its decision-making process can sometimes fail. In addition, each mapping is fixed and might not be completely correct for any given keyboard and X key code-to-keysym mapping. For example, a user might 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 are unswapped when using a local server (key code mapping). To correct this situation, use configuration settings.
To configure how keysyms are mapped
1
2
On the machine that hosts the virtual machine, add one or more of the following lines to the virtual machine configuration (.vmx) file or to ~/.vmware/config:
xkeymap.nokeycodeMap = "TRUE"
For more information, see X Key Codes Compared to Keysyms.
If Workstation has a table in the xkeymap directory for your keyboard but cannot detect it, set the following property:
xkeymap.language = "<keyboard_type>"
The value <keyboard_type> must specify one of the tables in the xkeymap directory. However, the failure to detect the keyboard probably means the table is not completely correct for you. You might need to create a modified table and use the xkeymap.fileName property, described next.
To use a different keysym mapping table that is not in the xkeymap directory, set the following property, where <file_path> is the path to the table:
xkeymap.fileName = "<file_path>"
The table must list a keysym for each key by using the following form:
<sym> = "<v-scan_code>"
The <sym> value is an X keysym name, and <v-scan_code> is a C-syntax hexadecimal number (for example, 0x001). Use a new line for each keysym.
Compiling a complete keysym mapping is difficult. VMware recommends editing an existing table and making small changes.
xkeymap.keysym.<sym> = "<v-scan_code>"
The value <sym> must be an X keysym name and <v-scan_code> is a C-syntax hexadecimal number (for example, 0x001).
Most v-scan codes are listed in V-Scan Code Table. The xkeymap tables themselves are also helpful.
3
V-Scan Code Table
Table 16-1 shows the v-scan codes for the 104-key U.S. keyboard.
 
 
 
 
 
The 84-key keyboard has a Sys Req key on the numeric pad. Its v-scan code is 0x054.
Keyboards outside the U.S. usually have an extra key (often < > or < > |) next to the left Shift key. The v-scan code for this key is 0x056.