YourWishes/jerryscript
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update the webpage (#5127)

Browse Source 
The GitHub ribbon is also revived.

Related issue: #5125

JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com
This commit is contained in:
Zsolt Borbély
2024-02-07 06:07:21 +01:00
committed by GitHub
parent d0671c4ff1
commit 9192b862c9
14 changed files with 2732 additions and 3647 deletions
Download Patch File Download Diff File Expand all files Collapse all files
05.PORT-API.md
+210 -319
View File
@@ -10,7 +10,7 @@ permalink: /port-api/
# Reference
## Termination
## Process management
It is questionable whether a library should be able to terminate an application. Any API function can signal an error (ex.: cannot allocate memory), so the engine use the termination approach with this port function.
@@ -34,202 +34,14 @@ Error codes
```c
typedef enum
{
ERR_OUT_OF_MEMORY = 10,
ERR_REF_COUNT_LIMIT = 12,
ERR_DISABLED_BYTE_CODE = 13,
ERR_FAILED_INTERNAL_ASSERTION = 120
JERRY_FATAL_OUT_OF_MEMORY = 10,
JERRY_FATAL_REF_COUNT_LIMIT = 12,
JERRY_FATAL_DISABLED_BYTE_CODE = 13,
JERRY_FATAL_UNTERMINATED_GC_LOOPS = 14,
JERRY_FATAL_FAILED_ASSERTION = 120
} jerry_fatal_code_t;
```
## I/O
These are the only I/O functions jerry calls.
```c
/**
* Jerry log levels. The levels are in severity order
* where the most serious levels come first.
*/
typedef enum
{
JERRY_LOG_LEVEL_ERROR, /**< the engine will terminate after the message is printed */
JERRY_LOG_LEVEL_WARNING, /**< a request is aborted, but the engine continues its operation */
JERRY_LOG_LEVEL_DEBUG, /**< debug messages from the engine, low volume */
JERRY_LOG_LEVEL_TRACE /**< detailed info about engine internals, potentially high volume */
} jerry_log_level_t;
/**
* Display or log a debug/error message, and sends it to the debugger client as well.
* The function should implement a printf-like interface, where the first argument
* specifies the log level and the second argument specifies a format string on how
* to stringify the rest of the parameter list.
*
* This function is only called with messages coming from the jerry engine as
* the result of some abnormal operation or describing its internal operations
* (e.g., data structure dumps or tracing info).
*
* It should be the port that decides whether error and debug messages are logged to
* the console, or saved to a database or to a file.
*
* Example: a libc-based port may implement this with vfprintf(stderr) or
* vfprintf(logfile), or both, depending on log level.
*
* Note:
* This port function is called by jerry-core when JERRY_LOGGING is
* enabled. It is also common practice though to use this function in
* application code.
*/
void jerry_port_log (jerry_log_level_t level, const char *fmt, ...);
```
The `jerry_port_print_char` is currently not used by the jerry-core directly.
However, it provides a port specific way for `jerry-ext` components to print
information.
```c
/**
* Print a character to stdout.
*/
void jerry_port_print_char (char c);
```
### Jerry Module system
The port API provides optional functions that can be used by the
user application to resolve modules. If no callback is provided
to `jerry_module_link`, the `jerry_port_module_resolve` function
is used for resolving modules.
```c
/**
* Opens file with the given path and reads its source.
* @return the source of the file
*/
uint8_t *
jerry_port_read_source (const char *file_name_p, /**< file name */
size_t *out_size_p) /**< [out] read bytes */
{
// open file from given path
// return its source
} /* jerry_port_read_source */
/**
* Release the previously opened file's content.
*/
void
jerry_port_release_source (uint8_t *buffer_p) /**< buffer to free */
{
free (buffer_p);
} /* jerry_port_release_source */
/**
* Default module resolver.
*
* @return a module object if resolving is successful, an error otherwise
*/
jerry_value_t
jerry_port_module_resolve (const jerry_value_t specifier, /**< module specifier string */
const jerry_value_t referrer, /**< parent module */
void *user_p) /**< user data */
{
// Resolves a module using the specifier string. If a referrer is a module,
// and specifier is a relative path, the base path should be the directory
// part extracted from the path of the referrer module.
// The callback function of jerry_module_link may call this function
// if it cannot resolve a module. Furthermore if the callback is NULL,
// this function is used for resolving modules.
// The default implementation only resolves ECMAScript modules, and does
// not (currently) use the user data.
} /* jerry_port_module_resolve */
/**
* Release known modules.
*/
void
jerry_port_module_release (const jerry_value_t realm) /**< if this argument is object, release only those modules,
* which realm value is equal to this argument. */
{
// This function releases the known modules, forcing their reload
// when resolved again later. The released modules can be filtered
// by realms. This function is only called by user applications.
} /* jerry_port_module_release */
```
## Date
```c
/**
* Get local time zone adjustment, in milliseconds, for the given timestamp.
* The timestamp can be specified in either UTC or local time, depending on
* the value of is_utc. Adding the value returned from this function to
* a timestamp in UTC time should result in local time for the current time
* zone, and subtracting it from a timestamp in local time should result in
* UTC time.
*
* Ideally, this function should satisfy the stipulations applied to LocalTZA
* in section 20.3.1.7 of the ECMAScript version 9.0 spec.
*
* See Also:
* ECMA-262 v9, 20.3.1.7
*
* Note:
* This port function is called by jerry-core when
* JERRY_BUILTIN_DATE is set to 1. Otherwise this function is
* not used.
*
* @param unix_ms The unix timestamp we want an offset for, given in
* millisecond precision (could be now, in the future,
* or in the past). As with all unix timestamps, 0 refers to
* 1970-01-01, a day is exactly 86 400 000 milliseconds, and
* leap seconds cause the same second to occur twice.
* @param is_utc Is the given timestamp in UTC time? If false, it is in local
* time.
*
* @return milliseconds between local time and UTC for the given timestamp,
* if available
*. 0 if not available / we are in UTC.
*/
double jerry_port_get_local_time_zone_adjustment (double unix_ms, bool is_utc);
/**
* Get system time
*
* Note:
* This port function is called by jerry-core when
* JERRY_BUILTIN_DATE is set to 1. It is also common practice
* in application code to use this function for the initialization of the
* random number generator.
*
* @return milliseconds since Unix epoch
*/
double jerry_port_get_current_time (void);
```
## External context
Allow user to provide external buffer for isolated engine contexts, so that user
can configure the heap size at runtime and run multiple JS applications
simultaneously.
```c
/**
* Get the current context of the engine. Each port should provide its own
* implementation of this interface.
*
* Note:
* This port function is called by jerry-core when
* JERRY_EXTERNAL_CONTEXT is enabled. Otherwise this function is not
* used.
*
* @return the pointer to the engine context.
*/
struct jerry_context_t *jerry_port_get_current_context (void);
```
## Sleep
```c
/**
* Makes the process sleep for a given time.
@@ -243,158 +55,237 @@ struct jerry_context_t *jerry_port_get_current_context (void);
void jerry_port_sleep (uint32_t sleep_time);
```
# How to port JerryScript
## External context
This section describes a basic port implementation which was created for Unix based systems.
## Termination
Allows the user to provide external buffer for isolated engine contexts, so that user
can configure the heap size at runtime and run multiple JS applications
simultaneously.
```c
#include <stdlib.h>
#include "jerryscript-port.h"
/**
* Default implementation of jerry_port_fatal.
* Allocate a new context for the engine.
*
* This port function is called by jerry_init when JERRY_EXTERNAL_CONTEXT is enabled. Otherwise this function is not
* used. The engine will pass the size required for the context structure. An implementation must make sure to
* allocate at least this amount.
*
* Excess allocated space will be used as the engine heap when jerryscript is configured to use it's internal allocator,
* this can be used to control the internal heap size.
*
* NOTE: The allocated memory must be pointer-aligned, otherwise the behavior is
* undefined.
*
* @param context_size: the size of the internal context structure
*
* @return total size of the allocated buffer
*/
void jerry_port_fatal (jerry_fatal_code_t code)
{
exit (code);
} /* jerry_port_fatal */
size_t jerry_port_context_alloc (size_t context_size);
```
```c
/**
* Get the currently active context of the engine.
*
* This port function is called by jerry-core when JERRY_EXTERNAL_CONTEXT is enabled.
* Otherwise this function is not used.
*
* @return the pointer to the currently used engine context.
*/
struct jerry_context_t *jerry_port_context_get (void);
```
```c
/**
* Free the currently used context.
*
* This port function is called by jerry_cleanup when JERRY_EXTERNAL_CONTEXT is enabled.
* Otherwise this function is not used.
*
* @return the pointer to the engine context.
*/
void jerry_port_context_free (void);
```
## I/O
```c
#include <stdarg.h>
#include "jerryscript-port.h"
/**
* Provide log message implementation for the engine.
* Display or log a debug/error message.
*
* Note:
* This example ignores the log level.
* The message is passed as a zero-terminated string. Messages may be logged in parts, which
* will result in multiple calls to this functions. The implementation should consider
* this before appending or prepending strings to the argument.
*
* This function is called with messages coming from the jerry engine as
* the result of some abnormal operation or describing its internal operations
* (e.g., data structure dumps or tracing info).
*
* The implementation can decide whether error and debug messages are logged to
* the console, or saved to a database or to a file.
*/
void
jerry_port_log (jerry_log_level_t level, /**< log level */
const char *format, /**< format string */
...) /**< parameters */
{
va_list args;
va_start (args, format);
vfprintf (stderr, format, args);
va_end (args);
} /* jerry_port_log */
void jerry_port_log (const char *message_p);
```
```c
/**
* Print a character to stdout with putchar.
* Print a single character to standard output.
*
* This port function is never called from jerry-core directly, it is only used by jerry-ext components to print
* information.
*
* @param byte: the byte to print.
*/
void
jerry_port_print_char (char c)
{
putchar (c);
} /* jerry_port_print_char */
void jerry_port_print_byte (jerry_char_t byte);
```
```c
/**
* Print a buffer to standard output
*
* This port function is never called from jerry-core directly, it is only used by jerry-ext components to print
* information.
*
* @param buffer_p: input buffer
* @param buffer_size: data size
*/
void jerry_port_print_buffer (const jerry_char_t *buffer_p, jerry_size_t buffer_size);
```
```c
/**
* Read a line from standard input.
*
* The implementation should allocate storage necessary for the string. The result string should include the ending line
* terminator character(s) and should be zero terminated.
*
* An implementation may return NULL to signal that the end of input is reached, or an error occured.
*
* When a non-NULL value is returned, the caller will pass the returned value to `jerry_port_line_free` when the line is
* no longer needed. This can be used to finalize dynamically allocated buffers if necessary.
*
* This port function is never called from jerry-core directly, it is only used by some jerry-ext components that
* require user input.
*
* @param out_size_p: size of the input string in bytes, excluding terminating zero byte
*
* @return pointer to the buffer storing the string,
* or NULL if end of input
*/
jerry_char_t *jerry_port_line_read (jerry_size_t *out_size_p);
```
```c
/**
* Free a line buffer allocated by jerry_port_line_read
*
* @param buffer_p: buffer returned by jerry_port_line_read
*/
void jerry_port_line_free (jerry_char_t *buffer_p);
```
## Filesystem
```
/**
* Canonicalize a file path.
*
* If possible, the implementation should resolve symbolic links and other directory references found in the input path,
* and create a fully canonicalized file path as the result.
*
* The function may return with NULL in case an error is encountered, in which case the calling operation will not
* proceed.
*
* The implementation should allocate storage for the result path as necessary. Non-NULL return values will be passed
* to `jerry_port_path_free` when the result is no longer needed by the caller, which can be used to finalize
* dynamically allocated buffers.
*
* NOTE: The implementation must not return directly with the input, as the input buffer is released after the call.
*
* @param path_p: zero-terminated string containing the input path
* @param path_size: size of the input path string in bytes, excluding terminating zero
*
* @return buffer with the normalized path if the operation is successful,
* NULL otherwise
*/
jerry_char_t *jerry_port_path_normalize (const jerry_char_t *path_p, jerry_size_t path_size);
```
```c
/**
* Free a path buffer returned by jerry_port_path_normalize.
*
* @param path_p: the path buffer to free
*/
void jerry_port_path_free (jerry_char_t *path_p);
```
```c
/**
* Get the offset of the basename component in the input path.
*
* The implementation should return the offset of the first character after the last path separator found in the path.
* This is used by the caller to split the path into a directory name and a file name.
*
* @param path_p: input zero-terminated path string
*
* @return offset of the basename component in the input path
*/
jerry_size_t jerry_port_path_base (const jerry_char_t *path_p);
```
```c
/**
* Open a source file and read its contents into a buffer.
*
* When the source file is no longer needed by the caller, the returned pointer will be passed to
* `jerry_port_source_free`, which can be used to finalize the buffer.
*
* @param file_name_p: Path that points to the source file in the filesystem.
* @param out_size_p: The opened file's size in bytes.
*
* @return pointer to the buffer which contains the content of the file.
*/
jerry_char_t *jerry_port_source_read (const char *file_name_p, jerry_size_t *out_size_p);
```
```c
/**
* Free a source file buffer.
*
* @param buffer_p: buffer returned by jerry_port_source_read
*/
void jerry_port_source_free (jerry_char_t *buffer_p);
```
## Date
```c
#include <time.h>
#include <sys/time.h>
#include "jerryscript-port.h"
/**
* Default implementation of jerry_port_get_local_time_zone_adjustment.
*/
double jerry_port_get_local_time_zone_adjustment (double unix_ms, /**< ms since unix epoch */
bool is_utc) /**< is the time above in UTC? */
{
struct tm tm;
time_t now = (time_t) (unix_ms / 1000);
localtime_r (&now, &tm);
if (!is_utc)
{
now -= tm.tm_gmtoff;
localtime_r (&now, &tm);
}
return ((double) tm.tm_gmtoff) * 1000;
} /* jerry_port_get_local_time_zone_adjustment */
/**
* Default implementation of jerry_port_get_current_time.
*/
double jerry_port_get_current_time (void)
{
struct timeval tv;
if (gettimeofday (&tv, NULL) != 0)
{
return 0;
}
return ((double) tv.tv_sec) * 1000.0 + ((double) tv.tv_usec) / 1000.0;
} /* jerry_port_get_current_time */
```
## External context
```c
#include "jerryscript-port.h"
#include "jerryscript-port-default.h"
/**
* Pointer to the current context.
* Note that it is a global variable, and is not a thread safe implementation.
*/
static jerry_context_t *current_context_p = NULL;
/**
* Set the current_context_p as the passed pointer.
*/
void
jerry_port_default_set_current_context (jerry_context_t *context_p) /**< points to the created context */
{
current_context_p = context_p;
} /* jerry_port_default_set_current_context */
/**
* Get the current context.
* Get local time zone adjustment in milliseconds for the given input time.
*
* @return the pointer to the current context
* The argument is a time value representing milliseconds since unix epoch.
*
* Ideally, this function should satisfy the stipulations applied to LocalTZA
* in section 21.4.1.7 of the ECMAScript version 12.0, as if called with isUTC true.
*
* This port function can be called by jerry-core when JERRY_BUILTIN_DATE is enabled.
* Otherwise this function is not used.
*
* @param unix_ms: time value in milliseconds since unix epoch
*
* @return local time offset in milliseconds applied to UTC for the given time value
*/
jerry_context_t *
jerry_port_get_current_context (void)
{
return current_context_p;
} /* jerry_port_get_current_context */
int32_t jerry_port_local_tza (double unix_ms);
```
## Sleep
```c
#include "jerryscript-port.h"
#include "jerryscript-port-default.h"
#ifdef HAVE_TIME_H
#include <time.h>
#elif defined (HAVE_UNISTD_H)
#include <unistd.h>
#endif /* HAVE_TIME_H */
#if defined (JERRY_DEBUGGER) && (JERRY_DEBUGGER == 1)
void jerry_port_sleep (uint32_t sleep_time)
{
#ifdef HAVE_TIME_H
nanosleep (&(const struct timespec)
{
(time_t) sleep_time / 1000, ((long int) sleep_time % 1000) * 1000000L /* Seconds, nanoseconds */
}
, NULL);
#elif defined (HAVE_UNISTD_H)
usleep ((useconds_t) sleep_time * 1000);
#endif /* HAVE_TIME_H */
(void) sleep_time;
} /* jerry_port_sleep */
#endif /* defined (JERRY_DEBUGGER) && (JERRY_DEBUGGER == 1) */
/**
* Get the current system time in UTC.
*
* This port function is called by jerry-core when JERRY_BUILTIN_DATE is enabled.
* It can also be used in the implementing application to initialize the random number generator.
*
* @return milliseconds since Unix epoch
*/
double jerry_port_current_time (void);
```