VirtualBox

source: vbox/trunk/include/iprt/formats/tracelog.h@ 77807

Last change on this file since 77807 was 76585, checked in by vboxsync, 6 years ago

*: scm --fix-header-guard-endif
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 8.7 KB
Line 
1/* $Id: tracelog.h 76585 2019-01-01 06:31:29Z vboxsync $ */
2/** @file
3 * IPRT, Binary trace log format.
4 */
5
6/*
7 * Copyright (C) 2018-2019 Oracle Corporation
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 *
17 * The contents of this file may alternatively be used under the terms
18 * of the Common Development and Distribution License Version 1.0
19 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20 * VirtualBox OSE distribution, in which case the provisions of the
21 * CDDL are applicable instead of those of the GPL.
22 *
23 * You may elect to license modified versions of this file under the
24 * terms and conditions of either the GPL or the CDDL or both.
25 */
26
27#ifndef IPRT_INCLUDED_formats_tracelog_h
28#define IPRT_INCLUDED_formats_tracelog_h
29#ifndef RT_WITHOUT_PRAGMA_ONCE
30# pragma once
31#endif
32
33#include <iprt/assert.h>
34#include <iprt/cdefs.h>
35#include <iprt/types.h>
36
37
38/** @defgroup grp_rt_formats_tracelog Binary trace log structures and definitions
39 * @ingroup grp_rt_formats
40 * @{
41 */
42
43/** Size of the record magic in bytes. */
44#define TRACELOG_MAGIC_SZ 8
45
46/**
47 * Trace log identification and options header.
48 */
49typedef struct TRACELOGHDR
50{
51 /** Identifiaction magic. */
52 uint8_t szMagic[8];
53 /** Endianess indicator. */
54 uint32_t u32Endianess;
55 /** File version indicator. */
56 uint32_t u32Version;
57 /** File flags (MBZ for now). */
58 uint32_t fFlags;
59 /** Size of the trace log description in bytes following this header. */
60 uint32_t cbStrDesc;
61 /** Size of a pointer item in bytes. */
62 uint8_t cbTypePtr;
63 /** size of the size_t item in bytes. */
64 uint8_t cbTypeSize;
65 /** Padding to an 4 byte boundary. */
66 uint16_t u16Reserved0;
67 /** Padding to an 8 byte boundary. */
68 uint32_t u32Reserved0;
69 /** Starting timestamp when the log was initialised. */
70 uint64_t u64TsStart;
71 /** Padding to 64byte boundary, reserved for future use. */
72 uint64_t au64Reserved[3];
73} TRACELOGHDR;
74AssertCompileSize(TRACELOGHDR, 64);
75/** Pointer to a trace log header. */
76typedef TRACELOGHDR *PTRACELOGHDR;
77/** Pointer to a const trace log header. */
78typedef const TRACELOGHDR *PCTRACELOGHDR;
79
80/** Magic value for a trace log file (TRACELOG backwards). */
81#define TRACELOG_HDR_MAGIC "GOLECART"
82/** Endianess indicator. */
83#define TRACELOG_HDR_ENDIANESS 0xdeadc0de
84/** The default version (Higher 16bits major, low 16bits minor version). */
85#define TRACELOG_VERSION RT_MAKE_U32(1, 0)
86
87
88/**
89 * Trace log event structure descriptor.
90 */
91typedef struct TRACELOGEVTDESC
92{
93 /** Event descriptor magic. */
94 uint8_t szMagic[8];
95 /** Event structure descriptor ID for identification in events later. */
96 uint32_t u32Id;
97 /** Severity class of the event .*/
98 uint32_t u32Severity;
99 /** Size of the identifier string in bytes without terminator. */
100 uint32_t cbStrId;
101 /** Size of the description string in bytes without terminator. */
102 uint32_t cbStrDesc;
103 /** Number of event items following. */
104 uint32_t cEvtItems;
105 /** Padding to end the descriptor on a 32 byte boundary. */
106 uint32_t au32Padding0;
107} TRACELOGEVTDESC;
108AssertCompileSize(TRACELOGEVTDESC, 32);
109/** Pointer to a trace log event structure descriptor. */
110typedef TRACELOGEVTDESC *PTRACELOGEVTDESC;
111/** Pointer to a const trace log event structure descriptor. */
112typedef const TRACELOGEVTDESC *PCTRACELOGEVTDESC;
113
114/** Event descriptor magic. */
115#define TRACELOG_EVTDESC_MAGIC "\0CSEDTVE"
116
117/** Severity: Informational event*/
118#define TRACELOG_EVTDESC_SEVERITY_INFO UINT32_C(0)
119/** Severity: Warning event*/
120#define TRACELOG_EVTDESC_SEVERITY_WARNING UINT32_C(1)
121/** Severity: Error event*/
122#define TRACELOG_EVTDESC_SEVERITY_ERROR UINT32_C(2)
123/** Severity: Fatal event*/
124#define TRACELOG_EVTDESC_SEVERITY_FATAL UINT32_C(3)
125/** Severity: Debug event*/
126#define TRACELOG_EVTDESC_SEVERITY_DEBUG UINT32_C(4)
127
128
129/**
130 * Trace log event item descriptor.
131 */
132typedef struct TRACELOGEVTITEMDESC
133{
134 /** Event item descriptor magic. */
135 uint8_t szMagic[8];
136 /** Size of the item name string in bytes without terminator. */
137 uint32_t cbStrName;
138 /** Size of the optional description string in bytes without terminator. */
139 uint32_t cbStrDesc;
140 /** Item type */
141 uint32_t u32Type;
142 /** Size of the raw data type if static throughout. */
143 uint32_t cbRawData;
144 /** Padding to end the descriptor on a 32 byte boundary. */
145 uint32_t au32Padding0[2];
146} TRACELOGEVTITEMDESC;
147AssertCompileSize(TRACELOGEVTITEMDESC, 32);
148/** Pointer to a trace log event item descriptor. */
149typedef TRACELOGEVTITEMDESC *PTRACELOGEVTITEMDESC;
150/** Pointer to a const trace log event item descriptor. */
151typedef const TRACELOGEVTITEMDESC *PCTRACELOGEVTITEMDESC;
152
153/** Event item descriptor magic. */
154#define TRACELOG_EVTITEMDESC_MAGIC "CSEDMETI"
155/** Boolean type. */
156#define TRACELOG_EVTITEMDESC_TYPE_BOOL UINT32_C(1)
157/** Unsigned 8bit integer type. */
158#define TRACELOG_EVTITEMDESC_TYPE_UINT8 UINT32_C(2)
159/** Signed 8bit integer type. */
160#define TRACELOG_EVTITEMDESC_TYPE_INT8 UINT32_C(3)
161/** Unsigned 16bit integer type. */
162#define TRACELOG_EVTITEMDESC_TYPE_UINT16 UINT32_C(4)
163/** Signed 16bit integer type. */
164#define TRACELOG_EVTITEMDESC_TYPE_INT16 UINT32_C(5)
165/** Unsigned 32bit integer type. */
166#define TRACELOG_EVTITEMDESC_TYPE_UINT32 UINT32_C(6)
167/** Signed 32bit integer type. */
168#define TRACELOG_EVTITEMDESC_TYPE_INT32 UINT32_C(7)
169/** Unsigned 64bit integer type. */
170#define TRACELOG_EVTITEMDESC_TYPE_UINT64 UINT32_C(8)
171/** Signed 64bit integer type. */
172#define TRACELOG_EVTITEMDESC_TYPE_INT64 UINT32_C(9)
173/** 32bit floating point type. */
174#define TRACELOG_EVTITEMDESC_TYPE_FLOAT32 UINT32_C(10)
175/** 64bit floating point type. */
176#define TRACELOG_EVTITEMDESC_TYPE_FLOAT64 UINT32_C(11)
177/** Raw binary data type. */
178#define TRACELOG_EVTITEMDESC_TYPE_RAWDATA UINT32_C(12)
179/** Pointer data type. */
180#define TRACELOG_EVTITEMDESC_TYPE_POINTER UINT32_C(13)
181/** size_t data type. */
182#define TRACELOG_EVTITEMDESC_TYPE_SIZE UINT32_C(14)
183
184/**
185 * Trace log event marker.
186 */
187typedef struct TRACELOGEVT
188{
189 /** Event marker magic. */
190 uint8_t szMagic[8];
191 /** Trace log sequence number to identify the event uniquely. */
192 uint64_t u64SeqNo;
193 /** Timestamp for the marker (resolution is infered from the header). */
194 uint64_t u64Ts;
195 /** Event group ID for grouping different events together - for no grouped event. */
196 uint64_t u64EvtGrpId;
197 /** Parent group ID this event originated from. */
198 uint64_t u64EvtParentGrpId;
199 /** Overall number of bytes for the event data following including static and possibly variable data. */
200 uint32_t cbEvtData;
201 /** Number of size_t sized raw data size indicators before the raw event data follows. */
202 uint32_t cRawEvtDataSz;
203 /** Event flags. */
204 uint32_t fFlags;
205 /** Event structure descriptor ID to use for structuring the event data. */
206 uint32_t u32EvtDescId;
207 /** Reserved for future use. */
208 uint64_t u64Reserved0;
209} TRACELOGEVT;
210AssertCompileSize(TRACELOGEVT, 64);
211/** Pointer to a trace log event marker. */
212typedef TRACELOGEVT *PTRACELOGEVT;
213/** Pointer to a const trace log event marker. */
214typedef const TRACELOGEVT *PCTRACELOGEVT;
215
216/** Event marker descriptor magic. */
217#define TRACELOG_EVT_MAGIC "\0RKRMTVE"
218/** Flag indicating this is the start of an event group and all subsequent events
219 * with the same group ID belong to the same group. */
220#define TRACELOG_EVT_F_GRP_START RT_BIT_32(0)
221/** Flag indicating this is the end of an event group which was started earlier. */
222#define TRACELOG_EVT_F_GRP_END RT_BIT_32(1)
223/** Combination of valid flags. */
224#define TRACELOG_EVT_F_VALID (TRACELOG_EVT_F_GRP_START | TRACELOG_EVT_F_GRP_END)
225
226/** @} */
227
228#endif /* !IPRT_INCLUDED_formats_tracelog_h */
229
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