lib_mic_array: PDM microphone array library£££doc/rst/lib_mic_array.html#lib-mic-array-pdm-microphone-array-library

lib_mic_array: PDM microphone array library$$$Overview$$$High level process view$$$Execution contexts£££doc/rst/src/overview.html#execution-contexts

The mic array unit uses two different execution contexts. The first is the PDM RX service (“PDM RX”), which is responsible for reading PDM samples from the physical port, and has relatively little work to do, but also has a strict real-time constraint on reading port data in a timely manner. The second is the decimation thread, which is where all processing other than PDM capture is performed.

This two-context model relaxes the need for tight coupling and synchronization between PDM RX and the decimation thread, allowing significant flexibility in how samples are processed in the decimation thread.

PDM RX is typically run within an interrupt on the same hardware core as the decimation thread, but it can also be run as a separate thread in cases where many channels result in a high processing load.

Likewise, the decimators may be split into multiple parallel hardware threads in the case where the processing load exceeds the MIPS available in a single hardware thread.

lib_mic_array: PDM microphone array library$$$Overview$$$High level process view$$$Step 1: PDM capture£££doc/rst/src/overview.html#step-1-pdm-capture

The PDM data signal is captured by the xcore.ai device’s port hardware. The port receiving the PDM signals buffers the received samples. Each time the port buffer is filled, PDM RX reads the received samples.

Samples are collected word-by-word and assembled into blocks. Each time a block has been filled, the block is transferred to the decimation thread where all remaining mic array processing takes place.

The size of PDM data blocks varies depending upon the configured number of microphone channels and the configured second stage decimator’s decimation factor. Each PDM data block will contain exactly enough PDM samples to produce one new mic array (multi-channel) output sample.

lib_mic_array: PDM microphone array library$$$Overview$$$High level process view$$$Step 2: First stage decimation£££doc/rst/src/overview.html#step-2-first-stage-decimation

The conversion from the high-sample-rate PDM stream to lower-sample-rate PCM stream involves two stages of decimating filters. After the decimation thread receives a block of PDM samples, the samples are filtered by the first stage decimator.

The first stage decimator has a fixed decimation factor of 32 and a fixed tap count of 256. An application is free to supply its own filter coefficients for the first stage decimator (using the fixed decimation factor and tap count), however this library also provides a reference filter for the first stage decimator that is recommended for most applications.

The first stage decimating filter is an FIR filter with 16-bit coefficients, and where each input sample corresponds to a +1 or a -1 (typical for PDM signals). The output of the first stage decimator is a block of 32-bit PCM samples with a sample time 32 times longer than the PDM sample time.

See Decimation filters for further details.

lib_mic_array: PDM microphone array library$$$Overview$$$High level process view$$$Step 3: Second stage decimation£££doc/rst/src/overview.html#step-3-second-stage-decimation

The second stage decimator is a decimating FIR filter with a configurable decimation factor and tap count. Like the first stage decimator, this library provides a reference filter suitable for the second stage decimator. The supplied filter has a tap count of 64 and a decimation factor of 6.

The output of the first stage decimator is a block of N*K PCM values, where N is the number of microphones and K is the second stage decimation factor. This is just enough samples to produce one output sample from the second stage decimator.

The resulting sample is vector-valued (one element per channel) and has a sample time corresponding to 32*K PDM clock periods. Using the reference filters and a 3.072 MHz PDM clock, his corresponds to an output sampling rate of 16 kHz, 32 kHz, or 48 kHz.

See Decimation filters for further details.

lib_mic_array: PDM microphone array library$$$Overview$$$High level process view$$$Step 4: post-processing£££doc/rst/src/overview.html#step-4-post-processing

After second stage decimation, the resulting sample goes to post-processing where two (optional) post-processing steps are available.

The first is a simple IIR filter, called DC Offset Elimination, which seeks to ensure each output channel tends to approach zero mean. DC Offset Elimination can be disabled if not desired. See Sample filters for further details.

The second post-processing step is framing, where instead of signalling each sample of audio to subsequent processing stages one at a time, samples can be aggregated and transferred to subsequent processing stages as non-overlapping blocks. The size of each frame is configurable (down to 1 sample per frame, where framing is functionally disabled).

