trunk/lttv/doc/developer/developer_guide/html/x23.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
   2 <HTML
   3 ><HEAD
   4 ><TITLE
   5 >A typical module</TITLE
   6 ><META
   7 NAME="GENERATOR"
   8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
   9 REL="HOME"
  10 TITLE="Linux Trace Toolkit Viewer Developer Guide"
  11 HREF="index.html"><LINK
  12 REL="UP"
  13 TITLE="Linux Trace Toolkit Viewer Text Module Tutorial"
  14 HREF="c18.html"><LINK
  15 REL="PREVIOUS"
  16 TITLE="Linux Trace Toolkit Viewer Text Module Tutorial"
  17 HREF="c18.html"><LINK
  18 REL="NEXT"
  19 TITLE="The hooks"
  20 HREF="x33.html"></HEAD
  21 ><BODY
  22 CLASS="sect1"
  23 BGCOLOR="#FFFFFF"
  24 TEXT="#000000"
  25 LINK="#0000FF"
  26 VLINK="#840084"
  27 ALINK="#0000FF"
  28 ><DIV
  29 CLASS="NAVHEADER"
  30 ><TABLE
  31 SUMMARY="Header navigation table"
  32 WIDTH="100%"
  33 BORDER="0"
  34 CELLPADDING="0"
  35 CELLSPACING="0"
  36 ><TR
  37 ><TH
  38 COLSPAN="3"
  39 ALIGN="center"
  40 >Linux Trace Toolkit Viewer Developer Guide</TH
  41 ></TR
  42 ><TR
  43 ><TD
  44 WIDTH="10%"
  45 ALIGN="left"
  46 VALIGN="bottom"
  47 ><A
  48 HREF="c18.html"
  49 ACCESSKEY="P"
  50 >Prev</A
  51 ></TD
  52 ><TD
  53 WIDTH="80%"
  54 ALIGN="center"
  55 VALIGN="bottom"
  56 >Chapter 1. Linux Trace Toolkit Viewer Text Module Tutorial</TD
  57 ><TD
  58 WIDTH="10%"
  59 ALIGN="right"
  60 VALIGN="bottom"
  61 ><A
  62 HREF="x33.html"
  63 ACCESSKEY="N"
  64 >Next</A
  65 ></TD
  66 ></TR
  67 ></TABLE
  68 ><HR
  69 ALIGN="LEFT"
  70 WIDTH="100%"></DIV
  71 ><DIV
  72 CLASS="sect1"
  73 ><H1
  74 CLASS="sect1"
  75 ><A
  76 NAME="AEN23"
  77 >1.2. A typical module</A
  78 ></H1
  79 ><P
  80 >&#13;A typical module must have a init() and destroy() function. Please refer to
  81 lttv/modules/text/textDump.c for the detail of these functions.
  82 </P
  83 ><P
  84 >&#13;The init() function is called when the library is loaded and destroy()
  85 inversely. It adds options to the command line by calling "lttv_option_add" from
  86 option.h
  87 </P
  88 ><P
  89 >&#13;The module communicates with the main lttv program through the use of global
  90 attributes. Use lttv/attribute.h, lttv/iattribute.h and lttv/lttv.h, and then
  91 LTTV_IATTRIBUTE(lttv_global_attributes()) to get the pointer to these
  92 global attributes.
  93 </P
  94 ><P
  95 >&#13;You can then add your hooks (functions that follows the prototype of a hook, as
  96 defined in lttv/hook.h) in the different hook lists defined in lttv/lttv.h. Note
  97 that hooks have an assigned priority. This is necessary to inform the trace
  98 reader that a specific hook needs to be called, for example, before or after the
  99 state update done for an event by the state module. For that specific example, a
 100 hook could use the LTTV_PRIO_STATE-5 to get called before the state update and a
 101 second hook could use the LTTV_PRIO_STATE+5 to get called after the state
 102 update. This is especially important for graphical module, which is the subject
 103 of a the chapter named "Linux Trace Toolkit Viewer Graphical Module Tutorial".
 104 </P
 105 ><P
 106 >&#13;You should also take a look at lttv/state.c, where by_id hooks are used. When
 107 you only need some specific events, you should use this interface. It makes the
 108 event filtering sooner in the dispatch chain : you hook doesn't have to be
 109 called for each event, only the ones selected. That improves the performances a
 110 lot!
 111 </P
 112 ><P
 113 >&#13;Note that you should use the lttv_trace_find_hook method from
 114 lttv/tracecontext.h to connect the hook to the right facility/event type. See
 115 state.c for an example. A problem that may arise is that the LttvTraceHook
 116 structure must be passed as hook_data when registering the hook. In fact, it is
 117 not necessary for it to be directly passed as the hook_data parameter. As long
 118 as the hook function can access the LttvTraceHook fields necessary to parse the
 119 LttEvent, there is no problem. In a complex viewer where you need a pointer to
 120 your own data structure, just keep a pointer to the LttvTraceHook structure
 121 inside your own data structure, and give to pointer to your data structure in
 122 parameter as the hook_data.
 123 </P
 124 ><P
 125 >&#13;Then, you should use the macro LTTV_MODULE, defined in lttv/module.h. It allows
 126 you to specify the module name, a short and a long description, the init and
 127 destroy functions and the module dependencies. That permits to the module
 128 backend to load the right dependencies when needed.
 129 </P
 130 ><P
 131 >&#13;A typical text module will depend on batchAnalysis for the batch computation of a
 132 trace, and simply register before and after trace hooks, as weel as the most
 133 important one : a event hook.
 134 </P
 135 ></DIV
 136 ><DIV
 137 CLASS="NAVFOOTER"
 138 ><HR
 139 ALIGN="LEFT"
 140 WIDTH="100%"><TABLE
 141 SUMMARY="Footer navigation table"
 142 WIDTH="100%"
 143 BORDER="0"
 144 CELLPADDING="0"
 145 CELLSPACING="0"
 146 ><TR
 147 ><TD
 148 WIDTH="33%"
 149 ALIGN="left"
 150 VALIGN="top"
 151 ><A
 152 HREF="c18.html"
 153 ACCESSKEY="P"
 154 >Prev</A
 155 ></TD
 156 ><TD
 157 WIDTH="34%"
 158 ALIGN="center"
 159 VALIGN="top"
 160 ><A
 161 HREF="index.html"
 162 ACCESSKEY="H"
 163 >Home</A
 164 ></TD
 165 ><TD
 166 WIDTH="33%"
 167 ALIGN="right"
 168 VALIGN="top"
 169 ><A
 170 HREF="x33.html"
 171 ACCESSKEY="N"
 172 >Next</A
 173 ></TD
 174 ></TR
 175 ><TR
 176 ><TD
 177 WIDTH="33%"
 178 ALIGN="left"
 179 VALIGN="top"
 180 >Linux Trace Toolkit Viewer Text Module Tutorial</TD
 181 ><TD
 182 WIDTH="34%"
 183 ALIGN="center"
 184 VALIGN="top"
 185 ><A
 186 HREF="c18.html"
 187 ACCESSKEY="U"
 188 >Up</A
 189 ></TD
 190 ><TD
 191 WIDTH="33%"
 192 ALIGN="right"
 193 VALIGN="top"
 194 >The hooks</TD
 195 ></TR
 196 ></TABLE
 197 ></DIV
 198 ></BODY
 199 ></HTML
 200 >