813 lines
44 KiB
C
813 lines
44 KiB
C
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
/// \file ealperf.h Engine Abstraction Layer Performance Logging Reference API
|
|
//
|
|
// For any questions/feedback please email gearsupport@ubisoft.com.
|
|
//
|
|
// See the ealdef.h file for details on how to use the various EAL APIs.
|
|
//
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
#ifndef __EALPERF_H_INCLUDED
|
|
#define __EALPERF_H_INCLUDED
|
|
|
|
#include "ealdef.h"
|
|
#include <cstdarg>
|
|
|
|
/// This module covers the performance logging reference API.
|
|
/*! \addtogroup Perf
|
|
@{
|
|
*/
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/// Interface version.
|
|
/// The format is an integer value equal to Major.Minor multiplied by 100 (Version 2.10 = 210).
|
|
/// See ealdef.h for more information.
|
|
#define EAL_PERF_VERSION 300
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/// \page Performance Tracks
|
|
/// The performance logging system is based on a track system. Each track can contain a variable
|
|
/// amount of events.
|
|
/// Each client is allowed to declare as many tracks as they want. It is up to the engine to select
|
|
/// which track to record and how much memory to dedicate to each one.
|
|
/// The track format is based on the unique identifier system. See ealdef.h for details.
|
|
|
|
/// \page Performance Time Unit
|
|
/// The unit of time is different for each platform, but usually maps to the unit
|
|
/// of the most precise hardware clock available. We call this unit "cycle" even
|
|
/// though the value may not represent an actual number of CPU cycles.
|
|
/// Here is what you should use on each platform:
|
|
/// - \b Win32/Win64/Durango: QueryPerformanceCounter
|
|
/// - \b Xenon: __mftb with safety loop
|
|
/// - \b PS3 PPU: SYS_TIMEBASE_GET
|
|
/// - \b Orbis: sceKernelReadTsc
|
|
/// - \b Cafe: OSGetTime
|
|
/// - \b Mac/iOS: mach_absolute_time
|
|
/// - \b Linux/Android: clock_gettime with CLOCK_MONOTONIC
|
|
/// - \b Vita: sceKernelGetProcessTime
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
/// Thread identifier
|
|
/// \deprecated DEPRECATED since version 3.00 (there is no replacement), will be removed in version 6.00
|
|
/// The thread ID type that needs to be used for the functions in the performance API. You need to use
|
|
/// the normal system thread IDs in most cases when running from the CPU. When instrumenting SPU
|
|
/// or GPU code, you should use the constants from eal_tid_constants.
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
typedef eal_u32 eal_perf_tid;
|
|
|
|
/// Thread ID constants.
|
|
/// \deprecated DEPRECATED since version 3.00 (there is no replacement), will be removed in version 6.00
|
|
enum eal_perf_tid_constants
|
|
{
|
|
// Current thread ID.
|
|
EAL_PERF_CURRENT_TID = 0,
|
|
/// Mask to obtain the index of the thread for a particular tid constant.
|
|
EAL_PERF_TID_IDX_MASK = 0x000000FF,
|
|
/// Base SPU thread ID.
|
|
EAL_PERF_BASE_SPU_TID = 0xCE110000,
|
|
/// Base GPU thread ID.
|
|
EAL_PERF_BASE_GPU_TID = 0xC0104000
|
|
};
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/// Structure used in Log functions.
|
|
/// \deprecated DEPRECATED since version 3.00 (there is no replacement), will be removed in version 6.00
|
|
struct eal_perf_event_info
|
|
{
|
|
const char* pCaption; /// A static string describing the event. Cannot be NULL.
|
|
const char* pFilename; /// A static string containing the filename where the event is located.
|
|
eal_id TrackId; /// The track identifier (see EalPerfSetTrackInfo()).
|
|
eal_u32 Line; /// The line number from where the event is located.
|
|
};
|
|
|
|
/// Structure used in Log functions.
|
|
/// \deprecated DEPRECATED since version 3.00 (there is no replacement), will be removed in version 6.00
|
|
struct eal_perf_event_ref
|
|
{
|
|
const char* pCaption; /// A static string describing the event. Cannot be NULL.
|
|
eal_id TrackId; /// The track identifier (see EalPerfSetTrackInfo()).
|
|
};
|
|
|
|
/// This is used to contain everything that is static for an entry in the performance log.
|
|
struct eal_perf_static_point
|
|
{
|
|
const char* pStaticCaption; /// A static string describing the entry. Cannot be NULL.
|
|
const char* pFileName; /// A static string to the source file where the entry is logged (usually taken from __FILE__). Can be NULL.
|
|
eal_id TrackId; /// An EAL ID used to organize and filter events in the performance log. Should at least be a product ID.
|
|
eal_u32 FileLine; /// The line number in the source file where the entry is logged (usually taken from __LINE__). Can be 0.
|
|
};
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Initialize the library.
|
|
\return true if initialization succeeded
|
|
|
|
\param Version Must be equal to current version = \ref EAL_PERF_VERSION
|
|
|
|
\PRECONDITIONS
|
|
- Must be called before any other API call.
|
|
- The client must keep track of the number of successful calls to EalPerfLibInit(), so
|
|
EalPerfLibShutdown() is called the exact same number of times.
|
|
- Implementation version must be no more than 3 versions higher.
|
|
|
|
\POSTCONDITIONS
|
|
- The library will be initialized and all APIs calls will be allowed.
|
|
- EalPerfLibShutdown() must be called only if initialization succeeded
|
|
|
|
\sa EalPerfLibShutdown
|
|
*/
|
|
EAL_DLL_ENTRY bool EalPerfLibInit(eal_u32 Version = EAL_PERF_VERSION);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Shut down the library after usage.
|
|
\PRECONDITIONS
|
|
- It must be called once for every call to EalPerfLibInit().
|
|
|
|
\POSTCONDITIONS
|
|
- You are not allowed to call any other library members after calling EalPerfLibShutdown().
|
|
|
|
\sa EalPerfLibInit
|
|
*/
|
|
EAL_DLL_ENTRY void EalPerfLibShutdown();
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Copies a dynamic string into a permanent storage on the implementation
|
|
side and returns a pointer to that copy, which can then safely be used as
|
|
the 'customString' parameter of EalPerf*WithPayload functions.
|
|
If the implementation cannot store the string, the return value is
|
|
implementation-defined. It can be NULL or set to a fixed string indicating
|
|
the problem.
|
|
Unlike \ref EalPerfConvertTemporaryStringVa, this function only needs to be
|
|
called once per dynamic string.
|
|
NOTE: As dynamic strings cannot be removed and will keep accumulating over
|
|
time, please use this function with parsimony.
|
|
|
|
\param pDynamicString A pointer on a string that needs to be copied. Can be NULL.
|
|
\return A pointer on a string that is safe to be passed to the EalPerf*WithPayload functions. Can be NULL.
|
|
|
|
\PRECONDITIONS
|
|
- Multithread safe call
|
|
|
|
\POSTCONDITIONS
|
|
- The returned string pointer can be used until \ref EalPerfLibShutdown is called.
|
|
|
|
\sa EalPerfConvertTemporaryStringVa, EalPerfBeginTaskWithPayload, EalPerfEndTaskWithPayload, EalPerfAddEventWithPayload
|
|
*/
|
|
EAL_DLL_ENTRY const char* EalPerfConvertDynamicString(const char* pDynamicString);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Provide information for a specific track.
|
|
\param TrackId A unique track ID. See ealdef.h for details on how to define IDs.
|
|
\param pTrackName A static string containing the name of the track. Cannot be NULL.
|
|
|
|
\PRECONDITIONS
|
|
- Multithread safe call
|
|
- This function can be called only once per track.
|
|
- It can be called at any time, even after logging on this track using EalPerf logging functions.
|
|
|
|
\sa EalPerfLogEvent, EalPerfLogEndEvent
|
|
*/
|
|
EAL_DLL_ENTRY void EalPerfSetTrackInfo(eal_id TrackId, const char* pTrackName);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Log an event.
|
|
\deprecated DEPRECATED since version 3.00 (use \ref EalPerfAddEvent instead), will be removed in version 6.00
|
|
This function is used to log an event that happens at a point in time and has no duration.
|
|
|
|
\param ThreadID The system thread ID, or a special constant from \ref eal_perf_tid_constants.
|
|
\param EventTime The time the event occurred. See \ref perftracks for details.
|
|
\param EventInfo A reference on a constant & static structure that must stay valid
|
|
until the logging data is actually sent/dumped.
|
|
See \ref eal_perf_event_info for details on the content of the struct.
|
|
\param pCaptionParam An optional string parameter that can be used in the EventInfo Caption.
|
|
The Event info caption can contain a '%s', which will be replaced by
|
|
pCaptionParam. Can be NULL. pCaption param must stay valid until the
|
|
logging data is actually send/dumped.
|
|
\param pExtraData Extra data can be stored with the event. Can be NULL if none.
|
|
Data must be aligned on an multiple of 4 bytes. This data will
|
|
be copied and thus can be modified or freed after this call.
|
|
\param ExtraDataSize Size of the extra data to store (in bytes).
|
|
|
|
\PRECONDITIONS
|
|
- pExtraData must be aligned on 4 bytes.
|
|
- ExtraDataSize must be 0 if pExtraData is NULL.
|
|
|
|
\sa EalPerfSetThreadInfo, EalPerfSetTrackInfo
|
|
*/
|
|
EAL_DLL_ENTRY void EalPerfLogEvent2(eal_perf_tid ThreadID,
|
|
const eal_u64& EventTime,
|
|
const eal_perf_event_info& EventInfo,
|
|
const char* pCaptionParam,
|
|
void* pExtraData,
|
|
eal_u32 ExtraDataSize);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Log the beginning of a range event.
|
|
\deprecated DEPRECATED since version 3.00 (use \ref EalPerfBeginTask instead), will be removed in version 6.00
|
|
A range event is an event that has a duration. This function is used to log the start of such
|
|
events. Use EalPerfLogEndEvent() to specify the end of this event.
|
|
|
|
\param ThreadID The system thread ID or a special constant from \ref eal_perf_tid_constants.
|
|
\param UniqueId A unique value that will be used by EalPerfLogEndEvent2 to link with this one.
|
|
\param Time The time the event started. See \ref perftracks for details.
|
|
\param EventInfo A reference on a constant & static structure that must stay valid
|
|
until the logging data is actually sent/dumped.
|
|
See \ref eal_perf_event_info for details on the content of the struct.
|
|
\param pCaptionParam An optional string parameter that can be used in the EventInfo Caption.
|
|
The Event info caption can contain a '%s', which will be replaced by
|
|
pCaptionParam. Can be NULL. pCaption param must stay valid until the
|
|
logging data is actually sent/dumped.
|
|
\param pExtraData Extra data can be stored with the event. Can be NULL if none.
|
|
Data must be aligned on a multiple of 4 bytes. This data will
|
|
be copied; therefore, it can be modified or freed after this call.
|
|
\param ExtraDataSize Size of the extra data to store (in bytes).
|
|
|
|
\PRECONDITIONS
|
|
- pExtraData must be aligned on 4 bytes.
|
|
- ExtraDataSize must be 0 if pExtraData is NULL.
|
|
\sa EalPerfSetThreadInfo, EalPerfSetTrackInfo
|
|
|
|
\sa EalPerfSetThreadInfo, EalPerfSetTrackInfo, EalPerfLogEndEvent2, EalPerfLogEventData2
|
|
*/
|
|
EAL_DLL_ENTRY void EalPerfLogBeginEvent2(eal_perf_tid ThreadID,
|
|
eal_u32 UniqueId,
|
|
const eal_u64& Time,
|
|
const eal_perf_event_info& EventInfo,
|
|
const char* pCaptionParam,
|
|
void* pExtraData,
|
|
eal_u32 ExtraDataSize);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Log the end of a range event.
|
|
\deprecated DEPRECATED since version 3.00 (use \ref EalPerfEndTask instead), will be removed in version 6.00
|
|
This function is used to log the end of an event. It will be associated with the
|
|
EalPerfLogBeginEvent() which contains the same: pCaption, pCaptionParam, TrackId & UniqueId.
|
|
|
|
\param UniqueId Value used to link with the corresponding BeginEvent with the same UID.
|
|
\param EventTime The time the event occurred. See \ref perftracks for details.
|
|
\param EventRef A reference on a constant & static structure that must stay valid
|
|
until the logging data is actually sent/dumped.
|
|
\param pCaptionParam An optional string parameter that can be used in the EventInfo Caption.
|
|
The Event info caption can contain a '%s', which will be replaced by
|
|
pCaptionParam. Can be NULL. pCaption param must stay valid until the
|
|
logging data is actually sent/dumped.
|
|
|
|
\PRECONDITIONS
|
|
- Must come after a call to EalPerfLogBeginEvent() with the same caption, thread id and track id.
|
|
|
|
\sa EalPerfSetThreadInfo, EalPerfSetTrackInfo, EalPerfLogBeginEvent2, EalPerfLogEventData2
|
|
*/
|
|
EAL_DLL_ENTRY void EalPerfLogEndEvent2(eal_u32 UniqueId,
|
|
const eal_u64& EventTime,
|
|
const eal_perf_event_ref& EventRef,
|
|
const char* pCaptionParam);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Log a range event.
|
|
\deprecated DEPRECATED since version 3.00 (use \ref EalPerfAddTask instead), will be removed in version 6.00
|
|
This function is used to log a range event in a single function call.
|
|
|
|
\param ThreadID The system thread ID or a special constant from \ref eal_perf_tid_constants.
|
|
\param StartTime The time the event occurred. See \ref perftracks for details.
|
|
\param Duration The duration of the event. see \ref perftracks for details.
|
|
\param EventInfo A reference on a constant & static structure that must stay valid
|
|
until the logging data is actually sent/dumped.
|
|
See \ref eal_perf_event_info for details on the content of the struct.
|
|
\param pCaptionParam An optional string parameter that can be used in the EventInfo Caption.
|
|
The Event info caption can contain a '%s', which will be replaced by
|
|
pCaptionParam. Can be NULL. pCaption param must stay valid until the
|
|
logging data is actually sent/dumped.
|
|
\param pExtraData Extra data can be stored with the event. Can be NULL if none.
|
|
Data must be aligned on a multiple of 4 bytes. This data will
|
|
be copied; therefore, it can be modified or freed after this call.
|
|
\param ExtraDataSize Size of the extra data to store (in bytes).
|
|
|
|
\PRECONDITIONS
|
|
- pExtraData must be aligned on 4 bytes.
|
|
- ExtraDataSize must be 0 if pExtraData is NULL.
|
|
\sa EalPerfSetThreadInfo, EalPerfSetTrackInfo
|
|
|
|
\sa EalPerfSetThreadInfo, EalPerfSetTrackInfo, EalPerfLogEndEvent2, EalPerfLogEventData2
|
|
*/
|
|
EAL_DLL_ENTRY void EalPerfLogRangeEvent2(eal_perf_tid ThreadID,
|
|
const eal_u64& StartTime,
|
|
const eal_u64& Duration,
|
|
const eal_perf_event_info& EventInfo,
|
|
const char* pCaptionParam,
|
|
void* pExtraData,
|
|
eal_u32 ExtraDataSize);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Append additional data to the last logged event.
|
|
\deprecated DEPRECATED since version 3.00 (there is no replacement), will be removed in version 6.00
|
|
This function is used to provide additional data to the last event logged by the same ThreadID
|
|
|
|
\param ThreadID The system thread ID or a special constant from \ref eal_perf_tid_constants.
|
|
\param pData Data to be stored with the event. Cannot be NULL.
|
|
Data must be aligned on a multiple of 4 bytes. This data will
|
|
be copied and thus can be modified or freed after this call.
|
|
\param DataSize Size of the data to store (in bytes).
|
|
|
|
\sa EalPerfSetThreadInfo, EalPerfSetTrackInfo, EalPerfLogEvent2, EalPerfLogBeginEvent2
|
|
*/
|
|
EAL_DLL_ENTRY void EalPerfLogEventData2(eal_perf_tid ThreadID,
|
|
void* pData,
|
|
eal_u32 DataSize);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Provide information on threads.
|
|
\deprecated DEPRECATED since version 3.00 (there is no replacement), will be removed in version 6.00
|
|
|
|
\param ThreadID The system thread ID or a special constant from \ref eal_perf_tid_constants.
|
|
\param Priority The thread priority. The value is system dependent.
|
|
\param Affinity The affinity mask of the thread.
|
|
\param pThreadName A string containing the thread name. Can be NULL if name did not change.
|
|
|
|
\PRECONDITIONS
|
|
- Multithread safe call
|
|
- This function can be called as often as needed or every time one of the parameters change.
|
|
*/
|
|
EAL_DLL_ENTRY void EalPerfSetThreadInfo(eal_perf_tid ThreadID,
|
|
eal_u32 Priority,
|
|
eal_u32 Affinity,
|
|
const char* pThreadName);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Log an event.
|
|
\deprecated DEPRECATED since version 3.00 (use \ref EalPerfAddEvent instead), will be removed in version 6.00
|
|
This function is used to log an event that happens at a point in time and has no duration.
|
|
|
|
\param pCaption A static string describing the event. Cannot be NULL.
|
|
\param ThreadID The system thread ID or a special constant from \ref eal_perf_tid_constants.
|
|
\param TrackId The track identifier (see EalPerfSetTrackInfo()).
|
|
\param EventTime The time the event occurred.
|
|
\param pExtraData Extra data can be stored with the event. Can be NULL if none.
|
|
Data must be aligned on an multiple of 4 bytes. This data will
|
|
be copied and thus can be modified or freed after this call.
|
|
\param ExtraDataSize Size of the extra data to store (in bytes).
|
|
\param pFilename A static string containing the filename where the event is located.
|
|
\param Line The line number from where the event is located.
|
|
|
|
\PRECONDITIONS
|
|
- pExtraData must be aligned on 4 bytes
|
|
|
|
\sa EalPerfSetThreadInfo, EalPerfSetTrackInfo
|
|
*/
|
|
EAL_DLL_ENTRY void EalPerfLogEvent(const char* pCaption,
|
|
eal_perf_tid ThreadID,
|
|
eal_id TrackId,
|
|
const eal_u64& EventTime,
|
|
void* pExtraData,
|
|
eal_u32 ExtraDataSize,
|
|
const char* pFilename,
|
|
eal_u32 Line);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Log the beginning of a range event.
|
|
\deprecated DEPRECATED since version 3.00 (use \ref EalPerfBeginTask instead), will be removed in version 6.00
|
|
A range event is an event that has a duration. This function is used to log the start of such
|
|
an event. Use EalPerfLogEndEvent() to specify the end of this event.
|
|
|
|
\param pCaption A static string describing the event. Cannot be NULL.
|
|
\param ThreadID The system thread ID, or a special constant from \ref eal_perf_tid_constants.
|
|
\param TrackId The track identifier (see EalPerfSetTrackInfo()).
|
|
\param TimeStart The time the event started.
|
|
\param pExtraData Extra data can be stored with the event. Can be NULL if none.
|
|
Data must be aligned on a multiple of 4 bytes. This data will
|
|
be copied; therefore, it can be modified or freed after this call.
|
|
\param ExtraDataSize Size of the extra data to store (in bytes).
|
|
\param pFilename A static string containing the filename where the event is located.
|
|
\param Line The line number from where the event is located.
|
|
|
|
\PRECONDITIONS
|
|
- pExtraData must be aligned on 4 bytes
|
|
|
|
\sa EalPerfSetThreadInfo, EalPerfSetTrackInfo, EalPerfLogEndEvent, EalPerfLogEventData
|
|
*/
|
|
EAL_DLL_ENTRY void EalPerfLogBeginEvent(const char* pCaption,
|
|
eal_perf_tid ThreadID,
|
|
eal_id TrackId,
|
|
const eal_u64& TimeStart,
|
|
void* pExtraData,
|
|
eal_u32 ExtraDataSize,
|
|
const char* pFilename,
|
|
eal_u32 Line);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Log the end of a range event.
|
|
\deprecated DEPRECATED since version 3.00 (use \ref EalPerfEndTask instead), will be removed in version 6.00
|
|
This function is used to log the end of an event. Must come after a call to EalPerfLogBeginEvent()
|
|
with the same caption, thread id and track id.
|
|
|
|
\param pCaption A static string describing the event. Cannot be NULL.
|
|
\param ThreadID The system thread ID, or a special constant from \ref eal_perf_tid_constants.
|
|
\param TrackId The track identifier (see EalPerfSetTrackInfo()).
|
|
\param TimeEnd The time the event ended.
|
|
|
|
\PRECONDITIONS
|
|
- Must come after a call to EalPerfLogBeginEvent() with the same caption, thread id and track id.
|
|
|
|
\sa EalPerfSetThreadInfo, EalPerfSetTrackInfo, EalPerfLogBeginEvent, EalPerfLogEventData
|
|
*/
|
|
EAL_DLL_ENTRY void EalPerfLogEndEvent(const char* pCaption,
|
|
eal_perf_tid ThreadID,
|
|
eal_id TrackId,
|
|
const eal_u64& TimeEnd);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Log a range event.
|
|
\deprecated DEPRECATED since version 3.00 (use \ref EalPerfAddTask instead), will be removed in version 6.00
|
|
This function is used to log a range event in a single function call.
|
|
|
|
\param pCaption A static string describing the event. Cannot be NULL.
|
|
\param ThreadID The system thread ID, or a special constant from \ref eal_perf_tid_constants.
|
|
\param TrackId The track identifier (see EalPerfSetTrackInfo()).
|
|
\param TimeStart The time the event started.
|
|
\param TimeEnd The time the event ended.
|
|
\param pExtraData Extra data can be stored with the event. Can be NULL if none.
|
|
Data must be aligned on a multiple of 4 bytes. This data will
|
|
be copied; therefore, it can be modified or freed after this call.
|
|
\param ExtraDataSize Size of the extra data to store (in bytes).
|
|
\param pFilename A static string containing the filename where the event is located.
|
|
\param Line The line number from where the event is located.
|
|
|
|
\PRECONDITIONS
|
|
- pExtraData must be aligned on 4 bytes
|
|
|
|
\sa EalPerfSetThreadInfo, EalPerfSetTrackInfo, EalPerfLogEndEvent, EalPerfLogEventData
|
|
*/
|
|
EAL_DLL_ENTRY void EalPerfLogRangeEvent(const char* pCaption,
|
|
eal_perf_tid ThreadID,
|
|
eal_id TrackId,
|
|
const eal_u64& TimeStart,
|
|
const eal_u64& TimeEnd,
|
|
void* pExtraData,
|
|
eal_u32 ExtraDataSize,
|
|
const char* pFilename,
|
|
eal_u32 Line);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Append additional data to the last logged event.
|
|
\deprecated DEPRECATED since version 3.00 (there is no replacement), will be removed in version 6.00
|
|
This function is used to provide additional data to the last event logged in the same thread
|
|
and track ID.
|
|
|
|
\param pCaption A static string describing the nature of the data. Cannot be NULL.
|
|
\param ThreadID The system thread ID, or a special constant from \ref eal_perf_tid_constants.
|
|
\param TrackId The track identifier (see EalPerfSetTrackInfo()).
|
|
\param pData Data to be stored with the event. Cannot be NULL.
|
|
Data must be aligned on a multiple of 4 bytes. This data will
|
|
be copied; therefore, it can be modified or freed after this call.
|
|
\param DataSize Size of the data to store (in bytes).
|
|
|
|
\sa EalPerfSetThreadInfo, EalPerfSetTrackInfo, EalPerfLogBeginEvent, EalPerfLogEventData
|
|
*/
|
|
EAL_DLL_ENTRY void EalPerfLogEventData(const char* pCaption,
|
|
eal_perf_tid ThreadID,
|
|
eal_id TrackId,
|
|
void* pData,
|
|
eal_u32 DataSize);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Formats and registers a temporary string for use as a custom string in
|
|
EalPerf*WithPayload functions.
|
|
Unlike strings returned from \ref EalPerfConvertDynamicString, the
|
|
returned string pointer becomes invalid every time the log is flushed on
|
|
the implementer's side, so this function needs to be called every time
|
|
before calling the EalPerf*WithPayload function with a temporary string.
|
|
This is intended for debugging complex cases where the formatted string
|
|
may vary a lot and cannot be accumulated indefinitely. A performance hit
|
|
is expected so do not use temporary strings in your default operating mode.
|
|
|
|
\param pFormat The printf-style format string for the temporary string.
|
|
\param Args The arguments that match the format string.
|
|
\return A pointer on a string that is safe to be passed to EalPerf*WithPayload functions.
|
|
|
|
\PRECONDITIONS
|
|
- Multithread safe call
|
|
|
|
\POSTCONDITIONS
|
|
- The returned pointer can only be used within the scope where the function is called.
|
|
|
|
\sa EalPerfConvertDynamicString, EalPerfBeginTaskWithPayload, EalPerfEndTaskWithPayload, EalPerfAddEventWithPayload
|
|
*/
|
|
EAL_DLL_ENTRY const char* EalPerfConvertTemporaryStringVa(
|
|
const char* pFormat,
|
|
va_list Args);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Begins a task interval in the performance log.
|
|
|
|
\param Point The static profile point where the task started.
|
|
\param Time The value of the hardware counter when the task started (in "cycles").
|
|
|
|
\PRECONDITIONS
|
|
- Multithread safe call
|
|
- Data in 'point' follow the conditions explained in \ref eal_perf_static_point.
|
|
|
|
\POSTCONDITIONS
|
|
- Must be followed symmetrically with a call to \ref EalPerfEndTask or \ref EalPerfEndTaskWithPayload using a static point with the same track and static caption pointer.
|
|
|
|
\sa EalPerfConvertDynamicString, EalPerfConvertTemporaryStringVa, EalPerfEndTask, EalPerfEndTaskWithPayload
|
|
*/
|
|
EAL_DLL_ENTRY void EalPerfBeginTask(
|
|
const eal_perf_static_point& Point,
|
|
eal_u64 Time);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Begins a task interval in the performance log, with a custom payload.
|
|
|
|
\param Point The static profile point where the task started.
|
|
\param Time The value of the hardware counter when the task started (in "cycles").
|
|
\param pCustomString An optional custom string that will be passed in the performance log. Can be NULL.
|
|
Must remain valid until the log is flushed (which can be unsafe),
|
|
or be the result of \ref EalPerfConvertDynamicString or \ref EalPerfConvertTemporaryStringVa (both of which guarantees validity).
|
|
\param pPayload Optional data to be copied in the performance log. Can be NULL.
|
|
Because it will be copied, the data does not have to be persistent.
|
|
\param PayloadSize Size of the payload. If payload is NULL, must be 0.
|
|
|
|
\PRECONDITIONS
|
|
- Multithread safe call
|
|
- Data in 'point' follow the conditions explained in \ref eal_perf_static_point.
|
|
- The data pointed to by 'payload' must remain stable and valid until the call returns.
|
|
|
|
\POSTCONDITIONS
|
|
- Must be followed symmetrically with a call to \ref EalPerfEndTask or \ref EalPerfEndTaskWithPayload using a static point with the same track and static caption pointer.
|
|
|
|
\sa EalPerfConvertDynamicString, EalPerfConvertTemporaryStringVa, EalPerfEndTask, EalPerfEndTaskWithPayload
|
|
*/
|
|
EAL_DLL_ENTRY void EalPerfBeginTaskWithPayload(
|
|
const eal_perf_static_point& Point,
|
|
eal_u64 Time,
|
|
const char* pCustomString,
|
|
const void* pPayload,
|
|
eal_size_t PayloadSize);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Ends a task interval in the performance log.
|
|
|
|
\param Point The static profile point where the task ended.
|
|
\param Time The value of the hardware counter when the task ended (in "cycles").
|
|
|
|
\PRECONDITIONS
|
|
- Multithread safe call
|
|
- Data in 'point' follow the conditions explained in \ref eal_perf_static_point.
|
|
- Must be preceded symmetrically with a call to \ref EalPerfBeginTask or \ref EalPerfBeginTaskWithPayload using a static point with the same track and static caption pointer.
|
|
|
|
\sa EalPerfConvertDynamicString, EalPerfConvertTemporaryStringVa, EalPerfBeginTask, EalPerfBeginTaskWithPayload
|
|
*/
|
|
EAL_DLL_ENTRY void EalPerfEndTask(
|
|
const eal_perf_static_point& Point,
|
|
eal_u64 Time);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Ends a task interval in the performance log, with a custom payload.
|
|
|
|
\param Point The static profile point where the task ended.
|
|
\param Time The value of the hardware counter when the task ended (in "cycles").
|
|
\param pCustomString An optional custom string that will be passed in the performance log. Can be NULL.
|
|
Must remain valid until the log is flushed (which can be unsafe),
|
|
or be the result of \ref EalPerfConvertDynamicString or \ref EalPerfConvertTemporaryStringVa (both of which guarantees validity).
|
|
\param pPayload Extra data to be copied in the performance log. It must be copied because it can be dynamic. Can be NULL.
|
|
\param PayloadSize Size of the payload. If payload is NULL, must be 0.
|
|
|
|
\PRECONDITIONS
|
|
- Multithread safe call
|
|
- Data in 'Point' follows the conditions explained in \ref eal_perf_static_point.
|
|
- Must be preceded symmetrically with a call to \ref EalPerfBeginTask or \ref EalPerfBeginTaskWithPayload using a static point with the same track and static caption pointer.
|
|
|
|
\sa EalPerfConvertDynamicString, EalPerfConvertTemporaryStringVa, EalPerfBeginTask, EalPerfBeginTaskWithPayload
|
|
*/
|
|
EAL_DLL_ENTRY void EalPerfEndTaskWithPayload(
|
|
const eal_perf_static_point& Point,
|
|
eal_u64 Time,
|
|
const char* pCustomString,
|
|
const void* pPayload,
|
|
eal_size_t PayloadSize);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Adds a discrete event to the performance log.
|
|
A discrete event is useful to indicate when a certain point is reached in
|
|
the code (e.g. entering/ending a wait, entering a certain condition).
|
|
|
|
\param Point The static profile point where the event occurred.
|
|
\param Time The value of the hardware counter when the event occurred (in "cycles").
|
|
\param Param An optional 64-bit signed value associated with the event.
|
|
|
|
\PRECONDITIONS
|
|
- Multithread safe call
|
|
- Data in 'Point' follows the conditions explained in \ref eal_perf_static_point.
|
|
|
|
\sa EalPerfConvertDynamicString, EalPerfConvertTemporaryStringVa, EalPerfAddEventWithPayload
|
|
*/
|
|
EAL_DLL_ENTRY void EalPerfAddEvent(
|
|
const eal_perf_static_point& Point,
|
|
eal_u64 Time,
|
|
eal_s64 Param);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Adds a discrete event to the performance log, with a custom payload.
|
|
A discrete event is useful to indicate when a certain point is reached in
|
|
the code (e.g. entering/ending a wait, entering a certain condition).
|
|
|
|
\param Point The static profile point where the event occurred.
|
|
\param Time The value of the hardware counter when the event occurred (in "cycles").
|
|
\param Param An optional 64-bit signed value associated with the event.
|
|
\param pCustomString An optional custom string that will be passed in the performance log. Can be NULL.
|
|
Must remain valid until the log is flushed (which can be unsafe),
|
|
or be the result of \ref EalPerfConvertDynamicString or \ref EalPerfConvertTemporaryStringVa (both of which guarantees validity).
|
|
\param pPayload Extra data to be copied in the performance log. It must be copied because it can be dynamic. Can be NULL.
|
|
\param PayloadSize Size of the payload. If payload is NULL, must be 0.
|
|
|
|
\PRECONDITIONS
|
|
- Multithread safe call
|
|
- Data in 'Point' follows the conditions explained in \ref eal_perf_static_point.
|
|
|
|
\sa EalPerfConvertDynamicString, EalPerfConvertTemporaryStringVa, EalPerfAddEvent
|
|
*/
|
|
|
|
EAL_DLL_ENTRY void EalPerfAddEventWithPayload(
|
|
const eal_perf_static_point& Point,
|
|
eal_u64 Time,
|
|
eal_s64 Param,
|
|
const char* pCustomString,
|
|
const void* pPayload,
|
|
eal_size_t PayloadSize);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Adds a warning count to the performance log.
|
|
A warning count can be used to indicate that a quantity (e.g. time, memory,
|
|
number of instances) has reached/exceeded a soft limit.
|
|
|
|
\param Point The static profile point where the event occurred.
|
|
\param Time The value of the hardware counter when the warning occurred (in "cycles").
|
|
\param Count The warning count value. Can be negative.
|
|
|
|
\PRECONDITIONS
|
|
- Multithread safe call
|
|
- Data in 'Point' follows the conditions explained in \ref eal_perf_static_point.
|
|
|
|
\sa EalPerfConvertDynamicString, EalPerfConvertTemporaryStringVa
|
|
*/
|
|
EAL_DLL_ENTRY void EalPerfAddWarningCount(
|
|
const eal_perf_static_point& Point,
|
|
eal_u64 Time,
|
|
eal_s64 Count);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
// The next section is only used if you are using Dynamic Linking (DLL). //
|
|
// If not, simply ignore this section. All the code declared in the next section is //
|
|
// implemented in the corresponding CPP file (ealxxxdll.cpp). //
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/// This structure contains a pointer to all EAL Perf functions.
|
|
struct eal_perf_dll_interface
|
|
{
|
|
bool (*pEalPerfLibInit)(eal_u32 Version);
|
|
void (*pEalPerfLibShutdown)();
|
|
void (*pEalPerfSetTrackInfo)(eal_id TrackId, const char* pTrackName);
|
|
|
|
// BEGIN DEPRECATED
|
|
void (*pEalPerfSetThreadInfo) (eal_perf_tid ThreadID,
|
|
eal_u32 Priority,
|
|
eal_u32 Affinity,
|
|
const char* pThreadName);
|
|
void (*pEalPerfLogEvent) (const char* pCaption,
|
|
eal_perf_tid ThreadID,
|
|
eal_id TrackId,
|
|
const eal_u64& EventTime,
|
|
void* pExtraData,
|
|
eal_u32 ExtraDataSize,
|
|
const char* pFilename,
|
|
eal_u32 Line);
|
|
void (*pEalPerfLogBeginEvent) (const char* pCaption,
|
|
eal_perf_tid ThreadID,
|
|
eal_id TrackId,
|
|
const eal_u64& TimeStart,
|
|
void* pExtraData,
|
|
eal_u32 ExtraDataSize,
|
|
const char* pFilename,
|
|
eal_u32 Line);
|
|
void (*pEalPerfLogEndEvent) (const char* pCaption,
|
|
eal_perf_tid ThreadID,
|
|
eal_id TrackId,
|
|
const eal_u64& TimeEnd);
|
|
void (*pEalPerfLogRangeEvent) (const char* pCaption,
|
|
eal_perf_tid ThreadID,
|
|
eal_id TrackId,
|
|
const eal_u64& TimeStart,
|
|
const eal_u64& TimeEnd,
|
|
void* pExtraData,
|
|
eal_u32 ExtraDataSize,
|
|
const char* pFilename,
|
|
eal_u32 Line);
|
|
void (*pEalPerfLogEventData) (const char* pCaption,
|
|
eal_perf_tid ThreadID,
|
|
eal_id TrackId,
|
|
void* pData,
|
|
eal_u32 DataSize);
|
|
// END DEPRECATED
|
|
|
|
const char* (*pEalPerfConvertDynamicString)(const char* pDynamicString);
|
|
|
|
// BEGIN DEPRECATED
|
|
void (*pEalPerfLogEvent2) (eal_perf_tid ThreadID,
|
|
const eal_u64& EventTime,
|
|
const eal_perf_event_info& EventInfo,
|
|
const char* pCaptionParam,
|
|
void* pExtraData,
|
|
eal_u32 ExtraDataSize);
|
|
void (*pEalPerfLogBeginEvent2) (eal_perf_tid ThreadID,
|
|
eal_u32 UniqueId,
|
|
const eal_u64& Time,
|
|
const eal_perf_event_info& EventInfo,
|
|
const char* pCaptionParam,
|
|
void* pExtraData,
|
|
eal_u32 ExtraDataSize);
|
|
void (*pEalPerfLogEndEvent2) (eal_u32 UniqueId,
|
|
const eal_u64& EventTime,
|
|
const eal_perf_event_ref& EventRef,
|
|
const char* pCaptionParam);
|
|
void (*pEalPerfLogRangeEvent2) (eal_perf_tid ThreadID,
|
|
const eal_u64& StartTime,
|
|
const eal_u64& Duration,
|
|
const eal_perf_event_info& EventInfo,
|
|
const char* pCaptionParam,
|
|
void* pExtraData,
|
|
eal_u32 ExtraDataSize);
|
|
void (*pEalPerfLogEventData2) (eal_perf_tid ThreadID,
|
|
void* pData,
|
|
eal_u32 DataSize);
|
|
// END DEPRECATED
|
|
|
|
const char* (*pEalPerfConvertTemporaryStringVa)(const char* pFormat, va_list Args);
|
|
void (*pEalPerfBeginTask)(const eal_perf_static_point& Point, eal_u64 Time);
|
|
void (*pEalPerfBeginTaskWithPayload)(const eal_perf_static_point& Point, eal_u64 Time, const char* pCustomString, const void* pPayload, eal_size_t PayloadSize);
|
|
void (*pEalPerfEndTask)(const eal_perf_static_point& Point, eal_u64 Time);
|
|
void (*pEalPerfEndTaskWithPayload)(const eal_perf_static_point& Point, eal_u64 Time, const char* pCustomString, const void* pPayload, eal_size_t PayloadSize);
|
|
void (*pEalPerfAddEvent)(const eal_perf_static_point& Point, eal_u64 Time, eal_s64 Param);
|
|
void (*pEalPerfAddEventWithPayload)(const eal_perf_static_point& Point, eal_u64 Time, eal_s64 Param, const char* pCustomString, const void* pPayload, eal_size_t PayloadSize);
|
|
void (*pEalPerfAddWarningCount)(const eal_perf_static_point& Point, eal_u64 Time, eal_s64 Count);
|
|
};
|
|
|
|
#if defined(EAL_DLL) || defined(EAL_IMPORT_DLL)
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Only defined on the DLL side. It is used to resolve dynamic functions.
|
|
This function should be called by the DLL initialization code and must be done before any
|
|
call to any EAL functions.
|
|
\param Interface A structure containing valid pointers to the engine EAL functions.
|
|
\sa EalPerfDllPopulateInterface
|
|
*/
|
|
void EalPerfDllInitInterface(const eal_perf_dll_interface& Interface);
|
|
|
|
#else // #if defined(EAL_DLL) || defined(EAL_IMPORT_DLL)
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*! Only defined on the engine side. It is used to fill up the Interface structure.
|
|
This function is provided by the ealperfdll package. It fills up the interface structure
|
|
with pointers to the current EAL functions implemented in the engine. You can then
|
|
pass this structure to the DLL so it will dynamically connect its internal EAL
|
|
function calls to the one in your engine.
|
|
\param Interface A structure that will be filled with pointers to local EAL functions.
|
|
\sa EalPerfDllInitInterface
|
|
*/
|
|
void EalPerfDllPopulateInterface(eal_perf_dll_interface& Interface);
|
|
|
|
#endif // #if defined(EAL_DLL) || defined(EAL_IMPORT_DLL)
|
|
|
|
/*! @} */
|
|
|
|
#endif // #ifdef __EALPERF_H_INCLUDED
|