Finally, the sample or frame is transmitted over a XCORE channel from the mic array module to the next stage of the processing pipeline.

lib_mic_array: PDM microphone array library$$$Overview$$$High level process view$$$Extending/Modifying mic array behaviour£££doc/rst/src/overview.html#extending-modifying-mic-array-behaviour

Most applications are expected to use the default usage model, which provides a complete, ready-to-integrate mic-array pipeline and should be sufficient for the majority of use cases. Only applications with specialised requirements such as non-standard data-transfer mechanisms, custom decimation behaviour etc. are likely to require customisation beyond the default model.

At the core of lib_mic_array are several C++ class templates which are loosely coupled and intended to be easily overridden for modified behaviour. The mic array unit itself is an object made by the composition of several smaller components which perform well-defined roles (See Software structure).

For example, modifying the mic array unit to use some mechanism other than a channel to move the audio frames out of the mic array is a matter of defining a small new class encapsulating just the modified transfer behaviour, and then instantiating the mic array class template with the new class as the appropriate template parameter.

lib_mic_array: PDM microphone array library$$$Using lib_mic_array$$$Default usage model$$$Identify hardware resources£££doc/rst/src/getting_started.html#mic-array-identify-resources

The key hardware resources to be identified are the ports and clock blocks that will be used by the mic array unit. The ports correspond to the physical pins on which clocks and sample data will be signaled. Clock blocks are a type of hardware resource which can be attached to ports to coordinate the presentation and capture of signals on physical pins.

...
<Tile Number="1" Reference="tile[1]">
  <!-- MIC related ports -->
  <Port Location="XS1_PORT_1G"  Name="PORT_PDM_CLK"/>
  <Port Location="XS1_PORT_1F"  Name="PORT_PDM_DATA"/>
  <!-- Audio ports -->
  <Port Location="XS1_PORT_1D"  Name="PORT_MCLK_IN_OUT"/>
  <Port Location="XS1_PORT_1C"  Name="PORT_I2S_BCLK"/>
  <Port Location="XS1_PORT_1B"  Name="PORT_I2S_LRCLK"/>
  <!-- Used for looping back clocks -->
  <Port Location="XS1_PORT_1N"  Name="PORT_NOT_IN_PACKAGE_1"/>
</Tile>
...

lib_mic_array: PDM microphone array library$$$Using lib_mic_array$$$Default usage model$$$Declare hardware resources£££doc/rst/src/getting_started.html#declare-hardware-resources

Once the ports and clock blocks to be used have been identified, these resources can be represented in code using a pdm_rx_resources_t struct. The following is an example of declaring resources in a DDR configuration. See pdm_rx_resources_t, PDM_RX_RESOURCES_SDR() and PDM_RX_RESOURCES_DDR() for more details.

pdm_rx_resources_t pdm_res = PDM_RX_RESOURCES_DDR(
                                PORT_MCLK_IN,
                                PORT_PDM_CLK,
                                PORT_PDM_DATA,
                                24576000,
                                3072000,
                                XS1_CLKBLK_1,
                                XS1_CLKBLK_2);

lib_mic_array: PDM microphone array library$$$Using lib_mic_array$$$Default usage model$$$Initialise and start the mic array£££doc/rst/src/getting_started.html#initialise-and-start-the-mic-array

Once the resources are identified and the pdm_rx_resources_t struct is populated, the application needs to call the mic array functions to initialise and start the mic array task.

Call mic_array_init() to initialise the mic array component. mic_array_init() accepts arguments for configuring the mic array component at run-time.

Additional configuration parameters defined in mic_array_conf_default.h specify the default compile-time configuration of the mic array component. These can be overridden by the application in a mic_array_conf.h file included by the application or through the application’s CMakeLists.txt. See the Configuration defines (mic_array_conf_default.h) section for details.

This is followed by a call to mic_array_start() which starts the mic array thread(s). mic_array_start() takes a single argument - the XCORE chanend used to transmit audio frames to subsequent stages of the processing pipeline. Typically, the call to mic_array_start() will be placed directly in a par {...} block along with other threads to be started on the same tile. mic_array_start() is a blocking call that runs the mic array thread(s) until the application signals shutdown using ma_shutdown().

