Main Page   Modules   Alphabetical List   Data Structures   Data Fields  

PlayStation 2 DMA Support
[Platform Specific]


Defines
#define  RWDMA_PKT_TYPE_MASK   0x000000ff
#define  RWDMA_MOD_MASK   0x00000300
#define  RWDMA_MOD_TTE_MASK   0x00001300
#define  RWDMA_PKT_IMM_MASK   0x0ffff000
#define  RWDMA_MOD_NORM   0x0000
#define  RWDMA_MOD_CHAIN   0x0100
#define  RWDMA_MOD_CHAIN_TTE   0x1100
#define  RWDMA_PKT_GIF_NORM   0x02
#define  RWDMA_PKT_VIF_NORM   0x01
#define  RWDMA_FIXUP   0x80000000
#define  RWDMA_PKT_RASUREF   0x42
#define  RWDMA_PKT_CALL   0x4f
#define  RWDMA_PKT_IMM_SHIFT   12
#define  RWDMA_PKT_IMM_MAX   (RWDMA_PKT_IMM_MASK>>RWDMA_PKT_IMM_SHIFT)
#define  RWDMA_PKT_GIF   (RWDMA_PKT_GIF_NORM | RWDMA_MOD_CHAIN)
#define  RWDMA_PKT_VIF_TTE   (RWDMA_PKT_VIF_NORM | RWDMA_MOD_CHAIN_TTE)
#define  RWDMA_CRITICAL_SECTION_BEGIN()
#define  RWDMA_CRITICAL_SECTION_END()
#define  RWDMA_SPR_MAX_PKT_SIZE   (511)
#define  RWDMA_SPR_WAIT_ON_FROM()
#define  RWDMA_SPR_WAIT_ON_TO()
#define  RWDMA_SPR_CPY_FROM(DST, SRC, SIZE)
#define  RWDMA_SPR_CPY_TO(DST, SRC, SIZE)
#define  RWDMA_HALF_OFFSET()
#define  RWDMA_LOCAL_BLOCK_BEGIN()
#define  RWDMA_LOCAL_BLOCK_END()
#define  RWDMA_ADD_TO_PKT(A)
#define  RWDMA_LOCAL_ASYNC_BLOCK_BEGIN()
#define  RWDMA_LOCAL_ASYNC_BLOCK_END()
#define  RWDMA_ADD_TO_ASYNC_PKT(A)

Typedefs
typedef RwBool(*  rwDMACallback )(RwBool inHandler)
typedef rwDMA_flipData  rwDMA_flipData

Functions
void  _rwDMAYieldCallbackSet (rwDMAYieldCallback callback)
void  _rwDMAMinVsyncCntSet (RwUInt8 minCnt)
RwBool  _rwDMACallbackRestart (void)
void  _rwDMAClosePkt (void)
void  _rwDMAForceBufferSwap (void)
void  _rwDMAAddPkt (void *addr, RwUInt32 type)
void  _rwDMAAddPkt2 (void *addrVif, void *addrGif)
void  _rwDMAAddPURef (RwInt32 *ptr)
RwBool  _rwDMAOpenGIFPkt (RwUInt32 size)
RwBool  _rwDMAOpenVIFPkt (RwUInt32 type, RwUInt32 size)
RwUInt128 *  _rwDMADMAAlloca (RwUInt32 size, RwBool sprFlush)
RwUInt128 *  _rwDMADMAPktAllocHigh (RwUInt32 size, RwBool sprFlush)
RwBool  _rwDMAAddImageUpload (RwBool parallel, RwUInt32 size)
RwBool  _rwDMAPreAlloc (RwUInt32 size, RwUInt16 puRefSize, RwUInt128 *optionalBuf)

Variables
rwDMA_flipData  _rwDMAFlipData
RwUInt128 *  _rwDMAGateSlot

PlayStation 2 DMA Support Overview

These functions are used to control the PlayStation 2 DMA system in coexistance with RenderWare Graphics. They are exposed predominantly so that the PlayStation 2 specific parts of plugins and toolkits can be written. These function and macros replace the swe* functions and macros in versions of RenderWare Graphics previous to 3.4.

If you do not use any of the DMA functions directly (search your code for the regular expression "[Ss][Ww][Ee]") these changes should have no impact, except better memory and CPU performance.

If you need to port code that used the old functions, the following notes will help:

Define Documentation

#define RWDMA_ADD_TO_ASYNC_PKT (  A    ) 
 

RWDMA_ADD_TO_ASYNC_PKT is used to add a quadword to a packet opened by _rwDMAAddImageUpload.
#define RWDMA_ADD_TO_PKT (  A    ) 
 

RWDMA_ADD_TO_PKT is used to add a quadword to a packet opened by _rwDMAOpenGIFPkt or _rwDMAOpenVIFPkt.
 
#define RWDMA_CRITICAL_SECTION_BEGIN ( 
  ) 
 

RWDMA_CRITICAL_SECTION_BEGIN is used to mark the beginning of a critical section in the code, for example a reference count increment.
 
#define RWDMA_CRITICAL_SECTION_END ( 
  ) 
 

RWDMA_CRITICAL_SECTION_END is used to mark the end of a critical section in the code.
#define RWDMA_FIXUP   0x80000000
 

RWDMA_FIXUP is passed to _rwDMAOpenVIFPkt to request a path 2 packet.
 
#define RWDMA_HALF_OFFSET ( 
  ) 
 

RWDMA_HALF_OFFSET returns the value of the half offset required in this frame to take account of interlacing. It should be used when building values for the GS XYOFFSET registers.
 
#define RWDMA_LOCAL_ASYNC_BLOCK_BEGIN ( 
  ) 
 

RWDMA_LOCAL_ASYNC_BLOCK_BEGIN can be used to make the code generated for a sequence of RWDMA_ADD_TO_ASYNC_PKT macros more efficient. The code segment should be bracketed by RWDMA_LOCAL_ASYNC_BLOCK_BEGIN and RWDMA_LOCAL_ASYNC_BLOCK_END. It works by shadowing the global packet pointer in a local variable. As such, no code that depends on the global pointer, such as calls to functions that use RWDMA_ADD_TO_ASYNC_PKT, should be used within the bracketed block.
 
#define RWDMA_LOCAL_ASYNC_BLOCK_END ( 
  ) 
 

RWDMA_LOCAL_ASYNC_BLOCK_END is used to close a RWDMA_LOCAL_ASYNC_BLOCK_BEGIN code block.
 
#define RWDMA_LOCAL_BLOCK_BEGIN ( 
  ) 
 

RWDMA_LOCAL_BLOCK_BEGIN can be used to make the code generated for a sequence of RWDMA_ADD_TO_PKT macros more efficient. The code segment should be bracketed by RWDMA_LOCAL_BLOCK_BEGIN and RWDMA_LOCAL_BLOCK_END. It works by shadowing the global packet pointer in a local variable. As such, no code that depends on the global pointer, such as calls to functions that use RWDMA_ADD_TO_PKT, should be used within the bracketed block.
 
#define RWDMA_LOCAL_BLOCK_END ( 
  ) 
 

RWDMA_LOCAL_BLOCK_END is used to close a RWDMA_LOCAL_BLOCK_BEGIN code block.
#define RWDMA_MOD_CHAIN   0x0100
 

RWDMA_MOD_CHAIN indicates that source chain mode DMA should be used.
#define RWDMA_MOD_CHAIN_TTE   0x1100
 

RWDMA_MOD_CHAIN_TTE indicates that source chain mode with TTE DMA should be used.
#define RWDMA_MOD_MASK   0x00000300
 

RWDMA_MOD_MASK is the mask used to extract the transfer mode from the _rwDMAAddPkt type argument. Interleave mode is not supported.
#define RWDMA_MOD_NORM   0x0000
 

RWDMA_MOD_NORM indicates that normal mode DMA should be used. The quad word count should be stored in the RWDMA_PKT_IMM_MASK field.
#define RWDMA_MOD_TTE_MASK   0x00001300
 

