Intel® Quark™ SoC S1000 Firmware Programming Guide

ID 671959
Updated 1/9/2018
Version Latest
Public

author-image

By

Introduction

Overview

This guide provides the information required to become familiar with the Intel® Quark™ SoC S1000 ASIC firmware infrastructure components and principles of operation.

Audience and Purpose

This document is intended for audio firmware engineers integrating algorithms on Intel Quark SoC S1000 ASIC.

Terminology

Term Description
ADSP Audio DSP
Canonical format 32-bit MSB samples
DMA Direct Memory Access
DMIC Digital Microphone (PDM Mems)
DP Data Processing (EDF scheduled tasks)
DSP Digital Signal Processing
EDF Earliest Deadline First
Endpoint Device associated with gateway
FW Firmware
Gateway Unidirectional (input OR output) DMA gateway
Graph Set of pipelines
IPC Inter-Process Communication
Library Dynamically loadable set of the modules
LL Low Latency (1ms, 0.33ms-8ms considered)
Loadable module Dynamically loadable module
Management service A service in FW that manages the communication, configuration, and processing pipelines.
Module Processing component
Pipeline Linear chain of modules
Queue Both Sink and Source
RT Real Time (works as prefix)
Sink Interface for write operation
Source Interface for read operation
SW Software
SysTick System Tick, main interrupt asserted every LL

Reference Documents

Document Document Number / Revision
Intel® Quark™ S1000 ASIC Datasheet 570159

Intel® Intel® Quark™ SoC S1000 ASIC Architecture Overview

The Intel Quark SoC S1000 ASIC offers the ability to do far-field speech recognition in various smart devices. The Intel Quark SoC S1000 ASIC is designed for complex far-field signal processing algorithms that use high dimensional microphone arrays to do beamforming, cancel echoes, and reduce noise. A pair of DSPs, a neural network accelerator, internal memory, and a set of I/Os provide the necessary resources for speech processing solutions.


Figure 1. Intel Quark SoC S1000 ASIC High-Level Block Diagram

Note For full technical specifications, see the Intel Quark SoC S1000 ASIC Datasheet.

System Model


Figure 2. System Model

IPC Communication Over SPI-S

SPI is a protocol that is fully controlled by the master of the SPI bus. The Intel Quark SoC S1000 ASIC is a slave on the SPI bus. Therefore, it cannot initiate any bus transactions or perform flow control when the master performs a transaction.

The DSP in the Intel Quark SoC S1000 ASIC gets notifications of received data only when a receive transfer is configured a priori by the DSP. That is, to get notifications of received data when the threshold is exceeded, the DSP firmware must program a specific data size threshold up front.

The DSP can prepare a response and setup for transfer to the Host, however, the transfer can only be initiated by the Host that is the master on the SPI bus.

The DSP indicates SPI-S readiness by asserting IRQ high. The Host may only start the transfer after a rising edge is observed on the IRQ. The Host may not initiate a transfer when the IRQ is deasserted.

To perform an asynchronous notification, the DSP toggles IRQ line by deasserting it low for minimum 1µs. The notification message (payload) is transmitted as a response when the master performs an SPI transfer on receiving the notification.

IPC Protocol

The IPC protocol defaults to the short version of the message called IPC64 that is 64 bytes long. This mode assumes the use of SPI-S IP FIFO to store transmitted data.

On explicit request, IPC64 protocol may be switched to IPC4K protocol. This allows a 4KB IPC transfer in one or both directions.

Note The ROM does not support IPC4K message protocol.

IPC64 Protocol

The IPC64 protocol is default after initialization, and after any other transfer that does not select an alternative protocol.

IPC64 uses SPI-S RX FIFO and FIFO full interrupt to receive data.

IPC64 uses SPI-S TX FIFO to store IPC response data. Data is placed into FIFO before transaction state.

Note ROM implementation of IPC64 uses polling instead of interrupts.


Figure 3. IPC64 Protocol

Receive routines on both the host and DSP side must be ready to receive a “null” message containing all zero bits in the first 32 bits of the message. A null response sent from DSP may have the RSP bit set (optionally). Since behavior may vary between messages, the host should accept both forms of the message.

If the DSP side has nothing more to send, it must post a “null” message and rise IRQ. This action is required to enable the host to perform a transaction, if required.

To enter protocol idle state, the host side must ignore this interrupt. To differentiate between interrupts/states, the host shall not initiate a transaction after receiving a “null” status in response to a “null” request. If host attention is required, the DSP side must toggle IRQ once again.

Note Although starting a transaction while IRQ is 0 violates the defined protocol, the host is not required to actively track this signal. In this case, setting IRQ to 0 by DSP is not related to the fact that data for transmission is not ready. It is necessary only to create the rising edge of the IRQ signal.

IPC4K Protocol

IPC4K protocol is selected via IPC 4K mode IPC. IPC4K IPC mode selects the direction of transfer via flags.


Figure 4. IPC4K Protocol

IPC4K protocol may be selected for single or multiple transfers. There is no response to protocol switch IPC. Also, the IPC4K response format depends on the format selected for the next IPC. By default, this format is IPC64.

IPC4K uses a DMA buffer pre-allocated in HP-SRAM (LP-SRAM is size constrained). Since LP-GPDMA cannot wake the HP domain, the IPC routine must prohibit the use of LPS for the time that DMA is armed (HP domain power gating).

Receive routines on both host and DSP side must be ready to receive a “null” message containing all zero bits in the first 32 bits of the message. The response size must adhere to the currently selected format. A DSP request to switch to IPC4K must, in all cases, prepare an IPC4K response. It may be any of the following:

  • IPC4K null packet (assume that hardware supports this function)
  • IPC4K data packet that was scheduled for transmission to Host
  • IPC64 packet placed into IPC4K DMA buffer and padded with zeros

Note This assumption is made to avoid FIFO underrun from an IPC64 packet being sent in an IPC4K transaction. An underrun that cannot be differentiated from other underrun cases is not acceptable, as it would prevent diagnosis of actual issues.

Byte Packing/Byte Order Assumptions

IPC communication over SPI-S uses plain (no designated fields) bit transfer. The receive/transmit FIFOs are 32 bits wide. Bytes within a 32-bit word are transferred starting from MSB.


Figure 5. Byte Ordering - IPC64 Example

Certain SPI-M controllers may not be able to generate raw transactions, or transactions that are 64 bytes long. For such hosts, you can send IPC message in portions with the following assumptions:

  • Each transaction frame (assertion of SS signal) must be a minimum of 32-bits or a multiple of 32-bits
  • The number of bytes must match the expected transfer size
  • No padding between transactions, all data is valid on both transmit and receive

To allow operation both with and without toggling the slave select signal during frame transfer, the slave controller uses mode 3 as default.

Figure 6 contains examples of data formatting from a controller that supports command, address fields, and 32-bit data. To keep 32-bit alignment, the example shows an 8-bit command and a 24-bit address, followed by various 32-bit wide data values.


Figure 6. SPI Data Layout Example — Command, 24-bit Address, and 32-bit Data

Depending on the number of supported data values, the transaction may need to be repeated multiple times. If only a single 32-bit value is supported, the host must generate eight 64-bit SPI transactions to send IPC64.


Figure 7. SPI Data Layout Example — Command, 24-bit Address, and 16-bit Data

Figure 7 depicts a similar case, with 16-bit long data values. An even number of data transactions is required (two, at minimum) to keep 32-bit alignment.


Figure 8. SPI Data Layout Example — Command, 24-bit Address, and 8-bit Data

Figure 8 differs only in the payload size. Here, the data is only one byte long. To keep the transaction, four data cycles or a multiple of four is required.


Figure 9. SPI Data Layout Example — Command, 8-bit Address, and 16-bit Data

Figure 9 shows an example of generating IPC with a simple host controller that can send only 32-bit transactions. The example uses a command, 8-bit address, and 16-bit data to create a 32-bit transaction. A separate transaction generates each 32-bit message data.


Figure 10. SPI Data Layout Example — Command, 16-bit Address, and 8-bit Data

The example in Figure 10 differs in field partitioning. The example uses a command, 16-bit long address, and 8-bit long data.

Depending on the capabilities of the host controller, other combinations are possible. In all the provided examples, the controller must be able to capture data while sending command and address bytes.

IPC64/IPC4K Message Format

IPC communication over SPI must be adapted to media-specific requirements. The design goal is to minimize the change scope and allow transparent translation messages in lower level of firmware and software.

IPC specifics include:

  • Must use predefined (announced earlier message size)
  • Must advertise message size to remote side
  • Asynchronous notification method


Figure 11. IPC64 Generic Message Format

Figure 11 depicts a generic IPC64 message. The low-level routine that transmits the message must ensure that the size of the message submitted to SPI hardware is exactly 64 bytes. If required, the low-level routine shall add padding (filled with zeros) to achieve the required size.

R4 and W4 bit fields are used to reduce transmission overhead. Both fields reuse B/E fields that are not used in a given version of the protocol. The R4 field requests the DMA buffer setup for SPI Read. For a master transaction initiated from the host, this means that the subsequent transaction is expected to read a 4KB message. The same field in the response message indicates to the SPI master a request for a 4KB transaction (for example, to return a long message response). Similarly, the W4 field defines the buffer transaction setup in the opposite direction.


Figure 12. IPC4K Generic Message Format

The format of a 4KB message is shown in Figure 12. The only difference in this situation is the amount of allowed payload or required padding.

The protocol allows independent setting of the R4 and W4 fields. However, if one bit is set, the host performs a 4KB R/W transaction. This means that an unselected buffer must either be disabled (null transfer), or adhere to the selected format.

A similar situation occurs when both the R4 and W4 bits are set. In this situation, a 4KB transfer is executed in both directions.


Figure 13. IPC Mode Select IPC

The explicit message IPC Mode Select (Figure 13) is used when the host or device must switch to 4K mode without data for transmitting/receiving. IPC Mode Select is essentially a “null” IPC64 message that allows mode selection for the next transaction. The message can be used in both directions. Specifically, the SPI slave may choose to return this message to indicate that the returning data requires a larger buffer.

IPC Mode Select IPC with both R4 and W4 messages is used as a “null” message. It is useful for the host to pull a pending message from SPI-S hardware.

Note In general, the master side shall request IPC4K transfers for transactions expected to return more than 60 bytes of data.

Note Intel recommends that you fit asynchronous notification data in IPC64 format. Otherwise, notification handling may require three messages.

Asynchronous Notification Support

Asynchronous notification requires the generation of a minimum of two interrupt events using the IRQ line.

During the first interrupt, the host transfers previously a configured (typically null) response according to selected protocol. In a typical case (idle/waiting for event scenario), the hardware IPC selects IPC64 protocol version.

This approach is required because, once firmware determines the need for an asynchronous response, the “current” (typically empty) response is already submitted to hardware. Since hardware does not allow the safe substitution of a response, the firmware must force a flush of the current response.

Since the host is expected to be idle at a time when asynchronous notification is received, it issues IPC Mode Select IPC.

Note The host may choose to request IPC64 mode (the default and recommended mode), or IPC4K mode (if majority of notifications are expected to be in IPC4K format).

The firmware parses the received data to determine the next transaction buffer size. In a typical case, the firmware submits an IPC64 response. However, as the host may choose IPC4K format, the firmware must also handle the case of sending an IPC64 response in the 4K buffer.

Yet another case is created when the upper firmware layers request the IPC4K notification format (message size >60 bytes), while the host selects IPC64 mode. To handle this situation, the firmware responds with IPC Mode Select, with the R4 field set, to force the host to select 4K mode.

Independently of the previous case, the firmware attempts to put response data and rise interrupt over the IRQ line, as long as asynchronous notification data remains unsubmitted.

Intel recommends that the host suppresses sending messages while previous operations are incomplete. Although such concurrency cannot be eliminated, both sides of the protocol must handle messages asynchronously. Specifically, the host must not block forward receive progress while waiting for a request response, because the asynchronous notification inserted in front of the expected response must be comprehended.

Host State Machine

Figure 14 shows the host state machine. After deasserting, a reset triggers ROM to put a status message in the RX FIFO. To read the message, the host must either send some message. Typically, this message is a null message that allows determination of the SoC version (status). For clarity, the figure does not include opportunistic transfers that may happen on both sides, nor does it include IPC format selection.


Figure 14. Host State Machine

Flows

Boot Options

SPI-S Mode Operation

Boot from SPI-S is used in configurations where the firmware for the Intel Quark SoC S1000 ASIC is downloaded from a host. This configuration does not usually have a flash memory attached to the SPI-M of the Intel Quark SoC S1000 ASIC.

SPI-S Mode Selection

SPI-S mode is selected by asserting high (statically or dynamically) strap option connected to SPI_SLAVE_MST_N_BOOT. The Intel Quark SoC S1000 ASIC samples the strap during de-assertion of the HOST_RST_N input. If the sampled strap value is 1, the ROM code attempts to initialize the SPI-S controller and start polling for messages from the host.


Figure 15. Interactions Between Host and Intel Quark SoC S1000 ASIC in SPI-S Mode

Figure 15 shows the SPI-S mode support. After early initialization and boot mode detection, the firmware enters a wait loop for the initial IPC64 command packet. Once the RX FIFO ready state is determined, the firmware starts reading the necessary DWORDs from the FIFO. By reading the first one or two DWORDs, the ROM implementation can determine and properly dispatch the command.

IPC Protocol

The defined messages use the Count field to indicate the number of message DWORDS present after the header. The IPC message send function provides padding between the current message size, (Count+2)*4, and the currently selected IPC mode. The IPC processing function consumes the padding DWORDs from the SPI-S FIFO. In the current definition, the ROM supports IPC64 messages only.

ROM Ready IPC

As part of early boot process ROM, puts ROM Ready IPC in SPI-S TX FIFO. The message indicates that the ROM is ready to receive IPC commands, and provides information about the ASIC version.


Figure 16. ROM Ready IPC

Firmware Load Messages

Regardless of framing, the payload is expected to contain only data up to the number of messages defined in the Image Size field. The address field is expected to reside in HP-SRAM. The memory address and image size must be aligned to a minimum of 64B.

The image offset field is not used in SPI-S mode. Set it to 0.


Figure 17. Load Firmware IPC

By default, the message carries the valid Memory Address, Image Size, and SHA-256 checksum of the image.

All N* fields are reserved and shall be set to 0.

The Clock Select field allows the host to select an alternative SPI-S clock source. The currently defined encodings are as follows:

  • 0 – use default clock
  • 1 – use high-performance clock

All other values for this field are reserved.


Figure 18. Load Firmware Response IPC

The Load Firmware response IPC is placed in the TX FIFO of the controller. It contains a copy of the original IPC with the RSP bit set, and an updated SHA-256 value.

The firmware entry point is the same as the load memory address. This allows maximum flexibility of internal image implementation.

SPI-M Mode Operation

Boot from SPI-M connected flash is used in configurations where the Intel Quark SoC S1000 ASIC is operating independently or with the host connected via USB/SPI-S. In these configurations, a valid firmware image must be stored in the connected flash from which the Intel Quark SoC S1000 ASIC can boot.

SPI Part Assumptions

To boot successfully, the SPI slave device (presumably a non-volatile memory type) must meet the following criteria:

  • Connection SPI-M interface of Intel Quark SoC S1000 ASIC as slave #0
  • VIO 1.8V, SPI clock min 19.2MHz
  • Support mode 0 (ROM uses mode 0)
  • Support read command 3 with 24-bit address and w/o need for dummy cycles
  • Support for linear read burst (no size constrains)
Boot Mode Selection

Select SPI-M mode by platform driving (pulling down) the SPI_SLAVE_MST_N_BOOT signal low before HOST_RST_N is deasserted.

Boot in SPI-M Mode

Figure 19 depicts the interactions between firmware (in ROM) and hardware.


Figure 19. Boot From Locally Attached SPI Device

SPI Memory Layout

The initial portion of flash is organized as a linear block of DWORD values. Starting from address 0, DWORD values can be read one by one and processed sequentially. This approach simplifies the ROM interpretation routine that must be assembly coded (SRAM is not available during initial parsing).


Figure 20. SPI Memory/Flash Layout

Figure 20 depicts the SPI memory (Flash) layout, as interpreted by ROM.

The SPI memory starts from the magic DWORD (0x30504353, the value used if flash is attached and programmed). This magic DWORD mechanism differentiates between a valid image and an invalid image, and takes fallback action if the image is invalid.

Next there is a single DWORD, not parsed by ROM. This DWORD is intended to be the partition pointer/flash file system pointer. In the example in Figure 21, the pointer references the partition table at 64 KB offset. This type of organization allows you to keep some reserved space for the hardware initialization or loader portion of the flash, and to update it without repartitioning the entire device. The pointer is used by the secondary loader to quickly locate the table without parsing the initial portion of the flash again.

After the two initial DWORDs, the IPC script starts. The entire script, including the initial DWORDs and Load command, fits in 64KB.

The minimum configuration is just 64B: 8 bytes of initial words, and a 56 byte load command.

The firmware image or secondary loader image is located entirely in the first 16 MB of SPI space.


Figure 21. Memory Partitioning Example

IPC Protocol

Firmware Load Messages

Regardless of framing, the payload is expected to contain only data up to the number of messages defined in the Count field. By default, the Address field is expected to reside in HP-SRAM. The Memory Address and Image Size must be aligned to a minimum of 64B.


Figure 22. Load Firmware IPC

By default, the message carries a valid memory address, DWORD aligned image size, and SHA-256 checksum of the image.

All N* fields are reserved and shall be set to 0.

The Clock Select field selects an SPI-M clock source and divider to be used during firmware load.

The currently defined encodings are as follows:

  • 0 – Use default clock

All other values of this field are reserved.

If there is SHA-256 hash check failure, the ROM enters a fatal error state.

Creating Streams

To create a stream, the management service must build the list of module instances that will be part of the stream processing logic. Each module instance affinity must be assigned to a core by the management service. If any instance that is on the list requires a loadable module to be available, the management service must check if the module is already loaded. Otherwise, it must execute the module loading flow before sending the module instance list to the firmware. The firmware expects that all resources, including processing code, memory, and core bandwidth, are verified by the management service before the module instance list arrives.

A stream may consist of one or more pipelines. The firmware supports up to four pipelines connected via Mixers in a single render stream. Each pipeline is a sequence of module instances. Each module instance may execute in either Low Latency or Data Processing domain. Each subsequence of consecutive Data Processing module instances must be assigned to the same Core.

For example, a pipeline that consists of the following module instances LL0-LL1-DP2-DP3-LL4-DP5-DP6-LL7 must be distributed among the cores so that the subsequence DP2…DP3 has the same affinity (for example, Core0) and DP5…DP6 also has the same affinity (for example, Core1).

Note Modules must be instantiated in their data processing order within the pipeline. That is, if mod1 produces data for mod2, then IPC Init Instance (mod1) must be called before IPC Init Instance (mod2).

Retrieving FW/HW Configuration and Topology Information

The management service may query firmware and hardware configuration, and topology information, by requesting the values of the following parameters:

  • Base FW parameters:
    • Firmware Config
    • Hardware Config
    • Modules Info
    • Pipeline List Info
    • Pipeline Properties
    • Module Instances Info
    • Gateways Info
    • Memory State Info
    • Power State Info
  • Module instance parameters:
    • Module Instance Properties

The management service may also set some of the firmware configuration parameters.

Retrieving Performance Data

Performance data collecting is disabled by default in the firmware.

To retrieve capture performance data, the management service must execute following steps:

  1. Enable performance measurements by setting Base FW’s PERF_MEASUREMENTS_STATE parameter to either Stopped or Started (in the latter, data collecting starts immediately).
  2. Start performance measurements by changing the state to Started (if not done in the previous step).
  3. Execute the scenario to be measured.
  4. Pause performance measurements by changing state to Paused. Changing the state to Stopped erases all collected data immediately.
  5. Retrieve performance measurements data, including global items provided by the Base FW’s GLOBAL_PERF_DATA parameter, and the pipeline and module instance properties.
  6. Now, performance measurements may be either resumed (Paused → Started), restarted (Paused →  Stopped →  Started) or disabled completely (Paused Disabled).

To see all possible transitions between states of performance data collection mechanism, refer to Introduction.

Fatal Error Reporting

The DSP ROM implements a fatal error handling mechanism. All unexpected errors, such as L1 or L2 double-bit errors, result in firmware halt and set the IRQ line to 1. More detailed reasons can be determined only using JTAG.

If the firmware is not responsive, the host-based software must reset the Intel Quark SoC S1000 ASIC by asserting the HOST_RST_N pin low.

IPC Interface

The IPC interface enables message exchange between firmware and the software running on host.

IPC communication may be initiated by either side, as follows:

  • The management service sends an IPC request – either a Global message directed to the firmware infrastructure (Base FW), or a Module message directed to a module instance running in firmware – and the firmware replies with an IPC response.
  • Firmware sends an IPC Notification (one way, not replied to by the host) that is a Global message of NOTIFICATION type.

An IPC message consists of a header exchanged through SPI interface, and an optional payload.

It applies to the following IPC messages:

  • Load Module
  • Unload Module
  • Init Module
  • Large Config Set
  • Large Config Get


Figure 23. IPC Message Header

There are three types of IPC message headers:

  • Global Message – a request from the management service directed to the firmware infrastructure
  • Module Message – a request from the management service directed to one of firmware module instances
  • Message Reply – a reply to the management service sent by the firmware in response to either request

IPC Base Structures

MsgCtrlReg Structure

Note The Msg structure and all derived structures preserve the upper level bit definition. The Msg structure breaks down MsgCtrlReg::payload_primary and MsgCtrlReg::payload_extension, preserving other fields of MsgCtrlReg. Derived messages break down Msg::Bits::rsvd0 and Msg::Bits::rsvd1, preserving other fields of Msg::Bits.

struct MsgCtrlReg
{
    union
    {
        struct
        {
            uint32_t primary;
            uint32_t extension;
        } dw;

        struct
        {
            // primary register fields

            uint32_t payload_primary   : 31;
            uint32_t _busy             : 1;  

            // extension register fields

            uint32_t payload_extension : 30;
            uint32_t _done             : 1;  
            uint32_t _error            : 1
        } bits;

    } regs;
};
Msg Structure

This is a base structure for all IPC message headers. It defines common bits that are used in both communication directions.

Syntax
struct Msg
{
    enum MsgTarget
    {
        FW_GEN_MSG = 0, // Global message
        MODULE_MSG = 1  // Module message
    };

    enum MsgDir
    {
        MSG_REQUEST = 0,       // Request
        MSG_NOTIFICATION = 0,  // Notification
        MSG_REPLY = 1          // Reply
    };

    struct Bits
    {
        // primary register

        uint32_t rsvd0      : 29;
        uint32_t rsp        : 1;
        uint32_t msg_tgt    : 1;
        uint32_t _busy      : 1;

        // extension register

        uint32_t rsvd1      : 30;
        uint32_t _done      : 1;
        uint32_t _error     : 1;
    };
};
Members
rsp

Indicates that an upstream message is a response to some request (and not a notification). This bit lets the management service dispatch the message appropriately avoiding a race condition in the following scenario:

  • Host sends a request down to FW.
  • FW (at the same time sends a notification).
  • Host receives upstream message and is able to qualify it as an unsolicited notification rather than a response to the request just sent to FW.
  • FW receives a request, processes it and sends a response.

One of MsgDir values.

msg_tgt

Used by FW to dispatch Global (infrastructure directed) messages and messages directed to module instances. One of MsgTarget values.

Global Request

Global::Bits Structure

This structure is a base class for all messages handled by the Base FW.

Syntax
struct Bits
{
    uint32_t rsvd0      : 24;
    uint32_t type       : 5;
    uint32_t rsp        : 1;
    uint32_t msg_tgt    : 1;
    uint32_t _busy      : 1;

    uint32_t rsvd1      : 30;
    uint32_t _done      : 1;
    uint32_t _error     : 1;
};
Members

msg_tgt

Set to Msg::FW_GEN_MSG

rsp

Set to Msg::MSG_REQUEST

type

Indicates type of the Global message (one of Global::Type).

ModuleMsg Request

This structure is a base class for all messages directed to the modules and handled inside the modules. There are some exceptions of module messages that are handled by the Base FW, but this is transparent for host IPC.

Every Module Message specifies the ID of the module and instance to which the message is dispatched.

ModuleMsg::Bits Structure
Syntax
struct Bits
{
    uint32_t module_id      : 16;
    uint32_t instance_id    : 8;
    uint32_t type           : 5;
    uint32_t rsp            : 1;
    uint32_t msg_tgt        : 1;
    uint32_t _busy          : 1;

    uint32_t rsvd1          : 30;
    uint32_t _done          : 1;
    uint32_t _error         : 1;
};
Members
msg_tgt

Set to Msg::MODULE_MSG

rsp

Set to Msg::MSG_REQUEST

type

Indicates type of the Module message (one of ModuleMsg::Type).

instance_id

ID of the target module instance.

module_id

ID of the target module.

MsgReply Response

This structure is a base class for replies sent back to the originator once handling of a request is completed.

Due to the new asymmetric nature of request and response, the status field is now 24-bits wide. Therefore, the first DWORD of the message control register is filled. If message-specific data must be sent back, it may be packed into either the second DWORD or into the Data payload. If there is no message type-specific data to be sent back, the message handler may send a reply of MsgReply type directly. Otherwise, a defined inherited structure is used to construct a reply.

Note Due to the same width and position of the type field in both Global and ModuleMsg requests, you do not need to define separate reply structures. MsgReply may be used for messages of both types.

MsgReply Structure
Syntax
struct MsgReply : Msg
{
    struct Bits
    {
        uint32_t status     : IXC_STATUS_BITS;
        uint32_t type       : 5;
        uint32_t rsp        : 1;
        uint32_t msg_tgt    : 1;
        uint32_t _busy      : 1;

        uint32_t rsvd1      : 30;
        uint32_t _done      : 1;
        uint32_t _error     : 1;
    };
};
Members
msg_tgt

Same as the request target. Either Msg::FW_GEN_MSG or Msg::MODULE_MSG.

rsp

Set to Msg::MSG_REPLY.

type

One of message types.

status

One of IxcStatus values.

Remarks

The MsgReply::status is set by FW to one of IxcStatus values. There is one flat space of status values used by all FW components that reports the status of the operation in the IPC reply.

See the adsp_ixc_status.h header file for the most up-to-date complete documentation. The following sections outline some message-specific status values.

General IPC Error Codes

Table 3. IPC General Error Codes

Error Code Value Description
ADSP_IPC_SUCCCESS 0 The operation was successful.
ADSP_IPC_ERROR_INVALID_PARAM 1 Invalid parameter specified.
ADSP_IPC_UNKNOWN_MESSAGE_TYPE 2 Unknown message ID specified.
ADSP_IPC_OUT_OF_MEMORY 3 No memory to complete the request.
ADSP_IPC_BUSY 4 System or resource is busy.
ADSP_IPC_PENDING 5 The request was scheduled for asynchronous processing.
ADSP_IPC_FAILURE 6 Unknown error while processing the request.
ADSP_IPC_INVALID_REQUEST 7 Unsupported operation requested.
<reserved> 8 N/A to SKU2-LP (was ADSP_STAGE_UNINTIALIZED).
ADSP_IPC_INVALID_RESOURCE_ID 9 Specified resource not found.
<reserved> 10 N/A to SKU2-LP (was ADSP_SOURCE_NOT_STARTED).
ADSP_IPC_OUT_OF_MIPS 11 No MCPS to complete the request.
ADSP_INVALID_RESOURCE_STATE 12 Required resource is in invalid state.
ADSP_IPC_UNAVAILABLE 15 Requested service or data is unavailable on the target platform.

General IPC Messages

Static and dynamic runtime FW infrastructure properties are retrieved using module configuration messages addressed to module ID 0 (Base FW). See Section 5.6.4, “Base FW”.

Performance Measurements Command

The management service sends this message to execute the performance measurements command.

Request Message Control Header
struct Bits
{
    uint32_t command        : 8;
    uint32_t rsvd0          : 16;
    uint32_t type           : 5;
    uint32_t rsp            : 1;
    uint32_t msg_tgt        : 1;
    uint32_t _reserved_0    : 1;  // HW ctrl reserved bits

    uint32_t rsvd1          : 30;
    uint32_t _reserved_2    : 2;  // HW ctrl reserved bits
};

Table 4. Performance Measurements Command – Request Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_REQUEST
type Global::PERF_MEASUREMENTS_CMD
command

Command to be executed by FW, one of:

  • 0 - Start
  • 1 - Pause
  • 2 - Reset
  • 3 - Stop
Input Data

There is no input data.

Reply Message Control Header
struct Bits
{
    uint32_t status     : IXC_STATUS_BITS;
    uint32_t type       : 5;
    uint32_t rsp        : 1;
    uint32_t msg_tgt    : 1;
    uint32_t _busy      : 1;

    uint32_t rsvd1      : 30;
    uint32_t _done      : 1;
    uint32_t _error     : 1;
};

