1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html> 3 4<head> 5<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 6<META name="GENERATOR" content="Microsoft FrontPage 5.0"> 7<META http-equiv="Content-Style-Type" content="text/css"> 8<LINK rel="stylesheet" type="text/css" href="../../CSS/revolution.css"> 9<title>GXRedirectWriteGatherPipe</title> 10</head> 11 12<body> 13 14<h1 align="left">GXRedirectWriteGatherPipe</h1> 15 16<h2>Syntax</h2> 17<dl><dd><pre class="construction"> 18#include <revolution/gx.h> 19 20volatile void* GXRedirectWriteGatherPipe( void * ptr ); 21</pre></dd></dl> 22 23<H2>Arguments</H2> 24<TABLE class="arguments" border="1" > 25 <TBODY> 26 <TR> 27<TH>ptr</TH> 28<TD>A pointer to a 32-byte aligned target buffer.</TD> 29 </TR> 30 </TBODY> 31</TABLE> 32 33<H2>Return Values</H2> 34<P>The actual address of the write gather port. All writes to this address are collected to the write gather pipe. The <CODE>GXWGFifo</CODE> union can also be used. If the <CODE>GXWGFifo</CODE> 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.</P> 35 36<h2>Description</h2> 37<P>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. </P> 38<P>After calling this function, subsequent writes to the address returned by this function (the <CODE>GXWGFifo</CODE> 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 <A href="GXRestoreWriteGatherPipe.html"><CODE>GXRestoreWriteGatherPipe</CODE></A> function. This function cannot be called between a <CODE>GXBegin</CODE> and <CODE>GXEnd</CODE> function pair. No GX commands can be called until the write gather pipe is restored. You <EM>must</EM> call the <a href="GXRestoreWriteGatherPipe.html"><CODE>GXRestoreWriteGatherPipe</CODE></a> function before calling this function again.</B>Otherwise, the final call to restore the pipe will fail.</P> 39<P>The destination buffer, referred to by (the 32-byte aligned) <SPAN class="argument">ptr</SPAN>, 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 <SPAN class="argument">ptr</SPAN> 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.</P> 40<P>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).<B>Note: In DEBUG builds, expect only half of the bandwidth performance because the compiler will generate extraneous loads</B>.</P> 41<P>This function is more economical than creating a fake CPU FIFO in a send destination buffer, which requires calls to the <A href="GXSetCPUFifo.html"><CODE>GXSetCPUFifo</CODE></A> and <A href="GXInitFifoBase.html"><CODE>GXInitFifoBase</CODE></A> functions. This function performs very lightweight state saves by assuming that the CPU and GP FIFOs never change. The <CODE>GXRedirectWriteGatherPipe</CODE> function calls the <A href="../Management/GXFlush.html"><CODE>GXFlush</CODE></A> function. Therefore, there is no need to explicitly call the <A href="../Management/GXFlush.html"><CODE>GXFlush</CODE></A> function after you have executed the <CODE>GXRedirectWriteGatherPipe</CODE> function.</P> 42 43<h2>See Also</h2> 44<P class="reference"> 45<a href="GXRestoreWriteGatherPipe.html">GXRestoreWriteGatherPipe</a> 46</p> 47 48<H2>Revision History</H2> 49<P> 502008/05/26 Added the fact that <SPAN class="argument">ptr</SPAN> is incremented automatically.<br>2008/05/12 Added mention that <CODE>GXFlush</CODE> is included.<br>2006/03/01 Initial version.<br> 51</P> 52 53<hr><p>CONFIDENTIAL</p></body> 54</HTML>