Merge pull request #46 from spicyjpeg/psxmdec

Critical ldscript fixes, initial MDEC support and CI updates

4 files changed, 107 insertions, 71 deletions

diff --git a/doc/cmake_reference.md b/doc/cmake_reference.md
index 3c89da3..25a89ec 100644
--- a/doc/cmake_reference.md
+++ b/doc/cmake_reference.md
@@ -4,17 +4,17 @@
 ## Setup
 
 The only requirement to use the SDK in CMake is to set the
-`CMAKE_TOOLCHAIN_FILE` variable to `INSTALL_PATH/lib/libpsn00b/cmake/sdk.cmake`
-(where `INSTALL_PATH` is the install prefix PSn00bSDK is installed to). This
-can be done on the command line (`-DCMAKE_TOOLCHAIN_FILE=...`), in
-`CMakeLists.txt` (before calling `project()`) or using a
-[preset](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html).
+`CMAKE_TOOLCHAIN_FILE` variable to the absolute path to
+`lib/libpsn00b/cmake/sdk.cmake` within the PSn00bSDK installation directory.
+This can be done on the command line (`-DCMAKE_TOOLCHAIN_FILE=...`), in
+`CMakeLists.txt` (`set(CMAKE_TOOLCHAIN_FILE ...)` before `project()`) or using
+[presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html).
 
 It's suggested to have a default preset that sets `CMAKE_TOOLCHAIN_FILE` to
