Add Comments README

It's important to have comments in source also ReadMe for guidance.

Makefile

@@ -1,67 +1,75 @@
-TARGET := capl
-TARGET_TEST	:= test.exe
-CC = i686-w64-mingw32-gcc
-CXX = i686-w64-mingw32-g++
-COMPILER := $(CXX)
-
-SRCS_DIR := src
-BUILD_DIR := build
+# Thanks to Job Vranish (https://spin.atomicobject.com/2016/08/26/makefile-c-projects/)
+TARGET_EXEC := capl
+TEST_EXEC :=test
+
+CC = gcc
+CXX = g++
+BUILD_DIR := ./build
+SRC_DIRS := ./src
+CXXFLAGS := -g
+CFLAGS := -g
+
+
 DATA_DIR := data
 INC_DIR := inc
 RELEASE_DIR := release
 DOC_DIR := doc
+All_DIR := $(SRC_DIRS) $(DATA_DIR) $(INC_DIR) $(RELEASE_DIR) $(DOC_DIR) $(BUILD_DIR)
 
-SHARED := 1
+SHARED ?= 1
 ifeq ($(SHARED),1)
 SHARED_FLAG := -shared
-LINK_FLAG := -L$(BUILD_DIR) -l$(TARGET)
-TARGET := $(addsuffix .dll,$(TARGET))
-else
-TARGET := $(addsuffix .exe,$(TARGET))
+LIB_FLAG := -L$(BUILD_DIR) -l$(TARGET_EXEC)
+TARGET_EXEC := $(addsuffix .dll,$(TARGET_EXEC))
 endif
 
-STATIC := 1
+STATIC ?= 1
 ifeq ($(STATIC),1)
 STATIC_FLAG := -static
 endif
 
-All_DIR := $(SRCS_DIR) $(DATA_DIR) $(INC_DIR) $(RELEASE_DIR) $(DOC_DIR) $(BUILD_DIR)
-
-INC_DIRS := $(patsubst %,-I%,$(shell find $(SRCS_DIR) -type d))
-$(info All inc dirs: $(INC_DIRS))
-
-
-SRCS := $(shell find $(SRCS_DIR) -name '*.c' -or -name '*.cpp' -or -name '*.S')
-$(info All srcs: $(SRCS))
-
+# Find all the C and C++ files we want to compile
+# Note the single quotes around the * expressions. Make will incorrectly expand these otherwise.
+SRCS := $(shell find $(SRC_DIRS) -name '*.cpp' -or -name '*.c' -or -name '*.s')
 HEADERS := $(patsubst $(SRCS_DIR)/%.h,$(INC_DIR)/%.h,$(shell find $(SRCS_DIR) -name '*.h')) 
 
-SRCS_O := $(patsubst $(SRCS_DIR)/%,$(BUILD_DIR)/%.o,$(SRCS))
-$(info All objects: $(SRCS_O))
+# String substitution for every C/C++ file.
+# As an example, hello.cpp turns into ./build/hello.cpp.o
+OBJS := $(SRCS:%=$(BUILD_DIR)/%.o)
 
-# DEPS := $(SRCS_O:.o=.d)
+# String substitution (suffix version without %).
+# As an example, ./build/hello.cpp.o turns into ./build/hello.cpp.d
+DEPS := $(OBJS:.o=.d)
 
-TARGET_O := $(filter-out %/test.c.o,$(SRCS_O))
-$(info All target objects: $(TARGET_O))
+# Every folder in ./src will need to be passed to GCC so that it can find header files
+INC_DIRS := $(shell find $(SRC_DIRS) -type d)
+# Add a prefix to INC_DIRS. So moduleA would become -ImoduleA. GCC understands this -I flag
+INC_FLAGS := $(addprefix -I,$(INC_DIRS))
 
