ext_headers/capi_v2.h

#ifndef CAPI_V2_H
#define CAPI_V2_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.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.
 */
/*=========================================================================*/

#include "capi_v2_types.h"
#include "capi_v2_events.h"
#include "capi_v2_properties.h"

typedef struct capi_v2_t capi_v2_t;

typedef struct capi_v2_vtbl_t capi_v2_vtbl_t;

/** @ingroup capiv2_virt_func_table
    Function table for plain C implementations of CAPIv2-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.
*/
struct capi_v2_vtbl_t {
    /**
    Processes input data on all input ports and provides output on all output
    ports.

    @datatypes
    capi_v2_t \n
    capi_v2_stream_data_t

    @param[in,out] _pif   Pointer to the module object.
    @param[in,out] input  Array of pointers to the input data for each input
                          port. \n
                          The length of the array is the number of input ports.
                          The client sets the number of input ports using the
                          #CAPI_V2_PORT_NUM_INFO property. \n
                          The function must modify the actual_data_len field
                          to indicate how many bytes were consumed.
    @param[out] output    Array of pointers to the output data for each output
                          port. \n
                          The client sets the number of output ports using the
                          #CAPI_V2_PORT_NUM_INFO property. \n
                          The function sets the actual_data_len field to
                          indicate how many bytes were generated.

    @detdesc
    This is a generic processing function.
    @par
    On each call to capi_v2_vtbl_t::process(), the behavior of the module
    depends on the value it returned for the #CAPI_V2_REQUIRES_DATA_BUFFERING
    property. For a description of the behavior, refer to the comments for
    CAPI_V2_REQUIRES_DATA_BUFFERING.
    @par
    No debug messages are allowed in this function.

    @return
    Indication of success or failure.

    @dependencies
    A valid input media type must have been set on each input port using the
    #CAPI_V2_INPUT_MEDIA_FORMAT property. @newpage
    */
    capi_v2_err_t (*process)(capi_v2_t *_pif,
                             capi_v2_stream_data_t *input[],
                             capi_v2_stream_data_t *output[]);

    /**
     Frees any memory allocated by the module.

     @datatypes
     capi_v2_t

     @param[in,out] _pif    Pointer to the module object.

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

     @return
     Indication of success or failure.

     @dependencies
     None. @newpage
     */
    capi_v2_err_t (*end)(capi_v2_t *_pif);

    /**
    Sets a parameter value based on a unique parameter ID.

    @datatypes
    capi_v2_t \n
    capi_v2_port_info_t \n
    capi_v2_buf_t

    @param[in,out] _pif      Pointer to the module object.
    @param[in] param_id      ID of the parameter whose value is to be set.
    @param[in] port_info_ptr Pointer to the information about the port on
                             which this function must operate. \n
                             If a valid port ID is not provided, either the
                             port index does not matter for the param_id or
                             the param_id is applicable to all ports.
    @param[in] params_ptr    Pointer to the buffer containing the value of the
                             parameter.
                             The format of the data in the buffer depends on
                             the implementation.

    @detdesc
    In the event of a failure, the appropriate error code is to be returned.
    @par
    The actual_data_len field of the parameter pointer is to be at least the
    size of the parameter structure. Therefore, the following check must be
    exercised for each tuning parameter ID:
    @par
    @code
    if (params_ptr->actual_data_len >= sizeof(asm_gain_struct_t))
    {
    :
    :
    }
    else
    {
    MSG_1(MSG_SSID_QDSP6, DBG_ERROR_PRIO,"CAPI_V2 Libname Set, Bad param size
    %lu",params_ptr->actual_data_len);
    return ADSP_ENEEDMORE;
    }

    @endcode
    @par
    Optionally, some parameter values can be printed for tuning verification.
    @par
    @note1 In this code sample, asm_gain_struct is an example only.
           Use the correct structure based on the parameter ID.

    @return
    None.

    @dependencies
    None. @newpage
    */
    capi_v2_err_t (*set_param)(capi_v2_t *_pif,
                               uint32_t param_id,
                               const capi_v2_port_info_t *port_info_ptr,
                               capi_v2_buf_t *params_ptr);

