Added COMPILE and USAGE docs

4 files changed, 223 insertions, 0 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 07c522eb..e2ac9cf2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
 Current version

 ======

+* 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

 ======

diff --git a/COMPILE.md b/COMPILE.md
new file mode 100755
index 00000000..0bb2a309
--- /dev/null
+++ b/COMPILE.md
@@ -0,0 +1,75 @@
+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 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)`

+

+#### 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)

+

+*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 ( ***it will be 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`. Also, be sure to use `-marm` in compilation flags (because many compileur use Thumb as default, and the dynarec will not work in this mode).

+

+*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/README.md b/README.md
index b9235f73..26023bd3 100644
--- a/README.md
+++ b/README.md
@@ -30,6 +30,12 @@ Note: Box64's Dynarec uses a mechanism with Memory Protection and a SegFault sig
 

 ----

 

+Compiling/Installation

+----

+> Compilation instructions can be found [here](COMPILE.md)  

+

+----

+

 Version history

 ----

 

diff --git a/USAGE.md b/USAGE.md
new file mode 100755
index 00000000..9fccf749
--- /dev/null
+++ b/USAGE.md
@@ -0,0 +1,136 @@
+

+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

+

+#### 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_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)