Microphone Array RTOS Driver

This driver can be used to instantiate and control a dual DDR PDM microphone interface on xcore in an RTOS application.

Initialization API

The following structures and functions are used to initialize and start a microphone array driver instance.

enum rtos_mic_array_format_t

Typedef for the RTOS mic array driver audio format

Values:

enumerator RTOS_MIC_ARRAY_CHANNEL_SAMPLE
enumerator RTOS_MIC_ARRAY_SAMPLE_CHANNEL
enumerator RTOS_MIC_ARRAY_FORMAT_COUNT
typedef struct rtos_mic_array_struct rtos_mic_array_t

Typedef to the RTOS mic array driver instance struct.

void rtos_mic_array_start(rtos_mic_array_t *mic_array_ctx, size_t buffer_size, unsigned interrupt_core_id)

Starts an RTOS mic array driver instance. This must only be called by the tile that owns the driver instance. It must be called after starting the RTOS from an RTOS thread, and must be called before any of the core mic array driver functions are called with this instance.

rtos_mic_array_init() must be called on this mic array driver instance prior to calling this.

Parameters

  • mic_array_ctx – A pointer to the mic array driver instance to start.

  • buffer_size – The size in frames of the input buffer. Each frame is two samples (one for each microphone) plus one sample per reference channel. This must be at least MIC_ARRAY_CONFIG_SAMPLES_PER_FRAME. Samples are pulled out of this buffer by the application by calling rtos_mic_array_rx().

  • interrupt_core_id – The ID of the core on which to enable the mic array interrupt.

void rtos_mic_array_init(rtos_mic_array_t *mic_array_ctx, uint32_t io_core_mask, rtos_mic_array_format_t format)

Initializes an RTOS mic array driver instance. This must only be called by the tile that owns the driver instance. It should be called before starting the RTOS, and must be called before calling rtos_mic_array_start() or any of the core mic array driver functions with this instance.

Parameters

  • mic_array_ctx – A pointer to the mic array driver instance to initialize.

  • io_core_mask – A bitmask representing the cores on which the low level mic array I/O thread created by the driver is allowed to run. Bit 0 is core 0, bit 1 is core 1, etc.

  • format – Format of the output data

struct rtos_mic_array_struct
#include <rtos_mic_array.h>

Struct representing an RTOS mic array driver instance.

The members in this struct should not be accessed directly.

Core API

The following functions are the core microphone array driver functions that are used after it has been initialized and started.

inline size_t rtos_mic_array_rx(rtos_mic_array_t *ctx, int32_t **sample_buf, size_t frame_count, unsigned timeout)

Receives sample frames from the PDM mic array interface.

This function will block until new frames are available.

Parameters

  • ctx – A pointer to the mic array driver instance to use.

  • sample_buf – A buffer to copy the received sample frames into.

  • frame_count – The number of frames to receive from the buffer. This must be less than or equal to the size of the buffer specified to rtos_mic_array_start() if in RTOS_MIC_ARRAY_SAMPLE_CHANNEL mode. This must be equal to MIC_ARRAY_CONFIG_SAMPLES_PER_FRAME if in RTOS_MIC_ARRAY_CHANNEL_SAMPLE mode.

  • timeout – The amount of time to wait before the requested number of frames becomes available.

Returns

The number of frames actually received into sample_buf.

RPC Initialization API

The following functions may be used to share a microphone array driver instance with other xcore tiles. Tiles that the driver instance is shared with may call any of the core functions listed above.

void rtos_mic_array_rpc_client_init(rtos_mic_array_t *mic_array_ctx, rtos_driver_rpc_t *rpc_config, rtos_intertile_t *host_intertile_ctx)

Initializes an RTOS mic array driver instance on a client tile. This allows a tile that does not own the actual driver instance to use a driver instance on another tile. This will be called instead of rtos_mic_array_init(). The host tile that owns the actual instance must simultaneously call rtos_mic_array_rpc_host_init().

Parameters

  • mic_array_ctx – A pointer to the mic array driver instance to initialize.

  • rpc_config – A pointer to an RPC config struct. This must have the same scope as mic_array_ctx.

  • host_intertile_ctx – A pointer to the intertile driver instance to use for performing the communication between the client and host tiles. This must have the same scope as mic_array_ctx.

void rtos_mic_array_rpc_host_init(rtos_mic_array_t *mic_array_ctx, rtos_driver_rpc_t *rpc_config, rtos_intertile_t *client_intertile_ctx[], size_t remote_client_count)

Performs additional initialization on a mic array driver instance to allow client tiles to use the mic array driver instance. Each client tile that will use this instance must simultaneously call rtos_mic_array_rpc_client_init().

Parameters

  • mic_array_ctx – A pointer to the mic array driver instance to share with clients.

  • rpc_config – A pointer to an RPC config struct. This must have the same scope as mic_array_ctx.

  • client_intertile_ctx – An array of pointers to the intertile driver instances to use for performing the communication between the host tile and each client tile. This must have the same scope as mic_array_ctx.

  • remote_client_count – The number of client tiles to share this driver instance with.

void rtos_mic_array_rpc_config(rtos_mic_array_t *mic_array_ctx, unsigned intertile_port, unsigned host_task_priority)

Configures the RPC for a mic array driver instance. This must be called by both the host tile and all client tiles.

On the client tiles this must be called after calling rtos_mic_array_rpc_client_init(). After calling this, the client tile may immediately begin to call the core mic array functions on this driver instance. It does not need to wait for the host to call rtos_mic_array_start().

On the host tile this must be called both after calling rtos_mic_array_rpc_host_init() and before calling rtos_mic_array_start().

Parameters

  • mic_array_ctx – A pointer to the mic array driver instance to configure the RPC for.

  • intertile_port – The port number on the intertile channel to use for transferring the RPC requests and responses for this driver instance. This port must not be shared by any other functions. The port must be the same for the host and all its clients.

  • host_task_priority – The priority to use for the task on the host tile that handles RPC requests from the clients.