Switch back to mkpsxiso master branch, update docs

5 files changed, 42 insertions, 61 deletions

diff --git a/.gitmodules b/.gitmodules
index 734dafd..ca834d1 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -3,5 +3,4 @@
 	url = https://github.com/leethomason/tinyxml2
 [submodule "tools/mkpsxiso"]
 	path = tools/mkpsxiso
-	url = https://github.com/spicyjpeg/mkpsxiso
-	branch = cmake
+	url = https://github.com/Lameguy64/mkpsxiso
diff --git a/doc/dev_notes.md b/doc/dev_notes.md
index 3aa2304..4873a59 100644
--- a/doc/dev_notes.md
+++ b/doc/dev_notes.md
@@ -14,20 +14,20 @@ _- spicyjpeg_
 
 ## MIPS ABI / compiler
 
-- When calling C functions (ie. BIOS functions) from assembly code you'll need
-  to allocate N words on the stack first when calling a function that has N
-  arguments (`addiu $sp, -(4*N)` where N = number of arguments of the function
-  being called) even if the arguments are on registers `a0` to `a3` and the C
-  functions don't always use the space allotted in stack. When calling a
-  function with a variable number of arguments (`printf`) always allocate 16
-  bytes of stack.
+- When calling C functions (including BIOS functions) from assembly code you'll
+  need to allocate one 32-bit word on the stack for each argument the function
+  takes (`addiu $sp, -(4*N)` where `N` = number of arguments of the function
+  being called), *even if the function takes its arguments from registers*
+  *`$a0`-`$a3` rather than from the stack*. When calling a variadic function
+  (i.e. one with a variable number of arguments, such as `printf`) always
+  allocate 16 bytes of stack.
 
 - For some reason `mipsel-unknown-elf-nm` and `mipsel-none-elf-nm` (symbol map
   generators) insist on outputting 64-bit addresses (with the top 32 bits set,
-  e.g. `FFFFFFFF80010000`) even when feeding it a regular 32-bit MIPS
-  executable, while the standard x86 nm tool that ships with most GCC packages
-  prints the proper 32-bit address. Unclear whether this is a bug, intended
-  behavior or the result of some ancient ELF ABI flag crap.
+  e.g. `FFFFFFFF80010000`) even when feeding them a regular 32-bit MIPS
+  executable, while the standard (x86) `nm` tool that ships with most GCC
+  packages prints the proper 32-bit address. Unclear whether this is a bug,
+  intended behavior or the result of some ancient ELF ABI flag crap.
   `DL_ParseSymbolMap()` will ignore the top 32 bits, so this should only bother
   you if you're implementing your own symbol map parser.
 
@@ -162,7 +162,7 @@ _- spicyjpeg_
   multiple times) and uses the same variable values as the main project,
   however CMake will *not* pass custom variables through by default. If your
   toolchain script has options that can be set via custom variables (like
-  `PSN00BSDK_TC` and `PSN00BSDK_PREFIX` in PSn00bSDK), you'll have to set
+  `PSN00BSDK_TC` and `PSN00BSDK_TARGET` in PSn00bSDK), you'll have to set
   `CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` to a list of variable names to be
   exported to generated dummy projects.
 
