📝 update documentation

Author: csrohit

dma/.gitignore

@@ -1,4 +1,13 @@
+# build files
 build
+
+# vscode files
+settings.json
+.cortex-debug*
+
+# draw.io files
 *.bkp
 *.dtmp
+
+# mac files
 .DS_Store

dma/.vscode/settings.json

@@ -2,5 +2,12 @@
     "files.associations": {
         "time.h": "c",
         "timer.h": "c"
-    }
+    },
+    "makefile.launchConfigurations": [
+        {
+            "cwd": "/Users/csrohit/code/blue-pill/uart/dma/build",
+            "binaryPath": "/Users/csrohit/code/blue-pill/uart/dma/build/dma-usart.elf",
+            "binaryArgs": []
+        }
+    ]
 }

dma/Makefile

@@ -10,14 +10,14 @@ FLOAT_ABI	= soft
 
 # compiler option
 OPT			:= -Os
-CSTD		?= c11
-CXXSTD		:= c++17
+CSTD		?= gnu11
+CXXSTD		:= gnu++17
 
 # Project specific configuration
 BUILD_DIR 	:= build
 BUILD_TYPE	?= Debug
 SRC_DIR 	:= src
-INC_DIRS	= include
+INC_DIRS	:= include
 
 
 PREFIX		?= arm-none-eabi
@@ -35,80 +35,103 @@ GDB			:= $(PREFIX)-gdb
 SRCS 		:= $(shell find $(SRC_DIR) -name '*.cpp' -or -name '*.c')	
 OBJS 		:= $(addsuffix .o,$(basename $(SRCS)))			# replace .c with .o
 OBJS 		:= $(addprefix $(BUILD_DIR)/,$(OBJS))			# replace .c with .o
-
+ASMS 		:= $(addsuffix .s,$(basename $(OBJS)))
 
 # Define stm32 family macro
-DEFS		+= -D$(MCU_FAMILY)
+DEFS		+=-D$(MCU_FAMILY)
 
 # header library include flsgs
-INC_FLAGS 	= $(addprefix -I,$(INC_DIRS))
+INC_FLAGS 	=$(addprefix -I,$(INC_DIRS))
 
 
 # Target-specific flags
-CPU_FLAGS	?= -mfloat-abi=$(FLOAT_ABI) -m$(INSTR_SET) -mcpu=$(CPU)
-
-CPPFLAGS	?=$(DEFS) $(INC_FLAGS)
-CFLAGS		?=$(CPU_FLAGS)
-CXXFLAGS 	:=$(CFLAGS) -fno-exceptions -fno-rtti
-LDFLAGS		?=$(CPU_FLAGS)
+CPU_FLAGS	?=-mfloat-abi=$(FLOAT_ABI) -m$(INSTR_SET) -mcpu=$(CPU)
+CPPFLAGS	?=$(DEFS) $(INC_FLAGS) -MMD
 
+# optiomization level according to build type
 ifeq ($(BUILD_TYPE), Debug)
 CFLAGS 		+= -g -gdwarf-2
+CXXFLAGS 	+= -g -gdwarf-2
+LDFLAGS 	+= -g -gdwarf-2
 else
 CFLAGS		+= $(OPT)
+CXXFLAGS	+= $(OPT)
+ASFLAGS		+= $(OPT)
 endif
 
 # Do not link stdlib with executable
 CFLAGS		+= -nostdlib -fno-tree-loop-distribute-patterns -fdata-sections -ffunction-sections
-CXXFLAGS	+= -nostdlib -fno-tree-loop-distribute-patterns -fdata-sections -ffunction-sections
+CXXFLAGS	+= -nostdlib -fno-tree-loop-distribute-patterns -fdata-sections -ffunction-sections -fno-exceptions -fno-rtti
 LDFLAGS		+= -nostdlib 
 
 
 # Warning options for C and CXX compiler
 CFLAGS		+= -Wall -Wextra -Wundef -Wshadow -Wredundant-decls -Wmissing-prototypes -Wstrict-prototypes
 CXXFLAGS	+= -Wall -Wextra -Wundef -Wshadow -Wredundant-decls -Weffc++ -Werror
 
-
+# Linker options
 LDFLAGS		+= -T $(LDSCRIPT)
 LDFLAGS		+= -Wl,-Map=$(basename $@).map,--gc-sections,-cref,--print-memory-usage
 
-all: size bin
-size: $(BUILD_DIR)/$(TARGET).size
-elf: $(BUILD_DIR)/$(TARGET).elf
-bin: $(BUILD_DIR)/$(TARGET).bin
-hex: $(BUILD_DIR)/$(TARGET).hex
-srec: $(BUILD_DIR)/$(TARGET).srec
-list: $(BUILD_DIR)/$(TARGET).list
+all		: size bin
+size	: $(BUILD_DIR)/$(TARGET).size
+elf		: $(BUILD_DIR)/$(TARGET).elf
+bin		: $(BUILD_DIR)/$(TARGET).bin
+hex		: $(BUILD_DIR)/$(TARGET).hex
+srec	: $(BUILD_DIR)/$(TARGET).srec
+list	: $(BUILD_DIR)/$(TARGET).list
+asm		: $(ASMS)
+
+# binary file to flash on target
+%.bin: %.elf
+	@echo "COPY " $< " => " $@
+	@$(OBJCOPY) -Obinary $(*).elf $(*).bin
+
+# executable object files for debugging
+%.hex: %.elf
+	$(OBJCOPY) -Oihex $(*).elf $(*).hex
+
+%.srec: %.elf
+	$(OBJCOPY) -Osrec $(*).elf $(*).srec
 
