Common Audio Processing (CAPI) Interfaces

capi.h

Common Audio Processing Interface v2 header file.

This file defines a generalized C interface that can wrap a wide variety of audio processing modules, so that they can be treated the same way by control code.

Copyright (c) Qualcomm Innovation Center, Inc. All Rights Reserved. SPDX-License-Identifier: BSD-3-Clause

Typedefs

typedef struct capi_t capi_t
typedef struct capi_vtbl_t capi_vtbl_t
typedef capi_err_t (*capi_get_static_properties_f)(capi_proplist_t *init_set_proplist, capi_proplist_t *static_proplist)

Queries for properties as follows:

  • Static properties of the module that are independent of the instance

  • Any property that is part of the set of properties that can be statically queried

Errors that occur when setting or getting a property must be handled in the following way:

  • If the property is not supported by the module, the CAPI_EUNSUPPORTED flag must be set in the error code and the actual_data_len field for that property must be set to zero.

  • The rest of the properties must still be processed (rather than exiting when an unsupported property is encountered).

Associated data types

capi_proplist_t

Detailed description

This function is used to query the memory requirements of the module to create an instance. The function must fill in the data for the properties in the static_proplist.

As an input to this function, the client must pass in the property list that it passes to capi_init_f(). The module can use the property values in init_set_proplist to calculate its memory requirements.

The same properties that are sent to the module in the call to capi_init_f() are also sent to this function to enable the module to calculate the memory requirement.

Error code — Failure (see Section)

Dependencies

None.

Param init_set_proplist:

[in] Pointer to the same properties that are sent in the call to capi_init_f().

Param static_proplist:

[out]

Pointer to the property list structure.

The client fills in the property IDs for which it needs property values. The client also allocates the memory for the payloads. The module must fill in the information in this memory.

Return:

CAPI_EOK — Success

typedef capi_err_t (*capi_init_f)(capi_t *_pif, capi_proplist_t *init_set_proplist)

Instantiates the module to set up the virtual function table, and also allocates any memory required by the module.

Associated data types

capi_t capi_proplist_t

Detailed description

States within the module must be initialized at the same time.

For any unsupported property ID passed in the init_set_proplist parameter, the function prints a message and continues processing other property IDs.

All return codes returned by this function, except CAPI_EOK, are considered to be FATAL.

Error code — Failure (see Section)

Dependencies

None.

Param _pif:

[inout]

Pointer to the module object.

The memory has been allocated by the client based on the size returned in the

CAPI_INIT_MEMORY_REQUIREMENT property.

Param init_set_proplist:

[in] Pointer to the properties set by the service to be used while initializing.

Return:

CAPI_EOK — Success

struct capi_vtbl_t
#include <capi.h>

Function table for plain C implementations of CAPI-compliant objects.

Objects must have a pointer to a function table as the first element in their instance structure. This structure is the function table type for all such objects.

Public Members

capi_err_t (*process)(capi_t *_pif, capi_stream_data_t *input[], capi_stream_data_t *output[])

Generic function that processes input data on all input ports and provides output on all output ports.

Associated data types

capi_t capi_stream_data_t

Detailed description

On each call to capi_vtbl_t::process(), the behavior of the module depends on the value it returned for the CAPI_REQUIRES_DATA_BUFFERING property. For a description of the behavior, see the comments for CAPI_REQUIRES_DATA_BUFFERING.

No debug messages are allowed in this function.

Modules must make a NULL check for the following and use them only if they are not NULL:

For some events that result from a capi_vtbl_t::process() call, the output buffer must not be filled. Check the event definition for this restriction.

Error code — Failure (see Section)

Dependencies

A valid input media type must have been set on each input port using the CAPI_INPUT_MEDIA_FORMAT property.

Param _pif:

[inout] Pointer to the module object.

Param input:

[inout]

Array of pointers to the input data for each input port.

The length of the array is the number of input ports. The client sets the number of input ports using the

CAPI_PORT_NUM_INFO

property.

The function must modify the actual_data_len field to indicate how many bytes were consumed.

Depending on stream_data_version (in capi_stream_flags_t), the actual structure can be a version of capi_stream_data_t (like capi_stream_data_t or capi_stream_data_v2_t

).

Some elements of input[] can be NULL. This occurs when there is mismatch between

CAPI_PORT_NUM_INFO and the currently active ports. NULL elements must be ignored.

Param output:

[out]

Array of pointers to the output data for each output port.

The client sets the number of output ports using the

CAPI_PORT_NUM_INFO

property.

The function sets the actual_data_len field to indicate how many bytes were generated.

Depending on stream_data_version (in capi_stream_flags_t), the actual structure can be a version of capi_stream_data_t (like capi_stream_data_t or capi_stream_data_v2_t

).

For single input/single output modules, the framework typically assigns the output flags, timestamp, and metadata with input flags, timestamp, and metadata before calling process. Metadata is only available in

capi_stream_data_v2_t

and later.

If the module has delay, it must reset the output

capi_stream_data_t (or capi_stream_data_v2_t

) and set it back after the delay is over.

Some elements of output[] can be NULL. This occurs when there is mismatch between

CAPI_PORT_NUM_INFO and the currently active ports. NULL elements must be ignored.

Return:

CAPI_EOK — Success

capi_err_t (*end)(capi_t *_pif)

Frees any memory allocated by the module.

After calling this function, _pif is no longer a valid CAPI object. Do not call any CAPI functions after using it.

Associated data types

capi_t

Error code — Failure (see Section)

Dependencies

None.

Param _pif:

[inout] Pointer to the module object.

Return:

CAPI_EOK — Success

capi_err_t (*set_param)(capi_t *_pif, uint32_t param_id, const capi_port_info_t *port_info_ptr, capi_buf_t *params_ptr)

Sets a parameter value based on a unique parameter ID.

Associated data types

capi_t capi_port_info_t capi_buf_t

Detailed description

The actual_data_len field of the parameter pointer must be at least the size of the parameter structure. Therefore, the following check must be performed for each tuning parameter ID: 

