# MI_SendGXCommand

## C Specification

      #include <nitro/mi.h>

      void MI_SendGXCommand(
                u32       dmaNo,
          const void*     src,
                u32       commandLength );

      void MI_SendGXCommandAsync(
                u32       dmaNo,
          const void*     src,
                u32       commandLength,
          MIDmaCallback   callback,
                void*     arg );

## Description

This function uses DMA to send a display list (GX command string) to command FIFO. The transfer source address must be 4-byte aligned.

The synchronous version of `MI_SendGXCommand()` ends DMA inside the function. The asynchronous version of `MI_SendGXCommandAsync()` uses a callback function when DMA ends. The callback function is an `MIDmaCallback` type function (a `void` type function with a `void*` type argument).

For `MI_SendGXCommandAsync()`, specifying `NULL` for callback is the equivalent of calling the synchronous version of `MI_SendGXCommand()`.

The difference between `MI_SendGXCommandAsync()` and `MI_SendGXCommandAsyncFast()`:

- `MI_SendGXCommandAsync()` does not use the Geometry transfer DMA but uses only the usual synchronous DMA. A small amount of DMA is performed by using the interrupt that is generated when GXFIFO is less than half.
- `MI_SendGXCommandAsyncFast()` uses the Geometry transfer DMA, so that DMA starts automatically when GXFIFO becomes low.

Note that multiple automatic DMAs cannot be used simultaneously because of hardware restrictions. However, the hardware allows the simultaneous startup of multiple automatic DMAs of the same type.

With NITRO-SDK, the exclusion process of `MI_SendGXCommandAsync()` with other `G3_` type API is not performed because of the priority of operation speed of the graphics command. Therefore, we cannot guarantee correct operation if the GX command is written directly to command FIFO by a `G3_` function while the GX command is being transferred by `MI_SendGXCommandAsync()`. It is strongly recommended that you pay particular attention in avoiding such a situation on the API call side.

## Internal Operation

Uses the following IO registers: DMAn source register (0x40000B0 + 12n), DMAn destination register (0x40000B4 + 12n), and DMAn control register (0x40000B8 + 12n). (n is the DMA channel used.) The `GXFIFO(0x4000400)` IO register is also accessed.

## Arguments

`dmaNo` | DMA channel used
`src` | Transmit source address
`commandLength` | Transmit command size
`callback` | Callback when DMA ends
`arg` | Callback argument when DMA ends

## Return Values

None

## See Also

`MI_DmaCopy*`, `G3_BeginMakeDL`, `G3_EndMakeDL`

## Revision History

08/26/2004 Added description for `MI_SendGXCommandAsyncFast`
07/18/2004 Added description when the callback is NULL
12/01/2003 Initial version