Add documentation to port API

JerryScript-DCO-1.0-Signed-off-by: László Langó [email protected]

docs/05.PORT-API.md

@@ -0,0 +1,210 @@
+# Reference
+
+## Termination
+
+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.
+
+```c
+/**
+ * Signal the port that jerry experienced a fatal failure from which it cannot
+ * recover.
+ *
+ * @param code gives the cause of the error.
+ *
+ * Note: jerry expects the function not to return.
+ *
+ * Example: a libc-based port may implement this with exit() or abort(), or both.
+ */
+void jerry_port_fatal (jerry_fatal_code_t code);
+```
+
+Error codes
+
+```c
+typedef enum
+{
+  ERR_OUT_OF_MEMORY = 10,
+  ERR_SYSCALL = 11,
+  ERR_REF_COUNT_LIMIT = 12,
+  ERR_FAILED_INTERNAL_ASSERTION = 120
+} jerry_fatal_code_t;
+```
+
+## I/O
+
+These are the only I/O functions jerry calls.
+
+```c
+/**
+ * Print a string to the console. The function should implement a printf-like
+ * interface, where the first argument specifies a format string on how to
+ * stringify the rest of the parameter list.
+ *
+ * This function is only called with strings coming from the executed ECMAScript
+ * wanting to print something as the result of its normal operation.
+ *
+ * It should be the port that decides what a "console" is.
+ *
+ * Example: a libc-based port may implement this with vprintf().
+ */
+void jerry_port_console (const char *fmt, ...);
+
+/**
+ * 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. 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.
+ */
+void jerry_port_log (jerry_log_level_t level, const char *fmt, ...);
+```
+
+## Date
+
+```c
+/**
+ * Jerry time zone structure
+ */
+typedef struct
+{
+  int offset;                /**< minutes from west */
+  int daylight_saving_time;  /**< daylight saving time (1 - DST applies, 0 - not on DST) */
+} jerry_time_zone_t;
+
+/**
+ * Get timezone and daylight saving data
+ *
+ * @return true  - if success
+ *         false - otherwise
+ */
+bool jerry_port_get_time_zone (jerry_time_zone_t *);
+
+/**
+ * Get system time
+ *
+ * @return milliseconds since Unix epoch
+ */
+double jerry_port_get_current_time (void);
+```
+
+# How to port JerryScript
+
+This section describes a basic port implementation which was created for Unix based systems.
+
+## Termination
+
+```c
+#include <stdlib.h>
+#include "jerry-port.h"
+
+/**
+ * Default implementation of jerry_port_fatal.
+ */
+void jerry_port_fatal (jerry_fatal_code_t code)
+{
+  exit (code);
+} /* jerry_port_fatal */
+```
+
+## I/O
+
+```c
+#include <stdarg.h>
+#include "jerry-port.h"
+
+/**
+ * Provide console message implementation for the engine.
+ */
+void
+jerry_port_console (const char *format, /**< format string */
+                    ...) /**< parameters */
+{
+  va_list args;
+  va_start (args, format);
+  vfprintf (stdout, format, args);
+  va_end (args);
+} /* jerry_port_console */
+
+/**
+ * Provide log message implementation for the engine.
+ *
+ * Note:
+ *      This example ignores the log level.
+ */
+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 */
+```
+
+## Date
+
+```c
+#include <sys/time.h>
+#include "jerry-port.h"
+
+/**
+ * Default implementation of jerry_port_get_time_zone.
+ */
+bool jerry_port_get_time_zone (jerry_time_zone_t *tz_p)
+{
+  struct timeval tv;
+  struct timezone tz;
+
+  /* gettimeofday may not fill tz, so zero-initializing */
+  tz.tz_minuteswest = 0;
+  tz.tz_dsttime = 0;
+
+  if (gettimeofday (&tv, &tz) != 0)
+  {
+    return false;
+  }
+
+  tz_p->offset = tz.tz_minuteswest;
+  tz_p->daylight_saving_time = tz.tz_dsttime > 0 ? 1 : 0;
+
+  return true;
+} /* jerry_port_get_time_zone */
+
+/**
+ * Default implementation of jerry_port_get_current_time.
+ */
+double jerry_port_get_current_time ()
+{
+  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 */
+```