Initial docs on using the C bindings.

docs/intro/mojom_protocol.md

Index: docs/intro/mojom_protocol.md
diff --git a/docs/intro/mojom_protocol.md b/docs/intro/mojom_protocol.md
index 6bc3b6f4cc6249d692b1d32e5fab39a67fa8f4b7..c0080a6063f7957cbd8b6fc2b1d37d1dc9eed488 100644
--- a/docs/intro/mojom_protocol.md
+++ b/docs/intro/mojom_protocol.md
@@ -1,3 +1,97 @@
 # Mojom protocol
 
-**TODO(vtl)**
+The Mojom protocol is the canonical protocol used by 2 communicating mojo
+applications. Communication is done by sending interface messages (some people
+call them methods), whose schema is specified using the mojom IDL. This document
+assumes a basic understanding of the [Mojom IDL](mojom_idl.md).
+
+## Interface messages
+
+Communication using the protocol happens between two parties over one
+communication channel, where the requests flow one way and the responses flow
+the other. Requests and response schemas are defined by mojom interface message
+formats. The request and response parameters are each framed as mojom structs,
+where each parameter is represented by a struct field.
+
+The beginning of every request on the wire is framed by an interface message
+header. There are two versions of the message header: one which includes a
+'request id', which is used to associate a request with a reply. The other
+doesn't include a request id. Both versions also include the 'ordinal' (a
+number) identifying which interface message it is, and some flags indicating if
+the message is a request expecting a response, a response, etc.
+
+Following the message header, a mojom struct representing the request parameters
+is encoded. This the top-level (i.e., the first) mojom struct that occurs on the
+wire.
+
+## Mojom struct
+
+The wire format of a mojom struct begins with an 8-byte header, followed by
+bytes representing each field. The fields on the wire appear in packing-order,
+not ordinal-order (ordinal numbers are implicitly assigned to each field unless
+they are explicitly assigned one in the IDL). A field's byte-alignment is the
+same as the field's size (determined by its type); a 4-byte type is 4-byte
+aligned. In order to make efficient use of the space, fields are packed in the
+first available block of bytes, which may well be the alignment-padding space.
+
+## Mojom types
+There are essentially two categories of mojom types: reference (a.k.a pointer)
+types, and non-reference.
+
+### Non-reference types
+These are plain-old-data types: `int8`, `uint8`, ..., `int64`, `float32`,
+`float64`, and sometimes unions (unions can also be reference types -- more on
+that later).
+
+### Reference types
+These are types that aren't fixed size. These types include structs, unions
+(sometimes), arrays, and maps.
+
+When a mojom struct field's type is another mojom struct, that field is encoded
+as a relative byte-offset to where the actual data for the field is. The same
+applies for mojom arrays and mojom maps. For example:
+
+```mojom
+struct Child {
+  int32 a;
+  int64 b;
+  int32 c;
+};
+struct Parent {
+  Child childA;
+  Child childB;
+};
+```
+
+The `Parent` struct is encoded as:
+Byte Offset | Data | Type | Size |
+| - | - | - | - |
+0 | .. | mojom struct header for `struct Parent` | 8 |
+8 | 16 | offset to `struct Child` | 8 |
+16 | 32 | offset to `struct Child` | 8 |
+24 | .. | mojom struct header for `struct Child` | 8 |
+32 | 666 | int32 | 4 |
+36 | 666 | int32 | 4 |
+40 | 666 | int64 | 8 |
+48 | .. | mojom struct header for `struct Child` | 8 |
+56 | 666 | int32 | 4 |
+60 | 666 | int32 | 4 |
+64 | 666 | int64 | 8 |
+
+Here, we see that the actually data for `childA` starts at byte `24`, so the
+relative byte offset recorded is `16` (i.e., the start of the data is 16 bytes
+away).  Another thing to note is the order of the structs that are encoded:
+**Referenced structs must be encoded in depth-first order.** That is, the struct
+referenced by `childA` is encoded before `childB`; similarly, if `struct Child`
+were to have a reference to another struct, that struct must be encoded before
+`struct Parent`'s `childB`.
+
+In addition to the ordering, there are two more restrictions:
+1. Referenced objects (structs, arrays, etc.) may only have 1 reference to them.
+2. Offsets to objects are always positive.
+
+While the ordering and the above restrictions are a limiting, it makes certain
+operations (validation) cheaper.
+
+TODO(vardhan): Write about arrays, strings, maps, unions. Maybe this can be in
+mojom_lang/ instead of intro/?