diff --git a/CMakeLists.txt b/CMakeLists.txt index b54dbe97a4..d9dab16ea3 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -32,7 +32,7 @@ option(ANDROID "Set to ON if targeting an Android device" ${ANDROID}) option(TERMUX "Set to ON if targeting an Android device with Termux" ${TERMUX}) option(USE_CCACHE "Set to ON to use ccache if present in the system" ${USE_CCACHE}) option(HAVE_TRACE "Set to ON to have Trace ability (needs ZydisInfo library)" ${HAVE_TRACE}) -option(SAVE_MEM "Set to ON to build dynarec with some slower memory saving optimisations" ${SAVE_MEM}) +option(SAVE_MEM "Set to ON to build dynarec with some slower memory saving optimizations" ${SAVE_MEM}) option(NOLOADADDR "Set to ON to avoid fixing the load address of Box64" OFF) option(NOGIT "Set to ON if not building from a git clone repo (like when building from a zip download from github)" ${NOGIT}) option(BAD_SIGNAL "Set to ON to activate the workaround for incoherent si_info on SIGSEGV" ${BAD_SIGNAL}) diff --git a/docs/COMPILE.md b/docs/COMPILE.md index 731502cb95..8ce7641bc3 100644 --- a/docs/COMPILE.md +++ b/docs/COMPILE.md @@ -6,9 +6,9 @@ If you don't want to compile box64 yourself and prefer to use third-party pre-bu You can also generate your own package using the [instructions below](https://github.com/ptitSeb/box64/blob/main/docs/COMPILE.md#debian-packaging). ## Per-platform compiling instructions ----- -### The general approach is: +### The general approach + ``` git clone https://github.com/ptitSeb/box64 cd box64 @@ -20,10 +20,11 @@ If it's the first install, you also need: ``` sudo systemctl restart systemd-binfmt ``` -- You can use `make -j1`, `make -j2` to prevent running out of memory -- You can also add `-DBAD_SIGNAL=ON` to the cmake command if you are on Linux Kernel mixed with Android, like on RK3588. +- You can use `make -j1`, `make -j2` with less jobs to prevent running out of memory +- You can also add `-DBAD_SIGNAL=ON` to the cmake command if you are on a Linux Kernel mixed with Android, like on RK3588. + +#### Example of generic ARM64 build for linux platforms -#### For Instance, if you want to build box64 for Generic ARM64 Linux platforms, it would look like this: ``` git clone https://github.com/ptitSeb/box64 cd box64 @@ -36,21 +37,21 @@ sudo systemctl restart systemd-binfmt #### for RK3399 -Using a 64bit OS: +On a 64bit OS: ``` -D RK3399=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo ``` #### for RK3588 / RK3588S -Using a 64bit OS: +On a 64bit OS: ``` -D RK3588=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo ``` #### for Raspberry Pi 3 -Warning, you need a 64bit OS: +On a 64bit OS: If building on the Pi, you will also need a large swap (3 GB+) [optionally reduce GPU memory to a minimum (e.g. 16 MB) using `raspi-config` @@ -66,7 +67,7 @@ Still, this can be faster if your build is attended. #### for Raspberry Pi 4 -Warning, you need a 64bit OS: +On a 64bit OS: ``` -D RPI4ARM64=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo @@ -80,7 +81,7 @@ Warning, you need a 64bit OS: #### for TEGRA X1 -Using a 64bit OS: +On a 64bit OS: ``` -D TEGRAX1=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo @@ -88,7 +89,7 @@ Using a 64bit OS: #### for Jetson Xavier/T194 -Using a 64bit OS: +On a 64bit OS: ``` -D TEGRA_T194=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo @@ -96,16 +97,16 @@ Using a 64bit OS: #### for Jetson Orin/T234 -Using a 64bit OS: +On a 64bit OS: -Caution: please use gcc-11 or higher, older gcc doesn't know cortex-a78ae +Note: use gcc-11 or higher, older gcc doesn't know cortex-a78ae ``` -D TEGRA_T234=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo ``` #### for ODROID N2/N2+ -Using a 64bit OS: +On a 64bit OS: ``` -D ODROIDN2=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo @@ -113,7 +114,7 @@ Using a 64bit OS: #### for Snapdragon -Using a 64bit OS: +On a 64bit OS: ``` -D SD845=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo @@ -125,18 +126,18 @@ or -D SD888=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo ``` -Depending how recent your Snapdragon is +Depending on how recent your Snapdragon is #### for Phytium -Using a 64bit OS: +On a 64bit OS: ``` -D PHYTIUM=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo ``` #### for ADLink machines -Using a 64bit OS: +On a 64bit OS: ``` -D ADLINK=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo ``` @@ -151,7 +152,7 @@ Only test on Asahi with Fedora, using the default "16K page" kernel #### for LoongArch -Using a 64bit OS: +On a 64bit OS: ``` -D LARCH64=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo @@ -159,7 +160,7 @@ Using a 64bit OS: #### for RISC-V -Using a 64bit OS: +On a 64bit OS: ``` -D RV64=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo @@ -167,7 +168,7 @@ Using a 64bit OS: #### for PowerPC 64 LE -Using a 64bit OS: +On a 64bit OS: ``` -D PPC64LE=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo @@ -175,7 +176,7 @@ Using a 64bit OS: #### for LX2160A -Using a 64bit OS: +On a 64bit OS: ``` -D LX2160A=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo @@ -183,7 +184,7 @@ Using a 64bit OS: #### for Termux -You must have ARM64 Device for build box64. +You must have ARM64 machine to build box64. ##### in CHRoot/PRoot @@ -193,15 +194,16 @@ You must have ARM64 Device for build box64. ##### in Termux (Native) -NOTE: BUILDING BOX64 IN TERMUX NATIVE IS EXPERIMENTAL AND DOESN'T GONNA RUN LINUX BINARIES IN NATIVE TERMUX BOX64!!! +Note: Box64 in native termux is experimental and won't run linux binaries! -You also needed have `libandroid-sysv-semaphore` and `libandroid-spawn` libraries: +You also need `libandroid-sysv-semaphore` and `libandroid-spawn` libraries. ``` -D TERMUX=1 -DCMAKE_C_COMPILER=clang -D CMAKE_BUILD_TYPE=RelWithDebInfo ``` #### for x86_64 Linux + ``` -D LD80BITS=1 -D NOALIGN=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo ``` @@ -215,58 +217,58 @@ Alternatively, you can **use the curses-based ccmake (or any other gui frontend ### Customize your build -#### Use ccache if you have it +#### Use ccache when present -Add `-DUSE_CCACHE=1` if you have ccache (it's better if you plan to touch the sources) +Add `-DUSE_CCACHE=1` option if you have ccache and plan to touch the sources. -#### To have some debug info +#### Include debug information -The `-DCMAKE_BUILD_TYPE=RelWithDebInfo` argument makes a build that is both optimized for speed, and has debug information embedded. That way, if you have a crash or try to analyse performance, you'll have some symbols. +Add `-DCMAKE_BUILD_TYPE=RelWithDebInfo` option for an optimized build with debug information embedded. That way, if you want to debug a crash or analyze performance, you have symbols. -#### To have a Trace Enabled build +#### Build with trace -To have a trace enabled build (***the interpreter will be slightly slower***), add `-DHAVE_TRACE=1`. But you will need to have the [Zydis library](https://github.com/zyantific/zydis) in your `LD_LIBRARY_PATH` or in the system library folders at runtime. Use version v3.2.1, as later version changed the API and will no longer work with box64 +To have a trace enabled build (***the interpreter will be slightly slower***), add `-DHAVE_TRACE=1`. You will need the [Zydis library](https://github.com/zyantific/zydis) in your `LD_LIBRARY_PATH` or in the system library folders at runtime to get x86 trace. Use version v3.2.1, as later versions have changed the API and no longer work with box64. -#### To have ARM Dynarec +#### Build ARM DynaRec -Dynarec is only available on ARM (for the meantime), Activate it by using `-DARM_DYNAREC=1`. +Add `-DARM_DYNAREC=1` option to enable DynaRec on ARM machines. -#### To have a build using less memory +#### Save memory at run time -You can use `-DSAVE_MEM` to have a build that will try to save some memory. It's, for now, only increasing the jumptable from 4 level to 5 levels. The added granularity avoid wasting space, but the 1 level more to the jumptable means there is on read from memory more when jumping between blocks. +You can use `-DSAVE_MEM` to have a build that will try to save some memory. For now, it only increases the jumptable from 4 levels to 5. The added granularity avoids wasting space, but adds one more read from memory when jumping between blocks. -#### Not building from a git clone +#### Build outside of a git repo -If you are not building from a git clone (for example, downloading a release source code zip from github), you need to use `-DNOGIT=1` from cmake to be able to build (box64 uses git SHA1 to show last commit in version number). +Box64 uses git SHA1 to show last commit in version number, use `-DNOGIT=1` option when building outside of a git repo (for example, downloading a release source code zip from github). #### Use faster linker -You need to add `-DWITH_MOLD=1` if GNU ld is extremely slow. Then run `mold -run make -j4` to build (make sure [Mold](https://github.com/rui314/mold) is installed). +Add `-DWITH_MOLD=1` option when GNU ld is extremely slow. Then run `mold -run make -j4` to build (make sure [Mold](https://github.com/rui314/mold) is installed). #### Build a statically linked box64 -You can now build box64 statically linked, with `-DSTATICBUILD`. This is to use inside an x86_64 chroot. Note that this version of box64 will have just the minimum of wrapped libs. So only libc, libm and libpthread basically are wrapped. Other libs (like libGL or libvulkan, SDL2, etc...) will not be wrapped and x86_64 version will be used. It's designed to be used in docker image, or in headless server. -Also, the Static Build is highly experimental, but feedback are always welcomed. +You can now build box64 statically linked, with `-DSTATICBUILD` to use inside of a x86_64 chroot. Note that this version of box64 will only have the minimal wrapped libs, such as libc, libm and libpthread. Other libs (like libGL or libvulkan, SDL2, etc...) will use x86_64 versions. A static build is intended to be used in a docker image, or in a headless server. It is highly experimental, but feedback is always welcome. ---- ## Testing ----- + A few tests are included with box64. They can be launched using the `ctest` command. -The tests are very basic and only tests some functionality for now. +The tests are very basic and only test some functionality for now. ---- ## Debian Packaging ----- -Box64 can also be packaged into a .deb file ***using the source code zip from the releases page*** with `DEB_BUILD_OPTIONS=nostrip dpkg-buildpackage -us -uc -nc`. Configure any additional cmake options you might want in `debian/rules`. -## Pre-build packages ----- +Box64 can also be packaged into a .deb file ***using the source code zip from the releases page*** with `DEB_BUILD_OPTIONS=nostrip dpkg-buildpackage -us -uc -nc`. Configure any additional cmake options you want in `debian/rules`. + +## Pre-built packages + ### Debian-based Linux + You can use the [Pi-Apps-Coders apt repository](https://github.com/Pi-Apps-Coders/box64-debs) to install precompiled box64 debs, updated every 24 hours. ``` diff --git a/docs/USAGE.md b/docs/USAGE.md index fd9fa551d6..237f386aa6 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -2,437 +2,533 @@ Usage ---- -There are many environment variables to control Box64 behaviour. -Env. var with * can also be put inside box64rc files. -Box64 look for 2 places for rcfile: `/etc/box64.box64rc` and `~/.box64rc` -The second takes precedence to the first, on an APP level -(that means if an [MYAPP] my appears in both file, only the settings in `~/.box64rc` will be applied) -There is also some "generic" name, like [*SETUP*] that will be applied to every program containing "setup" in the name -(Note that this is not a full regex rules, it's just a name between '[*' and '*]', nothing else) +There are multiple environment variables to control Box64 behaviour. + +### Configuration files + +Env. vars below marked with * can also be put inside box64rc file, with priority over command line environment. +Box64 looks for 2 places for rcfile: `/etc/box64.box64rc` and `~/.box64rc`. +The second takes precedence over the first per each application (when `[MYAPP]` appears in both files, only the settings in `~/.box64rc` will be applied). +Asterisks may be used to denote a substring in the application name, like `[*setup*]` that will be applied to every program containing "setup" in its name. Note that this is not a complete set of regex rules. Settings priority: `~/.box64rc` > `/etc/box64.box64rc` > Command line. +---- + +### Debugging + #### BOX64_LOG * -Controls the Verbosity level of the logs - * 0: NONE : No message (except some fatal error). (Default.) - * 1: INFO : Show some minimum log (Example: librairies not found) - * 2: DEBUG : Details a lot of stuff (Example: relocations or functions called). + +Set the level of box64 logs. + * 0: NONE : No messages (except for a few fatal errors). (default) + * 1: INFO : Minimum log (Example: missing libraries) + * 2: DEBUG : Verbose log (Example: relocations or functions called). * 3: DUMP : All DEBUG plus DUMP of all ELF Info. #### BOX64_ROLLING_LOG * -Show last few wrapped function call when a Signal is caught - * 0: No last function call printed (Default.) - * 1: Last 16 wrapped functions calls printed when a signal is printed. Incompatible with BOX64_LOG>1 (may need BOX64_SHOWSEGV=1 also) - * N: Last N wrapped functions calls printed when a signal is printed. Incompatible with BOX64_LOG>1 (may need BOX64_SHOWSEGV=1 also) -#### BOX64_NOBANNER -Disables Box64 printing its version and build - * 0 : Enable printing its banner. (Default.) - * 1 : Disable printing its banner. +Show last few wrapped function call when a Signal is caught. + * 0: No last function call printed (default) + * 1: Print last 16 wrapped functions calls when a signal is caught. Incompatible with BOX64_LOG>1 (may need BOX64_SHOWSEGV=1) + * N: Print last N wrapped functions calls when a signal is caught. Incompatible with BOX64_LOG>1 (may need BOX64_SHOWSEGV=1) -#### BOX64_LD_LIBRARY_PATH * -Path to look for x86_64 libraries. Default is current folder and `lib` in current folder. -Also, `/usr/lib/x86_64-linux-gnu`, `/lib/x86_64-linux-gnu` and `/usr/lib/box64-x86_64-linux-gnu` are added if they exist. +#### BOX64_NOBANNER -#### BOX64_PATH * -Path to look for x86_64 executable. Default is current folder and `bin` in current folder. +Disables printing box64 version and build. + * 0 : Print the banner. (default) + * 1 : Do not print the banner. #### BOX64_DLSYM_ERROR * -Enables/Disables the logging of `dlsym` errors. - * 0 : Don't log `dlsym` errors. (Default.) - * 1 : Log dlsym errors. + +Enable logging of `dlsym` errors. + * 0 : Do not print `dlsym` errors. (default) + * 1 : Print dlsym errors. #### BOX64_TRACE_FILE * -Send all log and trace to a file instead of `stdout` -Also, if name contains `%pid` then this is replaced by the actual PID of box64 instance -End the filename with `+` to have the trace appended instead of overwritten -Use `stderr` to use this instead of default `stdout` + +Send all log and trace to a file instead of `stdout`. +File name syntax: + * `%pid` in the name is replaced with the actual PID of box64 instance. + * Use `+` in the end of the name to append instead of overwriting. + * `stderr` can be used instead of default `stdout` + +#### BOX64_SHOWSEGV * + +Always show Segfault signal. + * 0 : Do not force show the SIGSEGV if a signal handler is present. (default) + * 1 : Show SIGSEGV detail, even if a signal handler is present. + +#### BOX64_SHOWBT * + +Show some backtrace (native and emulated) when a signal (SEGV, ILL or BUS) is caught. + * 0 : Do not show backtraces. (default) + * 1 : Show Backtrace details (for native, box64 is renamed as the x86_64 binary runs). + +#### BOX64_NOSIGSEGV * + +Disable handling of SigSEGV for debugging. + * 0 : Let the x86 program set sighandler for SEGV. (default) + * 1 : Disable the handling of SigSEGV. + +#### BOX64_NOSIGILL * + +Disable handling of SigILL for debugging. + * 0 : Let x86 program set sighandler for Illegal Instruction. + * 1 : Disable the handling of SigILL. + +#### BOX64_LOAD_ADDR * + +Try to load the binary at 0xXXXXXX. (if the binary is a PIE) + * 0xXXXXXXXX : The load address . (Only active on PIE programs.) + +#### BOX64_JITGDB * + + * 0 : Just print the Segfault message when the signal is caught. (default) + * 1 : Launch `gdb` when a segfault, bus error or illegal instruction signal is trapped, attached to the offending process and go in an endless loop, waiting. + When in gdb, you need to find the correct thread yourself (the one with `my_box64signalhandler` in is stack) + then probably need to `finish` 1 or 2 functions (inside `usleep(..)`) and then you'll be in `my_box64signalhandler`, + just before the printf of the Segfault message. Then simply + `set waiting=0` to exit the infinite loop. + * 2 : Launch `gdbserver` when a segfault, bus error or illegal instruction signal is trapped, attached to the offending process, and go in an endless loop, waiting. + Use `gdb /PATH/TO/box64` and then `target remote 127.0.0.1:1234` to connect to the gdbserver (or use actual IP if not on the machine). After that, the procedure is the same as with ` BOX64_JITGDB=1`. + This mode can be usefull when programs redirect all console output to a file (like Unity3D Games) + * 3 : Launch `lldb` when a segfault, bus error or illegal instruction signal is trapped, attached to the offending process and go in an endless loop, waiting. #### BOX64_TRACE * -Only on build with trace enabled. Trace allow the logging of all instruction executed, along with register dump - * 0 : No trace. (Default.) - * 1 : Trace enabled. Trace start after the initialisation of all depending libraries is done. - * symbolname : Trace only `symbolname` (trace is disable if the symbol is not found). + +Only available on box64 build with trace. Adds trace of all instructions executed, along with a register dump. + * 0 : No trace. (default) + * 1 : Enable trace. Trace starts after all dependencies are initialized. + * symbolname : Trace only `symbolname` (if the symbol was found). * 0xXXXXXXX-0xYYYYYYY : Trace only between the 2 addresses. #### BOX64_TRACE_INIT * -Use BOX64_TRACE_INIT instead of BOX64_TRACE to start trace before the initialisation of libraries and the running program - * 0 : No trace. (Default.) - * 1 : Trace enabled. The trace start with the initialisation of all depending libraries is done. + +Same as BOX64_TRACE but starts the trace immediately. + * 0 : No trace. (default) + * 1 : Trace enabled. The trace starts before the initialization of dependencies. #### BOX64_TRACE_START * -Only on builds with trace enabled. + +Only available on box64 build with trace. * NNNNNNN : Start trace only after NNNNNNNN opcode execute (number is an `uint64_t`). #### BOX64_TRACE_XMM * -Only on builds with trace enabled. - * 0 : The XMM (i.e. SSE/SSE2) register will not be logged with the general and x86 registers. (Default.) + +Only available on box64 build with trace. + * 0 : The XMM (i.e. SSE/SSE2) register will not be logged with the general and x86 registers. (default) * 1 : Dump the XMM registers. #### BOX64_TRACE_EMM * -Only on builds with trace enabled. - * 0 : The EMM (i.e. MMX) register will not be logged with the general and x86 registers. (Default.) + +Only available on box64 build with trace. + * 0 : The EMM (i.e. MMX) register will not be logged with the general and x86 registers. (default) * 1 : Dump the EMM registers. #### BOX64_TRACE_COLOR * -Only on builds with trace enabled. - * 0 : The general registers will always be the default white color. (Default.) + +Only available on box64 build with trace. + * 0 : The general registers will always be the default white color. (default) * 1 : The general registers will change color in the dumps when they changed value. -#### BOX64_LOAD_ADDR * -Try to load at 0xXXXXXX main binary (if binary is a PIE) - * 0xXXXXXXXX : The load address . (Only active on PIE programs.) +#### BOX64_DYNAREC * -#### BOX64_NOSIGSEGV * -Disable handling of SigSEGV. (Very useful for debugging.) - * 0 : Let the x86 program set sighandler for SEGV (Default.) - * 1 : Disable the handling of SigSEGV. +Enable Box64 DynaRec. + * 0 : Disable Dynarec. + * 1 : Enable Dynarec. (default) -#### BOX64_NOSIGILL * -Disable handling of SigILL (to ease debugging mainly). - * 0 : Let x86 program set sighandler for Illegal Instruction - * 1 : Disables the handling of SigILL +#### BOX64_DYNAREC_LOG * -#### BOX64_SHOWSEGV * -Show Segfault signal even if a signal handler is present - * 0 : Don"t force show the SIGSEGV analysis (Default.) - * 1 : Show SIGSEGV detail, even if a signal handler is present +Set the level of DynaRec logs. + * 0 : NONE : No logs. (default) + * 1 : INFO : Minimal logs. (only unimplemented OpCodes). + * 2 : DEBUG : Debug Logs for Dynarec (with details on block created / executed). + * 3 : VERBOSE : All of the above plus more. -#### BOX64_SHOWBT * -Show some Backtrace (Native and Emulated) when a signal (SEGV, ILL or BUS) is caught - * 0 : Don"t show backtraces (Default.) - * 1 : Show Backtrace detail (for native, box64 is rename as the x86_64 binary run) +#### BOX64_DYNAREC_TRACE * + +Enable the trace for generated code. + * 0 : Disable trace for generated code. (default) + * 1 : Enable trace for generated code (like regular trace, slows down the program a lot and generates huge logs). + +#### BOX64_DYNAREC_DUMP * + +Enable Box64 DynaRec dump. + * 0 : Do not dump DynaRec blocks. (default) + * 1 : Enable DynaRec blocks dump. + * 2 : Enable DynaRec blocks dump with some colors. + +#### BOX64_DYNAREC_MISSING * + +Print missing opcodes. + * 0 : Do not print the missing opcode. (default, unless DYNAREC_LOG>=1 or DYNAREC_DUMP>=1 is used) + * 1 : Print missing opcodes. + * 2 : Print the fallback to scalar opcodes. (only valid on RISC-V) + +#### BOX64_NODYNAREC * + +Forbid dynablock creation in the interval specified. (helpful for debugging behaviour difference between Dynarec and Interpreter) + * 0xXXXXXXXX-0xYYYYYYYY : the interval where dynablock cannot start. (inclusive-exclusive) + +#### BOX64_DYNAREC_TEST * + +Enable DynaRec execution comparison with the interpreter. (super slow, only for testing) + * 0 : No comparison. (default) + * 1 : Each opcode runs on interpreter and on Dynarec, regs and memory are compared and printed when they differ. + * 0xXXXXXXXX-0xYYYYYYYY : define the interval where dynarec is tested (inclusive-exclusive) + +#### BOX64_DYNAREC_GDBJIT * + +The GDBJIT debugging support, only available on build with `-DGDBJIT=ON`, enable it with gdb command: jit-reader-load /usr/local/lib/libbox64gdbjitreader.so. + * 0 : Dynarec will not generate GDBJIT debuginfo. (default) + * 1 : Dynarec will generate GDBJIT debuginfo. + * 2 : Dynarec will generate detailed GDBJIT debuginfo with internal state. + +#### BOX64_DYNAREC_PERFMAP * + +Generate map file for Linux perf tool. + * 0 : Dynarec will not generate perf map. (default) + * 1 : Dynarec will generate perf map. + +---- + +### Compatibility #### BOX64_X11THREADS * + Call XInitThreads when loading X11. (This is mostly for old Loki games with the Loki_Compat library.) - * 0 : Don't force call XInitThreads. (Default.) + * 0 : Do not force call XInitThreads. (default) * 1 : Call XInitThreads as soon as libX11 is loaded. #### BOX64_MMAP32 * -Will use 32bits address in priority for external MMAP (when 32bits process are detected) + +Use 32bit address in priority for external MMAP. * 0 : Use regular mmap (default, except for Snapdragron build) - * 1 : Use 32bits address space mmap in priority for external mmap as soon a 32bits process are detected (default for SnapDragon and TegraX1 build) + * 1 : Use 32bits address space mmap in priority for external mmap when 32bit process is detected (default for Snapdragon and TegraX1 build) #### BOX64_IGNOREINT3 * -What to do when a CC INT3 opcode is encounter in the code being run - * 0 : Trigger a TRAP signal if a handler is present - * 1 : Just skip silently the opcode + +Controls behaviour when a CC INT3 opcode is encountered. + * 0 : Trigger a TRAP signal if a handler is present. (default) + * 1 : Just skip silently the opcode. #### BOX64_X11GLX * -Force libX11's GLX extension to be present. -* 0 : Do not force libX11's GLX extension to be present. -* 1 : GLX will always be present when using XQueryExtension. (Default.) -#### BOX64_DYNAREC_DUMP * -Enables/disables Box64's Dynarec's dump. - * 0 : Disable Dynarec's blocks dump. (Default.) - * 1 : Enable Dynarec's blocks dump. - * 2 : Enable Dynarec's blocks dump with some colors. +Force Xorg GLX extension to be present. + * 0 : Do not force GLX extension to be present. + * 1 : Require Xorg GLX extension when using XQueryExtension. (default) -#### BOX64_DYNAREC_LOG * -Set the level of DynaRec's logs. - * 0 : NONE : No Logs for DynaRec. (Default.) - * 1 :INFO : Minimum Dynarec Logs (only unimplemented OpCode). - * 2 : DEBUG : Debug Logs for Dynarec (with details on block created / executed). - * 3 : VERBOSE : All of the above plus more. +#### BOX64_SSE_FLUSHTO0 * -#### BOX64_DYNAREC * -Enables/Disables Box64's Dynarec. - * 0 : Disables Dynarec. - * 1 : Enable Dynarec. (Default.) +Behaviour of SSE Flush to 0 flags. + * 0 : Just track the flag. (default) + * 1 : Apply SSE Flush to 0 flag directly. -#### BOX64_DYNAREC_TRACE * -Enables/Disables trace for generated code. - * 0 : Disable trace for generated code. (Default.) - * 1 : Enable trace for generated code (like regular Trace, this will slow down the program a lot and generate huge logs). +#### BOX64_X87_NO80BITS * -#### BOX64_NODYNAREC * -Forbid dynablock creation in the interval specified (helpful for debugging behaviour difference between Dynarec and Interpreter) - * 0xXXXXXXXX-0xYYYYYYYY : define the interval where dynablock cannot start (inclusive-exclusive) +Behavoiur of x87 80bits long double. + * 0 : Try to handle 80bits long double as precise as possible. (default) + * 1 : Handle them as double. -#### BOX64_DYNAREC_TEST * -Dynarec will compare it's execution with the interpreter (super slow, only for testing) - * 0 : No comparison. (Default.) - * 1 : Each opcode runs on interpreter and on Dynarec, and regs and memory are compared and print if different. - * 0xXXXXXXXX-0xYYYYYYYY : define the interval where dynarec is tested (inclusive-exclusive) +#### BOX64_MAXCPU + +Maximum CPU Cores exposed. + * 0 : Do not cap the number of cpu core exposed. (default) + * XXX : Cap the maximum CPU Core exposed to XXX. (usefull with wine64 or GridAutosport for example) + +#### BOX64_SYNC_ROUNDING * + +Sync rounding mode with fesetround/fegetround. + * 0 : Disable rounding mode syncing. (default) + * 1 : Enable rounding mode syncing. + +#### BOX64_SDL2_JGUID * + +Use a workaround for SDL_GetJoystickGUIDInfo function for wrapped SDL2. + * 0 : Don't do anything special. + * 1 : Use a workaround for program that use the private SDL_GetJoystickGUIDInfo function with 1 missing argument. + +#### BOX64_MALLOC_HACK * + +Behaviour when hooking malloc operators. + * 0 : Don't allow malloc operator to be redirected, rewriting code to use regular function. (default) + * 1 : Allow malloc operator to be redirected. (not advised) + * 2 : Like 0, but track special mmap / free (some redirected functions are inlined and cannot be redirected). + +#### BOX64_SHAEXT * + +Expose SHAEXT (a.k.a. SHA_NI) capabilities. + * 0 : Do not expose SHAEXT capabilities. + * 1 : Expose SHAEXT capabilities. (default) + +#### BOX64_SSE42 * + +Expose SSE 4.2 capabilities. + * 0 : Do not expose SSE 4.2 capabilities. (default when libjvm is detected) + * 1 : Expose SSE 4.2 capabilities. (default) + +#### BOX64_FUTEX_WAITV * + +Expose futex_waitv syscall. + * 0 : Report as unsupported. (default for BAD_SIGNAL build) + * 1 : Let program use futex_waitv. (default) + +#### BOX64_RESERVE_HIGH * + +* 0 : Do not try to pre-reserve high memory (beyond 47bits) (default) +* 1 : Try to reserve (without allocating it) memory beyond 47bits (seems unstable) + +#### BOX64_WRAP_EGL * + +Prefer wrapped libs for EGL and GLESv2. + * 0 : Emulated libs are preferred. (default) + * 1 : Native libs are preferred. + +#### BOX64_CRASHHANDLER * + +Use a dummy crashhandler.so library. + * 0 : Use emulated crashhandler.so library if needed. + * 1 : Use an internal dummy (completely empty) crashhandler.so library. (default) + +#### BOX64_NOPULSE * + +Do not load pulseaudio libraries. + * 0 : Load pulseaudio libraries if found. (default) + * 1 : Disables the load of pulse audio libraries, both native and x86_64. (libpulse and libpulse-simple) + +#### BOX64_NOGTK * + +Do not load wrapped GTK libraries. + * 0 : Load wrapped GTK libraries. (default) + * 1 : Disable loading of wrapped GTK libraries. + +#### BOX64_NOVULKAN * + +Do not load vulkan libraries. + * 0 : Load vulkan libraries if found. (default) + * 1 : Disables loading of vulkan libraries, both native and x86_64. (can be useful on Pi4, where the vulkan driver is not quite there yet.) + +---- + +### DynaRec optimizations #### BOX64_DYNAREC_BIGBLOCK * -Enables/Disables Box64's Dynarec building BigBlock. - * 0 : Don't try to build block as big as possible (can help program using lots of thread and a JIT, like C#/Unity) (Default when libmonobdwgc-2.0.so is loaded) - * 1 : Build Dynarec block as big as possible (Default.) - * 2 : Build Dynarec block bigger (don't stop when block overlaps, but only for blocks in elf memory) - * 3 : Build Dynarec block bigger (don't stop when block overlaps, for all type of memory) + +Enable building bigger DynaRec blocks for performance. + * 0 : Do not try to build block as big as possible (can help program using lots of threads and JIT, like C#/Unity) (default when libmonobdwgc-2.0.so is loaded) + * 1 : Build Dynarec block as big as possible. (default) + * 2 : Build Dynarec block bigger (do not stop when block overlaps, but only for blocks in elf memory) + * 3 : Build Dynarec block bigger (do not stop when block overlaps, for all type of memory) #### BOX64_DYNAREC_FORWARD * -Define Box64's Dynarec max allowed forward value when building Block. - * 0 : No forward value. When current block end, don't try to go further even if there are previous forward jumps - * XXX : Allow up to XXXX bytes of gap when building a Block after the block end to next forward jump (Default: 128) + +Define max allowed forward value when building block. + * 0 : No forward value. When current block ends, do not try to go further even if there are previous forward jumps + * XXX : Allow up to XXXX bytes of gap between end of the block and the next forward jump (default: 128) #### BOX64_DYNAREC_STRONGMEM * -Enable/Disable simulation of Strong Memory model -* 0 : Don't try anything special (Default.) -* 1 : Enable some memory barriers when writing to memory to simulate the Strong Memory Model in a limited way (Default when libmonobdwgc-2.0.so is loaded) -* 2 : All 1. plus memory barriers on SIMD instructions -* 3 : All 2. plus more memory barriers on a regular basis + +Enable simulation of Strong Memory model. + * 0 : Do not try anything special (default) + * 1 : Enable some memory barriers when writing to memory to simulate the Strong Memory Model in a limited way (default when libmonobdwgc-2.0.so is loaded) + * 2 : All 1. plus memory barriers on SIMD instructions + * 3 : All 2. plus more memory barriers on a regular basis #### BOX64_DYNAREC_WEAKBARRIER * -Tweaking the memory barriers to reduce the performance impact by STRONGMEM -* 0 : Use regular safe barrier (Default.) -* 1 : Use weak barriers to have more performance boost -* 2 : All 1. Plus disabled the last write barriers + +Tweak the memory barriers to reduce the performance impact by STRONGMEM. + * 0 : Use regular safe barrier. (default) + * 1 : Use weak barriers to have more performance boost. + * 2 : All 1. Plus disabled the last write barriers. #### BOX64_DYNAREC_PAUSE * -Enable/Disable x86 PAUSE emulation, which may help the performance of spinlocks -* 0 : Ignore x86 PAUSE instruction (Default.) -* 1 : Use YIELD to emulate x86 PAUSE instruction -* 2 : Use WFI to emulate x86 PAUSE instruction -* 3 : Use SEVL+WFE to emulate x86 PAUSE instruction + +Enable x86 PAUSE emulation, that helps the performance of spinlocks. + * 0 : Ignore x86 PAUSE instruction. (default) + * 1 : Use YIELD to emulate x86 PAUSE instruction. + * 2 : Use WFI to emulate x86 PAUSE instruction. + * 3 : Use SEVL+WFE to emulate x86 PAUSE instruction. #### BOX64_DYNAREC_X87DOUBLE * -Force the use of Double for x87 emulation -* 0 : Try to use float when possible for x87 emulation (default, faster) -* 1 : Only use Double for x87 emulation (slower, may be needed for some specific games, like Crysis) + +Force the use of Double for x87 emulation. + * 0 : Try to use float when possible for x87 emulation. (default, faster) + * 1 : Only use Double for x87 emulation. (slower, may be needed for some specific games, like Crysis) #### BOX64_DYNAREC_FASTNAN * -Enable/Disable generation of -NAN -* 0 : Generate -NAN like on x86 -* 1 : Don't do anything special with NAN, to go as fast as possible (default, faster) + +Generate x86 -NAN. + * 0 : Generate -NAN like on x86. + * 1 : Do not do anything special with NAN, to go as fast as possible. (default, faster) #### BOX64_DYNAREC_FASTROUND * -Enable/Disable generation of precise x86 rounding -* 0 : Generate float/double -> int rounding like on x86 -* 1 : Don't do anything special with edge case Rounding, to go as fast as possible (no INF/NAN/Overflow -> MIN_INT conversion) (default, faster) -* 2 : Everything from 1 plus also fast round of double->float (not taking into account current rounding mode) + +Generate precise x86 rounding. + * 0 : Generate float/double -> int rounding like on x86. + * 1 : Do not do anything special with edge case Rounding, to go as fast as possible (no INF/NAN/Overflow -> MIN_INT conversion). (default, faster) + * 2 : Everything from 1 plus also fast round of double->float (not taking into account current rounding mode). #### BOX64_DYNAREC_SAFEFLAGS * -Handling of flags on CALL/RET opcodes -* 0 : Treat CALL/RET as if it never needs any flags (faster but not advised) -* 1 : most of RET will need flags, most of CALLS will not (Default) -* 2 : All CALL/RET will need flags (slower, but might be needed. Automatically enabled for Vara.exe) + +Behaviour of flags on CALL/RET opcodes. + * 0 : Treat CALL/RET as if it never needs any flags (faster but not advised) + * 1 : most of RET will need flags, most of CALLS will not (default) + * 2 : All CALL/RET will need flags (slower, but might be needed. Automatically enabled for Vara.exe) #### BOX64_DYNAREC_CALLRET * -Optimisation of CALL/RET opcodes (not compatible with jit/dynarec/smc) -* 0 : Don't optimize CALL/RET, use Jump Table for boths (Default) -* 1 : Try to optimized CALL/RET, skipping the use of the JumpTable when possible + +Optimize CALL/RET opcodes. + * 0 : Do not optimize CALL/RET, use Jump Table. (default) + * 1 : Try to optimize CALL/RET, skipping the JumpTable when possible. #### BOX64_DYNAREC_ALIGNED_ATOMICS * -Generated code for aligned atomics only -* 0 : The code generated can handle unaligned atomics (Default) -* 1 : Generated code only for aligned atomics (faster and less code generated, but will SEGBUS if LOCK prefix is unused on unaligned data) -#### BOX64_DYNAREC_NATIVEFLAGS * -Generate code will use native flags if possible -* 0 : The code generated whill not use native flags even when possible -* 1 : Generated code will use native flags when possible (Default) +Generate code for aligned atomics only. + * 0 : Add handling of unaligned atomics. (default) + * 1 : Generate code for aligned atomics only (faster and less code is generated, but will SEGBUS if LOCK prefix is unused on unaligned data). -#### BOX64_DYNAREC_BLEEDING_EDGE * -Detect MonoBleedingEdge and apply conservative settings -* 0 : Don't detect MonoBleedingEdge -* 1 : Detect MonoBleedingEdge, and apply BIGBLOCK=0 STRONGMEM=1 if detected (Default) +#### BOX64_DYNAREC_NATIVEFLAGS * -#### BOX64_DYNAREC_JVM * -Detect libjvm and apply conservative settings. Obsolete, use BOX64_JVM instead. -* 0 : Don't detect libjvm -* 1 : Detect libjvm, and apply BIGBLOCK=0 STRONGMEM=1 SSE42=0 if detected (Default) +Use native ARM flags when possible. + * 0 : Do not use native flags. + * 1 : Use native flags when possible. (default) #### BOX64_DYNAREC_WAIT * -Behavior with FillBlock is not available (FillBlock build Dynarec blocks and is not multithreaded) -* 0 : Dynarec will not wait for FillBlock to ready and use Interpreter instead (might speedup a bit massive multithread or JIT programs) -* 1 : Dynarec will wait for FillBlock to be ready (Default) -#### BOX64_DYNAREC_GDBJIT * -The GDBJIT debugging support, only available with the compilation option GDBJIT=ON, enable it with gdb command: jit-reader-load /usr/local/lib/libbox64gdbjitreader.so. -* 0 : Dynarec will not generate GDBJIT debuginfo. (Default) -* 1 : Dynarec will generate GDBJIT debuginfo. -* 2 : Dynarec will generate detailed GDBJIT debuginfo with internal state. +Wait for FillBlock to be ready (FillBlock builds Dynarec blocks and is not multithreaded). + * 0 : Do not wait for FillBlock to ready and use Interpreter instead (might speedup a bit massive multithread or JIT programs). + * 1 : Wait for FillBlock to be ready. (default, mostly faster) -#### BOX64_DYNAREC_PERFMAP * -Dynarec generate map file for Linux perf tool. -* 0 : Dynarec will not generate perf map. (Default) -* 1 : Dynarec will generate perf map. +### Detection -#### BOX64_DYNAREC_MISSING * -Dynarec print the missing opcodes -* 0 : not print the missing opcode (Default, unless DYNAREC_LOG>=1 or DYNAREC_DUMP>=1 is used) -* 1 : Will print the missing opcodes -* 2 : Will print the fallback to scalar opcodes (only valid on RISC-V) - -#### BOX64_SSE_FLUSHTO0 * -Handling of SSE Flush to 0 flags -* 0 : Just track the flag (Default) -* 1 : Direct apply of SSE Flush to 0 flag +#### BOX64_DYNAREC_BLEEDING_EDGE * -#### BOX64_X87_NO80BITS * -Handling of x87 80bits long double -* 0 : Try to handle 80bits long double as precise as possible (Default) -* 1 : Handle them as double +Detect MonoBleedingEdge and apply conservative settings. + * 0 : Do not detect MonoBleedingEdge. + * 1 : Detect MonoBleedingEdge and apply BIGBLOCK=0 STRONGMEM=1 when detected. (default) -#### BOX64_MAXCPU -Maximum CPU Core exposed -* 0 : Don't cap the number of cpu core exposed (Default) -* XXX : Cap the maximum CPU Core exposed to XXX (usefull with wine64 or GridAutosport for example) +#### BOX64_DYNAREC_JVM * -#### BOX64_SYNC_ROUNDING * -Box64 will sync rounding mode with fesetround/fegetround. -* 0 : Disable rounding mode syncing. (Default.) -* 1 : Enable rounding mode syncing. +Detect libjvm and apply conservative settings. Obsolete, use BOX64_JVM instead. + * 0 : Do not detect libjvm. + * 1 : Detect libjvm and apply BIGBLOCK=0 STRONGMEM=1 SSE42=0 when detected. (default) #### BOX64_LIBCEF * -Detect libcef and apply malloc_hack settings -* 0 : Don't detect libcef -* 1 : Detect libcef, and apply MALLOC_HACK=2 if detected (Default) + +Detect libcef and apply malloc_hack settings. + * 0 : Don't do anything special. + * 1 : Detect libcef, and apply MALLOC_HACK=2 if detected. (default) #### BOX64_JVM * -Detect libjvm and apply conservative settings -* 0 : Don't detect libjvm -* 1 : Detect libjvm, and apply BIGBLOCK=0 STRONGMEM=1 SSE42=0 if detected (Default) + +Detect libjvm and apply conservative settings. + * 0 : Don't do anything special. + * 1 : Detect libjvm, and apply BIGBLOCK=0 STRONGMEM=1 SSE42=0 if detected. (default) #### BOX64_UNITYPLAYER * -Detect UnityPlayer.dll and apply strongmem settings -* 0 : Don't detect UnityPlayer.dll -* 1 : Detect UnityPlayer.dll, and apply BOX64_DYNAREC_STRONGMEM=1 if detected (Default) -#### BOX64_SDL2_JGUID * -Need a workaround for SDL_GetJoystickGUIDInfo function for wrapped SDL2 -* 0 : Don't use any workaround -* 1 : Use a workaround for program that use the private SDL_GetJoystickGUIDInfo function with 1 missing argument +Detect UnityPlayer.dll and apply strongmem settings. + * 0 : Don't do anything special. + * 1 : Detect UnityPlayer.dll, and apply BOX64_DYNAREC_STRONGMEM=1 if detected. (default) -#### BOX64_LIBGL * - * libXXXX set the name for libGL (defaults to libGL.so.1). - * /PATH/TO/libGLXXX : Sets the name and path for libGL - You can also use SDL_VIDEO_GL_DRIVER +---- + +### Paths and libraries + +#### BOX64_LD_LIBRARY_PATH * + +Path to look for x86_64 libraries. Default is current folder and `lib` in current folder. +Also, `/usr/lib/x86_64-linux-gnu`, `/lib/x86_64-linux-gnu` and `/usr/lib/box64-x86_64-linux-gnu` are added if they exist. #### BOX64_LD_PRELOAD + * XXXX[:YYYYY] force loading XXXX (and YYYY...) libraries with the binary PreLoaded libs can be emulated or native, and are treated the same way as if they were coming from the binary + +#### BOX64_PATH * + +Path to look for x86_64 executable. Default is current folder and `bin` in current folder. + +#### BOX64_BASH * + +Specify path to x86_64 bash to launch scripts. + * yyyy + Will use yyyy as x86_64 bash to launch script. yyyy needs to be a full path to a valid x86_64 version of bash + +#### BOX64_LIBGL * + + * libXXXX set the name for libGL. (defaults to libGL.so.1). + * /PATH/TO/libGLXXX : Sets the name and path for libGL. + Has similar action to SDL_VIDEO_GL_DRIVER. #### BOX64_EMULATED_LIBS * + * XXXX[:YYYYY] force lib XXXX (and YYYY...) to be emulated (and not wrapped) -Some games uses an old version of some libraries, with an ABI incompatible with native version. +Some games use old versions of libraries, with ABI incompatible with native version. Note that LittleInferno for example is auto detected, and libvorbis.so.0 is automatically added to emulated libs, and same for Don't Starve (and Together / Server variant) that use an old SDL2 too #### BOX64_ALLOWMISSINGLIBS * + Allow Box64 to continue even if a library is missing. - * 0 : Box64 will stop if a library cannot be loaded. (Default.) + * 0 : Box64 will stop if a library cannot be loaded. (default) * 1 : Continue even if a needed library cannot be loaded. Unadvised, this will, in most cases, crash later on. #### BOX64_PREFER_WRAPPED * -Box64 will use wrapped libs even if the lib is specified with absolute path - * 0 : Try to use emulated libs when they are defined with absolute path (Default.) - * 1 : Use Wrapped native libs even if path is absolute - -#### BOX64_PREFER_EMULATED * -Box64 will prefer emulated libs first (except for glibc, alsa, pulse, GL, vulkan and X11 - * 0 : Native libs are preferred (Default.) - * 1 : Emulated libs are preferred (Default for program running inside pressure-vessel) -#### BOX64_WRAP_EGL * -Box64 will prefer wrapped libs for EGL and GLESv2 - * 0 : Emulated libs are preferred (Default) - * 1 : Native libs are preferred - -#### BOX64_CRASHHANDLER * -Box64 will use a dummy crashhandler.so library - * 0 : Use Emulated crashhandler.so library if needed - * 1 : Use an internal dummy (completely empty) crashhandler.so library (default) - -#### BOX64_MALLOC_HACK * -How Box64 will handle hooking of malloc operators - * 0 : Don't allow malloc operator to be redirected, rewriting code to use regular function (Default) - * 1 : Allow malloc operator to be redirected (not advised) - * 2 : Like 0, but track special mmap / free (some redirected functions were inlined and cannot be redirected) - -#### BOX64_NOPULSE * -Disables the load of pulseaudio libraries. - * 0 : Load pulseaudio libraries if found. (Default.) - * 1 : Disables the load of pulse audio libraries (libpulse and libpulse-simple), both the native library and the x86 library +Prefer wrapped libs first even if the lib is specified with absolute path. + * 0 : Try to use emulated libs when they are defined with absolute path. (default) + * 1 : Use Wrapped native libs even if path is absolute. -#### BOX64_NOGTK * -Disables the loading of wrapped GTK libraries. - * 0 : Load wrapped GTK libraries if found. (Default.) - * 1 : Disables loading wrapped GTK libraries. - -#### BOX64_NOVULKAN * -Disables the load of vulkan libraries. - * 0 : Load vulkan libraries if found. - * 1 : Disables the load of vulkan libraries, both the native and the i386 version (can be useful on Pi4, where the vulkan driver is not quite there yet.) - -#### BOX64_SHAEXT * -Expose or not SHAEXT (a.k.a. SHA_NI) capabilities - * 0 : Do not expose SHAEXT capabilities - * 1 : Expose SHAEXT capabilities (Default.) +#### BOX64_PREFER_EMULATED * -#### BOX64_SSE42 * -Expose or not SSE 4.2 capabilities - * 0 : Do not expose SSE 4.2 capabilities (default when libjvm is detected) - * 1 : Expose SSE 4.2 capabilities (Default.) +Prefer emulated libs first (except for glibc, alsa, pulse, GL, vulkan and X11). + * 0 : Native libs are preferred. (default) + * 1 : Emulated libs are preferred. (default for program running inside pressure-vessel) -#### BOX64_FUTEX_WAITV * -Use of the new fuext_waitc syscall - * 0 : Do not try to use it, return unsupported (Default for BAD_SIGNAL build) - * 1 : let program use the syscall if the host system support it (Default for other build) +---- -#### BOX64_BASH * -Define x86_64 bash to launch script - * yyyy - Will use yyyy as x86_64 bash to launch script. yyyy needs to be a full path to a valid x86_64 version of bash +### Rcfiles -#### BOX64_ENV * - * XXX=yyyy - will add XXX=yyyy env. var. +#### BOX64_ENV, BOX64_ENV1, BOX64_ENV2, ... * -#### BOX64_ENV1 * +Add XXX=yyyy env. var. * XXX=yyyy - will add XXX=yyyy env. var. and continue with BOX86_ENV2 ... until var doesn't exist - -#### BOX64_RESERVE_HIGH * -* 0 : Don't try to pe-reserve high memory (beyond 47bits) (Default) -* 1 : Try to reserve (without allocating it) memory beyond 47bits (seems unstable) - -#### BOX64_JITGDB * - * 0 : Just print the Segfault message on segfault (default) - * 1 : Launch `gdb` when a segfault, bus error or illegal instruction signal is trapped, attached to the offending process and go in an endless loop, waiting. - When in gdb, you need to find the correct thread yourself (the one with `my_box64signalhandler` in is stack) - then probably need to `finish` 1 or 2 functions (inside `usleep(..)`) and then you'll be in `my_box64signalhandler`, - just before the printf of the Segfault message. Then simply - `set waiting=0` to exit the infinite loop. - * 2 : Launch `gdbserver` when a segfault, bus error or illegal instruction signal is trapped, attached to the offending process, and go in an endless loop, waiting. - Use `gdb /PATH/TO/box64` and then `target remote 127.0.0.1:1234` to connect to the gdbserver (or use actual IP if not on the machine). After that, the procedure is the same as with ` BOX64_JITGDB=1`. - This mode can be usefull when programs redirect all console output to a file (like Unity3D Games) - * 3 : Launch `lldb` when a segfault, bus error or illegal instruction signal is trapped, attached to the offending process and go in an endless loop, waiting. #### BOX64_NORCFILES -If the env var exist, no rc files (like /etc/box64.box64rc and ~/.box64rc) will be loaded + +Disable loading rcfiles. #### BOX64_RCFILE -If the env var is set and file exists, this variable will be used as path to the box64rc file instead of default paths (BOX64_RCFILE is loaded first, default paths are not loaded) ----- +Specify custom rcfile path instead of default paths. (BOX64_RCFILE is loaded first, default paths are not loaded) -Those variables are only valid inside a rcfile: ---- +### Valid inside rcfiles only + #### BOX64_NOSANDBOX - * 0 : Nothing special - * 1 : Added "--no-sandbox" to command line arguments (usefull for chrome based programs) + +Add `--no-sandbox` to the command line arguments (useful for chrome based programs). #### BOX64_INPROCESSGPU - * 0 : Nothing special - * 1 : Added "--in-process-gpu" to command line arguments (usefull for chrome based programs) + +Add `--in-process-gpu` to the command line arguments (useful for chrome based programs). #### BOX64_CEFDISABLEGPU - * 0 : Nothing special - * 1 : Added "-cef-disable-gpu" to command line arguments (usefull for steamwebhelper/cef based programs) + +Add `-cef-disable-gpu` to the command line arguments (useful for steamwebhelper/cef based programs). #### BOX64_CEFDISABLEGPUCOMPOSITOR - * 0 : Nothing special - * 1 : Added "-cef-disable-gpu-compositor" to command line arguments (usefull for steamwebhelper/cef based programs) + +Add `-cef-disable-gpu-compositor` to the command line arguments (useful for steamwebhelper/cef based programs). #### BOX64_ARGS -If that var exist, it will be added as argument(s) to the command line if there is no current argument (it's ignored else). Note that "" are supported, but not '' + +Append arguments to the command line if there is no current argument. Note that "" are supported, but not ''. #### BOX64_INSERT_ARGS -If that var exist, it will be inserted as firsts argument(s) to the command line. Note that "" are supported, but not '' + +Prepend arguments to the command line. Note that "" are supported, but not ''. #### BOX64_EXIT - * 0 : Nothing special - * 1 : Just exit, don't try to run the program + +Just exit, do not try to run the program. diff --git a/src/box64context.c b/src/box64context.c index d88d853099..94df114205 100644 --- a/src/box64context.c +++ b/src/box64context.c @@ -303,7 +303,7 @@ void FreeBox64Context(box64context_t** context) if(--(*context)->forked >= 0) return; - box64context_t* ctx = *context; // local copy to do the cleanning + box64context_t* ctx = *context; // local copy to do the cleaning //clean_current_emuthread(); // cleaning main thread seems a bad idea if(ctx->local_maplib) diff --git a/src/core.c b/src/core.c index 655f9d9622..cf7c789345 100644 --- a/src/core.c +++ b/src/core.c @@ -609,7 +609,7 @@ void computeRDTSC() uint64_t freq = ReadTSCFrequency(NULL); if(freq<((box64_rdtsc_1ghz)?1000000000LL:1000000)) { box64_rdtsc = 1; - if(hardware) printf_log(LOG_INFO, "Hardware counter to slow (%d kHz), not using it\n", freq/1000); + if(hardware) printf_log(LOG_INFO, "Hardware counter is too slow (%d kHz), not using it\n", freq/1000); hardware = 0; freq = ReadTSCFrequency(NULL); } @@ -1808,8 +1808,8 @@ void endBox64() printf_log(LOG_DEBUG, "Calling atexit registered functions (exiting box64)\n"); CallAllCleanup(emu); printf_log(LOG_DEBUG, "Calling fini for all loaded elfs and unload native libs\n"); - //void closeAllDLOpenned(); - //closeAllDLOpenned(); // close residual dlopenned libs. Disabled, seems like a bad idea, better to unload with proper dependancies + //void closeAllDLOpened(); + //closeAllDLOpened(); // close residual dlopened libs. Disabled, seems like a bad idea, better to unload with proper dependancies RunElfFini(my_context->elfs[0], emu); // unload needed libs needed_libs_t* needed = my_context->elfs[0]->needed; diff --git a/src/dynarec/arm64/dynarec_arm64_helper.c b/src/dynarec/arm64/dynarec_arm64_helper.c index 3833644e77..2a51678ed5 100644 --- a/src/dynarec/arm64/dynarec_arm64_helper.c +++ b/src/dynarec/arm64/dynarec_arm64_helper.c @@ -2217,7 +2217,7 @@ static void fpuCacheTransform(dynarec_arm_t* dyn, int ninst, int s1, int s2, int neoncache_t cache = dyn->n; int s1_val = 0; int s2_val = 0; - // unload every uneeded cache + // unload every unneeded cache // ymm0 first int s3_top = 1; uint16_t to_purge = dyn->ymm_zero&~dyn->insts[i2].ymm0_in; @@ -2233,7 +2233,7 @@ static void fpuCacheTransform(dynarec_arm_t* dyn, int ninst, int s1, int s2, int } } s3_top = 0xffff; - // check SSE first, than MMX, in order, to optimise successive memory write + // check SSE first, than MMX, in order, to optimize successive memory write for(int i=0; i<16; ++i) { int j=findCacheSlot(dyn, ninst, NEON_CACHE_XMMW, i, &cache); if(j>=0 && findCacheSlot(dyn, ninst, NEON_CACHE_XMMW, i, &cache_i2)==-1) diff --git a/src/dynarec/dynarec_private.h b/src/dynarec/dynarec_private.h index 20a22f7c72..09ba152d5f 100644 --- a/src/dynarec/dynarec_private.h +++ b/src/dynarec/dynarec_private.h @@ -39,7 +39,7 @@ typedef struct instruction_x64_s { int jmp_insts; // instuction to jump to (-1 if out of the block) uint8_t jmp_cond:1; // 1 of conditionnal jump uint8_t has_next:1; // does this opcode can continue to the next? - uint8_t has_callret:1; // this instruction have an optimised call setup + uint8_t has_callret:1; // this instruction have an optimized call setup uint8_t alive:1; // this opcode gets executed (0 if dead code in that block) uint8_t barrier; // next instruction is a jump point, so no optim allowed uint8_t state_flags;// One of SF_XXX state diff --git a/src/dynarec/la64/dynarec_la64_helper.c b/src/dynarec/la64/dynarec_la64_helper.c index b6448035a2..3e62251744 100644 --- a/src/dynarec/la64/dynarec_la64_helper.c +++ b/src/dynarec/la64/dynarec_la64_helper.c @@ -1256,8 +1256,8 @@ static void fpuCacheTransform(dynarec_la64_t* dyn, int ninst, int s1, int s2, in lsxcache_t cache = dyn->lsx; int s1_val = 0; int s2_val = 0; - // unload every uneeded cache - // check SSE first, than MMX, in order, for optimisation issue + // unload every unneeded cache + // check SSE first, than MMX, in order, for optimization issue for (int i = 0; i < 16; ++i) { int j = findCacheSlot(dyn, ninst, LSX_CACHE_XMMW, i, &cache); if (j >= 0 && findCacheSlot(dyn, ninst, LSX_CACHE_XMMW, i, &cache_i2) == -1) diff --git a/src/dynarec/rv64/dynarec_rv64_helper.c b/src/dynarec/rv64/dynarec_rv64_helper.c index 8aa14e53c2..3b73d8b474 100644 --- a/src/dynarec/rv64/dynarec_rv64_helper.c +++ b/src/dynarec/rv64/dynarec_rv64_helper.c @@ -2620,7 +2620,7 @@ static void fpuCacheTransform(dynarec_rv64_t* dyn, int ninst, int s1, int s2, in int s1_val = 0; int s2_val = 0; // unload every unneeded cache - // check SSE first, than MMX, in order, for optimisation issue + // check SSE first, than MMX, in order, for optimization issue for (int i = 0; i < 16; ++i) { int j = findCacheSlot(dyn, ninst, EXT_CACHE_SS, i, &cache); if (j >= 0 && findCacheSlot(dyn, ninst, EXT_CACHE_SS, i, &cache_i2) == -1) diff --git a/src/elfs/elfloader32.c b/src/elfs/elfloader32.c index 53fc595e15..2fbef7d528 100644 --- a/src/elfs/elfloader32.c +++ b/src/elfs/elfloader32.c @@ -407,7 +407,7 @@ static int FindR386COPYRel(elfheader_t* h, const char* name, ptr_t *offs, uint32 if((t==R_386_COPY) && symname && !strcmp(symname, name) && (sym->st_size==size)) { int version2 = h->VerSym?((Elf32_Half*)((uintptr_t)h->VerSym+h->delta))[ELF32_R_SYM(rel[i].r_info)]:-1; if(version2!=-1) version2 &= 0x7fff; - if(version && !version2) version2=-1; // match a versionned symbol against a global "local" symbol + if(version && !version2) version2=-1; // match a versioned symbol against a global "local" symbol const char* vername2 = GetSymbolVersion(h, version2); Elf32_Half flags = GetSymbolVersionFlag(h, version2); int veropt2 = flags?0:1; diff --git a/src/include/box64context.h b/src/include/box64context.h index 575348bfb0..6c14e21922 100644 --- a/src/include/box64context.h +++ b/src/include/box64context.h @@ -138,7 +138,7 @@ typedef struct box64context_s { uintptr_t ep; // entry point lib_t *maplib; // lib and symbols handling - lib_t *local_maplib; // libs and symbols openned has local (only collection of libs, no symbols) + lib_t *local_maplib; // libs and symbols opened has local (only collection of libs, no symbols) dic_t *versym; // dictionnary of versioned symbols kh_mapsymbols_t *globdata; // GLOBAL_DAT relocation for COPY mapping in main elf kh_mapsymbols_t *uniques; // symbols with STB_GNU_UNIQUE bindings diff --git a/src/libtools/threads32.c b/src/libtools/threads32.c index ae4064402b..be7cf2f798 100755 --- a/src/libtools/threads32.c +++ b/src/libtools/threads32.c @@ -36,8 +36,8 @@ typedef void (*vFppp_t)(void*, void*, void*); typedef void (*vFpi_t)(void*, int); typedef int (*iFLi_t)(unsigned long, int); -//starting with glibc 2.34+, those 2 functions are in libc.so as versionned symbol only -// So use dlsym to get the symbol unversionned, as simple link will not work. +//starting with glibc 2.34+, those 2 functions are in libc.so as versioned symbol only +// So use dlsym to get the symbol unversioned, as simple link will not work. static vFppp_t real_pthread_cleanup_push_defer = NULL; static vFpi_t real_pthread_cleanup_pop_restore = NULL; // with glibc 2.34+, pthread_kill changed behaviour and might break some program, so using old version if possible @@ -447,7 +447,7 @@ EXPORT int my32___pthread_key_create(x64emu_t* emu, void* key, void* dtor) __att // phtread_cond_init with null attr seems to only write 1 (NULL) dword on x64, while it's 48 bytes on ARM. // Not sure why as sizeof(pthread_cond_init) is 48 on both platform... But Neverwinter Night init seems to rely on that // What about cond that are statically initialized? -// Note, this is is a versionned function (the pthread_cond_*), and this seems to correspond to an old behaviour +// Note, this is is a versioned function (the pthread_cond_*), and this seems to correspond to an old behaviour KHASH_MAP_INIT_INT(mapcond, pthread_cond_t*); diff --git a/src/wrapped/wrappedlibdl.c b/src/wrapped/wrappedlibdl.c index d8b73b34e3..81ee1ff687 100644 --- a/src/wrapped/wrappedlibdl.c +++ b/src/wrapped/wrappedlibdl.c @@ -174,7 +174,7 @@ void* my_dlopen(x64emu_t* emu, void *filename, int flag) box_free(tmp); box_free(platform); } - // check if alread dlopenned... + // check if already dlopened... for (size_t i=MIN_NLIB; ilib_sz; ++i) { if(dl->dllibs[i].full && IsSameLib(dl->dllibs[i].lib, rfilename)) { if(flag&0x4) { // don't re-open in RTLD_NOLOAD mode @@ -254,7 +254,7 @@ void* my_dlopen(x64emu_t* emu, void *filename, int flag) my_context->deferredInitSz = old_deferredInitSz; my_context->deferredInitCap = old_deferredInitCap; } else { - // check if already dlopenned... + // check if already dlopened... for (size_t i=MIN_NLIB; ilib_sz; ++i) { if(dl->dllibs[i].is_self) { ++dl->dllibs[i].count; @@ -667,7 +667,7 @@ EXPORT int my__dl_find_object(x64emu_t* emu, void* addr, my_dl_find_object_t* re return -1; } -void closeAllDLOpenned() +void closeAllDLOpened() { dlprivate_t *dl = my_context->dlprivate; actualy_closing = 1; @@ -691,7 +691,7 @@ void closeAllDLOpenned() else #define CUSTOM_FINI \ - closeAllDLOpenned(); + closeAllDLOpened(); // define all standard library functions #include "wrappedlib_init.h" diff --git a/src/wrapped32/wrappedlibc.c b/src/wrapped32/wrappedlibc.c index 7ddf854520..464d5af79a 100755 --- a/src/wrapped32/wrappedlibc.c +++ b/src/wrapped32/wrappedlibc.c @@ -931,7 +931,7 @@ EXPORT int my32___vsprintf_chk(x64emu_t* emu, void* buff, int flags, size_t len, return r; } -EXPORT int my32_vfscanf(x64emu_t* emu, void* stream, void* fmt, void* b) // probably uneeded to do a GOM, a simple wrap should enough +EXPORT int my32_vfscanf(x64emu_t* emu, void* stream, void* fmt, void* b) // probably unnecessary to do a GOM, a simple wrap should be enough { int n = myStackAlignScanf32((const char*)fmt, (uint32_t*)b, emu->scratch, N_SCRATCH); PREPARE_VALIST_32; diff --git a/src/wrapped32/wrappedlibdl.c b/src/wrapped32/wrappedlibdl.c index c3a79feb54..6556f9a358 100755 --- a/src/wrapped32/wrappedlibdl.c +++ b/src/wrapped32/wrappedlibdl.c @@ -151,7 +151,7 @@ EXPORT int my32__dl_find_object(x64emu_t* emu, void* addr, my_dl_find_object_t* // if(!box32_isglibc234) setNeededLibs(lib, 1, "libc.so.6"); -void closeAllDLOpenned(); +void closeAllDLOpened(); #define PRE_INIT\ if(1) \ @@ -159,7 +159,7 @@ void closeAllDLOpenned(); else #define CUSTOM_FINI \ - closeAllDLOpenned(); + closeAllDLOpened(); // define all standard library functions #include "wrappedlib_init32.h" diff --git a/tests32/test21.c b/tests32/test21.c index cc003ffce5..332ed3a3fd 100644 --- a/tests32/test21.c +++ b/tests32/test21.c @@ -24,7 +24,7 @@ int main(int argc, char **argv) { void* v1 = dlopen("test21_v1.so", RTLD_NOW); void* v2 = dlopen("test21_v2.so", RTLD_NOW); if(!v1 || !v2) { - printf("Error openning libs: v1=%p, v2=%p\n", v1, v2); + printf("Error openning libs: v1=%p, v2=%p\n", v1, v2); // typo: opening exit(-1); } iFv_t returnVersion = (iFv_t)dlsym(v2, "returnVersion");