+%.list: %.elf
+	$(OBJDUMP) -S $(*).elf > $(*).list
 
 %.size: %.elf
+	@echo "Section wise usage: "
 	@$(SIZE) $<
 
-%.bin: %.elf
-	@echo "COPY " $< " => " $@
-	@$(OBJCOPY) -Obinary $(*).elf $(*).bin
+# Build assembly files
+$(BUILD_DIR)/%.s:%.c
+	@mkdir -p $(dir $@)
+	@echo "AS" $< " ==> " $@
+	@$(CC) $(CPU_FLAGS) $(CPPFLAGS) $(CFLAGS) -o $@ -S $<
 
+$(BUILD_DIR)/%.s:%.cpp
+	@mkdir -p $(dir $@)
+	@echo "AS" $< " ==> " $@
+	@$(CXX) $(CPU_FLAGS) $(CPPFLAGS) $(CXXFLAGS) -o $@ -S $<
+
+# Object files
 $(BUILD_DIR)/%.o:%.c
 	@mkdir -p $(dir $@)
 	@echo "CC" $< " ==> " $@
-	$(CC) $(CPPFLAGS) $(CFLAGS) -o $@ -c $<
+	@$(CC) $(CPU_FLAGS) $(CPPFLAGS) $(CFLAGS) -o $@ -c $<
 
 $(BUILD_DIR)/%.o:%.cpp
 	@mkdir -p $(dir $@)
 	@echo "CXX" $< " ==> " $@
-	$(CXX) $(CPPFLAGS) $(CXXFLAGS) -o $@ -c $<
-	
+	@$(CXX) $(CPU_FLAGS) $(CPPFLAGS) $(CXXFLAGS) -o $@ -c $<
+
+# final executable object file
 $(BUILD_DIR)/$(TARGET).elf: $(OBJS)
 	@echo "Linking sources into "$@
-	@$(CC) $(LDFLAGS) -o $@ $^
-
+	@$(CC) $(CPU_FLAGS) $(LDFLAGS) -o $@ $^
 
+# upload binary to stm32
 flash: bin
 	st-flash write $(BUILD_DIR)/$(TARGET).bin 0x8000000
-	
-debug: CFLAGS 		+= -g -gdwarf-2
-debug: CXXFLAGS 	+= -g -gdwarf-2
-debug: all
 
+# remove generated files 
 clean:
 	rm -rf build

dma/README.md

@@ -1,37 +1,66 @@
-# USART communication using DMA
+# USART communication using DMA in Circular mode
 
-A boilerplate for generating projects for stm32 blue pill board using makefile. The projects does not use any tools provided by ST Microelectronics.
-Everything from development, flashing to debugging can be done in Visual Studio Code only.
+Communication between PC and STM32 using USART and DMA peripherals.
 
