Documentation: Added trace-cmd.dat.5.txt

Added a documentation man page on the format of the trace.dat file.

Signed-off-by: Steven Rostedt <rostedt@goodmis.org>

3 files changed, 292 insertions, 6 deletions

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 72c9bad..f7f777f 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -35,6 +35,14 @@ do_xsltproc_build =				\
          xsltproc --nonet -o $@ ${MANPAGE_DOCBOOK_XSL} $< $(hide_xsltproc_output))
 
 #
+# asciidoc requires a synopsis, but file format man pages (5) do
+# not require them. This removes it from the file in the final step.
+define remove_synopsis
+        (sed -e '/^\.SH "SYNOPSIS"/,/^\.sp/d' $1 > $1.tmp;\
+         mv $1.tmp $1)
+endef
+
+#
 # Most likely a docbook.xsl is already installed on the users system
 # instead of creating a new wheel, lets reuse what's already there.
 #
@@ -49,10 +57,17 @@ $(obj)/%.1: $(obj)/%.1.xsl
         @$(call manpage.xsl)
         $(Q)$(do_xsltproc_build)
 
+$(obj)/%.5: $(obj)/%.5.xsl
+        @$(call manpage.xsl)
+        $(Q)$(do_xsltproc_build)
+        $(Q)$(call remove_synopsis, $@)
+
 TEXT1 = $(wildcard *.1.txt)
 MAN1 = $(patsubst %.1.txt,$(obj)/%.1, ${TEXT1})
+TEXT5 = $(wildcard *.5.txt)
+MAN5 = $(patsubst %.5.txt,$(obj)/%.5, ${TEXT5})
 
-all: $(MAN1)
+all: $(MAN1) $(MAN5)
 
 define do_install
         $(print_install)                        \
@@ -62,16 +77,19 @@ define do_install
         $(INSTALL) $1 $2;
 endef
 
-MAN1_INSTALL = $(subst .1,.install,$(MAN1))
+MAN1_INSTALL = $(subst .1,.1.install,$(MAN1))
+MAN5_INSTALL = $(subst .5,.5.install,$(MAN5))
 
-$(MAN1_INSTALL): %.install : %.1 force
+$(MAN1_INSTALL): %.1.install : %.1 force
         $(Q)$(call do_install, $<, '$(man_dir_SQ)/man1')
+$(MAN5_INSTALL): %.5.install : %.5 force
+        $(Q)$(call do_install, $<, '$(man_dir_SQ)/man5')
 
-install: $(MAN1_INSTALL)
+install: $(MAN1_INSTALL) $(MAN5_INSTALL)
 
 clean:
         (cd $(obj); \
-         $(RM) *.xml *.xsl *.1)
+         $(RM) *.xml *.xsl *.1 *.5)
 
 .PHONE: force
 force:
\ No newline at end of file
diff --git a/Documentation/trace-cmd.1.txt b/Documentation/trace-cmd.1.txt
index 9bd97c5..fb4cadd 100644
--- a/Documentation/trace-cmd.1.txt
+++ b/Documentation/trace-cmd.1.txt
@@ -56,7 +56,8 @@ SEE ALSO
 --------
 trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1),
 trace-cmd-stop(1), trace-cmd-extract(1), trace-cmd-reset(1),
-trace-cmd-split(1), trace-cmd-list(1), trace-cmd-listen(1)
+trace-cmd-split(1), trace-cmd-list(1), trace-cmd-listen(1),
+trace-cmd.dat(5)
 
 AUTHOR
 ------
