#include <revolution/gx.h> volatile void* GXRedirectWriteGatherPipe( void * ptr );
| ptr | A pointer to a 32-byte aligned target buffer. |
|---|
The actual address of the write gather port. All writes to this address are collected to the write gather pipe. The GXWGFifo union can also be used. If the GXWGFifo union is not used, be certain the local variables are volatile. Failure to do so can result in an optimization exception when the compiler is writing to the same pointer.
This high-level API temporarily redirects the write gather pipe to a new location. Ordinarily, the GX library sets up the write gather pipe to efficiently write command data to memory.
After calling this function, subsequent writes to the address returned by this function (the GXWGFifo union) will be gathered and sent to a destination buffer. The write pointer is automatically incremented by the GP. The write gather pipe can be restored by calling the GXRestoreWriteGatherPipe function. This function cannot be called between a GXBegin and GXEnd function pair. No GX commands can be called until the write gather pipe is restored. You must call the GXRestoreWriteGatherPipe function before calling this function again.Otherwise, the final call to restore the pipe will fail.
The destination buffer, referred to by (the 32-byte aligned) ptr, must be 32-byte aligned. The amount of data written should also be 32-byte aligned. If it is not, zeroes will be added to pad the destination buffer to 32 bytes. No part of the destination buffer should be modified inside the CPU caches - this may introduce cache incoherency problems. After the 32 bytes of data are written, the destination buffer referenced by ptr is automatically incremented by GP to point to the next 32-byte address. It is therefore unnecessary for applications to increment the destination buffer address when transferring continuous data.
The write gather pipe is one of the fastest ways to move data out of the CPU (the other being the locked cache DMA). In general, you are compute-bound when sending data from the CPU. In our tests, we have achieved approximately 1.12 GB/s sustained bandwidth to write trivial data with this API (assuming full speed external bus; on 75% systems, expect about 858 MB/s).Note: In DEBUG builds, expect only half of the bandwidth performance because the compiler will generate extraneous loads.
This function is more economical than creating a fake CPU FIFO in a send destination buffer, which requires calls to the GXSetCPUFifo and GXInitFifoBase functions. This function performs very lightweight state saves by assuming that the CPU and GP FIFOs never change. The GXRedirectWriteGatherPipe function calls the GXFlush function. Therefore, there is no need to explicitly call the GXFlush function after you have executed the GXRedirectWriteGatherPipe function.
2008/05/26 Added the fact that ptr is incremented automatically.
2008/05/12 Added mention that GXFlush is included.
2006/03/01 Initial version.
CONFIDENTIAL