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 17<h2>C Specification</h2> 18 19<dl> 20 <dd><PRE><CODE>#include <revolution/gx.h></CODE></PRE> 21 </dd> 22 <dd><pre><CODE>volatile void* GXRedirectWriteGatherPipe( void * ptr );</CODE></pre> 23 </dd> 24</dl> 25<H2>Arguments</H2> 26<DIV align="left"> 27<TABLE border="1" cellpadding="3" cellspacing="0.1"> 28 <TBODY> 29 <TR> 30 <TD width="120" bgcolor="#ffffe8"><CODE><STRONG><EM>ptr</EM></STRONG></CODE></TD> 31 <TD width="520">A pointer to a 32-byte aligned target buffer.</TD> 32 </TR> 33 </TBODY> 34</TABLE> 35</DIV> 36<H2>Return Values</H2> 37<P>The actual address of the write gather port. All writing to the 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> 38<h2>Description</h2> 39 40<P>This advanced 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> 41<P>After calling this function, subsequent writes to the address returned by this function (or 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 <CODE><A href="GXRestoreWriteGatherPipe.html">GXRestoreWriteGatherPipe</A></CODE>. This function cannot be called between a <CODE>GXBegin</CODE>/<CODE>GXEnd</CODE> pair. <B>Note: No GX commands can be called until the write gather pipe is restored. You <EM>must</EM> call <a href="GXRestoreWriteGatherPipe.html"><CODE>GXRestoreWriteGatherPipe</CODE></a> before calling this function again, or else the final call to restore the pipe will fail.</B></P> 42<P>The destination buffer, referred to by <em><strong>ptr</strong></em>, 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 32B. No part of the destination buffer should be modified inside the CPU caches - this may introduce cache incoherency problems.</P> 43<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). <strong>Note: In DEBUG builds, expect only half of the bandwidth performance because the compiler will generate extraneous loads</strong>.</P> 44<P>This function is more economical than creating a fake CPU FIFO in a send destination buffer, which requires calls to <a href="GXSetCPUFifo.html">GXSetCPUFifo</a> and <a href="GXInitFifoBase.html">GXInitFifoBase</a>. This function performs very light weight state saves by assuming that the CPU and GP fifos never change.</P> 45 46 47<h2>See Also</h2> 48 49<p><a href="GXRestoreWriteGatherPipe.html"><CODE>GXRestoreWriteGatherPipe</CODE></a></p> 50<H2>Revision History</H2> 51<P>2006/03/01 Initial version.</P> 52<hr> 53<P>CONFIDENTIAL</p> 54</BODY> 55</HTML>