LLDB -> GDB; +setup instructions for Windows and mac; -cargo-edit

this commit:

- changes the debugger to GDB since Windows and macOS users reported errors with
LLDB

- adds setup instructions for Windows and macOS

- drops the cargo-edit dependency since it's used only once and lets us simplify
  the setup instructions

- adds a note regarding .cargo/config being required in section 3 since some
  people missed it while reading section 2

- removes a note about llvm-objdump not working correctly since the problem was
  fixed in cargo-binutils v0.1.4

closes #8
closes #7

Author: japaric

ci/exceptions/app/app.objdump

@@ -0,0 +1,113 @@
+
+app:	file format ELF32-arm-little
+
+Disassembly of section .text:
+main:
+      40:	trap
+      42:	trap
+
+Reset:
+      44:	movw	r1, #0x0
+      48:	movw	r0, #0x0
+      4c:	movt	r1, #0x2000
+      50:	movt	r0, #0x2000
+      54:	subs	r1, r1, r0
+      56:	bl	#0xd2
+      5a:	movw	r1, #0x0
+      5e:	movw	r0, #0x0
+      62:	movt	r1, #0x2000
+      66:	movt	r0, #0x2000
+      6a:	subs	r2, r1, r0
+      6c:	movw	r1, #0x0
+      70:	movt	r1, #0x0
+      74:	bl	#0x8
+      78:	bl	#-0x3c
+      7c:	trap
+
+DefaultExceptionHandler:
+      7e:	b	#-0x4 <DefaultExceptionHandler>
+
+UsageFault:
+      7f:	sub	sp, #0x19c
+
+__aeabi_memcpy:
+      80:	push	{r4, r5, r7, lr}
+      82:	cbz	r2, #0x56
+      84:	subs	r3, r2, #0x1
+      86:	and	r12, r2, #0x3
+      8a:	cmp	r3, #0x3
+      8c:	bhs	#0x8 <__aeabi_memcpy+0x18>
+      8e:	movs	r2, #0x0
+      90:	cmp.w	r12, #0x0
+      94:	bne	#0x26 <__aeabi_memcpy+0x3e>
+      96:	b	#0x42 <__aeabi_memcpy+0x5c>
+      98:	sub.w	lr, r2, r12
+      9c:	movs	r2, #0x0
+      9e:	ldrb	r3, [r1, r2]
+      a0:	adds	r4, r1, r2
+      a2:	strb	r3, [r0, r2]
+      a4:	adds	r3, r0, r2
+      a6:	adds	r2, #0x4
+      a8:	ldrb	r5, [r4, #0x1]
+      aa:	cmp	lr, r2
+      ac:	strb	r5, [r3, #0x1]
+      ae:	ldrb	r5, [r4, #0x2]
+      b0:	strb	r5, [r3, #0x2]
+      b2:	ldrb	r4, [r4, #0x3]
+      b4:	strb	r4, [r3, #0x3]
+      b6:	bne	#-0x1c <__aeabi_memcpy+0x1e>
+      b8:	cmp.w	r12, #0x0
+      bc:	beq	#0x1c <__aeabi_memcpy+0x5c>
+      be:	ldrb	r3, [r1, r2]
+      c0:	cmp.w	r12, #0x1
+      c4:	strb	r3, [r0, r2]
+      c6:	beq	#0x12 <__aeabi_memcpy+0x5c>
+      c8:	adds	r3, r2, #0x1
+      ca:	cmp.w	r12, #0x2
+      ce:	ldrb	r5, [r1, r3]
+      d0:	strb	r5, [r0, r3]
+      d2:	it	eq
+      d4:	popeq	{r4, r5, r7, pc}
+      d6:	adds	r2, #0x2
+      d8:	ldrb	r1, [r1, r2]
+      da:	strb	r1, [r0, r2]
+      dc:	pop	{r4, r5, r7, pc}
+
+__aeabi_memset:
+      de:	cmp	r1, #0x0
+      e0:	it	eq
+      e2:	bxeq	lr
+      e4:	push	{r7, lr}
+      e6:	subs	r3, r1, #0x1
+      e8:	and	r12, r1, #0x3
+      ec:	cmp	r3, #0x3
+      ee:	bhs	#0x2 <__aeabi_memset+0x16>
+      f0:	movs	r1, #0x0
+      f2:	b	#0x14 <__aeabi_memset+0x2c>
+      f4:	sub.w	lr, r1, r12
+      f8:	movs	r1, #0x0
+      fa:	strb	r2, [r0, r1]
+      fc:	adds	r3, r0, r1
+      fe:	adds	r1, #0x4
+     100:	cmp	lr, r1
+     102:	strb	r2, [r3, #0x1]
+     104:	strb	r2, [r3, #0x2]
+     106:	strb	r2, [r3, #0x3]
+     108:	bne	#-0x12 <__aeabi_memset+0x1c>
+     10a:	cmp.w	r12, #0x0
+     10e:	pop.w	{r7, lr}
+     112:	itt	ne
+     114:	strbne	r2, [r0, r1]
+     116:	cmpne.w	r12, #0x1
+     11a:	bne	#0x0 <__aeabi_memset+0x40>
+     11c:	bx	lr
+     11e:	add	r0, r1
+     120:	cmp.w	r12, #0x2
+     124:	strb	r2, [r0, #0x1]
+     126:	it	ne
+     128:	strbne	r2, [r0, #0x2]
+     12a:	bx	lr
+
+__aeabi_memclr:
+     12c:	movs	r2, #0x0
+     12e:	b.w	#-0x54 <__aeabi_memset>

ci/script.sh

@@ -79,6 +79,8 @@ main() {
 
     # check that the disassembly matches
     pushd app
+    diff app.objdump \
+         <(cargo objdump --bin app --release -- -d -no-show-raw-insn -print-imm-hex)
     diff app.vector_table.objdump \
          <(cargo objdump --bin app --release -- -s -j .vector_table)
     edition_check

src/exceptions.md

@@ -117,57 +117,39 @@ application:
 ```
 
 ``` console
-(lldb) b DefaultExceptionHandler
-Breakpoint 1: where = app`DefaultExceptionHandler at lib.rs:95, address = 0x000000ec
+(gdb) target remote :3333
+Remote debugging using :3333
+Reset () at ../rt/src/lib.rs:7
+7       pub unsafe extern "C" fn Reset() -> ! {
 
-(lldb) continue
-Process 1 resuming
-Process 1 stopped
-* thread #1, stop reason = breakpoint 1.1
-    frame #0: 0x000000ec app`DefaultExceptionHandler at lib.rs:95
-   92
-   93   #[no_mangle]
-   94   pub extern "C" fn DefaultExceptionHandler() {
--> 95       loop {}
-   96   }
+(gdb) b DefaultExceptionHandler
+Breakpoint 1 at 0xec: file ../rt/src/lib.rs, line 95.
+
+(gdb) continue
+Continuing.
+
+Breakpoint 1, DefaultExceptionHandler ()
+    at ../rt/src/lib.rs:95
+95          loop {}
+
+(gdb) list
+90          Vector { handler: SysTick },
+91      ];
+92
+93      #[no_mangle]
+94      pub extern "C" fn DefaultExceptionHandler() {
+95          loop {}
+96      }
 ```
 
 And for completeness, here's the disassembly of the optimized version of the program:
 
 ``` console
-$ cargo objdump --bin app --release -- -d
+$ cargo objdump --bin app --release -- -d -no-show-raw-insn -print-imm-hex
 ```
 
-> **NOTE** `llvm-objdump`, which is what `cargo-objdump` invokes, produces
-> broken output for this particular file so the output below is actually the
-> output from `arm-none-eabi-objdump`
-
-
 ``` text
-00000040 <main>:
-  40:   defe            udf     #254    ; 0xfe
-  42:   defe            udf     #254    ; 0xfe
-
-00000044 <Reset>:
-  44:   f240 0100       movw    r1, #0
-  48:   f240 0000       movw    r0, #0
-  4c:   f2c2 0100       movt    r1, #8192       ; 0x2000
-  50:   f2c2 0000       movt    r0, #8192       ; 0x2000
-  54:   1a09            subs    r1, r1, r0
-  56:   f000 f869       bl      12c <__aeabi_memclr>
-  5a:   f240 0100       movw    r1, #0
-  5e:   f240 0000       movw    r0, #0
-  62:   f2c2 0100       movt    r1, #8192       ; 0x2000
-  66:   f2c2 0000       movt    r0, #8192       ; 0x2000
-  6a:   1a0a            subs    r2, r1, r0
-  6c:   f240 1132       movw    r1, #306        ; 0x132
-  70:   f2c0 0100       movt    r1, #0
-  74:   f000 f804       bl      80 <__aeabi_memcpy>
-  78:   f7ff ffe2       bl      40 <main>
-  7c:   defe            udf     #254    ; 0xfe
-
-0000007e <DefaultExceptionHandler>:
-  7e:   e7fe            b.n     7e <DefaultExceptionHandler>
+{{#include ../ci/exceptions/app/app.objdump:1:28}}
 ```
 
 ``` console
@@ -221,18 +203,28 @@ matches the name we used in `EXCEPTIONS`.
 You can test it in QEMU
 
 ``` console
-(lldb) b HardFault
-
-(lldb) continue
-Process 1 resuming
-Process 1 stopped
-* thread #1, stop reason = breakpoint 1.1
-    frame #0: 0x00000044 app`HardFault at main.rs:18
-   15   #[no_mangle]
-   16   pub extern "C" fn HardFault() -> ! {
-   17       // do something interesting here
--> 18       loop {}
-   19   }
+(gdb) target remote :3333
+Remote debugging using :3333
+Reset () at /home/japaric/rust/embedonomicon/ci/exceptions/rt/src/lib.rs:7
+7       pub unsafe extern "C" fn Reset() -> ! {
+
+(gdb) b HardFault
+Breakpoint 1 at 0x44: file src/main.rs, line 18.
+
+(gdb) continue
+Continuing.
+
+Breakpoint 1, HardFault () at src/main.rs:18
+18          loop {}
+
+(gdb) list
+13      }
+14
+15      #[no_mangle]
+16      pub extern "C" fn HardFault() -> ! {
+17          // do something interesting here
+18          loop {}
+19      }
 ```
 
 The program now executes the user defined `HardFault` function instead of the

src/main.md

@@ -67,8 +67,15 @@ $ cargo new --edition 2018 --bin app
 
 $ cd app
 
-$ cargo add rt --path ../rt
+$ # modify Cargo.toml to include the `rt` crate as a dependency
+$ tail -n2 Cargo.toml
+```
 
+``` toml
+{{#include ../ci/main/app/src/Cargo.toml:7:8}}
+```
+
+``` console
 $ # copy over the config file that sets a default target and tweaks the linker invocation
 $ cp -r ../rt/.cargo .
 

src/memory-layout.md

@@ -174,6 +174,9 @@ We have to tweak linker process to make it use our linker script. This is done
 passing the `-C link-arg` flag to `rustc` but there are two ways to do it: you
 can use the `cargo-rustc` subcommand instead of `cargo-build` as shown below:
 
+**IMPORTANT**: Make sure you have the `.cargo/config` file that was added at the
+end of the last section before running this command.
+
 ``` console
 $ cargo rustc -- -C link-arg=-Tlink.x
 ```
@@ -241,51 +244,30 @@ $ qemu-system-arm \
 
 ``` console
 $ # on a different terminal
-$ lldb target/thumbv7m-none-eabi/debug/app
-
-(lldb) gdb-remote 3333
-Process 1 stopped
-* thread #1, stop reason = signal SIGTRAP
-    frame #0: 0x00000008 app`Reset at main.rs:22
-   19
-   20   #[panic_handler]
-   21   fn panic(_panic: &PanicInfo<'_>) -> ! {
--> 22       loop {}
-   23   }
-
-(lldb) # ^ that source is wrong; the processor is about to execute Reset; see below
-(lldb) disassemble -frame
-app`Reset:
-->  0x8 <+0>:  sub    sp, #0x4
-    0xa <+2>:  movs   r0, #0x2a
-    0xc <+4>:  str    r0, [sp]
-    0xe <+6>:  b      0x10                      ; <+8> at main.rs:12
-    0x10 <+8>: b      0x10                      ; <+8> at main.rs:12
-
-(lldb) # the SP has the initial value we programmed in the vector table
-(lldb) print/x $sp
-(unsigned int) $0 = 0x20010000
-
-(lldb) step
-(lldb) step
-(lldb) step
-Process 1 stopped
-* thread #1, stop reason = step in
-    frame #0: 0x0000000e app`Reset at main.rs:13
-   10       let _x = 42;
-   11
-   12       // can't return so we go into an infinite loop here
--> 13       loop {}
-   14   }
-   15
-   16   // The reset vector, a pointer into the reset handler
-
-(lldb) # next we inspect the stack variable `_x`
-(lldb) print _x
-(int) $1 = 42
-
-(lldb) print &_x
-(int *) $2 = 0x2000fffc
-
-(lldb) exit
+$ arm-none-eabi-gdb -q target/thumbv7m-none-eabi/debug/app
+Reading symbols from target/thumbv7m-none-eabi/debug/app...done.
+
+(gdb) target remote :3333
+Remote debugging using :3333
+Reset () at src/main.rs:8
+8       pub unsafe extern "C" fn Reset() -> ! {
+
+(gdb) # the SP has the initial value we programmed in the vector table
+(gdb) print/x $sp
+$1 = 0x20010000
+
+(gdb) step
+9           let _x = 42;
+
+(gdb) step
+12          loop {}
+
+(gdb) # next we inspect the stack variable `_x`
+(gdb) print _x
+$2 = 42
+
+(gdb) print &_x
+$3 = (i32 *) 0x2000fffc
+
+(gdb) quit
 ```