-TARGET_TEST_O := $(filter-out %/main.c.o,$(SRCS_O))
-$(info All target_test objects: $(TARGET_TEST_O))
+# The -MMD and -MP flags together generate Makefiles for us!
+# These files will have .d instead of .o as the output.
+CPPFLAGS := $(INC_FLAGS) -MMD -MP
 
-.default: $(BUILD_DIR)/$(TARGET)
-$(BUILD_DIR)/$(TARGET): $(BUILD_DIR) $(TARGET_O) 
-	$(COMPILER) $(TARGET_O)  -o$@ $(STATIC_FLAG) $(SHARED_FLAG)
+# The final build step.
+$(BUILD_DIR)/$(TARGET_EXEC): $(filter-out %/test.cpp.o,$(OBJS))
+	$(CXX) $(filter-out %/test.cpp.o,$(OBJS)) -o $@ $(LDFLAGS) $(STATIC_FLAG) $(SHARED_FLAG)
 
-$(BUILD_DIR)/$(TARGET_TEST): $(BUILD_DIR) $(TARGET_TEST_O) 
-	$(COMPILER) $(TARGET_TEST_O) -o$@ $(LINK_FLAG)
+$(BUILD_DIR)/$(TEST_EXEC): $(filter-out %/main.cpp.o,$(OBJS))
+	$(CXX) $(filter-out %/main.cpp.o,$(OBJS)) -o $@ $(LDFLAGS) $(LIB_FLAG)
 
-$(BUILD_DIR)/%.o: $(SRCS_DIR)/%
+# Build step for C source
+$(BUILD_DIR)/%.c.o: %.c
 	mkdir -p $(dir $@)
-	$(COMPILER) $^ -o $@ $(INC_DIRS) -c
+	$(CC) $(CPPFLAGS) $(CFLAGS) -c $< -o $@
 
+# Build step for C++ source
+$(BUILD_DIR)/%.cpp.o: %.cpp
+	mkdir -p $(dir $@)
+	$(CXX) $(CPPFLAGS) $(CXXFLAGS) -c $< -o $@
 
 .PHONY: test
-test: $(BUILD_DIR)/$(TARGET_TEST)
-	cd $(DATA_DIR)  && ../$(BUILD_DIR)/$(TARGET_TEST) 
+test: $(BUILD_DIR)/$(TEST_EXEC)
+	cd $(DATA_DIR)  && ../$(BUILD_DIR)/$(TEST_EXEC)
 
 .PHONY: dir
 dir: $(All_DIR)
@@ -76,8 +84,12 @@ $(INC_DIR)/%.h: $(SRCS_DIR)/%.h
 	mkdir -p $(dir $@)
 	cp $^ $@
 
+.PHONY: clean
 clean:
 	rm -rf $(BUILD_DIR)
-	rm -rf $(wildcard $(DATA_DIR)/hex*) $(DATA_DIR)/testlog $(DATA_DIR)/capldlllog
-
-# -include $(DEPS)
+	rm -rf $(wildcard $(DATA_DIR)/hex* $(DATA_DIR)/testlog $(DATA_DIR)/capldlllog)
+
+# Include the .d makefiles. The - at the front suppresses the errors of missing
+# Makefiles. Initially, all the .d files will be missing, and we don't want those
+# errors to show up.
+-include $(DEPS)

README.md

