[lttv.git] / lttv / doc / developer / developer_guide / html / x23.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>A typical module</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="Linux Trace Toolkit Viewer Developer Guide"
HREF="index.html"><LINK
REL="UP"
TITLE="Linux Trace Toolkit Viewer Text Module Tutorial"
HREF="c18.html"><LINK
REL="PREVIOUS"
TITLE="Linux Trace Toolkit Viewer Text Module Tutorial"
HREF="c18.html"><LINK
REL="NEXT"
TITLE="The hooks"
HREF="x33.html"></HEAD
><BODY
CLASS="sect1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>Linux Trace Toolkit Viewer Developer Guide</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="c18.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 1. Linux Trace Toolkit Viewer Text Module Tutorial</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="x33.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="AEN23"
>1.2. A typical module</A
></H1
><P
>&#13;A typical module must have a init() and destroy() function. Please refer to
lttv/modules/text/textDump.c for the detail of these functions.
</P
><P
>&#13;The init() function is called when the library is loaded and destroy()
inversely. It adds options to the command line by calling "lttv_option_add" from
option.h
</P
><P
>&#13;The module communicates with the main lttv program through the use of global
attributes. Use lttv/attribute.h, lttv/iattribute.h and lttv/lttv.h, and then
LTTV_IATTRIBUTE(lttv_global_attributes()) to get the pointer to these
global attributes.
</P
><P
>&#13;You can then add your hooks (functions that follows the prototype of a hook, as
defined in lttv/hook.h) in the different hook lists defined in lttv/lttv.h. Note
that hooks have an assigned priority. This is necessary to inform the trace
reader that a specific hook needs to be called, for example, before or after the
state update done for an event by the state module. For that specific example, a
hook could use the LTTV_PRIO_STATE-5 to get called before the state update and a
second hook could use the LTTV_PRIO_STATE+5 to get called after the state
update. This is especially important for graphical module, which is the subject
of a the chapter named "Linux Trace Toolkit Viewer Graphical Module Tutorial".
</P
><P
>&#13;You should also take a look at lttv/state.c, where by_id hooks are used. When
you only need some specific events, you should use this interface. It makes the
event filtering sooner in the dispatch chain : you hook doesn't have to be
called for each event, only the ones selected. That improves the performances a
lot!
</P
><P
>&#13;Note that you should use the lttv_trace_find_hook method from
lttv/tracecontext.h to connect the hook to the right facility/event type. See
state.c for an example. A problem that may arise is that the LttvTraceHook
structure must be passed as hook_data when registering the hook. In fact, it is
not necessary for it to be directly passed as the hook_data parameter. As long
as the hook function can access the LttvTraceHook fields necessary to parse the
LttEvent, there is no problem. In a complex viewer where you need a pointer to
your own data structure, just keep a pointer to the LttvTraceHook structure
inside your own data structure, and give to pointer to your data structure in
parameter as the hook_data.
</P
><P
>&#13;Then, you should use the macro LTTV_MODULE, defined in lttv/module.h. It allows
you to specify the module name, a short and a long description, the init and
destroy functions and the module dependencies. That permits to the module
backend to load the right dependencies when needed.
</P
><P
>&#13;A typical text module will depend on batchAnalysis for the batch computation of a
trace, and simply register before and after trace hooks, as weel as the most
important one : a event hook.
</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="c18.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="x33.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Linux Trace Toolkit Viewer Text Module Tutorial</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="c18.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>The hooks</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
Commit	Line	Data
7cb02901	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	> 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	> 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	> 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	> 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	> 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	> 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	> 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	> 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	>