This section introduces the Audio APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, Audio function groups, enums, structures and functions. More...

Overview

This section introduces the Audio APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, Audio function groups, enums, structures and functions.

How to use this driver

Initiate the audio play function and use an earphone to play it out.
- step1: call hal_audio_set_stream_out_sampling_rate() to configure the audio sampling rate.
- step2: call hal_audio_set_stream_out_channel_number() to configure the audio channel number.
- step3: call hal_audio_set_stream_out_device() to configure audio output device.
- step4: call hal_audio_start_stream_out() to start the audio playback.
- sample code:
  static void user_audio_stream_out_callback(hal_audio_event_t event, void *user_data)
  {
  switch(event) {
  case HAL_AUDIO_EVENT_UNDERFLOW:
  //Provide more data once this event is received.
  //Audio output might be discontinuous since there is data underflow.
  break;
  case HAL_AUDIO_EVENT_DATA_REQUEST:
  //Fill with output data, if available.
  break;
  case HAL_AUDIO_EVENT_ERROR:
  //Error handler.
  break;
  }
  }
  uint8_t *memory;
  static void audio_play(void)
  {
  uint32_t memory_size = 0;
  hal_audio_set_stream_out_sampling_rate(HAL_AUDIO_SAMPLING_RATE_48KHZ);
  hal_audio_set_stream_out_channel_number(HAL_AUDIO_STEREO);
  hal_audio_set_stream_out_device(HAL_AUDIO_DEVICE_HEADSET);
  hal_audio_register_stream_out_callback(user_audio_stream_out_callback, NULL);
  // Get the amount of internal memory usage.
  hal_audio_get_memory_size(&memory_size);
  memory = malloc(memory_size * sizeof(uint8_t *));
  if(NULL == memory){
  //Error handler, if memory allocation failed.
  }
  result = hal_audio_set_memory(memory);
  if(HAL_AUDIO_STATUS_OK != result){
  //Error handler.
  }
  hal_audio_start_stream_out(HAL_AUDIO_PLAYBACK_MUSIC);
  }
  static void audio_stop(void)
  {
  hal_audio_stop_stream_out();
  //Free the internal memory allocation
  free(memory);
  }

The APIs are grouped based on their functionality for more convenient usage. For more information about each function, please click on the function name.