RWDMA_MOD_TTE_MASK is the mask used to extract the transfer mode including the chain mode TTE bit from the _rwDMAAddPkt type argument. Interleave mode is not supported.
#define RWDMA_PKT_CALL   0x4f
 

RWDMA_PKT_CALL is used to add a call back of type rwDMACallback to the chain. When this packet is "dispatched" it will call the function specified by the address argument of _rwDMAAddPkt with interrupts disabled.
#define RWDMA_PKT_GIF   (RWDMA_PKT_GIF_NORM | RWDMA_MOD_CHAIN)
 

RWDMA_PKT_GIF is used to request a transfer on DMA channel 2 using chain mode.
#define RWDMA_PKT_GIF_NORM   0x02
 

RWDMA_PKT_GIF_NORM is used to request a transfer on DMA channel 2.
#define RWDMA_PKT_IMM_MASK   0x0ffff000
 

RWDMA_PKT_IMM_MASK is the mask used to extract an immediate integer argument required by some packet types from the _rwDMAAddPkt type argument.
#define RWDMA_PKT_IMM_MAX   (RWDMA_PKT_IMM_MASK>>RWDMA_PKT_IMM_SHIFT)
 

RWDMA_PKT_IMM_MAX is the maximum immediate argument that may be specified as part of the type argument to _rwDMAAddPkt
#define RWDMA_PKT_IMM_SHIFT   12
 

RWDMA_PKT_IMM_SHIFT is the shift required to move an integer into the RWDMA_PKT_IMM_MASK field.
#define RWDMA_PKT_RASUREF   0x42
 

RWDMA_PKT_RASUREF is used to add a reference count decrement packet. When this packet is "dispatched" it will decrement the 32 bit number pointed to by the address argument of _rwDMAAddPkt by the number in the RWDMA_PKT_IMM_MASK field. If this number is 0, 1 is assumed. In general, it is better to use _rwDMAAddPURef, rather than this type.
#define RWDMA_PKT_TYPE_MASK   0x000000ff
 

RWDMA_PKT_TYPE_MASK is the mask used to extract a packet type from the _rwDMAAddPkt type argument.
#define RWDMA_PKT_VIF_NORM   0x01
 

RWDMA_PKT_VIF_NORM is used to request a transfer on DMA channel 1.
#define RWDMA_PKT_VIF_TTE   (RWDMA_PKT_VIF_NORM | RWDMA_MOD_CHAIN_TTE)
 

RWDMA_PKT_VIF_TTE is used to request a transfer on DMA channel 1 using chain mode with TTE enabled.
#define RWDMA_SPR_CPY_FROM (  DST,
SRC,
SIZE    ) 
 

RWDMA_SPR_CPY_FROM is used to copy SIZE quad words to memory. This should only be used when channel 8 is not busy.
#define RWDMA_SPR_CPY_TO (  DST,
SRC,
SIZE    ) 
 

RWDMA_SPR_CPY_TO is used to copy SIZE quad words to SPR. This should only be used when channel 9 is not busy.
#define RWDMA_SPR_MAX_PKT_SIZE   (511)
 

RWDMA_SPR_MAX_PKT_SIZE is the maximum quad word packet chunk that can be built at one time.
 
#define RWDMA_SPR_WAIT_ON_FROM ( 
  ) 
 

RWDMA_SPR_WAIT_ON_FROM waits until a transfer on channel 8 completes. It assumes that interrupts on the channel are not enabled and that CIS8 was cleared before the transfer started.
 
#define RWDMA_SPR_WAIT_ON_TO ( 
  ) 
 

RWDMA_SPR_WAIT_ON_TO waits until a transfer on channel 9 completes. It assumes that interrupts on the channel are not enabled and that CIS9 was cleared before the transfer started.

Typedef Documentation

typedef struct rwDMA_flipData rwDMA_flipData
 

