[an error occurred while processing this directive] [an error occurred while processing this directive]
VMware

VMware Workstation 3.2

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.usekey codeMap = 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, 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 9-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 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 below are also helpful.

Use this feature to make small modifications to the mapping. For example, to swap left control and caps lock, use the following lines:

xkeymap.key code.64 = 0x01d # X Caps_Lock -> VM left ctrl
xkeymap.key code.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. This is done 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 heuristics 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 control 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, most of the behavior can be changed with 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 hard. 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 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