Table 5. Performance Measurements Command – Reply Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_REPLY
type Global::PERF_MEASUREMENTS_CMD
status

ADSP_IPC_SUCCESS
Operation successful.

ADSP_IPC_INVALID_RESOURCE_STATE
Performance measurements are disabled.

ADSP_IPC_INVALID_REQUEST
Invalid parameter specified.

Output Data

There is no output data.

Library & Module Management IPC Messages

Load Library

The management service sends this message to initiate loading of a library into the ADSP memory.

Request Message Control Header
struct Bits
{
    uint32_t dma_id      : 5;
    uint32_t rsvd0       : 11;
    uint32_t lib_id      : 4;
    uint32_t rsvd1       : 4;
    uint32_t type        : 5;
    uint32_t rsp         : 1;
    uint32_t msg_tgt     : 1;
    uint32_t _reserved_0 : 1;  // HW ctrl reserved bits

    uint32_t rsvd1      : 30;
    uint32_t _reserved_2 : 2;  // HW ctrl reserved bits
};

Table 6. Load Library – Request Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_REQUEST
type Global::LOAD_LIBRARY
lib_id Identifier of the library assigned by the management service at runtime. Numbering should be simple and starts from 1 for the first library, incremented by 1 for each subsequently loaded library.
dma_id Not used in S1000 Firmware.
Input Data

None.

Reply Message Control Header
struct Bits
{
    uint32_t status     : IXC_STATUS_BITS;
    uint32_t type       : 5;
    uint32_t rsp        : 1;
    uint32_t msg_tgt    : 1;
    uint32_t _busy      : 1;

    uint32_t rsvd1      : 30;
    uint32_t _done      : 1;
    uint32_t _error     : 1;
};

Table 7. Load Multiple Modules – Reply Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_REPLY
type Global::LOAD_LIBRARY
status

ADSP_IPC_SUCCESS
Operation successful.

ADSP_IPC_ERROR_INVALID_PARAM
Invalid argument specified in the header.

ADSP_IPC_OUT_OF_MEMORY
No memory to add manifest and all declared module descriptors.

ADSP_IPC_INVALID_TARGET_ADDRESS
Target memory address space declared by the library is invalid (out of valid range).

ADSP_IPC_UNTRUSTED_PUBLIC_KEY
Public key specified in the library’s manifest is not trusted.

ADSP_IPC_INVALID_SIGNATURE
Verification of the signature specified in the library’s manifest failed.

Output Data

None.

Init Instance

The management service sends this message to create a module instance. The new instance is a child element of the pipeline, and is identified by the ppl_id specified by the management service.

The module_id should be set to an index of the module entry in the FM Image Manifest.

The instance_id should be one of the 0..ModuleEntry.max_instance_count defined in the FM Image Manifest.

Initial configuration of the module instance is provided by the management service in the param_data array. The size of the array is specified in param_block_size field of the message header.

For details on module-specific initial configuration parameters, see Section 5.6, “Module Configuration”.

Request Message Control Header
struct Bits
{
    uint32_t module_id          : 16;
    uint32_t instance_id        : 8;
    uint32_t type               : 5;
    uint32_t rsp                : 1;
    uint32_t msg_tgt            : 1;
    uint32_t _busy              : 1;

    uint32_t param_block_size   : 16;
    uint32_t ppl_instance_id    : 8;
    uint32_t core_id            : 4;
    uint32_t proc_domain        : 1;
    uint32_t rsvd1              : 1;
    uint32_t _done              : 1;
    uint32_t _error             : 1;
};

Table 8. Init Instance – Request Parameters

Field Value
msg_tgt Msg::MODULE_MSG
Rsp Msg::MSG_REQUEST
type ModuleMsg::INIT_INSTANCE
instance_id ID of module instance assigned by the management service (if it exists)
module_id ID of module (0-based index of the module entry in the FM Image Manifest)
proc_domain Module’s target processing domain. Either Low Latency (0) or Data Processing (1).
core_id ID of core that instance will run on
ppl_instance_id ID of module instance’s parent pipeline
param_block_size Size of Data::param_data[] (in dwords)
Input Data
struct Data
{
    uint32_t param_data[0];
};

The actual size of param_data is specified by the param_block_size field of the control header.

Reply Message Control Header

Standard MsgReply is sent back.

Table 9. Init Instance – Reply Parameters

Field Value
msg_tgt Msg::MODULE_MSG
rsp Msg::MSG_REPLY
type ModuleMsg::INIT_INSTANCE
status

ADSP_IPC_SUCCESS
Operation successful.

ADSP_IPC_MOD_INVALID_ID
Invalid module ID specified.

ADSP_IPC_MOD_INST_INVALID_ID
Invalid module instance ID specified.

ADSP_IPC_CORE_INVALID_ID
Invalid core ID specified.

ADSP_IPC_OUT_OF_MEMORY
No memory to allocate module instance.

ADSP_IPC_MOD_INST_EXISTS
Module instance exists.

ADSP_IPC_MOD_NOT_INITIALIZED
Module instance initialization failed.

Output Data

No additional output data.

Module Config Set

Using the Module Config Set command, the management service (if it exists) may send a parameter that fits into the header, packed with the parameter ID. Larger parameters require fragmentation and a series of Large Config Set commands.

For details on module specific runtime parameters, see “Module Configuration”.

Request Message Control Header
struct Bits
{
    uint32_t module_id      : 16;
    uint32_t instance_id    : 8;
    uint32_t type           : 5;
    uint32_t rsp            : 1;
    uint32_t msg_tgt        : 1;
    uint32_t _busy          : 1;

    uint32_t param_id_data  : 30;
    uint32_t _done          : 1;
    uint32_t _error         : 1;
};

Table 10. Module Config Set – Request Parameters

Field Value
msg_tgt Msg::MODULE_MSG
rsp Msg::MSG_REQUEST
type ModuleMsg::MODULE_CONFIG_SET
instance_id ID of module instance assigned by the management service (if it exists)
module_id ID of module (0-based index of the module entry in the FM Image Manifest)
param_id_data

Specifies both ID of the parameter, defined by the module and value of the parameter.

It is up to the module how to distribute bits to ID and value of the parameter.

If there are more bits required than available to value, then Input Data may be used to pass the value.
Input Data

None

Reply Message Control Header

Standard MsgReply is sent back.

Table 11. Module Config Set – Reply Parameters

Field Value
msg_tgt Msg::MODULE_MSG
rsp Msg::MSG_REPLY
type ModuleMsg::MODULE_CONFIG_SET
status

ADSP_IPC_SUCCESS
Operation successful.

ADSP_IPC_INVALID_RESOURCE_ID
Invalid module ID or module instance ID specified.

ADSP_IPC_INVALID_CONFIG_PARAM_ID
Invalid parameter ID specified.

ADSP_IPC_INVALID_CONFIG_DATA_LEN
Invalid parameter length specified.

<module specific error codes>
Output Data

There is no output data.

Module Config Get

Symmetric to the Module Config Set.

Reply Message Control Header
struct Bits
{
    uint32_t status         : IXC_STATUS_BITS;
    uint32_t type           : 5;
    uint32_t rsp            : 1;
    uint32_t msg_tgt        : 1;
    uint32_t _busy          : 1;

    uint32_t param_id_data  : 30;
    uint32_t _done          : 1;
    uint32_t _error         : 1;
};

Table 12. Module Config Get – Reply Parameters

Field Value
msg_tgt Msg::MODULE_MSG
rsp Msg::MSG_REPLY
type ModuleMsg::MODULE_CONFIG_GET
param_id_data Value of this field may be changed by the module if parameter value fits into the available bits, or stay intact if the value is copied to the Output Data.
status

ADSP_IPC_SUCCESS
Operation successful.

ADSP_IPC_INVALID_RESOURCE_ID
Invalid module ID or module instance ID specified.

ADSP_IPC_INVALID_CONFIG_PARAM_ID
Invalid parameter ID specified.
<module specific error codes>

Output Data

None.

Large Config Set

Using the Large Config Set command, the management service may send configuration data that cannot fit into Module Config Set.

Note All documentation in this section applies to the symmetric Large Config Get as well.

The management service may send internally defined configuration parameters declared by Intel modules. The format of the message payload is module-specific and agreed between the management service and the module.

However the Large Config Set can be also used to tunnel parameters coming through Module Configuration API. Then, the large_param_id is set to APPLICATION_PARAM (formerly known as VENDOR_CONFIG_PARAM), with the valuE 0xFF. The message payload is populated with one or more configuration parameters submitted to the management service by a client software component. The firmware reads the parameters one by one and passes them to the addressed module instance. The structure of a single external parameter transported inside message data appears as follows:

Syntax
struct ModConfParam
{
    uint32_t param_id;
    uint32_t param_size;
    uint32_t param_data[ceil(param_size/sizeof(uint32_t))];
};
Members

param_id
ID of the parameter, transparent to FW, passed to the module’s configuration routine.

param_size
Size of the param_data, specified in bytes.

param_data
Parameter data.

Note Multiple tunneled parameters cannot span across multiple messages. They must fit into a single request/response pair. Sending a series of Large Config Set is allowed for a single parameter payload (still tunneled using APPLICATION_PARAM).

Request Message Control Header
struct Bits
{
    uint32_t module_id      : 16;
    uint32_t instance_id    : 8;
    uint32_t type           : 5;
    uint32_t rsp            : 1;
    uint32_t msg_tgt        : 1;
    uint32_t _busy          : 1;

    uint32_t data_off_size  : 20;
    uint32_t large_param_id : 8;
    uint32_t final_block    : 1;
    uint32_t init_block     : 1;
    uint32_t _done          : 1;
    uint32_t _error         : 1;
};

Table 13. Large Config Set – Request Parameters

Field Value
msg_tgt Msg::MODULE_MSG
rsp Msg::MSG_REQUEST
type ModuleMsg::LARGE_CONFIG_SET
instance_id ID of module instance assigned by the management service (if it exists)
module_id ID of module (0-based index of the module entry in the FM Image Manifest)
init_block Indicates whether this is the first block
final_block Indicates whether this is the final block
large_param_id

ID of the parameter.
0xFF – APPLICATION_PARAM.

data_off_size

In case of the first data fragment (init_block = 1) this field specifies total size of the parameter (in bytes).

In case of subsequent data fragments it specifies offset (in bytes) of the fragment within the fragment blob.
Input Data

If large_param_id is set to APPLICATION_PARAM, the message data contains an array of module configuration parameters.

struct Data
{
    ModConfParam param[];
};

Otherwise, the message data contains a chunk of parameter’s value.

struct Data
{
    uint32_t param_data[];
};
Reply Message Control Header

Standard MsgReply is sent back.

Table 14. Large Config Set – Reply Parameters

Field Value
msg_tgt Msg::MODULE_MSG
rsp Msg::MSG_REPLY
type ModuleMsg::LARGE_CONFIG_SET
status

ADSP_IPC_SUCCESS
Operation successful.

ADSP_IPC_INVALID_RESOURCE_ID
Invalid module ID or module instance ID specified.

ADSP_IPC_INVALID_CONFIG_PARAM_ID
Invalid parameter ID specified.

ADSP_IPC_INVALID_CONFIG_DATA_LEN
Invalid parameter length specified.

ADSP_IPC_LARGE_CONFIG_SET_ERROR
Vendor-specific parameter rejected by module instance.
<module specific error codes>

Output Data

If the returned status is set to ADSP_IPC_CONFIG_SET_ERROR, the message data specifies the index of the failed parameter and the vendor-specific error code returned by the module instance.

struct Data
{
    uint32_t failed_param_index;
    uint32_t vendor_error_code;
};

Large Config Get

This message is set by the management service (if it exists) to retrieve one or more configuration parameters from specified module instance.

If the Large Config Get is used to tunnel parameters requested through Module Configuration API, the message payload is expected to contain an array of parameter descriptors in the following format:

Syntax
struct ModConfParamGet
{
    uint32_t param_id;
    uint32_t param_max_size; // in bytes
};
Members

param_id
ID of the parameter to retrieve, transparent to FW, passed to the module’s configuration API.

param_max_size
Maximum size of the parameter data to be retrieved (in bytes).

Note The previous reference to tunneling multiple vendor parameters within a single request/response pair in the Large Config Set documentation applies symmetrically to the Large Config Get. The total size of param_max_size, specified in the request, must not exceed IPC_UPLINK_MAILBOX_SIZE (as retrieved by the Get ADSP Properties IPC message).

Request Message Control Header
struct Bits
{
    uint32_t module_id      : 16;
    uint32_t instance_id    : 8;
    uint32_t type           : 5;
    uint32_t rsp            : 1;
    uint32_t msg_tgt        : 1;
    uint32_t _busy          : 1;

    uint32_t data_off_size  : 20;
    uint32_t large_param_id : 8;
    uint32_t final_block    : 1;
    uint32_t init_block     : 1;
    uint32_t _done          : 1;
    uint32_t _error         : 1;
};

Table 15. Large Config Get – Request Parameters

Field Value
msg_tgt Msg::MODULE_MSG
rsp Msg::MSG_REQUEST
type ModuleMsg::LARGE_CONFIG_GET
instance_id ID of module instance assigned by the management service (if it exists)
module_id ID of module (0-based index of the module entry in the FM Image Manifest)
init_block Indicates whether this is the first block
final_block Indicates whether this is the final block
large_param_id

ID of the parameter.
0xFF – APPLICATION_PARAM.

data_off_size

In case of the first data fragment (init_block = 1) this field specifies total size (in bytes) of message data containing array of parameter specifiers.

In case of subsequent data fragments it specifies offset (in bytes) of the fragment within the fragment blob.
Input Data

If large_param_id is set to APPLICATION_PARAM, the message data of the first command in the series contains an array of parameter specifiers:

struct Data
{
    ModConfParamGet param_get[];
};

Otherwise there is no input data.

Reply Message Control Header
struct Bits
{
    uint32_t status         : IXC_STATUS_BITS;
    uint32_t type           : 5;
    uint32_t rsp            : 1;
    uint32_t msg_tgt        : 1;
    uint32_t _busy          : 1;

    uint32_t data_off_size  : 20;
    uint32_t large_param_id : 8;
    uint32_t final_block    : 1;
    uint32_t init_block     : 1;
    uint32_t _done          : 1;
    uint32_t _error         : 1;
};

Table 16. Large Config Get – Reply Parameters

Field Value
msg_tgt Msg::MODULE_MSG
rsp Msg::MSG_REPLY
type ModuleMsg::LARGE_CONFIG_GET
status

ADSP_IPC_SUCCESS
Operation successful.

ADSP_IPC_INVALID_RESOURCE_ID
Invalid module ID or module instance ID specified.

ADSP_IPC_INVALID_CONFIG_PARAM_ID
Invalid parameter ID specified.

ADSP_IPC_LARGE_CONFIG_GET_ERROR
Vendor-specific parameter failed to be retrieved from the module instance.
<module specific error codes>

Output Data

If large_param_id is set to APPLICATION_PARAM, the message data contains an array of module configuration parameters.

struct Data
{
    ModConfParam param[];
};

If the firmware failed to retrieve one of vendor-specific parameters, the status is set to ADSP_IPC_CONFIG_GET_ERROR, and the message data contains the following information:

struct Data
{
    uint32_t failed_param_index;
    uint32_t vendor_error_code;
};

If large_param_id is set to one of the Intel internal parameter IDs, the parameter data is copied directly to the response data buffer.

struct Data
{
    uint32_t param_data[];
};

Bind/Unbind

The management service sends the Bind IPC message to connect two module instances and create a data processing path between them.

The Unbind IPC message is sent to destroy a connection between two module instances (belonging to different pipelines) that were created previously with a Bind call.

Note When both module instances are parts of the same pipeline, firmware ignores Unbind IPC because firmware does not support changing the internal topology of a pipeline during runtime. The only way to change pipeline topology is to delete the whole pipeline and create it in modified form.

Request Message Control Header
struct Bits
{
    uint32_t module_id          : 16;
    uint32_t instance_id        : 8;
    uint32_t type               : 5;
    uint32_t rsp                : 1;
    uint32_t msg_tgt            : 1;
    uint32_t _busy              : 1;

    uint32_t dst_module_id      : 16;
    uint32_t dst_instance_id    : 8;
    uint32_t dst_queue          : 3;
    uint32_t src_queue          : 3;
    uint32_t _done              : 1;
    uint32_t _error             : 1;
};

Table 17. Bind/Unbind – Request Parameters

Field Value
msg_tgt Msg::MODULE_MSG
rsp Msg::MSG_REQUEST
type

ModuleMsg::BIND, or
ModuleMsg::UNBIND

instance_id ID of source module instance assigned by the management service (if it exists)
module_id ID of source module (0-based index of the module entry in the FM Image Manifest)
src_queue ID of source queue (pin).
dst_queue ID of destination queue (pin).
dst_instance_id ID of destination module instance to be bound/unbound with the source module instance.
dst_module_id ID of destination module
Input Data

There is no input data.

Reply Message Control Header

Table 18. Bind / Unbind – Reply Parameters

Field Value
msg_tgt Msg::MODULE_MSG
rsp Msg::MSG_REPLY
type

ModuleMsg::BIND, or
ModuleMsg::UNBIND

status

ADSP_IPC_SUCCESS
Operation successful.

ADSP_IPC_INVALID_RESOURCE_ID
Invalid module ID or module instance ID specified.

ADSP_IPC_QUEUE_INVALID_ID
Invalid source queue ID specified.

ADSP_IPC_QUEUE_DST_INVALID_ID
Invalid destination queue ID specified.

ADSP_IPC_BIND_UNBIND_DST_SINK_UNSUPPORTED
Operation not allowed by pipeline state.

Output Data

There is no output data.

Enter Module Restore

This message is sent by the management service (if it exists) to indicate that it is beginning to restore the module instance state. This message is expected to be followed by series of Large/Module Config messages. Once all configuration parameters are sent to the module instance, the management service sends the Exit Module Restore message.

On Enter Module Restore, the target module instance performs the following actions:

  • Retrieves the state (enabled or disabled) of the internal logic and stores it internally. If the state cannot be retrieved, it is set to ‘enabled’ by default.
  • “Disables” processing logic (that is, triggers pass through mode).
  • Activates parameter filtering. The filtering means that enable/disable parameter is not applied. Instead, its value is cached (overriding the value retrieved earlier). All other parameters are applied instantly.

On Exit Module Restore, the target module instance applies the cached value of the enable/disable parameter and exits parameter filtering mode.

Request Message Control Header
struct Bits
{
    uint32_t module_id      : 16;
    uint32_t instance_id    : 8;
    uint32_t type           : 5;
    uint32_t rsp            : 1;
    uint32_t msg_tgt        : 1;
    uint32_t _busy          : 1;

    uint32_t rsvd1          : 30;
    uint32_t _done          : 1;
    uint32_t _error         : 1;
};

Table 19. Enter Module Restore – Request Parameters

Field Value
msg_tgt Msg::MODULE_MSG
rsp Msg::MSG_REQUEST
type ModuleMsg::ENTER_MODULE_RESTORE
instance_id ID of module instance assigned by the management service (if it exists)
module_id ID of module (0-based index of the module entry in the FM Image Manifest)
Input Data

None

Reply Message Control Header

Standard MsgReply is sent back.

Table 20. Enter Module Restore – Reply Parameters

Field Value
msg_tgt Msg::MODULE_MSG
Rsp Msg::MSG_REPLY
Type ModuleMsg::ENTER_MODULE_RESTORE
status

ADSP_IPC_SUCCESS

ADSP_IPC_INVALID_RESOURCE_ID
Invalid module ID or module instance ID specified.

Output Data

None

Exit Module Restore

This message is sent by the management service (if it exists) to complete the module restore sequence (see Section “Enter Module Restore”).

Request Message Control Header
struct Bits
{
    uint32_t module_id      : 16;
    uint32_t instance_id    : 8;
    uint32_t type           : 5;
    uint32_t rsp            : 1;
    uint32_t msg_tgt        : 1;
    uint32_t _busy          : 1;

    uint32_t rsvd1          : 30;
    uint32_t _done          : 1;
    uint32_t _error         : 1;
};

Table 21. Exit Module Restore – Request Parameters

Field Value
msg_tgt Msg::MODULE_MSG
rsp Msg::MSG_REQUEST
type ModuleMsg::EXIT_MODULE_RESTORE
instance_id ID of module instance assigned by the management service (if it exists)
module_id ID of module (0-based index of the module entry in the FM Image Manifest)
Input Data

None.

Reply Message Control Header

Standard MsgReply is sent back.

Table 22. Exit Module Restore – Reply Parameters

Field Value
msg_tgt Msg::MODULE_MSG
rsp Msg::MSG_REPLY
type ModuleMsg::EXIT_MODULE_RESTORE
status

ADSP_IPC_SUCCESS
Operation successful.

ADSP_IPC_INVALID_RESOURCE_ID
Invalid module ID or module instance ID specified.

Output Data

None.

Pipeline Management IPC Messages

Create Pipeline

The management service sends this message to create a new pipeline inside the firmware.

The pipeline priority assigned by the caller determines the priority of tasks associated with the pipeline’s module instances. A pipeline with priority 0 is executed before a pipeline with priority 1. The management service may assign priority 0 to the decode pipeline and priority 1 to the mixer pipeline to make sure that the decode pipeline’s low latency part runs first and delivers data to the low latency part of the mixer pipeline. The low latency part of the mixer pipeline, in turn, delivers data to the link within a single system tick.

Memory Requirements

Before sending this request, the management service (if it exists) must estimate the amount of memory that the pipeline will require to allocate its object and other associated buffers, as follows:

  • Pipeline object
  • Queues that are persistent (that is, queues attached to a DP task at least at one end)
  • Buffers allocated for instances of built-in child modules, and optionally their additional buffers
  • Task objects created for LL and DP module instances associated with the pipeline

The estimated memory size, expressed in pages, is specified by the management service in the ppl_mem_size parameter.

Table 23. Pipeline Memory Requirements

Component Size (bytes) Remarks
Pipeline object 320  
Child module instance list item 12 Per each child module instance.

Data queue buffer

+ data queue object

2 * max(IBS,OBS) + min(IBS,OBS)

or

3 * max(IBS,OBS)

+ 92

Per each binding between child module instances where at least one module instance is created in DP domain.

Data queue buffer is extended to 3*max(IBS,OBS) if at least one module instance requires extended queue.
LL task object 40 One per chain of contiguous child modules running in LL domain.

DP task object

+ DP task list item

+ DP task stack

84

+ 8

[+ <size specified in the Manifest>]

One per each child module running in DP domain.

Module descriptor contained by the FM Image Manifest specifies size of the stack (in bytes) required by the module instance (see Note1 below)

DP task list

+ list collection item

12

+ 8
One per chain of contiguous child modules running in DP domain.
Request Message Control Header
struct Bits
{
    uint32_t ppl_mem_size   : 11;
    uint32_t ppl_priority   : 5;
    uint32_t instance_id    : 8;
    uint32_t type           : 5;
    uint32_t rsp            : 1;
    uint32_t msg_tgt        : 1;
    uint32_t _busy          : 1;

    uint32_t lp             : 1;
    uint32_t rsvd1          : 29;
    uint32_t _done          : 1;
    uint32_t _error         : 1;
};

Table 24. Create Pipeline – Request Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_REQUEST
type Global::CREATE_PIPELINE
instance_id ID of the pipeline assigned by the management service
ppl_priority Pipeline priority. One of 0..7.
ppl_mem_size Size of memory (in pages) required for pipeline and its data.
lp

Indicates whether the pipeline should kept on running in Low-Power mode.

The management service should set this flag to 1 for a WOV pipeline.
Input Data

There is no input data.

Reply Message Control Header

Standard MsgReply is sent back.

Table 25. Create Pipeline – Reply Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_REPLY
type Global::CREATE_PIPELINE
status

ADSP_IPC_SUCCESS
Operation successful.

ADSP_IPC_INVALID_RESOURCE_ID
Pipeline ID is out of supported range.

ADSP_IPC_OUT_OF_MEMORY
No memory available to allocate the pool.

ADSP_IPC_PIPELINE_ALREADY_EXISTS
Specified ID is already in use.

Output Data

There is no output data.

Delete Pipeline

The management service sends this IPC message to delete a pipeline from ADSP memory. All module instances and tasks that are associated with the pipeline are deleted also.

For this command to complete successfully, there must be no existing binding from any pipeline’s module instance to another pipeline.

Request Message Control Header
struct Bits
{
    uint32_t rsvd0          : 16;
    uint32_t instance_id    : 8;
    uint32_t type           : 5;
    uint32_t rsp            : 1;
    uint32_t msg_tgt        : 1;
    uint32_t _busy          : 1;

    uint32_t rsvd1          : 30;
    uint32_t _done          : 1;
    uint32_t _error         : 1;
};

Table 26. Delete Pipeline – Request Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_REQUEST
type Global::DELETE_PIPELINE
instance_id ID of the pipeline assigned by the management service
Input Data

There is no input data.

Reply Message Control Header

Standard MsgReply is sent back.

Table 27. Delete Pipeline – Reply Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_REPLY
type Global::DELETE_PIPELINE
status

ADSP_IPC_SUCCESS
Operation successful.

ADSP_IPC_INVALID_RESOURCE_ID
Invalid pipeline ID specified.

ADSP_IPC_INVALID_RESOURCE_STATE
One (or more) of pipeline module instances are still bound to another pipeline.

Output Data

There is no output data.

Set Pipeline State

Note Task Creation/Registration is part of first state transition. There is no other dedicated call for this.

Request Message Control Header
struct Bits
{
    uint32_t state          : 16;
    uint32_t ppl_id         : 8;
    uint32_t type           : 5;
    uint32_t rsp            : 1;
    uint32_t msg_tgt        : 1;
    uint32_t _busy          : 1;

    uint32_t multi_ppl      : 1;
    uint32_t rsvd1          : 29;
    uint32_t _done          : 1;
    uint32_t _error         : 1;
};

Table 28. Set Pipeline State – Request Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_REQUEST
type Global::SET_PIPELINE_STATE
ppl_id ID of the pipeline assigned by the management service. If multi_ppl is set to 1 this field is ignored and list of pipelines’ identifiers is read from the message payload.
state

Target pipeline state. One of:
2 – RESET,

3 – PAUSED,

4 – RUNNING,

5 – END_OF_STREAM.
multi_ppl

Indicates if state should be set to a single pipeline or multiple pipelines.

0 – single pipeline specified by ppl_id field,

1 – multiple pipelines specified by the payload.
Input Data

The input data is optional. It occurs only when multi_ppl is set to 1.

struct Data
{
    pipelines_count;
    ppl_id[1]; // actual size specified by pipelines_count
};
Reply Message Control Header

Standard MsgReply is sent back.

Table 29. Set Pipeline State – Reply Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_REPLY
type Global::SET_PIPELINE_STATE
status

ADSP_IPC_SUCCESS
Operation successful.

ADSP_IPC_PIPELINE_NOT_EXIST
Invalid pipeline ID specified.

ADSP_IPC_PIPELINE_STATE_NOT_SET
Pipeline is exported to the host memory.

ADSP_IPC_INVALID_REQUEST
Either transition from the current state to the requested state is unsupported or new pipeline state is invalid.

Output Data

There is no output data.

Get Pipeline State

This IPC message is sent to the firmware to retrieve a pipeline state.

Request Message Control Header
struct Bits
{
    uint32_t rsvd0          : 16;
    uint32_t instance_id    : 8;
    uint32_t type           : 5;
    uint32_t rsp            : 1;
    uint32_t msg_tgt        : 1;
    uint32_t _busy          : 1;

    uint32_t rsvd1          : 30;
    uint32_t _done          : 1;
    uint32_t _error         : 1;
};

Table 30. Get Pipeline State – Request Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_REQUEST
type Global::GET_PIPELINE_STATE
instance_id ID of the pipeline assigned by the management service
Input Data

There is no input data.

Reply Message Control Header
struct Bits
{
    uint32_t status     : IXC_STATUS_BITS;
    uint32_t type       : 5;
    uint32_t rsp        : 1;
    uint32_t msg_tgt    : 1;
    uint32_t _busy      : 1;

    uint32_t state      : 5;
    uint32_t rsvd1      : 25;
    uint32_t _done      : 1;
    uint32_t _error     : 1;
};

Table 31. Get Pipeline State – Reply Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_REPLY
type Global::GET_PIPELINE_STATE
status

ADSP_IPC_SUCCESS
Operation successful.

ADSP_IPC_INVALID_RESOURCE_ID
Invalid pipeline ID specified.

state

Pipeline state. One of:
1 – UNINITIALIZED,
2 – RESET,
3 – PAUSED,
4 – RUNNING,
5 – ERROR_STOP,
6 – SAVED.

Output Data

There is no output data.

Notifications

FW Ready Notification

This notification is reported by the Base FW immediately after the initialization phase completes.

Notification Message Control Header
struct Bits
{
    uint32_t rsvd2          : 16;
    uint32_t notif_type     : 8;
    uint32_t type           : 5;
    uint32_t rsp            : 1;
    uint32_t msg_tgt        : 1;
    uint32_t _busy          : 1;

