Add CdUnlock() and DMA priority API

2 files changed, 78 insertions, 20 deletions

diff --git a/libpsn00b/include/psxcd.h b/libpsn00b/include/psxcd.h
index 503bc83..78c90db 100644
--- a/libpsn00b/include/psxcd.h
+++ b/libpsn00b/include/psxcd.h
@@ -811,6 +811,48 @@ int CdMode(void);
 int CdStatus(void);
 
 /**
+ * @brief Returns the CD-ROM controller's region code.
+ *
+ * @details Reads region information from the drive using a CdlTest command.
+ * This can be used to reliably determine the system's region without having to
+ * resort to workarounds like probing the BIOS ROM.
+ *
+ * This function may return incorrect results and trigger error callbacks on
+ * emulators or consoles equipped with CD-ROM drive emulation devices such as
+ * the PSIO. It is not affected by modchips.
+ *
+ * @return Region code or 0 if the region cannot be determined
+ */
+CdlRegionCode CdGetRegion(void);
+
+/**
+ * @brief Attempts to disable the CD-ROM controller's region check.
+ *
+ * @details Sends undocumented commands to the drive in an attempt to disable
+ * the region string check, in order to allow reading data from non-PS1 discs
+ * as well as CD-Rs without needing a modchip. As unlocking commands are region
+ * specific, the drive's region must be obtained beforehand using CdGetRegion()
+ * and passed to this function. The unlock persists even if the lid is opened,
+ * but not if a CdlReset command is issued.
+ *
+ * Unlocking is only supported on US, European and Net Yaroze consoles (not on
+ * Japanese models, devkits and most emulators). This function will return 1
+ * without doing anything if CdlRegionDebug is passed as region, as debug
+ * consoles can already read unlicensed discs.
+ *
+ * NOTE: if any callbacks were set using CdReadyCallback() or CdSyncCallback()
+ * prior to calling CdUnlock(), they will be called with an error code as part
+ * of the unlocking sequence, even if the unlock was successful. It is thus
+ * recommended to call this function before setting any callbacks.
+ *
+ * @param region
+ * @return 1 if the drive was successfully unlocked, 0 otherwise
+ *
+ * @see CdGetRegion()
+ */
+int CdUnlock(CdlRegionCode region);
+
+/**
  * @brief Retrieves the disc's table of contents.
  *
  * @details Retrieves the track entries from a CD's table of contents (TOC). The
@@ -832,21 +874,6 @@ int CdStatus(void);
 int CdGetToc(CdlLOC *toc);
 
 /**
- * @brief Returns the CD-ROM controller's region code.
- *
- * @details Attempts to fetch region information from the drive using a CdlTest
- * command. This can be used to reliably determine the system's region without
- * having to resort to workarounds like probing the BIOS ROM.
- *
- * This function may return incorrect results on emulators or consoles equipped
- * with CD-ROM drive emulation devices such as the PSIO. It is not affected by
- * modchips.
- *
- * @return Region code or 0 if the region cannot be determined
- */
-CdlRegionCode CdGetRegion(void);
-
-/**
  * @brief Sets the CD-ROM volume mixing matrix.
  *
  * @details Sets the volume levels of the CD-ROM drive's audio output (used for
diff --git a/libpsn00b/include/psxetc.h b/libpsn00b/include/psxetc.h
index ae4611e..ebf7966 100644
--- a/libpsn00b/include/psxetc.h
+++ b/libpsn00b/include/psxetc.h
@@ -156,19 +156,50 @@ void *DMACallback(DMA_Channel dma, void (*func)(void));
 void *GetDMACallback(DMA_Channel dma);
 
 /**
- * @brief Initializes the interrupt dispatcher.
+ * @brief Enables, disables or sets the priority of a DMA channel.
+ *
+ * @details Enables the specified DMA channel and configures its priority (if
+ * priority >= 0) or disables it (if priority = -1). The priority value must be
+ * in 0-7 range, with 0 being the highest priority and 7 the lowest.
+ *
+ * All channels are disabled upon calling ResetCallback(); most libraries will
+ * re-enable them as needed. By default the priority is set to 3 for all
+ * channels.
+ *
+ * @param dma
+ * @param priority Priority in 0-7 range or -1 to disable the channel
+ * @return Previously set priority in 0-7 range, -1 if the channel was disabled
+ */
+int SetDMAPriority(DMA_Channel dma, int priority);
+
+/**
+ * @brief Gets the priority of a DMA channel.
+ *
+ * @details Returns the currently set priority value for the specified DMA
+ * channel in 0-7 range, with 0 being the highest priority and 7 the lowest.
+ * Returns -1 if the channel is not enabled.
+ *
+ * @param dma
+ * @return Priority in 0-7 range, -1 if the channel is disabled
+ *
+ * @see SetDMAPriority()
+ */
+int GetDMAPriority(DMA_Channel dma);
+
+/**
+ * @brief Initializes the interrupt dispatcher and DMA controller.
  *
  * @details Sets up the interrupt handling system, hooks the BIOS to dispatch
- * interrupts to the library and clears all registered callbacks. This function
- * must be called once at the beginning of the program, prior to registering
- * any IRQ or DMA callbacks.
+ * interrupts to the library, clears all registered callbacks and disables all
+ * DMA channels. This function must be called once at the beginning of the
+ * program, prior to registering any IRQ or DMA callbacks.
  *
  * ResetCallback() is called by psxgpu's ResetGraph(), so invoking it manually
  * is usually not required. Calling ResetCallback() after ResetGraph() will
  * actually result in improper initialization, as ResetGraph() registers
  * several callbacks used internally by psxgpu.
  *
- * @return 0 or -1 if the was already initialized
+ * @return 0 or -1 if the dispatcher was already initialized
  */
 int ResetCallback(void);