romdev-mcp 0.1.1

package/src/platforms/genesis/lib/sgdk/include/dma.h

@@ -0,0 +1,542 @@
+/**
+ *  \file dma.h
+ *  \brief DMA support
+ *  \author Stephane Dallongeville
+ *  \date 04/2015
+ *
+ * This unit provides methods to use the hardware DMA capabilities.
+ */
+
+#include "config.h"
+#include "types.h"
+
+#ifndef _DMA_H_
+#define _DMA_H_
+
+
+/**
+ *  \brief
+ *      VRAM destination for DMA operation.
+ */
+#define DMA_VRAM    0
+/**
+ *  \brief
+ *      CRAM destination for DMA operation.
+ */
+#define DMA_CRAM    1
+/**
+ *  \brief
+ *      VSRAM destination for DMA operation.
+ */
+#define DMA_VSRAM   2
+
+#define DMA_QUEUE_SIZE_DEFAULT          80
+#define DMA_QUEUE_SIZE_MIN              32
+
+#define DMA_TRANSFER_CAPACITY_NTSC      7200
+#define DMA_TRANSFER_CAPACITY_PAL_LOW   8000
+#define DMA_TRANSFER_CAPACITY_PAL_MAX   15000
+
+// better to allocate a bit more than DMA capacity
+#define DMA_BUFFER_SIZE_NTSC            8192
+#define DMA_BUFFER_SIZE_PAL_LOW         8192
+#define DMA_BUFFER_SIZE_PAL_MAX         (14 * 1024)
+#define DMA_BUFFER_SIZE_MIN             (2 * 1024)
+
+
+/**
+ *  \brief
+ *      VRAM transfer method
+ */
+typedef enum
+{
+    CPU = 0,            /**< Transfer through the CPU immediately (slower.. useful for testing purpose mainly) */
+    DMA = 1,            /**< Transfer through DMA immediately, using DMA is faster but can lock Z80 execution */
+    DMA_QUEUE = 2,      /**< Put in the DMA queue so it will be transferred at next VBlank. Using DMA is faster but can lock Z80 execution */
+    DMA_QUEUE_COPY = 3  /**< Copy the buffer and put in the DMA queue so it will be transferred at next VBlank. Using DMA is faster but can lock Z80 execution */
+} TransferMethod;
+
+
+/**
+ *  \brief
+ *      DMA transfer definition (used for DMA queue)
+ */
+typedef struct
+{
+    u16 regLenL;        // (newLen & 0xFF) | 0x9300;
+    u16 regLenH;        // ((newLen >> 8) & 0xFF) | 0x9400;
+    u32 regAddrMStep;   // (((addr << 7) & 0xFF0000) | 0x96008F00) + step;
+    u32 regAddrHAddrL;  // ((addr >> 1) & 0x7F00FF) | 0x97009500;
+    u32 regCtrlWrite;   // VDP_DMA_VRAMCOPY_ADDR(to)
+} DMAOpInfo;
+
+
+/**
+ *  \brief
+ *      DMA queue structure
+ */
+extern DMAOpInfo *dmaQueues;
+/**
+ *  \brief
+ *      DMA queue structure
+ */
+extern u16* dmaDataBuffer;
+
+/**
+ *  \brief
+ *      Initialize the DMA queue sub system with default settings.
+ *
+ *      SGDK automatically call this method on hard reset so you don't need to call it again unless
+ *      you want to change the default parameters in which casse you should use #DMA_initEx(..)
+ *
+ * \see #DMA_initEx(..)
+ */
+void DMA_init(void);
+/**
+ *  \brief
+ *      Initialize the DMA queue sub system.
+ *
+ *  \param size
+ *      The queue size (0 = default size = 64, min size = 20).
+ *  \param capacity
+ *      The maximum allowed size (in bytes) to transfer per #DMA_flushQueue() call (0 = default = no limit).<br>
+ *      Depending the current selected strategy, furthers transfers can be ignored (by default all transfers are done whatever is the limit).
+ *      See the #DMA_setIgnoreOverCapacity(..) method to change the strategy to adopt when capacity limit is reached.
+ *  \param bufferSize
+ *      Size of the buffer (in bytes) to store temporary data that will be transferred through the DMA queue (0 = default size = 8192 on NTSC and 14336 on PAL).<br>
+ *      The buffer should be big enough to contains all temporary that you need to store before next #DMA_flushQueue() call.
+ *
+ *      SGDK automatically call this method on hard reset so you don't need to call it again unless
+ *      you want to change the default parameters.
+ *
+ * \see #DMA_setIgnoreOverCapacity(..)
+ */
+void DMA_initEx(u16 size, u16 capacity, u16 bufferSize);
+
+/**
+ *  \brief
+ *      Returns TRUE if the DMA_flushQueue() method is automatically called at VBlank to process DMA operations
+ *      pending in the queue.
+ *
+ *  \see DMA_setAutoFlush()
+ *  \see DMA_flushQueue()
+ */
+bool DMA_getAutoFlush(void);
+/**
+ *  \brief
+ *      If set to TRUE (default) then the DMA_flushQueue() method is automatically called at VBlank
+ *      to process DMA operations pending in the queue otherwise you have to call the DMA_flushQueue()
+ *      method by yourself.
+ *
+ *  \see DMA_flushQueue()
+ */
+void DMA_setAutoFlush(bool value);
+/**
+ *  \brief
+ *      Returns the maximum allowed number of pending transfer in the queue (allocated queue size).
+ *
+ *  \see DMA_setMaxQueueSize()
+ */
+u16 DMA_getMaxQueueSize(void);
+/**
+ *  \brief
+ *      Sets the maximum allowed number of pending transfer in the queue (allocated queue size).<br>
+ *      <b>WARNING:</b> changing the queue size will clear the DMA queue.
+ *
+ *  \param value
+ *      The queue size (minimum allowed size = 20)
+ *
+ *  \see DMA_getMaxQueueSize()
+ *  \see DMA_setMaxQueueSizeToDefault()
+ */
+void DMA_setMaxQueueSize(u16 value);
+/**
+ *  \brief
+ *      Sets the maximum allowed number of pending transfer in the queue (allocated queue size) to default value (64).<br>
+ *      <b>WARNING:</b> changing the queue size will clear the DMA queue.
+ *
+ *  \see DMA_setMaxQueueSize(..)
+ */
+void DMA_setMaxQueueSizeToDefault(void);
+/**
+ *  \brief
+ *      Returns the maximum allowed size (in bytes) to transfer per #DMA_flushQueue() call.<br>
+ *      A value of 0 means there is no DMA limit.
+ *
+ *  \see DMA_setMaxTransferSize(..)
+ */
+u16 DMA_getMaxTransferSize(void);
+/**
+ *  \brief
+ *      Sets the maximum amount of data (in bytes) to transfer per #DMA_flushQueue() call.<br>
+ *      VBlank period allows to transfer up to 7.2 KB on NTSC system and 15 KB on PAL system.<br>
+ *      By default there is no size limit (0)
+ *
+ *  \param value
+ *      The maximum amount of data (in bytes) to transfer during DMA_flushQueue() operation.<br>
+ *      Use <b>0</b> for no limit.
+ *
+ *  \see DMA_flushQueue(void)
+ */
+void DMA_setMaxTransferSize(u16 value);
+/**
+ *  \brief
+ *      Sets the maximum amount of data (in bytes) to default value (7.2 KB on NTSC system and 15 KB on PAL system).
+ *
+ *  \see DMA_setMaxTransferSize()
+ */
+void DMA_setMaxTransferSizeToDefault(void);
+/**
+ *  \brief
+ *      Returns the size (in bytes) of the temporary data buffer which can be used to store data
+ *      that will be transferred through the DMA queue.
+ *
+ *  \see DMA_setBufferSize(void)
+ */
+u16 DMA_getBufferSize(void);
+/**
+ *  \brief
+ *      Sets the size (in bytes) of the temporary data buffer which can be used to store data
+ *      that will be transferred through the DMA queue.<br>
+ *      <b>WARNING:</b> changing the buffer size will clear the DMA queue.
+ *
+ *  \param value
+ *      The size of the temporary data buffer (in bytes).<br>
+ *      Minimum allowed buffer size if 2048 (internals methods require a minimal buffer size)
+ *
+ *  \see DMA_getBufferSize(void)
+ *  \see DMA_setBufferSizeToDefault(void)
+ */
+void DMA_setBufferSize(u16 value);
+/**
+ *  \brief
+ *      Sets the size (in bytes) of the temporary data buffer to default value (8 KB on NTSC system and 14 KB on PAL system).
+ *
+ *  \see DMA_setBufferSize(void)
+ */
+void DMA_setBufferSizeToDefault(void);
+/**
+ *  \brief
+ *      Return TRUE means that we ignore future DMA operation when we reach the maximum capacity (see #DMA_setIgnoreOverCapacity(..) method).
+ *
+ *  \see DMA_setIgnoreOverCapacity(void)
+ */
+bool DMA_getIgnoreOverCapacity(void);
+/**
+ *  \brief
+ *      Set the "over capacity" DMA queue strategy (default is FALSE).
+ *
+ *      When set to <i>TRUE</i> any DMA operation queued after we reached the maximum defined transfer capacity
+ *      with #DMA_setMaxTransferSize(..) are ignored.<br>
+ *      When set to <i>FALSE</i> all DMA operations are done even when we are over the maximum capacity (which can lead to important slowdown).
+ *
+ *  \see DMA_setMaxTransferSize()
+ */
+void DMA_setIgnoreOverCapacity(bool value);
+
+/**
+ *  \brief
+ *      Clears the DMA queue (all queued operations are lost).<br>
+ *  \see DMA_flushQueue(void)
+ */
+void DMA_clearQueue(void);
+/**
+ *  \brief
+ *      Transfer the content of the DMA queue to the VDP:<br>
+ *      Each pending DMA operation is sent to the VDP and processed as quickly as possible.<br>
+ *      This method returns when all DMA operations present in the queue has been transferred (or when maximum capacity has been reached).<br>
+ *      Note that this method is automatically called at VBlank time and you shouldn't call yourself except if
+ *      you want to process it before vblank (if you manually extend blank period with h-int for instance) in which case
+ *      you can disable the auto flush feature (see DMA_setAutoFlush(...))
+ *
+ *  \see DMA_queue(...)
+ *  \see DMA_setAutoFlush(...)
+ */
+void DMA_flushQueue(void);
+
+/**
+ *  \brief
+ *      Returns the number of transfer currently pending in the DMA queue.
+ */
+u16 DMA_getQueueSize(void);
+/**
+ *  \brief
+ *      Returns the size (in byte) of data to be transferred currently present in the DMA queue.<br>
+ *      NTSC frame allows about 7.6 KB of data to be transferred during VBlank (in H40) while
+ *      PAL frame allows about 17 KB (in H40).
+ */
+u16 DMA_getQueueTransferSize(void);
+
+/**
+ *  \brief
+ *      Tool method allowing to allocate memory from the DMA temporary buffer if you need a very temporary buffer.<br>
+ *      Don't forget to release memory using #DMA_releaseTemp(..).<br>
+ *      <b>WARNING:</b> it's very important to disable interrupts while using the temporary DMA buffer as DMA buffer can be flushed on interrupt.
+ *
+ *  \param len
+ *      Number of word to allocate.
+ *  \return
+ *      The source buffer pointer if allocation succeeded,.<br>
+ *      Returns NULL if the buffer is full (or not big enough).
+ *  \see DMA_releaseTemp(..)
+ */
+void* DMA_allocateTemp(u16 len);
+/**
+ *  \brief
+ *      Tool method allowing to release memory previously allocated using #DMA_allocateTemp(..).<br>
+ *      <b>WARNING:</b> it's very important to disable interrupts while using the temporary DMA buffer as DMA buffer can be flushed on interrupt.
+ *
+ *  \param len
+ *      Number of word to release.
+ *  \see DMA_allocateTemp(..)
+ */
+void DMA_releaseTemp(u16 len);
+
+/**
+ *  \brief
+ *      General method to transfer data to VDP memory.
+ *
+ *  \param tm
+ *      Transfer method.<br>
+ *      Accepted values are:<br>
+ *      - CPU<br>
+ *      - DMA<br>
+ *      - DMA_QUEUE<br>
+ *      - DMA_QUEUE_COPY<br>
+ *  \param location
+ *      Destination location.<br>
+ *      Accepted values:<br>
+ *      - DMA_VRAM (for VRAM transfer).<br>
+ *      - DMA_CRAM (for CRAM transfer).<br>
+ *      - DMA_VSRAM (for VSRAM transfer).<br>
+ *  \param from
+ *      Source buffer.
+ *  \param to
+ *      VRAM/CRAM/VSRAM destination address.
+ *  \param len
+ *      Number of word to allocate and transfer.
+ *  \param step
+ *      destination (VRAM/VSRAM/CRAM) address increment step after each write (0 to 255).<br>
+ *      By default you should set it to 2 for normal copy operation but you can use different value
+ *      for specific operation.<br>
+ *  \return
+ *      TRUE if the operation succeeded, FALSE otherwise (buffer or queue full).
+ *  \see DMA_queueDMA(..)
+ */
+bool DMA_transfer(TransferMethod tm, u8 location, void* from, u16 to, u16 len, u16 step);
+
+/**
+ *  \brief
+ *      Return TRUE if we have enough DMA capacity to transfer the given data block len (see #DMA_setMaxTransferSize(..))
+ *
+ *  \param location
+ *      Destination location.<br>
+ *      Accepted values:<br>
+ *      - DMA_VRAM (for VRAM transfer).<br>
+ *      - DMA_CRAM (for CRAM transfer).<br>
+ *      - DMA_VSRAM (for VSRAM transfer).<br>
+ *  \param len
+ *      Number of word we want to transfer.
+ *  \return
+ *      TRUE if we have enough capacity, FALSE otherwise
+ *  \see DMA_getMaxTransferSize(..)
+ *  \see DMA_queueDma(..)
+ */
+bool DMA_canQueue(u8 location, u16 len);
+/**
+ *  \brief
+ *      Allocate temporary memory and queues the DMA transfer operation in the DMA queue.<br>
+ *      The idea of the DMA queue is to burst all DMA operations during VBLank to maximize bandwidth usage.<br>
+ *      <b>IMPORTANT:</b> You need to fill the returned data buffer before DMA occurs so it's a good practise to disable interrupts before
+ *      calling this method and re-enable them *after* you filled the buffer to avoid DMA queue flush operation happening in between.
+ *
+ *  \param location
+ *      Destination location.<br>
+ *      Accepted values:<br>
+ *      - DMA_VRAM (for VRAM transfer).<br>
+ *      - DMA_CRAM (for CRAM transfer).<br>
+ *      - DMA_VSRAM (for VSRAM transfer).<br>
+ *  \param to
+ *      VRAM/CRAM/VSRAM destination address.
+ *  \param len
+ *      Number of word to allocate and transfer.
+ *  \param step
+ *      destination (VRAM/VSRAM/CRAM) address increment step after each write (0 to 255).<br>
+ *      By default you should set it to 2 for normal copy operation but you can use different value
+ *      for specific operation.<br>
+ *  \return
+ *      The source buffer pointer that will be used for the DMA transfer so you can fill its content.<br>
+ *      Returns NULL if the buffer is full or if the DMA queue operation failed (queue is full).
+ *  \see DMA_queueDMA(..)
+ *  \see DMA_copyAndQueueDma(..)
+ */
+void* DMA_allocateAndQueueDma(u8 location, u16 to, u16 len, u16 step);
+/**
+ *  \brief
+ *      Same as #DMA_queueDma(..) method except that it first copies the data to transfer through DMA queue into a temporary buffer.<br>
+ *      This is useful when you know that source data may be modified before DMA acutally occurs and want to avoid that.
+ *
+ *  \param location
+ *      Destination location.<br>
+ *      Accepted values:<br>
+ *      - DMA_VRAM (for VRAM transfer).<br>
+ *      - DMA_CRAM (for CRAM transfer).<br>
+ *      - DMA_VSRAM (for VSRAM transfer).<br>
+ *  \param from
+ *      Source buffer.
+ *  \param to
+ *      VRAM/CRAM/VSRAM destination address.
+ *  \param len
+ *      Number of word to transfer.
+ *  \param step
+ *      destination (VRAM/VSRAM/CRAM) address increment step after each write (0 to 255).<br>
+ *      By default you should set it to 2 for normal copy operation but you can use different value
+ *      for specific operation.<br>
+ *  \return
+ *      FALSE if the operation failed (queue is full)
+ *  \see DMA_doDma(..)
+ *  \see DMA_queueDma(..)
+ */
+bool DMA_copyAndQueueDma(u8 location, void* from, u16 to, u16 len, u16 step);
+/**
+ *  \brief
+ *      Queues the specified DMA transfer operation in the DMA queue.<br>
+ *      The idea of the DMA queue is to burst all DMA operations during VBLank to maximize bandwidth usage.<br>
+ *
+ *  \param location
+ *      Destination location.<br>
+ *      Accepted values:<br>
+ *      - DMA_VRAM (for VRAM transfer).<br>
+ *      - DMA_CRAM (for CRAM transfer).<br>
+ *      - DMA_VSRAM (for VSRAM transfer).<br>
+ *  \param from
+ *      Source buffer address.
+ *  \param to
+ *      VRAM/CRAM/VSRAM destination address.
+ *  \param len
+ *      Number of word to transfer.
+ *  \param step
+ *      destination (VRAM/VSRAM/CRAM) address increment step after each write (0 to 255).<br>
+ *      By default you should set it to 2 for normal copy operation but you can use different value
+ *      for specific operation.<br>
+ *  \return
+ *      FALSE if the operation failed (queue is full)
+ *  \see DMA_doDma(..)
+ */
+bool DMA_queueDma(u8 location, void* from, u16 to, u16 len, u16 step);
+/**
+ *  \brief
+ *      Same as #DMA_queueDma(..) method except if doesn't check for 128 KB bank crossing on source
+ *  \see #DMA_queueDma(..)
+ */
+bool DMA_queueDmaFast(u8 location, void* from, u16 to, u16 len, u16 step);
+
+/**
+ *  \brief
+ *      Do DMA transfer operation immediately
+ *
+ *  \param location
+ *      Destination location.<br>
+ *      Accepted values:<br>
+ *      - DMA_VRAM (for VRAM transfer).<br>
+ *      - DMA_CRAM (for CRAM transfer).<br>
+ *      - DMA_VSRAM (for VSRAM transfer).<br>
+ *  \param from
+ *      Source buffer address.
+ *  \param to
+ *      VRAM/CRAM/VSRAM destination address.
+ *  \param len
+ *      Number of word to transfer.
+ *  \param step
+ *      destination (VRAM/VSRAM/CRAM) address increment step after each write (-1 to keep current step).<br>
+ *      By default you should set it to 2 for normal copy operation but you can use different value
+ *      for specific operation.
+ *  \see DMA_queue(..)
+ */
+void DMA_doDma(u8 location, void* from, u16 to, u16 len, s16 step);
+/**
+ *  \brief
+ *      Same as #DMA_doDma(..) method except if doesn't check for 128 KB bank crossing on source
+ *  \see #DMA_doDma(..)
+ */
+void DMA_doDmaFast(u8 location, void* from, u16 to, u16 len, s16 step);
+
+/**
+ *  \brief
+ *      Do software (CPU) copy to VDP memory (mainly for testing purpose as it's slower than using DMA)
+ *
+ *  \param location
+ *      Destination location.<br>
+ *      Accepted values:<br>
+ *      - DMA_VRAM (for VRAM transfer).<br>
+ *      - DMA_CRAM (for CRAM transfer).<br>
+ *      - DMA_VSRAM (for VSRAM transfer).<br>
+ *  \param from
+ *      Source buffer.
+ *  \param to
+ *      VRAM/CRAM/VSRAM destination address.
+ *  \param len
+ *      Number of word to transfer.
+ *  \param step
+ *      destination (VRAM/VSRAM/CRAM) address increment step after each write (-1 to keep current step).<br>
+ *      By default you should set it to 2 for normal copy operation but you can use different value
+ *      for specific operation.
+ */
+void DMA_doCPUCopy(u8 location, void* from, u16 to, u16 len, s16 step);
+/**
+ *  \brief
+ *      Do software (CPU) copy to VDP memory (mainly for testing purpose as it's slower than using DMA)
+ *
+ *  \param cmd
+ *      VDP packed control command (contains operation and destination address).
+ *  \param from
+ *      Source buffer.
+ *  \param len
+ *      Number of word to transfer.
+ *  \param step
+ *      destination (VRAM/VSRAM/CRAM) address increment step after each write (-1 to keep current step).<br>
+ *      By default you should set it to 2 for normal copy operation but you can use different value
+ *      for specific operation.
+ */
+void DMA_doCPUCopyDirect(u32 cmd, void* from, u16 len, s16 step);
+
+/**
+ *  \brief
+ *      Do VRAM DMA fill operation.
+ *
+ *  \param to
+ *      VRAM destination address.
+ *  \param len
+ *      Number of byte to fill (minimum is 2 for even addr destination and 3 for odd addr destination).<br>
+ *      A value of 0 mean 0x10000.
+ *  \param value
+ *      Fill value (byte).
+ *  \param step
+ *      VRAM address increment step after each write (-1 to keep current step).<br>
+ *      should be 1 for a classic fill operation but you can use different value for specific operation.
+ */
+void DMA_doVRamFill(u16 to, u16 len, u8 value, s16 step);
+/**
+ *  \brief
+ *      Do VRAM DMA copy operation.
+
+ *  \param from
+ *      VRAM Source address.
+ *  \param to
+ *      VRAM destination address.
+ *  \param len
+ *      Number of byte to copy.
+ *  \param step
+ *      VRAM address increment step after each write (-1 to keep current step).<br>
+ *      should be 1 for a classic copy operation but you can use different value for specific operation.
+ */
+void DMA_doVRamCopy(u16 from, u16 to, u16 len, s16 step);
+
+/**
+ *  \brief
+ *      Wait current DMA fill/copy operation to complete (same as #VDP_waitDMACompletion())
+ */
+void DMA_waitCompletion(void);
+
+
+#endif // _DMA_H_