    uint32_t rsvd1          : 30;
    uint32_t _done          : 1;
    uint32_t _error         : 1;
};

Table 32. FW Ready Notification – Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_NOTIFICATION (0)
type Global::NOTIFICATION
notif_type Notification::FW_READY
Input Data

There is no input data.

Voice Cmd Notification

This notification is reported by the WOV module on key phrase detection.

Notification Message Control Header
struct Bits
{
    uint32_t word_id        : 16;
    uint32_t notif_type     : 8;
    uint32_t type           : 5;
    uint32_t rsp            : 1;
    uint32_t msg_tgt        : 1;
    uint32_t _busy          : 1;

    uint32_t sv_score       : 16
    uint32_t rsvd1          : 14;
    uint32_t _done          : 1;
    uint32_t _error         : 1;
};

Table 33. Voice Cmd Notification –Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_NOTIFICATION (0)
type Global::NOTIFICATION
notif_type Notification::PHRASE_DETECTED
word_id ID of detected keyword
sv_score Final speaker verification score in range of 0..8192.
Input Data

Depending on the running WOV implementation, optional data may be provided. The data may be provided as a BLOB to a client by the management service.

Intel® Wake on Voice (Intel® WOV)
struct Data
{
    uint16_t kpd_score;
    uint16_t reserved;
};

Refer to the Intel® WOV documentation for details.

MCPS Budget Violation Notification

This notification is reported by the resource verifier after either LL or DP task finished processing and measured number of consumed cycles exceeded number declared in associated module instance configuration sent by the management service along with module instance initialization request.

The module stores the peak value of cycles consumed reported to the management service during runtime. If the measured value is less than reported peak, then notification is not sent even if the current measurement exceeds the budget.

Notification Message Control Header
struct Bits
    {
        uint32_t rsvd0          : 16;
        uint32_t notif_type     : 8;
        uint32_t type           : 5;
        uint32_t rsp            : 1;
        uint32_t msg_tgt        : 1;
        uint32_t _busy          : 1;

        uint32_t rsvd1          : 30;
        uint32_t _done          : 1;
        uint32_t _error         : 1;
    };

Table 34. MCPS Budget Violation Notification –Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_NOTIFICATION (0)
type Global::NOTIFICATION
notif_type Notification::RESOURCE_EVENT
Input Data
struct Data
{
    uint32_t resource_type;
    uint32_t resource_id;
    uint32_t event_type;
    uint32_t event_data[6];
};

Table 35. MCPS Budget Violation Notification –Data

Field Value
resource_type Message::ResourceType::MODULE_INSTANCE
resource_id Module ID (MS word) + Module Instance ID (LS word)
event_type Message::ResourceEventType::BUDGET_VIOLATION
event_data[0] Cycles consumed by last processing data routine.

Mixer/Gateway Underrun Detected Notification

This notification is sent by the mixer or copier attached to a gateway on stream underrun detection.

The frequency of sending this notification by the mixer depends on the MixIn settings (see Section “Runtime Parameters”).

Notification Message Control Header
    struct Bits
    {
        uint32_t rsvd0          : 16;
        uint32_t notif_type     : 8;
        uint32_t type           : 5;
        uint32_t rsp            : 1;
        uint32_t msg_tgt        : 1;
        uint32_t _busy          : 1;

        uint32_t rsvd1          : 30;
        uint32_t _done          : 1;
        uint32_t _error         : 1;
    };

Table 36. Mixer/Gateway Underrun Detected Notification – Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_NOTIFICATION (0)
type Global::NOTIFICATION
notif_type Notification::RESOURCE_EVENT
Input Data
    struct Data
    {
        uint32_t resource_type;
        uint32_t resource_id;
        uint32_t event_type;
        uint32_t event_data[6];
    };

Table 37. Mixer/Gateway Underrun Detected Notification – Data

Field Value
resource_type Message::ResourceType::PIPELINE
resource_id Pipeline ID
event_type

Message::ResourceEventType::MIXER_UNDERRUN_DETECTED

or

Message::ResourceEventType::GATEWAY_UNDERRUN_DETECTED

Gateway Overrun Detected Notification

This notification is sent by the copier attached to a gateway on stream overrun detection.

Notification Message Control Header
    struct Bits
    {
        uint32_t rsvd0          : 16;
        uint32_t notif_type     : 8;
        uint32_t type           : 5;
        uint32_t rsp            : 1;
        uint32_t msg_tgt        : 1;
        uint32_t _busy          : 1;

        uint32_t rsvd1          : 30;
        uint32_t _done          : 1;
        uint32_t _error         : 1;
    };

Table 38. Gateway Overrun Detected Notification – Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_NOTIFICATION (0)
type Global::NOTIFICATION
notif_type Notification::RESOURCE_EVENT
Input Data
    struct Data
    {
        uint32_t resource_type;
        uint32_t resource_id;
        uint32_t event_type;
        uint32_t event_data[6];
    };

Table 39. Gateway Overrun Detected Notification – Data

Field Value
resource_type Message::ResourceType::PIPELINE
resource_id Pipeline ID
event_type Message::ResourceEventType::GATEWAY_OVERRUN_DETECTED

Process Data Error Notification

Note Formerly known as DECODER_ERROR.

This notification is sent by a shim of module instance on error raised by data processing function.

Notification Message Control Header
    struct Bits
    {
        uint32_t rsvd0          : 16;
        uint32_t notif_type     : 8;
        uint32_t type           : 5;
        uint32_t rsp            : 1;
        uint32_t msg_tgt        : 1;
        uint32_t _busy          : 1;

        uint32_t rsvd1          : 30;
        uint32_t _done          : 1;
        uint32_t _error         : 1;
    };

Table 40. Process Data Error Notification – Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_NOTIFICATION (0)
type Global::NOTIFICATION
notif_type Notification::RESOURCE_EVENT
Input Data
    struct Data
    {
        uint32_t resource_type;
        uint32_t resource_id;
        uint32_t event_type;
        uint32_t event_data[6];
    };

Table 41. Process Data Error Notification – Data

Field Value
resource_type Message::ResourceType::MODULE_INSTANCE
resource_id Module ID (MS word) + Module Instance ID (LS word)
event_type Message::ResourceEventType::PROCESS_DATA_ERROR
event_data[0] Set to the error code raised by the data processing function. If there is 3rd party IP, it is set to its native error code returned by the 3rd party library.

End of Stream Notification

This notification is a variant of underrun notification. It is reported by the mixer immediately after the last sample from a stream, marked by the management service as EoS pending, is sent to the link.

Data::event_data[0] is set to 1 to indicate that this is EoS Underrrun.

Log Buffer Status Notification

This notification is reported by the tracing facility when the write pointer passes either half of the trace buffer (of either core).

Notification Message Control Header
    struct Bits
    {
        uint32_t core_id        : 4;
        uint32_t rsvd0          : 12;
        uint32_t notif_type     : 8;
        uint32_t type           : 5;
        uint32_t rsp            : 1;
        uint32_t msg_tgt        : 1;
        uint32_t _busy          : 1;

        uint32_t rsvd1          : 30;
        uint32_t _done          : 1;
        uint32_t _error         : 1;
    };

Table 42. Log Buffer Status Notification – Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_NOTIFICATION (0)
type Global::NOTIFICATION
notif_type Notification::LOG_BUFFER_STATUS
core_id ID of DSP core that crossed its buffer boundary.
Input Data

There is no input data.

Timestamp Captured Notification

This notification is reported by a gateway management service when timestamping request sent by the management service (if it exists) is completed and timestamping data is available.

Node ID of the gateway is specified in the event data.

Notification Message Control Header
    struct Bits
    {
        uint32_t rsvd0          : 16;
        uint32_t notif_type     : 8;
        uint32_t type           : 5;
        uint32_t rsp            : 1;
        uint32_t msg_tgt        : 1;
        uint32_t _busy          : 1;

        uint32_t rsvd1          : 30;
        uint32_t _done          : 1;
        uint32_t _error         : 1;
    };

Table 43. Timestamp Captured Notification – Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_NOTIFICATION (0)
type Global::NOTIFICATION
notif_type Notification::TIMESTAMP_CAPTURED

Input Data

Syntax
    struct Data
    {
        uint32_t module_instance_id;
        uint32_t node_id;
        uint32_t timestamp_data[7];
    };
Members

module_instance_id

Module ID (MS word) + module instance ID (LS word).

node_id

ID of gateway (see ConnectorNodeId).

timestamp_data

Value of <ifc>_ISOFFSET (32 bits),

Value of <ifc>_LOCAL_SAMPLE (64 bits),

Value of <ifc>_LOCAL_WALCLK (64 bits),

Value of <ifc>_Time Stamp Counter Captured (64 bits).

Refer to DSP Timestamping Registers for detailed description.

Stream Data Segment Notification

This notification is reported by an instance of a Copier when the amount of data transferred through an attached Gateway exceeds the configured data segment size.

Event data contains the linear position (in bytes) of the segment beginning and end, where the linear counter starts from the last gateway reset.

Notification Message Control Header
    struct Bits
    {
        uint32_t rsvd0          : 16;
        uint32_t notif_type     : 8;
        uint32_t type           : 5;
        uint32_t rsp            : 1;
        uint32_t msg_tgt        : 1;
        uint32_t _busy          : 1;

        uint32_t rsvd1          : 30;
        uint32_t _done          : 1;
        uint32_t _error         : 1;
    };

Table 44. Stream Data Segment Notification – Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_NOTIFICATION (0)
type Global::NOTIFICATION
notif_type Notification::RESOURCE_EVENT
Input Data
    struct Data
    {
        uint32_t resource_type;
        uint32_t resource_id;
        uint32_t event_type;
        uint32_t event_data[6];
    };

Table 45. Stream Data Segment Notification – Data

Field Value
resource_type Message::ResourceType::PIPELINE
resource_id Pipeline ID
event_type Message::ResourceEventType::STREAM_DATA_SEGMENT
event_data[0] Copier instance ID.
event_data[1] Gateway Node ID.
event_data[2-3] 64-bit linear position (in bytes) of the segment beginning. Linear counter starts from the last gateway reset.
event_data[4-5] 64-bit linear position (in bytes) of the segment end.

Buffering Mode Changed Notification

This notification is reported by an instance of KPBUF once buffered data was transferred through the speech pipeline and the buffer is freed. The management service (if it exists) should use this information to update its internally maintained FW resource allocation record.

Notification Message Control Header
    struct Bits
    {
        uint32_t rsvd0          : 16;
        uint32_t notif_type     : 8;
        uint32_t type           : 5;
        uint32_t rsp            : 1;
        uint32_t msg_tgt        : 1;
        uint32_t _busy          : 1;

        uint32_t rsvd1          : 30;
        uint32_t _done          : 1;
        uint32_t _error         : 1;
    };

Table 46. Buffering Mode Changed Notification – Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_NOTIFICATION (0)
type Global::NOTIFICATION
notif_type Notification::RESOURCE_EVENT
Input Data
    struct Data
    {
        uint32_t resource_type;
        uint32_t resource_id;
        uint32_t event_type;
        uint32_t event_data[6];
    };

Table 47. Buffering Mode Changed Notification – Data

Field Value
resource_type Message::ResourceType::MODULE_INSTANCE
resource_id Module ID (MS word) + Module Instance ID (LS word)
event_type Message::ResourceEventType::BUFFERING_MODE_CHANGED
event_data[0] New buffering mode (see KPBUF’s BUFFERING_MODE parameter documentation).

Module Callback Notification

This notification is reported by a module instance when it encapsulates a library that requires a callback to report events to a software component residing on the host.

Notification Message Control Header
    struct Bits
    {
        uint32_t rsvd0          : 16;
        uint32_t notif_type     : 8;
        uint32_t type           : 5;
        uint32_t rsp            : 1;
        uint32_t msg_tgt        : 1;
        uint32_t _busy          : 1;

        uint32_t rsvd1          : 30;
        uint32_t _done          : 1;
        uint32_t _error         : 1;
    };

Table 48. Module Callback Notification – Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_NOTIFICATION (0)
type Global::NOTIFICATION
notif_type Notification::MODULE_CALLBACK_EVENT

Input Data

Syntax
struct Data
{
    uint32_t module_instance_id;
    uint32_t event_id;
    uint32_t event_data_size;
    uint32_t event_data[1];
};
Members

module_instance_id

Module ID (MS word) + Module Instance ID (LS word)

event_id

Module’s specific event ID.

event_data_size

Size of event_data array in bytes. May be set to 0 in case there is no data.

event_data

Optional event data

Exception Caught Notification

This notification is reported by the Base FW when DSP core exception is caught.

Notification Message Control Header
    struct Bits
    {
        uint32_t core_id        : 4;
        uint32_t rsvd2          : 12;
        uint32_t notif_type     : 8;
        uint32_t type           : 5;
        uint32_t rsp            : 1;
        uint32_t msg_tgt        : 1;
        uint32_t _busy          : 1;

        uint32_t rsvd1          : 30;
        uint32_t _done          : 1;
        uint32_t _error         : 1;
    };

Table 49. Exception Caught Notification – Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_NOTIFICATION (0)
type Global::NOTIFICATION
notif_type Notification::EXCEPTION_CAUGHT
core_id ID of a core that thrown an exception.
Input Data

There is no input data.

Core exception data may be dumped by the management service from FW Registers memory window area (see also, the CoreExceptionRecord structure).

Gateway High/Low Threshold Notification

This notification is sent by the IPC gateway when the low or high threshold is reached.

Notification Message Control Header
    struct Bits
    {
        uint32_t rsvd0          : 16;
        uint32_t notif_type     : 8;
        uint32_t type           : 5;
        uint32_t rsp            : 1;
        uint32_t msg_tgt        : 1;
        uint32_t _busy          : 1;

        uint32_t rsvd1          : 30;
        uint32_t _done          : 1;
        uint32_t _error         : 1;
    };

Table 50. Buffering Mode Changed Notification –Parameters

Field Value
msg_tgt Msg::FW_GEN_MSG
rsp Msg::MSG_NOTIFICATION (0)
type Global::NOTIFICATION
notif_type Notification::RESOURCE_EVENT
Input Data
    struct Data
    {
        uint32_t resource_type;
        uint32_t resource_id;
        uint32_t event_type;
        uint32_t event_data[6];
    };

Table 51. Gateway Threshold Notification – Data

Field Value
resource_type Message::ResourceType::GATEWAY
resource_id Module ID (MS word) + Module Instance ID (LS word)
event_type

Message::ResourceEventType::GATEWAY_HIGH_THRES

Or

Message::ResourceEventType::GATEWAY_LOW_THRES
event_data[0] Amount of data in sink/source gateway
event_data[1] Threshold

Module Configuration

There are two classes of module parameters:

  • Parameters applied at the module creation time, called Initial Module Configuration
  • Parameters applied/modified at runtime, called Runtime Module Configuration

Initial Module Configuration

Each module instance must be configured initially during creation by the Init Instance IPC request.

Note Base FW as a special firmware module is an exception. There is no initial configuration in this case.

An initial module configuration structure, BaseModuleCfg, is inherited by any module-specific configuration. Module configuration begins with BaseModuleCfg, and is followed by either a module-specific extension or a generic extension (BaseModuleCfgExt) that contains the audio format for all the module’s pins that are in use. BaseModuleCfg configures only input pin 0 and output pin 0 with a common audio_fmt.

A module that does not define a specific extension must be prepared to handle BaseModuleCfg, both with and without BaseModuleCfgExt.

Note Even when BaseModuleCfgExt is provided by the management service and specifies the format of the input and output pins in use, the BaseModuleCfg must be fully specified for backward compatibility with a module that does not require the audio format of more pins, and keeps the legacy implementation that is aware of BaseModuleCfg only.

BaseModuleCfg Structure

Syntax
struct BaseModuleCfg
{
    uint32_t           cpc;
    uint32_t           ibs;
    uint32_t           obs;
    uint32_t           is_pages;
    AudioDataFormatIpc audio_fmt;
};
Members

cpc

Number of DSP cycles required to process one input frame,

ibs

Size of the module instance input frame (in bytes),

obs

Size of the module instance output frame (in bytes),

is_pages

Number of memory pages to be allocated for this module instance (valid and used by FW if there is an instance of loadable module; ignored for a build-in module instance)

audio_fmt

Format of the module instance input data.

Remarks

The data required to build basic module configuration should be retrieved by the management service from the Module Configuration array, part of the FM Image Manifest. Appropriate Module Configuration record is selected based on lookup parameters (specific lookup parameter values are management service implementation specific and should be provided as an input to the Firmware Image Builder).

BaseModuleCfgExt Structure

Syntax
struct BaseModuleCfgExt
{
    uint16_t           nb_input_pins;
    uint16_t           nb_output_pins;
    uint8_t            reserved[8];
    uint32_t           priv_param_length;
    InputPinFormat     input_pins[length_is(nb_input_pins)];
    OuputPinFormat     output_pins[length_is(nb_output_pins)];
};
Members

nb_input_pins

Specifies number of items in input_pins array. Maximum size is 8.

nb_output_pins

Specifies number of items in output_pins array. Maximum size is 8.

reserved

Not used, set to 0.

priv_param_length

Length of optional module-specific parameters that follow BaseModuleCfgExt.

input_pins

Specifies format of input pins.

output_pins

Specifies format of output pins.

Remarks

Pin format arrays may be non-continuous that is, may contain pin #0 format followed by pin #2 format in case pin #1 will not be in use. FW assigned format of the pin based on pin_index, not on a position of the item in the array.

InputPinFormat Structure

Syntax
struct InputPinFormat
{
    uint32_t         pin_index;
    uint32_t         ibs;
    AudioDataFormat  audio_fmt;
};
Members

pin_index

Index of the pin.

ibs

Specifies input frame size (in bytes).

audio_fmt

Format of the input data.

OutputPinFormat Structure

Syntax
struct OutputPinFormat
{
    uint32_t            pin_index;
    uint32_t            obs;
    AudioDataFormatIpc  audio_fmt;
};
Members

pin_index

Index of the pin.

obs

Specifies output frame size (in bytes).

audio_fmt

Format of the output data.

AudioDataFormatIpc Structure

Defines format of the audio data that is either sent to or received from a module instance.

Syntax
#pragma pack(4)
struct AudioDataFormatIpc
{
    SamplingFrequency sampling_frequency;
    BitDepth          bit_depth;
    ChannelMap        channel_map;
    ChannelConfig     channel_config;
    InterlivingStyle  interliving_style;
    uint32_t          number_of_channels    : 8;
    uint32_t          valid_bit_depth       : 8;
    uint32_t          sample_type           : 8;

    uint32_t          reserved              : 8;
};
C_ASSERT(sizeof(AudioDataFormatIpc) == (24));
Members

sampling_frequency

Sampling frequency in Hz.

bit_depth

Bit depth

channel_map

Channel ordering

channel_config

Channel configuration

interliving_style

The way the samples are interleaved.

number_of_channels

Total number of channels.

valid_bit_depth

Valid bit depth. Must be equal or less than the container size specified by bit_depth.

sample_type

Type of sample (see SampleType definition).

enum SamplingFrequency
{
    FS_8000HZ   = 8000,
    FS_11025HZ  = 11025,
    FS_12000HZ  = 12000,
    FS_16000HZ  = 16000,
    FS_22050HZ  = 22050,
    FS_24000HZ  = 24000,
    FS_32000HZ  = 32000,
    FS_44100HZ  = 44100,
    FS_48000HZ  = 48000,
    FS_64000HZ  = 64000,
    FS_88200HZ  = 88200,
    FS_96000HZ  = 96000,
    FS_128000HZ = 128000,
    FS_176400HZ = 176400,
    FS_192000HZ = 192000,
    FS_INVALID
};

enum BitDepth
{
    DEPTH_8BIT  = 8,
    DEPTH_16BIT = 16,
    DEPTH_24BIT = 24,
    DEPTH_32BIT = 32,
    DEPTH_INVALID
};



typedef uint32_t ChannelMap;

enum ChannelIndex
{
    CHANNEL_LEFT            = 0,
    CHANNEL_CENTER          = 1,
    CHANNEL_RIGHT           = 2,
    CHANNEL_LEFT_SURROUND   = 3,
    CHANNEL_CENTER_SURROUND = 3,
    CHANNEL_RIGHT_SURROUND  = 4,
    CHANNEL_LEFT_SIDE       = 5,
    CHANNEL_RIGHT_SIDE      = 6,
    CHANNEL_LFE             = 7,
    CHANNEL_INVALID         = 0xF,
};

enum ChannelConfig
{
    CHANNEL_CONFIG_MONO      = 0,     // One channel only
    CHANNEL_CONFIG_STEREO    = 1,     // L & R
    CHANNEL_CONFIG_2_POINT_1 = 2,     // L, R & LFE; PCM only
    CHANNEL_CONFIG_3_POINT_0 = 3,     // L, C & R; MP3 & AAC only
    CHANNEL_CONFIG_3_POINT_1 = 4,     // L, C, R & LFE; PCM only
    CHANNEL_CONFIG_QUATRO    = 5,     // L, R, Ls & Rs; PCM only
    CHANNEL_CONFIG_4_POINT_0 = 6,     // L, C, R & Cs; MP3 &
                                      // AAC only
    CHANNEL_CONFIG_5_POINT_0 = 7,     // L, C, R, Ls & Rs
    CHANNEL_CONFIG_5_POINT_1 = 8,     // L, C, R, Ls, Rs & LFE
    CHANNEL_CONFIG_DUAL_MONO = 9,     // One channel replicated 
                                      // in two
    CHANNEL_CONFIG_I2S_DUAL_STEREO_0 = 10, // Stereo (L,R) in 4
                                           // slots, 1st stream:
                                           // [ L, R, -, - ]
    CHANNEL_CONFIG_I2S_DUAL_STEREO_1 = 11, // Stereo (L,R) in 4
                                           // slots, 2nd stream:
                                           // [ -, -, L, R ]
    CHANNEL_CONFIG_INVALID
};

enum InterlivingStyle
{
    INTERLIVING_PER_CHANNEL = 0, //[s1_ch1...s1_chN,...,sM_ch1...sM_chN]
    INTERLIVING_PER_SAMPLE  = 1, //[s1_ch1...sM_ch1,...,s1_chN...sM_chN]
};

typedef uint32_t SampleType;
const SampleType SAMPLE_TYPE_INT_MSB = 0;
const SampleType SAMPLE_TYPE_INT_LSB = 1;
const SampleType SAMPLE_TYPE_INT_SIGNED = 2;
const SampleType SAMPLE_TYPE_INT_UNSIGNED = 3;
const SampleType SAMPLE_TYPE_FLOAT = 4;

Runtime Module Configuration

Some of the module instance parameters can be changed later during runtime using Module Config Set/Large Config Set IPC requests. There is also a symmetric Module Config Get/Large Config Get pair of IPC requests to retrieve the parameter values of a module instance.

Common Configuration Parameters

Configuration parameters are defined for all module instances.

Handling depends on the specific module implementation. If error-free handling of a parameter is required from all module instances, it is explicitly expressed.

Runtime Parameters

The following runtime parameters are common for all modules.

Table 52.Common Runtime Parameters

Parameter ID Dir Type
MOD_INST_ENABLE 0X3000 R/W Small
MOD_INST_PROPs 0xFE R Large

Module Instance Enable

The management service sets this property to enable or disable data processing inside the target module instance.

This property must be handled in all post-processing modules.

Implementation is expected to be translated into an IP-specific parameter that enables or disables pass-through mode in the IP library.

This property must be accepted by the module instance even during ongoing data processing. In this situation, the response is sent back to the management service when the pass-through mode is enabled after ongoing processing is complete, so that the IP mode is changed from the next data frame.

There is no data, as this is a small parameter. The 16-bit value is set by the management service to either of the following:

  • 1 – Enable processing
  • 0 – Disable processing

Module Instance Properties

The management service reads this module instance parameter to retrieve various properties of the module instance.

ModuleInstanceProps Structure

Syntax
struct ModuleInstanceProps
{
    uint32_t          id;
    uint32_t          dp_queue_type;
    uint32_t          queue_alignment;
    uint32_t          cp_usage_mask;
    uint32_t          stack_bytes;
    uint32_t          bss_total_bytes;
    uint32_t          bss_used_bytes;
    uint32_t          ibs_bytes;
    uint32_t          obs_bytes;
    uint32_t          cpc;
    uint32_t          cpc_peak;
    PinListInfo       input_pins;
    PinListInfo       output_pins;
    ConnectorNodeId   input_gateway;
    ConnectorNodeId   output_gateway;
};
Members

id

Unique ID of the module instance. 16 MSBits specify the module ID that can refer to the module properties (ModuleEntry::module_id) while 16 LSBits specify the instance ID.

dp_queue_type

Required type of DP queues (if in DATA_PROCESSING domain).

queue_alignment

Required alignment of queues.

cp_usage_mask

Indicates which coprocessors are used by the module instance.

bit[1] – indicates use of Hifi3.

stack_bytes

Size of the stack allocated for the module instance’s task.

Non-zero value if module runs in a task with own allocated stack.

bss_total_bytes

Size of .bss segment allocated by the module instance.

bss_used_bytes

Size of part of .bss segment used by the module instance. bss_used_bytes <= bss_total_bytes.

ibs_bytes

Input buffer size.

obs_bytes

Output buffer size.

cpc

Required processor cycles per single data processing iteration.

cpc_peak

Peak CPC value measured since enabling/resetting performance measurements.

input_pins

Information about input pins.

output_pins

Information about output pins.

input_gateway

Specifies gateway connector node ID of input gateway if connected to a module on input, otherwise INVALID_NODE_ID.

output_gateway

Specifies gateway connector node ID of output gateway if connected to a module on output, otherwise INVALID_NODE_ID.

PinListInfo Structure
Syntax
struct PinListInfo
{
    uint32_t  pin_count;
    PinProps  pin_info[];
};
Members

pin_count

Number of items in pin_info array.

This value does not exceed MAX_MODULE_PIN_COUNT member of Base FW’s FIRMWARE_CONFIG parameter.

pin_info

List of pins’ properties. See also PinProps.

PinProps Structure
Syntax
struct PinProps
{
    StreamType          stream_type;
    AudioDataFormatIpc  format;
    uint32_t            phys_queue_id;
};
Members

stream_type

Type of the stream. One of the following:

  • 0 – PCM
  • 1 – MP3 encoded

format

Audio format of pin. The content is valid if there is PCM stream.

phys_queue_id

Unique ID of physical queue connected to the pin. If there is no queue connected, then -1 (invalid queue ID) is set.

Base FW

UUID: 61EB0CB9-34D8-4F59-A21D-04C54C21D3A4

There is no initial configuration provided to the firmware infrastructure while the Base FW module is loaded by ROM. The only instance of the Base FW configures itself internally.

Runtime Parameters

Base FW handles requests that come directly from the management service where the 8-bit parameter ID is specified in the LargeConfigGet/Set header. It also handles requests that come from an application where the parameter ID in the message header is set to APPLICATION_PARAM, and the actual 8-bit parameter ID is specified in the request payload.

When the parameter ID is specified in the request payload, its width is extended to 32 bits. This extension enables subaddressing, using the most significant 24 bits for parameter instance ID (see the ExtendedParameterId structure).

ExtendedParameterId Structure

Syntax
struct ExtendedParameterId
{
    uint32_t parameter_type     : 8;
    uint32_t parameter_instance : 24;
};
Members

parameter_type

Set to major parameter ID, for example, 11 when retrieving PIPELINE_PROPS.

parameter_instance

Set to parameter instance value, for example, pipeline ID when retrieving PIPELINE_PROPS.

The following runtime parameters are handled by the Base FW.

Table 53. Base FW Runtime Parameters

Parameter ID Dir Type
ADSP_PROPERTIES 0 R Large
ADSP_RESOURCE_STATE 1 R Large
NOTIFICATION_MASK 3 R/W Large
ASTATE_TABLE 4 R/W Large
DMA_CONTROL 5 W Large
ENABLE_LOGS 6 W Large
FIRMWARE_CONFIG 7 R/W Large
HARDWARE_CONFIG 8 R Large
MODULES_INFO 9 R Large
PIPELINE_LIST_INFO 10 R Large
PIPELINE_PROPS 11 R Large
SCHEDULERS_INFO 12 R Large
GATEWAYS_INFO 13 R Large
MEMORY_STATE_INFO 14 R Large
POWER_STATE_INFO 15 R Large
LIBRARIES_INFO 16 R Large
PERF_MEASUREMENTS_STATE 17 R/W Large
GLOBAL_PERF_DATA 18 R Large
L2_CACHE_INFO 19 R Large
SYSTEM_TIME 20 R/W Large

ADSP Properties

The management service requests the value of this Base FW property to discover the firmware configuration. Configuration data is returned as a TLV list and contains the items described in the following table.

Table 54. ADSP Properties

Type Length(Bytes) Value

FW_VERSION (0)
FW Version

8

struct FwVersion

{
    uint16_t major;
    uint16_t minor;
    uint16_t hotfix;
    uint16_t build;
};

