Add documentation to port API

JerryScript-DCO-1.0-Signed-off-by: László Langó llango.u-szeged@partner.samsung.com

Author: LaszloLango

docs/05.PORT-API.md

@@ -0,0 +1,287 @@
+# Reference
+
+## Termination
+
+It is questionable whether a library should be able to terminate an application. However, as of now, we only have the concept of completion code around `jerry_parse` and `jerry_run`. Most of the other API functions have no way of signaling an error. So, we keep 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 the default port implementation which was created for Unix based systems.
+
+## jerry-port-default.h
+
+This header containt the decleration of port specific helper functions for termination and I/O.
+
+```C
+#include "jerry-port.h"
+
+void jerry_port_default_set_abort_on_fail (bool);
+bool jerry_port_default_is_abort_on_fail (void);
+
+jerry_log_level_t jerry_port_default_get_log_level (void);
+void jerry_port_default_set_log_level (jerry_log_level_t);
+```
+
+## Termination
+
+```C
+#include <stdlib.h>
+
+#include "jerry-port.h"
+#include "jerry-port-default.h"
+
+static bool abort_on_fail = false;
+
+/**
+ * Sets whether 'abort' should be called instead of 'exit' upon exiting with
+ * non-zero exit code in the default implementation of jerry_port_fatal.
+ */
+void jerry_port_default_set_abort_on_fail (bool flag) /**< new value of 'abort on fail' flag */
+{
+  abort_on_fail = flag;
+} /* jerry_port_default_set_abort_on_fail */
+
+/**
+ * Check whether 'abort' should be called instead of 'exit' upon exiting with
+ * non-zero exit code in the default implementation of jerry_port_fatal.
+ *
+ * @return true - if 'abort on fail' flag is set,
+ *         false - otherwise.
+ */
+bool jerry_port_default_is_abort_on_fail ()
+{
+  return abort_on_fail;
+} /* jerry_port_default_is_abort_on_fail */
+
+/**
+ * Default implementation of jerry_port_fatal.
+ */
+void jerry_port_fatal (jerry_fatal_code_t code)
+{
+  if (code != 0
+      && code != ERR_OUT_OF_MEMORY
+      && jerry_port_default_is_abort_on_fail ())
+  {
+    abort ();
+  }
+  else
+  {
+    exit (code);
+  }
+} /* jerry_port_fatal */
+```
+
+## I/O
+
+```C
+#include <stdarg.h>
+
+#include "jerry-port.h"
+#include "jerry-port-default.h"
+
+/**
+ * Actual log level
+ */
+static jerry_log_level_t jerry_log_level = JERRY_LOG_LEVEL_ERROR;
+
+/**
+ * Get the log level
+ *
+ * @return current log level
+ */
+jerry_log_level_t
+jerry_port_default_get_log_level (void)
+{
+  return jerry_log_level;
+} /* jerry_port_default_get_log_level */
+
+/**
+ * Set the log level
+ */
+void
+jerry_port_default_set_log_level (jerry_log_level_t level) /**< log level */
+{
+  jerry_log_level = level;
+} /* jerry_port_default_set_log_level */
+
+/**
+ * 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.
+ */
+void
+jerry_port_log (jerry_log_level_t level, /**< log level */
+                const char *format, /**< format string */
+                ...)  /**< parameters */
+{
+  if (level <= jerry_log_level)
+  {
+    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"
+#include "jerry-port-default.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 */
+```