diff --git a/Documentation/trace-cmd.dat.5.txt b/Documentation/trace-cmd.dat.5.txt
new file mode 100644
index 0000000..b393d3d
--- /dev/null
+++ b/Documentation/trace-cmd.dat.5.txt
@@ -0,0 +1,267 @@
+TRACE-CMD.DAT(5)
+===============
+
+NAME
+----
+trace-cmd.dat - trace-cmd file format
+
+SYNOPSIS
+--------
+*trace-cmd.dat* ignore
+
+DESCRIPTION
+-----------
+The trace-cmd(1) utility produces a "trace.dat" file. The file may also
+be named anything depending if the user specifies a different output name,
+but it must have a certain binary format. The file is used
+by trace-cmd to save kernel traces into it and be able to extract
+the trace from it at a later point (see *trace-cmd-report(1)*).
+
+
+INITIAL FORMAT
+--------------
+
+  The first three bytes contain the magic value:
+
+     0x17 0x08  0x44
+
+  The next 7 bytes contain the characters:
+
+     "tracing"
+
+  The next set of characters contain a null '\0' terminated string,
+  that contains the version of the file (for example):
+
+     "6\0"
+
+  The next 1 byte contains the flags for the file endianess:
+
+     0 = little endian
+     1 = big endian
+
+  The next byte contains the number of bytes per "long" value:
+
+     4 - 32 bit long values
+     8 - 64 bit long values
+
+  Note: This is the long size of the target's userspace. Not the
+  kernel space size.
+
+  [ Now all numbers are written in file defined endianess ]
+
+  The next 4 bytes is a 32 bit word that defines what the traced
+  host machine page size was.
+
+HEADER INFO FORMAT
+------------------
+
+  Directly after the initial format comes information about the
+  trace headers recorded from the target box.
+
+  The next 12 bytes contain the string:
+
+    "header_page\0"
+
+  The next 8 bytes is a 64 bit word containing the size of the
+  page header information stored next.
+
+  The next set of data is of the size read from the previous 8 bytes,
+  and contains the data retrieved from debugfs/tracing/events/header_page
+
+  Note: The size of the second field \fBcommit\fR contains the target
+  kernel long size. For example:
+
+  field: local_t commit;        offset:8;       \fBsize:8;\fR   signed:1;
+
+  Shows the kernel has a 64 bit long.
+
+  The next 13 bytes contain the string:
+
+  "header_event\0"
+
+  The next 8 bytes is a 64 bit word containing the size of the
+  event header information stored next.
+
+  The next set of data is of the size read from the previous 8 bytes
+  and contains the data retrieved from debugfs/tracing/events/header_event
+
+  This data allows the trace-cmd tool to know if the ring buffer format
+  of the kernel made any changes.
+
+FTRACE EVENT FORMATS
+--------------------
+
+  Directly after the header information comes the information about
+  the Ftrace specific events. These are the events used by the Ftrace plugins
+  and are not enabled by the event tracing.
+
+  The next 4 bytes contains a 32 bit word of the number of Ftrace event
+  format files that are stored in the file.
+
+  For the number of times defined by the previous 4 bytes is the
+  following:
+
+  8 bytes for the size of the Ftrace event format file.
+
+  The Ftrace event format file copied from the target machine:
+  debugfs/tracing/events/ftrace/<event>/format
+
+EVENT FORMATS
+-------------
+
+  Directly after the Ftrace formats comes the information about
+  the event layout.
+
+  The next 4 bytes is a 32 bit word containing the number of
+  event systems that are stored in the file. These are the
+  directories in debugfs/tracing/events excluding the \fBftrace\fR
+  directory.
+
+  For the number of times defined by the previous 4 bytes is the
+  following:
+
+  A null terminated string containing the system name.
+
+  4 bytes containing a 32 bit word containing the number
+  of events within the system.
+
+  For the number of times defined in the previous 4 bytes is the
+  following:
+
+  8 bytes for the size of the event format file.
+
+  The event format file copied from the target machine:
+  debugfs/tracing/events/<system>/<event>/format
+
+KALLSYMS INFORMATION
+--------------------
+
+  Directly after the event formats comes the information of the mapping
+  of function addresses to the function names.
+
+  The next 4 bytes is a 32 bit word containing the size of the
+  data holding the function mappings.
+
+  The next set of data is of the size defined by the previous 4 bytes
+  and contains the information from the target machine's file:
+  /proc/kallsyms
+
+
+TRACE_PRINTK INFORMATION
+------------------------
+
+  If a developer used trace_printk() within the kernel, it may
+  store the format string outside the ring buffer.
+  This information can be found in:
+  debugfs/tracing/printk_formats
+
+  The next 4 bytes is a 32 bit word containing the size of the
+  data holding the printk formats
+
+  The next set of data is of the size defined by the previous 4 bytes
+  and contains the information from debugfs/tracing/printk_formats.
+
+
+PROCESS INFORMATION
+-------------------
+
+  Directly after the trace_printk formats comes the information mapping
+  a PID to a process name.
+
+  The next 8 bytes contains a 64 bit word that holds the size of the
+  data mapping the PID to a process name.
+
+  The next set of data is of the size defined by the previous 8 bytes
+  and contains the information from debugfs/tracing/saved_cmdlines
+
+
+REST OF TRACE-CMD HEADER
+------------------------
+
+  Directly after the process information comes the last bit of the
+  trace.dat file header.
+
+  The next 4 bytes is a 32 bit word defining the number of CPUs that
+  was discovered on the target machine (and has matching trace data
+  for it).
+
+  The next 10 bytes is one of the following:
+
+    "options  \0"
+
+    "latency  \0"
+
+    "flyrecord\0"
+
+  If it is "options  \0" then:
+
+  The next 2 bytes is a 16 bit word defining the current option.
+  If the the value is zero then there are no more options.
+
+  Otherwise, the next 4 bytes contains a 32 bit word containing the
+  option size. If the reader does not know how to handle the option
+  it can simply skip it. Currently there are no options defined,
+  but this is here to extend the data.
+
+  The next option will be directly after the previous option, and
+  the options ends with a zero in the option type field.
+
+  The next 10 bytes after the options is one of the following:
+
+  "latency  \0"
+
+  "flyrecord\0"
+
+  Which would follow the same as if options were not present.
+
+  If the value is "latency  \0", then the rest of the file is
+  simply ASCII text that was taken from the targets:
+  debugfs/tracing/trace
+
+  If the value is "flyrecord\0", the following is present:
+
+  For the number of CPUs that were read earlier, the
+  following is present:
+
+  8 bytes that is a 64 bit word containing the offset into the file
+  that holds the data for the CPU.
+
+  8 bytes that is a 64 bit word containing the size of the CPU
+  data at that offset.
+
+CPU DATA
+--------
+
+  The CPU data is located in the part of the file that is specified
+  in the end of the header. Padding is placed between the header and
+  the CPU data, placing the CPU data at a page aligned (target page) position
+  in the file.
+
+  This data is copied directly from the Ftrace ring buffer and is of the
+  same format as the ring buffer specified by the event header files
+  loaded in the header format file.
+
+  The trace-cmd tool will try to \fBmmap(2)\fR the data page by page with the
+  target's page size if possible. If it fails to mmap, it will just read the
+  data instead.
+
+SEE ALSO
+--------
+trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1),
+trace-cmd-stop(1), trace-cmd-extract(1), trace-cmd-reset(1),
+trace-cmd-split(1), trace-cmd-list(1), trace-cmd-listen(1),
+trace-cmd.dat(5)
+
+AUTHOR
+------
+Written by Steven Rostedt, <rostedt@goodmis.org>
+
+RESOURCES
+---------
+git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/trace-cmd.git
+
+COPYING
+-------
+Copyright \(C) 2010 Red Hat, Inc. Free use of this software is granted under
+the terms of the GNU Public License (GPL).
+