if (params_ptr->actual_data_len >= sizeof(gain_struct_t))
{
:
:
}
else
{
MSG_1(MSG_SSID_QDSP6, DBG_ERROR_PRIO,"CAPI Libname Set, Bad param size
%lu",params_ptr->actual_data_len);
return AR_ENEEDMORE;
}

Optionally, some parameter values can be printed for tuning verification.

In this code sample, gain_struct is an example only. Use the correct structure based on the parameter ID.

Error code — Failure (see Section)

Dependencies

None.

Param _pif:

[inout] Pointer to the module object.

Param param_id:

[in] ID of the parameter whose value is to be set.

Param port_info_ptr:

[in]

Pointer to the information about the port on which this function must operate.

If a valid port index is not provided, the port index does not matter for the param_id, the param_id is applicable to all ports, or the port index might be part of the parameter payload.

Param params_ptr:

[in]

Pointer to the buffer containing the value of the parameter.

The format of the data in the buffer depends on the implementation.

Return:

CAPI_EOK — Success

capi_err_t (*get_param)(capi_t *_pif, uint32_t param_id, const capi_port_info_t *port_info_ptr, capi_buf_t *params_ptr)

Gets a parameter value based on a unique parameter ID.

Associated data types

capi_t capi_port_info_t capi_buf_t

Detailed description

The max_data_len field of the parameter pointer must be at least the size of the parameter structure. Therefore, the following check must be performed for each tuning parameter ID. 

if (params_ptr->max_data_len >= sizeof(gain_struct_t))
{
:
:
}
else
{
MSG_1(MSG_SSID_QDSP6, DBG_ERROR_PRIO,"CAPI Libname Get, Bad param size
%lu",params_ptr->max_data_len);
return AR_ENEEDMORE;
}

Before returning, the actual_data_len field must be filled with the number of bytes written into the buffer.

Optionally, some parameter values can be printed for tuning verification.

In this code sample, gain_struct is an example only. Use the correct structure based on the parameter ID.

Error code — Failure (see Section)

Dependencies

None.

Param _pif:

[inout] Pointer to the module object.

Param param_id:

[in] Parameter ID of the parameter whose value is being passed in this function. For example:

  • CAPI_LIBNAME_ENABLE

  • CAPI_LIBNAME_FILTER_COEFF

Param port_info_ptr:

[in]

Pointer to the information about the port on which this function must operate.

If the port index is invalid, either the port index does not matter for the param_id, the param_id is applicable to all ports, or the port information might be part of the parameter payload.

Param params_ptr:

[out] Pointer to the buffer to be filled with the value of the parameter. The format depends on the implementation.

Return:

CAPI_EOK — Success

capi_err_t (*set_properties)(capi_t *_pif, capi_proplist_t *proplist_ptr)

Sets a list of property values. Optionally, some property values can be printed for debugging.

Errors that occur when setting or getting a property must be handled in the following way:

  • If the property is not supported by the module, the CAPI_EUNSUPPORTED flag must be set in the error code and the actual_data_len field for that property must be set to zero.

  • The rest of the properties must still be processed (rather than exiting when an unsupported property is encountered).

Associated data types

capi_t capi_proplist_t

Error code — Failure (see Section)

Dependencies

None.

Param _pif:

[inout] Pointer to the module object.

Param proplist_ptr:

[in] Pointer to the list of property values.

Return:

CAPI_EOK — Success

capi_err_t (*get_properties)(capi_t *_pif, capi_proplist_t *proplist_ptr)

Gets a list of property values.

Errors that occur when setting or getting a property must be handled in the following way:

  • If the property is not supported by the module, the CAPI_EUNSUPPORTED flag must be set in the error code and the actual_data_len field for that property must be set to zero.

  • The rest of the properties must still be processed (rather than exiting when an unsupported property is encountered).

Associated data types

capi_t capi_proplist_t

Error code — Failure (see Section)

Dependencies

None.

Param _pif:

[inout] Pointer to the module object.

Param proplist_ptr:

[out]

Pointer to the list of empty structures that must be filled with the appropriate property values, which are based on the property IDs provided.

The client must fill some elements of the structures as input to the module. These elements must be explicitly indicated in the structure definition.

Return:

CAPI_EOK — Success

struct capi_t
#include <capi.h>

Plain C interface wrapper for the virtual function table, capi_vtbl_t.

This capi_t structure appears to the caller as a virtual function table. The virtual function table in the instance structure is followed by other structure elements, but those are invisible to the users of the CAPI object. This capi_t structure is all that is publicly visible.

Public Members

const capi_vtbl_t *vtbl_ptr

Pointer to the virtual function table.

capi_types.h

This file defines the basic data types for the Common Audio Processing Interface.

Copyright (c) Qualcomm Innovation Center, Inc. All Rights Reserved. SPDX-License-Identifier: BSD-3-Clause

Defines

CAPI_INVALID_VAL
CAPI_EOK

Success. The operation completed with no errors.

CAPI_EFAILED

General failure.

CAPI_EBADPARAM

Invalid parameter value set.

CAPI_EUNSUPPORTED

Unsupported routine or operation.

CAPI_ENOMEMORY

Operation does not have memory.

CAPI_ENEEDMORE

Operation needs more data or buffer space.

CAPI_ENOTREADY

CAPI currently cannot perform this operation because necessary properties and parameters are not set or because of any internal state.

CAPI_EALREADY

CAPI currently cannot perform this operation. There might be restrictions on overwriting calibration after a certain operation. For example, recalibrating the hardware interface after it is started.

CAPI_FAILED(x)

Macro that checks whether a CAPI error code has any error bits set.

CAPI_SUCCEEDED(x)

Macro that checks whether a CAPI error code represents a success case.

CAPI_SET_ERROR(error_flags, return_code)

Macro that sets an error flag in a CAPI error code.

CAPI_IS_ERROR_CODE_SET(error_flags, error_code)

Macro that checks whether a specific error flag is set in a CAPI error code.

CAPI_MAX_CHANNELS

Maximum number of channels supported in a stream.

CAPI_MAX_CHANNELS_V2

Version 2 of the maximum number of channels macro.

CAPI_MEDIA_FORMAT_MINOR_VERSION

Minor version of media format version 2.

CAPI_DATA_FORMAT_INVALID_VAL

Macro used in any field of capi_data_format_header_t to indicate that the value is unspecified.

Typedefs

typedef uint32_t capi_err_t

Error code type for CAPI.

typedef struct capi_buf_t capi_buf_t
typedef union capi_stream_flags_t capi_stream_flags_t
typedef struct capi_stream_data_t capi_stream_data_t
typedef struct capi_stream_data_v2_t capi_stream_data_v2_t
typedef struct capi_data_format_header_t capi_data_format_header_t
typedef struct capi_set_get_media_format_t capi_set_get_media_format_t
typedef struct capi_standard_data_format_t capi_standard_data_format_t
typedef uint16_t capi_channel_type_t

Valid channel types as defined in media_fmt_api.h.

typedef struct capi_standard_data_format_v2_t capi_standard_data_format_v2_t
typedef struct capi_raw_compressed_data_format_t capi_raw_compressed_data_format_t
typedef struct capi_channel_mask_t capi_channel_mask_t

Channel mask.

typedef struct capi_deinterleaved_raw_compressed_data_format_t capi_deinterleaved_raw_compressed_data_format_t
typedef struct capi_port_info_t capi_port_info_t

Enums

enum capi_stream_version_t

Version information for the capi_stream_data_t structure specified in stream_data_version (in capi_stream_flags_t).

Values:

enumerator CAPI_STREAM_V1

Indicates the initial version of the structure (00 — capi_stream_data_t).

enumerator CAPI_STREAM_V2

Indicates version 2 of the structure (01 — capi_stream_data_v2_t).

enum data_format_t

Valid values for data formats of the inputs and outputs of a module.

Values:

enumerator CAPI_FIXED_POINT

Fixed point PCM data.

Payload: capi_standard_data_format_t

enumerator CAPI_FLOATING_POINT

Floating point PCM data.

Payload: capi_standard_data_format_t

enumerator CAPI_RAW_COMPRESSED

Compressed audio data bitstream in an unpacketized form.

Payload: capi_raw_compressed_data_format_t

enumerator CAPI_IEC61937_PACKETIZED

Compressed audio data bitstream packetized according to

.

Payload: capi_standard_data_format_t

enumerator CAPI_DSD_DOP_PACKETIZED

Compressed audio data bitstream packetized in Qualcomm DSD-over-PCM (DSD_DOP) format (16 bit, MSB first, word interleaved).

Payload: capi_standard_data_format_t

enumerator CAPI_COMPR_OVER_PCM_PACKETIZED

Compressed bitstreams packetized like PCM using a Qualcomm-designed packetizer.

Payload: capi_standard_data_format_t

enumerator CAPI_GENERIC_COMPRESSED

Compressed audio data bitstream that will be passed through as is, without knowing or modifying the underlying structure.

Payload: capi_standard_data_format_t

enumerator CAPI_IEC60958_PACKETIZED

PCM audio data bitstream packetized according to IEC 60958

format.

Payload: capi_standard_data_format_t

enumerator CAPI_IEC60958_PACKETIZED_NON_LINEAR

Compressed audio data bitstream packetized according to IEC 60958 format.

Payload: capi_standard_data_format_t

enumerator CAPI_DEINTERLEAVED_RAW_COMPRESSED

Compressed audio data bitstream in an unpacketized form where each channel has its own buffers.

Payload: capi_deinterleaved_raw_compressed_data_format_t

enumerator CAPI_MAX_FORMAT_TYPE

Maximum value that a data format can take.

enum capi_interleaving_t

Valid values for data interleaving or deinterleaving.

Values:

enumerator CAPI_INTERLEAVED

Data for all channels is present in one buffer. The samples are interleaved per channel.

enumerator CAPI_DEINTERLEAVED_PACKED

Data for all channels is present in one buffer.

All of the samples of one channel are present, followed by all of the samples of the next channel, and so on.

enumerator CAPI_DEINTERLEAVED_UNPACKED

Data for each channel is present in a different buffer.

In this case, the capi_stream_data_v2_t::buf_ptr field points to an array of buffer structures with the number of elements equal to the number of channels. The bufs_num field must be set to the number of channels. Actual data length and max data lengths is expected to be same for all the channel buffers.

enumerator CAPI_DEINTERLEAVED_UNPACKED_V2

Data for each channel is present in a different buffer.

In this case, the capi_stream_data_v2_t::buf_ptr field points to an array of buffer structures with the number of elements equal to the number of channels. Actual data length and max data length of every channel is expected to be same, and lengths are set only for the first channel. The bufs_num field must be set to the number of channels.

enumerator CAPI_INVALID_INTERLEAVING

Interleaving is not valid.

struct capi_buf_t
#include <capi_types.h>

Contains input buffers, output buffers, property payloads, event payloads, and parameters that are passed into the CAPI functions.

Public Members

int8_t *data_ptr

Data pointer to the raw data. The alignment depends on the format of the raw data.

uint32_t actual_data_len

Length of the valid data (in bytes).

For input buffers:

  • The caller fills this field with the number of bytes of valid data in the buffer.

  • The callee fills this field with the number of bytes of data it read.

For output buffers:

  • The caller leaves this field uninitialized.

  • The callee fills it with the number of bytes of data it filled.

uint32_t max_data_len

Total allocated size of the buffer (in bytes).

The caller always fills this value, and the callee does not modify it.

union capi_stream_flags_t
#include <capi_types.h>

Flags that are passed with every input buffer and must be filled by the module for every output buffer. These flags apply only to the buffer with which they are associated.

marker_eos and end_of_frame flags are closely associated with metadata. Modules that implement #INTF_EXTN_METADATA must take care of setting/clearing/propagating marker_eos and end_of_frame. For other modules, the framework takes care of end_of_frame and marker_eos. If the framework’s method of handling marker_eos/end_of_frame does not address a module’s requirements, the module must implement the #INTF_EXTN_METADATA extension and handle these flags.

Public Members

uint32_t is_timestamp_valid

Specifies whether the timestamp is valid.

For SISO modules the framework propagates timestamp and related flags (timestamp valid, continue) from input to output.

  • 0 — Not valid

  • 1 — Valid

uint32_t end_of_frame

Specifies whether the buffer has an end of frame.

  • 0 — end_of_frame is not marked

  • 1 — end_of_frame is marked

When end_of_frame is set, the modules must try to process given data even if the threshold is not met. Otherwise, data might be dropped.

For raw-compressed-data, end_of_frame usually indicates that the buffer has integral number of encoded frames.

end_of_frame is also set for discontinuities (timestamp discontinuity, EOS).

If a module does not implement the #INTF_EXTN_METADATA extension, then it must not write to this flag.

Framework callbacks in #INTF_EXTN_METADATA, don’t take care of end_of_frame. Therefore, modules that support the #INTF_EXTN_METADATA extension must also take care of setting/clearing/propagating of this flag.

uint32_t marker_eos

Indicates that this data is the last valid data from the upstream port.

There are two types of EOS, flushing and non-flushing. This flag pertains to flushing EOS.

Flushing EOS extracts all the data out of the modules.

  • For decoders, this is achieved by repeatedly calling the module without input.

  • For generic modules, this is achieved by pushing zeroes worth algorithm delay (zeroes worth = zero samples equal to the amount of algorithmic delay).

  • Multi-port modules must take care of flushing internally.

Non-flushing EOS is indicated only through metadata (marker_eos is not set).

marker_eos is accompanied by EOS metadata.

Typical Flushing EOS propagation works as follows:

  1. EOS is given at the input of a module. marker_eos flag is set on the input. EOS metadata is present in the input port metadata list.

  2. EOS undergoes algorithmic or buffering delay (if applicable). marker_eos flag is set on the input. EOS metadata moves internal to the module and the input port metadata list is cleared.

  3. EOS goes to output, gets destroyed, or gets converted to non-flushing EOS. The marker_eos flag moves to output. Input marker_eos is cleared and the internal metadata list is cleared. In case EOS moves to output, marker_eos on output is set and the output port metadata list is populated.

On the input port, marker_eos is set whenever a new EOS arrives or when the previous EOS is stuck inside the module due to delays. Output marker_eos is set only when there is EOS metadata in the output list.

marker_eos handling is taken care of by the framework, for modules that don’t implement INTF_EXTN_METADATA. For others, EOS metdata propagation including marker_eos handling, is taken care of by #intf_extn_param_id_metadata_handler_t::metadata_propagate() in #INTF_EXTN_METADATA. However, for create/destroy/clone etc., the module must set/clear marker_eos.

uint32_t marker_1

Data marker 1 the service uses to track data.

The module must propagate this marker from the input port to any output port that gets input from this port.

uint32_t marker_2

Data marker 2 the service uses to track data.

The module must propagate this marker from the input port to any output port that gets input from this port.

uint32_t marker_3

Data marker 3 the service uses to track data.

The module must propagate this marker from the input port to any output port that gets input from this port.

uint32_t erasure

Explicitly signals erasure due to underflow.

  • 0 — No erasure

  • 1 — Erasure

This flag triggers erasure handling in decoders. Some implementations push this flag to the modules while signaling erasure.

uint32_t stream_data_version

Version of the capi_stream_data_t structure.

Versions are defined in capi_stream_version_t:

uint32_t ts_continue

If the timestamp continue flag is set, then the timestamp field must not be read. Timestamp values based on previously set timestamp must continue. If the previous timestamp value is invalid, then this flag doesn’t apply. If ts_continue is reset and ts_valid is set, sync to the input timestamp. This field should be used only for raw compressed data formats.

  • 0 — ts_continue is set as FALSE

  • 1 — ts_continue is set as TRUE

uint32_t reserved

Reserved for future use. The module must ignore this value for input ports.

struct capi_stream_flags_t::[anonymous] [anonymous]

Defines the flags.

uint32_t word

Entire 32-bit word for easy access to read or write the entire word in one shot.

struct capi_stream_data_t
#include <capi_types.h>

Data structure for one stream.

Public Members

capi_stream_flags_t flags

Flags that indicate the stream properties. For more information on the flags, see capi_stream_flags_t.

int64_t timestamp

Timestamp of the first data sample, in microseconds.

The time origin is not fixed; it must be inferred from the timestamp of the first buffer. Negative values are allowed.

capi_buf_t *buf_ptr

Pointer to the array of CAPI buffer elements.

For deinterleaved unpacked uncompressed data, one buffer is to be used per channel. For CAPI_DEINTERLEAVED_RAW_COMPRESSED, as many buffers are used as specified in the media format. For all other cases, only one buffer is to be used.

uint32_t bufs_num

Number of buffer elements in the buf_ptr array.

For deinterleaved unpacked uncompressed data, this is equal to the number of channels in the stream. For CAPI_V2_DEINTERLEAVED_RAW_COMPRESSED, as many buffers are used as specified in the media format. For all other cases, all the data is put in one buffer, so this field is set to 1.

struct capi_stream_data_v2_t
#include <capi_types.h>

Version 2 of the data structure for one stream.

Public Members

capi_stream_flags_t flags

Flags that indicate the stream properties.

For more information on the flags, see capi_stream_flags_t.

int64_t timestamp

Timestamp of the first data sample, in microseconds.

The time origin is not fixed; it must be inferred from the timestamp of the first buffer. Negative values are allowed.

capi_buf_t *buf_ptr

Pointer to the array of CAPI buffer elements.

For deinterleaved unpacked uncompressed data, one buffer is to be used per channel. For CAPI_V2_DEINTERLEAVED_RAW_COMPRESSED, as many buffers are used as specified in the media format. For all other cases, only one buffer is to be used.

uint32_t bufs_num

Number of buffer elements in the buf_ptr array.

For deinterleaved unpacked uncompressed data, this is equal to the number of channels in the stream. For all other cases, all the data is put in one buffer, so this field is set to 1.

module_cmn_md_list_t *metadata_list_ptr

Pointer to the list of metadata. The object pointer in this list is of type #module_cmn_md_t.

struct capi_data_format_header_t
#include <capi_types.h>

Header structure for a data format that is passed into the module. Following this header is the appropriate media format payload.

Public Members

data_format_t data_format

Indicates the format in which the data is represented. The rest of the payload depends on the data format.

struct capi_set_get_media_format_t
#include <capi_types.h>

Header structure used to set and get a media format. Following this header is the appropriate media format payload.

Public Members

capi_data_format_header_t format_header

Header of the media format.

struct capi_standard_data_format_t
#include <capi_types.h>

Payload structure for the CAPI_FIXED_POINT, CAPI_FLOATING_POINT, and CAPI_IEC61937_PACKETIZED data formats.

Public Members

uint32_t bitstream_format

Valid types are MEDIA_FMT_ID_* as defined in media_fmt_api.h.

uint32_t num_channels

Number of channels.

uint32_t bits_per_sample

Number of bits used to store each sample.

This value should be interpreted as the sample word size in bits. For example, if the data is 24-bit audio packed in 24 bits, this value is 24. If the data is 24-bit audio packed in 32 bits, this value is

uint32_t q_factor

Number of fractional bits in the fixed point representation of the data.

If the data is floating point, this field must be set to CAPI_DATA_FORMAT_INVALID_VAL.

uint32_t sampling_rate

Sampling rate in samples per second.

uint32_t data_is_signed

Specifies whether data is signed.

  • 1 — Signed

  • 0 — Unsigned

capi_interleaving_t data_interleaving

Indicates whether the data is interleaved. This value is not relevant for packetized data.

uint16_t channel_type[CAPI_MAX_CHANNELS]

Array of channel types for each num_channels.

PCM_CHANNEL_* types as defined in media_fmt_api.h.

struct capi_standard_data_format_v2_t
#include <capi_types.h>

Media format version 2 payload for the CAPI_FIXED_POINT, CAPI_FLOATING_POINT, and CAPI_IEC61937_PACKETIZED data formats.

Public Members

uint32_t minor_version

Minor version for this payload.

uint32_t bitstream_format

Valid types are MEDIA_FMT_ID_* as defined in media_fmt_api.h.

uint32_t num_channels

Number of channels.

uint32_t bits_per_sample

Number of bits used to store each sample.

This value should be interpreted as the sample word size in bits. For example, if the data is 24-bit audio packed in 24 bits, this value is

  1. If the data is 24-bit audio packed in 32 bits, this value is 32.

uint32_t q_factor

Number of fractional bits in the fixed point representation of the data.

If the data is floating point, this field must be set to CAPI_DATA_FORMAT_INVALID_VAL.

uint32_t sampling_rate

Sampling rate in samples per second.

uint32_t data_is_signed

Specifies whether data is signed.

  • 1 — Signed

  • 0 — Unsigned

capi_interleaving_t data_interleaving

Indicates whether the data is interleaved. This value is not relevant for packetized data.

capi_channel_type_t channel_type[0]

Channel type payload is of variable length and depends on the number of channels. This payload has channel types for each of the num_channels.

PCM_CHANNEL_* types as defined in media_fmt_api.h

struct capi_raw_compressed_data_format_t
#include <capi_types.h>

Payload header for the RAW_COMPRESSED data format.

Following this structure is the media format structure for the specific data format as defined in media_fmt_api.h or specific decoder API file.

Public Members

uint32_t bitstream_format

Valid types are MEDIA_FMT_ID_* as defined in media_fmt_api.h.

struct capi_channel_mask_t
#include <capi_types.h>

Public Members

uint32_t channel_mask_lsw

LSW of the channel mask.

uint32_t channel_mask_msw

MSW of the channel mask.

struct capi_deinterleaved_raw_compressed_data_format_t
#include <capi_types.h>

Payload header for the DEINTERLEAVED_RAW_COMPRESSED data format. Unlike raw compressed, there is no media format specific payload following this struct, only channel mask follows.

Public Members

uint32_t minor_version

Minor version for this payload. Only version 1 supported currently.

uint32_t bitstream_format

Valid types are MEDIA_FMT_ID_* as defined in media_fmt_api.h.

uint32_t bufs_num

Number of buffers.

struct capi_port_info_t
#include <capi_types.h>

Payload structure header with data port information.

Control ports do not use this structure. Control ports are handled through interface extensions.

Public Members

bool_t is_valid

Indicates whether port_index is valid.

  • 0 — Not valid

  • 1 — Valid

bool_t is_input_port

Indicates the type of port.

  • TRUE — Input port

  • FALSE — Output port

uint32_t port_index

Identifies the port.

Index values must be sequential numbers starting from zero. There are separate sequences for input and output ports. For example, if a module has three input ports and two output ports:

  • The input ports have index values of 0, 1, and 2.

  • The output ports have index values of 0 and 1.

When capi_vtbl_t::process() is called:

  • Data in input[0] is for input port 0.

  • Data in input[1] is for input port 1.

  • And so on.

  • Output port 0 must fill data into output[0].

  • Output port 1 must fill data into output[1].

  • And so on.

capi_events.h

This file defines the events that can be raised by a module using the CAPI interface.

Copyright (c) Qualcomm Innovation Center, Inc. All Rights Reserved. SPDX-License-Identifier: BSD-3-Clause

Typedefs

typedef struct capi_event_info_t capi_event_info_t
typedef capi_err_t (*capi_event_cb_f)(void *context_ptr, capi_event_id_t id, capi_event_info_t *event_info_ptr)

Signature of the callback function used to raise an event to the client.

Associated data types

capi_event_id_t capi_event_info_t

Detailed description

The client provides the pointer to this function and the context_ptr in the call to capi_init_f().

Error code — Failure (see Section)

Dependencies

This function must be called from the same thread context as the interface functions.

Param context_ptr:

[in] Context pointer value provided by the framework when the callback function was passed.

Param id:

[in] ID for the event being raised.

Param event_info_ptr:

[in] Information about the event being raised.

Return:

CAPI_EOK — Success

typedef struct capi_event_KPPS_t capi_event_KPPS_t
typedef struct capi_event_bandwidth_t capi_event_bandwidth_t
typedef struct capi_event_data_to_dsp_client_t capi_event_data_to_dsp_client_t
typedef struct capi_event_dynamic_inplace_change_t capi_event_dynamic_inplace_change_t
typedef struct capi_event_data_to_dsp_client_v2_t capi_event_data_to_dsp_client_v2_t
typedef struct capi_event_data_to_dsp_service_t capi_event_data_to_dsp_service_t
typedef struct capi_event_get_data_from_dsp_service_t capi_event_get_data_from_dsp_service_t
typedef struct capi_event_process_state_t capi_event_process_state_t
typedef struct capi_event_algorithmic_delay_t capi_event_algorithmic_delay_t
typedef struct capi_event_headroom_t capi_event_headroom_t
typedef struct capi_port_data_threshold_change_t capi_port_data_threshold_change_t
typedef struct capi_library_base_t capi_library_base_t
typedef struct capi_event_get_library_instance_t capi_event_get_library_instance_t
typedef struct capi_event_dlinfo_t capi_event_dlinfo_t
typedef struct capi_event_hw_accl_proc_delay_t capi_event_hw_accl_proc_delay_t
typedef struct capi_event_island_vote_t capi_event_island_vote_t

Enums

enum capi_event_id_t

Valid IDs for the events that can be raised by a module.

Values:

enumerator CAPI_EVENT_KPPS

Indicates the KPPS requirement of the module. This value must be calculated assuming zero cache miss.

This event must be raised when the module is enabled and when the KPPS requirement changes.

Kilo-Packets-Per-Second (KPPS), where ‘packets’ is a Hexagon processor specific terminology referring to multiple instructions grouped for parallel execution. When CAPI is used for non-Hexagon processors, this event must be re-interpreted as Kilo-Instructions-Per-Second (KIPS) or a similar property that indicates processing load per second. The platform specific layers (POSAL) and CAPI modules must be in sync with respect to the meaning of this property.

Payload: capi_event_KPPS_t

enumerator CAPI_EVENT_BANDWIDTH

Indicates the bandwidth requirement of the module (in bytes per second).

This event must be raised when the module is enabled and when the bandwidth requirement changes. The bandwidth must be specified separately for code and data, and it must be calculated assuming no cache.

Payload: capi_event_bandwidth_t

enumerator CAPI_EVENT_DATA_TO_DSP_CLIENT

Deprecated. Use CAPI_EVENT_DATA_TO_DSP_CLIENT_V2.

Sends data to the client framework.

The module must specify a parameter ID to indicate the type of data that is present in the payload. The module can also specify an optional token to indicate additional information such as an instance identifier. The module must provide the payload in a buffer. The buffer can be safely destroyed or reused once the callback returns.

Payload: capi_event_data_to_dsp_client_t

enumerator CAPI_EVENT_DATA_TO_OTHER_MODULE

Currently not supported.

enumerator CAPI_EVENT_OUTPUT_MEDIA_FORMAT_UPDATED

Indicates that the output media format from the module has changed.

If this event is raised during a call to capi_vtbl_t::process(), no data can be output in the process() call.

Subsequent calls to the process function output the data of the new media type. If the module is to immediately output the data of the new media type, it must exit the process function with zero output and wait for the process function to be called again.

Payload: capi_set_get_media_format_t

enumerator CAPI_EVENT_PROCESS_STATE

Sent to the client to specify whether the module is enabled or disabled. The module is considered enabled by default.

We recommend that the module disable itself if it is not doing any processing. The capi_vtbl_t::process() function of the module is not called until it raises this event again to enable itself.

If this event is raised during a call to process(), no data can be output in the process() call.

Single port modules are bypassed when they are disabled. However, multi-port modules cannot be bypassed. This event might not be suitable for multi-port modules.

Payload: capi_event_process_state_t

enumerator CAPI_EVENT_ALGORITHMIC_DELAY

Indicates the algorithmic delay (in microseconds) caused by the module.

This event must be raised when the delay changes. The value must include any buffering delay.

Payload: capi_event_algorithmic_delay_t

enumerator CAPI_EVENT_HEADROOM

Deprecated. Use control links instead.

Indicates the head room requirement (in millibels) of the module (the default is zero).

Payload: capi_event_headroom_t

enumerator CAPI_EVENT_PORT_DATA_THRESHOLD_CHANGE

Indicates to the client that the threshold for a port has changed.

One event must be raised for each port whose threshold has changed. For more information on port thresholds, see CAPI_REQUIRES_DATA_BUFFERING.

If this event is raised during a call to capi_vtbl_t::process(), no data can be output in the process() call.

Payload: capi_port_data_threshold_change_t

enumerator CAPI_EVENT_METADATA_AVAILABLE

Deprecated. Use capi_metadata_t.

Indicates to the client that metadata is available for an output port.

One event must be raised for each port whose threshold has changed. For more information, see CAPI_METADATA.

enumerator CAPI_EVENT_DATA_TO_DSP_SERVICE

Sends data to the framework.

The module must specify a parameter ID to indicate the type of data that is present in the payload. It can also specify an optional token to indicate additional information such as an instance identifier. It must then provide the payload in a buffer. The buffer can be safely destroyed or reused once the callback returns.

Payload: capi_event_data_to_dsp_service_t

enumerator CAPI_EVENT_GET_LIBRARY_INSTANCE

Queries for an instance of a supporting library.

The module must provide the ID of the library. The service returns a pointer to an instance of the library. The instance contains a pointer to the virtual function table of the library interface as the first element. Every library virtual function table has capi_library_base_t as its first element.

Payload: capi_event_get_library_instance_t

For example, the following definitions are in the library header file: 

#define LIB_GUID <GUID>

struct lib_obj;

struct lib_vtable
{
   capi_library_base_t b; // Should be the first element of every library
vtable capi_err_t lib_func1(lib_obj *obj, uint32_t param); capi_err_t
lib_func2(lib_obj *obj, uint32_t param); capi_err_t lib_func3(lib_obj *obj,
uint32_t param);
};

struct lib_obj
{
   lib_vtable *vtble;
};

The following code is in the module: 

 capi_event_get_library_instance_t payload;
 payload.id = LIB_GUID;
 payload.ptr = NULL;

 capi_event_info_t payload_buffer;
 payload_buffer.port_info.is_valid = FALSE; // May be a valid value based on
the use case. payload_buffer.payload.data_ptr = (int8_t*)(&payload);
 payload_buffer.payload.actual_data_len = payload_buffer.payload.max_data_len =
sizeof(payload);

 capi_err_t result = event_cb_ptr(context_ptr, CAPI_EVENT_GET_LIBRARY_INSTANCE,
&payload_buffer);

 lib_obj *lib_ptr = (lib_obj*)payload.ptr;

 lib_ptr->vtbl.lib_func1(lib_ptr, param);
 ...
 lib_ptr->vtbl.lib_func2(lib_ptr, param);
 ...
 lib_ptr->vtbl.lib_func3(lib_ptr, param);
 ...

 lib_ptr->vtbl.b.end(lib_ptr); // The pointer is freed here.
 lib_ptr = NULL;

 //The GUID can be queried from the lib object itself. This allows the code to
determine the type of the object if it is not known: void *unknown_lib_ptr =
get_lib(); // Some function that returns a stored lib pointer whose type is
unknown. uint32_t interface_id =
((capi_library_base_t**)unknown_lib_ptr)->get_interface_id();
 switch(interface_id)
 {
 case LIB_GUID:
    lib_obj *lib_ptr = (lib_obj*)unknown_lib_ptr;
    ...
 ...
 }

enumerator CAPI_EVENT_GET_DLINFO

Queries the dynamic load information if the module is part of an SO

file.

Payload: capi_event_dlinfo_t

enumerator CAPI_EVENT_OUTPUT_MEDIA_FORMAT_UPDATED_V2

Indicates that media format version 2 output from the module has changed.

If this event is raised during a call to capi_vtbl_t::process(), any data output from this process function is assumed to use the old media type.

Subsequent calls to the process function output the data of the new media type. If the module is to immediately output the data of the new media type, it must exit the process function with zero output and wait for the process function to be called again.

Payload: capi_set_get_media_format_t

enumerator CAPI_EVENT_GET_DATA_FROM_DSP_SERVICE

Gets data from the framework.

The module must specify a parameter ID to indicate the type of data that is required from the framework. The ID can also specify an optional token to indicate additional information (like an instance identifier). The ID must provide the pointer to the data in the payload of the buffer. The buffer can be safely destroyed or reused once the callback returns.

The event is a blocking call. To update and return the callback, it must wait for the framework to get the required information. Because the request for data is a blocking call to the framework, the event handling in the framework must ensure that the response is instantaneous and does not involve any heavy processing.

For modules offloaded using the MDF framework, this event waits for the master processor to send the details.

Payload: capi_event_get_data_from_dsp_service_t

enumerator CAPI_EVENT_DATA_TO_DSP_CLIENT_V2

Sends data to the SPF client application processor.

The module must specify a parameter ID to indicate the type of data that is present in the payload. It can also specify an optional token to indicate additional information such as an instance identifier. The module must then provide the payload in a buffer. The buffer can be safely destroyed or reused once the callback returns.

Payload: capi_event_data_to_dsp_client_v2_t

enumerator CAPI_EVENT_DYNAMIC_INPLACE_CHANGE

Event ID used by the module to inform dynamic changes to the inplace property.

Module changing itself to inplace must be:

  • SISO as long as its inplace, if it’s MIMO when the event is raised it will error out.

  • Input media format and output media format must be equal.

  • Port thresholds must be equal.

Module must change itself to non-inplace if:

  • It becomes MIMO at any point in time.

  • Input and output media formats are different.

  • Input and output thresholds are different.

Payload: capi_event_dynamic_inplace_change_t

enumerator CAPI_EVENT_HW_ACCL_PROC_DELAY

Event ID used by the module to indicate hardware accelerator delay.

This delay applies to the modules utilizing hardware accelerators for off-loading partial/complete processing. It is the maximum time in microseconds taken by the hardware accelerator for the off-loaded processing for the provided input frame. Hardware accelerator processing happens in a synchronous manner such that the caller waits for the frame processing to finish. This delay does not include algorithmic delay due to signal processing in the hardware accelerator.

Default value: zero.

Payload: capi_event_hw_accl_proc_delay_t

enumerator CAPI_EVENT_ISLAND_VOTE

Event ID used by the module to indicate if it wants to vote for or against island.

If this event is raised by a module placed in a non-island container, it will be ignored. A vote against will be honored immediately.

Default value: Vote for island (island entry) 0.

Payload: capi_event_island_vote_t

enumerator CAPI_EVENT_DEINTERLEAVED_UNPACKED_V2_SUPPORTED

Event ID used by the module to indicate if it supports CAPI_DEINTERLEAVED_UNPACKED_V2 interleaving format on the input ports. Module needs to raise this event once during init, to indicate if all the input ports accept processing the CAPI_DEINTERLEAVED_UNPACKED_V2 interleaving format.

Note that if a module raise this event, and if module is generating unpacked output data then it must make sure to raise output media format with CAPI_DEINTERLEAVED_UNPACKED_V2 interleaving format.

Payload: None

enumerator CAPI_MAX_EVENT

Maximum value that an event ID can take.

struct capi_event_info_t
#include <capi_events.h>

Contains information about an event.

Public Members

capi_port_info_t port_info

Port for which this event is raised.

Set this field to an invalid value for events that are not specific to any port or if the payload contains the port information.

capi_buf_t payload

Buffer that holds the payload for the event.

struct capi_event_KPPS_t
#include <capi_events.h>

Payload for the CAPI_EVENT_KPPS event.

Public Members

uint32_t KPPS

Kilo packets per second requirement of the module.

struct capi_event_bandwidth_t
#include <capi_events.h>

Payload for the CAPI_EVENT_BANDWIDTH event.

Public Members

uint32_t code_bandwidth

Code bandwidth of the module (in bytes per second).

uint32_t data_bandwidth

Data bandwidth of the module (in bytes per second).

struct capi_event_data_to_dsp_client_t
#include <capi_events.h>

Deprecated. See capi_event_data_to_dsp_client_v2_t.

Payload for the CAPI_EVENT_DATA_TO_DSP_CLIENT event.

Public Members

uint32_t param_id

Indicates the type of data that is present in the payload.

uint32_t token

Optional token that indicates additional information, such as an instance identifier.

capi_buf_t payload

Buffer that contains the payload.

This buffer can be safely destroyed or reused once the callback returns.

struct capi_event_dynamic_inplace_change_t
#include <capi_events.h>

Deprecated.

Payload for the CAPI_EVENT_DYNAMIC_INPLACE_CHANGE event.

Public Members

uint32_t is_inplace

  • 0 — Indicates module changed to non-inplace

  • Non zero — Indicates module changed to inplace

struct capi_event_data_to_dsp_client_v2_t
#include <capi_events.h>

Payload for the CAPI_EVENT_DATA_TO_DSP_CLIENT_V2 event.

Public Members

uint64_t dest_address

Address to which this event is to be sent. The address that was provided during registration must be used.

uint32_t token

Optional token that indicates additional information, such as an instance identifier.

uint32_t event_id

Identifies the event.

capi_buf_t payload

Buffer that contains the payload.

This buffer can be safely destroyed or reused once the callback returns.

struct capi_event_data_to_dsp_service_t
#include <capi_events.h>

Payload for the CAPI_EVENT_DATA_TO_DSP_SERVICE event.

Public Members

uint32_t param_id

Indicates the type of data that is present in the payload.

uint32_t token

Optional token that indicates additional information, such as an instance identifier.

capi_buf_t payload

Buffer that contains the payload.

This buffer can be safely destroyed or reused once the callback returns.

struct capi_event_get_data_from_dsp_service_t
#include <capi_events.h>

Payload for the CAPI_EVENT_GET_DATA_FROM_DSP_SERVICE event.

Public Members

uint32_t param_id

Indicates the type of data that is required from the framework.

uint32_t token

Optional token that indicates additional information, such as an instance identifier.

capi_buf_t payload

Buffer that contains the payload.

This buffer can be safely destroyed or reused once the callback returns.

struct capi_event_process_state_t
#include <capi_events.h>

Payload for the CAPI_EVENT_PROCESS_STATE event.

Public Members

bool_t is_enabled

Specifies whether the module is enabled. If a module is disabled, its capi_vtbl_t::process() function is not called.

  • 0 — Disabled

  • 1 — Enabled (Default)

struct capi_event_algorithmic_delay_t
#include <capi_events.h>

Payload for the CAPI_EVENT_ALGORITHMIC_DELAY event.

Public Members

uint32_t delay_in_us

Algorithmic delay in microseconds caused by the module.

This value must not include a buffering delay. Otherwise, metadata offset adjustments will be calculated incorrectly.

struct capi_event_headroom_t
#include <capi_events.h>

Deprecated. Use control links instead.

Payload for the CAPI_EVENT_HEADROOM event.

Public Members

uint32_t headroom_in_millibels

Headroom requirement of the module. The default is zero.

struct capi_port_data_threshold_change_t
#include <capi_events.h>

Payload for the CAPI_EVENT_PORT_DATA_THRESHOLD_CHANGE event.

Public Members

uint32_t new_threshold_in_bytes

Value of the threshold for a port.

struct capi_library_base_t
#include <capi_events.h>

Function pointers that are the first element of every library virtual function table.

Public Members

uint32_t (*get_interface_id)(void *obj_ptr)

Returns the ID associated with the interface that this object implements.

void (*end)(void *obj_ptr)

De-initializes the object and frees the memory associated with it. The object pointer is not valid after this call.

struct capi_event_get_library_instance_t
#include <capi_events.h>

Payload for the CAPI_EVENT_GET_LIBRARY_INSTANCE event.

Public Members

uint32_t id

Identifies the library.

void *ptr

Pointer to the instance of the library.

struct capi_event_dlinfo_t
#include <capi_events.h>

Payload for the CAPI_EVENT_GET_DLINFO event.

Public Members

uint32_t is_dl

Indicates whether the SO file is dynamically loaded.

  • TRUE — File is dynamically loaded

  • FALSE — Otherwise

The rest of this payload is applicable only if the SO file is loaded.

uint32_t load_addr_lsw

Lower 32 bits of the physical address where the SO file is loaded.

uint32_t load_addr_msw

Upper 32 bits of the physical address where the SO file is loaded.

The 64-bit number formed by load_addr_lsw and load_addr_msw must be 32-byte aligned and must have been previously mapped.

uint32_t load_size

Size (in bytes) of the loaded SO file.

struct capi_event_hw_accl_proc_delay_t
#include <capi_events.h>

Payload for the CAPI_EVENT_HW_ACCL_PROC_DELAY event.

Public Members

uint32_t delay_in_us

Hardware requirement of the module. Default value is 0.

struct capi_event_island_vote_t
#include <capi_events.h>

Payload for the CAPI_EVENT_ISLAND_VOTE event.

Public Members

uint32_t island_vote

Island vote of the module placed in an LPI container.

  • 0 — Vote for island entry

  • 1 — Vote against island entry

capi_properties.h

This file defines the data structures and ids for getting and setting properties in the Common Audio Processing Interface.

Copyright (c) Qualcomm Innovation Center, Inc. All Rights Reserved. SPDX-License-Identifier: BSD-3-Clause

Defines

CAPI_PERSISTENCE_INVALID_VAL

Macro that defines an ID for an invalid persistence type.

Typedefs

typedef struct capi_prop_t capi_prop_t
typedef struct capi_proplist_t capi_proplist_t
typedef struct capi_init_memory_requirement_t capi_init_memory_requirement_t
typedef struct capi_stack_size_t capi_stack_size_t
typedef struct capi_max_metadata_size_t capi_max_metadata_size_t
typedef struct capi_is_inplace_t capi_is_inplace_t
typedef struct capi_requires_data_buffering_t capi_requires_data_buffering_t
typedef struct capi_is_elementary_t capi_is_elementary_t
typedef struct capi_min_port_num_info_t capi_min_port_num_info_t
typedef struct capi_event_callback_info_t capi_event_callback_info_t
typedef struct capi_port_num_info_t capi_port_num_info_t
typedef struct capi_heap_id_t capi_heap_id_t
typedef struct capi_metadata_t capi_metadata_t
typedef struct capi_port_data_threshold_t capi_port_data_threshold_t
typedef struct capi_output_media_format_size_t capi_output_media_format_size_t
typedef struct capi_num_needed_framework_extensions_t capi_num_needed_framework_extensions_t
typedef struct capi_framework_extension_id_t capi_framework_extension_id_t
typedef struct capi_log_code_t capi_log_code_t
typedef struct capi_session_identifier_t capi_session_identifier_t
typedef struct capi_custom_property_t capi_custom_property_t
typedef struct capi_interface_extns_list_t capi_interface_extns_list_t
typedef struct capi_interface_extn_desc_t capi_interface_extn_desc_t
typedef struct capi_register_event_to_dsp_client_t capi_register_event_to_dsp_client_t
typedef struct capi_register_event_to_dsp_client_v2_t capi_register_event_to_dsp_client_v2_t
typedef struct capi_param_persistence_info_t capi_param_persistence_info_t
typedef struct capi_module_instance_id_t capi_module_instance_id_t
typedef struct capi_logging_info_t capi_logging_info_t
typedef struct capi_module_version_info_t capi_module_version_info_t

Enums

enum capi_property_id_t

Valid property IDs.

Values:

enumerator CAPI_INIT_MEMORY_REQUIREMENT

Amount of memory (in bytes) to be passed into the capi_init_f() function.

Payload: capi_init_memory_requirement_t

enumerator CAPI_STACK_SIZE

Stack size required by this module (in bytes).

Payload: capi_stack_size_t

enumerator CAPI_MAX_METADATA_SIZE

Deprecated. See #module_cmn_md_t.

Maximum size of metadata generated by this module after each call to capi_vtbl_t::process().

If this value is zero, the module does not generate any metadata. The value includes the sizes of different structures used to pack metadata (see CAPI_METADATA).

Payload: capi_max_metadata_size_t

enumerator CAPI_IS_INPLACE

Indicates whether the module can perform in-place computation.

If this value is TRUE, the caller can provide the same pointers for input and output (but this is not guaranteed). In this case, the input and output data format must be the same, and the requires_data_buffering property must be set to FALSE.

Payload: capi_is_inplace_t

enumerator CAPI_REQUIRES_DATA_BUFFERING

Specifies whether data buffering is TRUE or FALSE.

If this value is FALSE and the module does not require a port data threshold (CAPI_PORT_DATA_THRESHOLD), the module must behave as follows:

  • The number of output samples on all output ports must always be the same as the number of input samples. The caller must ensure that the number of input samples is the same on all input ports.

  • All of the input must be consumed. The caller must ensure that the output buffers have enough space.

  • The module must be able to handle any number of samples.

If this value is FALSE and the module requires a port data threshold (CAPI_PORT_DATA_THRESHOLD), the module must behave as follows:

  • The number of samples per buffer on all input and output ports must be the same as the threshold.

  • The caller must call the module with the required number of samples.

  • All of the input must be consumed. The caller must ensure that the output buffers have enough space.

If this value is TRUE, the module must behave as follows:

  • The module must define a threshold in number of bytes for each input port and each output port.

  • The module must consume data on its input ports and fill data on its output ports until one of the following occurs:

    • The amount of remaining data in each buffer of at least one input port is less than its threshold

    • Or the amount of free space in each buffer of at least one output port is less than its threshold.

When this value is set to TRUE, significant overhead is added. Use the TRUE setting only under the following circumstances:

  • The module performs encoding/decoding of data.

  • The module performs rate conversion between the input and output.

Payload: capi_requires_data_buffering_t

enumerator CAPI_NUM_NEEDED_FRAMEWORK_EXTENSIONS

Number of framework extensions required by this module.

Payload: capi_num_needed_framework_extensions_t

enumerator CAPI_NEEDED_FRAMEWORK_EXTENSIONS

List of framework extensions that are required by the module.

Payload: Array of capi_framework_extension_id_t structures

enumerator CAPI_INTERFACE_EXTENSIONS

List of interface extensions provided by the client.

The module must set the is_supported flag to TRUE or FALSE to indicate whether the module supports this extension. Additional data can also be exchanged using an optional buffer per extension.

Payload: capi_interface_extns_list_t

enumerator CAPI_IS_ELEMENTARY

Indicates whether the module is an elementary module.

To qualify as an elementary module, the module must meet the following criteria:

  • The module must be SISO

  • The module must have no requirements about trigger policy; it will get called every time the upstream module produces data

  • For each process call, the module must consume all data provided to it and produce the exact same amount of data

  • The module must not modify timestamps

  • The module must have 0 algorithmic delay

  • The module cannot raise the DM framework extension

  • The module cannot modify or write metadata; metadata reads are allowed as long as the metadata list is not modified

  • The module cannot reject media format; if the module can’t handle a media format, it must externally accept the module and disable itself until a valid media format is received

  • The module cannot raise any propagated values (port state, is_realtime)

  • The module cannot modify any propagated values (port state, is_realtime)

  • Any information propagated along the data path will NOT be sent to the tap point module

    • One exception — The media format will be propagated to the tap point module.

Payload: capi_is_elementary_t

enumerator CAPI_MIN_PORT_NUM_INFO

Indicates the minimum number of input and output data ports for the module. Along with SISO if the module can also behave as sink or source then this property must be implemented and: a. if sink behavior is supported then minimum output port must be zero b. if source behavior is supported then minimum input port must be zero If the minimum number of output port is zero: a. Then framework doesn’t propagate the downstream port state by default. b. If the module is acting as SISO and the output port is stopped then framework will treat it as a sink module, if this is not the desired behavior then the module should implement the #INTF_EXTN_PROP_PORT_DS_STATE extension and propagate the output state to the input.

Following are the types of limits on the number of data ports:

  1. Maximum number of ports as defined by the module

  2. Minimum number of ports as defined by the module

  3. Maximum number of ports as defined by the client (if the module defines an infinite number of ports)

  4. Number of currently active ports

Control ports are handled through interface extensions.

Payload: capi_min_port_num_info_t

enumerator CAPI_MODULE_VERSION_INFO

Indicates the module version information of the module.

Payload: capi_module_version_info_t

enumerator CAPI_MAX_STATIC_PROPERTIES

Dummy value that indicates the range of properties.

enumerator CAPI_EVENT_CALLBACK_INFO

Function pointer and state required for raising events to the framework.

Payload: capi_event_callback_info_t

enumerator CAPI_PORT_NUM_INFO

Sets the maximum number of input and output data ports for the module.

Following are the types of limits on the number of data ports:

  1. Maximum number of ports as defined by the module

  2. Minimum number of ports as defined by the module

  3. Maximum number of ports as defined by the client (if the module defines an infinite number of ports)

  4. Number of currently active ports

For example, a mixer can support infinite inputs (1) with four possible inputs in a given use

case (2), but only two inputs are currently active (3). This property sets number 2.

Control ports are handled through interface extensions.

Payload: capi_port_num_info_t

enumerator CAPI_HEAP_ID

Provides the heap IDs for allocating memory. Heap ID must not be interpreted by the modules; it can only be used as an argument for malloc and other functions.

Payload: capi_heap_id_t

enumerator CAPI_INPUT_MEDIA_FORMAT

Sets the media format for an input port. The caller must set the port ID in the payload.

Payload: capi_set_get_media_format_t

enumerator CAPI_LOG_CODE

Provides the logging code to the module for logging module data.

Payload: capi_log_code_t

enumerator CAPI_CUSTOM_INIT_DATA

Provides module-specific initialization data. This property ID is typically set only at initialization time.

Payload: Module-specific

enumerator CAPI_SESSION_IDENTIFIER

Deprecated.

Provides values that allow the module to uniquely identify its placement and session.

Payload: capi_session_identifier_t

enumerator CAPI_INPUT_MEDIA_FORMAT_V2

Sets media format version 2 for an input port. The caller must set the port ID in the payload.

Payload: capi_set_get_media_format_t followed by capi_standard_data_format_v2_t followed by the channel type information

enumerator CAPI_MODULE_INSTANCE_ID

Provides the instance ID of the module. This ID uniquely identifies the module in a graph.

Payload: capi_module_instance_id_t

enumerator CAPI_LOGGING_INFO

Information provided by the containers to the module to help with logging, including text and PCM/binary dump logging.

Payload: capi_logging_info_t

enumerator CAPI_MAX_INIT_PROPERTIES

Dummy value that indicates the range of properties.

enumerator CAPI_ALGORITHMIC_RESET

Specifies whether the module is to reset any internal buffers and the algorithm state to zero.

Settings are not required to be reset, and memory allocated by the module is not required to be freed.

Payload: Empty buffer

enumerator CAPI_EXTERNAL_SERVICE_ID

Currently not used.

enumerator CAPI_REGISTER_EVENT_DATA_TO_DSP_CLIENT

Specifies the registration information for an event of type CAPI_EVENT_DATA_TO_DSP_CLIENT_V2.

Payload: capi_register_event_to_dsp_client_t

enumerator CAPI_REGISTER_EVENT_DATA_TO_DSP_CLIENT_V2

Specifies the registration information for an event of type CAPI_EVENT_DATA_TO_DSP_CLIENT_V2.

Payload: capi_register_event_to_dsp_client_v2_t

enumerator CAPI_PARAM_PERSISTENCE_INFO

Specifies the type of persistent memory that is associated with a certain parameter.

A capi_vtbl_t::set_properties() of this property ID is immediately followed by a capi_vtbl_t::set_param() of the corresponding parameter. Using this property, the module can do the following:

  • Perform error checks. For example, when module’s expectation is to receive a persistent memory for a parameter, but the parameter is specified as non-persistent.

  • Decide to copy the pointer or copy the actual memory.

If this property is not set, the module should, by default, assume that the parameter’s payload is non-persistent. However, it is up to module implementation to support persistent, non-persistent, or both.

If memory is persistent, this property also specifies whether memory is shared with other modules.

  • Persistent: Specifies whether the memory is exclusively available for the module. The module is not required to copy the contents of the set_param() payload; it can just store the pointer.

  • Global persistent: Specifies whether memory is shared with other modules. The module must never write to the memory.

Payload: capi_param_persistence_info_t

enumerator CAPI_MAX_SET_PROPERTIES

Dummy value that indicates the range of properties.

enumerator CAPI_METADATA

Deprecated. See #module_cmn_md_t.

Specifies that the module must fill in any metadata that it generated during a capi_vtbl_t::process() call when the caller queries this parameter. The query is typically done after the module raises CAPI_EVENT_METADATA_AVAILABLE.

Payload: capi_metadata_t

enumerator CAPI_PORT_DATA_THRESHOLD

Threshold of an input or output port (in bytes).

This property ID is used only for modules that require a specific amount of data on any port. The module behavior depends on whether the module requires data buffering. For more information, see CAPI_REQUIRES_DATA_BUFFERING.

enumerator CAPI_OUTPUT_MEDIA_FORMAT_SIZE

Size of the media format payload for an output port. The size excludes the size of capi_data_format_header_t.

Payload: capi_output_media_format_size_t

enumerator CAPI_MAX_GET_PROPERTIES

Dummy value that indicates the range of properties.

enumerator CAPI_OUTPUT_MEDIA_FORMAT

Queries the media format for a specified output port.

This property ID can also be used to set the output media format for modules that support control of the output media format.

If a module supports control of some aspects such as the sample rate only, all other fields can be set to CAPI_DATA_FORMAT_INVALID_VAL. The caller must set the port ID in the payload.

Payload: capi_set_get_media_format_t

enumerator CAPI_CUSTOM_PROPERTY

Sets and gets a property that is specific to a framework extension. This property ID can also be used to statically get a module-specific property.

The framework extension must define a secondary property ID and corresponding payload structure (capi_custom_property_t) that are specific to the information the property is to set or get.

Payload: capi_custom_property_t

enumerator CAPI_OUTPUT_MEDIA_FORMAT_V2

Queries media format version 2 for a specified output port.

This property ID can also be used to set the output media format for modules that support control of the output media format.

If a module supports control of some aspects, such as the sample rate only, all other fields can be set to CAPI_DATA_FORMAT_INVALID_VAL. The caller must set the port ID in the payload.

Payload: capi_set_get_media_format_t

enumerator CAPI_MAX_SET_GET_PROPERTIES

Dummy value that indicates the range of properties.

enumerator CAPI_MAX_PROPERTY

Maximum value that a property ID can take.

enum capi_persistence_type_t

Valid types of persistence memory associated with parameters.

Values:

enumerator CAPI_PERSISTENT_MEM

Indicates that the memory is persistent.

This property indicates that this global memory is valid only for as long as the module is valid or until deregistration (whichever is first).

This memory is unique to each module instance. Therefore, the module is free to read from or write to this memory region.

enumerator CAPI_GLOBAL_PERSISTENT

Indicates that the memory is global persistent.

This global memory is valid only for as long as the module is valid or until deregistration (whichever is first).

This memory is shared with other modules. Therefore, the module must only read from this region; it is prohibited from writing into it.

enumerator CAPI_INVALID_PERSISTENCE

Persistence type is invalid.

struct capi_prop_t
#include <capi_properties.h>

Contains properties that can be sent to a module.

Properties are used for generic set and get commands, which are independent of the underlying module.

Public Members

capi_property_id_t id

Identifies the property that is being sent.

capi_buf_t payload

Payload buffer.

The buffer must contain the payload corresponding to the property value for the capi_vtbl_t::set_properties() call, and it must be sufficiently large to contain the payload for the set_properties() call.

capi_port_info_t port_info

Information about the port for which the property is applicable.

If the property is applicable to any port, the is_valid flag must be set to FALSE in the port information

struct capi_proplist_t
#include <capi_properties.h>

Contains a list of CAPI properties. This structure can be used to send a list of properties to the module or query for the properties.

Public Members

uint32_t props_num

Number of elements in the array.

capi_prop_t *prop_ptr

Array of CAPI property elements.

struct capi_init_memory_requirement_t
#include <capi_properties.h>

Payload for the CAPI_INIT_MEMORY_REQUIREMENT property.

Public Members

uint32_t size_in_bytes

Amount of memory.

struct capi_stack_size_t
#include <capi_properties.h>

Payload for the CAPI_STACK_SIZE property.

Public Members

uint32_t size_in_bytes

Size of the stack.

struct capi_max_metadata_size_t
#include <capi_properties.h>

Deprecated. see #module_cmn_md_t.

Payload for the CAPI_MAX_METADATA_SIZE property.

Public Members

uint32_t output_port_index

Index of the output port for which this property applies.

uint32_t size_in_bytes

Size of the metadata.

struct capi_is_inplace_t
#include <capi_properties.h>

Payload for the CAPI_IS_INPLACE property.

Public Members

bool_t is_inplace

Indicates whether a module is capable of doing in-place processing.

  • 0 — Does not support in-place processing

  • 1 — Supports in-place processing

struct capi_requires_data_buffering_t
#include <capi_properties.h>

Payload for the CAPI_REQUIRES_DATA_BUFFERING property.

Public Members

bool_t requires_data_buffering

Specifies whether data buffering is set to TRUE.

struct capi_is_elementary_t
#include <capi_properties.h>

Payload for the CAPI_IS_ELEMENTARY property.

Public Members

bool_t is_elementary

Indicates whether the module can operate as an elementary module.

  • 0 — This module is an elementary module

  • 1 — This module is not an elementary module

struct capi_min_port_num_info_t
#include <capi_properties.h>

Payload for the CAPI_MIN_PORT_NUM_INFO property.

Public Members

uint32_t num_min_input_ports

Mininum number of input ports.

uint32_t num_min_output_ports

Mininum number of output ports.

struct capi_event_callback_info_t
#include <capi_properties.h>

Payload for the CAPI_EVENT_CALLBACK_INFO property.

Public Members

capi_event_cb_f event_cb

Callback function used to raise an event.

void *event_context

Opaque pointer value used as the context for this callback function.

struct capi_port_num_info_t
#include <capi_properties.h>

Payload for the CAPI_PORT_NUM_INFO property.

Public Members

uint32_t num_input_ports

Number of input ports.

uint32_t num_output_ports

Number of output ports.

struct capi_heap_id_t
#include <capi_properties.h>

Payload for the CAPI_HEAP_ID property.

Public Members

uint32_t heap_id

Heap ID for allocating memory.

struct capi_metadata_t
#include <capi_properties.h>

Deprecated. See #module_cmn_md_t.

Payload for the CAPI_METADATA property.

Public Members

capi_buf_t payload

Contains the metadata.

struct capi_port_data_threshold_t
#include <capi_properties.h>

Payload for the CAPI_PORT_DATA_THRESHOLD property.

Public Members

uint32_t threshold_in_bytes

Threshold of an input or output port.

struct capi_output_media_format_size_t
#include <capi_properties.h>

Payload for the CAPI_OUTPUT_MEDIA_FORMAT_SIZE property.

Public Members

uint32_t size_in_bytes

Size of the media format payload for an output port.

struct capi_num_needed_framework_extensions_t
#include <capi_properties.h>

Payload for the CAPI_NUM_NEEDED_FRAMEWORK_EXTENSIONS property.

Public Members

uint32_t num_extensions

Number of framework extensions.

struct capi_framework_extension_id_t
#include <capi_properties.h>

Payload for the CAPI_NEEDED_FRAMEWORK_EXTENSIONS property.

Public Members

uint32_t id

Identifies the framework extension.

struct capi_log_code_t
#include <capi_properties.h>

Payload for the CAPI_LOG_CODE property.

Public Members

uint32_t code

Code for logging module data.

struct capi_session_identifier_t
#include <capi_properties.h>

Deprecated. Payload for the CAPI_SESSION_IDENTIFIER property.

Public Members

uint16_t service_id

Identifies the service in which the module is contained.

This ID is an opaque value that is not guaranteed to be backward compatible. As such, modules are not to determine their behavior based on this value.

uint16_t session_id

Identifies the session within the service as indicated by service_id.

Modules can use this value together with service_id to generate unique IDs for setting up intermodule communication within the same service session or for debug messaging.

struct capi_custom_property_t
#include <capi_properties.h>

Payload for the CAPI_CUSTOM_PROPERTY property.

Public Members

uint32_t secondary_prop_id

Secondary property ID that indicates the format of the rest of the payload.

Following this ID is the custom payload defined by the service. If a module does not support a custom property or a secondary property ID, it must return 0 in payload.actual_data_len of capi_prop_t.

struct capi_interface_extns_list_t
#include <capi_properties.h>

Payload for the CAPI_INTERFACE_EXTENSIONS property.

Following this structure is an array of capi_interface_extn_desc_t structures with num_extensions elements.

Public Members

uint32_t num_extensions

Number of interface extensions for which the client is querying. The client must provide this value.

struct capi_interface_extn_desc_t
#include <capi_properties.h>

Data type of each element in an array of capi_interface_extns_list_t::num_extensions elements (for the CAPI_INTERFACE_EXTENSIONS property).

Public Members

uint32_t id

Identifies the interface extension being queried. The client must provide this value.

bool_t is_supported

Indicates whether this extension is supported.

  • 0 — Not supported

  • 1 — Supported

The module must provide this value.

capi_buf_t capabilities

Optional buffer containing a structure that can be used for further negotiation of capabilities related to this extension.

The structure is defined in the interface extension file. If it is not defined in this file, the interface extension does not have a capabilities structure.

struct capi_register_event_to_dsp_client_t
#include <capi_properties.h>

Payload for the CAPI_REGISTER_EVENT_DATA_TO_DSP_CLIENT_V2 event.

Public Members

uint32_t event_id

Identifies the event to be registered.

bool_t is_registered

Indicates whether a registered client exists for the event.

  • TRUE — Event is registered

  • FALSE — Event is not registered

struct capi_register_event_to_dsp_client_v2_t
#include <capi_properties.h>

Payload for the CAPI_REGISTER_EVENT_DATA_TO_DSP_CLIENT_V2 event.

Public Members

uint64_t dest_address

Address to which this event must be sent.

uint32_t token

Token to be used when raising this event.

uint32_t event_id

Identifies the event to be registered.

bool_t is_register

Indicates whether a registered client exists for this event.

  • 0 — FALSE (event is not registered)

  • 1 — TRUE (event is registered)

capi_buf_t event_cfg

Event configuration. Data is interpreted based on the event ID.

struct capi_param_persistence_info_t
#include <capi_properties.h>

Payload header of the CAPI_PARAM_PERSISTENCE_INFO property. Following this structure is the parameter ID payload.

Public Members

bool_t is_register

Indicates whether the property is intended for registration or deregistration of memory.

  • TRUE — Registration

  • FALSE — Deregistration

capi_persistence_type_t mem_type

Indicates the type of persistence memory associated with the parameter ID payload that follows.

uint32_t param_id

Identifies the parameter.

struct capi_module_instance_id_t
#include <capi_properties.h>

Payload for the CAPI_MODULE_INSTANCE_ID property.

Public Members

uint32_t module_id

Identifies the module.

uint32_t module_instance_id

Identifies the module instance.

struct capi_logging_info_t
#include <capi_properties.h>

Payload for the CAPI_LOGGING_INFO property.

Public Members

uint32_t log_id

Valid log ID for the module.

Any message printed with this ID uniquely identifies messages from this instance of the module.

uint32_t log_id_mask

Bits reserved in the log_id field for the module to modify.

The module can use these bits for changing the log ID during a discontinuity such as EOS or flush.

struct capi_module_version_info_t
#include <capi_properties.h>

Payload for the #CAPI_MODULE_VERSION property.

Public Members

uint16_t version_major

Major version of the module

uint16_t version_minor

Minor version of the module