HALDeviceSysPeri_DMAC (Rev #1, changes)

Showing changes from revision #0 to #1: 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.

Support in RISC OS

HALDeviceSysPeri_DMAC is supported by the trunk branch of the DMAManager module.

Known implementations

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