lib_mic_array: PDM microphone array library$$$Using lib_mic_array$$$Default usage model$$$Receive PCM frames£££doc/rst/src/getting_started.html#receive-pcm-frames

The application receives output PCM frames from the mic array task over an XCORE chanend. This is the other end of the XCORE chanend passed to mic_array_start(). A call to ma_frame_rx() with the chanend as an argument is typically called from another thread to receive PCM blocks from the mic array for further processing.

lib_mic_array: PDM microphone array library$$$Using lib_mic_array$$$Default usage model$$$Shutdown£££doc/rst/src/getting_started.html#shutdown

The application can to shut down the mic array task by calling ma_shutdown(). The shutdown request is sent over the same channel end that is used by ma_frame_rx(). Therefore, the application must ensure that ma_frame_rx() is not being called concurrently when invoking ma_shutdown().

Calling ma_shutdown() causes the mic-array threads to terminate (mic_array_start() returns). ma_shutdown() itself returns only after all mic-array threads have fully terminated. Once shut down, mic_array_init() and mic_array_start() can be called again to restart the mic array.

lib_mic_array: PDM microphone array library$$$Using lib_mic_array$$$Default usage model$$$Example code£££doc/rst/src/getting_started.html#example-code

The code block below shows the application main() function containing calls to the mic array functions:

#include <platform.h>
#include <xs1.h>
#include "mic_array_task.h"


on tile[PORT_PDM_CLK_TILE_NUM] : port p_mclk = PORT_MCLK_IN_OUT;
on tile[PORT_PDM_CLK_TILE_NUM] : port p_pdm_clk = PORT_PDM_CLK;
on tile[PORT_PDM_CLK_TILE_NUM] : port p_pdm_data = PORT_PDM_DATA;
on tile[PORT_PDM_CLK_TILE_NUM] : clock clk_a = XS1_CLKBLK_1;
on tile[PORT_PDM_CLK_TILE_NUM] : clock clk_b = XS1_CLKBLK_2;

unsafe{
void receive_from_mics(chanend c_pcm)
{
  int32_t audio_frame[MIC_ARRAY_CONFIG_MIC_COUNT * 1]; // frame = 1 sample for each of the MIC_ARRAY_CONFIG_MIC_COUNT channels
  while(1)
  {
    ma_frame_rx(audio_frame, (chanend_t)c_pcm, MIC_ARRAY_CONFIG_MIC_COUNT, 1);
    // further processing of the pcm data...
  }
}

int main() {
  chan c_audio_frames;
  par {
    on tile[1]: {
      pdm_rx_resources_t pdm_res = PDM_RX_RESOURCES_DDR(p_mclk, p_pdm_clk, p_pdm_data, 24576000, 3072000, clk_a, clk_b);

      mic_array_init(&pdm_res, null, 48000);

      par {
        mic_array_start((chanend_t) c_audio_frames);
        receive_from_mics(c_audio_frames);
      }
    }
  }
  return 0;
}
}

lib_mic_array: PDM microphone array library$$$Using lib_mic_array$$$Default usage model$$$Limitations of the default model£££doc/rst/src/getting_started.html#limitations-of-the-default-model

The default model for using the mic array, while easiest to integrate in an application, has the following constraints:

• Fixed supported output sampling rates:

  Only 16 kHz, 32 kHz, and 48 kHz output sampling rates are supported. This is because the default decimation filters provided as part of the library (see Filters provided as part of lib_mic_array) are designed for a small set of decimation factors and they assume a fixed input PDM frequency of 3.072 MHz. See Custom decimation filters and app_custom_filter for using custom filters for the mic array (provided they are compatible with the TwoStageDecimator implementation)

• Only one mic array instance:

  The default model does not support multiple independent, mic array instances

• Single decimator thread:

  In the default model, the entire decimation process runs within a single hardware thread. For higher microphone counts, this may exceed the available compute capacity of one thread (see mic array MIPS requirement). In general, up to four microphones can be accommodated within a single thread, depending on the configuration. Higher channel counts therefore require splitting the decimation process across multiple hardware threads and using lib_mic_array in a customised configuration. The app_par_decimator example demonstrates a two-threaded decimator implementation.

• Memory usage:

  The default API incurs an additional memory overhead compared to a custom instantiation of MicArray object. This overhead is primarily from wrapper code and inclusion of all provided filter coefficient sets, even when only a subset is used (see Memory usage (in bytes)). For memory‑constrained systems a custom configuration might be preferable.