DSP_CORES (1)
Number of cores

4 uint32_t dsp_cores;

MEM_PAGE_SIZE (2)
Size of a single memory page.

4 uint32_t mem_page_size;

TOTAL_PHYS_MEM_PAGES (3)
Total number of physical pages available for allocation.

4 uint32_t total_mem_pages;

IPC_DL_MAILBOX_SIZE (4)
IPC down link mailbox size.

4 uint32_t mailbox_size;

IPC_UL_MAILBOX_SIZE (5)
IPC up link mailbox size.

4 uint32_t mailbox_size;

TRACE_LOG_SIZE (6)
Size of a single-core trace login bytes.

4 uint32_t trace_log_size;

MAX_PPL_CNT (7)
Maximum number of pipelines that may be instantiated at the same time.

4 uint32_t max_ppl_cnt;

ADSP Resource State

The management service requests the value of this Base FW property to learn the current state of resources. The list of resources is TLV encoded.

Table 55. ADSP Resource State

Type Length(Bytes) Value

FREE_PHYS_MEM_PAGES (0)

Free physical memory pages.

The value of parameter is an array of PhysMemPages records. Number of records depends on how many separately manageable memory classes are defined in ADSP. Memory class is set to mem_type field. Currently there are two memory classes:

  • 0 – HP_MEM,
  • 1 – LP_MEM.s
So the length of value is 2 * 8 = 16 bytes.
16

struct PhysMemPages

{
uint32_t mem_type;
uint32_t pages;
};

Notification Mask

The management service sends this request to enable or disable notifications. Use this message with the management service in debug mode to avoid flooding the host with underrun notifications (for example, when the management service is stopped by breakpoint).

NotificationMaskInfo Structure

Syntax
struct NotificationMaskInfo
{
    uint32_t ntfy_mask;
    uint32_t enabled_mask;
};
Members

ntfy_mask

Indicates which notifications are begin enabled/disabled.

[0] – Underruns at gateway

[1] – Underruns at mixer

[2] – MCPS Budget Violation

enabled_mask

Indicates if notifications indicated by corresponding bits in notification_mask are enabled (1b) or disabled (1b).

A-State Table

The management service sends A-State Table data when the Base FW is ready to handle IPC communication. The table is forwarded to the Power Manager to configure available power states according to the underlying platform.

The table must be nonempty.

Default A-State table

120K     LPRO

400K     HPRO

Astate Structure
Syntax
enum ClockSrc
{
    CLOCK_SRC_INVALID   = 0,
    CLOCK_SRC_XTAL      = 1,
    CLOCK_SRC_FAST_OSC  = 2,
    CLOCK_SRC_PLL       = 3,
    CLOCK_SRC_LPRO      = 4,
    CLOCK_SRC_HPRO      = 5,
    CLOCK_SRC_CRO_DIV_4 = 6,
    CLOCK_SRC_CRO       = 7,
};

struct Astate
{
    uint32_t kcps;
    uint32_t clk_src;
};
Members

kcps

Specifies core load threshold (expressed in kilo cycles per second). When load is below this threshold DSP is clocked from source specified by clk_src.

Configuring 0 kcps in the first entry means that this clock source is used in idle state only.

clk_src

Clock source associated with kcps threshold (see enum ClockSrc).

AstateArray Structure

Syntax
struct AstateArray
{
    uint32_t count;
    Astate states[];
};
Members

count

Number of entries in states array. The value does not exceed maximum number specified by MAX_ASTATE_COUNT member of Base FW’s FIRMWARE_CONFIG parameter.

states

Array of states.

DMA Control

The management service sends the DMA Control parameter to initialize or modify the DMA gateway configuration outside of a stream lifetime. Typically, a DMA gateway is initialized during pipeline creation when a Copier module is instantiated and attached to that gateway. Similarly, the gateway is de-initialized when the Copier’s parent pipeline is destroyed. However, the management service may sometimes want to control the gateway before or after a stream is to it.

The data of the DMA Control parameter starts with a DmaControl structure, followed optionally by the target gateway-specific data. This data may consist of two parts, the former coming from NHLT BIOS tables and the latter provided by the management service.

DmaControl Structure

Syntax
struct DmaControl
{
    uint32_t node_id;
    uint32_t config_length;
    uint32_t config_data[];
};
Remarks

All members have the same meaning as in the CopierGatewayCfg structure (except for the dma_buffer_size that is not used here).

Enable Logs

The management service sets this parameter to control the state of firmware logging. The management service may enable logging for each core and specify logging level. The management service also configures the period of aging and FIFO full timers. The aging timer period specifies how frequently the firmware sends a Log Buffer Status notification for new entries when the usual notification sending criteria are not met (that is, the buffer is half full). The FIFO full timer period specifies the latency of logging ‘dropped log entries’ information after the content is consumed by the management service, but no new log entry appears (which also triggers the logging of ‘dropped entries’ also).

Note The System Time property must be provided by the management service before enabling the logs for the first time. Otherwise, the firmware raises an error because it cannot translate log event timestamps in to the host CPU clock domain.

Note Log FIFO content is reset when logs are enabled by the management service, so the RP is expected to be 0. However, the management service should not assume that value, but read the RP from FW Registers instead.

LogStateInfo Structure

Syntax
struct LogStateInfo
{
    uint32_t  aging_timer_period;
    uint32_t  fifo_full_timer_period;

    uint32_t  core_mask;
    LogState  logs_core[];
};
Members

aging_timer_period

Specifies how frequently FW sends Log Buffer Status notification for new entries when the usual notification sending criteria are not met (the buffer is half full).

fifo_full_timer_period

Specifies the latency of logging ‘dropped log entries’ information after the content is consumed by the management service, but no new log entry appears (which would trigger logging ‘dropped entries’ as well).

core_mask

Indicates which cores are targeted by the message. Bit[i] set to 1 means that configuration for i-th core, specified in logs_core[i] is valid and should be processed.

logs_core[]

Logging state for each core. i-th entry is processed by FW only if bit[i] of core_mask is set.

The size of the array is determined by the number of DSP cores available on the platform (equals DSP_CORES in Hardware Config). The array is expected to contain all entries, even if number of 1 in the core_mask is < DSP_CORES.

LogState Structure

Syntax
struct LogState
{
    uint32_t enable;
    uint32_t min_priority;
};
Members

enable

Indicates whether logging should be enabled (1) or disabled (0) on the core.

min_priority

Specifies logging priority for the core. One of the following:

  1. – Critical,
  2. – High,
  3. – Medium,
  4. – Low,
  5. – Verbose.

Firmware Config

The management service requests the value of this Base FW property to discover the firmware configuration. Configuration data is returned as a TLV list and contains the items described in the following table.

The management service may also set values of parameters that are marked as R/W in the table.

Note: FirmwareConfig is expected to be queried/set once at the time of firmware initialization. Properties that change more frequently (for example, the current number of module descriptors loaded, or the performance measurements state) are moved and become separate parameters.

Type Access Length (Bytes) Value

FW_VERSION (0)

FW Version assigned by the build system. The value is not related to the feature set, SW should display the value to identify the build.
R 8

struct FwVersion

{
uint16_t major;
uint16_t minor;
uint16_t hotfix;
uint16_t build;
};

MEMORY_RECLAIMED (1)

Indicates whether legacy DMA memory is managed by FW.
R/W 4 uint32_t memory_reclaimed;

SLOW_CLOCK_FREQ_HZ (2)

Frequency of oscillator clock.
R/W 4 uint32_t slow_clock_freq_hz;

FAST_CLOCK_FREQ_HZ (3)

Frequency of PLL clock.
R/W   uint32_t fast_clock_freq_hz;

DMA_BUFFER_CONFIG (4)

List of static and dynamic DMA buffer sizes.

SW may configure minimum and maximum size for each buffer.
R/W n * 8

DmaBufferConfig

{
uint32_t min_size_bytes;
uint32_t max_size_bytes;
} dma_buffer_config[];

TRACE_LOG_BYTES (8)

Size of trace log buffer per single core.
R 4 uint32_t trace_log_bytes;

MAX_PPL_COUNT (9)

Maximum number of pipelines that may be instantiated at the same time.
R 4 uint32_t max_ppl_count;

MAX_ASTATE_COUNT (10)

Maximum number of A-state table entries that may be configured by the management service. The management service may also use this value to estimate the size of data retrieved as ASTATE_TABLE property.
R 4 uint32_t max_astate_count;

MAX_MODULE_PIN_COUNT (11)

Maximum number of input or output pins supported by a module.
R 4 uint32_t max_module_pin_count;

MODULES_COUNT (12)

Current total number of module entries loaded into the DSP.
R 4 uint32_t modules_count;

MAX_MOD_INST_COUNT (13)

Maximum number of tasks supported by a single pipeline.
R 4 uint32_t max_mod_inst_count;

MAX_LL_TASKS_PER_PRI_COUNT (14)

Maximum number of LL tasks that may be allocated with the same priority (specified by a priority of the parent pipeline).
R 4 uint32_t max_ll_tasks_per_pri_count;

LL_PRI_COUNT (15)

Number of LL priorities.
R 4 uint32_t ll_pri_count;

MAX_DP_TASKS_COUNT (16)

Maximum number of DP tasks that may be allocated on a single core.
R 4 uint32_t max_dp_tasks_count;

MAX_LIBS_COUNT (17)

Maximum number of libraries that can be loaded into the ADSP memory (Base FW excluded).
R 4 uint32_t max_libs_count;

SCHEDULER_CONFIG (18)

Configuration of system tick source and period. See details below.
R/W Var struct SchedulerConfig sched_cfg;

XTAL_FREQ_HZ (19)

Frequency of XTAL clock.
R/W 4 uint32_t xtal_freq_hz;
CLOCKS_CONFIG R/W    

SchedulerConfig Structure

Syntax
struct SchedulerConfig
{
    uint32_t  sys_tick_multiplier;
    uint32_t  sys_tick_divider;
    uint32_t  sys_tick_source;
    uint32_t  sys_tick_cfg_length;
    uint32_t  sys_tick_cfg[];
};
Members

sys_tick_multiplier

Multiplier to base 1 ms period.

sys_tick_divider

Divider to base 1 ms period.

sys_tick_source

Source of system tick event, one of:

  1. – Low power timer interrupt,
  2. – DMA gateway interrupt.

sys_tick_cfg_length

Specifies length (in DWORDs) of optional system tick source configuration provided in sys_tick_cfg[] array.

sys_tick_cfg

Optional configuration for system tick source.

Remarks

Setting system tick source to Low Power Timer interrupt (1):

  • No configuration is expected, i.e. sys_tick_length = 0 and sys_tick_cfg is not appended,
  • Period is computed as 1 ms * multiplier / divider.

Setting system tick source to DMA Gateway interrupt (2):

  • The gateway Node ID must be provided in the configuration, i.e. sys_tick_length = 1 and sys_tick_cfg[0] = gateway_node_id.
  • Period is determined by a size of single DMA buffer that is computed as
    calc_1ms_data_size(attached_copier_audio_fmt) * multiplier / divider.

Hardware Config

The management service requests the value of this Base FW property to discover the underlying hardware configuration. The configuration data is returned as a TLV list and contains the items described in the following table.

Table 57. Hardware Config

Type Length (Bytes) Value

CAVS_VERSION (0)

Version of cAVS implemented by FW (from ROMInfo).

4

enum CavsVersion

{
CAVS_VER_1_5 = 0x10005,
CAVS_VER_1_8 = 0x10008
} cavs_version;

DSP_CORES (1)

Number of cores.
4 uint32_t dsp_cores;

MEM_PAGE_BYTES (2)

Size of a single memory page.
4 uint32_t mem_page_bytes;

TOTAL_PHYS_MEM_PAGES (3)

Total number of physical pages available for allocation.
4 uint32_t total_phys_mem_pages;

I2S_CAPS (4)

SSP capabilities.

Number of items in controller_base_addr array is specified by controller_count.

Note: Lower 16 bits of I2sVersion may be used in future to indicate implementation revision if necessary.
var

enum I2sVersion

{
I2S_VER_15_SKYLAKE   = 0x00000,
I2S_VER_15_BROXTON   = 0x10000,
I2S_VER_15_BROXTON_P = 0x20000
}

struct I2sCapabilities

{
I2sVersion version;
uint32_t controller_count;
uint32_t controller_base_addr[];
} i2s_caps;

{tbd}

GPDMA_CAPS (5)

GPDMA capabilities.

# of LP controllers

# channels on each LP controller; actual size of the array is specified by lp_ctrl_count.
 

# of HP controllers
 

# channels on each HP controller; actual size of the array is specified by hp_ctrl_count.

8 + lp_ctrl_count*4 + hp_ctrl_count*4

struct GpdmaCapabilities

{
uint32_t lp_ctrl_count;
uint32_t lp_ch_count[];
uint32_t hp_ctrl_count;
uint32_t hp_ch_count[];
} gpdma_caps;

GATEWAY_COUNT (6)

Total number of DMA gateways of all types.
4 uint32_t gateway_count;

HP_EBB_COUNT (7)

Number of HP SRAM memory banks manageable by DSP.

4 uint32_t hb_ebb_count;

LP_EBB_COUNT (8)

Number of LP SRAM memory banks manageable by DSP.

4 uint32_t lp_ebb_count;

EBB_SIZE_BYTES (9)

Size of a single memory bank (EBB) in bytes.
4 uint32_t ebb_size_bytes;

Modules Info

The management service requests the value of this Base FW property to retrieve a list of the module entries loaded into the firmware memory space (as part of either the image manifest or library manifest).

The response may be too large to fit into a single message. The management service must be prepared to handle multiple fragments.

ModulesInfo Structure

Syntax
struct ModulesInfo
{
    uint32_t    module_count;
    ModuleEntry module_info[];
};
Members

module_count

Specifies number of items in module_info array.

This value does not exceed MODULES_COUNT member of Base FW’s FIRMWARE_CONFIG parameter.

module_info

Array of module entries from the FW Manifest.

ModuleEntry Structure

Syntax
struct ModuleEntry
{
    uint16_t    module_id;
    uint16_t    state_flags;
    uint8_t     name[8];
    uint32_t    uuid[4];
    ModuleType  type;
    uint8_t     hash[32];
    uint32_t    entry_point;
    uint16_t    cfg_offset;
    uint16_t    cfg_count;
    uint16_t    affinity_mask;
    uint16_t    instance_max_count;
    uint16_t    instance_bss_size;
    SegmentDesc segments[3];
};
Members

module_id

Unique identifier of the module.

state_flags

Bit[0] indicates whether module is loaded (1) into ADSP memory or unloaded (0).

Other bits are reserved.

name

Name of the module.

uuid

Unique identifier.

type

Type of the module. See ModuleType.

hash

SHA-256 hash of the module content.

entry_point

Address of the module’s entry point.

cfg_offset

Offset to the first configuration entry in the configuration block included by the FW image manifest.

cfg_count

Number of configuration entries in the configuration block included by the FW image manifest.

affinity_mask

Bit mask that indicates which cores are allowed to execute the module.

instance_max_count

Maximum number of module instances.

instance_bss_size

Maximum size (in pages) of .bss allocated for a single module instance.

segments

Array of module segments (text, rodata, bss) descriptors. See also SegmentDesc.

ModuleType Union

Syntax
union ModuleType
{
    uint32_t     load_type  :4;
    uint32_t     auto_start :1;
    uint32_t     _rsvd      :27;
};
Members

load_type

Indicates whether the module is built in (0) or loadable (1).

auto_start

Indicates whether instances of the module are created on the management service’s demand (0) or single instance is created automatically by FW once module is available in FW memory.

SegmentDesc Structure
Syntax
union SegmentFlags
{
    uint32_t    contents : 1;
    uint32_t    alloc    : 1;
    uint32_t    load     : 1;
    uint32_t    readonly : 1;
    uint32_t    code     : 1;
    uint32_t    data     : 1;
    uint32_t    _rsvd0   : 2;

    uint32_t    type     : 4;  // 0 – text, 1 – rodata, 2 - bss
    uint32_t    _rsvd1   : 4;

    uint32_t    length   : 16; // segment length in pages
} SegmentFlags;

struct SegmentDesc
{
    SegmentFlags flags;
    uint32_t     v_base_addr;
    uint32_t     file_offset;
};
Members

flags

Segment flags

v_base_addr

Virtual base address of the segment.

file_offset

Offset in the FW binary file that segment content starts at.

Pipeline List Info

The management service requests the value of this Base FW property to retrieve a list of pipeline IDs. Once the list is received, the management service can retrieve the properties of each pipeline by querying Pipeline Info and specifying IDs from the list.

PipelineListInfo Structure

Syntax
struct PipelineListInfo
{
    uint32_t  ppl_count;
    uint32_t  ppl_id[];
};
Members

ppl_count

Specifies number of items in ppl_id array.

This value does not exceed MAX_PPL_COUNT member of Base FW’s FIRMWARE_CONFIG parameter.

ppl_info

Array of pipelines’ properties.

Pipeline Properties

The management service requests the value of this Base FW property to retrieve the properties of a pipeline. The full parameter ID, wrapped by APPLICATION_PARAM into the request payload, is of ExtendedParameterId type, where parameter_type is set to PIPELINE_PROPS and parameter_instance is set to the target pipeline ID.

The properties of a single pipeline are expected to fit into a single IPC response as there is room for ~1000 task and modules instance IDs.

PplProps Structure
Syntax
struct PplProps
{
    uint32_t         id;
    uint32_t         priority;
    uint32_t         state;
    uint32_t         total_memory_bytes;
    uint32_t         used_memory_bytes;
    uint32_t         context_pages;
    ModInstListInfo  module_instances;
    TaskListInfo     ll_tasks;
    TaskListInfo     dp_tasks;
};
Members

id

ID of pipeline assigned by the management service.

priority

Priority of pipeline’s LL tasks executed by the LL Scheduler.

state

Current pipeline state.

total_memory_bytes

Total size of memory buffer assigned to the pipeline.

used_memory_bytes

Size of memory allocated by the pipeline from assigned memory buffer.

context_pages

Number of memory pages occupied by the pipeline context. Sum of total_memory_bytes/PAGE_SIZE and size of child module instance contexts.

module_instances

Array of IDs of child module instances created by the pipeline. Instances are listed in order of stream processing within the pipeline.

ll_tasks

List of registered LL tasks.

dp_tasks

List of registered DP tasks.

TaskListInfo Structure
Syntax
struct TaskListInfo
{
    uint32_t        task_id_count;
    uint32_t        task_id[];
};
Members

task_id_count

Specifies number of items in task_id array.

Sum of values for all pipelines does not exceed

MAX_LL_TASKS_PER_PRI_COUNT*LL_PRI_COUNT + #Cores*MAX_DP_TASKS_COUNT (all are members of Base FW’s FIRMWARE_CONFIG parameter).

#Cores reported as DSP_CORES member of HARDWARE_CONFIG parameter.

task_id

Array of IDs of tasks.

Remarks

Task IDs may be used to refer to TaskProps retrieved along with SchedulerProps.

ModInstListInfo Structure
Syntax
struct ModInstListInfo
{
    uint32_t  module_instance_count;
    uint32_t  module_instance_id[];
};
Members

module_instance_count

Specifies number of items in module_instance_id array.

Sum of values for all pipelines does not exceed value of MAX_MOD_INST_COUNT of Base FW’s FIRMWARE_CONFIG parameter.

module_instance_id

Array of IDs of modules instances.

Schedulers Info

The management service requests the value of this Base FW property to retrieve a list of task schedulers and tasks created inside the firmware that are executed on a core. The full parameter ID, wrapped by APPLICATION_PARAM into the request payload, is of ExtendedParameterId type where parameter_type is set to SCHEDULERS_INFO and parameter_instance is set to the target core ID.

SchedulersInfo Structure
Syntax
struct SchedulersInfo
{
    uint32_t        scheduler_count;
    SchedulerProps  scheduler_info[];
};
Members

scheduler_count

Specifies number of items in scheduler_info array, expected to be set to 1+#cores by the FW.

scheduler_info

Array of scheduler properties.

SchedulerProps Structure
Syntax
enum ProcessingDomain
{
    PD_LOW_LATENCY     = 0,
    PD_DATA_PROCESSING = 1,
};

struct SchedulerProps
{
    uint32_t   processing_domain;
    uint32_t   core_id;
    uint32_t   task_count;
    TaskProps  task_info[];
};
Members

processing_domain

Processing domain (see enum ProcessingDomain).

core_id

ID of core that scheduler is running on.

task_count

Specifies number of items in task_info array.

task_info

Array of properties of assigned and scheduled by the scheduler.

TaskProps Structure
Syntax
struct TaskProps
{
    uint32_t  task_id;
    uint32_t  task_memory_bytes;
    uint32_t  task_stack_bytes;
    uint32_t  module_instance_count;
    uint32_t  module_instance_id[];
};
Members

task_id

Unique ID of task.

task_memory_bytes

Size of the task in memory (just a task object, stack size not included).

task_stack_bytes

Size of the task stack in memory.

module_instance_count

Specifies number of items in module_instance_id array.

module_instance_id

Array of IDs of module instances running inside the task.

Gateways Info

The management service requests the value of this Base FW property to retrieve a list of available DMA gateways.

GatewaysInfo Structure
Syntax
struct GatewaysInfo
{
    uint32_t      gateway_count;
    GatewayProps  gateways[];
};
Members

gateway_count

Specifies number of items in gateways array.

gateways

Array of gateways’ properties.

GatewayProps Structure
Syntax
struct GatewayProps
{
    ConnectorNodeId    id;
    GatewayAttributes  attribs;
};
Members

id

Gateway ID (refer to ConnectorNodeId).

gateways

Gateway attributes (refer to GatewayAttributes).

Memory State Info

The management service requests the value of this Base FW property to retrieve information about the current DSP memory state.

The configuration data is returned as a TLV list and contains the items described in the following table.

Table 58. Memory State Info

Type Length (Bytes) Value

LPSRAM_STATE (0)

 

free_phys_mem_pages – Number of free memory pages.

ebb_state_dword_count – Number of items in ebb_state array.

