1.1.2 AK4954 CODEC Driver Library Help

This topic describes the AK4954 Codec Driver Library.

Introduction

This topic describes the basic architecture of the AK4954 Codec Driver Library and provides information and examples on its use.

Interface Header File: drv_AK4954.h

The interface to the AK4954 Codec Driver library is defined in the audio/driver/codec/AK4954/drv_AK4954.h header file.

Any C language source (.c) file that uses the AK4954 Codec Driver library should include this header.

Library Source Files:

The AK4954 Codec Driver library source files are provided in the audio/driver/codec/AK4954/src directory. This folder may contain optional files and alternate implementations. Please refer to Configuring the Library for instructions on how to select optional features and to Building the Library for instructions on how to build the library.

Example Applications:

This library is used by the following applications:

  • audio/apps/audio_tone

  • audio/apps/microphone_loopback

Abstration Model

This library provides a low-level abstraction of the AK4954 Codec Driver Library on the Microchip family microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface.

Description

The abstraction model shown in the following diagram depicts how the AK4954 Codec Driver is positioned in the MPLAB Harmony framework. The AK4954 Codec Driver uses the I2C and I2S drivers for control and audio data transfers to the AK4954 module.

AK4954 Driver Abstraction Model

Library Overview

Refer to the Driver Library Overview section for information on how the driver operates in a system.

The AK4954 Codec Driver Library provides an API interface to transfer control commands and digital audio data to the serially interfaced AK4954 Codec module. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the AK4954 Codec Driver Library.

Library Interface SectionDescription
System FunctionsProvides system module interfaces, device initialization, deinitialization, reinitialization, tasks and status functions.
Client Setup FunctionsProvides open and close functions.
Data Transfer FunctionsProvides data transfer functions, such as Buffer Read and Write.
Settings FunctionsProvides driver specific functions for settings, such as volume control and sampling rate.
Other FunctionsMiscellaneous functions, such as getting the driver’s version number and syncing to the LRCLK signal.
Data Types and ConstantsThese data types and constants are required while interacting and setting up the AK4954 Codec Driver Library.

Note: All functions and constants in this section are named with the format DRV_ AK4954_xxx, where 'xxx' is a function name or constant. These names are redefined in the appropriate configuration’s configuration.h file to the format DRV_CODEC_xxx using #defines so that code in the application that references the library can be written as generically as possible (e.g., by writing DRV_CODEC_Open instead of DRV_ AK4954_Open etc.). This allows the codec type to be changed in the MHC without having to modify the application’s source code.

How the Library Works

How the Library Works

The library provides interfaces to support:

  • System Functionality

  • Client Functionality

Setup (Initialization)

This topic describes system initialization, implementations, and includes a system access code example.

System Initialization

The system performs the initialization of the device driver with settings that affect only the instance of the device that is being initialized. During system initialization in the system_init.c file, each instance of the AK4954 module would be initialized with the following configuration settings (either passed dynamically at run time using DRV_AK4954_INIT or by using Initialization Overrides) that are supported by the specific AK4954 device hardware:

  • Device requested power state: one of the System Module Power States. For specific details please refer to Data Types and Constants in the Library Interface section.

  • I2C driver module index. The module index should be same as the one used in initializing the I2C Driver

  • I2S driver module index. The module index should be same as the one used in initializing the I2S Driver

  • Sampling rate

  • Volume

  • Audio data format. The audio data format should match with the audio data format settings done in I2S driver initialization

  • Determines whether or not the microphone input is enabled

The DRV_AK4954_Initialize API returns an object handle of the type SYS_MODULE_OBJ. The object handle returned by the Initialize interface would be used by the other system interfaces such as DRV_AK4954_Deinitialize, DRV_AK4954_Status and DRV_I2S_Tasks.

Client Access

This topic describes driver initialization and provides a code example.

Description

For the application to start using an instance of the module, it must call the DRV_AK4954_Open function. The DRV_AK4954_Open function provides a driver handle to the AK4954 Codec Driver instance for operations. If the driver is deinitialized using the function DRV_AK4954_Deinitialize, the application must call the DRV_AK4954_Open function again to set up the instance of the driver.