rwDMA_flipData holds the data used by the VSYNC handler to flip frames. The display env is updated from dc, read circuit 1 from tcaaDisp, and if non NULL, the DMA packet pointed to by dmaPkt[(rwDMAFlipId | ((DGET_GS_CSR() >> 12) & 0x2))] will be dispatched to DMA channel 2 using chain mode.

Warning:
To get access to this, libgraph.h has to have been included before rwcore.h.
typedef RwBool(* rwDMACallback)(RwBool inHandler)
 

rwDMACallback is the type of the function called when a RWDMA_PKT_CALL packet is "dispatched". The function is invoked with interrupts disabled. If the callback needs to perform more work than can reasonably occur within an interrupt handler, it should raise another thread and then return FALSE.

Parameters:
inHandler  Indicates if the callback occurred from the context of an interrupt handler.
Returns:
TRUE if the next packet may be dispatched. If FALSE is returned, _rwDMACallbackRestart must eventually be called to restart dispatch.

Function Documentation

RwBool _rwDMAAddImageUpload (  RwBool    parallel,
RwUInt32    size
) 
 

_rwDMAAddImageUpload starts/extends a DMA channel 2 chain to permit an image upload to be performed. It also starts/extends a DMA channel 1 chain and modifies it to permit the image upload to be synchronized with the chain.

Warning:
This function should only be called when it would be safe to terminate any partially constructed packet, as it will cause a call to _rwDMAClosePkt if it runs out of memory in the current buffer, or the currently open packet is not of the correct type.
The function provides support for asynchronous image upload. If a parallel image upload is requested and _rwDMAGateSlot is non-NULL, this will be overwritten to cause the upload to overlap a section of the channel 1 chain.

The caller is required to fill the space allocated in the channel 2 chain with suitable DMA/GIF tags using RWDMA_ADD_TO_ASYNC_PKT. Only the final GIF tag should have its EOP bit set. The function assumes that the channel 2 chain will end with a DMA cnt 2 tag followed by a GIF a+d 1 tag and a GS nop. This is important as when this chain is extended, the DMA tag needs to be overwritten.

Note:
It is almost never necessary to call this function directly, as the texture cache will call it when required.
Parameters:
parallel  TRUE if the upload should overlap the previous channel 1 segment.
size  Number of quad words required.
Returns:
Returns TRUE if sucessful, FALSE if there is an error.
void _rwDMAAddPkt (  void *    addr,
RwUInt32    type
) 
 

_rwDMAAddPkt is used to add a packet to the dispatch chain. As well as data to be dispatched to a DMA channel, pseudo-packet types are also avaliable to perform reference counting, callbacks, etc.

If a packet is open, it will be closed and added before the chains passed to this function.

Note:
It is not necessary to call this function with packets built using _rwDMAOpenVIFPkt, etc, as these will be automatically added to the dispatch chain when they are closed.
Parameters:
addr  Address of packet data.
type  Type of packet.
void _rwDMAAddPkt2 (  void *    addrVif,
void *    addrGif
) 
 

_rwDMAAddPkt2 adds a chain-tte channel 1 DMA chain and a channel 2 chain to the dispatch list. These will be dispatched together with GS path 3 initially masked to allow interrupt free texture synchronization.

If a packet is open, it will be closed and added before the chains passed to this function.

Warning:
These chains must be correctly formed, that is have a suitable end tag. A buffer swap may occur before these packets are added to the dispatch list, unless guaranteed by some other function.
Note:
It is not necessary to call this function with packets built using _rwDMAOpenVIFPkt, etc, as these will be automatically added to the dispatch chain when they are closed.
Parameters:
addrVif  Address of the channel 1 DMA chain.
addrGif  Address of the channel 2 DMA chain.
void _rwDMAAddPURef (  RwInt32 *    ptr ) 
 

_rwDMAAddPURef is used to procrastinate an un-ref. This allows reference counting of objects referenced by DMA chains, without causing the chains to be broken by an immediate decrement comand. Typically, the reference count on an object would be incremented with interrupts disabled. With interrupts re-enabled, the decrement count would then be incremented, and if that count becomes 1, then this function would be called.

