/*========================== begin_copyright_notice ============================
Copyright (C) 2021-2022 Intel Corporation

SPDX-License-Identifier: MIT
============================= end_copyright_notice ===========================*/

/*!
 * @file GTPin tool interface
 */

#ifndef IGT_TOOL_H_
#define IGT_TOOL_H_

#include "gt_basic_defs.h"

namespace gtpin
{
#pragma pack(push, 8)

/* ===================================================================================================== */
// External declarations
/* ===================================================================================================== */
class IGtKernelInstrument;  // Instrumentator of the GEN kernel
class IGtKernelDispatch;    // Interface of the kernel instance being dispatched for execution

/* ===================================================================================================== */
// Class IGtTool
/* ===================================================================================================== */
/*! @ingroup GTPIN_TOOL_CALLBACKS
 *  @brief Abstract class that defines interface of the GTPin tool; i.e. set of callbacks invoked by the 
 *  GTPin core
 * 
 * @par Availability:
 * - Anytime between IGtCore::RegisterTool and IGtCore::UnregisterTool
 */
class IGtTool
{
public:
    /// Return Name of the tool
    virtual const char* Name() const = 0;

    /// Return The GTPin API version supported by this tool
    virtual uint32_t ApiVersion() const = 0;

    /*!
     * @brief A callback invoked by GTPin for each kernel being compiled
     * 
     * The tool can use this callback to instrument the original code of the kernel.
     * 
     * @param[in]   instrumentor    Object that implements kernel instrumentation interface
     */
    virtual void OnKernelBuild(IGtKernelInstrument& instrumentor) = 0;

    /*!
     * @brief A callback invoked by GTPin for each kernel instance before dispatching it for execution
     * 
     * The tool can use this callback to enable or disable profiling of specific kernel instances. 
     * 
     * @param[in]   dispatcher    Object that implements kernel dispatching interface
     */
    virtual void OnKernelRun(IGtKernelDispatch& dispatcher) = 0;

    /*!
     * @brief A callback invoked by GTPin for each kernel instance that finished execution
     * 
     * The tool can use this callback to store and/or analyze profile data generated by the instrumented kernel.
     * 
     * @param[in]   dispatcher    Object that implements kernel dispatching interface
     */
    virtual void OnKernelComplete(IGtKernelDispatch& dispatcher) = 0;

protected:
    /// @internal Protected destructor
    virtual ~IGtTool() = default;
};
GTPIN_ASSERT_PURE_ABSTRACT(IGtTool);

#pragma pack(pop)
}
#endif
