General functions for DMIC driver. More...

Functions
INIT_CODE dmic_status_en	dmic_init (dmic_instance_en instance)
dmic_status_en	dmic_get_capability (dmic_instance_en instance, dmic_capability_t *capability)
dmic_status_en	dmic_config_channel (dmic_instance_en instance, uint8_t channel, const dmic_channel_config_t *cfg)
dmic_status_en	dmic_configure_io (dmic_instance_en instance, const dmic_io_config_t *dmic_config)
dmic_status_en	dmic_enable_interrupts (dmic_instance_en instance, uint32_t mask)
dmic_status_en	dmic_reset (dmic_instance_en instance)
dmic_status_en	dmic_enable (dmic_instance_en instance)
dmic_status_en	dmic_disable (dmic_instance_en instance)
dmic_status_en	dmic_isr (dmic_instance_en instance)
dmic_status_en	dmic_start (dmic_instance_en instance)
dmic_status_en	dmic_stop (dmic_instance_en instance)
dmic_status_en	dmic_read (dmic_instance_en instance, dmic_buffer_context_t *buf, int32_t timeout)
dmic_status_en	dmic_read_nonblocking (dmic_instance_en instance, dmic_buffer_context_t *buf)
dmic_status_en	dmic_set_channel_volume (dmic_instance_en instance, uint8_t channel, float volume_db)
dmic_status_en	dmic_set_channel_gain (dmic_instance_en instance, dmic_channel_en channel, dmic_gain_ctrl_en gain_ctrl)
dmic_status_en	dmic_set_channel_boost (dmic_instance_en instance, dmic_channel_en channel, dmic_boost_en boost_level)
dmic_status_en	dmic_register_callback (dmic_instance_en instance, dmic_event_cb_t event_cb, void *user_data)
dmic_status_en	dmic_config_data_path (dmic_instance_en instance, const dmic_data_path_config_t *cfg)

Detailed Description

General functions for DMIC driver.

Function Documentation

◆ dmic_init()

INIT_CODE dmic_status_en dmic_init ( dmic_instance_en instance )

Initialize the DMIC peripheral and internal driver structures.

This function initializes the specified DMIC instance by setting up the hardware, configuring internal data structures, and preparing the peripheral for further configuration and use. It must be called before any other DMIC operations such as setting the configuration or starting transfers.

Parameters

instance DMIC instance identifier (e.g., DMIC0, DMIC1)

Returns

Error type dmic_status_en:

DMIC_OK : Initialization successful
DMIC_ERROR_INVALID_CONTEXT : Invalid instance identifier

◆ dmic_get_capability()

dmic_status_en dmic_get_capability	(	dmic_instance_en	instance,
		dmic_capability_t *	capability )

Query capabilities of a DMIC instance.

This function reports whether the instance supports FIFO and/or DMA paths, channel count, buffer model support, maximum clock information, gain/boost/IIR filter support, and other relevant capability fields.

Parameters

instance	DMIC instance identifier.
capability	Pointer to capability output structure.

Returns

Error type dmic_status_en:

DMIC_OK : Capability query successful
DMIC_ERROR_INVALID_PARAM : Null capability pointer
DMIC_ERROR_INVALID_CONTEXT: Invalid DMIC instance identifier

◆ dmic_config_channel()

dmic_status_en dmic_config_channel	(	dmic_instance_en	instance,
		uint8_t	channel,
		const dmic_channel_config_t *	cfg )

Configure the channel settings for a given DMIC instance.

This function sets up the channel configuration for a specified channel of the given DMIC instance. It writes user-provided configuration values to the internal context structure and prepares the channel for data conversion. This function should be called before starting capture operations or transferring data to hardware registers.

Parameters

instance	DMIC instance identifier (e.g., DMIC0, DMIC1)
channel	Channel number to configure
cfg	Pointer to the channel configuration structure dmic_channel_config_t

Returns

Error type dmic_status_en:

DMIC_OK : Configuration successful
DMIC_ERROR_INVALID_PARAM : Null configuration pointer or invalid channel
DMIC_ERROR_INVALID_CONTEXT: Invalid DMIC instance identifier

◆ dmic_configure_io()

dmic_status_en dmic_configure_io	(	dmic_instance_en	instance,
		const dmic_io_config_t *	dmic_config )

Configure the I/O settings for a given DMIC instance.

This function sets up the I/O configuration for the given DMIC instance. It writes user-provided timing and polarity values to the internal context structure and prepares the interface for capture. This function should be called before starting capture operations or transferring data to hardware registers.

Parameters

instance	DMIC instance identifier (e.g., DMIC0, DMIC1)
dmic_config	Pointer to the I/O configuration structure dmic_io_config_t

Returns

Error type dmic_status_en:

DMIC_OK : Configuration successful
DMIC_ERROR_INVALID_PARAM : Null configuration pointer
DMIC_ERROR_INVALID_CONTEXT: Invalid DMIC instance identifier

