API

2016-10-31 15:53:07 chip Page 1912 📢 PUBLIC

October 31 2016

Guide

DbgOut is a programmer's tool that is embedded into the project's source code.

Getting Started

The program should initialize the DbgOut pipeline during its start up, typically from WinMain (or DllMain).

WinMain.c: #ifndef DBGOUT static __inline void DbgOutStart(void) { } static __inline void DbgOutEnd(void) { } #else static void DbgOutStart(void); static void DbgOutEnd(void); struct DbgOutChannelList_s gTrace; #endif int WINAPI WinMain(HINSTANCE hInst,HINSTANCE hPrev,LPSTR CmdLine,int ShowCmd) { int Err= ERR_OK; ghInst= hInst; DbgOutStart(); ... DbgOutEnd(); return(Err); } #ifdef DBGOUT static void DbgOutStart(void) { int Err; if(DbgErr(Err= DbgOutCreate(DBGOUT_API,"TextEdit"))) { OutputDebugString(L"DbgOutCreate failed.\r\n"); } else { LARGE_INTEGER Freq; QueryPerformanceFrequency(&Freq); DbgOut(0,"TextEdit startup HINSTANCE %X",ghInst); DbgOut(DBG_INIT,"QueryPerformanceFrequency: %llu",Freq.QuadPart); } } static void DbgOutEnd(void) { DbgOut(0,"TextEdit shutdown."); DbgOutDestroy(); } #endif

Creating Trace Channels

Trace events are identified by channels, much like an oscilloscope displays multiple trace channels. DbgOut can store up to 511 separate channels. These channels are identifed by only the channel ID, which must be unique across all clients. Each channel can be assigned a text name and type.

Trace channels require a bit more set up work. The trace channels are global across all clients and the assignment of channels needs to be coordinated. I can maintain my own table of channels to make sure the same channel ID is never reused, or an unused channel ID can be requested from the DbgOut server.

If the channels are defined using constant values, the user only needs to set the text name for each channel. For example, I

Trace: Setting the channel name: #define DBGTRACE_MSGPROC 1 DbgTraceNameA(DBGTRACE_MSGPROC,DBGTRACE_TYPE_HILO,"MsgProc");

Alternatively, I can set the channels dynamically by letting DbgOut allocate unused channels and storing the allocated channels for use later.

Trace: Allocating channels: static struct TraceName_s { const char *Name; WORD Type; WORD ID; //To be assigned. } TraceNames[]= { { "Fast", DBGTRACE_TYPE_HILO }, { "Print", DBGTRACE_TYPE_HILO }, { "Sine", DBGTRACE_TYPE_PLOT }, { "Tangent", DBGTRACE_TYPE_PLOT }, { 0 } }; static int DbgOutAssignChannels(const char *Name) { UINT n1; for(n1=0;TraceNames[n1].Name;n1++) DbgTraceChnlAlloc(TraceNames[n1].Type,TraceNames[n1].Name,&TraceNames[n1].ID); }

Channel events are displayed differently depending on which trace type I assign.

DBGTRACE_TYPE_HILO: On/Off or In/Out events that store only the time and a binary state and are displayed as a HIGH/LOW trace. Use events to record the time spent inside a function. Events require the least amount of data and are the most efficient.
DBGTRACE_TYPE_PLOT: Data events that store the time and a 32bit value that is displayed as a Time/Value plot. These events are used to record things such as the amount of available memory over time.
DBGTRACE_TYPE_STATE: Data events that store the time and a 32bit value that labels a time range with the state value. The channel can be linked to a ID table that lets the viewer translate the state number to friendly text.

API

Guide

Getting Started

Creating Trace Channels

Reference