@@ 12,10 12,6 @@ pdf: cp-cmd-list.tex cp-directory-sample
 cp-cmd-list.tex:
 	./gen-docs.sh
 
-.PHONY: cp-directory-sample.tex
-cp-directory-sample.tex:
-	(echo "\\begin{verbatim}"; cat ../../sys/hvf.directory; echo "\\end{verbatim}") > $@
-
 clean:
-	rm -f *.toc *.aux *.cb *.cb2 *.dvi *.log manual.pdf cp-cmd-list.tex cp-directory-sample.tex
+	rm -f *.toc *.aux *.cb *.cb2 *.dvi *.log manual.pdf cp-cmd-list.tex
 	rm -rf tex/

          

@@ 1,4 1,5 @@ 
 \chapter{ABI}
+\label{chap:abi}
 HVF uses the same ABI (s390x) as Linux on z.  The following sections attempt
 to introduce portions of it.  For more information see the relevant
 literature.

          
@@ 35,4 36,81 @@ R15   &   Stack-pointer                 
 \end{center}
 
 \section{ELF Binary File Format}
-FIXME: describe ELF
+This section introduces the ELF binary file format for the s390x ABI.  For
+more detailed description, see the appropriate standard.
+
+Each ELF file begins with the following header:
+
+\begin{lstlisting}[language=C]
+typedef struct {
+	u8       e_ident[16];
+	u16      e_type;
+	u16      e_machine;
+	u32      e_version;
+	u64      e_entry;
+	u64      e_phoff;
+	u64      e_shoff;
+	u32      e_flags;
+	u16      e_ehsize;
+	u16      e_phentsize;
+	u16      e_phnum;
+	u16      e_shentsize;
+	u16      e_shnum;
+	u16      e_shstrndx;
+} Elf64_Ehdr;
+\end{lstlisting}
+
+\begin{description}
+\item[e\_ident] contains several bytes of information:
+	
+	Bytes 0-3 contain the magic ASCII string ``\textbackslash x7FELF'', which is
+	equal to 7F454C46 hex.
+
+	Byte 4 contains the ELF class which should equal 1 for 31-bit files,
+	and 2 for 64-bit files.
+
+	Byte 5 contains the byte order information.  A value of 1 indicates
+	little endian format, while value of 2 indicates a big endian
+	format.  In HVF this must always be equal to 2.
+
+	Byte 6 contains the ELF file format version.  Currently, only one
+	version is defined --- 1.
+
+	Bytes 7-15 contain other information, however HVF ignores these
+	fields.
+	% FIXME: fill this in later
+
+\item[e\_type] specifies the type of the payload.  Currently, HVF expects
+	only executables, and therefore this field should be set to 2.
+
+\item[e\_machine] identifies the target architecture.  It should always
+	equal 16 hex identifying it as ESA/390 or z/Architecture.
+
+\item[e\_version] contains the ELF header version number.  It should always
+	equal to 1.
+
+\item[e\_entry] is the address of the entry point.  That is the location of
+	the instruction to transfer control to once loading has completed.
+
+\item[e\_phoff] contains the offset into the file to the first program
+	header.  HVF ignores this field.
+
+\item[e\_shoff] contains the offset into the file to the first section
+	header.
+
+\item[e\_flags] contains processor specific flags.  HVF ignores this field.
+
+\item[e\_ehsize] is the ELF header size.  HVF ignores this field.
+
+\item[e\_phentsize] equals the program header entry size.  HVF ignores this
+	field.
+
+\item[e\_phnum] is the number of program headers.  HVF ignores this field.
+
+\item[e\_shentsize] equals the section header entry size.
+
+\item[e\_shnum] is the number of section header.
+
+\item[e\_shstrndx] contains the section name string table index.  HVF
+	ignores this field.
+\end{description}

          

@@ 1,4 1,5 @@ 
 \chapter{CP Commands}
