Tock: Tracking: Kernel Documentation Round 2

[bradjc]

High-level advice documentation

• [ ] Document Tock design decisions.
  
  
  
  • [x] Event-driven kernel. No blocking. #1466
  
  
  • [x] No dependencies or external crates. #1466
  
  
  • [x] Ease of understanding code and getting started with Tock. #1466
  
  
  • [ ] Passing &mut references.
  
  
  • [ ] Interior mutability and circular references.
  
  
  • [x] HIL design and when to introduce a new HIL. #1466
  
  
  • [ ] Things Tock is (likely) never going to do.
  
  
  • [x] Path to core team. #1508
  
  
  • [x] Minimum requirements for merging a new board into Tock master. #1509
  
  
• [x] Generic overview on how to do various high-level goals.
  
  
  
  • Examples:
  
  
  • [x] Write a chip peripheral.
  
  
  • [x] Add an IC driver.
  
  
  • [x] Pass an interface to userspace.
  
  
  • [x] Need to define a new HIL. @bradjc
  
  
• [x] When to use capabilities. #1466

More detailed developer help documentation

• [x] Comment differences (// vs /// vs //!) and when to use which. #1506
• [x] How to write kernel tests. https://github.com/tock/book/pull/7
• [ ] Expand the debugging help in the debugging folder. (Pat)

Update existing docs

• [x] Initial readme with more links.
• [ ] Mutable references. Make sure doc is consistent with actual use.

New documentation on Tock things

• [ ] Doc describing how resources are virtualized in capsules.

Update Tock Book

• [ ] Add in notes about components for boards (Pat)
• [ ] Another kernel course module
• [ ] More walkthrough-style documentation

Other Ideas

• Merge all (most?) documentation into the book so there is one canonical place to look.
• Pointers to good example code.
• Document workshop agenda / outcomes
  
  
  
  • Post all slides from the workshop(s?)
  
  

[bradjc]

Can we volunteer people to write the remaining documents?

[bradjc]

Also, will you upvote this comment if you support moving most of the documentation that is in tock/doc to the book (or downvote if not)? I would like to move all of the design-esque .md files to the book so that everything is in one place.

[hudson-ayers]

I think that if we move all of the documentation in tock/doc to the book we need to reorganize the book so that documentation is at the start, and the hands-on guides are at the end.

[bradjc]

We got fairly far on this. We can do a Round 3 as new documentation is requested/needed.