From 343bac56b2ad7d7b8213fa3f6944f5c432a9b566 Mon Sep 17 00:00:00 2001 From: Zoltan Herczeg Date: Wed, 29 Mar 2017 12:46:07 +0200 Subject: [PATCH] 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 | 126 +++++++++++++++++++++++++++++- jerry-core/jerryscript-debugger.c | 90 +++++++++++++++++++++ jerry-core/jerryscript-debugger.h | 44 +++++++++++ jerry-core/jerryscript.h | 1 - jerry-core/vm/vm.c | 1 - 5 files changed, 259 insertions(+), 3 deletions(-) create mode 100644 jerry-core/jerryscript-debugger.c create mode 100644 jerry-core/jerryscript-debugger.h diff --git a/docs/07.DEBUGGER.md b/docs/07.DEBUGGER.md index c84645a06..99ab673dc 100644 --- a/docs/07.DEBUGGER.md +++ b/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. \ No newline at end of file +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); +} +``` diff --git a/jerry-core/jerryscript-debugger.c b/jerry-core/jerryscript-debugger.c new file mode 100644 index 000000000..e869969e0 --- /dev/null +++ b/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 */ diff --git a/jerry-core/jerryscript-debugger.h b/jerry-core/jerryscript-debugger.h new file mode 100644 index 000000000..1cdcaeac4 --- /dev/null +++ b/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 +#include +#include + +#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 */ diff --git a/jerry-core/jerryscript.h b/jerry-core/jerryscript.h index 77c53dd12..99b1559fd 100644 --- a/jerry-core/jerryscript.h +++ b/jerry-core/jerryscript.h @@ -19,7 +19,6 @@ #include #include #include -#include #ifdef __cplusplus extern "C" diff --git a/jerry-core/vm/vm.c b/jerry-core/vm/vm.c index 63090fc2b..f909a5a6e 100644 --- a/jerry-core/vm/vm.c +++ b/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 */