-
-<H2>Event type descriptions</H2>
-
-<P>
-A facility contains the descriptions of several event types. When a structure
-is reused in several event types, a named type is defined and may be referenced
-by several other event types or named types.
-
-<PRE><TT>
-<facility name=facility_name>
- <description>Some text</description>
- <event name=eventtype_name>
- <description>Some text</description>
- --type structure--
- </event>
- ...
- <type name=type_name>
- --type structure--
- </type>
-</facility>
-</TT></PRE>
-
-<P>
-The type structure may be one of the following primitive type elements.
-Whenever the keyword isize is used, the allowed values are
-short, medium, long, 1, 2, 4, 8, indicating the size in bytes.
-The fsize keyword represents one of medium, long, 4 and 8 bytes.
-
-<PRE><TT>
-<int size=isize format="printf format"/>
-
-<uint size=isize format="printf format"/>
-
-<float size=fsize format="printf format"/>
-
-<string format="printf format"/>
-
-<enum size=isize format="printf format">label1 label2 ...</enum>
-</TT></PRE>
-
-<P>
-The string is null terminated. For the enumeration, the size of the integer
-used for its representation is specified.
-
-<P>
-The type structure may also be a compound type.
-
-<PRE><TT>
-<array size=n> --type structure-- </array>
-
-<sequence lengthsize=isize> --type structure-- </sequence>
-
-<struct>
- <field name=field_name>
- <description>Some text</description>
- --type structure--
- </field>
- ...
-</struct>
-
-<union typecodesize=isize>
- <field name=field_name>
- <description>Some text</description>
- --type structure--
- </field>
- ...
-</union>
-</TT></PRE>
-
-<P>
-Array is a fixed size array of length size. Sequence is a variable size
-array with its length stored as a prepended uint of length lengthsize.
-A structure is simply an aggregation of fields. An union is one of its n
-fields (variant record), as indicated by a preceeding code (0 to n - 1)
-of the specified size typecodesize.
-
-<P>
-Finally the type structure may be defined by referencing a named type.
-
-<PRE><TT>
-<typeref name=type_name/>
-</PRE></TT>
-
-<H2>Core events</H2>
-
-<P>
-The facility named "core" is always present and contains at least the
-following event types.
-
-<PRE><TT>
-<event name=facility_load>
- <description>Facility used in the trace</description>
- <struct>
- <field name="name"><string/></field>
- <field name="checksum"><uint size=4/></field>
- <field name="id"><uint size=4/></field>
- <field name="int_size"><uint size=4/></field>
- <field name="long_size"><uint size=4/></field>
- <field name="pointer_size"><uint size=4/></field>
- <field name="size_t_size"><uint size=4/></field>
- <field name="has_alignment"><uint size=4/></field>
- </struct>
-</event>
-
-<event name=state_dump_facility_load>
- <description>Facility used in the trace</description>
- <struct>
- <field name="name"><string/></field>
- <field name="checksum"><uint size=4/></field>
- <field name="id"><uint size=4/></field>
- <field name="int_size"><uint size=4/></field>
- <field name="long_size"><uint size=4/></field>
- <field name="pointer_size"><uint size=4/></field>
- <field name="size_t_size"><uint size=4/></field>
- <field name="has_alignment"><uint size=4/></field>
- </struct>
-</event>
-
-<event name=time_heartbeat>
- <description>System time values sent periodically to minimize cycle counter
- drift with respect to real time clock and to detect cycle counter
- rollovers
- </description>
- <typeref name=timestamp/>
-</event>
-
-<type name=timestamp>
- <struct>
- <field name="seconds"><uint size=4/></field>
- <field name="nanoseconds"><uint size=4/></field>
- <field name="cycle_count"><uint size=8/></field>
- </struct>
-</event>
-
-</TT></PRE>
-
-<H2>Control files</H2>
-
-<P>
-The interrupts file reflects the content of the /proc/interrupts system file.
-It contains one event describing each interrupt. At trace start, events are
-generated describing all the current interrupts. If the assignment of
-interrupts changes later, due to devices or device drivers being activated or
-deactivated, additional events may be added to the file. Each interrupt
-event has the following structure.
-
-<PRE><TT>
-<event name=interrupt>
- <description>Interrupt request number assignment<description>
- <struct>
- <field name="number"><uint size=4/></field>
- <field name="count"><uint size=4/></field>
- <field name="controller"><string/></field>
- <field name="name"><string/></field>
- </struct>
-</event>
-</TT></PRE>
-
-<P>
-The processes file contains the list of processes already created when the
-trace starts. Each process describing event is modeled after the
-/proc/self/status system file. The number of fields in this event is
-expected to be expanded in the future to include groups, signal masks,
-opened file descriptors and address maps.
-
-<PRE><TT>
-<event name=process>
- <description>Existing process<description>
- <struct>
- <field name="name"><string/></field>
- <field name="pid"><uint size=4/></field>
- <field name="ppid"><uint size=4/></field>
- <field name="tracer_pid"><uint size=4/></field>
- <field name="uid"><uint size=4/></field>
- <field name="euid"><uint size=4/></field>
- <field name="suid"><uint size=4/></field>
- <field name="fsuid"><uint size=4/></field>
- <field name="gid"><uint size=4/></field>
- <field name="egid"><uint size=4/></field>
- <field name="sgid"><uint size=4/></field>
- <field name="fsgid"><uint size=4/></field>
- <field name="state"><enum size=4>
- Running WaitInterruptible WaitUninterruptible Zombie Traced Paging
- </enum></field>
- </struct>
-</event>
-</TT></PRE>
-
-<H2>Facilities</H2>
-
-<P>
-Facilities define a granularity of events grouping for filtering, activation
-and compilation. Each facility does cost a table entry in the kernel (name,
-checksum, event type code range), or somewhere between 20 and 30 bytes. Having
-one facility per tracing statement in the kernel would be too much (assuming
-that they eventually are routinely inserted in the kernel code and replace
-the 80000+ printk statements in some proportion). However, having a few
-facilities, up to a few tens, would make sense.
-
-<P>
-The "builtin" facility contains a small number of predefined events which must
-always exist. The "core" facility contains a small subset of OS events which
-are almost always of interest (scheduling, interrupts, faults, system calls).
-Then, specialized facilities may exist for each subsystem (network, disks,
-USB, SCSI...).
-
-