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 27 extern "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 */ 49 typedef 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 */ 69 void 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 */ 79 typedef 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 */ 108 void 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 */ 145 double 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 */ 158 double 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 */ 171 struct 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 */ 182 void 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 */ 194 void 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 */ 210 uint8_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 */ 218 void 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 */ 236 size_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 */ 253 jerry_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