////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Copyright (c) 2022-2023 Qualcomm Technologies, Inc.
// All Rights Reserved.
// Confidential and Proprietary - Qualcomm Technologies, Inc.
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @file   chihwnodeconfigoverride.h
/// @brief  Defines Chi HwNode Configuration Override interface
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

#ifndef CHIHWNODECONFIGOVERRIDE_H
#define CHIHWNODECONFIGOVERRIDE_H

#include "chibpsconfigoverride.h"
#include "chiifeconfigoverride.h"
#include "chiipeconfigoverride.h"
#include "chicommon.h"

#ifdef __cplusplus
extern "C"
{
#endif // __cplusplus

#pragma pack(push, 8)

/// @brief  Defines the property of a CHI Node.
struct ChiHwNodeProperty
{
    UINT    nodeId;                             ///< Node Id
    UINT    instanceId;                         ///< Instance Id
    CHAR*   pNodeName;                          ///< Pipeline Name, Node name and instance id

    union
    {
        ChiIFENodeProperty     IFEProperty;     ///< IFE property info
        ChiBPSNodeProperty     BPSProperty;     ///< BPS property info
        ChiIPENodeProperty     IPEProperty;     ///< IPE property info
    };
};


/// @brief  Define the create session information for OEM.
typedef struct ChiHwConfigSessionCreateInfo
{
    CHIHANDLE               hHwCfgWrapper;      ///< CHI hardware config wrapper handle
    CHIHANDLE               hOEMHwConfig;       ///< OEM hardware config handle
                                                ///  The handle can be unique for each session and HW node that CHI creates.
                                                ///  CamX expects OEM to return the correct handle associated with a session.
    PFNCHIGETVENDORTAGBASE  pGetVendorTagBase;  ///< Get the base assigned to a vendor tag.
    UINT64                  featureTypeMask;    ///< OEM feature type mask
    HwCfgMetaInfo*          pHwCfgMetaInfo;     ///< OEM metadata information
    ChiHwNodeProperty       chiHwNodeProperty;  ///< Chi Node Property
} CHIHWCONFIGSESSIONCREATEINFO;


/// @brief  Defines the Destroy information for OEM.
typedef struct ChiHwConfigSessionDestroyInfo
{
    CHIHANDLE               hOEMHwConfig;       ///< Handle of the session object
} CHIHWCONFIGSESSIONDESTROYINFO;


////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @cond PFNHWCONFIGCREATE @endcond
///
/// @brief Creates a OEM HwNode config override instance.
///
/// @datatypes
/// #CHIHWCONFIGSESSIONCREATEINFO
///
/// @param[in] pCfgSessionInfo  Pointer to the structure that defines the create session information for OEM.
///
/// @detdesc
/// CHI calls this function at the start of a camera session during chi_create_pipeline() when a topology is created.
/// At this time, the CHI node can allocate any additional resources for managing per-session states.
/// @par
/// Multiple independent sessions might be active at the same time, so a CHI node can have multiple calls into this function.
///
/// @return #CDKResultSuccess or an error code (see Section @xref{hdr:resultMessages}). @newpage
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef CDKResult (*PFNHWCONFIGCREATE)(
    CHIHWCONFIGSESSIONCREATEINFO* pSessionCreateInfo
    );

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @cond PFNHWCONFIGDESTROY @endcond
///
/// @brief Destroys HW Configure .
///
/// @datatypes
/// #CHIHWCONFIGSESSIONDESTROYINFO
///
/// @param[in] destroyInfo  Pointer to the structure that defines the destroy session information for OEM.
///
/// @detdesc
/// CHI calls this function at the end of a camera session during chi_destroy_pipeline()when a topology is destroyed.
/// @par
/// After this function call, the CHI node session handle is invalid and the node is expected to deallocate all per-session
/// state resources associated with this session.
///
/// @return #CDKResultSuccess or an error code (see Section @xref{hdr:resultMessages}).
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef CDKResult (*PFNHWCONFIGDESTROY)(
    CHIHWCONFIGSESSIONDESTROYINFO* pSessionDestroyInfo
    );

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @cond PFNHWCONFIGQUERYINFO @endcond
///
/// @brief Query OEM configure information
///
/// @datatypes
/// #VOID
///
/// @param[in]  hOEMHwConfig  Pointer to the structure that defines the hardware node information to OEM
/// @param[in]  featureType   feature type of this query
/// @param[in]  reqID         req id for this query
/// @param[in]  pDataToOEM    Pointer to the structure that defines the hardware node information to OEM
/// @param[out] pDataToHwNode Pointer to the structure that defines the OEM override information to hardware node
///
/// @detdesc
/// The CHI HWnode call the function to pass OEM node information and get OEM override information.
///
/// @return #CDKResultSuccess or an error code (see Section @xref{hdr:resultMessages}). @newpage
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef CDKResult (*PFNHWCONFIGQUERYINFO)(
    VOID*   hOEMHwConfig,
    UINT    featureType,
    UINT64  reqID,
    VOID*   pDataToOEM,
    VOID*   pDataToHwNode
    );

/** @addtogroup chi_hwnode_config_datatypes
@{ */

/// @brief Interface for OEM to override the hardware configuration for each node on per-request basis
typedef struct CHIHwNodeConfigOverride
{
    UINT32                  majorVersion;               ///< Track the major version of the interface that CHI is using.
                                                        ///  If majorVersion does not match the majorVersion in
                                                        ///  use by the CHIHwNodeConfigOverride, the interfaces
                                                        ///  are not binary compatible and the
                                                        ///  CHIHwNodeConfigOverride entry fails.
    UINT32                  minorVersion;               ///< Track the minor version of the interface that CHI is using.
                                                        ///  If minorVersion does not match the minorVersion in use
                                                        ///  the CHIHwNodeConfigOverride, the mismatch is not an
                                                        ///  error condition. Interfaces with the same minorVersion
                                                        ///  number are binary compatible.
    PFNHWCONFIGCREATE       pHwConfigCreate;            ///  Function pointer to HW config create.
    PFNHWCONFIGDESTROY      pHwConfigDestroy;           ///  Function pointer to HW config destroy.
    PFNHWCONFIGQUERYINFO    pHwConfigQueryInfo;         ///  Function pointer to HW config queryinfo.

} CHIHWNODECONFIGOVERRIDE;

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/// @cond PFCHIHWNODECONFIGOVERRIDEENTRY @endcond
///
/// @brief Entry point called by the CHI driver to initialize a custom CHIHWNODECONFIGOVERRIDE.
///
/// @datatypes
/// #CHIHWNODECONFIGOVERRIDE
///
/// @param[in,out] pNodeOverride   Pointer to the structure that defines CHIHWNODECONFIGOVERRIDE structure for the CHI driver
///                                to send to the CHInode. The node must fill in these function pointers.
///
/// @detdesc
/// For driver to initialize the CHI HwNode config, this function must be exported by every \<library\>.so.
/// @par
/// This function is called during camera server initialization, which occurs when the HAL process starts.
/// In addition to communicating the necessary function pointers from CHI HwNode Override, this
/// function allows a CHI HwNode config to do any initialization work that it would typically do during process
/// initialization.
/// @par
/// Any work the CHIHwNodeConfigOverride does here must not be specific to a session.
/// Any variables stored in the CHI HwNode config
/// must be protected from multiple sessions accessing it at the same time.
///
/// @return None. @newpage
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef VOID (*PFCHIHWNODECONFIGOVERRIDEENTRY) (
    CHIHWNODECONFIGOVERRIDE* pNodeOverride
    );

#pragma pack(pop)

#ifdef __cplusplus
}
#endif // __cplusplus

#endif // CHIHWNODEOVERRIDE_H
