--- a/docs/fs-protocol.md	Sat Oct 17 15:27:39 2015 -0400
+++ b/docs/fs-protocol.md	Sat Oct 17 16:35:10 2015 -0400
@@ -1,28 +1,43 @@
 This document describes the RPC protocol between the client daemon and the
 fs component.  It is still a work-in-progress.
 
-Each RPC message is made up of 128-byte message followed by zero or more data
-bytes.  The data bytes are consumed in the order that the fields in the fixed
-size message are defined.  All multi-byte integers are stored in big endian.
+Currently, we use `rpcgen(1)` created XDR encoding.
 
-The first two bytes of the message define an "opcode".
+Each RPC request begins with a `struct rpc_header_req`.  It is then followed
+by a variable number of bytes representing the rest of the request.  The
+exact layout of this additional payload depends on the `opcode` in the
+request header.
 
-struct msg {
+```C
+struct rpc_header_req {
 	uint16_t opcode;
-	uint8_t opaque[126];
 };
+```
 
-The interpretation of the opaque portion of the message varies based on the
-opcode.
+Each RPC reply starts with a `struct rpc_header_res` which contains a status
+code.  In the case of success (status code is 0), more data may follow
+depending on the `opcode` in the request header.
+
+```C
+struct rpc_header_res {
+	uint32_t err;
+};
+```
 
-Each RPC returns a status code and possibly additional data.  The following
-list of RPC commands does not explicitly list the status code since it is
-always present.
+The following list of RPC commands does not explicitly list the request and
+response headers since they are always present.  It only lists the
+additional fields that follow.
 
-Many of the RPC commands use an object handle (struct nobjhndl) which is
+Many of the RPC commands use an object handle (`struct nobjhndl`) which is
 just a shorthand for a oid combined with a vector clock.
 
 
+NOP (0x0000)
+============
+
+This is a simple no-operation.
+
+
 LOGIN (0x0001)
 ==============
 
@@ -30,24 +45,28 @@
 the daemon of a mount request.  Eventually, this will also contain
 credentials checking, etc. (hence the name).
 
-	arg:
-	 - conn name
-	 - vg name
+Inputs
+------
+* conn name
+* vg name
 
-	ret:
-	 - obj handle of root
+Outputs
+-------
+* obj handle of root
 
 
 STAT (0x0002)
 =============
 
-Get attributes (struct nattr) for a specific version of an object.
+Get attributes (`struct nattr`) for a specific version of an object.
 
-	arg:
-	 - obj handle
+Inputs
+------
+* obj handle
 
-	ret:
-	 - attributes
+Outputs
+-------
+* attributes
 
 
 LOOKUP (0x0003)
@@ -56,18 +75,22 @@
 Given a directory (handle) and a path component (string), do a lookup of the
 path component in the directory.
 
-	arg:
-	 - directory/parent obj handle
-	 - path component name
+Inputs
+------
+* directory/parent obj handle
+* path component name
 
-	ret:
-	 - child obj handle
+Outputs
+-------
+* child obj handle
 
 Is the return value flawed?  What if someone replaces a file?  E.g.,
 
+```
 $ touch foo
 $ rm foo
 $ touch foo
+```
 
 THOUGHT: The second "foo" will have a totally different oid.  Does this mean
 that the directory has to keep track of the previous oids?  Maybe not
@@ -83,15 +106,17 @@
 Given a directory (obj handle), a path component (string), and mode (both
 type and access bits) create the new path component returning the handle of
 the newly created file.  Creating an already existing path component fails
-with EEXIST.
+with `EEXIST`.
 
-	arg:
-	 - directory/parent obj handle
-	 - path component name
-	 - mode (see NATTR_*)
+Inputs
+------
+* directory/parent obj handle
+* path component name
+* mode (see `NATTR_*`)
 
-	ret:
-	 - new file/dir/etc.'s obj handle
+Outputs
+-------
+* new file/dir/etc.'s obj handle
 
 
 REMOVE (0x0005)
@@ -99,11 +124,12 @@
 
 Given a directory (obj handle) and a path component (string), remove the
 path component from the directory.  Removing a non-existent path component
-fails with ENOENT.
+fails with `ENOENT`.
 
-	arg:
-	 - directory/parent obj handle
-	 - path component name
+Inputs
+------
+* directory/parent obj handle
+* path component name
 
 THOUGHT: Should this RPC also take an obj handle of the object we want to
 remove?
@@ -112,7 +138,7 @@
 Other RPCs that may end up useful
 =================================
 
-OPEN - open a file/dir
-CLOSE - close a file/dir
-READ - read an open file
-WRITE - write an open file
+* OPEN - open a file/dir
+* CLOSE - close a file/dir
+* READ - read an open file
+* WRITE - write an open file