+\label{chap:commands}
 This chapter details the CP commands.
 
 Each command is accompanied by a syntax diagram, authorization level

          

@@ 1,6 1,8 @@ 
 \chapter{CP Directory}
+\label{chap:directory}
 The directory contains a list of all valid users on the system.  Currently,
-any changes to the directory require that the nucleus be rebuilt.
+any changes to the directory require that the nucleus be rebuilt, and the
+system re-IPLed.
 
 \section{Directory Syntax}
 The directory is a simple text file with a declarative syntax used to

          
@@ 64,9 66,12 @@ long.
 \end{syntdiag}
 
 \section{Example Directory}
+Figure~\ref{fig:directory-sample} is the default directory distributed with
+HVF.  It defines several users with nearly identical configurations.
+
 \begin{figure*}[htb]
 \small
-\input{cp-directory-sample}
+\lstinputlisting{../../sys/hvf.directory}
 \captionfont
 \caption{\capfont Example directory defining three users.}
 \label{fig:directory-sample}

          

@@ 1,4 1,5 @@ 
 \chapter{CP Named Saved Segments}
+\label{chap:nss}
 XXX: describe NSS file format
 
 \section{Supplied Named Saved Segments}

          

@@ 1,5 1,7 @@ 
 \chapter{CP Programming Interfaces}
+\label{chap:prog}
 \section{DIAGs}
-FIXME: list all the diags that are supported
-\section{Remote Procedure Call Interface}
-FIXME: describe the rpc
+Currently, there are no DIAGs supported.
+
+%\section{Remote Procedure Call Interface}
+%FIXME: describe the rpc; currently not supported

          

@@ 24,7 24,7 @@ 
 \hfill HVF-0001-00
 \newpage
 \vspace*{\stretch{1}}
-\section*{First Edition (?, 2009)}
+\section*{First Edition (August, 2009)}
 This information in this manual is subject to change without notice.
 
 Please address any comments to Josef ``Jeff'' Sipek

          

@@ 1,4 1,5 @@ 
 \chapter{License}
+\label{chap:license}
 \begin{center}
 \Large
 GNU GENERAL PUBLIC LICENSE\\

          

@@ 37,6 37,19 @@ 
 \newcommand{\capfont}                   \small
 \newcommand{\captionfont}               {}
 
+\usepackage{listings}
+\lstset{%
+numbers=left,
+numberstyle=\footnotesize,
+stepnumber=1,
+numbersep=5pt,
+showspaces=false,
+frame=single,
+tabsize=8,
+captionpos=b,
+breaklines=true
+}
+
 %\setcounter{tocdepth}{3}
 
 \setlength{\parskip}{\baselineskip}

          
@@ 52,7 65,7 @@ 
 \input{cp-directory}
 \input{cp-commands}
 \input{cp-prog}
-\input{cp-nss}
+%\input{cp-nss}
 \input{abi}
 \appendix
 \input{license}

          

@@ 1,5 1,24 @@ 
 \chapter*{Preface}
-FIXME: this is where the preface will be
+This document includes information about HVF user and developer interfaces,
+as well as some internal details.
+
+Chapter~\ref{chap:directory} describes the handling of the directory.
+Including the syntax of the directory file.
+
+Chapter~\ref{chap:commands} describes each CP command in detail.  Each
+command includes a syntax diagram, as well as other information such as
+purpose, notes, and examples.
+
+Chapter~\ref{chap:prog} describes the interfaces a developer can use to
+communicate with the hypervisor.
+
+%Chapter~\ref{chap:nss} describes the design of the Named Saved Segment (NSS)
+%feature.  Additionally, it also describes the NSS supplied with HVF.
+
+Chapter~\ref{chap:abi} describes HVF's internal ABI.
+
+Appendix~\ref{chap:license} includes a copy of the GNU General Public
+License (version 2) under which HVF is licensed.
 
 %\cbstart
 %\section*{Summary of Changes in Second Edition}