Discourage use of semihosting and mention viable alternatives

Open
#257 10 comments 7 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
45/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
rust
Domain
documentation, embedded-iot

Research direction

Search the book for its semihosting documentation and read the surrounding guidance. Add a prominent warning, a checklist for diagnosing semihosting problems, and explanations of cargo-embed with RTT and serial as alternatives; done means the documentation no longer presents semihosting as the default choice.

Written by the indexing model from the issue text.

Description

Semihosting is a top contender for being the stumble block in embedded so we really should discourage its use with a big fat warning and a checklist what to look out for if a program uses semihosting and doesn't work. At the moment it's described in very peachy terms so people naturally try it, run into problems and then are told on matrix to not use semihosting -- not a great experience.

Instead of semihosting the better approach is to explain cargo-embed and RTT, which is similarly ubiquitous. And as a runner up serial is also a viable and less intrusive option.

Dominant language
No language data
Stars
1.3k
Forks
223
No merged PRs in 30d

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from rust-embedded/book

All issues in rust-embedded/book

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.