From ef931611140f7265ba82ebb3839f33fa4c7df249 Mon Sep 17 00:00:00 2001
From: DrChat <arkolbed@gmail.com>
Date: Fri, 18 Nov 2016 22:01:45 -0600
Subject: [PATCH] Docs! More docs!

---
 docs/gpu.md    | 32 ++++++++++++++++++++++++++++----
 docs/kernel.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 70 insertions(+), 4 deletions(-)
 create mode 100644 docs/kernel.md

diff --git a/docs/gpu.md b/docs/gpu.md
index 407fcc714..f8e572180 100644
--- a/docs/gpu.md
+++ b/docs/gpu.md
@@ -1,17 +1,37 @@
 # GPU Documentation
 
+## The Xenos Chip
+
+The [Xenos](https://en.wikipedia.org/wiki/Xenos_\(graphics_chip\)) is a graphics
+chip designed by AMD based off of the R5xx architecture.
+
+### Command Processing
+
+The Xenos runs commands supplied to it directly by the DirectX bare-bones driver
+via a ringbuffer located in system memory.
+
+The bulk of the command processing code is located at
+[src/xenia/gpu/command_processor.cc](../src/xenia/gpu/command_processor.cc)
+
+### EDRAM
+
+The Xenos uses special high-speed memory located on the same die as the chip to 
+store framebuffers/render targets.
+
+TODO: More documentation
+
 ## Options
 
 ### General
 
-See the top of [src/xenia/gpu/gpu.cc](https://github.com/benvanik/xenia/blob/master/src/xenia/gpu/gpu.cc).
+See the top of [src/xenia/gpu/gpu.cc](../src/xenia/gpu/gpu.cc).
 
 `--vsync=false` will attempt to render the game as fast as possible instead of
 waiting for a fixed 60hz timer.
 
 ### OpenGL
 
-See the top of [src/xenia/gpu/gl4/gl4_gpu.cc](https://github.com/benvanik/xenia/blob/master/src/xenia/gpu/gl4/gl4_gpu.cc).
+See the top of [src/xenia/gpu/gl4/gl4_gpu.cc](../src/xenia/gpu/gl4/gl4_gpu.cc).
 
 Buggy GL implementations can benefit from `--thread_safe_gl`.
 
@@ -42,7 +62,7 @@ Playground tool.
 
 #### Shader Playground
 
-Built separately (for now) under [tools/shader-playground/](https://github.com/benvanik/xenia/blob/master/tools/shader-playground/)
+Built separately (for now) under [tools/shader-playground/](../tools/shader-playground/)
 is a GUI for interactive shader assembly, disassembly, validation, and
 translation.
 
@@ -59,7 +79,7 @@ disassembly is broken. Finally, the right most box will show the
 translated shader in the desired format.
 
 For more information and setup instructions see
-[tools/shader-playground/README.md](https://github.com/benvanik/xenia/blob/master/tools/shader-playground/README.md).
+[tools/shader-playground/README.md](../tools/shader-playground/README.md).
 
 ### xe-gpu-trace-viewer
 
@@ -95,6 +115,10 @@ you to seek through them in the trace viewer. These files will get large.
 
 ### Command Buffer/Registers
 
+Registers documented at [src/xenia/gpu/register_table.inc](../src/xenia/gpu/register_table.inc).
+
+PM4 commands documented at [src/xenia/gpu/xenos.h](../src/xenia/gpu/xenos.h#L521).
+
 ### Shaders
 
 * [LLVM R600 Tables](https://llvm.org/viewvc/llvm-project/llvm/trunk/lib/Target/R600/R600Instructions.td)
diff --git a/docs/kernel.md b/docs/kernel.md
new file mode 100644
index 000000000..82e2ed755
--- /dev/null
+++ b/docs/kernel.md
@@ -0,0 +1,42 @@
+# Kernel Documentation
+
+## Kernel shims
+Xenia implements all kernel APIs as native functions under the host.
+
+When a module is loaded, the loader will find all kernel imports, put a syscall in
+their place, then lookup a kernel export and link it to each import. The JIT will
+generate a sequence of instructions to call into Xenia's export if it encounters a syscall.
+
+Currently, there are two ways an export can be defined -
+[for example](../src/xenia/kernel/xboxkrnl/xboxkrnl_audio.cc):
+* `SHIM_CALL XAudioGetSpeakerConfig_shim(PPCContext* ppc_context, KernelState* kernel_state)`
+* `dword_result_t XAudioGetSpeakerConfig(lpdword_t config_ptr)`
+
+The `SHIM_CALL` convention is deprecated, but allows a closer look at the internals of how
+calls are done. `ppc_context` is the guest PowerPC context, which holds all guest
+registers. Function parameters are fetched from r3...r10 (`SHIM_GET_ARG_32`), and
+additional parameters are loaded from the stack. The return value (if there is one)
+is stored in r3 (`SHIM_SET_RETURN_32`).
+
+Details on how calls transition from guest -> host can be found in the [cpu documentation](cpu.md).
+
+The newer convention does the same, but uses templates to automate the process
+of loading arguments and setting a return value.
+
+## Kernel Modules
+Xenia has an implementation of two xbox kernel modules, xboxkrnl.exe and xam.xex
+
+### xboxkrnl.exe - Xbox kernel
+
+Defined under src/xenia/kernel/xboxkrnl.
+
+This is a slightly modified version of the NT kernel. Most of the APIs 
+are equivalent to ones you'd find on MSDN or other online sources.
+
+Source files are organized into groups of APIs.
+
+### xam.xex - Xbox Auxiliary Methods
+
+Defined under src/xenia/kernel/xam.
+
+This module implements functionality specific to the Xbox.
\ No newline at end of file