-`$env{PSN00BSDK_LIBS}/cmake/sdk.cmake`, so the `PSN00BSDK_LIBS` environment
-variable (used by former PSn00bSDK versions) is respected. Such a preset can be
-created by placing a `CMakePresets.json` file in the project's root with the
-following contents:
+`$env{PSN00BSDK_LIBS}/cmake/sdk.cmake`, taking advantage of the
+`PSN00BSDK_LIBS` environment variable (used by former PSn00bSDK versions) to
+automatically find the SDK. Such a preset can be created by placing a
+`CMakePresets.json` file in the project's root with the following contents:
 
 ```json
 {
@@ -102,13 +102,14 @@ of these names.
   As with executables, the `.dll` extension can be customized by setting
   `PSN00BSDK_SHARED_LIBRARY_SUFFIX`.
 
-- `psn00bsdk_add_cd_image(<name> <image name> <config file> [...])`
+- `psn00bsdk_add_cd_image(<name> <image name> <config file> [DEPENDS ...] [...])`
 
   Creates a new target that will build a CD image using `mkpsxiso`.
 
   The first argument is the name of the target to create; next up is the name
   of the generated image file (`<image name>.bin` + `<image name>.cue`). The
-  third argument is the path to the XML file passed to `mkpsxiso`.
+  third argument is the path to the XML file (relative to the source directory)
+  passed to `mkpsxiso`.
 
   The XML file is "configured" by CMake, i.e. any `${var}` or `@var@`
   expressions are replaced with the values of the respective variables. In
@@ -126,7 +127,42 @@ of these names.
 
   Any additional argument is passed through to the underlying call to
   `add_custom_target()`, so most of the options supported by
-  `add_custom_target()` are also supported here.
+  `add_custom_target()` (including `DEPENDS`) are also supported here.
+
+- `psn00bsdk_target_incbin(<target> <PRIVATE|PUBLIC|INTERFACE> <symbol name> <binary file>)`
+
+  Embeds the contents of a binary file into an executable or a library.
+
+  A new symbol/object will be created with the given name, escaped by replacing
+  non-alphanumeric characters with underscores. The contents of the file will
+  be aligned to 4 bytes and placed in the `.data` section. An unsigned 32-bit
+  integer named `<symbol name>_size` will also be defined and set to the length
+  of the file in bytes (without taking alignment/padding into account).
+
+  Once added the file and its size can be accessed by C/C++ code by declaring
+  the respective symbols as an extern array and as an integer, like this:
+
+  ```c
+  extern const uint8_t my_file[];
+  extern const size_t  my_file_size;
+  ```
+
+  The fourth argument specifies the path to the binary file relative to the
+  source directory. This path can be prepended with `${PROJECT_BINARY_DIR}/` to
+  reference a file generated by the build script (such as an LZP archive): in
+  that case a file-level dependency will also be created, ensuring CMake does
+  not attempt to compile the executable or library before the file is built.
+
+  **IMPORTANT**: in order for this command to work, assembly language support
+  must be enabled by specifying `LANGUAGES C ASM` (or `LANGUAGES C CXX ASM` if
+  C++ is also used) when invoking `project()`.
+
+- `psn00bsdk_target_incbin_a(<target> <PRIVATE|PUBLIC|INTERFACE> <symbol name> <size symbol name> <binary file> <alignment>)`
+
+  Advanced variant of `psn00bsdk_target_incbin()` that allows specifying a
+  custom name for the size symbol and changing the default alignment setting.
+  Note that the size integer is always aligned to a multiple of 4 bytes as the
+  MIPS architecture doesn't support unaligned reads.
 
 ## Definitions
 
@@ -233,4 +269,4 @@ the build script.
   LZP archives as part of the build pipeline.
 
 -----------------------------------------
-_Last updated on 2021-12-29 by spicyjpeg_
+_Last updated on 2022-02-26 by spicyjpeg_
diff --git a/doc/dev_notes.md b/doc/dev_notes.md
index 3aa2304..a96d6ef 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,9 +162,26 @@ _- 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.
+  exported to generated dummy projects. Additionally you may need to set
+  `CMAKE_TRY_COMPILE_TARGET_TYPE` to `STATIC_LIBRARY` to prevent CMake from
+  invoking the linker.
+
+- When `project()` is called, CMake uses the value of `CMAKE_SYSTEM_NAME` to
+  determine default values for several variables and properties. Most of these
+  defaults are undocumented: e.g. setting the system name to `Generic` (as
+  suggested by the docs for bare metal targets) will result in CMake assuming
+  that the target platform does not support dynamic linking, so you'll have to
+  turn it back on by setting the `TARGET_SUPPORTS_SHARED_LIBS` global property
+  *after* invoking `project()`.
+
+- It is not possible to use custom toolchains (through toolchain files or by
+  setting `CMAKE_*_COMPILER` manually) with any of the Xcode or VS generators,
+  as their respective build systems handle compiler selection internally rather
+  than relying on variables passed by CMake. Ninja or `make` is thus always
+  required to build PSn00bSDK and any projects made with it, even if the
+  host-side tools are built using Xcode or MSVC.
 
 - There is no way to use multiple toolchains (PS1 + host) in a single project,
   even if you use `add_subdirectory()` to execute multiple project files
@@ -220,20 +237,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 +280,4 @@ _- spicyjpeg_
   space.
 
 -----------------------------------------
-_Last updated on 2021-11-28 by spicyjpeg_
+_Last updated on 2022-02-06 by spicyjpeg_
diff --git a/doc/installation.md b/doc/installation.md
index 1646653..2d058ab 100644
--- a/doc/installation.md
+++ b/doc/installation.md
@@ -1,6 +1,12 @@
 
 # Getting started with PSn00bSDK
 
+**IMPORTANT**: due to a bug in `libflac` (used by `mkpsxiso`), building using
+MinGW on Windows currently requires `-DMKPSXISO_NO_LIBFLAC=ON` to be passed to
+CMake when configuring PSn00bSDK. This will result in the `dumpsxiso` utility
+being built without support for ripping CD audio tracks to FLAC, however the
+`mkpsxiso` command will still retain FLAC support.
+
 ## Building and installing
 
 The instructions below are for Windows and Linux. Building on macOS hasn't been
@@ -79,8 +85,8 @@ and installed properly.
 
    **NOTE**: Ninja is used by default to build the SDK. If you can't get it to
    work or don't have it installed, pass `-G "Unix Makefiles"` (or
-   `-G "MSYS Makefiles"` on Windows) to the first command to build using `make`
-   instead.
+   `-G "MinGW Makefiles"` on Windows) to the first command to build using
+   `make` instead.
 
 6. Install the SDK to the path you chose (add `sudo` or run it from a command
    prompt with admin privileges if necessary):
@@ -150,4 +156,4 @@ The toolchain script defines a few CMake macros to create PS1 executables, DLLs
 and CD images. See the [reference](cmake_reference.md) for details.
 
 -----------------------------------------
-_Last updated on 2021-12-29 by spicyjpeg_
+_Last updated on 2022-02-06 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_