VirtualBox

source: vbox/trunk/include/iprt/tracelog.h@ 71496

Last change on this file since 71496 was 71496, checked in by vboxsync, 7 years ago

Doxygen

  • Property svn:executable set to *
File size: 20.5 KB
Line 
1/** @file
2 * IPRT - Binary trace log API.
3 */
4
5/*
6 * Copyright (C) 2018 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef ___iprt_tracelog_h
27#define ___iprt_tracelog_h
28
29#include <iprt/sg.h>
30#include <iprt/types.h>
31#include <iprt/err.h>
32
33RT_C_DECLS_BEGIN
34
35
36/** @defgroup grp_tracelog RTTraceLog - Binary trace log API
37 * @ingroup grp_rt
38 * @{
39 */
40
41/**
42 * Trace log item type.
43 */
44typedef enum RTTRACELOGTYPE
45{
46 /** Invalid first value. */
47 RTTRACELOGTYPE_INVALID = 0,
48 /** Boolean item type. */
49 RTTRACELOGTYPE_BOOL,
50 /** Unsigned 8bit integer type. */
51 RTTRACELOGTYPE_UINT8,
52 /** Signed 8bit integer type. */
53 RTTRACELOGTYPE_INT8,
54 /** Unsigned 16bit integer type. */
55 RTTRACELOGTYPE_UINT16,
56 /** Signed 16bit integer type. */
57 RTTRACELOGTYPE_INT16,
58 /** Unsigned 32bit integer type. */
59 RTTRACELOGTYPE_UINT32,
60 /** Signed 32bit integer type. */
61 RTTRACELOGTYPE_INT32,
62 /** Unsigned 64bit integer type. */
63 RTTRACELOGTYPE_UINT64,
64 /** Signed 64bit integer type. */
65 RTTRACELOGTYPE_INT64,
66 /** 32bit floating point type. */
67 RTTRACELOGTYPE_FLOAT32,
68 /** 64bit floating point type. */
69 RTTRACELOGTYPE_FLOAT64,
70 /** Raw binary data type. */
71 RTTRACELOGTYPE_RAWDATA,
72 /** Pointer data type. */
73 RTTRACELOGTYPE_POINTER,
74 /** size_t data type. */
75 RTTRACELOGTYPE_SIZE,
76 /** 32-bit hack. */
77 RTTRACELOGTYPE_32BIT_HACK = 0x7fffffff
78} RTTRACELOGTYPE;
79/** Pointer to a trace log item type. */
80typedef RTTRACELOGTYPE *PRTTRACELOGTYPE;
81/** Pointer to a const trace log item type. */
82typedef const RTTRACELOGTYPE *PCRTTRACELOGTYPE;
83
84
85/**
86 * Trace log event severity.
87 */
88typedef enum RTTRACELOGEVTSEVERITY
89{
90 /** Invalid severity. */
91 RTTRACELOGEVTSEVERITY_INVALID = 0,
92 /** Informational event. */
93 RTTRACELOGEVTSEVERITY_INFO,
94 /** Warning event. */
95 RTTRACELOGEVTSEVERITY_WARNING,
96 /** Error event. */
97 RTTRACELOGEVTSEVERITY_ERROR,
98 /** Fatal event. */
99 RTTRACELOGEVTSEVERITY_FATAL,
100 /** Debug event. */
101 RTTRACELOGEVTSEVERITY_DEBUG,
102 /** 32bit hack.*/
103 RTTRACELOGEVTSEVERITY_32BIT_HACK = 0x7fffffff
104} RTTRACELOGEVTSEVERITY;
105/** Pointer to a event severity class. */
106typedef RTTRACELOGEVTSEVERITY *PRTTRACELOGEVTSEVERITY;
107/** Pointer to a const event severiy class. */
108typedef RTTRACELOGEVTSEVERITY *PCRTTRACELOGEVTSEVERITY;
109
110
111/**
112 * Trace log reader event.
113 */
114typedef enum RTTRACELOGRDRPOLLEVT
115{
116 /** Invalid event. */
117 RTTRACELOGRDRPOLLEVT_INVALID = 0,
118 /** The header was received and valid. */
119 RTTRACELOGRDRPOLLEVT_HDR_RECVD,
120 /** Event data was fetched. */
121 RTTRACELOGRDRPOLLEVT_TRACE_EVENT_RECVD,
122 /** 32bit hack. */
123 RTTRACELOGRDRPOLLEVT_32BIT_HACK = 0x7fffffff
124} RTTRACELOGRDRPOLLEVT;
125/** Pointer to a trace log reader event. */
126typedef RTTRACELOGRDRPOLLEVT *PRTTRACELOGRDRPOLLEVT;
127
128
129/**
130 * Trace log event item descriptor.
131 */
132typedef struct RTTRACELOGEVTITEMDESC
133{
134 /** Event item name. */
135 const char *pszName;
136 /** Event item description. */
137 const char *pszDesc;
138 /** Event item type. */
139 RTTRACELOGTYPE enmType;
140 /** The size of the raw data if static for the item,
141 * 0 otherwise (and given when the event is logged).
142 * Only valid for the RTTRACELOGTYPE_RAWDATA type,
143 * ignored otherwise. */
144 size_t cbRawData;
145} RTTRACELOGEVTITEMDESC;
146/** Pointer to an trace log event item descriptor. */
147typedef RTTRACELOGEVTITEMDESC *PRTTRACELOGEVTITEMDESC;
148/** Pointer to a const trace log event item descriptor. */
149typedef const RTTRACELOGEVTITEMDESC *PCRTTRACELOGEVTITEMDESC;
150/** Pointer to a trace log event item descriptor pointer. */
151typedef PRTTRACELOGEVTITEMDESC *PPRTTRACELOGEVTITEMDESC;
152/** Pointer to a const trace log event item descriptor pointer. */
153typedef PCRTTRACELOGEVTITEMDESC *PPCRTTRACELOGEVTITEMDESC;
154
155
156/**
157 * Trace log event descriptor.
158 */
159typedef struct RTTRACELOGEVTDESC
160{
161 /** Event identifier. */
162 const char *pszId;
163 /** Event description. */
164 const char *pszDesc;
165 /** Severity class of the event. */
166 RTTRACELOGEVTSEVERITY enmSeverity;
167 /** Number of items recorded for an event. */
168 uint32_t cEvtItems;
169 /** Pointer to array of event item descriptors. */
170 PCRTTRACELOGEVTITEMDESC paEvtItemDesc;
171} RTTRACELOGEVTDESC;
172/** Pointer to a trace log event descriptor. */
173typedef RTTRACELOGEVTDESC *PRTTRACELOGEVTDESC;
174/** Pointer to a const trace log event descriptor. */
175typedef const RTTRACELOGEVTDESC *PCRTTRACELOGEVTDESC;
176
177
178/**
179 * Trace log event item value.
180 */
181typedef struct RTTRACELOGEVTVAL
182{
183 /** Pointer to the corresponding event item descriptor. */
184 PCRTTRACELOGEVTITEMDESC pItemDesc;
185 /** Value union. */
186 union
187 {
188 bool f;
189 uint8_t u8;
190 int8_t i8;
191 uint16_t u16;
192 int16_t i16;
193 uint32_t u32;
194 int32_t i32;
195 uint64_t u64;
196 int64_t i64;
197 uint64_t sz;
198 uint64_t uPtr;
199 float f32;
200 double f64;
201 struct
202 {
203 size_t cb;
204 const uint8_t *pb;
205 } RawData;
206 } u;
207} RTTRACELOGEVTVAL;
208/** Pointer to trace log event item value. */
209typedef RTTRACELOGEVTVAL *PRTTRACELOGEVTVAL;
210/** Pointer to a const trace log event item value. */
211typedef const RTTRACELOGEVTVAL *PCRTTRACELOGEVTVAL;
212
213
214/** Event group ID. */
215typedef uint64_t RTTRACELOGEVTGRPID;
216/** Pointer to the event group ID. */
217typedef RTTRACELOGEVTGRPID *PRTTRACELOGEVTGRPID;
218/** Trace log event handle. */
219typedef uint64_t RTRACELOGEVT;
220/** Pointer to a trace log event handle. */
221typedef RTRACELOGEVT *PRTRACELOGEVT;
222/** Trace log writer handle. */
223typedef struct RTTRACELOGWRINT *RTTRACELOGWR;
224/** Pointer to a trace log writer handle. */
225typedef RTTRACELOGWR *PRTTRACELOGWR;
226/** NIL trace log writer handle value. */
227#define NIL_RTTRACELOGWR ((RTTRACELOGWR)0)
228/** Trace log reader handle. */
229typedef struct RTTRACELOGRDRINT *RTTRACELOGRDR;
230/** Pointer to a trace log reader handle. */
231typedef RTTRACELOGRDR *PRTTRACELOGRDR;
232/** NIL trace log reader handle value. */
233#define NIL_RTTRACELOGRDR ((RTTRACELOGRDR)0)
234/** Trace log reader iterator handle. */
235typedef struct RTTRACELOGRDRITINT *RTTRACELOGRDRIT;
236/** Pointer to a trace log reader iterator handle. */
237typedef RTTRACELOGRDRIT *PRTTRACELOGRDRIT;
238/** NIL trace log reader iterator handle. */
239#define NIL_RTTRACELOGRDRIT ((RTTRACELOGRDRIT)0)
240/** Trace log reader event handle. */
241typedef struct RTTRACELOGRDREVTINT *RTTRACELOGRDREVT;
242/** Pointer to a trace log reader event handle. */
243typedef RTTRACELOGRDREVT *PRTTRACELOGRDREVT;
244
245/** A new grouped event is started. */
246#define RTTRACELOG_WR_ADD_EVT_F_GRP_START RT_BIT_32(0)
247/** A grouped event is finished. */
248#define RTTRACELOG_WR_ADD_EVT_F_GRP_FINISH RT_BIT_32(1)
249
250/**
251 * Callback to stream out data from the trace log writer.
252 *
253 * @returns IPRT status code.
254 * @param pvUser Opaque user data passed on trace log writer creation.
255 * @param pvBuf Pointer to the buffer to stream out.
256 * @param cbBuf Number of bytes to stream.
257 * @param pcbWritten Where to store the number of bytes written on success, optional.
258 */
259typedef DECLCALLBACK(int) FNRTTRACELOGWRSTREAM(void *pvUser, const void *pvBuf, size_t cbBuf, size_t *pcbWritten);
260/** Pointer to a writer stream callback. */
261typedef FNRTTRACELOGWRSTREAM *PFNRTTRACELOGWRSTREAM;
262
263
264/**
265 * Callback to stream int data to the trace log reader.
266 *
267 * @returns IPRT status code.
268 * @retval VERR_EOF if the stream reached the end.
269 * @retval VERR_INTERRUPTED if waiting for something to arrive was interrupted.
270 * @retval VERR_TIMEOUT if the timeout was reached.
271 * @param pvUser Opaque user data passed on trace log reader creation.
272 * @param pvBuf Where to store the read data.
273 * @param cbBuf Number of bytes the buffer can hold.
274 * @param pcbRead Where to store the number of bytes read on success.
275 * @param cMsTimeout How long to wait for something to arrive
276 */
277typedef DECLCALLBACK(int) FNRTTRACELOGRDRSTREAM(void *pvUser, void *pvBuf, size_t cbBuf, size_t *pcbRead,
278 RTMSINTERVAL cMsTimeout);
279/** Pointer to a writer stream callback. */
280typedef FNRTTRACELOGRDRSTREAM *PFNRTTRACELOGRDRSTREAM;
281
282
283/**
284 * Callback to close the stream.
285 *
286 * @returns IPRT status code.
287 * @param pvUser Opaque user data passed on trace log writer creation.
288 */
289typedef DECLCALLBACK(int) FNRTTRACELOGSTREAMCLOSE(void *pvUser);
290/** Pointer to a stream close callback. */
291typedef FNRTTRACELOGSTREAMCLOSE *PFNRTTRACELOGSTREAMCLOSE;
292
293
294/**
295 * Creates a new trace log writer.
296 *
297 * @returns IPRT status code.
298 * @param phTraceLogWr Where to store the handle to the trace log writer on success.
299 * @param pszDesc Optional description to store in the header.
300 * @param pfnStreamOut The callback to use for streaming the trace log data.
301 * @param pfnStreamClose The callback to use for closing the stream.
302 * @param pvUser Opaque user data to pass to the streaming callback.
303 */
304RTDECL(int) RTTraceLogWrCreate(PRTTRACELOGWR phTraceLogWr, const char *pszDesc,
305 PFNRTTRACELOGWRSTREAM pfnStreamOut,
306 PFNRTTRACELOGSTREAMCLOSE pfnStreamClose, void *pvUser);
307
308
309/**
310 * Creates a new trace log writer streaming data to the given file.
311 *
312 * @returns IPRT status code.
313 * @param phTraceLogWr Where to store the handle to the trace log writer on success.
314 * @param pszDesc Optional description to store in the header.
315 * @param pszFilename The filename to stream the data to.
316 */
317RTDECL(int) RTTraceLogWrCreateFile(PRTTRACELOGWR phTraceLogWr, const char *pszDesc,
318 const char *pszFilename);
319
320
321/**
322 * Creates a new TCP server style trace log writer waiting for the other end to connect to it.
323 *
324 * @returns IPRT status code.
325 * @param phTraceLogWr Where to store the handle to the trace log writer on success.
326 * @param pszDesc Optional description to store in the header.
327 * @param pszListen The address to listen on, NULL to listen on all interfaces.
328 * @param uPort The port to listen on.
329 *
330 * @note The writer will block here until a client has connected.
331 */
332RTDECL(int) RTTraceLogWrCreateTcpServer(PRTTRACELOGWR phTraceLogWr, const char *pszDesc,
333 const char *pszListen, unsigned uPort);
334
335
336/**
337 * Creates a new TCP client style trace log writer connecting to the other end.
338 *
339 * @returns IPRT status code.
340 * @param phTraceLogWr Where to store the handle to the trace log writer on success.
341 * @param pszDesc Optional description to store in the header.
342 * @param pszAddress The address to connect to.
343 * @param uPort The port to connect to.
344 *
345 * @note An error is returned if no connection can be established.
346 */
347RTDECL(int) RTTraceLogWrCreateTcpClient(PRTTRACELOGWR phTraceLogWr, const char *pszDesc,
348 const char *pszAddress, unsigned uPort);
349
350
351/**
352 * Destroys the given trace log writer instance.
353 *
354 * @returns IPRT status code.
355 * @param hTraceLogWr The trace log writer instance handle.
356 */
357RTDECL(int) RTTraceLogWrDestroy(RTTRACELOGWR hTraceLogWr);
358
359
360/**
361 * Adds a given event structure descriptor to the given trace log writer instance
362 * (for prepopulation).
363 *
364 * @returns IPRT status code.
365 * @param hTraceLogWr The trace log writer instance handle.
366 * @param pEvtDesc The event structure descriptor to add.
367 *
368 * @note The event descriptor is keyed by the pointer for faster lookup in subsequent calls,
369 * so don't free after this method finishes.
370 */
371RTDECL(int) RTTraceLogWrAddEvtDesc(RTTRACELOGWR hTraceLogWr, PCRTTRACELOGEVTDESC pEvtDesc);
372
373
374/**
375 * Adds a new event to the trace log.
376 *
377 * @returns IPRT status code.
378 * @param hTraceLogWr The trace log writer instance handle.
379 * @param pEvtDesc The event descriptor to use for formatting.
380 * @param fFlags Flags to use for this event.y
381 * @param uGrpId A unique group ID for grouped events.
382 * @param uParentGrpId A parent group ID this event originated from.
383 * @param pvEvtData Pointer to the raw event data.
384 * @param pacbRawData Pointer to the array of size indicators for non static raw data in the event data stream.
385 *
386 * @note The event descriptor is keyed by the pointer for faster lookup in subsequent calls,
387 * so don't free after this method finishes.
388 */
389RTDECL(int) RTTraceLogWrEvtAdd(RTTRACELOGWR hTraceLogWr, PCRTTRACELOGEVTDESC pEvtDesc, uint32_t fFlags,
390 RTTRACELOGEVTGRPID uGrpId, RTTRACELOGEVTGRPID uParentGrpId,
391 const void *pvEvtData, size_t *pacbRawData);
392
393
394/**
395 * Adds a new event to the trace log.
396 *
397 * @returns IPRT status code.
398 * @param hTraceLogWr The trace log writer instance handle.
399 * @param pEvtDesc The event descriptor used for formatting the data.
400 * @param fFlags Flags to use for this event.
401 * @param uGrpId A unique group ID for grouped events.
402 * @param uParentGrpId A parent group ID this event originated from.
403 * @param pSgBufEvtData S/G buffer holding the raw event data.
404 * @param pacbRawData Pointer to the array of size indicators for non static raw data in the event data stream.
405 *
406 * @note The event descriptor is keyed by the pointer for faster lookup in subsequent calls,
407 * so don't free after this method finishes.
408 */
409RTDECL(int) RTTraceLogWrEvtAddSg(RTTRACELOGWR hTraceLogWr, PCRTTRACELOGEVTDESC pEvtDesc, uint32_t fFlags,
410 RTTRACELOGEVTGRPID uGrpId, RTTRACELOGEVTGRPID uParentGrpId,
411 PRTSGBUF *pSgBufEvtData, size_t *pacbRawData);
412
413
414/**
415 * Creates a new trace log reader instance.
416 *
417 * @returns IPRT status code.
418 * @param phTraceLogRdr Where to store the handle to the trace log reader instance on success.
419 * @param pfnStreamIn Callback to stream the data into the reader.
420 * @param pfnStreamClose The callback to use for closing the stream.
421 * @param pvUser Opaque user data passed to the stream callback.
422 */
423RTDECL(int) RTTraceLogRdrCreate(PRTTRACELOGRDR phTraceLogRdr, PFNRTTRACELOGRDRSTREAM pfnStreamIn,
424 PFNRTTRACELOGSTREAMCLOSE pfnStreamClose, void *pvUser);
425
426
427/**
428 * Creates a new trace log reader for the given file.
429 *
430 * @returns IPRT status code.
431 * @param phTraceLogRdr Where to store the handle to the trace log reader instance on success.
432 * @param pszFilename The file to read the trace log data from.
433 */
434RTDECL(int) RTTraceLogRdrCreateFromFile(PRTTRACELOGRDR phTraceLogRdr, const char *pszFilename);
435
436
437/**
438 * Destroys the given trace log reader instance.
439 *
440 * @returns IPRT status code.
441 * @param hTraceLogRdr The trace log reader instance handle.
442 */
443RTDECL(int) RTTraceLogRdrDestroy(RTTRACELOGRDR hTraceLogRdr);
444
445
446/**
447 * Polls for an event on the trace log reader instance.
448 *
449 * @returns IPRT status code.
450 * @retval VERR_TIMEOUT if the timeout was reached.
451 * @retval VERR_INTERRUPTED if the poll was interrupted.
452 * @param hTraceLogRdr The trace log reader instance handle.
453 * @param penmEvt Where to store the event identifier.
454 * @param cMsTimeout How long to poll for an event.
455 */
456RTDECL(int) RTTraceLogRdrEvtPoll(RTTRACELOGRDR hTraceLogRdr, RTTRACELOGRDRPOLLEVT *penmEvt, RTMSINTERVAL cMsTimeout);
457
458/**
459 * Queries the last received event from the trace log read instance.
460 *
461 * @returns IPRT status code.
462 * @retval VERR_NOT_FOUND if no event was received so far.
463 * @param hTraceLogRdr The trace log reader instance handle.
464 * @param phRdrEvt Where to store the event handle on success.
465 */
466RTDECL(int) RTTraceLogRdrQueryLastEvt(RTTRACELOGRDR hTraceLogRdr, PRTTRACELOGRDREVT phRdrEvt);
467
468/**
469 * Queries a new iterator for walking received events.
470 *
471 * @returns IPRT status code
472 * @param hTraceLogRdr The trace log reader instance handle.
473 * @param phIt Where to store the handle to iterator on success.
474 */
475RTDECL(int) RTTraceLogRdrQueryIterator(RTTRACELOGRDR hTraceLogRdr, PRTTRACELOGRDRIT phIt);
476
477
478/**
479 * Frees a previously created iterator.
480 *
481 * @returns nothing.
482 * @param hIt The iterator handle to free.
483 */
484RTDECL(void) RTTraceLogRdrIteratorFree(RTTRACELOGRDRIT hIt);
485
486
487/**
488 * Advances to the next event.
489 *
490 * @returns IPRT status code
491 * @retval VERR_TRACELOG_READER_ITERATOR_END if the iterator reached the end.
492 * @param hIt The iterator handle.
493 */
494RTDECL(int) RTTraceLogRdrIteratorNext(RTTRACELOGRDRIT hIt);
495
496
497/**
498 * Queries the event at the current iterator position.
499 *
500 * @returns IPRT status code.
501 * @param hIt The iterator handle.
502 * @param phRdrEvt Where to store the event handle on success.
503 */
504RTDECL(int) RTTraceLogRdrIteratorQueryEvent(RTTRACELOGRDRIT hIt, PRTTRACELOGRDREVT phRdrEvt);
505
506
507/**
508 * Returns the sequence number of the given event.
509 *
510 * @returns Sequence number of the given event.
511 * @param hRdrEvt The reader event handle.
512 */
513RTDECL(uint64_t) RTTraceLogRdrEvtGetSeqNo(RTTRACELOGRDREVT hRdrEvt);
514
515
516/**
517 * Gets the timestamp of the given event.
518 *
519 * @returns Timestamp of the given event.
520 * @param hRdrEvt The reader event handle.
521 */
522RTDECL(uint64_t) RTTraceLogRdrEvtGetTs(RTTRACELOGRDREVT hRdrEvt);
523
524
525/**
526 * Returns whether the given event is part of an event group.
527 *
528 * @returns Flag whether the event is part of a group.
529 * @param hRdrEvt The reader event handle.
530 */
531RTDECL(bool) RTTraceLogRdrEvtIsGrouped(RTTRACELOGRDREVT hRdrEvt);
532
533
534/**
535 * Returns the event descriptor associated with the given event.
536 *
537 * @returns The trace log event descriptor associated with this event.
538 * @param hRdrEvt The reader event handle.
539 */
540RTDECL(PCRTTRACELOGEVTDESC) RTTraceLogRdrEvtGetDesc(RTTRACELOGRDREVT hRdrEvt);
541
542
543/**
544 * Queries an event item by its name returning the value in the supplied buffer.
545 *
546 * @returns IPRT status code.
547 * @retval VERR_NOT_FOUND if the item name was not found for the given event.
548 * @param hRdrEvt The reader event handle.
549 * @param pszName The item name to query.
550 * @param pVal The item value buffer to initialise.
551 */
552RTDECL(int) RTTraceLogRdrEvtQueryVal(RTTRACELOGRDREVT hRdrEvt, const char *pszName, PRTTRACELOGEVTVAL pVal);
553
554
555/**
556 * Fills the given value array using the values from the given event.
557 *
558 * @returns IPRT status code
559 * @param hRdrEvt The reader event handle.
560 * @param idxItemStart The index of the item to start filling the value in.
561 * @param paVals Array of values to fill.
562 * @param cVals Number of values the array is able to hold.
563 * @param pcVals Where to store the number of values filled on success.
564 */
565RTDECL(int) RTTraceLogRdrEvtFillVals(RTTRACELOGRDREVT hRdrEvt, unsigned idxItemStart, PRTTRACELOGEVTVAL paVals,
566 unsigned cVals, unsigned *pcVals);
567
568RT_C_DECLS_END
569
570/** @} */
571
572#endif
573
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette