Peripherals Chapter #15

jamesmunns · 2018-08-22T01:50:07Z

Still needs heavy expansion and editing
Move "singleton" to "peripherals"

jamesmunns · 2018-08-22T01:53:25Z

Related to #5, #6, and #2.

I have a four hour flight tomorrow, I hope to bring some more structure and detail to this, it still really looks like presenter notes.

CC @rust-embedded/resources, let me know if you do or do not like the content and structure.

For reference, my conference talk is here: https://ferrous-systems.github.io/rustconf-james-2018

jamesmunns · 2018-08-22T02:03:39Z

I'd say there are two strategies here:

Merge the ugly content, and iteratively fix
Close this PR (or leave it unmerged as a reference), and open up separate PRs for each section as it has been prettified.

Open to suggestions, but I'm done for the evening.

jamesmunns · 2018-08-23T17:29:16Z

src/portability/traits.md

+}
+```
+
+> this goes in your chip crate


NOTE: Make the wording (and presentation) consistent - use "Device Crate", include links to all example crates, consistent structuring.

thejpster · 2018-09-04T18:37:28Z

I like this. I'd merge it on the grounds that something is better than nothing, and there's definitely value in here even if it does have gaps.

therealprof

Found a few nits but otherwise that looks really good to me.

therealprof · 2018-09-12T19:39:57Z

src/peripherals/a-first-attempt.md

+}
+```
+
+Although this works it is subjectively a little messy, so the first reaction might be to wrap these related things up in to a `struct` to better organize them. A second attempt could come up with something like this:


3 prepositions after one another are maybe a bit excessive, I'd probably strike up and merge "in" and "to" into "into".

therealprof · 2018-09-12T19:45:42Z

src/peripherals/borrowck.md

+
+## The Borrow Checker
+
+The last two of these rules sound suspiciously exactly like what the Borrow Checker does already!


"suspiciously exactly like" has a weird ring to it. Maybe "suspiciously similar to"?

therealprof · 2018-09-12T19:57:30Z

src/peripherals/peripherals.md

+
+## What are Peripherals?
+
+Most Microcontrollers have more than just a CPU, RAM, or Flash Memory - they contain sections of silicon which are used for interacting with systems outside of the microcontroller. These components are collectively known as Peripherals, and are often used to manage communication with sensors, Bluetooth radios, screens, or touch pads.


Maybe be a more general about what peripherals are: They're not just useful for interacting with other systems but to interface with the surroundings in the world, e.g. sensors, actors, humans and other systems.

therealprof · 2018-09-12T20:04:28Z

src/peripherals/peripherals.md

+
+These peripherals are useful because they allow a developer to offload processing to them, avoiding having to handle everything in software. Similar to how a desktop developer would offload graphics processing to a video card, embedded developers can offload some tasks to peripherals allowing the CPU to spend it's time doing something else important, or doing nothing in order to save power.
+
+However, unlike graphics cards, which typically have a Software API like Vulkan, Metal, or OpenGL, peripherals are exposed to our CPU with a hardware interface, which is mapped to a chunk of the memory.


My use of CPU here was generally that "MCU = CPU + RAM + Flash + Peripherals" or such. Though, either way I should clarify.

I tend to agree, but there's a certain understanding of what goes into a CPU nowadays and that's a lot more than a plain ALU as it used to be 30 years ago so to avoid confusion I would not use the term CPU.

therealprof · 2018-09-12T20:12:36Z

src/peripherals/peripherals.md

+
+On a desktop system, access to memory is tightly controlled by the MMU, or Memory Management Unit. This component has two major responsibilities: enforcing access permission to sections of memory (preventing one thread from reading or modifying the memory of another thread); and re-mapping segments of the physical memory to virtual memory ranges used in software. Microcontrollers do not typically have an MMU, and instead only use real physical addresses in software.
+
+Although 32 bit microcontrollers have a real and linear address space from `0x0000_0000`, and `0xFFFF_FFFF`, they generally only use a few hundred kilobytes of that range for actual memory. This leaves a significant about of address space remaining.


amount instead of about

therealprof · 2018-09-12T20:48:15Z

src/portability/traits.md

