From afb008d4801ca2dfdd6f495c1fde2d9bfa8a429a Mon Sep 17 00:00:00 2001
From: "turnidge@google.com" <turnidge@google.com>
Date: Wed, 20 Aug 2014 22:09:58 +0000
Subject: [PATCH] Edits to protocol.md.

R=johnmccutchan@google.com

Review URL: https://codereview.chromium.org//493893002

git-svn-id: https://dart.googlecode.com/svn/branches/bleeding_edge/dart@39433 260f80e4-7a28-3924-810f-c04153c831b5
---
 runtime/vm/service/protocol.md | 59 ++++++++++++++++++++++++++++++++--
 1 file changed, 56 insertions(+), 3 deletions(-)

diff --git a/runtime/vm/service/protocol.md b/runtime/vm/service/protocol.md
index 065d8607ca0..b9546490b1a 100644
--- a/runtime/vm/service/protocol.md
+++ b/runtime/vm/service/protocol.md
@@ -1,10 +1,63 @@
 # Dart VM Service Protocol
 
 Description
+How to start
+JSON
+Websocket
 
-## Response Format
+## Types
 
-### VM
+Every response returned by the VM Service has the <code>type</code> property.  This allows the client distinguish between different kinds of responses.  For example, global information about the VM is encoded in an response of type [VM](#VM) and information about an isolate is encoded in an response of type [Isolate](#Isolate).
+
+If the type name of a response begins with an <code>@</code> character then that response is a _reference_.  If the type name of a response does not begin with an <code>@</code> character then that response is an _object_ (or sometimes _full object_).  A reference is meant to be a subset of a full object with just enough information for the client to generate a reasonable-looking link.
+
+For example, an isolate reference may look like this...
+
+    {
+      type: "@Isolate",
+      id: "isolates/123",
+      name: "worker"
+    }
+
+... and a full isolate object would have additional properties:
+
+    {
+      type: "@Isolate",
+      id: "isolates/123",
+      name: "worker"
+      entry: ...
+      heaps: ...
+      topFrame: ...
+      ...
+    }
+ 
+## IDs
+
+Most responses returned by the VM Service have an <code>id</code> property.  An id is used to request an object from the VM.
+
+An id is either _global_ or _relative_.  Global ids can be requested from the VM directly by requesting the uri <code>/{global id}</code>.
+
+The following is a list of known,  fixed global ids:
+
+| id | uri | type
+| --- | --- | ---
+| vm | /vm | [VM](#VM)
+| flags | /flags | [FlagList](#FlagList)
+
+In addition, all isolates have global ids, but these ids are dynamically generated.  An isolate with an id like <code>isolates/123</code> would be available at the uri <code>/isolates/123</code>.
+
+Relative ids are used to refer to objects that are owned by an isolate.  Relative ids can be requested from the VM directly by requesting the uri <code>/{isolate&nbsp;id}/{relative&nbsp;id}</code>.
+
+For example, we can get information about a class with id <code>classes/Foo</code> from isolate <code>isolates/123</code> by requesting the uri <code>/isolates/123/classes/Foo</code> from the VM.
+
+The client must not parse ids -- they must be treated as opaque strings.  We reserve the right to change the ids of objects.
+
+## Events
+
+TODO
+
+## Catalog of Types
+### <a name="VM"></a>VM
 
 | keys | values | comments
 | --- | --- | ---
@@ -39,7 +92,7 @@ Description
 | name | String |
 | entry? | [@Function](#atFunction) |
 | heaps | ??? |
-| topFrame? | [@Frame](#atFrame) |
+| topFrame? | [Frame](#Frame) |
 | livePorts | int |
 | pauseOnExit | bool |
 | pauseEvent? | [DebuggerEvent](#DebuggerEvent) |