    /**
    Gets a parameter value based on a unique parameter ID.

    @datatypes
    capi_v2_t \n
    capi_v2_port_info_t \n
    capi_v2_buf_t

    @param[in,out] _pif      Pointer to the module object.
    @param[in]     param_id  Parameter ID of the parameter whose value is
                             being passed in this function. For example:\n
                             - CAPI_V2_LIBNAME_ENABLE
                             - CAPI_V2_LIBNAME_FILTER_COEFF @tablebulletend
    @param[in] port_info_ptr Pointer to the information about the port on which
                             this function must operate. \n
                             If the port is invalid, either the port index does
                             not matter for the param_id or or the param_id
                             is applicable to all ports.
    @param[out] params_ptr   Pointer to the buffer that is to be filled with
                             the value of the parameter. The format depends on
                             the implementation.

    @detdesc
    In the event of a failure, the appropriate error code is to be returned.
    @par
    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
    exercised for each tuning parameter ID.
    @par
    @code
    if (params_ptr->max_data_len >= sizeof(asm_gain_struct_t))
    {
    :
    :
    }
    else
    {
    MSG_1(MSG_SSID_QDSP6, DBG_ERROR_PRIO,"CAPI_V2 Libname Get, Bad param size
    %lu",params_ptr->max_data_len);
    return ADSP_ENEEDMORE;
    }

    @endcode
    @par
    Before returning, the actual_data_len field must be filled with the number
    of bytes written into the buffer.
    @par
    Optionally, some parameter values can be printed for tuning verification.
    @par
    @note1 In this code sample, asm_gain_struct is an example only.
           Use the correct structure based on the parameter ID.

    @newpage
    @return
    Indication of success or failure.

    @dependencies
    None. @newpage
    */
    capi_v2_err_t (*get_param)(capi_v2_t *_pif,
                               uint32_t param_id,
                               const capi_v2_port_info_t *port_info_ptr,
                               capi_v2_buf_t *params_ptr);

    /**
    Sets a list of property values.

    @datatypes
    capi_v2_t \n
    capi_v2_proplist_t

    @param[in,out] _pif      Pointer to the module object.
    @param[in] proplist_ptr  Pointer to the list of property values.

    @detdesc
    In the event of a failure, the appropriate error code is to be returned.
    @par
    Optionally, some property values can be printed for debugging.

    @return
    None.

    @dependencies
    None. @newpage
    */
    capi_v2_err_t (*set_properties)(capi_v2_t *_pif,
                                    capi_v2_proplist_t *proplist_ptr);

    /**
    Gets a list of property values.

    @datatypes
    capi_v2_t \n
    capi_v2_proplist_t

    @param[in,out] _pif       Pointer to the module object.
    @param[out] proplist_ptr  Pointer to the list of empty structures that
                              must be filled with the appropriate property
                              values, which are based on the property IDs
                              provided. \n \n
                              The client must fill some elements
                              of the structures as input to the module. These
                              elements must be explicitly indicated in the
                              structure definition.

    @detdesc
    In the event of a failure, the appropriate error code is to be returned.

    @return
    Indication of success or failure.

    @dependencies
    None.
    */
    capi_v2_err_t (*get_properties)(capi_v2_t *_pif,
                                    capi_v2_proplist_t *proplist_ptr);
};

/** @ingroup capiv2_func_wrapper
  Plain C interface wrapper for the virtual function table, capi_v2_vtbl_t.

  This capi_v2_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_V2
  object. This capi_v2_t structure is all that is publicly visible.
 */
struct capi_v2_t {
    const capi_v2_vtbl_t *vtbl_ptr; /**< Pointer to the virtual function table. */
};

/** @ingroup capiv2_func_get_static_prop
  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

  @datatypes
  capi_v2_proplist_t

  @param[in] init_set_proplist Pointer to the same properties that are sent in
                               the call to capi_v2_init_f().
  @param[out] static_proplist  Pointer to the property list structure. \n
                               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.

  @detdesc
  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.
  @par
  As an input to this function, the client must pass in the property list that
  it passes to capi_v2_init_f(). The module can use the property
  values in init_set_proplist to calculate its memory requirements.
  @par
  The same properties that are sent to the module in the call to
  %capi_v2_init_f() are also sent to this function to enable the module to
  calculate the memory requirement.

  @return
  Indication of success or failure.

  @dependencies
  None.
 */
typedef capi_v2_err_t (*capi_v2_get_static_properties_f)(
    capi_v2_proplist_t *init_set_proplist,
    capi_v2_proplist_t *static_proplist);

/** @ingroup capiv2_func_init
  Instantiates the module to set up the virtual function table, and also
  allocates any memory required by the module.

  @datatypes
  capi_v2_t \n
  capi_v2_proplist_t

  @param[in,out] _pif          Pointer to the module object. \n
                               The memory has been allocated by the client
                               based on the size returned in the
                               #CAPI_V2_INIT_MEMORY_REQUIREMENT property.
  @param[in] init_set_proplist Pointer to the properties set by the service
                               to be used while initializing.

  @detdesc
  States within the module must be initialized at the same time.
  @par
  All return codes returned by this function, except #CAPI_V2_EOK, are
  considered to be FATAL.
  @par
  For any unsupported property ID passed in the init_set_proplist parameter,
  the function prints a message and continues processing other property IDs.

  @return
  Indication of success or failure.

  @dependencies
  */
typedef capi_v2_err_t (*capi_v2_init_f)(
    capi_v2_t *_pif,
    capi_v2_proplist_t *init_set_proplist);

#endif /* #ifndef CAPI_V2_H */