overdrivenpotato · sajattack · Dec 30, 2023 · Dec 30, 2023 · Dec 30, 2023 · Dec 30, 2023
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,3 @@
-target
+book/book
+target/
 Cargo.lock
diff --git a/book.toml b/book.toml
@@ -0,0 +1,6 @@
+[book]
+authors = ["Marko Mijalkovic", "Paul Sajna"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Rust-PSP Book"
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -0,0 +1,34 @@
+# Summary
+
+[Welcome](welcome.md)
+
+- [Introduction](intro.md)
+  - [What is Rust-PSP and its significance in PSP development?](intro/what_is.md)
+  - [Hardware Overview](intro/hw_overview.md)
+- [Setup](setup.md)
+  - [Installing Rust and Rust-PSP tools](setup/install.md)
+- [Hello World](hello_world.md)
+  - [Understanding project structure](hello/structure.md)
+  - [Writing your first Rust-PSP application](hello/writing_hello_world.md)
+- [Debugging](debug.md)
+  - [Emulator](debug/emulator.md)
+  - [Hardware](debug/hardware.md)
+- [Logging with stdio](stdio.md)
+- [Input](input.md)
+  - [Introduction to controls and input handling](input/intro.md)
+  - [Modifying your Hello World to respond to button presses](input/hello.md)
+- [Framebuffer](framebuffer.md)
+  - [Introduction to the PSP's framebuffer](framebuffer/intro.md)
+  - [Raw framebuffer writes from code](framebuffer/raw.md)
+  - [Embedded Graphics](framebuffer/emb-g.md)
+- [Introduction to Hardware-Accelerated graphics with sceGu](scegu.md)
+  - [Understanding sceGu and it's role in PSP graphics](scegu/understanding.md)
+  - [Setting up sceGu and understanding the basics of PSP graphics](scegu/setup.md)
+- [Rendering a Triangle](triangle.md)
+- [Complex 3D Shapes](complex_3d.md)
+- [Integrating Sound](sound.md)
+- [VFPU assembly](vfpu.md)
+- [Networking](networking.md)
+- [Final Project](final_project.md)
+- [Next Steps](next_steps.md)
+
diff --git a/book/src/complex_3d.md b/book/src/complex_3d.md
@@ -0,0 +1 @@
+# Complex 3D Shapes
diff --git a/book/src/debug.md b/book/src/debug.md
@@ -0,0 +1 @@
+# Debugging
diff --git a/book/src/debug/emulator.md b/book/src/debug/emulator.md
@@ -0,0 +1 @@
+# Emulator
diff --git a/book/src/debug/hardware.md b/book/src/debug/hardware.md
@@ -0,0 +1,111 @@
+# Debugging Rust-PSP on real PSP Hardware
+This section will teach you how to debug Rust-PSP programs on a real PSP over USB.
+
+## Dependencies
+You will need several dependencies from the [C pspsdk](https://github.com/pspdev/pspdev/)
+
+Specifically you will need:
+- usbhostfs_pc
+- psplinkusb
+- psp-gdb
+- pspsh
+
+Start by installing the C pspsdk and making these tools available on your `$PATH`.
+There are release builds available in the github releases tab, or you can run the
+build scripts, but compiling everything from scratch can be quite time consuming.
+
+There is also a part of the setup required on a PSP running CFW. Ensure you have
+a PSP running a recent custom firmware, then extract and install the psplink EBOOT
+from the psplink.zip available [here](https://github.com/pspdev/psplinkusb/releases/tag/latest) to your memory card. 
+
+## Compiling your project with debug symbols
+In order to debug our program, we need the compiler to output information that the
+debugger will use to identify our functions and variables by name. 
+These are available in the non-release build profile, which you can build by running
+`cargo psp` without `--release`, or if you want standard speed optimizations 
+and debug symbols you can add the following to Cargo.toml and build with `--release`
+```
+[profile.release]
+debug = true
+```
+
+## Setting up PSPLink
+`usbhostfs_pc` exposes part of your host filesystem to the PSP over USB.
+Run `usbhostfs_pc <path>` where `<path>` is your `target` directory
+or somewhere above it in your folder hierarchy. Basically you will need the `target`
+directory build outputs to be accessible from the path chosen. 
+
+To follow along using the hello world from the previous chapter, ensure you've
+built it with debug symbols, then run 
+
+`usbhostfs_pc hello-world/target/mipsel-sony-psp/<release or debug>`
+
+Now you're ready to plug in your PSP to your PC with a mini-USB cable and launch the
+PSPLink EBOOT. It should appear under your memory stick games.
+
+Back on the PC, launch `pspsh` in a separate terminal from `usbhostfs_pc`.
+This will launch the "psp shell" which is what you will use to communicate with the PSP
+over usb. You can read about all the things you can do with this in the [psplink
+manual](https://github.com/pspdev/psplinkusb/blob/master/psplink_manual.pdf), but for now
+all we need is the debug command to start the psplink gdb server.
+
+## Debugging with PSP-GDB
+In pspsh, run 
+
+`debug ./psp-hello-world-example.prx`.
+
+Now you'll need yet another terminal (hope you have lots of screen real estate 😉),
+to run psp-gdb. Run it with the path to the ELF file with debug symbols, like so:
+
+`psp-gdb --tui ./psp-hello-world-example`
+
+Now connect psp-gdb to the GDB server with 
+
+`target remote :10001`
+
+Start by setting a breakpoint in our main function. 
+
+`break psp_main`
+
+Continue the flow of execution past all the init code to our main function.
+
+`continue`
+
+Step into the main function
+
+`step`
+
+Step into the `psp::enable_home_button` function call
+
+`step`
+
+Step over the next two calls to avoid going into their internals
+
+`next`
+
+`next`
+
+Print the value of the `id` variable in the `enable_home_button` function
+
+`print id`
+
+Exit the `enable_home_button` function
+
+`finish`
+
+Get a stack trace of the function hierarchy
+
+`backtrace`
+
+Continue running the program
+
+`continue`
+
+These are the main commands you'll use to navigate and examine variables in GDB. 
+Refer to [upstream documentation](https://ftp.gnu.org/old-gnu/Manuals/gdb/html_node/gdb_11.html#SEC12) for more details. 
+Most of these have shortforms as well such as `b` for breakpoints,
+and you can press enter to repeat the last command without typing it again.
+
+# Additional Resources
+There are tools that integrate with GDB such as [seer](https://github.com/epasveer/seer)
+and vscode's debug tools to provide a more friendly UI, which are not covered here.
diff --git a/book/src/final_project.md b/book/src/final_project.md
@@ -0,0 +1 @@
+# Final Project
diff --git a/book/src/framebuffer.md b/book/src/framebuffer.md
@@ -0,0 +1 @@
+# Framebuffer
diff --git a/book/src/framebuffer/emb-g.md b/book/src/framebuffer/emb-g.md
@@ -0,0 +1 @@
+# Embedded Graphics
diff --git a/book/src/framebuffer/intro.md b/book/src/framebuffer/intro.md
@@ -0,0 +1 @@
+# Introduction to the PSP's framebuffer
diff --git a/book/src/framebuffer/raw.md b/book/src/framebuffer/raw.md
@@ -0,0 +1 @@
+# Raw framebuffer writes from code
diff --git a/book/src/hello/structure.md b/book/src/hello/structure.md
@@ -0,0 +1 @@
+# Understanding project structure
diff --git a/book/src/hello/writing_hello_world.md b/book/src/hello/writing_hello_world.md
@@ -0,0 +1 @@
+# Writing your first Rust-PSP application
diff --git a/book/src/hello_world.md b/book/src/hello_world.md
@@ -0,0 +1 @@
+# Hello World
diff --git a/book/src/input.md b/book/src/input.md
@@ -0,0 +1 @@
+# Input
diff --git a/book/src/input/hello.md b/book/src/input/hello.md
@@ -0,0 +1 @@
+# Modifying your Hello World to respond to button presses
diff --git a/book/src/input/intro.md b/book/src/input/intro.md
@@ -0,0 +1 @@
+# Introduction to controls and input handling
diff --git a/book/src/intro.md b/book/src/intro.md
@@ -0,0 +1 @@
+# Introduction
diff --git a/book/src/intro/hw_overview.md b/book/src/intro/hw_overview.md
@@ -0,0 +1 @@
+# Hardware Overview
diff --git a/book/src/intro/what_is.md b/book/src/intro/what_is.md
@@ -0,0 +1 @@
+# What is Rust-PSP and its significance in PSP development?
diff --git a/book/src/networking.md b/book/src/networking.md
@@ -0,0 +1 @@
+# Networking
diff --git a/book/src/next_steps.md b/book/src/next_steps.md
@@ -0,0 +1 @@
+# Next Steps
diff --git a/book/src/scegu.md b/book/src/scegu.md
@@ -0,0 +1 @@
+# Introduction to Hardware-Accelerated graphics with sceGu
diff --git a/book/src/scegu/setup.md b/book/src/scegu/setup.md
@@ -0,0 +1 @@
+# Setting up sceGu and understanding the basics of PSP graphics
diff --git a/book/src/scegu/understanding.md b/book/src/scegu/understanding.md
@@ -0,0 +1 @@
+# Understanding sceGu and it's role in PSP graphics
diff --git a/book/src/setup.md b/book/src/setup.md
@@ -0,0 +1 @@
+# Setup
diff --git a/book/src/setup/install.md b/book/src/setup/install.md
@@ -0,0 +1,42 @@
+# Installing Rust and Rust-PSP tools
+
+Follow the directions on [https://rustup.rs/](https://rustup.rs) to install Rust for the operating system of your choice. 
+Note, Windows users will need to install Microsoft Visual Studio Build tools as a prerequisite.
+
+To confirm you have rust installed correctly, run the following commands:
+```sh
+cargo new --bin hello
+cd hello
+cargo run --release
+```
+Your output should look something like this:
+```
+[paul@P50-Arch hello]$ cargo run --release
+   Compiling hello v0.1.0 (/tmp/hello)
+    Finished release [optimized] target(s) in 0.23s
+     Running `target/release/hello`
+Hello, world!
+```
+
+Next we need to add some special components to our rust installation that rust-psp needs.
+
+Firstly we need the nightly compiler, because there are special unstable features
+needed by rust-psp that aren't available in stable rust.
+
+```sh
+rustup default nightly
+```
+
+Refer to the [rust-psp README](https://github.com/overdrivenpotato/rust-psp/blob/master/README.md#dependencies)
+for the current minimum rust version needed to use rust-psp. 
+Compare to what you have installed by running `rustc --version`.
+
+Next we need the source code for the rust compiler.
+```sh
+rustup component add rust-src
+```
+
+Finally, we're ready to install the rust-psp tools
+```sh
+cargo install cargo-psp
+```
diff --git a/book/src/sound.md b/book/src/sound.md
@@ -0,0 +1 @@
+# Integrating Sound
diff --git a/book/src/stdio.md b/book/src/stdio.md
@@ -0,0 +1 @@
+# Logging with stdio
diff --git a/book/src/triangle.md b/book/src/triangle.md
@@ -0,0 +1 @@
+# Rendering a Triangle
diff --git a/book/src/vfpu.md b/book/src/vfpu.md
@@ -0,0 +1 @@
+# VFPU assembly
diff --git a/book/src/welcome.md b/book/src/welcome.md
@@ -0,0 +1 @@
+# Welcome