New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Book: Review Outline #115

Closed
jamesmunns opened this Issue Jul 10, 2018 · 16 comments

Comments

Projects
None yet
6 participants
@jamesmunns
Member

jamesmunns commented Jul 10, 2018

Update

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

  • Introduction - #116
    • covers setup
    • what #[no_std] means: no I/O (filesystems), allocation, etc.
  • Blinking Your First LED - #117
    • use cortex-m-rt
    • emphasis on zero cost abstractions: high level vs unsafe manual way (same disassembly)
  • "Static guarantees" - #118
    • static configuration, use svd2rust for the example
  • Portability - #119
    • examples: embedded-hal + drivers
  • The singleton pattern (*)
    • examples: static configuration, memory pools
  • Concurrency - #124
    • examples: static+interrupts, RTFM
  • Dynamic data structures - #125
    • fixed capacity collections: heapless
    • heap allocated collections: #[global_allocator], #[alloc_error]
  • Tips for embedded C developers - #126
    • e.g. iterators instead of for loop + indexing
  • Interop - #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 jamesmunns added the book label Jul 10, 2018

@jamesmunns

This comment has been minimized.

Member

jamesmunns commented Jul 10, 2018

@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

This comment has been minimized.

Member

jamesmunns commented Jul 10, 2018

@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

This comment has been minimized.

Member

japaric commented Jul 16, 2018

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

This comment has been minimized.

Collaborator

thejpster commented Jul 17, 2018

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

@ryankurte

This comment has been minimized.

Contributor

ryankurte commented Jul 17, 2018

@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

This comment has been minimized.

Member

japaric commented Jul 17, 2018

@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.

@japaric japaric added this to the RC milestone Jul 17, 2018

@thejpster

This comment has been minimized.

Collaborator

thejpster commented Jul 20, 2018

LGTM

@kjetilkjeka

This comment has been minimized.

kjetilkjeka commented Jul 20, 2018

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

This comment has been minimized.

Member

jamesmunns commented Jul 29, 2018

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

This comment has been minimized.

Member

jamesmunns commented Aug 4, 2018

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

This comment has been minimized.

Member

andre-richter commented Aug 4, 2018

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

This comment has been minimized.

Member

jamesmunns commented Aug 4, 2018

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

This comment has been minimized.

Member

japaric commented Aug 7, 2018

@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

This comment has been minimized.

Member

japaric commented Aug 7, 2018

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

@japaric

This comment has been minimized.

Member

japaric commented Aug 7, 2018

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 comment has been minimized.

Member

japaric commented Aug 10, 2018

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

@japaric japaric closed this Aug 10, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment