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_ES2015_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 ES2015_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 ES2015_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 * @}
257 */
258
259#ifdef __cplusplus
260}
261#endif /* __cplusplus */
262#endif /* !JERRYSCRIPT_PORT_H */
263