For custom usage involving creating a MicArray object with potentially custom implementations of the component classes, refer to the advanced use methods described in Advanced usage

lib_mic_array: PDM microphone array library$$$Examples$$$Running the examples$$$Required hardware£££doc/rst/src/examples.html#required-hardware

• 1x XK-VOICE-L71 board

• 2x Micro USB cable (For USB power and XTAG)

• 3.5mm audio cable to connect to the line out connector on the `XK-VOICE-L71 board

lib_mic_array: PDM microphone array library$$$Examples$$$Running the examples$$$Setup procedure£££doc/rst/src/examples.html#setup-procedure

1. Connect the XTAG to the XK-VOICE-L71

2. Connect one Micro USB cable between the host computer and the XK-VOICE-L71 USB port.

3. Connect the other Micro USB cable between the host computer and the XTAG.

XK-VOICE-L71 setup shows the XK-VOICE-L71 board with all the cables connected.

lib_mic_array: PDM microphone array library$$$Examples$$$Running the examples$$$Building£££doc/rst/src/examples.html#building

The following instructions assumes that the XMOS XTC tools has been downloaded and installed (see README for required version).

Installation instructions can be found here. Particular attention should be paid to the section Installation of required third-party tools.

The application uses the XMOS build and dependency system, xcommon-cmake. xcommon-cmake is bundled with the XMOS XTC tools.

To configure the build, run the following from an XTC command prompt:

cd examples
cd app_mic_array
cmake -G "Unix Makefiles" -B build

Any missing dependencies will be downloaded by the build system at this configure step.

Finally, the application binaries can be built using xmake:

xmake -j -C build

The example build four configurations - 1mic_isr, 1mic_thread, 2mic_isr and 2mic_thread, which indicate the number of microphones used and whether the PDM RX service runs in an ISR or a hardware thread. The executable binaries (.xe files) for each configuration are placed in bin/<config> directory (e.g. bin/2mic_isr/app_mic_array_2mic_isr.xe).

lib_mic_array: PDM microphone array library$$$Examples$$$Running the examples$$$Running the application£££doc/rst/src/examples.html#running-the-application

To run the application from the /examples/app_mic_array directory, execute:

xrun --xscope bin/2mic_isr/app_mic_array_2mic_isr.xe

The command above runs the 2mic_isr configuration. To run a different configuration, replace 2mic_isr in the path with the desired build variant.

When running, the application captures the microphones audio and routes it to the DAC on the XK-VOICE-L71 after linearly scaling the PCM samples received from lib_mic_array by a factor of 64. Connect headphones to the 3.5mm LINE OUT jack on the board to listen to the captured microphone signal.

lib_mic_array: PDM microphone array library$$$Examples$$$Running the examples$$$Other examples£££doc/rst/src/examples.html#other-examples

Starting at sample rate 16000
Starting at sample rate 48000
Starting at sample rate 16000
Starting at sample rate 48000
Starting at sample rate 16000
Starting at sample rate 48000
Starting at sample rate 16000

lib_mic_array: PDM microphone array library$$$Resource usage$$$Discrete Resources$$$Ports£££doc/rst/src/resource_usage.html#ports

In all configurations, the mic array unit requires 3 of the xcore.ai device’s hardware ports. Two of these ports (for the master audio clock and PDM clock) must be 1-bit ports. The third (PDM capture port) can be 1-, 4- or 8-bit, depending on the microphone count and SDR/DDR configuration.

lib_mic_array: PDM microphone array library$$$Resource usage$$$Discrete Resources$$$Clock Blocks£££doc/rst/src/resource_usage.html#clock-blocks

In applications which use an SDR microphone configuration, the mic array unit requires 1 of the xcore.ai device’s 5 clock blocks. This clock block is used both to generate the PDM clock from the master audio clock and as the PDM capture clock.

In applications which use a DDR microphone configuration, the mic array unit requires 2 of the xcore.ai device’s 5 clock blocks. One clock is used to generate the PDM clock from the master audio clock, and the other is used as the PDM capture clock (which must operate at different rates in a DDR configuration).

lib_mic_array: PDM microphone array library$$$Resource usage$$$Discrete Resources$$$Chanends£££doc/rst/src/resource_usage.html#chanends

Chanends are a hardware resource which allow threads (possibly running on different tiles) to communicate over channels. The mic array unit requires 4 chanends. Two are used for communication between the PDM rx service and the decimation thread. Two more are needed for transferring completed frames from the mic array unit to other application components.

lib_mic_array: PDM microphone array library$$$Resource usage$$$Discrete Resources$$$Threads£££doc/rst/src/resource_usage.html#threads

The PDM rx service can run either as a stand-alone thread or as an interrupt within the decimator thread. Accordingly, the mic array requires one thread when the PDM rx service runs in interrupt mode, and two threads when it runs as a stand-alone thread.

Running PDM rx as a stand-alone thread modestly reduces the mic array unit’s MIPS consumption by eliminating the context switch overhead of an interrupt. The cost of that is one hardware thread.

lib_mic_array: PDM microphone array library$$$Software structure$$$High level view$$$Mic Array / Decimator thread£££doc/rst/src/software_structure.html#mic-array-decimator-thread

Aside from aggregating its sub-components into a single logical entity, the MicArray class template also holds the high-level logic for capturing, processing and coordinating movement of the audio stream data.

The following code snippet is the implementation for the main mic array thread (or “decimation thread”; not to be confused with (optional) PDM capture thread).

int32_t sample_out[MIC_COUNT] = {0};
volatile bool shutdown = false;

while(!shutdown){
  uint32_t *pdm_samples = PdmRx.GetPdmBlock();
  Decimator.ProcessBlock(sample_out, pdm_samples);
  SampleFilter.Filter(sample_out);
  shutdown = OutputHandler.OutputSample(sample_out);
}
PdmRx.Shutdown();
OutputHandler.CompleteShutdown();
}

The thread loops till OutputHandler.OutputSample() indicates a shutdown request and on each iteration,

• Requests a block of PDM sample data from the PDM rx service. This is a blocking call which only returns once a complete block becomes available.

• Passes the block of PDM sample data to the decimator to produce a single output sample.

• Applies a post-processing filter to the sample data.

• Passes the processed sample to the output handler to be transferred to the next stage of the processing pipeline. This may also be a blocking call, only returning once the data has been transferred.

Note that the MicArray object doesn’t care how these steps are actually implemented. For example, one output handler implementation may send samples one at a time over a channel. Another output handler implementation may collect samples into frames, and use a FreeRTOS queue to transfer the data to another thread.

lib_mic_array: PDM microphone array library$$$Software structure$$$High level view$$$Sub-Component initialization£££doc/rst/src/software_structure.html#sub-component-initialization

Each of MicArray’s sub-components may have implementation-specific configuration or initialization requirements. Each sub-component is a public member of MicArray (see MicArray sub-components). An application can access a sub-component directly to perform any type-specific initialization or other manipulation.

For example, the ChannelFrameTransmitter output handler class needs to know the chanend to be used for sending samples. This can be initialized on a MicArray object mics with mics.OutputHandler.SetChannel(c_sample_out).

lib_mic_array: PDM microphone array library$$$Software structure$$$Sub-Components$$$PdmRx£££doc/rst/src/software_structure.html#pdmrx

PdmRx, or the PDM RX service is the MicArray sub-component responsible for capturing PDM sample data, assembling it into blocks, and passing it along so that it can be decimated.

The MicArray class requires only that PdmRx implement GetPdmBlock(), a blocking call that returns a pointer to a block of PDM data which is ready for further processing and Shutdown(), which is called in the even of MicArray shutdown.

Generally speaking, PdmRx will derive from the StandardPdmRxService class template. StandardPdmRxService encapsulates the logic of using an xCore port for capturing PDM samples one word (32 bits) at a time, and managing two buffers where blocks of samples are collected. It also simplifies the logic of running PDM RX as either an interrupt or as a stand-alone thread.

It uses a streaming channel to transfer PDM blocks to the decimator. It also provides methods for installing an optimized ISR for PDM capture.

lib_mic_array: PDM microphone array library$$$Software structure$$$Sub-Components$$$Decimator£££doc/rst/src/software_structure.html#decimator

The Decimator sub-component encapsulates the logic of converting blocks of PDM samples into PCM samples. The TwoStageDecimator class is a decimator implementation that uses a pair of decimating FIR filters to accomplish this.

The first stage has a fixed tap count of 256 and a fixed decimation factor of 32. The second stage has a configurable tap count and decimation factor.

For more details, see Decimation filters.

lib_mic_array: PDM microphone array library$$$Software structure$$$Sub-Components$$$SampleFilter£££doc/rst/src/software_structure.html#samplefilter

The SampleFilter sub-component is used for post-processing samples emitted by the decimator. Two implementations for the sample filter sub-component are provided by this library.

The NopSampleFilter class can be used to effectively disable per-sample filtering on the output of the decimator. It does nothing to the samples presented to it, and so calls to it can be optimized out during compilation.

The DcoeSampleFilter class is used for applying the DC offset elimination filter to the decimator’s output. The DC offset elimination filter is meant to ensure the sample mean for each channel tends toward zero.

For more details, see Sample filters.

lib_mic_array: PDM microphone array library$$$Software structure$$$Sub-Components$$$OutputHandler£££doc/rst/src/software_structure.html#outputhandler

The OutputHandler sub-component is responsible for transferring processed sample data to subsequent processing stages.

There are two main considerations for output handlers. The first is whether audio data should be transferred sample-by-sample or as frames containing many samples. The second is the method of actually transferring the audio data.

The class ChannelSampleTransmitter sends samples one at a time to subsequent processing stages using an xCore channel.

The FrameOutputHandler class collects samples into frames, and uses a frame transmitter to send the frames once they’re ready.

lib_mic_array: PDM microphone array library$$$Decimation filters$$$Filters provided as part of lib_mic_array$$$Stage 1 filters£££doc/rst/src/decimator_stages.html#stage-1-filters

lib_mic_array: PDM microphone array library$$$Decimation filters$$$Filters provided as part of lib_mic_array$$$Stage 2 filters£££doc/rst/src/decimator_stages.html#stage-2-filters

lib_mic_array: PDM microphone array library$$$Decimation filters$$$Filters provided as part of lib_mic_array$$$Filter characteristics£££doc/rst/src/decimator_stages.html#filter-characteristics

This sections provides filters characteristics of the filters provided as part of lib_mic_array.

lib_mic_array: PDM microphone array library$$$Decimation filters$$$Filters provided as part of lib_mic_array$$$16 kHz output PCM sampling rate filter£££doc/rst/src/decimator_stages.html#khz-output-pcm-sampling-rate-filter

16 kHz output sampling rate filter freq response shows the frequency response of the first and second stages of the provided 16 kHz sampling rate filters as well as the cascaded overall response.

lib_mic_array: PDM microphone array library$$$Decimation filters$$$Filters provided as part of lib_mic_array$$$32 kHz output PCM sampling rate filter£££doc/rst/src/decimator_stages.html#id1

32 kHz output sampling rate filter freq response shows the frequency response of the first and second stages of the provided 32 kHz sampling rate filters as well as the cascaded overall response. Note that the overall combined response provides a nice flat passband.

lib_mic_array: PDM microphone array library$$$Decimation filters$$$Filters provided as part of lib_mic_array$$$48 kHz output PCM sampling rate filter£££doc/rst/src/decimator_stages.html#id2

48 kHz output sampling rate filter freq response shows the frequency response of the first and second stages of the provided 48 kHz sampling rate filters as well as the cascaded overall response. Note that the overall combined response provides a nice flat passband.

The following sections provide more details about the first and second stage decimation filters, implemented in TwoStageDecimator.

lib_mic_array: PDM microphone array library$$$Decimation filters$$$Decimator stage 1$$$Filter implementation (Stage 1)£££doc/rst/src/decimator_stages.html#filter-implementation-stage-1

The input to the first stage decimator (here called “Stream A”) is a stream of 1-bit PDM samples with a sample rate of PDM_FREQ. Rather than each PDM sample representing a value of 0 or 1, each PDM sample represents a value of either +1 or -1. Specifically, on-chip and in-memory, a bit value of 0 represents +1 and a bit value of 1 represents -1.

The output from the first stage decimator, Stream B, is a stream of 32-bit PCM samples with a sample rate of PDM_FREQ/S1_DEC_FACTOR = PDM_FREQ/32. For example, if PDM_FREQ is 3.072 MHz, then Stream B’s sample rate is 96.0 kHz.

The first stage filter is structured to make optimal use of the XCore XS3 vector processing unit (VPU), which can compute the dot product of a pair of 256-element 1-bit vectors in a single cycle. The first stage uses 256 16-bit coefficients for its filter taps.

The signature of the filter function is

int32_t fir_1x16_bit(uint32_t signal[8], uint32_t coeff_1[]);

Each time 32 PDM samples (1 word) become available for an audio channel, those samples are shifted into the 8-word (256-bit) filter state, and a call to fir_1x16_bit results in 1 Stream B sample element for that channel.

The actual implementation for the first stage filter can be found in src/fir_1x16_bit.S. Additional usage details can be found in api/etc/fir_1x16_bit.h.

Note that the 256 16-bit filter coefficients are not stored in memory as a standard coefficient array (i.e. int16_t filter[256] = {b[0], b[1], ... };). Rather, in order to take advantage of the VPU, the coefficients must be rearranged bit-by-bit into a block form suitable for VPU processing.

The filter state (delay line) consists of 256 one-bit PDM samples (equal to the number of filter taps) and requires a buffer of 8 unsigned 32-bit words for storage.

lib_mic_array: PDM microphone array library$$$Decimation filters$$$Decimator stage 1$$$Filter Conversion Script£££doc/rst/src/decimator_stages.html#filter-conversion-script

Taking a set of floating-point coefficients, quantizing them into 16-bit coefficients and ‘boggling’ them into the correct memory layout can be a tricky business. To simplify this process, this library provides a Python3 script that does this process automatically.

The script can be found in this repository at python/stage1.py.

lib_mic_array: PDM microphone array library$$$Decimation filters$$$Decimator stage 2$$$Filter implementation (Stage 2)£££doc/rst/src/decimator_stages.html#filter-implementation-stage-2

The input to the second stage decimator (here called “Stream B”) is the stream of 32-bit PCM samples emitted from the first stage decimator with a sample rate of PDM_FREQ/32.

The output from the second stage decimator, Stream C, is a stream of 32-bit PCM samples with a sample rate of PDM_FREQ/(32*S2_DEC_FACTOR). For example, if PDM_FREQ is 3.072 MHz, and S2_DEC_FACTOR is 6, then Stream C’s sample rate (the sample rate received by the main application code) is

3.072 MHz / (32*6) = 16 kHz

The second stage filter uses the 32-bit FIR filter implementation from lib_xcore_math. See xs3_filter_fir_s32() in that library for more implementation details.

The filter state (delay line) consists of as many 32-bit samples as there are taps in the stage-2 filter, and requires those many 32-bit words for storage.

lib_mic_array: PDM microphone array library$$$Sample filters$$$DC Offset elimination$$$Enabling/Disabling DCOE£££doc/rst/src/sample_filters.html#enabling-disabling-dcoe

Whether the DCOE filter is enabled by default and how to enable or disable it depends on which approach your project uses to include the mic array component in the application.

#include "mic_array/cpp/MicArray.hpp"
using namespace mic_array;
...
template <unsigned MIC_COUNT, class TDecimator,
          class TPdmRx, class TOutputHandler>
class DcoeEnabledMicArray : public MicArray<MIC_COUNT, TDecimator, TPdmRx,
                                    DcoeSampleFilter, TOutputHandler>
{
  ...
};

lib_mic_array: PDM microphone array library$$$Sample filters$$$DC Offset elimination$$$DCOE filter equation£££doc/rst/src/sample_filters.html#dcoe-filter-equation

As mentioned above, the DCOE filter is a simple IIR filter given by the following equation, where x[t] and x[t-1] are the current and previous input sample values respectively, and y[t] and y[t-1] are the current and previous output sample values respectively.

R = 252.0 / 256.0
y[t] = R * y[t-1] + x[t] - x[t-1]

lib_mic_array: PDM microphone array library$$$Sample filters$$$DC Offset elimination$$$DCOE filter frequency response£££doc/rst/src/sample_filters.html#dcoe-filter-frequency-response

The plot below indicates the frequency response of DCOE filter DCOE filter frequency response.