◆ dmic_enable_interrupts()

dmic_status_en dmic_enable_interrupts	(	dmic_instance_en	instance,
		uint32_t	mask )

Enables specific interrupt sources.

This function enables interrupts represented by the provided bitmask. Interrupt status is typically acknowledged in backend ISR flow and/or through low-level interrupt acknowledge APIs where available.

Parameters

instance	DMIC instance identifier.
mask	Bitwise OR of dmic_int_en values to enable.

Returns

Error type dmic_status_en:

DMIC_ERROR_INVALID_CONTEXT : Invalid DMIC instance identifier

◆ dmic_reset()

dmic_status_en dmic_reset ( dmic_instance_en instance )

Reset the DMIC module and its associated components.

This function resets the specified DMIC instance and its associated components, including:

DMIC Interface
Input channels for the selected instance
Driver runtime/software state defaults

Returns

Error type dmic_status_en:

DMIC_OK : Reset successful

◆ dmic_enable()

dmic_status_en dmic_enable ( dmic_instance_en instance )

Enable the specified DMIC instance.

This function powers/enables the DMIC hardware interface for the given instance. Streaming does not begin until dmic_start is called. It should be called after all necessary configurations such as clock and input-path setup are completed.

Parameters

instance DMIC instance identifier (e.g., DMIC0, DMIC1)

Returns

Error type dmic_status_en:

DMIC_OK : DMIC enabled successfully
DMIC_ERROR_INVALID_CONTEXT: Invalid DMIC instance identifier

◆ dmic_disable()

dmic_status_en dmic_disable ( dmic_instance_en instance )

Disable the specified DMIC instance.

This function disables the DMIC hardware interface for the given instance. Stop-vs-disable semantics:

dmic_stop is the streaming control API and, in current implementation, it also performs hardware disable as part of stop.
dmic_disable is a direct hardware disable API. Calling dmic_disable after a successful dmic_stop is allowed and behaves as an idempotent no-op on already-disabled hardware state. It is typically used during shutdown, reconfiguration, or power management sequences.

Parameters

instance DMIC instance identifier (e.g., DMIC0, DMIC1)

Returns

Error type dmic_status_en:

DMIC_OK : DMIC disabled successfully
DMIC_ERROR_INVALID_CONTEXT: Invalid DMIC instance identifier

◆ dmic_isr()

dmic_status_en dmic_isr ( dmic_instance_en instance )

Interrupt Service Routine (ISR) for the DMIC interface.

This function handles interrupts triggered by the DMIC interface. It retrieves the context for the specified DMIC instance and processes the data. If the context is invalid, it returns an error.

Parameters

instance The DMIC instance identifier.

Returns: dmic_status_en Returns DMIC_ERROR_INVALID_CONTEXT if the context is null, otherwise returns the result of the backend ISR handler.

◆ dmic_start()

dmic_status_en dmic_start ( dmic_instance_en instance )

Start the DMIC operation for the specified instance.

This function starts capture/streaming for the given instance after it has already been enabled and configured.

Ensure that all required configurations are completed before calling this function.

Parameters

instance DMIC instance identifier (e.g., DMIC0, DMIC1)

Returns

Error type dmic_status_en:

DMIC_OK : DMIC started successfully
DMIC_ERROR_INVALID_CONTEXT: Invalid or uninitialized DMIC instance

◆ dmic_stop()

dmic_status_en dmic_stop ( dmic_instance_en instance )

Stop the DMIC operation for the specified instance.

This function stops capture/streaming for the given instance, halting audio data capture. Stop-vs-disable semantics:

Current implementation performs stop + hardware disable in this API.
After dmic_stop returns DMIC_OK, the instance is no longer capturing and is also hardware-disabled.
To resume capture, call dmic_enable and then dmic_start.

All active transfers will be terminated, and the interface will enter an idle state. Current implementation also disables the DMIC hardware instance (equivalent to stop + disable).

Parameters

instance DMIC instance identifier (e.g., DMIC0, DMIC1)

Returns

Error type dmic_status_en:

DMIC_OK : DMIC stopped successfully
DMIC_ERROR_INVALID_CONTEXT: Invalid DMIC instance identifier

◆ dmic_read()

dmic_status_en dmic_read	(	dmic_instance_en	instance,
		dmic_buffer_context_t *	buf,
		int32_t	timeout )

Poll and read audio data for an instance.

This API is intended for polling-based data collection. In DMA mode, a successful read returns one completed period from the active DMA ring buffer (zero-copy buffer contract applies). Timeout behavior in DMA mode:

timeout < 0: wait indefinitely for next completed period.
timeout > 0: wait until timeout expires.
timeout == 0: return immediately; if no completed period is available, return DMIC_OK with offset_bytes=0 and available_bytes=0. In FIFO mode, depending on availability and backend policy, data may be returned as a complete request or a partial chunk.

Parameters

