elfconv

elfconv is an experimental binary translator that translates a Linux ELF binary to the executable binary for other platforms. elfconv mainly converts Linux/ELF binaries into WebAssembly or ELF for different CPU architectures. elfconv converts an original ELF binary to the LLVM bitcode using Remill (However, many parts have been modified to improve functionality and performance) and elfconv uses Emscripten (for browser) or wasi-sdk (for WASI runtimes) to generate the WASM binary from the LLVM bitcode file.

Status

Warning

"elfconv is WORK IN PROGRESS" and the test is insufficient, so you may fail to compile your ELF binary or execute the generated WASM binary. Current limitations are as follows. However, we will resolve these issues in the future.

• Only support of aarch64 ELF binary as an input binary
  • Furthermore, a part of the aarch64 instructions are not supported. If your ELF binary's instruction is not supported, elfconv outputs the message ([WARNING] Unsupported instruction at 0x...) when you build with #define WARNING_OUTPUT 1 being commented out.
• No support for shared objects
• Only the part of Linux system calls are implemented (ref: runtime/syscalls/)

Benchmark

For several test programs, we measured the performance of the WebAssembly (both for browser and WASI runtimes) generated by elfconv. The comparison target was the Wasm program compiled directly by Emscripten or WASI-SDK from the source code . elfconv converts the ELF/aarch64 produced by an existing compiler (gcc or clang) from the same source code into a Wasm program. In this performance tests, we compared the performance of both Wasm programs.

To Wasm (Emscripten)

Target Program	from source code	elfconv
eratosthenes_sieve (↓ better)	0.567 (s) (100%)	0.692 (s) (82%)
LINPACK benchmark (↑ better)	1617 (MFLOPS) (100%)	1256 (MFLOPS) (78%)
mnist-neural-network-plain-c (during 30 steps) (↑ better)	2.138 (s) (100%)	2.255 (s) (96%)

To WASI

Target Program	from source code	elfconv
eratosthenes_sieve (↓ better)	0.362 (s) (100%)	0.608 (s) (60%)
LINPACK benchmark (↑ better)	4821 (MFLOPS) (100%)	2720 (MFLOPS) (56%)
mnist-neural-network-plain-c (during 30 steps) (↑ better)	2.271 (s) (100%)	2.302 (s) (96%)

As this table shows, Wasm on both Browser and WASI runtimes can be executed with less performance degradation than when Wasm is generated from the source code.

Quick Start

You can try elfconv using the docker container (amd64 and arm64) by executing the commands as follows and can execute the WASM application on the both browser and host environment (WASI runtimes).

Browser

$ git clone --recursive https://github.com/yomaytk/elfconv
$ cd elfconv
elfconv/$ docker build . -t <image-name>
elfconv/$ docker run -it --rm -p 8080:8080 --name <container-name> <image-name>
### running build and test ...
# You can test elfconv using `bin/elfconv.sh`
~/elfconv# cd bin
~/elfconv/bin# TARGET=Browser ./elfconv.sh /path/to/ELF # e.g. ../examples/hello/a.out
# exe.js and exe.wasm should be generated.
~/elfconv/bin# emrun --no_browser --port 8080 exe.html
Web server root directory: /root/elfconv/bin
Now listening at http://0.0.0.0:8080/

Now, the WASM application server has started, so that you can access it (e.g. http://localhost:8080/exe.wasm.html) from outside the container.

Host (WASI runtimes)

$ git clone --recursive https://github.com/yomaytk/elfconv
$ cd elfconv
$ docker build . -t <image-name>
$ docker run -it --name <container-name> <image-name>
### running build and test ...
# You can test elfconv using `bin/elfconv.sh`
~/elfconv# cd bin
~/elfconv/bin# TARGET=Wasi ./elfconv.sh /path/to/ELF # e.g. ../examples/hello/a.out
~/elfconv/bin# wasmtime exe.wasm # wasmtime is preinstalled

Source code build

1. Dev Container

elfconv provides the Dev Container environment using the root Dockerfile and .devcontainer.json, so you can develop without making the build environment if you can use Dev Container on your vscode (Please refer to the official website of vscode for basically using Dev Container).

2. Local Environment

Dependencies

The libraries required for the build are almost the same as those for Remill, and the main libraries are as follows. The other required libraries are automatically installed using cxx-common.

Name	Version
CMake	3.14+
Google Flags	Latest
Google Log	Latest
Google Test	Latest
LLVM	16+
Clang	16+
Intel XED	Latest
Unzip	Latest
ccache	Latest
libelf	Latest
libbfd	Latest
libdwarf	Latest

Build

If you prepare these libraries, you can easily build elfconv by executing scripts/build.sh as follows.

$ git clone --recursive https://github.com/yomaytk/elfconv
$ cd elfconv
/elfconv$ ./scripts/build.sh

Note

If you fail to build elfconv, please feel free to submit an issue!

Develop

After finishing the build, you can find the directory elfconv/build/, and you can build the 'lifter' ('lifter' is the module that converts the ELF binary to LLVM bitcode and those source codes are mainly located in the backend/remill/ and lifter/) by ninja after modifying the 'lifter' codes.

You can compile the ELF binary to the WASM binary using scripts/dev.sh as follows. dev.sh execute the translation (ELF -> LLVM bitcode by 'lifter') and compiles the runtime/ (statically linked with generated LLVM bitcode) and generate the WASM binary. when you execute the script, you should explicitly specify the path of the elfconv directory (/root/elfconv on the container) with NEW_ROOT or rewrite the ROOT_DIR in dev.sh.

# TARGET=<elf_arch>-<target_arch> (e.g. ELF/aarch64 -> Wasi32: aarch64-wasi32)

### Native
~/elfconv/build# NEW_ROOT=/path/to/elfconv TARGET=aarch64-native ../scripts/dev.sh path/to/ELF # generate the Native binary (Host architecture) under the elfconv/build/lifter
~/elfconv/build# ./exe.${HOST_CPU}
------------------------
### Browser (use xterm-pty (https://github.com/mame/xterm-pty))
~/elfconv/build# NEW_ROOT=/path/to/elfconv TARGET=aarch64-wasm ../scripts/dev.sh path/to/ELF # generate the WASM binary under the elfconv/build/lifter
~/elfconv/build# emrun --no_browser --port 8080 ../examples/browser/exe.html # execute the generated WASM binary with emscripten
------------------------
### Host (WASI Runtimes)
~/elfconv/build# NEW_ROOT=/path/to/elfconv TARGET=aarch64-wasi32 ../scripts/dev.sh path/to/ELF
~/elfconv/build# wasmedge ./exe.wasm # or wasmedge ./exe_o3.wasm

Acknowledgement

elfconv uses or references some projects as follows. Great thanks to its all developers!

• Remill (Apache Lisence 2.0)
  • Original Source: https://github.com/lifting-bits/remill
  • elfconv uses Remill in order to convert machine codes to LLVM IR instructions. the source code is contained in ./backend/remill and is modified for using from front-end and supporting additional instructions.
• MyAOT (Apache Lisence 2.0)
  • Original Source: https://github.com/AkihiroSuda/myaot
  • An experimental AOT-ish compiler (Linux/riscv32 ELF → Linux/x86_64 ELF, Mach-O, WASM, ...)
  • We referenced the design of MyAOT for developing elfconv.