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/pounder/dds_output.rs:1:1
   |
1  | / ///! The DdsOutput is used as an output stream to the pounder DDS.
2  | | ///!
3  | | ///! # Design
4  | | ///!
...  |
53 | | ///! process can be done once and then register values can be written into a pre-computed serialized
54 | | ///! buffer to avoid the software overhead of much of the serialization process.
   | |________________________________________________________________________________^
   |
   = 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 DdsOutput is used as an output stream to the pounder DDS.
2  + //!
3  + //! # Design
4  + //!
5  + //! The DDS stream interface is a means of quickly updating pounder DDS (direct digital synthesis)
6  + //! outputs of the AD9959 DDS chip. The DDS communicates via a quad-SPI interface and a single
7  + //! IO-update output pin.
8  + //!
9  + //! In order to update the DDS interface, the frequency tuning word, amplitude control word, and
10 + //! the phase offset word for a channel can be modified to change the frequency, amplitude, or
11 + //! phase on any of the 4 available output channels. Changes do not propagate to DDS outputs until
12 + //! the IO-update pin is toggled high to activate the new configurations. This allows multiple
13 + //! channels or parameters to be updated and then effects can take place simultaneously.
14 + //!
15 + //! In this implementation, the phase, frequency, or amplitude can be updated for any single
16 + //! collection of outputs simultaneously. This is done by serializing the register writes to the
17 + //! DDS into a single buffer of data and then writing the data over QSPI to the DDS.
18 + //!
19 + //! In order to minimize software overhead, data is written directly into the QSPI output FIFO. In
20 + //! order to accomplish this most efficiently, serialized data is written as 32-bit words to
21 + //! minimize the number of bus cycles necessary to write to the peripheral FIFO. A consequence of
22 + //! this is that additional unneeded register writes may be appended to align a transfer to 32-bit
23 + //! word sizes.
24 + //!
25 + //! In order to pulse the IO-update signal, the high-resolution timer output is used. The timer is
26 + //! configured to assert the IO-update signal after a predefined delay and then de-assert the
27 + //! signal after a predefined assertion duration. This allows for the actual QSPI transfer and
28 + //! IO-update toggle to be completed asynchronously to the rest of software processing - that is,
29 + //! software can schedule the DDS updates and then continue data processing. DDS updates then take
30 + //! place in the future when the IO-update is toggled by hardware.
31 + //!
32 + //!
33 + //! # Limitations
34 + //!
35 + //! The QSPI output FIFO is used as an intermediate buffer for holding pending QSPI writes. Because
36 + //! of this, the implementation only supports up to 16 serialized bytes (the QSPI FIFO is 8 32-bit
37 + //! words, or 32 bytes, wide) in a single update.
38 + //!
39 + //! There is currently no synchronization between completion of the QSPI data write and the
40 + //! IO-update signal. It is currently assumed that the QSPI transfer will always complete within a
41 + //! predefined delay (the pre-programmed IO-update timer delay).
42 + //!
43 + //!
44 + //! # Future Improvement
45 + //!
46 + //! In the future, it would be possible to utilize a DMA transfer to complete the QSPI transfer.
47 + //! Once the QSPI transfer completed, this could trigger the IO-update timer to start to
48 + //! asynchronously complete IO-update automatically. This would allow for arbitrary profile sizes
49 + //! and ensure that IO-update was in-sync with the QSPI transfer.
50 + //!
51 + //! Currently, serialization is performed on each processing cycle. If there is a
52 + //! compile-time-known register update sequence needed for the application, the serialization
53 + //! process can be done once and then register values can be written into a pre-computed serialized
54 + //! buffer to avoid the software overhead of much of the serialization process.
   |

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/dac.rs:1:1
   |
1  | / ///! Stabilizer DAC management interface
2  | | ///!
3  | | ///! # Design
4  | | ///!
...  |
51 | | ///! for re-use of a previously provided DAC output buffer. It is assumed that the DMA request is
52 | | ///! served promptly after the transfer completes.
   | |__________________________________________________^
   |
   = 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 DAC management interface
2  + //!
3  + //! # Design
4  + //!
5  + //! Stabilizer DACs are connected to the MCU via a simplex, SPI-compatible interface. Each DAC
6  + //! accepts a 16-bit output code.
7  + //!
8  + //! In order to maximize CPU processing time, the DAC code updates are offloaded to hardware using
9  + //! a timer compare channel, DMA stream, and the DAC SPI interface.
10 + //!
11 + //! The timer comparison channel is configured to generate a DMA request whenever the comparison
12 + //! occurs. Thus, whenever a comparison happens, a single DAC code can be written to the output. By
13 + //! configuring a DMA stream for a number of successive DAC codes, hardware can regularly update
14 + //! the DAC without requiring the CPU.
15 + //!
16 + //! In order to ensure alignment between the ADC sample batches and DAC output code batches, a DAC
17 + //! output batch is always exactly 3 batches after the ADC batch that generated it.
18 + //!
19 + //! The DMA transfer for the DAC output codes utilizes a double-buffer mode to avoid losing any
20 + //! transfer events generated by the timer (for example, when 2 update cycles occur before the DMA
21 + //! transfer completion is handled). In this mode, by the time DMA swaps buffers, there is always a valid buffer in the
22 + //! "next-transfer" double-buffer location for the DMA transfer. Once a transfer completes,
23 + //! software then has exactly one batch duration to fill the next buffer before its
24 + //! transfer begins. If software does not meet this deadline, old data will be repeatedly generated
25 + //! on the output and output will be shifted by one batch.
26 + //!
27 + //! ## Multiple Samples to Single DAC Codes
28 + //!
29 + //! For some applications, it may be desirable to generate a single DAC code from multiple ADC
30 + //! samples. In order to maintain timing characteristics between ADC samples and DAC code outputs,
31 + //! applications are required to generate one DAC code for each ADC sample. To accomodate mapping
32 + //! multiple inputs to a single output, the output code can be repeated a number of times in the
33 + //! output buffer corresponding with the number of input samples that were used to generate it.
34 + //!
35 + //!
36 + //! # Note
37 + //!
38 + //! There is a very small amount of latency between updating the two DACs due to bus matrix
39 + //! priority. As such, one of the DACs will be updated marginally earlier before the other because
40 + //! the DMA requests are generated simultaneously. This can be avoided by providing a known offset
41 + //! to other DMA requests, which can be completed by setting e.g. DAC0's comparison to a
42 + //! counter value of 2 and DAC1's comparison to a counter value of 3. This will have the effect of
43 + //! generating the DAC updates with a known latency of 1 timer tick to each other and prevent the
44 + //! DMAs from racing for the bus. As implemented, the DMA channels utilize natural priority of the
45 + //! DMA channels to arbitrate which transfer occurs first.
46 + //!
47 + //!
48 + //! # Limitations
49 + //!
50 + //! While double-buffered mode is used for DMA to avoid lost DAC-update events, there is no check
51 + //! for re-use of a previously provided DAC output buffer. It is assumed that the DMA request is
52 + //! served promptly after the transfer completes.
   |

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
  |