| #ifndef CAPI_V2_TYPES_H |
| #define CAPI_V2_TYPES_H |
| |
| /* |
| * This file contrains the functions for controlling the |
| * internal circular buffer within the sound trigger HAL. |
| * The purpose is to keep all the different read and write |
| * commands from different threads synchronized. |
| * |
| * Copyright (c) 2019, The Linux Foundation. All rights reserved. |
| * |
| * Redistribution and use in source and binary forms, with or without |
| * modification, are permitted provided that the following conditions are |
| * met: |
| * * Redistributions of source code must retain the above copyright |
| * notice, this list of conditions and the following disclaimer. |
| * * Redistributions in binary form must reproduce the above |
| * copyright notice, this list of conditions and the following |
| * disclaimer in the documentation and/or other materials provided |
| * with the distribution. |
| * * Neither the name of The Linux Foundation nor the names of its |
| * contributors may be used to endorse or promote products derived |
| * from this software without specific prior written permission. |
| * |
| * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED |
| * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF |
| * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT |
| * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS |
| * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
| * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
| * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR |
| * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, |
| * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE |
| * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN |
| * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| */ |
| /* |
| @file capi_v2_types.h |
| Common Audio Processing Interface v2 common types. |
| |
| This file defines the basic data types for the Common Audio Processing |
| Interface. |
| */ |
| /*=========================================================================*/ |
| |
| #include "mmdefs.h" |
| |
| /** @addtogroup capiv2_error_codes |
| @{ */ |
| |
| /** Error code type for CAPIv2. */ |
| typedef uint32_t capi_v2_err_t; |
| |
| /** Success. The operation completed with no errors. */ |
| #define CAPI_V2_EOK 0 |
| |
| /** General failure. */ |
| #define CAPI_V2_EFAILED ((uint32_t)1) |
| |
| /** Invalid parameter value set. */ |
| #define CAPI_V2_EBADPARAM (((uint32_t)1) << 1) |
| |
| /** Unsupported routine or operation. */ |
| #define CAPI_V2_EUNSUPPORTED (((uint32_t)1) << 2) |
| |
| /** Operation does not have memory. */ |
| #define CAPI_V2_ENOMEMORY (((uint32_t)1) << 3) |
| |
| /** Operation needs more data or buffer space. */ |
| #define CAPI_V2_ENEEDMORE (((uint32_t)1) << 4) |
| |
| /** Macro that checks whether a CAPIv2 error code has any error bits set. */ |
| #define CAPI_V2_FAILED(x) (CAPI_V2_EOK != (x)) |
| |
| /** Macro that checks whether a CAPIv2 error code represents a success case. */ |
| #define CAPI_V2_SUCCEEDED(x) (CAPI_V2_EOK == (x)) |
| |
| /** Macro that sets an error flag in a CAPIv2 error code. */ |
| #define CAPI_V2_SET_ERROR(error_flags, return_code) ((error_flags) |= (return_code)) |
| |
| /** Macro that checks whether a specific error flag is set in a CAPIv2 error |
| code. */ |
| #define CAPI_V2_IS_ERROR_CODE_SET(error_flags, error_code) (((error_flags) & (error_code)) != CAPI_V2_EOK) |
| |
| /** @} *//* end_addtogroup capiv2_error_codes */ |
| |
| |
| typedef struct capi_v2_buf_t capi_v2_buf_t; |
| |
| /** @addtogroup capiv2_data_types |
| @{ */ |
| /** Contains input buffers, output buffers, property payloads, event payloads, |
| and parameters that are passed into the CAPIv2 functions. |
| */ |
| struct capi_v2_buf_t { |
| 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. |
| @tablebulletend */ |
| |
| uint32_t max_data_len; |
| /**< Total allocated size of the buffer (in bytes). |
| |
| This value is always filled by the caller, and it is not modified by |
| the callee. */ |
| }; |
| |
| typedef struct capi_v2_stream_flags_t capi_v2_stream_flags_t; |
| |
| /** 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. |
| */ |
| struct capi_v2_stream_flags_t { |
| uint32_t is_timestamp_valid :1; |
| /**< Specifies whether the timestamp is valid. |
| |
| @values |
| - 0 -- Not valid |
| - 1 -- Valid @tablebulletend */ |
| |
| uint32_t end_of_frame :1; |
| /**< Specifies whether the buffer ends with the end of an encoded frame. |
| |
| @values |
| - 0 -- The buffer might have an incomplete frame (relevant for |
| compressed data only) |
| - 1 --The buffer ends with the end of a frame. This allows the module |
| to start processing without scanning for the end of frame. |
| @tablebulletend */ |
| |
| uint32_t marker_eos :1; |
| /**< Indicates that this data is the last valid data from the upstream |
| port. */ |
| |
| uint32_t marker_1 :1; |
| /**< Data marker 1 used by the service 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 :1; |
| /**< Data marker 2 used by the service 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 :1; |
| /**< Data marker 3 used by the service 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 reserved :26; |
| /**< Reserved for future use. The client must ignore this value for input |
| ports and set it to zero for output ports. */ |
| }; |
| |
| typedef struct capi_v2_stream_data_t capi_v2_stream_data_t; |
| |
| /** Data structure for one stream. |
| */ |
| struct capi_v2_stream_data_t { |
| capi_v2_stream_flags_t flags; |
| /**< Flags that indicate the stream properties. For more information on |
| the flags, see the capi_v2_stream_flags_t structure. */ |
| |
| 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_v2_buf_t *buf_ptr; |
| /**< Array of CAPI_V2 buffer elements. |
| |
| For deinterleaved unpacked uncompressed data, one buffer is to be |
| used per channel. 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. */ |
| }; |
| |
| /** Maximum number of channels supported in a stream. */ |
| #define CAPI_V2_MAX_CHANNELS 16 |
| |
| /** Valid values for data formats of the inputs and outputs of a module. |
| */ |
| enum data_format_t { |
| CAPI_V2_FIXED_POINT, |
| /**< Fixed point PCM data. |
| |
| Payload structure: capi_v2_standard_data_format_t @vertspace{6} */ |
| |
| CAPI_V2_FLOATING_POINT, |
| /**< Floating point PCM data. |
| |
| Payload structure: capi_v2_standard_data_format_t @vertspace{6} */ |
| |
| CAPI_V2_RAW_COMPRESSED, |
| /**< Compressed audio data bitstream in an unpacketized form. |
| |
| Payload structure: capi_v2_raw_compressed_data_format_t @vertspace{6} */ |
| |
| CAPI_V2_IEC61937_PACKETIZED, |
| /**< Compressed audio data bitstream packetized according to |
| @xhyperref{S1,IEC~61937}. |
| |
| Payload structure: capi_v2_standard_data_format_t @vertspace{6} */ |
| |
| CAPI_V2_DSD_DOP_PACKETIZED, |
| /**< Compressed audio data bitstream packetized in QTI DSD-over-PCM |
| (DSD_DOP) format (16 bit, MSB first, word interleaved). |
| |
| Payload structure: capi_v2_standard_data_format_t @vertspace{6} */ |
| |
| CAPI_V2_COMPR_OVER_PCM_PACKETIZED, |
| /**< Compressed bitstreams packetized like PCM using a QTI-designed |
| packetizer. |
| |
| Payload structure: capi_v2_standard_data_format_t @vertspace{6} */ |
| |
| CAPI_V2_GENERIC_COMPRESSED, |
| /**< Compressed audio data bitstream that will be passed through as is, |
| without knowing or modifying the underlying structure. |
| |
| Payload structure: capi_v2_standard_data_format_t @vertspace{6} */ |
| |
| CAPI_V2_MAX_FORMAT_TYPE = 0x7FFFFFFF |
| /**< Maximum value that a data format can take. */ |
| }; |
| |
| typedef enum data_format_t data_format_t; |
| |
| /** Used in any field of capi_v2_data_format_t to indicate that the value is |
| unspecified. */ |
| #define CAPI_V2_DATA_FORMAT_INVALID_VAL 0xFFFFFFFF |
| |
| /** Valid values for data interleaving or deinterleaving. |
| */ |
| enum capi_v2_interleaving_t { |
| CAPI_V2_INTERLEAVED, |
| /**< Data for all channels is present in one buffer. The samples are |
| interleaved per channel. */ |
| |
| CAPI_V2_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, etc. */ |
| |
| CAPI_V2_DEINTERLEAVED_UNPACKED, |
| /**< Data for each channel is present in a different buffer. In this case, |
| the capi_v2_stream_data_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. */ |
| |
| CAPI_V2_INVALID_INTERLEAVING = CAPI_V2_DATA_FORMAT_INVALID_VAL |
| /**< Interleaving is not valid. */ |
| }; |
| |
| typedef enum capi_v2_interleaving_t capi_v2_interleaving_t; |
| |
| /** @} *//* end_addtogroup capiv2_data_types */ |
| |
| typedef struct capi_v2_data_format_header_t capi_v2_data_format_header_t; |
| |
| /** @addtogroup capiv2_payload_structs |
| @{ */ |
| /** Header structure for a data format that is passed into the module. |
| Following this header is the appropriate media format payload. |
| */ |
| struct capi_v2_data_format_header_t { |
| data_format_t data_format; |
| /**< Indicates the format in which the data is represented. |
| The rest of the payload depends on the data format. @newpagetable */ |
| }; |
| |
| typedef struct capi_v2_set_get_media_format_t capi_v2_set_get_media_format_t; |
| |
| /** Header structure used to set and get a media format. |
| Following this header is the appropriate media format payload. |
| */ |
| struct capi_v2_set_get_media_format_t { |
| capi_v2_data_format_header_t format_header; |
| /**< Header of the media format. */ |
| }; |
| |
| typedef struct capi_v2_standard_data_format_t capi_v2_standard_data_format_t; |
| |
| /** Payload structure for FIXED_POINT, FLOATING_POINT, and |
| IEC61937_PACKETIZED data formats. |
| */ |
| struct capi_v2_standard_data_format_t { |
| uint32_t bitstream_format; |
| /**< Valid types are ADSP_MEDIA_FMT_* as defined in |
| @xrefcond{Q3,80-NF774-1,80-NA610-1}. */ |
| /* adsp_media_fmt.h */ |
| |
| uint32_t num_channels; |
| /**< Number of channels. */ |
| |
| uint32_t bits_per_sample; |
| /**< Number of bits used to store each sample. |
| |
| For example, if the data is 24-bit audio packed in 24 bits, |
| this value is 24. If it 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_V2_DATA_FORMAT_INVALID_VAL. */ |
| |
| uint32_t sampling_rate; |
| /**< Sampling rate in samples per second. */ |
| |
| uint32_t data_is_signed; |
| /**< Specifies whether data is signed. |
| |
| @values |
| - 1 -- Signed |
| - 0 -- Unsigned @tablebulletend */ |
| |
| capi_v2_interleaving_t data_interleaving; |
| /**< Indicates whether the data is interleaved. This value is not relevant |
| for packetized data. |
| |
| @values |
| - #CAPI_V2_INTERLEAVED |
| - #CAPI_V2_DEINTERLEAVED_PACKED |
| - #CAPI_V2_DEINTERLEAVED_UNPACKED @tablebulletend */ |
| |
| uint16_t channel_type[CAPI_V2_MAX_CHANNELS]; |
| /**< Channel types for each of the num_channels. Valid channel types are |
| the PCM_CHANNEL_* types defined in @xrefcond{Q3,80-NF774-1,80-NA610-1}. |
| @newpagetable */ |
| /* adsp_media_fmt.h */ |
| }; |
| |
| typedef struct capi_v2_raw_compressed_data_format_t capi_v2_raw_compressed_data_format_t; |
| |
| /** Payload structure header for the RAW_COMPRESSED data format. |
| Following this structure is the media format structure for the specific data |
| format as defined in adsp_media_fmt.h. |
| */ |
| struct capi_v2_raw_compressed_data_format_t { |
| uint32_t bitstream_format; |
| /**< Valid types are ADSP_MEDIA_FMT_* as defined in |
| @xrefcond{Q3,80-NF774-1,80-NA610-1}. */ |
| /* adsp_media_fmt.h */ |
| }; |
| |
| /** @} *//* end_addtogroup capiv2_payload_structs */ |
| |
| typedef struct capi_v2_port_info_t capi_v2_port_info_t; |
| |
| /** @ingroup capiv2_data_types |
| Port information payload structure. |
| */ |
| struct capi_v2_port_info_t { |
| bool_t is_valid; |
| /**< Indicates whether port_index is valid. |
| |
| @values |
| - 0 -- Not valid |
| - 1 -- Valid @tablebulletend */ |
| |
| bool_t is_input_port; |
| /**< Indicates the type of port. |
| |
| @values |
| - TRUE -- Input port |
| - FALSE -- Output port @tablebulletend */ |
| |
| 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_v2_vtbl_t::process() is called: |
| - The data in input[0] is for input port 0. |
| - The data in input[1] is for input port 1. |
| - Etc. |
| - Output port 0 must fill data into output[0]. |
| - Output port 1 must fill data into output[1]. |
| - Etc. @tablebulletend @newpagetable */ |
| }; |
| |
| #endif /* #ifndef CAPI_V2_TYPES_H */ |