dol: initial dol commit

[jump.git] / dol / src / dol / visitor / rtems / lib / README

diff --git a/dol/src/dol/visitor/rtems/lib/README b/dol/src/dol/visitor/rtems/lib/README
new file mode 100644 (file)
index 0000000..e5d0dc0
--- /dev/null
+++ b/dol/src/dol/visitor/rtems/lib/README
@@ -0,0 +1,80 @@
+How-to for running code in MPARM environment:
+
+One-to-one mapping:
+- Generate the code: ant -f runexample -Dnumber=? mparm
+- Copy the generated dir 'systemc' to <MPARM>/MPARM/apps
+- Copy the library 'queue_lib' into dir 'systemc'
+- Compile the code: make
+- Link the binary: ln -sf o-optimize/app.exe TargetMem_<?>.mem
+    ? depends on how many processors
+- Run: $SWARMDIR/bin/mpsim.x -c <?> --intc=i  -C -S -D
+    ? is number of processors
+
+
+Multi-to-one mapping:
+- Modify main.c
+    - number_of_processes: each field is number of processes per processor
+    - xxx_PROCESSOR: set to a same number if mapping to common processor
+    - processor_init(): leave  one for each processor (not necessary)
+- system.c
+    - macro CONFIGURE_MAXIMUM_TASKS should be two times larger than the 
+      maximum number of processes mapped to one processor.
+- MAXQUEUE
+    - where should we put this macro ?
+- If using the dol mapping specification, the processor 1 should be reserved
+  in the case of enabling macro QUEUE_BUFF_SHAPER !
+
+MPARM queue_lib spec:
+- Always use interrupt
+- Always use memcpy
+- DMA always enables, the switch is in the Makefile
+- Token size is always 32 bits
+- Default Queue size is 4, can be redefined
+
+
+Segment wide Calibration:
+- Modify Makefile:
+    - enable macro PERFORMANCE_EXTRACT (default disable)
+    - uncomment line: 
+      CXXSRCS += lib/xmlParser.cpp lib/Performance_Extraction.cpp
+- main.c: Map all processes into one processor
+- Run: $SWARMDIR/bin/mpsim.x -c 1 --intc=i  -C -S -D  
+
+
+Communication exploration:
+- Modify Makefile:
+  - enable one of below macro exclusively:
+    - QUEUE_BUFF_IN_PRODUCER (default)
+    - QUEUE_BUFF_IN_PRODUCER_DMA
+    - QUEUE_BUFF_IN_CONSUMER
+    - QUEUE_BUFF_IN_CONSUMER_DMA
+    - QUEUE_BUFF_SHAPER
+
+Running mpeg2 decoder on MPARM:
+- copy dol.h from other case studies
+- add macro _DOL_ETHZ_GEN_ to Makefile
+- change queue size to 4096 in system.h
+- call mpsim.x with option --s-size=19 (scratchpad size=1Mbyts)
+
+Running mjpeg-2000 decoder on MPARM:
+- jpeg.h
+    - disable macro VIEWER
+    - disable macros VERBOSE and INFO
+- scratch_queue.h
+    - macro MAXQUEUE > 24, if mapping all to one processor
+- system.h
+    - macro CONFIGURE_MAXIMUM_TASKS > 9
+
+
+Tricks:
+- CONFIGURE_MAXIMUM_TASKS in system.h
+- MAXQUEUE in scratch_queue.h 
+- Token size should be multiple of 4 bytes
+- W/R operations should be the same size, otherwise token size should be
+  gcd(Write_token, Read_token).
+
+BUGS & TODO:
+- free() in wrapper not correct
+- Iterated port not tested yet
+- Shaper not finished!
+- Timeslice works?  (Yes)