Merge pull request #223 from DLTcollab/develop

Pre-release v0.6.0

.travis.yml

@@ -1,5 +1,9 @@
 language: c
 
+arch:
+  - amd64
+  - arm64
+
 os:
   - linux
   - osx

AUTHORS

@@ -7,7 +7,7 @@ dcurl is written by:
 Externel Source:
 * src/pow_sse.c is derived from preliminary work of Shinya Yagyu.
 * src/pow_cl.c and src/pow_kernel.cl are adopted from ccurl [1].
-* src/pow_fpga_accel.c is derived from accelerator by LampaLab [2].
+* src/pow_fpga.c is derived from accelerator by LampaLab [2].
 * src/list.h is adopted from National Cheng Kung University, Taiwan.
 
 [1] https://github.com/iotaledger/ccurl

Doxyfile

@@ -2,7 +2,7 @@
 # Project related configuration options
 #---------------------------------------------------------------------------
 PROJECT_NAME           = "dcurl"
-PROJECT_NUMBER         = 0.5.0
+PROJECT_NUMBER         = 0.6.0
 OUTPUT_DIRECTORY       = docs
 OPTIMIZE_OUTPUT_FOR_C  = YES
 #---------------------------------------------------------------------------

LICENSE

@@ -1,4 +1,4 @@
-Copyright (C) 2018-2019 BiiLabs Co., Ltd. and Contributors.
+Copyright (C) 2018-2020 BiiLabs Co., Ltd. and Contributors.
 Copyright (C) 2018 Ievgen Korokyi.
 Copyright (C) 2017 IOTA AS, IOTA Foundation and Developers.
 Copyright (C) 2016 Shinya Yagyu.

Makefile

@@ -1,4 +1,4 @@
-VERSION = 0.5.0
+VERSION = 0.6.0
 
 OUT ?= ./build
 SRC := src
@@ -22,13 +22,16 @@ endif
 ifneq ("$(BUILD_DEBUG)","0")
     CFLAGS += -Og -g3 -DENABLE_DEBUG
     ifneq ("$(BUILD_DEBUG)","1")
-        include mk/sanitizers.mk
+        include mk/dynamic-analysis.mk
     endif
 else
     # Enable all the valid optimizations for standard programs in release build
     CFLAGS += -O3
 endif
 
+# Static code analysis
+include mk/static-analysis.mk
+
 # Check specific CPU features available on build host
 include mk/cpu-features.mk
 
@@ -72,7 +75,7 @@ include mk/opencl.mk
 endif
 
 ifeq ("$(BUILD_FPGA_ACCEL)","1")
-CFLAGS += -DENABLE_FPGA_ACCEL
+CFLAGS += -DENABLE_FPGA
 endif
 
 ifeq ("$(BUILD_REMOTE)","1")
@@ -137,17 +140,17 @@ endif
 
 ifeq ("$(BUILD_JNI)","1")
 OBJS += \
-	jni/iri-pearldiver-exlib.o
+	jni/iri_pearldiver_exlib.o
 endif
 
 ifeq ("$(BUILD_COMPAT)", "1")
 OBJS += \
-	compat-ccurl.o
+	compat_ccurl.o
 endif
 
 ifeq ("$(BUILD_FPGA_ACCEL)","1")
 OBJS += \
-	pow_fpga_accel.o
+	pow_fpga.o
 endif
 
 ifeq ("$(BUILD_REMOTE)", "1")
@@ -157,7 +160,7 @@ OBJS += \
 
 WORKER_EXCLUDE_OBJS := remote_interface.o
 ifeq ("$(BUILD_JNI)", "1")
-WORKER_EXCLUDE_OBJS += jni/iri-pearldiver-exlib.o
+WORKER_EXCLUDE_OBJS += jni/iri_pearldiver_exlib.o
 endif
 WORKER_OBJS := $(addprefix $(OUT)/worker-,$(filter-out $(WORKER_EXCLUDE_OBJS), $(OBJS)))
 WORKER_CFLAGS := $(filter-out -DENABLE_REMOTE, $(CFLAGS))

README.md

@@ -16,13 +16,43 @@ IOTA Reference Implementation (IRI) adaptation is available to benefit from hard
 ## Build Instructions
 Check [docs/build-n-test.md](docs/build-n-test.md) for details.
 
+## Source Code Naming Convention
+Check [docs/naming-convention.md](docs/naming-convention.md) for details.
+
 ## Performance
