Documentation update.

3 files changed, 56 insertions, 25 deletions

diff --git a/doc/bib.bib b/doc/bib.bib
index d6b9292..b5d2abb 100644
--- a/doc/bib.bib
+++ b/doc/bib.bib
@@ -80,3 +80,15 @@
   number = 872,
   month = oct
 }
+
+@Article{popek74requirements-for-virtualizable-architectures,
+  author = {Gerald J. Popek and Robert P. Goldberg},
+  title = {Formal Requirements for Virtualizable Third Generation
+                  Architectures},
+  journal = {Communications of the {ACM}},
+  year = 1974,
+  volume = 17,
+  number = 7,
+  pages = {412--421},
+  month = jul
+}
diff --git a/doc/reference-guide.tex b/doc/reference-guide.tex
index ffcc547..755d3e3 100644
--- a/doc/reference-guide.tex
+++ b/doc/reference-guide.tex
@@ -109,7 +109,7 @@ Viengoos was built on the following ideas:
 
 \begin{itemize}
 \item object based,
-\item virtualizable interfaces,
+\item recursively virtualizable interfaces \cite{popek74requirements-for-virtualizable-architectures},
 \item object statelessness \cite{tullmann96userlevel-checkpointing-through-exportable-kernel-state},
 \item no kernel dynamic allocation,
 \item resource accountability,
@@ -144,15 +144,16 @@ cause such file invocations to be redirected to the proxy, another
 problem arises: proxying a file is non-trivial as the object's state
 machine is quite complicated.  For instance, the proxy must maintain a
 file pointer for each client.  This is because each client expects
-that the file descriptor it designates the normal file and that the
-file pointer is private.  To work around this, the proxy must maintain
-a private file pointer for each client and then serialize access to
-the object and adjust the object's file pointer using the seek method
-before invoking the read method.  This is required even if the proxy
-only wants to do some sort of bounds checking.  To simplify
-virtualization, objects should avoid maintaining sessions: as much as
-is feasible, interfaces should be so designed such that a method
-either senses or transforms the state of the object.
+that the file descriptor it designates acts like a normal file
+descriptor, that is, that the file pointer is private.  To work around
+this, the proxy must maintain a private file pointer for each client
+and then serialize access to the object and adjust the object's file
+pointer using the seek method before invoking the read method.  This
+is required even if the proxy only wants to do some sort of bounds
+checking.  To simplify virtualization, objects should avoid
+maintaining sessions: as much as is feasible, interfaces should be so
+designed such that a method either senses or transforms the state of
+the object.
 
 \section{Future Directions or TODO}
 
@@ -172,14 +173,13 @@ walks the cappages and other objects to resolve an address but what
 should it do when it encounters an end point?  The kernel cannot
 invoke it as then it must wait for a reply and this provides an
 opportunity for destructive interference.  The kernel also cannot
-reply and to tell the client to revert to some other method of
-resolution (or can it?).  If we just fault, a process can determine
-whether an object is kernel or user-implemented by installing it in
-its address space and then trying to access it.  Perhaps, the process
-that does the virtualization can do some tricks to provide a
-user-object but when the user tries to use it in its address space, by
-interposing on the thread object, it can the install an appropriate
-cappage.
+reply and tell the client to revert to some other method of resolution
+(or can it?).  If we just fault, a process can determine whether an
+object is kernel or user-implemented by installing it in its address
+space and then trying to access it.  Perhaps, the process that does
+the virtualization can do some tricks to provide a user-object but
+when the user tries to use it in its address space, by interposing on
+the thread object, it can the install an appropriate cappage.
 
 As for the rest, to be able to virtualize a kernel object, the
 implementation needs to have access to all the information that the
diff --git a/doc/viengoos.tex b/doc/viengoos.tex
index 0cc115f..0d662d5 100644
--- a/doc/viengoos.tex
+++ b/doc/viengoos.tex
@@ -326,7 +326,7 @@ allow the easy designation of the capability that designates the
 object at some address, if there are not bits remaining to translate
 after translating the guard, the capability is returned.
 
-\section{Data Types}
+\section{Data Structures}
 
 \subsection{\type{addr}}
 
@@ -450,21 +450,40 @@ are interpreted as per cap\_copy.
 
 \begin{lstlisting}
 object_slot_read (addr_t principal, addr_t address_space,
-                    addr_t object, uint8_t slot,
-                    struct cap_properties *properties)
+    addr_t object, uint32_t slot,
+    struct cap_properties properties)
 \end{lstlisting}
 
 Store the public bits of the capability slot \var{slot} of object
 \var{object} in *\var{cap\_properties}.  Capability slots are numbered
-starting at 0.
+starting from 0.
 
 \clearpage
 \section{Folios}
 
 A folio is the unit of backing store allocation.  A folio consists of
-129 4k pages.  128 may be used to allocate objects.  The remainder is
-a header that describes the folio itself and the individual objects.
-It holds
+129 4k pages.  128 may be used to allocate objects and the remainder
+is a header that describes the folio itself and the individual
+objects.
+
+The header holds a
+
+\subsection{Data Structures}
+
+\subsubsection{folio\_priority}
+
+\begin{struct}{32}
+  \bit{\dontcare} & \bits{15}{priority} & \bits{15}{group} &
+  \bit{D}
+\end{struct}
+
+\var{D} is the discardability predicate.
+
+\begin{struct}{32}
+  \bits{5}{\dontcare} & \bit{C} & \bits{6}{type} & \bits{20}{version} \\
+  \wordbox{2}{wait\_queue\_next}
+  \wordbox{2}{wait\_queue\_prev}
+\end{struct}
 
 \subsection{Methods}