diff --git a/.gitignore b/.gitignore index a9d37c56..38b83874 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ -target +book/book +target/ Cargo.lock diff --git a/book.toml b/book.toml new file mode 100644 index 00000000..59b6e699 --- /dev/null +++ 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 new file mode 100644 index 00000000..11742d09 --- /dev/null +++ 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 new file mode 100644 index 00000000..4b968a5c --- /dev/null +++ b/book/src/complex_3d.md @@ -0,0 +1 @@ +# Complex 3D Shapes diff --git a/book/src/debug.md b/book/src/debug.md new file mode 100644 index 00000000..1e584c95 --- /dev/null +++ b/book/src/debug.md @@ -0,0 +1 @@ +# Debugging diff --git a/book/src/debug/emulator.md b/book/src/debug/emulator.md new file mode 100644 index 00000000..a9d577f8 --- /dev/null +++ b/book/src/debug/emulator.md @@ -0,0 +1 @@ +# Emulator diff --git a/book/src/debug/hardware.md b/book/src/debug/hardware.md new file mode 100644 index 00000000..7bdab3dc --- /dev/null +++ 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 ` where `` 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/` + +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 new file mode 100644 index 00000000..d3020113 --- /dev/null +++ b/book/src/final_project.md @@ -0,0 +1 @@ +# Final Project diff --git a/book/src/framebuffer.md b/book/src/framebuffer.md new file mode 100644 index 00000000..5eb5b5e6 --- /dev/null +++ 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 new file mode 100644 index 00000000..c82a1669 --- /dev/null +++ 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 new file mode 100644 index 00000000..6c2b8b3b --- /dev/null +++ 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 new file mode 100644 index 00000000..4ba44132 --- /dev/null +++ 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 new file mode 100644 index 00000000..4698a320 --- /dev/null +++ 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 new file mode 100644 index 00000000..1d69ee51 --- /dev/null +++ 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 new file mode 100644 index 00000000..29658341 --- /dev/null +++ b/book/src/hello_world.md @@ -0,0 +1 @@ +# Hello World diff --git a/book/src/input.md b/book/src/input.md new file mode 100644 index 00000000..135b6af3 --- /dev/null +++ b/book/src/input.md @@ -0,0 +1 @@ +# Input diff --git a/book/src/input/hello.md b/book/src/input/hello.md new file mode 100644 index 00000000..91f91c1d --- /dev/null +++ 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 new file mode 100644 index 00000000..3db98fce --- /dev/null +++ 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 new file mode 100644 index 00000000..e10b99d0 --- /dev/null +++ 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 new file mode 100644 index 00000000..7daa23f4 --- /dev/null +++ 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 new file mode 100644 index 00000000..0baf830e --- /dev/null +++ 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 new file mode 100644 index 00000000..048579a4 --- /dev/null +++ b/book/src/networking.md @@ -0,0 +1 @@ +# Networking diff --git a/book/src/next_steps.md b/book/src/next_steps.md new file mode 100644 index 00000000..188c9c76 --- /dev/null +++ b/book/src/next_steps.md @@ -0,0 +1 @@ +# Next Steps diff --git a/book/src/scegu.md b/book/src/scegu.md new file mode 100644 index 00000000..5d64215c --- /dev/null +++ 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 new file mode 100644 index 00000000..6041d914 --- /dev/null +++ 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 new file mode 100644 index 00000000..98bb99dd --- /dev/null +++ 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 new file mode 100644 index 00000000..feae8cb5 --- /dev/null +++ b/book/src/setup.md @@ -0,0 +1 @@ +# Setup diff --git a/book/src/setup/install.md b/book/src/setup/install.md new file mode 100644 index 00000000..f556506e --- /dev/null +++ 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 new file mode 100644 index 00000000..6b09417b --- /dev/null +++ b/book/src/sound.md @@ -0,0 +1 @@ +# Integrating Sound diff --git a/book/src/stdio.md b/book/src/stdio.md new file mode 100644 index 00000000..905be74a --- /dev/null +++ b/book/src/stdio.md @@ -0,0 +1 @@ +# Logging with stdio diff --git a/book/src/triangle.md b/book/src/triangle.md new file mode 100644 index 00000000..2d12d963 --- /dev/null +++ b/book/src/triangle.md @@ -0,0 +1 @@ +# Rendering a Triangle diff --git a/book/src/vfpu.md b/book/src/vfpu.md new file mode 100644 index 00000000..a33a08e7 --- /dev/null +++ b/book/src/vfpu.md @@ -0,0 +1 @@ +# VFPU assembly diff --git a/book/src/welcome.md b/book/src/welcome.md new file mode 100644 index 00000000..f82f58ec --- /dev/null +++ b/book/src/welcome.md @@ -0,0 +1 @@ +# Welcome