Initialization and configuration.
The hal_audio_init() function intitializes the audio hardware. Call this function when the system restarts.
The hal_audio_set_stream_out_sampling_rate() and hal_audio_set_stream_in_sampling_rate() are used to set the sampling rate.
When audio application is related to voice, stream in/out sampling rate should be set to 8kHz for narrowband and 16kHz for wideband.
Use hal_audio_set_stream_out_channel_number() and hal_audio_set_stream_in_channel_number() to set the channel number.
The sampling rate and channel number configuration functions should be called before powering on the audio application, and cannot be changed during the application execution.
Which means the user needs to reconfigure the settings to start a new audio track or application.
Specify the hal_audio_set_stream_out_device() and # hal_audio_set_stream_in_device() functions before starting the audio streaming. Device settings could be changed even if the audio is active. The functions are:
Callback registation functions
Use the following functions to register callback functions to stream output and input data, respectively.
- hal_audio_register_stream_out_callback()
- hal_audio_register_stream_in_callback()
Enable and disable functions.
hal_audio_start_stream_out() function enables the output audio signal streaming hardware. hal_audio_stop_stream_out() function immediately stops the output streaming.
hal_audio_start_stream_in() function enables the input audio streaming hardware. hal_audio_stop_stream_in() function immediately stops the input audio streaming.
Volume control functions
Call hal_audio_set_stream_out_volume() and hal_audio_set_stream_in_volume() to set the volume of stream out and in, respectively.
The volume can be changed during the application execution. It has digital and analog gain controls. The gain range is chip dependent. Please refer to the chip specification to setup the range.
Mute functions are also provided. Call hal_audio_mute_stream_out() and hal_audio_mute_stream_in() to mute the audio path. Note, that unmute should be called after mute is set when the audio needs to be played out or recorded in. The functions are:
Data transfer functions
- Stream out transfer The hal_audio_get_stream_out_sample_count() should be called before hal_audio_write_stream_out() to know how many free space of output buffer can be written. The functions are:
  - hal_audio_write_stream_out()
  - hal_audio_get_stream_out_sample_count()
  - sample code:
    uint8_t user_buffer[1024] = { //with data };
    static void audio_write_data(void)
    {
    uint32_t sample_count = 0;
    uint8_t *data_buffer = (uint8_t *)user_buffer;
    // Get available free space of output buffer.
    hal_audio_get_stream_out_sample_count(&sample_count);
    //Write numbers of sample_count samples for audio out.
    hal_audio_write_stream_out(data_buffer, sample_count);
    }
- Stream in transfer Call hal_audio_get_stream_in_sample_count() function before hal_audio_read_stream_in() to identify the number of available samples in the input buffer ready to read. The functions are:
  - hal_audio_read_stream_in()
  - hal_audio_get_stream_in_sample_count()
  - sample code:
    uint8_t user_buffer[1024];
    static void audio_read_data(void)
    {
    uint32_t sample_count = 0;
    uint8_t *data_buffer = (uint8_t *)user_buffer;
    //Get available data count of input buffer.
    hal_audio_get_stream_in_sample_count(&sample_count);
    //Copy numbers of sample_count samples into user_buffer.
    hal_audio_read_stream_in(data_buffer, sample_count);
    }

Functions
hal_audio_status_t	hal_audio_init (void)
	Initializes basic settings of the audio hardware. More...

hal_audio_status_t	hal_audio_deinit (void)
	Deinitialize audio settings. More...

hal_audio_status_t	hal_audio_register_copied_stream_out_callback (hal_audio_stream_copy_callback_t callback, void *user_data)
	Register the callback function to copy stream out data. More...

hal_audio_status_t	hal_audio_set_stream_out_sampling_rate (hal_audio_sampling_rate_t sample_rate)
	Set the sampling rate of the audio output stream. More...

hal_audio_status_t	hal_audio_set_stream_out_channel_number (hal_audio_channel_number_t channel_number)
	Set the audio output channel number. More...

hal_audio_status_t	hal_audio_start_stream_out (hal_audio_active_type_t active_type)
	Power on the audio out. More...

void	hal_audio_stop_stream_out (void)
	Power off the stream out path. More...

hal_audio_status_t	hal_audio_set_stream_out_volume (uint32_t digital_volume_index, uint32_t analog_volume_index)
	Set audio output the volume. More...

void	hal_audio_mute_stream_out (bool mute)
	Mute the audio output stream. More...

hal_audio_status_t	hal_audio_set_stream_out_device (hal_audio_device_t device)
	Set the audio output device. More...

hal_audio_status_t	hal_audio_write_stream_out (const void *buffer, uint32_t size)
	Write data to audio output. More...

hal_audio_status_t	hal_audio_get_stream_out_sample_count (uint32_t *sample_count)
	Query available free space for the output. More...

hal_audio_status_t	hal_audio_register_stream_out_callback (hal_audio_stream_out_callback_t callback, void *user_data)
	Register the callback function for output data. More...

hal_audio_status_t	hal_audio_set_stream_in_sampling_rate (hal_audio_sampling_rate_t sample_rate)
	Set audio input stream sampling rate. More...

hal_audio_status_t	hal_audio_set_stream_in_channel_number (hal_audio_channel_number_t channel_number)
	Set audio input channel number. More...

hal_audio_status_t	hal_audio_start_stream_in (hal_audio_active_type_t active_type)
	Power on the audio in. More...

void	hal_audio_stop_stream_in (void)
	Power off the stream in path. More...

hal_audio_status_t	hal_audio_set_stream_in_volume (uint32_t digital_volume_index, uint32_t analog_volume_index)
	Set audio input volume. More...

void	hal_audio_mute_stream_in (bool mute)
	Mute the audio input stream. More...

hal_audio_status_t	hal_audio_set_stream_in_device (hal_audio_device_t device)
	Set audio input device. More...

hal_audio_status_t	hal_audio_read_stream_in (void *buffer, uint32_t sample_count)
	Recieve data from the audio input. More...

hal_audio_status_t	hal_audio_get_stream_in_sample_count (uint32_t *sample_count)
	Query the available input data sample count. More...

hal_audio_status_t	hal_audio_register_stream_in_callback (hal_audio_stream_in_callback_t callback, void *user_data)
	Register the callback function for input data. More...

hal_audio_status_t	hal_audio_get_memory_size (uint32_t *memory_size)
	Query the size of needed memory to be allocated for internal use in audio driver. More...

hal_audio_status_t	hal_audio_set_memory (void *memory)
	Hand over allocated memory to audio driver. More...

hal_audio_status_t	hal_audio_get_audio_clock (uint32_t *sample_count)
	Get audio clock. More...

Modules
	Enum

	Struct

	Typedef

Function Documentation

hal_audio_status_t hal_audio_deinit ( void )

Deinitialize audio settings.

Returns: HAL_AUDIO_STATUS_OK, if OK.

See also: hal_audio_init()

hal_audio_status_t hal_audio_get_audio_clock ( uint32_t * sample_count )

Get audio clock.

Parameters

[out] sample_count is a pointer to the accumulated audio sample count.

Returns: HAL_AUDIO_STATUS_OK, if OK.

Note: The function is called to get the accumulated audio sample count written to audio hardware. One pair of L / R counts as one audio sample.

hal_audio_status_t hal_audio_get_memory_size ( uint32_t * memory_size )

Query the size of needed memory to be allocated for internal use in audio driver.

Parameters

[out] memory_size is the amount of memory required by the audio driver for an internal use (in bytes).

Returns: HAL_AUDIO_STATUS_OK, if OK.

Note: The function should be called at least before hal_audio_start_stream_in() or hal_audio_start_stream_out() to ensure enough memory can be used internally.

See also: hal_audio_set_memory()

hal_audio_status_t hal_audio_get_stream_in_sample_count ( uint32_t * sample_count )

Query the available input data sample count.

Parameters

[out] sample_count the available amount of received data (in bytes).

Returns: HAL_AUDIO_STATUS_OK, if OK.

Note: Call this function before hal_audio_read_stream_in() to check the content availability in an input buffer.

See also: hal_audio_read_stream_in()

hal_audio_status_t hal_audio_get_stream_out_sample_count ( uint32_t * sample_count )

Query available free space for the output.

Parameters

[out] sample_count is the available output sample count (in bytes).

Returns: HAL_AUDIO_STATUS_OK, if OK.

Note: Call this function before hal_audio_write_stream_out() to make sure there is enough free space to write the output.

See also: hal_audio_write_stream_out()

hal_audio_status_t hal_audio_init ( void )

Initializes basic settings of the audio hardware.

Returns: HAL_AUDIO_STATUS_OK, if OK.

Note: This function should at least be called once after system restarts and before using any audio functionality.

See also: hal_audio_deinit()

void hal_audio_mute_stream_in ( bool mute )

Mute the audio input stream.

Parameters

[in] mute is a flag to set the audio on/off silent.

Example: 1 hal_audio_mute_stream_in(true);

void hal_audio_mute_stream_out ( bool mute )

Mute the audio output stream.

Parameters

[in] mute is a flag to set the audio on/off silent.

example: 1 hal_audio_mute_stream_out(true);

hal_audio_status_t hal_audio_read_stream_in	(	void *	buffer,
		uint32_t	sample_count
	)

Recieve data from the audio input.

Parameters

[in]	buffer	is a pointer to a user defined buffer.
[in]	sample_count	is the amount of data received (in bytes).

Returns: HAL_AUDIO_STATUS_OK, if OK.

See also: hal_audio_get_stream_in_sample_count()

hal_audio_status_t hal_audio_register_copied_stream_out_callback	(	hal_audio_stream_copy_callback_t	callback,
		void *	user_data
	)

Register the callback function to copy stream out data.

Parameters

[in]	callback	is the function pointer of callback for output data control
[in]	user_data	is a user defined extended parameter.

Returns: HAL_AUDIO_STATUS_OK, if OK.

hal_audio_status_t hal_audio_register_stream_in_callback	(	hal_audio_stream_in_callback_t	callback,
		void *	user_data
	)

Register the callback function for input data.

Parameters

[in]	callback	is the function pointer of callback for input data control.
[in]	user_data	is extended parameter for user.

Returns: HAL_AUDIO_STATUS_OK, if OK.

Example: 1 hal_audio_register_stream_in_callback(stream_in_callback, user_data);

hal_audio_status_t hal_audio_register_stream_out_callback	(	hal_audio_stream_out_callback_t	callback,
		void *	user_data
	)

Register the callback function for output data.

Parameters

[in]	callback	is the function pointer of callback for output data control
[in]	user_data	is a user defined extended parameter.

Returns: HAL_AUDIO_STATUS_OK, if OK.

hal_audio_status_t hal_audio_set_memory ( void * memory )

Hand over allocated memory to audio driver.

Parameters

[in] memory is a pointer to an allocated memory. It should be 4 bytes aligned.

Returns: HAL_AUDIO_STATUS_OK, if OK.

Note: The function should be called after user allocates enough memory that is at least greater than the size queried from hal_audio_get_memory_size().

See also: hal_audio_get_memory_size()

hal_audio_status_t hal_audio_set_stream_in_channel_number ( hal_audio_channel_number_t channel_number )

Set audio input channel number.

Parameters

[in] channel_number is to set input channel number. For more details, please refer to hal_audio_channel_number_t.

Returns: HAL_AUDIO_STATUS_OK, if channel number is valid.

Example: 1 hal_audio_set_stream_in_channel_number(HAL_AUDIO_MONO);

hal_audio_status_t hal_audio_set_stream_in_device ( hal_audio_device_t device )

Set audio input device.

Parameters

[in] device is the input component. For more details, please refer to hal_audio_device_t.

Returns: HAL_AUDIO_STATUS_OK, if input device is valid.

Example: 1 hal_audio_set_stream_in_device(HAL_AUDIO_DEVICE_MAIN_MIC);

hal_audio_status_t hal_audio_set_stream_in_sampling_rate ( hal_audio_sampling_rate_t sample_rate )

Set audio input stream sampling rate.

Parameters

[in] sample_rate is to set input sampling rate. Please refers to hal_audio_sampling_rate_t.

Returns: HAL_AUDIO_STATUS_OK, if sampling rate is valid

Note: Only 8kHz and 16kHz is supported.

Example: 1 hal_audio_set_stream_in_sampling_rate(HAL_AUDIO_SAMPLING_RATE_8KHZ);

hal_audio_status_t hal_audio_set_stream_in_volume	(	uint32_t	digital_volume_index,
		uint32_t	analog_volume_index
	)

Set audio input volume.

Parameters

[in]	digital_volume_index	is to set a digital gain in centi-db in hex (FFFFFE0C equal to -5db). Gain range: depend on the gain map.
[in]	analog_volume_index	is to set digital gain in centi-db in hex (FFFFFE0C equal to -5db). Gain range: depends on the hardware design and gain map.

Returns: HAL_AUDIO_STATUS_OK, if input volume range is valid.

hal_audio_status_t hal_audio_set_stream_out_channel_number ( hal_audio_channel_number_t channel_number )

Set the audio output channel number.

Parameters

[in] channel_number is to set the output channel number. For more details, please refer to hal_audio_channel_number_t.

Returns: HAL_AUDIO_STATUS_OK, if channel number is valid.

hal_audio_status_t hal_audio_set_stream_out_device ( hal_audio_device_t device )

Set the audio output device.

Parameters

[in] device is the ouput component. For more details, please refer to hal_audio_device_t.

Returns: HAL_AUDIO_STATUS_OK, if output device is valid.

hal_audio_status_t hal_audio_set_stream_out_sampling_rate ( hal_audio_sampling_rate_t sample_rate )

Set the sampling rate of the audio output stream.

Parameters

[in] sample_rate is to set the output sampling rate. For more details, please refer to hal_audio_sampling_rate_t.

Returns: HAL_AUDIO_STATUS_OK, if sampling rate is valid.

Note: If the audio function is for speech, such as HAL_AUDIO_PLAYBACK_VOICE/ HAL_AUDIO_RECORD_VOICE/ HAL_AUDIO_BLUETOOTH_CALL, only 8kHz or 16kHz is available.

hal_audio_status_t hal_audio_set_stream_out_volume	(	uint32_t	digital_volume_index,
		uint32_t	analog_volume_index
	)

Set audio output the volume.

Parameters

[in]	digital_volume_index	is to set digital gain in centi-db in hex (FFFFFE0C equal to -5db). Gain range: depends on the gain map.
[in]	analog_volume_index	is to set digital gain in centi-db in hex (FFFFFE0C equal to -5db). Gain range: depends on the hardware design and gain map.

Returns: HAL_AUDIO_STATUS_OK, if output volume range is valid.

hal_audio_status_t hal_audio_start_stream_in ( hal_audio_active_type_t active_type )

Power on the audio in.

Parameters

[in] active_type is to set input function type. For more details, please refer to hal_audio_active_type_t.

Returns: HAL_AUDIO_STATUS_OK, if input path type is valid.

See also: hal_audio_stop_stream_in()

Example: 1 hal_audio_start_stream_in(HAL_AUDIO_RECORD_VOICE);

hal_audio_status_t hal_audio_start_stream_out ( hal_audio_active_type_t active_type )

Power on the audio out.

Parameters

[in] active_type is to set the audio output function type. For more details, please refer to hal_audio_active_type_t.

Returns: HAL_AUDIO_STATUS_OK, if the output path type is valid

See also: hal_audio_stop_stream_out()

void hal_audio_stop_stream_in ( void )

Power off the stream in path.

See also: hal_audio_start_stream_in()

Example: 1 hal_audio_stop_stream_in();

void hal_audio_stop_stream_out ( void )

Power off the stream out path.

See also: hal_audio_start_stream_out()

hal_audio_status_t hal_audio_write_stream_out	(	const void *	buffer,
		uint32_t	size
	)

Write data to audio output.

Parameters

[in]	buffer	is the pointer to output data.
[in]	size	is the available free space of the output buffer (in bytes).

Returns: HAL_AUDIO_STATUS_OK, if OK.

See also: hal_audio_get_stream_out_sample_count()

Overview

How to use this driver

Functions

Modules

Function Documentation