View source for Arm Cortex-M Assembly

=== <br />Introduction ===
There are a large number of processors out there that are based on the various processor architectures designed by [https://arm.com ARM Ltd.]. The capabilities of these processor vary greatly. Nevertheless ARM designed the instruction sets for its processor architectures so that the instruction sets of the more capable processors build on the instruction set of the simpler processors. A programmer can thus transfer most of the knowledge of programming for one type of ARM processor to programming another type of ARM processor.
<br />
<br />
I will be using the GNU variant of assembler directives that are used alongside ARM instructions to create a complete program. Please refer to the [https://sourceware.org/binutils/docs/as/index.html GNU Assembler user manual] for detailed information on the assembler directives shown here.
<br />
<br />
=== Registers ===
In ARM, there are 16 32-bit registers available. These are
{|
! #
! name
! use
! note
|-
| 1 || R0 || General Purpose || The return code of a function is read from this register.
|-
| 2 || R1 || General Purpose ||
|-
| 3 || R2 || General Purpose ||
|-
| 4 || R3 || General Purpose ||
|-
| 5 || R4 || General Purpose ||
|-
| 6 || R5 || General Purpose ||
|-
| 7 || R6 || General Purpose ||
|-
| 8 || R7 || General Purpose ||
|-
| 9 || R8 || General Purpose ||
|-
| 10 || R9 || General Purpose ||
|-
| 11 || R10 || General Purpose ||
|-
| 12 || R11 || General Purpose ||
|-
| 13 || R12 || General Purpose ||
|-
| 14 || SP || Stack Pointer ||
|-
| 15 || LR || Link Register || stores the return address from subroutines and interrupt service routines
|-
| 16 || PC || Program Counter || contains the start address of the current instruction
|}
<br />
=== Thumb ===
The classic ARM instruction set is a RISC instruction set with a fixed length of 32-bit. To achieve better code density, which is especially important in the Cortex-M series processors that are designed for use as microcontrollers, a 16-bit instruction set called ''Thumb'', containing the most frequently used ARM instructions, was created. Thumb was later extended to the hybrid 16-bit/32-bit ''Thumb-2'' instruction set in order to achieve good code density while also offering feature-rich 32-bit instructions.
<br />
<br />
* [http://infocenter.arm.com/help/topic/com.arm.doc.qrc0001m/QRC0001_UAL.pdf ARM and Thumb-2 Instruction Set Quick Reference Card]
<br />
Keep in mind that in Thumb (not Thumb-2) registers R8 through R12 are not available. While the ARM instruction set uses 32-bit numbers with a clever [https://alisdair.mcdiarmid.org/arm-immediate-value-encoding/ 12-bit-encoding scheme] for its immediate values, Thumb uses plain 8-bit binary encoding for immediate values. Therefore, you can't use numbers larger than 255 as immediate value. Instead, you keep your 32-bit number in a memory pool close to the code and load the number into a register via PC-relative addressing as shown below.
<br />
<pre class="code">
ldr  r1,[pc,#0x9]
... // 8 instructions in between
large_num: .word 0x8410033a
</pre>
You can also use the "=" prefix that instructs the GNU assembler to automatically insert a memory pool from which LDR loads the specified value:
<pre class="code">
ldr  r1,=0x8410033a // automatically create a memory pool for storing '0x8410033a'
... // a few instructions
bx // jump somewhere
.pool // insert the memory pool here, close to the ldr instruction 
</pre>
<br />
=== GNU Assembler ===
==== In-code Directives ====
The following table lists frequently used GNU Assembler directives. The complete list can be found at the official documentation pages for [https://sourceware.org/binutils/docs/as/Pseudo-Ops.html device-independent directives] plus [https://sourceware.org/binutils/docs/as/ARM-Directives.html ARM directives].
<br />
{|
! Syntax
! Description
|-
| .syntax unified || Use modern assembler syntax + auto-generate IT instructions. Place this at the top of your source file.
|-
| .weak <label>{,<label>} || Allow 'label' to be undefined. If it's undefined, it will have the value NULL (0x00000000).
|-
| .weakref <label>,<default label> || Allow ''label'' to be undefined. If it's undefined, it will have the value of another label.
|-
| .section <section name> || All output from now on goes into a new section with the given name. Sections are labelled chunks of code or data and are processed by the linker.
|-
| .align <num zero bits> [,<pattern> [,<max skipped bytes>]] || Pad the output up to the first address that has the given number of low-order zero bits. ([https://sourceware.org/binutils/docs/as/Align.html#Align external documentation])
|-
| .balign <num bytes> [,<pattern> [,<max skipped bytes>]]  || Pad the output up to the first address that is a multiple of the given number of bytes.  ([https://sourceware.org/binutils/docs/as/Balign.html#Balign external documentation])
|-
| .long <value> || output a 32-bit value
|-
| .text || Specifies that subsequent lines contain program code (same as '.section .text')
|-
| .data || Specifies that subsequent lines contain data, no code.
|-
| .global <label> || Makes the symbol with the given label visible to the linker. That is, "exports'' the symbol. Also used to mark external symbols (defined in another compile unit).
|-
| .func <label> [, <actual label>] || Mark the beginning of function 'label', so the linker may exclude the block if not referenced.
|-
| .endfunc || Marks the end of a function.
|-
| .size <label>,<size> || Tells the linker how long (in bytes) the block is that this symbol points to.
|-
| .thumb || Specifies that the Thumb instruction set is being used. Use this with ''.syntax unified''.
|-
| .thumb_func <label> || Marks the given entry point as a function with Thumb instructions. Thumb is required if the function is called by using 'bx' or 'blx'.
|-
| .type <label>,%<type> || Specifies the type of the symbol. Required if there is a pointer to the function somewhere.
|-
| .cpu <CPU type> || The CPU type can be, for example, ''cortex-m0'', ''cortex-m3'' or ''cortex-m4''.
|-
| .zero <num bytes> || Denotes a block of memory of given size and initialized to zeros everywhere.
|-
| .fill < num of bytes>{, <value>{, <value_size>}} || Denotes a block of memory of given size and initialzed to the given value of the given size value (1, 2, or 4 for byte, half word, or word, respectively).
|-
| .pool, .ltorg || Instructs the assembler to dump the current contents of the literal pool (=constants) to be dumped into the current ''.text'' section at the location where this directive is inserted (aligned to a word boundary).
|}
<br />

==== Sections ====
The table below lists the most important or frequently encountered sections that the assembler (or GCC) writes into the binary image.
{|
! Section Name
! Description
|-
| .data || Global, static variables are stored here. The C variable declaration "static int i;", for example, will cause an entry in this section.
|-
| .rodata || Read-only, global static variables are stored here. The C code line "static const int i = 8;" will cause an entry in this section.
|-
| .text || This section contains executable machine code.
|-
| .comment || GCC writes information about the compiler into this section. For example, "GCC: (Raspbian4.9.2-10) 4.9.2"
|-
| .ARM.attributes || Contains information about the generated ARM code. For example whether it is [https://en.wikipedia.org/wiki/Application_binary_interface#Embedded_ABIs EABI] compliant.
|}
<br />
===== Debug Sections =====
These sections are generated when calling ''as'' or ''gcc'' with the "-g" option.
{|
! Section Name
! Description
|-
| .debug_info || 
|-
| .debug_abbrev || 
|-
| .debug_aranges || 
|-
| .debug_line || 
|-
| .debug_str || 
|-
| .debug_frame || 
|}
<br />

=== Inline Assembly ===
Occasionally, there is need for embedding assembly code inside of C/C++ code. This is referred to as ''inline'' assembly. Assuming that you are using the GCC toolchain, refer to the [https://gcc.gnu.org/onlinedocs/gcc/Using-Assembly-Language-with-C.html GCC manual for embedding assembly in C]. An additional online resource is the [http://www.ethernut.de/en/documents/arm-inline-asm.html ARM GCC Inline Assembler Cookbook] by Harald Kipp.
<br />
<br />
=== Disassembling Binaries ===
Use the ''objdump'' tool (part of GNU Binutils) to view the machine code of an object file in assembly: 
<pre class="terminal">
objdump -d <executable file name>
</pre>
<br />

=== Online Tutorials ===
There is [http://infocenter.arm.com ARM's official documentation site] and many tutorials about ARM assembly pogramming by third parties. For example, the [http://thinkingeek.com/arm-assembler-raspberry-pi/ tutorial series on the ''Think In Geek'' website] about ARM assembly programming on Raspberry Pi, written by Roger Ferrer Ibáñez. I also liked the [http://www.davespace.co.uk/arm/introduction-to-arm/ Introduction to ARM] written by David Thomas although it's more reference than tutorial.
<br />
<br />
There are also many nice video tutorials out there. For example, [https://youtu.be/dUWf1d9En04?list=PLZbTfKPloQ_X4Tu0ffeysIovycvQNBW7u this video tutorial series by Youtube user Arat192] for the Raspberry Pi 1 with ARM11 processor, or the [https://youtu.be/ViNnfoE56V8?list=PLGLfVvz_LVvQu9IwUcpn8KOZsOvoHx8sU video tutorial series by Derek Banas] for assembly programming on the same model Raspberry Pi.
<br />
<br />

=== Example Code ===
The following two assembly programs are based on code from the video tutorials mentioned above and are written for the GNU toolchain and ARMv7-A processor.
<br />
<br />
==== Example 1 ====
This simple program performs a bitwise logical operation.
<pre class="code">
.global _start  // _start is the expected entry symbol for a standalone assembly program
_start:
  mov r1, #5          // loads binary 0101
  mov r2, #9          // loads binary 1001
  //and r0, r1, r2    // bitwise AND
  //orr r0, r1, r2    // bitwise OR
  //eor r0, r1, r2    // bitwise XOR
  bic r0, r1, r2      // bitwise clear. Returns 0 except when bit in r1 is 1 and bit in r2 is 0

end:
  mov r7, #1          // selects system call for exiting to terminal
  swi 0               // executes system call via interrupt 
</pre>
Assuming that the above code is saved to the file ''example1.s'', you create the executable via
<pre class="terminal">
as -o example1.o example1.s
ld -o example1 example1.o
</pre>
then run the executable and check the return value, which is the value in r0, by entering
<pre class="terminal">
./example1; echo $?
</pre>
where ''echo $?'' prints the return value of the last executed terminal command.
<br />
<br />
==== Example 2 ====
This program prints the uppercase character corresponding to the input lowercase character.
<pre class="code">
.global main
.func main
main:                 // 'main' is the expected entry point for an executable that links to a library
  mov r7, #3          // sets system call "read from input stream"
  mov r0, #0          // selects the keyboard as input stream
  mov r2, #1          // sets number of characters to read from stream
  ldr r1, =character  // set the address where the character will be stored
  swi 0               // executes the system call

_uppercase:
  ldr r1, =character
  ldr r0, [r1]
// for example,
// a : 0110 0001
// A : 0100 0001
// Bit #6 (= 0x0010 0000 = 32) determines whether an ASCII letter is lowercase or uppercase.
  bic r0, r0, #32     // converts to uppercase
  str r0, [r1]        // stores the result in the memory location pointed at by r1
  b _write_via_printf

_write_to_device:
  mov r7, #4          //  system call for printing output
  mov r0, #1          //  selects the monitor as output device
  mov r2, #1          //  outputs only one character
  ldr r1, =character  // loads the character to be printed
  swi 0

.extern printf
_write_via_printf:
  ldr r0, =out_format
  ldr r1, [r1]
  bl printf          // Don't forget to link against libc. Use 'gcc' or add '-lc' when using 'ld'.

//.endfunc           // use GNU Assembler directive to mark the end of the function

end:
  //mov pc, lr       // alternatively, return from function call by setting the program counter
  mov r7, #1         // instead, we exit the program altogether via system call 
  swi 0              // executing the system call

.data
character:
  .ascii " "         // a single ASCII character is stored in this memory location
out_format:
  .asciz "%c\n"      // a null-terminated ASCII string, compatible with printf, is stored here
</pre>
Note that ''main'' is used instead of ''_start'' as the entry point due to use of ''printf'' and, therefore, linkage with libc via ''gcc''. Assuming that the above code is saved to the file ''example2.s'', you create the executable via
<pre class="terminal">
as -o example2.o example2.s
gcc -Wl,-s -o example2 example2.o
</pre>
where ''gcc'' will automatically link to libc and generate the code for the ''_start'' entry point, which will be calling the function ''main''.
<br />
<br />
==== Example 3: Working With Floating Points ====
In this example, the floating point unit (FPU) is used for calculation. The FPU on ARM Cortex-A processors is called VFP (Vector Foating Point). The most useful instructions in the VFP instruction set are listed on [http://infocenter.arm.com/help/topic/com.arm.doc.qrc0007e/QRC0007_VFP.pdf this quick reference card].
<pre class="code">
</pre>
Since the FPU is an optional component inn the ARM architecture, the presence of an FPU is passed to the assembler as a command line argument. 
<pre class="terminal">
as -mfpu=vfpv4 -o example.o example.s
</pre>
Raspberry Pi 2 (BCM2836 processor) supports VFP version 3 while Raspberry Pi 3 (BCM2837 processor) supports VFP version 4.
If you don't enable support for VFP, the assembler will emit the following error message:
<pre class="terminal">
selected processor does not support ARM mode `vmrs r4,fpsid'
</pre>
<br />
<br />

=== Debugging ===
In order to debug an executable, the executable needs to contain debug symbols. Use the ''-g'' option of the GNU Assembler to generate object files with debug symbols. The debugger, ''gdb'', will load the symbols automatically. Use the GDB command ''disassemble'' to view the assembly instructions for a given function as reconstructed from machine code. The addresses of the memory locations in which the instructions are stored are also shown. An example debug session on a Raspberry Pi is shown below.
<br />
<pre class="terminal">
pi@raspberrypi:~/asm_test $ as -g -o test8.o test8.s
pi@raspberrypi:~/asm_test $ ld -o test8 test8.o
pi@raspberrypi:~/asm_test $ gdb test8
GNU gdb (Raspbian 7.7.1+dfsg-5+rpi1) 7.7.1
Copyright (C) 2014 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
and "show warranty" for details.
This GDB was configured as "arm-linux-gnueabihf".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
<http://www.gnu.org/software/gdb/documentation/>.
For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from test8...done.
(gdb) list
1	// looping
2	// r0 = 0
3	// r1 = 1
4	// while (r0 <= 10)
5	//   r0 = r0 + 1
6	
7	.global _start
8	_start:
9	  mov r0, #0
10	  mov r1, #1
(gdb) disassemble _start
Dump of assembler code for function _start:
   0x00010054 <+0>:	mov	r0, #0
   0x00010058 <+4>:	mov	r1, #1
   0x0001005c <+8>:	b	0x10064 <_continue_loop>
End of assembler dump.
</pre>
<br />
You can set a breakpoint before running the executable in the breakpoint. Execution will stop at the breakpoint where you can inspect the register values with the command ''info r''.
<pre class="terminal">
(gdb) b 13
Breakpoint 1 at 0x10060: file test8.s, line 13.
(gdb) run
Starting program: /home/pi/asm_test/test8 

Breakpoint 1, _loop () at test8.s:14
14	  add r0, r0, r1
(gdb) info r
r0             0x0	0
r1             0x1	1
r2             0x0	0
r3             0x0	0
r4             0x0	0
r5             0x0	0
r6             0x0	0
r7             0x0	0
r8             0x0	0
r9             0x0	0
r10            0x0	0
r11            0x0	0
r12            0x0	0
sp             0x7efff6b0	0x7efff6b0
lr             0x0	0
pc             0x10060	0x10060 <_loop>
cpsr           0x80000010	-2147483632
</pre>
<br />
To inspect a region in memory type ''x'' followed by a forward slash, followed by the number of memory locations, whitespace, followed by the label or address of the start location. If the number is omitted only the value at the memory location with the given label is displayed. Typing only ''x'' will show the 4 memory locations following the last shown location.
<pre class="terminal">
(gdb) x/4 info
0x10078 <info>:	10	65656	4929	1634033920
(gdb) x 0x10078
0x10078:                0x0000000a
(gdb) x info
0x10078 <info>:         0x0000000a
(gdb) x
0x1007c <info+4>:	0x00010078
</pre>
<br />
To inspect the contents of a memory location referenced by a register, type "''x $<register name>''" like this:
<pre class="terminal">
(gdb) x $sp
0x7efff6a8:	0x00000002
</pre>
<br />