diff --git a/docs/USAGE.md b/docs/USAGE.md index c86cbc508d..68c8d19923 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -49,46 +49,46 @@ This configuration will apply the specified settings application-wide to any exe Enable/disable the Dynamic Recompiler (a.k.a DynaRec). This option defaults to 1 if it's enabled in the build options for a supported architecture. Available in WowBox64. - * 0: Disable DynaRec. - * 1: Enable DynaRec. + * 0: Disable DynaRec. + * 1: Enable DynaRec. ### BOX64_DYNAREC_ALIGNED_ATOMICS Generate aligned atomics only (only available on Arm64 for now). Available in WowBox64. * 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 unaligned data addresses. + * 1: Generate aligned atomics only, which is faster and smaller code size, but will cause SIGBUS for LOCK prefixed opcodes operating on unaligned data addresses. ### BOX64_DYNAREC_BIGBLOCK Enable building bigger DynaRec code blocks for better performance. Available in WowBox64. - * 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. - * 2: Build Dynarec block bigger, do not stop when block overlaps, but only for blocks in elf memory. [Default] - * 3: Build Dynarec block bigger, do not stop when block overlaps, for all type of memory, useful for wine programs. + * 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. + * 2: Build DynaRec block bigger, do not stop when block overlaps, but only for blocks in elf memory. [Default] + * 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. Available in WowBox64. * 0: Do not optimize CALL/RET, use jump table. [Default] - * 1: Try to optimize CALL/RET, skipping the jump table when possible. - * 2: Try to optimize CALL/RET, skipping the jump table when possible, adding code to handle return to dirty/modified block. Does not work on WowBox64. + * 1: Try to optimize CALL/RET, skipping the jump table when possible. + * 2: Try to optimize CALL/RET, skipping the jump table when possible, adding code to handle return to dirty/modified block. Does not work on WowBox64. ### BOX64_DYNAREC_SEP Optimize CALL/RET further with Secondary Entry Points (SEP). Has no effect if CALLRET is not enabled Available in WowBox64. - * 0: Do not add SEP at CALLRET return + * 0: Do not add SEP at CALLRET return * 1: Add SEP at CALLRET return, on memory that are from known binary files [Default] - * 2: Add SEP at CALLRET return for all type of memory. + * 2: Add SEP at CALLRET return for all type of memory. ### BOX64_DYNAREC_DF Enable or disable the use of deferred flags. Available in WowBox64. - * 0: Disable the use of deferred flags. + * 0: Disable the use of deferred flags. * 1: Enable the use of deferred flags. [Default] ### BOX64_DYNAREC_DIRTY @@ -96,51 +96,44 @@ Enable or disable the use of deferred flags. Available in WowBox64. 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. - * 2: Will also, when it detects a HotPage, flag that page as NEVERCLEAN, and so it will not be write protected but blocks built from that page will always be tested. It can be faster that way (but some SMC case might not be trapped). + * 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. + * 2: Will also, when it detects a HotPage, flag that page as NEVERCLEAN, and so it will not be write protected but blocks built from that page will always be tested. It can be faster that way (but some SMC case might not be trapped). ### BOX64_DYNAREC_NOHOTPAGE Disable detection of hot page (where code is executed and data written at the same time). * 0: Detect hot page [Default] - * 1: Do not detect hot page - -### BOX64_DYNAREC_HOTPAGE_ALT - -Use alternative way to detect HotPages (legacy way). - - * 0: Detect hot page, using new method from v0.3.9+ [Default] - * 1: Use alternate method to detect HotPage (from v0.3.8 and earlier) + * 1: Do not detect hot page ### BOX64_DYNAREC_FASTNAN Enable or disable fast NaN handling. Available in WowBox64. - * 0: Precisely emulate the -NaN generation like on x86. + * 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. Available in WowBox64. - * 0: Generate float/double -> int rounding and use current rounding mode for float/double computation like on x86. + * 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. + * 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. Available in WowBox64. - * 0: No forward value. When current block ends, do not try to go further even if there are previous forward jumps. + * 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. + * 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. Available in WowBox64. - * 0: Do not use native flags. + * 0: Do not use native flags. * 1: Use native flags when possible. [Default] ### BOX64_DYNAREC_PAUSE @@ -148,112 +141,106 @@ Enable or disable the use of native flags. Available in WowBox64. Enable x86 PAUSE emulation, may help the performance of spinlocks. Available in WowBox64. * 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. + * 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_PURGE -Purge dynablocks that haven't been executed recently, based on tick age threshold (BOX64_DYNAREC_PURGE_AGE). +Purge DynaBlocks that haven't been executed recently, based on tick age threshold (BOX64_DYNAREC_PURGE_AGE). - * 0: Dynarec will not purge old unused dynablocks. [Default] - * 1: Dynarec will purge old unused dynablocks based on tick age. + * 0: DynaRec will not purge old unused DynaBlocks. [Default] + * 1: DynaRec will purge old unused DynaBlocks based on tick age. ### BOX64_DYNAREC_PURGE_AGE -Tick age threshold for dynablock purging (requires BOX64_DYNAREC_PURGE=1). +Tick age threshold for DynaBlock purging (requires BOX64_DYNAREC_PURGE=1). * 4096: Default age threshold. [Default] - * XXXX: Custom age threshold (range: 10-65536). + * XXXX: Custom age threshold (range: 10-65536). ### BOX64_DYNAREC_SAFEFLAGS Behaviour of flags emulation on CALL/RET opcodes and other edge cases. Available in WowBox64. - * 0: Treat CALL/RET as if it never needs any flags. + * 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. All edge cases are also handled. + * 2: All CALL/RET will need flags. All edge cases are also handled. ### BOX64_DYNAREC_STRONGMEM Enable the emulation of x86 strong memory model. Available in WowBox64. * 0: Do not try anything special. [Default] - * 1: Enable some memory barriers when writing to memory to emulate the x86 strong memory model in a limited way. - * 2: All in 1, plus memory barriers on SIMD instructions. - * 3: All in 2, plus more memory barriers on a regular basis. - * 4: Mimic x86 TSO similarly to QEMU's approach, for evaluation purposes. + * 1: Enable some memory barriers when writing to memory to emulate the x86 strong memory model in a limited way. + * 2: All in 1, plus memory barriers on SIMD instructions. + * 3: All in 2, plus more memory barriers on a regular basis. + * 4: Mimic x86 TSO similarly to QEMU's approach, for evaluation purposes. ### BOX64_DYNAREC_VOLATILE_METADATA Use volatile metadata parsed from PE files, only valid for 64bit Windows games. - * 0: Do not use volatile metadata. + * 0: Do not use volatile metadata. * 1: Use volatile metadata, which will guide Box64 for better strong memory emulation. [Default] ### BOX64_DYNAREC_WAIT Wait or not for the building of a DynaRec code block to be ready. Available in WowBox64. - * 0: Do not wait and use interpreter instead, might speedup a bit on massive multithread or JIT programs. + * 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 emulation. Available in WowBox64. - * 0: Use regular safe barrier. + * 0: Use regular safe barrier. * 1: Use weak barriers to have more performance boost. [Default] - * 2: All in 1, plus disable the last write barriers. + * 2: All in 1, plus disable the last write barriers. ### BOX64_DYNACACHE Enable/disable the Dynamic Recompiler Cache (a.k.a DynaCache). This option defaults to 2 (to read cache if present but not generate any). DynaCache writes files to the home folder by default, and can grow without limit. - * 0: Disable DynaCache. - * 1: Enable DynaCache. + * 0: Disable DynaCache. + * 1: Enable DynaCache. * 2: Use DynaCache files if present, but do not generate new one. [Default] ### BOX64_DYNACACHE_FOLDER Set the folder for DynaCache files. Default is $XDG_CACHE_HOME/box64 or $HOME/.cache/box64 if $XDG_CACHE_HOME is not set. - * XXXX: Use folder XXXX for DynaCache files. + * XXXX: Use folder XXXX for DynaCache files. ### BOX64_DYNACACHE_MIN Minimum size, in KB, for a DynaCache to be written to disk. Default size is 350KB - * XXXX: Set a minimum size of XXXX KB of Dynarec code to write the dynacache to disk. Will not be saved to disk else. + * XXXX: Set a minimum size of XXXX KB of DynaRec code to write the dynacache to disk. Will not be saved to disk else. * 350: A size of 350 KB is the default value. [Default] ### BOX64_MMAP32 Force 32-bit compatible memory mappings on 64-bit programs that run 32-bit code (like Wine WOW64), can improve performance. - * 0: Do not force 32-bit memory mappings. + * 0: Do not force 32-bit memory mappings. * 1: Force 32-bit memory mappings. [Default] -### BOX64_NODYNAREC - -Forbid dynablock creation in the address range specified, helpful for debugging behaviour difference between Dynarec and Interpreter. Available in WowBox64. - - * 0xXXXXXXXX-0xYYYYYYYY: Define the range where dynablock creation is forbidden (inclusive-exclusive). - ### BOX64_DYNAREC_NOARCH -Remove Architecture metadata from Dynarec blocks (used on signal). Available in WowBox64. +Remove Architecture metadata from DynaRec blocks (used on signal). Available in WowBox64. * 0: Generate all architecture metadata for each blocks, including x87/mmx/SSE/AVX regs tracking. Will use some more memory. [Default] - * 1: Generate only essential metadata for each blocks (flags, alignments), saving some memory, but some encrypted software might fail. - * 2: Do not generate metadata for blocks. Saving a bit more memory but might fail on signal handling. + * 1: Generate only essential metadata for each blocks (flags, alignments), saving some memory, but some encrypted software might fail. + * 2: Do not generate metadata for blocks. Saving a bit more memory but might fail on signal handling. ### 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. + * 1: Use hardware counter for rdtsc if and only if precision is at least 1GHz. ## Arguments @@ -261,29 +248,29 @@ Use hardware counter for rdtsc if available. 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. + * XXXX: Pass argument XXXX to the program. + * XXXX YYYY ZZZZ: Pass arguments XXXX, YYYY and ZZZZ 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. + * 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. + * 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. + * 1: Add --no-sandbox argument to the guest program. ## Compatibility @@ -291,51 +278,51 @@ Add --no-sandbox argument to the guest program. Expose AES capabilities. Available in WowBox64. - * 0: Do not expose AES capabilities. + * 0: Do not expose AES capabilities. * 1: Expose AES capabilities. [Default] ### BOX64_ARCH Specify the architecture in rcfiles to which the current entry applies. This option only takes effect when used inside rcfiles. - * `arm64`: Only apply current entry for AArch64. - * `la64`: Only apply current entry for LoongArch64. - * `rv64`: Only apply current entry for RISC-V. + * `arm64`: Only apply current entry for AArch64. + * `la64`: Only apply current entry for LoongArch64. + * `rv64`: Only apply current entry for RISC-V. * ``: Apply current entry for all architectures, will be replaced by more specific entries. [Default] ### BOX64_AVX Expose AVX extension to CPUID and cpuinfo file. Default value is 2 on Arm64 because it's fully implemented in DynaRec, 0 otherwise. Available in WowBox64. - * 0: Do not expose AVX capabilities. - * 1: Expose AVX, BMI1, F16C and VAES extensions to CPUID and cpuinfo file. - * 2: All in 1, plus AVX2, BMI2, FMA, ADX,VPCLMULQDQ and RDRAND extensions. + * 0: Do not expose AVX capabilities. + * 1: Expose AVX, BMI1, F16C and VAES extensions to CPUID and cpuinfo file. + * 2: All in 1, plus AVX2, BMI2, FMA, ADX,VPCLMULQDQ and RDRAND extensions. ### BOX64_BASH Path to the bash executable. - * XXXX: Use bash executable at path XXXX. + * XXXX: Use bash executable at path XXXX. ### BOX64_CPUTYPE Specify the CPU type to emulate. Available in WowBox64. * 0: Emulate a Intel CPU Model. [Default] - * 1: Emulate a AMD CPU Model. + * 1: Emulate a AMD CPU Model. ### BOX64_CRASHHANDLER Use a dummy crash handler or not. - * 0: Use emulated crashhandler.so library if needed. + * 0: Use emulated crashhandler.so library if needed. * 1: Use an internal dummy (empty) crashhandler.so library. [Default] ### BOX64_DYNAREC_BLEEDING_EDGE Detect MonoBleedingEdge and apply conservative settings (Linux only). - * 0: Do not detect MonoBleedingEdge. + * 0: Do not detect MonoBleedingEdge. * 1: Detect MonoBleedingEdge and apply BOX64_DYNAREC_BIGBLOCK=0 BOX64_DYNAREC_STRONGMEM=1 when detected. [Default] ### BOX64_DYNAREC_DIV0 @@ -343,13 +330,13 @@ Detect MonoBleedingEdge and apply conservative settings (Linux only). Enable or disable the generation of division-by-zero exception. Available in WowBox64. * 0: Do not generate the division-by-zero exception. [Default] - * 1: Generate the division-by-zero exception. + * 1: Generate the division-by-zero exception. ### BOX64_DYNAREC_TBB Enable or disable libtbb detection. - * 0: Do not detect libtbb. + * 0: Do not detect libtbb. * 1: Detect libtbb and apply conservative settings. [Default] ### BOX64_DYNAREC_X87DOUBLE @@ -357,49 +344,49 @@ Enable or disable libtbb detection. Force the use of float/double for x87 emulation. Available in WowBox64. * 0: Try to use float when possible for x87 emulation. [Default] - * 1: Only use Double for x87 emulation. - * 2: Check Precision Control low precision on x87 emulation. + * 1: Only use Double for x87 emulation. + * 2: Check Precision Control low precision on x87 emulation. ### BOX64_DYNAREC_INTERP_SIGNAL -Allow the use of Dynarec in Signal Handlers. +Allow the use of DynaRec in Signal Handlers. - * 0: Allow the use of Dynarec in signal handlers. [Default] - * 1: Only use the Interpreter for signal handlers (as it was in v0.3.8 and earlier). + * 0: Allow the use of DynaRec in signal handlers. [Default] + * 1: Only use the Interpreter for signal handlers (as it was in v0.3.8 and earlier). ### BOX64_EXIT Just exit, do not try to run the program. * 0: Does nothing. [Default] - * 1: Just exit. + * 1: Just exit. ### BOX64_FIX_64BIT_INODES Fix 64bit inodes. * 0: Do not fix 64bit inodes. [Default] - * 1: Fix 64bit inodes. + * 1: Fix 64bit inodes. ### BOX64_FORCE_LD_PRELOAD Force symbols from BOX64_LD_PRELOAD libraries to be resolved by RTLD_NEXT. * 0: Do nothing. [Default] - * 1: Force symbols from BOX64_LD_PRELOAD libraries to be resolved by RTLD_NEXT. + * 1: Force symbols from BOX64_LD_PRELOAD libraries to be resolved by RTLD_NEXT. ### BOX64_IGNOREINT3 Ignore INT3 instructions. * 0: Trigger a TRAP signal if a handler is present. [Default] - * 1: Skip the opcode silently. + * 1: Skip the opcode silently. ### BOX64_JVM Detect libjvm and apply conservative settings. - * 0: Does nothing. + * 0: Does nothing. * 1: Detect libjvm, and apply BOX64_DYNAREC_BIGBLOCK=0 BOX64_DYNAREC_STRONGMEM=1 BOX64_SSE42=0 when detected. [Default] ### BOX64_LIBCEF @@ -407,91 +394,91 @@ Detect libjvm and apply conservative settings. Detect libcef and apply BOX64_MALLOC_HACK settings. * 0: Does nothing. [Default] - * 1: Detect libcef, and apply BOX64_MALLOC_HACK=2 if detected. + * 1: Detect libcef, and apply BOX64_MALLOC_HACK=2 if detected. ### 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). + * 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. Available in WowBox64. * 0: Use the actual number of CPU cores. [Default] - * XXXX: Use XXXX CPU cores. + * 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. + * 1: Do not load any rc files. ### BOX64_PATH Path to look for x86_64 binaries. - * XXXX: Add path XXXX to the binary path. + * XXXX: Add path XXXX to the binary path. ### BOX64_PCLMULQDQ Expose PCLMULQDQ capabilities. Available in WowBox64. - * 0: Do not expose PCLMULQDQ capabilities. + * 0: Do not expose PCLMULQDQ capabilities. * 1: Expose PCLMULQDQ capabilities. [Default] ### BOX64_PROFILE Predefined sets of environment variables with compatibility or performance in mind. Available in WowBox64. - * safest: Profile with all the unsafe DynaRec optimizations disabled. - * safe: Well, less safer than safest. + * safest: Profile with all the unsafe DynaRec optimizations disabled. + * safe: Well, less safer than safest. * default: The default settings that most programs runs fine with a handy performance. [Default] - * fast: Enable many unsafe optimizations, but also enable strongmem emulation. - * fastest: Enable many unsafe optimizations to have a better performance. + * fast: Enable many unsafe optimizations, but also enable strongmem emulation. + * fastest: Enable many unsafe optimizations to have a better performance. ### BOX64_PYTHON3 Path to a python3 executable. - * XXXX: Use python3 executable at path XXXX. + * XXXX: Use python3 executable at path XXXX. ### BOX64_RCFILE Path to the rc file to load. - * XXXX: Load the rc file XXXX, default rc files will not be loaded. + * XXXX: Load the rc file XXXX, default rc files will not be loaded. ### BOX64_RDTSC_INV -Report Invariant TSC bit in CPUID for Intel CPU type. +Report Invariant TSC bit in CPUID for Intel CPU type. Available in WowBox64. * 0: Do not report Invariant TSC for Intel CPU type (default). [Default] - * 1: Report Invariant TSC bit in CPUID leaf 0x80000007 for Intel CPU type. + * 1: Report Invariant TSC bit in CPUID leaf 0x80000007 for Intel CPU type. ### 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. + * 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. + * 1: Use a workaround for SDL_GetJoystickGUIDInfo function for wrapped SDL2. ### BOX64_SHAEXT Expose SHAEXT (a.k.a. SHA_NI) capabilities. Available in WowBox64. - * 0: Do not expose SHAEXT capabilities. + * 0: Do not expose SHAEXT capabilities. * 1: Expose SHAEXT capabilities. [Default] ### BOX64_SSE_FLUSHTO0 @@ -499,13 +486,13 @@ Expose SHAEXT (a.k.a. SHA_NI) capabilities. Available in WowBox64. Behaviour of SSE Flush to 0 flags. Also tracking SSE exception flags. Available in WowBox64. * 0: Just track the flag. [Default] - * 1: Apply SSE Flush to 0 flag directly. Also reflect SSE exception flags in Dynarec (if available) + * 1: Apply SSE Flush to 0 flag directly. Also reflect SSE exception flags in DynaRec (if available) ### BOX64_SSE42 Expose SSE4.2 capabilities. Available in WowBox64. - * 0: Do not expose SSE4.2 capabilities. + * 0: Do not expose SSE4.2 capabilities. * 1: Expose SSE4.2 capabilities. [Default] ### BOX64_STEAM_VULKAN @@ -513,27 +500,27 @@ Expose SSE4.2 capabilities. Available in WowBox64. Force Vulkan for Linux Steam UI. * 0: Do nothing. [Default] - * 1: Force Vulkan for Linux Steam UI. + * 1: Force Vulkan for Linux Steam UI. ### 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. + * 1: Synchronize rounding mode between x86 and native. ### BOX64_UNITYPLAYER Detect UnityPlayer and apply conservative settings. - * 0: Does nothing. + * 0: Does nothing. * 1: Detect UnityPlayer (Windows or Linux), and apply BOX64_UNITY=1 when detected. [Default] ### BOX64_UNITY Games is a Unity one. - * 0: Does nothing. + * 0: Does nothing. * 1: Unity Game, use special detecting code for Windows, apply BOX64_DYNAREC_STRONGMEM=1 for Linux. [Default] ### BOX64_X11GLX @@ -541,28 +528,35 @@ Games is a Unity one. 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. + * 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. + * 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. + * 1: Call XInitThreads as soon as libX11 is loaded. ### BOX64_X87_NO80BITS Behaviour of x87 80bits long double. Available in WowBox64. * 0: Try to handle 80bits long double as precise as possible. [Default] - * 1: Use 64bits double for x87. + * 1: Use 64bits double for x87. + +### BOX64_NOPERSONA32BITS + +Disable the automatic switch of personality for 32-bit binaries (always enabled on Box32). + + * 0: Switch personality for 32-bit binaries (if not already tried). [Default] + * 1: Do not switch personality for 32-bit binaries. ## Debugging @@ -571,91 +565,91 @@ Behaviour of x87 80bits long double. Available in WowBox64. Enable or disable the logging of dlsym errors. * 0: Disable the logging of dlsym errors. [Default] - * 1: Enable the logging of dlsym errors. + * 1: Enable the logging of dlsym errors. ### BOX64_DUMP Dump elfloader debug information. Available in WowBox64. * 0: Do not dump elfloader debug information. [Default] - * 1: Dump elfloader debug information. + * 1: Dump elfloader debug information. ### BOX64_DYNAREC_DUMP Enable DynaRec dump. Available in WowBox64. * 0: Do not dump DynaRec blocks. [Default] - * 1: Dump DynaRec blocks. - * 2: Dump DynaRec blocks with some colors. + * 1: Dump DynaRec blocks. + * 2: Dump DynaRec blocks with some colors. ### BOX64_DYNAREC_DUMP_RANGE Dump DynaRec blocks in the specified range. Available in WowBox64. - * 0xXXXXXXXX-0xYYYYYYYY: Define the range where dynablock gets dumped (inclusive-exclusive). + * 0xXXXXXXXX-0xYYYYYYYY: Define the range where DynaBlock gets dumped (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. - * 3: Dynarec will register detailed GDBJIT debuginfo only for dynablocks that the guest program trap into, greatly improving performance. - * 0xXXXXXXX-0xYYYYYYY: Define the range where Dynarec will generate detailed GDBJIT debuginfo with internal state. + * 0: DynaRec will not generate GDBJIT debuginfo. [Default] + * 1: DynaRec will generate GDBJIT debuginfo. + * 2: DynaRec will generate detailed GDBJIT debuginfo with internal state. + * 3: DynaRec will register detailed GDBJIT debuginfo only for DynaBlocks that the guest program trap into, greatly improving performance. + * 0xXXXXXXX-0xYYYYYYY: Define the range where DynaRec will generate detailed GDBJIT debuginfo with internal state. ### BOX64_DYNAREC_LOG Disable or enable DynaRec logs. Available in WowBox64. * 0: Disable DynaRec logs. [Default] - * 1: Enable minimal DynaRec logs. - * 2: Enable debug level DynaRec logs. - * 3: Enable verbose level DynaRec logs. + * 1: Enable minimal DynaRec logs. + * 2: Enable debug level DynaRec logs. + * 3: Enable verbose level DynaRec logs. ### BOX64_DYNAREC_MISSING Print missing opcodes. Available in WowBox64. * 0: Do not print the missing opcode. [Default] - * 1: Print missing opcodes. - * 2: Print the fallback to scalar opcodes, only valid on RISC-V. + * 1: Print missing opcodes. + * 2: Print the fallback to scalar opcodes, only valid on RISC-V. ### BOX64_DYNAREC_NOHOSTEXT Disable optional host extensions. * 0: Disable nothing. [Default] - * 1: Disable all the optional extensions. - * xxx,yyy,zzz: Disable selected optional extensions, choices are Arm: `crc32,pmull,aes,atomics,sha1,sha2,uscat,flagm,flagm2,frintts,afp,rndr`, LoongArch: `lasx,lbt,frecipe,lam_bh,lamcas,scq`, and RISC-V: `zba,zbb,zbc,zbs,vector,xtheadba,xtheadbb,xtheadbs,xtheadmemidx,xtheadmempair,xtheadcondmov`. + * 1: Disable all the optional extensions. + * xxx,yyy,zzz: Disable selected optional extensions, choices are Arm: `crc32,pmull,aes,atomics,sha1,sha2,uscat,flagm,flagm2,frintts,afp,rndr`, LoongArch: `lasx,lbt,frecipe,lam_bh,lamcas,scq`, and RISC-V: `zba,zbb,zbc,zbs,vector,xtheadba,xtheadbb,xtheadbs,xtheadmemidx,xtheadmempair,xtheadcondmov`. ### BOX64_DYNAREC_PERFMAP Generate map file for Linux perf tool. - * 0: Dynarec will not generate perf map. [Default] - * 1: Dynarec will generate perf map. + * 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. Available in WowBox64. * 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). + * 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_TEST_NODUP Enable deduplication of IP address where COSIM find a difference. Available in WowBox64. * 0: Show all addresses in error. [Default] - * 1: Show address in error only 1 time, even if dump might differs. + * 1: Show address in error only 1 time, even if dump might differs. ### BOX64_DYNAREC_TEST_NODUMP Do not dump test code when BOX64_DYNAREC_DUMP is enabled. Available in WowBox64. - * 0: Dump test code. + * 0: Dump test code. * 1: Do not dump test code. [Default] ### BOX64_DYNAREC_TRACE @@ -663,137 +657,143 @@ Do not dump test code when BOX64_DYNAREC_DUMP is enabled. Available in WowBox64. 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. + * 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 its 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. + * 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 its 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. + * 0xXXXXXXXX: Set the address where the program is loaded. ### BOX64_LOG Enable or disable Box64 logs, default value is 0 if stdout is not terminal, 1 otherwise. Available in WowBox64. - * 0: Disable Box64 logs. - * 1: Enable minimal Box64 logs. - * 2: Enable debug level Box64 logs. - * 3: Enable verbose level Box64 logs. + * 0: Disable Box64 logs. + * 1: Enable minimal Box64 logs. + * 2: Enable debug level Box64 logs. + * 3: Enable verbose level Box64 logs. ### BOX64_NOBANNER Disable the Box64 banner. Available in WowBox64. - * 0: Show the Box64 banner. - * 1: Do not show the Box64 banner. + * 0: Show the Box64 banner. + * 1: Do not show the Box64 banner. + +### BOX64_NODYNAREC + +Forbid DynaBlock creation in the address range specified, helpful for debugging behaviour difference between DynaRec and Interpreter. Available in WowBox64. + + * 0xXXXXXXXX-0xYYYYYYYY: Define the range where DynaBlock creation is forbidden (inclusive-exclusive). ### BOX64_NODYNAREC_DELAY -Remove NoDynarec range after a delay. Available in WowBox64. +Remove NoDynaRec range after a delay. Available in WowBox64. - * 0: Do not remove NoDynarec range. [Default] - * 1: Remove the NoDynarec range once 2 threads have been created. + * 0: Do not remove NoDynaRec range. [Default] + * 1: Remove the NoDynaRec range once 2 threads have been created. ### BOX64_NOSIGSEGV Disable the handling of SIGSEGV. * 0: Let the x86 program set sighandler for SIGSEGV. [Default] - * 1: Disable the handling of SIGSEGV. + * 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. + * 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. - * XXXX: Show last XXXX wrapped function call when a signal is caught. + * 1: Show last 16 wrapped function call when a signal is caught. + * XXXX: Show last XXXX 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. + * 1: Show native and emulated backtrace when a signal is caught. ### BOX64_SHOWSEGV Always show SIGSEGV signal details. * 0: Does nothing. [Default] - * 1: Always show SIGSEGV signal details. + * 1: Always show SIGSEGV signal details. ### BOX64_TRACE_COLOR Enable or disable colored trace output. * 0: Disable colored trace output. [Default] - * 1: Enable colored trace output. + * 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. + * 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. + * 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`. [Default] - * stdout: Send all log and trace to `stdout`. + * stdout: Send all log and trace to `stdout`. ### 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. - * symbolname: Enable trace output for `symbolname` only. Trace starts before the initialization of dependencies. - * 0xXXXXXXX-0xYYYYYYY: Enable trace output for the range of address (inclusive-exclusive). Trace starts before the initialization of dependencies. + * 1: Enable trace output. Trace starts before the initialization of dependencies. + * symbolname: Enable trace output for `symbolname` only. Trace starts before the initialization of dependencies. + * 0xXXXXXXX-0xYYYYYYY: Enable trace output for the range of address (inclusive-exclusive). 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. + * 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. + * 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). + * 1: Enable trace output. + * symbolname: Enable trace output for `symbolname` only. + * 0xXXXXXXX-0xYYYYYYY: Enable trace output for the range of address (inclusive-exclusive). ## Environment @@ -801,13 +801,13 @@ Only available on box64 build with trace. Adds trace of all instructions execute Add an environment variable. - * XXXX=yyyy: Add environment variable XXXX with value yyyy. + * 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. + * XXXX=yyyy: Add environment variable XXXX with value yyyy. ## Libraries @@ -815,89 +815,89 @@ Add an environment variable. 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. + * 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. + * 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. + * 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. + * 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. + * 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. + * 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. + * 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. + * 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. + * 1: Do not load Vulkan libraries, both native and x86_64. ### BOX64_NOVULKANOVERLAY Do not load x64 Vulkan overlay. * 0: Try to load x64 Vulkan overlay. [Default] - * 1: Do not load x64 Vulkan overlay. + * 1: Do not load x64 Vulkan overlay. ### BOX64_PREFER_EMULATED Prefer emulated libraries over native ones. * 0: Prefer native libraries over emulated ones. [Default] - * 1: Prefer emulated libraries over native ones. + * 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. + * 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. + * 1: Prefer wrapped libs for EGL and GLESv2. diff --git a/docs/USAGE_CN.md b/docs/USAGE_CN.md new file mode 100644 index 0000000000..fceb14dff6 --- /dev/null +++ b/docs/USAGE_CN.md @@ -0,0 +1,903 @@ + +使用说明 +---- + +Box64 有许多环境变量可用于控制其行为，下面将按类别列出。 + +Box64 有两种构建类型：Wine WOW64 构建（WowBox64）和常规 Linux 构建。请注意，只有部分环境变量在 WowBox64 中可用。 + +### 配置文件 + +除了环境变量之外，如果你使用的是常规 Linux 构建，Box64 默认还会在两个位置查找 rcfile：系统范围的 `/etc/box64.box64rc` 和用户目录下的 `~/.box64rc`。 +而在 WowBox64 中，配置文件仅在 `%USERPROFILE%/.box64rc` 处检查。 +设置的优先级如下（从高到低）：`~/.box64rc` > `/etc/box64.box64rc` > 环境变量。 + +配置示例： + +``` +[factorio] +BOX64_DYNAREC_SAFEFLAGS=0 +BOX64_DYNAREC_BIGBLOCK=2 +BOX64_DYNAREC_FORWARD=1024 +BOX64_DYNAREC_CALLRET=1 +``` + +此配置将使所有名为 `factorio` 的可执行文件应用指定的设置。 + +### Linux 构建的高级用法 + +1. **通配符匹配** + + 可以使用星号（`*`）对应用程序名称进行基本的模式匹配。例如，`[*setup*]` 将匹配名称中包含 "setup" 的任何程序。请注意，这里实现的是简单的通配符匹配，而非完整的正则表达式支持。 +2. **自定义配置文件** + + `BOX64_RCFILE` 环境变量可以指定一个替代的配置文件，而不是默认的 `/etc/box64.box64rc`。 +3. **按文件设置** + + 以 `/` 开头的配置项适用于特定文件。例如： + ``` + [/d3d9.dll] + BOX64_DYNAREC_SAFEFLAGS=0 + ``` + 这些设置将仅影响 `d3d9.dll` 文件。此语法同样适用于**模拟的** Linux 库，例如 `[/libstdc++.so.6]`。 + +---- + +## 性能 + +### BOX64_DYNAREC + +启用或禁用动态重编译器（DynaRec）。如果在支持的架构上构建时开启了 DynaRec 支持，则默认为 1。 在 WowBox64 中可用。 + + * 0: 禁用 DynaRec。 + * 1: 启用 DynaRec。 + +### BOX64_DYNAREC_ALIGNED_ATOMICS + +仅生成对齐的原子操作（目前仅在 Arm64 上可用）。 在 WowBox64 中可用。 + + * 0: 生成非对齐原子操作处理代码。 [默认值] + * 1: 仅生成对齐的原子操作，代码更快更小，但在非对齐数据地址上执行 LOCK 前缀指令时会导致 SIGBUS。 + +### BOX64_DYNAREC_BIGBLOCK + +尝试构建更大的代码块以提高性能。 在 WowBox64 中可用。 + + * 0: 不尝试构建尽可能大的代码块，适用于使用大量线程和 JIT 的程序（如 Unity）。 + * 1: 尽可能构建大的代码块。 + * 2: 构建更大的代码块，代码块重叠时不停止，但仅针对 elf 内存中的代码块。 [默认值] + * 3: 构建更大的代码块，代码块重叠时不停止，适用于所有类型的内存，因此也对 wine 程序有用。 + +### BOX64_DYNAREC_CALLRET + +优化 CALL/RET 指令。 在 WowBox64 中可用。 + + * 0: 不优化 CALL/RET，使用跳转表。 [默认值] + * 1: 尝试优化 CALL/RET，在可能的情况下跳过跳转表。 + * 2: 尝试优化 CALL/RET，在可能的情况下跳过跳转表，同时增加对返回到脏/已修改代码块的代码的处理。在 WowBox64 上不可用。 + +### BOX64_DYNAREC_SEP + +使用二级入口点（SEP）进一步优化 CALL/RET。如果 CALLRET 未启用则无效。 在 WowBox64 中可用。 + + * 0: 不在 CALLRET 返回时添加 SEP。 + * 1: 在 CALLRET 返回时添加 SEP，仅针对来自已知二进制文件的内存。 [默认值] + * 2: 在 CALLRET 返回时添加 SEP，适用于所有类型的内存。 + +### BOX64_DYNAREC_DF + +启用或禁用延迟 FLAGS 的使用。 在 WowBox64 中可用。 + + * 0: 禁用延迟 FLAGS 的使用。 + * 1: 启用延迟 FLAGS 的使用。 [默认值] + +### BOX64_DYNAREC_DIRTY + +是否允许继续运行未受保护且可能已脏的代码块。 + + * 0: 不允许继续运行未受保护且可能已脏的代码块。 [默认值] + * 1: 允许继续运行在与代码相同页面中写入数据的代码块，可以加快某些游戏的加载时间，但也可能导致意外崩溃。 + * 2: 除了 1 之外，当检测到热页时，将该页面标记为永不写保护，但基于该页面构建的代码块将始终被测试。这样可以更快（但某些 SMC 情况可能无法捕获）。 + +### BOX64_DYNAREC_NOHOTPAGE + +是否禁用热页检测（即代码执行和数据写入同时发生的页面）。 + + * 0: 检测热页。 [默认值] + * 1: 不检测热页。 + +### BOX64_DYNAREC_FASTNAN + +启用或禁用快速 NaN 处理。 在 WowBox64 中可用。 + + * 0: 精确模拟 x86 上的 -NaN 生成。 + * 1: 不对 -NaN 生成做任何特殊处理，速度更快。 [默认值] + +### BOX64_DYNAREC_FASTROUND + +启用或禁用快速舍入。 在 WowBox64 中可用。 + + * 0: 生成 float/double -> int 舍入，并使用当前舍入模式进行 float/double 计算，类似 x86。 + * 1: 不对边缘情况的舍入做任何特殊处理，速度更快。 [默认值] + * 2: 使用当前舍入模式生成 float/double -> int 舍入（类似 x86），但使用快速的 int -> float/double 转换。 + +### BOX64_DYNAREC_FORWARD + +定义构建代码块时允许的最大前向跳转值。 在 WowBox64 中可用。 + + * 0: 无前向跳转值。当前代码块结束时，即使存在之前的前向跳转也不尝试继续前进。 + * 128: 允许代码块结束与下一个前向跳转之间最多 128 字节的间隙。 [默认值] + * XXXX: 允许代码块结束与下一个前向跳转之间最多 XXXX 字节的间隙。 + +### BOX64_DYNAREC_NATIVEFLAGS + +启用或禁用原生FLAGS的使用。 在 WowBox64 中可用。 + + * 0: 不使用原生FLAGS。 + * 1: 在可能的情况下使用原生FLAGS。 [默认值] + +### BOX64_DYNAREC_PAUSE + +启用 x86 PAUSE 模拟，可能有助于自旋锁的性能。 在 WowBox64 中可用。 + + * 0: 忽略 x86 PAUSE 指令。 [默认值] + * 1: 使用 YIELD 模拟 x86 PAUSE 指令。 + * 2: 使用 WFI 模拟 x86 PAUSE 指令。 + * 3: 使用 SEVL+WFE 模拟 x86 PAUSE 指令。 + +### BOX64_DYNAREC_PURGE + +根据年龄阈值（BOX64_DYNAREC_PURGE_AGE）清除最近未执行的代码块。 + + * 0: DynaRec 不会清除旧的未使用代码块。 [默认值] + * 1: DynaRec 将根据年龄阈值清除旧的未使用代码块。 + +### BOX64_DYNAREC_PURGE_AGE + +代码块清除的年龄阈值（需要 BOX64_DYNAREC_PURGE=1）。 + + * 4096: 默认年龄阈值。 [默认值] + * XXXX: 自定义年龄阈值（范围：10-65536）。 + +### BOX64_DYNAREC_SAFEFLAGS + +在 CALL/RET 指令和其他边缘情况下 FLAGS 模拟的行为。 在 WowBox64 中可用。 + + * 0: 将 CALL/RET 标记为从不需要任何 FLAGS。 + * 1: 将大多数 RET 标记为需要 FLAGS，将大多数 CALL 标记为不需要。 [默认值] + * 2: 将所有 CALL/RET 都标记为需要 FLAGS。同时也处理所有边缘情况。 + +### BOX64_DYNAREC_STRONGMEM + +开启或关闭 x86 强内存模型的模拟。 在 WowBox64 中可用。 + + * 0: 不做任何特殊处理。 [默认值] + * 1: 在写入内存时启用以有限方式模拟 x86 强内存模型的内存屏障。 + * 2: 包含 1 的全部内容，外加 SIMD 指令的内存屏障。 + * 3: 包含 2 的全部内容，外加定期添加更多内存屏障。 + * 4: 模仿 x86 TSO，类似 QEMU 的方法，可用于评估目的。 + +### BOX64_DYNAREC_VOLATILE_METADATA + +使用从 PE 文件解析的 volatile 元数据，仅对 64 位 Windows 游戏有效。 + + * 0: 不使用 volatile 元数据。 + * 1: 使用 volatile 元数据，将指导 Box64 进行更好的强内存模拟。 [默认值] + +### BOX64_DYNAREC_WAIT + +是否等待代码块构建完成。 在 WowBox64 中可用。 + + * 0: 不等待，改用解释器，可能在大量多线程或 JIT 程序上略微加速。 + * 1: 等待代码块构建完成。 [默认值] + +### BOX64_DYNAREC_WEAKBARRIER + +调整内存屏障以减少强内存模拟的性能影响。 在 WowBox64 中可用。 + + * 0: 使用常规安全屏障。 + * 1: 使用弱屏障以获得更多性能提升。 [默认值] + * 2: 包含 1 的全部内容，外加禁用最后的写屏障。 + +### BOX64_DYNACACHE + +启用或禁用动态重编译器缓存（DynaCache）。此选项默认为 2（读取已有缓存但不生成新的）。DynaCache 默认将文件写入 home 文件夹，且可能无限增长。 + + * 0: 禁用 DynaCache。 + * 1: 启用 DynaCache。 + * 2: 使用已有的 DynaCache 文件，但不生成新的。 [默认值] + +### BOX64_DYNACACHE_FOLDER + +设置 DynaCache 文件的文件夹。默认为 $XDG_CACHE_HOME/box64，如果 $XDG_CACHE_HOME 未设置则为 $HOME/.cache/box64。 + + * XXXX: 使用文件夹 XXXX 存储 DynaCache 文件。 + +### BOX64_DYNACACHE_MIN + +DynaCache 写入磁盘的最小大小（KB）。默认大小为 350KB。 + + * XXXX: 设置将缓存写入磁盘的最小 DynaRec 代码大小（XXXX KB），小于此值将不会保存到磁盘。 + * 350: 默认值为 350 KB。 [默认值] + +### BOX64_MMAP32 + +在运行 32 位代码的 64 位程序（如 Wine WOW64）上强制使用 32 位兼容的内存映射，可提高性能。 + + * 0: 不强制使用 32 位内存映射。 + * 1: 强制使用 32 位内存映射。 [默认值] + +### BOX64_DYNAREC_NOARCH + +从代码块中移除架构元数据（在信号处理时使用）。 在 WowBox64 中可用。 + + * 0: 为每个代码块生成所有架构元数据，包括 x87/mmx/SSE/AVX 寄存器追踪。会使用更多内存。 [默认值] + * 1: 仅生成每个代码块的必要元数据（FLAGS、对齐），节省一些内存，但某些加密软件可能会失败。 + * 2: 不为代码块生成元数据，进一步节省内存，但在信号处理时可能会失败。 + +### BOX64_RDTSC_1GHZ + +如果可用，使用硬件计数器实现 rdtsc。 + + * 0: 如果可用，使用硬件计数器实现 rdtsc 指令。 [默认值] + * 1: 仅当精度至少为 1GHz 时，使用硬件计数器实现 rdtsc。 + +## 兼容性 + +### BOX64_AES + +是否暴露 AES 能力。 在 WowBox64 中可用。 + + * 0: 不暴露 AES 能力。 + * 1: 暴露 AES 能力。 [默认值] + +### BOX64_ARCH + +在 rcfile 中指定当前条目适用的架构。此选项仅在 rcfile 中使用时生效。 + + * `arm64`: 仅对 AArch64 应用当前条目。 + * `la64`: 仅对 LoongArch64 应用当前条目。 + * `rv64`: 仅对 RISC-V 应用当前条目。 + * ``: 对所有架构应用当前条目，但如果存在更具体的条目，当前条目将被替换。 [默认值] + +### BOX64_AVX + +向 CPUID 和 cpuinfo 文件暴露 AVX 扩展。在 Arm64 上默认值为 2，因为 DynaRec 已完全实现，其他架构默认为 0。 在 WowBox64 中可用。 + + * 0: 不暴露 AVX 能力。 + * 1: 向 CPUID 和 cpuinfo 文件暴露 AVX、BMI1、F16C 和 VAES 扩展。 + * 2: 包含 1 的全部内容，外加 AVX2、BMI2、FMA、ADX、VPCLMULQDQ 和 RDRAND 扩展。 + +### BOX64_BASH + +用于指定 bash 可执行文件的路径。 + + * XXXX: 使用路径为 XXXX 的 bash 可执行文件。 + +### BOX64_CPUTYPE + +指定要模拟的 CPU 类型。 在 WowBox64 中可用。 + + * 0: 模拟某个 Intel CPU 型号。 [默认值] + * 1: 模拟某个 AMD CPU 型号。 + +### BOX64_CRASHHANDLER + +是否使用模拟的 crashhandler.so 库。 + + * 0: 在需要时使用模拟的 crashhandler.so 库。 + * 1: 使用内部定义的空 crashhandler.so 库。 [默认值] + +### BOX64_DYNAREC_BLEEDING_EDGE + +检测 MonoBleedingEdge 并应用保守设置（仅 Linux）。 + + * 0: 不检测 MonoBleedingEdge。 + * 1: 检测 MonoBleedingEdge，并在检测到时应用 BOX64_DYNAREC_BIGBLOCK=0 和 BOX64_DYNAREC_强内存模型=1。 [默认值] + +### BOX64_DYNAREC_DIV0 + +启用或禁用除零异常的生成。 在 WowBox64 中可用。 + + * 0: 不生成除零异常。 [默认值] + * 1: 生成除零异常。 + +### BOX64_DYNAREC_TBB + +启用或禁用 libtbb 检测。 + + * 0: 不检测 libtbb。 + * 1: 检测 libtbb 并应用保守设置。 [默认值] + +### BOX64_DYNAREC_X87DOUBLE + +强制使用 float/double 进行 x87 模拟。 在 WowBox64 中可用。 + + * 0: 尝试在可能的情况下对 x87 模拟使用 float。 [默认值] + * 1: 仅对 x87 模拟使用 Double。 + * 2: 在 x87 模拟中检查精度控制的低精度。 + +### BOX64_DYNAREC_INTERP_SIGNAL + +允许在信号处理器中使用 DynaRec。 + + * 0: 允许在信号处理器中使用 DynaRec。 [默认值] + * 1: 仅在信号处理器中使用解释器（与 v0.3.8 及更早版本相同）。 + +### BOX64_EXIT + +直接退出，不运行程序。 + + * 0: 不执行任何操作。 [默认值] + * 1: 直接退出。 + +### BOX64_FIX_64BIT_INODES + +修复 64 位 inode。 + + * 0: 不修复 64 位 inode。 [默认值] + * 1: 修复 64 位 inode。 + +### BOX64_FORCE_LD_PRELOAD + +是否强制 BOX64_LD_PRELOAD 库中的符号通过 RTLD_NEXT 解析。 + + * 0: 不执行任何操作。 [默认值] + * 1: 强制 BOX64_LD_PRELOAD 库中的符号通过 RTLD_NEXT 解析。 + +### BOX64_IGNOREINT3 + +忽略 INT3 指令。 + + * 0: 如果存在处理器则触发 TRAP 信号。 [默认值] + * 1: 静默跳过该指令。 + +### BOX64_JVM + +检测 libjvm 并应用保守设置。 + + * 0: 不执行任何操作。 + * 1: 检测 libjvm，并在检测到时应用 BOX64_DYNAREC_BIGBLOCK=0 BOX64_DYNAREC_强内存模型=1 BOX64_SSE42=0。 [默认值] + +### BOX64_LIBCEF + +检测 libcef 并应用 BOX64_MALLOC_HACK 设置。 + + * 0: 不执行任何操作。 [默认值] + * 1: 检测 libcef，并在检测到时应用 BOX64_MALLOC_HACK=2。 + +### BOX64_MALLOC_HACK + +挂钩 malloc 操作符时的行为。 + + * 0: 不允许重定向 malloc 操作符，重写代码使用常规函数。 [默认值] + * 1: 允许重定向 malloc 操作符。 + * 2: 与 0 类似，但追踪特殊的 mmap/free（某些内联的重定向函数无法被重定向）。 + +### BOX64_MAXCPU + +暴露的最大 CPU 核心数。 在 WowBox64 中可用。 + + * 0: 使用实际的 CPU 核心数。 [默认值] + * XXXX: 使用 XXXX 个 CPU 核心。 + +### BOX64_NORCFILES + +不加载任何 rc 文件。 + + * 0: 加载 rc 文件。 [默认值] + * 1: 不加载任何 rc 文件。 + +### BOX64_PATH + +查找 x86_64 二进制文件的路径。 + + * XXXX: 将路径 XXXX 添加到二进制搜索路径。 + +### BOX64_PCLMULQDQ + +暴露 PCLMULQDQ 能力。 在 WowBox64 中可用。 + + * 0: 不暴露 PCLMULQDQ 能力。 + * 1: 暴露 PCLMULQDQ 能力。 [默认值] + +### BOX64_PROFILE + +预定义的环境变量集合，以兼容性或性能为导向。 在 WowBox64 中可用。 + + * safest: 禁用所有不安全的 DynaRec 优化的配置文件。 + * safe: 比 safest 略不安全。 + * default: 大多数程序都能正常运行且性能适中的默认设置。 [默认值] + * fast: 启用许多不安全的优化，但同时启用 强内存模型 模拟。 + * fastest: 启用许多不安全的优化以获得更好的性能。 + +### BOX64_PYTHON3 + +python3 可执行文件的路径。 + + * XXXX: 使用路径为 XXXX 的 python3 可执行文件。 + +### BOX64_RCFILE + +要加载的 rc 文件路径。 + + * XXXX: 加载 rc 文件 XXXX，不会加载默认的 rc 文件。 + +### BOX64_RDTSC_INV + +在 Intel CPU 类型的 CPUID 中报告 Invariant TSC 位。 在 WowBox64 中可用。 + + * 0: 不为 Intel CPU 类型报告 Invariant TSC（默认）。 [默认值] + * 1: 在 Intel CPU 类型的 CPUID leaf 0x80000007 中报告 Invariant TSC 位。 + +### BOX64_RESERVE_HIGH + +为程序保留高内存区域，在 Box32 上始终启用。 + + * 0: 不为程序保留高内存区域。 [默认值] + * 1: 为程序保留高内存区域。 + +### BOX64_SDL2_JGUID + +对包装的 SDL2 使用 SDL_GetJoystickGUIDInfo 函数的变通方案。 + + * 0: 不执行任何操作。 [默认值] + * 1: 对包装的 SDL2 使用 SDL_GetJoystickGUIDInfo 函数的变通方案。 + +### BOX64_SHAEXT + +暴露 SHAEXT（即 SHA_NI）能力。 在 WowBox64 中可用。 + + * 0: 不暴露 SHAEXT 能力。 + * 1: 暴露 SHAEXT 能力。 [默认值] + +### BOX64_SSE_FLUSHTO0 + +SSE Flush to 0 FLAGS的行为，同时追踪 SSE 异常FLAGS。 在 WowBox64 中可用。 + + * 0: 仅追踪FLAGS。 [默认值] + * 1: 直接应用 SSE Flush to 0 FLAGS。同时在 DynaRec 中反映 SSE 异常FLAGS（如果可用）。 + +### BOX64_SSE42 + +暴露 SSE4.2 能力。 在 WowBox64 中可用。 + + * 0: 不暴露 SSE4.2 能力。 + * 1: 暴露 SSE4.2 能力。 [默认值] + +### BOX64_STEAM_VULKAN + +为 Linux Steam UI 强制使用 Vulkan。 + + * 0: 不执行任何操作。 [默认值] + * 1: 为 Linux Steam UI 强制使用 Vulkan。 + +### BOX64_SYNC_ROUNDING + +在 x86 和原生之间同步舍入模式。 + + * 0: 不同步舍入模式。 [默认值] + * 1: 在 x86 和原生之间同步舍入模式。 + +### BOX64_UNITYPLAYER + +检测 UnityPlayer 并应用保守设置。 + + * 0: 不执行任何操作。 + * 1: 检测 UnityPlayer（Windows 或 Linux），并在检测到时应用 BOX64_UNITY=1。 [默认值] + +### BOX64_UNITY + +告诉 Box64 这是一个 Unity 游戏。 + + * 0: 不执行任何操作。 + * 1: 这是 Unity 游戏，对 Windows 使用特殊的检测代码，对 Linux 应用 BOX64_DYNAREC_强内存模型=1。 [默认值] + +### BOX64_X11GLX + +是否强制 Xorg GLX 扩展存在。 + + * 0: 不强制 Xorg GLX 扩展存在。 [默认值] + * 1: 在使用 XQueryExtension 时要求 Xorg GLX 扩展存在。 + +### BOX64_X11SYNC + +是否强制 X11 显示同步操作。 + + * 0: 不强制 X11 显示同步操作。 [默认值] + * 1: 强制 X11 显示同步操作。 + +### BOX64_X11THREADS + +加载 X11 时调用 XInitThreads。这主要用于使用 Loki_Compat 库的旧 Loki 游戏。 + + * 0: 不调用 XInitThreads。 [默认值] + * 1: 一旦加载 libX11 就调用 XInitThreads。 + +### BOX64_X87_NO80BITS + +x87 80 位 long double 的行为。 在 WowBox64 中可用。 + + * 0: 尝试尽可能精确地处理 80 位 long double。 [默认值] + * 1: 对 x87 使用 64 位 double。 + +### BOX64_NOPERSONA32BITS + +禁用 32 位二进制文件的自动 personality 切换（在 Box32 上始终启用）。 + + * 0: 为 32 位二进制文件切换 personality（如果尚未尝试）。 [默认值] + * 1: 不为 32 位二进制文件切换 personality。 + +## 参数 + +### BOX64_ARGS + +传递给目标程序的参数，仅在没有任何已有参数时有效。 + + * XXXX: 将 XXXX 参数传递给目标程序。 + * XXXX YYYY ZZZZ: 将 XXXX、YYYY 和 ZZZZ 参数传递给目标程序。 + +### BOX64_INSERT_ARGS + +在命令行前添加参数。 + + * XXXX: 在程序前添加参数 XXXX。 + * XXXX YYYY ZZZZ: 在目标程序前添加参数 XXXX、YYYY 和 ZZZZ。 + +### BOX64_INPROCESSGPU + +向目标程序添加 --in-process-gpu 参数。 + + * 0: 不执行任何操作。 [默认值] + * 1: 向目标程序添加 --in-process-gpu 参数。 + +### BOX64_NOSANDBOX + +向目标程序添加 --no-sandbox 参数。 + + * 0: 不执行任何操作。 [默认值] + * 1: 向目标程序添加 --no-sandbox 参数。 + +## 库 + +### BOX64_ADDLIBS + +添加额外需要的共享库（这个选项不太常用）。 + + * XXXX: 将 XXXX 共享库添加到所需库列表。 + * XXXX:YYYY:ZZZZ: 将 XXXX、YYYY 和 ZZZZ 共享库添加到所需库列表。 + +### BOX64_ALLOWMISSINGLIBS + +是否允许忽略缺失的共享库。 + + * 0: 不允许忽略缺失的共享库。 [默认值] + * 1: 允许忽略缺失的共享库。 + +### BOX64_EMULATED_LIBS + +强制使用模拟库。 + + * XXXX: 强制使用模拟库 XXXX。 + * XXXX:YYYY:ZZZZ: 强制使用模拟库 XXXX、YYYY 和 ZZZZ。 + +### BOX64_LD_LIBRARY_PATH + +查找 x86_64 库的路径。 + + * XXXX: 将路径 XXXX 添加到库搜索路径。 + +### BOX64_LD_PRELOAD + +强制随二进制文件加载库。 + + * XXXX: 强制加载库 XXXX。 + * XXXX:YYYY: 强制加载库 XXXX 和 YYYY。 + +### BOX64_LIBGL + +设置 libGL 的名称。 + + * libXXXX: 将 libGL 的名称设置为 libXXXX。 + * /path/to/libXXXX: 将 libGL 的名称和路径设置为 /path/to/libXXXX，你也可以使用 SDL_VIDEO_GL_DRIVER。 + +### BOX64_NOGTK + +不加载包装的 GTK 库。 + + * 0: 加载包装的 GTK 库。 [默认值] + * 1: 不加载包装的 GTK 库。 + +### BOX64_NOPULSE + +不加载 PulseAudio 库（原生库和模拟库均不加载）。 + + * 0: 加载 PulseAudio 库。 [默认值] + * 1: 不加载 PulseAudio 库。 + +### BOX64_NOVULKAN + +不加载 Vulkan 库。 + + * 0: 加载 Vulkan 库。 [默认值] + * 1: 不加载 Vulkan 库，原生库和模拟库均不加载。 + +### BOX64_NOVULKANOVERLAY + +不加载 x64 Vulkan 覆盖层。 + + * 0: 尝试加载 x64 Vulkan 覆盖层。 [默认值] + * 1: 不加载 x64 Vulkan 覆盖层。 + +### BOX64_PREFER_EMULATED + +优先使用模拟库而非原生库。 + + * 0: 优先使用原生库而非模拟库。 [默认值] + * 1: 优先使用模拟库而非原生库。 + +### BOX64_PREFER_WRAPPED + +即使库使用绝对路径指定，也优先使用包装库。 + + * 0: 优先使用绝对路径指定的库而非包装库。 [默认值] + * 1: 即使库使用绝对路径指定，也优先使用包装库。 + +### BOX64_WRAP_EGL + +优先使用包装库处理 EGL 和 GLESv2。 + + * 0: 优先使用模拟库处理 EGL 和 GLESv2。 [默认值] + * 1: 优先使用包装库处理 EGL 和 GLESv2。 + +## 环境变量 + +### BOX64_ENV + +添加环境变量。 + + * XXXX=yyyy: 添加值为 yyyy 的环境变量 XXXX。 + +### BOX64_ENV[1-5] + +添加环境变量。 + + * XXXX=yyyy: 添加值为 yyyy 的环境变量 XXXX。 + +## 调试 + +### BOX64_DLSYM_ERROR + +启用或禁用 dlsym 错误的日志记录。 + + * 0: 禁用 dlsym 错误的日志记录。 [默认值] + * 1: 启用 dlsym 错误的日志记录。 + +### BOX64_DUMP + +是否输出 elfloader 调试信息。 在 WowBox64 中可用。 + + * 0: 不输出 elfloader 调试信息。 [默认值] + * 1: 输出 elfloader 调试信息。 + +### BOX64_DYNAREC_DUMP + +启用 DynaRec 转储。 在 WowBox64 中可用。 + + * 0: 不转储代码块。 [默认值] + * 1: 转储代码块。 + * 2: 转储代码块并带有颜色。 + +### BOX64_DYNAREC_DUMP_RANGE + +转储指定范围内的代码块。 在 WowBox64 中可用。 + + * 0xXXXXXXXX-0xYYYYYYYY: 定义代码块 被转储的范围（左闭右开）。 + +### BOX64_DYNAREC_GDBJIT + +GDBJIT 调试支持，仅在使用 `-DGDBJIT=ON` 构建时可用，通过 gdb 命令启用：jit-reader-load /usr/local/lib/libbox64gdbjitreader.so。 + + * 0: DynaRec 不会生成 GDBJIT 调试信息。 [默认值] + * 1: DynaRec 将生成 GDBJIT 调试信息。 + * 2: DynaRec 将生成包含内部状态的详细 GDBJIT 调试信息。 + * 3: DynaRec 将仅对目标程序陷入的代码块 注册详细的 GDBJIT 调试信息，大幅提升性能。 + * 0xXXXXXXX-0xYYYYYYY: 定义 DynaRec 将生成包含内部状态的详细 GDBJIT 调试信息的范围。 + +### BOX64_DYNAREC_LOG + +禁用或启用 DynaRec 日志。 在 WowBox64 中可用。 + + * 0: 禁用 DynaRec 日志。 [默认值] + * 1: 启用最小级别的 DynaRec 日志。 + * 2: 启用调试级别的 DynaRec 日志。 + * 3: 启用详细级别的 DynaRec 日志。 + +### BOX64_DYNAREC_MISSING + +打印缺失的指令。 在 WowBox64 中可用。 + + * 0: 不打印缺失的指令。 [默认值] + * 1: 打印缺失的指令。 + * 2: 打印回退到标量指令的信息，仅对 RISC-V 有效。 + +### BOX64_DYNAREC_NOHOSTEXT + +禁用可选的主机扩展。 + + * 0: 不禁用任何扩展。 [默认值] + * 1: 禁用所有可选扩展。 + * xxx,yyy,zzz: 禁用指定的可选扩展，可选项包括 Arm：`crc32,pmull,aes,atomics,sha1,sha2,uscat,flagm,flagm2,frintts,afp,rndr`，LoongArch：`lasx,lbt,frecipe,lam_bh,lamcas,scq`，以及 RISC-V：`zba,zbb,zbc,zbs,vector,xtheadba,xtheadbb,xtheadbs,xtheadmemidx,xtheadmempair,xtheadcondmov`。 + +### BOX64_DYNAREC_PERFMAP + +为 Linux perf 工具生成映射文件。 + + * 0: DynaRec 不会生成 perf 映射。 [默认值] + * 1: DynaRec 将生成 perf 映射。 + +### BOX64_DYNAREC_TEST + +启用 DynaRec 与解释器的执行对比，非常慢，仅用于测试。 在 WowBox64 中可用。 + + * 0: 不进行对比。 [默认值] + * 1: 每个指令都在解释器和 DynaRec 上运行，当寄存器或内存不同时进行对比并打印。 + * 0xXXXXXXXX-0xYYYYYYYY: 定义 DynaRec 测试的范围（左闭右开）。 + +### BOX64_DYNAREC_TEST_NODUP + +启用 COSIM 发现差异的 IP 地址去重。 在 WowBox64 中可用。 + + * 0: 显示所有出错的地址。 [默认值] + * 1: 每个出错地址仅显示一次，即使转储可能不同。 + +### BOX64_DYNAREC_TEST_NODUMP + +当 BOX64_DYNAREC_DUMP 启用时不转储测试代码。 在 WowBox64 中可用。 + + * 0: 转储测试代码。 + * 1: 不转储测试代码。 [默认值] + +### BOX64_DYNAREC_TRACE + +启用或禁用 DynaRec 追踪。 + + * 0: 不追踪代码块。 [默认值] + * 1: 追踪代码块，会大幅降低程序速度并生成大量日志。 + +### BOX64_JITGDB + +发生 SIGSEGV、SIGILL 和 SIGBUS 时是否启动 gdb。 + + * 0: 捕获信号时仅打印消息。 [默认值] + * 1: 当捕获到 SIGSEGV、SIGILL 或 SIGBUS 信号时启动 gdb，附加到有问题的进程并进入无限循环等待。在 gdb 中，你需要自己找到正确的线程（在其堆栈中有 `my_box64signalhandler` 的线程），然后可能需要 `finish` 1 或 2 个函数（在 `usleep(..)` 内部），之后你将进入 `my_box64signalhandler`，就在 Segfault 消息的 printf 之前。然后 `set waiting=0` 退出无限循环。 + * 2: 当捕获到 SIGSEGV、SIGILL 或 SIGBUS 信号时启动 gdbserver，附加到有问题的进程，并进入无限循环等待。使用 `gdb /PATH/TO/box64` 然后 `target remote 127.0.0.1:1234` 连接到 gdbserver（如果不在本机，则使用实际 IP）。之后的操作步骤与 `BOX64_JITGDB=1` 相同。 + * 3: 当捕获到 SIGSEGV、SIGILL 或 SIGBUS 信号时启动 lldb，附加到有问题的进程并进入无限循环等待。 + +### BOX64_LOAD_ADDR + +设置程序加载的地址，仅对 PIE 目标程序有效。 + + * 0xXXXXXXXX: 设置程序加载的地址。 + +### BOX64_LOG + +启用或禁用 Box64 日志，如果 stdout 不是终端则默认为 0，否则为 1。 在 WowBox64 中可用。 + + * 0: 禁用 Box64 日志。 + * 1: 启用最小级别的 Box64 日志。 + * 2: 启用调试级别的 Box64 日志。 + * 3: 启用详细级别的 Box64 日志。 + +### BOX64_NOBANNER + +禁用 Box64 横幅。 在 WowBox64 中可用。 + + * 0: 显示 Box64 横幅。 + * 1: 不显示 Box64 横幅。 + +### BOX64_NODYNAREC + +在指定的地址范围内禁止创建代码块，有助于调试 DynaRec 和解释器之间的行为差异。 在 WowBox64 中可用。 + + * 0xXXXXXXXX-0xYYYYYYYY: 定义禁止创建代码块 的范围（左闭右开）。 + +### BOX64_NODYNAREC_DELAY + +延迟后移除 NoDynaRec 范围。 在 WowBox64 中可用。 + + * 0: 不移除 NoDynaRec 范围。 [默认值] + * 1: 创建 2 个线程后移除 NoDynaRec 范围。 + +### BOX64_NOSIGSEGV + +禁用 SIGSEGV 的处理。 + + * 0: 允许 x86 程序为 SIGSEGV 设置信号处理器。 [默认值] + * 1: 禁用 SIGSEGV 的处理。 + +### BOX64_NOSIGILL + +禁用 SIGILL 的处理。 + + * 0: 允许 x86 程序为 SIGILL 设置信号处理器。 [默认值] + * 1: 禁用 SIGILL 的处理。 + +### BOX64_ROLLING_LOG + +当捕获信号时显示最近几个包装函数调用。 + + * 0: 不执行任何操作。 [默认值] + * 1: 捕获信号时显示最近 16 个包装函数调用。 + * XXXX: 捕获信号时显示最近 XXXX 个包装函数调用。 + +### BOX64_SHOWBT + +捕获信号时显示原生和模拟的回溯。 + + * 0: 不执行任何操作。 [默认值] + * 1: 捕获信号时显示原生和模拟的回溯。 + +### BOX64_SHOWSEGV + +始终显示 SIGSEGV 信号详情。 + + * 0: 不执行任何操作。 [默认值] + * 1: 始终显示 SIGSEGV 信号详情。 + +### BOX64_TRACE_COLOR + +启用或禁用彩色追踪输出。 + + * 0: 禁用彩色追踪输出。 [默认值] + * 1: 启用彩色追踪输出。 + +### BOX64_TRACE_EMM + +启用或禁用 EMM（即 MMX）追踪输出。 + + * 0: 禁用 EMM 追踪输出。 [默认值] + * 1: 启用 EMM 追踪输出。 + +### BOX64_TRACE_FILE + +将所有日志和追踪发送到文件而非 `stdout`。 + + * XXXX: 将所有日志和追踪发送到文件 XXXX。 + * XXXX%pid: 将所有日志和追踪发送到文件 XXXX，文件名中附加 pid。 + * stderr: 将所有日志和追踪发送到 `stderr`。 [默认值] + * stdout: 将所有日志和追踪发送到 `stdout`。 + +### BOX64_TRACE_INIT + +与 BOX64_TRACE 相同，但立即开始追踪。 + + * 0: 禁用追踪输出。 [默认值] + * 1: 启用追踪输出。追踪在依赖项初始化之前开始。 + * symbolname: 仅对 `symbolname` 启用追踪输出。追踪在依赖项初始化之前开始。 + * 0xXXXXXXX-0xYYYYYYY: 对指定地址范围（左闭右开）启用追踪输出。追踪在依赖项初始化之前开始。 + +### BOX64_TRACE_START + +在 N 个指令执行后开始追踪。 + + * 0: 立即开始追踪。 [默认值] + * 1: 执行 1 个指令后开始追踪。 + * XXXX: 执行 XXXX 个指令后开始追踪。 + +### BOX64_TRACE_XMM + +启用或禁用 XMM（即 SSE）追踪输出。 + + * 0: 禁用 XMM 追踪输出。 [默认值] + * 1: 启用 XMM 追踪输出。 + +### BOX64_TRACE + +仅在带追踪功能的 box64 构建中可用。添加所有执行指令的追踪以及寄存器转储。 + + * 0: 禁用追踪输出。 [默认值] + * 1: 启用追踪输出。 + * symbolname: 仅对 `symbolname` 启用追踪输出。 + * 0xXXXXXXX-0xYYYYYYY: 对指定地址范围（左闭右开）启用追踪输出。 + diff --git a/docs/box64.pod b/docs/box64.pod index b0c9888cb7..4d6fd8370a 100644 --- a/docs/box64.pod +++ b/docs/box64.pod @@ -160,9 +160,9 @@ Generate aligned atomics only (only available on Arm64 for now). Available in Wo Enable building bigger DynaRec code blocks for better performance. Available in WowBox64. * 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. - * 2 : Build Dynarec block bigger, do not stop when block overlaps, but only for blocks in elf memory. [Default] - * 3 : Build Dynarec block bigger, do not stop when block overlaps, for all type of memory, useful for wine programs. + * 1 : Build DynaRec block as big as possible. + * 2 : Build DynaRec block bigger, do not stop when block overlaps, but only for blocks in elf memory. [Default] + * 3 : Build DynaRec block bigger, do not stop when block overlaps, for all type of memory, useful for wine programs. =item B =I<0|1> @@ -204,7 +204,7 @@ Enable or disable the use of deferred flags. Available in WowBox64. 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. + * 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. * 2 : Will also, when it detects a HotPage, flag that page as NEVERCLEAN, and so it will not be write protected but blocks built from that page will always be tested. It can be faster that way (but some SMC case might not be trapped). @@ -216,14 +216,6 @@ Disable detection of hot page (where code is executed and data written at the sa * 1 : Do not detect hot page -=item B =I<0|1> - -Use alternative way to detect HotPages (legacy way). - - * 0 : Detect hot page, using new method from v0.3.9+ [Default] - * 1 : Use alternate method to detect HotPage (from v0.3.8 and earlier) - - =item B =I<0|1> Enable or disable the generation of division-by-zero exception. Available in WowBox64. @@ -245,7 +237,7 @@ Enable DynaRec dump. Available in WowBox64. Dump DynaRec blocks in the specified range. Available in WowBox64. - * 0xXXXXXXXX-0xYYYYYYYY : Define the range where dynablock gets dumped (inclusive-exclusive). + * 0xXXXXXXXX-0xYYYYYYYY : Define the range where DynaBlock gets dumped (inclusive-exclusive). =item B =I<0|1> @@ -278,11 +270,11 @@ Define max allowed forward value when building block. Available in WowBox64. 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. - * 3 : Dynarec will register detailed GDBJIT debuginfo only for dynablocks that the guest program trap into, greatly improving performance. - * 0xXXXXXXX-0xYYYYYYY : Define the range where Dynarec will generate detailed GDBJIT debuginfo with internal state. + * 0 : DynaRec will not generate GDBJIT debuginfo. [Default] + * 1 : DynaRec will generate GDBJIT debuginfo. + * 2 : DynaRec will generate detailed GDBJIT debuginfo with internal state. + * 3 : DynaRec will register detailed GDBJIT debuginfo only for DynaBlocks that the guest program trap into, greatly improving performance. + * 0xXXXXXXX-0xYYYYYYY : Define the range where DynaRec will generate detailed GDBJIT debuginfo with internal state. =item B =I<0|1|2|3> @@ -335,21 +327,21 @@ Enable x86 PAUSE emulation, may help the performance of spinlocks. Available in Generate map file for Linux perf tool. - * 0 : Dynarec will not generate perf map. [Default] - * 1 : Dynarec will generate perf map. + * 0 : DynaRec will not generate perf map. [Default] + * 1 : DynaRec will generate perf map. =item B =I<0|1> -Purge dynablocks that haven't been executed recently, based on tick age threshold (BOX64_DYNAREC_PURGE_AGE). +Purge DynaBlocks that haven't been executed recently, based on tick age threshold (BOX64_DYNAREC_PURGE_AGE). - * 0 : Dynarec will not purge old unused dynablocks. [Default] - * 1 : Dynarec will purge old unused dynablocks based on tick age. + * 0 : DynaRec will not purge old unused DynaBlocks. [Default] + * 1 : DynaRec will purge old unused DynaBlocks based on tick age. =item B =I<4096|XXXX> -Tick age threshold for dynablock purging (requires BOX64_DYNAREC_PURGE=1). +Tick age threshold for DynaBlock purging (requires BOX64_DYNAREC_PURGE=1). * 4096 : Default age threshold. [Default] * XXXX : Custom age threshold (range: 10-65536). @@ -388,8 +380,8 @@ Enable or disable libtbb detection. Enable DynaRec execution comparison with the interpreter, very slow, only for testing. Available in WowBox64. * 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). + * 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). =item B =I<0|1> @@ -452,9 +444,9 @@ Force the use of float/double for x87 emulation. Available in WowBox64. =item B =I<0|1> -Allow the use of Dynarec in Signal Handlers. +Allow the use of DynaRec in Signal Handlers. - * 0 : Allow the use of Dynarec in signal handlers. [Default] + * 0 : Allow the use of DynaRec in signal handlers. [Default] * 1 : Only use the Interpreter for signal handlers (as it was in v0.3.8 and earlier). @@ -478,7 +470,7 @@ Set the folder for DynaCache files. Default is $XDG_CACHE_HOME/box64 or $HOME/.c Minimum size, in KB, for a DynaCache to be written to disk. Default size is 350KB - * XXXX : Set a minimum size of XXXX KB of Dynarec code to write the dynacache to disk. Will not be saved to disk else. + * XXXX : Set a minimum size of XXXX KB of DynaRec code to write the dynacache to disk. Will not be saved to disk else. * 350 : A size of 350 KB is the default value. [Default] @@ -653,22 +645,22 @@ Disable the Box64 banner. Available in WowBox64. =item B =I<0xXXXXXXXX-0xYYYYYYYY> -Forbid dynablock creation in the address range specified, helpful for debugging behaviour difference between Dynarec and Interpreter. Available in WowBox64. +Forbid DynaBlock creation in the address range specified, helpful for debugging behaviour difference between DynaRec and Interpreter. Available in WowBox64. - * 0xXXXXXXXX-0xYYYYYYYY : Define the range where dynablock creation is forbidden (inclusive-exclusive). + * 0xXXXXXXXX-0xYYYYYYYY : Define the range where DynaBlock creation is forbidden (inclusive-exclusive). =item B =I<0|1> -Remove NoDynarec range after a delay. Available in WowBox64. +Remove NoDynaRec range after a delay. Available in WowBox64. - * 0 : Do not remove NoDynarec range. [Default] - * 1 : Remove the NoDynarec range once 2 threads have been created. + * 0 : Do not remove NoDynaRec range. [Default] + * 1 : Remove the NoDynaRec range once 2 threads have been created. =item B =I<0|1|2> -Remove Architecture metadata from Dynarec blocks (used on signal). Available in WowBox64. +Remove Architecture metadata from DynaRec blocks (used on signal). Available in WowBox64. * 0 : Generate all architecture metadata for each blocks, including x87/mmx/SSE/AVX regs tracking. Will use some more memory. [Default] * 1 : Generate only essential metadata for each blocks (flags, alignments), saving some memory, but some encrypted software might fail. @@ -805,7 +797,7 @@ Use hardware counter for rdtsc if available. =item B =I<0|1> -Report Invariant TSC bit in CPUID for Intel CPU type. +Report Invariant TSC bit in CPUID for Intel CPU type. Available in WowBox64. * 0 : Do not report Invariant TSC for Intel CPU type (default). [Default] * 1 : Report Invariant TSC bit in CPUID leaf 0x80000007 for Intel CPU type. @@ -865,7 +857,7 @@ Always show SIGSEGV signal details. Behaviour of SSE Flush to 0 flags. Also tracking SSE exception flags. Available in WowBox64. * 0 : Just track the flag. [Default] - * 1 : Apply SSE Flush to 0 flag directly. Also reflect SSE exception flags in Dynarec (if available) + * 1 : Apply SSE Flush to 0 flag directly. Also reflect SSE exception flags in DynaRec (if available) =item B =I<0|1> @@ -1011,6 +1003,14 @@ Behaviour of x87 80bits long double. Available in WowBox64. * 1 : Use 64bits double for x87. +=item B =I<0|1> + +Disable the automatic switch of personality for 32-bit binaries (always enabled on Box32). + + * 0 : Switch personality for 32-bit binaries (if not already tried). [Default] + * 1 : Do not switch personality for 32-bit binaries. + + =back =cut diff --git a/docs/gen/gen.py b/docs/gen/gen.py index 7cb8e80c1f..8a2bf3cdcb 100644 --- a/docs/gen/gen.py +++ b/docs/gen/gen.py @@ -8,11 +8,12 @@ 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(""" +# Language definitions — add a key here and a corresponding usage_.json +# (if translations are needed) to add a new language. +LANG = { + 'en': { + 'suffix': '', + 'preamble': """ Usage ---- @@ -57,24 +58,122 @@ ---- -""") +""", + 'wine': "Available in WowBox64.", + 'default': "[Default]", + 'top_cat': "Performance", + 'categories': {}, + }, + 'cn': { + 'suffix': '_CN', + 'preamble': """ +使用说明 +---- - categories = defaultdict(list) - for entry in data: - categories[entry["category"]].append(entry) - - # Put "Performance" at the top, then sort the rest alphabetically - sorted_categories = sorted(categories.items(), key=lambda x: (x[0] != "Performance", x[0])) - for category, entries in sorted_categories: - md_file.write(f"## {category}\n\n") - for entry in entries: - md_file.write(f"### {entry['name']}\n\n{entry['description']}{' Available in WowBox64.' if entry['wine'] else ''}\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") +Box64 有许多环境变量可用于控制其行为，下面将按类别列出。 + +Box64 有两种构建类型：Wine WOW64 构建（WowBox64）和常规 Linux 构建。请注意，只有部分环境变量在 WowBox64 中可用。 + +### 配置文件 + +除了环境变量之外，如果你使用的是常规 Linux 构建，Box64 默认还会在两个位置查找 rcfile：系统范围的 `/etc/box64.box64rc` 和用户目录下的 `~/.box64rc`。 +而在 WowBox64 中，配置文件仅在 `%USERPROFILE%/.box64rc` 处检查。 +设置的优先级如下（从高到低）：`~/.box64rc` > `/etc/box64.box64rc` > 环境变量。 + +配置示例： + +``` +[factorio] +BOX64_DYNAREC_SAFEFLAGS=0 +BOX64_DYNAREC_BIGBLOCK=2 +BOX64_DYNAREC_FORWARD=1024 +BOX64_DYNAREC_CALLRET=1 +``` + +此配置将使所有名为 `factorio` 的可执行文件应用指定的设置。 + +### Linux 构建的高级用法 +1. **通配符匹配** - with open(os.path.join(script_dir, '../box64.pod'), 'w') as pod_file: + 可以使用星号（`*`）对应用程序名称进行基本的模式匹配。例如，`[*setup*]` 将匹配名称中包含 "setup" 的任何程序。请注意，这里实现的是简单的通配符匹配，而非完整的正则表达式支持。 +2. **自定义配置文件** + + `BOX64_RCFILE` 环境变量可以指定一个替代的配置文件，而不是默认的 `/etc/box64.box64rc`。 +3. **按文件设置** + + 以 `/` 开头的配置项适用于特定文件。例如： + ``` + [/d3d9.dll] + BOX64_DYNAREC_SAFEFLAGS=0 + ``` + 这些设置将仅影响 `d3d9.dll` 文件。此语法同样适用于**模拟的** Linux 库，例如 `[/libstdc++.so.6]`。 + +---- + +""", + 'wine': "在 WowBox64 中可用。", + 'default': "[默认值]", + 'top_cat': "性能", + 'categories': { + "Performance": "性能", + "Arguments": "参数", + "Compatibility": "兼容性", + "Debugging": "调试", + "Environment": "环境变量", + "Libraries": "库", + }, + }, +} + + +def write_md(data, lang, t_data=None): + L = LANG[lang] + out_path = os.path.join(script_dir, f'../USAGE{L["suffix"]}.md') + + with open(out_path, 'w') as md_file: + md_file.write(L['preamble']) + + categories = defaultdict(list) + for entry in data: + entry = dict(entry) + entry['category'] = L['categories'].get(entry['category'], entry['category']) + categories[entry["category"]].append(entry) + + sorted_categories = sorted(categories.items(), key=lambda x: (x[0] != L['top_cat'], x[0])) + for category, entries in sorted_categories: + md_file.write(f"## {category}\n\n") + for entry in entries: + if t_data: + t_entry = t_data.get(entry['name'], {}) + desc = t_entry.get('description', entry['description']) + else: + desc = entry['description'] + wine_note = f" {L['wine']}" if entry['wine'] else "" + md_file.write(f"### {entry['name']}\n\n{desc}{wine_note}\n\n") + for option in entry['options']: + if t_data: + t_opts = t_data.get(entry['name'], {}).get('options', {}) + opt_desc = t_opts.get(option['key'], option['description']) + else: + opt_desc = option['description'] + default_mark = f" {L['default']}" if option['default'] else "" + md_file.write(f" * {option['key']}: {opt_desc}{default_mark}\n") + md_file.write("\n") + + +with open(usage_file, 'r') as file: + data = json.load(file) + +for lang in LANG: + t_file = os.path.join(script_dir, f'usage_{lang}.json') + t_data = None + if os.path.exists(t_file): + with open(t_file, 'r') as file: + t_data = json.load(file) + write_md(data, lang, t_data) + +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 @@ -128,10 +227,10 @@ """) 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']}{' Available in WowBox64.' if entry['wine'] else ''}\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(f"\n=item B<{entry['name']}> =I<{ '|'.join(option['key'] for option in entry['options']) }>\n\n{entry['description']}{' Available in WowBox64.' if entry['wine'] else ''}\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 diff --git a/docs/gen/usage.json b/docs/gen/usage.json index 17a0ab506d..72c2746c43 100644 --- a/docs/gen/usage.json +++ b/docs/gen/usage.json @@ -256,17 +256,17 @@ }, { "key": "1", - "description": "Build Dynarec block as big as possible.", + "description": "Build DynaRec block as big as possible.", "default": false }, { "key": "2", - "description": "Build Dynarec block bigger, do not stop when block overlaps, but only for blocks in elf memory.", + "description": "Build DynaRec block bigger, do not stop when block overlaps, but only for blocks in elf memory.", "default": true }, { "key": "3", - "description": "Build Dynarec block bigger, do not stop when block overlaps, for all type of memory, useful for wine programs.", + "description": "Build DynaRec block bigger, do not stop when block overlaps, for all type of memory, useful for wine programs.", "default": false } ] @@ -366,7 +366,7 @@ }, { "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.", + "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 }, { @@ -394,24 +394,6 @@ } ] }, - { - "name": "BOX64_DYNAREC_HOTPAGE_ALT", - "description": "Use alternative way to detect HotPages (legacy way).", - "category": "Performance", - "wine": false, - "options": [ - { - "key": "0", - "description": "Detect hot page, using new method from v0.3.9+", - "default": true - }, - { - "key": "1", - "description": "Use alternate method to detect HotPage (from v0.3.8 and earlier)", - "default": false - } - ] - }, { "name": "BOX64_DYNAREC_DIV0", "description": "Enable or disable the generation of division-by-zero exception.", @@ -461,7 +443,7 @@ "options": [ { "key": "0xXXXXXXXX-0xYYYYYYYY", - "description": "Define the range where dynablock gets dumped (inclusive-exclusive).", + "description": "Define the range where DynaBlock gets dumped (inclusive-exclusive).", "default": false } ] @@ -538,27 +520,27 @@ "options": [ { "key": "0", - "description": "Dynarec will not generate GDBJIT debuginfo.", + "description": "DynaRec will not generate GDBJIT debuginfo.", "default": true }, { "key": "1", - "description": "Dynarec will generate GDBJIT debuginfo.", + "description": "DynaRec will generate GDBJIT debuginfo.", "default": false }, { "key": "2", - "description": "Dynarec will generate detailed GDBJIT debuginfo with internal state.", + "description": "DynaRec will generate detailed GDBJIT debuginfo with internal state.", "default": false }, { "key": "3", - "description": "Dynarec will register detailed GDBJIT debuginfo only for dynablocks that the guest program trap into, greatly improving performance.", + "description": "DynaRec will register detailed GDBJIT debuginfo only for DynaBlocks that the guest program trap into, greatly improving performance.", "default": false }, { "key": "0xXXXXXXX-0xYYYYYYY", - "description": "Define the range where Dynarec will generate detailed GDBJIT debuginfo with internal state.", + "description": "Define the range where DynaRec will generate detailed GDBJIT debuginfo with internal state.", "default": false } ] @@ -691,37 +673,37 @@ "options": [ { "key": "0", - "description": "Dynarec will not generate perf map.", + "description": "DynaRec will not generate perf map.", "default": true }, { "key": "1", - "description": "Dynarec will generate perf map.", + "description": "DynaRec will generate perf map.", "default": false } ] }, { "name": "BOX64_DYNAREC_PURGE", - "description": "Purge dynablocks that haven't been executed recently, based on tick age threshold (BOX64_DYNAREC_PURGE_AGE).", + "description": "Purge DynaBlocks that haven't been executed recently, based on tick age threshold (BOX64_DYNAREC_PURGE_AGE).", "category": "Performance", "wine": false, "options": [ { "key": "0", - "description": "Dynarec will not purge old unused dynablocks.", + "description": "DynaRec will not purge old unused DynaBlocks.", "default": true }, { "key": "1", - "description": "Dynarec will purge old unused dynablocks based on tick age.", + "description": "DynaRec will purge old unused DynaBlocks based on tick age.", "default": false } ] }, { "name": "BOX64_DYNAREC_PURGE_AGE", - "description": "Tick age threshold for dynablock purging (requires BOX64_DYNAREC_PURGE=1).", + "description": "Tick age threshold for DynaBlock purging (requires BOX64_DYNAREC_PURGE=1).", "category": "Performance", "wine": false, "options": [ @@ -824,12 +806,12 @@ }, { "key": "1", - "description": "Each opcode runs on interpreter and on Dynarec, regs and memory are compared and printed when they differ.", + "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).", + "description": "Define the range where DynaRec is tested (inclusive-exclusive).", "default": false } ] @@ -972,13 +954,13 @@ }, { "name": "BOX64_DYNAREC_INTERP_SIGNAL", - "description": "Allow the use of Dynarec in Signal Handlers.", + "description": "Allow the use of DynaRec in Signal Handlers.", "category": "Compatibility", "wine": false, "options": [ { "key": "0", - "description": "Allow the use of Dynarec in signal handlers.", + "description": "Allow the use of DynaRec in signal handlers.", "default": true }, { @@ -1032,7 +1014,7 @@ "options": [ { "key": "XXXX", - "description": "Set a minimum size of XXXX KB of Dynarec code to write the dynacache to disk. Will not be saved to disk else.", + "description": "Set a minimum size of XXXX KB of DynaRec code to write the dynacache to disk. Will not be saved to disk else.", "default": false }, { @@ -1427,38 +1409,38 @@ }, { "name": "BOX64_NODYNAREC", - "description": "Forbid dynablock creation in the address range specified, helpful for debugging behaviour difference between Dynarec and Interpreter.", - "category": "Performance", + "description": "Forbid DynaBlock creation in the address range specified, helpful for debugging behaviour difference between DynaRec and Interpreter.", + "category": "Debugging", "wine": true, "options": [ { "key": "0xXXXXXXXX-0xYYYYYYYY", - "description": "Define the range where dynablock creation is forbidden (inclusive-exclusive).", + "description": "Define the range where DynaBlock creation is forbidden (inclusive-exclusive).", "default": false } ] }, { "name": "BOX64_NODYNAREC_DELAY", - "description": "Remove NoDynarec range after a delay.", + "description": "Remove NoDynaRec range after a delay.", "category": "Debugging", "wine": true, "options": [ { "key": "0", - "description": "Do not remove NoDynarec range.", + "description": "Do not remove NoDynaRec range.", "default": true }, { "key": "1", - "description": "Remove the NoDynarec range once 2 threads have been created.", + "description": "Remove the NoDynaRec range once 2 threads have been created.", "default": false } ] }, { "name": "BOX64_DYNAREC_NOARCH", - "description": "Remove Architecture metadata from Dynarec blocks (used on signal).", + "description": "Remove Architecture metadata from DynaRec blocks (used on signal).", "category": "Performance", "wine": true, "options": [ @@ -1771,7 +1753,7 @@ "name": "BOX64_RDTSC_INV", "description": "Report Invariant TSC bit in CPUID for Intel CPU type.", "category": "Compatibility", - "wine": false, + "wine": true, "options": [ { "key": "0", @@ -1911,7 +1893,7 @@ }, { "key": "1", - "description": "Apply SSE Flush to 0 flag directly. Also reflect SSE exception flags in Dynarec (if available)", + "description": "Apply SSE Flush to 0 flag directly. Also reflect SSE exception flags in DynaRec (if available)", "default": false } ] @@ -2256,5 +2238,23 @@ "default": false } ] + }, + { + "name": "BOX64_NOPERSONA32BITS", + "description": "Disable the automatic switch of personality for 32-bit binaries (always enabled on Box32).", + "category": "Compatibility", + "wine": false, + "options": [ + { + "key": "0", + "description": "Switch personality for 32-bit binaries (if not already tried).", + "default": true + }, + { + "key": "1", + "description": "Do not switch personality for 32-bit binaries.", + "default": false + } + ] } -] +] \ No newline at end of file diff --git a/docs/gen/usage_cn.json b/docs/gen/usage_cn.json new file mode 100644 index 0000000000..785480f84d --- /dev/null +++ b/docs/gen/usage_cn.json @@ -0,0 +1,848 @@ +{ + "BOX64_ADDLIBS": { + "description": "添加额外需要的共享库（这个选项不太常用）。", + "options": { + "XXXX": "将 XXXX 共享库添加到所需库列表。", + "XXXX:YYYY:ZZZZ": "将 XXXX、YYYY 和 ZZZZ 共享库添加到所需库列表。" + } + }, + "BOX64_AES": { + "description": "是否暴露 AES 能力。", + "options": { + "0": "不暴露 AES 能力。", + "1": "暴露 AES 能力。" + } + }, + "BOX64_ALLOWMISSINGLIBS": { + "description": "是否允许忽略缺失的共享库。", + "options": { + "0": "不允许忽略缺失的共享库。", + "1": "允许忽略缺失的共享库。" + } + }, + "BOX64_ARCH": { + "description": "在 rcfile 中指定当前条目适用的架构。此选项仅在 rcfile 中使用时生效。", + "options": { + "`arm64`": "仅对 AArch64 应用当前条目。", + "`la64`": "仅对 LoongArch64 应用当前条目。", + "`rv64`": "仅对 RISC-V 应用当前条目。", + "``": "对所有架构应用当前条目，但如果存在更具体的条目，当前条目将被替换。" + } + }, + "BOX64_ARGS": { + "description": "传递给目标程序的参数，仅在没有任何已有参数时有效。", + "options": { + "XXXX": "将 XXXX 参数传递给目标程序。", + "XXXX YYYY ZZZZ": "将 XXXX、YYYY 和 ZZZZ 参数传递给目标程序。" + } + }, + "BOX64_AVX": { + "description": "向 CPUID 和 cpuinfo 文件暴露 AVX 扩展。在 Arm64 上默认值为 2，因为 DynaRec 已完全实现，其他架构默认为 0。", + "options": { + "0": "不暴露 AVX 能力。", + "1": "向 CPUID 和 cpuinfo 文件暴露 AVX、BMI1、F16C 和 VAES 扩展。", + "2": "包含 1 的全部内容，外加 AVX2、BMI2、FMA、ADX、VPCLMULQDQ 和 RDRAND 扩展。" + } + }, + "BOX64_BASH": { + "description": "用于指定 bash 可执行文件的路径。", + "options": { + "XXXX": "使用路径为 XXXX 的 bash 可执行文件。" + } + }, + "BOX64_CPUTYPE": { + "description": "指定要模拟的 CPU 类型。", + "options": { + "0": "模拟某个 Intel CPU 型号。", + "1": "模拟某个 AMD CPU 型号。" + } + }, + "BOX64_CRASHHANDLER": { + "description": "是否使用模拟的 crashhandler.so 库。", + "options": { + "0": "在需要时使用模拟的 crashhandler.so 库。", + "1": "使用内部定义的空 crashhandler.so 库。" + } + }, + "BOX64_DLSYM_ERROR": { + "description": "启用或禁用 dlsym 错误的日志记录。", + "options": { + "0": "禁用 dlsym 错误的日志记录。", + "1": "启用 dlsym 错误的日志记录。" + } + }, + "BOX64_DUMP": { + "description": "是否输出 elfloader 调试信息。", + "options": { + "0": "不输出 elfloader 调试信息。", + "1": "输出 elfloader 调试信息。" + } + }, + "BOX64_DYNAREC": { + "description": "启用或禁用动态重编译器（DynaRec）。如果在支持的架构上构建时开启了 DynaRec 支持，则默认为 1。", + "options": { + "0": "禁用 DynaRec。", + "1": "启用 DynaRec。" + } + }, + "BOX64_DYNAREC_ALIGNED_ATOMICS": { + "description": "仅生成对齐的原子操作（目前仅在 Arm64 上可用）。", + "options": { + "0": "生成非对齐原子操作处理代码。", + "1": "仅生成对齐的原子操作，代码更快更小，但在非对齐数据地址上执行 LOCK 前缀指令时会导致 SIGBUS。" + } + }, + "BOX64_DYNAREC_BIGBLOCK": { + "description": "尝试构建更大的代码块以提高性能。", + "options": { + "0": "不尝试构建尽可能大的代码块，适用于使用大量线程和 JIT 的程序（如 Unity）。", + "1": "尽可能构建大的代码块。", + "2": "构建更大的代码块，代码块重叠时不停止，但仅针对 elf 内存中的代码块。", + "3": "构建更大的代码块，代码块重叠时不停止，适用于所有类型的内存，因此也对 wine 程序有用。" + } + }, + "BOX64_DYNAREC_BLEEDING_EDGE": { + "description": "检测 MonoBleedingEdge 并应用保守设置（仅 Linux）。", + "options": { + "0": "不检测 MonoBleedingEdge。", + "1": "检测 MonoBleedingEdge，并在检测到时应用 BOX64_DYNAREC_BIGBLOCK=0 和 BOX64_DYNAREC_强内存模型=1。" + } + }, + "BOX64_DYNAREC_CALLRET": { + "description": "优化 CALL/RET 指令。", + "options": { + "0": "不优化 CALL/RET，使用跳转表。", + "1": "尝试优化 CALL/RET，在可能的情况下跳过跳转表。", + "2": "尝试优化 CALL/RET，在可能的情况下跳过跳转表，同时增加对返回到脏/已修改代码块的代码的处理。在 WowBox64 上不可用。" + } + }, + "BOX64_DYNAREC_SEP": { + "description": "使用二级入口点（SEP）进一步优化 CALL/RET。如果 CALLRET 未启用则无效。", + "options": { + "0": "不在 CALLRET 返回时添加 SEP。", + "1": "在 CALLRET 返回时添加 SEP，仅针对来自已知二进制文件的内存。", + "2": "在 CALLRET 返回时添加 SEP，适用于所有类型的内存。" + } + }, + "BOX64_DYNAREC_DF": { + "description": "启用或禁用延迟 FLAGS 的使用。", + "options": { + "0": "禁用延迟 FLAGS 的使用。", + "1": "启用延迟 FLAGS 的使用。" + } + }, + "BOX64_DYNAREC_DIRTY": { + "description": "是否允许继续运行未受保护且可能已脏的代码块。", + "options": { + "0": "不允许继续运行未受保护且可能已脏的代码块。", + "1": "允许继续运行在与代码相同页面中写入数据的代码块，可以加快某些游戏的加载时间，但也可能导致意外崩溃。", + "2": "除了 1 之外，当检测到热页时，将该页面标记为永不写保护，但基于该页面构建的代码块将始终被测试。这样可以更快（但某些 SMC 情况可能无法捕获）。" + } + }, + "BOX64_DYNAREC_NOHOTPAGE": { + "description": "是否禁用热页检测（即代码执行和数据写入同时发生的页面）。", + "options": { + "0": "检测热页。", + "1": "不检测热页。" + } + }, + "BOX64_DYNAREC_DIV0": { + "description": "启用或禁用除零异常的生成。", + "options": { + "0": "不生成除零异常。", + "1": "生成除零异常。" + } + }, + "BOX64_DYNAREC_DUMP": { + "description": "启用 DynaRec 转储。", + "options": { + "0": "不转储代码块。", + "1": "转储代码块。", + "2": "转储代码块并带有颜色。" + } + }, + "BOX64_DYNAREC_DUMP_RANGE": { + "description": "转储指定范围内的代码块。", + "options": { + "0xXXXXXXXX-0xYYYYYYYY": "定义代码块 被转储的范围（左闭右开）。" + } + }, + "BOX64_DYNAREC_FASTNAN": { + "description": "启用或禁用快速 NaN 处理。", + "options": { + "0": "精确模拟 x86 上的 -NaN 生成。", + "1": "不对 -NaN 生成做任何特殊处理，速度更快。" + } + }, + "BOX64_DYNAREC_FASTROUND": { + "description": "启用或禁用快速舍入。", + "options": { + "0": "生成 float/double -> int 舍入，并使用当前舍入模式进行 float/double 计算，类似 x86。", + "1": "不对边缘情况的舍入做任何特殊处理，速度更快。", + "2": "使用当前舍入模式生成 float/double -> int 舍入（类似 x86），但使用快速的 int -> float/double 转换。" + } + }, + "BOX64_DYNAREC_FORWARD": { + "description": "定义构建代码块时允许的最大前向跳转值。", + "options": { + "0": "无前向跳转值。当前代码块结束时，即使存在之前的前向跳转也不尝试继续前进。", + "128": "允许代码块结束与下一个前向跳转之间最多 128 字节的间隙。", + "XXXX": "允许代码块结束与下一个前向跳转之间最多 XXXX 字节的间隙。" + } + }, + "BOX64_DYNAREC_GDBJIT": { + "description": "GDBJIT 调试支持，仅在使用 `-DGDBJIT=ON` 构建时可用，通过 gdb 命令启用：jit-reader-load /usr/local/lib/libbox64gdbjitreader.so。", + "options": { + "0": "DynaRec 不会生成 GDBJIT 调试信息。", + "1": "DynaRec 将生成 GDBJIT 调试信息。", + "2": "DynaRec 将生成包含内部状态的详细 GDBJIT 调试信息。", + "3": "DynaRec 将仅对目标程序陷入的代码块 注册详细的 GDBJIT 调试信息，大幅提升性能。", + "0xXXXXXXX-0xYYYYYYY": "定义 DynaRec 将生成包含内部状态的详细 GDBJIT 调试信息的范围。" + } + }, + "BOX64_DYNAREC_LOG": { + "description": "禁用或启用 DynaRec 日志。", + "options": { + "0": "禁用 DynaRec 日志。", + "1": "启用最小级别的 DynaRec 日志。", + "2": "启用调试级别的 DynaRec 日志。", + "3": "启用详细级别的 DynaRec 日志。" + } + }, + "BOX64_DYNAREC_MISSING": { + "description": "打印缺失的指令。", + "options": { + "0": "不打印缺失的指令。", + "1": "打印缺失的指令。", + "2": "打印回退到标量指令的信息，仅对 RISC-V 有效。" + } + }, + "BOX64_DYNAREC_NATIVEFLAGS": { + "description": "启用或禁用原生FLAGS的使用。", + "options": { + "0": "不使用原生FLAGS。", + "1": "在可能的情况下使用原生FLAGS。" + } + }, + "BOX64_DYNAREC_NOHOSTEXT": { + "description": "禁用可选的主机扩展。", + "options": { + "0": "不禁用任何扩展。", + "1": "禁用所有可选扩展。", + "xxx,yyy,zzz": "禁用指定的可选扩展，可选项包括 Arm：`crc32,pmull,aes,atomics,sha1,sha2,uscat,flagm,flagm2,frintts,afp,rndr`，LoongArch：`lasx,lbt,frecipe,lam_bh,lamcas,scq`，以及 RISC-V：`zba,zbb,zbc,zbs,vector,xtheadba,xtheadbb,xtheadbs,xtheadmemidx,xtheadmempair,xtheadcondmov`。" + } + }, + "BOX64_DYNAREC_PAUSE": { + "description": "启用 x86 PAUSE 模拟，可能有助于自旋锁的性能。", + "options": { + "0": "忽略 x86 PAUSE 指令。", + "1": "使用 YIELD 模拟 x86 PAUSE 指令。", + "2": "使用 WFI 模拟 x86 PAUSE 指令。", + "3": "使用 SEVL+WFE 模拟 x86 PAUSE 指令。" + } + }, + "BOX64_DYNAREC_PERFMAP": { + "description": "为 Linux perf 工具生成映射文件。", + "options": { + "0": "DynaRec 不会生成 perf 映射。", + "1": "DynaRec 将生成 perf 映射。" + } + }, + "BOX64_DYNAREC_PURGE": { + "description": "根据年龄阈值（BOX64_DYNAREC_PURGE_AGE）清除最近未执行的代码块。", + "options": { + "0": "DynaRec 不会清除旧的未使用代码块。", + "1": "DynaRec 将根据年龄阈值清除旧的未使用代码块。" + } + }, + "BOX64_DYNAREC_PURGE_AGE": { + "description": "代码块清除的年龄阈值（需要 BOX64_DYNAREC_PURGE=1）。", + "options": { + "4096": "默认年龄阈值。", + "XXXX": "自定义年龄阈值（范围：10-65536）。" + } + }, + "BOX64_DYNAREC_SAFEFLAGS": { + "description": "在 CALL/RET 指令和其他边缘情况下 FLAGS 模拟的行为。", + "options": { + "0": "将 CALL/RET 标记为从不需要任何 FLAGS。", + "1": "将大多数 RET 标记为需要 FLAGS，将大多数 CALL 标记为不需要。", + "2": "将所有 CALL/RET 都标记为需要 FLAGS。同时也处理所有边缘情况。" + } + }, + "BOX64_DYNAREC_STRONGMEM": { + "description": "开启或关闭 x86 强内存模型的模拟。", + "options": { + "0": "不做任何特殊处理。", + "1": "在写入内存时启用以有限方式模拟 x86 强内存模型的内存屏障。", + "2": "包含 1 的全部内容，外加 SIMD 指令的内存屏障。", + "3": "包含 2 的全部内容，外加定期添加更多内存屏障。", + "4": "模仿 x86 TSO，类似 QEMU 的方法，可用于评估目的。" + } + }, + "BOX64_DYNAREC_TBB": { + "description": "启用或禁用 libtbb 检测。", + "options": { + "0": "不检测 libtbb。", + "1": "检测 libtbb 并应用保守设置。" + } + }, + "BOX64_DYNAREC_TEST": { + "description": "启用 DynaRec 与解释器的执行对比，非常慢，仅用于测试。", + "options": { + "0": "不进行对比。", + "1": "每个指令都在解释器和 DynaRec 上运行，当寄存器或内存不同时进行对比并打印。", + "0xXXXXXXXX-0xYYYYYYYY": "定义 DynaRec 测试的范围（左闭右开）。" + } + }, + "BOX64_DYNAREC_TEST_NODUP": { + "description": "启用 COSIM 发现差异的 IP 地址去重。", + "options": { + "0": "显示所有出错的地址。", + "1": "每个出错地址仅显示一次，即使转储可能不同。" + } + }, + "BOX64_DYNAREC_TEST_NODUMP": { + "description": "当 BOX64_DYNAREC_DUMP 启用时不转储测试代码。", + "options": { + "0": "转储测试代码。", + "1": "不转储测试代码。" + } + }, + "BOX64_DYNAREC_TRACE": { + "description": "启用或禁用 DynaRec 追踪。", + "options": { + "0": "不追踪代码块。", + "1": "追踪代码块，会大幅降低程序速度并生成大量日志。" + } + }, + "BOX64_DYNAREC_VOLATILE_METADATA": { + "description": "使用从 PE 文件解析的 volatile 元数据，仅对 64 位 Windows 游戏有效。", + "options": { + "0": "不使用 volatile 元数据。", + "1": "使用 volatile 元数据，将指导 Box64 进行更好的强内存模拟。" + } + }, + "BOX64_DYNAREC_WAIT": { + "description": "是否等待代码块构建完成。", + "options": { + "0": "不等待，改用解释器，可能在大量多线程或 JIT 程序上略微加速。", + "1": "等待代码块构建完成。" + } + }, + "BOX64_DYNAREC_WEAKBARRIER": { + "description": "调整内存屏障以减少强内存模拟的性能影响。", + "options": { + "0": "使用常规安全屏障。", + "1": "使用弱屏障以获得更多性能提升。", + "2": "包含 1 的全部内容，外加禁用最后的写屏障。" + } + }, + "BOX64_DYNAREC_X87DOUBLE": { + "description": "强制使用 float/double 进行 x87 模拟。", + "options": { + "0": "尝试在可能的情况下对 x87 模拟使用 float。", + "1": "仅对 x87 模拟使用 Double。", + "2": "在 x87 模拟中检查精度控制的低精度。" + } + }, + "BOX64_DYNAREC_INTERP_SIGNAL": { + "description": "允许在信号处理器中使用 DynaRec。", + "options": { + "0": "允许在信号处理器中使用 DynaRec。", + "1": "仅在信号处理器中使用解释器（与 v0.3.8 及更早版本相同）。" + } + }, + "BOX64_DYNACACHE": { + "description": "启用或禁用动态重编译器缓存（DynaCache）。此选项默认为 2（读取已有缓存但不生成新的）。DynaCache 默认将文件写入 home 文件夹，且可能无限增长。", + "options": { + "0": "禁用 DynaCache。", + "1": "启用 DynaCache。", + "2": "使用已有的 DynaCache 文件，但不生成新的。" + } + }, + "BOX64_DYNACACHE_FOLDER": { + "description": "设置 DynaCache 文件的文件夹。默认为 $XDG_CACHE_HOME/box64，如果 $XDG_CACHE_HOME 未设置则为 $HOME/.cache/box64。", + "options": { + "XXXX": "使用文件夹 XXXX 存储 DynaCache 文件。" + } + }, + "BOX64_DYNACACHE_MIN": { + "description": "DynaCache 写入磁盘的最小大小（KB）。默认大小为 350KB。", + "options": { + "XXXX": "设置将缓存写入磁盘的最小 DynaRec 代码大小（XXXX KB），小于此值将不会保存到磁盘。", + "350": "默认值为 350 KB。" + } + }, + "BOX64_EMULATED_LIBS": { + "description": "强制使用模拟库。", + "options": { + "XXXX": "强制使用模拟库 XXXX。", + "XXXX:YYYY:ZZZZ": "强制使用模拟库 XXXX、YYYY 和 ZZZZ。" + } + }, + "BOX64_ENV": { + "description": "添加环境变量。", + "options": { + "XXXX=yyyy": "添加值为 yyyy 的环境变量 XXXX。" + } + }, + "BOX64_ENV[1-5]": { + "description": "添加环境变量。", + "options": { + "XXXX=yyyy": "添加值为 yyyy 的环境变量 XXXX。" + } + }, + "BOX64_EXIT": { + "description": "直接退出，不运行程序。", + "options": { + "0": "不执行任何操作。", + "1": "直接退出。" + } + }, + "BOX64_FIX_64BIT_INODES": { + "description": "修复 64 位 inode。", + "options": { + "0": "不修复 64 位 inode。", + "1": "修复 64 位 inode。" + } + }, + "BOX64_FORCE_LD_PRELOAD": { + "description": "是否强制 BOX64_LD_PRELOAD 库中的符号通过 RTLD_NEXT 解析。", + "options": { + "0": "不执行任何操作。", + "1": "强制 BOX64_LD_PRELOAD 库中的符号通过 RTLD_NEXT 解析。" + } + }, + "BOX64_IGNOREINT3": { + "description": "忽略 INT3 指令。", + "options": { + "0": "如果存在处理器则触发 TRAP 信号。", + "1": "静默跳过该指令。" + } + }, + "BOX64_INSERT_ARGS": { + "description": "在命令行前添加参数。", + "options": { + "XXXX": "在程序前添加参数 XXXX。", + "XXXX YYYY ZZZZ": "在目标程序前添加参数 XXXX、YYYY 和 ZZZZ。" + } + }, + "BOX64_INPROCESSGPU": { + "description": "向目标程序添加 --in-process-gpu 参数。", + "options": { + "0": "不执行任何操作。", + "1": "向目标程序添加 --in-process-gpu 参数。" + } + }, + "BOX64_JITGDB": { + "description": "发生 SIGSEGV、SIGILL 和 SIGBUS 时是否启动 gdb。", + "options": { + "0": "捕获信号时仅打印消息。", + "1": "当捕获到 SIGSEGV、SIGILL 或 SIGBUS 信号时启动 gdb，附加到有问题的进程并进入无限循环等待。在 gdb 中，你需要自己找到正确的线程（在其堆栈中有 `my_box64signalhandler` 的线程），然后可能需要 `finish` 1 或 2 个函数（在 `usleep(..)` 内部），之后你将进入 `my_box64signalhandler`，就在 Segfault 消息的 printf 之前。然后 `set waiting=0` 退出无限循环。", + "2": "当捕获到 SIGSEGV、SIGILL 或 SIGBUS 信号时启动 gdbserver，附加到有问题的进程，并进入无限循环等待。使用 `gdb /PATH/TO/box64` 然后 `target remote 127.0.0.1:1234` 连接到 gdbserver（如果不在本机，则使用实际 IP）。之后的操作步骤与 `BOX64_JITGDB=1` 相同。", + "3": "当捕获到 SIGSEGV、SIGILL 或 SIGBUS 信号时启动 lldb，附加到有问题的进程并进入无限循环等待。" + } + }, + "BOX64_JVM": { + "description": "检测 libjvm 并应用保守设置。", + "options": { + "0": "不执行任何操作。", + "1": "检测 libjvm，并在检测到时应用 BOX64_DYNAREC_BIGBLOCK=0 BOX64_DYNAREC_强内存模型=1 BOX64_SSE42=0。" + } + }, + "BOX64_LD_LIBRARY_PATH": { + "description": "查找 x86_64 库的路径。", + "options": { + "XXXX": "将路径 XXXX 添加到库搜索路径。" + } + }, + "BOX64_LD_PRELOAD": { + "description": "强制随二进制文件加载库。", + "options": { + "XXXX": "强制加载库 XXXX。", + "XXXX:YYYY": "强制加载库 XXXX 和 YYYY。" + } + }, + "BOX64_LIBCEF": { + "description": "检测 libcef 并应用 BOX64_MALLOC_HACK 设置。", + "options": { + "0": "不执行任何操作。", + "1": "检测 libcef，并在检测到时应用 BOX64_MALLOC_HACK=2。" + } + }, + "BOX64_LIBGL": { + "description": "设置 libGL 的名称。", + "options": { + "libXXXX": "将 libGL 的名称设置为 libXXXX。", + "/path/to/libXXXX": "将 libGL 的名称和路径设置为 /path/to/libXXXX，你也可以使用 SDL_VIDEO_GL_DRIVER。" + } + }, + "BOX64_LOAD_ADDR": { + "description": "设置程序加载的地址，仅对 PIE 目标程序有效。", + "options": { + "0xXXXXXXXX": "设置程序加载的地址。" + } + }, + "BOX64_LOG": { + "description": "启用或禁用 Box64 日志，如果 stdout 不是终端则默认为 0，否则为 1。", + "options": { + "0": "禁用 Box64 日志。", + "1": "启用最小级别的 Box64 日志。", + "2": "启用调试级别的 Box64 日志。", + "3": "启用详细级别的 Box64 日志。" + } + }, + "BOX64_MALLOC_HACK": { + "description": "挂钩 malloc 操作符时的行为。", + "options": { + "0": "不允许重定向 malloc 操作符，重写代码使用常规函数。", + "1": "允许重定向 malloc 操作符。", + "2": "与 0 类似，但追踪特殊的 mmap/free（某些内联的重定向函数无法被重定向）。" + } + }, + "BOX64_MAXCPU": { + "description": "暴露的最大 CPU 核心数。", + "options": { + "0": "使用实际的 CPU 核心数。", + "XXXX": "使用 XXXX 个 CPU 核心。" + } + }, + "BOX64_MMAP32": { + "description": "在运行 32 位代码的 64 位程序（如 Wine WOW64）上强制使用 32 位兼容的内存映射，可提高性能。", + "options": { + "0": "不强制使用 32 位内存映射。", + "1": "强制使用 32 位内存映射。" + } + }, + "BOX64_NOBANNER": { + "description": "禁用 Box64 横幅。", + "options": { + "0": "显示 Box64 横幅。", + "1": "不显示 Box64 横幅。" + } + }, + "BOX64_NODYNAREC": { + "description": "在指定的地址范围内禁止创建代码块，有助于调试 DynaRec 和解释器之间的行为差异。", + "options": { + "0xXXXXXXXX-0xYYYYYYYY": "定义禁止创建代码块 的范围（左闭右开）。" + } + }, + "BOX64_NODYNAREC_DELAY": { + "description": "延迟后移除 NoDynaRec 范围。", + "options": { + "0": "不移除 NoDynaRec 范围。", + "1": "创建 2 个线程后移除 NoDynaRec 范围。" + } + }, + "BOX64_DYNAREC_NOARCH": { + "description": "从代码块中移除架构元数据（在信号处理时使用）。", + "options": { + "0": "为每个代码块生成所有架构元数据，包括 x87/mmx/SSE/AVX 寄存器追踪。会使用更多内存。", + "1": "仅生成每个代码块的必要元数据（FLAGS、对齐），节省一些内存，但某些加密软件可能会失败。", + "2": "不为代码块生成元数据，进一步节省内存，但在信号处理时可能会失败。" + } + }, + "BOX64_NOGTK": { + "description": "不加载包装的 GTK 库。", + "options": { + "0": "加载包装的 GTK 库。", + "1": "不加载包装的 GTK 库。" + } + }, + "BOX64_NOPULSE": { + "description": "不加载 PulseAudio 库（原生库和模拟库均不加载）。", + "options": { + "0": "加载 PulseAudio 库。", + "1": "不加载 PulseAudio 库。" + } + }, + "BOX64_NORCFILES": { + "description": "不加载任何 rc 文件。", + "options": { + "0": "加载 rc 文件。", + "1": "不加载任何 rc 文件。" + } + }, + "BOX64_NOSANDBOX": { + "description": "向目标程序添加 --no-sandbox 参数。", + "options": { + "0": "不执行任何操作。", + "1": "向目标程序添加 --no-sandbox 参数。" + } + }, + "BOX64_NOSIGSEGV": { + "description": "禁用 SIGSEGV 的处理。", + "options": { + "0": "允许 x86 程序为 SIGSEGV 设置信号处理器。", + "1": "禁用 SIGSEGV 的处理。" + } + }, + "BOX64_NOSIGILL": { + "description": "禁用 SIGILL 的处理。", + "options": { + "0": "允许 x86 程序为 SIGILL 设置信号处理器。", + "1": "禁用 SIGILL 的处理。" + } + }, + "BOX64_NOVULKAN": { + "description": "不加载 Vulkan 库。", + "options": { + "0": "加载 Vulkan 库。", + "1": "不加载 Vulkan 库，原生库和模拟库均不加载。" + } + }, + "BOX64_NOVULKANOVERLAY": { + "description": "不加载 x64 Vulkan 覆盖层。", + "options": { + "0": "尝试加载 x64 Vulkan 覆盖层。", + "1": "不加载 x64 Vulkan 覆盖层。" + } + }, + "BOX64_PATH": { + "description": "查找 x86_64 二进制文件的路径。", + "options": { + "XXXX": "将路径 XXXX 添加到二进制搜索路径。" + } + }, + "BOX64_PCLMULQDQ": { + "description": "暴露 PCLMULQDQ 能力。", + "options": { + "0": "不暴露 PCLMULQDQ 能力。", + "1": "暴露 PCLMULQDQ 能力。" + } + }, + "BOX64_PREFER_EMULATED": { + "description": "优先使用模拟库而非原生库。", + "options": { + "0": "优先使用原生库而非模拟库。", + "1": "优先使用模拟库而非原生库。" + } + }, + "BOX64_PREFER_WRAPPED": { + "description": "即使库使用绝对路径指定，也优先使用包装库。", + "options": { + "0": "优先使用绝对路径指定的库而非包装库。", + "1": "即使库使用绝对路径指定，也优先使用包装库。" + } + }, + "BOX64_PROFILE": { + "description": "预定义的环境变量集合，以兼容性或性能为导向。", + "options": { + "safest": "禁用所有不安全的 DynaRec 优化的配置文件。", + "safe": "比 safest 略不安全。", + "default": "大多数程序都能正常运行且性能适中的默认设置。", + "fast": "启用许多不安全的优化，但同时启用 强内存模型 模拟。", + "fastest": "启用许多不安全的优化以获得更好的性能。" + } + }, + "BOX64_PYTHON3": { + "description": "python3 可执行文件的路径。", + "options": { + "XXXX": "使用路径为 XXXX 的 python3 可执行文件。" + } + }, + "BOX64_RCFILE": { + "description": "要加载的 rc 文件路径。", + "options": { + "XXXX": "加载 rc 文件 XXXX，不会加载默认的 rc 文件。" + } + }, + "BOX64_RDTSC_1GHZ": { + "description": "如果可用，使用硬件计数器实现 rdtsc。", + "options": { + "0": "如果可用，使用硬件计数器实现 rdtsc 指令。", + "1": "仅当精度至少为 1GHz 时，使用硬件计数器实现 rdtsc。" + } + }, + "BOX64_RDTSC_INV": { + "description": "在 Intel CPU 类型的 CPUID 中报告 Invariant TSC 位。", + "options": { + "0": "不为 Intel CPU 类型报告 Invariant TSC（默认）。", + "1": "在 Intel CPU 类型的 CPUID leaf 0x80000007 中报告 Invariant TSC 位。" + } + }, + "BOX64_RESERVE_HIGH": { + "description": "为程序保留高内存区域，在 Box32 上始终启用。", + "options": { + "0": "不为程序保留高内存区域。", + "1": "为程序保留高内存区域。" + } + }, + "BOX64_ROLLING_LOG": { + "description": "当捕获信号时显示最近几个包装函数调用。", + "options": { + "0": "不执行任何操作。", + "1": "捕获信号时显示最近 16 个包装函数调用。", + "XXXX": "捕获信号时显示最近 XXXX 个包装函数调用。" + } + }, + "BOX64_SDL2_JGUID": { + "description": "对包装的 SDL2 使用 SDL_GetJoystickGUIDInfo 函数的变通方案。", + "options": { + "0": "不执行任何操作。", + "1": "对包装的 SDL2 使用 SDL_GetJoystickGUIDInfo 函数的变通方案。" + } + }, + "BOX64_SHAEXT": { + "description": "暴露 SHAEXT（即 SHA_NI）能力。", + "options": { + "0": "不暴露 SHAEXT 能力。", + "1": "暴露 SHAEXT 能力。" + } + }, + "BOX64_SHOWBT": { + "description": "捕获信号时显示原生和模拟的回溯。", + "options": { + "0": "不执行任何操作。", + "1": "捕获信号时显示原生和模拟的回溯。" + } + }, + "BOX64_SHOWSEGV": { + "description": "始终显示 SIGSEGV 信号详情。", + "options": { + "0": "不执行任何操作。", + "1": "始终显示 SIGSEGV 信号详情。" + } + }, + "BOX64_SSE_FLUSHTO0": { + "description": "SSE Flush to 0 FLAGS的行为，同时追踪 SSE 异常FLAGS。", + "options": { + "0": "仅追踪FLAGS。", + "1": "直接应用 SSE Flush to 0 FLAGS。同时在 DynaRec 中反映 SSE 异常FLAGS（如果可用）。" + } + }, + "BOX64_SSE42": { + "description": "暴露 SSE4.2 能力。", + "options": { + "0": "不暴露 SSE4.2 能力。", + "1": "暴露 SSE4.2 能力。" + } + }, + "BOX64_STEAM_VULKAN": { + "description": "为 Linux Steam UI 强制使用 Vulkan。", + "options": { + "0": "不执行任何操作。", + "1": "为 Linux Steam UI 强制使用 Vulkan。" + } + }, + "BOX64_SYNC_ROUNDING": { + "description": "在 x86 和原生之间同步舍入模式。", + "options": { + "0": "不同步舍入模式。", + "1": "在 x86 和原生之间同步舍入模式。" + } + }, + "BOX64_TRACE_COLOR": { + "description": "启用或禁用彩色追踪输出。", + "options": { + "0": "禁用彩色追踪输出。", + "1": "启用彩色追踪输出。" + } + }, + "BOX64_TRACE_EMM": { + "description": "启用或禁用 EMM（即 MMX）追踪输出。", + "options": { + "0": "禁用 EMM 追踪输出。", + "1": "启用 EMM 追踪输出。" + } + }, + "BOX64_TRACE_FILE": { + "description": "将所有日志和追踪发送到文件而非 `stdout`。", + "options": { + "XXXX": "将所有日志和追踪发送到文件 XXXX。", + "XXXX%pid": "将所有日志和追踪发送到文件 XXXX，文件名中附加 pid。", + "stderr": "将所有日志和追踪发送到 `stderr`。", + "stdout": "将所有日志和追踪发送到 `stdout`。" + } + }, + "BOX64_TRACE_INIT": { + "description": "与 BOX64_TRACE 相同，但立即开始追踪。", + "options": { + "0": "禁用追踪输出。", + "1": "启用追踪输出。追踪在依赖项初始化之前开始。", + "symbolname": "仅对 `symbolname` 启用追踪输出。追踪在依赖项初始化之前开始。", + "0xXXXXXXX-0xYYYYYYY": "对指定地址范围（左闭右开）启用追踪输出。追踪在依赖项初始化之前开始。" + } + }, + "BOX64_TRACE_START": { + "description": "在 N 个指令执行后开始追踪。", + "options": { + "0": "立即开始追踪。", + "1": "执行 1 个指令后开始追踪。", + "XXXX": "执行 XXXX 个指令后开始追踪。" + } + }, + "BOX64_TRACE_XMM": { + "description": "启用或禁用 XMM（即 SSE）追踪输出。", + "options": { + "0": "禁用 XMM 追踪输出。", + "1": "启用 XMM 追踪输出。" + } + }, + "BOX64_TRACE": { + "description": "仅在带追踪功能的 box64 构建中可用。添加所有执行指令的追踪以及寄存器转储。", + "options": { + "0": "禁用追踪输出。", + "1": "启用追踪输出。", + "symbolname": "仅对 `symbolname` 启用追踪输出。", + "0xXXXXXXX-0xYYYYYYY": "对指定地址范围（左闭右开）启用追踪输出。" + } + }, + "BOX64_UNITYPLAYER": { + "description": "检测 UnityPlayer 并应用保守设置。", + "options": { + "0": "不执行任何操作。", + "1": "检测 UnityPlayer（Windows 或 Linux），并在检测到时应用 BOX64_UNITY=1。" + } + }, + "BOX64_UNITY": { + "description": "告诉 Box64 这是一个 Unity 游戏。", + "options": { + "0": "不执行任何操作。", + "1": "这是 Unity 游戏，对 Windows 使用特殊的检测代码，对 Linux 应用 BOX64_DYNAREC_强内存模型=1。" + } + }, + "BOX64_WRAP_EGL": { + "description": "优先使用包装库处理 EGL 和 GLESv2。", + "options": { + "0": "优先使用模拟库处理 EGL 和 GLESv2。", + "1": "优先使用包装库处理 EGL 和 GLESv2。" + } + }, + "BOX64_X11GLX": { + "description": "是否强制 Xorg GLX 扩展存在。", + "options": { + "0": "不强制 Xorg GLX 扩展存在。", + "1": "在使用 XQueryExtension 时要求 Xorg GLX 扩展存在。" + } + }, + "BOX64_X11SYNC": { + "description": "是否强制 X11 显示同步操作。", + "options": { + "0": "不强制 X11 显示同步操作。", + "1": "强制 X11 显示同步操作。" + } + }, + "BOX64_X11THREADS": { + "description": "加载 X11 时调用 XInitThreads。这主要用于使用 Loki_Compat 库的旧 Loki 游戏。", + "options": { + "0": "不调用 XInitThreads。", + "1": "一旦加载 libX11 就调用 XInitThreads。" + } + }, + "BOX64_X87_NO80BITS": { + "description": "x87 80 位 long double 的行为。", + "options": { + "0": "尝试尽可能精确地处理 80 位 long double。", + "1": "对 x87 使用 64 位 double。" + } + }, + "BOX64_NOPERSONA32BITS": { + "description": "禁用 32 位二进制文件的自动 personality 切换（在 Box32 上始终启用）。", + "options": { + "0": "为 32 位二进制文件切换 personality（如果尚未尝试）。", + "1": "不为 32 位二进制文件切换 personality。" + } + } +} \ No newline at end of file