303 lines
12 KiB
C
303 lines
12 KiB
C
|
/* SPDX-License-Identifier: MIT */
|
||
|
|
/**
|
||
|
|
@file debugshare.h
|
||
|
|
@brief Declares the constants used for sharing debug messages. These structures are used
|
||
|
|
to gather debug messages and share them with the applications that report and log.
|
||
|
|
@note This file is shared with drivers written in c.
|
||
|
|
@copyright (C) 2009-2021 AJA Video Systems, Inc. All rights reserved.
|
||
|
|
**/
|
||
|
|
|
||
|
|
#ifndef AJA_DEBUGSHARE_H
|
||
|
|
#define AJA_DEBUGSHARE_H
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The list of debug message severity codes.
|
||
|
|
* @ingroup AJAGroupDebug
|
||
|
|
*/
|
||
|
|
///@{
|
||
|
|
typedef enum _AJADebugSeverity
|
||
|
|
{
|
||
|
|
AJA_DebugSeverity_Emergency = 0, /**< System is unusable */
|
||
|
|
AJA_DebugSeverity_Alert = 1, /**< Action must be taken immediately */
|
||
|
|
AJA_DebugSeverity_Assert = 2, /**< Assert conditions */
|
||
|
|
AJA_DebugSeverity_Error = 3, /**< Error conditions */
|
||
|
|
AJA_DebugSeverity_Warning = 4, /**< Warning conditions */
|
||
|
|
AJA_DebugSeverity_Notice = 5, /**< Normal but significant condition */
|
||
|
|
AJA_DebugSeverity_Info = 6, /**< Informational */
|
||
|
|
AJA_DebugSeverity_Debug = 7, /**< Debug-level messages */
|
||
|
|
AJA_DebugSeverity_Size = 8 /**< Size of severity enum, must be last */
|
||
|
|
|
||
|
|
} AJADebugSeverity;
|
||
|
|
///@}
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The list of debug message groups.
|
||
|
|
* @ingroup AJAGroupDebug
|
||
|
|
*/
|
||
|
|
///@{
|
||
|
|
typedef enum _AJADebugUnit
|
||
|
|
{
|
||
|
|
AJA_DebugUnit_Unknown = 0,
|
||
|
|
AJA_DebugUnit_Critical = 1,
|
||
|
|
AJA_DebugUnit_DriverGeneric = 2,
|
||
|
|
AJA_DebugUnit_ServiceGeneric = 3,
|
||
|
|
AJA_DebugUnit_UserGeneric = 4,
|
||
|
|
AJA_DebugUnit_VideoGeneric = 5,
|
||
|
|
AJA_DebugUnit_AudioGeneric = 6,
|
||
|
|
AJA_DebugUnit_TimecodeGeneric = 7,
|
||
|
|
AJA_DebugUnit_AncGeneric = 8,
|
||
|
|
AJA_DebugUnit_RoutingGeneric = 9,
|
||
|
|
AJA_DebugUnit_StatsGeneric = 10,
|
||
|
|
AJA_DebugUnit_Enumeration = 11,
|
||
|
|
AJA_DebugUnit_Application = 12,
|
||
|
|
AJA_DebugUnit_QuickTime = 13,
|
||
|
|
AJA_DebugUnit_ControlPanel = 14,
|
||
|
|
AJA_DebugUnit_Watcher = 15,
|
||
|
|
AJA_DebugUnit_Plugins = 16,
|
||
|
|
AJA_DebugUnit_CCLine21Decode = 17,
|
||
|
|
AJA_DebugUnit_CCLine21Encode = 18,
|
||
|
|
AJA_DebugUnit_CC608DataQueue = 19,
|
||
|
|
AJA_DebugUnit_CC608MsgQueue = 20,
|
||
|
|
AJA_DebugUnit_CC608Decode = 21,
|
||
|
|
AJA_DebugUnit_CC608DecodeChannel = 22,
|
||
|
|
AJA_DebugUnit_CC608DecodeScreen = 23,
|
||
|
|
AJA_DebugUnit_CC608Encode = 24,
|
||
|
|
AJA_DebugUnit_CC708Decode = 25,
|
||
|
|
AJA_DebugUnit_CC708Service = 26,
|
||
|
|
AJA_DebugUnit_CC708ServiceBlockQueue = 27,
|
||
|
|
AJA_DebugUnit_CC708Window = 28,
|
||
|
|
AJA_DebugUnit_CC708Encode = 29,
|
||
|
|
AJA_DebugUnit_CCFont = 30,
|
||
|
|
AJA_DebugUnit_SMPTEAnc = 31,
|
||
|
|
AJA_DebugUnit_AJAAncData = 32,
|
||
|
|
AJA_DebugUnit_AJAAncList = 33,
|
||
|
|
AJA_DebugUnit_Testing = 34,
|
||
|
|
AJA_DebugUnit_PnP = 35,
|
||
|
|
AJA_DebugUnit_Persistence = 36,
|
||
|
|
AJA_DebugUnit_Avid = 37,
|
||
|
|
AJA_DebugUnit_DriverInterface = 38,
|
||
|
|
AJA_DebugUnit_AutoCirculate = 39,
|
||
|
|
AJA_DebugUnit_NMOS = 40,
|
||
|
|
AJA_DebugUnit_App_DiskRead = 41,
|
||
|
|
AJA_DebugUnit_App_DiskWrite = 42,
|
||
|
|
AJA_DebugUnit_App_Decode = 43,
|
||
|
|
AJA_DebugUnit_App_Encode = 44,
|
||
|
|
AJA_DebugUnit_App_DMA = 45,
|
||
|
|
AJA_DebugUnit_App_Screen = 46,
|
||
|
|
AJA_DebugUnit_App_User1 = 47,
|
||
|
|
AJA_DebugUnit_App_User2 = 48,
|
||
|
|
AJA_DebugUnit_Anc2110Xmit = 49,
|
||
|
|
AJA_DebugUnit_Anc2110Rcv = 50,
|
||
|
|
AJA_DebugUnit_DemoPlayout = 51,
|
||
|
|
AJA_DebugUnit_DemoCapture = 52,
|
||
|
|
AJA_DebugUnit_CSC = 53,
|
||
|
|
AJA_DebugUnit_LUT = 54,
|
||
|
|
AJA_DebugUnit_Cables = 55,
|
||
|
|
AJA_DebugUnit_RPCServer = 56,
|
||
|
|
AJA_DebugUnit_RPCClient = 57,
|
||
|
|
AJA_DebugUnit_Firmware = 58,
|
||
|
|
|
||
|
|
// to add a new unit:
|
||
|
|
//
|
||
|
|
// if there is an unused unit below:
|
||
|
|
//
|
||
|
|
// * rename the next available unused and move above this comment block
|
||
|
|
// * make sure the enum starts with "AJA_DebugUnit_"
|
||
|
|
// * update the value of AJA_DebugUnit_FirstUnused with the value of the new next available unused
|
||
|
|
//
|
||
|
|
// else if there are not any unused units below:
|
||
|
|
//
|
||
|
|
// * add the new unit above this message block with the next available index
|
||
|
|
// * make sure the enum starts with "AJA_DebugUnit_"
|
||
|
|
// * increment AJA_DebugUnit_Size by 1
|
||
|
|
//
|
||
|
|
// if no more unused units
|
||
|
|
// * set AJA_DebugUnit_FirstUnused to the same value as AJA_DebugUnit_Size
|
||
|
|
//
|
||
|
|
AJA_DebugUnit_FirstUnused = 59,
|
||
|
|
AJA_DebugUnit_Unused_59 = AJA_DebugUnit_FirstUnused,
|
||
|
|
AJA_DebugUnit_Unused_60 = 60,
|
||
|
|
AJA_DebugUnit_Unused_61 = 61,
|
||
|
|
AJA_DebugUnit_Unused_62 = 62,
|
||
|
|
AJA_DebugUnit_Unused_63 = 63,
|
||
|
|
AJA_DebugUnit_Unused_64 = 64,
|
||
|
|
AJA_DebugUnit_Unused_65 = 65,
|
||
|
|
AJA_DebugUnit_Unused_66 = 66,
|
||
|
|
AJA_DebugUnit_Unused_67 = 67,
|
||
|
|
AJA_DebugUnit_Unused_68 = 68,
|
||
|
|
AJA_DebugUnit_Unused_69 = 69,
|
||
|
|
AJA_DebugUnit_Unused_70 = 70,
|
||
|
|
AJA_DebugUnit_Unused_71 = 71,
|
||
|
|
AJA_DebugUnit_Unused_72 = 72,
|
||
|
|
AJA_DebugUnit_Unused_73 = 73,
|
||
|
|
AJA_DebugUnit_Unused_74 = 74,
|
||
|
|
AJA_DebugUnit_Unused_75 = 75,
|
||
|
|
AJA_DebugUnit_Unused_76 = 76,
|
||
|
|
AJA_DebugUnit_Unused_77 = 77,
|
||
|
|
AJA_DebugUnit_Unused_78 = 78,
|
||
|
|
AJA_DebugUnit_Unused_79 = 79,
|
||
|
|
AJA_DebugUnit_Unused_80 = 80,
|
||
|
|
AJA_DebugUnit_Unused_81 = 81,
|
||
|
|
AJA_DebugUnit_Unused_82 = 82,
|
||
|
|
AJA_DebugUnit_Unused_83 = 83,
|
||
|
|
AJA_DebugUnit_Unused_84 = 84,
|
||
|
|
|
||
|
|
AJA_DebugUnit_Size = 85
|
||
|
|
|
||
|
|
} AJADebugUnit;
|
||
|
|
///@}
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
@defgroup AJAUnitDestination AJA_DEBUG_DESTINATION
|
||
|
|
Bit definitions that specify the destination of a debug message.
|
||
|
|
|
||
|
|
@ingroup AJAGroupDebug
|
||
|
|
Use logical OR for multiple destinations.
|
||
|
|
**/
|
||
|
|
///@{
|
||
|
|
#define AJA_DEBUG_DESTINATION_NONE 0 /**< Unknown destination, used as default */
|
||
|
|
#define AJA_DEBUG_DESTINATION_DEBUG 0x00000001 /**< Send message to the debug window */
|
||
|
|
#define AJA_DEBUG_DESTINATION_CONSOLE 0x00000002 /**< Send message to the console */
|
||
|
|
#define AJA_DEBUG_DESTINATION_LOG 0x00000004 /**< Send message to a log file */
|
||
|
|
#define AJA_DEBUG_DESTINATION_DRIVER 0x00000008 /**< Send message directly to driver output (driver messages only) */
|
||
|
|
///@}
|
||
|
|
|
||
|
|
/**
|
||
|
|
@defgroup AJAGroupVarious AJA_DEBUG
|
||
|
|
Various parameters that define the characteristics of the shared debug memory space.
|
||
|
|
SDK 16.0 introduced a new stats measurement feature that still allows logging to work in pre-16.0 clients.
|
||
|
|
@ingroup AJAGroupDebug
|
||
|
|
**/
|
||
|
|
///@{
|
||
|
|
#define AJA_DEBUG_MAGIC_ID AJA_FOURCC('D','B','U','G') /**< Magic identifier of the debug system */
|
||
|
|
#define AJA_DEBUG_VERSION 110 /**< Version of the debug system */
|
||
|
|
#define AJA_DEBUG_UNIT_ARRAY_SIZE 65536 /**< Number of unit destinations */
|
||
|
|
#define AJA_DEBUG_SEVERITY_ARRAY_SIZE 64 /**< Number of severity destinations */
|
||
|
|
#define AJA_DEBUG_MAX_NUM_STATS 256 /**< Max number of individual stats measurements (multiple of 64) */
|
||
|
|
#define AJA_DEBUG_STAT_DEQUE_SIZE 11
|
||
|
|
#define AJA_DEBUG_MESSAGE_MAX_SIZE 512 /**< Maximum size of a message */
|
||
|
|
#define AJA_DEBUG_MESSAGE_RING_SIZE 4096 /**< Size of the message ring */
|
||
|
|
#define AJA_DEBUG_FILE_NAME_MAX_SIZE 512 /**< Maximum size of a file name */
|
||
|
|
#define AJA_DEBUG_SHARE_NAME "aja-shm-debug" /**< Name of the shared memory for the debug messages */
|
||
|
|
#define AJA_DEBUG_TICK_RATE 1000000 /**< Resolution of debug time in ticks/second */
|
||
|
|
#define AJA_DEBUG_STATE_FILE_VERSION 510 /**< Version number of the state file format */
|
||
|
|
///@}
|
||
|
|
|
||
|
|
/**
|
||
|
|
Structure representing the debug message.
|
||
|
|
@ingroup AJAGroupDebug
|
||
|
|
**/
|
||
|
|
|
||
|
|
// using a 16 byte alignment for arm64 atomic operations to work properly
|
||
|
|
#pragma pack(push, 16)
|
||
|
|
|
||
|
|
typedef struct _AJADebugMessage
|
||
|
|
{
|
||
|
|
uint64_t sequenceNumber; /**< Sequence number of this message */
|
||
|
|
int64_t time; /**< Time this message was generated (microseconds) */
|
||
|
|
int64_t wallTime; /**< Time this message was generated as returned by time() */
|
||
|
|
int32_t groupIndex; /**< Group that generated this message */
|
||
|
|
uint32_t destinationMask; /**< Destination of the message */
|
||
|
|
int32_t severity; /**< Severity of the message */
|
||
|
|
int32_t lineNumber; /**< Source file line number that generated this message */
|
||
|
|
uint64_t pid; /**< Process ID that generated the message */
|
||
|
|
uint64_t tid; /**< Thread ID that generated the message */
|
||
|
|
char fileName[AJA_DEBUG_FILE_NAME_MAX_SIZE]; /**< Source file name that generated this message */
|
||
|
|
char messageText[AJA_DEBUG_MESSAGE_MAX_SIZE]; /**< Text generated for this message */
|
||
|
|
} AJADebugMessage;
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
64-byte structure representing an unsigned 32-bit measurement (timer, counter or data value).
|
||
|
|
As a timer, it stores minimum, maximum and average elapsed time in microseconds.
|
||
|
|
As a data value, it stores minimum, maximum, moving average value, and last update usec timestamp.
|
||
|
|
As a counter, it can increment or decrement, with or without rollover/rollunder.
|
||
|
|
@ingroup AJAGroupDebug
|
||
|
|
**/
|
||
|
|
class AJADebugStat
|
||
|
|
{
|
||
|
|
public:
|
||
|
|
uint32_t fMin; /**< Smallest value yet seen. (Fixed at 0xFFFFFFFF and unused for counters.) */
|
||
|
|
uint32_t fMax; /**< Largest value yet seen. (Fixed at zero and unused for counters.) */
|
||
|
|
uint32_t fCount; /**< Update/change count */
|
||
|
|
uint64_t fLastTimeStamp; /**< Timestamp (start time for timer, zero if not running; last update time for counter or data value) */
|
||
|
|
uint32_t fValues[AJA_DEBUG_STAT_DEQUE_SIZE]; /**< Deque that provides an 11-sample moving average. (Unused for counters.) */
|
||
|
|
|
||
|
|
AJADebugStat() {Reset();}
|
||
|
|
|
||
|
|
void Reset (void)
|
||
|
|
{
|
||
|
|
fMin = 0xFFFFFFFF;
|
||
|
|
fMax = fCount = 0;
|
||
|
|
fLastTimeStamp = 0;
|
||
|
|
for (size_t n(0); n < AJA_DEBUG_STAT_DEQUE_SIZE; n++)
|
||
|
|
fValues[n] = 0;
|
||
|
|
}
|
||
|
|
|
||
|
|
double Average(void) const; /**< Returns the average of the stored values */
|
||
|
|
uint64_t Sum (const size_t inNum = 0) const; /**< Returns the sum of the first "inNum" stored values */
|
||
|
|
void Start (void); /**< Starts a timer by setting fLastTimeStamp to the high-resolution host OS system timestamp */
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Stops the timer, stores the elapsed time in the deque, bumps fCount, and clears fLastTimeStamp.
|
||
|
|
* Also updates fMin and/or fMax if necessary.
|
||
|
|
*/
|
||
|
|
void Stop (void);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Increments fCount by the given amount, and sets fLastTimeStamp.
|
||
|
|
* @param[in] inIncrement Optionally specifies a different increment value. Defaults to 1.
|
||
|
|
* @param[in] inRollOver Optionally controls if overflow is permitted. Defaults to true.
|
||
|
|
*/
|
||
|
|
void Increment (const uint32_t inIncrement = 1, const bool inRollOver = true);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Decrements fCount by the given amount, and sets fLastTimeStamp.
|
||
|
|
* @param[in] inDecrement Optionally specifies a different increment value. Defaults to 1.
|
||
|
|
* @param[in] inRollUnder Optionally controls if underflow is permitted. Defaults to true.
|
||
|
|
*/
|
||
|
|
void Decrement (const uint32_t inDecrement = 1, const bool inRollUnder = true);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Inserts the given value into the deque, bumps fCount, and sets fLastTimeStamp to the current time.
|
||
|
|
* @param[in] inValue Specifies the value to store.
|
||
|
|
* @param[in] inStamp Optionally specifies whether to set the timestamp or not. Defaults to true.
|
||
|
|
*/
|
||
|
|
void SetValue (const uint32_t inValue, const bool inStamp = true);
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
Structure representing the shared debug groups and messages.
|
||
|
|
@ingroup AJAGroupDebug
|
||
|
|
**/
|
||
|
|
typedef struct _AJADebugShare
|
||
|
|
{
|
||
|
|
uint32_t magicId; /**< Magic cookie identifier used to id this as an AJADebugShare structure */
|
||
|
|
uint32_t version; /**< Version of the debug system */
|
||
|
|
uint64_t volatile writeIndex; /**< Write index for the message ring */
|
||
|
|
int32_t volatile clientRefCount; /**< A count of current number of clients using structure*/
|
||
|
|
|
||
|
|
uint32_t messageRingCapacity; /**< The number of messages that can be in the ring */
|
||
|
|
uint32_t messageTextCapacity; /**< The maximum text capacity of message in bytes */
|
||
|
|
uint32_t messageFileNameCapacity; /**< The maximum text capacity of message filename in bytes */
|
||
|
|
uint32_t unitArraySize; /**< The number of unit destinations */
|
||
|
|
|
||
|
|
uint64_t volatile statsMessagesAccepted; /**< The number of messages accepted into the ring since creation */
|
||
|
|
uint64_t volatile statsMessagesIgnored; /**< The number of messages ignored since creation, filtered out */
|
||
|
|
|
||
|
|
uint32_t statCapacity; /**< The number of stats that can be stored, or zero if no stat facility (new in SDK 16) */
|
||
|
|
uint32_t volatile statAllocChanges; /**< Number of changes to statAllocMask (new in SDK 16.0) */
|
||
|
|
uint64_t statAllocMask[AJA_DEBUG_MAX_NUM_STATS/64]; /**< Stats allocation bitmask, 1 bit per stats measurement (new in SDK 16.0) */
|
||
|
|
uint32_t reserved[128 - 1 - 1 - 2*AJA_DEBUG_MAX_NUM_STATS/64]; /**< Reserved (was [128] in version 110) */
|
||
|
|
uint32_t unitArray[AJA_DEBUG_UNIT_ARRAY_SIZE]; /**< Array of message destinations by unit */
|
||
|
|
AJADebugMessage messageRing[AJA_DEBUG_MESSAGE_RING_SIZE]; /**< Message ring holding current message data */
|
||
|
|
AJADebugStat stats[AJA_DEBUG_MAX_NUM_STATS]; /**< Per-stat measurement data (new in v111) */
|
||
|
|
} AJADebugShare;
|
||
|
|
|
||
|
|
#pragma pack(pop)
|
||
|
|
|
||
|
|
#endif // AJA_DEBUGSHARE_H
|