/* *********************************************************************************************************************** * * 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 #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 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& 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