Merge pull request #22 from gcjenkinson/master

Minor updates typos, formatting and errors.

Author: gvnn3

specification/chap-intro.tex

@@ -1,5 +1,5 @@
 OpenDTrace is a dynamic tracing facility integrated into the Solaris,
-FreeBSD, and macOS operating systems -- with ports also available for
+FreeBSD, and macOS operating systems\textemdash with ports also available for
 Linux and Windows.  Dynamic tracing allows system administrators and
 software developers to develop short scripts (in the D programming
 language) that instruct OpenDTrace to instrument aspects of system
@@ -8,7 +8,7 @@
 available for the D programming language, command-line tools, and
 OpenDTrace-based investigation and operation, the internal formats to
 OpenDTrace are generally documented via the source code.  This report
-acts as a de facto specification for those formats, including the
+acts as a \textit{de facto} specification for those formats, including the
 DTrace Intermediate Format (DIF), which is a bytecode that D scripts
 are compiled into for safe execution within the kernel, and the DTrace
 Object Format (DOF), which bundles together complete scripts along
@@ -20,15 +20,15 @@ \section{Background}
 The original DTrace code was designed and developed by Sun
 Microsystems to solve a particular problem, being able to instrument
 systems that were currently deployed, without requiring the
-recompilation of any code\cite{DTrace2004}.  The DTrace system was
+recompilation of any code \cite{DTrace2004}.  The DTrace system was
 written in a portable style typical of code from the Sun Microsystems
 Kernel Development group in the early 2000s.  Shortly after the
 release of the original DTrace system a port was made, by John Birrel,
 to the FreeBSD Operating System.  A port was also made by Apple to
 their macOS at about the same time.  DTrace gained popularity as a
 dynamic tracing system throughout the first decade of the 21st Century
 and its usage is well
-documented\cite{mckusick2014design}\cite{Microsystems2008a}\cite{Gregg:2011:DDT:1971960}.
+documented \cite{mckusick2014design}\cite{Microsystems2008a}\cite{Gregg:2011:DDT:1971960}.
 
 The OpenDTrace system is meant to capture information about systems at
 run time, without the need to stop the program or kernel being
@@ -47,14 +47,14 @@ \section{Background}
 of module X?'', is a typical query that might be made of a debugger.
 The answer to this question is gathered by setting a break point at
 line 100, where the program will stop, and printing the value of the
