warning: manual slice size calculation
   --> src/net/data_stream.rs:367:29
    |
367 | ...                   buf.len() * core::mem::size_of::<MaybeUninit<u8>>(),
    |                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    |
    = help: consider using std::mem::size_of_value instead
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#manual_slice_size_calculation
    = note: `#[warn(clippy::manual_slice_size_calculation)]` on by default

warning: this is an outer doc comment and does not apply to the parent module or crate
  --> src/net/telemetry.rs:1:1
   |
1  | / ///! Stabilizer Telemetry Capabilities
2  | | ///!
3  | | ///! # Design
4  | | ///! Telemetry is reported regularly using an MQTT client. All telemetry is reported in SI units
...  |
11 | | ///! required immediately before transmission. This ensures that any slower computation required
12 | | ///! for unit conversion can be off-loaded to lower priority tasks.
   | |___________________________________________________________________^
   |
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#suspicious_doc_comments
help: use an inner doc comment to document the parent module or crate
   |
1  + //! Stabilizer Telemetry Capabilities
2  + //!
3  + //! # Design
4  + //! Telemetry is reported regularly using an MQTT client. All telemetry is reported in SI units
5  + //! using standard JSON format.
6  + //!
7  + //! In order to report ADC/DAC codes generated during the DSP routines, a telemetry buffer is
8  + //! employed to track the latest codes. Converting these codes to SI units would result in
9  + //! repetitive and unnecessary calculations within the DSP routine, slowing it down and limiting
10 + //! sampling frequency. Instead, the raw codes are stored and the telemetry is generated as
11 + //! required immediately before transmission. This ensures that any slower computation required
12 + //! for unit conversion can be off-loaded to lower priority tasks.
   |

warning: this is an outer doc comment and does not apply to the parent module or crate
 --> src/net/network_processor.rs:1:1
  |
1 | / ///! Task to process network hardware.
2 | | ///!
3 | | ///! # Design
4 | | ///! The network processir is a small taks to regularly process incoming data over ethernet, handle
5 | | ///! the ethernet PHY state, and reset the network as appropriate.
  | |__________________________________________________________________^
  |
  = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#suspicious_doc_comments
help: use an inner doc comment to document the parent module or crate
  |
1 + //! Task to process network hardware.
2 + //!
3 + //! # Design
4 + //! The network processir is a small taks to regularly process incoming data over ethernet, handle
5 + //! the ethernet PHY state, and reset the network as appropriate.
  |

warning: this is an outer doc comment and does not apply to the parent module or crate
 --> src/net/mod.rs:1:1
  |
1 | / ///! Stabilizer network management module
2 | | ///!
3 | | ///! # Design
4 | | ///! The stabilizer network architecture supports numerous layers to permit transmission of
5 | | ///! telemetry (via MQTT), configuration of run-time settings (via MQTT + Miniconf), and live data
6 | | ///! streaming over raw UDP/TCP sockets. This module encompasses the main processing routines
7 | | ///! related to Stabilizer networking operations.
  | |_________________________________________________^
  |
  = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#suspicious_doc_comments
help: use an inner doc comment to document the parent module or crate
  |
1 + //! Stabilizer network management module
2 + //!
3 + //! # Design
4 + //! The stabilizer network architecture supports numerous layers to permit transmission of
5 + //! telemetry (via MQTT), configuration of run-time settings (via MQTT + Miniconf), and live data
6 + //! streaming over raw UDP/TCP sockets. This module encompasses the main processing routines
7 + //! related to Stabilizer networking operations.
  |

warning: this is an outer doc comment and does not apply to the parent module or crate
 --> src/hardware/timers.rs:1:1
  |
1 | ///! The sampling timer is used for managing ADC sampling and external reference timestamping.
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#suspicious_doc_comments
help: use an inner doc comment to document the parent module or crate
  |
1 | //! The sampling timer is used for managing ADC sampling and external reference timestamping.
  |

warning: this is an outer doc comment and does not apply to the parent module or crate
 --> src/hardware/setup.rs:1:1
  |
1 | / ///! Stabilizer hardware configuration
2 | | ///!
3 | | ///! This file contains all of the hardware-specific configuration of Stabilizer.
  | |_________________________________________________________________________________^
  |
  = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#suspicious_doc_comments
help: use an inner doc comment to document the parent module or crate
  |
1 + //! Stabilizer hardware configuration
2 + //!
3 + //! This file contains all of the hardware-specific configuration of Stabilizer.
  |

warning: this is an outer doc comment and does not apply to the parent module or crate
  --> src/hardware/pounder/timestamp.rs:1:1
   |