@@ -220,20 +220,6 @@ _- spicyjpeg_
   endforeach()
   ```
 
-- Depending on how you find external dependencies (`find_package()`, vcpkg,
-  pkg-config...), CMake may end up outputting an executable that relies on a
-  DLL installed system-wide. To correctly install the DLL alongside the
-  executable you have to specify a regex as follows:
-
-  ```cmake
-  install(
-    TARGETS my_executable
-    RUNTIME_DEPENDENCIES
-    PRE_EXCLUDE_REGEXES ".*"
-    PRE_INCLUDE_REGEXES "tinyxml2"
-  )
-  ```
-
   CMake will scan the executable at install time and copy all the required DLLs
   that match the second regex. If no regex is specified CMake will also copy OS
   DLLs like `libc` or `msvcrt`, which usually isn't the desired behavior.
@@ -277,4 +263,4 @@ _- spicyjpeg_
   space.
 
 -----------------------------------------
-_Last updated on 2021-11-28 by spicyjpeg_
+_Last updated on 2022-01-30 by spicyjpeg_
diff --git a/doc/known_bugs.md b/doc/known_bugs.md
index 2af9e3f..e39da43 100644
--- a/doc/known_bugs.md
+++ b/doc/known_bugs.md
@@ -4,8 +4,24 @@
 This is an incomplete list of things that are currently broken (or not behaving
 as they should, or untested on real hardware) and haven't yet been fixed.
 
+## Toolchain
+
+- It is currently not possible to link static libraries (including the SDK
+  libraries themselves) with DLLs, since the build scripts currently assume that
+  static library object files are always going to be linked into executables.
+  This can be worked around by linking all static libraries as part of the main
+  executable rather than the DLLs: the dynamic linker will automatically search
+  the executable for undefined symbols used by a DLL and patch the code to use
+  them. It might be necessary to list such symbols in a dummy array to prevent
+  the compiler from stripping them away from the executable.
+
 ## Libraries
 
+`psxgpu`:
+
+- In some *very rare* cases, `VSync()` seems to crash the system by performing
+  unaligned accesses for unknown reasons.
+
 `psxspu`:
 
 - Calls to `SpuSetTransferMode()` are ignored. SPU transfers are always
@@ -19,34 +35,9 @@ as they should, or untested on real hardware) and haven't yet been fixed.
   used by loading DLL binaries into RAM manually and calling `DL_CreateDLL()`
   on them (see the `system/dynlink` example).
 
-## Tools
-
-- The `mkpsxiso` submodule is temporarily set to point to a fork of `mkpsxiso`
-  with bugfixed CMake scripts (the main repo is broken to the point it fails to
-  build). There is [another fork](https://github.com/CookiePLMonster/mkpsxiso)
-  which is currently work-in-progress and includes more fixes as well as a tool
-  to dump existing CD images: PSn00bSDK will switch back to the main `mkpsxiso`
-  repo once the changes get upstreamed.
-
 ## Examples
 
-- `cdrom/cdxa` and `sound/spustream` demonstrate how to stream an audio file
-  from CD-ROM. Such a file isn't provided however, as PSn00bSDK does not yet
-  come with the tooling required for transcoding audio from a source file. In
-  order to run these examples you'll have to provide your own audio files,
-  convert them and build the CD image manually.
-
-- `demos/n00bdemo` suffers from flickering on real hardware, especially when
-  masking/stencil buffering is used.
-
-- `graphics/render2tex` gets stuck after initialization on real hardware.
-
-- `io/pads` seems to work on real hardware, but fails to automatically enable
-  analog mode on DualShock controllers. This example needs more testing with
-  official and unofficial controllers.
-
-- `io/system573` hasn't been tested on a real Konami System 573. It runs on
-  MAME, however MAME's System 573 emulation is *very* inaccurate.
+See [README.md in the examples directory](../examples/README.md#examples-summary).
 
 -----------------------------------------
-_Last updated on 2021-12-30 by spicyjpeg_
+_Last updated on 2022-02-03 by spicyjpeg_
diff --git a/examples/README.md b/examples/README.md
index dfea465..60ccd21 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -12,7 +12,7 @@ Additional information may be found in the source code of each example.
 | [`beginner/hello`](./beginner/hello)           | The obligatory "Hello World" example program          | EXE  |       |
 | [`cdrom/cdbrowse`](./cdrom/cdbrowse)           | File browser using libpsxcd's directory functions     | CD   |       |
 | [`cdrom/cdxa`](./cdrom/cdxa)                   | CD-XA ADPCM audio player                              | CD   |   1   |
-| [`demos/n00bdemo`](./demos/n00bdemo)           | The premiere demonstration program of PSn00bSDK       | EXE  |       |
+| [`demos/n00bdemo`](./demos/n00bdemo)           | The premiere demonstration program of PSn00bSDK       | EXE  |   2   |
 | [`graphics/balls`](./graphics/balls)           | Draws colored balls bouncing around the screen        | EXE  |       |
 | [`graphics/billboard`](./graphics/billboard)   | Demonstrates how to draw 2D sprites in a 3D space     | EXE  |       |
 | [`graphics/fpscam`](./graphics/fpscam)         | First-person perspective camera with look-at          | EXE  |       |
@@ -21,9 +21,9 @@ Additional information may be found in the source code of each example.
 | [`graphics/render2tex`](./graphics/render2tex) | Procedural texture effects using off-screen drawing   | EXE  |       |
 | [`graphics/rgb24`](./graphics/rgb24)           | Displays a 640x480 24-bit RGB image                   | EXE  |       |
 | [`graphics/tilesasm`](./graphics/tilesasm)     | Drawing a tile-map with assembly language             | EXE  |       |
-| [`io/pads`](./io/pads)                         | Demonstrates reading controllers via low-level access | EXE  |       |
+| [`io/pads`](./io/pads)                         | Demonstrates reading controllers via low-level access | EXE  |   3   |
 | [`io/system573`](./io/system573)               | Konami System 573 (PS1-based arcade board) example    | CD   |       |
-| [`lowlevel/cartrom`](./lowlevel/cartrom)       | ROM firmware for cheat devices written using GNU GAS  | ROM  |   2   |
+| [`lowlevel/cartrom`](./lowlevel/cartrom)       | ROM firmware for cheat devices written using GNU GAS  | ROM  |   4   |
 | [`sound/spustream`](./sound/spustream)         | Custom (non XA) CD-ROM audio streaming using the SPU  | CD   |   1   |
 | [`sound/vagsample`](./sound/vagsample)         | Demonstrates playing VAG sound files with the SPU     | EXE  |       |
 | [`system/childexec`](./system/childexec)       | Loading a child program and returning to parent       | EXE  |       |
@@ -38,7 +38,12 @@ Notes:
    order to run these examples you'll have to provide your own files (and, in
    the case of `spustream`, convert them using the included Python script) and
    build the CD image manually.
-2. The `lowlevel/cartrom` example is outdated and does not use SDK libraries.
+2. `demos/n00bdemo` suffers from flickering on real hardware, especially when
+   masking/stencil buffering is used.
+3. `io/pads` seems to work on real hardware, but fails to automatically enable
+   analog mode on DualShock controllers. This example needs more testing with
+   official and unofficial controllers.
+4. The `lowlevel/cartrom` example is outdated and does not use SDK libraries.
    It is kept for reference purposes only.
 
 ## Building the examples
@@ -79,4 +84,4 @@ are for rebuilding the examples *after* the SDK has been installed.
    CD images for each example.
 
 -----------------------------------------
-_Last updated on 2022-01-17 by spicyjpeg_
+_Last updated on 2022-01-21 by spicyjpeg_
diff --git a/tools/mkpsxiso b/tools/mkpsxiso
-Subproject fe14e95d07a0da5727a8c2fb3ff2aaa892e465c
+Subproject 75b3da9701dc57e0f23a8c7414237198285ef6c