-varialbe \emph{A}.  Debuggers are most often used in a \emph{stop and
+variable \emph{A}.  Debuggers are most often used in a \emph{stop and
   inquire} mode, while a tracing system, such as OpenDTrace, aims to
-keep overheads low enogh that we can capture and analyze information
+keep overheads low enough that we can capture and analyze information
 at run time with very little perturbation to the overall system.  The
 tracing system \emph{only} captures data at run time and \emph{never}
 stops the running system, which has the side effect of being quite
 useful for critical systems such as the operating system kernel and
-its components, such as device drivers, locking primitves and
+its components, such as device drivers, locking primitives and
 scheduler.
 
 From the perspective of the user the OpenDTrace model is one of

specification/chap-opendtrace-ctf.tex

@@ -15,7 +15,7 @@ \section{On-Disk Format}
 CTF data is stored in its own ELF section within an object file or
 executable.  It is meant to be stored in a format that is both compact
 and which is properly aligned so that it can be accessed using the
-mmap(2) system call.
+\texttt{mmap} (2) system call.
 
 \begin{figure}[h]
   \centering
@@ -71,7 +71,7 @@ \section{On-Disk Format}
     \verb|CTF_K_UNKNOWN|    & unknown type (used for padding) \\
     \verb|CTF_K_INTEGER|    & variant data is \verb|CTF_INT_DATA()| (see below)\\
     \verb|CTF_K_FLOAT|      & variant data is \verb|CTF_FP_DATA()| (see below)\\
-    \verb|CTF_K_POINTER|    & \verb|ctt_type| is referenced type\\
+    \verb|CTF_K_POINTER|    & \verb|ctf_type| is referenced type\\
     \verb|CTF_K_ARRAY|      & variant data is single \verb|ctf_array_t|\\
     \verb|CTF_K_FUNCTION| & \verb|ctt_type| is return type\\
                             &  variant data is list of argument types\\
@@ -80,17 +80,17 @@ \section{On-Disk Format}
     \verb|CTF_K_UNION|      & variant data is list of \verb|ctf_member_t|'s\\
     \verb|CTF_K_ENUM|       & variant data is list of \verb|ctf_enum_t|'s\\
     \verb|CTF_K_FORWARD|    & no additional data; \verb|ctt_name| is tag\\
-    \verb|CTF_K_TYPEDEF|    & \verb|ctt_type| is referenced type\\
-    \verb|CTF_K_VOLATILE|   & \verb|ctt_type| is base type\\
-    \verb|CTF_K_CONST|      & \verb|ctt_type| is base type\\
-    \verb|CTF_K_RESTRICT|   & \verb|ctt_type| is base type\\
+    \verb|CTF_K_TYPEDEF|    & \verb|ctf_type| is referenced type\\
+    \verb|CTF_K_VOLATILE|   & \verb|ctf_type| is base type\\
+    \verb|CTF_K_CONST|      & \verb|ctf_type| is base type\\
+    \verb|CTF_K_RESTRICT|   & \verb|ctf_type| is base type\\
     \hline
   \end{tabular}
   \caption{Kinds of CTF Base Types}
   \label{tbl:ctf-kinds}
 \end{table}
 
-Table\ref{tbl:ctf-kinds} lists the kinds of base data types that are
+Table~\ref{tbl:ctf-kinds} lists the kinds of base data types that are
 encoded by CTF.  Complex data types, such as structures, are also
 contained in the \verb|types| section, and are encoded as a structure
 with a name that references the string table.
@@ -175,7 +175,7 @@ \section{On-Disk Format}
 
 The \verb|flags| field indicates whether the integer is signed,
 contains character data, is a boolean or is to be displayed
-with a varags style of formatting.
+with a vargs style of formatting.
 
 Floating point numbers have the exact same fields to describe them
 but a larger number of possible flags, to match the larger

specification/chap-opendtrace-dlang.tex

@@ -16,7 +16,7 @@ \section{Safety}
 \label{sec:safety}
 
 The D language will look familiar to anyone who has programmed in C or
-its close linguistice relatives, but in order to provide certain
+its close linguistic relatives, but in order to provide certain
 safety guarantees there are features of C like languages that are
 missing from D.  The most obviously missing feature is the lack of any
 sort of looping mechanism.  Once they are compiled into byte code D
@@ -27,8 +27,8 @@ \section{Safety}
 occurring.
 
 By default, OpenDTrace runs in a mode where memory can be read but not
-written by D language scripts.  A command line option to the dtrace(1)
-program, -w, puts OpenDTrace into destructive mode, where both reads
+written by D language scripts.  A command line option to the \texttt{dtrace} (1)
+program, \texttt{-w}, puts OpenDTrace into destructive mode, where both reads
 and writes are possible.  Although destructive mode is not a feaure of
 the D language itself, it is an important part of the system's overall
 commitment to safety.
@@ -125,10 +125,10 @@ \subsection{Global variables}
 \noindent
 Because DIF performs all of its operations on a virtual machine's
 registers as opposed to variables in memory, the ++ operator is not
-atomic. Compiling the syscall:::entry clause from
+atomic. Compiling the \texttt{syscall:::entry} clause from
 Figure~\ref{fig:global-var-usage} generates the DIF shown in
 Figure~\ref{fig:dif-asm}.  This DIF section is safe, as long as the
-num\_syscalls variable is not visible from any other thread. If it is
+\texttt{num\_syscalls} variable is not visible from any other thread. If it is
 visible and accessible from another thread, it suffers from a race
 condition which results in wrong information being given to the
 user. The race condition is shown in Figure~\ref{fig:race}. \newline
@@ -203,7 +203,7 @@ \section{Aggregations}
 
 The ability to aggregate data during data collection, and to then
 process the data via several types of statistical analysis, is one of
-the key features of OpenDTrace.  The data for an aggretation is
+the key features of OpenDTrace.  The data for an aggregation is
 collected, like all other trace data, by the kernel, while the data
 processing is carried out in user space by the \emph{libdtrace}
 library functions.
@@ -228,7 +228,7 @@ \section{Aggregations}
 \end{table}
 
 There are nine (9) aggregation functions, which are listed in
-Table~\ref{}.
+Table~\ref{tab:agg-func}.
 
 \section{Subroutines}
 \label{sec:subroutines}

specification/chap-opendtrace-intermediate-format.tex

@@ -67,9 +67,9 @@ \subsection{Comparison and Test Instructions}
 DIF has three instructions, \instruction{cmp}, \instruction{scmp} and
 \instruction{tst} which can set various result flags, shown in
 Table~\ref{tbl:cmp-vars}.  The result flags are are later used by the
-branch instructions to determine how to .  The result flags are never
-returned directly to the calling DIF program but are only used
-internally by the interpretation routine.
+branch instructions to determine whether or not the branch is taken.
+The result flags are never returned directly to the calling DIF program but are
+only used internally by the interpretation routine.
 
 \textbf{XXXRW: Something about instructions}
 
@@ -95,9 +95,9 @@ \subsection{Subroutine Calls}
 through use of the \instruction{PUSHTR} and \instruction{PUSHTV}
 instructions. The return values of the subroutines are provided
 through the \registerop{rd} register. The subroutine identifier is
-placed in the \registerop{idx} field of the W-Format described in
-Subsection~\ref{subsec:w-format}. Any subroutine that is provided to
-DTrace \emph{must} go via these mechanisms.
+placed in the \registerop{idx} field of the wide-immediate format (W-Format)
+described in Subsection~\ref{subsec:w-format}. Any subroutine that is provided
+to DTrace \emph{must} go via these mechanisms.
 
 \begin{quote}
   Notice that we don't bother validating the proper number of
@@ -155,8 +155,8 @@ \subsection{Global Variables}
 to simple names within the D script.  Space for global variables is statically
 allocated on each invocation of a script. Additionally, global variables are
 identified using the modified register format as described in
-Subsection~\ref{subsec:r-format} the case of arrays and the wide-immediate
-format which is described in Subsection~\ref{subsec:w-format} in the case
+Subsection~\ref{subsec:r-format} the case of arrays and the W-Format
+which is described in Subsection~\ref{subsec:w-format} in the case
 of scalar variables inside of the \function{dtrace_dif_variable} function.
 
 \subsubsection{Dynamic Variables}

specification/chap-opendtrace-object-format.tex

@@ -53,7 +53,7 @@ \subsection{Stable Storage Format}
 sections associated with this DIFO.
 
 This loose coupling of the file structure (header and sections) to the
-structure of the DTrace program itself (enebled code block
+structure of the DTrace program itself (enabling control block
 descriptions, action descriptions, and DIFOs) permits activities such
 as relocation processing to occur in a single pass without having to
 understand D program structure.

specification/chap-opendtrace-operation.tex

@@ -18,28 +18,27 @@
 The kernel module is also the intermediary between the DTrace user
 interface and the providers. When compiling user scripts, the kernel
 module provides the D compiler with probe arguments and types. Once
-compiled, scripts are pushed into the kernel as Enabling Code Blocks
+compiled, scripts are pushed into the kernel as Enabling Control Blocks
 (ECBs) to be executed when probes fire. After each ECB is executed,
 the data is handed back to user space where the \texttt{dtrace}
-command line tool, or other programs linked against the OpenDtrace
+command line tool, or other programs linked against the OpenDTrace
 libraries can manipulate or display the data to end users.
 
 Providers in OpenDTrace encapsulate the probe points that are used to
 instrument code and provide data to the end user. A provider defines
 both a set of probe points as well as the standard by which the system
 interacts with that set of probe points.  For example the Function
-Boundary Tracepoint (fbt) provider defines \texttt{return} trace
+Boundary Tracepoint (\texttt{fbt}) provider defines \texttt{return} trace
 points in which only arguments zero ($0$) and one ($1$) are valid and
 which always contain the return value and return address
 respectively, whereas no other provider has such a definition.
 
 OpenDTrace has a base set of providers that are shipped as part of the
-system, see Appendix~\ref{chap:opendtrace-providers}, but developers are free
-to
+system, see Appendix~\ref{chap:opendtrace-providers}, but developers are free to
 create their own, to expose more or different information from their
 code. Providers can be developed either for the kernel, in which case
 they are defined as kernel modules, or for user space, as part of the
-User Defined Static Tracing (USDT) system.
+Userland Statically Defined Tracing (USDT) system.
 
 A provider is simply a collection of probe points. Probe points are
 functions that are run when certain points in the code are
@@ -105,7 +104,7 @@ \section{Probe Life Cycle}
 If the script did not supply any type information, the compilation
 will complete and any mismatch will result in a runtime error.
 
-The result of the D script compilation is a set of Enabling Code Blocks
+The result of the D script compilation is a set of Enabling Control Blocks
 (ECB)s.  An ECB is created for each enabling, or probe point, as well
 as for each action statement in a D language clause.
 The ECBs are provided to the kernel module (3c) which stores them,