HALDeviceSysPeri_DMAC (changes)

Showing changes from revision #2 to #3: Added | Removed | Changed

Hardware Abstraction Layer

» HAL Device API

» List of HAL devices

» DMA controller

(HALDeviceSysPeri_DMAC)

Device API

Currently, only API versions 0, 0.1 and 1 are defined.

API version 0

struct dmacontroller
{
  /* Public interface */
  struct device dev;

  uint32_t (*Features)(struct dmacontroller *);
  __value_in_regs struct { struct dmachannel **channel; uint32_t count; }
      (*Enumerate)(struct dmacontroller *);
  struct dmachannel *(*Allocate)(struct dmacontroller *, uint32_t channel);
  void (*Deallocate)(struct dmacontroller *, uint32_t channel);
};

dev is the standard HAL Device descriptor. The address field is not used. Controllers are activated/deactivated on module initialisation/finalisation. dev.Reset is called on software-initiated OS resets. Interrupts are ignored – provide them using the DMA channel device instead.

Features returns a flag word indicating the capabilities of the controller. Currently no bits are defined; all bits should be zero.

Enumerate returns a static list of available physical DMA channel devices (Pointers to DMA buffer or DMA list devices)

Allocate returns a pointer to the physical DMA channel struct to associate with the given logical DMA channel. If the hardware requires a particular logical-physical mapping, this will be obeyed; otherwise one will be allocated at the whim of the software (typically: physical channels grouped according to priority of logical channel, then within each group logical channels are allocated on a one-to-one mapping until no physical channels remain, after which logical channels are arbitrarily doubled up). Return value NULL => this logical channel not supported on this controller

Recommended DMA priorities:

• High: sound DMA
• Medium: other device DMA
• Low: memory-to-memory DMA

Deallocate is the partner of Allocate, this lets the device know that a particular logical channel is no longer being used.

API version 0.1

API version 0.1 extends the dmacontroller struct:

struct dmacontroller_0_1
{
  /* Version 0 interface */
  struct dmacontroller dev;

  /* 0.1 extension */
  int32_t TestIRQ2(struct device *);
}

The TestIRQ2 function allows the controller to take on the role of identifying which physical DMA channel is the cause of the current interrupt. This is useful in situations where all the physical DMA channels share the same IRQ number, and the DMA controller contains a flag word indicating which channel(s) are currently interrupting.

If TestIRQ2 is provided, then the following rules must be followed:

• The dev.dev.devicenumber field must specify the device (IRQ) number of the controller.
• All channels returned by Enumerate must be of the same type (e.g. all buffer-type or all list-type)
• All channels returned by Enumerate must still provide their dev.devicenumber and dev.TestIRQ entries.
• All channels must share the same device number (the same as the controller)
  • Note that in the channel devices, bit 31 of devicenumber would typically be set in order to indicate a shared IRQ line. However for the controller bit 31 does not need to be set if the only other devices sharing the same IRQ are the channels belonging to the controller instance.

TestIRQ should return the index of the channel that is interrupting (relative to the list returned by Enumerate), or -1 if no channel is interrupting.

If TestIRQ is not provided, behaviour is as per API version 0.

API version 1

API version 1 refines the specification of Deallocate:

  void (*Deallocate)(struct dmacontroller *, uint32_t channel, struct device *dev);

The dev parameter is a pointer to the channel device that is being deallocated.

Memory barriers

For both list-based and buffer-based DMA channels, it is the responsibility of the HAL device to ensure that the correct data read/write barriers are used where appropriate. Typically this means that:

• Whenever a memory → device transfer is about to be started, a write barrier should be used to ensure that any buffered writes have reached RAM (pages involved in a DMA transfer will never be cacheable, but they will typically be bufferable).
• Whenever the progress of a device → memory transfer is being reported (e.g. TransferState and Status calls), a read barrier should be used to ensure the CPU hasn’t prefetched any stale data from the destination buffer.
• For list-based controllers, the transfer descriptor list will typically be located in bufferable memory, and so barriers will be needed whenever it is being accessed. E.g. a write barrier is needed after the list has been fully populated by the CPU, and if the DMA controller updates the descriptors with progress information then a read barrier should be used before the CPU reads from the descriptors.

The above covers situations where the HAL device should use barriers. The following covers situations where the client (e.g. a DMAManager client) should use barriers:

• If DMA is being used to transfer code, an instruction synchronisation barrier (e.g. ARMv7 ISB instruction) may be required to ensure any stale prefetched instructions are flushed before the new code is executed. Calling OS_SynchroniseCodeAreas for the affected range is a safe and valid method of doing this. Other methods may fail on future systems (e.g. consider a DMA controller which is able to perform cache-coherent DMA to/from the CPU data cache, but not to the instruction cache).
• If the contents of a circular buffer are being updated on-the-fly by the CPU (e.g. audio playback as used by SoundDMA) then it is the responsibility of the client to ensure any freshly written data is flushed to RAM. However, in this case barriers are only likely to be needed in exceptional circumstances – e.g. if the CPU is repeatedly writing to the same location, and the hardware keeps merging the data into the write buffer but never flushing it to RAM.

Support in RISC OS

HALDeviceSysPeri_DMAC is supported by the trunk branch version of theDMAManager module.

Known implementations

Information sources: Kernel.Hdr.HALDevice, HWSupport.DMA.HAL_DMAAPI, HWSupport.DMA.hdr.DMADevice in CVS