Warning:
This should only be called when it would be safe to close any currently open packets.
Parameters:
ptr  Pointer to the reference count. (ptr+1) should point to the number by which the reference count should be decremented.
RwBool _rwDMACallbackRestart (  void    ) 
 

_rwDMACallbackRestart is used to restart dispatch after a callback that took too long to execute with interrupts disabled.

Returns:
Returns TRUE if successful, or FALSE if dispatching had not been suspended by a callback.
void _rwDMAClosePkt (  void    ) 
 

_rwDMAClosePkt is used to close packets opened by _rwDMAOpenVIFPkt, etc. It will add a closing end tag to the open packets and fixup if required. It adds the just closed packet to the dispatch chain, and flushes any outstanding procrastinated un-ref to the dispatch list. It may be safely called even if no packets are open.

Note:
There are very few reasons to call this function. RenderWare Graphics will try hard to join packets of suitable types if a succession of open functions are called, which will result in more efficient dispatch and fewer interrupts per frame. SPR will be free after this call on the completion of dma from SPR. RWDMA_SPR_WAIT_ON_FROM() can be used to test this. To free SPR without closing a currently open packet, call _rwDMADMAPktAllocHigh with a size of zero.
RwUInt128* _rwDMADMAAlloca (  RwUInt32    size,
RwBool    sprFlush
) 
 

_rwDMADMAAlloca is used to allocate space in the current DMA build buffer when no packets are open. It is guaranteed that there will be space to call _rwDMAAddPkt or _rwDMAAddPkt2 after the space is allocated without a buffer swap occurring, so this function can be used to allocate space in which temporary dispatchable data will be placed.

The resultant block will be cache aligned and not in cache.

Parameters:
size  Size of block required in bytes.
sprFlush  If TRUE, flush any packet data from SPR so that it may be used until the next packet construction macro or function is called.
Returns:
Returns a pointer to RwUInt128 indicating the block, or NULL if too big a block was requested.
RwUInt128* _rwDMADMAPktAllocHigh (  RwUInt32    size,
RwBool    sprFlush
) 
 

_rwDMADMAPktAllocHigh is used to allocate some space in the current DMA chain build space, outside of a currently open packet. It is used by _rwDMAAddImageUpload to allocate space for the parallel channel 2 chain which needs to be built while a partially constructed channel 1 chain is being built. Immediate mode constructs a temporary dispatch buffer using the function which it then calls from the open channel 1 chain. This function is a convient way of overcomming the RWDMA_SPR_MAX_PKT_SIZE limit on the size of packet segments.

It can only be called if a packet is currently open. The resultant block will be cache aligned and not in cache.

Warning:
This function should only be called when it would be safe to terminate any partially constructed packet, as it will cause a call to _rwDMAClosePkt if it runs out of memory in the current buffer. It will re-open a packet of the correct type and size if it is forced to close the current packet and swap buffers.
Parameters:
size  Size of requested block in bytes.
sprFlush  If TRUE, flush any packet data from SPR so that it may be used until the next packet construction macro or function is called.
Returns:
Returns a pointer to RwUInt128 indicating the block, or NULL if too big a block was requested.
void _rwDMAForceBufferSwap (  void    ) 
 

_rwDMAForceBufferSwap closes any open packets, flushes them from SPR and starts the dispatch of the buffered dispatch list. It sets up the other buffer for use and returns. If a dispatch is already in progress when this function is called, the function will block until the dispatching buffer drains, so calling this function twice in succession will guarantee that all data has dispatched.
void _rwDMAMinVsyncCntSet (  RwUInt8    minCnt ) 
 

_rwDMAMinVsyncCntSet is used to specify the minimum number of of VSYNCs that must occur before a frame flip will be processed. This can be used to lock an application to a maximum frame rate.

Note:
This defaults to 0 and is reset on RwEngineStop
Parameters:
minCnt  Minimum count
RwBool _rwDMAOpenGIFPkt (  RwUInt32    size ) 
 

