Moved documentation to "docs/" folder.

author: Jai-JAP <parjailu@gmail.com> 2021-07-12 10:52:59 +0530
committer: Jai-JAP <parjailu@gmail.com> 2021-07-12 10:52:59 +0530
commit: cc8f926d669aad7a05d439461dbbe89cd02bd6b3 (patch)
tree: bc95696a1ddf596b0277ff1707a62445e59cb8ce /docs
parent: 486aa58b157c74d2d0623eecd08489fb520a5510 (diff)
download: box64-cc8f926d669aad7a05d439461dbbe89cd02bd6b3.tar.gz
box64-cc8f926d669aad7a05d439461dbbe89cd02bd6b3.zip
7 files changed, 366 insertions, 0 deletions
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
new file mode 100644
index 00000000..c8527d88
--- /dev/null
+++ b/docs/CHANGELOG.md
@@ -0,0 +1,55 @@
+Current Version
+======
+
+v0.1.2
+======
+* OpenSource!
+* A few more opcode added to the Interpretor and the Dynarec
+* Improved Native Function calling
+* Added some function to limit allocated memory to 47bits space (for Wine)
+* Improved and Fixed the functions to limit allocated memory to 32bits space
+* Wine is starting now, but not everything and every version works
+
+v0.1.0
+======
+* Improvement to ElfLoader
+* More opcode added to the Dynarec
+* More lib wrapping
+* Some fixes to a few function signature
+* Improvement to Signal handling, and internal mutex handling
+* A few fixes to some dynarec opcodes
+* A few fixes to some interpretor opcodes
+
+v0.0.8
+======
+* Improvement to SSE/x87 handling
+* More opcode added to the Dynarec
+* More lib wrapping
+
+v0.0.6
+======
+* Added Dynarec for ARM64
+* Many general CPU opcode added to the Dynarec
+* Many SSEx opcodes added to the Dynarec
+* Added a few more symbols in libc
+* A few changes to the "thread once" handling
+* New Logo and Icon from @grayduck
+
+v0.0.4
+======
+* Added a lot of opcodes
+* Added SDL1 and SDL2 wrapping
+* OpenGL/GLU wrapping done
+* libasound / libpulse wrapping done
+* libopenal / libalure / libalut wrapping done
+* Many X11 libs wrapped
+* Added "install" with binfmt integration
+* A few games are actualy starting now (old WorldOfGoo, Into The Breach, VVVVVV and Thimbeweed Park)
+
+v0.0.2
+======
+* Using box86 as a base, implemented most planned box64 part except dynarec
+* Wrapped a few libs
+* ELF loader a bit crude, but seems working
+* Signal handling implemented
+* MMX and x87 are sharing their registers
diff --git a/docs/COMPILE.md b/docs/COMPILE.md
new file mode 100755
index 00000000..d12fd2a0
--- /dev/null
+++ b/docs/COMPILE.md
@@ -0,0 +1,92 @@
+Compiling
+----
+#### for RK3399
+
+Using a 64bits OS:
+```
+git clone https://github.com/ptitSeb/box64
+cd box64
+mkdir build; cd build; cmake .. -DRK3399=1 -DCMAKE_BUILD_TYPE=RelWithDebInfo
+make -j4
+sudo make install
+```
+If it's the first install, you also need:
+```
+sudo systemctl restart systemd-binfmt
+```
+
+#### for PI4
+
+Warning, you need a 64bits OS:
+
+```
+git clone https://github.com/ptitSeb/box64
+cd box64
+mkdir build; cd build; cmake .. -DRPI4ARM64=1 -DCMAKE_BUILD_TYPE=RelWithDebInfo
+make -j4
+sudo make install
+```
+If it's the first install, you also need:
+```
+sudo systemctl restart systemd-binfmt
+```
+
+#### for TEGRA X1
+
+Using a 64bits OS:
+
+```
+git clone https://github.com/ptitSeb/box64
+cd box64
+mkdir build; cd build; cmake .. -DTEGRAX1=1 -DCMAKE_BUILD_TYPE=RelWithDebInfo
+make -j4
+sudo make install
+```
+If it's the first install, you also need:
+```
+sudo systemctl restart systemd-binfmt
+```
+
+#### for Other ARM64 Linux platforms
+
+ `mkdir build; cd build; cmake .. -DARM_DYNAREC=ON -DCMAKE_BUILD_TYPE=RelWithDebInfo; make -j$(nproc)`
+
+#### for x86_64 Linux
+
+ `mkdir build; cd build; cmake .. -DLD80BITS=1 -DNOALIGN=1 -DCMAKE_BUILD_TYPE=RelWithDebInfo; make -j$(nproc)`
+
+If you encounter some linking errors, try activating `NOLOADADDR` (`cmake -DNOLOADADDR=ON; make -j$(nproc)`).
+
+### use ccmake
+
+Alternatively, you can **use the curses-bases ccmake (or any other gui frontend for cmake)** to select wich platform to use interactively.
+
+### Customize your build
+
+*Use ccache if you have it* 
+
+Add `-DUSE_CCACHE=1` if you have ccache (it's better if you plan to touch the sources)
+
+*To have some debug info* 
+
+The `-DCMAKE_BUILD_TYPE=RelWithDebInfo` argument makes a build that is both optimized for speed, and has debug information embedded. That way, if you have a crash or try to analyse performance, you'll have some symbols.
+
+*To have a Trace Enabled build* 
+
+To have a trace enabled build ( ***the interpretor will be slightly slower***), add `-DHAVE_TRACE=1` but you will need, at runtime, to have the [Zydis library](https://github.com/zyantific/zydis) library in your `LD_LIBRARY_PATH` or in the system library folders.
+
+*To have ARM Dynarec*
+
+The Dynarec is only available on the ARM architecture(Right now, anyways.). Notes also that VFPv3 and NEON are required for the Dynarec. Activate it by using `-DARM_DYNAREC=1`.
+
+*Not building from a git clone*
+
+If you are not building from a git clone (for example, downloading a release source zipped from github), you need to activate `-DNOGIT=1` from cmake to be able to build (normal process include git sha1 of HEAD in the version that box64 print).
+
+----
+
+Testing
+----
+A few tests are included.
+They can be launched with `ctest`
+They are very basic and don't test much for now.
diff --git a/docs/LICENSE b/docs/LICENSE
new file mode 100644
index 00000000..0718fe3c
--- /dev/null
+++ b/docs/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 ptitSeb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..41fecb24
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,51 @@
+# box64
+
+![Official logo](Box64Logo.png "Official Logo")
+Linux Userspace x86_64 Emulator with a twist
+
+----
+
+Box64 lets you run x86_64 Linux programs (such as games) on non-x86_64 Linux systems, like ARM (host system needs to be 64bit little-endian).
+
+You can find many more Box64 video on Youtube in the [MicroLinux](https://www.youtube.com/channel/UCwFQAEj1lp3out4n7BeBatQ), [Pi Labs](https://www.youtube.com/channel/UCgfQjdc5RceRlTGfuthBs7g) or [The Byteman](https://www.youtube.com/channel/UCEr8lpIJ3B5Ctc5BvcOHSnA) Channels
+
+Because Box64 uses the native versions of some "system" libraries, like libc, libm, SDL, and OpenGL, it's easy to integrate and use with most applications, and performance can be surprisingly high in many cases. Take a look at thoses bench analysis for an example [here](https://box86.org/index.php/2021/06/game-performances/).
+
+Box64 integrates a DynaRec (dynamic recompiler) for the ARM64 platform, providing a speed boost between 5 to 10 times faster than only using the interpreter. Some high level information on how the Dynarec work can be found [here](https://box86.org/2021/07/inner-workings-a-high%e2%80%91level-view-of-box86-and-a-low%e2%80%91level-view-of-the-dynarec/).
+
+Some x64 internal opcodes use parts of "Realmode X86 Emulator Library", see [x64primop.c](src/emu/x64primop.c) for copyright details
+
+<img src="Box64Icon.png" width="96" height="96">
+
+Logo and Icon made by @grayduck, thanks!
+
+----
+
+Usage
+----
+
+There are a few environment variables to control the behaviour of Box64.
+
+See [here](USAGE.md) for all environment variables and what they do.
+
+Note: Box64's Dynarec uses a mechanism with Memory Protection and a SegFault signal handler to handle JIT code. In simpler terms, if you want to use GDB to debug a running program that use JIT'd code (like mono/Unity3D), you will still have many "normal" segfaults triggering. It is suggested to use something like `handle SIGSEGV nostop` in GDB to not stop at each segfault, and maybe put a breakpoint inside `my_memprotectionhandler` in `signals.c` if you want to trap SegFaults.
+
+----
+
+Compiling/Installation
+----
+> Compilation instructions can be found [here](COMPILE.md)  
+
+----
+
+Version history
+----
+
+The change log is available [here](CHANGELOG.md)
+
+----
+
+Final words
+----
+
+(If you use Box64 in your project, please don't forget to mention Box64!)
diff --git a/docs/USAGE.md b/docs/USAGE.md
new file mode 100755
index 00000000..27afc08d
--- /dev/null
+++ b/docs/USAGE.md
@@ -0,0 +1,147 @@
+
+Usage
+----
+
+There are many environment variables to control Box64 behaviour. 
+
+#### BOX64_LOG
+Controls the Verbosity level of the logs
+ * 0: NONE : No message (except some fatal error). (Default.)
+ * 1: INFO : Show some minimum log (Example: librairies not found)
+ * 2: DEBUG : Details a lot of stuff (Example: relocations or functions called).
+ * 3: DUMP : All DEBUG plus DUMP of all ELF Info.
+
+#### BOX64_NOBANNER
+Disables Box64 printing its version and build
+ * 0 : Enable printing its banner. (Default.)
+ * 1 : Disable printing its banner. 
+
+#### BOX64_LD_LIBRARY_PATH
+Path to look for x86_64 libraries. Default is current folder and `lib` in current folder.
+Also, `/usr/lib/x86_64-linux-gnu` and `/lib/x86_64-linux-gnu` are added if they exist.
+
+#### BOX64_PATH
+Path to look for x86_64 executable. Default is current folder and `bin` in current folder.
+
+#### BOX64_DLSYM_ERROR
+Enables/Disables the logging of `dlsym` errors.
+ * 0 : Don't log `dlsym` errors. (Default.)
+ * 1 : Log dlsym errors.
+
+#### BOX64_TRACE_FILE
+Send all log and trace to a file instead of `stdout`
+Also, if name contains `%pid` then this is replaced by the actual PID of box64 instance
+Use `stderr` to use this instead of default `stdout` 
+
+#### BOX64_TRACE
+Only on build with trace enabled. Trace allow the logging of all instruction executed, along with register dump
+ * 0 : No trace. (Default.) 
+ * 1 : Trace enabled. Trace start after the initialisation of all depending libraries is done.
+ * symbolname : Trace only `symbolname` (trace is disable if the symbol is not found).
+ * 0xXXXXXXX-0xYYYYYYY : Trace only between the 2 addresses.
+
+#### BOX64_TRACE_INIT
+Use BOX64_TRACE_INIT instead of BOX_TRACE to start trace before the initialisation of libraries and the running program
+ * 0 : No trace. (Default.)
+ * 1 : Trace enabled. The trace start with the initialisation of all depending libraries is done.
+
+#### BOX64_TRACE_START
+Only on builds with trace enabled.
+ * NNNNNNN : Start trace only after NNNNNNNN opcode execute (number is an `uint64_t`).
+
+#### BOX64_TRACE_XMM
+Only on builds with trace enabled.
+ * 0 : The XMM (i.e. SSE/SSE2) register will not be logged with the general and x86 registers. (Default.)
+ * 1 : Dump the XMM registers.
+
+#### BOX64_TRACE_EMM
+Only on builds with trace enabled.
+ * 0 : The EMM (i.e. XMM/x87) register will not be logged with the general and x86 registers. (Default.)
+ * 1 : Dump the EMM registers.
+
+#### BOX64_TRACE_COLOR
+Only on builds with trace enabled.
+ * 0 : The general registers will always be the default white color. (Default.)
+ * 1 : The general registers will change color in the dumps when they changed value.
+
+#### BOX64_LOAD_ADDR
+Try to load at 0xXXXXXX main binary (if binary is a PIE)
+ * 0xXXXXXXXX : The load address . (Only active on PIE programs.)
+
+#### BOX64_NOSIGSEGV
+Disable handling of SigSEGV. (Very useful for debugging.)
+ * 0 : Let the x86 program set sighandler for SEGV (Default.)
+ * 1 : Disable the handling of SigSEGV.
+
+#### BOX64_NOSIGILL
+Disable handling of SigILL (to ease debugging mainly).
+ * 0 : Let x86 program set sighandler for Illegal Instruction
+ * 1 : Disables the handling of SigILL 
+
+#### BOX64_X11THREADS
+Call XInitThreads when loading X11. (This is mostly for old Loki games with the Loki_Compat library.)
+ * 0 : Don't force call XInitThreads. (Default.)
+ * 1 : Call XInitThreads as soon as libX11 is loaded.
+
+#### BOX64_X11GLX
+Force libX11's GLX extension to be present.
+* 0 : Do not force libX11's GLX extension to be present. 
+* 1 : GLX will always be present when using XQueryExtension. (Default.)
+
+#### BOX64_DYNAREC_DUMP
+Enables/disables Box64's Dynarec's dump.
+ * 0 : Disable Dynarec's blocks dump. (Default.)
+ * 1 : Enable Dynarec's blocks dump.
+ * 2 : Enable Dynarec's blocks dump with some colors.
+
+#### BOX64_DYNAREC_LOG
+Set the level of DynaRec's logs.
+ * 0 : NONE : No Logs for DynaRec. (Default.)
+ * 1 :INFO : Minimum Dynarec Logs (only unimplemented OpCode).
+ * 2 : DEBUG : Debug Logs for Dynarec (with details on block created / executed).
+ * 3 : VERBOSE : All of the above plus more.
+
+#### BOX64_DYNAREC
+Enables/Disables Box64's Dynarec.
+ * 0 : Disables Dynarec.
+ * 1 : Enable Dynarec. (Default.)
+
+#### BOX64_DYNAREC_TRACE
+Enables/Disables trace for generated code.
+ * 0 : Disable trace for generated code. (Default.)
+ * 1 : Enable trace for generated code (like regular Trace, this will slow down the program a lot and generate huge logs).
+
+#### BOX64_NODYNAREC 
+Forbid dynablock creation in the interval specified (helpfull for debugging behaviour difference between Dynarec and Interpretor)
+ * 0xXXXXXXXX-0xYYYYYYYY : define the interval where dynablock cannot start (inclusive-exclusive)
+
+#### BOX64_LIBGL
+ * libXXXX set the name for libGL (defaults to libGL.so.1).
+ * /PATH/TO/libGLXXX : Sets the name and path for libGL
+ You can also use SDL_VIDEO_GL_DRIVER
+
+#### BOX64_LD_PRELOAD
+ * XXXX[:YYYYY] force loading XXXX (and YYYY...) libraries with the binary
+ PreLoaded libs can be emulated or native, and are treated the same way as if they were comming from the binary
+ 
+#### BOX64_EMULATED_LIBS
+ * XXXX[:YYYYY] force lib XXXX (and YYYY...) to be emulated (and not wrapped)
+Some games uses an old version of some libraries, with an ABI incompatible with native version.
+Note that LittleInferno for example is auto detected, and libvorbis.so.0 is automatical added to emulated libs, and same for Don't Starve (and Together / Server variant) that use an old SDL2 too
+
+#### BOX64_ALLOWMISSINGLIBS
+Allow Box64 to continue even if a library is missing.
+ * 0 : Box64 will stop if a library cannot be loaded. (Default.)
+ * 1 : Continue even if a needed library cannot be loaded. Unadvised, this will, in most cases, crash later on.
+
+#### BOX64_JITGDB
+
+ * 0 : Just print the Segfault message on segfault (default)
+ * 1 : Launch `gdb` when a segfault, bus error or illegal instruction signal is trapped, attached to the offending process and go in an endless loop, waiting.
+ When in gdb, you need to find the correct thread yourself (the one with `my_box64signalhandler` in is stack)
+ then probably need to `finish` 1 or 2 functions (inside `usleep(..)`) and then you'll be in `my_box64signalhandler`, 
+ just before the printf of the Segfault message. Then simply 
+ `set waiting=0` to exit the infinite loop.
+ * 2 : Launch `gdbserver` when a segfault, bus error or illegal instruction signal is trapped, attached to the offending process, and go in an endless loop, waiting.
+ Use `gdb /PATH/TO/box64` and then `target remote 127.0.0.1:1234` to connect to the gdbserver (or use actual IP if not on the machine). After that, the procedure is the same as with ` BOX64_JITGDB=1`.
+ This mode can be usefullwhen programs redirect all console output to a file (like Unity3D Games)
diff --git a/docs/img/Box64Icon.png b/docs/img/Box64Icon.png
new file mode 100755
index 00000000..8b3c7a91
--- /dev/null
+++ b/docs/img/Box64Icon.png
Binary files differdiff --git a/docs/img/Box64Logo.png b/docs/img/Box64Logo.png
new file mode 100755
index 00000000..bac2f54d
--- /dev/null
+++ b/docs/img/Box64Logo.png
Binary files differ
author	Jai-JAP <parjailu@gmail.com>	2021-07-12 10:52:59 +0530
committer	Jai-JAP <parjailu@gmail.com>	2021-07-12 10:52:59 +0530
commit	cc8f926d669aad7a05d439461dbbe89cd02bd6b3 (patch)
tree	bc95696a1ddf596b0277ff1707a62445e59cb8ce /docs
parent	486aa58b157c74d2d0623eecd08489fb520a5510 (diff)
download	box64-cc8f926d669aad7a05d439461dbbe89cd02bd6b3.tar.gz box64-cc8f926d669aad7a05d439461dbbe89cd02bd6b3.zip