For the various options available for IO_INTENT, please refer to Data Types and Constants in the Library Interface section.

Note: It is necessary to check the status of driver initialization before opening a driver instance. The status of the AK4954 Codec Driver can be known by calling DRV_ AK4954_Status.

Example:

DRV_HANDLE handle; SYS_STATUS ak4954Status;

ak4954Status Status = DRV_AK4954_Status(sysObjects.ak4954Status DevObject); if (SYS_STATUS_READY == ak4954Status) { \/\/ The driver can now be opened. appData.ak4954Client.handle = DRV_AK4954_Open

( DRV_AK4954_INDEX_0, DRV_IO_INTENT_WRITE | DRV_IO_INTENT_EXCLUSIVE); if(appData.ak4954Client.handle != DRV_HANDLE_INVALID) {

appData.state = APP_STATE_AK4954_SET_BUFFER_HANDLER; } else { SYS_DEBUG(0, "Find out what's wrong \r\n");

} } else { \/* AK4954 Driver Is not ready *\/

}

Client Operations

This topic provides information on client operations.

Description

Client operations provide the API interface for control command and audio data transfer to the AK4954 Codec.

The following AK4954 Codec specific control command functions are provided:

  • DRV_AK4954_SamplingRateSet

  • DRV_AK4954_SamplingRateGet

  • DRV_AK4954_VolumeSet

  • DRV_AK4954_VolumeGet

  • DRV_AK4954_MuteOn

  • DRV_AK4954_MuteOff

These functions schedule a non-blocking control command transfer operation. These functions submit the control command request to the AK4954 Codec. These functions submit the control command request to I2C Driver transmit queue, the request is processed immediately if it is the first request, or processed when the previous request is complete.

DRV_AK4954_BufferAddWrite, DRV_AK4954_BufferAddRead, and DRV_AK4954_BufferAddWriteRead are buffered data operation functions. These functions schedule non-blocking audio data transfer operations. These functions add the request to I2S Driver transmit or receive buffer queue depends on the request type, and are executed immediately if it is the first buffer, or executed later when the previous buffer is complete. The driver notifies the client with DRV_AK4954_BUFFER_EVENT_COMPLETE, DRV_AK4954_BUFFER_EVENT_ERROR, or DRV_AK4954_BUFFER_EVENT_ABORT events.

Note: It is not necessary to close and reopen the client between multiple transfers.

Configuring the Library

The configuration of the I2S Driver Library is based on the file configurations.h, as generated by the MHC.

This header file contains the configuration selection for the I2S Driver Library. Based on the selections made, the I2S Driver Library may support the selected features. These configuration settings will apply to all instances of the I2S Driver Library.

This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Help section for more details.

System Configuration

Macros

NameDescription
DRV_AK4954_AUDIO_DATA_FORMAT_MACROSpecifies the audio data format for the codec.
DRV_AK4954_AUDIO_SAMPLING_RATESpecifies the initial baud rate for the codec.
DRV_AK4954_CLIENTS_NUMBERSets up the maximum number of clients that can be connected to any hardware instance.
DRV_AK4954_ENABLE_MIC_BIASSpecifies whether to enable the microphone bias.
DRV_AK4954_I2C_DRIVER_MODULE_INDEX_IDXxSpecifies the instance number of the I2C interface.
DRV_AK4954_I2S_DRIVER_MODULE_INDEX_IDXxSpecifies the instance number of the I2S interface.
DRV_AK4954_INSTANCES_NUMBERSets up the maximum number of hardware instances that can be supported
DRV_AK4954_MASTER_MODESpecifies if codec is in Host or Client mode.
DRV_AK4954_MIC_GAINSpecifies the gain of the microphone (external or line input only)
DRV_AK4954_VOLUMESpecifies the initial volume level.
DRV_AK4954_WHICH_MIC_INPUTSpecifies whether to enable the microphone input.