Created Overview of the project & Glossary of terms (markdown)

Overview-of-the-project-&-Glossary-of-terms.md

@@ -0,0 +1,107 @@
+# Cxbx-Reloaded rationale
+   Cxbx has been around since 2002, gained a spin-off with Dxbx in 2008-2011, but both attempts are
+   currently still at a very low compatibility-level. Cxbx-Reloaded is an attempt to bring back live
+   into the Cxbx codebase and improve it, so it will support (much) more software than ever before.
+   We believe Cxbx-Reloaded has a right to exist as a Hybrid emulator, covering the middle-ground
+   between the LLE based emulators and the completely HLE based old Cxbx, which offered one remarkable
+   feature : faster-than-original emulation speed. We intent to keep that speed (mainly contributed
+   by the fact we run code on the native CPU) and improve compatability by using Hybrid emulation of
+   various XBox hardware components.
+
+#Glossary of terms used in this project:
+
+## LLE
+   Low Level Emulation, a technique in which an emulated piece of software is executed by way of
+   emulating the original hardware. This is done by a piece of code that replicates as close as possible
+   the behaviour and state of the emulated hardware.
+
+## HLE
+   High Level Emulation, a technique in which an emulated piece of software is executed without
+   emulating the original hardware. This can done when the emulated system and the host use comparable
+   hardware. In the case of Cxbx, the CPU code is executed as-is most of the time, and hardware acceses
+   to the video, audio and input/output devices is bypassed using Patches over the original Functions.
+
+## Hybrid emulation
+   A mix of HLE and LLE, in which some parts are HLE'ed, while other parts are LLE'ed.
+   In the case of Cxbx, we're underway to emulate the graphics and sound hardware using a form of LLE.
+   It won't be complete LLE, as we're planning to interpret hardware accesses and replate their
+   behaviour using native hardware using OpenGL for graphics (and possibly something like OpenAL for
+   audio and OpenIO for input/output).
+
+## XBox emulation
+   Emulation of the Microsoft XBox console platform. In contrast with many other platforms,
+   there are not many succesfull XBox emulators. The first one was made by Microsoft themselves,
+   for the XBox 360. Others are xqemu and the XBox/Chihiro driver in MAME, which are both quite
+   complete, since they both use LLE, but as a result both are also quite slow.
+  
+## XBox harware
+   The main XBox hardware components are: a 733MHz Pentium 3 CPU, a NV2A GPU, and an MCPX APU.
+
+## XBox Kernel (BIOS)
+   Normally present in the BIOS of the XBox, the kernel offers more than 360 basic system functions.
+   These functions deal with memory reservation, manage kernel objects (like hardware timers,
+   mutexes, semaphores, storage devices, symbolic links, files, etc.) and accesses to hardware
+   (like PCI, EEPROM, etc.). Cxbx contains it's own implementation of the Kernel, as we need our
+   emulator to create it's own 'sandbox' enviroment, so it's native code execution doesn't escape
+   the sandbox and overloads, or otherwise wreaks havoc on the native system.
+
+## XBox Development Kit (XDK)
+   A package full of resouces (documentation, tools, source code, etc.) as once distributed by Microsoft to XBox developers.
+
+## XBox Executable (XBE)
+   A binary file containing all code for a piece of software that can be run on the XBox.
+   An XBE file is generated using a compiler toolchain of either a XDK or an Open Source alternative (like OpenXDK).
+
+## Library
+   A binary object file distributed with an XDK, containing Symbols - code and data needed for specific tasks.
+   Libraries are linked (inserted) into XBE files. Older XDK's contained Libraries with different versions.
+   Later XDK's used only one Version for all it's contained Libraries.
+
+## Version
+   A four-digit number, indicating the release number of a Library (thus, also of all Symbols orginating from it)
+
+## Location
+   A unique memory address with contents of an XBE loaded into memory, ready for execution or read/write access
+
+## Symbol
+   A unique label, indicating either a Global or a Function.
+
+## Global
+   A piece of data, uniquely indentified by a Symbol (thus, Globals are a subset of all Symbols)
+
+## Function
+   A piece of code, uniquely indentified by a Symbol (thus, Functions are a subset of all Symbols)
+
+## XRef
+  A cross-referenced Symbol Location from within a Function 
+
+## OOVPA
+  A data structure used as a 'thumbprint' for searching for the Location of a Function
+
+## Symbol detection
+  A method that tries to find Symbol Locations in an XBE, in case of Cxbx using OOVPA's.
+
+## Patch
+   A piece of emulation code, used as a replacement, written over the Location of a Function.
+   This original Function is found using an OOVPA, resulting in the Location of both Functions
+   and in some cases also XRef-erenced Symbols (thus: either Functions or Globals).
+   Patch are written over the found Function Locations, so a wrongly detected Location
+   will result in incorrecly placed Patches, resulting in incorrect emulation behaviour and
+   potential crashes. Also, the implementation of a Patch greatly influences the level of
+   accurateness of emulation. Some Patches don't do anything, whilst others try to mimic the
+   behaviour of the original Function as closely as possible. The end result is sometimes
+   very noticable (beeps & pops, graphics artifacts, etc) and sometimes you can't tell
+   the difference.
+
+## AliasOovpa
+   An alternative OOVPA, used when a Patch may also be applied to another OOVPA 'thumbprint'
+   This is mainly used for XBE's generated with LTCG, which mangles Function contents somewhat.
+
+## LTCG
+   An optimizing linking technique sometimes used when compiling XBE's, resulting in faster code.
+   This results in slight deviations in the way Functions are represented in the XBE.
+   This makes Function detection unreliable, resulting in unused Patches, cause emulation errors.
+
+## Name
+   A string used for debugging, associated with a combination of a Symbol (via an Oovpa) and Version.
+   In some cases expanded with additional information