eJS -- JavaScript for embedded systems
eJS is a framework to generate JavaScript VMs that are specialised for applications.
Most of the contents are created by eJS project.
- Tomoharu Ugawa (The Univeristy of Tokyo)
- Hideya Iwasaki (The University of Electro-communications)
- Yasunao Takano (Kitasato University)
and students.
Contents
ejsvm
-- eJSVM, JavaScript virtual machine (core)vmdl
-- VMDL compiler to generate specialised type-based dispatcher used in eJSVMvmgen
-- VMgen is the previous version of VM generator. VMDL compiler is the current mainstream.ejsc
-- eJS compiler to compile JavaScript programs into bytecode files executed by eJSVM.ejsi
-- eJS interpreter interface.
Quick Start
Check requirements
Following build tools are required.
- C compiler (GCC or Clang)
- JDK 8 or higher
- make
- Ant
- sed
- Ruby
- Python 3
Following tools are optional.
- Coccinelle
- Oniguruma Regexp library
Prepare external libraries
Download the following libraries into ejsc/libs
if they are not
contained in the repository.
- antlr-4.5.3-complete.jar
- javax.json-1.0.4.jar
Build
- Create build directory
$ mkdir build.debug
$ cd build.debug
- Create
Makefile
from templateejsvm/Makefile.template
$ cp ../ejsvm/Makefile.template Makefile
-
Edit
Makefile
. Thecommands
andpaths
section may need to be changed. -
Build by
make
.
$ make -j
If failed, try to build ejsc and vmgen manually, and then make ejsvm again.
$ make cleanest
$ cd ../ejsc
$ ant
$ cd ../vmgen
$ ant
$ cd ../build
$ make
- Followings are generated.
ejsvm
-- VMejsc.jar
-- compilerejsi
-- Interpreter user interface
execute
Interpreter mode (not recommended)
Simply execute ejsi
in the build directory.
$ ejsi
Compile & run
The following steps demonstrate compilation and execution of a JavaScript
program a.js
. Pathes to ejsc.jar
and ejsvm
should be replaced
appropriately.
- compile to SBC style bytecode
$ java -jar ejsc.jar -O a.js -o a.sbc
- execute
$ ./ejsvm a.sbc
eJS VM
Build option
See comments in Makefile.template
for the details.
-
Genral options
USE_SBC=true/false
: Enable SBC support. (OBC is always supported)
-
Word size options
CFLAGS+=-DBIT_INSN32
: Use 32 bit layout of internal and OBC instructions.CFLAGS+=-DBIT_JSVALUE32
: Use 32 bit layout of JSValue. Pointer size should also be 32bit (-m32
compiler and linker options are required).CFLAGS+=-DBIT_ALIGN32
: Alignment heap objects in 32 bit boundary rather than 64 bit. Handcrafted code does not support this option.
-
GC options
OPT_GC=native
: mark-sweep GC with single free-list allocatorOPT_GC=bibop
: mark-sweep GC with BiBoPOPT_GC=copy
: semispace copy GCOPT_GC=threaded
: Fusuma (based on Jonkers's threaded compaction)
Usage
ejsvm [options] file1 file2 ...
Files are executed in the order of parameter. Files with sbc
extensions are executed as SBC files if ejsvm supprots SBC format.
Other files (and all files for ejsvm without SBC support) are
executed as OBC files.
Options
-
General options
-s size
: stack size in words. (default: 50K)-m size
: heap size in bytes. (default: 1M)
-
Profiling options for eJS users (available when built with
PROFILE
flag)-profile
: Print profiling information.--poutput filename
: Change output file of-profile
tofilename
. (default: standard output)--coverage
: Print coverage inforamtion of instructions with log flags.---icount
: Print execution count of each instruction (count only instructions with log flags).--forcelog
: Do profiling as if all instructions have log flags.
-
Debug options (available when built with
DEBUG
flag)-l
: Print the result of the evaluation of the last expression.-f
: Print function table.-t
: Print execution trace.-a
: Same as the combination of the above (-l -f -t
).
-
Profiling options for VM developers
-u
: Print execution times and summary of GC information.--hc-prof
: Print hidden class graph information. (available when built withHC_PROF
flag)--gc-prof
: Print GC information (available when built withGC_PROF
flag)
-
Other flags
-R
: REPL mode. (not for users)
eJS Compiler
Build option
When building the eJS compiler separately, i.e., building with ant
in the ejsc
directory, the following properties for ant are available.
These properties are specified appropriately when building all components
altogether in the build directory.
specfile
: Path to the default spec file. (default: ''src/ejsc/default.spec'')vmgen
: Path tovmgen.jar
orvmdlc.jar
. (default: ''../ejsvm/vmgen/vmgen.jar'')
Usage
java -jar ejsc.jar [options] source1.js source2.js ...
eJSC compiles JavaScript programs source1.js
, source2.js
, ...
into a single bytecode file. The produced bytecode file executes
source1.js
, source2.js
, ... in this order. If -log
option is
specified before some source files, the immediate following source file
is compiled so that executions of instructions produced from the source
file are logged.
Options
-
output
-o <filename>
: Output tofilename
. (defailt:source1.sbc
)--out-obc
(prefix is double minus): Output OBC (binary) format instead of SBC.--out-insn32
: Emit 32 bit format of instructions (OBC only).--out-align32
: Assume the number of pointer tag bit is 2 rather than 3.--out-bit32
: Same as--out-insn32 --out-align32
-
optimization
-O
: Recommended set of optimizations. (same as--bc-opt const:cce:copy:rie:dce:reg:rie:dce:reg -opt-g3
)--bc-opt <optimizers>
(prefix is double minus): BC based optimizations.<optimizers>
is a series of the following optimizers.const
: Constant propagation and using superinstructionscce
: Common constant loading eliminationcopy
: Copy propagationrie
: Redundant instruction eliminationdce
: Dead code eliminationreg
: Register (re-)assignment
-opt-g3
: Allocate registers for local variables and arguments if possible.
-
misc
--spec <specfile>
: Specify the specfile created asejsvm.spec
in the process of building VM. (default: normal instruction set with no superinstructions)-fn n
: (For REPL) Assume the function number starts fromn
.-log source.js
: Compilesource.js
using logging instructions.
-
debug
--estree
: print ESTree--iast
: print iAST--analyzer
: print result of some AST-based analysis (???)--show-llcode
: print low-level internal code--show-opt
: print details of optimizations