Author: [EMAIL PROTECTED]
Date: Mon Sep 22 07:49:37 2008
New Revision: 355
Added:
wiki/DebuggerProtocol.wiki
Log:
Created wiki page through web user interface.
Added: wiki/DebuggerProtocol.wiki
==============================================================================
--- (empty file)
+++ wiki/DebuggerProtocol.wiki Mon Sep 22 07:49:37 2008
@@ -0,0 +1,535 @@
+#summary Description of the V8 debugger JSON based protocol.
+
+= Introduction =
+
+V8 has support for debugging the JavaScript code running in it. There are
two API's for this a function based API using JavaScript objects and a
message based API using a JSON based protocol. The function based API can
be used by an in-process debugger agent, whereas the message based API can
be used out of process as well.
+
+The debugger protocol is based on [http://www.json.org/ JSON]). Each
protocol package is defined in terms of JSON and is transmitted as a string
value. All packages have two basic elements `seq` and `type`.
+
+{{{
+{ "seq" : <number>,
+ "type" : <type>,
+ ...
+}
+}}}
+
+The element `seq` holds the sequence number of the package. And element
type is the type of the package. The type is a string value with one of the
following values `"request"`, `"response"` or `"event"`.
+
+A `"request"` package has the following structure:
+
+{{{
+{ "seq" : <number>,
+ "type" : "request",
+ "command" : <command>
+ "arguments" : ...
+}
+}}}
+
+A `"response"` package has the following structure. If `success` is true
`body` will contain the response data. If `success` is false `message` will
contain an error message.
+
+{{{
+{ "seq" : <number>,
+ "type" : "response",
+ "request_seq" : <number>,
+ "command" : <command>
+ "body" : ...
+ "running" : <is the VM running after sending this response>
+ "success" : <boolean indicating success>
+ "message" : <if command failed this property contains an error
message>
+}
+}}}
+
+An `"event"` package has the following structure:
+
+{{{
+{ "seq" : <number>,
+ "type" : "event",
+ "event" : <event name>
+ body : ...
+}
+}}}
+
+= Request/response pairs =
+
+== Request `continue` ==
+
+The request `continue` is a request from the debugger to start the VM
running again. As part of the `continue` request the debugger can specify
if it wants the VM to perform a single step action.
+
+{{{
+{ "seq" : <number>,
+ "type" : "request",
+ "command" : "continue",
+ "arguments" : { "stepaction" : <"in", "next" or "out">,
+ "stepcount" : <number of steps (default 1)>
+ }
+}
+}}}
+
+In the response the property `running` will always be true as the VM will
be running after executing the `continue` command. If a single step action
is requested the VM will respond with a `break` event after running the
step.
+
+{{{
+{ "seq" : <number>,
+ "type" : "response",
+ "request_seq" : <number>,
+ "command" : "continue",
+ "running" : true
+ "success" : true
+}
+}}}
+
+
+Here are a couple of examples.
+
+{{{
+{"seq":117,"type":"request","command":"continue"}
+{"seq":118,"type":"request","command":"continue","arguments":{"stepaction":"out"}}
+{"seq":119,"type":"request","command":"continue","arguments":{"stepaction":"next","stepcount":5}}
+}}}
+
+== Request `evaluate` ==
+
+The request `evaluate` is used to evaluate an expression. The body of the
result is as described in response object serialization below.
+
+{{{
+{ "seq" : <number>,
+ "type" : "request",
+ "command" : "evaluate",
+ "arguments" : { "expression" : <expression to evaluate>,
+ "frame" : <number>,
+ "global" : <boolean>,
+ "disable_break" : <boolean>
+ }
+}
+}}}
+
+Response:
+
+{{{
+{ "seq" : <number>,
+ "type" : "response",
+ "request_seq" : <number>,
+ "command" : "evaluate",
+ "body" : ...
+ "running" : <is the VM running after sending this response>
+ "success" : true
+}
+}}}
+
+Here are a couple of examples.
+
+{{{
+{"seq":117,"type":"request","command":"evaluate","arguments":{"expression":"1+2"}}
+{"seq":118,"type":"request","command":"evaluate","arguments":{"expression":"a()","frame":3,"disable_break":false}}
+{"seq":119,"type":"request","command":"evaluate","arguments":{"expression":"[o.a,o.b,o.c]","global":true,"disable_break":true}}
+}}}
+
+== Request `backtrace` ==
+
+The request `backtrace` returns a backtrace (or stacktrace) from the
current execution state. When issuing a request a range of frames can be
supplied. The top frame is frame number 0. If no frame range is supplied
data for all frames will be returned.
+
+{{{
+{ "seq" : <number>,
+ "type" : "request",
+ "command" : "backtrace",
+ "arguments" : { "fromFrame" : <number>
+ "toFrame" : <number>
+ }
+}
+}}}
+
+The response contains the frame data together with the actual frames
returned and the toalt frame count.:
+
+{{{
+{ "seq" : <number>,
+ "type" : "response",
+ "request_seq" : <number>,
+ "command" : "backtrace",
+ "body" : { "fromFrame" : <number>
+ "toFrame" : <number>
+ "totalFrames" : <number>
+ "frames" : [ ... ]
+ }
+ "running" : <is the VM running after sending this response>
+ "success" : true
+}
+}}}
+
+Here are a couple of examples.
+
+{{{
+{"seq":117,"type":"request","command":"backtrace"}
+{"seq":118,"type":"request","command":"backtrace","arguments":{"toFrame":2}}
+{"seq":119,"type":"request","command":"backtrace","arguments":{"fromFrame":0,"toFrame":9}}
+}}}
+
+== Request `frame` ==
+
+The request frame selects a new selected frame and returns information for
that. If no frame number is specified the selected frame is returned.
+
+{{{
+{ "seq" : <number>,
+ "type" : "request",
+ "command" : "frame",
+ "arguments" : { "number" : <frame number>
+ }
+}
+}}}
+
+Response:
+
+{{{
+{ "seq" : <number>,
+ "type" : "response",
+ "request_seq" : <number>,
+ "command" : "frame",
+ "body" : { ...
+ }
+ "running" : <is the VM running after sending this response>
+ "success" : true
+}
+}}}
+
+Here are a couple of examples.
+
+{{{
+{"seq":117,"type":"request","command":"frame"}
+{"seq":118,"type":"request","command":"frame","arguments":{"number":1}}
+}}}
+
+== Request `scripts` ==
+
+The request `scripts` retrieves active scripts from the VM. An active
script is source code from which there is still live objects in the VM.
This request will always force a full garbage collection in the VM.
+
+{{{
+{ "seq" : <number>,
+ "type" : "request",
+ "command" : "scripts",
+ "arguments" : { "types" : <types of scripts to retrieve
+ set bit 0 for native scripts
+ set bit 1 for extension scripts
+ set bit 2 for normal scripts
+ (default is 4 for normal scripts)>
+ }
+}
+}}}
+
+The request contains an array of the scripts in the VM. This information
includes the relative location of the script within the containing resource.
+
+{{{
+{ "seq" : <number>,
+ "type" : "response",
+ "request_seq" : <number>,
+ "command" : "scripts",
+ "body" : [ { "name" : <name of the script>,
+ "lineOffset" : <line offset within the containing
resource>
+ "columnOffset" : <column offset within the
containing resource>
+ "lineCount" : <number of lines in the script>
+ "sourceStart" : <first 80 characters of the source>
+ "sourceLength" : <total length of the source in
characters>
+ "type" : <script type (see request for values)>
+
+ ]
+ "running" : <is the VM running after sending this response>
+ "success" : true
+}
+}}}
+
+Here are a couple of examples.
+
+{{{
+{"seq":117,"type":"request","command":"scripts"}
+{"seq":118,"type":"request","command":"scripts","arguments":{"types":7}}
+}}}
+
+== Request `source` ==
+
+The request `source` retrieves source code for a frame. It returns a
number of source lines running from the `fromLine` to but not including the
`toLine`, that is the interval is open on the "to" end. For example,
requesting source from line 2 to 4 returns two lines (2 and 3). Also note
that the line numbers are 0 based: the first line is line 0.
+
+{{{
+{ "seq" : <number>,
+ "type" : "request",
+ "command" : "source",
+ "arguments" : { "frame" : <frame number (default selected frame)>
+ "fromLine" : <from line within the source default is
line 0>
+ "toLine" : <to line within the source this line is not
included in
+ the result default is the number of lines
in the script>
+ }
+}
+}}}
+
+Response:
+
+{{{
+{ "seq" : <number>,
+ "type" : "response",
+ "request_seq" : <number>,
+ "command" : "source",
+ "body" : { "source" : <the source code>
+ "fromLine" : <actual from line within the script>
+ "toLine" : <actual to line within the script
this line is not included in the source>
+ "fromPosition" : <actual start position within the
script>
+ "toPosition" : <actual end position within the
script>
+ "totalLines" : <total lines in the script>
+ }
+ "running" : <is the VM running after sending this response>
+ "success" : true
+}
+}}}
+
+Here are a couple of examples.
+
+{{{
+{"seq":117,"type":"request","command":"source","arguments":{"fromLine":10,"toLine":20}}
+{"seq":118,"type":"request","command":"source","arguments":{"frame":2,"fromLine":10,"toLine":20}}
+}}}
+
+== Request `setbreakpoint` ==
+
+The request `setbreakpoint` creates a new break point. This request can be
used to set both function and script break points. A function break point
sets a break point in an existing function whereas a script break point
sets a break point in a named script. A script break point can be set even
if the named script is not found.
+
+{{{
+{ "seq" : <number>,
+ "type" : "request",
+ "command" : "setbreakpoint",
+ "arguments" : { "type" : <"function" or "script">
+ "target" : <function expression or script
identification>
+ "line" : <line in script or function>
+ "position" : <character position within the line>
+ "enabled" : <initial enabled state. True or false,
default is true>
+ "condition" : <string with break point condition>
+ "ignoreCount" : <number specifying the number of break
point hits to ignore, default value is 0>
+ }
+}
+}}}
+
+The result of the `setbreakpoint` request is a response with the number of
the newly created break point. This break point number is used in the
`changebreakpoint` and `clearbreakpoint` requests.
+
+{{{
+{ "seq" : <number>,
+ "type" : "response",
+ "request_seq" : <number>,
+ "command" : "setbreakpoint",
+ "body" : { "type" : <"function" or "script">
+ "breakpoint" : <break point number of the new break
point>
+ }
+ "running" : <is the VM running after sending this response>
+ "success" : true
+}
+}}}
+
+Here are a couple of examples.
+
+{{{
+{"seq":117,"type":"request","command":"setbreakpoint","arguments":{"type":"function,"target":"f"}}
+{"seq":118,"type":"request","command":"setbreakpoint","arguments":{type:"script","target":"test.js","line":100}}
+{"seq":119,"type":"request","command":"setbreakpoint","arguments":{"type":"function,"target":"f","condition":"i
>
7"}}
+}}}
+
+
+== Request `changebreakpoint` ==
+
+The request `changebreakpoint` changes the status of a break point.
+
+{{{
+{ "seq" : <number>,
+ "type" : "request",
+ "command" : "changebreakpoint",
+ "arguments" : { "breakpoint" : <number of the break point to clear>
+ "enabled" : <initial enabled state. True or false,
default is true>
+ "condition" : <string with break point condition>
+ "ignoreCount" : <number specifying the number of break
point hits }
+}
+}}}
+
+= Request `clearbreakpoint` =
+
+The request `clearbreakpoint` clears a break point.
+
+{{{
+{ "seq" : <number>,
+ "type" : "request",
+ "command" : "clearbreakpoint",
+ "arguments" : { "type" : <"function" or "script">
+ "breakpoint" : <number of the break point to clear>
+ }
+}
+}}}
+
+Response:
+
+{{{
+{ "seq" : <number>,
+ "type" : "response",
+ "request_seq" : <number>,
+ "command" : "clearbreakpoint",
+ "body" : { "type" : <"function" or "script">
+ "breakpoint" : <number of the break point cleared>
+ }
+ "running" : <is the VM running after sending this response>
+ "success" : true
+}
+}}}
+
+Here are a couple of examples.
+
+{{{
+{"seq":117,"type":"request","command":"clearbreakpoint","arguments":{"type":"function,"breakpoint":1}}
+{"seq":118,"type":"request","command":"clearbreakpoint","arguments":{"type":"script","breakpoint":2}}
+}}}
+
+= Events =
+
+== Event `break` ==
+
+The event `break` indicate that the execution in the VM has stopped due to
a break condition. This can be caused by an unconditional break request, by
a break point previously set, a stepping action have completed or by
executing the `debugger` statement in JavaScript.
+
+{{{
+{ "seq" : <number>,
+ "type" : "event",
+
+ "event" : "break",
+ "body" : { "invocationText" : <text representation of the stack frame>,
+ "sourceLine" : <source line where execution is stopped>,
+ "sourceColumn" : <column within the source line where
execution is stopped>,
+ "sourceLineText" : <text for the source line where execution
is stopped>,
+ "script" : { name : <resource name of the
origin of the script>
+ lineOffset : <line offset within the
origin of the script>
+ columnOffset : <column offset within
the origin of the script>
+ lineCount : <number of lines in the
script>
+ "breakpoints" : <array of break point numbers hit if any>
+ }
+}
+}}}
+
+Here are a couple of examples.
+
+{{{
+{"seq":117,"type":"event","event":"break","body":{"functionName":"f","sourceLine":1,"sourceColumn":14}}
+{"seq":117,"type":"event","event":"break","body":{"functionName":"g","scriptData":"test.js","sourceLine":12,"sourceColumn":22,"breakpoints":[1]}}
+{"seq":117,"type":"event","event":"break","body":{"functionName":"h","sourceLine":100,"sourceColumn":12,"breakpoints":[3,5,7]}}
+}}}
+
+== Event `exception` ==
+
+The event `exception` indicate that the execution in the VM has stopped
due to an exception.
+
+{{{
+{ "seq" : <number>,
+ "type" : "event",
+ "event" : "exception",
+ "body" : { "uncaught" : <boolean>,
+ "exception" : ...
+ "sourceLine" : <source line where the exception was
thrown>,
+ "sourceColumn" : <column within the source line from where
the exception was thrown>,
+ "sourceLineText" : <text for the source line from where the
exception was thrown>,
+ "script" : { "name" : <name of script>
+ "lineOffset" : <number>
+ "columnOffset" : <number>
+ "lineCount" : <number>
+ }
+
+ }
+}
+}}}
+
+= Response object serialization =
+
+Some responses contain values as part of the body, e.g. the response to
the evaluate request contains the result of the expression evaluated. For
all values the JSON serialization contains the type of the object.
+
+{{{
+{ "type" :
<"undefined", "null", "boolean", "number", "string", "object", "function"
or "frame">
+}
+}}}
+
+For the primitive JavaScript types `undefined` and `null` the type
describes the value fully.
+
+{{{
+{"type":"undefined"}
+}}}
+
+{{{
+{"type":"null"}
+}}}
+
+For the rest of the primitive types `boolean`, `number` and `string` the
value is part of the result.
+
+{{{
+{ "type" : <"boolean", "number" or "string">
+ "value" : <JSON encoded value>
+}
+}}}
+
+Boolean value.
+
+{{{
+{"type":"boolean","value":true}
+}}}
+
+Number value.
+
+{{{
+{"type":"number","value":42}
+}}}
+
+String value.
+
+{{{
+{"type":"string","value":"a string"}
+}}}
+
+An object is encoded with additional information.
+
+{{{
+{ "type" : "object"
+ "cls" : <Class name, ECMA-262 property [[Class]]>
+ "ctor" : <JSON encoded value>
+ "proto" : <JSON encoded value>
+ "properties" : [ {"name" : <name>,
+ "value" : <JSON encoded value>
+ },
+ ...
+ ]
+}
+}}}
+
+{{{
+{"type":"object","cls":"Object","ctor":{...},"proto":{...},"properties":[{"name":"a","value:1},{"name":"b","value":2}]}
+}}}
+
+An function is encoded as an object but with additional information.
+
+{{{
+{ "type" : "function"
+ "cls" : "Function"
+ "name" : "function name"
+ "source" : <function source>
+ "ctor" : <JSON encoded value>
+ "proto" : <JSON encoded value>
+ "properties" : [ {"name" : <name>,
+ "value" : <JSON encoded value>
+ },
+ ...
+ ]
+}
+}}}
+
+Array objects are encoded like objects but the properties are split into
indexed properties and named properties. Also for Arrays the length is
encoded. The `indexedProperties` part does not contain indexes for which
the value is undefined.
+
+{{{
+{ "type" : "object"
+ "cls" : "Array"
+ "ctor" : <JSON encoded value>
+ "proto" : <JSON encoded value>
+ ""length" : <length of the array>
+ "indexedProperties" : [ {"index" : <index number>,
+ "value" : <JSON encoded value>
+ },
+ ...
+ ]
+ "namedProperties" : [ {"name" : <name>,
+ "value" : <JSON encoded value>
+ },
+ ...
+ ]
+}
+}}}
\ No newline at end of file
--~--~---------~--~----~------------~-------~--~----~
v8-dev mailing list
[email protected]
http://groups.google.com/group/v8-dev
-~----------~----~----~----~------~----~------~--~---