-![Build Passing](https://img.shields.io/badge/build-passing-brightgreen) [![GPLv3 License](https://img.shields.io/badge/License-GPL%20v3-yellow.svg)](https://opensource.org/licenses/)
+Transmit data using USART1 and DMA in continuous mode without interruption of CPU. This project does not require any IDE like CubeIde, any text editor will work including notepad, vim. For better debugging experience, VSCode is preferred.
 
+![Build Passing](https://img.shields.io/badge/build-passing-brightgreen) [![GPLv3 License](https://img.shields.io/badge/License-GPL%20v3-yellow.svg)](https://opensource.org/licenses/)
 
 ## Dependencies
 
 * make
     Make utility is required for configuring and building this project. You can install make on linux by running command:
 
     ```bash
+    # for debian based linux distros
     sudo apt install build-essential
+
+    # for macos
+    xcode-select --install
+    
+    # for macos using brew formulae
+    brew install make
     ```
 
 * gcc-arm-none-eabi toolchain
     ARM cross-platform toolchain is required to build applications for arm mcus. Toolchain can be installed by running following command:
 
     ```bash
+    # for debian based linux distros
     sudo apt install gcc-arm-none-eabi
+
+    # for macos
+    brew install --cask gcc-arm-embedded
     ```
 
 * openocd
     It is an Open On Circuit Debugging tool used to flash and debug arm micro controllers. You can install openocd on linux by running command:
 
    ```bash
+   # for debian based linux distros
    sudo apt install openocd -y
+
+    # for macos
+    brew install openocd
    ```
 
+* stlink-tools
+    This program is required for uploading binaries to the STM32 boards. You can install stlink tools  by running the command:
+
+    ```bash
+    # for debian based linux distros
+    sudo apt install stlink-tools   
+
+    # for macos
+    brew install stlink
+    ```
+
 * Cortex Debug extension
-x`
+This extension for VSCode is helpful for debugging the application on Blue Pill. The contents of registers as well as memory are visible in the context menu. Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter.
 
+```bash
+ext install marus25.cortex-debug
+```
 
 ## Project Structure
 
@@ -40,68 +69,68 @@ x`
 
 ### Source file description
 
-* `STM32F103C8TX_FLASH.ld`  - linker script
-* `src\main.c` - application code
-* `src\startup_stm32f103c8tx.s` - assembly startup script for blue pill board
-* `system_stm32f1xx.c` - clock configuration and system initialization functions
+* `stm32f1.ld`  - linker script for stm32f103
+* `src/main.c` - main application code
+* `src/startup_stm32f1.c` - boot sequence for arm cortex-m3 processors
+* `src/system_stm32f1xx.c` - clock configuration and system initialization functions
 
 ## Run Locally
 
-Running the project is super easy. Just clone, build, and flash.
-
-### Clone the project
+Running the project is super easy. Just clone, build, and flash. Clone this project using **Code** button above.
 
-1. Using https
-
-    ```bash
-    git clone https://github.com/csrohit/bluepill-template-project.git
-    cd bluepill-template-project
-    ```
-
-2. Using ssh
-
-    ```bash
-    git clone git@github.com:csrohit/bluepill-template-project.git
-    cd bluepill-template-project
-    ```
-## Configuration
+### Configuration
 
 All the configuration required for building this project is given below.
 
 1. Build output directory
     In `Makefile`, output directory can be configured using variable `BUILD_DIR`.
 
 2. Build type
-    In `Makefile`, build type can be configured using variable`DEBUG`. Possible values are `Debug` and `Release`.
+    In `Makefile`, build type can be configured using variable`BUILD_TYPE`. Possible values are `Debug` and `Release`.
 
 3. Binary name
-    In `CMakeLists.txt`, output binary name can be configured using `project(<binary-name>)` macro.
-    ** update above info in `.vscode/launch.json` as well for debugging to work.
+    In `Makefile`, output binary name can be configured using `TARGET` variable.
+    ** update the target name in the `executable` property `.vscode/launch.json` for the debugger to work.
 
-## Build
+### Build
 
 Run following command in terminal to generate flashable binaries for blue pill board. Build files will be written to **Build Output Directory** as configured.
 
 ```bash
-make all
+make
 ```
 
 ## Flash
 
 1. Connect Stlink to PC and blue pill board using swd headers.
-2. Put blue pill board in programming mode.
+2. Put blue pill board in programming mode *(optional)*.
+    The *Boot0* jumper is set to *0*, set it to *1* and reset the device.
 3. Run following to flash board with binary.
 
 ```bash
 make flash
 ```
 
+4. Done.
+
+## Hardware Setup
+
+Connect the board with host through USB to TTL converter (FTDI board in our case). The connections are described as follows.
+
+| Pin on Blue Pill  | Pin on FTDI  |
+|------------------ |------------- |
+| PA9               | Rx           |
+| PA10              | Tx           |
+| Gnd               | Gnd          |
+
+![Connection diagram for USART1](../docs/label.png "Pin connection diagram for usart1")
+
 ## Output
 
-Onboard led connected to Pin C13 can be observed to be blinking after 500ms.
+"Hello world" messages are visible on the terminal arriving continuously dues to circular mode of operation as seen below.
+![Serial prompt at 115200 baudrate](docs/out_115200_circ.png "Output on terminal")
 
 ## Debug
 
 Click in `Run and Debug` option in VsCode sidebar. Then launch `Cortex Debug` target.
 
-Happy debugging....

dma/src/startup_stm32f1.c

@@ -177,21 +177,19 @@ void Default_Handler(void)
 void Reset_Handler(void)
 {
   // copy .data section to SRAM
-  uint8_t *pSramData = (uint8_t *)&_sdata;    // sram
-  uint8_t *pFlashData = (uint8_t *)&_la_data; // flash
-  uint32_t data_size = (uint32_t)&_edata - (uint32_t)&_sdata;
-  for (uint32_t i = 0; i < data_size; i++)
+  uint32_t *start_sram = (uint32_t *)&_sdata;
+  uint32_t *start_flash = (uint32_t *)&_la_data;
+  while (start_sram < (uint32_t *)&_edata)
   {
-    *pSramData++ = *pFlashData++;
+    *start_sram++ = *start_flash++;
   }
 
-  // init. the .bss section to zero in SRAM
-  uint32_t bss_size = (uint32_t)&_ebss - (uint32_t)&_sbss;
-  uint8_t *pBssData = (uint8_t *)&_sbss;
-  for (uint32_t i = 0; i < bss_size; i++)
+  uint32_t *start_bss = (uint32_t *)&_sbss;
+  while (start_bss < (uint32_t *)&_ebss)
   {
-    *pBssData++ = 0;
+    *start_bss++ = 0;
   }
+  
   SystemCoreClockUpdate();
   // now invoke main
   main();