rocm-systems/rocclr/runtime/device/hwdebug.hpp

/* ========================================================================
   Copyright (c) 2014 Advanced Micro Devices, Inc.  All rights reserved.
  ========================================================================*/

#ifndef HWDEBUG_H_
#define HWDEBUG_H_

#include "device.hpp"
#include "amdocl/cl_debugger_amd.h"

static const int TbaStartOffset = 256;

static const int RtTrapBufferWaveSize = 64;
static const int RtTrapBufferSeNum    =  4;
static const int RtTrapBufferShNum    =  2;
static const int RtTrapBufferCuNum    = 16;
static const int RtTrapBufferSimdNum  =  4;
static const int RtTrapBufferWaveNum  = 16;
static const int RtTrapBufferTotalWaveNum =
                            ((RtTrapBufferSeNum) * \
                             (RtTrapBufferShNum) * \
                             (RtTrapBufferCuNum) * \
                             (RtTrapBufferSimdNum) * \
                             (RtTrapBufferWaveNum));


/*!  \brief Debug trap handler location in the runtime trap buffer
 *
 *   This enumeration is used to indicate the location where the debug
 *   trap handler and debug trap buffer are set in the device trap buffer.
 */
enum DebugTrapLocation
{
    kDebugTrapHandlerLocation = 0,  //! Debug Trap handler location, this location must be 0
    kDebugTrapBufferLocation = 1,   //! Debug Trap buffer location, this location must be 1
    kDebugTrapLocationMax = 2
};


/*!  \brief This structure is for the debug info in each kernel dispatch.
 *
 *   Contains the memory descriptor information of the scratch memory and the global
 *   memory
 */
struct DispatchDebugInfo
{
    uint32_t scratchMemoryDescriptor_[4];    //! Scratch memory descriptor
    uint32_t globalMemoryDescriptor_[4];     //! Global memory descriptor
};

/*!  \brief Trap handler descriptor
 *
 *   The trap handler descriptor contains the details of a given trap handler.
 */
struct TrapHandlerInfo {
    amd::Memory* trapHandler_;       //!< Device memory for the trap handler
    amd::Memory* trapBuffer_;        //!< Device memory for the trap buffer
};

/*!  \brief Structure of the runtime trap handler buffer, which includes the following
 *   information: information of the runtime trap handler and buffer, information of
 *   the level-2 trap handlers and buffers.
 */
struct RuntimeTrapInfo {
    TrapHandlerInfo trap_;     //!< Structure of the address of all trap handlers
    uint32_t dispatchId_;      //!< Dispatch ID that signals the shader event
    uint32_t vgpr_backup_[RtTrapBufferTotalWaveNum][RtTrapBufferWaveSize];
                              //!< Buffer to backup the VGPR used by the runtime trap handler
};



/**
 * Opaque pointer to trap event
 */
typedef uintptr_t DebugEvent;

namespace amd {


class Context;
class Device;
class HostQueue;


/*! \class HwDebugManager
 *
 *  \brief The device interface class for the hardware debug manager
 */
class HwDebugManager
{
public:

    //! Constructor for the Hardware Debug Manager
    HwDebugManager(amd::Device* device);

    //! Destructor for Hardware Debug Manager
    virtual ~HwDebugManager();

    //!  Setup the call back function pointer
    void setCallBackFunctions(cl_PreDispatchCallBackFunctionAMD  preDispatchFn,
                              cl_PostDispatchCallBackFunctionAMD postDispatchFn);

    //!  Setup the call back argument pointers
    void setCallBackArguments(void* preDispatchArgs, void* postDispatchArgs);

    //!  Get dispatch debug info
    void getDispatchDebugInfo(void* debugInfo) const;

    //!  Set the kernel code address and its size
    void setKernelCodeInfo(address aqlCodeAddr, uint32_t aqlCodeSize);

    //!  Get the scratch ring
    void setScratchRing(address scratchRingAddr, uint32_t scratchRingSize);

    //!  Map the shader (AQL code) for host access
    void mapKernelCode(uint64_t* aqlCodeAddr, uint32_t* aqlCodeSize) const;

    //!  Map the scratch ring for host access
    void mapScratchRing(uint64_t* scratchRingAddr, uint32_t* scratchRingSize) const;

    //!  Retrieve the pre-dispatch callback function
    cl_PreDispatchCallBackFunctionAMD preDispatchCallBackFunc() const
                                                { return preDispatchCallBackFunc_; }

    //!  Retrieve the post-dispatch callback function
    cl_PostDispatchCallBackFunctionAMD postDispatchCallBackFunc() const
                                                { return postDispatchCallBackFunc_; }

    //!  Retrieve the pre-dispatch callback function arguments
    void* preDispatchCallBackArgs() const { return preDispatchCallBackArgs_;  }

    //!  Retrieve the post-dispatch callback function arguments
    void* postDispatchCallBackArgs() const { return postDispatchCallBackArgs_; }

    //!  Set exception policy
    void setExceptionPolicy(void* policy);