1  | / ///! ADC sample timestamper using external Pounder reference clock.
2  | | ///!
3  | | ///! # Design
4  | | ///!
...  |
17 | | ///! batch size. This results in the input capture triggering identically to when the ADC samples
18 | | ///! the last sample of the batch. That sample is then available for processing by the user.
   | |____________________________________________________________________________________________^
   |
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#suspicious_doc_comments
help: use an inner doc comment to document the parent module or crate
   |
1  + //! ADC sample timestamper using external Pounder reference clock.
2  + //!
3  + //! # Design
4  + //!
5  + //! The pounder timestamper utilizes the pounder SYNC_CLK output as a fast external reference clock
6  + //! for recording a timestamp for each of the ADC samples.
7  + //!
8  + //! To accomplish this, a timer peripheral is configured to be driven by an external clock input.
9  + //! Due to the limitations of clock frequencies allowed by the timer peripheral, the SYNC_CLK input
10 + //! is divided by 4. This clock then clocks the timer peripheral in a free-running mode with an ARR
11 + //! (max count register value) configured to overflow once per ADC sample batch.
12 + //!
13 + //! Once the timer is configured, an input capture is configured to record the timer count
14 + //! register. The input capture is configured to utilize an internal trigger for the input capture.
15 + //! The internal trigger is selected such that when a sample is generated on ADC0, the input
16 + //! capture is simultaneously triggered. That trigger is prescaled (its rate is divided) by the
17 + //! batch size. This results in the input capture triggering identically to when the ADC samples
18 + //! the last sample of the batch. That sample is then available for processing by the user.
   |

warning: this is an outer doc comment and does not apply to the parent module or crate
 --> src/hardware/pounder/hrtimer.rs:1:1
  |
1 | ///! The HRTimer (High Resolution Timer) is used to generate IO_Update pulses to the Pounder DDS.
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#suspicious_doc_comments
help: use an inner doc comment to document the parent module or crate
  |
1 | //! The HRTimer (High Resolution Timer) is used to generate IO_Update pulses to the Pounder DDS.
  |

warning: this is an outer doc comment and does not apply to the parent module or crate
  --> src/hardware/input_stamper.rs:1:1
   |
1  | / ///! Digital Input 0 (DI0) reference clock timestamper
2  | | ///!
3  | | ///! This module provides a means of timestamping the rising edges of an external reference clock on
4  | | ///! the DI0 with a timer value from TIM5.
...  |
25 | | ///! This module only supports DI0 for timestamping due to trigger constraints on the DIx pins. If
26 | | ///! timestamping is desired in DI1, a separate timer + capture channel will be necessary.
   | |__________________________________________________________________________________________^
   |
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#suspicious_doc_comments
help: use an inner doc comment to document the parent module or crate
   |
1  + //! Digital Input 0 (DI0) reference clock timestamper
2  + //!
3  + //! This module provides a means of timestamping the rising edges of an external reference clock on
4  + //! the DI0 with a timer value from TIM5.
5  + //!
6  + //! # Design
7  + //! An input capture channel is configured on DI0 and fed into TIM5's capture channel 4. TIM5 is
8  + //! then run in a free-running mode with a configured tick rate (PSC) and maximum count value
9  + //! (ARR). Whenever an edge on DI0 triggers, the current TIM5 counter value is captured and
10 + //! recorded as a timestamp. This timestamp can be either directly read from the timer channel or
11 + //! can be collected asynchronously via DMA collection.
12 + //!
13 + //! To prevent silently discarding timestamps, the TIM5 input capture over-capture flag is
14 + //! continually checked. Any over-capture event (which indicates an overwritten timestamp) then
15 + //! triggers a panic to indicate the dropped timestamp so that design parameters can be adjusted.
16 + //!
17 + //! # Tradeoffs
18 + //! It appears that DMA transfers can take a significant amount of time to disable (400ns) if they
19 + //! are being prematurely stopped (such is the case here). As such, for a sample batch size of 1,
20 + //! this can take up a significant amount of the total available processing time for the samples.
21 + //! This module checks for any captured timestamps from the timer capture channel manually. In
22 + //! this mode, the maximum input clock frequency supported is dependant on the sampling rate and
23 + //! batch size.
24 + //!
25 + //! This module only supports DI0 for timestamping due to trigger constraints on the DIx pins. If
26 + //! timestamping is desired in DI1, a separate timer + capture channel will be necessary.
   |

warning: this is an outer doc comment and does not apply to the parent module or crate
  --> src/hardware/adc.rs:1:1
   |
1  | / ///! Stabilizer ADC management interface
2  | | ///!
3  | | ///! # Design
4  | | ///!
...  |
66 | | ///! have finite depth, FIFO access is slower than AXISRAM access, and because the single
67 | | ///! buffer mode DMA disable/enable and buffer update sequence is slow.
   | |_______________________________________________________________________^
   |
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#suspicious_doc_comments
help: use an inner doc comment to document the parent module or crate
   |
