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. |