Reality Display Processor/Interface: Difference between revisions

RDP executes a stream of commands called ''primitives'' that are sent to it via DMA. The RDP interface allows to initiate and monitor the DMA transfers to RDP, and to query the current status of RDP.

DMA transfers allow to send a sequence of primitivescommands from RDRAM or DMEM to the RDP. When a DMA is triggered the RDP will start fetching the primitivescommands in small batches withininto an internal commandFIFO bufferqueue, from which they will get run; the DMA will then wait for space to become available in this internal command bufferFIFO before more data can be transferred.

PrimitivesCommands can be stored in either RDRAM or DMEM. Bit 0 of DP_STATUSDPC_STATUS is used to select whether RDRAM or DMEM is used. When reading data from DMEM, the RDP uses an internal bus in the RCP called XBUS, so normally "using XBUS" is a shorthand expression for "programming the RDP to fetch primitivescommands from DMEM". Notice that both VR4300 and RSP can program the RDP to either use XBUS or not; there is no correlation between the CPU programming the RDP and the data source being used.

The RDP is a highlydeeply parallelpipelined unit. There is thus no correlation between a DMA being finished and the respective primitivescommands being finished (that is,e.g. pixels drawn into the framebuffer). Instead, the end of DMA can just be used as a signal that the RDRAM/DMEM buffer that stores the primitivescommands can be recycled, but no further information can be deducteddeduced aboutregarding the actual execution of the primitivescommands. A few syncingsynchronization primitivescommands can be used to createguarantee syncingthat pointswork inwill thehave variousbeen completed by the RDP internalbefore parallelthe unitsnext command begins execution; see the SYNCpage primitiveson ofRDP commands for more informationdetails.

RDP primitivescommands are madecomposed of one or multiplemore 64-bit (8 bytesbyte) words. For this reason, RDP DMA must fetch data from an address that is 64-bit aligned: in fact, the lowest 3 bits of the DMA address register are ignored. There is no destination register: the destination is the RDP itself and its internal command bufferFIFO is not addressable in any way.

To allow the RDP to begin processing primitivescommands as soon as they are available (that is, while the VR4300 and RSP are generating them), the RDP DMA allows for incremental transfers: in fact,; the DP_ENDDPC_END register can be updated while a DMA is in progress (or after it has finished) and the effect is that the DMA will continue running until the new end pointer is reached. This operation is totally safe and free of race conditions. The intended purpose is that the VR4300 or the RSP can continue updating the DP_ENDDPC_END register while they add more data to the primitivecommand buffer in RDRAM/DMEM, until it is full., Atat thatwhich point, they can start another transfer to switch to another buffer.

To program a pending DMA transfer, just write to <code>DP_STARTDPC_START</code>/<code>DP_ENDDPC_END</code> a new buffer start/end address. The <code>START_PENDING</code> / <code>END_PENDING</code> bits in <code>DP_STATUSDPC_STATUS</code> will be set to 1, signaling that a transfer is indeed pending. New writes to <code>DP_ENDDPC_END</code> will now update the pending transfer; in other words, after a new DMA transfer is pending, it is not possible to incrementally add more primitivescommands to the currently-running transfer.

