Changes between Initial Version and Version 1 of Tracing

Timestamp:

2009-04-09T00:17:30Z (15 years ago)

Author:

trac

Comment:

—

Tracing

@@ +1 @@
+== Using the Syscall/IPC Tracer ==
+
+The tracer application (/app/trace) is meant to give you a rough idea about what your application is doing by printing the system calls it is making. However, since HelenOS is a microkernel system, the system calls are not all that interesting, since they are mostly just IPC calls. For this reason, the tracer tries to analyze communication on higher layers to a certain extent, i.e. the IPC communication and (in a very primitive way) the application protocols.
+
+=== Command-line parameters ===
+
+To execute a program and trace it, type
+{{{
+trace <executable_path>
+}}}
+
+on the command line. You can also specify which type of messages you want to see with a `+` and a combination of letters:
+
+ * `t` - Thread information (creation and termination of threads)
+ * `s` - System-call layer
+ * `i` - IPC layer (IPC calls with some decoding)
+ * `p` - Application protocol messages (formatted to look like function calls and more extensively decoded)
+
+For example,
+{{{
+trace +tsip /app/tetris
+}}}
+will trace the Tetris application and it will output all possible messages (and there's a lot of them).
+
+Alternatively, to trace a running task, type
+{{{
+trace -t <task_id>
+}}}
+
+=== Keyboard controls ===
+
+Press 'Q' anytime to quit the tracing application.
+
+=== Understanding the output ===
+
+A typical application-protocol message has the form:
+{{{
+<protocol>(<phone_id>).<method>(<arguments>).
+}}}
+
+For example,
+{{{
+console(3).putchar('A').
+}}}
+
+Here ''phone_id'' is the ID of the phone on which the request is being made. The ''protocol'' field is the name of the protocol that the tracer believes is being used on that phone. (This is normally detected by spying on the communication with the naming service.) The ''method'' is a textual representation of the IPC method number (for that protocol). The period (`.`) at the end of the line denotes that the request returns no value (and thus the response will not be displayed).
+
+=== Notes ===
+
+ * Decoding tables for application protocols are currently very incomplete. Unrecognized calls are not printed at all at the ''protocol'' level, you must display IPC-level messages (`+i`) to see them!
+
+ * There are still bugs, the kernel can panic if the task being traced crashes.
+
+ * The tracer actually kicks in a little while ''before'' the program starts (i.e. at the end of the loader). Thus the first few messages you see concern the loader, rather than the C library startup code. (The loader closes its console connection and answers the RUN call, then it jumps to the entry point of the program).