Skip to content

Commit 26842b1

Browse files
rauhulBoisy PitreiCMDdev
authored
Fix documentation drift in SVD2LLDBGuide (#229)
The lldb transcripts and code snippets in this guide had drifted from the tutorial source as it evolved, so readers following along would see paths and line references that no longer match: - Correct the example directory name in the target-create commands (rpi-pico2-lldb -> rpi-pico-lldb) - Refresh stale line numbers across the backtrace, frame-select, and breakpoint transcripts to match the current Application, OnboardLED, MemoryI2CDevice, and I2C sources - Fix invalid Swift in the walkthrough snippets: guard-bind the optional read instead of force-unwrapping, and add the missing let to the ledPin declaration All snippets and line references were verified against the current tutorial sources. --------- Co-authored-by: Boisy Pitre <bpitre@apple.com> Co-authored-by: CMD <80255379+iCMDdev@users.noreply.github.com>
1 parent aa9a1ac commit 26842b1

1 file changed

Lines changed: 106 additions & 84 deletions

File tree

‎Sources/EmbeddedSwift/EmbeddedSwift.docc/Examples/SVD2LLDBGuide.md‎

Lines changed: 106 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -78,10 +78,12 @@ struct Application {
7878
memory.serveBytesFromMemory()
7979

8080
// Controller receives the byte
81-
let readValue = controller.receiveRequestedBytesFromMemory()
81+
guard let readValue = controller.receiveRequestedBytesFromMemory() else {
82+
blinkFailForever(1)
83+
}
8284

8385
// Validate the transmission
84-
if readValue != nil && readValue! == txByte + 1 {
86+
if readValue != nil && readValue == txByte + 1 {
8587
ledSuccess()
8688
} else {
8789
blinkFailForever(2)
@@ -180,8 +182,8 @@ Run lldb with your `Application` Mach-O and connect to your debug server (here y
180182

181183
```shell
182184
$ lldb .build/armv7em-apple-none-macho/debug/Application
183-
(lldb) target create "/Users/cmd/swift-embedded-examples/rpi-pico2-lldb/start-tutorial/.build/armv7em-apple-none-macho/debug/Application"
184-
Current executable set to '/Users/cmd/swift-embedded-examples/rpi-pico2-lldb/start-tutorial/.build/armv7em-apple-none-macho/debug/Application' (armv7em).
185+
(lldb) target create "/Users/cmd/swift-embedded-examples/rpi-pico-lldb/start-tutorial/.build/armv7em-apple-none-macho/debug/Application"
186+
Current executable set to '/Users/cmd/swift-embedded-examples/rpi-pico-lldb/start-tutorial/.build/armv7em-apple-none-macho/debug/Application' (armv7em).
185187
(lldb) gdb-remote 3333
186188
Process 1 stopped
187189
* thread #1, stop reason = signal SIGINT
@@ -192,7 +194,14 @@ Process 1 stopped
192194
-> 92 while (1) {}
193195
93 }
194196
94
195-
95 __attribute((section("__DATA,stack"), aligned(32)))
197+
frame #0: 0x200053fe Application`interrupt at Support.c:97:3
198+
94 }
199+
95
200+
96 void interrupt(void) {
201+
-> 97 while (1) {}
202+
98 }
203+
99
204+
100 __attribute((section("__DATA,stack"), aligned(32)))
196205
Target 0: (Application) stopped.
197206
```
198207
@@ -218,7 +227,14 @@ The `thread sel` command can be used to select the board's core:
218227
-> 92 while (1) {}
219228
93 }
220229
94
221-
95 __attribute((section("__DATA,stack"), aligned(32)))
230+
frame #0: 0x200053fe Application`interrupt at Support.c:97:3
231+
94 }
232+
95
233+
96 void interrupt(void) {
234+
-> 97 while (1) {}
235+
98 }
236+
99
237+
100 __attribute((section("__DATA,stack"), aligned(32)))
222238
(lldb)
223239
```
224240
@@ -241,25 +257,31 @@ Find out where execution stopped by checking the backtrace with `thread backtrac
241257
242258
```shell
243259
* thread #1, stop reason = signal SIGINT
244-
frame #0: 0x200053fe Application`interrupt at Support.c:92:3
260+
frame #0: 0x200053fe Application`interrupt at Support.c:97:3
245261
89 }
246262
90
247263
91 void interrupt(void) {
248264
-> 92 while (1) {}
249-
93 }
265+
94 }
266+
95
267+
96 void interrupt(void) {
268+
-> 97 while (1) {}
269+
98 }
270+
99
271+
100 __attribute((section("__DATA,stack"), aligned(32)))
250272
94
251273
95 __attribute((section("__DATA,stack"), aligned(32)))
252274
(lldb) bt
253275
* thread #1, stop reason = signal SIGINT
254-
* frame #0: 0x200053fe Application`interrupt at Support.c:92:3
276+
* frame #0: 0x200053fe Application`interrupt at Support.c:97:3
255277
frame #1: 0x20000dba Application`Swift._assertionFailure(_: Swift.StaticString, _: Swift.StaticString, file: Swift.StaticString, line: Swift.UInt, flags: Swift.UInt32) -> Swift.Never at <compiler-generated>:0
256278
frame #2: 0x20003c9a Application`generic specialization <RP2350.PADS_BANK0.GPIO, Swift.UInt32> of MMIO.RegisterArray<τ_0_0 where τ_0_0: MMIO.RegisterValue>.subscript.getter : <τ_0_0 where τ_1_0: Swift.BinaryInteger>(τ_1_0) -> MMIO.Register<τ_0_0> at RegisterArray.swift:174:5
257-
frame #3: 0x20003b72 Application`Application.configureLedPinSIO(Swift.UInt32) -> () at OnboardLED.swift:21:18
258-
frame #4: 0x20000968 Application`Application.enableInterfaces() -> () at Application.swift:80:5
259-
frame #5: 0x20000bbc Application`static Application.Application.main() -> () at Application.swift:93:5
279+
frame #3: 0x20003b72 Application`Application.configureLedPinSIO(Swift.UInt32) -> () at OnboardLED.swift:28:18
280+
frame #4: 0x20000968 Application`Application.enableInterfaces() -> () at Application.swift:91:5
281+
frame #5: 0x20000bbc Application`static Application.Application.main() -> () at Application.swift:104:5
260282
frame #6: 0x20000d6c Application`static Application.Application.$main() -> () at <compiler-generated>:0
261283
frame #7: 0x20000d78 Application`Application_main at Application.swift:0
262-
frame #8: 0x200053ee Application`reset at Support.c:87:19
284+
frame #8: 0x200053ee Application`reset at Support.c:92:19
263285
frame #9: 0x000002f4
264286
```
265287
@@ -290,32 +312,32 @@ Find what triggered this issue by looking at the frames related to the Applicati
290312
291313
```shell
292314
(lldb) frame sel 3
293-
frame #3: 0x20003b72 Application`Application.configureLedPinSIO(Swift.UInt32) -> () at OnboardLED.swift:21:18
294-
18 // GPIO config (LED via SIO)
295-
19 func configureLedPinSIO(_ pin: UInt32) {
296-
20 // Pad electrical properties
297-
-> 21 pads_bank0.gpio[pin].modify { rw in
298-
22 rw.raw.od = 0 // outputs enabled
299-
23 rw.raw.ie = 0 // input disabled
300-
24 rw.raw.pue = 0 // no pull-up
315+
frame #3: 0x20003b72 Application`Application.configureLedPinSIO(Swift.UInt32) -> () at OnboardLED.swift:28:18
316+
25 // GPIO config (LED via SIO)
317+
26 func configureLedPinSIO(_ pin: UInt32) {
318+
27 // Pad electrical properties
319+
-> 28 pads_bank0.gpio[pin].modify { rw in
320+
29 rw.raw.od = 0 // outputs enabled
321+
30 rw.raw.ie = 0 // input disabled
322+
31 rw.raw.pue = 0 // no pull-up
301323
(lldb) frame sel 4
302-
frame #4: 0x20000968 Application`Application.enableInterfaces() -> () at Application.swift:80:5
303-
77 while resets.reset_done.read().raw.i2c1 == 0 {}
304-
78
305-
79 // LED pin init
306-
-> 80 configureLedPinSIO(ledPin)
307-
81 ledSet(false)
308-
82
309-
83 // I2C pins config
324+
frame #4: 0x20000968 Application`Application.enableInterfaces() -> () at Application.swift:91:5
325+
88 while resets.reset_done.read().raw.i2c1 == 0 {}
326+
89
327+
90 // LED pin init
328+
-> 91 configureLedPinSIO(ledPin)
329+
92 ledSet(false)
330+
93
331+
94 // I2C pins config
310332
(lldb) frame sel 5
311-
frame #5: 0x20000bbc Application`static Application.Application.main() -> () at Application.swift:93:5
312-
90 @main
313-
91 struct Application {
314-
92 static func main() {
315-
-> 93 enableInterfaces()
316-
94 let controller = I2CController(i2c0SclPin: i2c0SclPin, i2c0SdaPin: i2c0SdaPin)
317-
95 let memory = MemoryI2CDevice(i2c1SclPin: i2c1SclPin, i2c1SdaPin: i2c1SdaPin)
318-
96
333+
frame #5: 0x20000bbc Application`static Application.Application.main() -> () at Application.swift:104:5
334+
101 @main
335+
102 struct Application {
336+
103 static func main() {
337+
-> 104 enableInterfaces()
338+
105 let controller = I2CController(i2c0SclPin: i2c0SclPin, i2c0SdaPin: i2c0SdaPin)
339+
106 let memory = MemoryI2CDevice(i2c1SclPin: i2c1SclPin, i2c1SdaPin: i2c1SdaPin)
340+
107
319341
(lldb)
320342
```
321343
@@ -325,7 +347,7 @@ Searching the codebase for `ledPin`, you can see that it is initialized with `10
325347
326348
```swift
327349
// Board LED
328-
ledPin: UInt32 = 100
350+
let ledPin: UInt32 = 100
329351
```
330352
331353
The Raspberry Pi Pico has only 40 physical pins, including 26 GPIO; `100` is an odd, incorrect choice for the LED pin number.
@@ -343,14 +365,14 @@ Re-connect the board to the computer, while holding `BOOTSEL`, and attach the Op
343365

344366
```shell
345367
$ lldb .build/armv7em-apple-none-macho/debug/Application
346-
(lldb) target create "/Users/cmd/swift-embedded-examples/rpi-pico2-lldb/start-tutorial/.build/armv7em-apple-none-macho/debug/Application"
347-
Current executable set to '/Users/cmd/swift-embedded-examples/rpi-pico2-lldb/start-tutorial/.build/armv7em-apple-none-macho/debug/Application' (armv7em)
368+
(lldb) target create "/Users/cmd/swift-embedded-examples/rpi-pico-lldb/start-tutorial/.build/armv7em-apple-none-macho/debug/Application"
369+
Current executable set to '/Users/cmd/swift-embedded-examples/rpi-pico-lldb/start-tutorial/.build/armv7em-apple-none-macho/debug/Application' (armv7em)
348370
(lldb) breakpoint set --hardware -n main
349371
Breakpoint 1: 2 locations.
350372
(lldb) br list
351373
Current breakpoints:
352374
1: name = 'main', locations = 2, resolved = 2, hit count = 0
353-
1.1: where = Application`static Application.main() + 24 at Application.swift:93:5, address = 0x20000bb8, resolved, hardware, hit count = 0
375+
1.1: where = Application`static Application.main() + 24 at Application.swift:104:5, address = 0x20000bb8, resolved, hardware, hit count = 0
354376
1.2: where = Application`Application_main at Application.swift, address = 0x20000d70, resolved, hardware, hit count = 0
355377
356378
(lldb)
@@ -399,14 +421,14 @@ Target 0: (Application) stopped.
399421
Process 1 resuming
400422
Process 1 stopped
401423
* thread #1, stop reason = breakpoint 1.1
402-
frame #0: 0x20000bb8 Application`static Application.main() at Application.swift:93:5
403-
90 @main
404-
91 struct Application {
405-
92 static func main() {
406-
-> 93 enableInterfaces()
407-
94 let controller = I2CController(i2c0SclPin: i2c0SclPin, i2c0SdaPin: i2c0SdaPin)
408-
95 let memory = MemoryI2CDevice(i2c1SclPin: i2c1SclPin, i2c1SdaPin: i2c1SdaPin)
409-
96
424+
frame #0: 0x20000bb8 Application`static Application.main() at Application.swift:104:5
425+
101 @main
426+
102 struct Application {
427+
103 static func main() {
428+
-> 104 enableInterfaces()
429+
105 let controller = I2CController(i2c0SclPin: i2c0SclPin, i2c0SdaPin: i2c0SdaPin)
430+
106 let memory = MemoryI2CDevice(i2c1SclPin: i2c1SclPin, i2c1SdaPin: i2c1SdaPin)
431+
107
410432
Target 0: (Application) stopped.
411433
(lldb)
412434
```
@@ -436,23 +458,23 @@ note: This address is not associated with a specific line of code. This may be d
436458
* thread #1
437459
* frame #0: 0x20002dce Application`generic specialization <serialized, RP2350.I2C0.IC_STATUS> of MMIO.Register.init(unsafeAddress: Swift.UInt) -> MMIO.Register<τ_0_0> at <compiler-generated>:0
438460
frame #1: 0x200048de Application`RP2350.I2C0.ic_status.getter : MMIO.Register<RP2350.I2C0.IC_STATUS> at @__swiftmacro_6RP23504I2C0V9ic_status13RegisterBlockfMa_.swift:6:15
439-
frame #2: 0x200031dc Application`closure #1 () -> Swift.Bool in Application.MemoryI2CDevice.receiveBytesToMemory() -> () at MemoryI2CDevice.swift:60:18
440-
frame #3: 0x200022ec Application`Application.waitForCondition(() -> Swift.Bool) -> () at I2C.swift:42:8
441-
frame #4: 0x20003194 Application`Application.MemoryI2CDevice.receiveBytesToMemory() -> () at MemoryI2CDevice.swift:59:9
442-
frame #5: 0x20000c18 Application`static Application.Application.main() -> () at Application.swift:108:12
461+
frame #2: 0x200031dc Application`closure #1 () -> Swift.Bool in Application.MemoryI2CDevice.receiveBytesToMemory() -> () at MemoryI2CDevice.swift:71:18
462+
frame #3: 0x200022ec Application`Application.waitForCondition(() -> Swift.Bool) -> () at I2C.swift:51:8
463+
frame #4: 0x20003194 Application`Application.MemoryI2CDevice.receiveBytesToMemory() -> () at MemoryI2CDevice.swift:70:9
464+
frame #5: 0x20000c18 Application`static Application.Application.main() -> () at Application.swift:120:12
443465
frame #6: 0x20000d6c Application`static Application.Application.$main() -> () at <compiler-generated>:0
444466
frame #7: 0x20000d78 Application`Application_main at Application.swift:0
445-
frame #8: 0x200053f6 Application`reset at Support.c:87:19
467+
frame #8: 0x200053f6 Application`reset at Support.c:92:19
446468
frame #9: 0x000002f4
447469
(lldb) frame sel 3
448-
frame #3: 0x200022ec Application`Application.waitForCondition(() -> Swift.Bool) -> () at I2C.swift:42:8
449-
39 @inline(__always)
450-
40 func waitForCondition(_ cond: () -> Bool) {
451-
41 while true {
452-
-> 42 if cond() { return }
453-
43 nop()
454-
44 }
455-
45 }
470+
frame #3: 0x200022ec Application`Application.waitForCondition(() -> Swift.Bool) -> () at I2C.swift:51:8
471+
48 @inline(__always)
472+
49 func waitForCondition(_ cond: () -> Bool) {
473+
50 while true {
474+
-> 51 if cond() { return }
475+
52 nop()
476+
53 }
477+
54 }
456478
```
457479
458480
> Note: This time, when interrupting the program, you may end up stopping at a different place, since the board is continuously looping over some instructions. However, from the third frame 3 onwards, everything should look similar.
@@ -541,13 +563,13 @@ note: This address is not associated with a specific line of code. This may be d
541563
* frame #0: 0x20001b88 Application`generic specialization <Swift.UnsafeMutablePointer<Swift.UInt32>> of Swift.Optional.unsafelyUnwrapped.getter : τ_0_0 at <compiler-generated>:0
542564
frame #1: 0x200019e2 Application`generic specialization <RP2350.I2C0.IC_STATUS> of MMIO.Register.pointer.getter : Swift.UnsafeMutablePointer<τ_0_0.Raw.Storage> at Register.swift:180:43
543565
frame #2: 0x20000ae8 Application`generic specialization <RP2350.I2C0.IC_STATUS> of MMIO.Register.read() -> τ_0_0.Read at Register.swift:216:49
544-
frame #3: 0x200031e0 Application`closure #1 () -> Swift.Bool in Application.MemoryI2CDevice.receiveBytesToMemory() -> () at MemoryI2CDevice.swift:60:28
545-
frame #4: 0x200022ec Application`Application.waitForCondition(() -> Swift.Bool) -> () at I2C.swift:42:8
546-
frame #5: 0x20003194 Application`Application.MemoryI2CDevice.receiveBytesToMemory() -> () at MemoryI2CDevice.swift:59:9
547-
frame #6: 0x20000c18 Application`static Application.Application.main() -> () at Application.swift:108:12
566+
frame #3: 0x200031e0 Application`closure #1 () -> Swift.Bool in Application.MemoryI2CDevice.receiveBytesToMemory() -> () at MemoryI2CDevice.swift:71:28
567+
frame #4: 0x200022ec Application`Application.waitForCondition(() -> Swift.Bool) -> () at I2C.swift:51:8
568+
frame #5: 0x20003194 Application`Application.MemoryI2CDevice.receiveBytesToMemory() -> () at MemoryI2CDevice.swift:70:9
569+
frame #6: 0x20000c18 Application`static Application.Application.main() -> () at Application.swift:120:12
548570
frame #7: 0x20000d6c Application`static Application.Application.$main() -> () at <compiler-generated>:0
549571
frame #8: 0x20000d78 Application`Application_main at Application.swift:0
550-
frame #9: 0x200053f6 Application`reset at Support.c:87:19
572+
frame #9: 0x200053f6 Application`reset at Support.c:92:19
551573
frame #10: 0x000002f4
552574
(lldb) svd load /Users/cmd/Downloads/swift-embedded-examples/Tools/SVDs/rp235x.patched.svd
553575
Loaded SVD file: “rp235x.patched.svd”.
@@ -703,19 +725,19 @@ Set a breakpoint on `configBus` and re-run the app, to see if this write really
703725
704726
```
705727
(lldb) break set --hardware --name MemoryI2CDevice.configBus
706-
Breakpoint 5: where = Application`MemoryI2CDevice.configBus() + 18 at MemoryI2CDevice.swift:44:14, address = 0x20003062
728+
Breakpoint 5: where = Application`MemoryI2CDevice.configBus() + 18 at MemoryI2CDevice.swift:56:14, address = 0x20003062
707729
[rp2350.cm0] external reset detected
708730
[rp2350.cm1] external reset detected
709731
Process 1 stopped
710732
* thread #1, stop reason = breakpoint 5.1
711-
frame #0: 0x20003062 Application`Application.MemoryI2CDevice.configBus() -> () at MemoryI2CDevice.swift:43:14
712-
40 // Configure I2C0 as CONTROLLER
713-
41
714-
42 // Config as peripheral
715-
-> 43 i2c1.ic_con.write { w in
716-
44 w.raw.master_mode = 0
717-
45 w.raw.speed = 1
718-
46 w.raw.ic_restart_en = 1
733+
frame #0: 0x20003062 Application`Application.MemoryI2CDevice.configBus() -> () at MemoryI2CDevice.swift:55:14
734+
52 // Configure I2C0 as CONTROLLER
735+
53
736+
54 // Config as peripheral
737+
-> 55 i2c1.ic_con.write { w in
738+
56 w.raw.master_mode = 0
739+
57 w.raw.speed = 1
740+
58 w.raw.ic_restart_en = 1
719741
(lldb)
720742
```
721743
@@ -734,14 +756,14 @@ Step-over the register write and check if the new values were written:
734756
(lldb) next
735757
Process 1 stopped
736758
* thread #1, stop reason = step over
737-
frame #0: 0x20003080 Application`Application.MemoryI2CDevice.configBus() -> () at MemoryI2CDevice.swift:52:9
738-
48 }
739-
49
740-
50 // Set peripheral address
741-
-> 51 i2c1.ic_sar.write { w in
742-
52 w.storage = address
743-
53 }
744-
54 }
759+
frame #0: 0x20003080 Application`Application.MemoryI2CDevice.configBus() -> () at MemoryI2CDevice.swift:63:9
760+
60 }
761+
61
762+
62 // Set peripheral address
763+
-> 63 i2c1.ic_sar.write { w in
764+
64 w.storage = address
765+
65 }
766+
66 }
745767
Target 0: (Application) stopped.
746768
(lldb) svd read i2c1.ic_con
747769
RP2350:

0 commit comments

Comments
 (0)