FreeBSD bhyve keyboard layout specified option patch & support QEMU extended keyevent message patch

Backgroud

When a guest OS is loaded using UEFI and connected with VNC, if the keyboard on the VNC client side is other than the US keyboard, some keys input may not be performed correctly.
For example, if you press the '@' key on a Japanese keyboard, the number '2' will be entered on the guest OS.
The cause is that the '@' key on the US keyboard is assigned to Shift + '2' keys.
In addition, there is a problem that keys that do not exist on the US keyboard cannot be entered. (example, Zenkaku-Hankaku key in the Japanese Keyboard)

In the current bhyve(13.x-RELEASE & 12.x-RELEASE), in the virtual PS2 keyboard driver, there is a conversion table that converts from the key entered from the VNC client side to the virtual keyboard scancode for the Guest OS.
However, since this conversion table is set for US keyboards, the above problem will occur if the client side is not a US keyboard.

Therefore, in order to solve this problem, the following two types of patches were created.

Patches Overview

<Patch 1> Support for QEMU Extended Key Event Message.
By applying a patch that supports QEMU Extended Key Event message to bhyve, this patch bypasses the conversion process to keyboard scancode by the conversion table and sends the Keycode on the VNC client side directly to the guest OS.
If you're using TigerVNC, this method can solve keyboard layout issues without any bhyve boot options or VNC client settings.
However, it has no effect when using VNC clients that do not support QEM messages, such as tightVNC and ssvnc.

<Patch 2> Append Keyboard Layout specified option.
This patch adds the ability to overwrite the keyboard scancode conversion table that is causing the problem from the settings for the US key board to the settings for the language you want to use.
In addition, the content of the setting (conversion table) to be overwritten is an external layout setting file for each language so that the language to be used can be set from the bhyve command option.
This method will work fine with VNC clients that do not support QEMU Extended Key Event Message, such as tightVNC.
However, it is necessary to specify options according to the keyboard layout of the client on the hypervisor side, and it is necessary to prepare an external configuration file that matches the keyboard layout of each language.
(For each keyboard layout available on the FreeBSD console, we have created a layout configuration file that allows you to use the minimum keys, such as alphabets and numbers.)

Patch 1 and 2 are independent. Therefore, it is possible to apply only one or both.

Usage <Patch 1> Support for QEMU Extended Key Event Message.

This patch can be used only by applying the patch according to the following procedure and then building and installing the bhyve command.
VNC clients can only be used with QEMU Extended Key Event Messages, (e.g. tigerVNC)
The patch is stored in the qemu_ext_keyevent_msg directory.

1. cd /usr/src/usr.sbin/bhyve
2. patch -u -p1 < bhyve_qemu_ext_key_event_msg_fbsd131r.patch
3. make
4. make install

Usage <Patch 2> Append Keyboard Layout specified option.

First, please apply the patch to bhyve by following the steps below.
Then extract the keyboard layout settings files and then build and install it.

1. cd /usr/src/usr.sbin/bhyve
2. patch -u -p1 < bhyve_kbdlayout_option_fbsd131r.patch
3. cd /usr/src/usr.sbin
4. sh bhyve_kbdlayout_layoutfile.shar
5. cd /usr/src/usr.sbin/bhyve
6. make
7. make install

Second, please apply the patch to vmrun.sh.

8. cd /usr/src/share
9. patch -u < bhyve_kbdlayout_vmrunsh_fbsd131r.patch

Finaly, if you use the bhyve command directly, specify the '-K layout' option for the bhyve command.
You can specify the "layout" in the file name stored in /usr/share/bhyve/kbdlayout dir.
If no '-K' option is specified, the US keyboard (default) is assumed to be selected.

Others, If you use the bhyve via the vm-bhyve package, specify the following lines for the Guest OS configure file.

bhyve_options="-K layout"

CAUTION for <Patch 2>

The layout specified option is changed to uppercase "-K", since the version of 2021/5/5.
Please note that if you are using an earlier patch, it will be INCOMPATIBLE!

Change Log

  * 2022/05/19
     - Add the patches for FreeBSD 13.1-RELEASE.
     - Remove the patches for FreeBSD 13-STABLE(20211223).
     - Fix install operation in this file.

  * 2022/01/21
     - Add to the README (this doc.) that these patches was merged into the FreeBSD-CURRENT source tree.

  * 2022/01/02
     - Add the patches for FreeBSD 12.3-RELEASE.
     - Add the patches for FreeBSD 13-STABLE(20211223).

  * 2021/05/05
     - Update for FreeBSD 13.0-RELEASE.(Along with this, the patch filename was changed)
         >> [Patch 1] & [Patch 2]

     - Change keyboard layout specification option to "-K" (uppercase K).
       (Because "-k" is used for other purposes in FreeBSD current's bhyve)
         >> [Patch 2] - for FreeBSD 13.0-RELEASE & 12.2-RELEASE

     - Fix the following issues on the FreeBSD review site.
         (Corrected the violation of man's notation rule by incorporating the content of the proposal
          on the review side.) (https://reviews.freebsd.org/D29473)

  * 2021/01/24
     - Initial Version as an archive file for osdn.net.

Note

These patches was merged into the FreeBSD-CURRENT source-tree on 2022/1/21.
I really appreciate everyone who cooperated.
THANK YOU VERY MUCH!!

The patches on this page will be updated irregularly until they are merged into the FreeBSD Release version.

Request for Cooperation (The remaining tasks)

Currently, the keyboard layout configuration file is generated from the FreeBSD console layout configuration file. (Excluding layout setting files for Japanese keyboards)
Therefore, there are the following problems.

• There are no settings for keyboard-specific keys for each language, such as alphabets, number keys, Enter, Space, and Escape, which are not found in US keyboards.
• The layout setting file has not been tested except for the Japanese keyboard.

Regarding the above, please add to the created layout setting file and cooperate with the test.
If the layout configuration file has been improved or tested, please report the results to the following FreeBSD bugzilla or koinec@users.osdn.me.

Release Files

Filename	크기	Time	Download count
bhyve_keyboard_layout_patch_20220519.tgz	24.65 k	2022-05-19 21:13:22	66
bhyve_keyboard_layout_patch_20220121.tgz	24.53 k	2022-05-19 21:13:00	119
bhyve_keyboard_layout_patch_20210505.tgz	22.67 k	2022-01-21 21:11:21	75
bhyve_keyboard_layout_patch_20210102.tgz	22.05 k	2021-05-05 13:54:38	69

Repository

Recent Commits