+    CS: OutputPin,
+{
+    /// Creates a new driver from a SPI peripheral
+    /// and a NCS pin


Spell out NCS (or CS) so people can guess what that does

Will do. This is a direct copy/paste from the embedded hal code. I'll make it more verbose to be readable out of context.

therealprof · 2018-09-12T20:50:14Z

src/typestate-programming/design-contracts.md

+In
+
+```rust
+struct GpioPin; struct InputGpio; struct OutputGpio;


Fan out and maybe put it in a comment or fictionally import them.

therealprof · 2018-09-12T21:00:07Z

src/typestate-programming/design-contracts.md

+```
+
+* Use type transitions to enforce setup steps
+* Like the builder pattern in "normal" rust


rust -> Rust

therealprof · 2018-09-12T21:35:09Z

src/typestate-programming/zero-cost-abstractions.md

+
+```rust
+pub struct PushPull;  // good for general usage
+pub struct OpenDrain; // better for high power LEDs


In a MCU the main usage of OpenDrain GPIOs is communication with several devices on one bus. The internal MOSFETs in MCUs typically do not have a very high power rating, often not even higher than what a PP configuration can sink or source and also the maximum power is usually limited by the general sinking capabilities of the MCU which usually is in the order of a few hundred mA.

therealprof · 2018-09-12T21:36:08Z

src/typestate-programming/zero-cost-abstractions.md

+}
+```
+
+* Nested zero sized types are still zero sized, no matter how deep you nest it


* Still needs heavy expansion and editing * Move "singleton" to "peripherals"

…uggestion

jamesmunns · 2018-09-24T17:52:46Z

Reping @rust-embedded/resources, I have stripped this down to just the peripherals chapter, and should be ready to merge if there are no further review comments.

jamesmunns · 2018-09-26T12:57:31Z

@therealprof addressed changes, dismissing old review

addressed changes

therealprof

LGTM.

jamesmunns · 2018-09-26T13:15:12Z

Thanks!

bors r+

15: Peripherals Chapter r=jamesmunns a=jamesmunns * Still needs heavy expansion and editing * Move "singleton" to "peripherals" Co-authored-by: James Munns <[email protected]> Co-authored-by: James Munns <[email protected]>

bors · 2018-09-26T13:17:34Z

Build succeeded

continuous-integration/travis-ci/push

15: Peripherals Chapter r=jamesmunns a=jamesmunns * Still needs heavy expansion and editing * Move "singleton" to "peripherals" Co-authored-by: James Munns <[email protected]> Co-authored-by: James Munns <[email protected]>

jamesmunns requested a review from a team as a code owner August 22, 2018 01:50

jamesmunns commented Aug 23, 2018

View reviewed changes

jamesmunns force-pushed the rustconf-dump branch from bb4442a to 4a2c521 Compare September 11, 2018 21:08

therealprof previously requested changes Sep 12, 2018

View reviewed changes

jamesmunns added 7 commits September 24, 2018 19:35

Add content from my RustConf talk

daf4c73

* Still needs heavy expansion and editing * Move "singleton" to "peripherals"

Use correct relative path for assets

fa51b62

Refactor Peripherals introduction

f3c86d7

keep cleaning

c96ba51

A couple of typos

45dbe00

Clean up Peripherals chapter

f0084e0

Static Guarantees becomes Typestate Programming, as per @japaric 's s…

df8e2e8

…uggestion

jamesmunns force-pushed the rustconf-dump branch from 4d0a4be to df8e2e8 Compare September 24, 2018 17:35

jamesmunns added 2 commits September 24, 2018 19:46

Changes based on @therealprof 's suggestions

7791f06

Isolate peripherals chapter

214af2e

jamesmunns changed the title ~~WIP: Add content from my RustConf talk~~ Peripherals Chapter Sep 24, 2018

restore old file

b3b5732

japaric added T-resources S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 25, 2018

Merge branch 'master' into rustconf-dump

3746885

therealprof approved these changes Sep 26, 2018

View reviewed changes

jamesmunns removed the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Sep 26, 2018

bors bot merged commit 3746885 into master Sep 26, 2018

bors bot deleted the rustconf-dump branch September 26, 2018 13:17

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Peripherals Chapter #15

Peripherals Chapter #15

jamesmunns commented Aug 22, 2018

jamesmunns commented Aug 22, 2018

jamesmunns commented Aug 22, 2018

jamesmunns Aug 23, 2018

thejpster commented Sep 4, 2018

therealprof left a comment

therealprof Sep 12, 2018

therealprof Sep 12, 2018

therealprof Sep 12, 2018

therealprof Sep 12, 2018

jamesmunns Sep 13, 2018

therealprof Sep 13, 2018

therealprof Sep 12, 2018

therealprof Sep 12, 2018

jamesmunns Sep 13, 2018

therealprof Sep 12, 2018

therealprof Sep 12, 2018

therealprof Sep 12, 2018

therealprof Sep 12, 2018

jamesmunns commented Sep 24, 2018

jamesmunns commented Sep 26, 2018

therealprof left a comment

jamesmunns commented Sep 26, 2018

bors bot commented Sep 26, 2018


		## The Borrow Checker

		The last two of these rules sound suspiciously exactly like what the Borrow Checker does already!


		## What are Peripherals?

		Most Microcontrollers have more than just a CPU, RAM, or Flash Memory - they contain sections of silicon which are used for interacting with systems outside of the microcontroller. These components are collectively known as Peripherals, and are often used to manage communication with sensors, Bluetooth radios, screens, or touch pads.


		These peripherals are useful because they allow a developer to offload processing to them, avoiding having to handle everything in software. Similar to how a desktop developer would offload graphics processing to a video card, embedded developers can offload some tasks to peripherals allowing the CPU to spend it's time doing something else important, or doing nothing in order to save power.

		However, unlike graphics cards, which typically have a Software API like Vulkan, Metal, or OpenGL, peripherals are exposed to our CPU with a hardware interface, which is mapped to a chunk of the memory.


		On a desktop system, access to memory is tightly controlled by the MMU, or Memory Management Unit. This component has two major responsibilities: enforcing access permission to sections of memory (preventing one thread from reading or modifying the memory of another thread); and re-mapping segments of the physical memory to virtual memory ranges used in software. Microcontrollers do not typically have an MMU, and instead only use real physical addresses in software.

		Although 32 bit microcontrollers have a real and linear address space from `0x0000_0000`, and `0xFFFF_FFFF`, they generally only use a few hundred kilobytes of that range for actual memory. This leaves a significant about of address space remaining.

Peripherals Chapter #15

Peripherals Chapter #15

Conversation

jamesmunns commented Aug 22, 2018

jamesmunns commented Aug 22, 2018

jamesmunns commented Aug 22, 2018

Choose a reason for hiding this comment

thejpster commented Sep 4, 2018

therealprof left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jamesmunns commented Sep 24, 2018

jamesmunns commented Sep 26, 2018

therealprof left a comment

Choose a reason for hiding this comment

jamesmunns commented Sep 26, 2018

bors bot commented Sep 26, 2018

Build succeeded