* If primitivescommands are already in RDRAM (eg: a static display list of RDP commands, read from ROM), then it is obviously more efficient to send them directly from there, without copying them first to DMEM. Libultra does not support this (in libultra, all RDP primitivescommands are always passed through RSP as they were RSP commands first, causing a double memory bandwidth impact if they are then sent back to RDRAM for RDP DMA); in libdragon, this is supported via [https://github.com/DragonMinded/libdragon/blob/caf684a06096afa3e9fc8ec8e70dd6643dab419e/include/rdpq.h#L1346-L1364 rdpq_exec].

* If primitivescommands are generated by the RSP (eg: triangles at the end of a T&L pipeline), consider the following aspects:

** sending back all the primitivescommands to RDRAM will have an impact on memory bandwidth (first, to transfer them from DMEM to RDRAM, and later from RDRAM to RDP). Memory bandwidth is often a bottleneck on N64.

** on the other hand, RDRAM allows for much larger buffers. When the buffers are small (like they typically are in DMEM), it means that the RSP could be forced to wait for the RDP to process the primitivescommands before producing new ones (basically this is back-pressure from RDP to RSP), and in turns it could cause a back-pressure on the VR4300. Often, RDP is the slowest among the three, so a larger buffer allows for better pacing.

While preparing buffers on RDP primitivescommands, it is useful to take advantage of incremental transfers. This is a possible algorithm:

# Get ready to send the first buffer by setting <code>DP_STARTDPC_START</code> = <code>DP_ENDDPC_END</code> = pointer to the start of the first buffer. This will not actually transfer any byte (remember DP_ENDDPC_END is an ''exclusive'' bound, so if you set <code>DP_STARTDPC_START</code> = <code>DP_ENDDPC_END</code>, this means "0 byte buffer"), but will setup the DMA engine as such.

# Generate RDP primitivescommands into the first buffer (assuming this is RSP, depending whether you are using XBUS or not, either just write them to DMEM, or also DMA them to RDRAM into the first buffer). Any time a new primitivecommand is added to the buffer, write <code>DP_ENDDPC_END</code> to point past it. This basically tells the RDP that there are more primitivescommands to run, as soon as it is ready.

# When the buffer is full, go back to point 2, switching to the next buffer. Notice that the RDP DMA on the first buffer will continue running until all primitivescommands have been fetched, so the new buffer will be effectively pending at this point. Anyway, you can continue working on the new buffer and keep writing <code>DP_ENDDPC_END</code>: this is totally race-free, whether the new transfer is still pending, is ongoing, or even if it is finished.

# Consider that the RDP can only have one transfer pending. So anytime you write <code>DP_STARTDPC_START</code> to switch to a new buffer, first check if another transfer is already pending (by checking if the <code>START_PENDING</code> bit is set in <code>DP_STATUSDPC_STATUS</code>). If it is pending, then you will need to wait for it. This also makes sure you don't start pushing new primitivescommands into the first buffer again, before the previous contents have been fully consumed.

Another possible approach to push primitivescommands into the RDP is using a single buffer, and checking <code>DP_CURRENTDPC_CURRENT</code> to race against the DMA. The idea is using the buffer as a circular one, and have the DMA constantly trailing behind our write pointer.

# Prepare a single buffer (in either DMEM or RDRAM). Write <code>DP_STARTDPC_START</code> = <code>DP_ENDDPC_END</code> = pointer to the start of the buffer. Notice that, as soon as the RDP accepts these register writes, <code>DP_CURRENTDPC_CURRENT</code> will also point there when read.

# Generate RDP primitivescommands and write them into the buffer. Any time a new primitivecommand is written, update <code>DP_ENDDPC_END</code>. At this point, there are no pending DMAs (<code>START_PENDING</code> = 0), and in general we will have that <code>DP_STARTDPC_START</code> <= <code>DP_CURRENTDPC_CURRENT</code> <= <code>DP_ENDDPC_END</code>. To visualize this, remember that <code>DP_CURRENTDPC_CURRENT</code> is basically the "read pointer", while <code>DP_ENDDPC_END</code> is our "write pointer", within the same circular buffer.

# When we reach the end of the buffer, schedule a new DMA transfer on the same buffer from the beginning (so again <code>DP_STARTDPC_START</code> = <code>DP_ENDDPC_END</code> = pointer to the start of the buffer). At this point, this second transfer will be pending (<code>START_PENDING</code> = 1), but the RDP DMA will probably be still going through the buffer on the first time. So at this point we have <code>DP_STARTDPC_START</code> <= <code>DP_ENDDPC_END</code> < <code>DP_CURRENTDPC_CURRENT</code>. Notice in fact that reading <code>DP_STARTDPC_START</code> and <code>DP_ENDDPC_END</code> will return the ''pending'' values (the new run on the buffer), while <code>DP_CURRENTDPC_CURRENT</code> will still report the currently running transfer, and will keep going until the end of the buffer.

# Keep writing primitivescommands from the start of the buffer. This time, though, make sure that you never write past the current value of <code>DP_CURRENTDPC_CURRENT</code>. If you need to write a primitivecommand but you have reached the current value of <code>DP_CURRENTDPC_CURRENT</code>, it means that you risk overwriting primitivescommands that have not been sent to RDP yet. So in this case, you will need to throttle (wait) for a bit.

# As soon as the RDP has finished going through the buffer, it will run the pending transfer and thus start from the beginning of the buffer again. After this happens (you can check it with <code>START_PENDING</code> becoming 0), you can freely go through the buffer writing primitivescommands, without checking <code>DP_CURRENTDPC_CURRENT</code> anymore. In fact, at this point we are back to the initial situation in which <code>DP_STARTDPC_START</code> <= <code>DP_CURRENTDPC_CURRENT</code> <= <code>DP_ENDDPC_END</code> so it is possible to keep writing until the end of the buffer.

In general, the second algorithm is more complex and requires a bit more code to be implemented, but it allows for less throttling and more efficient use of the memory. In fact, in the first scenario, whenever we have filled the available memory (two buffers) and we throttle, we will need to wait until the RDP finishes processing the whole first buffer. In the second scenario, instead, throttling is much reduced because as soon as the RDP processes one primitivecommand, we get room for one more primitivecommand to write.

|[[Reality Display Processor/Interface#DPDPC START|DP_STARTDPC_START]]

| Start address in RDRAM / DMEM for a DMA transfer of RDP primitivescommands

|[[Reality Display Processor/Interface#DPDPC END|DP_ENDDPC_END]]

|End address in RDRAM / DMEM for a DMA transfer of RDP primitivescommands (exclusive bound)

|[[Reality Display Processor/Interface#DPDPC CURRENT|DP_CURRENTDPC_CURRENT]]

|[[Reality Display Processor/Interface#DPDPC STATUS|DP_STATUSDPC_STATUS]]

====<span style="display:none;">0x0410 0000 (c8) - DP_STARTDPC_START ====

----{{#invoke:Register table|head|800px|DP_STARTDPC_START <code>0x0410 0000</code> (<code>c8</code>) }}

| 23-0 | START[23:0] | Physical address of the start of the primitivecommand bufferlist in RDRAM or DMEM. When reading, it always returns the last written value.

:'''START''' This address points to the beginning of the primitivecommand bufferlist from which primitivesRDP commands will be fetched by the DMA. After writing this register, the address is latched into the RDP interface, and the <code>START_PENDING</code> bit in <code>DP_STATUSDPC_STATUS</code> becomes 1, but no transfer is started. Writing <code>DP_ENDDPC_END</code> will actually initiate the transfer. Selection of the data source (RDRAM or DMEM) is controller by bit 0 of <code>DP_STATUSDPC_STATUS</code>. Writing <code>DP_STARTDPC_START</code> while another value is pending (<code>START_PENDING</code> is 1) will update the pending value. Notice though that this is a risky operation because of races: the pending transfer could in fact start at any point, and if you write a new pending value just before or just after the transfer starts, the behavior will be totally different; in general, it is better to avoid writing <code>DP_STARTDPC_START</code> if <code>START_PENDING</code> is 1.

====<span style="display:none;">0x0410 0004 (c9) - DP_ENDDPC_END ====

----{{#invoke:Register table|head|800px|DP_ENDDPC_END <code>0x0410 0004</code> (<code>c9</code>)}}

| 23-0 | END[23:0] | Physical address of the end of the primitivecommand bufferlist (in RDRAM or DMEM). When reading, it always returns the last written value.

:'''END''' This address points to the end of the primitivecommand bufferlist. The address is interpreted as an exclusive bound, so it must point ''after'' the last primitivecommand to transfer. Notice that writing <code>DP_STARTDPC_START</code>=<code>DP_ENDDPC_END</code> is well formed, and will run a perfectly valid zero byte transfer (which can later extended via an incremental transfer).

When <code>DP_ENDDPC_END</code> is written, the RDP does the following:

* ifIf <code>START_PENDING</code> (in <code>DP_STATUSDPC_STATUS</code>) is 0, the write is considered an "incremental transfer", so the RDP DMA is programmed to continue the last transfer up to the new value of <code>DP_ENDDPC_END</code>. This works whether the previous transfer is still running or was already finished; in both cases, the transfer is continued/restored until the new <code>DP_ENDDPC_END</code> is reached;

* ifIf <code>START_PENDING</code> (in <code>DP_STATUSDPC_STATUS</code>) is 1, the behavior depends on whether a transfer is running or not:

** if no transfer is running, the new transfer is started (from <code>DP_STARTDPC_START</code> to <code>DP_ENDDPC_END</code>), and <code>START_PENDING</code> goes back to 0.

**if a transfer is in progress, <code>END_PENDING</code> is set to 1 and the new transfer remains pending and will start as soon as the current transfer is finished. Further writes to <code>DP_ENDDPC_END</code> in this state will simply update the pending transfer's end address.

'''WARNING''': doDo not start a DMA transfer or even process any primitivecommand if you have previously enqueued a <code>SYNC_FULL</code> primitivecommand. There is a RDP hardware bug that makes RDP sometimes crash if any other primitivecommand is processed while <code>SYNC_FULL</code> is run. Thus, when you schedule a <code>SYNC_FULL</code> (usually at the end of the frame), it must be the last scheduled primitivecommand (<code>DP_ENDDPC_END</code> must point immediately after it), and you must wait until the RDP has processed it and got back to fully idle status (<code>BUSY</code> bit goes to 0 in <code>DP_STATUSDPC_STATUS</code>), before starting a new DMA transfer, even just an incremental one. It is fine to just write <code>DP_STARTDPC_START</code> though, as that doesn't start a transfer.

====<span style="display:none;">0x0410 0008 (c10) - DP_CURRENTDPC_CURRENT ====

----{{#invoke:Register table|head|800px|DP_CURRENTDPC_CURRENT <code>0x0410 0008</code> (<code>c10</code>)}}

:'''CURRENT''' This address points after the last primitivecommand that was transferred by DMA. It is possible to monitor this register to know how far the transfer has gone. In general, it is expected that <code>DP_STARTDPC_START</code> <= <code>DP_CURRENTDPC_CURRENT</code> <= <code>DP_ENDDPC_END</code>, and thus the portion of the buffer between <code>DP_STARTDPC_START</code> and <code>DP_CURRENTDPC_CURRENT</code> is free to be recycled for other uses. When a transfer is finished, <code>DP_CURRENTDPC_CURRENT</code> will always be equal to <code>DP_ENDDPC_END</code>. Notice that when <code>START_PENDING</code> or <code>END_PENDING</code> are 1, reading <code>DP_STARTDPC_START</code> and <code>DP_ENDDPC_END</code> will return the pending values, while reading <code>DP_CURRENTDPC_CURRENT</code> will always refer to the currently running (or last finished) transfer.

====<span style="display:none;">0x0410 000C (c11) - DP_STATUSDPC_STATUS ====

----{{#invoke:Register table|head|800px1400px|DP_STATUSDPC_STATUS <code>0x0410 000C</code> (<code>c11</code>) - Read access}}

| READYCBUF_READY || BUSY || PIPE_BUSY || TMEM_BUSY || START_GCLK || FLUSH || FREEZE || XBUS

| 10 | START_PENDING | Set if DP_STARTDPC_START was written and the value is still pending because DP_ENDDPC_END was not written yet, or another transfer is in progress (see DP_STARTDPC_START and DP_ENDDPC_END).

| 9 | END_PENDING | Set if DP_ENDDPC_END was written and the value is still pending because another transfer is in progress (see DP_ENDDPC_END)

| 7 | READYCBUF_READY | ?

| 6 | BUSYBUF_BUSY | Becomes 1 as soon as a DMA transfer starts, and stays to 1 until a <code>SYNC_FULL</code> primitivecommand is run.

| 1 | FREEZE | While set, RDP will stop processing primitivescommands

{{#invoke:Register table|head|1200px1400px|DPC_STATUS <code>0x0410 000C</code> (<code>c11</code>) - Write access}}

| CLR_PIPE_BUSY || CLR_TMEM_BUSY || SET_FLUSH || CLR_FLUSH || SET_FREEZE || CLR_FREEZE || SET_SOURCESET_XBUS || CLR_SOURCECLR_XBUS

| 9 | CLR_CLOCK | Reset the `DP_CLOCK`'''DPC_CLOCK''' to zero.

| 8 | CLR_BUFFER_BUSY | ?Reset '''DPC_BUSY''' to zero.

| 7 | CLR_PIPE_BUSY | ?Reset '''DPC_PIPE_BUSY''' to zero.

| 6 | CLR_TMEM_BUSY | ?Reset '''DPC_TMEM_BUSY''' to zero.

:'''FREEZE''' During freeze, the RDP DMA engine is suspended (paused). If a transfer was ongoing, it is paused and will resume as soon as the freeze bit is reset to 0. During the freeze, it is still possible to write DP_STARTDPC_START or DP_ENDDPC_END, and the writes will still affect the START_PENDING / END_PENDING bits, but no transfer will be initiated.

:'''BUSY''' This bit seems to refer to a more general state of RDP, which is not related to actually performing any task. When the bit is 0, the RDP is like "turned off". As long as a single primitivecommand is sent to RDP, this bit goes to 1 and will stay there even if after that single primitivecommand, you wait for seconds, far beyond the actual execution time of that primitivecommand. It looks like the RDP is now "turned on". To turn it off again, the only known way is sending a SYNC_FULL. After processing a SYNC_FULL, the BUSY bit goes back to 0 again.

====<span style="display:none;">0x0410 0010 (c12) - DP_CLOCKDPC_CLOCK ====

----{{#invoke:Register table|head|1200px|DP_CLOCKDPC_CLOCK <code>0x0410 0010</code> (<code>c12</code>)}}

:'''CLOCK''' This register accesses a read-only 24-bit clock that runs at the RCP frequency (which is 62.5 Mhz on standard N64, and 96 Mhz on iQue). The counter starts ticking from boot and does not stop (not even if you freeze the RDP via the `FREEZE` bit in `DP_STATUSDPC_STATUS`). The only possible interaction from the CPU/RSP is to reset it to 0 by writing the `CLR_CLOCK` bit in `DP_STATUSDPC_STATUS`. Being the only counter available directly from RSP, it can be useful to perform benchmarks on it.

====<span style="display:none;">0x0410 0014 (c13) - DPC_BUSYDPC_BUF_BUSY ====

----{{#invoke:Register table|head|1200px|DPC_BUSYDPC_BUF_BUSY <code>0x0410 0014</code> (<code>c13</code>)}}

| colspan=8|BUSYBUF_BUSY[23:16]

| colspan=8|BUSYBUF_BUSY[15:08]

| colspan=8|BUSYBUF_BUSY[7:0]

| 23-0 | BUSYBUF_BUSY[23:0] | ?

====<span style="display:none;">0x0410 0018 (c14) - DPC_PIPE_BUSY ====

----{{#invoke:Register table|head|1200px|DPC_PIPE_BUSY <code>0x0410 0018</code> (<code>c14</code>)}}

====<span style="display:none;">0x0410 001C (c15) - DPC_TMEM_BUSY ====

----{{#invoke:Register table|head|1200px|DPC_TMEM_BUSY <code>0x0410 001C</code> (<code>c15</code>)}}