1  + //! Stabilizer ADC management interface
2  + //!
3  + //! # Design
4  + //!
5  + //! Stabilizer ADCs are connected to the MCU via a simplex, SPI-compatible interface. The ADCs
6  + //! require a setup conversion time after asserting the CSn (convert) signal to generate the ADC
7  + //! code from the sampled level. Once the setup time has elapsed, the ADC data is clocked out of
8  + //! MISO. The internal setup time is managed by the SPI peripheral via a CSn setup time parameter
9  + //! during SPI configuration, which allows offloading the management of the setup time to hardware.
10 + //!
11 + //! Because of the SPI-compatibility of the ADCs, a single SPI peripheral + DMA is used to automate
12 + //! the collection of multiple ADC samples without requiring processing by the CPU, which reduces
13 + //! overhead and provides the CPU with more time for processing-intensive tasks, like DSP.
14 + //!
15 + //! The automation of sample collection utilizes three DMA streams, the SPI peripheral, and two
16 + //! timer compare channel for each ADC. One timer comparison channel is configured to generate a
17 + //! comparison event every time the timer is equal to a specific value. Each comparison then
18 + //! generates a DMA transfer event to write into the SPI CR1 register to initiate the transfer.
19 + //! This allows the SPI interface to periodically read a single sample. The other timer comparison
20 + //! channel is configured to generate a comparison event slightly before the first (~10 timer
21 + //! cycles). This channel triggers a separate DMA stream to clear the EOT flag within the SPI
22 + //! peripheral. The EOT flag must be cleared after each transfer or the SPI peripheral will not
23 + //! properly complete the single conversion. Thus, by using two DMA streams and timer comparison
24 + //! channels, the SPI can regularly acquire ADC samples.
25 + //!
26 + //! In order to collect the acquired ADC samples into a RAM buffer, a final DMA transfer is
27 + //! configured to read from the SPI RX FIFO into RAM. The request for this transfer is connected to
28 + //! the SPI RX data signal, so the SPI peripheral will request to move data into RAM whenever it is
29 + //! available. When enough samples have been collected, a transfer-complete interrupt is generated
30 + //! and the ADC samples are available for processing.
31 + //!
32 + //! After a complete transfer of a batch of samples, the inactive buffer is available to the
33 + //! user for processing. The processing must complete before the DMA transfer of the next batch
34 + //! completes.
35 + //!
36 + //! ## Starting Data Collection
37 + //!
38 + //! Because the DMA data collection is automated via timer count comparisons and DMA transfers, the
39 + //! ADCs can be initialized and configured, but will not begin sampling the external ADCs until the
40 + //! sampling timer is enabled. As such, the sampling timer should be enabled after all
41 + //! initialization has completed and immediately before the embedded processing loop begins.
42 + //!
43 + //!
44 + //! ## Batch Sizing
45 + //!
46 + //! The ADCs collect a group of N samples, which is referred to as a batch. The size of the batch
47 + //! is configured by the user at compile-time to allow for a custom-tailored implementation. Larger
48 + //! batch sizes generally provide for lower overhead and more processing time per sample, but come
49 + //! at the expense of increased input -> output latency.
50 + //!
51 + //!
52 + //! # Note
53 + //!
54 + //! While there are two ADCs, only a single ADC is configured to generate transfer-complete
55 + //! interrupts. This is done because it is assumed that the ADCs will always be sampled
56 + //! simultaneously. If only a single ADC is used, it must always be ADC0, as ADC1 will not generate
57 + //! transfer-complete interrupts.
58 + //!
59 + //! There is a very small amount of latency between sampling of ADCs due to bus matrix priority. As
60 + //! such, one of the ADCs will be sampled marginally earlier before the other because the DMA
61 + //! requests are generated simultaneously. This can be avoided by providing a known offset to the
62 + //! sample DMA requests, which can be completed by setting e.g. ADC0's comparison to a counter
63 + //! value of 0 and ADC1's comparison to a counter value of 1.
64 + //!
65 + //! In this implementation, double buffer mode DMA transfers are used because the SPI RX FIFOs
66 + //! have finite depth, FIFO access is slower than AXISRAM access, and because the single
67 + //! buffer mode DMA disable/enable and buffer update sequence is slow.
   |

warning: this is an outer doc comment and does not apply to the parent module or crate
 --> src/hardware/mod.rs:2:1
  |
2 | ///! Module for all hardware-specific setup of Stabilizer
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#suspicious_doc_comments
  = note: `#[warn(clippy::suspicious_doc_comments)]` on by default
help: use an inner doc comment to document the parent module or crate
  |
2 | //! Module for all hardware-specific setup of Stabilizer
  |