This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down list at the bottom of the left panel and select the desired version.

Digital Microphone (DMIC)

Overview

The audio DMIC interface provides access to digital microphones.

Configuration Options

Related configuration options:

API Reference

Related code samples

Digital Microphone (DMIC)

Perform PDM transfers using different configurations.

X-NUCLEO-IKS02A1 shield - MEMS microphone

Acquire audio using the digital MEMS microphone on X-NUCLEO-IKS02A1 shield.

group audio_dmic_interface

Abstraction for digital microphones.

Since

1.13

Version

0.1.0

Enums

enum dmic_state

DMIC driver states.

Values:

enumerator DMIC_STATE_UNINIT

Uninitialized.

enumerator DMIC_STATE_INITIALIZED

Initialized.

enumerator DMIC_STATE_CONFIGURED

Configured.

enumerator DMIC_STATE_ACTIVE

Active.

enumerator DMIC_STATE_PAUSED

Paused.

enumerator DMIC_STATE_ERROR

Error.

enum dmic_trigger

DMIC driver trigger commands.

Values:

enumerator DMIC_TRIGGER_STOP

Stop stream.

enumerator DMIC_TRIGGER_START

Start stream.

enumerator DMIC_TRIGGER_PAUSE

Pause stream.

enumerator DMIC_TRIGGER_RELEASE

Release paused stream.

enumerator DMIC_TRIGGER_RESET

Reset stream.

enum pdm_lr

PDM Channels LEFT / RIGHT.

Values:

enumerator PDM_CHAN_LEFT

Left channel.

enumerator PDM_CHAN_RIGHT

Right channel.

Functions

static inline uint32_t dmic_build_channel_map(uint8_t channel, uint8_t pdm, enum pdm_lr lr)

Build the channel map to populate struct pdm_chan_cfg.

Returns the map of PDM controller and LEFT/RIGHT channel shifted to the bit position corresponding to the input logical channel value

Parameters:

  • channel – The logical channel number

  • pdm – The PDM hardware controller number

  • lr – LEFT/RIGHT channel within the chosen PDM hardware controller

Returns:

Bit-map containing the PDM and L/R channel information

static inline void dmic_parse_channel_map(uint32_t channel_map_lo, uint32_t channel_map_hi, uint8_t channel, uint8_t *pdm, enum pdm_lr *lr)

Helper function to parse the channel map in pdm_chan_cfg.

Returns the PDM controller and LEFT/RIGHT channel corresponding to the channel map and the logical channel provided as input

Parameters:

  • channel_map_lo – Lower order/significant bits of the channel map

  • channel_map_hi – Higher order/significant bits of the channel map

  • channel – The logical channel number

  • pdm – Pointer to the PDM hardware controller number

  • lr – Pointer to the LEFT/RIGHT channel within the PDM controller

static inline uint32_t dmic_build_clk_skew_map(uint8_t pdm, uint8_t skew)

Build a bit map of clock skew values for each PDM channel.

Returns the bit-map of clock skew value shifted to the bit position corresponding to the input PDM controller value

Parameters:

  • pdm – The PDM hardware controller number

  • skew – The skew to apply for the clock output from the PDM controller

Returns:

Bit-map containing the clock skew information

static inline int dmic_configure(const struct device *dev, struct dmic_cfg *cfg)

Configure the DMIC driver and controller(s)

Configures the DMIC driver device according to the number of channels, channel mapping, PDM I/O configuration, PCM stream configuration, etc.

Parameters:

  • dev – Pointer to the device structure for DMIC driver instance

  • cfg – Pointer to the structure containing the DMIC configuration

Returns:

0 on success, a negative error code on failure

static inline int dmic_trigger(const struct device *dev, enum dmic_trigger cmd)

Send a command to the DMIC driver.

Sends a command to the driver to perform a specific action

Parameters:

  • dev – Pointer to the device structure for DMIC driver instance

  • cmd – The command to be sent to the driver instance

Returns:

0 on success, a negative error code on failure

static inline int dmic_read(const struct device *dev, uint8_t stream, void **buffer, size_t *size, int32_t timeout)

Read received decimated PCM data stream.

Optionally waits for audio to be received and provides the received audio buffer from the requested stream

Parameters:

  • dev – Pointer to the device structure for DMIC driver instance

  • stream – Stream identifier

  • buffer – Pointer to the received buffer address

  • size – Pointer to the received buffer size

  • timeout – Timeout in milliseconds to wait in case audio is not yet received, or SYS_FOREVER_MS

Returns:

0 on success, a negative error code on failure

struct pdm_io_cfg
#include <dmic.h>

PDM Input/Output signal configuration.

Parameters common to all PDM controllers

uint32_t min_pdm_clk_freq

Minimum clock frequency supported by the mic.

uint32_t max_pdm_clk_freq

Maximum clock frequency supported by the mic.

uint8_t min_pdm_clk_dc

Minimum duty cycle in % supported by the mic.

uint8_t max_pdm_clk_dc

Maximum duty cycle in % supported by the mic.

Parameters unique to each PDM controller

uint8_t pdm_clk_pol

Bit mask to optionally invert PDM clock.

uint8_t pdm_data_pol

Bit mask to optionally invert mic data.

uint32_t pdm_clk_skew

Collection of clock skew values for each PDM port.

struct pcm_stream_cfg
#include <dmic.h>

Configuration of the PCM streams to be output by the PDM hardware.

Note

if either pcm_rate or pcm_width is set to 0 for a stream, the stream would be disabled

Public Members

uint32_t pcm_rate

PCM sample rate of stream.

uint8_t pcm_width

PCM sample width of stream.

uint16_t block_size

PCM sample block size per transfer.

struct k_mem_slab *mem_slab

SLAB for DMIC driver to allocate buffers for stream.

struct pdm_chan_cfg
#include <dmic.h>

Mapping/ordering of the PDM channels to logical PCM output channel.

Since each controller can have 2 audio channels (stereo), there can be a total of 8x2=16 channels. The actual number of channels shall be described in act_num_chan.

If 2 streams are enabled, the channel order will be the same for both streams.

Each channel is described as a 4-bit number, the least significant bit indicates LEFT/RIGHT selection of the PDM controller.

The most significant 3 bits indicate the PDM controller number:

  • bits 0-3 are for channel 0, bit 0 indicates LEFT or RIGHT

  • bits 4-7 are for channel 1, bit 4 indicates LEFT or RIGHT and so on.

CONSTRAINT: The LEFT and RIGHT channels of EACH PDM controller needs to be adjacent to each other.

Requested channel map

uint32_t req_chan_map_lo

Channels 0 to 7.

uint32_t req_chan_map_hi

Channels 8 to 15.

Actual channel map that the driver could configure

uint32_t act_chan_map_lo

Channels 0 to 7.

uint32_t act_chan_map_hi

Channels 8 to 15.

Public Members

uint8_t req_num_chan

Requested number of channels.

uint8_t act_num_chan

Actual number of channels that the driver could configure.

uint8_t req_num_streams

Requested number of streams for each channel.

uint8_t act_num_streams

Actual number of streams that the driver could configure.

struct dmic_cfg
#include <dmic.h>

Input configuration structure for the DMIC configuration API.

Public Members

struct pcm_stream_cfg *streams

Array of pcm_stream_cfg for application to provide configuration for each stream.