1// Copyright (c) 2011 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5// This file contains the Windows-specific declarations for trace_event.h.
6#ifndef BASE_DEBUG_TRACE_EVENT_WIN_H_
7#define BASE_DEBUG_TRACE_EVENT_WIN_H_
8#pragma once
9
10#include <string>
11
12#include "base/base_api.h"
13#include "base/win/event_trace_provider.h"
14
15#define TRACE_EVENT_BEGIN(name, id, extra) \
16  base::debug::TraceLog::Trace( \
17      name, \
18      base::debug::TraceLog::EVENT_BEGIN, \
19      reinterpret_cast<const void*>(id), \
20      extra);
21
22#define TRACE_EVENT_END(name, id, extra) \
23  base::debug::TraceLog::Trace( \
24      name, \
25      base::debug::TraceLog::EVENT_END, \
26      reinterpret_cast<const void*>(id), \
27      extra);
28
29#define TRACE_EVENT_INSTANT(name, id, extra) \
30  base::debug::TraceLog::Trace( \
31      name, \
32      base::debug::TraceLog::EVENT_INSTANT, \
33      reinterpret_cast<const void*>(id), \
34      extra);
35
36// Fwd.
37template <typename Type>
38struct StaticMemorySingletonTraits;
39
40namespace base {
41namespace debug {
42
43// This EtwTraceProvider subclass implements ETW logging
44// for the macros above on Windows.
45class BASE_API TraceLog : public base::win::EtwTraceProvider {
46 public:
47  enum EventType {
48    EVENT_BEGIN,
49    EVENT_END,
50    EVENT_INSTANT
51  };
52
53  // Start logging trace events.
54  // This is a noop in this implementation.
55  static bool StartTracing();
56
57  // Trace begin/end/instant events, this is the bottleneck implementation
58  // all the others defer to.
59  // Allowing the use of std::string for name or extra is a convenience,
60  // whereas passing name or extra as a const char* avoids the construction
61  // of temporary std::string instances.
62  // If -1 is passed for name_len or extra_len, the strlen of the string will
63  // be used for length.
64  static void Trace(const char* name,
65                    size_t name_len,
66                    EventType type,
67                    const void* id,
68                    const char* extra,
69                    size_t extra_len);
70
71  // Allows passing extra as a std::string for convenience.
72  static void Trace(const char* name,
73                    EventType type,
74                    const void* id,
75                    const std::string& extra) {
76    return Trace(name, -1, type, id, extra.c_str(), extra.length());
77  }
78
79  // Allows passing extra as a const char* to avoid constructing temporary
80  // std::string instances where not needed.
81  static void Trace(const char* name,
82                    EventType type,
83                    const void* id,
84                    const char* extra) {
85    return Trace(name, -1, type, id, extra, -1);
86  }
87
88  // Retrieves the singleton.
89  // Note that this may return NULL post-AtExit processing.
90  static TraceLog* GetInstance();
91
92  // Returns true iff tracing is turned on.
93  bool IsTracing() {
94    return enable_level() >= TRACE_LEVEL_INFORMATION;
95  }
96
97  // Emit a trace of type |type| containing |name|, |id|, and |extra|.
98  // Note: |name| and |extra| must be NULL, or a zero-terminated string of
99  //    length |name_len| or |extra_len| respectively.
100  // Note: if name_len or extra_len are -1, the length of the corresponding
101  //    string will be used.
102  void TraceEvent(const char* name,
103                  size_t name_len,
104                  EventType type,
105                  const void* id,
106                  const char* extra,
107                  size_t extra_len);
108
109  // Exposed for unittesting only, allows resurrecting our
110  // singleton instance post-AtExit processing.
111  static void Resurrect();
112
113 private:
114  // Ensure only the provider can construct us.
115  friend struct StaticMemorySingletonTraits<TraceLog>;
116  TraceLog();
117
118  DISALLOW_COPY_AND_ASSIGN(TraceLog);
119};
120
121// The ETW trace provider GUID.
122BASE_API extern const GUID kChromeTraceProviderName;
123
124// The ETW event class GUID for 32 bit events.
125BASE_API extern const GUID kTraceEventClass32;
126
127// The ETW event class GUID for 64 bit events.
128BASE_API extern const GUID kTraceEventClass64;
129
130// The ETW event types, IDs 0x00-0x09 are reserved, so start at 0x10.
131const base::win::EtwEventType kTraceEventTypeBegin = 0x10;
132const base::win::EtwEventType kTraceEventTypeEnd = 0x11;
133const base::win::EtwEventType kTraceEventTypeInstant = 0x12;
134
135// If this flag is set in enable flags
136enum TraceEventFlags {
137  CAPTURE_STACK_TRACE = 0x0001,
138};
139
140// The event format consists of:
141// The "name" string as a zero-terminated ASCII string.
142// The id pointer in the machine bitness.
143// The "extra" string as a zero-terminated ASCII string.
144// Optionally the stack trace, consisting of a DWORD "depth", followed
145//    by an array of void* (machine bitness) of length "depth".
146
147// Forward decl.
148struct TraceLogSingletonTraits;
149
150}  // nemspace debug
151}  // namespace base
152
153#endif  // BASE_DEBUG_TRACE_EVENT_WIN_H_
154