FreeBSD bhyve keyboard layout patch

Fork

[[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 keyboard 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

  * If you use the FreeBSD 12.1/2/3/4-RELEASE, please replace the "fbsd131r" of the above No.2 to
    the "fbsd124r" or "fbsd123r" or "fbsd122r" or "fbsd121r".


<<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

  * If you use the FreeBSD 12.1/2/3/4-RELEASE, please replace the "fbsd131r" of the above No.2 to
    the "fbsd124r" or "fbsd123r" or "fbsd122r" or "fbsd121r".

  Second, please apply the patch to vmrun.sh.

    8. cd /usr/src/share
    9. patch -u < bhyve_kbdlayout_vmrunsh_fbsd130r.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 **
	The layout specified option is changed to uppercase "-K", from the version of 2021/5/5.
	Please note that if you are using an earlier patch, it will be incompatible!


<<ChangeLog>>=======================================================================================
  * 2023/04/12
     - Add the patches for FreeBSD 12.4-RELEASE.

  * 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.

<< Request for Coooperation (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 FreeBSD
  bugzilla below or koinec@users.osdn.me.

    https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=246121

<< Remarks >> ======================================================================================
  These patches was merged into the FreeBSD-CURRENT source-tree on 2022/1/21.
  I really appreciate everyone who cooperated.
  Thank you very much !!

  These patches will be updated irregularly until it is merged into FreeBSD RELEASE.

--- Koine Yuusuke <koinec@users.osdn.me>