Update scripts, cleanup project files, and add more documentation

.gitignore

@@ -4,13 +4,13 @@ SCUS_971.98
 *971*98*
 SCUS_*.*
 *.elf
+disc/*
 
 prodg*
 tools/cc/
 usr/
 
 html/
-functions.txt
 
 # Splat files
 splat/

README.md

@@ -27,44 +27,43 @@
 <!-- Shields -->
 [![Build][build-badge]][build-url] ![code-progress-badge] <!--![data-progress-badge]--> [![Contributors][contributors-badge]][contributors-url] [![Discord Channel][discord-badge]][discord-url] [![Docs][docs-badge]][docs-url] [![Wiki][wiki-badge]][wiki-url]
 
-[<img src="logo.png" style="margin:7px" align="right" width="33%" alt="Sly 1 Decompilation Logo by Cooper941">][docs-url]
+[<img src=".github/logo.png" style="margin:7px" align="right" width="33%" alt="Sly 1 Decompilation Logo by Cooper941">][docs-url]
 
 This is a work-in-progress decompilation of [*Sly Cooper and the Thievius Raccoonus*](https://en.wikipedia.org/wiki/Sly_Cooper_and_the_Thievius_Raccoonus) for the PlayStation 2. It builds the NTSC-U version of the game, `SCUS_971.98` (SHA1: `57dc305d`).
 
-The goal of this project is to better understand the game engine. This repo does not contain any game assets or code from the game's executable; It requires your own copy of the game to build and run.
+The goal of this project is to better understand the game engine. This repo does not contain any game assets or original code from the game's executable; It requires your own copy of the game to build and run.
 
 Documentation of the code can be found at [theonlyzac.github.io/sly1](https://theonlyzac.github.io/sly1). For further reading on the game's internal structures and mechanics, visit the [SlyMods Wiki][wiki-url].
 
 New contributors are welcome and encouraged to make a pull request! If you would like to help but aren't sure where to start, check out [CONTRIBUTING.md](/docs/CONTRIBUTING.md) and feel free to [join our Discord server][discord-url] for guidance.
 
 ## Quickstart
 
-**1. Setup build environment.**
+You can quickly setup the project on Linux (or WSL) using the quickstart script. Follow these three steps get started.
 
-Copy and paste this into your terminal:
+### 1. Clone the repo and run quickstart.sh.
+
+Copy and run the following command. It may ask for your password to install dependencies.
 
 ```bash
 git clone https://github.com/theonlyzac/sly1 && \
 cd sly1 && \
-pip install -U -r requirements.txt && \
-sudo ./scripts/setup_build_environment.sh
+./scripts/quickstart.sh
 ```
 
-**2. Extract your original ELF file.**
-
-Copy the file `SCUS_971.98` from your Sly 1 game disc to the `disc` directory of the project.
+### 2. Extract the executable from your disc.
 
-**3. Build the project.**
+Copy the file `SCUS_971.98` from your Sly 1 game disc to the `disc` directory of the project. It is needed to build.
 
-Run the build script with this command:
+### 3. Build the project.
 
 ```bash
 ./scripts/build.sh
 ```
 
 If it works, you will see this:
 ```
-[XXX/XXX] sha1sum checksum.sha1
+[XXX/XXX] sha1sum config/checksum.sha1
 out/SCUS_971.98: OK
 ```
 

config/readme.md

@@ -0,0 +1,21 @@
+# Splat Config Files
+
+This directory contains config files for splat, the tool we use to split and disassemble the game binary. The config files are used to tell splat how to split the binary and what to name the output files.
+
+## Files in this directory
+- `sly1.yaml` - Main config file for splat. Contains the offsets of each file split in the game binary. Creating new `.c` files involves modifying this file to create a `c` split and then running `python configure.py` to generate the new files.
+- `symbol_addrs.txt` - Contains the addresses of symbols in the game binary. Used by splat to properly reference functions and variables in the game code when splitting the binary.
+- `checksum.sha1` - SHA1 checksum of the original game binary. Used to verify the integrity of the binary after compilation.
+
+## Adding new splits
+To add a new source code file to the project, you must add the split to `sly1.yaml`. Here is an example of some file splits:
+```yaml
+    - [0x1f560, c, P2/brx]
+    - [0x1fe70, asm, P2/ac]
+    #- [0x, asm, P2/act]
+```
+- The first line tells splat to split the binary at offset `0x1f560` and create a new file `P2/brx.c`. It will contain the data from the translation unit starting at `0x1f560` and ending at the next split offset. The `c` tells splat to create a `.c` file in `src/P2/`.
+- The second line tells splat to split that the functions starting from offset `0x1fe70` are in the translation unit `P2/ac`, but not to create a new `.c` file.
+- The third line is commented out and does nothing, because we know the next translation unit is `P2/act`, but we don't yet know the offset of the first function in that TU.
+
+When splat is run, it will create `.s` assembly files for each non-matching functions in each split in the `asm/nonmatchings/` directory.

config/sly1.yaml

@@ -128,7 +128,7 @@ segments:
 
     - [0x529e0, c, P2/difficulty]
     - [0x53438, c, P2/dl]
-    - [0x5380C, asm, dl_padding] # Needed to align dmas
+    - [0x5380C, asm, P2/dl_padding] # Needed to align dmas
     - [0x53810, c, P2/dmas]
     - [0x53E28, asm, P2/dsp]
     #- [0x, asm, P2/dysh]

configure.py

@@ -1,5 +1,6 @@
 """
-Configure the project for building.
+Configures the project for building. Invokes splat to split the binary and
+creates build files for ninja.
 """
 #! /usr/bin/env python3
 import argparse
@@ -200,7 +201,7 @@ def build(
         ninja.build(
             ELF_PATH + ".ok",
             "sha1sum",
-            "checksum.sha1",
+            "config/checksum.sha1",
             implicit=[ELF_PATH],
         )
     else:

disc/readme.md

@@ -0,0 +1,6 @@
+# Disc Files
+
+This directory is intentionally left empty. It is where you should place files you extract from your own copy of the game. The files you will need are:
+- `SCUS_971.98` - The original executable of the game. This file is required to build the project.
+
+Extract your original ELF file and place it in this directory before building the project.

docs/CONTRIBUTING.md

@@ -1,4 +1,6 @@
-# So you want to decompile Sly 1...
+# Contributing Guide
+
+## So you want to decompile Sly 1...
 
 You've come to the right place! We welcome new contributors of all skill levels. Even if you've never tried game hacking, modding, or reverse-engineering, we have a dedicated community of modders and reverse-engineers to help you get started. Feel feel to join our [Discord server](https://discord.gg/2GSXcEzPJA) and ask for help in #sly-research.
 
@@ -12,17 +14,18 @@ By following this guide, you will learn how to fork the repo on GitHub, choose a
 2. [Find a function to match](#find-a-function-to-match)
 3. [Match the function using Decomp.me](#match-the-function-using-decompme)
 4. [Integrate the matched code](#integrate-the-matched-code)
+5. [Make a Pull Request](#make-a-pull-request)
 5. [Conclusion](#conclusion)
 
 
-## Getting Started
+## Getting started
 
-If you haven't used Git before, follow the [Beginner's Guide](/docs/BEGINNERSGUIDE.md) to learn how to fork the repo, make changes, and submit a pull request. If you are already familiar with Git, continue on with this guide.
+If you haven't used Git before, follow the [Beginner's Guide](/docs/BEGINNERSGUIDE.md) to learn how to fork the repo, make changes, and submit a pull request when you're done. If you're already familiar with Git, continue on with this guide.
 
-Start by following the instructions in the [README](/README.md) to build the project. If you see the following in the terminal, you're ready to start contributing:
+First, follow the instructions in the [README](/README.md) to build the project. If you see the following in the terminal, you're ready to start contributing:
 
 ```
-[XXX/XXX] sha1sum checksum.sha1
+[XXX/XXX] sha1sum config/checksum.sha1
 out/SCUS_971.98: OK
 ```
 
@@ -41,14 +44,14 @@ First, find a function in the game that you want to match. There are a few ways
 
 Once you have chosen a function, you can use the website [decomp.me](https://decomp.me/) to match it.
 1. Go the website and click "Start decomping".
-2. Under "Preset", select "Sly Cooper and the Thievius Raccoonus".
+2. Click "PS2", then under "Preset", select "Sly Cooper and the Thievius Raccoonus".
 3. Under "Diff label", enter the name of the function.
 4. Find the `.s` file corresponding to the function you want to match in the `asm/nonmatchings` directory. Copy the contents of the file into the "Target assembly" box.
 5. Copy any functions, global variables, or data types used by the function from the headers in the `include` directory into the "Context" box.
    * E.g. For the function `void ResetClock(struct CLOCK* pclock, float t)`, you will need to include the definition of `CLOCK` struct, and the `TICK` data type since it is used in the CLOCK struct.
    * You should almost always copy the entirety of "types.h" to ensure you have all the necessary primitive types.
 6. Click "Create scratch".
-7. (Optional) Go to the "Options" tab and under "Debug information" select `-g3 (Macro expansions)`. This will show you which line numbers the source code coreespond to each line in the assembly.
+7. **(Recommended)** Go to the "Options" tab and under "Debug information" select `-g3 (Macro expansions)`. This will show you which line numbers the source code correspond to each line in the assembly.
 
 Then start writing your code under the "Source code" tab. It will tell you what percent of the code matches the original. Tweak the code until it matches 100%. An example scratch can be found here: https://decomp.me/scratch/hmmyP
 
@@ -60,12 +63,12 @@ Once the function matches 100%, follow these steps to integrate it into the proj
 1. Replace the `INCLUDE_ASM` macro in the `.c` file with the matched function.
    * If the function is in a new file, **do not create a new file**. Creating new `.c` files is done by editing the `config/sly1.yaml` file to change the file split from `asm` to `c`, then running `python configure.py` to generate the new file. If you don't know how to do this, feel free to ask for help in the Discord server.
 2. Check `config/symbol_addrs.txt` to see if the mangled name of the function is present.
-   * If it is not, add the **mangled name** of the function with it's address. The mangled name of the function can be found by searching the strings in the May 19 prototype elf, if it's the same as the release version. If you don't know how to do this, ask for help in the Discord server; Someone will be able to find it for you easily.
-   * The symbol_addrs.txt file is sorted alphabetically by filename, then by address within the file.
+   * If it is not, add the **mangled name** of the function with it's address. The mangled name of the function can be found in the debug symbols for the May 2002 prototype. If you don't know how to find it, ask for help in the Discord server; someone will be able to find it for you easily.
+   * The symbol_addrs.txt file is grouped alphabetically by filename, then sorted by address within the file.
 
-The project should build and match. Here are some tips for troubleshooting common issues:
-* Undefined reference errors usually mean the entry in the symbol_addrs.txt is wrong. Make sure the function name is mangled in symbol_addrs.txt and normal/un-mangled in the source code, and the mangled version matches the signature of the function. Also ensure that the address is correct in symbol_addrs.txt.
-* Checksum failed means the compiled elf doesn't match the original. If it matches on decomp.me, it might be an issue with the compiler, so open an issue on GitHub or let someone know on Discord.
+The project should build and match. Here are some common troubleshooting tips:
+* `undefined reference error` usually means the entry in the symbol_addrs.txt is wrong. Make sure the function name is mangled in symbol_addrs.txt and unmangled in the source code, and the mangled version matches the signature of the function. Also ensure that the address is correct in symbol_addrs.txt.
+* `checksum failed` means the compiled elf with your added code doesn't match the original. If it matches on decomp.me but not in the project, it might be an issue with the compiler, so open an issue on GitHub or let someone know on Discord.
 
 <!--### CodeMatcher
 
@@ -74,16 +77,15 @@ You can use [CodeMatcher](https://github.com/felinis/CodeMatcher) to help match
 If you are adding new code, it is strongly recommended that you run CodeMatcher before submitting a pull request. We will accept pull requests that don't match as long as the code is clean and readable, but in the future we may require that your code matches before merging it into the main branch.-->
 
 
-## Code Review Process
+## Make a pull request
 
 Once you add your code to the project and it builds + matches, you can open a pull request to merge your fork into the main branch of the project. A code reviewer will need to approve it before it can be merged into the main branch.
 
 We are a volunteer-driven project, so please be patient while we review your code. These are the main things we will look for in your code:
-
 * It compiles without any errors.
 * The compiled elf matches the original elf.
 
-If everything looks good, we will merge your pull request as soon as possible. If anything needs to be fixed, we will let you know.
+If everything looks good, we will merge your pull request as soon as possible. If anything needs to be addressd, we will let you know.
 
 
 ## Conclusion

include/dmas.h

@@ -6,10 +6,10 @@
 #ifndef DMAS_H
 #define DMAS_H
 
+#include <sdk/ee/dma.h>
+#include <sdk/ee/eekernel.h>
 #include "common.h"
 #include <shd.h>
-#include <sce/dma.h>
-#include <sce/kernel.h>
 
 class DMAS
 {

include/lib/libkernl/filestub.h

@@ -0,0 +1,13 @@
+/**
+ * @file include/lib/libkernl/filestub.h
+ * @note src/lib/libkernl/filestub.c
+ */
+#ifndef FILESTUB_H
+#define FILESTUB_H
+
+extern "C"
+{
+    int sceClose(int fd);
+};
+
+#endif // FILESTUB_H

