Programming, Running and Debugging Book

[japaric]

From @japaric on August 10, 2018 2:43

From @ryankurte on July 5, 2018 22:23

As mentioned here it'd be great to develop Running and Debugging into a useful tool-independent resource.

As far as I see it, we need:

• A common description of how embedded debugging works
  • JTAG
  • SWD
• An intro to embedded debugging
  • GDB for now
  • LLDB one day?
• An overview of available tools (hardware and software) and how to identify them
• An intro to the higher level tools (w/ arbitrary hardware)
  • bobbin-cli by @jcsoo
  • OpenOCD
• A page on the use of each tool for each of
  • JLink hardware + JLink software + GDB,
  • STLink hardware + texane/stlink + GDB,
  • BLackMagic Probe (BMP) hardware + GDB
  • CMSIS-DAP/DapLink

At this stage lldb isn't really viable for embedded debugging, so there's going to be a requirement for target GDB at least for now.

Any thoughts?

(@therealprof, @kjetilkjeka, @korken89)

Copied from original issue: rust-embedded/wg#112

Copied from original issue: rust-embedded/book#10

[japaric]

From @therealprof on July 5, 2018 22:56

@ryankurte LLDB is (was?) not viable for flashing, debugging works okay. But you're right we should probably focus on GDB for now and once we have a proper LLDB workflow (potentially even "batteries included") we could add a chapter/section and swap roles.

Re: Debuggers I think it is important to mention that each debugger (except for BMP) comes with their own flashing tools and/or built-in MSD and also can be used with OpenOCD. I don't think it makes sense to highlight the proprietary software aspects of e.g. JLink and STLink and instead focus on OSS (e.g. OpenOCD or in case of STLink there's also https://github.com/texane/stlink). Hardware wise we should also mention https://github.com/ARMmbed/DAPLink which is a ARM protocol standard and used by a lot of manufacturers (except ST). Also so far we only have SWD covered which is ARM only. We might have to extend that for other proprietary protocols or (shrug) JTAG.

[japaric]

From @ryankurte on July 5, 2018 23:30

Agreed about swapping to LLDB when viable.

Re: Debuggers I think it is important to mention that each debugger (except for BMP) comes with their own flashing tools and/or built-in MSD and also can be used with OpenOCD. I don't think it makes sense to highlight the proprietary software aspects of e.g. JLink and STLink and instead focus on OSS (e.g. OpenOCD or in case of STLink there's also https://github.com/texane/stlink)

I think it's less absolute than that, ime JLink/JLinkExe/GDB is pretty standard in industry and the only approach that works with many of the cores I use, for that example I think the proprietary tools should be highlighted.
texane/stlink is excellent for STLink devices, so for STLink we can talk about that.
I think it's good to describe OpenOCD as an overarching option, but I also don't think it's friendly enough to use by default.

I've updated the top post to reflect these changes, does that cover your concerns?

[japaric]

From @therealprof on July 5, 2018 23:41

Looks good to me.

[japaric]

From @kjetilkjeka on July 6, 2018 7:49

Looks good, just a few comments.

• I think JTAG and SWD will suffice, I'm not convinced any other protocols are common enough to describe them in this text.
• I agree about swapping to LLDB when viable as well.
• I like that bobbin-cli is introduced before OpenOCD. bobbin-cli represents a much lower effort solution but will probably be more than enough to get started.
• Using gdb without tweaking the ui is much harder than it needs to be. Should something like this be mentioned?

[japaric]

From @therealprof on July 6, 2018 8:9

@kjetilkjeka I never managed to get that working properly on my Mac so I'm wary about adding it. Having said that, the 1990s interface of GDB is one the two reasons why I'd really like to see lldb becoming useful for embedded.

[japaric]

From @korken89 on July 6, 2018 8:56

@ryankurte I think this looks good. On GDB vs LLDB, I think it will be gradual transition as LLDB becomes viable. Not loosing functionality is important to the "advanced user", while the beginner often only "wants it to work" - and we need to cater to both when coming to try Rust.

@kjetilkjeka I use GDB dashboard daily, but it has its quirks. If one wants a simple frontend to GDB there is a plethora to choose from, from built in views in Eclipse, VS Code, Atom, etc. to website based GDB frontends. However I do not believe that specific effort should be given to one specific as it is very much up to the user to select ones favorite - but I certainly think a few links to common and popular ones could be a good middle ground.

[japaric]

From @ryankurte on July 7, 2018 5:1

Using gdb without tweaking the ui is much harder than it needs to be. Should something like this be mentioned?

It's nasty to learn but on a whole gdb --tui is a bit friendlier than the plain version IMO. I think we could definitely describe / link out to some options, and some IDE integrations as @korken89 mentioned.

@ryankurte I think this looks good. On GDB vs LLDB, I think it will be gradual transition as LLDB becomes viable. Not loosing functionality is important to the "advanced user", while the beginner often only "wants it to work" - and we need to cater to both when coming to try Rust.

Definitely agreed

[japaric]

Ok, the "New Book" exists now. @rust-embedded/resources, @ryankurte and @korken89 have write access, bors permissions, etc. I have not yet enabled the bors restriction of "one approved review to land" (let me know when I should do that) and I have given this repo a terrible name so please come up with a good one :-).