docs: Add details about protocol to the docs

This has been adopted from the documentaion about agent
that was added to the runtime docs.

Fixes clearcontainers#106

Signed-off-by: Archana Shinde <[email protected]>

README.md

@@ -6,5 +6,68 @@
 Virtual Machine agent for hardware virtualized containers
 
 ## Role
-This project holds the code related to a virtual machine agent relying on the communication protocol defined by hyperstart. That way, it allows to spawn some processes on behalf of pod/container(s) running inside the virtual machine.
-The code relies heavily on [libcontainer](https://github.com/opencontainers/runc/tree/master/libcontainer) so that we can reuse as much as possible the code used by `runc` (standard to run containers on bare metal).
+[`agent`](https://github.com/clearcontainers/agent) is a daemon that runs in the
+guest as a supervisor for managing containers and processes potentially running
+within those containers.
+
+The `agent` execution unit is the pod. An `agent` pod is a container sandbox 
+defined by a set of namespaces (NS, UTS, IPC and PID). `cc-runtime` can run 
+several containers per pod to support container engines that require multiple 
+containers running inside a single VM. In case of docker, `cc-runtime` runs a
+single container per pod.
+
+The `agent` uses a communication protocol defined by the [hyperstart](https://github.com/hyperhq/hyperstart) project.
+This was done to maintain backward compatibility with the `hyperstart` agent
+used in 2.1 version of `Clear Containers`.
+
+The `agent` interface consists of:
+- A control serial channel over which the `agent` sends and receives specific
+commands for controlling and managing pods and containers. Detailed information
+about the commands can be found at [`agent api`](https://github.com/clearcontainers/agent/tree/master/api)
+- An I/O serial channel for passing the container processes output streams
+(stdout, stderr) back to cc-proxy and receiving the input stream (stdin) 
+for them. As all streams for all containers are going through one single serial
+channel, hyperstart prepends them with container specific sequence numbers. 
+There are at most 2 sequence numbers per container process, one for stdout 
+and stdin, and another one for stderr.
+
+The `agent` supports the following commands:
+- `StartPodCmd`: Sets up a pod in a newly created VM. 
+- `NewContainerCmd`: Creates a new container within a pod. This needs to be sent
+after the StartPodCmd has been issued for starting a pod. This starts the
+container process as well.
+- `ExecCmd`: Executes a new process within an already running container.
+- `KillContainerCmd`: `cc-shim` uses this to send signals to a container process.
+- `WinsizeCmd`: `cc-shim` uses this to change the terminal size of the terminal 
+associated with a container.
+- `RemoveContainerCmd`: Removes a container from the pod. This command will
+fail for a container in running state.
+- `Destroypod`: Removes all containers within a pod . All containers need to be
+in stopped state for this command to succeed. Frees resources associated with the pod.
+
+Each control message is composed of a command code and a payload required for the command:
+
+```
+  ┌────────────────┬────────────────┬──────────────────────────────┐
+  │  Command Code  │     Length     │ Payload(request or response) │
+  │   (32 bits)    │    (32 bits)   │     (data length bytes)      │
+  └────────────────┴────────────────┴──────────────────────────────┘
+```
+- `Command Code` is the predefined id associated with a command.
+- `Length` is the size of the entire message in byes and encoded in network order.
+- `Payload` is the JSON-encoded command request or response data.
+
+Each stream message is composed of a stream sequence code and a payload 
+containing the stream data.
+
+```
+  ┌────────────────┬────────────────┬──────────────────────────────┐
+  │  Sequence Code │     Length     │          Payload             │
+  │   (64 bits)    │    (64 bits)   │     (data length bytes)      │
+  └────────────────┴────────────────┴──────────────────────────────┘
+```
+- `Sequence code` is the 64 bit sequence number assigned by the `agent` for a stream.
+- `Length` is the size of the entire stream message in bytes and encoded in network order.
+- `Payload` is the stream data.
+
+The `agent` makes use of [`libcontainer`](https://github.com/opencontainers/runc/tree/master/libcontainer) to manage the lifecycle of the container. This way the `agent` reuses most of the code used by [`runc`](https://github.com/opencontainers/runc).