gba/book/src-bak/03-dma.md

# Direct Memory Access

The GBA has four Direct Memory Access (DMA) units that can be utilized. They're
mostly the same in terms of overall operation, but each unit has special rules
that make it better suited to a particular task.

**Please Note:** TONC and GBATEK have slightly different concepts of how a DMA
unit's registers should be viewed. I've chosen to go by what GBATEK uses.

## General DMA

A single DMA unit is controlled through four different IO Registers.

* **Source:** (`DMAxSAD`, read only) A `*const` pointer that the DMA reads from.
* **Destination:** (`DMAxDAD`, read only) A `*mut` pointer that the DMA writes
  to.
* **Count:** (`DMAxCNT_L`, read only) How many transfers to perform.
* **Control:** (`DMAxCNT_H`, read/write) A register full of bit-flags that
  controls all sorts of details.

Here, the `x` is replaced with 0 through 3 when utilizing whichever particular
DMA unit.

### Source Address

This is either a `u32` or `u16` address depending on the unit's assigned
transfer mode (see Control). The address MUST be aligned.

With DMA0 the source must be internal memory. With other DMA units the source
can be any non-`SRAM` location.

### Destination Address

As with the Source, this is either a `u32` or `u16` address depending on the
unit's assigned transfer mode (see Control). The address MUST be aligned.

With DMA0/1/2 the destination must be internal memory. With DMA3 the destination
can be any non-`SRAM` memory (allowing writes into Game Pak ROM / FlashROM,
assuming that your Game Pak hardware supports that).

### Count

This is a `u16` that says how many transfers (`u16` or `u32`) to make.

DMA0/1/2 will only actually accept a 14-bit value, while DMA3 will accept a full
16-bit value. A value of 0 instead acts as if you'd used the _maximum_ value for
the DMA in question. Put another way, DMA0/1/2 transfer `1` through `0x4000`
words, with `0` as the `0x4000` value, and DMA3 transfers `1` through `0x1_0000`
words, with `0` as the `0x1_0000` value.

The maximum value isn't a very harsh limit. Even in just `u16` mode, `0x4000`
transfers is 32k, which would for example be all 32k of `IWRAM` (including your
own user stack). If you for some reason do need to transfer more than a single
DMA use can move around at once then you can just setup the DMA a second time
and keep going.

### Control

This `u16` bit-flag field is where things get wild.

* Bits 0-4 do nothing
* Bit 5-6 control how the destination address changes per transfer:
  * 0: Offset +1
  * 1: Offset -1
  * 2: No Change
  * 3: Offset +1 and reload when a Repeat starts (below)
* Bit 7-8 similarly control how the source address changes per transfer:
  * 0: Offset +1
  * 1: Offset -1
  * 2: No Change
  * 3: Prohibited
* Bit 9: enables Repeat mode.
* Bit 10: Transfer `u16` (false) or `u32` (true) data.
* Bit 11: "Game Pak DRQ" flag. GBATEK says that this is only allowed for DMA3,
  and also your Game Pak hardware must be equipped to use DRQ mode. I don't even
  know what DRQ mode is all about, and GBATEK doesn't say much either. If DRQ is
  set then you _must not_ set the Repeat bit as well. The `gba` crate simply
  doesn't bother to expose this flag to users.
* Bit 12-13: DMA Start:
  * 0: "Immediate", which is 2 cycles after requested.
  * 1: VBlank
  * 2: HBlank
  * 3: Special, depending on what DMA unit is involved:
    * DMA0: Prohibited.
    * DMA1/2: Sound FIFO (see the [Sound](04-sound.md) section)
    * DMA3: Video Capture, intended for use with the Repeat flag, performs a
      transfer per scanline (similar to HBlank) starting at `VCOUNT` 2 and
      stopping at `VCOUNT` 162. Intended for copying things from ROM or camera
      into VRAM.
* Bit 14: Interrupt upon DMA complete.
* Bit 15: Enable this DMA unit.

## DMA Life Cycle

The general technique for using a DMA unit involves first setting the relevent
source, destination, and count registers, then setting the appropriate control
register value with the Enable bit set.

Once the Enable flag is set the appropriate DMA unit will trigger at the
assigned time (Bit 12-13). The CPU's operation is halted while any DMA unit is
active, until the DMA completes its task. If more than one DMA unit is supposed
to be active at once, then the DMA unit with the lower number will activate and
complete before any others.

When the DMA triggers via _Enable_, the `Source`, `Destination`, and `Count`
values are copied from the GBA's registers into the DMA unit's internal
registers. Changes to the DMA unit's internal copy of the data don't affect the
values in the GBA registers. Another _Enable_ will read the same values as
before.

If DMA is triggered via having _Repeat_ active then _only_ the Count is copied
in to the DMA unit registers. The `Source` and `Destination` are unaffected
during a Repeat. The exception to this is if the destination address control
value (Bits 5-6) are set to 3 (`0b11`), in which case a _Repeat_ will also
re-copy the `Destination` as well as the `Count`.

Once a DMA operation completes, the Enable flag of its Control register will
automatically be disabled, _unless_ the Repeat flag is on, in which case the
Enable flag is left active. You will have to manually disable it if you don't
want the DMA to kick in again over and over at the specified starting time.

## DMA Limitations

The DMA units cannot access `SRAM` at all.

If you're using HBlank to access any part of the memory that the display
controller utilizes (`OAM`, `PALRAM`, `VRAM`), you need to have enabled the
"HBlank Interval Free" bit in the Display Control Register (`DISPCNT`).

Whenever DMA is active the CPU is _not_ active, which means that
[Interrupts](05-interrupts.md) will not fire while DMA is happening. This can
cause any number of hard to track down bugs. Try to limit your use of the DMA
units if you can.