HALDeviceSysPeri_DMAL (changes)

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

Hardware Abstraction Layer

» HAL Device API

» List of HAL devices

» DMA channel – list type

(HALDeviceSysPeri_DMAL)

Device API

Currently, only API versions 0 and 1 are defined.

API version 0

struct dmalistchannel
{
  /* Public interface */
  struct device dev;
  
  struct dmalistchannelfeatures *(*Features)(struct dmachannel *);
  dmacontroller *controller;
  void (*Abort)(struct dmachannel *);
  void (*SetOptions)(struct dmachannel *, uint32_t flags, uint32_t address);
  void (*SetListTransfer)(struct dmachannel *, uint32_t blockphy,
      void *blocklog, uint32_t nentries, uint32_t length);
  uint32_t (*ListTransferProgress)(struct dmachannel *);
  uint32_t (*ListTransferStatus)(struct dmachannel *);
  uint32_t (*CurtailListTransfer)(struct dmachannel *, uint32_t minimum);
}

dev is the standard HAL Device descriptor. The address field is not used. Channels are activated/deactivated around each transfer (and are deactivated when a transfer is suspended). Interrupts are used to detect transfer termination, and to trigger sync callbacks. If the device provides no interrupt, the device is interrogated from a TickerV routine instead.

dev.Activate, dev.Deactivate_, and_dev.Reset are handled similarly to buffer-type DMA channel

Features returns a pointer to the following data structure:

struct dmalistchannelfeatures
{
  uint32_t flags;
  uint32_t blocksize;
  uint32_t blockalign;
  uint32_t blockbound;
  uint32_t maxtransfers;
  uint32_t transferlimit;
  uint32_t transferbound;
}

Defined flags bits are as followed:

Flag bits not mentioned are reserved and must be set to zero.

Other entries in the structure are as follows:

• blocksize is the amount of memory to allocate for transfer descriptors block.
• blockalign is the required alignment of the transfer descriptors block (0 if none).
• blocklimit is the boundary limitation of transfer descriptors block (0 if none).
• maxtransfers is the maximum number of entries to provide in the transfer descriptors block (note this may differe from blocksize/8 if postprocessing needs to be done before the block is presented to the hardware).
• transferlimit is the maximum amount of data that can be transferred by a single entry in the transfer descriptors block.
• transferbound is the boundary limitation of individual entries in the transfer descriptors block.

controller points to this channel’s DMA controller device

Abort should be considered a “forced” version of dev.Deactivate, and is only used for SWI DMA_TerminateTransfer. The call must not block, but the values subsequently returned from TransferState and Status are allowed to report inaccurate results, providing they underestimate the progress of the transfer.

SetOptions is the same as for buffer-type DMA channel devices, with the addition of one extra flag:

SetListTransfer initiates the transfer according t o the transfer descriptors block:

• blockphy is the physical address of the transfer descritpors block.
• blocklog is the logical address of the transfer descriptors block.
• nentries is the number of entries in the transfer descriptors block.
• length is the total length to transfer, or 0 for infinite transfer.

ListTransferProgress returns the number of bytes transferred since the transfer was initiated. If this cannot be determined exactly, an underestimate should be returned.

ListTransferStatus returns status flags for the current channel:

Other bits are reserved and should be zero.

CurtailListTransfer requests that a transfer in progress be shortened as much as possible subject to normal termination conditions (e.g. raising the TC line). The call need not block. For infinite transfers, there is a minimum requirement that this makes the transfer finite. minimum specifies the minimum number of bytes that must still be transferred (as returned from the DMASync callback). Returns the number of bytes that will have been transferred when the transfer terminates.

API version 1

API version 1 extends the set of flags returned by Features:

Support in RISC OS

HALDeviceSysPeri_DMAL is supported by the trunk branch version of the DMAManager module.DMAManager module.

Known implementations

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