Book: Review Outline

[jamesmunns]

Update

We revised the outline during the meeting held on 2018-07-16 and came up with the following sections:

• Introduction - Book: Section 1: Introduction (draft) #116
  • covers setup
  • what #[no_std] means: no I/O (filesystems), allocation, etc.
• Blinking Your First LED - Book: Section 2: Blinking your first LED (draft) #117
  • use cortex-m-rt
  • emphasis on zero cost abstractions: high level vs unsafe manual way (same disassembly)
• "Static guarantees" - Book: Section 3A: Static Guarantees (draft) #118
  • static configuration, use svd2rust for the example
• Portability - Book: Section 3B: Portability #119
  • examples: embedded-hal + drivers
• The singleton pattern (*)
  • examples: static configuration, memory pools
• Concurrency - Book section: Concurrency (draft) #124
  • examples: static+interrupts, RTFM
• Dynamic data structures - Book section: Dynamic data structures (draft) #125
  • fixed capacity collections: heapless
  • heap allocated collections: #[global_allocator], #[alloc_error]
• Tips for embedded C developers - Book section: Tips for embedded C / C++ developers #126
  • e.g. iterators instead of for loop + indexing
• Interop - Integration with C codebases #48
  • Binding a C SDK, Rust program on top (a little C with your Rust)
  • Exposing Rust code to a C program (a little Rust with your C)

We will probably reorder the sections in the future but we were content with the selection of topics.

(*) I see quite a bit of overlap between singletons and the "static guarantess" and "dynamic data structures" sections. It may be best to write those two first and the decide whether we want a standalone section on singletons (I think a standalone section would end up being too short and / or may not properly showcase its usefulness without applying it to something like configuration or memory management).

---

This issue is for decisions on the layout or outline of the book contents.

The outline can be seen as markdown, or rendered. Also check out the book tag on issues.

We will open new issues for managing chapters and sections of the book.

Current Section Outline:

1. Introduction - Issue
2. Blinking Your First LED - Issue
3. Embedded-HAL Ecosystem
   • 3A: Static Guarantees - Issue
   • 3B: Portability - Issue
4. Tock-OS Ecosystem - (No Tracking Issue)
5. Interoperability - (No Tracking Issue)
6. Testing - (No Tracking Issue)
7. Unsorted - (No Tracking Issue)

[jamesmunns]

@thejpster proposed moving Sections 7.1-7.4 into a new section (how to think in embedded rust), to be placed after section 2.

[jamesmunns]

@japaric proposed splitting up Section 3 (embedded-hal) into two Sections, one covering Portablility, and one covering Static Guarantees

Edit: This was agreed in the meeting on 2018-07-09. For now I have split these up as 3A and 3B until we update the outline.

[japaric]

Tock-OS Ecosystem

Are Tock userland apps working on stable? The books should only contain stuff that works on stable.

I propose we add a section on concurrency briefly talking about Send and Sync (which are well covered in the Rust book) and then go over the concurrency systems / pattetrns that exists: bare metal (static + interrupt handlers), Real Time For the Masses (tasks, message passing) and, if stable, Tock (multiprocess and cooperative within a process).

[thejpster]

Will this be updated with the revised layout as discussed at the WG meeting, or is that tracked elsewhere?

[ryankurte]

@jamesmunns there was some discussion in #56 and from there #112 about building Running and Debugging into a good tool-independent resource (which I definitely support), and in which case I would suggest it could be a separate section?

[japaric]

@thejpster the issue description has bee updated with the revised outline.

@ryankurte

the embedded book is aimed at people familiar with embedded development. IME running and debugging Rust programs doesn't look much different from running and debugging C programs -- the same tooling is used, the format is the same (ELF or binary) -- so I'm not sure if such section should be in the embedded book (i.e. it could live elsewhere). It also seems more efficient (less work) to point to existing resources (e.g. Discovery for OpenOCD + GDB, C resources for other tools) and just cover Rust specific stuff: the compiler produces ELF files and places them in target/$TARGET/$binary; use objcopy to get a binary file out of that; Rust symbols look like foo::bar::$function::$hash; and so on.

Of course if someone commits to writing documentation for every combination of flashing / debugging tool out there then we would be happy to publish such documentation somewhere.

[thejpster]

LGTM

[kjetilkjeka]

I've already mentioned bobbin-cli in other issues. This tool is unique to rust, integrated well with existing tools and makes debugging and running rust programs a much more pleasant experience than c. I think this tool should be mentioned in the book. It do not need its own section and csn be included into "Introduction" or "Blinking Your First LED"

[jamesmunns]

Hey all, I've started implementing this new outline in #133. I would appreciate any review.

If you think any of my old notes should be preserved in the new outline, please feel free to let me know.

[jamesmunns]

I've written up my plan for getting the book shipped this year. TL;DR, I am going to commit to shipping one chapter every two weeks until the end of the year.

If anyone has time to contribute, review, or expand on anything towards the book. It would be very welcome. Hopefully I should be much more active on this issue over the next 18 weeks :)

[andre-richter]

Whoa that's an ambitious plan. Let's see if we can keep you motivated :). I'll try to help with some review work whenever I can in my abundance of free time... 😕

[jamesmunns]

Yeah, We'll see how far I get! I signed up for this a while back, and life happened. Hopefully after RustConf (in about two weeks), I'll be able to commit more of my "free" cycles. I don't think two weeks is enough to make each chapter a master work, but hopefully enough to ship our first version of the book, and functional enough for people new to working in embedded rust.

I definitely think I would benefit from any additional help, but I wanted to put my commitment out there, hoping other people would benefit from seeing my schedule.

#133 is up for review if you have any cycles now :)

[japaric]

@jamesmunns awesome! I'll be assigning all the book issues to you then. I will try to submit some braindumps for memory management, singletons and concurrency this week.

[japaric]

Oh and we should move out the book ASAP to have a dedicated issue tracker.

[japaric]

And that means migrating the book issues in this issue tracker to the other one. (I don't know how to do that :-).

[japaric]

This issue was moved to rust-embedded/book#2