-After integrating dcurl into IRI, performance of [attachToTangle](https://iota.readme.io/reference#attachtotangle) is measured as following.
-* Each sampling is measured with 30 transaction trytes and total 200 samples are measured.
-* mwm = 14, 26 CPU threads to find nonce
-* Settings: enable 2 pow tasks in CPU, 1 pow tasks in GPU at the same time
+After integrating dcurl into IRI, performance of [attachToTangle](https://docs.iota.org/docs/node-software/0.1/iri/references/api-reference#attachtotangle) is measured as the following.
+
+* Setting: MWM = 14, 200 attachToTangle API requests with each containing 2 transactions
+* Local CPU:
+  * AMD Ryzen Threadripper 2990WX 32-Core Processor 
+  * 2 PoW tasks at the same time
+  * Each task uses 32 CPU threads to find nonce
+  * SIMD enabled
+* Remote worker:
+  * The board with Intel/Altera Cyclone V SoC
+  * 1 PoW task at the same time in a board
+  * FPGA acceleration enabled
+  * Connected with local network
+
 ![](https://raw.githubusercontent.com/DLTcollab/dcurl/develop/docs/benchmark.png)
 
+### Conclusion
+
+Except the original IRI, the other instances use the [DLTcollab/IRI](https://github.com/DLTcollab/iri) instead of [iotaledger/IRI](https://github.com/iotaledger/iri).
+
+| IRI version | attachToTangle API behavior | Effect |
+|:-|:-|:-|
+| IOTA IRI | One transaction bundle at the same time **(Synchronized)** | Transactions of a bundle are calculated one by one |
+| DLTCollab IRI | Multiple transaction bundles at the same time | Transactions of different bundles compete for the PoW calculation resources |
+
+The original IRI should be the slowest one since it does not contain any PoW acceleration.
+However, the graph is different from the expectation.
+This is caused by 2 factors:
+* The graph shows the execution time of each API request instead of the overall throughput.
+* The table shows that there are competition of the PoW resources, which means the execution time would be longer than expected.
+
+And from the graph we can see that 4 remote workers would be a good choice to accelerate PoW.
+
 ## IRI Adaptation
 [Modified IRI accepting external PoW Library](https://github.com/DLTcollab/iri)
 Supported IRI version: 1.7.0

cppcheck_suppress

@@ -0,0 +1,2 @@
+// Do not treat system header files missing as errors
+missingIncludeSystem:*

docs/board-de10-nano.md

@@ -25,7 +25,7 @@ Change the FPGA configuration mode switch as shown in the image\
 <img src="https://forum.uvm.io/uploads/default/original/1X/e09be635519a0af23ad88baed8ef99d06941eca4.png" width="600">
 
 
-## Connect with the De10-Nano board
+## Connect with the DE10-Nano board
 ### Hardware
 Please make sure the following list are well set or connected:
 - 5V DC Power Jack
@@ -92,6 +92,23 @@ $ sudo minicom
 ```
 Then enter the user account and the password to login.
 
+### MAC address setting (optional)
+For monitoring or using [Ansible Playbooks](https://docs.ansible.com/ansible/latest/user_guide/playbooks.html) on remote workers,
+the IP address of them should be fixed.
+The router can assign the IP address by detecting the hardware MAC address.
+However, each time the **DE10-Nano** board is rebooted, the MAC address would be different.
+
+The steps to set the MAC address:
+- Open the file `/etc/network/interfaces`
+- Add the following text
+  ```
+  auto eth0
+  iface eth0 inet dhcp
+  hwaddress ether xx:xx:xx:xx:xx:xx
+  ```
+  xx:xx:xx:xx:xx:xx is the assigned MAC address
+- Reboot
+
 
 ## Build and execute the remote worker
 ### Load the driver

docs/build-n-test.md

@@ -132,6 +132,11 @@ Success.
         [ Verified ] 
 ```
 
+## Static Code Analysis
+```
+$ make static-analysis
+```
+
 ## Tweaks
 * Number of threads to find nonce in CPU
     * ```$ export DCURL_NUM_CPU=26```

docs/naming-convention.md

@@ -0,0 +1,27 @@
+# Naming Convention
+
+dcurl uses the **[snake case](https://en.wikipedia.org/wiki/Snake_case)** naming convention.
+
+- Variable and function
+  ```
+  bool pow_c(void *pow_ctx) {
+      ......
+      int completed_index = -1; 
+      ......
+  }
+  ```
+
+- Structure: The suffixes **_s** represents for structure and **_t** represents for type
+  ```
+  typedef struct pwork_s pwork_t;
+  struct pwork_s {
+      ......
+  }
+  ```
+
+- Macro: Use capital letters
+  ```
+  #define MIN_TRYTE_VALUE (-13)
+  #define MAX_TRYTE_VALUE 13
+  ```
+

docs/remote-interface.md

@@ -77,3 +77,17 @@ $ make BUILD_REMOTE=1 BUILD_DEBUG=1 check
 
 ## Requirements
 Remote interface requires RabbitMQ broker
+
+## Fallback mechanism
+If the remote interface is not working for some reason, the PoW calculation will be transferred to the local hardwares.
+The possible situations are:
+
+* Initialization failure:
+The remote interface is not initialized successfully because the RabbitMQ broker it not activated.
+dcurl would record the initialization status of the remote interface.
+If it does not succeed, dcurl would use local hardwares to do the PoW.
+
+* Runtime failure:
+The remote interface is initialized successfully but the remote workers do not exist or the RabbitMQ broker is closed after initialization.
+dcurl would wait 10 seconds for the responding.
+If nothing returns, dcurl would use local hardwares to do the PoW.