trunk/lttv/doc/developer/lttng-new-marker-event-desc.txt

   1
   2 Mathieu Desnoyers, June 2007
   3
   4 Marker design
   5
   6 Events are described in data structures in DECLARE_MARKER(), in the same file
   7 the marker is in, or exported and in a globally included header.
   8
   9 When a new marker is encountered (module load, marker armed), an event_load
  10 event is traced in the facilities channel. If the marker refers to an already
  11 existing marker declaration, nothing changes, except that it must check that the
  12 types match.
  13
  14 At trace start, we take the superset of the filtered in events and arm their
  15 markers. We trace an event load event for each armed marker encountered.
  16
  17 Format string verification by GCC.
  18
  19 Format string extensions (sequence, structs, arrays..)
  20
  21 Field names.
  22
  23
  24 User space tracing
  25
  26 Declare their own DECLARE_MARKER, use MARK() macros that refers to it. At module
  27 load, (to decide) either the kernel or the library walks on the markers sections
  28 and issues a marker_load  system call. Facility namespacing prefix "user_" is
  29 used for userspace facilities.
  30
  31 We have to deal with multiple registrations of the same event with different
  32 caracteristics but same name.
  33
  34 Markers must be enabled by the kernel, if activated and tracing starts.
  35
  36 Modify linker script to get section start and end in programs.
  37
  38
  39 -------------------------
  40
  41 Maybe DECLARE_MARKER is not necessary:
  42
  43 Use LTTV dictionnary to add information about events.
  44 event and field description.
  45
  46 <facility name="fac">
  47 <event name="event"> <description> assdfas </description> </event>
  48 <field name="field1"> <description> asdfasdf </description> </field>
  49 <field name="field2"> <enum>....</enum><description> asdfasdf </description> </field>
  50 </facility>
  51
  52 Field names
  53
  54 trace_mark(facility_event, "field1 %u field2 %p", asdf, asdf);
  55
  56 Extract the field names from the format string.
  57 Check for format string equivalence before enabling a marker. Allow enabling
  58 markers with the same format string as the first one found, but warn about the
  59 others which do not match.
  60 Trace an event_load event for each enabled marker with non-NULL format string at
  61 trace start and when they are activated. Since we want to keep the same format
  62 string if module loads/unload/reload, and we cannot point into this module's
  63 memory, we reallocate the entry and copy the format string whenever the newly
  64 loaded module contains active markers and these markers have a NULL format
  65 string.
  66 When we enable a marker, if the marker has a non null format string, we trace a
  67 marker_load.
  68
  69 Default : cardinal field1, field2....
  70 Calling: ltt_trace
  71 callback[0]: ltt_serialize_data
  72
  73 Types
  74
  75 -- Add network byte ordering to types.
  76 -- Change format strings to use backward compatible types. (format check)
  77
  78 Reserve 8 IDs for core events. Never allow wrapping over 65535 IDs during a
  79 trace : need compaction when no trace is active.
  80
  81 Marker hash table points to a structure containing the marker's event ID (16
  82 bits). Assign event ID when a probe is registered.
  83
  84 Compact channel. Use separate 8 bits event IDs for events going in the
  85 compact channel. Identified by registering probe with id type MARKER_ID_COMPACT.
  86
  87 update probes (temp)
  88
  89 -- Enabling a marker:
  90 -- give: state marker name, channel.
  91 /proc/markers: enable/disable name [channel]
  92
  93 probe_data should provide, for ltt:
  94 callbacks
  95 id <-- will stay in marker because otherwise we would need another hash table.
  96 channel index : put inside the marker structure (parameter to register).
  97 A marker control module
  98
  99 Q: field names in dictionnary or in marker ?
 100
 101
 102 What users will do with marker interface:
 103
 104 from userspace:
 105 enable/disable marker_name (act on any marker, reg by module or other)
 106 channel marker_name channel_name (act on any marker)
 107
 108 Default: use serializer
 109 But.. module can override _default_ probe with a "register" operation.
 110
 111 Use case
 112 Set channel
 113 Register by specific module (unregister default, register specific)
 114 activate.
 115
 116 Serve as a proxy for probe registration.
 117
 118
 119