Joseph Macaranas
365 lines
17 KiB
C++
365 lines
17 KiB
C++
/*
|
|
***********************************************************************************************************************
|
|
*
|
|
* Copyright (c) 2017-2025 Advanced Micro Devices, Inc. All Rights Reserved.
|
|
*
|
|
* Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
* of this software and associated documentation files (the "Software"), to deal
|
|
* in the Software without restriction, including without limitation the rights
|
|
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
* copies of the Software, and to permit persons to whom the Software is
|
|
* furnished to do so, subject to the following conditions:
|
|
*
|
|
* The above copyright notice and this permission notice shall be included in all
|
|
* copies or substantial portions of the Software.
|
|
*
|
|
* 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
|
|
* AUTHORS 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 IN THE
|
|
* SOFTWARE.
|
|
*
|
|
**********************************************************************************************************************/
|
|
/**
|
|
***********************************************************************************************************************
|
|
* @file palDbgPrint.h
|
|
* @brief Defines PAL utility collection debug print functionality.
|
|
***********************************************************************************************************************
|
|
*/
|
|
|
|
#pragma once
|
|
|
|
#include "palUtil.h"
|
|
#include <stdarg.h>
|
|
|
|
#if PAL_ENABLE_LOGGING
|
|
#include "palDbgLogHelper.h"
|
|
#endif
|
|
|
|
namespace Util
|
|
{
|
|
#if (PAL_ENABLE_PRINTS_ASSERTS || PAL_ENABLE_LOGGING)
|
|
// Forward declarations.
|
|
class File;
|
|
enum FileAccessMode : uint32;
|
|
|
|
/// Specifies the category of a debug print.
|
|
///
|
|
/// Driver developer can enable/disable each category separately through settings.
|
|
enum DbgPrintCategory : uint32
|
|
{
|
|
DbgPrintCatInfoMsg = 0, ///< Generic informational messages.
|
|
DbgPrintCatWarnMsg, ///< Warning messages.
|
|
DbgPrintCatErrorMsg, ///< Error messages.
|
|
DbgPrintCatScMsg, ///< Generic shader compiler messages.
|
|
DbgPrintCatEventPrintMsg, ///< System event messages.
|
|
DbgPrintCatEventPrintCallbackMsg, ///< System event messages via callback.
|
|
DbgPrintCatMsgFile, ///< All Messages via file.
|
|
DbgPrintCatCount
|
|
};
|
|
|
|
/// Specifies the debug print mode: disabled, print to debugger, or print to file.
|
|
enum class DbgPrintMode : uint32
|
|
{
|
|
Disable, ///< Debug print is ignored.
|
|
Print, ///< Debug print is routed to the debug window or stdout.
|
|
File, ///< Debug print is routed to a file.
|
|
PrintCallback, ///< Debug print is routed to the print callback only
|
|
};
|
|
|
|
/// Flags specifying style controls for a debug print.
|
|
enum DbgPrintStyle : uint32
|
|
{
|
|
DbgPrintStyleDefault = 0x0, ///< Normal mode: has a prefix and a CR-LF.
|
|
DbgPrintStyleNoPrefix = 0x1, ///< Skip the prefix.
|
|
DbgPrintStyleNoCrLf = 0x2, ///< Skip the CR-LF.
|
|
DbgPrintStyleNoPrefixNoCrLf = 0x3, ///< Skip both the prefix and the CR-LF.
|
|
};
|
|
|
|
/// Definition for debug print callback.
|
|
///
|
|
/// @param [in] pUserData User data that is installed with the callback for use by the installer.
|
|
/// @param [in] category Debug print category that the message belongs to.
|
|
/// @param [in] pText Text data to be printed by the callback.
|
|
typedef void (PAL_STDCALL *DbgPrintCallbackFunc)(
|
|
void* pUserdata,
|
|
DbgPrintCategory category,
|
|
const char* pText);
|
|
|
|
/// Debug print callback struct that bundles the callback function and its userdata pointer.
|
|
struct DbgPrintCallback
|
|
{
|
|
DbgPrintCallbackFunc pCallbackFunc;
|
|
void* pUserdata;
|
|
};
|
|
|
|
/// Generic debug printf function to be used when the caller wishes to specify the output category and style. Clients
|
|
/// should use the PAL_DPF macro instead of calling this function directly.
|
|
///
|
|
/// @param [in] category Message category (e.g., CS dumps, SC output, etc.).
|
|
/// @param [in] style Text output style (i.e., has prefix and/or CR-LF).
|
|
/// @param [in] pFormat Printf-style format string.
|
|
extern void DbgPrintf(
|
|
DbgPrintCategory category,
|
|
DbgPrintStyle style,
|
|
const char* pFormat,
|
|
...);
|
|
|
|
/// Generic printf function to be used when the caller wishes to specify the output category and style, and has
|
|
/// pre-started the variable arg list (va_list argument instead of ...).
|
|
///
|
|
/// @param [in] category Message category (e.g., CS dumps, SC output, etc.).
|
|
/// @param [in] style Text output style (i.e., has prefix and/or CR-LF).
|
|
/// @param [in] pFormat Printf-style format string.
|
|
/// @param [in] argList Variable argument list.
|
|
extern void DbgVPrintf(
|
|
DbgPrintCategory category,
|
|
DbgPrintStyle style,
|
|
const char* pFormat,
|
|
va_list argList);
|
|
|
|
#endif
|
|
|
|
#if PAL_ENABLE_PRINTS_ASSERTS
|
|
/// Sets the debug print mode (output to debugger, write to file, or disabled) for the specified category of messages.
|
|
///
|
|
/// Probably controlled by a setting and set during initialization.
|
|
///
|
|
/// @param [in] category Message category to control (e.g., CS dumps, SC output, etc.).
|
|
/// @param [in] mode New mode to be used for this message category (print to file, etc.).
|
|
extern void SetDbgPrintMode(
|
|
DbgPrintCategory category,
|
|
DbgPrintMode mode);
|
|
|
|
/// Opens a file that resides in the selected log directory.
|
|
///
|
|
/// This function exists in all build configurations.
|
|
///
|
|
/// @param [in,out] pFile File object to represent the opened file.
|
|
/// @param [in] pFilename Filename to open.
|
|
/// @param [in] flags ORed mask of FileAccessMode values specifying how this file will be accessed.
|
|
///
|
|
/// @returns Success if successful, otherwise an appropriate error.
|
|
extern Result OpenLogFile(
|
|
File* pFile,
|
|
const char* pFilename,
|
|
uint32 flags);
|
|
|
|
/// Sets the global debug print callback.
|
|
///
|
|
/// @param [in] callback Debug print callback struct that contains the callback function and a userdata pointer
|
|
extern void SetDbgPrintCallback(
|
|
const DbgPrintCallback& callback);
|
|
|
|
#endif
|
|
|
|
// Forward declarations.
|
|
template<typename CharT> class StringView;
|
|
|
|
/// Logs a text string via client callback when provided.
|
|
///
|
|
/// @param [in] pClientData Pointer to client-defined data. The pClientData value specified in the pLogCbInfo
|
|
/// parameter to CreatePlatform() will be passed back to the client on every log callback.
|
|
/// @param [in] level Log priority level associated with the message.
|
|
/// @param [in] categoryMask Log category mask that represents what category fields the message relates to.
|
|
/// @param [in] pFormat Format string for the log message.
|
|
/// @param [in] args Variable arguments that correspond to the format string.
|
|
typedef void (PAL_STDCALL *LogCallbackFunc)(
|
|
void* pClientData,
|
|
uint32 level,
|
|
uint64 categoryMask,
|
|
const char* pFormat,
|
|
va_list args);
|
|
|
|
/// Specifies client-provided logging callbacks. Used as a parameter to Pal::CreatePlatform().
|
|
///
|
|
/// @ingroup LibInit
|
|
struct LogCallbackInfo
|
|
{
|
|
void* pClientData; ///< Opaque pointer to data of client's choosing. This pointer will be passed back to
|
|
/// every @ref LogCallbackFunc call made by PAL.
|
|
LogCallbackFunc pfnLogCb; ///< Debug print logging callback. @see LogCallbackFunc.
|
|
};
|
|
|
|
/// Compiler-specific wrapper of the standard snprintf implementation.
|
|
///
|
|
/// @param [out] pOutput Output string.
|
|
/// @param [in] bufSize Available space in pOutput.
|
|
/// @param [in] pFormat Printf-style format string.
|
|
///
|
|
/// @returns The resultant length of the formatted string.
|
|
extern int32 Snprintf(
|
|
char* pOutput,
|
|
size_t bufSize,
|
|
const char* pFormat,
|
|
...);
|
|
|
|
/// Compiler-specific wrapper of the standard vsnprintf implementation.
|
|
///
|
|
/// @param [out] pOutput Output string. If buffer is a nullptr it returns the length of the string that would be
|
|
/// printed had a buffer with enough space been provided.
|
|
/// @param [in] bufSize Available space in pOutput.
|
|
/// @param [in] pFormat Printf-style format string.
|
|
/// @param [in] argList variable argument list.
|
|
///
|
|
/// @returns The resultant length of the formatted string.
|
|
extern int32 Vsnprintf(
|
|
char* pOutput,
|
|
size_t bufSize,
|
|
const char* pFormat,
|
|
va_list argList);
|
|
|
|
/// Compiler-specific wrapper of the standard snprintf implementation.
|
|
///
|
|
/// @param [out] pOutput Output string.
|
|
/// @param [in] bufSize Available space in pOutput.
|
|
/// @param [in] pFormat Printf-style format string.
|
|
///
|
|
/// @returns The resultant length of the formatted string.
|
|
extern int32 Snprintf(
|
|
wchar_t* pOutput,
|
|
size_t bufSize,
|
|
const wchar_t* pFormat,
|
|
...);
|
|
|
|
/// Compiler-specific wrapper of the standard vsnprintf implementation.
|
|
///
|
|
/// @param [out] pOutput Output string. If buffer is a nullptr it returns the length of the string that would be
|
|
/// printed had a buffer with enough space been provided.
|
|
/// @param [in] bufSize Available space in pOutput.
|
|
/// @param [in] pFormat Printf-style format string.
|
|
/// @param [in] argList variable argument list.
|
|
///
|
|
/// @returns The resultant length of the formatted string.
|
|
extern int32 Vsnprintf(
|
|
wchar_t* pOutput,
|
|
size_t bufSize,
|
|
const wchar_t* pFormat,
|
|
va_list argList);
|
|
|
|
/// Copy an arbitrary string into the provided buffer, encoding as necessary to avoid characters that are illegal
|
|
/// in filenames (assuming the more restrictive Windows rules, even on non-Windows OSs).
|
|
///
|
|
/// Any byte that would be illegal is encoded as % then two hex digits, like in a URL.
|
|
///
|
|
/// @param [out] pOutput Output string.
|
|
/// @param bufSize Available space in pOutput.
|
|
/// @param [in] input Input string
|
|
/// @param allowSpace Allow (do not % encode) space
|
|
/// @param allowDirSeparator Allow (do not % encode) / and \ characters
|
|
///
|
|
/// @returns Works like C++ standard snprintf:
|
|
/// - If the provided buffer is big enough, it returns the number of bytes written, excluding the
|
|
/// terminating \0.
|
|
/// - If the provided buffer is not big enough, then the result string is truncated to fit, and the
|
|
/// function returns the number of bytes that would have been written if the buffer had been long
|
|
/// enough, excluding the terminating \0.
|
|
/// - Passing 0 buffer length is allowed as a special case of that, and nullptr pOutput is then allowed.
|
|
extern size_t EncodeAsFilename(
|
|
char* pOutput,
|
|
size_t bufSize,
|
|
const StringView<char>& input,
|
|
bool allowSpace,
|
|
bool allowDirSeparator);
|
|
|
|
/// Generate a log filename.
|
|
///
|
|
/// @param [inout] pFilenameBuffer Buffer to hold the filename.
|
|
/// @param maxSize Max size of the pFilenameBuffer.
|
|
/// @param nextPost The next write position.
|
|
/// @param [in] pExt The filename extension.
|
|
/// @param logDuplicate Log duplicate objects.
|
|
extern void GenLogFilename(
|
|
char* pFilenameBuffer,
|
|
size_t maxSize,
|
|
size_t nextPos,
|
|
const char* const pExt,
|
|
bool logDuplicate);
|
|
|
|
} // Util
|
|
|
|
/// PAL_ENABLE_LOGGING enables the new logging code. At this time, both, the current and new logging
|
|
/// code will be active for development purpose if both macros are enabled.
|
|
#if (PAL_ENABLE_PRINTS_ASSERTS && PAL_ENABLE_LOGGING)
|
|
/// Debug printf macro.
|
|
#define PAL_DPF ::Util::DbgPrintf
|
|
/// Debug info printf macro.
|
|
#define PAL_DPINFO(_pFormat, ...) \
|
|
{ \
|
|
::Util::DbgPrintf(::Util::DbgPrintCatInfoMsg, ::Util::DbgPrintStyleDefault, _pFormat " (%s:%d:%s)", \
|
|
##__VA_ARGS__, __FILE__, __LINE__, __func__); \
|
|
::Util::DbgLog(::Util::SeverityLevel::Info, ::Util::OriginationType::DebugPrint, \
|
|
"AMD-PAL", _pFormat " (%s:%d:%s)", ##__VA_ARGS__, __FILE__, __LINE__, __func__); \
|
|
}
|
|
/// Debug warning printf macro.
|
|
#define PAL_DPWARN(_pFormat, ...) \
|
|
{ \
|
|
::Util::DbgPrintf(::Util::DbgPrintCatWarnMsg, ::Util::DbgPrintStyleDefault, _pFormat " (%s:%d:%s)", \
|
|
##__VA_ARGS__, __FILE__, __LINE__, __func__); \
|
|
::Util::DbgLog(::Util::SeverityLevel::Warning, ::Util::OriginationType::DebugPrint, \
|
|
"AMD-PAL", _pFormat " (%s:%d:%s)", ##__VA_ARGS__, __FILE__, __LINE__, __func__); \
|
|
}
|
|
/// Debug error printf macro.
|
|
#define PAL_DPERROR(_pFormat, ...) \
|
|
{ \
|
|
::Util::DbgPrintf(::Util::DbgPrintCatErrorMsg, ::Util::DbgPrintStyleDefault, _pFormat " (%s:%d:%s)", \
|
|
##__VA_ARGS__, __FILE__, __LINE__, __func__); \
|
|
::Util::DbgLog(::Util::SeverityLevel::Error, ::Util::OriginationType::DebugPrint, \
|
|
"AMD-PAL", _pFormat " (%s:%d:%s)", ##__VA_ARGS__, __FILE__, __LINE__, __func__); \
|
|
}
|
|
#elif PAL_ENABLE_PRINTS_ASSERTS
|
|
/// Debug printf macro.
|
|
#define PAL_DPF ::Util::DbgPrintf
|
|
/// Debug info printf macro.
|
|
#define PAL_DPINFO(_pFormat, ...) \
|
|
{ \
|
|
::Util::DbgPrintf(::Util::DbgPrintCatInfoMsg, ::Util::DbgPrintStyleDefault, _pFormat " (%s:%d:%s)", \
|
|
##__VA_ARGS__, __FILE__, __LINE__, __func__); \
|
|
}
|
|
/// Debug warning printf macro.
|
|
#define PAL_DPWARN(_pFormat, ...) \
|
|
{ \
|
|
::Util::DbgPrintf(::Util::DbgPrintCatWarnMsg, ::Util::DbgPrintStyleDefault, _pFormat " (%s:%d:%s)", \
|
|
##__VA_ARGS__, __FILE__, __LINE__, __func__); \
|
|
}
|
|
/// Debug error printf macro.
|
|
#define PAL_DPERROR(_pFormat, ...) \
|
|
{ \
|
|
::Util::DbgPrintf(::Util::DbgPrintCatErrorMsg, ::Util::DbgPrintStyleDefault, _pFormat " (%s:%d:%s)", \
|
|
##__VA_ARGS__, __FILE__, __LINE__, __func__); \
|
|
}
|
|
#elif PAL_ENABLE_LOGGING
|
|
/// Debug printf macro.
|
|
#define PAL_DPF ::Util::DbgPrintf
|
|
/// Debug info printf macro.
|
|
#define PAL_DPINFO(_pFormat, ...) \
|
|
{ \
|
|
::Util::DbgLog(::Util::SeverityLevel::Info, ::Util::OriginationType::DebugPrint, \
|
|
"AMD-PAL", _pFormat " (%s:%d:%s)", ##__VA_ARGS__, __FILE__, __LINE__, __func__); \
|
|
}
|
|
/// Debug warning printf macro.
|
|
#define PAL_DPWARN(_pFormat, ...) \
|
|
{ \
|
|
::Util::DbgLog(::Util::SeverityLevel::Warning, ::Util::OriginationType::DebugPrint, \
|
|
"AMD-PAL", _pFormat " (%s:%d:%s)", ##__VA_ARGS__, __FILE__, __LINE__, __func__); \
|
|
}
|
|
/// Debug error printf macro.
|
|
#define PAL_DPERROR(_pFormat, ...) \
|
|
{ \
|
|
::Util::DbgLog(::Util::SeverityLevel::Error, ::Util::OriginationType::DebugPrint, \
|
|
"AMD-PAL", _pFormat " (%s:%d:%s)", ##__VA_ARGS__, __FILE__, __LINE__, __func__); \
|
|
}
|
|
#else
|
|
/// Debug printf macro.
|
|
#define PAL_DPF(...) ((void)0)
|
|
/// Debug info printf macro.
|
|
#define PAL_DPINFO(...) ((void)0)
|
|
/// Debug warning printf macro.
|
|
#define PAL_DPWARN(...) ((void)0)
|
|
/// Debug error printf macro.
|
|
#define PAL_DPERROR(...) ((void)0)
|
|
#endif
|
|
|