HALDeviceAudio_AudC (changes)

Showing changes from revision #6 to #7: Added | Removed | Changed

Hardware Abstraction Layer

» HAL Device API

» List of HAL devices

» 16-bit sound input/output controller

16-bit sound input/output controller

(HALDeviceAudio_AudC)

Device API

API versions 0, 1 1, and 2 and 3 are currently defined.

API version 0

API version 0 is a simplistic version of the API, where most of the work is performed directly by the SoundDMA module.

struct haldeviceaudio_audc
{
    struct device;
    struct haldeviceaudio_mixer *mixer;
    unsigned int channels_out;
    unsigned int channels_in;
}

mixer points to the mixer device associated with this sound output device. channels_out and channels_in contain the number of output and input channels supported by the device.

API version 1

API version 1 extends the haldevice_audc struct, allowing the HAL device to implement all the device-specific functionality that was previously in SoundDMA.

struct haldevice_audc_1
{
  /* Version 0 interface */
  struct haldevice_audc dev;

  /* 1.0 extension */
  uint32_t dmaparams[5];
  void (*PreEnable)(struct haldevice_audc_1 *, uint32_t dmabufsize);
  void (*PostEnable)(struct haldevice_audc_1 *, uint32_t dmabufsize);
  void (*PreDisable)(struct haldevice_audc_1 *);
  void (*PostDisable)(struct haldevice_audc_1 *);
  uint32_t (*IRQHandle)(struct haldevice_audc_1 *);
  uint32_t numrates;
  struct audioratetable *ratetable;
  void (*SetRate)(struct haldevice_audc_1 *, uint32_t index);
};

The dmaparams array contains the values of R0, R1, R2, R3 and R7 to provide to DMA_RegisterChannel when SoundDMA module registers itself with DMAManager.

The PreEnable and PostEnable calls are made when audio is being enabled. They are both called with IRQs enabled, and with dmabufsize specifying the size of the DMA buffer that is in use (in bytes). The driver should use dmabufsize to program the controller as required, e.g. setting FIFO threshold levels. PreEnable will be called before DMA is enabled, and PostEnable will be called after DMA is enabled.

The PreDisable and PostDisable calls are made when audio is being disabled. As with the Enable calls, IRQs will be enabled, and PreDisable will be called before DMA is disabled, while PostDisable will be called after DMA has been disabled.

If the device specifies an IRQ device number, then IRQHandle will be called whenever an interrupt is received from the device, whether audio is currently enabled or not. The return code of IRQHandle indicates what action the SoundDMA module should take:

numrates specifies the number of entries in the sample rate table. The sample rate table, pointed to by ratetable is an array of audioratetable structures:

struct audioratetable
{
  uint32_t frequency; // Frequency in Hz * 1024
  uint8_t period; // Period in usec
  uint8_t reserved[3]; // Reserved - can be used by audio device
};

The entries in the sample rate table must be in order of increasing frequency.

SetRate is used to set the current sample rate. The index parameter is a 0-based index into ratetable, indicating the sample rate to use. The sample rate will only be modified while audio is turned off.

API version 2

API version 2 extends the haldevice_audc_1 struct, adding support for:

• Devices which don’t use DMAManager for transferring data
• Control over whether stereo reversal is required
• Control over buffer minimum size and alignment/granularity

struct haldevice_audc_2
{
  /* Version 1 interface */
  struct haldevice_audc_1 dev;

  /* 2.0 extension */
  _kernel_oserror *(*CustomDMAEnable)(struct haldevice_audc_2 *dev, uint32_t dmabufsize, void *buff0, void *buff1, void *cbparam, void (*dmacallback)(uint32_t reason,void *cbparam));
  uint32_t Flags;
  uint32_t MinBuffSize;
  uint32_t MinBuffAlign;
};

CustomDMAEnable

CustomDMAEnable is an optional entry, for use by devices which don’t use DMAManager for handling data transfers. If this function is present then behaviour will be as follows:

• PreEnable and PostEnable won’t be called. CustomDMAEnable will be called instead.
• PreDisable and PostDisable will still be called; however as there will be no DMA_TerminateTransfer call between them, there is no difference in specification of the two functions. It’s recommended that PreDisable is implemented to disable sound/DMA, and PostDisable is implemented as a NOP.
• dmaparams will not be used

The buff0 and buff1 arguments to CustomDMAEnable specify the logical addresses of both of the audio buffers. Playback should start with buff0 followed by buff1. dmabuffsize is the size of each buffer.

If CustomDMAEnable is unable to start playback, a standard RISC OS error block can be returned describing the problem.

dmacallback is a callback function that must be called in certain situations:

Currently the only defined reason code is 0. This reason code must be used when a buffer has finished playback and is ready for re-filling by SoundDMA.

The callback function must be called in a privileged processor mode, where it’s safe to call SWIs (i.e. if in IRQ mode, SVC_lr has been preserved by caller). IRQs must be disabled if called in IRQ mode, otherwise IRQ state is unrestricted.

Other features

Flags is a flags word allowing specification of additional properties:

MinBuffSize allows the device to specify the minimum buffer size that it supports, in bytes. MinBuffAlign allows the device to specify the minimum buffer alignment/granularity, in bytes. This value must be a power of 2. Currently there is a maximum value of 4KB for both values.

Support in RISC OS

The Sound0Trid version of the SoundDMA module only supports API version 0.×.

The Sound0HAL version of the SoundDMA module supports API version 1.x and – 2.×. 3.×.

Known implementations

Information sources: Kernel.Hdr.HALDevice, HWSupport.Sound.Sound0Trid.hdr.AudioDevice, HWSupport.Sound.Sound0HAL.hdr.AudioDevice in CVS