.. _salbwg:

Assembly Language Blinky README
===============================

Aim
---
This document hopes to show how that Cortex-M0 Assembly Language programming can be fun when used with certain aids.

These aids include:
* GDB-TUI, the GNU Debugger
* SVD2equ include file for memory mapping
* A BlackMagic Pill with a MCU target or a STM32 Discovery 

Target Audience
---------------
Existing knowledge of Cortex-M0, familiarity with the documentation

Mcu
^^^
The Target MCU can be any MCU supported by GDB and in this instance a STM32F051 is used.

Hardware
^^^^^^^^
1. A Black Magic Pill (BMP) to use with an external mcu, please see: <URL>   -OR-
2. Otherwise a STM32F0 Discovery board can be used.

.. note:: different .gdbinit files will be required for either hardware choice above but they are given below.

The Assembly Language Program
-----------------------------
An Assembly Language  program to blink a LED will be used in this example because it's short and provides visual feedback that everything is working.

Hardware Notes
--------------
The LED is connected to GPIOB-8 because the port pin used on the STM32F0 Discovery board isn't available on the external MCU I used in choice 1, above.

If you're using a F0 Disco, just connect a LED to PB-8 to use with the program sourcecode below, or better still, change it to suit the LED on the Discovery Board at PC-8 ? It's much easier than it looks thanks to the use of the svd2forth STM32F0xx-tp1.svd.equates.s file used in a .include directive.

The Blink.s Program
-------------------
This is written in Assembly Language and compiled with arm-none-eabi. 

::

 @ blink.s
 @ Assembly language Blinky example for stm32f051 mcu using a svd2as designed to be more readable,
 @ Board: 'green pill' https://mecrisp-stellaris-folkdoc.sourceforge.io/stm32-boards.html?highlight=green%20pill#why-not-make-your-own-green-pill
 @ led: PB-8 pin 32
 @ Copyright 2020 <terry@tjporter.com.au> Released under BSD License, see COPYING.TXT
 
 .cpu cortex-m0				  @ Tell the assembler what model of Cortex-M this is for
 .thumb					  @ Cortex micros only understand thumb(2) code  
 .text					  @ What follows is code
 .include "gpio-equates.s"		  @ GPIO action labels
 .include "bitposn-equates.s"		  @ A list of ".equ  BIT0, 0x00000001", " etc
 .include "STM32F0xx-tp1.svd.equates.s"	  @ Every register and bitfield equate from Svd2Forth
 .syntax unified			  @ Mse newer style instructions
 .global _start				  @ Make start function global so the linker can see it later
 Vector_Table:	.word     0x20000000	  @ stack pointer value when stack is empty 0x20000000
 ResetVector:    .word     _start + 1	  @ Reset Handler 
  
 					      
 _start: ldr r1, = RCC_AHBENR		  @ AHB Peripheral Clock enable register 0x40021014
 	 ldr r2, = RCC_AHBENR_IOPBEN	  @ I/O port B clock enable
 	 str r2, [r1]
 
 	 ldr r1, = GPIOB_MODER			      @ GPIO port mode register
 	 ldr r2, = OUTPUT << GPIOB_MODER_MODER8	      @ Set PB-8 bit as output
 	 str r2, [r1]
 	 						   
 led_on:			       
 	 ldr r1, = GPIOB_BSRR	       
 	 ldr r2, = GPIOB_BSRR_BS8	  @ PB-8 on
  	 str r2, [r1]
  	 bl delay
 
 led_off:
 	 ldr r1, = GPIOB_BSRR	       	     
  	 ldr r2, = GPIOB_BSRR_BR8	  @ PB-8 off
  	 str r2, [r1]
  	 bl delay
 	 b led_on		       
 
 delay:	 ldr r0, = DELAY
 loop:	 subs r0,r0,#1
 	 bne loop
 end:	 bx lr				  @ return to caller
 
 constants:
  	 .equ DELAY, 0xfffff
 @ 	 .equ DELAY, 0x2		  @ for GDB quick step thru loop
 

Quick Runthru
^^^^^^^^^^^^^






Useful References
-----------------

ARM-ASM-Tutorial
^^^^^^^^^^^^^^^^
By Niklas Gürtler. This is a fantastic Assembly turorial written for the ARMv7-M, Cortex-M3 STM32F103 MCU which is a lot more advanced than the Cortex-M0 I'm using in this tutorial, but all the important parts of the process such as the Linker usage are the same.

https://www.mikrocontroller.net/articles/ARM-ASM-Tutorial

Useful-GDB-commands
^^^^^^^^^^^^^^^^^^^
https://github.com/blacksphere/blackmagic/wiki/Useful-GDB-commands

Debugging with GDB
^^^^^^^^^^^^^^^^^^
https://sourceware.org/gdb/current/onlinedocs/gdb/