Difference between revisions of "Development:Setting up Thunks"

From FEX-Emu Wiki
Jump to navigation Jump to search
m
Line 1: Line 1:
[[Category:Development]]
+
= Build instructions =
== Build Dependencies ==
+
== Build dependencies ==
 
* g++-x86-64-linux-gnu (For building thunks)
 
* g++-x86-64-linux-gnu (For building thunks)
* '''Development libraries for various thunks'''
+
* pkg-config
* libdrm-dev
+
* libclang-dev
* libxcb-present-dev
+
* libssl-dev
* libxcb-dri2-0-dev
+
* Development packages for thunked libraries:
* libxcb-dri3-dev
+
** libdrm-dev
* libxcb-glx0-dev
+
** libxcb-present-dev
* libxcb-shm0-dev
+
** libxcb-dri2-0-dev
* libxshmfence-dev
+
** libxcb-dri3-dev
* libvulkan-dev  
+
** libxcb-glx0-dev
 
+
** libxcb-shm0-dev
== Building vulkan-docs if your host is too old ==
+
** libxshmfence-dev
If you're host's libvulkan-dev is too old, which is highly likely then you'll need to install a new set of vulkan headers
+
** libvulkan-dev  
 
 
* git clone https://github.com/KhronosGroup/Vulkan-Headers.git
 
* cd Vulkan-Headers
 
* mkdir Build
 
* cd Build
 
* cmake -DCMAKE_INSTALL_PREFIX=/usr ..
 
* sudo make install
 
  
== Setting cmake to build thunks ==
+
== Setting CMake to build thunks ==
Pass in to cmake the option to enable thunk building.
+
Pass in to CMake the option to enable thunk building.
 
* -DBUILD_THUNKS=True
 
* -DBUILD_THUNKS=True
  
 +
= Configuration =
 
== FEX thunk options ==
 
== FEX thunk options ==
 
* FEX_THUNKHOSTLIBS, -t <Thunk Host Libs Path>, --thunkhostlibs=<Thunk Host Libs path>, JSON: '''ThunkHostLibs:<Path>'''
 
* FEX_THUNKHOSTLIBS, -t <Thunk Host Libs Path>, --thunkhostlibs=<Thunk Host Libs path>, JSON: '''ThunkHostLibs:<Path>'''
Line 105: Line 99:
 
   }
 
   }
  
 +
= Further notes =
 
== Limitations and problems ==
 
== Limitations and problems ==
 
* 32-bit thunks aren't available currently
 
* 32-bit thunks aren't available currently
Line 126: Line 121:
 
     }
 
     }
 
   }
 
   }
 +
[[Category:Development]]

Revision as of 14:00, 22 June 2022

Build instructions

Build dependencies

  • g++-x86-64-linux-gnu (For building thunks)
  • pkg-config
  • libclang-dev
  • libssl-dev
  • Development packages for thunked libraries:
    • libdrm-dev
    • libxcb-present-dev
    • libxcb-dri2-0-dev
    • libxcb-dri3-dev
    • libxcb-glx0-dev
    • libxcb-shm0-dev
    • libxshmfence-dev
    • libvulkan-dev

Setting CMake to build thunks

Pass in to CMake the option to enable thunk building.

  • -DBUILD_THUNKS=True

Configuration

FEX thunk options

  • FEX_THUNKHOSTLIBS, -t <Thunk Host Libs Path>, --thunkhostlibs=<Thunk Host Libs path>, JSON: ThunkHostLibs:<Path>
    • Folder to find the host-side thunking libraries.
    • FEX by default installs these files to: /usr/lib/fex-emu/HostThunks/
  • FEX_THUNKGUESTLIBS, -j <Thunk Host Libs Path>, --thunkguestlibs=<Thunk Host Libs path>, JSON: ThunkGuestLibs:<Path>
    • Folder to find the guest-side thunking libraries.
    • FEX by default installs these files to: /usr/share/fex-emu/GuestThunks/
  • FEX_THUNKCONFIG, -k <Thunk Config json path>, --thunkconfig=<Thunk Config json path>, JSON: ThunkConfig:<Path>
    • A json file specifying where to overlay the thunks.
    • If the filename isn't a path then FEX will search for the file in $HOME/.fex-emu/ThunkConfigs/

How to use Thunks

Once Thunks are built and installed then you can can set the three configuration options to the correct paths

  • The user can likely set ThunkHostLibs and ThunkGuestLibs to the global install path
    • Unless these are set in the ThunkConfig file, these will be unused
    • Overriding these to another location is useful for application specific hacks if necessary
  • Setting the global application profile for ThunkConfig is useful for testing but not recommended for long term use
    • Due to the unstable nature of thunks, it is recommended to use application specific profiles to enable thunks
    • This allows the user to test applications first using the global config, then once confirmed it works, generating an application profile
    • Recommended to reduce the application profile to the minimum set of options. FEXConfig will save a full config.

Thunks Database format

FEX provides a ThunksDB.json file which allows the user to describe a thunk mapping. $prefix/share/fex-emu/ThunksDB.json

The user can also provide a $HOME/.fex-emu/ThunksDB.json which will overlay the system installed path

This allows the user to configure the thunk file mapping once, since it is unlikely to change between applications. The user can also mix and match ThunksDB and regular thunks configuration if a complex configuration is necessary.

  • ThunksDB.json example
 {
     "DB": {
       "<User Defined Name>": {
         "Library": "<Guest Library Name>.so",
         "Depends": [
           "<Other User Defined Name>"
         ],
         "Overlay": [
           "<System Library Path to library>"
         ]
       }
     }
 }

Look at the FEX provided library for a real implementation, or just use the provided configuration.

Once the user has a viable ThunksDB provided, now configure FEX with a ThunkConfig filepath with the application thunk configuration.

This thunks configuration file can now enable Thunk definitions using the user defined names.

  • ThunkConfig example
 {
   "ThunksDB": {
     "GL": 0,
     "xcb": 1,
     "xcb-dri2": 1,
     "xcb-dri3": 1,
     "X11": 0,
     "xcb-xfixes": 1,
     "xcb-shm": 1,
     "xcb-sync": 1,
     "xcb-randr": 0,
     "xcb-present": 0,
     "xcb-glx": 1,
     "xshmfence": 1,
     "drm": 0,
     "Xrender": 0,
     "Xext": 0,
     "Xfixes": 0,
     "Vulkan-lavapipe": 1,
     "Vulkan-radeon": 1,
     "Vulkan-freedreno": 1,
     "Vulkan-intel": 1,
     "Vulkan-panfrost": 1,
     "Vulkan-virtio": 1,
     "asound": 0
   }
 }

Further notes

Limitations and problems

  • 32-bit thunks aren't available currently
    • Requires kernel patches for ARM64 support
  • Thunks aren't fully stable. Expect missing symbols and crashes.

Legacy ThunkConfig example

This is legacy path and not recommended.

This is just an example for how one could lay out the thunks.

  • Save this to a file somewhere and point ThunkConfig option to it
    • $HOME/.fex-emu/ThunkConfigs/ isn't a bad choice for consistency.
 {
  "thunks": {
   "libGL-guest.so": ["/lib/x86_64-linux-gnu/libGL.so.1", "/usr/lib/x86_64-linux-gnu/libGL.so.1"],
   "libasound-guest.so": ["/lib/x86_64-linux-gnu/libasound.so.2", "/usr/lib/x86_64-linux-gnu/libasound.so.2"],
   "libX11-guest.so": ["/lib/x86_64-linux-gnu/libX11.so.6", "/usr/lib/x86_64-linux-gnu/libX11.so.6"],
   "libXrender-guest.so": ["/lib/x86_64-linux-gnu/libXrender.so.1", "/usr/lib/x86_64-linux-gnu/libXrender.so.1"],
   "libXext-guest.so": ["/lib/x86_64-linux-gnu/libXext.so.6", "/usr/lib/x86_64-linux-gnu/libXext.so.6"],
   "libXfixes-guest.so": ["/lib/x86_64-linux-gnu/libXfixes.so.3", "/usr/lib/x86_64-linux-gnu/libXfixes.so.3"]
   }
 }