diff options
| -rw-r--r-- | docs/USAGE.md | 1212 | ||||
| -rw-r--r-- | docs/box64.pod | 840 | ||||
| -rw-r--r-- | docs/gen/gen.py | 106 | ||||
| -rw-r--r-- | docs/gen/usage.json | 1605 | ||||
| -rw-r--r-- | src/include/env.h | 2 |
5 files changed, 2921 insertions, 844 deletions
diff --git a/docs/USAGE.md b/docs/USAGE.md index 98b77696..bc4a69cd 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -1,545 +1,667 @@ - -Usage ----- - -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 * - -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: 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_NOBANNER - -Disables printing box64 version and build. - * 0 : Print the banner. (default) - * 1 : Do not print the banner. - -#### BOX64_DLSYM_ERROR * - -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`. -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 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 * - -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 available on box64 build with trace. - * NNNNNNN : Start trace only after NNNNNNNN opcode execute (number is an `uint64_t`). - -#### BOX64_TRACE_XMM * - -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 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 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_DYNAREC * - -Enable Box64 DynaRec. - * 0 : Disable Dynarec. - * 1 : Enable Dynarec. (default) - -#### BOX64_DYNAREC_LOG * - -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_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 : Do not force call XInitThreads. (default) - * 1 : Call XInitThreads as soon as libX11 is loaded. - -#### BOX64_MMAP32 * - -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 when 32bit process is detected (default for Snapdragon and TegraX1 build) - -#### BOX64_IGNOREINT3 * - -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 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_SSE_FLUSHTO0 * - -Behaviour of SSE Flush to 0 flags. - * 0 : Just track the flag. (default) - * 1 : Apply SSE Flush to 0 flag directly. - -#### BOX64_X87_NO80BITS * - -Behavoiur of x87 80bits long double. - * 0 : Try to handle 80bits long double as precise as possible. (default) - * 1 : Handle them as double. - -#### 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_RDTSC_1GHZ - -Use hardware counter for rdtsc if available. -* 0 : Use hardware counter for rdtsc opcode if available (default) -* 1 : Use hardware counter for rdtsc if available and only if precision is at least 1GHz - -#### 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.) - -#### BOX64_ARG0 -Define argv[0] of the executable. - * yyyy -Will rewrite argv[0] instead of using program path. - ----- - -### DynaRec optimizations - -#### BOX64_DYNAREC_BIGBLOCK * - -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 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 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 * - -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 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) - -#### BOX64_DYNAREC_FASTNAN * - -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 * - -Generate precise x86 rounding. - * 0 : Generate float/double -> int rounding and use current rounding mode for float/double computation 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, and no non-default rounding modes). (default, faster) - * 2 : Everything from 1 plus also fast round of double->float (not taking into account current rounding mode). - -#### BOX64_DYNAREC_SAFEFLAGS * - -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 * - -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 * - -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_NATIVEFLAGS * - -Use native ARM flags when possible. - * 0 : Do not use native flags. - * 1 : Use native flags when possible. (default) - -#### BOX64_DYNAREC_WAIT * - -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_DIRTY * - -Allow continue running a block that is unprotected and potentially dirty - * 0 : Do not allow conitnuing to run a dynablock that gets unprotected (default) - * 1 : Allow continue to run a dynablock that write data in the same page the code is. It can get faster loading time of some game but can also get unexpected crash. - -### Detection - -#### BOX64_DYNAREC_BLEEDING_EDGE * - -Detect MonoBleedingEdge and apply conservative settings. - * 0 : Do not detect MonoBleedingEdge. - * 1 : Detect MonoBleedingEdge and apply BIGBLOCK=0 STRONGMEM=1 when detected. (default) - -#### BOX64_LIBCEF * - -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 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 do anything special. - * 1 : Detect UnityPlayer.dll, and apply BOX64_DYNAREC_STRONGMEM=1 if detected. (default) - ----- - -### 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 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) - * 1 : Continue even if a needed library cannot be loaded. Unadvised, this will, in most cases, crash later on. - -#### BOX64_PREFER_WRAPPED * - -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_PREFER_EMULATED * - -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) - ----- - -### Rcfiles - -#### BOX64_ENV, BOX64_ENV1, BOX64_ENV2, ... * - -Add XXX=yyyy env. var. - * XXX=yyyy - -#### BOX64_NORCFILES - -Disable loading rcfiles. - -#### BOX64_RCFILE - -Specify custom rcfile path instead of default paths. (BOX64_RCFILE is loaded first, default paths are not loaded) - ----- - -### Valid inside rcfiles only - -#### BOX64_NOSANDBOX - -Add `--no-sandbox` to the command line arguments (useful for chrome based programs). - -#### BOX64_INPROCESSGPU - -Add `--in-process-gpu` to the command line arguments (useful for chrome based programs). - -#### BOX64_CEFDISABLEGPU - -Add `-cef-disable-gpu` to the command line arguments (useful for steamwebhelper/cef based programs). - -#### BOX64_CEFDISABLEGPUCOMPOSITOR - -Add `-cef-disable-gpu-compositor` to the command line arguments (useful for steamwebhelper/cef based programs). - -#### BOX64_ARGS - -Append arguments to the command line if there is no current argument. Note that "" are supported, but not ''. - -#### BOX64_INSERT_ARGS - -Prepend arguments to the command line. Note that "" are supported, but not ''. - -#### BOX64_EXIT - -Just exit, do not try to run the program. +<!--- This file is generated by gen.py, do not edit it directly. --> +Usage +---- + +There are many environment variables to control Box64's behaviour. + +## Configuration files + +In addition to environment variables, Box64 also looks for 2 places for rcfile: `/etc/box64.box64rc` and `~/.box64rc`, in the format of .ini files. +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` > environment variables. + +---- + +## Libraries + +### BOX64_ADDLIBS + +Add extras to the needed libraries list, rarely needed. + + * XXXX: Add library XXXX to the needed libraries list. + * XXXX:YYYY:ZZZZ: Add library XXXX, YYYY and ZZZZ to the needed libraries list. + +### BOX64_ALLOWMISSINGLIBS + +Allow missing libraries to be ignored. + + * 0: Do not allow missing libraries. [Default] + * 1: Allow missing libraries. + +### BOX64_EMULATED_LIBS + +Force the use of emulated libraries. + + * XXXX: Force the use of emulated library XXXX. + * XXXX:YYYY:ZZZZ: Force the use of emulated libraries XXXX, YYYY and ZZZZ. + +### BOX64_LD_LIBRARY_PATH + +Path to look for x86_64 libraries. + + * XXXX: Add path XXXX to the library path. + +### BOX64_LD_PRELOAD + +Force loading libraries with the binary. + + * XXXX: Force the loading of library XXXX. + * XXXX:YYYY: Force the loading of libraries XXXX and YYYY. + +### BOX64_LIBGL + +Set the name for libGL. + + * libXXXX: Set the name for libGL to libXXXX. + * /path/to/libXXXX: Set the name and path for libGL to /path/to/libXXXX, you can also use SDL_VIDEO_GL_DRIVER. + +### BOX64_NOGTK + +Do not load wrapped GTK libraries. + + * 0: Load wrapped GTK libraries. [Default] + * 1: Do not load wrapped GTK libraries. + +### BOX64_NOPULSE + +Do not load PulseAudio libraries (both native and x86_64). + + * 0: Load PulseAudio libraries. [Default] + * 1: Do not load PulseAudio libraries. + +### BOX64_NOVULKAN + +Do not load Vulkan libraries. + + * 0: Load Vulkan libraries. [Default] + * 1: Do not load Vulkan libraries, both native and x86_64. + +### BOX64_PREFER_EMULATED + +Prefer emulated libraries over native ones. + + * 0: Prefer native libraries over emulated ones. [Default] + * 1: Prefer emulated libraries over native ones. + +### BOX64_PREFER_WRAPPED + +Prefer wrapped libs first even if the lib is specified with absolute path. + + * 0: Prefer libs with absolute path over wrapped ones. [Default] + * 1: Prefer wrapped libs first even if the lib is specified with absolute path. + +### BOX64_WRAP_EGL + +Prefer wrapped libs for EGL and GLESv2. + + * 0: Prefer emulated libs for EGL and GLESv2. [Default] + * 1: Prefer wrapped libs for EGL and GLESv2. + +## Arguments + +### BOX64_ARGS + +Arguments to pass to the guest program, only valid if there is no existing arguments. + + * XXXX: Pass argument XXXX to the program. + * XXXX YYYY ZZZZ: Pass arguments XXXX, YYYY and ZZZZ to the guest program. + +### BOX64_CEFDISABLEGPU + +Add -cef-disable-gpu argument to the guest program. + + * 0: Does nothing. [Default] + * 1: Add -cef-disable-gpu argument to the guest program. + +### BOX64_CEFDISABLEGPUCOMPOSITOR + +Add -cef-disable-gpu-compositor argument to the guest program. + + * 0: Does nothing. [Default] + * 1: Add -cef-disable-gpu-compositor argument to the guest program. + +### BOX64_INSERT_ARGS + +Prepend arguments to the command line. + + * XXXX: Prepend argument XXXX to the program. + * XXXX YYYY ZZZZ: Prepend arguments XXXX, YYYY and ZZZZ to the guest program. + +### BOX64_INPROCESSGPU + +Add --in-process-gpu argument to the guest program. + + * 0: Does nothing. [Default] + * 1: Add --in-process-gpu argument to the guest program. + +### BOX64_NOSANDBOX + +Add --no-sandbox argument to the guest program. + + * 0: Does nothing. [Default] + * 1: Add --no-sandbox argument to the guest program. + +## Compatibility + +### BOX64_BASH + +Path to the bash executable. + + * XXXX: Use bash executable at path XXXX. + +### BOX64_CPUTYPE + +Specify the CPU type to emulate. + + * 0: Emulate a Intel CPU Model. [Default] + * 1: Emulate a AMD CPU Model. + +### BOX64_CRASHHANDLER + +Use a dummy crash handler or not. + + * 0: Use emulated crashhandler.so library if nedded. + * 1: Use an internal dummy (empty) crashhandler.so library. [Default] + +### BOX64_DYNAREC_BLEEDING_EDGE + +Detect MonoBleedingEdge and apply conservative settings. + + * 0: Do not detect MonoBleedingEdge. + * 1: Detect MonoBleedingEdge and apply BOX64_DYNAREC_BIGBLOCK=0 BOX64_DYNAREC_STRONGMEM=1 when detected. [Default] + +### BOX64_DYNAREC_DIV0 + +Enable or disable the generation of division-by-zero exception. + + * 0: Do not generate thr division-by-zero exception. [Default] + * 1: Generate the division-by-zero exception. + +### BOX64_DYNAREC_TBB + +Enable or disable libtbb detection. + + * 0: Do not detect libtbb. + * 1: Detect libtbb and apply conservative settings. [Default] + +### BOX64_DYNAREC_X87DOUBLE + +Force the use of float/double for x87 emulation. + + * 0: Try to use float when possible for x87 emulation. [Default] + * 1: Only use Double for x87 emulation. + +### BOX64_EXIT + +Just exit, do not try to run the program. + + * 0: Does nothing. [Default] + * 1: Just exit. + +### BOX64_FIX_64BIT_INODES + +Fix 64bit inodes. + + * 0: Do not fix 64bit inodes. [Default] + * 1: Fix 64bit inodes. + +### BOX64_IGNOREINT3 + +Ignore INT3 instructions. + + * 0: Trigger a TRAP signal if a handler is present. [Default] + * 1: Skip the opcode silently. + +### BOX64_JVM + +Detect libjvm and apply conservative settings. + + * 0: Does nothing. + * 1: Detect libjvm, and apply BOX64_DYNAREC_BIGBLOCK=0 BOX64_DYNAREC_STRONGMEM=1 BOX64_SSE42=0 when detected. [Default] + +### BOX64_LIBCEF + +Detect libcef and apply BOX64_MALLOC_HACK settings. + + * 0: Does nothing. + * 1: Detect libcef, and apply BOX64_MALLOC_HACK=2 if detected. [Default] + +### 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. + * 2: Like 0, but track special mmap/free (some redirected functions are inlined and cannot be redirected). + +### BOX64_MAXCPU + +Maximum CPU cores exposed. + + * 0: Use the actual number of CPU cores. [Default] + * XXXX: Use XXXX CPU cores. + +### BOX64_NORCFILES + +Do not load any rc files. + + * 0: Load rc files. [Default] + * 1: Do not load any rc files. + +### BOX64_PATH + +Path to look for x86_64 binaries. + + * XXXX: Add path XXXX to the binary path. + +### BOX64_RCFILE + +Path to the rc file to load. + + * XXXX: Load the rc file XXXX, default rc files will not be loaded. + +### BOX64_RESERVE_HIGH + +Reserve high memory area for the program, always enabled on Box32. + + * 0: Do not reserve high memory area for the program. [Default] + * 1: Reserve high memory area for the program. + +### BOX64_SDL2_JGUID + +Use a workaround for SDL_GetJoystickGUIDInfo function for wrapped SDL2. + + * 0: Does nothing. [Default] + * 1: Use a workaround for SDL_GetJoystickGUIDInfo function for wrapped SDL2. + +### BOX64_SHAEXT + +Expose SHAEXT (a.k.a. SHA_NI) capabilities. + + * 0: Do not expose SHAEXT capabilities. + * 1: Expose SHAEXT capabilities. [Default] + +### BOX64_SSE_FLUSHTO0 + +Behaviour of SSE Flush to 0 flags. + + * 0: Just track the flag. [Default] + * 1: Apply SSE Flush to 0 flag directly. + +### BOX64_SSE42 + +Expose SSE4.2 capabilities. + + * 0: Do not expose SSE4.2 capabilities. + * 1: Expose SSE4.2 capabilities. [Default] + +### BOX64_SYNC_ROUNDING + +Synchronize rounding mode between x86 and native. + + * 0: Do not synchronize rounding mode. [Default] + * 1: Synchronize rounding mode between x86 and native. + +### BOX64_UNITYPLAYER + +Detect UnityPlayer and apply conservative settings. + + * 0: Does nothing. + * 1: Detect UnityPlayer, and apply BOX64_DYNAREC_STRONGMEM=1 when detected. [Default] + +### BOX64_X11GLX + +Force Xorg GLX extension to be present. + + * 0: Do not force Xorg GLX extension to be present. [Default] + * 1: Require Xorg GLX extension when using XQueryExtension. + +### BOX64_X11SYNC + +Force synchronized operation on X11 display. + + * 0: Do not force synchronized operation on X11 display. [Default] + * 1: Force synchronized operation on X11 display. + +### BOX64_X11THREADS + +Call XInitThreads when loading X11. This is mostly for old Loki games with the Loki_Compat library. + + * 0: Do not call XInitThreads. [Default] + * 1: Call XInitThreads as soon as libX11 is loaded. + +### BOX64_X87_NO80BITS + +Behavoiur of x87 80bits long double. + + * 0: Try to handle 80bits long double as precise as possible. [Default] + * 1: Use 64bits double for x87. + +## Debugging + +### BOX64_DLSYM_ERROR + +Enable or disable the logging of dlsym errors. + + * 0: Disable the logging of dlsym errors. [Default] + * 1: Enable the logging of dlsym errors. + +### BOX64_DUMP + +Dump elfloader debug information. + + * 0: Do not dump elfloader debug information. [Default] + * 1: Dump elfloader debug information. + +### BOX64_DYNAREC_DUMP + +Enable DynaRec dump. + + * 0: Do not dump DynaRec blocks. [Default] + * 1: Dump DynaRec blocks. + * 2: Dump DynaRec blocks with some colors. + +### 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_LOG + +Disable or enable DynaRec logs. + + * 0: Disable DynaRec logs. [Default] + * 1: Enable minimal DynaRec logs. + * 2: Enable debug level DynaRec logs. + * 3: Enable verbose level DynaRec logs. + +### BOX64_DYNAREC_MISSING + +Print missing opcodes. + + * 0: Do not print the missing opcode. [Default] + * 1: Print missing opcodes. + * 2: Print the fallback to scalar opcodes, only valid on RISC-V. + +### BOX64_DYNAREC_PERFMAP + +Generate map file for Linux perf tool. + + * 0: Dynarec will not generate perf map. [Default] + * 1: Dynarec will generate perf map. + +### BOX64_DYNAREC_TEST + +Enable DynaRec execution comparison with the interpreter, very 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 range where dynarec is tested (inclusive-exclusive). + +### BOX64_DYNAREC_TRACE + +Enable or disable DynaRec trace. + + * 0: Do not trace DynaRec blocks. [Default] + * 1: Trace DynaRec blocks, will slow down the program a lot and generates huge logs. + +### BOX64_JITGDB + +Launch gdb or not for SIGSEGV, SIGILL, and SIGBUS. + + * 0: Just print the message when the signal is caught. [Default] + * 1: Launch gdb when a SIGSEGV, SIGILL or SIGBUS signal is trapped, attached to the offending process and go in an endless loop, waiting. Inside 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 `set waiting=0` to exit the infinite loop. + * 2: Launch gdbserver when a SIGSEGV, SIGILL or SIGBUS 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`. + * 3: Launch lldb when a SIGSEGV, SIGILL or SIGBUS signal is trapped, attached to the offending process and go in an endless loop, waiting. + +### BOX64_LOAD_ADDR + +Set the address where the program is loaded, only active for PIE guest programs. + + * 0xXXXXXXXX: Set the address where the program is loaded. + +### BOX64_LOG + +Enable or disable Box64 logs. + + * 0: Disable Box64 logs. [Default] + * 1: Enable minimal Box64 logs. + * 2: Enable debug level Box64 logs. + * 3: Enable verbose level Box64 logs. + +### BOX64_NOBANNER + +Disable the Box64 banner. + + * 0: Show the Box64 banner. [Default] + * 1: Do not show the Box64 banner. + +### BOX64_NOSIGSEGV + +Disable the handling of SIGSEGV. + + * 0: Let the x86 program set sighandler for SIGSEGV. [Default] + * 1: Disable the handling of SIGSEGV. + +### BOX64_NOSIGILL + +Disable the handling of SIGILL. + + * 0: Let the x86 program set sighandler for SIGILL. [Default] + * 1: Disable the handling of SIGILL. + +### BOX64_ROLLING_LOG + +Show last few wrapped function call when a signal is caught. + + * 0: Does nothing. [Default] + * 1: Show last 16 wrapped function call when a signal is caught. + * XXX: Show last XXX wrapped function call when a signal is caught. + +### BOX64_SHOWBT + +Show native and emulated backtrace when a signal is caught. + + * 0: Does nothing. [Default] + * 1: Show native and emulated backtrace when a signal is caught. + +### BOX64_SHOWSEGV + +Always show SIGSEGV signal detailes. + + * 0: Does nothing. [Default] + * 1: Always show SIGSEGV signal detailes. + +### BOX64_TRACE_COLOR + +Enable or disable colored trace output. + + * 0: Disable colored trace output. [Default] + * 1: Enable colored trace output. + +### BOX64_TRACE_EMM + +Enable or disable EMM (i.e. MMX) trace output. + + * 0: Disable EMM trace output. [Default] + * 1: Enable EMM trace output. + +### BOX64_TRACE_FILE + +Send all log and trace to a file instead of `stdout`. + + * XXXX: Send all log and trace to file XXXX. + * XXXX%pid: Send all log and trace to file XXXX with pid appended. + * stderr: Send all log and trace to `stderr`. + +### BOX64_TRACE_INIT + +Same as BOX64_TRACE but starts the trace immediately. + + * 0: Disable trace output. [Default] + * 1: Enable trace output. Trace starts before the initialization of dependencies. + +### BOX64_TRACE_START + +Start trace after N opcodes executed. + + * 0: Start trace immediately. [Default] + * 1: Start trace after 1 opcode executed. + * XXXX: Start trace after XXXX opcodes executed. + +### BOX64_TRACE_XMM + +Enable or disable XMM (i.e. SSE) trace output. + + * 0: Disable XMM trace output. [Default] + * 1: Enable XMM trace output. + +### BOX64_TRACE + +Only available on box64 build with trace. Adds trace of all instructions executed, along with a register dump. + + * 0: Disable trace output. [Default] + * 1: Enable trace output. + * symbolname: Enable trace output for `symbolname` only. + * 0xXXXXXXX-0xYYYYYYY: Enable trace output for the range of address (inclusive-exclusive). + +## Performance + +### BOX64_DYNAREC_ALIGNED_ATOMICS + +Generate aligned atomics only (only available on Arm64 for now). + + * 0: Generate unaligned atomics handling code. [Default] + * 1: Generate aligned atomics only, which is faster and smaller code size, but will cause SIGBUS for LOCK prefixed opcodes operating on aligned data addresses. + +### BOX64_DYNAREC_BIGBLOCK + +Enable building bigger DynaRec code blocks for better performance. + + * 0: Do not try to build block as big as possible, suitable for programs using lots of threads and JIT, like Unity. + * 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, useful for wine programs. + +### BOX64_DYNAREC_CALLRET + +Optimize CALL/RET opcodes. + + * 0: Do not optimize CALL/RET, use jump table. [Default] + * 1: Try to optimize CALL/RET, skipping the jump table when possible. + +### BOX64_DYNAREC_DF + +Enable or disable the use of deferred flags. + + * 0: Disable the use of deferred flags. + * 1: Enable the use of deferred flags. [Default] + +### BOX64_DYNAREC_DIRTY + +Allow continue running a block that is unprotected and potentially dirty. + + * 0: Do not allow continue running a block that is unprotected and potentially dirty. [Default] + * 1: Allow continue to run a dynablock that write data in the same page as code. It can gets faster in loading time of some game but can also get unexpected crashes. + +### BOX64_DYNAREC_FASTNAN + +Enable or disable fast NaN handling. + + * 0: Precisely emulate the -NaN generation like on x86. + * 1: Do not do anything special with -NAN generation, faster. [Default] + +### BOX64_DYNAREC_FASTROUND + +Enable or disable fast rounding. + + * 0: Generate float/double -> int rounding and use current rounding mode for float/double computation like on x86. + * 1: Do not do anything special with edge case rounding, faster. [Default] + * 2: Generate float/double -> int rounding using current rounding mode for float/double computation like on x86, but use fast int -> float/double conversion. + +### BOX64_DYNAREC_FORWARD + +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. + * 128: Allow up to 128 bytes of gap between end of the block and the next forward jump. [Default] + * XXXX: Allow up to XXXX bytes of gap between end of the block and the next forward jump. + +### BOX64_DYNAREC_NATIVEFLAGS + +Enable or disable the use of native flags. + + * 0: Do not use native flags. + * 1: Use native flags when possible. [Default] + +### BOX64_DYNAREC_PAUSE + +Enable x86 PAUSE emulation, 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. + +### BOX64_DYNAREC_SAFEFLAGS + +Behaviour of flags emulation on CALL/RET opcodes. + + * 0: Treat CALL/RET as if it never needs any flags. + * 1: Most of RETs will need flags, most of CALLs will not. [Default] + * 2: All CALL/RET will need flags. + +### BOX64_DYNAREC_STRONGMEM + +Enable the emulation of x86 strong memory model. + + * 0: Do not try anything special. + * 1: Enable some memory barriers when writing to memory to emulate the x86 strong memory model in a limited way. [Default] + * 2: All in 1, plus memory barriers on SIMD instructions. + * 3: All in 2, plus more memory barriers on a regular basis. + +### BOX64_DYNAREC_WAIT + +Wait or not for the building of a DynaRec code block to be ready. + + * 0: Do not wait and use interpreter instead, might speedup a bit on massive multithread or JIT programs. + * 1: Wait for a DynaRec code block to be ready. [Default] + +### BOX64_DYNAREC_WEAKBARRIER + +Tweak the memory barriers to reduce the performance impact by strong memory emualtion. + + * 0: Use regular safe barrier. + * 1: Use weak barriers to have more performance boost. [Default] + * 2: All in 1, plus disabled the last write barriers. + +### BOX64_NODYNAREC + +Forbid dynablock creation in the address range specified, helpful for debugging behaviour difference between Dynarec and Interpreter. + + * 0xXXXXXXXX-0xYYYYYYYY: Define the range where dynablock creation is forbidden (inclusive-exclusive). + +### BOX64_RDTSC_1GHZ + +Use hardware counter for rdtsc if available. + + * 0: Use hardware counter for rdtsc opcode if available. [Default] + * 1: Use hardware counter for rdtsc if and only if precision is at least 1GHz. + +## Environment + +### BOX64_ENV + +Add an environment variable. + + * XXXX=yyyy: Add environment variable XXXX with value yyyy. + +### BOX64_ENV[1-5] + +Add an environment variable. + + * XXXX=yyyy: Add environment variable XXXX with value yyyy. + diff --git a/docs/box64.pod b/docs/box64.pod index 3f5970b7..1cd71ed6 100644 --- a/docs/box64.pod +++ b/docs/box64.pod @@ -30,15 +30,13 @@ Print box64 version and quit. =back -=head1 CONFIGURATION FILE +=head1 BRIEF USAGE -B<Box64> now have configurations files. There are 2 files loaded. -F</etc/box64.box64rc> and F<~/.box64rc>. Both files have the same syntax, and is -basically an ini files. Section in square brackets define the process name, and -the rest is the environment variable. B<Box64> comes with a default file that -should be installed for better stability. Note that the priority is: -F<~/.bashrc> > F</etc/box64.box64rc> > command line So, your settings in -F<~/.bashrc> may override the setting from your command line. Example: +There are many environment variables to control B<Box64>'s behaviour. In +addition to environment variables, B<Box64> also looks for 2 places for rcfile: +F</etc/box64.box64rc> and F<~/.box64rc>, in the format of .ini files. +Settings priority: F<~/.box64rc> > F</etc/box64.box64rc> > environment variables. +Example: [factorio] BOX64_DYNAREC_SAFEFLAGS=0 @@ -46,494 +44,740 @@ F<~/.bashrc> may override the setting from your command line. Example: BOX64_DYNAREC_FORWARD=1024 BOX64_DYNAREC_CALLRET=1 -=head1 VARIABLES FOR RCFILE ONLY +=head1 ENVIRONMENT VARIABLES =over 8 -=item B<BOX64_NOSANDBOX=0|1> -When set to 1, add C<--no-sandbox> to command line arguments (useful for chrome -based programs). +=item B<BOX64_ADDLIBS> =I<XXXX|XXXX:YYYY:ZZZZ> -=item B<BOX64_INPROCESSGPU=0|1> +Add extras to the needed libraries list, rarely needed. -When set to 1, add C<--in-process-gpu> to command line arguments (useful for chrome -based programs). + * XXXX : Add library XXXX to the needed libraries list. + * XXXX:YYYY:ZZZZ : Add library XXXX, YYYY and ZZZZ to the needed libraries list. -=item B<BOX64_EXIT>=I<0|1> -When set to 1, just exit, don't try to run the program. +=item B<BOX64_ALLOWMISSINGLIBS> =I<0|1> -=back +Allow missing libraries to be ignored. -=head1 VARIABLES ONLY FOR ENVIRONMENT AND NOT RCFILE + * 0 : Do not allow missing libraries. [Default] + * 1 : Allow missing libraries. -=over 8 -=item B<BOX64_NOBANNER>=I<0|1> +=item B<BOX64_ARGS> =I<XXXX|XXXX YYYY ZZZZ> -When set to 1, don't prints the banner including version and build. +Arguments to pass to the guest program, only valid if there is no existing arguments. -=item B<BOX64_LD_PRELOAD>=I<lib1>[:I<lib2>:...] + * XXXX : Pass argument XXXX to the program. + * XXXX YYYY ZZZZ : Pass arguments XXXX, YYYY and ZZZZ to the guest program. -Force loading 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. -=item B<BOX64_ENV>=I<env=val> +=item B<BOX64_BASH> =I<XXXX> -Add an variable with value to the environment. +Path to the bash executable. -=item B<BOX64_ENV1>=I<env=val> B<BOX64_ENV2>=I<env=val> ... + * XXXX : Use bash executable at path XXXX. -Add arbitrary many variables using B<BOX64_ENV1>, B<BOX64_ENV2>, ... -=item B<BOX64_NORCFILES> +=item B<BOX64_CEFDISABLEGPU> =I<0|1> -No rc files (like F</etc/box64.box64rc> and F<~/.box64rc>) will be loaded. +Add -cef-disable-gpu argument to the guest program. -=back + * 0 : Does nothing. [Default] + * 1 : Add -cef-disable-gpu argument to the guest program. -=head1 VARIABLES FOR BOTH ENVIRONMENT AND RCFILE -=over 8 +=item B<BOX64_CEFDISABLEGPUCOMPOSITOR> =I<0|1> + +Add -cef-disable-gpu-compositor argument to the guest program. + + * 0 : Does nothing. [Default] + * 1 : Add -cef-disable-gpu-compositor argument to the guest program. + + +=item B<BOX64_CPUTYPE> =I<0|1> + +Specify the CPU type to emulate. + + * 0 : Emulate a Intel CPU Model. [Default] + * 1 : Emulate a AMD CPU Model. + + +=item B<BOX64_CRASHHANDLER> =I<0|1> + +Use a dummy crash handler or not. + + * 0 : Use emulated crashhandler.so library if nedded. + * 1 : Use an internal dummy (empty) crashhandler.so library. [Default] + + +=item B<BOX64_DLSYM_ERROR> =I<0|1> + +Enable or disable the logging of dlsym errors. + + * 0 : Disable the logging of dlsym errors. [Default] + * 1 : Enable the logging of dlsym errors. + + +=item B<BOX64_DUMP> =I<0|1> + +Dump elfloader debug information. + + * 0 : Do not dump elfloader debug information. [Default] + * 1 : Dump elfloader debug information. + + +=item B<BOX64_DYNAREC_ALIGNED_ATOMICS> =I<0|1> + +Generate aligned atomics only (only available on Arm64 for now). + + * 0 : Generate unaligned atomics handling code. [Default] + * 1 : Generate aligned atomics only, which is faster and smaller code size, but will cause SIGBUS for LOCK prefixed opcodes operating on aligned data addresses. + + +=item B<BOX64_DYNAREC_BIGBLOCK> =I<0|1|2|3> + +Enable building bigger DynaRec code blocks for better performance. + + * 0 : Do not try to build block as big as possible, suitable for programs using lots of threads and JIT, like Unity. + * 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, useful for wine programs. + + +=item B<BOX64_DYNAREC_BLEEDING_EDGE> =I<0|1> + +Detect MonoBleedingEdge and apply conservative settings. + + * 0 : Do not detect MonoBleedingEdge. + * 1 : Detect MonoBleedingEdge and apply BOX64_DYNAREC_BIGBLOCK=0 BOX64_DYNAREC_STRONGMEM=1 when detected. [Default] + + +=item B<BOX64_DYNAREC_CALLRET> =I<0|1> + +Optimize CALL/RET opcodes. + + * 0 : Do not optimize CALL/RET, use jump table. [Default] + * 1 : Try to optimize CALL/RET, skipping the jump table when possible. + + +=item B<BOX64_DYNAREC_DF> =I<0|1> + +Enable or disable the use of deferred flags. + + * 0 : Disable the use of deferred flags. + * 1 : Enable the use of deferred flags. [Default] + + +=item B<BOX64_DYNAREC_DIRTY> =I<0|1> + +Allow continue running a block that is unprotected and potentially dirty. + + * 0 : Do not allow continue running a block that is unprotected and potentially dirty. [Default] + * 1 : Allow continue to run a dynablock that write data in the same page as code. It can gets faster in loading time of some game but can also get unexpected crashes. + + +=item B<BOX64_DYNAREC_DIV0> =I<0|1> + +Enable or disable the generation of division-by-zero exception. + + * 0 : Do not generate thr division-by-zero exception. [Default] + * 1 : Generate the division-by-zero exception. + + +=item B<BOX64_DYNAREC_DUMP> =I<0|1|2> + +Enable DynaRec dump. + + * 0 : Do not dump DynaRec blocks. [Default] + * 1 : Dump DynaRec blocks. + * 2 : Dump DynaRec blocks with some colors. + + +=item B<BOX64_DYNAREC_FASTNAN> =I<0|1> + +Enable or disable fast NaN handling. + + * 0 : Precisely emulate the -NaN generation like on x86. + * 1 : Do not do anything special with -NAN generation, faster. [Default] + + +=item B<BOX64_DYNAREC_FASTROUND> =I<0|1|2> + +Enable or disable fast rounding. + + * 0 : Generate float/double -> int rounding and use current rounding mode for float/double computation like on x86. + * 1 : Do not do anything special with edge case rounding, faster. [Default] + * 2 : Generate float/double -> int rounding using current rounding mode for float/double computation like on x86, but use fast int -> float/double conversion. + + +=item B<BOX64_DYNAREC_FORWARD> =I<0|128|XXXX> + +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. + * 128 : Allow up to 128 bytes of gap between end of the block and the next forward jump. [Default] + * XXXX : Allow up to XXXX bytes of gap between end of the block and the next forward jump. + + +=item B<BOX64_DYNAREC_GDBJIT> =I<0|1|2> + +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. + + +=item B<BOX64_DYNAREC_LOG> =I<0|1|2|3> + +Disable or enable DynaRec logs. + + * 0 : Disable DynaRec logs. [Default] + * 1 : Enable minimal DynaRec logs. + * 2 : Enable debug level DynaRec logs. + * 3 : Enable verbose level DynaRec logs. + + +=item B<BOX64_DYNAREC_MISSING> =I<0|1|2> + +Print missing opcodes. + + * 0 : Do not print the missing opcode. [Default] + * 1 : Print missing opcodes. + * 2 : Print the fallback to scalar opcodes, only valid on RISC-V. + + +=item B<BOX64_DYNAREC_NATIVEFLAGS> =I<0|1> + +Enable or disable the use of native flags. + + * 0 : Do not use native flags. + * 1 : Use native flags when possible. [Default] + + +=item B<BOX64_DYNAREC_PAUSE> =I<0|1|2|3> -=item B<BOX64_LOG>=I<0|NONE|1|INFO|2|DEBUG|3|DUMP> +Enable x86 PAUSE emulation, may help the performance of spinlocks. -Controls the Verbosity level of the logs + * 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. - * 0 or NONE : No message (except some fatal error). (Default.) - * 1 or INFO : Show some minimum log (Example: libraries not found) - * 2 or DEBUG : Details a lot of stuff (Example: relocations or functions called). - * 3 or DUMP : All DEBUG plus DUMP of all ELF Info. -=item B<BOX64_ROLLING_LOG>=I<0|1|N> +=item B<BOX64_DYNAREC_PERFMAP> =I<0|1> -Show last few wrapped function call when a Signal is caught. Incompatible with -B<BOX64_LOG> > 1 (may need B<BOX64_SHOWSEGV=1> also) +Generate map file for Linux perf tool. - * 0: No last function call printed (Default.) - * 1: Last 16 wrapped functions calls printed when a signal is printed. - * N: Last N wrapped functions calls printed when a signal is printed. + * 0 : Dynarec will not generate perf map. [Default] + * 1 : Dynarec will generate perf map. -=item B<BOX64_LD_LIBRARY_PATH>=I</path/to/libs> -Path to look for x86_64 libraries. Default is current folder and C<lib> in -current folder. Also, F</usr/lib/x86_64-linux-gnu>, -F</lib/x86_64-linux-gnu> and F</usr/lib/box64-x86_64-linux-gnu> are added if they exist. +=item B<BOX64_DYNAREC_SAFEFLAGS> =I<0|1|2> -=item B<BOX64_PATH>=I</path/to/bins> +Behaviour of flags emulation on CALL/RET opcodes. -Path to look for x86_64 executable. Default is current folder and C<bin> in -current folder. + * 0 : Treat CALL/RET as if it never needs any flags. + * 1 : Most of RETs will need flags, most of CALLs will not. [Default] + * 2 : All CALL/RET will need flags. -=item B<BOX64_DLSYM_ERROR>=I<0|1> -Enables/Disables the logging of `dlsym` errors. +=item B<BOX64_DYNAREC_STRONGMEM> =I<0|1|2|3> - * 0 : Don't log `dlsym` errors. (Default.) - * 1 : Log dlsym errors. +Enable the emulation of x86 strong memory model. -=item B<BOX64_TRACE_FILE>=I</path/to/file> + * 0 : Do not try anything special. + * 1 : Enable some memory barriers when writing to memory to emulate the x86 strong memory model in a limited way. [Default] + * 2 : All in 1, plus memory barriers on SIMD instructions. + * 3 : All in 2, plus more memory barriers on a regular basis. -Send all log and trace to a file instead of C<stdout>. Also, if name contains -C<%pid> then this is replaced by the actual C<PID> of B<box64> instance. End -the filename with `+` to have thetrace appended instead of overwritten Use -C<stderr> to use this instead of default C<stdout>. -=item B<BOX64_TRACE>=I<0|1|symbolname|0xXXXXXXX-0xYYYYYYY> +=item B<BOX64_DYNAREC_TBB> =I<0|1> -Only on build with trace enabled. Trace allow the logging of all instruction executed, along with register dump +Enable or disable libtbb detection. - * 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). - * 0xXXXXXXX-0xYYYYYYY : Trace only between the 2 addresses. + * 0 : Do not detect libtbb. + * 1 : Detect libtbb and apply conservative settings. [Default] -=item B<BOX64_TRACE_INIT>=I<0|1> -Use B<BOX64_TRACE_INIT> instead of B<BOX64_TRACE> to start trace before the -initialization of libraries and the running program +=item B<BOX64_DYNAREC_TEST> =I<0|1|0xXXXXXXXX-0xYYYYYYYY> - * 0 : No trace. (Default.) - * 1 : Trace enabled. The trace start with the initialisation of all depending libraries is done. +Enable DynaRec execution comparison with the interpreter, very slow, only for testing. -=item B<BOX64_TRACE_START>=I<NNNNNNN> + * 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 range where dynarec is tested (inclusive-exclusive). -Only on builds with trace enabled. Start trace only after I<NNNNNNNN> opcode -execute (number is an `uint64_t`). -=item B<BOX64_TRACE_XMM>=I<0|1> +=item B<BOX64_DYNAREC_TRACE> =I<0|1> -Only on builds with trace enabled. +Enable or disable DynaRec 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. + * 0 : Do not trace DynaRec blocks. [Default] + * 1 : Trace DynaRec blocks, will slow down the program a lot and generates huge logs. -=item B<BOX64_TRACE_EMM>=I<0|1> -Only on builds with trace enabled. +=item B<BOX64_DYNAREC_WAIT> =I<0|1> - * 0 : The EMM (i.e. MMX) register will not be logged with the general and x86 registers. (Default.) - * 1 : Dump the EMM registers. +Wait or not for the building of a DynaRec code block to be ready. -=item B<BOX64_TRACE_COLOR>=I<0|1> + * 0 : Do not wait and use interpreter instead, might speedup a bit on massive multithread or JIT programs. + * 1 : Wait for a DynaRec code block to be ready. [Default] -Only on builds with trace enabled. - * 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. +=item B<BOX64_DYNAREC_WEAKBARRIER> =I<0|1|2> -=item B<BOX64_LOAD_ADDR>=I<0xXXXXXXXX> +Tweak the memory barriers to reduce the performance impact by strong memory emualtion. -Try to load at C<0xXXXXXX> main binary (if binary is a PIE). + * 0 : Use regular safe barrier. + * 1 : Use weak barriers to have more performance boost. [Default] + * 2 : All in 1, plus disabled the last write barriers. -=item B<BOX64_NOSIGSEGV>=I<0|1> -Disable handling of SigSEGV. (Very useful for debugging.) +=item B<BOX64_DYNAREC_X87DOUBLE> =I<0|1> - * 0 : Let the x86 program set sighandler for SEGV (Default.) - * 1 : Disable the handling of SigSEGV. +Force the use of float/double for x87 emulation. -=item B<BOX64_NOSIGILL>=I<0|1> + * 0 : Try to use float when possible for x87 emulation. [Default] + * 1 : Only use Double for x87 emulation. -Disable handling of SigILL (to ease debugging mainly). - * 0 : Let x86 program set sighandler for Illegal Instruction - * 1 : Disables the handling of SigILL +=item B<BOX64_EMULATED_LIBS> =I<XXXX|XXXX:YYYY:ZZZZ> -=item B<BOX64_SHOWSEGV>=I<0|1> +Force the use of emulated libraries. -Show Segfault signal even if a signal handler is present + * XXXX : Force the use of emulated library XXXX. + * XXXX:YYYY:ZZZZ : Force the use of emulated libraries XXXX, YYYY and ZZZZ. - * 0 : Don't force show the SIGSEGV analysis (Default.) - * 1 : Show SIGSEGV detail, even if a signal handler is present -=item B<BOX64_SHOWBT>=I<0|1> +=item B<BOX64_ENV> =I<XXXX=yyyy> -Show some Backtrace (Nativ e and Emulated) when a signal (SEGV, ILL or BUS) is caught +Add an environment variable. - * 0 : Don't show backtraces (Default.) - * 1 : Show Backtrace detail (for native, box64 is rename as the x86_64 binary run) + * XXXX=yyyy : Add environment variable XXXX with value yyyy. -=item B<BOX64_X11THREADS>=I<0|1> -Call XInitThreads when loading X11. (This is mostly for old Loki games with the Loki_Compat library.) +=item B<BOX64_ENV[1-5]> =I<XXXX=yyyy> - * 0 : Don't force call XInitThreads. (Default.) - * 1 : Call XInitThreads as soon as libX11 is loaded. +Add an environment variable. -=item B<BOX64_X11GLX>=I<0|1> + * XXXX=yyyy : Add environment variable XXXX with value yyyy. -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.) +=item B<BOX64_EXIT> =I<0|1> -=item B<BOX64_DYNAREC_DUMP>=I<0|1|2> +Just exit, do not try to run the program. -Enables/disables Box64's Dynarec's dump. + * 0 : Does nothing. [Default] + * 1 : Just exit. - * 0 : Disable Dynarec's blocks dump. (Default.) - * 1 : Enable Dynarec's blocks dump. - * 2 : Enable Dynarec's blocks dump with some colors. -=item B<BOX64_DYNAREC_LOG>=I<0|1|2|3> +=item B<BOX64_FIX_64BIT_INODES> =I<0|1> -Set the level of DynaRec's logs. +Fix 64bit inodes. - * 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. + * 0 : Do not fix 64bit inodes. [Default] + * 1 : Fix 64bit inodes. -=item B<BOX64_DYNAREC>=I<0|1> -Enables/Disables Box64's Dynarec. +=item B<BOX64_IGNOREINT3> =I<0|1> - * 0 : Disables Dynarec. - * 1 : Enable Dynarec. (Default.) +Ignore INT3 instructions. -=item B<BOX64_DYNAREC_TRACE>=I<0|1> + * 0 : Trigger a TRAP signal if a handler is present. [Default] + * 1 : Skip the opcode silently. -Enables/Disables trace for generated code. Like regular Trace, this will slow -down the program a lot and generate huge logs. - * 0 : Disable trace for generated code. (Default.) - * 1 : Enable trace for generated code +=item B<BOX64_INSERT_ARGS> =I<XXXX|XXXX YYYY ZZZZ> -=item B<BOX64_NODYNAREC>=I<0xXXXXXXXX-0xYYYYYYYY> +Prepend arguments to the command line. -Forbid dynablock creation in the interval specified (helpful for debugging -behaviour difference between Dynarec and Interpreter) + * XXXX : Prepend argument XXXX to the program. + * XXXX YYYY ZZZZ : Prepend arguments XXXX, YYYY and ZZZZ to the guest program. -=item B<BOX64_DYNAREC_TEST>=I<0|1> -Dynarec will compare it's execution with the interpreter (super slow, only for testing) +=item B<BOX64_INPROCESSGPU> =I<0|1> - * 0 : No comparison. (Default.) - * 1 : Each opcode runs on interepter and on Dynarec, and regs and memory are compared and print if different. - * 0xXXXXXXXX-0xYYYYYYYY : Define the interval where dynarec is tested (inclusive-exclusive) +Add --in-process-gpu argument to the guest program. + * 0 : Does nothing. [Default] + * 1 : Add --in-process-gpu argument to the guest program. -=item B<BOX64_DYNAREC_BIGBLOCK>=I<0|1|2|3> -Enables/Disables Box64's Dynarec building BigBlock. +=item B<BOX64_JITGDB> =I<0|1|2|3> - * 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) +Launch gdb or not for SIGSEGV, SIGILL, and SIGBUS. -=item B<BOX64_DYNAREC_FORWARD>=I<0|XXX> + * 0 : Just print the message when the signal is caught. [Default] + * 1 : Launch gdb when a SIGSEGV, SIGILL or SIGBUS signal is trapped, attached to the offending process and go in an endless loop, waiting. Inside 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 `set waiting=0` to exit the infinite loop. + * 2 : Launch gdbserver when a SIGSEGV, SIGILL or SIGBUS 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`. + * 3 : Launch lldb when a SIGSEGV, SIGILL or SIGBUS signal is trapped, attached to the offending process and go in an endless loop, waiting. -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) - -=item B<BOX64_DYNAREC_STRONGMEM>=I<0|1|2|3> +=item B<BOX64_JVM> =I<0|1> -Enable/Disable simulation of Strong Memory model +Detect libjvm and apply conservative settings. - * 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 + * 0 : Does nothing. + * 1 : Detect libjvm, and apply BOX64_DYNAREC_BIGBLOCK=0 BOX64_DYNAREC_STRONGMEM=1 BOX64_SSE42=0 when detected. [Default] -=item B<BOX64_DYNAREC_WEAKBARRIER>=I<0|1|2> -Tweaking the memory barriers to reduce the performance impact by STRONGMEM +=item B<BOX64_LD_LIBRARY_PATH> =I<XXXX> - * 0 : Use regular safe barrier (Default.) - * 1 : Use weak barriers to have more performance boost - * 2 : All 1. Plus disabled the last write barriers +Path to look for x86_64 libraries. -=item B<BOX64_DYNAREC_PAUSE>=I<0|1|2|3> + * XXXX : Add path XXXX to the library path. -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 +=item B<BOX64_LD_PRELOAD> =I<XXXX|XXXX:YYYY> -=item B<BOX64_DYNAREC_X87DOUBLE>=I<0|1> +Force loading libraries with the binary. -Force the use of Double for x87 emulation + * XXXX : Force the loading of library XXXX. + * XXXX:YYYY : Force the loading of libraries XXXX and YYYY. - * 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) -=item B<BOX64_DYNAREC_FASTNAN>=I<0|1> +=item B<BOX64_LIBCEF> =I<0|1> -Enable/Disable generation of -NAN +Detect libcef and apply BOX64_MALLOC_HACK settings. - * 0 : Generate -NAN like on x86 - * 1 : Don't do anything special with NAN, to go as fast as possible (default, faster) + * 0 : Does nothing. + * 1 : Detect libcef, and apply BOX64_MALLOC_HACK=2 if detected. [Default] -=item B<BOX64_DYNAREC_FASTROUND>=I<0|1> -Enable/Disable generation of precise x86 rounding +=item B<BOX64_LIBGL> =I<libXXXX|/path/to/libXXXX> - * 0 : Generate float/double -> int rounding and use current rounding mode for float/double computation 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, and no non-default rounding modes) (default, faster) +Set the name for libGL. -=item B<BOX64_DYNAREC_SAFEFLAGS>=I<0|1|2> + * libXXXX : Set the name for libGL to libXXXX. + * /path/to/libXXXX : Set the name and path for libGL to /path/to/libXXXX, you can also use SDL_VIDEO_GL_DRIVER. -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) +=item B<BOX64_LOAD_ADDR> =I<0xXXXXXXXX> -=item B<BOX64_DYNAREC_CALLRET>=I<0|1> +Set the address where the program is loaded, only active for PIE guest programs. -Optimisation of CALL/RET opcodes (not compatible with jit/dynarec/smc) + * 0xXXXXXXXX : Set the address where the program is loaded. - * 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 (will crash if blacks are invalidate, so probably incompatible with JIT/Dynarec) -=item B<BOX64_DYNAREC_BLEEDING_EDGE>=I<0|1> +=item B<BOX64_LOG> =I<0|1|2|3> -Detect MonoBleedingEdge and apply conservative settings +Enable or disable Box64 logs. - * 0 : Don't detect MonoBleedingEdge - * 1 : Detect MonoBleedingEdge, and apply BIGBLOCK=0 STRONGMEM=1 if detected (Default) + * 0 : Disable Box64 logs. [Default] + * 1 : Enable minimal Box64 logs. + * 2 : Enable debug level Box64 logs. + * 3 : Enable verbose level Box64 logs. -=item B<BOX64_DYNAREC_WAIT>=I<0|1> -Behavior with FillBlock is not available (FillBlock build Dynarec blocks and is not multithreaded) +=item B<BOX64_MALLOC_HACK> =I<0|1|2> - * 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) +Behaviour when hooking malloc operators. -=item B<BOX64_DYNAREC_DIRTY>=I<0|1> + * 0 : Don't allow malloc operator to be redirected, rewriting code to use regular function. [Default] + * 1 : Allow malloc operator to be redirected. + * 2 : Like 0, but track special mmap/free (some redirected functions are inlined and cannot be redirected). -Allow continue running a block that is unprotected and potentially dirty - * 0 : Do not allow conitnuing to run a dynablock that gets unprotected (default) - * 1 : Allow continue to run a dynablock that write data in the same page the code is. It can get faster loading time of some game but can also get unexpected crash. +=item B<BOX64_MAXCPU> =I<0|XXXX> -=item B<BOX64_DYNAREC_GDBJIT>=I<0|1|2> +Maximum CPU cores exposed. -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 : Use the actual number of CPU cores. [Default] + * XXXX : Use XXXX CPU cores. - * 0 : Dynarec will not generate GDBJIT debuginfo. (Default) - * 1 : Dynarec will generate GDBJIT debuginfo. - * 2 : Dynarec will generate detailed GDBJIT debuginfo with internal state. -=item B<BOX64_DYNAREC_PERFMAP>=I<0|1> +=item B<BOX64_NOBANNER> =I<0|1> -Dynarec generate map file for Linux perf tool. +Disable the Box64 banner. - * 0 : Dynarec will not generate perf map. (Default) - * 1 : Dynarec will generate perf map. + * 0 : Show the Box64 banner. [Default] + * 1 : Do not show the Box64 banner. -=item B<BOX64_SSE_FLUSHTO0>=I<0|1> -Handling of SSE Flush to 0 flags +=item B<BOX64_NODYNAREC> =I<0xXXXXXXXX-0xYYYYYYYY> - * 0 : Just track the flag (Default) - * 1 : Direct apply of SSE Flush to 0 flag +Forbid dynablock creation in the address range specified, helpful for debugging behaviour difference between Dynarec and Interpreter. -=item B<BOX64_X87_NO80BITS>=I<0|1> + * 0xXXXXXXXX-0xYYYYYYYY : Define the range where dynablock creation is forbidden (inclusive-exclusive). -Handling of x87 80bits long double - * 0 : Try to handle 80bits long double as precise as possible (Default) - * 1 : Handle them as double +=item B<BOX64_NOGTK> =I<0|1> -=item B<BOX64_MAXCPU>=I<0|XXX> +Do not load wrapped GTK libraries. -Maximum CPU Cores exposed. + * 0 : Load wrapped GTK libraries. [Default] + * 1 : Do not load wrapped GTK libraries. - * 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) -=item B<BOX64_RDTSC_1GHZ>=I<0|1> +=item B<BOX64_NOPULSE> =I<0|1> + +Do not load PulseAudio libraries (both native and x86_64). + + * 0 : Load PulseAudio libraries. [Default] + * 1 : Do not load PulseAudio libraries. + + +=item B<BOX64_NORCFILES> =I<0|1> + +Do not load any rc files. + + * 0 : Load rc files. [Default] + * 1 : Do not load any rc files. + + +=item B<BOX64_NOSANDBOX> =I<0|1> + +Add --no-sandbox argument to the guest program. + + * 0 : Does nothing. [Default] + * 1 : Add --no-sandbox argument to the guest program. + + +=item B<BOX64_NOSIGSEGV> =I<0|1> + +Disable the handling of SIGSEGV. + + * 0 : Let the x86 program set sighandler for SIGSEGV. [Default] + * 1 : Disable the handling of SIGSEGV. + + +=item B<BOX64_NOSIGILL> =I<0|1> + +Disable the handling of SIGILL. + + * 0 : Let the x86 program set sighandler for SIGILL. [Default] + * 1 : Disable the handling of SIGILL. + + +=item B<BOX64_NOVULKAN> =I<0|1> + +Do not load Vulkan libraries. + + * 0 : Load Vulkan libraries. [Default] + * 1 : Do not load Vulkan libraries, both native and x86_64. + + +=item B<BOX64_PATH> =I<XXXX> + +Path to look for x86_64 binaries. + + * XXXX : Add path XXXX to the binary path. + + +=item B<BOX64_PREFER_EMULATED> =I<0|1> + +Prefer emulated libraries over native ones. + + * 0 : Prefer native libraries over emulated ones. [Default] + * 1 : Prefer emulated libraries over native ones. + + +=item B<BOX64_PREFER_WRAPPED> =I<0|1> + +Prefer wrapped libs first even if the lib is specified with absolute path. + + * 0 : Prefer libs with absolute path over wrapped ones. [Default] + * 1 : Prefer wrapped libs first even if the lib is specified with absolute path. + + +=item B<BOX64_RCFILE> =I<XXXX> + +Path to the rc file to load. + + * XXXX : Load the rc file XXXX, default rc files will not be loaded. + + +=item B<BOX64_RDTSC_1GHZ> =I<0|1> Use hardware counter for rdtsc if available. - * 0 : Use hardware counter for rdtsc opcode if available (default) - * 1 : Use hardware counter for rdtsc if available and only if precision is at least 1GHz + * 0 : Use hardware counter for rdtsc opcode if available. [Default] + * 1 : Use hardware counter for rdtsc if and only if precision is at least 1GHz. -=item B<BOX64_SYNC_ROUNDING>=I<0|1> -Box64 will sync rounding mode with fesetround/fegetround. +=item B<BOX64_RESERVE_HIGH> =I<0|1> - * 0 : Disable rounding mode syncing. (Default.) - * 1 : Enable rounding mode syncing. +Reserve high memory area for the program, always enabled on Box32. -=item B<BOX64_LIBCEF>=I<0|1> + * 0 : Do not reserve high memory area for the program. [Default] + * 1 : Reserve high memory area for the program. -Detect libcef and apply malloc_hack settings - * 0 : Don't detect libcef - * 1 : Detect libcef, and apply MALLOC_HACK=2 if detected (Default) +=item B<BOX64_ROLLING_LOG> =I<0|1|XXX> -=item B<BOX64_LIBGL>=I<libXXXX|/PATH/TO/libGLXXX> +Show last few wrapped function call when a signal is caught. -You can also use B<SDL_VIDEO_GL_DRIVER> + * 0 : Does nothing. [Default] + * 1 : Show last 16 wrapped function call when a signal is caught. + * XXX : Show last XXX wrapped function call when a signal is caught. - * libXXXX set the name for libGL (defaults to libGL.so.1). - * /PATH/TO/libGLXXX : Sets the name and path for libGL -=item B<BOX64_EMULATED_LIBS>=I<XXXX[:YYYY:...]> +=item B<BOX64_SDL2_JGUID> =I<0|1> -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. -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 +Use a workaround for SDL_GetJoystickGUIDInfo function for wrapped SDL2. -=item B<BOX64_ALLOWMISSINGLIBS>=I<0|1> + * 0 : Does nothing. [Default] + * 1 : Use a workaround for SDL_GetJoystickGUIDInfo function for wrapped SDL2. -Allow Box64 to continue even if a library is missing. - * 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. +=item B<BOX64_SHAEXT> =I<0|1> -=item B<BOX64_PREFER_WRAPPED>=I<0|1> +Expose SHAEXT (a.k.a. SHA_NI) capabilities. -Box64 will use wrapped libs even if the lib is specified with absolute path + * 0 : Do not expose SHAEXT capabilities. + * 1 : Expose SHAEXT capabilities. [Default] - * 0 : Try to use emulated libs when they are defined with absolute path (Default.) - * 1 : Use Wrapped native libs even if path is absolute -=item B<BOX64_PREFER_EMULATED>=I<0|1> +=item B<BOX64_SHOWBT> =I<0|1> -Box64 will prefer emulated libs first (except for glibc, alsa, pulse, GL, -vulkan and X11 +Show native and emulated backtrace when a signal is caught. - * 0 : Native libs are preferred (Default.) - * 1 : Emulated libs are preferred (Default for program running inside pressure-vessel) + * 0 : Does nothing. [Default] + * 1 : Show native and emulated backtrace when a signal is caught. -=item B<BOX64_CRASHHANDLER>=I<0|1> -Box64 will use a dummy crashhandler.so library +=item B<BOX64_SHOWSEGV> =I<0|1> - * 0 : Use Emulated crashhandler.so library if needed - * 1 : Use an internal dummy (completely empty) crashhandler.so library (default) +Always show SIGSEGV signal detailes. -=item B<BOX64_MALLOC_HACK>=I<0|1|2> + * 0 : Does nothing. [Default] + * 1 : Always show SIGSEGV signal detailes. -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) +=item B<BOX64_SSE_FLUSHTO0> =I<0|1> -=item B<BOX64_NOPULSE>=I<0|1> +Behaviour of SSE Flush to 0 flags. -Disables the load of pulseaudio libraries. + * 0 : Just track the flag. [Default] + * 1 : Apply SSE Flush to 0 flag directly. - * 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 -=item B<BOX64_NOGTK>=I<0|1> +=item B<BOX64_SSE42> =I<0|1> -Disables the loading of wrapped GTK libraries. +Expose SSE4.2 capabilities. - * 0 : Load wrapped GTK libraries if found. (Default.) - * 1 : Disables loading wrapped GTK libraries. + * 0 : Do not expose SSE4.2 capabilities. + * 1 : Expose SSE4.2 capabilities. [Default] -=item B<BOX64_NOVULKAN>=I<0|1> -Disables the load of vulkan libraries. +=item B<BOX64_SYNC_ROUNDING> =I<0|1> - * 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.) +Synchronize rounding mode between x86 and native. -=item B<BOX64_FUTEX_WAITV>=I<0|1> + * 0 : Do not synchronize rounding mode. [Default] + * 1 : Synchronize rounding mode between x86 and native. -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) +=item B<BOX64_TRACE_COLOR> =I<0|1> -=item B<BOX64_BASH>=I<yyyy> +Enable or disable colored trace output. -Define x86_64 bash to launch script. 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 + * 0 : Disable colored trace output. [Default] + * 1 : Enable colored trace output. -=item B<BOX64_JITGDB>=I<0|1|2> - * 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) +=item B<BOX64_TRACE_EMM> =I<0|1> -=back +Enable or disable EMM (i.e. MMX) trace output. -=head1 VARIABLES FOR ENVIRONMENT ONLY + * 0 : Disable EMM trace output. [Default] + * 1 : Enable EMM trace output. -=over 8 -=item B<BOX64_VERSION> +=item B<BOX64_TRACE_FILE> =I<XXXX|XXXX%pid|stderr> + +Send all log and trace to a file instead of `stdout`. + + * XXXX : Send all log and trace to file XXXX. + * XXXX%pid : Send all log and trace to file XXXX with pid appended. + * stderr : Send all log and trace to `stderr`. + + +=item B<BOX64_TRACE_INIT> =I<0|1> + +Same as BOX64_TRACE but starts the trace immediately. + + * 0 : Disable trace output. [Default] + * 1 : Enable trace output. Trace starts before the initialization of dependencies. + + +=item B<BOX64_TRACE_START> =I<0|1|XXXX> + +Start trace after N opcodes executed. + + * 0 : Start trace immediately. [Default] + * 1 : Start trace after 1 opcode executed. + * XXXX : Start trace after XXXX opcodes executed. + + +=item B<BOX64_TRACE_XMM> =I<0|1> + +Enable or disable XMM (i.e. SSE) trace output. + + * 0 : Disable XMM trace output. [Default] + * 1 : Enable XMM trace output. + + +=item B<BOX64_TRACE> =I<0|1|symbolname|0xXXXXXXX-0xYYYYYYY> + +Only available on box64 build with trace. Adds trace of all instructions executed, along with a register dump. + + * 0 : Disable trace output. [Default] + * 1 : Enable trace output. + * symbolname : Enable trace output for `symbolname` only. + * 0xXXXXXXX-0xYYYYYYY : Enable trace output for the range of address (inclusive-exclusive). + + +=item B<BOX64_UNITYPLAYER> =I<0|1> + +Detect UnityPlayer and apply conservative settings. + + * 0 : Does nothing. + * 1 : Detect UnityPlayer, and apply BOX64_DYNAREC_STRONGMEM=1 when detected. [Default] + + +=item B<BOX64_WRAP_EGL> =I<0|1> + +Prefer wrapped libs for EGL and GLESv2. + + * 0 : Prefer emulated libs for EGL and GLESv2. [Default] + * 1 : Prefer wrapped libs for EGL and GLESv2. + + +=item B<BOX64_X11GLX> =I<0|1> + +Force Xorg GLX extension to be present. + + * 0 : Do not force Xorg GLX extension to be present. [Default] + * 1 : Require Xorg GLX extension when using XQueryExtension. + + +=item B<BOX64_X11SYNC> =I<0|1> + +Force synchronized operation on X11 display. + + * 0 : Do not force synchronized operation on X11 display. [Default] + * 1 : Force synchronized operation on X11 display. + + +=item B<BOX64_X11THREADS> =I<0|1> + +Call XInitThreads when loading X11. This is mostly for old Loki games with the Loki_Compat library. + + * 0 : Do not call XInitThreads. [Default] + * 1 : Call XInitThreads as soon as libX11 is loaded. + + +=item B<BOX64_X87_NO80BITS> =I<0|1> + +Behavoiur of x87 80bits long double. + + * 0 : Try to handle 80bits long double as precise as possible. [Default] + * 1 : Use 64bits double for x87. -When set, B<box64> will only print its version and then exit. This option is -analogous to B<QEMU_VERSION> used by C<binfmt_misc> emulation of qemu-user. Its -purpose is the same: provide a way to soft-disable C<binfmt_misc> emulation as -well as for identifying B<box64> as the registered C<binfmt_misc> emulator. =back diff --git a/docs/gen/gen.py b/docs/gen/gen.py new file mode 100644 index 00000000..c47cf4bd --- /dev/null +++ b/docs/gen/gen.py @@ -0,0 +1,106 @@ +# Usage: python gen.py + +import json +import os +from collections import defaultdict + +script_dir = os.path.dirname(os.path.abspath(__file__)) +usage_file = os.path.join(script_dir, 'usage.json') + +with open(usage_file, 'r') as file: + data = json.load(file) + + with open(os.path.join(script_dir, '../USAGE.md'), 'w') as md_file: + md_file.write("""<!--- This file is generated by gen.py, do not edit it directly. --> +Usage +---- + +There are many environment variables to control Box64's behaviour. + +## Configuration files + +In addition to environment variables, Box64 also looks for 2 places for rcfile: `/etc/box64.box64rc` and `~/.box64rc`, in the format of .ini files. +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` > environment variables. + +---- + +""") + + categories = defaultdict(list) + for entry in data: + categories[entry["category"]].append(entry) + + for category, entries in categories.items(): + md_file.write(f"## {category}\n\n") + for entry in entries: + md_file.write(f"### {entry['name']}\n\n{entry['description']}\n\n") + for option in entry['options']: + md_file.write(f" * {option['key']}: {option['description']} {"[Default]" if option['default'] else ""}\n") + md_file.write("\n") + + + with open(os.path.join(script_dir, '../box64.pod'), 'w') as pod_file: + pod_file.write("""=head1 NAME + +box64 - Linux Userspace x86_64 Emulator with a twist + +=head1 SYNOPSIS + +B<box64> [B<--help>] [B<--version>] I<executable> + +=head1 DESCRIPTION + +B<Box64> lets you run x86_64 Linux programs (such as games) on non-x86_64 Linux +systems, like ARM (host system needs to be 64-bit little-endian). Since B<Box64> +uses the native versions of some "system" libraries, like libc, libm, SDL, and +OpenGL, it's easy to integrate and use with most applications, and performance +can be surprisingly high in many cases. B<Box64> integrates with DynaRec (dynamic +recompiler) for the ARM64 platform, providing a speed boost between 5 to 10 +times faster than using only the interpreter. + +=head1 OPTIONS + +=over 8 + +=item B<-h,--help> + +Print box64 help and quit. + +=item B<-v,--version> + +Print box64 version and quit. + +=back + +=head1 BRIEF USAGE + +There are many environment variables to control B<Box64>'s behaviour. In +addition to environment variables, B<Box64> also looks for 2 places for rcfile: +F</etc/box64.box64rc> and F<~/.box64rc>, in the format of .ini files. +Settings priority: F<~/.box64rc> > F</etc/box64.box64rc> > environment variables. +Example: + + [factorio] + BOX64_DYNAREC_SAFEFLAGS=0 + BOX64_DYNAREC_BIGBLOCK=2 + BOX64_DYNAREC_FORWARD=1024 + BOX64_DYNAREC_CALLRET=1 + +=head1 ENVIRONMENT VARIABLES + +=over 8 + +""") + + for entry in data: + pod_file.write(f"\n=item B<{entry['name']}> =I<{ '|'.join(option['key'] for option in entry['options']) }>\n\n{entry['description']}\n\n") + for option in entry['options']: + pod_file.write(f" * {option['key']} : {option['description']} {"[Default]" if option['default'] else ""}\n") + pod_file.write("\n") + + pod_file.write(""" +=back + +=cut +""") diff --git a/docs/gen/usage.json b/docs/gen/usage.json new file mode 100644 index 00000000..395eaf09 --- /dev/null +++ b/docs/gen/usage.json @@ -0,0 +1,1605 @@ +[ + { + "name": "BOX64_ADDLIBS", + "description": "Add extras to the needed libraries list, rarely needed.", + "category": "Libraries", + "options": [ + { + "key": "XXXX", + "description": "Add library XXXX to the needed libraries list.", + "default": false + }, + { + "key": "XXXX:YYYY:ZZZZ", + "description": "Add library XXXX, YYYY and ZZZZ to the needed libraries list.", + "default": false + } + ] + }, + { + "name": "BOX64_ALLOWMISSINGLIBS", + "description": "Allow missing libraries to be ignored.", + "category": "Libraries", + "options": [ + { + "key": "0", + "description": "Do not allow missing libraries.", + "default": true + }, + { + "key": "1", + "description": "Allow missing libraries.", + "default": false + } + ] + }, + { + "name": "BOX64_ARGS", + "description": "Arguments to pass to the guest program, only valid if there is no existing arguments.", + "category": "Arguments", + "options": [ + { + "key": "XXXX", + "description": "Pass argument XXXX to the program.", + "default": false + }, + { + "key": "XXXX YYYY ZZZZ", + "description": "Pass arguments XXXX, YYYY and ZZZZ to the guest program.", + "default": false + } + ] + }, + { + "name": "BOX64_BASH", + "description": "Path to the bash executable.", + "category": "Compatibility", + "options": [ + { + "key": "XXXX", + "description": "Use bash executable at path XXXX.", + "default": false + } + ] + }, + { + "name": "BOX64_CEFDISABLEGPU", + "description": "Add -cef-disable-gpu argument to the guest program.", + "category": "Arguments", + "options": [ + { + "key": "0", + "description": "Does nothing.", + "default": true + }, + { + "key": "1", + "description": "Add -cef-disable-gpu argument to the guest program.", + "default": false + } + ] + }, + { + "name": "BOX64_CEFDISABLEGPUCOMPOSITOR", + "description": "Add -cef-disable-gpu-compositor argument to the guest program.", + "category": "Arguments", + "options": [ + { + "key": "0", + "description": "Does nothing.", + "default": true + }, + { + "key": "1", + "description": "Add -cef-disable-gpu-compositor argument to the guest program.", + "default": false + } + ] + }, + { + "name": "BOX64_CPUTYPE", + "description": "Specify the CPU type to emulate.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Emulate a Intel CPU Model.", + "default": true + }, + { + "key": "1", + "description": "Emulate a AMD CPU Model.", + "default": false + } + ] + }, + { + "name": "BOX64_CRASHHANDLER", + "description": "Use a dummy crash handler or not.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Use emulated crashhandler.so library if nedded.", + "default": false + }, + { + "key": "1", + "description": "Use an internal dummy (empty) crashhandler.so library.", + "default": true + } + ] + }, + { + "name": "BOX64_DLSYM_ERROR", + "description": "Enable or disable the logging of dlsym errors.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Disable the logging of dlsym errors.", + "default": true + }, + { + "key": "1", + "description": "Enable the logging of dlsym errors.", + "default": false + } + ] + }, + { + "name": "BOX64_DUMP", + "description": "Dump elfloader debug information.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Do not dump elfloader debug information.", + "default": true + }, + { + "key": "1", + "description": "Dump elfloader debug information.", + "default": false + } + ] + }, + { + "name": "BOX64_DYNAREC_ALIGNED_ATOMICS", + "description": "Generate aligned atomics only (only available on Arm64 for now).", + "category": "Performance", + "options": [ + { + "key": "0", + "description": "Generate unaligned atomics handling code.", + "default": true + }, + { + "key": "1", + "description": "Generate aligned atomics only, which is faster and smaller code size, but will cause SIGBUS for LOCK prefixed opcodes operating on aligned data addresses.", + "default": false + } + ] + }, + { + "name": "BOX64_DYNAREC_BIGBLOCK", + "description": "Enable building bigger DynaRec code blocks for better performance.", + "category": "Performance", + "options": [ + { + "key": "0", + "description": "Do not try to build block as big as possible, suitable for programs using lots of threads and JIT, like Unity.", + "default": false + }, + { + "key": "1", + "description": "Build Dynarec block as big as possible.", + "default": true + }, + { + "key": "2", + "description": "Build Dynarec block bigger, do not stop when block overlaps, but only for blocks in elf memory.", + "default": false + }, + { + "key": "3", + "description": "Build Dynarec block bigger, do not stop when block overlaps, for all type of memory, useful for wine programs.", + "default": false + } + ] + }, + { + "name": "BOX64_DYNAREC_BLEEDING_EDGE", + "description": "Detect MonoBleedingEdge and apply conservative settings.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Do not detect MonoBleedingEdge.", + "default": false + }, + { + "key": "1", + "description": "Detect MonoBleedingEdge and apply BOX64_DYNAREC_BIGBLOCK=0 BOX64_DYNAREC_STRONGMEM=1 when detected.", + "default": true + } + ] + }, + { + "name": "BOX64_DYNAREC_CALLRET", + "description": "Optimize CALL/RET opcodes.", + "category": "Performance", + "options": [ + { + "key": "0", + "description": "Do not optimize CALL/RET, use jump table.", + "default": true + }, + { + "key": "1", + "description": "Try to optimize CALL/RET, skipping the jump table when possible.", + "default": false + } + ] + }, + { + "name": "BOX64_DYNAREC_DF", + "description": "Enable or disable the use of deferred flags.", + "category": "Performance", + "options": [ + { + "key": "0", + "description": "Disable the use of deferred flags.", + "default": false + }, + { + "key": "1", + "description": "Enable the use of deferred flags.", + "default": true + } + ] + }, + { + "name": "BOX64_DYNAREC_DIRTY", + "description": "Allow continue running a block that is unprotected and potentially dirty.", + "category": "Performance", + "options": [ + { + "key": "0", + "description": "Do not allow continue running a block that is unprotected and potentially dirty.", + "default": true + }, + { + "key": "1", + "description": "Allow continue to run a dynablock that write data in the same page as code. It can gets faster in loading time of some game but can also get unexpected crashes.", + "default": false + } + ] + }, + { + "name": "BOX64_DYNAREC_DIV0", + "description": "Enable or disable the generation of division-by-zero exception.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Do not generate thr division-by-zero exception.", + "default": true + }, + { + "key": "1", + "description": "Generate the division-by-zero exception.", + "default": false + } + ] + }, + { + "name": "BOX64_DYNAREC_DUMP", + "description": "Enable DynaRec dump.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Do not dump DynaRec blocks.", + "default": true + }, + { + "key": "1", + "description": "Dump DynaRec blocks.", + "default": false + }, + { + "key": "2", + "description": "Dump DynaRec blocks with some colors.", + "default": false + } + ] + }, + { + "name": "BOX64_DYNAREC_FASTNAN", + "description": "Enable or disable fast NaN handling.", + "category": "Performance", + "options": [ + { + "key": "0", + "description": "Precisely emulate the -NaN generation like on x86.", + "default": false + }, + { + "key": "1", + "description": "Do not do anything special with -NAN generation, faster.", + "default": true + } + ] + }, + { + "name": "BOX64_DYNAREC_FASTROUND", + "description": "Enable or disable fast rounding.", + "category": "Performance", + "options": [ + { + "key": "0", + "description": "Generate float/double -> int rounding and use current rounding mode for float/double computation like on x86.", + "default": false + }, + { + "key": "1", + "description": "Do not do anything special with edge case rounding, faster.", + "default": true + }, + { + "key": "2", + "description": "Generate float/double -> int rounding using current rounding mode for float/double computation like on x86, but use fast int -> float/double conversion.", + "default": false + } + ] + }, + { + "name": "BOX64_DYNAREC_FORWARD", + "description": "Define max allowed forward value when building block.", + "category": "Performance", + "options": [ + { + "key": "0", + "description": "No forward value. When current block ends, do not try to go further even if there are previous forward jumps.", + "default": false + }, + { + "key": "128", + "description": "Allow up to 128 bytes of gap between end of the block and the next forward jump.", + "default": true + }, + { + "key": "XXXX", + "description": "Allow up to XXXX bytes of gap between end of the block and the next forward jump.", + "default": false + } + ] + }, + { + "name": "BOX64_DYNAREC_GDBJIT", + "description": "The GDBJIT debugging support, only available on build with `-DGDBJIT=ON`, enable it with gdb command: jit-reader-load /usr/local/lib/libbox64gdbjitreader.so.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Dynarec will not generate GDBJIT debuginfo.", + "default": true + }, + { + "key": "1", + "description": "Dynarec will generate GDBJIT debuginfo.", + "default": false + }, + { + "key": "2", + "description": "Dynarec will generate detailed GDBJIT debuginfo with internal state.", + "default": false + } + ] + }, + { + "name": "BOX64_DYNAREC_LOG", + "description": "Disable or enable DynaRec logs.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Disable DynaRec logs.", + "default": true + }, + { + "key": "1", + "description": "Enable minimal DynaRec logs.", + "default": false + }, + { + "key": "2", + "description": "Enable debug level DynaRec logs.", + "default": false + }, + { + "key": "3", + "description": "Enable verbose level DynaRec logs.", + "default": false + } + ] + }, + { + "name": "BOX64_DYNAREC_MISSING", + "description": "Print missing opcodes.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Do not print the missing opcode.", + "default": true + }, + { + "key": "1", + "description": "Print missing opcodes.", + "default": false + }, + { + "key": "2", + "description": "Print the fallback to scalar opcodes, only valid on RISC-V.", + "default": false + } + ] + }, + { + "name": "BOX64_DYNAREC_NATIVEFLAGS", + "description": "Enable or disable the use of native flags.", + "category": "Performance", + "options": [ + { + "key": "0", + "description": "Do not use native flags.", + "default": false + }, + { + "key": "1", + "description": "Use native flags when possible.", + "default": true + } + ] + }, + { + "name": "BOX64_DYNAREC_PAUSE", + "description": "Enable x86 PAUSE emulation, may help the performance of spinlocks.", + "category": "Performance", + "options": [ + { + "key": "0", + "description": "Ignore x86 PAUSE instruction.", + "default": true + }, + { + "key": "1", + "description": "Use YIELD to emulate x86 PAUSE instruction.", + "default": false + }, + { + "key": "2", + "description": "Use WFI to emulate x86 PAUSE instruction.", + "default": false + }, + { + "key": "3", + "description": "Use SEVL+WFE to emulate x86 PAUSE instruction.", + "default": false + } + ] + }, + { + "name": "BOX64_DYNAREC_PERFMAP", + "description": "Generate map file for Linux perf tool.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Dynarec will not generate perf map.", + "default": true + }, + { + "key": "1", + "description": "Dynarec will generate perf map.", + "default": false + } + ] + }, + { + "name": "BOX64_DYNAREC_SAFEFLAGS", + "description": "Behaviour of flags emulation on CALL/RET opcodes.", + "category": "Performance", + "options": [ + { + "key": "0", + "description": "Treat CALL/RET as if it never needs any flags.", + "default": false + }, + { + "key": "1", + "description": "Most of RETs will need flags, most of CALLs will not.", + "default": true + }, + { + "key": "2", + "description": "All CALL/RET will need flags.", + "default": false + } + ] + }, + { + "name": "BOX64_DYNAREC_STRONGMEM", + "description": "Enable the emulation of x86 strong memory model.", + "category": "Performance", + "options": [ + { + "key": "0", + "description": "Do not try anything special.", + "default": false + }, + { + "key": "1", + "description": "Enable some memory barriers when writing to memory to emulate the x86 strong memory model in a limited way.", + "default": true + }, + { + "key": "2", + "description": "All in 1, plus memory barriers on SIMD instructions.", + "default": false + }, + { + "key": "3", + "description": "All in 2, plus more memory barriers on a regular basis.", + "default": false + } + ] + }, + { + "name": "BOX64_DYNAREC_TBB", + "description": "Enable or disable libtbb detection.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Do not detect libtbb.", + "default": false + }, + { + "key": "1", + "description": "Detect libtbb and apply conservative settings.", + "default": true + } + ] + }, + { + "name": "BOX64_DYNAREC_TEST", + "description": "Enable DynaRec execution comparison with the interpreter, very slow, only for testing.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "No comparison.", + "default": true + }, + { + "key": "1", + "description": "Each opcode runs on interpreter and on Dynarec, regs and memory are compared and printed when they differ.", + "default": false + }, + { + "key": "0xXXXXXXXX-0xYYYYYYYY", + "description": "Define the range where dynarec is tested (inclusive-exclusive).", + "default": false + } + ] + }, + { + "name": "BOX64_DYNAREC_TRACE", + "description": "Enable or disable DynaRec trace.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Do not trace DynaRec blocks.", + "default": true + }, + { + "key": "1", + "description": "Trace DynaRec blocks, will slow down the program a lot and generates huge logs.", + "default": false + } + ] + }, + { + "name": "BOX64_DYNAREC_WAIT", + "description": "Wait or not for the building of a DynaRec code block to be ready.", + "category": "Performance", + "options": [ + { + "key": "0", + "description": "Do not wait and use interpreter instead, might speedup a bit on massive multithread or JIT programs.", + "default": false + }, + { + "key": "1", + "description": "Wait for a DynaRec code block to be ready.", + "default": true + } + ] + }, + { + "name": "BOX64_DYNAREC_WEAKBARRIER", + "description": "Tweak the memory barriers to reduce the performance impact by strong memory emualtion.", + "category": "Performance", + "options": [ + { + "key": "0", + "description": "Use regular safe barrier.", + "default": false + }, + { + "key": "1", + "description": "Use weak barriers to have more performance boost.", + "default": true + }, + { + "key": "2", + "description": "All in 1, plus disabled the last write barriers.", + "default": false + } + ] + }, + { + "name": "BOX64_DYNAREC_X87DOUBLE", + "description": "Force the use of float/double for x87 emulation.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Try to use float when possible for x87 emulation.", + "default": true + }, + { + "key": "1", + "description": "Only use Double for x87 emulation.", + "default": false + } + ] + }, + { + "name": "BOX64_EMULATED_LIBS", + "description": "Force the use of emulated libraries.", + "category": "Libraries", + "options": [ + { + "key": "XXXX", + "description": "Force the use of emulated library XXXX.", + "default": false + }, + { + "key": "XXXX:YYYY:ZZZZ", + "description": "Force the use of emulated libraries XXXX, YYYY and ZZZZ.", + "default": false + } + ] + }, + { + "name": "BOX64_ENV", + "description": "Add an environment variable.", + "category": "Environment", + "options": [ + { + "key": "XXXX=yyyy", + "description": "Add environment variable XXXX with value yyyy.", + "default": false + } + ] + }, + { + "name": "BOX64_ENV[1-5]", + "description": "Add an environment variable.", + "category": "Environment", + "options": [ + { + "key": "XXXX=yyyy", + "description": "Add environment variable XXXX with value yyyy.", + "default": false + } + ] + }, + { + "name": "BOX64_EXIT", + "description": "Just exit, do not try to run the program.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Does nothing.", + "default": true + }, + { + "key": "1", + "description": "Just exit.", + "default": false + } + ] + }, + { + "name": "BOX64_FIX_64BIT_INODES", + "description": "Fix 64bit inodes.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Do not fix 64bit inodes.", + "default": true + }, + { + "key": "1", + "description": "Fix 64bit inodes.", + "default": false + } + ] + }, + { + "name": "BOX64_IGNOREINT3", + "description": "Ignore INT3 instructions.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Trigger a TRAP signal if a handler is present.", + "default": true + }, + { + "key": "1", + "description": "Skip the opcode silently.", + "default": false + } + ] + }, + { + "name": "BOX64_INSERT_ARGS", + "description": "Prepend arguments to the command line.", + "category": "Arguments", + "options": [ + { + "key": "XXXX", + "description": "Prepend argument XXXX to the program.", + "default": false + }, + { + "key": "XXXX YYYY ZZZZ", + "description": "Prepend arguments XXXX, YYYY and ZZZZ to the guest program.", + "default": false + } + ] + }, + { + "name": "BOX64_INPROCESSGPU", + "description": "Add --in-process-gpu argument to the guest program.", + "category": "Arguments", + "options": [ + { + "key": "0", + "description": "Does nothing.", + "default": true + }, + { + "key": "1", + "description": "Add --in-process-gpu argument to the guest program.", + "default": false + } + ] + }, + { + "name": "BOX64_JITGDB", + "description": "Launch gdb or not for SIGSEGV, SIGILL, and SIGBUS.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Just print the message when the signal is caught.", + "default": true + }, + { + "key": "1", + "description": "Launch gdb when a SIGSEGV, SIGILL or SIGBUS signal is trapped, attached to the offending process and go in an endless loop, waiting. Inside 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 `set waiting=0` to exit the infinite loop.", + "default": false + }, + { + "key": "2", + "description": "Launch gdbserver when a SIGSEGV, SIGILL or SIGBUS 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`.", + "default": false + }, + { + "key": "3", + "description": "Launch lldb when a SIGSEGV, SIGILL or SIGBUS signal is trapped, attached to the offending process and go in an endless loop, waiting.", + "default": false + } + ] + }, + { + "name": "BOX64_JVM", + "description": "Detect libjvm and apply conservative settings.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Does nothing.", + "default": false + }, + { + "key": "1", + "description": "Detect libjvm, and apply BOX64_DYNAREC_BIGBLOCK=0 BOX64_DYNAREC_STRONGMEM=1 BOX64_SSE42=0 when detected.", + "default": true + } + ] + }, + { + "name": "BOX64_LD_LIBRARY_PATH", + "description": "Path to look for x86_64 libraries.", + "category": "Libraries", + "options": [ + { + "key": "XXXX", + "description": "Add path XXXX to the library path.", + "default": false + } + ] + }, + { + "name": "BOX64_LD_PRELOAD", + "description": "Force loading libraries with the binary.", + "category": "Libraries", + "options": [ + { + "key": "XXXX", + "description": "Force the loading of library XXXX.", + "default": false + }, + { + "key": "XXXX:YYYY", + "description": "Force the loading of libraries XXXX and YYYY.", + "default": false + } + ] + }, + { + "name": "BOX64_LIBCEF", + "description": "Detect libcef and apply BOX64_MALLOC_HACK settings.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Does nothing.", + "default": false + }, + { + "key": "1", + "description": "Detect libcef, and apply BOX64_MALLOC_HACK=2 if detected.", + "default": true + } + ] + }, + { + "name": "BOX64_LIBGL", + "description": "Set the name for libGL.", + "category": "Libraries", + "options": [ + { + "key": "libXXXX", + "description": "Set the name for libGL to libXXXX.", + "default": false + }, + { + "key": "/path/to/libXXXX", + "description": "Set the name and path for libGL to /path/to/libXXXX, you can also use SDL_VIDEO_GL_DRIVER.", + "default": false + } + ] + }, + { + "name": "BOX64_LOAD_ADDR", + "description": "Set the address where the program is loaded, only active for PIE guest programs.", + "category": "Debugging", + "options": [ + { + "key": "0xXXXXXXXX", + "description": "Set the address where the program is loaded.", + "default": false + } + ] + }, + { + "name": "BOX64_LOG", + "description": "Enable or disable Box64 logs.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Disable Box64 logs.", + "default": true + }, + { + "key": "1", + "description": "Enable minimal Box64 logs.", + "default": false + }, + { + "key": "2", + "description": "Enable debug level Box64 logs.", + "default": false + }, + { + "key": "3", + "description": "Enable verbose level Box64 logs.", + "default": false + } + ] + }, + { + "name": "BOX64_MALLOC_HACK", + "description": "Behaviour when hooking malloc operators.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Don't allow malloc operator to be redirected, rewriting code to use regular function.", + "default": true + }, + { + "key": "1", + "description": "Allow malloc operator to be redirected.", + "default": false + }, + { + "key": "2", + "description": "Like 0, but track special mmap/free (some redirected functions are inlined and cannot be redirected).", + "default": false + } + ] + }, + { + "name": "BOX64_MAXCPU", + "description": "Maximum CPU cores exposed.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Use the actual number of CPU cores.", + "default": true + }, + { + "key": "XXXX", + "description": "Use XXXX CPU cores.", + "default": false + } + ] + }, + { + "name": "BOX64_NOBANNER", + "description": "Disable the Box64 banner.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Show the Box64 banner.", + "default": true + }, + { + "key": "1", + "description": "Do not show the Box64 banner.", + "default": false + } + ] + }, + { + "name": "BOX64_NODYNAREC", + "description": "Forbid dynablock creation in the address range specified, helpful for debugging behaviour difference between Dynarec and Interpreter.", + "category": "Performance", + "options": [ + { + "key": "0xXXXXXXXX-0xYYYYYYYY", + "description": "Define the range where dynablock creation is forbidden (inclusive-exclusive).", + "default": false + } + ] + }, + { + "name": "BOX64_NOGTK", + "description": "Do not load wrapped GTK libraries.", + "category": "Libraries", + "options": [ + { + "key": "0", + "description": "Load wrapped GTK libraries.", + "default": true + }, + { + "key": "1", + "description": "Do not load wrapped GTK libraries.", + "default": false + } + ] + }, + { + "name": "BOX64_NOPULSE", + "description": "Do not load PulseAudio libraries (both native and x86_64).", + "category": "Libraries", + "options": [ + { + "key": "0", + "description": "Load PulseAudio libraries.", + "default": true + }, + { + "key": "1", + "description": "Do not load PulseAudio libraries.", + "default": false + } + ] + }, + { + "name": "BOX64_NORCFILES", + "description": "Do not load any rc files.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Load rc files.", + "default": true + }, + { + "key": "1", + "description": "Do not load any rc files.", + "default": false + } + ] + }, + { + "name": "BOX64_NOSANDBOX", + "description": "Add --no-sandbox argument to the guest program.", + "category": "Arguments", + "options": [ + { + "key": "0", + "description": "Does nothing.", + "default": true + }, + { + "key": "1", + "description": "Add --no-sandbox argument to the guest program.", + "default": false + } + ] + }, + { + "name": "BOX64_NOSIGSEGV", + "description": "Disable the handling of SIGSEGV.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Let the x86 program set sighandler for SIGSEGV.", + "default": true + }, + { + "key": "1", + "description": "Disable the handling of SIGSEGV.", + "default": false + } + ] + }, + { + "name": "BOX64_NOSIGILL", + "description": "Disable the handling of SIGILL.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Let the x86 program set sighandler for SIGILL.", + "default": true + }, + { + "key": "1", + "description": "Disable the handling of SIGILL.", + "default": false + } + ] + }, + { + "name": "BOX64_NOVULKAN", + "description": "Do not load Vulkan libraries.", + "category": "Libraries", + "options": [ + { + "key": "0", + "description": "Load Vulkan libraries.", + "default": true + }, + { + "key": "1", + "description": "Do not load Vulkan libraries, both native and x86_64.", + "default": false + } + ] + }, + { + "name": "BOX64_PATH", + "description": "Path to look for x86_64 binaries.", + "category": "Compatibility", + "options": [ + { + "key": "XXXX", + "description": "Add path XXXX to the binary path.", + "default": false + } + ] + }, + { + "name": "BOX64_PREFER_EMULATED", + "description": "Prefer emulated libraries over native ones.", + "category": "Libraries", + "options": [ + { + "key": "0", + "description": "Prefer native libraries over emulated ones.", + "default": true + }, + { + "key": "1", + "description": "Prefer emulated libraries over native ones.", + "default": false + } + ] + }, + { + "name": "BOX64_PREFER_WRAPPED", + "description": "Prefer wrapped libs first even if the lib is specified with absolute path.", + "category": "Libraries", + "options": [ + { + "key": "0", + "description": "Prefer libs with absolute path over wrapped ones.", + "default": true + }, + { + "key": "1", + "description": "Prefer wrapped libs first even if the lib is specified with absolute path.", + "default": false + } + ] + }, + { + "name": "BOX64_RCFILE", + "description": "Path to the rc file to load.", + "category": "Compatibility", + "options": [ + { + "key": "XXXX", + "description": "Load the rc file XXXX, default rc files will not be loaded.", + "default": false + } + ] + }, + { + "name": "BOX64_RDTSC_1GHZ", + "description": "Use hardware counter for rdtsc if available.", + "category": "Performance", + "options": [ + { + "key": "0", + "description": "Use hardware counter for rdtsc opcode if available.", + "default": true + }, + { + "key": "1", + "description": "Use hardware counter for rdtsc if and only if precision is at least 1GHz.", + "default": false + } + ] + }, + { + "name": "BOX64_RESERVE_HIGH", + "description": "Reserve high memory area for the program, always enabled on Box32.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Do not reserve high memory area for the program.", + "default": true + }, + { + "key": "1", + "description": "Reserve high memory area for the program.", + "default": false + } + ] + }, + { + "name": "BOX64_ROLLING_LOG", + "description": "Show last few wrapped function call when a signal is caught.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Does nothing.", + "default": true + }, + { + "key": "1", + "description": "Show last 16 wrapped function call when a signal is caught.", + "default": false + }, + { + "key": "XXX", + "description": "Show last XXX wrapped function call when a signal is caught.", + "default": false + } + ] + }, + { + "name": "BOX64_SDL2_JGUID", + "description": "Use a workaround for SDL_GetJoystickGUIDInfo function for wrapped SDL2.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Does nothing.", + "default": true + }, + { + "key": "1", + "description": "Use a workaround for SDL_GetJoystickGUIDInfo function for wrapped SDL2.", + "default": false + } + ] + }, + { + "name": "BOX64_SHAEXT", + "description": "Expose SHAEXT (a.k.a. SHA_NI) capabilities.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Do not expose SHAEXT capabilities.", + "default": false + }, + { + "key": "1", + "description": "Expose SHAEXT capabilities.", + "default": true + } + ] + }, + { + "name": "BOX64_SHOWBT", + "description": "Show native and emulated backtrace when a signal is caught.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Does nothing.", + "default": true + }, + { + "key": "1", + "description": "Show native and emulated backtrace when a signal is caught.", + "default": false + } + ] + }, + { + "name": "BOX64_SHOWSEGV", + "description": "Always show SIGSEGV signal detailes.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Does nothing.", + "default": true + }, + { + "key": "1", + "description": "Always show SIGSEGV signal detailes.", + "default": false + } + ] + }, + { + "name": "BOX64_SSE_FLUSHTO0", + "description": "Behaviour of SSE Flush to 0 flags.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Just track the flag.", + "default": true + }, + { + "key": "1", + "description": "Apply SSE Flush to 0 flag directly.", + "default": false + } + ] + }, + { + "name": "BOX64_SSE42", + "description": "Expose SSE4.2 capabilities.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Do not expose SSE4.2 capabilities.", + "default": false + }, + { + "key": "1", + "description": "Expose SSE4.2 capabilities.", + "default": true + } + ] + }, + { + "name": "BOX64_SYNC_ROUNDING", + "description": "Synchronize rounding mode between x86 and native.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Do not synchronize rounding mode.", + "default": true + }, + { + "key": "1", + "description": "Synchronize rounding mode between x86 and native.", + "default": false + } + ] + }, + { + "name": "BOX64_TRACE_COLOR", + "description": "Enable or disable colored trace output.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Disable colored trace output.", + "default": true + }, + { + "key": "1", + "description": "Enable colored trace output.", + "default": false + } + ] + }, + { + "name": "BOX64_TRACE_EMM", + "description": "Enable or disable EMM (i.e. MMX) trace output.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Disable EMM trace output.", + "default": true + }, + { + "key": "1", + "description": "Enable EMM trace output.", + "default": false + } + ] + }, + { + "name": "BOX64_TRACE_FILE", + "description": "Send all log and trace to a file instead of `stdout`.", + "category": "Debugging", + "options": [ + { + "key": "XXXX", + "description": "Send all log and trace to file XXXX.", + "default": false + }, + { + "key": "XXXX%pid", + "description": "Send all log and trace to file XXXX with pid appended.", + "default": false + }, + { + "key": "stderr", + "description": "Send all log and trace to `stderr`.", + "default": false + } + ] + }, + { + "name": "BOX64_TRACE_INIT", + "description": "Same as BOX64_TRACE but starts the trace immediately.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Disable trace output.", + "default": true + }, + { + "key": "1", + "description": "Enable trace output. Trace starts before the initialization of dependencies.", + "default": false + } + ] + }, + { + "name": "BOX64_TRACE_START", + "description": "Start trace after N opcodes executed.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Start trace immediately.", + "default": true + }, + { + "key": "1", + "description": "Start trace after 1 opcode executed.", + "default": false + }, + { + "key": "XXXX", + "description": "Start trace after XXXX opcodes executed.", + "default": false + } + ] + }, + { + "name": "BOX64_TRACE_XMM", + "description": "Enable or disable XMM (i.e. SSE) trace output.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Disable XMM trace output.", + "default": true + }, + { + "key": "1", + "description": "Enable XMM trace output.", + "default": false + } + ] + }, + { + "name": "BOX64_TRACE", + "description": "Only available on box64 build with trace. Adds trace of all instructions executed, along with a register dump.", + "category": "Debugging", + "options": [ + { + "key": "0", + "description": "Disable trace output.", + "default": true + }, + { + "key": "1", + "description": "Enable trace output.", + "default": false + }, + { + "key": "symbolname", + "description": "Enable trace output for `symbolname` only.", + "default": false + }, + { + "key": "0xXXXXXXX-0xYYYYYYY", + "description": "Enable trace output for the range of address (inclusive-exclusive).", + "default": false + } + ] + }, + { + "name": "BOX64_UNITYPLAYER", + "description": "Detect UnityPlayer and apply conservative settings.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Does nothing.", + "default": false + }, + { + "key": "1", + "description": "Detect UnityPlayer, and apply BOX64_DYNAREC_STRONGMEM=1 when detected.", + "default": true + } + ] + }, + { + "name": "BOX64_WRAP_EGL", + "description": "Prefer wrapped libs for EGL and GLESv2.", + "category": "Libraries", + "options": [ + { + "key": "0", + "description": "Prefer emulated libs for EGL and GLESv2.", + "default": true + }, + { + "key": "1", + "description": "Prefer wrapped libs for EGL and GLESv2.", + "default": false + } + ] + }, + { + "name": "BOX64_X11GLX", + "description": "Force Xorg GLX extension to be present.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Do not force Xorg GLX extension to be present.", + "default": true + }, + { + "key": "1", + "description": "Require Xorg GLX extension when using XQueryExtension.", + "default": false + } + ] + }, + { + "name": "BOX64_X11SYNC", + "description": "Force synchronized operation on X11 display.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Do not force synchronized operation on X11 display.", + "default": true + }, + { + "key": "1", + "description": "Force synchronized operation on X11 display.", + "default": false + } + ] + }, + { + "name": "BOX64_X11THREADS", + "description": "Call XInitThreads when loading X11. This is mostly for old Loki games with the Loki_Compat library.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Do not call XInitThreads.", + "default": true + }, + { + "key": "1", + "description": "Call XInitThreads as soon as libX11 is loaded.", + "default": false + } + ] + }, + { + "name": "BOX64_X87_NO80BITS", + "description": "Behavoiur of x87 80bits long double.", + "category": "Compatibility", + "options": [ + { + "key": "0", + "description": "Try to handle 80bits long double as precise as possible.", + "default": true + }, + { + "key": "1", + "description": "Use 64bits double for x87.", + "default": false + } + ] + } +] diff --git a/src/include/env.h b/src/include/env.h index 598cb1db..ba867f41 100644 --- a/src/include/env.h +++ b/src/include/env.h @@ -71,7 +71,7 @@ extern char* ftrace_name; BOOLEAN(BOX64_IGNOREINT3, ignoreint3, 0) \ STRING(BOX64_INSERT_ARGS, insert_args) \ BOOLEAN(BOX64_INPROCESSGPU, inprocessgpu, 0) \ - BOOLEAN(BOX64_JITGDB, jitgdb, 0) \ + INTEGER(BOX64_JITGDB, jitgdb, 0, 0, 3) \ BOOLEAN(BOX64_JVM, jvm, 1) \ STRING(BOX64_LD_LIBRARY_PATH, ld_library_path) \ BOOLEAN(BOX64_LIBCEF, libcef, 1) \ |