PDM Interface

Detailed Description

Interface for PDM audio communication.

Summary

The pulse-density modulation(PDM) interface provides APIs and definitions for PDM audio communication.

Data Structures
struct	pdm_callback_args_t
struct	pdm_sound_detection_setting_t
struct	pdm_status_t
struct	pdm_cfg_t
struct	pdm_api_t
struct	pdm_instance_t

Typedefs
typedef void	pdm_ctrl_t

Enumerations
enum	pdm_pcm_width_t
enum	pdm_input_data_edge_t
enum	pdm_event_t
enum	pdm_error_t
enum	pdm_state_t

---

Data Structure Documentation

pdm_callback_args_t

struct pdm_callback_args_t

Callback function parameter data

Data Fields
void *	p_context	Placeholder for user data. Set in pdm_api_t::open function in pdm_cfg_t.
pdm_event_t	event	The event can be used to identify what caused the callback (overflow or error).
pdm_error_t	error	The kind of error.

pdm_sound_detection_setting_t

struct pdm_sound_detection_setting_t

Sound detection window setting

Data Fields
uint32_t	sound_detection_lower_limit	Sound detection lower limit (20-bit signed fixed point data)
uint32_t	sound_detection_upper_limit	Sound detection upper limit (20-bit signed fixed point data)

pdm_status_t

struct pdm_status_t

PDM status.

Data Fields
pdm_state_t	state	Current PDM data state.
bool	sound_detection_enabled	Current PDM sound detection status.
pdm_error_t	error	Bitfield of current PDM errors.

pdm_cfg_t

struct pdm_cfg_t

User configuration structure, used in open function

Data Fields
uint32_t	unit
pdm_pcm_width_t	pcm_width
	Audio PCM data width.
pdm_input_data_edge_t	pcm_edge
	Input data select.
transfer_instance_t const *	p_transfer_rx
void(*	p_callback )(pdm_callback_args_t *p_args)
void *	p_context
void const *	p_extend
	Extension parameter for hardware specific settings.
uint8_t	dat_ipl
	Data reception interrupt priority.
uint8_t	sdet_ipl
	Sound detection interrupt priority.
uint8_t	err_ipl
	Idle/Error interrupt priority.
IRQn_Type	dat_irq
	IRQ number of data reception interrupt.
IRQn_Type	sdet_irq
	IRQ number of sound detection interrupt.
IRQn_Type	err_irq
	IRQ number of error detection interrupt.

Field Documentation

unit

uint32_t pdm_cfg_t::unit

Select a unit/channel corresponding to the unit/channel number of the hardware.

p_transfer_rx

transfer_instance_t const* pdm_cfg_t::p_transfer_rx

To use DMA for receiving link a Transfer instance here. Set to NULL if unused.

p_callback

void(* pdm_cfg_t::p_callback) (pdm_callback_args_t *p_args)

Callback provided when an PDM ISR occurs. Set to NULL for no CPU interrupt.

p_context

void* pdm_cfg_t::p_context

Placeholder for user data. Passed to the user callback in pdm_callback_args_t.

pdm_api_t

struct pdm_api_t

PDM functions implemented at the HAL layer will follow this API.

Data Fields
fsp_err_t(*	open )(pdm_ctrl_t *const p_ctrl, pdm_cfg_t const *const p_cfg)
fsp_err_t(*	start )(pdm_ctrl_t *const p_ctrl, void *const p_buffer, size_t const buffer_size, uint32_t const number_of_data_to_callback)
fsp_err_t(*	stop )(pdm_ctrl_t *const p_ctrl)
fsp_err_t(*	soundDetectionEnable )(pdm_ctrl_t *const p_ctrl, pdm_sound_detection_setting_t pdm_sound_detection_setting)
fsp_err_t(*	soundDetectionDisable )(pdm_ctrl_t *const p_ctrl)
fsp_err_t(*	read )(pdm_ctrl_t *const p_ctrl, void *const p_dest, uint32_t const bytes)
fsp_err_t(*	statusGet )(pdm_ctrl_t *const p_ctrl, pdm_status_t *const p_status)
fsp_err_t(*	close )(pdm_ctrl_t *const p_ctrl)
fsp_err_t(*	callbackSet )(pdm_ctrl_t *const p_ctrl, void(*p_callback)(pdm_callback_args_t *), void *const p_context, pdm_callback_args_t *const p_callback_memory)

Field Documentation

open

fsp_err_t(* pdm_api_t::open) (pdm_ctrl_t *const p_ctrl, pdm_cfg_t const *const p_cfg)

Initial configuration.

Precondition

Peripheral clocks and any required output pins should be configured prior to calling this function.

Note

To reconfigure after calling this function, call pdm_api_t::close first.

Parameters

[in]	p_ctrl	Pointer to control block. Must be declared by user. Elements set here.
[in]	p_cfg	Pointer to configuration structure. All elements of this structure must be set by user.

start

fsp_err_t(* pdm_api_t::start) (pdm_ctrl_t *const p_ctrl, void *const p_buffer, size_t const buffer_size, uint32_t const number_of_data_to_callback)

Start communication.

Parameters

[in]	p_ctrl	Control block set in pdm_api_t::open call for this instance.
[in]	p_buffer	Pointer to the reception buffer
[in]	buffer_size	Size of the buffer
[in]	number_of_data_to_callback	Number of the data to call the callback function from dat_isr

stop

fsp_err_t(* pdm_api_t::stop) (pdm_ctrl_t *const p_ctrl)

Stop communication. Communication is stopped when callback is called with PDM_EVENT_IDLE.

Parameters

[in]

p_ctrl

Control block set in pdm_api_t::open call for this instance.

soundDetectionEnable

