ia64/xen-unstable

changeset 1165:c4aa70095bed

bitkeeper revision 1.783 (4050a132Pr3c64IiyOkXPCbCmiihxg)

Update Xen manual to include a chapter on debugging.
author mwilli2@equilibrium.research.intel-research.net
date Thu Mar 11 17:26:10 2004 +0000 (2004-03-11)
parents 240abd842f1a
children aa95cfec4242
files docs/interface.tex
line diff
     1.1 --- a/docs/interface.tex	Thu Mar 11 15:54:01 2004 +0000
     1.2 +++ b/docs/interface.tex	Thu Mar 11 17:26:10 2004 +0000
     1.3 @@ -19,7 +19,7 @@
     1.4  
     1.5  {\Large Xen is Copyright (c) 2004, The Xen Team} \\[3mm]
     1.6  {\Large University of Cambridge, UK} \\[20mm]
     1.7 -{\large Last updated on 18th January, 2004}
     1.8 +{\large Last updated on 11th March, 2004}
     1.9  \end{tabular}
    1.10  \vfill
    1.11  \end{center}
    1.12 @@ -380,6 +380,64 @@ and providing control interfaces for man
    1.13  blocks.
    1.14  
    1.15  
    1.16 +\chapter{Debugging}
    1.17 +
    1.18 +Xen provides tools for debugging both Xen and guest OSes.  Currently, the
    1.19 +Pervasive Debugger provides a GDB stub, which provides facilities for symbolic
    1.20 +debugging of Xen itself and of OS kernels running on top of Xen.  The Trace
    1.21 +Buffer provides a lightweight means to log data about Xen's internal state and
    1.22 +behaviour at runtime, for later analysis.
    1.23 +
    1.24 +\section{Pervasive Debugger}
    1.25 +
    1.26 +Information on using the pervasive debugger is available in pdb.txt.
    1.27 +
    1.28 +
    1.29 +\section{Trace Buffer}
    1.30 +
    1.31 +The trace buffer provides a means to observe Xen's operation from domain 0.
    1.32 +Trace events, inserted at key points in Xen's code, record data that can be
    1.33 +read by the {\tt xentrace} tool.  Recording these events has a low overhead
    1.34 +and hence the trace buffer may be useful for debugging timing-sensitive
    1.35 +behaviours.
    1.36 +
    1.37 +\subsection{Internal API}
    1.38 +
    1.39 +To use the trace buffer functionality from within Xen, you must {\tt \#include
    1.40 +<xeno/trace.h>}, which contains definitions related to the trace buffer.  Trace
    1.41 +events are inserted into the buffer using the {\tt TRACE\_xD} ({\tt x} = 0, 1,
    1.42 +2, 3, 4 or 5) macros.  These all take an event number, plus {\tt x} additional
    1.43 +(32-bit) data as their arguments.  For trace buffer-enabled builds of Xen these
    1.44 +will insert the event ID and data into the trace buffer, along with the current
    1.45 +value of the CPU cycle-counter.  For builds without the trace buffer enabled,
    1.46 +the macros expand to no-ops and thus can be left in place without incurring
    1.47 +overheads.
    1.48 +
    1.49 +\subsection{Enabling tracing}
    1.50 +
    1.51 +By default, the trace buffer is enabled only in debug builds (i.e. {\tt NDEBUG}
    1.52 +is not defined).  It can be enabled separately by defining {\tt TRACE\_BUFFER},
    1.53 +either in {\tt <xeno/config.h>} or on the gcc command line.
    1.54 +
    1.55 +\subsection{Dumping trace data}
    1.56 +
    1.57 +When running a trace buffer build of Xen, trace data are written continuously
    1.58 +into the buffer data areas, with newer data overwriting older data.  This data
    1.59 +can be captured using the {\tt xentrace} program in Domain 0.
    1.60 +
    1.61 +The {\tt xentrace} tool uses {\tt /dev/mem} in domain 0 to map the trace
    1.62 +buffers into its address space.  It then periodically polls all the buffers for
    1.63 +new data, dumping out any new records from each buffer in turn.  As a result,
    1.64 +for machines with multiple (logical) CPUs, the trace buffer output will not be
    1.65 +in overall chronological order.
    1.66 +
    1.67 +The output from {\tt xentrace} can be post-processed using {\tt
    1.68 +xentrace\_split.py} (used to split trace data out into per-cpu log files) and
    1.69 +{\tt xentrace\_format.py} (used to pretty-print trace data).
    1.70 +
    1.71 +For more information, see the {\tt xentrace} manual page.
    1.72 +
    1.73 +
    1.74  \chapter{Hypervisor calls}
    1.75  
    1.76  \section{ set\_trap\_table(trap\_info\_t *table)}