A multimedia system is an indispensable part in Internet of Things (IoT) devices. Audio is an important module of the multimedia system, and building an audio driver model is particularly important in device development.
This document describes the audio driver architecture and functional modules and how to develop audio drivers based on the Hardware Driver Foundation (HDF). Chip vendors can develop their own drivers and invocation of Hardware Abstraction Layer (HAL) APIs based on the driver architecture.
This document describes the audio driver architecture and functional modules and how to develop audio drivers based on the Hardware Driver Foundation (HDF). You can develop your own drivers and call Hardware Abstraction Layer (HAL) APIs based on this driver architecture.
## Audio Driver Architecture
The audio driver architecture is implemented based on the [HDF](driver-hdf-overview.md). The audio driver architecture is as follows:
The audio driver framework is implemented based on the [HDF](driver-overview-foundation.md). The following figure illustrates the audio driver architecture.
The driver architecture consists of the following:
- Hardware Device Interface (HDI) adapter: implements the audio HAL driver (HDI adaptation) and provides hardware driver capability interfaces for the audio service (frameworks). The HDI adapter provides interface objects such as Audio Manager, Audio Adapter, Audio Control, Audio Capture, and Audio Render.
- Audio Interface Lib: works with the Audio Driver Model (ADM) in the kernel to control audio hardware, read recording data, and write playback data. The **Stream_ctrl_common** in the Audio Interface Lib interacts with the audio HDI adapter layer.
- ADM: helps system developers to develop scenario-specific applications for the multimedia audio subsystem. With the ADM, codec and DSP device vendors can adapt their driver code based on the unified interfaces provided by the ADM and implement quick development and easy adaptation to the OpenHarmony system.
- Hardware Device Interface (HDI) adapter: implements the audio HAL driver (for HDI adaptation) and provides hardware driver APIs for audio services (frameworks). The HDI adapter provides API objects such as **AudioManager**, **AudioAdapter**, **AudioControl**, **AudioCapture**, and **AudioRender**.
- Audio Interface Lib: works with the Audio Driver Model (ADM) in the kernel to control audio hardware, read recording data, and write playback data. The **Stream_ctrl_common** in the Audio Interface Lib interacts with the Audio HDI Adapter layer.
- ADM: helps system developers to develop scenario-specific applications for the multimedia audio subsystem. With the ADM, codec and DSP device vendors can adapt their driver code based on the APIs provided by the ADM and implement quick development and easy adaptation to the OpenHarmony system.
- Audio Control Dispatch: dispatches the control instructions from the Audio Interface Lib to the driver layer.
- Audio Stream Dispatch: dispatches the data from the Audio Interface Lib to the driver layer.
- Card Manager: manages multiple audio adapters. Each audio adapter consists of the digital audio interface (DAI), platform, codec, accessory, DSP, and Smart Audio Power Manager (SAPM) modules.
- Card Manager: manages multiple audio adapters. Each audio adapter consists of the digital audio interface (DAI), platform, codec, DSP, and Smart Audio Power Manager (SAPM) modules.
- Platform Drivers: driver adaptation layer.
- SAPM: optimizes the power consumption policy of the ADM.
...
...
@@ -31,36 +31,39 @@ The driver architecture consists of the following:
The following uses the Hi3516D V300 as an example to describe how to develop drivers based on the audio driver architecture.
### Audio ADM Architecture
The audio driver provides the **hdf_audio_render**, **hdf_audio_capture**, and **hdf_audio_control** services for the HDI layer. The driver service nodes in the **dev** directory of the development board are as follows:
crw-rw---- 1 system system 247, 5 1970-01-01 00:00 hdf_audio_control // Audio control service.
crw-rw---- 1 system system 247, 7 1970-01-01 00:00 hdf_audio_render // Audio playback service.
```
The audio adapters have the following driver services:
hdf\_audio\_codec\_dev0
-**dma\_service\_0**: direct memory access (DMA) service
hdf_audio_codec_primary_dev0
-**dma_service_0**: DMA service
-**dai_service**: CPU DAI service
-**codec\_service\_0**: codec service (built-in codec)
-**dsp\_service\_0**: DSP service (optional)
-**codec_service_0**: codec service (which can be smartPA)
-**dsp_service_0**: DSP service (optional)
hdf\_audio\_codec\_dev1
-**dma\_service\_0**: DMA service
hdf_audio_codec_primary_dev11
-**dma_service_0**: DMA service
-**dai_service**: CPU DAI service
-**codec\_service\_1**: accessory service (SmartPA)
-**dsp\_service\_0**: DSP service (optional)
-**codec_service_1**: codec service (which can be smartPA)
-**dsp_service_0**: DSP service (optional)
#### Startup Process
1. When the system starts, the platform, codec, accessory, DSP, and DAI drivers of the audio module are loaded first. Each driver obtains the configuration information from its configuration file and saves the obtained information to the data structures.
1. When the system starts, the platform, codec, DSP, and DAI drivers of the audio module are loaded first. Each driver obtains the configuration information from its configuration file and saves the obtained information to the data structs.
2. Each driver module calls the ADM registration interface to add itself to the linked list of the driver module.
...
...
@@ -72,7 +75,7 @@ hdf\_audio\_codec\_dev1
#### Playback Process
1. The Audio Interface Lib sends the **Render Open** instruction to the Audio Stream Dispatch service. The Audio Stream Dispatch service calls the API of each module to deliver the instruction.
...
...
@@ -95,11 +98,35 @@ hdf\_audio\_codec\_dev1
1. When the volume needs to be adjusted, the Audio Interface Lib sends an instruction for obtaining the volume range to the Control Dispatch service. The Control Dispatch service parses the instruction and calls **get()** of the codec module to obtain the volume range.
2. The Audio Interface Lib sends an instruction for setting the volume to the Control Dispatch service. The Control Dispatch service parses the instruction and calls **Set()** of the codec module to set the volume.
| CodecGetDaiName | Obtains the DAI name in the HCS. |
| CodecGetServiceName | Obtains the service name in the HCS. |
| DaiDeviceReadReg | Reads data from a DAI register. |
| DaiDeviceWriteReg | Writes data to a DAI register. |
| DaiSetConfigInfoOfControls | Sets the DAI control function and register information. |
| DaiGetConfigInfo | Obtains the DAI HCS. |
### Audio Driver Development Procedure
#### Development on an Adapted Platform
The following figure shows the process for developing the codec or accessory (SmartPA) driver on a chip platform (Hi3516D V300) to which the ADM has adapted.
The following figure shows the process for developing the codec or SmartPA driver on a chip platform (Hi3516D V300) to which the ADM has adapted.
...
...
@@ -125,26 +152,26 @@ The codec (optional), DAI, DMA, DSP (optional), and SmartPA (optional) modules o
.DaiInit=CodecDaiDeviceInit,// Initialize the codec DAI device (need to be implemented for a new platform).
.ops=&g_codecDaiDeviceOps,// codec DAI device operation function set.
.ops=&g_codecDaiDeviceOps,// Codec DAI device operation function set.
};
```
#### Initializing codecDevice and codecDai
**CODECDeviceInit** sets audio input/audio output (AIAO), initializes registers, inserts **g_audioControls** into the control linked list, initializes the power management, and selects a path.
**CODECDeviceInit** sets audio input/audio output (AIAO), initializes registers, inserts **g_audioControls** into the controller linked list, initializes the power management, and selects a path.
This process depends on the driver implementation mode of the HDF. For details, see [HDF](driver-hdf-overview.md).
The following implementation depends on the driver implementation mode of the HDF. For details, see [HDF](driver-overview-foundation.md).
Fill in the **g_codecDriverEntry** structure. Ensure that the value of **moduleName** is the same as that in **device_info.hcs**. Implement the pointers to the **Bind**, **Init**, and **Release** functions.
Fill in the **g_codecDriverEntry** struct. Ensure that the value of **moduleName** is the same as that in **device_info.hcs**. Implement the pointers to the **Bind**, **Init**, and **Release** functions.
Configure the driver node, loading sequence, and service name in the .hcs file. For details about the HCS syntax, see [Driver Configuration Management](driver-hdf-manage.md) in the HDF.
Configure the driver node, loading sequence, and service name in the .hcs file. For details about the HCS syntax, see [Configuration Management](driver-hdf-manage.md) of the HDF.
Path of the standard-system configuration file:
...
...
@@ -343,7 +370,7 @@ Path of the small-system configuration file:
**Configuring Codec Device Information in device_info.hcs**
Add codec node configuration. Modify **moduleName** in the configuration file. The value must be the same as **moduleName** in the **HdfDriverEntry** structure. Generally, the value should present the hardware platform. For example, moduleName = "CODEC_HI3516".
Add codec node configuration. Modify **moduleName** in the configuration file. The value must be the same as **moduleName** in the **HdfDriverEntry** struct. Generally, the value should present the hardware platform. For example, moduleName = "CODEC_HI3516".
The code snippet is as follows:
...
...
@@ -364,7 +391,7 @@ The code snippet is as follows:
**Configuring Dependencies in audio_config.hcs**
Configure dependencies between the codec, platform, DAI, DSP, and accessory for the audio adapters.
Configure the dependency between the codec, platform, DAI, and DSP on which the audio_card device depends.
The code snippet is as follows:
...
...
@@ -373,13 +400,13 @@ root {
platform{
...
controller_0x120c1001::card_controller{
// Set the private data attribute name, which must be the same as deviceMatchAttr in device_info.hcs.
// Set the private data attribute name, which must be the same as the deviceMatchAttr in device_info.hcs.
match_attr="hdf_audio_driver_1";
serviceName="hdf_audio_smartpa_dev0";// Name of the service provided externally.
accessoryName="codec_service_1";// External codec service name.
serviceName="hdf_audio_codec_primary_dev11";// Name of the service provided externally.
codecName="codec_service_1";// Codec service name.
platformName="dma_service_0";// DMA service.
cpuDaiName="dai_service";// CPU DAI service.
accessoryDaiName="accessory_dai";// External DAI.
codecDaiName="tfa9879_codec_dai";// Codec DAI service.
dspName="dsp_service_0";// DSP service name.
dspDaiName="dsp_dai";// DSP DAI.
}
...
...
@@ -391,45 +418,37 @@ root {
The configuration matches **deviceMatchAttr** of the codec configured in **device_info.hcs**. It includes the register configuration.
Binding the control functionality configuration is to configure the control functionalities and their register parameters in the .hcs file according to unified structure specifications. The configuration can be obtained and parsed, and added to the controller linked list.
Binding the control functionality configuration is to configure the control functionalities and their register parameters in the .hcs file according to unified struct specifications. The configuration can be obtained and parsed, and added to the controller linked list.
-**regConfig**: register and control functionality configuration
-**regConfig**: register and control functionality configuration.
-**ctrlParamsSeqConfig**: control functionality register configuration
-**ctrlParamsSeqConfig**: register configuration for a function. The items in **ctrlParamsSeqConfig** must be in the same sequence as the items in **controlsConfig**.
-**daiStartupSeqConfig**: DAI startup configuration
-**daiStartupSeqConfig**: DAI startup configuration.
-**resetSeqConfig**: reset process register configuration
-**resetSeqConfig**: reset process register configuration.
-**initSeqConfig**: initialization process register configuration
-**initSeqConfig**: initialization process register configuration.
-**controlsConfig**: control functionality configuration. The **array index** (specific service scenario) and **iface** (same as the HAL) are of fixed values.
-**controlsConfig**: control function configuration. The **array index** (specific service scenario) and **iface** (same as that in the HAL) have fixed values.
```
array index
0: Main Playback Volume
1: Main Capture Volume
2: Playback Mute
3: Capture Mute
4: Mic Left Gain
5: Mic Right Gain
6: External Codec Enable
7: Internally Codec Enable
8: Render Channel Mode
9: Capture Channel Mode
iface
0: virtual dac device
1: virtual adc device
2: virtual adc device
3: virtual mixer device
4: Codec device
5: PGA device
6: AIAO device
```
-**sapmConfig**: power management and control function configuration. The values of **array index** (specific service scenario) and **iface** (consistent with the HAL) have fixed values.
-**ctrlSapmParamsSeqConfig**: register configuration of the power management and control function.
-**sapmComponent**: power management component configuration.
-**array index**:
The **array index** in **controlsConfig** is the element ID in the **g_audioCodecControlsList** array in the **audio_codec_base.c** file.
**ctrlParamsSeqConfig**: control function register configuration. The **item** sequence corresponds to the **item** sequence in **controlsConfig**, indicating the register configuration corresponding to a function.
The **array index** in **sapmConfig** is the element ID in the **g_audioSapmCfgNameList** array in the **audio_codec_base.c** file.
The **compNameIndex** in **sapmComponent** is the element ID in the **g_audioSapmCompNameList** array in the **audio_codec_base.c** file.
-**iface**: **2** for the virtual mixer device.
```c
root{
...
...
@@ -444,14 +463,14 @@ iface
serviceName="codec_service_0";
codecDaiName="codec_dai";
/* Base address of the Hi3516 register*/
/* Base address of Hi3516 registers. */
idInfo{
chipName="hi3516";// Codec name
chipIdRegister=0x113c0000;// Codec base address
chipIdSize=0x1000;// Codec address offset
chipName="hi3516";// Codec name.
chipIdRegister=0x113c0000;// Codec base address.
chipIdSize=0x1000;// Codec address offset.
}
/* Register configuration, including configuration of registers */
/* Register configuration, including configuration of registers. */
regConfig{
/* reg: register address
rreg: register address
...
...
@@ -479,28 +498,27 @@ iface
0x14,0x04000002
];
/* Control functionality configuration
array index, iface, enable*/
controlsConfig=[
0,0,0,
1,1,1,
2,0,1,
3,1,1,
4,2,1,
5,2,1,
8,6,0,
9,6,0,
/* Control functionality configuration.
array index, iface, mixer/mux, enable, */
0,2,0,0,
1,2,0,1,
2,2,0,1,
3,2,0,1,
4,2,0,1,
5,2,0,1,
8,2,0,0,
9,2,0,0,
];
/* Control functionality register configuration
reg, rreg, shift, rshift, min, max, mask, invert, value */
The SmartPA is a type of codec driver. The development process is as follows:
SmartPA is a type of accessory driver. The SmartPA development procedure is similar to the codec development procedure.
1. Define and fill in an accessory instance.
2. Implement callbacks for the accessory instance.
3. Register and bind the accessory instance to the HDF.
1. Define and fill in a codec instance.
2. Implement callbacks for the codec instance.
3. Register and bind the codec instance to the HDF.
4. Configure the HCS and makefile.
#### Filling in Accessory Data Structures
#### Filling in the Codec Data Structs
Fill in the following data structures for the accessory module:
Fill in the following data structs for the codec module:
-**g_tfa9879Data**: operation function set of the accessory device. It contains the configuration in the .hcs file, and defines and maps the functions for initializing the accessory device and reading and writing registers.
-**g_tfa9879Data**: operation function set of the codec device. It contains the configuration in the .hcs file, and defines and maps the functions for initializing the codec device and reading and writing registers.
-**g_tfa9879DaiDeviceOps**: data set of the DAI of the accessory device. It defines and maps the operation set of the accessory device DAI.
-**g_tfa9879DaiDeviceOps**: DAI data set that defines and maps the operations of the codec device DAI.
-**g_tfa9879DaiData**: data set of the DAI of the accessory device. It defines and maps the driver name, initialization, and operation set of the data access interface of the accessory device.
-**g_tfa9879DaiData**: DAI data set that defines and maps the driver name, initialization, and operations of the data access interfaces of the codec device.
#### Initializing accessoryDevice and accessoryDai
#### Initializing codecDevice and codecDai
As the entry function for device initialization, **Tfa9879DeviceInit** sets the address of the SmartPA I2C device, obtains configuration data, initializes (including resets) the device registers, and adds the control functionality to the controller linked list. The current demo also includes the initialization of the registers related to the Hi3516D V300 device, such as initialization of GPIO pins.
#### Implementing the Accessory Operation Function Set
The callbacks **AccessoryDeviceRegRead** and **AccessoryDeviceRegWrite** invoke **AccessoryI2cReadWrite** to read and write the control register values.
This process depends on the driver implementation mode of the HDF. For details, see [HDF](driver-hdf-overview.md).
The following implementation depends on the driver implementation mode of the HDF. For details, see [HDF](driver-overview-foundation.md).
Fill in the **g_tfa9879DriverEntry** structure. Ensure that the value of **moduleName** is the same as that in **device_info.hcs**. Implement the pointers to the **Bind**, **Init**, and **Release** functions.
Fill in the **g_tfa9879DriverEntry** struct. Ensure that the value of **moduleName** is the same as that in **device_info.hcs**. Implement the pointers to the **Bind**, **Init**, and **Release** functions.
In audio driver development, the Platform module is configured to adapt to the DMA driver. The major steps for developing the platform driver are as follows:
1. Define and fill in a platform instance.
2. Implement callbacks for the platform instance.
3. Register and bind the platform instance to the HDF.
3. Register and bind the codec instance to the HDF.
4. Configure the HCS and makefile.
#### Filling in Platform Data Structures
Fill in the following structures for the platform module:
Fill in the following structs for the platform module:
-**g_platformData**: private configuration of the platform device, including the initialization and operation functions of the platform device.
The DMA device operation function set includes the encapsulation of DMA common APIs. If the common APIs cannot meet development requirements, you can implement new DMA callbacks.
The major steps for developing the DAI driver are as follows:
1. Define and fill in a DAI instance.
2. Implement callbacks for the DAI instance.
3. Register and bind the DAI instance to the HDF.
3. Register and bind the codec instance to the HDF.
4. Configure the HCS and makefile.
#### Filling in DAI Data Structures
Fill in the following structures for the DAI module:
Fill in the following structs for the DAI module:
-**g_daiData**: private configuration of the DAI device, including the initialization of the DAI device, read/write of registers, and operation functions.
The development example implements the functions in the header file of the driver interface. The following uses Hi3516 as an example to describe the directory structure.
The development example implements the functions in the header file of the driver interface. The following uses Hi3516 as an example to describe the directory struct.
Path of the driver implementation sample code: **drivers\peripheral\audio\chipsets\**
Path of the driver implementation sample code: **device/board/hisilicon/hispark_taurus/audio_drivers/**
The Hardware Abstraction Layer (HAL) provides the following functions:
1. Provides audio HDIs for audio services to implement basic audio features on applications.
2. Provides standard interfaces for device developers to comply with the HDI adapter standards. This promises a healthy evolution of the ecosystem.
The Hardware Abstraction Layer (HAL) provides the following function:
Code path: **drivers/peripheral/audio/hal**
- Provides audio HDIs for audio services to implement basic audio features on applications.
- Provides standard interfaces for device developers to comply with the HDI adapter standards. This promises a healthy evolution of the ecosystem.
Code path: **drivers_interface/audio/v1_0**
### Development procedure
1. Call **GetAudioManagerFuncs()** to obtain functions.
2. Call **GetAllAdapters()** to obtain information about the supported audio adapters and call **LoadAdapter()** to load the corresponding audio adapter.
3. Create an audio player class by calling **CreateRender()** or create a recorder class and deliver audio attributes.
1. Call **GetAudioManagerFuncs()** to obtain methods.
4. Call the methods mounted to the created audio player class to call **render->control.Start()** and **render->RenderFrame()** to dispatch the start instruction and deliver audio data cyclically.
2. Use **GetAllAdapters()** to obtain information about the supported audio adapter, and call **LoadAdapter()** to load the audio adapter.
5. During the playback, call **render->control.Pause()**, **render->control.Resume()**, or **render->volume.SetVolume()** to control the audio player service, for example, pausing the playback, resuming the playback, and adjusting the volume.
3. Create a **Render** class by calling **CreateRender()** or create a recorder class and deliver audio attributes.
6. After the audio player service is complete, stop the playback, destroy the audio player class, and unload the audio adapter.
4. Call the methods hooked in the **Render** class created. For example, call **render->Start()** to start the playback, and call **render->RenderFrame()** to deliver audio data cyclically.
1. render->control.Stop();
5. During the playback, call control commands to control the playback service, for example, call **render->SetVolume()** to adjust the volume, call **render->Pause()** to pause the playback, and call **render->Resume()** to resume the playback.
2. adapter->DestroyRender();
6. After the playback is complete, call **render->Stop()** to stop the playback, call **adapter->DestroyRender()** to destroy the playback instance, and call **audioManagerIns->UnloadAdapter()** to unload the audio adapter.
This document provides all the key adaptations involved in the audio driver development. It elaborates how to adapt the audio driver and use HDI APIs. You can conduct development based on the chip you use. After reading this document, you will be able to master the audio driver development based on the HDF framework.
This document provides all the key adaptations involved in the audio driver development. It elaborates how to adapt the audio driver and use HDI APIs. You can conduct development based on the chip you use. After reading this document, you will be able to master the audio driver development based on the HDF.