fsp_err_t(* pdm_api_t::soundDetectionEnable) (pdm_ctrl_t *const p_ctrl, pdm_sound_detection_setting_t pdm_sound_detection_setting)

Enable sound detection with the specified settings.

Parameters

[in]	p_ctrl	Control block set in pdm_api_t::open call for this instance.
[in]	pdm_sound_detection_setting	Settings to configure sound detection.

soundDetectionDisable

fsp_err_t(* pdm_api_t::soundDetectionDisable) (pdm_ctrl_t *const p_ctrl)

Disable sound detection.

Parameters

[in]

p_ctrl

Control block set in pdm_api_t::open call for this instance.

read

fsp_err_t(* pdm_api_t::read) (pdm_ctrl_t *const p_ctrl, void *const p_dest, uint32_t const bytes)

Read remaining PDM data. This function can be called during PDM_STATE_STOPPED.

Parameters

[in]	p_ctrl	Control block set in pdm_api_t::open call for this instance.
[in]	p_dest	Buffer to store PCM samples. Must be 4 byte aligned.
[in]	bytes	Number of bytes in the buffer. Recommended requesting a multiple of 8 bytes. If not a multiple of 8, receive will stop at the multiple of 8 below requested bytes.

statusGet

fsp_err_t(* pdm_api_t::statusGet) (pdm_ctrl_t *const p_ctrl, pdm_status_t *const p_status)

Get current status and store it in provided pointer p_status.

Parameters

[in]	p_ctrl	Control block set in pdm_api_t::open call for this instance.
[out]	p_status	Current status of the driver.

close

fsp_err_t(* pdm_api_t::close) (pdm_ctrl_t *const p_ctrl)

Allows driver to be reconfigured and may reduce power consumption.

Parameters

[in]

p_ctrl

Control block set in pdm_api_t::open call for this instance.

callbackSet

fsp_err_t(* pdm_api_t::callbackSet) (pdm_ctrl_t *const p_ctrl, void(*p_callback)(pdm_callback_args_t *), void *const p_context, pdm_callback_args_t *const p_callback_memory)

Specify callback function and optional context pointer and working memory pointer.

Parameters

[in]	p_ctrl	Pointer to the PDM control block.
[in]	p_callback	Callback function
[in]	p_context	Pointer to send to callback function
[in]	p_callback_memory	Pointer to volatile memory where callback structure can be allocated. Callback arguments allocated here are only valid during the callback.

pdm_instance_t

struct pdm_instance_t

This structure encompasses everything that is needed to use an instance of this interface.

Data Fields
pdm_ctrl_t *	p_ctrl	Pointer to the control structure for this instance.
pdm_cfg_t const *	p_cfg	Pointer to the configuration structure for this instance.
pdm_api_t const *	p_api	Pointer to the API structure for this instance.

Typedef Documentation

pdm_ctrl_t

typedef void pdm_ctrl_t

PDM control block. Allocate an instance specific control block to pass into the PDM API calls.

Enumeration Type Documentation

pdm_pcm_width_t

enum pdm_pcm_width_t

Audio PCM width

Enumerator
PDM_PCM_WIDTH_20_BITS_0_18	Using 20-bit PCM Clips [18:0] bit of the buffer and 1-bit of sign.
PDM_PCM_WIDTH_20_BITS_1_18	Using 20-bit PCM Clips [18:1] bit of the buffer and 2-bits of sign.
PDM_PCM_WIDTH_20_BITS_2_18	Using 20-bit PCM Clips [18:2] bit of the buffer and 3-bits of sign.
PDM_PCM_WIDTH_20_BITS_3_18	Using 20-bit PCM Clips [18:3] bit of the buffer and 4-bits of sign.
PDM_PCM_WIDTH_16_BITS_4_18	Using 16-bit PCM Clips [18:4] bit of the buffer and 1-bit of sign.
PDM_PCM_WIDTH_16_BITS_3_17	Using 16-bit PCM Clips [17:3] bit of the buffer and 1-bit of sign.
PDM_PCM_WIDTH_16_BITS_2_16	Using 16-bit PCM Clips [16:2] bit of the buffer and 1-bit of sign.
PDM_PCM_WIDTH_16_BITS_1_15	Using 16-bit PCM Clips [15:1] bit of the buffer and 1-bit of sign.
PDM_PCM_WIDTH_16_BITS_0_14	Using 16-bit PCM Clips [14:0] bit of the buffer and 1-bit of sign.

pdm_input_data_edge_t

enum pdm_input_data_edge_t

Input data select.

Enumerator
PDM_INPUT_DATA_EDGE_RISE	Rise-edge data of channel n.
PDM_INPUT_DATA_EDGE_FALL	Fall-edge data of channel n-1 (In case of n = 0, fall-edge data of channel 2 is selected.)

pdm_event_t

enum pdm_event_t

Events that can trigger a callback function

Enumerator
PDM_EVENT_IDLE	IDLE.
PDM_EVENT_DATA	Data reception.
PDM_EVENT_SOUND_DETECTION	Sound detection.
PDM_EVENT_ERROR	Error.

pdm_error_t

enum pdm_error_t

Error information included in a callback function

Enumerator
PDM_ERROR_NONE	No error.
PDM_ERROR_SHORT_CIRCUIT	Short circuit detection.
PDM_ERROR_OVERVOLTAGE_LOWER	Overvoltage lower limit exceeded detection.
PDM_ERROR_OVERVOLTAGE_UPPER	Overvoltage upper limit exceeded detection.
PDM_ERROR_BUFFER_OVERWRITE	Buffer overwriting detection.

pdm_state_t

enum pdm_state_t

Possible status values returned by pdm_api_t::statusGet.

Enumerator
PDM_STATE_IN_USE	PDM is actively reading data.
PDM_STATE_STOPPED	PDM is stopped and not actively reading data.