1/* Copyright JS Foundation and other contributors, http://js.foundation
2 *
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16#ifndef JERRYSCRIPT_PORT_H
17#define JERRYSCRIPT_PORT_H
18
19#include <stdbool.h>
20#include <stdint.h>
21#include <stdio.h>
22
23#include "jerryscript-compiler.h"
24#include "jerryscript-core.h"
25
26#ifdef __cplusplus
27extern "C"
28{
29#endif /* __cplusplus */
30
31/** \addtogroup jerry_port Jerry engine port
32 * @{
33 */
34
35/*
36 * Termination Port API
37 *
38 * Note:
39 * It is questionable whether a library should be able to terminate an
40 * application. However, as of now, we only have the concept of completion
41 * code around jerry_parse and jerry_run. Most of the other API functions
42 * have no way of signaling an error. So, we keep the termination approach
43 * with this port function.
44 */
45
46/**
47 * Error codes
48 */
49typedef enum
50{
51 ERR_OUT_OF_MEMORY = 10,
52 ERR_REF_COUNT_LIMIT = 12,
53 ERR_DISABLED_BYTE_CODE = 13,
54 ERR_UNTERMINATED_GC_LOOPS = 14,
55 ERR_FAILED_INTERNAL_ASSERTION = 120
56} jerry_fatal_code_t;
57
58/**
59 * Signal the port that jerry experienced a fatal failure from which it cannot
60 * recover.
61 *
62 * @param code gives the cause of the error.
63 *
64 * Note:
65 * Jerry expects the function not to return.
66 *
67 * Example: a libc-based port may implement this with exit() or abort(), or both.
68 */
69void JERRY_ATTR_NORETURN jerry_port_fatal (jerry_fatal_code_t code);
70
71/*
72 * I/O Port API
73 */
74
75/**
76 * Jerry log levels. The levels are in severity order
77 * where the most serious levels come first.
78 */
79typedef enum
80{
81 JERRY_LOG_LEVEL_ERROR, /**< the engine will terminate after the message is printed */
82 JERRY_LOG_LEVEL_WARNING, /**< a request is aborted, but the engine continues its operation */
83 JERRY_LOG_LEVEL_DEBUG, /**< debug messages from the engine, low volume */
84 JERRY_LOG_LEVEL_TRACE /**< detailed info about engine internals, potentially high volume */
85} jerry_log_level_t;
86
87/**
88 * Display or log a debug/error message. The function should implement a printf-like
89 * interface, where the first argument specifies the log level
90 * and the second argument specifies a format string on how to stringify the rest
91 * of the parameter list.
92 *
93 * This function is only called with messages coming from the jerry engine as
94 * the result of some abnormal operation or describing its internal operations
95 * (e.g., data structure dumps or tracing info).
96 *
97 * It should be the port that decides whether error and debug messages are logged to
98 * the console, or saved to a database or to a file.
99 *
100 * Example: a libc-based port may implement this with vfprintf(stderr) or
101 * vfprintf(logfile), or both, depending on log level.
102 *
103 * Note:
104 * This port function is called by jerry-core when JERRY_LOGGING is
105 * enabled. It is also common practice though to use this function in
106 * application code.
107 */
108void JERRY_ATTR_FORMAT (printf, 2, 3) jerry_port_log (jerry_log_level_t level, const char *format, ...);
109
110/*
111 * Date Port API
112 */
113
114/**
115 * Get local time zone adjustment, in milliseconds, for the given timestamp.
116 * The timestamp can be specified in either UTC or local time, depending on
117 * the value of is_utc. Adding the value returned from this function to
118 * a timestamp in UTC time should result in local time for the current time
119 * zone, and subtracting it from a timestamp in local time should result in
120 * UTC time.
121 *
122 * Ideally, this function should satisfy the stipulations applied to LocalTZA
123 * in section 20.3.1.7 of the ECMAScript version 9.0 spec.
124 *
125 * See Also:
126 * ECMA-262 v9, 20.3.1.7
127 *
128 * Note:
129 * This port function is called by jerry-core when
130 * JERRY_BUILTIN_DATE is defined to 1. Otherwise this function is
131 * not used.
132 *
133 * @param unix_ms The unix timestamp we want an offset for, given in
134 * millisecond precision (could be now, in the future,
135 * or in the past). As with all unix timestamps, 0 refers to
136 * 1970-01-01, a day is exactly 86 400 000 milliseconds, and
137 * leap seconds cause the same second to occur twice.
138 * @param is_utc Is the given timestamp in UTC time? If false, it is in local
139 * time.
140 *
141 * @return milliseconds between local time and UTC for the given timestamp,
142 * if available
143 *. 0 if not available / we are in UTC.
144 */
145double jerry_port_get_local_time_zone_adjustment (double unix_ms, bool is_utc);
146
147/**
148 * Get system time
149 *
150 * Note:
151 * This port function is called by jerry-core when
152 * JERRY_BUILTIN_DATE is defined to 1. It is also common practice
153 * in application code to use this function for the initialization of the
154 * random number generator.
155 *
156 * @return milliseconds since Unix epoch
157 */
158double jerry_port_get_current_time (void);
159
160/**
161 * Get the current context of the engine. Each port should provide its own
162 * implementation of this interface.
163 *
164 * Note:
165 * This port function is called by jerry-core when
166 * JERRY_EXTERNAL_CONTEXT is enabled. Otherwise this function is not
167 * used.
168 *
169 * @return the pointer to the engine context.
170 */
171struct jerry_context_t *jerry_port_get_current_context (void);
172
173/**
174 * Makes the process sleep for a given time.
175 *
176 * Note:
177 * This port function is called by jerry-core when JERRY_DEBUGGER is
178 * enabled (set to 1). Otherwise this function is not used.
179 *
180 * @param sleep_time milliseconds to sleep.
181 */
182void jerry_port_sleep (uint32_t sleep_time);
183
184/**
185 * Print a single character.
186 *
187 * Note:
188 * This port function is here so the jerry-ext components would have
189 * a common way to print out information.
190 * If possible do not use from the jerry-core.
191 *
192 * @param c the character to print.
193 */
194void jerry_port_print_char (char c);
195
196/**
197 * Open a source file and read its contents into a buffer.
198 *
199 * Note:
200 * This port function is called by jerry-core when JERRY_MODULE_SYSTEM
201 * is enabled. The path is specified in the import statement's 'from "..."'
202 * section.
203 *
204 * @param file_name_p Path that points to the EcmaScript file in the
205 * filesystem.
206 * @param out_size_p The opened file's size in bytes.
207 *
208 * @return the pointer to the buffer which contains the content of the file.
209 */
210uint8_t *jerry_port_read_source (const char *file_name_p, size_t *out_size_p);
211
212/**
213 * Frees the allocated buffer after the contents of the file are not needed
214 * anymore.
215 *
216 * @param buffer_p The pointer the allocated buffer.
217 */
218void jerry_port_release_source (uint8_t *buffer_p);
219
220/**
221 * Normalize a file path string.
222 *
223 * Note:
224 * This port function is called by jerry-core when JERRY_MODULE_SYSTEM
225 * is enabled. The normalized path is used to uniquely identify modules.
226 *
227 * @param in_path_p Input path as a zero terminated string.
228 * @param out_buf_p Pointer to the output buffer where the normalized path should be written.
229 * @param out_buf_size Size of the output buffer.
230 * @param base_file_p A file path that 'in_path_p' is relative to, usually the current module file.
231 * A NULL value represents that 'in_path_p' is relative to the current working directory.
232 *
233 * @return length of the string written to the output buffer
234 * zero, if the buffer was not sufficient or an error occured
235 */
236size_t jerry_port_normalize_path (const char *in_path_p,
237 char *out_buf_p,
238 size_t out_buf_size,
239 char *base_file_p);
240
241/**
242 * Get the module object of a native module.
243 *
244 * Note:
245 * This port function is called by jerry-core when JERRY_MODULE_SYSTEM
246 * is enabled.
247 *
248 * @param name String value of the module specifier.
249 *
250 * @return Undefined, if 'name' is not a native module
251 * jerry_value_t containing the module object, otherwise
252 */
253jerry_value_t jerry_port_get_native_module (jerry_value_t name);
254
255/**
256 * HostPromiseRejectionTracker operations
257 */
258typedef enum
259{
260 JERRY_PROMISE_REJECTION_OPERATION_REJECT, /**< promise is rejected without any handlers */
261 JERRY_PROMISE_REJECTION_OPERATION_HANDLE, /**< handler is added to a rejected promise for the first time */
262} jerry_promise_rejection_operation_t;
263
264/**
265 * Track unhandled promise rejections.
266 *
267 * Note:
268 * This port function is called by jerry-core when JERRY_BUILTIN_PROMISE
269 * is enabled.
270 *
271 * @param promise rejected promise
272 * @param operation HostPromiseRejectionTracker operation
273 */
274void jerry_port_track_promise_rejection (const jerry_value_t promise,
275 const jerry_promise_rejection_operation_t operation);
276
277/**
278 * @}
279 */
280
281#ifdef __cplusplus
282}
283#endif /* __cplusplus */
284#endif /* !JERRYSCRIPT_PORT_H */
285