instance	DMIC instance identifier.
buf	Buffer descriptor. Caller provides channel/buffer/size and receives filled data according to available_bytes. buf->buffer_size is treated as maximum writable bytes and is not exceeded. Size calculations must use 4 bytes per sample container. In DMA mode, buf->buffer must reference the same DMA ring buffer configured through dmic_dma_config_t.buffer.
timeout	Timeout in milliseconds. If timeout < 0, wait indefinitely.

Returns: Error type dmic_status_en.

◆ dmic_read_nonblocking()

dmic_status_en dmic_read_nonblocking	(	dmic_instance_en	instance,
		dmic_buffer_context_t *	buf )

Non-blocking audio data query/read for an instance.

This API checks for available captured data and returns immediately without waiting.

FIFO mode: performs an immediate read of currently available samples.
DMA mode: same semantics as dmic_read(..., timeout=0) and returns immediately with available period data (or zero bytes if none are ready).

Parameters

instance	DMIC instance identifier.
buf	Buffer descriptor to receive currently available data information and payload metadata.

Returns

Error type dmic_status_en.

DMIC_OK : Data was available and returned in buf, or no data was available (indicated by available_bytes == 0). In FIFO mode, if a callback is registered, the driver may also report DMIC_EVENT_READ_NOT_READY for immediate no-data reads.

◆ dmic_set_channel_volume()

dmic_status_en dmic_set_channel_volume	(	dmic_instance_en	instance,
		uint8_t	channel,
		float	volume_db )

Sets input volume for a channel.

Parameters

instance	DMIC instance identifier.
channel	Channel number.
volume_db	Volume level in dB. The driver quantizes this value to the nearest supported register step.

Returns

Error type dmic_status_en:

DMIC_OK : DMIC Volume Set successfully
DMIC_ERROR_INVALID_PARAM : Invalid channel

◆ dmic_set_channel_gain()

dmic_status_en dmic_set_channel_gain	(	dmic_instance_en	instance,
		dmic_channel_en	channel,
		dmic_gain_ctrl_en	gain_ctrl )

Sets microphone gain for a channel.

Parameters

instance	DMIC instance identifier.
channel	Channel number.
gain_ctrl	Gain control setting.

Returns

Error type dmic_status_en:

DMIC_OK : DMIC Gain Set successfully
DMIC_ERROR_INVALID_PARAM : Invalid channel
DMIC_ERROR_INVALID_GAIN : DMIC Gain Level Invalid

◆ dmic_set_channel_boost()

dmic_status_en dmic_set_channel_boost	(	dmic_instance_en	instance,
		dmic_channel_en	channel,
		dmic_boost_en	boost_level )

Sets digital boost level for a channel.

Parameters

instance	DMIC instance identifier.
channel	Channel number.
boost_level	Boost setting value.

Returns

Error type dmic_status_en:

DMIC_OK : DMIC Boost Set successfully
DMIC_ERROR_INVALID_PARAM : Invalid channel
DMIC_ERROR_INVALID_BOOST : DMIC Boost Level Invalid

◆ dmic_register_callback()

dmic_status_en dmic_register_callback	(	dmic_instance_en	instance,
		dmic_event_cb_t	event_cb,
		void *	user_data )

Registers a callback for DMIC events.

Parameters

instance	DMIC instance identifier.
callback	User-defined callback function.
user_data	User context to pass to callback.

Returns

Error type dmic_status_en:

DMIC_OK : Callback Registered

◆ dmic_config_data_path()

dmic_status_en dmic_config_data_path	(	dmic_instance_en	instance,
		const dmic_data_path_config_t *	cfg )

Unified data-path configuration API for FIFO or DMA.

The API internally selects FIFO or DMA based on active backend capability and applies the matching portion of dmic_data_path_config_t.

Parameters

instance	DMIC instance identifier.
cfg	Pointer to unified data-path configuration.

Returns

Error type dmic_status_en:

DMIC_OK : Configuration successful
DMIC_ERROR_INVALID_PARAM : Invalid argument(s)
DMIC_ERROR_INVALID_CONTEXT: Invalid DMIC context/backend
DMIC_ERROR_NOT_SUPPORTED : Operation or option not supported in active backend (including FIFO threshold and interrupt flags)

Note: For DMA mode, invalid argument(s) include violating DMA memory, size, alignment, or descriptor/ring constraints documented above.

Functions

Detailed Description

Function Documentation

◆ dmic_init()

◆ dmic_get_capability()

◆ dmic_config_channel()

◆ dmic_configure_io()

◆ dmic_enable_interrupts()

◆ dmic_reset()

◆ dmic_enable()

◆ dmic_disable()

◆ dmic_isr()

◆ dmic_start()

◆ dmic_stop()

◆ dmic_read()

◆ dmic_read_nonblocking()

◆ dmic_set_channel_volume()

◆ dmic_set_channel_gain()

◆ dmic_set_channel_boost()

◆ dmic_register_callback()

◆ dmic_config_data_path()