include/sce/memset.h

@@ -5,12 +5,11 @@
  */
 #ifndef MEMSET_H
 #define MEMSET_H
-
-#include "common.h"
+#include <stddef.h>
 
 extern "C"
 {
-    void* memset(void* ptr, s32 value, size_t num);
+    void* memset(void* ptr, int value, size_t num);
 }
 
 #endif // MEMSET_H

include/sce/rand.h

@@ -1,12 +1,14 @@
 /**
  * @file rand.h
+ * @note /sce/ee/gcc/src/newlib/libc/stdlib/rand.c
  *
- * @brief Random number generator.
+ * @brief Random number generation.
  */
 #ifndef RAND_H
 #define RAND_H
 
-#include "common.h"
+typedef unsigned int undefined4;
+typedef unsigned int u_int;
 
 extern "C"
 {
@@ -33,18 +35,18 @@ extern "C"
         undefined4 field19_0x4c;
         undefined4 field20_0x50;
         undefined4 field21_0x54;
-        uint next;
+        u_int next;
     };
 
     /**
      * @brief Seed the random number generator.
      */
-    void srand(uint seed);
+    void srand(u_int seed);
 
     /**
      * @brief Generate a random number.
      */
-    uint rand();
+    u_int rand();
 
     extern struct RNG g_rng;
     extern struct RNG *g_prng;