    //!  Get exception policy
    void getExceptionPolicy(void* policy) const;

    //!  Set the kernel execution mode
    void setKernelExecutionMode(void* mode);

    //!  Get the kernel execution mode
    void getKernelExecutionMode(void* mode) const;

    //!  Setup the pointer to the aclBinary within the debug manager
    void setAclBinary(void* aclBinary);

    //!  Allocate storage to keep the memory pointers of the kernel parameters
    void allocParamMemList(uint32_t numParams);

    //!  Assign the kernel parameter memory
    void assignKernelParamMem(uint32_t paramIdx, amd::Memory* mem);

    //!  Get kernel parameter memory object
    cl_mem getKernelParamMem(uint32_t paramIdx) const;

    //!  Flush cache
    virtual void flushCache(uint32_t mask) = 0;

    //!  Create the debug event
    virtual DebugEvent createDebugEvent(const bool autoReset) = 0;

    //!  Wait for the debug event
    virtual cl_int waitDebugEvent(DebugEvent pEvent, uint32_t  timeOut) const = 0;

    //!  Destroy the debug event
    virtual void destroyDebugEvent(DebugEvent* pEvent) = 0;

    //!  Register the debugger
    virtual cl_int registerDebugger(amd::Context* context, uintptr_t pMessageStorage) = 0;

    //!  Call KMD to register the debugger
    virtual cl_int registerDebuggerOnQueue(device::VirtualDevice* vDevice) = 0;

    //!  Unregister the debugger
    virtual void unregisterDebugger() = 0;


    //!  Send the wavefront control cmmand
    virtual void wavefrontControl(uint32_t waveAction,
                                    uint32_t waveMode,
                                    uint32_t trapId,
                                    void*    waveAddr) const = 0;

    //!  Set address watching point
    virtual void setAddressWatch(uint32_t     numWatchPoints,
                                 void**       watchAddress,
                                 uint64_t*    watchMask,
                                 uint64_t*    watchMode,
                                 DebugEvent*  event) = 0;

    //!  Get the packet information for dispatch
    virtual void getPacketAmdInfo(const void* aqlCodeInfo,
                                  void*       packetInfo) const = 0;

    //!  Set global memory values
    virtual void setGlobalMemory(amd::Memory*   memObj,
                                 uint32_t       offset,
                                 void*          srcPtr,
                                 uint32_t       size) = 0;

    //!  Execute the post-dispatch callback function
    virtual void executePostDispatchCallBack() = 0;

    //!  Execute the pre-dispatch callback function
    virtual void executePreDispatchCallBack(void*   aqlPacket,
                                              void*   toolInfo) = 0;

    //!  Return the use of HW DEBUG flag
    bool isMsgBufferReady() const { return dbgMsgBufferReady_; }

protected:
    //!  Return the context
    const amd::Context*  context() const { return context_; }

    //!  Get the debug device
    const amd::Device*   device() const { return device_; }

    //!  Return the register flag
    bool isRegistered() const { return isRegistered_; }

    //!  Return the device trap handler information
    const uint64_t* deviceTrapInfo() const { return deviceTrapInfo_; }

protected:

    const amd::Context* context_;          ///< context that used to create host queue for the debugger
    amd::Device*        device_;           ///< Device to run the debugger

    cl_PreDispatchCallBackFunctionAMD   preDispatchCallBackFunc_;   //!< pre-dispatch callback function
    cl_PostDispatchCallBackFunctionAMD  postDispatchCallBackFunc_;  //!< post-dispatch callback function
    void* preDispatchCallBackArgs_;         //!< pre-dispatch callback function arguments
    void* postDispatchCallBackArgs_;        //!< post-dispatch callback function arguments

    DispatchDebugInfo   debugInfo_;         //!< Debug setting/information for kernel dispatch
    uint64_t    deviceTrapInfo_[kDebugTrapLocationMax];    //!< Device trap buffer, to store various trap handlers on the device

    amd::Memory**    paramMemory_;          //!< list of memory pointers for kernel parameters
    uint32_t         numParams_;            //!< number of kernel parameters

    void*       aclBinary_;                 //!< ACL binary

    address     aqlCodeAddr_;               //!< The mapped AQL code to allow host access
    uint32_t    aqlCodeSize_;               //!< The size of the AQL code info

    address     scratchRingAddr_;           //!< The mapped address of the scratch buffer
    uint32_t    scratchRingSize_;           //!< The size of the scratch ring

    bool isRegistered_;                     //! flag to indicate the debugger has been registered
    bool dbgMsgBufferReady_;                //! flag to indicate the HW DEBUG is using

    cl_dbg_exception_policy_amd     excpPolicy_;         //!< exception policy
    cl_dbg_kernel_exec_mode_amd     execMode_;           //!< kernel execution mode
    RuntimeTrapInfo                 rtTrapHandlerInfo_;  //!< Runtime trap information

};



/**@}*/

/**
 * @}
 */
} // namespace amd

#endif  // HWDEBUG_H_