Precise number of EBBs is reported by respective EBB_COUNT in HwConfig. Here this number is rounded up to 32 (# bits in DWORD) boundary.

ebb_state – State of EBBs (memory banks). bit[i] indicates whether i-th EBB is in use (1) or powered down (0).

page_alloc_count – Number of items in page_alloc array.

page_alloc – State of memory page allocation. bit[i] indicates whether i-th page is allocated.
var

struct SramStateInfo

{
uint32_t free_phys_mem_pages;
uint32_t ebb_state_dword_count;
uint32_t ebb_state[];
uint32_t page_alloc_count;
uint16_t page_alloc[];
} lpsram_state;

HPSRAM_STATE (1) var struct SramStateInfo hpsram_state;
Power State Info

The management service requests the value of this Base FW property to retrieve information about the current DSP power state.

The configuration data is returned as a TLV list and contains the items described in the following table.

Table 59. Power State Info

Type Length (Bytes) Value

ACTIVE_CORES_MASK (0)

Indicates state of DSP cores.

bit[i] – indicates whether i-th core is active (1) or powered down (0).
4 uint32_t active_cores_mask;

CORE_KCPS (1)

Current core utilization (in kilo cycles per second).

Actual size of the array equals DSP_CORES value retrieved as part of Hardware Config property.
var uint32_t core_kcps[];
Libraries Info

The management service requests the value of this Base FW property to retrieve information about the libraries loaded into the ADSP memory.

LibrariesInfo Structure
Syntax
struct LibrariesInfo
{
    uint32_t      library _count;
    LibraryProps  libraries[];
};
Members

library_count

Specifies number of items in libraries array.

libraries

Array of libraries’ properties.

LibraryProps Structure
Syntax
struct LibraryProps
{
    uint32_t  id;
    uint8_t   name[8];
    uint16_t  major_version;
    uint16_t  minor_version;
    uint16_t  hotfix_version;
    uint16_t  build_version;
    uint32_t  num_module_entries;
};
Members

id

Library runtime identifier, depends on order of loading. Base FW is always reported with ID 0.

name

Name of the library.

major_version, minor_version, hotfix_version, and build_version

Version of the library.

num_module_entries

Number of modules contained by the library.

Performance Measurements State

The management service may set the value of this Base FW property to control the state of performance measurements process in the DSP FW.

This state applies to MCPS monitoring only. Memory allocation state (see Memory State Info) is always available.

The state machine and actions performed by firmware on a state transition are illustrated in the following figure.


Figure 24. State of Performance Measurements State

PerfMeasurementsState Structure

Syntax
struct PerfMeasurementsState
{
    uint32_t  state;
};
Members

enabled

Indicates whether performance is measured,

0 – Disabled (this is the system default),

1 – Stopped,

2 – Started,

3 – Paused.

Global Performance Data

The management service requests the value of this Base FW property to retrieve performance data captured on the DSP. The firmware sends a list of items reported by firmware components. KCPS are sampled each DSP system tick (1ms in D0) for low latency and infrastructure components, or each processed frame otherwise. The KCPS are used to compute reported peak and average values by firmware.

Data items reported for resource_id = {module_id = 0, instance_id = <core_id>} contain the total KCPS spent on each active core.

This parameter reports only KCPS, while the memory state is reported by the Memory State Info parameter.

GlobalPerfData Structure
Syntax
struct GlobalPerfData
{
    uint32_t      perf_item_count;
    PerfDataItem  perf_items[];
};
Members

perf_item_count

Specifies number of items in perf_items array.

perf_items

Array of global performance measurements.

PerfDataItem Structure
Syntax
struct PerfDataItem
{
    uint32_t  resource_id;

    uint32_t  power_mode : 1;
    uint32_t  rsvd       : 30;
    uint32_t  is_removed : 1;

    uint32_t  peak_kcps;
    uint32_t  avg_kcps;
};
Members

resource_id

ID of the FW component.

{module_id = 0 | module_instance = core_id } reports total load measured on a core identified by core_id.

pewer_mode

0 – D0,

1 – D0i3.

is_removed

Indicates whether the component still exists (0) or has been already deleted (1).

peak_kcps

Peak KCPS captured.

avg_kcps

Average KCPS measured.

L2 Cache Info

The management service requests the value of this Base FW property to retrieve information about the current state of L2 Cache. It is available on platforms where the L2 cache is in use, otherwise ADSP_IPC_UNAVAILABLE is returned.

L2CacheInfo Structure
Syntax
struct L2CacheInfo
{
    uint32_t                 lock_status;
    uint32_t                 memory_descriptors_count;
    L2CacheMemoryDescriptor  memory_descriptor[];
};
Members

lock_status

Lock status code.

0 – current FW may be successfully locked into L2 cache

memory_descriptors_count

Specifies number of items in memory_descriptor array.

memory_descriptor

Descriptors of memory areas to be locked.

L2CacheMemoryDescriptor Structure
Syntax
const uint16_t MRT_TYPE_CODE    = 0;
const uint16_t MRT_TYPE_RO_DATA = 1;
const uint16_t MRT_TYPE_RW_DATA = 2;

const uint16_t MRT_LOCK_PREFERENCE_L1     = 0;
const uint16_t MRT_LOCK_PREFERENCE_L2     = 1;
const uint16_t MRT_LOCK_PREFERENCE_L2_OPT = 2;

struct MemoryRegionAttribute
{
    uint32_t  type            : 4;
    uint32_t  lock_preference : 4;
    uint32_t  rsvd            : 24;
};

struct L2CacheMemoryDescriptor
{
    uint32_t               va;
    uint32_t               size_bytes;
    MemoryRegionAttribute  attribute;
};
Members

va

Virtual base address of memory area.

size_bytes

Size of memory area in bytes.

attribute

Attributes of memory area.

System Time

The management service sets this property to pass down information about the current system time. The firmware uses it to translate event timestamps (for example, logs, or probe packets) to the system time (current host time) domain.

Note for management service implementation:

  • The value of system time is expressed in US
  • Time is in UTC
  • Epoch is 1601-01-01T00:00:00Z
SystemTime Structure
Syntax
struct SystemTime
{
    uint32_t  val_l;
    uint32_t  val_u;
};
Members

val_l

Lower DWORD of current system time value.

val_u

Upper DWORD of current system time value.

Mix In

UUID: 39656EB2-3B71-4049-8D3F-F92CD5C43C09

Initial Configuration

Mix In accepts the basic module configuration, BaseModuleCfg, without extensions.

Audio Data Format

Table 60. Mix In Audio Data Format

Interface Sampling Rate Number of Channels Sample Size Container Size
Input [0] * 1+ 32-bit 32-bit
Output [0] Same as input 1+ 32-bit 32-bit
Frame Size

Mix In works on a 1ms frame.

Memory Requirements

Table 61. Mix In Memory Requirements

Component Size (bytes) Remarks
Object 168  
Stream latency data 56 Only if MixIn’s parent pipeline is attached to a host output gateway.

Runtime Parameters

Table 62. Mix In Runtime Parameters

Parameter ID Dir Type
UNDERRUN_NOTIF_PERIOD 0 R/W Small
MIXER_MODE 1 W Large
Underrun Notification Period

The management service sends this configuration parameter to set the minimal notification period. The default value is set to 10ms.

Note The End-of-Stream variant of underrun notification does not honor the minimal notification period. It is always sent instantly.

Mixer Mode

This configuration parameter is sent to remap input channels into another channel slot, as defined per each individual connected Mix Out’s channel map. The Mix Out channel map may also define a different number of channels than Mix In’s input. Therefore, Mix In needs to know not only the target positions of its input channels, but also the output channel count, so that it can iterate to the next output sample group correctly.

MixerModeConfig Structure
Syntax
struct MixerModeConfig
{
    uint32_t             mixer_mode_config_count;
    MixerModeSinkConfig  mixer_mode_sink_configs[];
};
Members

mixer_mode_config_count

Number of items in mixer_mode_sink_configs.

mixer_mode_sink_configs

Array of channel map, one per each connected Mix Out’s sink.

MixerModeSinkConfig Structure
Syntax
struct MixerModeSinkConfig
{
    uint32_t  output_queue_id;
    uint32_t  mixer_mode;
    uint32_t  output_channel_count;
    uint32_t  output_channel_map;
};
Members

output_queue_id

Index of the output queue to be configured.

mixer_mode

Mode of channel remapping.

0 – Normal mode (the default identity mode),

1 – Channel remapping mode.

output_channel_count

Number of channels configured at Mix Out connected to this output queue. This item is valid only if mixer_mode is set to 1.

output_channel_map

Map of channels at Mix Out connected to this output queue.

This item is valid only if mixer_mode is set to 1. For detailed definition of channel map used for remapping, refer to the CopierModuleCfg structure documentation.

Mix Out

UUID: 3C56505A-24D7-418F-BDDC-C1F5A3AC2AE0

Initial Configuration

Mix Out accepts the basic module configuration, BaseModuleCfg, without extensions.

Audio Data Format

Table 63. MixOut Audio Data Format

Interface Sampling Rate Number of Channels Sample Size Container Size
Input [n] * 1+ 32-bit 32-bit
Output [0] Same as input 1+ 32-bit 32-bit
Frame Size

Mix Out works on a 1 ms frame.

Memory Requirements

Table 64. Mix Out Memory Requirements

Component Size (bytes) Remarks
Object 392  
Common sink buffer OBS Equals to OBS parameter specified as a part of the module configuration.

Runtime Parameters

None.

Copier

UUID: 9BA00C83-CA12-4A83-943C-1FA2E82F9DDA

Copier may be instantiated and bound in one of following configurations:

  • Input DMA Gateway → Copier → another module instance …,
  • … another module instance → Copier → Output DMA Gateway,
  • … another module instance → Copier → another module instance …

In the first two configurations, the initial configuration must include Gateway Configuration data and the valid Node ID of the gateway to be connected on either Copier’s end.

The initial configuration data allows you to set up the audio format of the main Copier’s pins (input pin #0 and output pin #0), and to prepare a PCM conversion routine (if required). However, Copier supports two output pins. Before an extra output pin is used in a binding operation, the management service must first send the runtime parameter SET_SINK_FORMAT to set up a PCM conversion routine, if one is required.

Initial Configuration

Copier requires CopierModuleCfg, a basic module configuration with extensions.

Audio Data Format

Table 65. Copier Audio Data Format

Interface Sampling Rate Number of Channels Sample Size Container Size
Input [0] * 1+

32-bit
24 bit
16 bit
8 bit

32-bit
24 bit
16 bit
8 bit

Output [n] Same as input 1+

32-bit
24 bit
16 bit
8 bit

32-bit
24 bit
16 bit
8 bit

Frame Size

Copier works on a 1ms frame. The exact number of samples depends on the sampling rate.

Data Structures
CopierModuleCfg Structure
Syntax
struct CopierModuleCfg : BaseModuleCfg
{
    AudioDataFormatIpc out_fmt;
    uint32_t           copier_feature_mask;
    CopierGatewayCfg   gtw_cfg;
};
Members

out_fmt

Audio format of the output pin #0.

copier_feature_mask

Additionally defines copier behavior

  • Bit [0] – Fast Mode:
    1 – copies as many data as possible with regards to input/output queues state
    0 – copying is limited to 1ms of data.

gtw_cfg

Gateway configuration [optional] specified by the management service if copier instance is to be connected to a DMA gateway on either end.

Remarks

When Copier is attached to an input gateway, the input channel_mask is ignored, while the output channel mask is used to remap channels coming from the input DMA to the channels of stream outputted by the Copier. Each half-byte of the channel map is an index of the input DMA stream channel that should be copied to the position determined by this half-byte index.

For example:

out_fmt.channel_map = 0xFFFFFF00 means that channel[0] from the input stream should be copied to the channel[0] of the output stream and also duplicated as a channel[1] of the output stream.

out_fmt.channel_map = 0xFFFFFF10 means exact copy of stereo stream,

out_fmt.channel_map = 0xFFFFFF01 means that stereo stream is copied with swapped channels.

When Copier is attached to an output gateway, the input channel_mask is interpreted as above, while out_fmt.channel_mask is ignored.

CopierGatewayCfg Structure

Configuration of a gateway that the instance of the Copier module is attached to.

The structure of the configuration data is presented in the following figure.


Figure 25. DMA Gateway Configuration Structure

The DMA Gateway configuration begins with CopierGatewayCfg, specified by the management service, where the node_id structure depends on the DMA type.

It is followed by the DMA-specific configuration that is copied from the ACPI tables and is transparent to the management service. config_length is set to the size of the configuration BLOB, and the content is appended to the CopierGatewayCfg. This part of the configuration BLOB may begin with the GatewayAttributes structure (optional), followed by an optional configuration BLOB that is specific for the DMA gateway type.

Another optional DMA-specific configuration (aux_config in the figure) may also be present. It is a structure that is known to the management service and is specified by the management service. For example, I2sDmaControlData or other i2s parameters are controlled directly by the management service in the case of an i2s DMA gateway.

For detailed documentation on DMA gateway configurations, see Section “Initial Gateway Configuration”.

Syntax
struct CopierGatewayCfg
{
    uint32_t node_id;
    uint32_t dma_buffer_size;
    uint32_t config_length;
    uint32_t config_data[];
};
Members

node_id

ID of the gateway connected to either input pin #0 or output pin #0, depending on the gateway’s direction. Set to INVALID_NODE_ID (-1) if no gateway is being connected. If no gateway is connected, the rest of the structure is ignored.

See also ConnectorNodeId structure.

dma_buffer_size

Preferred size of the gateway buffer (in bytes).

config_length

Size of the config_data (in DWORDS), may be 0 if the type of gateway used does not require configuration data.

config_data

Gateway configuration BLOB. See next sections for details. The actual size of the array is specified in the config_length field.

Remarks

FW attempts to allocate DMA buffer size according to dma_buffer_size value, however it may fall back to IBS (or OBS) * 2 size in case there is no memory available for deeper buffering.

ConnectorNodeId Structure

Base structure of a gateway address. Virtual index value is expected to be encoded in a gateway-specific way, depending on the actual type of gateway.

Syntax
struct ConnectorNodeId
{
    union
    {
        uint32_t dw;
        struct
        {
            uint32_t v_index    : 8;
            uint32_t dma_type   : 5;
            uint32_t _rsvd      : 19;
        } f;
    } val;
};    
Members

dma_type

Type of the gateway. One of:

kDmicLinkInputClass = 11,

kI2sLinkOutputClass = 12,

kI2sLinkInputClass = 13,

kIPCOutputClass = 18,

kIPCInputClass = 19,

v_index

Index of the virtual DMA at the gateway.

Initial Gateway Configuration

Some gateway types require a configuration BLOB with additional settings, while others do not.

The gateway configuration BLOB may be preceded by the GatewayAttributes structure, which is defined here.

GatewayAttributes Structure
Syntax
struct GatewayAttributes
{
    uint32_t lp_buffer_alloc : 1;
    uint32_t _rsvd           : 31;
};
Members

lp_buffer_alloc

Indicates whether FW should attempt (if set to 1) to allocate the gateway buffer in Low-Power memory area.

i2s Gateway Configuration

The i2s configuration BLOB, coming from BIOS, may be followed by more control parameters that are specified by the management service as a TLV array. The array may contain the following items (both are optional):

  • I2sDmaControlData structure
  • M/N divider configuration


Figure 26. i2s Gateway Configuration Structure

I2sDmaNodeId Structure

i2s gateway address.

Syntax
struct I2sDmaNodeId : ConnectorNodeId
{
    union VirtualIndex
    {
        uint8_t b;
        struct
        {
            uint8_t time_slot_group_index   : 4;
            uint8_t i2s_instance            : 4;
        } f;
    };
};
Members

time_slot_group_index

Index of the time slot group within the i2s instance.

i2s_instance

Index of the i2s instance

Remarks

TDM time slots are assigned statically to streams by definition coming from ACPI. A single stream transmits data through time slots of a single time slot group.

For example, eight TDM time slots may be grouped by the following definition from ACPI:

tsd[0] = 0xFFFFFF43, tsd[1] = 0xFFFFFF01, …

Stream #0 specifies time_slot_group_index = 1, Stream #1 uses time_slot_group_index = 0 that would mean that 1st TDM slot is mapped to S0 Ch0, 0th TDM slot is mapped to S0 Ch1, 3rd TDM slot is mapped to S1 Ch0, and 4th TDM slot is mapped to S1 Ch1.


Figure 27. TDM Time Slots

i2s Gateway Configuration BLOB

Note For i2s Gateway BLOB details, contact your Intel representative.

The configuration BLOB that is passed to the Copier when attached to an i2s gateway consists of i2s register settings and a total of 8+12 DWORDs: eight per TDM time slot group mapping, 10 per i2s instance, and two for global MCLK configuration. The DWORDs are in the following order.


Figure 28. I2S Configuration

Syntax

BLOB

struct I2sConfigurationBlob_ver_1_5
{
   // header part
   uint32_t ver_min : 8; // set to 0x05
   uint32_t ver_maj : 8; // set to 0x01
   uint32_t rsvd0   : 8; // set to 0x00
   uint32_t sig     : 8; // set to 0xEE

   uint32_t size_bytes;

   uint32_t tdm_ts_group[8];
   uint32_t ssc0;
   uint32_t ssc1;
   uint32_t sscto;
   uint32_t sspsp;
   uint32_t sstsa;
   uint32_t ssrsa;
   uint32_t ssc2;
   uint32_t sspsp2;
   uint32_t ssc3;
   uint32_t ssioc;

   uint32_t mdivc;
   uint32_t mdivr_count;
   uint32_t mdivr[];
};
Members

tdm_ts_group

TDM time slot mappings.

There may be up to 8 groups (number of TDM slots) defined.

ssc0, ssc1, ssto, sspsp, sstsa, ssrsa, ssc2, sspsp2, ssc3, ssioc

i2s HW registers. Refer to the i2s HW specification for details.

mdivc

MDIVC – Master Clock Divider Control Register.

mdivr_count

Number of items in mdivr array.

mdivr

Array of MDIVxR – Master Clock Divider x Ratio Register

Remarks

The master clock is common for all i2s interfaces. Therefore, all i2s instances should be configured using the same MCLK settings. If MCLK is already running, FW checks the MCLK configuration against the operating configuration. The setting is applied once any i2s gateway exists. If no i2s instance is used, the MCLK is disabled.

Additional i2s Control Parameters
I2sMnDivData Structure

I2sMnDivData structure may be a part of TLV-encoded array that follows DmaControl or CopierGatewayCfg structure in the DMA Control configuration parameter payload when node_id specifies an i2s gateway.

The ID of the TLV is set to 0.

Syntax
struct Is2MnDivData 
{
    uint32_t m_div_val;
    uint32_t n_div_val;
};
Members

m_div_val

Value of M.

n_div_val

Value of N.

I2sDmaControlData Structure

I2sDmaControlData structure may be a part of TLV-encoded array similarly to I2sMnDivData.

The ID of the TLV is set to 1.

Syntax
struct I2sDmaControlData
{	
    uint32_t clock_warm_up    : 16;
    uint32_t mclk             : 1;
    uint32_t warm_up_ovr      : 1;
    uint32_t rsvd0            : 14;

    uint32_t clock_stop_delay : 16;
    uint32_t keep_running     : 1;
    uint32_t clock_stop_ovr   : 1;
    uint32_t rsvd1            : 14;
};
Members

clock_warm_up

Delay in msec between enabling interface (moment when Copier instance is being attached to the interface) and actual interface start. Value of 0 means no delay.

mclk

Specifies if parameters target MCLK (1) or SCLK (0).

warm_up_ovr

Value of 1 means that clock should be started immediately even if no Copier instance is currently attached to the interface.

clock_stop_delay

Delay in msec between stopping the interface (moment when Copier instance is being detached from the interface) and interface clock stop. Value of 0 means no delay.

keep_running

Value of 1 means that clock should be kept running (infinite stop delay) after Copier instance detaches from the interface.

clock_stop_ovr

Value of 1 means that clock should be stopped immediately.

DMIC Gateway Configuration


Figure 29. DMIC Gateway Configuration

DmicDmaNodeId Structure

DMIC gateway address.

Syntax
struct DmicDmaNodeId : ConnectorNodeId
{
    union VirtualIndex
    {
        uint8_t b;
        struct
        {
            uint8_t dmic_interface_queue_id :3;
            uint8_t time_slot_group_index   :2;
            uint8_t instance                :3;
        } f;
    };
};
Members

dmic_interface_queue_id

Index of the input queue within the DMIC instance specified by instance.

time_slot_group_index

Index of the time slot group within the queue specified by the queue ID.

instance

Index of DMIC instance.

Remarks

See the I2sDmaNodeId structure documentation for more details about time slot group indexing.

DMIC Gateway Configuration BLOB

Note For DMIC Gateway BLOB details, contact your Intel representative.

The configuration BLOB that is passed to the Copier when attached to a DMIC gateway has the following structure.

DmicConfigurationBlob Structure

Syntax
struct DmicConfigurationBlob
{
    uint32_t    ts_group[4];
    GlobalCfg   global_cfg;
    uint32_t    channel_ctrl_mask;
    ChannelCfg  channel_cfg[];
    uint32_t    pdm_ctrl_mask;
    PdmCtrlCfg  pdm_ctrl_cfg[];
};
Members

ts_group

Time slot mappings.

global_cfg

Global configuration settings (see below).

channel_ctrl_mask

Specifies PDM channels to be programmed using data from channel_cfg array.

bit [0] = 1 means that configuration for PDM channel 0 is provided.

bit [1] = 1 means that configuration for PDM channel 1 is provided.

channel_cfg

PDM channel configuration settings (see below).

pdm_ctrl_mask

Specifies PDM controllers to be programmed using data from pdm_ctrl_cfg array.

bit [0] = 1 means that configuration for PDM controller 0 is provided.

bit [1] = 1 means that configuration for PDM controller 1 is provided.

pdm_ctrl_cfg

PDM controller configuration settings (see below).

GlobalCfg Structure
Syntax
struct GlobalCfg
{
    uint32_t clock_on_delay;
};
Members

clock_on_delay

Specifies delay in ms to unmute mics after clock is started.

Expected value is 1-3ms.

Typical value is 1ms.

ChannelCfg Structure
Syntax
struct ChannelCfg
{
    uint32_t out_control;
};
Members

out_control

OUTCONTROL

PdmCtrlCfg Structure
Syntax
struct PdmCtrlCfg
{
    uint32_t  cic_control;
    uint32_t  cic_config;
    uint32_t  rsvd0;
    uint32_t  mic_control;
    uint32_t  pdmsm;
    uint32_t  rsvd1[3];
    FirCfg    fir_config[2];
    uint32_t  fir_coeffs[n];
};
Members

cic_control

CIC_CONTROL

cic_config

CIC_CONFIG

rsvd0

Reserved field

mic_control

MIC_CONTROL

pdmsm

PDM SoundWire Map. This field is used on platforms with SoundWire, otherwise it is ignored.

rsvd1

Reserved field

fir_config

FIR configurations

fir_coeffs

Array of FIR coefficients, channel A first, then channel B.

n – Actual size of the array depends on the number of active taps of the FIR filter for channel A plus the number of active taps of the FIR filter for channel B (see FIR_CONFIG) and on the unpacked/packed form of values (see Remarks).

Remarks

Size of a single coefficient is 20-bit. Coefficients may be sent in either unpacked form where each value takes one DWORD (32-bits) or in packed form where the array begins with a single DWORD of 0xFFFFFFFF value to indicate packed form (unpacked coefficient has always most significant byte set to 0) followed by array of 24-bit values (in little endian form).

FirCfg Structure

Syntax
struct FirCfg
{
    uint32_t fir_control;
    uint32_t fir_config;
    uint32_t dc_offset_left;
    uint32_t dc_offset_right;
    uint32_t out_gain_left;
    uint32_t out_gain_right;
    uint32_t rsvd[2];
};
Members

fir_control

FIR_CONTROL

fir_config

FIR_CONFIG

dc_offset_left

DC_OFFSET_LEFT

dc_offset_right

DC_OFFSET_RIGHT

out_gain_left

OUT_GAIN_LEFT

out_gain_right

OUT_GAIN_RIGHT

rsvd

Reserved field

Note: If only one PDM controller configuration is passed, the other (missing) one is configured by the management service by clearing CIC_CONTROL.SOFT_RESET bit.

Note: The management service must ensure that all mics are disabled before starting to program PDM controllers.

Additional DMIC Control Parameters
DmicClockControlData Structure

DmicClockControlData structure may be a part of TLV-encoded array sent by the management service as a DMA Control configuration request.

The ID of the TLV is set to 0.

Syntax
struct DmicClockControlData
{	
    uint32_t pdm_ctrl_mask    : 32;

    uint32_t pdm_0_en_a       : 1;
    uint32_t pdm_0_en_b       : 1;
    uint32_t pdm_1_en_a       : 1;
    uint32_t pdm_1_en_b       : 1;

    uint32_t rsvd0            : 28;
};
Members

pdm_ctrl_mask

Specifies which pdm_<x>_en_a/b pairs are valid.

pdm_<x>_en_a/b

Specifies whether a/b clock of PDM <x> should be enabled.

Remarks

Each PDM that is addressed by pdm_ctrl_mask must be programmed by configuration BLOB previously provided by a Copier instance otherwise request is rejected.

IPC Gateway Configuration


Figure 30. IPC Gateway Configuration Structure

IPC Gateway Configuration BLOB

The configuration BLOB passed to the Copier when being attached to an IPC gateway.

Syntax
struct IpcGtwCfg
{
    uint32_t buffer_size;
    union
    {
        struct
        {
            uint32_t notif_high : 1;
            uint32_t notif_low : 1;
            uint32_t rsvd : 30;
        };
        uint32_t flags_raw;
    };
    uint32_t threshold_high;
    uint32_t threshold_low;
};
Members

buffer_size

Size of internal buffer maintained by an IPC gateway.

notify_high

Flag specifies if GATEWAY_HIGH_THRES IPC notification should be sent when threshold_high is reached.

notify_low

Flag specifies if GATEWAY_LOW_THRES IPC notification should be sent when threshold_low is reached.

threshold_high

Specifies amount of data in internal gateway buffer when GATEWAY_HIGH_THRES IPC is sent if notify_high is enabled.

threshold_low

Specifies amount of data in internal gateway buffer when GATEWAY_LOW_THRES IPC is sent if notify_low is enabled.

Memory Requirements

Table 66. Copier Memory Requirements

Component Size (bytes) Remarks
Object 224  
Copy of configuration size of CopierModuleCfg

Actual size of the configuration, including actual size of config_data.

Only if copier is connected to a gateway.
Copy of gateway state

HD/A Link Output: 20

HD/A Host Output: 24 + 4 * number of 4KB pages required for DMA buffer (if not LL buffer)
Only if copier is connected to a gateway and pipelines may be saved to host memory.
Virtual Channels Slot Map 12 Only if copier is connected to a gateway.

Runtime Parameters

Table 67. Copier Runtime Parameters

Parameter ID Dir Type
TIMESTAMP_INIT 1 W Large
SET_SINK_FORMAT 2 W Large
DATA_SEGMENT_ENABLED 3 R/W Large
LLP_READING 4 R Large
GET_DATA 5 R Large
SET_DATA 6 W Large
Timestamp Init

The management service sends this configuration parameter to trigger time stamping flow.

Once the timestamp is captured, Copier sends back a Timestamp Captured Notification.

Type Length (Bytes) Value

TIMESTAMP_INIT

tsctrl_reg – Contains low-level configuration for timestamp init, passed through directly into <ifc>_LOCAL_TS_Contol register of corresponding HW i/f within DSP Timestamping registers.
4

struct TimestampInitData

{
uint32_t tsctrl_reg;
};

Set Sink Format

The management service sends this configuration parameter to configure the audio format of the Copier’s output pin that is to be bound to another module instance. The management service resends the audio format of the input pin, as Copier might have been unbound from previous source and is to be bound to a new source. If Copier is still bound to a source, the audio format of the input pin must be the same as the current source.

Table 69. Set Sink Format

Type Length (Bytes) Value

SET_SINK_FORMAT

sink_id – Index of the output pin.

src_fmt – Audio format of the input pin.

sink_fmt – Audio format of the specified output pin.
52

struct SetSinkFormat

{
size_t sink_id;
AudioDataFormatIpc src_fmt;
AudioDataFormatIpc sink_fmt;
};

Data Segment Enabled

The management service sends this configuration parameter to an instance of a Copier that is attached to a Gateway, to enable or disable the sending of a Stream Data Segment Notification to the host.

The Node ID may be unspecified (set to INVALID_NODE_ID (-1)) if the Copier is attached to a single Gateway (which is currently the case, as Copier does not support gateway-to-gateway mode).

The notification is sent every segment that is transferred until it is canceled by the management service.

Table 70. Data Segment Enabled

Type Length (Bytes) Value

DATA_SEGMENT_ENABLED

node_id – Gateway node ID.

enabled – indicates whether notification should be enabled (1) or disabled (0).

data_seg_size – data segment size (in bytes).
12

struct DataSegmentEnabled

{
uint32_t node_id;
uint32_t enabled;
uint32_t data_seg_size;
};

LLP (Linear Link Position) Reading

The management service requests this property from a Copier associated with a DMA Gateway that does not support direct LLP reading from host CPU. In this situation, the DSP firmware must read LLP from hardware registers.

The current LLP value and the current Wallclock value are provided, to allow the management service to adjust the LLP with IPC response delay.

Table 71. LLP Reading

Type Length (Bytes) Value

LLP_READING

llpl_l – lower part of 64-bit LLP

llpl_u – upper part of 64-bit LLLP

local_tsc_l – lower part of 64-bit Wallclock

local_tsc_u – upper part of 64-bit Wallclock
16

struct LlpReading

{
uint32_t llp_l;
uint32_t llp_u;
uint32_t local_tsc_l;
uint32_t local_tsc_u;
};

Gateway Notification Period

See MixIn Underrun Notification Period.

Get Data

The management service sends this configuration parameter to obtain data from the IPC gateway connected with Copier.

Set Data

The management service sends this configuration parameter to upload data to the IPC gateway connected with Copier.

Peak Volume Control

UUID: 8A171323-94A3-4E1D-AFE9-FE5DBAA4C393

Initial Configuration

Peak Volume requires PeakVolumeModuleCfg, a basic module configuration with some extensions.

Audio Data Format

Table 72. PeakVol Audio Data Format

Interface Sampling Rate Number of Channels Sample Size Container Size
Input [0] 1 1..8

32-bit

16-bit*

32-bit

16-bit*
Output [0] Same as input 1+ Same as input Same as input

Note

  1. No volume control works in 16 bit / 16-bit mode, only peak metering is supported
Frame Size

PeakVol works on 1ms frame.

Data Structures
PeakVolumeModuleCfg Structure
Syntax
struct PeakVolumeModuleCfg : BaseModuleCfg
{
    PeakVolumeConfig config[1];
};
Members

config

Configuration, one item per input channel.

PeakVolumeConfig Structure
Syntax
struct PeakVolumeConfig
{
    uint32_t channel_id;
    uint32_t target_volume;
    uint32_t curve_type;
    uint64_t curve_duration;
};
Members

channel_id

Index of the input channel. ALL_CHANNELS (0xFFFFFFFF) value indicates all channels to be addressed.

target_volume

Target volume. Should be converted by the management service to linear value as target_volume=0x7FFFFFFF*10^(dbVal/1310720).

Note: -2147483648 (0x80000000 in hexadecimal, or LONG_MIN) is -Infinity decibels (attenuation) – should be specified as 0.

curve_type

One of NONE = 0, WINDOWS_FADE = 1.

curve_duration

Duration of curve expressed in hundreds of nanoseconds.

Memory Requirements

Table 73. Peak Volume Memory Requirements

Component Size (bytes) Remarks
Object 416  

Runtime Parameters

Table 74. Peak Volume Runtime Parameters

Parameter ID Dir Type
VOLUME 0 R/W Large
Volume

When the volume parameter is set by the management service, a single PeakVolumeConfig instance is expected to be in the parameter data. The channel ID may indicate either a single target channel (0..n-1) or all channels (ALL_CHANNELS).

When the volume parameter is retrieved by the management service, the parameter data contains multiple PeakVolumeConfig instances (one per channel).

Gain

UUID: 61BCA9A8-18D0-4A18-8E7B-2639219804B7

Gain module interface is identical to the one provided by Peak Volume Control. The difference is that Gain does not report peak values in the FW Registers area.

Up Down Mixer

UUID: 42F8060C-832F-4DBF-B247-51E961997B34

Initial Configuration

Up Down Mixer requires UpDownMixerCfg, a basic module configuration with some extensions.

Audio Data Format
Interface Sampling Rate Number of Channels Sample Size Container Size
Input [0] *

1
2
2.1
3.0
3.1
4.0
5.0
5.1

32-bit 32-bit
Output [0] Same as input

2
5.1

32-bit 32-bit
Frame Size

Up Down Mixer works on a 1ms frame.

Data Structures
UpDownMixerCfg Structure
Syntax
struct UpDownMixerCfg : BaseModuleCfg
{
    ChannelConfig        out_channel_config;
    UpDownMixCoeffSelect coefficients_select;
    int32_t              coefficients[1];
};
Members

out_channel_config

Configuration of the output channels (instead of full output format specification as other properties stay the same).

coefficients_select

Indicates whether the module uses built-in coefficients and default channel map or the ones sent within this structure.

0 - Indicates whether module uses default built-in coefficients (when set to 0), or the ones specified in this structure (when set to 1).

coefficients

Array of coefficients values. When coefficients are specified (coefficients_select = 1), the actual length of this array is 6. Otherwise it is 0.

Memory Requirements

Table 76. Up Down Mixer Memory Requirements

Component Size (bytes) Remarks
Object 144  
Coefficients 32 When custom coefficients are specified by the management service.

Runtime Parameters

None.

SRC

UUID: e61bb28d-149a-4c1f-b709-46823ef5f5ae

Initial Configuration

SRC requires SrcIntcCfg, a basic module configuration with some extensions.

Audio Data Format

Table 77. SRC Audio Data Format

Interface Sampling Rate [kHz] Number of Channels Sample Size Container Size
Input [0]

8
11.025
12
16
18.9 (to 44.1 only)
22.05
24
32
37.8 (to 44.1 only)
44.1
48
64
88.2
96
176.4
192

1..8 32-bit 32-bit
Output [0]

8
16
24
32
44.1
48
88.2
96
176.4
192

Same as input 32-bit 32-bit
Frame Size

SRC frame size may be as small as 1ms.

Data Structures
SrcIntcCfg Structure
Syntax
struct SrcIntcCfg : BaseModuleCfg
{
    SamplingFrequency out_freq;
};
Members

out_freq

Output frequency.

Memory Requirements

Table 78. SRC Memory Requirements

Component Size (bytes) Remarks
Object 16816 -4096 if stack is allocated from pipeline memory pool.

Runtime Parameters

None.

Mic Selection/LL-DMIX

UUID: 32FE92C1-1E17-4FC2-9758-C7F3542E980A

Both modes of work are supported by a single logic provided by the ITP PP team. The API supports input-to-output channel map. If more than a single input channel is mapped to the same output channel, the average value of the inputs is computed as the output value.

The following settings are used to configure mode of work:

  • Mic Selection
    • Either multiple input channels are mapped to the output channel #0 so the average value from all specified mics is computed as output,
    • Or single (dynamically selected) mic channel is mapped to the output channel #0 and input from that channel is copied to the output channel.
  • LL-DMIX
    • In this mode, the map is statically defined by the adapter (shim) as average from input channel #0 and input channel #1 to output channel #0.

Audio Data Format

Table 79. Mic Selection Audio Data Format

Interface Sampling Rate Number of Channels Sample Size Container Size
Input [0] 16 kHz 1..8 16 bit 16 bit
Output [0] 16 kHz 1..8 16 bit 16 bit

Frame Size

Input and output frame size is 1ms (16 samples) as the module works in LL domain.

Memory Requirements

Table 80. Mic Selection/LL-DMIX Memory Requirements

Component Size (bytes)
Object 960

Probe

UUID: 20A1F350-19B4-428A-BEF6-F7C27CB8B5FB

Probe is a loadable module.

Since Probe is designed as a standalone module (no parent pipeline assigned), its instance must be deleted explicitly by sending the Delete Instance IPC request.

Initial Configuration

Probe requires ProbeModuleConfig, a basic module configuration with some extensions.

The Probe module is a standalone block, and does not belong to any pipeline. Therefore, ppl_instance_id should be set to INVALID_PIPELINE_ID (-1) in the Init Instance IPC request. If the management service provides the ID of any existing pipeline, it is ignored by the firmware.

Probe is not invoked in any audio data processing chain. Therefore, both the audio data format and the input/output frame sizes specified in the initial configuration are unused.

There is no dedicated execution context, therefore core_id should be set to 0.

Init Instance IPC request = {
	instance_id = 0, 	       // single instance
	proc_domain = 0, 	       // ignored by FW
	core_id = 0, 		       // ignored by FW,
	ppl_instance_id = INVALID_PIPELINE_ID, // no parent
                                              // pipeline
}
ProbeModuleCfg Structure
Syntax
struct ProbeModuleCfg : BaseModuleCfg
{
    ProbeGatewayCfg  gtw_cfg;
};
Members

gtw_cfg

Configuration of the probe capture (host input) gateway.

ProbeGatewayCfg Strtucture
Syntax
struct ProbeGatewayCfg
{
    uint32_t node_id;
    uint32_t dma_buffer_size;
};
Members

node_id

ID of gateway used to transport extracted data to the host. This must be one of IPC host input gateway IDs. Should be set to INVALID_NODE_ID if no gateway is allocated (extraction will not be supported).

dma_buffer_size

Preferred size of the gateway buffer (in bytes).

Memory Requirements

Table 81. Probe Memory Requirements

Component Size (bytes)
Total BSS  

Runtime Parameters

Runtime parameters controls capture and insertion probes. Probes may be connected to a module instance’s input/output queue (supported for any module by the infrastructure). Probes may also be connected to an internal probe point inside the module instance, if supported by the target module instance implementation.

Probe point addressing is documented in the Probe Points parameter section.

Table 82. Probe Runtime Parameters

Parameter ID Dir Type
INJECTION_PROBE_DMA 1 R/W Large
INJECTION_PROBE_DMA_DETACH 2 R/W Large
PROBE_POINTS 3 R/W Large
DISCONNECT_PROBE_POINTS 4 R/W Large
Injection Probe DMA

The management service writes this parameter to associate host output DMAs as injection probes with Probe module.

The management service may read this parameter to obtain the list of host output DMAs currently associated with Probe module.

ProbeDmaList Structure
Syntax
struct ProbeDmaList
{
    ProbeDma probe_dma[];
};
Members

probe_dma

Array of DMAs to be associated with the Probe module. Actual size of the list is specified by the data_off_size field in the message header.

ProbeDma Structure
Syntax
struct ProbeDma
{
    uint32_t  node_id;
    uint32_t  dma_buffer_size;
};
Members

node_id

ID of gateway. This must be one of IPC host gateway IDs (host output in case of an injection probe).

dma_buffer_size

Preferred size of the gateway buffer (in bytes).

Remarks

Attempt to assign a DMA that is already in use by Probe module or any other module results in error.

Injection Probe DMA Detach

The management service sends this configuration parameter to detach one or more probe DMAs from the Probe module.

ProbeDmaDetachList Structure
Syntax
struct ProbeDmaDetachList
{
    uint32_t node_id[];
};
Members

node_id

Array of gateway IDs to be detached. Actual size of node_id array is determined by size of the payload specified in the message header.

Remarks

Attempt to detach a DMA being in-use by any probe points results in error.

Attempt to detach a DMA that is not associated with Probe module completes successfully.

Probe Points

The management service writes this parameter to create probe points.

The management service may read this parameter to obtain the list of currently created probe points.

ProbePoints Structure
Syntax
struct ProbePoints
{
    ProbePointDesc probe_points[];
};
Members

probe_points

Array of probe point descriptors. Actual size is specified in the message header.

Remarks

All probes that are created by a single request are synchronously started at the same system tick by the FW.

Attempt to create/re-configure a probe point that already exists results in error.

Attempt to create a probe point associated with either unassigned or occupied DMA results in error.

Attempt to create a probe point targeted at non-exiting module instance results in error.

A probe point is automatically deleted while its target is being deleted.

ProbePointDesc Structure
Syntax
struct ProbePointDesc
{
    ProbePointId id;
    uint32_t     purpose;
    uint32_t     node_id;
};
Members

id

Probe point identifier. See ProbePointId.

purpose

Indicates connection purpose.

0 – Extract,

1 – Inject,

2 – InjectReextract.

node_id

Specifies injection gateway ID in case purpose is set to Inject or InjectReextract, otherwise set to INVALID_NODE_ID.

ProbePointId Structure
Syntax
struct ProbePointId
{
    uint32_t module_id   : 16;
    uint32_t instance_id : 8;
    uint32_t type        : 2;
    uint32_t index       : 6;
};
Members

module_id

Target module ID.

instance_id

Target module instance ID.

type

Type.

0 – Input,

1 – Output,

2 – Internal.

index

Specifies a 0-based index of the target module instance’s queue.

Disconnect Probe Points

The management service sends this configuration parameter to disconnect one or more probe points.

ProbePointList Structure
Syntax
struct ProbePointList
{
    ProbePointId probe_point_id[];
};
Members

probe_point_id

Array of probe point IDs to be disconnected. Actual size of the array is determined by size of the payload specified in the message header.

Remarks

Attempt to disconnect a non-exiting probe point is ignored by FW and does not raise an error.

Probe Data Stream

Extraction Data Format

Since a single extraction probe DMA is used to transfer data from multiple probe points, the data is packetized where the management service may expect that packets coming from different probe points are interleaved. Each pocket begins with the following header.

ProbeDataPacket Structure
Syntax
struct ProbeDataPacket
{
    uint32_t     sync_word;
    ProbePointId probe_point_id;
    ProbeDataFmt format;
    uint32_t     timestamp_low;
    uint32_t     timestamp_high;
    uint32_t     data_size_bytes;
    uint32_t     data[];
    uint64_t     checksum;
};
Members

sync_word

Set to 0xBABEBEBA.

probe_point_id

Probe point ID. See ProbePointId for details.

format

Data format. See ProbeDataFmt for details. Note that it may be either ProbeDataFmtBasic, or ProbeDataFmtStandard.

timestamp_low

Low DWORD of 64-bit timestamp read from wall clock.

timestamp_high

High DWORD of 64-bit timestamp read from wall clock.

data_size_bytes

Actual size of data[] array, expressed in bytes.

data

Data, padded to the DWORD boundary with zeroes.

checksum

Checksum (little-endian encoded), data[] not included.

Injection Data Format

The data being injected is a pure data stream, without any headers. It must be formatted accordingly to the format of the input/output pin or internal queue of the target module instance.

ProbeDataFmtBasic Structure
Syntax
struct ProbeDataFmtBasic
{
    uint32_t fmt_type       : 1; // = 0
    uint32_t basic_type_enc : 31;
};
Members

fmt_type

Format type, set to 0 to indicate Basic format.

basic_type_enc

Basic type encoding TBD.

ProbeDataFmtStandard Structure
Syntax
struct ProbeDataFmtStandard
{
    uint32_t fmt_type        : 1; // = 1
    uint32_t standard_type   : 4;
    uint32_t audio_fmt       : 4;
    uint32_t sample_rate     : 4;
    uint32_t nb_channels     : 5;
    uint32_t sample_size     : 2;
    uint32_t container_size  : 2;
    uint32_t sample_fmt      : 1;
    uint32_t sample_end      : 1;
    uint32_t interleaving_st : 1;
    uint32_T _rsvd_0         : 7;
};
Members

fmt_type

Format type, set to 1 to indicate Standard format.

standard_type

Stream type.

0 – Audio stream,

1 – Video stream.

audio_fmt

Audio encoding type.

0 – PCM,

1 – MP3,

sample_rate

Sample rate.

0 – 8 kHz,

1 – 11.025 kHz,

2 – 12 kHz,

3 – 16 kHz,

4 – 22.05 kHz,

5 – 24 kHz,

6 – 32 kHz,

7 – 44.1 kHz,

8 – 48 kHz,

9 – 64 kHz,

10 – 88.2 kHz,

11 – 96 kHz,

12 – 128 kHz,

13 – 176.4 kHz,

14 – 192 kHz,

15 – INVALID_SAMPLE_RATE.

nb_channels

Channel count. Zero based (0 means 1 channel, 1 means 2 channels and so on).

sample_size

Sample size in bytes. Zero based (0 means 1 byte, and so on).

container_size

Container size in bytes. Zero based.

sample_fmt

Sample format.

0 – integer format,

1 – 32-bit floating point format. Note that sample_size and container_size must be both set to 3 in this case.

sample_end

Sample endianness.

0 – Little endian,

1 – Big endian.

interleaving_st

Interleaving style.

0 – Sample interleaving,1 – Channel interleaving.

Management Service

Management Service is a standalone module (no parent pipeline assigned). It instantiates automatically after the firmware boots successfully. This section provides an example implementation of the management service in firmware. For example, the module allows you to configure hardware codecs, create a full audio pipeline, and start it with one IPC message.

The Module ID can be retrieved from firmware using the Module Info Base FW Parameter.

Pipeline

As part of the management service example, the audio pipeline shown in the following figure is implemented.


Figure 31. Audio Pipeline in Management Service

The capture part (the top part of diagram) of pipeline is created automatically and started. The device listens for a key phrase (KP). It notifies the host about KP detection with an IPC message, and starts streaming audio frames to the host via IPC gateway when the phrase is detected. The audio stream to the host can be stopped with the CLOUD_STOP IPC message.

The example implementation of the management service expects that the playback (render) pipeline is paused at the beginning. It activates once the host wants to deliver a response from Cloud via i2s.

Runtime Parameters

Table 83. Management Service Runtime Parameters

Parameter ID Dir Type
STOP_PLAYBACK 1 R/W Large
START_PLAYBACK 2 R/W Large
CLOUD_STOP 3 R/W Large
PIPELINE_SOFT_RESET 4 R/W Large

Stop Playback

The host sends this configuration parameter to stop the playback pipeline.

Stop Playback

The host sends this configuration parameter to start the playback pipeline when, for example, a cloud response must be delivered.

Cloud Stop

The device starts streaming audio frames when a Key Phrase is detected. The host must send a Cloud Stop message to move to the “listening for KP” state.

Pipeline Soft Reset

The host sends this configuration parameter to delete, then recreate, the pipeline.

Modules Available in the Firmware

Module Categories

Modules are classified by processing domain (Low Latency versus Data Processing) and by packaging (Built-In versus Loadable).

Low Latency (LL) Modules

Properties of low latency (LL) modules:

  • Processing is done in LL domain.
  • Processes only LL 8ms chunks of data.
  • Modules are executed in order of their parent pipeline priorities.
  • Processing is done till completion (without preemption).
  • Module is executed only on Core 0.

Data Processing (DP) Modules

Properties of DP modules:

  • Processing in done in the DP domain.
  • The size of the input frame is specified by a module.
  • They are scheduled by EDF scheduler.
  • Module is executed in dedicated task (one per module instance).
  • Module is executed on a core assigned by the management service.

Built-In Versus Loadable Modules

Some modules are built-in modules, always present in firmware memory space and ready to be instantiated. Other modules are loadable modules that may be dynamically loaded and unloaded during runtime.

The Module Manager is initialized with a module list from the FM Image Manifest.

  • The existence of built-in modules is guaranteed.
  • To use loadable modules, the correct data must be loaded (.text and .rodata sections).
  • Built-in modules are allocated on pipeline memory.
  • Loadable modules have dedicated memory for module.

Firmware LL Modules

Copier Module (PCM converter)

This module serves as a 1:n simple bridge between pipelines. Copying data between the queues during LL cycles guarantees real-time data flow.

Copier consumes data from the attached input queue, 1ms of data at the time. The data is written to one or more output queues. Having multiple output queues resolves many problems with timing and size dependencies between outputs.

Copier also provides PCM conversion routines, and the ability to (de-)interleave samples while copying data to/from DMA Gateways. Providing this additional processing capability inside the Copier allows for a reduced number of memcpy operations and a reduced number of module instances created in the pipeline (PcmConverter is not needed).

Copier provides the following:

  • Gateway (one per instance) handling
  • PCM conversions

For more information, see Section “Copier”.


Figure 32. Copier Module

Mixer Modules (MixIn, MixOut)

The output of a MixIn module instance is always attached to a MixOut module instance by the Bind command. The output writes data from the input source to the MixOut’s sink interface. The data is written to the sink using a saturating ADD operation.

A MixIn instance uses a sink that maintains its private write pointer and global read pointer to determine the part of the buffer that can be written. However, it does not know whether its add operation is the first one at the current write position. Therefore, MixIn assumes that the part of the buffer that is not written by anyone yet is zeroed.

The MixOut module instance is the second part of the Mixer complex.

Since the state of the mixer buffer is recalculated by the sinks when MixIn instances write their data, the data processing routine just copies the common part to the target queue. Then, it iterates over the write pointers associated with the internal buffer and resets them to reflect recent data consumption.

The part of internal buffer that is consumed by the MixOut::ProcessData() function must be zeroed before ProcessData() exits, to ‘restart’ the next mixing (adding) operation at this place from 0.

MixOut supports up to eight ‘input’ sinks.

To satisfy pipeline latency computation requirements, MixOut must implement an artificial Source interface on top of the mixer buffer and register it in the source array. There is a single instance of Source (that reflects the already-mixed data coming into the MixOut) registered, not eight ones.

  • Mixes all data from all connected MixIns
  • Always has data ready on output
  • Provides eight Sinks (virtualized over the same physical buffer)
  • Has only one buffer per instance

For IPC Configuration, see Section “Mix In”, and Section “Mix Out”.


Figure 33. Mixer Modules

Peak Meter/Volume

The Peak Meter/Volume module provides the following:

  • Input signal meter (per channel)
  • Volume changing (per channel)
  • Fade apply (optional per demand)
  • Exposing set/measured parameters via memory window

For IPC Configuration, see Section “Get Data”.


Figure 34. Peak Meter/Volume Module

UpDown Mixer

UpDown Mixer provides channel up- and down-mixing routines.

It supports the transformations shown in the following table.

Table 84. UpDownMixer Transformations

Input Channel Configuration Output Channel Configuration
CHANNEL_CONFIG_STEREO CHANNEL_CONFIG_MONO
CHANNEL_CONFIG_MONO CHANNEL_CONFIG_STEREO
CHANNEL_CONFIG_DUAL_MONO CHANNEL_CONFIG_STEREO
CHANNEL_CONFIG_STEREO CHANNEL_CONFIG_STEREO
CHANNEL_CONFIG_2_POINT_1 CHANNEL_CONFIG_STEREO
CHANNEL_CONFIG_3_POINT_0 CHANNEL_CONFIG_STEREO
CHANNEL_CONFIG_3_POINT_1 CHANNEL_CONFIG_STEREO
CHANNEL_CONFIG_QUATRO CHANNEL_CONFIG_STEREO
CHANNEL_CONFIG_4_POINT_0 CHANNEL_CONFIG_STEREO
CHANNEL_CONFIG_5_POINT_0 CHANNEL_CONFIG_STEREO
CHANNEL_CONFIG_5_POINT_1 CHANNEL_CONFIG_STEREO
CHANNEL_CONFIG_7_POINT_1 CHANNEL_CONFIG_STEREO
CHANNEL_CONFIG_MONO CHANNEL_CONFIG_5_POINT_1
CHANNEL_CONFIG_STEREO CHANNEL_CONFIG_5_POINT_1
CHANNEL_CONFIG_STEREO CHANNEL_CONFIG_7_POINT_1

For IPC Configuration, see Section “Up Down Mixer”.


Figure 35. UpDown Mixer

Firmware DP Modules

Multiplexer (MUX)

  • For processing, this module requires that at least input “0” is connected
  • Input “1” is also known as “reference pin”
  • Reference pin, when not connected, inserts zeroes


Figure 36. Multiplexer

Microphone Selector (MICSEL)

  • Combines N number of channels at input into M number of channels at output
  • Typically realizes down-mixing from N channels to 1 channel


Figure 37. Microphone Selector

Sample Rate Converter

  • Performs Sample Rate Conversion
  • Can be executed in either LL or DP domain
  • Highly optimized implementation


Figure 38. Sample Rate Converter

Post Processing Modules

  • Shim wraps 3rd party library
  • Processing time depends on processing function
  • Configured via generic module configuration API
  • Processing can be disabled using generic call

 
Figure 39. Post Processing Modules

Module Interfaces

Module Instances

  • A Module instance is a single processing unit.
  • The maximum number of instances is declared per module during image configuration.
  • A Module provides up to 8 input pins (aka sinks) and up to 8 output pins (aka Sources).
  • A Module instance must be initialized before use.
  • There is a base module configuration defined, common for all modules. It can be extended by a specific module (optional).

Module Instance Supported Calls

  • Init Module Instance
  • Config Parameter Get
  • Config Parameter Set
  • Set Processing State (On|Bypass)
  • Enter/Exit Module Restore

For a full description of the supported calls, see Section 5.6 for full description of the Module Instance Supported Calls.

Implementing a new Module

{TBD}

Module API

You can find information about the Module API at Intel Audio FDK Module API.

While the Intel ADSP system provides some built-in processing modules for typical use cases, you can also extend its feature set with user-defined module packages. Such module packages are referred to as "loadable processing module" (or simply "loadable module") packages, because they can be loaded into the ADSP memory dynamically, as needed.

This section presents an overview of the Intel ADSP API.

Module implementation shall meet three minimum requirements:

  • As a processing module class, it shall implement the ProcessingModuleInterface class.
  • As a module factory class, it shall implement the ProcessingModuleFactoryInterface class.
  • It shall declare itself as "loadable" with help of the macro DECLARE_LOADABLE_MODULE.
ProcessingModule Class

The ProcessingModuleInterface defines methods that the Intel ADSP System calls to configure and fire the stream processing.

The center of the development of a loadable module package is the Intel_adsp::ProcessingModuleInterface class. Every custom module must implement this class. The ProcessingModuleInterface defines methods that the Intel ADSP System calls to configure and fire the stream processing.

For convenience, the Intel_adsp::ProcessingModule class is provided as a partial default implementation of the ProcessingModuleInterface class. It is suitable for the usual needs of most modules, when the count of input and output module pins is known at compile time.

A custom module class needs to implement at least the following three functions:

  • ProcessingModule::Process()
  • ProcessingModule::SetConfiguration()
  • ProcessingModule::SetProcessingMode()

ProcessingModule::Process()

Processes the stream buffers extracted from the input pins, and produces the resulting signal in the stream buffer of the output pins.

ProcessingModule::SetConfiguration()

Applies the upcoming configuration message for the given configuration ID.

ProcessingModule::SetProcessingMode()

Sets the processing mode for the module.

Optionally, the methods in the following sections can be overridden in ProcessingModule.

ProcessingModule::GetConfiguration()

Retrieves the configuration message for the given configuration ID.

ProcessingModule::Reset()

Upon call to this method, the Intel ADSP system requires the module to reset its internal state to a well-known initial value.

Parameters which may have been set through SetConfiguration() are expected to be left unchanged.

ProcessingModuleFactory class

As part of a custom module package, a process module factory shall be provided to handle creation of the custom processing module components. The ProcessingModuleFactoryInterface class defines requirements for this. The Create() method, on some parameters given by the ADSP system in the factory, is intended to provide the following:

  • An initialized user-defined module instance
  • The input and output pins associated to the module instance
  • The stack buffer for execution of the module instance

You should implement the methods in the following sections.

ProcessingModuleFactory::Create()

Creates a RegisteredProcessingModule instance.

The custom implementation of the Create method is expected to handle initialization of the custom module instances.

ProcessingModuleFactory::GetPrerequisites()

Indicates the prerequisites for module instance creation.

The ADSP system calls this method before each module instance creation.

Tasks and Schedulers

To meet different task requirements for low latency domain tasks and processing tasks, the DSP scheduling uses separate scheduler levels.


Figure 40. Scheduler Levels

The low latency scheduler and data processing scheduler are configured by the management service.

The management service receives a request to start a specific type of processing request. In the first step, the request must be split into tasks. The task list depends on the current DSP state (running tasks), and on configuration data (for example, post processing).

Each task must be looked up in the task database to obtain its parameters. The database may come from module metadata or a dedicated plug-in.

The management service sends the prepared topology (binding), allocated instances of memory blocks, and core assignment to DSP.


Figure 41. Scheduling between Management Service and Pipelines

Low Latency Task Scheduler

The low latency scheduler is a set of processing routines that walk through a required set of queues and bits.

From an overall scheduling perspective, the important parameter is the number of clock cycles consumed by the low latency domain. The remaining number of clock cycles is the budget that the data processing scheduler can use.

The number of CPU cycles consumed by the low latency domain depends on the number of active components. The management service uses post-implementation firmware performance data to estimate the amount of computing required by the low latency domain. The calculation considers fixed overhead, type of active blocks, number of instances, and (sometimes) parameters of instance. 

Data Processing Task Scheduler

In DSP firmware, the number of possible stream configurations and combinations is enormous. It is enough to consider each stream parameter (such as decoder type, channel configuration, and sampling rate) that are set separately for each stream. Adding multiple extra decoders and post-/pre-processing modules makes a solution unmanageable.

Therefore, a major focus of the data processing scheduler is reducing the effort required to integrate and validate new processing modules. This goal is achieved by the following:

Each data processing pipeline contains a set of processing modules and ends with a real-time sink.

  • Automated pipeline setup
    • Flexible component binding
    • Automatic buffer calculation
    • Setting up schedule
    • Resource requirement calculation
  • Pipeline separation
  • Diagnostic feedback mechanism


Figure 42. Example of Data Processing pipeline

Figure 42 shows an example pipeline, consisting of three processing modules, intermediate buffers, and a real-time sink. Analysis of the playback pipeline starts from the end. The real-time sink consumes data sample groups (or ‘samples’) at the sampling frequency rate. In the Intel Quark SoC S1000 ASIC, all samples in a system tick interval is consumed by the low latency portion of the firmware within a system tick interval.

Each processing module is characterized by a set of configuration-dependent parameters:

  • Block Size (BS) describes the nominal amount of data samples processed in single processing cycle
  • Output Buffer Size (OBS) describes the output buffer space in samples that is required to run the module
  • Input Buffer Size (IBS) describes the number of samples available at input that are required to run the module
  • Block Processing Cost (BPC) describes the number of Core clocks required to process a single block
    • This shall be the guaranteed worst case for any block, not the average number

Each audio streaming task needs to work in real time. As a result, we can assume that the overall DSP utilization must be guaranteed to be less than 100%. The management service task mapping must ensure that this is the case. With this assumption, it is possible to adopt derivative Earliest Deadline First (EDF) scheduling.

EDF has attractive properties in this situation for the following reasons:

  • Ability to schedule tasks up to 100% (theoretical) load

    In theory, any combination of independent tasks will be scheduled once utilization is under 100%.

  • Algorithm simplicity (low cost)

    The scheduler can always pick the first task from the active task list. The active task list is a sorted list of task deadlines. Scheduling a new deadline is a simple insertion task into the appropriate place on the list.

  • Dynamic scheduling

    The algorithm can execute tasks back-to-back, consuming less than allocated time and allowing the core to go to low-power state. For comparison, in Synchronous Data Flow (SDF), if a task completes faster (which is common on DSP), the algorithm must wait until the start of the next scheduled task.

  • Reduced number of context switches

    This is due to a lack of fairness: for example, using round robin algorithm limits the number of task switches. It always executes the first task from the list until it is complete. This happens even when the next task on the list has the same deadline.

Memory Map

The 4 MB of internal high performance memory is the central memory block for the Intel Quark SoC S1000 ASIC. The dual DSP cores and GNA engine can access this central memory. This high performance internal memory is used as workspace for the DSP core with firmware code and data, samples from the audio streams, speech scoring models used by the GNA Engine, and so on.

The 64 kB of low power memory is attached to the low power Memory Fabric domain, where LP SRAMs are located. The DSP cores use this memory mainly for DMA buffers.

All allocation requests refer to virtual memory address space. Even DMA drivers allocating buffers for DMA operations do not require continuous physical memory since VA/PA translation mechanism includes also DMA transactions.


Figure 43. Virtual memory allocation example

Figure 43 depicts example of virtual memory allocation for the firmware image. In generic case firmware image may contain:

  • Base firmware (including initialization)
  • Libraries
  • Large module instance data area
  • Pipeline data areas
  • Optional 3rd party library areas

Base firmware contains base runtime infrastructure and minimum set of modules that are linked into typical three sections: code, read-only data and bss.

Firmware libraries can contain one or more modules, module parameters are described in library manifest.

Last part of the image is bss area used to keep module instance data. Instance data contains all memory areas required by module instance including: persistent memory, scratch area (due to preemptive scheduling scratch area cannot be shared) and thread stack. Modules using large instance data (> 32KB) have instance data allocated in this area. Each module has allocated maximum instances of maximum size as indicated in module entry.

Instance data of modules consuming less space are allocated in pipeline areas. There is fixed amount of pipelines with predefined size that given firmware image configuration may support.

This scheme of allocation is designed to reduce memory allocation overhead and use of virtual address space: Large modules are natural way supported in limited amount of instances (typically 1 or 2). There may be much more small modules and page alignment on each allocated area would be expensive. Inter-module queues fall also into category of small areas. All memory within pipeline area is allocated linear way, it is freed altogether with destroying pipeline.

Stream and Pipeline Management

Pipeline Overview

  • A pipeline is a set of module instances, in the processing order
  • The pipeline allocates tasks (LL and DP) as execution context for module instances
  • The pipeline allocates queues between module instances (DP queues are sharable between cores)


Figure 44. Pipeline

Pipeline Attributes

Static
  • ID (init parameter) is unique within the system
  • Priority (init parameter) determines the order of execution in LL domain (0 – highest, 7 – lowest)
  • Memory pool size
Runtime
  • State (propagated to modules/tasks/queues etc.)

Pipeline Messages

A pipeline supports the following messages:

  • CreatePipeline
  • DeletePipeline
  • SetPipelineState
  • GetPipelineState

For a full description of pipeline supported messages, see Pipeline Management IPC

Pipeline States


Figure 45. Pipeline State Machine

Uninitialized

This is initial state of the pipeline when it is created. The pipeline remains in this state while modules are instantiated and added. Other than setting another state, no other information comes from software that this process is completed. Therefore, an exit from this state triggers the creation and registration of the pipeline’s tasks.

Moreover, to ensure consistent state transition sequence, the Reset state is set internally immediately after all tasks are registered. It means that IPC_PplSetState(Reset) triggers the Uninitialized → Reset sequence, while IPC_PplSetState(Paused) triggers the Uninitialized → Reset → Paused sequence.

Reset

When the pipeline enters the Reset state, all associated tasks and module instances are reinitialized by propagating the new state to their SetPplState() methods.

The state of the queues allocated by the pipeline for data exchange of LL/DP tasks is also reset.

Paused

The Paused state is propagated to all associated tasks and modules instances to deactivate them and exclude them from scheduling.

Running

The Running state is propagated to all associated tasks and module instances to make them schedulable again.

EndOfStream

The EndOfStream state is valid for the Decode pipeline type only.

This state is saved inside the pipeline object but is not propagated to tasks. All associated tasks and module instances should continue their normal operations until an underrun is detected by the MixIn module instance. Detecting underrun when the parent pipeline enters the EndOfStream state triggers a special flow, which is documented in "End of Stream Notification”.

ErrorStop

The ErrorStop state is propagated to all associated tasks and module instances to deactivate them when an unrecoverable error occurs inside the pipeline.

[Saved]

This state is propagated to the pipeline components internally by the Pipeline::Save() method, to save module instances and context information of tasks. The Pipeline Manager also returns this value in response to IPC_PplGetState if the specified pipeline ID points to a pipeline that was stored in the host memory.

The current state of the pipeline is not changed.

[Restored]

This state is propagated to the pipeline components internally by the Pipeline::Restore() method to restore context information and reconnect to HW components.

Driver Interfaces


Figure 46. Physical Interfaces

The physical interfaces include the following:

  • A USB 2.0 HS device interface
  • A slave SPI interface connects to a master host MCU or AP
  • A master SPI interface can be used to connect audio codec or memory devices
  • An I2C interface connects to off-chip components such as codecs and PMICs
  • A UART interface for debug
  • Four i2s interfaces connect to a microphone array, a speaker codec, the host processor, and a radio
  • Four stereo PDM interfaces can be used to connect up to eight PDM microphones
  • 26 general-purpose I/O signals connect to platform controls and status indicators such as LEDs and power switches
  • A parallel memory interface connects to off-chip memories of up to 8 MB
  • System interface includes asynchronous reset, wake-up, interrupt request, crystal oscillator power-down, and clock outputs and crystal

GNA (GMM and Neural Network Accelerator) Engine

This section describes the application-facing API for the GNA accelerator in the Intel Quark SoC S1000 ASIC.

API Definition

Data Structures

gna_device

Description

This structure is created during the module initialization process. It provides access to internal data (MMIO, irq resource, and so on) and is a mandatory argument of the GNA firmware API function calls.

Syntax

From the firmware level (GNA module code), access to this structure’s instance can be obtained through the module’s private field. The module initialization routine is responsible for preparing the gna_device structure. The following snippet takes care of gna_device initialization.

gna_device_attributes attrs;
gna_device_attributes_init(&attrs, DSP_MS_GNA_BA, EMPTY_IRQ_RESOURCE);
gna_device_init(&this->gna_, &attrs);

gna_request

Description

This structure must be passed to every calculation call. It ties a unique request identifier with input/output buffers and the model to be used for scoring.

Syntax
struct gna_request
{
uint16_t request_id;
int16_t *inputs;
int16_t *outputs;
void *model;
};
Members

request_id

Unique identifier assigned by the client application to recognize the request later.

inputs

Pointer to the buffer containing inputs for the neural network. The buffer should be allocated in DSP memory space and 64-byte aligned in both location and size.

outputs

Pointer to the output buffer. The calculation results appear there. The buffer should be allocated in DSP memory space and 64-byte aligned in both location and size.

model

Pointer to the model image to be used for scoring this request. Should be allocated in DSP memory space, 64-byte aligned in location and size, and populated with the model image data.

Functions

gna_device_model_setup

Description

Sets up the model in GNA’s configuration. Every model, after loading to memory, must be configured. The model image is described by GNA’s MMU entries. Model loading to DSP memory space is outside of the scope of this API.

Syntax
ECODE gna_device_model_setup(
struct gna_device *self,
void *model);

Parameters

self

This is gna_device structure. It provides access to configuration details, which are filled on the function call.

model

Pointer to the space where model data begins. Should be 64-byte aligned in location. The size is inferred from the header present inside the model image.

gna_device_calculate

Description

Sets up the model in GNA’s configuration. Every model, after loading to memory, must be configured. The model image is described by GNA’s MMU entries. Model loading to DSP memory space is outside of the scope of this API.

Syntax
ECODE gna_device_calculate(
struct gna_device *self,
struct gna_request *request);

Parameters

self

This is gna_device structure.

request

Structure describing the request.

gna_device_get_status

Description

Returned ECODE provides basic information about the status: success, in progress, failed, or in queue. If the returned value indicates success, it is safe to inspect the scoring results in the output buffer. In case of failure, additional information can be obtained by inspecting the request_status output parameter.

Syntax
ECODE gna_device_get_status(
struct gna_device *self,
uint16_t request_id,
uint32_t *request_status);
Parameters

self

This is gna_device structure.

request_id

Unique identifier of the request we are waiting for.

request_status

If the request is not still in queue, this will get filled with the value of GNA’s status register.

Sample Usage Model


Figure 47. Sample Usage Model

I2C Interface

[TBD]

API Definition

Definitions

Constants
Syntax
#define IC_TX_BUFFER_DEPTH 8
#define IC_RX_BUFFER_DEPTH 8
#define IC_EMPTYFIFO_HOLD_MASTER_EN 1
#define IC_FIRST_DATA_BYTE_STATUS 1
#define IC_RX_FULL_HLD_BUS_EN 1
#define I2C_DYNAMIC_TAR_UPDATE 1
#define IC_BUS_CLEAR_FEATURE 1
#define IC_RESTART_EN 1
#define IC_SMBUS 0
#define IC_DEVICE_ID 0
#define PIN_MUXING 1
i2c_transfer_flags
Description

I2C transfer flags.

Syntax
typedef enum {
    I2C_MASTER_TRANSFER_NORMAL=0,
    I2C_MASTER_TRANSFER_GENERAL_CALL=1
} i2c_transfer_flags;
i2c_device_speed
Description

I2C device speed flags.

Syntax
typedef enum {
    I2C_MASTER_DEVICE_SPEED_STANDARD = 1,
    I2C_MASTER_DEVICE_SPEED_FAST,
    I2C_MASTER_DEVICE_SPEED_HIGH
} i2c_device_speed;

I2C_MASTER_DEVICE_SPEED_HIGH - not supported, IC_MAX_SPEED_MOD=2

i2c_device_operation
Description

I2C device operation flags.

Syntax
typedef enum {
    I2C_MASTER_DEVICE_OP_WRITE=0,
    I2C_MASTER_DEVICE_OP_READ=1
} i2c_device_operation;
i2c_addressing_option
Description

I2C addressing option flags.

Syntax
typedef enum {
    I2C_MASTER_DEVICE_ADDR_10_BIT,
    I2C_MASTER_DEVICE_ADDR_7_BIT
} i2c_addressing_option;
pfn_i2c_master_device_workitem_done
Description

I2C master workitem completion callback.

Syntax
typedef void (*pfn_i2c_master_device_workitem_done)(
    struct i2c_master_device_workitem* self,
    void* context,
    ErrorCode error_code);

self - pointer to I2C workitem that has completed.

context - Client supplied callback context.

error_code - Reason why the workitem has finished.

pfn_gpdma_transfer_i2c_xblock_done
Description

I2C master GP DMA transfer block completion callback.

Syntax
typedef void (*pfn_gpdma_transfer_i2c_xblock_done)(
    struct gpdma_transfer_i2c_xblock* self,
    void* context,
    ErrorCode error_code);

self - pointer to I2C block that has completed.

Context - Client supplied callback context.

error_code - Reason why the block has finished.

Structures

i2c_master_device_workitem
Description

I2C master device workitem.

Bare I2C master executes workitems in interrupt mode. Higher level objects like gpdma_transfer_i2c may be created to execute series of workitems also over GP DMA.

This object must be initialized in client-maintained buffer using i2c_master_device_workitem_init().

Then, client shall insert read/write commands to the buffer up to the buffer capacity.

Syntax
struct i2c_master_device_workitem
{
    pfn_i2c_master_device_workitem_done cb_done_;
    void* cb_done_context_;
    uint16_t slave_address_;
    uint8_t slave_10bit_addr_en;
    uint8_t transfer_flags_;
    uint32_t cmd_buffer_size_;
    uint16_t tx_commands_count_;
    uint16_t rx_commands_count_;
    uint32_t progress;
    uint32_t reads_done;
    ErrorCode tx_status;
    IC_DATA_CMD commands_[];
};

transfer_flags_ - for example, always restart

cmd_buffer_size_ - buffer for storing commands and received data

progress - field for command exeucuting progress save

reads_done - field for saving buffer write position

commands_ - contains TX commands up to index tx_commands_count_

i2c_master_device_attributes
Description

I2C master device initialization attributes.

Caller initializes this structure with a call to i2c_master_device_attributes_init() then applies desired configuration and finally passes it to i2c_master_device_init().

Syntax
struct i2c_master_device_attributes
{
    regs mmio_;
    void* i2c_mux_register_;
    irq_resource irq_;

    i2c_device_speed speed_;
    uint8_t restart_en_;
    uint8_t slave_disable_;
    uint8_t master_mode_;
    uint8_t ten_bit_addr_mode_;

    uint8_t bus_clr_feature_ctrl_;
    uint8_t stop_det_if_master_active_;

    uint8_t rx_fifo_full_hld_ctrl_;
    uint8_t tx_empty_ctrl_;

    uint8_t rx_fifo_tl_;
    uint8_t tx_fifo_tl_;

    uint32_t scl_low_timoeout_;
    uint32_t sdl_low_timoeout_;

    uint32_t SDA_RX_HOLD_;
    uint32_t SDA_TX_HOLD_;
    uint32_t tx_handshake_line_;
    uint32_t rx_handshake_line_;
};
i2c_master_device
Description

Bare metal I2C master device.

May transfer a single i2c_master_device_workitem in PIO/interrupt mode. DMA transfer over I2C is implemented in gpdma_transfer_i2c.

Syntax
struct i2c_master_device
{
    struct device_node device_;
    i2c_addressing_option addressing_;
    struct i2c_master_device_workitem* workitem_;
    uint32_t tx_handshake_line_;
    uint32_t rx_handshake_line_;

    uint32_t flushed_tx_cnt;
    uint32_t rx_full_ints;
};
gpdma_transfer_i2c_xblock
Description

I2C master device transfer block for #gpdma_transfer_i2c.

Syntax
struct gpdma_transfer_i2c_xblock
{
    dllist list_;
    LinkedList tx_descriptor_;
    LinkedList rx_descriptor_;
    pfn_gpdma_transfer_i2c_xblock_done cb_dma_done_;
    void* cb_dma_done_context_;
    struct i2c_master_device_workitem workitem_;

    ErrorCode transfer_status;
};
gpdma_transfer_i2c
Description

I2C master GP DMA transfer component.

This utility may be used to enqueue series of transfers to various I2C slaves using GP DMA.

Syntax
struct gpdma_transfer_i2c
{
    struct i2c_master_device* i2c_master_;
    struct dllist* xblock_head_;
};

Functions

i2c_master_clockgate_and_disable
Description

Clockgate and disable device.

Syntax
void i2c_master_clockgate_and_disable();
i2c_master_device_workitem_init
Description

Initializes I2C workitem in a buffer.

Capacity of the workitem results from subtracting workitem header size from the buffer_size and dividing that by size of command (2 bytes).

Returns a pointer to the workitem or NULL on failure.

Syntax
ErrorCode i2c_master_device_workitem_init(
        struct i2c_master_device_workitem* workitem,
                uint32_t buffer_size,
                uint32_t slave_address,
                uint8_t slave_10bit_addr_en,
                pfn_i2c_master_device_workitem_done cb_done,
                void* cb_done_context);

buffer - Buffer to be used for I2C workitem.

buffer_size - Size of buffer in bytes.

slave_address - Destination slave address.

cb_done - Completion callback pointer.

cb_done_context - Context to be passed to the completion callback.

i2c_master_device_workitem_write
Description

Appends register write operation to I2C workitem.

Syntax
ErrorCode i2c_master_device_workitem_write(
    struct i2c_master_device_workitem* self,
    uint8_t value);

self - Pointer to I2C workitem.

i2c_master_device_workitem_read
Description

Appends series of register read operations to I2C workitem.

Returns success or ADSP_NO_MORE_ENTRIES if workitem has no more capacity to hold requested operation.

Syntax
ErrorCode i2c_master_device_workitem_read(
    struct i2c_master_device_workitem* self,
    uint16_t bytes_to_read);

self - Pointer to I2C workitem.

bytes_to_read - Read length.

i2c_master_device_workitem_get_rx_byte
Description

Get response byte after workitem has been executed.

Returns success or ADSP_NO_MORE_ENTRIES if requested offset is beyond the workitem.

Syntax
ErrorCode i2c_master_device_workitem_get_rx_byte(
    struct i2c_master_device_workitem* self,
    uint16_t offset,
    uint8_t* value);

self - Pointer to I2C workitem.

offset - Number of read operation which result should be returned.

value - Pointer of location to store the result.

i2c_master_device_attributes_init
Description

Initializes I2C master device attributes.

Syntax
ErrorCode i2c_master_device_attributes_init(
    struct i2c_master_device_attributes* self,
    regs mmio,
    irq_resource irq);

self - Pointer to I2C master device initialization attributes.

mmio - pointer to I2C master device register space

irq - I2C master device interrupt resource

i2c_master_device_attributes_set_handshake
Description

Sets handshare.

Syntax
void i2c_master_device_attributes_set_handshake(
    struct i2c_master_device_attributes* self,
    uint32_t tx_handshake_line,
    uint32_t rx_handshake_line)
{
    self->tx_handshake_line_ = tx_handshake_line;
    self->rx_handshake_line_ = rx_handshake_line;
}

self - Pointer to I2C master device initialization attributes

tx_handshake_line – Transfer handshake line

rx_handshake_line – Receive handshake line

i2c_master_device_attributes_set_speed
Description

Sets speed.

Syntax
void i2c_master_device_attributes_set_speed(
    struct i2c_master_device_attributes* self,
    i2c_device_speed speed)
{
    self->speed_ = speed;
}

self Pointer to I2C master device initialization attributes.

speed - Speed

i2c_master_device_attributes_set_address_mode
Description

Sets address mode.

Syntax
ErrorCode i2c_master_device_attributes_set_address_mode(
    struct i2c_master_device_attributes* self,
    uint8_t address_mode);

self - Pointer to I2C master device initialization attributes

address_mode – Address mode

i2c_master_device_attributes_set_pin_mux_reg
Description

Sets ping mux reg.

Syntax
ErrorCode i2c_master_device_attributes_set_pin_mux_reg(
    struct i2c_master_device_attributes* self,
    void* pin_mux_reg);

self - Pointer to I2C master device initialization attributes

pin_mux_reg - Pointer to pin muxing global register

i2c_master_device_attributes_set_rx_tl
Description

Sets RX FIFO threshold.

Syntax
ErrorCode i2c_master_device_attributes_set_rx_tl(
    struct i2c_master_device_attributes* self,
    uint8_t rx_tl);

self - Pointer to I2C master device initialization attributes.

rx_tl - FIFO threshold

i2c_master_device_attributes_set_tx_tl
Description

Sets TX FIFO threshold.

Syntax
ErrorCode i2c_master_device_attributes_set_tx_tl(
    struct i2c_master_device_attributes* self,
    uint8_t tx_tl);

self - Pointer to I2C master device initialization attributes.

tx_tl - FIFO threshold

i2c_master_device_attributes_set_sda_hold
Description

Sets sda hold.

Syntax
inline ErrorCode i2c_master_device_attributes_set_sda_hold(
    struct i2c_master_device_attributes* self,
    uint32_t tx_sda,
    uint32_t rx_sda);

self Pointer to I2C master device initialization attributes.

tx_sda - TX SDA hold (unit of one ic_clk period)

rx_sda - RX SDA hold (unit of one ic_clk period)

i2c_master_device_attributes_scl_sdl_auto_recover
Description

Make I2C autonomously recover from SCL stuck at low condition.

Syntax
ErrorCode i2c_master_device_attributes_scl_sdl_auto_recover(
    struct i2c_master_device_attributes* self,
    uint32_t scl_low_timoeout,
    uint32_t sdl_low_timoeout);

self - Pointer to I2C master device initialization attributes.

scl_low_timeout – SCL low timeout

sdl_low_timeout – SDL low timeout

i2c_master_device_init
Description

I2C master device initialization.

Syntax
ErrorCode i2c_master_device_init(
    struct i2c_master_device* self,
    struct i2c_master_device_attributes* attributes);

self - pointer to caller-allocated buffer to store the device object.

attributes - Preconfigured attributes structure which may be discarded after init.

i2c_master_device_make_tx_port
Description

Make TX port.

Syntax
void i2c_master_device_make_tx_port(
    struct i2c_master_device* self,
    struct gpdma_peripheral_port* i2c_gpdma_tx);
i2c_master_device_make_rx_port
Description

Make RX port.

Syntax
void i2c_master_device_make_rx_port(
    struct i2c_master_device* self,
    struct gpdma_peripheral_port* i2c_gpdma_rx);

i2c_master_device_execute

Description

Requests I2C master to execute a transfer workitem.

Syntax
ErrorCode i2c_master_device_execute(
    struct i2c_master_device* self,
    struct i2c_master_device_workitem* workitem);
gpdma_transfer_i2c_xblock_write
Description

Appends register write operation to I2C GP DMA transfer block.

Returns success or error code if given xblock has no capacity to hold requested operation.

Syntax
ErrorCode gpdma_transfer_i2c_xblock_write(
    struct gpdma_transfer_i2c_xblock* self,
    uint8_t value);
gpdma_transfer_i2c_xblock_read
Description

Appends register read operation to I2C transfer.

Returns success or error code if given xblock has no capacity to hold requested operation.

Syntax
ErrorCode gpdma_transfer_i2c_xblock_read(
    struct gpdma_transfer_i2c_xblock* self,
    uint32_t bytes_to_read);
gpdma_transfer_i2c_xblock_get_rx_byte
Description

Get response byte after xblock has been executed.

Returns success or ADSP_NO_MORE_ENTRIES if requested offset is beyond the workitem.

Syntax
ErrorCode gpdma_transfer_i2c_xblock_get_rx_byte(
    struct gpdma_transfer_i2c_xblock* self,
    uint16_t offset,
    uint8_t* value);

self - Pointer to I2C workitem.

offset - Number of read operations for which result should be returned.

value - Pointer of location to store the result.

gpdma_transfer_i2c_xblock_next
Description

Iterates through I2C transfer for result inspection.

Returns:

- ADSP_SUCCESS if entry has been properly fetched,

- ADSP_NO_MORE_ENTRIES end of transfer has been reached.

Syntax
ErrorCode gpdma_transfer_i2c_xblock_next(
    struct gpdma_transfer_i2c_xblock* self,
    uint8_t* operation,
    uint16_t* register_address,
    uint8_t* data);
gpdma_transfer_i2c_xblock_init
Description

Initializes an empty I2C GP DMA transfer block in caller maintained buffer.

Capacity of the xblock results from subtracting xblock header size from the buffer_size and dividing that by size of command (2 bytes).

Returns xblock pointer or NULL on failure

Syntax
struct gpdma_transfer_i2c_xblock* gpdma_transfer_i2c_xblock_init(
         uint32_t buffer_size,
         uint16_t slave_address,
         uint32_t slave_10bit_addr_en,
         pfn_gpdma_transfer_i2c_xblock_done dma_cb_done,
         void* cb_dma_done_context_);

buffer - Buffer to be used.

buffer_size - Size of the buffer.

slave_address – Slave address

cb_done – Callback function

cb_done_context – Context

gpdma_transfer_i2c_init
Description

I2C init.

Syntax
ErrorCode gpdma_transfer_i2c_init(
    struct gpdma_transfer_i2c* self,
    struct i2c_master_device* i2c_master
    );
gpdma_transfer_i2c_enqueue_xblock
Description

I2C enqueue xblock.

Syntax
ErrorCode gpdma_transfer_i2c_enqueue_xblock(
    struct gpdma_transfer_i2c* self,
    struct gpdma_transfer_i2c_xblock* xblock);
gpdma_transfer_i2c_execute
Description

I2C execute.

Syntax
ErrorCode gpdma_transfer_i2c_execute(
    struct gpdma_transfer_i2c* self, gpdma_device* dma);

GPIO

[TBD]

API Definition

Definitions

Constants
Syntax
#define GPIO_PORTA 0
#define GPIO_PORTB 1
#define GPIO_PORTC 2
#define GPIO_PORTD 3
gpio_device_pin_mode
Description

GPIO pin mode.

Syntax
typedef enum {
    GPIO_PIN_MODE_INPUT,
    GPIO_PIN_MODE_OUTPUT
} gpio_device_pin_mode;
gpio_device_pin_level
Description

GPIO pin level.

Syntax
typedef enum {
    GPIO_PIN_LEVEL_LOW,
    GPIO_PIN_LEVEL_HIGH
} gpio_device_pin_level;
gpio_device_pin_irq_mode
Description

Interrupt sensitivity modes for GPIOs.

Syntax
typedef enum {
    GPIO_DEVICE_PIN_NO_IRQ,
    GPIO_DEVICE_PIN_IRQ_LOW,
    GPIO_DEVICE_PIN_IRQ_FALLING,
    GPIO_DEVICE_PIN_IRQ_HIGH,
    GPIO_DEVICE_PIN_IRQ_RISING,
    GPIO_DEVICE_PIN_IRQ_BOTH_EDGE,
} gpio_device_pin_irq_mode;

GPIO_DEVICE_PIN_NO_IRQ - GPIO pin no interrupt mode enabled

GPIO_DEVICE_PIN_IRQ_LOW - GPIO pin interrupt active-low mode

GPIO_DEVICE_PIN_IRQ_FALLING - GPIO pin interrupt falling-edge sensitive mode

GPIO_DEVICE_PIN_IRQ_HIGH - GPIO pin interrupt active-high mode

GPIO_DEVICE_PIN_IRQ_RISING - GPIO pin interrupt rising-edge sensitive mode

GPIO_DEVICE_PIN_IRQ_BOTH_EDGE - GPIO pin interrupt falling and falling edge sensitive mode

gpio_device_pin_attribute
Description

GPIO interrupt callback.

Syntax
typedef void (*pfn_gpio_interrupt)(
    void* context,
    struct gpio_device* gpio,
    uint8_t pin);

Structures

gpio_device_pin_attribute
Description

Initialization attributes of a GPIO pin.

Syntax
typedef void (*pfn_gpio_interrupt)(
    void* context,
    struct gpio_device* gpio,
    uint8_t pin);

struct gpio_device_pin_attribute
{
    uint8_t mode_ : 1;
    uint8_t level_ : 1;
    uint8_t irq_mode_ : 3;
    uint8_t pad_ : 4;
    pfn_gpio_interrupt cb_interrupt_;
    void* cb_interrupt_context_;
};
gpio_device_attributes
Description

GPIO device initialization attributes.

GPIO pin configuration is specified once at initialization according to the needs of particular board design and does not change later.

Structure must be initialized with gpio_device_attributes_init().

Syntax
struct gpio_device_attributes
{
    regs mmio_;
    irq_resource irq_;
    uint8_t ports_num_;
    uint8_t port_width_;
    struct gpio_device_pin_attribute pins_[GPIO_DEVICE_MAX_PORT_NUM][GPIO_DEVICE_MAX_PORT_WIDTH];
};
gpio_device_pin
Description

GPIO device single pin descriptor

Syntax
struct gpio_device_pin
{
    pfn_gpio_interrupt cb_interrupt_;
    void* cb_interrupt_context_;
};
gpio_device
Description

The gpio_device struct.

Syntax
struct gpio_device
{
    struct device_node device_;
    uint8_t ports_num_;
    uint8_t port_width_;
    struct gpio_device_pin pins_[GPIO_DEVICE_MAX_PORT_NUM][GPIO_DEVICE_MAX_PORT_WIDTH];
};

Functions

gpio_device_attributes_init
Description

Initializes GPIO device attributes.

All GPIOs are disabled by default. Use either of

- gpio_device_attributes_set_pin_mode_input(),

- gpio_device_attributes_set_pin_mode_output(),

- gpio_device_attributes_set_pin_mode_interrupt()

to select particular mode on specific GPIOs.

Syntax
ErrorCode gpio_device_attributes_init(
    struct gpio_device_attributes* self,
    regs mmio,
    irq_resource irq);

self - Pointer to GPIO device initialization attributes

mmio - pointer to GPIO device register space

irq - GPIO device interrupt resource

gpio_device_attributes_set_pin_mode_input
Description

Configures a GPIO as input.

Syntax
ErrorCode gpio_device_attributes_set_pin_mode_input(
    struct gpio_device_attributes* self,
    uint8_t port,
    uint8_t pin);

self - Pointer to GPIO device initialization attributes

port - GPIO port to be configured

pin - GPIO pin to be configured

gpio_device_attributes_set_pin_mode_interrupt
Description

Configures a GPIO as interrupt source.

Syntax
ErrorCode gpio_device_attributes_set_pin_mode_interrupt(
    struct gpio_device_attributes* self,
    uint8_t pin,
    pfn_gpio_interrupt interrupt_callback,
    void* interrupt_callback_context,
    gpio_device_pin_irq_mode irq_mode);

self - Pointer to GPIO device initialization attributes

pin - GPIO pin to be configured (PORTA pins support interrupt mode)

interrupt_callback - pointer of function to be called on GPIO interrupt

interrupt_callback_context - User specified context to be passed to interrupt_callback

irq_mode - Specifies kind of GPIO event that triggers interrupt

gpio_device_attributes_set_pin_mode_output
Description

Configures an output mode of GPIO pin.

Syntax
ErrorCode gpio_device_attributes_set_pin_mode_output(
    struct gpio_device_attributes* self,
    uint8_t port,
    uint8_t pin,
    gpio_device_pin_level initial_level);

self - Pointer to GPIO device initialization attributes

port - GPIO port to be configured

pin - GPIO pin to be configured

initial_level – Initial GPIO level

gpio_device_init
Description

GPIO device init function.

Syntax
ErrorCode gpio_device_init(
    struct gpio_device* self,
    struct gpio_device_attributes* attributes);

self - Pointer to GPIO device.

attributes - Preconfigured attributes structure which may be discarded after init.

gpio_device_pin_level gpio_device_pin_get_level
Description

Returns current level on gpio pin.

Syntax
enum gpio_device_irq_status { GPIO_DEVICE_PIN_IRQ_DISABLED, GPIO_DEVICE_PIN_IRQ_ENABLED };
gpio_device_pin_level gpio_device_pin_get_level(
    struct gpio_device* self,
    uint8_t port,
    uint8_t pin);

self - Pointer to GPIO device

port - GPIO port

pin - GPIO pin within port

gpio_device_pin_int_ctrl
Description

GPIO device pin int control.

Syntax
ErrorCode gpio_device_pin_int_ctrl(
    struct gpio_device* self,
    uint8_t pin,
    gpio_device_irq_status status);

self - Pointer to GPIO device

pin - GPIO pin (PORTA pins support interrupt mode)

status - Status

gpio_device_pin_set_output
Description

Set GPIO device pin output.

Syntax
ErrorCode gpio_device_pin_set_output(
    struct gpio_device* self,
    uint8_t port,
    uint8_t pin,
    gpio_device_pin_level level);

self - Pointer to GPIO device

port - GPIO port

pin - GPIO pin within port

level - Level

gpio_device_isr
Description
Syntax
void gpio_device_isr(
    struct gpio_device* self,
    irq_resource irq);

self - Pointer to GPIO device

irq – IRQ resource

UART

[TBD]

Building the Firmware

This section outlines the steps required to build the firmware. It addresses the setup of the host development environment, source code download, and build procedure. The development environment for building the firmware will be Windows. There is no support for Linux at this point.

Prerequisites

  • Access to the quark-audio git repository: https://github.com/otcshare/quark-audio
  • Access to Xtensa Development Environment installation executable: Xplorer-6.0.4-windows-installer.exe
  • Access to X6H3SUE_2016_4_win32.tgz

Setting Up the Development Environment

Install Xtensa Development Environment

1. Install the Xtensa Development Environment by running the self-extracting executable Xplorer-6.0.4-windows-installer.exe Choose the default options.

Set Up the Network Configuration

2. Choose Window → Preferences → General → Network Connections

3. Set any required HTTP/HTTPS Proxy settings.

Create a New Xtensa Configuration

4. Choose File → New → Xtensa Configuration → Install a new build from downloaded bundle as the new configuration

5. Click Next.

6. In the next window, click Browse and select the file X6H3SUE_2016_4_win32.tgz Click Add Build. You should see something like the following picture.


Figure 48. Create New Xtensa Configuration

7. Click Finish. The installer will take some time to complete, as it creates files.

Install the Xtensa License.

8. Choose Help → Xplorer License Keys → License Options → Install License Keys.

9. Insert the <port>@<server> and select Point to the selected license file in its current location.


Figure 49. Install the Xtensa License

Building the Firmware

Download the Source Code

10. Open https://github.com/otcshare/quark-audio

11. Either download or clone the software.

Create a New Project

12. In the Xtensa Development GUI, press <CTRL>+N to create a new Unmanaged Xtensa C/C++ Project. Alternatively, go to File → New → Other → Unmanaged Xtensa C/C++ Project.

13. Set the location to the FW folder in which you cloned or unzipped the software.


Figure 50. Create a New Xtensa Project (1)


Figure 51. Create a New Xtensa Project (2)

Create Make Target

14. Right-click the project and choose Make Targets → Create

15. Enter the target name, as shown in the following figure.


Figure 52. Create a Make Target

Build the Firmware Image

16. Choose Window → Show View → Make Target

17. Select Build Target. It takes about 10 minutes to build the first time.


Figure 53. Build Firmware Image

Firmware Binary

There are three main parts of the Firmware Image Binary:

  • Extended Manifest
  • Manifest
  • Firmware Binaries

Firmware Image Builder processes the content of firmware ELF files into a firmware binary using binmap files. The binmap files describe the layout of the firmware binary and contain information about firmware modules and their properties.

The structure of the binary image is identical for the Base FW and for libraries.


Figure 54. Firmware Binary Build Process

Firmware Image Extended Manifest

Firmware Image Extended Manifest begins with ExtendedManifestHeader followed by array of ExtendedModuleConfig entries.

ExtendedManifestHeader Structure

Syntax
struct ExtendedManifestHeader
{
    uint32_t  ext_manifest_id;
    uint32_t  ext_manifest_len;
    uint16_t  ext_manifest_version_major;
    uint16_t  ext_manifest_version_minor;
    uint32_t  ext_manifest_entries;
};
Members

ext_manifest_id

Extended manifest magic number. Set to “$AE1”.

ext_manifest_len

Size of extended manifest in bytes.

ext_manifest_version_major

Major version of extended manifest structure. Set to 1 for FDK 1.0.

ext_manifest_version_minor

Minor version of extended manifest structure. Set to 0 for FDK 1.0.

ext_manifest_entries

Number of extended manifest module entries.

ExtendedModuleConfig Structure

Each ExtendedModuleConfig structure is followed by array of SchedulingCapabilities and array of PinDescription entries.

Number of entries in the SchedulingCapabilities is specified by num_scheduling_capabilities.

Number of entries in the PinDescription array is specified by num_pin_entries.

Syntax
struct ExtendedModuleConfig
{
    uint32_t    ext_module_config_length;
    uint32_t    guid[4];
    uint16_t    version_major;
    uint16_t    version_minor;
    uint16_t    version_hotfix;
    uint16_t    version_build;
    ModuleType  module_type;
    uint32_t    init_settings_min_size;
    uint32_t    num_scheduling_capabilities;
    uint32_t    num_pin_entries;
};
Members

ext_module_config_length

Size of this extended module config in bytes.

guid

Module GUID.

version_major

Module version major.

version_minor

Module version minor.

version_hotfix

Module version hotfix.

version_build

Module version build.

module_type

Type of the module.

enum ModuleType
{
    BaseFwModule    = 0,
    MixInModule     = 1,
    MixOutModule    = 2,
    CopierModule    = 3,
    PeakVolModule   = 4,
    UpDwMixModule   = 5,
    MuxModule       = 6,
    SrcModule       = 7,
    WovModule       = 8,
    FxModule        = 9,
    AecModule       = 10,
    KpbModule       = 11,
    MicSelectModule = 12
};

init_settings_min_size

Minimum size of initialization settings.

num_scheduling_capabilities

Number of scheduling capabilities entries that follow ExtendedModuleConfig.

num_pin_entries

Number of pin description entries that follow scheduling capabilities array.

SchedulingCapability Structure

Each ExtendedModuleConfig structure is followed by array of SchedulingCapabilities and array of PinDescription entries.

Number of entries in the SchedulingCapabilities is specified by num_scheduling_capabilities.

Number of entries in the PinDescription array is specified by num_pin_entries.

Syntax
struct ExtendedModuleConfig
{
    uint32_t    ext_module_config_length;
    uint32_t    guid[4];
    uint16_t    version_major;
    uint16_t    version_minor;
    uint16_t    version_hotfix;
    uint16_t    version_build;
    ModuleType  module_type;
    uint32_t    init_settings_min_size;
    uint32_t    num_scheduling_capabilities;
    uint32_t    num_pin_entries;
};
Members

ext_module_config_length

Size of this extended module config in bytes.

guid

Module GUID.

version_major

Module version major.

version_minor

Module version minor.

version_hotfix

Module version hotfix.

version_build

Module version build.

module_type

Type of the module.

enum ModuleType
{
    BaseFwModule    = 0,
    MixInModule     = 1,
    MixOutModule    = 2,
    CopierModule    = 3,
    PeakVolModule   = 4,
    UpDwMixModule   = 5,
    MuxModule       = 6,
    SrcModule       = 7,
    WovModule       = 8,
    FxModule        = 9,
    AecModule       = 10,
    KpbModule       = 11,
    MicSelectModule = 12
};

init_settings_min_size

Minimum size of initialization settings.

num_scheduling_capabilities

Number of scheduling capabilities entries that follow ExtendedModuleConfig.

num_pin_entries

Number of pin description entries that follow scheduling capabilities array.

SchedulingCapability Structure

Syntax
struct SchedulingCapabilities
{
    uint16_t   frame_length;
    Multiples  multiples_supported;
};
Members

frame_length

Input frame length in Samples (sample groups).

multiples_supported

Supported frame length multiples.

Multiples Structure
Syntax
struct Multiples
{
    uint16_t x1 : 1;   // (base * 1)
    uint16_t x2 : 1;   // (base * 2)
    uint16_t x3 : 1;   // (base * 3)
    uint16_t x4 : 1;   // (base * 4)
    uint16_t x5 : 1;   // (base * 5)
    uint16_t x6 : 1;   // (base * 6)
    uint16_t x7 : 1;   // (base * 7)
    uint16_t x8 : 1;   // (base * 8)
    uint16_t x9 : 1;   // (base * 9)
    uint16_t x10 : 1;  // (base * 10)
    uint16_t x11 : 1;  // (base * 11)
    uint16_t x12 : 1;  // (base * 12)
    uint16_t x13 : 1;  // (base * 13)
    uint16_t x14 : 1;  // (base * 14)
    uint16_t x15 : 1;  // (base * 15)
    uint16_t all : 1;  // (base * X)
};

PinDescription Structure

Syntax
struct PinDescription
{
    PinCapabilities        capabilities;
    StreamType             format_type;
    SampleRates            supported_sample_per_second;
    SampleSizes            supported_valid_bits_per_samples;
    SampleContainers       supported_container_per_samples;
    ChannelConfigurations  supported_number_channels;
};
Members

capabilities

Pin capabilities.

format_type

Supported stream type.

enum StreamType
{
    Pcm = 0,
    Mp3 = 1,
    Aac = 2
};

supported_sample_per_second

Supporter sample rates.

struct SampleRates
{
    uint32_t freq_8000   : 1;
    uint32_t freq_11500  : 1;
    uint32_t freq_12000  : 1;
    uint32_t freq_16000  : 1;
    uint32_t freq_18900  : 1;
    uint32_t freq_22050  : 1;
    uint32_t freq_24000  : 1;
    uint32_t freq_32000  : 1;
    uint32_t freq_37800  : 1;
    uint32_t freq_44100  : 1;
    uint32_t freq_48000  : 1;
    uint32_t freq_64000  : 1;
    uint32_t freq_88200  : 1;
    uint32_t freq_96000  : 1;
    uint32_t freq_176400 : 1;
    uint32_t freq_192000 : 1;
    uint32_t reserved_   : 16;
};

supported_valid_bits_per_samples

Supported valid bits per sample.

struct SampleSizes
{
    uint16_t bits_8    : 1;
    uint16_t bits_16   : 1;
    uint16_t bits_24   : 1;
    uint16_t bits_32   : 1;
    uint16_t bits_64   : 1;
    uint16_t reserved_ : 11;
};

supported_container_per_samples

Supported bits per container.

typedef SampleContainers
{
    uint16_t bits_8    : 1;
    uint16_t bits_16   : 1;
    uint16_t bits_32   : 1;
    uint16_t bits_64   : 1;
    uint16_t reserved_ : 12;
};

supported_number_channels

Supported channel configuration.

struct ChannelConfigurations
{
    // FRONT_CENTER
    uint32_t channel_mono : 1;
    
    // FRONT_LEFT | BACK_LEFT
    uint32_t channel_dual_mono : 1;

    // FRONT_LEFT | FRONT_RIGHT
    uint32_t channel_stereo : 1;

    // FRONT_LEFT | FRONT_RIGHT | LOW_FREQUENCY
    uint32_t channel_2_1 : 1;

    // FRONT_LEFT | FRONT_RIGHT | FRONT_CENTER
    uint32_t channel_3_0 : 1;

    // FRONT_LEFT | FRONT_RIGHT | BACK_LEFT  | BACK_RIGHT
    uint32_t channel_quad : 1;

    // FRONT_LEFT | FRONT_RIGHT | FRONT_CENTER | BACK_CENTER
    uint32_t channel_surround : 1;

    // FRONT_LEFT | FRONT_RIGHT | FRONT_CENTER | LOW_FREQUENCY
    uint32_t channel_3_1 : 1;

    // FRONT_LEFT | FRONT_RIGHT | FRONT_CENTER 
    //  | BACK_LEFT | BACK_RIGHT
    uint32_t channel_5_0 : 1;

    // FRONT_LEFT | FRONT_RIGHT | FRONT_CENTER
    //  | SIDE_LEFT | SIDE_RIGHT
    uint32_t channel_5_0_surround : 1;

    // FRONT_LEFT | FRONT_RIGHT | FRONT_CENTER
    //  | LOW_FREQUENCY | BACK_LEFT | BACK_RIGHT
    uint32_t channel_5_1 : 1;

    // FRONT_LEFT | FRONT_RIGHT | FRONT_CENTER
    //  | LOW_FREQUENCY | SIDE_LEFT | SIDE_RIGHT
    uint32_t channel_5_1_surround : 1;

    // FRONT_LEFT | FRONT_RIGHT | FRONT_CENTER
    //  | BACK_LEFT | BACK_RIGHT | FRONT_LEFT_OF_CENTER
    //  | FRONT_RIGHT_OF_CENTER
    uint32_t channel_7_0 : 1;

    // FRONT_LEFT | FRONT_RIGHT | FRONT_CENTER
    //  | BACK_LEFT | BACK_RIGHT | SIDE_LEFT | SIDE_RIGHT
    uint32_t channel_7_0_surround : 1;

    // FRONT_LEFT | FRONT_RIGHT | FRONT_CENTER
    //  | LOW_FREQUENCY | BACK_LEFT | BACK_RIGHT
    //  | FRONT_LEFT_OF_CENTER | FRONT_RIGHT_OF_CENTER
    uint32_t channel_7_1 : 1;	

    // FRONT_LEFT | FRONT_RIGHT | FRONT_CENTER
    //  | LOW_FREQUENCY | BACK_LEFT | BACK_RIGHT
    //  | SIDE_LEFT | SIDE_RIGHT
    uint32_t channel_7_1_surround : 1;

    uint32_t reserved_ : 16;
};

PinCapabilities Structure

Syntax
struct PinCapabilities
{
    uint16_t  direction : 1;
    uint16_t  reserved_ : 15;
};
Members

direction

Specifies direction of the pin, either

input (0),

output (1).

Firmware Image Manifest

This section documents the layout of the Firmware Image Manifest. The layout of the firmware image binary and the layout of the top-level firmware image manifest structures are platform-specific. However, most structures are common for all platforms. Therefore, this section contains both common and platform-specific subsections.

Firmware Image Layout

The firmware image binary for audio DSP begins with {TBD} followed by the AdspFwBinaryHeader structure that begins area the relevant for the management service.

AdspFwBinaryHeader can be found at offset 0x2000 in the image binary file.

Common Structures

AdspFwBinaryHeader Structure

Syntax
struct AdspFwBinaryHeader
{
    uint32_t    header_id;
    uint32_t    header_len;
    uint8_t     name[8];
    uint32_t    preload_page_count;
    FwImgFlags  fw_image_flags;
    uint32_t    feature_mask;
    uint16_t    major_version;
    uint16_t    minor_version;
    uint16_t    hotfix_version;
    uint16_t    build_version;
    uint32_t    num_module_entries;
    uint32_t    hw_buf_base_addr;
    uint32_t    hw_buf_length;
    uint32_t    load_offset;
};
Members

header_id

Set to “$AM1”,

header_len

Set to sizeof(AdspFwBinaryHeader) in bytes; using this value, ROM knows where the Module Entry array starts even if structure was altered after ROM release,

name

Set to the name of the image; this field is not used by the ROM,

preload_page_count

Size of the beginning of binary that should be loaded by the management service.

It is set to:

  • Main image:
    • Total size of the binary’s .text and .rodata
  • Library image:
    • Total size of the library’s .text and .rodata

fw_image_flags

Contains firmware Image flags set by the Firmware Image Builder.

feature_mask

Set to the mask of features provided by the firmware image.

major_version, minor_version, hotfix_version, and build_version

Updated by the build system.

num_module_entries

Set to number of entries in the module_entries array.

hw_buf_base_addr

Set to the base address of HW buffers area.

hw_buf_len

Set to the length of the HW buffers area.

Remarks

Even after a ROM release, the layout of the structure may be modified only within the part that starts after the num_module_entries field. This part is skipped by the ROM, and the ROM uses header_len to detect the actual structure size.

ModuleEntry Structure

Syntax
struct ModuleEntry
{
    uint32_t    struct_id;
    uint8_t     name[8];
    uint32_t    uuid[4];
    ModuleType  type;
    uint8_t     hash[DEFAULT_HASH_SHA256_LEN];
    uint32_t    entry_point;
    uint16_t    cfg_offset;
    uint16_t    cfg_count;
    uint32_t    affinity_mask;
    uint16_t    instance_max_count;
    uint16_t    instance_bss_size;
    SegmentDesc segments[3];
};
Members

struct_id

Set to “$AME”.

name

Set to text identifier of the module. This field is not interpreted by firmware. It is used currently only to improve readability of the manifest binary.

uuid

Set to a unique identifier. This field is not used by firmware.

type

See ModuleType structure.

hash

Set to SHA-256 hash of the content of all loadable module segments declared in segments.

entry_point

Set to address of module’s entry point.

cfg_offset

Set to index of entry in module_config that begins sub array of configuration entries associated with the module. Firmware does not use this field as the configuration is always received from the management service as part of Init Module Instance IPC message.

cfg_count

Set to count of configuration entries in sub array of configuration entries associated with the module. Firmware does not use this field.

affinity_mask

Set to mask of cores that the module is allowed to run on. i-th bit in the mask set to 1 means that instances of this module are allowed to run on Core i.

instance_max_count

Maximum number of instances.

instance_bss_size

Maximum size (in 4KB pages) of .bss that may be allocated by a single module instance. Actual size of .bss may be smaller and depends on module instance configuration. Total .bss segment size set in 2-nd entry of segments array must be set to instance_max_count * instance_bss_size to be consistent.

segments

Contains descriptors for all module’s segments.

ModuleType Structure

Syntax
struct ModuleType
{
    uint32_t  load_type   : 4;
    uint32_t  auto_start  : 1;
    uint32_t  domain_ll   : 1;
    uint32_t  domain_dp   : 1;
    uint32_t  lib_code    : 1;
    uint32_t  rsvd_       : 24;
};
Members

load_type

Indicates built-in module (0) or loadable (1).

auto_start

Indicates whether a module instance of the module should be created automatically (with no parent pipeline attached) at the Base FW startup.

domain_ll

Indicates whether a module instance can be executed in LL domain.

domain_dp

Indicates whether a module instance can be executed in DP domain.

lib_code

Indicates whether a module serves as a container for library code. Such a module is loaded by the management service but cannot be instantiated. There is no entry point defined neither other instance properties.

SegmentDesc Structure

Syntax
struct SegmentDesc
{
    SegmentFlags    flags;
    uint32_t        v_base_addr;
    uint32_t        file_offset;
};

union SegmentFlags
{
    uint32_t    ul;
    struct
    {
        uint32_t    contents  : 1;
        uint32_t    alloc     : 1;
        uint32_t    load      : 1;
        uint32_t    readonly  : 1;
        uint32_t    code      : 1;
        uint32_t    data      : 1;
        uint32_t    _rsvd0    : 2;

        uint32_t    type      : 4;
        uint32_t    _rsvd1    : 4;

        uint32_t    length    : 16;
    } r;
};
Members

flags.type

Set to type of segment. One of ST_TEXT (0), ST_RODATA (1), or ST_BSS (2). Since .text segment is expected to be described by the first entry, .rodata is expected to be described by the second entry and so on, the type value should equal the index of entry in segments array.

flags.length

Length of segment in pages. Page size is 4KB.

v_base_addr

Set to virtual address of segment.

ModuleConfig Structure

Syntax
struct ModuleConfig
{
    uint32_t    par[4];
    uint32_t    is_pages;
    uint32_t    cps;
    uint32_t    ibs;
    uint32_t    obs;
    uint32_t    module_flags;
    uint32_t    cpc;
    uint32_t    obls;
};
Members

par

Configuration lookup parameters used by the management service [if exists].

is_pages

Number of bytes (not pages as the historical name suggests) required by the module instance if configured by this set of parameters.

cps

Number of DSP cycles consumed by the module instance to process one second of data.

ibs

Input buffer size expressed in sample groups (a sample group is a set of samples for all channels, for example, for 48kHz stereo signal there are 48 sample groups per millisecond and 96 samples per millisecond).

In case of modules that are instantiated in LL domain or designed to work with 1ms based frame size ibs is set to 1.

obs

Output buffer size expressed in sample groups.

module_flags

Reserved for future use.

cpc

Number of DSP cycles required to process chunk of data of ibs size.

obls

Output block size (reserved for future use).

Firmware Builder Input Files

The firmware builder reads the description of the layout of the firmware binary image from binmap-s.

This section documents the format of the binmap files.

Number Format

All number values in binmaps are specified in hex form (without the leading 0x) for parameters of mod_cfg entries, which are specified in decimal form.

Binmap Preprocessing

Comments

Binmap files may include single line comments put in a line that begins with #. The binmap preprocessor skips these lines.

Example

# This is a single line comment.

Includes

A binmap may use the include directive to include another binmap.

Syntax

include <another_binmap_file_path>

The file path may be either relative or absolute. The former approach is recommended to make the binmaps OS independent.

Example

include <another_binmap_file_path>

Defines

A binmap may define an identifier and assign a value to it.

Syntax

define <identifier> <value>

Example

define $PLATFORM SKU2

Binmap Processing

Numbers

All numbers, except for module configuration entries, should be specified in hexadecimal form (without the leading 0x specifier).

Strings

No quotes are used in a string specification. A multiword string containing spaces is read till the end of the line.

Example

# Pretty name of the module (“Up Down Mixer”)
name Up Down Mixer

Structure of Binmap

ADSP Binary Header Data

Syntax

binary_name <name>

Pretty name of the binary, max 8 characters long.

binary_ver 1.5|1.8

Version of the binary manifest and layout.

hw_buf_ba <base address>

Base address of HW buffers section in DSP memory.

This item is valid for 1.5 version only.

hw_buf_size <size in bytes>

Size of HW buffers section.

This item is valid for 1.5 version only.

max_data <size in bytes>

Maximum size of .data section that may be present in the input firmware ELF image.

This option should be used only for debug purpose when linking experimental, not fully-compliant code, as the .data section is not included in the output binary and is not loaded to the target DSP memory.

This parameter must be set to 0 for production image.

dyn_mem <section name>

Specifies a section defined by the input ELF file that has no content and is dynamically allocated by the firmware. This is so the address space assigned for that section is not included in any module’s address space. However, it is included in the computation of virtual memory area reserved for the image (the result of the computation is written by the builder to the PKG file).

Example

binary_name ADSPFW
binary_ver 1.5
hw_buf_ba be050000
hw_buf_size 4a000
max_data 0

Module Entry & Module Config Data

Specification of each module entry begins with general parameters followed by:

  • A list of section groups that delivers data for ModuleEntry::segments[]
  • A list of input and output pins and their capabilities
  • Module configuration entries that deliver data for the module configuration table
Syntax

module <depl_type> <short_name>

This keyword begins a new section for each module.

<depl_type> specifies deployment type of the module, it is one of (see also Remarks):

b – Built-in module

d – Discrete mandatory module

o – Discrete optional module

l – Internal module in a library, contains library code and is never instantiated (does not have entry point defined and so on). Such a module serves as a container for section groups and does not need any of other module parameters listed below. Builder sets ModuleType::lib_code bit to 1 for this kind of module.

<short_name> specifies a short name of the module that appears in the FM Image Manifest, max 8 characters long.

uuid <uuid_value>

Unique identifier of the module (known also as GUID in Windows documentation).

name <pretty_name>

Pretty name of the module. It does not appear in the Firmware Image Manifest.

ver <ver_string>

Version of the module. It does not appear in the Firmware Image Manifest.

This item is optional.

type <mod_func_type>

Functional type of the module, one of:

  • BaseFwModule  (0),
  • MixInModule  (1),
  • MixOutModule  (2),
  • CopierModule  (3),
  • PeakVolModule  (4),
  • UpDwMixModule  (5),
  • MuxModule  (6),
  • SrcModule  (7),
  • WovModule  (8),
  • FxModule   (9),
  • AecModule  (10),
  • KpbModule  (11),
  • MicSelectModule  (12).

Note: Constants should be defined in a common binmap file included by platform-specific binmaps.

Note: This information goes to the extended manifest.

affinity_mask <mask_value>

Specifies indexes of cores that the module is allowed to run on.

bit[i] set to 1 means that the module is allowed to run on core #i.

instance_count <count>

Specifies maximum number of instances of the module.

stack_size <size_in_bytes>

Specifies required stack size.

This item is mandatory for modules that have DP specified as one of the domain_types.

Remarks

The module <type> determines how the builder processes section group information found in the binmap and in the input ELF files.

See Section Group for more information.

Sections of built-in modules are expected to be specified inside Base FW section groups.

Example

module d XAMAXXAU
uuid B489C2DE-0F96-42E1-8A2D-C25B5091EE49
name Waves Maxx Audio
ver 5.9
affinity_mask 3
instance_count 2
stack_size 1000

Section Group

There are three segments defined by each module in the ModuleEntry::segments[] array in the FM Image Manifest:

  • .text – containing the module’s code
  • .rodata – containing the module’s read-only data
  • .bss – containing module instances’ persistent and scratch data at run-time

Each section is allocated in the DSP memory based on the properties of sections delivered by the input ELF file. Those sections are aggregated by the section groups defined in the binmap.

Usually there are three section groups defined for each module (one per manifest segment), except for built-in modules. For built-in modules, only the text section should be specified, containing only one section with the ep attribute set.

All sections specified by a group belonging to a discrete mandatory module must be present in the input ELF file, while sections specified by an optional module are optional.

Note Any loadable section defined by the input ELF files must be referred by either a section or ignore entry, or else the building process fails with an error.

Syntax

group text|rodata|bss

Begins section group of specified category.

section [ep] <section_name>

Specifies a section.

ep This optional attribute, valid only for a section within text group indicates that beginning address of the section is a module’s entry point.

<section_name> Specifies section name as defined by the input ELF file.

ignore <section_name>

This keyword may be used instead of section to indicate that ELF defined section named <section_name> should be ignored by the builder. This reference helps the builder to determine that the section was skipped intentionally.

Example

module d XAMAXXAU
uuid B489C2DE-0F96-42E1-8A2D-C25B5091EE49
name Waves Maxx Audio
ver 5.9
affinity_mask 3
instance_count XAMAXXAU_AUDIO_MAX_INSTANCE
stack_size 1000
group text
section .xa_maxx_audio.text
section ep .xa_maxx_audio.cmi.text
group rodata
section .xa_maxx_audio.rodata
group bss
section .xa_maxx_audio.noload

Scheduling Capability

Scheduling capability entry is the primary source of information about the size of the module’s processing frame. IBS and OBS parameters that are part of module config entries are made obsolete by the scheduling capability.

Syntax

sched_caps <frame_size> <list_of_multiples>

Specifies a scheduling capability of the module instance.

<frame_size> Specifies size of the input frame in Samples (sample groups).

<list_of_multiples> Specifies allowed multiples of the frame size, one of (as currently mapped to numeric values by the common binmaps part):

  • x1 .. x15
  • all

Pin

Syntax

pin <direction>

This keyword begins a new section for a pin that is exposed by the parent module.

<direction> is either:

  • in (0),
  • out (1).

Note: Constants to be defined in a common binmap.

stream_type <type>

<type> is either:

  • pcm (0),
  • mp3 (1),
  • aac (2).

Note: Constants to be defined in a common binmap.

sample_rates <list_of_supported_sample_rates>

<list_of_supported_sample_rates> is one or more of:

  • 8k  (0x00000001),
  • 11.025k  (0x00000002),
  • 12k  (0x00000004),
  • 16k  (0x00000008),
  • 18.9k  (0x00000010),
  • 22.05k  (0x00000020),
  • 24k  (0x00000040),
  • 32k  (0x00000080),
  • 37.8k  (0x00000100),
  • 44.1k  (0x00000200),
  • 48k  (0x00000400),
  • 64k  (0x00000800),
  • 88.2k  (0x00001000),
  • 96k  (0x00002000),
  • 176.4k  (0x00004000),
  • 192k  (0x00008000).

Note: Constants to be defined in a common binmap.

sample_sizes <list_of_supported_sample_sizes>

<list_of_supported_sample_sizes> is one or more of:

  • sample_8b  (0x00000001),
  • sample_16b  (0x00000002),
  • sample_24b  (0x00000004),
  • sample_32b  (0x00000008),
  • sample_64b  (0x00000010).

Note: Constants to be defined in a common binmap.

sample_containers <list_of_supported_sample_containers>

<list_of_supported_sample_containers> is one or more of:

  • container_8b  (0x00000001),
  • container_16b  (0x00000002),
  • container_32b  (0x00000004),
  • container_64b  (0x00000008).

Note: Constants to be defined in a common binmap.

channel_cfg <list_of_supported_channel_configurations>

<list_of_supported_channel_configurations> is one or more of:

  • ch_mono  (0x00000001),
  • ch_dual_mono  (0x00000002),
  • ch_stereo  (0x00000004),
  • ch_2_1  (0x00000008),
  • ch_3_0  (0x00000010),
  • ch_quad  (0x00000020),
  • ch_surround  (0x00000040),
  • ch_3_1  (0x00000080),
  • ch_5_0  (0x00000100),
  • ch_5_0_surround  (0x00000200),
  • ch_5_1  (0x00000400),
  • ch_5_1_surround  (0x00000800),
  • ch_7_0  (0x00001000),
  • ch_7_0_surround  (0x00002000),
  • ch_7_1  (0x00004000),
  • ch_7_1_surround  (0x00008000).

Note: Constants to be defined in a common binmap.

Example

pin in
stream_type pcm
sample_rates 8k 16k 44.1k 48k
sample_sizes 16 32
sample_containers 16 32
channel_cfg ch_mono ch_stereo ch_5_1

Module Config

For detailed documentation, see Section “Firmware Image Manifest” and the ModuleConfig structure documentation.

Syntax

mod_cfg <par_0> <par_1> <par_2> <par3> <is_pages> <cps> <ibs> <obs> <mod_flags> <cpc> <obls>

JTAG Debugging

This section describes how to connect a JTAG probe to Quark S1000 CRB for debugging.

HW:

 The recommended probe is USB Wiggler  from Macraigor systems. 

Select the following configuration while ordering this part.

SW Tools:

  • Tensilica  Xtensa OCD deamon version 12.0.3 is needed to enable JTAG debugging.  Run xt-ocd-12.0.3-windows-installer.exe installer package which will unpack this to c:\Program Files (x86)\Tensilica\Xtensa OCD Daemon 12.0.3
  • JTAG configuration scripts available at ../quark_audio/scripts/SueOCDScripts

Connection Between CRB and USB Wiggler

The table below shows the pin mappings of CRB JTAG header and USB wiggler header as a reference.

PIN CRB USB Wiggler  
JTAG_TCK 1 5 TCK
JTAG_TMS 2 10 TMS
JTAG_TDI 3 1 TDI
JTAG_TRST 4 14 TRST
JTAG_TDO 5 3 TDO
  6    
V1P8A 7 11 TVcc
GND 8 2 GND

Set Up and Configuration


Xplorer and OCD Deamon on the Host processor

Procedure:

  • Install Xtensa OCD Daemon 12.0.3 on your PC (run xt-ocd-12.0.3-windows-installer.exe)
  • Connect usbWiggler to CRB  and to USB port of PC workstation as shown in the diagram above
  • Copy provided topology and initialization script files (these are available under ../quark_audio/scripts/SueOCDScripts directory to xt-ocd target directory: c:\Program Files (x86)\Tensilica\Xtensa OCD Daemon 12.0.3
  •  Start cmd, go to xt-ocd root directory
  • Connect to  Raspberry Pi Terminal  and change the directory to where the quark_audio/scrtips directory is copied.,
  • load fw using python script on Raspberry Pi. For example: python3.5 test_load_fw_spi.py –f ./dsp_fw_sue_release_loadable.img  --board crb . This will load the FW.
  • from PC’s cmd run: xt-ocd.exe –c topology_sue_dsp0.xml –I dsp0_gdb.txt  xt-ocd exposes socket port 80, configurable in topology file: <application id='GDBStub0' module='gdbstub' port='80'>. xt-gdb connects to xt-ocd over TCP/IP.  If everything is successful, you will find something like this

  • Run Xtensa Xplorer
  • Create a new project, if it does not existing as describled in the build FW section. Expand Binaries in Project Explorer view. Right click dsp_fw_sue_release, choose Debug As, Debug configurations… This will open Debug Configuration window.
  • Right click Xtensa OnChip Debug → New Provide xt-ocd’s PC workstation IP address in Target → Host Name
  • Choose core0: ${xt_project}
  • Click Select next to the Project: input, choose your project name
  • Click Select next to C/C++ Application:, choose dsp_fw_sue_release
  • Expand Advanced options Set GDB Port to 80
  • Click Debug
  • Download binary window popups, click No choosing to attach to target without restart
  • Click pause (suspend) icon in Debug view to confirm Xplorer IDE is attached to the target
  • For further description please refer to Cadence Xtensa Debug Guide document.