@@ -0,0 +1,94 @@
+<p align="center">
+  <a href="" rel="noopener">
+ <img width=200px height=200px src="https://i.imgur.com/6wj0hh6.jpg" alt="Project logo"></a>
+</p>
+
+<h3 align="center">Bootloader Test CAPL DLL</h3>
+
+<div align="center">
+
+[![Status](https://img.shields.io/badge/status-active-success.svg)]()
+[![GitHub Issues](https://img.shields.io/github/issues/huangdong332/bootloader)](https://github.com/JashonBourne/bootloader/issues)
+[![GitHub Pull Requests](https://img.shields.io/github/issues-pr/huangdong332/bootloader)](https://github.com/kylelobo/The-Documentation-Compendium/pulls)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](/LICENSE)
+
+</div>
+
+---
+
+<p align="center"> A CAPL DLL supporting bootloader test.
+    <br> 
+</p>
+
+## 📝 Table of Contents
+
+- [About](#about)
+- [Getting Started](#getting_started)
+- [Usage](#usage)
+- [Built Using](#built_using)
+
+## 🧐 About <a name = "about"></a>
+
+This is a CAPL DLL project. This CAPL dll can be add to the CAPL environment to extend its functionalty.
+
+There are two functions exported in ths dll.
+
+blOpenFlashFile: Prase the Intel Hex file or Motorola SREC file and calculate checksum of each segment in it. Also extract the start address and size of each segment.
+
+blBuffer: Extract data from specific segment in a HEX or SREC file and compose it to a complete UDS download service PDU.
+
+## 🏁 Getting Started <a name = "getting_started"></a>
+
+These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. 
+
+### Prerequisites
+
+MinGW and Make.
+
+This CAPL dll is built with a MinGW gcc tools for 32bit Windows target. The 64bit CAPL dll can't be recognized by the CAPL browser any way. The compile process is managed by a Makefile.
+
+```
+I use msys64 to install MinGW and Make.
+```
+
+## 🎈 Usage <a name="usage"></a>
+
+To use this CAPL dll in CAPL code, include it in your code first.
+The path should be either the absolute or related to the CAPL code.
+
+```
+includes
+{
+  #pragma library("capl.dll")
+}
+```
+
+After this, APIs in this dll are listed in CAPL Funtions window.
+
+File crcspec
+
+To specify CRC parameters in crcspec, below content should be 
+added in file crcspec and this file should be located in CANoe project's root.
+
+```
+Width 32
+Polynomial 04C11DB7
+InitialValue FFFFFFFF
+InputReflected 1
+ResultReflected 1
+FinalXORvalue FFFFFFFF
+```
+
+## ⛏️ Built Using <a name = "built_using"></a>
+
+After change to this project's root directory, run follow command to build this CAPL dll.
+
+```
+make
+```
+
+To test this build, run
+
+```
+make test
+```

src/capldll.cpp

@@ -30,13 +30,6 @@
 
 #define USECDLL_FEATURE
 #define _BUILDNODELAYERDLL
-// #define MINGW_C
-
-#ifdef MINGW_C
-#define CLINKAGE extern "C"
-#else
-#define CLINKAGE
-#endif
 
 #include "cdll.h"
 #include "VIA.h"
@@ -567,8 +560,18 @@ void CAPLEXPORT CAPLPASCAL appPutDataOnePar(const uint8_t dataBlock[])
 }
 
 // BOOTLOADER SECTION
-
-CLINKAGE int32_t CAPLEXPORT CAPLPASCAL blOpenFlashFile(const char *fileName,
+/*
+Function Name: blOpenFlashFile
+
+Function: Parsing a HEX or SREC file. 
+
+Parameters:
+  fileName:       The path of a HEX or SREC file to be parsed.
+  segmentsCount:  Qauntity of blockes will be saved in this variable.
+  AddressAndSize: Start address and size of each block will be saved in this array.
+  checksum:       Checksum of each block will be saved in this array.
+*/
+int32_t CAPLEXPORT CAPLPASCAL blOpenFlashFile(const char *fileName,
                                               uint32_t *segmentsCount, uint8_t addressAndSize[][8],
                                               uint8_t checksum[][4])
 {
@@ -610,7 +613,21 @@ CLINKAGE int32_t CAPLEXPORT CAPLPASCAL blOpenFlashFile(const char *fileName,
   return 0;
 }
 
-CLINKAGE int32_t CAPLEXPORT CAPLPASCAL blBuffer(uint32_t bufferLength,
+/*
+Function name: blBuffer
+
+Function: Composing whole Transfer Data PDUs i.e. 0x3601xxxx...xxxxx 
+according to the data in each block and fill the transimition buffer
+with those PDUs.
+
+Parameters:
+  bufferLength: Availabel length of the transimition buffer.
+  data:         Transimition buffer. The PDU will be saved in this buffer.
+  dataLength:   Length of a PDU saved in the transimition buffer will
+                be saved in this variable.
+  segment:      Indicate which block will be used for composing PDUs.
+*/
+int32_t CAPLEXPORT CAPLPASCAL blBuffer(uint32_t bufferLength,
 uint8_t *data, uint32_t *dataLength, uint32_t segment)
 {
   static uint8_t blockSequenceCounter = 0x0;
@@ -664,7 +681,16 @@ uint8_t *data, uint32_t *dataLength, uint32_t segment)
   return 0;
 }
 
-CLINKAGE int32_t CAPLEXPORT CAPLPASCAL blFaultInjectionBufferCorruptData(uint32_t bufferLength,
+/**
+ * @brief 
+ * 
+ * @param bufferLength 
+ * @param data 
+ * @param dataLength 
+ * @param segment 
+ * @return int32_t 
+ */
+int32_t CAPLEXPORT CAPLPASCAL blFaultInjectionBufferCorruptData(uint32_t bufferLength,
 uint8_t *data, uint32_t *dataLength, uint32_t segment)
 {
   static uint8_t blockSequenceCounter = 0x01;
@@ -716,6 +742,22 @@ uint8_t *data, uint32_t *dataLength, uint32_t segment)
   return 0;
 }
 
+int32_t CAPLEXPORT CAPLPASCAL blRequest2Array(char * request, uint32_t &requestLength, uint8_t * data)
+{
+  uint32_t strLength;
+  strLength=strlen(request)/2;
+  if(requestLength==0) requestLength=strLength;
+  if(requestLength>4095) requestLength=4095;
+  for(int i=0;i<requestLength;i++)
+  {
+    if(i<strLength)
+    sscanf(request+2*i,"%2x",data+i);
+    else
+    data[i]=i;
+  }
+  return 0;
+}
+
 // ============================================================================
 // CAPL_DLL_INFO_LIST : list of exported functions
 //   The first field is predefined and mustn't be changed!
@@ -744,6 +786,7 @@ CAPL_DLL_INFO4 table[] = {
     {"dllBuffer", (CAPL_FARCALL)blBuffer, "BOOT_LOADER", "This function will fill the data buffer with 0xff", 'L', 4, {'D', 'B', 'D' - 128, 'D'}, "\000\001\000\000", {"bufferLength", "data", "dataLength", "segment"}},
     {"dllFaultInjectionBufferCorruptData", (CAPL_FARCALL)blFaultInjectionBufferCorruptData, "BOOT_LOADER", "This function will fill the data buffer with 0xff", 'L', 4, {'D', 'B', 'D' - 128, 'D'}, "\000\001\000\000", {"bufferLength", "data", "dataLength", "segment"}},
     {"dllOpenFlashFile", (CAPL_FARCALL)blOpenFlashFile, "BOOT_LOADER", "This function will open a SREC file", 'L', 4, {'C', 'D' - 128, 'B', 'B'}, "\001\000\002\002", {"fileName", "segmentsCount", "addressAndSize", "checksum"}},
+    {"dllRequest2Array", (CAPL_FARCALL)blRequest2Array, "BOOT_LOADER", "This function will cast a hex-coded string to an array", 'L', 3, {'C', 'D'-128, 'B'}, "\001\000\001", {"request", "requestLength", "data"}},
 
     {0, 0}};
 CAPLEXPORT CAPL_DLL_INFO4 *caplDllTable4 = table;

src/capldll.h

@@ -13,5 +13,4 @@ int32_t CAPLDLL_API __stdcall blOpenFlashFile(const char *fileName,
                                               uint8_t checksum[][4]);
 int32_t CAPLDLL_API __stdcall blBuffer(uint32_t bufferLength,
 uint8_t *data, uint32_t *dataLength, uint32_t segment);
-
 #endif