_rwDMAOpenGIFPkt is use to open/extend a channel 2 DMA packet. The packet will be transfered in chain mode. When initially opened, the packet will be 128-16 byte aligned for maximum transfer speed.

Once opened, RWDMA_ADD_TO_PKT may be used to add quad words to the packet. Packets are built in SPR and flushed to the chain as required.

Warning:
A valid DMA chain should be written before other _rwDMA* functions are called.
Parameters:
size  Number of quad words required.
Returns:
Returns TRUE if successful, or FALSE if too big a packet was requested.
RwBool _rwDMAOpenVIFPkt (  RwUInt32    type,
RwUInt32    size
) 
 

_rwDMAOpenVIFPkt is use to open/extend a channel 1 DMA packet. The packet will be transfered with tag transfer enabled. If a type of RWDMA_FIXUP is specified, the system will allocate space for a DMA tag with a DIRECT command in its top word, and will fix this up when the packet is closed or the type of open packet is changed. If not, all DMA tags must be provided with the data. When initially opened, the packet will be 128 byte aligned for maximum transfer speed.

Once opened, RWDMA_ADD_TO_PKT may be used to add quad words to the packet. Packets are built in SPR and flushed to the chain as required.

Warning:
The packet must not contain any end tags. The packet must not contain any MSKPATH3 commands. If the packet contains any path 2 image transfers, these must be prefixed with a FLUSHA. It may also be necessary to set _rwDMAGateSlot to NULL in this case to prevent a parallel image transfer being promoted to before the path 2 image transfer and so being overwritten by it. A valid DMA chain should be written before other _rwDMA* functions are called.
Parameters:
type  0 for a chain-tte packet or RWDMA_FIXUP for path 2 data.
size  Number of quad words required.
Returns:
Returns TRUE if successful, or FALSE if too big a packet was requested.
RwBool _rwDMAPreAlloc (  RwUInt32    size,
RwUInt16    puRefSize,
RwUInt128 *    optionalBuf
) 
 

_rwDMAPreAlloc is used to specify the size of the buffer and the maximum number of outstanding procrastinated un-refs. It can optionally be used to specify an area of memory to be used by the system, rather than having it malloc a block.

The single block currently defaults to 1Mb in size with a maximum of 1k outstanding procrastinated un-refs.

Note:
If used, this function must be called before RwEngineStart. Calling RwEngineStop will reset the values to their defaults.
Parameters:
size  Either the size of the block to be allocated and used, or the size of the block pointed to by optionalBuf, in bytes.
puRefSize  Maximum number of outstanding procrastinated un-refs.
optionalBuf  NULL, or a pointer to a buffer of size bytes which is 128 byte aligned for the system to use.
Returns:
Returns TRUE if successful, or FALSE if the system has already started or the parameter values are incorrect.
void _rwDMAYieldCallbackSet (  rwDMAYieldCallback    callback ) 
 

_rwDMAYieldCallbackSet sets a callback to be called from _rwDMAForceBufferSwap. This permits free CPU to be yielded to the application when the library would normally block, and monitoring of the amount of free space in the dma dispatch space.

Note:
This defaults to NULL and is reset on RwEngineStop
Parameters:
callback  The callback

Variable Documentation

rwDMA_flipData _rwDMAFlipData
 

_rwDMAFlipData is used to hold data about the video mode used by the VSYNC handler to flip frames.

Warning:
To get access to this, libgraph.h has to have been included before rwcore.h.
_rwDMAGateSlot
 

_rwDMAGateSlot points to the location of the current gate slot for parallel texture upload. It is used by _rwDMAAddImageUpload. It may be necessary to set it to NULL to prevent a parallel upload overlapping part of a channel 1 transfer. To mark a safe point to start a parallel upload, insert a count 0 DMA tag in the channel 1 chain, and make this variable point to it.
Criterion Software © 1993-2003 Criterion Software Limited. All rights reserved. Built Tue Apr 22 12:46:23 2003. Send Feedback
Converted from CHM to HTML with chm2web Pro 2.85 (unicode)