text: // Copyright 2014 HSA Foundation Inc.  All Rights Reserved.
  //
  // HSAF is granting you permission to use this software and documentation (if
  // any) (collectively, the "Materials") pursuant to the terms and conditions
  // of the Software License Agreement included with the Materials.  If you do
  // not have a copy of the Software License Agreement, contact the  HSA
  // Foundation for a copy.
  // Redistribution and use in source and binary forms, with or without
  // modification, are permitted provided that the following conditions
  // are met:
  // 1. Redistributions of source code must retain the above copyright
  //    notice, this list of conditions and the following disclaimer.
  // 2. 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
  // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
  // CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  // WITH THE SOFTWARE.
  
  #ifndef _AMD_HSA_TOOLS_INTERFACES_H_
  #define _AMD_HSA_TOOLS_INTERFACES_H_
  
  #include "hsa.h"
  
  #ifdef __cplusplus
  extern "C" {
  #endif  // __cplusplus
  
  /**
   * Hash define for exporting the API functions.
   */
  #if defined _WIN32 || defined __CYGWIN__
  #ifdef __GNUC__
  #define HSA_TOOLS_API __attribute__ ((dllexport))
  #else
  #define HSA_TOOLS_API __declspec(dllexport)  // Note: actually gcc seems
                                               // to also supports this
                                               // syntax.
  #endif
  #ifndef DLL_LOCAL
  #define DLL_LOCAL
  #endif
  
  #else  // defined _WIN32 || defined __CYGWIN__
  #if __GNUC__ >= 4
  #define HSA_TOOLS_API __attribute__ ((visibility("default")))
  #ifndef DLL_LOCAL
  #define DLL_LOCAL  __attribute__ ((visibility("hidden")))
  #endif
  #else
  #define HSA_TOOLS_API
  #ifndef DLL_LOCAL
  #define DLL_LOCAL
  #endif
  #endif
  #endif  // defined _WIN32 || defined __CYGWIN__
  
  /**
   * @brief Struct encapsulating pre and post dispatch callback
   * parameters. Users can query the boolean flag "pre_dispatch"
   * to distinguish if an instance is related to pre or post
   * dispatch. The flag is set to TRUE for pre dispatch callbacks.
   */
  typedef struct hsa_dispatch_callback_s {
    
    // Set to true if instance represents a
    // pre dispatch callback parameter
    bool pre_dispatch;
  
    // Hsa Agent associated with dispatch
    const hsa_agent_t agent;
  
    // Hsa Queue associated with dispatch
    const hsa_queue_t *queue;
  
    // Handle of an instance of PM4Buffer class
    void *aql_translation_handle;
  
    // User supplied callback parameter.
    //
    // @note: Currently this is initialized via an
    // explicit Api. The existence of this parameter
    // suggests the current interface is not complete.
    void *correlation_handle;
  
    // Monotonically increasing numeric identifier of
    // a Aql Dispatch packet. It must be emphasized that
    // every Aql packet is associated with an Id, not just
    // those that dispatch a kernel.
    uint64_t packet_id;
  
    // Aql dispatch packet associated with dispatch
    hsa_kernel_dispatch_packet_t *aql_packet;
  
    // Hsa Completion Signal associated with dispatch
    hsa_signal_t signal;
  
    // Default constructor of structure
    hsa_dispatch_callback_s(const hsa_agent_t agent) : agent(agent) { }
   
  } hsa_dispatch_callback_t;
  
  //---------------------------------------------------------------------------//
  // Pre-dispatch call back function signature. This is the call back fuction  //
  // before the kernel dispatch. The call back function is to indicate the     //
  // start of the kernel launch. It is used by the debugger and profiler.      //
  //---------------------------------------------------------------------------//
  typedef void
    (*hsa_ext_tools_pre_dispatch_callback_function)
      (const hsa_dispatch_callback_t *hsart_param, void *user_args);
  
  //---------------------------------------------------------------------------//
  // Post-dispatch call back function signature. The post dispatch callback    //
  // fuction is called after the kernel dispatch. The callback function is to  //
  // indicate the completion of the the kernel launch. It is used by the       //
  // debugger and profiler.                                                    //
  //---------------------------------------------------------------------------//
  typedef void
    (*hsa_ext_tools_post_dispatch_callback_function)
      (const hsa_dispatch_callback_t *hsart_param, void *user_args);
  
  //---------------------------------------------------------------------------//
  // @brief Setup the callback function pointers                               //
  // @param queue Pointer to queue that the callback functions are bind to     //
  // @param pre_dispatch_function Pointer to predispatch callback function     //
  // @param post_dispatch_function Pointer to postdispatch callback function   //
  // @retval        - HSA_STATUS_SUCCESS                                       //
  //---------------------------------------------------------------------------//
  hsa_status_t HSA_TOOLS_API hsa_ext_tools_set_callback_functions(
    hsa_queue_t *queue,
    hsa_ext_tools_pre_dispatch_callback_function pre_dispatch_function,
    hsa_ext_tools_post_dispatch_callback_function post_dispatch_function);
  
  //---------------------------------------------------------------------------//
  // @brief Query the callback function pointers                               //
  // @param queue Pointer to queue that the callback functions are bind to     //
  // @param pre_dispatch_function Pointer to predispatch callback function     //
  // @param post_dispatch_function Pointer to postdispatch callback function   //
  // @retval        - HSA_STATUS_SUCCESS                                       //
  //---------------------------------------------------------------------------//
  hsa_status_t HSA_TOOLS_API hsa_ext_tools_get_callback_functions(
      hsa_queue_t *queue,
      hsa_ext_tools_pre_dispatch_callback_function &pre_dispatch_function,
      hsa_ext_tools_post_dispatch_callback_function &post_dispatch_function);
  
  //---------------------------------------------------------------------------//
  // @brief Setup the call back function argument pointers                     //
  // @param queue Pointer to queue that the callback functions are bind to     //
  // @param pre_dispatch_args Pointer to predispatch callback function         //
  // arguments                                                                 //
  // @param post_dispatch_args Pointer to postdispatch callback function       //
  // arguments                                                                 //
  // @retval        - HSA_STATUS_SUCCESS                                       //
  //---------------------------------------------------------------------------//
  hsa_status_t HSA_TOOLS_API hsa_ext_tools_set_callback_arguments(
    hsa_queue_t *queue,
    void *pre_dispatch_args,
    void *post_dispatch_args);
  
  //---------------------------------------------------------------------------//
  // @brief Query the call back function argument pointers                     //
  // @param queue Pointer to queue that the callback functions are bind to     //
  // @param pre_dispatch_args Pointer to predispatch callback function         //
  // arguments                                                                 //
  // @param post_dispatch_args Pointer to postdispatch callback function       //
  // arguments                                                                 //
  // @retval        - HSA_STATUS_SUCCESS                                       //
  //---------------------------------------------------------------------------//
  hsa_status_t HSA_TOOLS_API hsa_ext_tools_get_callback_arguments(
      hsa_queue_t *queue,
      void * &pre_dispatch_args,
      void * &post_dispatch_args);
  
  #ifdef __cplusplus
  }
  #endif  // __cplusplus
  #endif  // _AMD_HSA_TOOLS_INTERFACES_H_
  