WIP: [docs] Add 3rd party links, debug and testing guidelines

Signed-off-by: lizzie <lizzie@eden-emu.dev>

docs/Debug.md

@@ -0,0 +1,68 @@
+# Debug Guidelines
+
+## Debugging (host code)
+
+Ignoring SIGSEGV when debugging in host:
+
+- **gdb**: `handle all nostop pass`.
+- **lldb**: `pro hand -p true -s false -n false SIGSEGV`.
+
+## Debugging (guest code)
+
+### gdb
+
+Run `./build/bin/eden-cli -c <path to your config file (see logs where you run eden normally to see where it is)> -d -g <path to game>`
+
+Then hook up an aarch64-gdb (use `yay aarch64-gdb` or `sudo pkg in arch64-gdb` to install)
+Then type `target remote localhost:1234` and type `c` (for continue) - and then if it crashes just do a `bt` (backtrace) and `layout asm`.
+
+### gdb cheatsheet
+
+- `mo <cmd>`: Monitor commands, `get info`, `get fastmem` and `get mappings` are available. Type `mo help` for more info.
+- `detach`: Detach from remote (i.e restarting the emulator).
+- `c`: Continue
+- `p <expr>`: Print variable, `p/x <expr>` for hexadecimal.
+- `r`: Run
+- `bt`: Print backtrace
+- `info threads`: Print all active threads
+- `thread <number>`: Switch to the given thread (see `info threads`)
+- `layout asm`: Display in assembly mode (TUI)
+- `si`: Step assembly instruction
+- `s` or `step`: Step over LINE OF CODE (not assembly)
+- `display <expr>`: Display variable each step.
+- `n`: Next (skips over call frame of a function)
+- `frame <number>`: Switches to the given frame (from `bt`)
+- `br <expr>`: Set breakpoint at `<expr>`.
+- `delete`: Deletes all breakpoints.
+- `catch throw`: Breakpoint at throw. Can also use `br __cxa_throw`
+- `br _mesa_error`: Break on mesa errors (set environment variable `MESA_DEBUG=1` beforehand), see [MESA_DEBUG](https://mesa-docs.readthedocs.io/en/latest/debugging.html).
+
+Expressions can be `variable_names` or `1234` (numbers) or `*var` (dereference of a pointer) or `*(1 + var)` (computed expression).
+
+For more information type `info gdb` and read [the man page](https://man7.org/linux/man-pages/man1/gdb.1.html).
+
+## Simple checklist for debugging black screens using Renderdoc
+
+Renderdoc is a free, cross platform, multi-graphics API debugger. It is an invaluable tool for diagnosing issues with graphics applications, and includes support for Vulkan. Get it [here](https://renderdoc.org).
+
+Before using renderdoc to diagnose issues, it is always good to make sure there are no validation errors. Any errors means the behavior of the application is undefined. That said, renderdoc can help debug validation errors if you do have them.
+
+When debugging a black screen, there are many ways the application could have setup Vulkan wrong. 
+Here is a short checklist of items to look at to make sure are appropriate:
+* Draw call counts are correct (aka not zero, or if rendering many triangles, not 3)
+* Vertex buffers are bound 
+* vertex attributes are correct - Make sure the size & offset of each attribute matches what should it should be
+* Any bound push constants and descriptors have the right data - including:
+  * Matrices have correct values - double check the model, view, & projection matrices are uploaded correctly
+* Pipeline state is correct
+  * viewport range is correct - x,y are 0,0; width & height are screen dimensions, minDepth is 0, maxDepth is 1, NDCDepthRange is 0,1
+  * Fill mode matches expected - usually solid
+  * Culling mode makes sense - commonly back or none
+  * The winding direction is correct - typically CCW (counter clockwise)
+  * Scissor region is correct - usually same as viewport's x,y,width, &height
+* Blend state is correct
+* Depth state is correct - typically enabled with Function set to Less than or Equal
+* Swapchain images are bound when rendering to the swapchain
+* Image being rendered to is the same as the one being presented when rendering to the swapchain 
+
+Alternatively, a [RenderDoc Extension](https://github.com/baldurk/renderdoc-contrib/tree/main/baldurk/whereismydraw) ([Archive](https://web.archive.org/web/20250000000000*/https://github.com/baldurk/renderdoc-contrib/tree/main/baldurk/whereismydraw)) exists which automates doing a lot of these manual steps.

docs/Development.md

@@ -1,4 +1,4 @@
-# Guidelines
+# Development guidelines
 
 ## License Headers
 All commits must have proper license header accreditation.
@@ -103,49 +103,6 @@ May not be used but worth mentioning nonethless:
 - OGG files: Use [OptiVorbis](https://github.com/OptiVorbis/OptiVorbis).
 - Video files: Use ffmpeg, preferably re-encode as AV1.
 
-# Debugging
-
-## Debugging (host code)
-
-Ignoring SIGSEGV when debugging in host:
-
-- **gdb**: `handle all nostop pass`.
-- **lldb**: `pro hand -p true -s false -n false SIGSEGV`.
-
-## Debugging (guest code)
-
-### gdb
-
-Run `./build/bin/eden-cli -c <path to your config file (see logs where you run eden normally to see where it is)> -d -g <path to game>`
-
-Then hook up an aarch64-gdb (use `yay aarch64-gdb` or `sudo pkg in arch64-gdb` to install)
-Then type `target remote localhost:1234` and type `c` (for continue) - and then if it crashes just do a `bt` (backtrace) and `layout asm`.
-
-### gdb cheatsheet
-
-- `mo <cmd>`: Monitor commands, `get info`, `get fastmem` and `get mappings` are available. Type `mo help` for more info.
-- `detach`: Detach from remote (i.e restarting the emulator).
-- `c`: Continue
-- `p <expr>`: Print variable, `p/x <expr>` for hexadecimal.
-- `r`: Run
-- `bt`: Print backtrace
-- `info threads`: Print all active threads
-- `thread <number>`: Switch to the given thread (see `info threads`)
-- `layout asm`: Display in assembly mode (TUI)
-- `si`: Step assembly instruction
-- `s` or `step`: Step over LINE OF CODE (not assembly)
-- `display <expr>`: Display variable each step.
-- `n`: Next (skips over call frame of a function)
-- `frame <number>`: Switches to the given frame (from `bt`)
-- `br <expr>`: Set breakpoint at `<expr>`.
-- `delete`: Deletes all breakpoints.
-- `catch throw`: Breakpoint at throw. Can also use `br __cxa_throw`
-- `br _mesa_error`: Break on mesa errors (set environment variable `MESA_DEBUG=1` beforehand), see [MESA_DEBUG](https://mesa-docs.readthedocs.io/en/latest/debugging.html).
-
-Expressions can be `variable_names` or `1234` (numbers) or `*var` (dereference of a pointer) or `*(1 + var)` (computed expression).
-
-For more information type `info gdb` and read [the man page](https://man7.org/linux/man-pages/man1/gdb.1.html).
-
 # Bisecting older commits
 
 Since going into the past can be tricky (especially due to the dependencies from the project being lost thru time). This should "restore" the URLs for the respective submodules.

docs/README.md

@@ -5,6 +5,7 @@ This contains documentation created by developers. This contains build instructi
 - **[General Build Instructions](Build.md)**
 - **[Development Guidelines](Development.md)**
 - **[Dependencies](Deps.md)**
-- **[CPM - CMake Package Manager](./CPMUtil)**
+- **[Debug Guidelines](./Debug.md)**
+- **[CPM - CMake Package Manager](CPMUtil.md)**
 - **[Platform-Specific Caveats](Caveats.md)**
 - **[User Handbook](User.md)**

docs/User.md

@@ -8,3 +8,4 @@ This handbook is primarily aimed at the end-user - baking useful knowledge for e
 - **[Audio](user/Audio.md)**
 - **[Graphics](user/Graphics.md)**
 - **[Platforms and Architectures](user/Architectures.md)**
+- **[Testing](user/Testing.md)**

docs/user/Testing.md

@@ -0,0 +1,32 @@
+# User Handbook - Testing
+
+While this is mainly aimed for testers - normal users can benefit from these guidelines to make their life easier when trying to outline and/or report an issue.
+
+## How to Test a PR Against the Based Master When Issues Arise
+
+When you're testing a pull request (PR) and encounter unexpected behavior, it's important to determine whether the issue was introduced by the PR or if it already exists in the base code. To do this, compare the behavior against the based master branch.
+
+Even before an issue occurs, it is best practice to keep the same settings and delete the shader cache. Using an already made shader cache can make the PR look like it is having a regression in some rare cases.
+
+### What to Do When Something Seems Off
+If you notice something odd during testing:
+- Reproduce the issue using the based master branch.
+- Observe whether the same behavior occurs.
+
+### Two Possible Outcomes
+- If the issue exists in the based master: This means the problem was already present before the PR. The PR most likely did not introduce the regression.
+- If the issue does not exist in the based master: This suggests the PR most likely introduced the regression and needs further investigation.
+
+### Report your findings
+When you report your results:
+- Clearly state whether the behavior was observed in the based master.
+- Indicate whether the result is good (expected behavior) or bad (unexpected or broken behavior). Without mentioning if your post/report/log is good or bad it may confuse the Developer of the PR.
+- Example:
+```
+1. "Tested on based master — issue not present. Bad result for PR, likely regression introduced."
+2. "Tested on based master — issue already present. Good result for PR, not a regression."
+```
+
+This approach helps maintain clarity and accountability in the testing process and ensures regressions are caught and addressed efficiently. If the behavior seems normal for a certain game/feature then it may not be always required to check against the based master. 
+
+If a master build for the PR' based master does not exist. It will be helpful to just test past and future builds nearby. That would help with gathering more information about the problem.

docs/user/ThirdParty.md

@@ -0,0 +1,8 @@
+# User Handbook - Third party tools and extras
+
+The Eden emulator by itself lacks some functionality - or otherwise requires external files (such as packaging) to operate correctly in a given OS. Addendum to that some repositories provide nightly or specialised builds of the emulator.
+
+While most of the links mentioned in this guide are relatively "safe"; we urge users to use their due diligence and appropriatedly verify the integrity of all files downloaded and ensure they're not compromised.
+
+- [Nightly Eden builds](https://github.com/pflyly/eden-nightly)
+- [NixOS Eden Flake](https://github.com/Grantimatter/eden-flake)