Showing changes from revision #6 to #7:
Added | Removed | Changed
API versions 0, 1 1, and 2 and 3 are currently defined.
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 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:
Return code | Meaning |
---|---|
0 | No action necessary |
1 | Audio reset required (i.e. turn audio off and then on again). This return code has no effect if audio is already off. |
Other values | Reserved |
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 extends the haldevice_audc_1 struct, adding support for:
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 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:
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:
Parameter | Description |
---|---|
reason | Reason code (see below) |
cbparam | cbparam value that was passed to CustomDMAEnable |
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.
Flags is a flags word allowing specification of additional properties:
Bit | Description |
---|---|
0 | Stereo reversal required (Hardware uses L-R-L-R sample ordering instead of VIDC/RISC OS R-L-R-L ordering) |
Other bits reserved, should be 0 |
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.
API version 3 adds support for the following additional features. The device struct is the same as with API version 2.
Bit | Description |
---|---|
1 | For CustomDMAEnable mode: If set, SoundDMA should perform its processing in a synchronous manner from within the dmacallback function, rather than postponing to an RTSupport routine. |
Typically you would set this flag if you need to perform post-processing of the filled buffer on the CPU.
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.×.
Device ID | Description | Implemented in |
---|---|---|
HALDeviceID_AudC_M5451 | Acer M5451 AC’97 controller | HAL.Tungsten.s.Audio |
HALDeviceID_AudC_TPS65950 | TPS65950-compatible audio controller | HAL.OMAP3.s.Audio |
HALDeviceID_AudC_TWL6040 | TWL6040-compatible audio controller | HAL.OMAP4.s.Audio |
HALDeviceID_AudC_VCHIQ | VCHIQ audio service controller | HWSupport.Sound.BCMSound.s.Module |
HALDeviceID_AudC_Pandora | Pandora audio controller | HAL.OMAP3.s.PAudio |