Merge #532

532: Comment buffer usage in adc_dma_rtic example r=burrbull a=9names

`@apollolabsdev` asked on Discord what was going on in the adc_dma_rtic example, and I explained it as best I could.
They seem to understand it enough to write a blog post about it, so I assume my help was sufficient.
This is the gist of that.

Co-authored-by: 9names <[email protected]>

Author: bors[bot]

CHANGELOG.md

@@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Added
 
+ - Docs in `rtic-adc-dma` example [#532]
  - `OutPortX` (X = 2..8) and `OutPortArray` structures which can handle several pins at once [#426]
  - `restore` for `ErasedPin` and `PartiallyErasedPin`
 
@@ -27,6 +28,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
  - Fix SDIO hardware flow control errata [#577]
 
 [#426]: https://github.com/stm32-rs/stm32f4xx-hal/pull/426
+[#532]: https://github.com/stm32-rs/stm32f4xx-hal/pull/532
 [#571]: https://github.com/stm32-rs/stm32f4xx-hal/pull/571
 [#572]: https://github.com/stm32-rs/stm32f4xx-hal/pull/572
 [#577]: https://github.com/stm32-rs/stm32f4xx-hal/pull/577

examples/rtic-adc-dma.rs

@@ -77,8 +77,11 @@ mod app {
         adc.configure_channel(&voltage, Sequence::Two, SampleTime::Cycles_480);
         adc.enable_temperature_and_vref();
 
+        // These buffers need to be 'static to use safely with the DMA - we can't allow them to be dropped while the DMA is accessing them.
+        // The easiest way to satisfy that is to make them static, and the safest way to do that is with `cortex_m::singleton!`
         let first_buffer = cortex_m::singleton!(: [u16; 2] = [0; 2]).unwrap();
         let second_buffer = Some(cortex_m::singleton!(: [u16; 2] = [0; 2]).unwrap());
+        // Give the first buffer to the DMA. The second buffer is held in an Option in `local.buffer` until the transfer is complete
         let transfer = Transfer::init_peripheral_to_memory(dma.0, adc, first_buffer, None, config);
 
         polling::spawn_after(1.secs()).ok();
@@ -107,6 +110,8 @@ mod app {
     fn dma(cx: dma::Context) {
         let dma::Context { mut shared, local } = cx;
         let (buffer, sample_to_millivolts) = shared.transfer.lock(|transfer| {
+            // When the DMA completes it will return the buffer we gave it last time - we now store that as `buffer`
+            // We still have our other buffer waiting in `local.buffer`, so `take` that and give it to the `transfer`
             let (buffer, _) = transfer
                 .next_transfer(local.buffer.take().unwrap())
                 .unwrap();
@@ -115,9 +120,12 @@ mod app {
             (buffer, sample_to_millivolts)
         });
 
+        // Pull the ADC data out of the buffer that the DMA transfer gave us
         let raw_temp = buffer[0];
         let raw_volt = buffer[1];
 
+        // Now that we're finished with this buffer, put it back in `local.buffer` so it's ready for the next transfer
+        // If we don't do this before the next transfer, we'll get a panic
         *local.buffer = Some(buffer);
 
         let cal30 = VtempCal30::get().read() as f32;