Add C-API for the debugger. (#1688)

JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com

docs/07.DEBUGGER.md

@@ -69,4 +69,128 @@ function. This resource name is used by the client to identify
 the corresponding resource. In general it is always recommended to
 use `jerry_parse_named_resource ()` when the resource name is
 available because it silently ignores the resource name if the
-debugger is disabled.
+debugger is disabled.
+
+## JerryScript debugger C-API interface
+
+The following section describes the debugger functions
+available for the host application.
+
+### jerry_debugger_is_connected
+
+**Summary**
+
+Returns true if a remote debugger client is connected.
+
+**Prototype**
+
+```c
+bool
+jerry_debugger_is_connected (void);
+```
+
+**Example**
+
+```c
+{
+  jerry_init (JERRY_INIT_DEBUGGER);
+
+  if (jerry_debugger_is_connected ())
+  {
+    printf ("A remote debugger client is connected.");
+  }
+}
+```
+
+### jerry_debugger_stop
+
+**Summary**
+
+Stops execution at the next available breakpoint if a remote
+debugger client is connected and the engine is not waiting at
+a breakpoint. The engine will stop regardless the breakpoint
+is enabled or not.
+
+**Prototype**
+
+```c
+void
+jerry_debugger_stop (void)
+```
+
+**Example**
+
+```c
+{
+  jerry_init (JERRY_INIT_DEBUGGER);
+
+  jerry_debugger_stop ();
+}
+```
+
+**See also**
+
+- [jerry_debugger_continue](#jerry_debugger_continue)
+
+### jerry_debugger_continue
+
+**Summary**
+
+If the engine would stop at the next available breakpoint it
+cancels this effect. The engine will still stop at enabled
+breakpoints. This function effectively negates the effect of
+[jerry_debugger_stop ()](#jerry_debugger_stop) calls or stop
+requests issued by the debugger client.
+
+**Prototype**
+
+```c
+void
+jerry_debugger_continue (void)
+```
+
+**Example**
+
+```c
+{
+  jerry_init (JERRY_INIT_DEBUGGER);
+
+  jerry_debugger_continue ();
+}
+```
+
+**See also**
+
+- [jerry_debugger_stop](#jerry_debugger_stop)
+
+### jerry_debugger_disable_stop_at_breakpoint
+
+**Summary**
+
+Enables or disables stopping at breakpoints. When stopping is
+disabled all breakpoints are ignored including user enabled
+breakpoints. This allows hidden execution of ECMAScript code.
+
+**Prototype**
+
+```c
+void
+jerry_debugger_stop_at_breakpoint (bool enable_stop_at_breakpoint)
+```
+
+- `enable_stop_at_breakpoint` - enable (=`true`) or disable (=`false`) stopping at breakpoints
+
+**Example**
+
+```c
+{
+  jerry_init (JERRY_INIT_DEBUGGER);
+
+  jerry_debugger_stop_at_breakpoint (true);
+
+  // Protected execution of JavaScript code.
+  jerry_eval (...);
+
+  jerry_debugger_stop_at_breakpoint (false);
+}
+```

jerry-core/jerryscript-debugger.c

@@ -0,0 +1,90 @@
+/* Copyright JS Foundation and other contributors, http://js.foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "jcontext.h"
+#include "jerryscript-debugger.h"
+#include "jerry-debugger.h"
+
+/**
+ * Checks whether the debugger is connected.
+ *
+ * @return true - if the debugger is connected
+ *         false - otherwise
+ */
+bool
+jerry_debugger_is_connected (void)
+{
+#ifdef JERRY_DEBUGGER
+  return JERRY_CONTEXT (debugger_flags) & JERRY_DEBUGGER_CONNECTED;
+#else
+  return false;
+#endif /* JERRY_DEBUGGER */
+} /* jerry_debugger_is_connected */
+
+/**
+ * Stop execution at the next available breakpoint.
+ */
+void
+jerry_debugger_stop (void)
+{
+#ifdef JERRY_DEBUGGER
+  if ((JERRY_CONTEXT (debugger_flags) & JERRY_DEBUGGER_CONNECTED)
+      && !(JERRY_CONTEXT (debugger_flags) & JERRY_DEBUGGER_BREAKPOINT_MODE))
+  {
+    JERRY_CONTEXT (debugger_flags) = (uint8_t) (JERRY_CONTEXT (debugger_flags) | JERRY_DEBUGGER_VM_STOP);
+    JERRY_CONTEXT (debugger_stop_context) = NULL;
+  }
+#endif /* JERRY_DEBUGGER */
+} /* jerry_debugger_stop */
+
+/**
+ * Continue execution.
+ */
+void
+jerry_debugger_continue (void)
+{
+#ifdef JERRY_DEBUGGER
+  if ((JERRY_CONTEXT (debugger_flags) & JERRY_DEBUGGER_CONNECTED)
+      && !(JERRY_CONTEXT (debugger_flags) & JERRY_DEBUGGER_BREAKPOINT_MODE))
+  {
+    JERRY_CONTEXT (debugger_flags) = (uint8_t) (JERRY_CONTEXT (debugger_flags) & ~JERRY_DEBUGGER_VM_STOP);
+    JERRY_CONTEXT (debugger_stop_context) = NULL;
+  }
+#endif /* JERRY_DEBUGGER */
+} /* jerry_debugger_continue */
+
+/**
+ * Sets whether the engine should stop at breakpoints.
+ */
+void
+jerry_debugger_stop_at_breakpoint (bool enable_stop_at_breakpoint) /**< enable/disable stop at breakpoint */
+{
+#ifdef JERRY_DEBUGGER
+  if (JERRY_CONTEXT (debugger_flags) & JERRY_DEBUGGER_CONNECTED
+      && !(JERRY_CONTEXT (debugger_flags) & JERRY_DEBUGGER_BREAKPOINT_MODE))
+  {
+    if (enable_stop_at_breakpoint)
+    {
+      JERRY_CONTEXT (debugger_flags) = (uint8_t) (JERRY_CONTEXT (debugger_flags) | JERRY_DEBUGGER_VM_IGNORE);
+    }
+    else
+    {
+      JERRY_CONTEXT (debugger_flags) = (uint8_t) (JERRY_CONTEXT (debugger_flags) & ~JERRY_DEBUGGER_VM_IGNORE);
+    }
+  }
+#else /* !JERRY_DEBUGGER */
+  JERRY_UNUSED (enable_stop_at_breakpoint);
+#endif /* JERRY_DEBUGGER */
+} /* jerry_debugger_stop_at_breakpoint */

jerry-core/jerryscript-debugger.h

@@ -0,0 +1,44 @@
+/* Copyright JS Foundation and other contributors, http://js.foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef JERRYSCRIPT_DEBUGGER_H
+#define JERRYSCRIPT_DEBUGGER_H
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif /* __cplusplus */
+
+/** \addtogroup jerry Jerry engine debugger interface
+ * @{
+ */
+
+bool jerry_debugger_is_connected (void);
+void jerry_debugger_stop (void);
+void jerry_debugger_continue (void);
+void jerry_debugger_stop_at_breakpoint (bool enable_stop_at_breakpoint);
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif /* __cplusplus */
+#endif /* !JERRYSCRIPT_H */

jerry-core/jerryscript.h

@@ -19,7 +19,6 @@
 #include <stdbool.h>
 #include <stddef.h>
 #include <stdint.h>
-#include <stdio.h>
 
 #ifdef __cplusplus
 extern "C"

jerry-core/vm/vm.c

@@ -2379,7 +2379,6 @@ vm_loop (vm_frame_ctx_t *frame_ctx_p) /**< frame context */
 
           if (JERRY_CONTEXT (debugger_flags) & JERRY_DEBUGGER_VM_STOP)
           {
-            JERRY_ASSERT (JERRY_CONTEXT (debugger_stop_context) == NULL);
             jerry_debugger_breakpoint_hit (JERRY_DEBUGGER_BREAKPOINT_HIT);
           }
 #endif /* JERRY_DEBUGGER */