Update the webpage and add Port API documentation

JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com
2016-09-01 15:47:24 +02:00
parent 622f42e0a8
commit c19318b057
3 changed files with 230 additions and 9 deletions
@@ -11,19 +11,20 @@ permalink: /getting-started/

 Currently, only Ubuntu 14.04+ is officially supported as primary development environment.

-There are several dependencies, that should be installed manually. The following list is required for building:
+There are several dependencies, that should be installed manually. The following list is the absolute minimum for building:

- `gcc` or any C99-compliant compiler
-  - native
-  - arm-none-eabi
+- `gcc` or any C99-compliant compiler (native or cross, e.g., arm-none-eabi)
 - `cmake` >= `2.8.12.2`
+
+Several scripts and tools help the building and development process, thus it is recommended to have the following installed as well:
+
 - `bash` >= `4.3.11`
 - `cppcheck` >= `1.61`
 - `vera++` >= `1.2.1`
 - `python` >= `2.7.6`

 ```bash
-sudo apt-get install gcc g++ gcc-arm-none-eabi cmake cppcheck vera++ python
+sudo apt-get install gcc gcc-arm-none-eabi cmake cppcheck vera++ python
 ```

 To make our scripts run correctly, several shell utilities should be available on the system:
@@ -248,10 +248,11 @@ Compressed pointers were introduced to save heap space.

 ![Compressed Pointer]({{ site.baseurl }}/img/ecma_compressed.png){: class="thumbnail center-block img-responsive" }

-These pointers are 8 byte aligned 16 bit long pointers which can address 512 Kb of memory which is also the maximum size of the JerryScript heap.
-
-ECMA data elements are allocated in pools (pools are allocated on heap)
-Chunk size of the pool is 8 bytes (reduces fragmentation).
+These pointers are 8 byte aligned 16 bit long pointers which can address 512 Kb of
+memory which is also the maximum size of the JerryScript heap. To support even more
+memory the size of compressed pointers can be extended to 32 bit to cover the entire
+address space of a 32 bit system by passing "--cpointer_32_bit on" to the build
+system. These "uncompressed pointers" increases the memory consumption by around 20%.

 ### Number

@@ -0,0 +1,219 @@
+---
+layout: page
+title: Port API
+permalink: /port-api/
+---
+
+* toc
+{:toc}
+
+# 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 */
+```