1/* Copyright (c) 2012 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
6/**
7 * This file defines the <code>PPB_Trace_Event</code> interface. It is meant
8 * to be used in plugins as the API that trace macros from trace_event.h use.
9 */
10
11label Chrome {
12  M25 = 0.1,
13  M29 = 0.2
14};
15
16/**
17 * A trace event timestamp.
18 */
19typedef int64_t PP_TraceEventTime;
20
21interface PPB_Trace_Event_Dev {
22  /**
23   * Gets a pointer to a character for identifying a category name in the
24   * tracing system as well as for being able to early exit in client-side
25   * tracing code.
26   *
27   * NB: This mem_t return value should technically be const, but return values
28   * for Pepper IDL of mem_t type are not const.  The same is true for the arg
29   * |category_enabled| for AddTraceEvent.
30   */
31  mem_t GetCategoryEnabled([in] cstr_t category_name);
32
33  /**
34   * Adds a trace event to the platform tracing system. This function call is
35   * usually the result of a TRACE_* macro from trace_event.h when tracing and
36   * the category of the particular trace are enabled. It is not advisable to
37   * call this function on its own; it is really only meant to be used by the
38   * trace macros.
39   */
40  void AddTraceEvent(
41      [in] int8_t phase,
42      [in] mem_t category_enabled,
43      [in] cstr_t name,
44      [in] uint64_t id,
45      [in] uint32_t num_args,
46      [in, size_as=num_args] str_t[] arg_names,
47      [in, size_as=num_args] uint8_t[] arg_types,
48      [in, size_as=num_args] uint64_t[] arg_values,
49      [in] uint8_t flags);
50
51  /**
52   * Version of the above interface that allows specifying a custom thread id
53   * and timestamp. This is useful for when tracing data cannot be registered
54   * in real time. For example, this could be used by storing timestamps
55   * internally and then registering the events retroactively.
56   */
57  [version=0.2]
58  void AddTraceEventWithThreadIdAndTimestamp(
59      [in] int8_t phase,
60      [in] mem_t category_enabled,
61      [in] cstr_t name,
62      [in] uint64_t id,
63      [in] int32_t thread_id,
64      [in] PP_TraceEventTime timestamp,
65      [in] uint32_t num_args,
66      [in, size_as=num_args] str_t[] arg_names,
67      [in, size_as=num_args] uint8_t[] arg_types,
68      [in, size_as=num_args] uint64_t[] arg_values,
69      [in] uint8_t flags);
70
71  /**
72   * Get the current clock value. Since this uses the same function as the trace
73   * events use internally, it can be used to create events with explicit time
74   * stamps.
75   */
76  [version=0.2]
77  PP_TraceEventTime Now();
78
79  /**
80   * Sets the thread name of the calling thread in the tracing system so it will
81   * show up properly in chrome://tracing.
82   */
83  void SetThreadName([in] cstr_t thread_name);
84};
85