tools/docs/devs/Optimization-Tips.md

   1 Optimization Tips
   2 =================
   3
   4 ## Tracing JerryScript heap usage
   5
   6 Adding below arguments when building and running IoT.js will show you the JerryScript memory status.
   7
   8 ```text
   9 $ ./tools/build.py --jerry-memstat
  10 $ ./build/bin/iotjs test.js --memstat
  11 Heap stats:
  12   Heap size = 262136 bytes
  13   Allocated = 0 bytes
  14   Waste = 0 bytes
  15   Peak allocated = 24288 bytes
  16   Peak waste = 261 bytes
  17   Skip-ahead ratio = 2.6059
  18   Average alloc iteration = 1.1284
  19   Average free iteration = 19.3718
  20
  21 Pools stats:
  22   Pool chunks: 0
  23   Peak pool chunks: 735
  24   Free chunks: 0
  25   Pool reuse ratio: 0.3459
  26 ```
  27
  28 Note that currently only JerryScript heap usage can be shown with memstat option, not IoT.js memory usage. You can use system profiler to trace IoT.js memory usage.
  29
  30 ## JerryScript 'external magic string' feature
  31
  32 When parsing and executing JavaScript module, JavaScript strings occupy a huge amount of space in JerryScript heap. To optimize this kind of heap usage, JerryScript has 'external magic string' feature. If you enable snapshot when building, build script will automatically generate `src/iotjs_string_ext.inl.h` file, which includes all of the JavaScript strings used in builtin modules. This file is used by JerryScript to reduce heap usage.
  33
  34 Since same strings will be included only once, you can use this information to get some hints on binary size reduction. Note that only strings with length<32 will be included in this list.
  35
  36 ## Placement of JerryScript heap (with an example of STM32F4 CCM Memory)
  37
  38 IoT.js uses two kind of heaps: System heap for normal usage, and separated JerryScript heap for javascript. JerryScript heap is implemented as c array with fixed length decided in static time. Its size can be ~512K.
  39
  40 For some devices, placing this kind of large memory block can be important issue. For example, STM32F4 chips have *Core Coupled Memory* (a.k.a. *ccm* memory), which is usually used as heap or stack. However, since compiler do not have any special knowledge about JerryScript heap, it can be treated as simple array.
  41
  42 You can make your compiler to place the JerryScript heap in specific section by using `--jerry-heap-section` argument when building IoT.js. Your argument will be used with below code in `deps/jerry/jerry-core/jcontext/jcontext.c`
  43
  44 ```c
  45 #define JERRY_GLOBAL_HEAP_SECTION __attribute__ ((section (JERRY_HEAP_SECTION_ATTR)))
  46
  47 jmem_heap_t jerry_global_heap __attribute__ ((aligned (JMEM_ALIGNMENT))) JERRY_GLOBAL_HEAP_SECTION;
  48 ```