update block documentation

examples/cdc_pu_2chan_tx.grc

@@ -381,7 +381,7 @@ blocks:
     nchan: '1'
     out_clk: 'False'
     ref_clk: '0'
-    sample_rate: samp_rate
+    sample_rate: n_chan*samp_rate
     sampling: internal
     show_pmic: 'False'
     smb: '0'

include/gnuradio/cdc/dsa_pu_scenario_cc.h

@@ -16,7 +16,7 @@ namespace cdc {
 
 /*!
  * \brief Implements primary user scenario control for CDC dynamic spectrum
-          access project.
+ *        access project.
  * \ingroup cdc
  *
  */
@@ -26,16 +26,16 @@ public:
     typedef std::shared_ptr<dsa_pu_scenario_cc> sptr;
 
     /*!
-    * \brief DSA PU Scenario Constructor
-    *
      * \param samp_rate      Sample rate of incoming data streams
      * \param duration_ms    Duration (in ms) of scenario before randomly
-    * \param random         Randomly select primary user scenario
-    * \param seed           Seed used in random scenario selection.
+     *                       selecting new scenario
+     * \param random         Randomly select primary user scenario every
+     *                      \p duration_ms
+     * \param seed           Seed used in random scenario selection
      * \param scenario       Initial primary user scenario - bitmap of active
-    *                       channels, e.g., for 4 PU channels SCENARIO = 0b1010
-    *                       indicates channels 2 and 4 are active.
-    *                       selecting new scenario.
+     *                       channels, e.g., for 2 PU channels SCENARIO = 0b10
+     *                       indicates channel 1 is inactive and channel 2 is
+     *                       active
      */
     static sptr make(int samp_rate,
                      float duration_ms,

include/gnuradio/cdc/dsa_stats.h

@@ -18,19 +18,43 @@ namespace cdc {
  * \brief Track DSA scenario statistics.
  * \ingroup cdc
  *
+ * This block tracks statistics for the CDC DSA scenario. The current 
+ * instantaneous and long-term average throughput are calculated based
+ * on PDUs passed to the input `pdu' message port. Statistics are outputted
+ * on the `stats' message port as a PMT dictionary with the following keys.
+ *
+ * tput_inst: instantaneous throughput (in bps)\n
+ * tput_avg:  average throughput (in bps)\n
+ * score:     DSA score metric
+ * 
+ * The score metric requires the user to set \p tput_offered, the throughput
+ * offered to the primary user, and for the statistic message of the other 
+ * node (whether primary or secondary) to be passed into the `stats_in'
+ * message port.
+ * 
  */
 class CDC_API dsa_stats : virtual public gr::block {
 public:
     typedef std::shared_ptr<dsa_stats> sptr;
 
+    /*!
+     * \param period        Statistic update period (in seconds)                
+     * \param primary       True if this is primary user, false if secondary
+     *                      user - determines how score metric is calculated
+     * \param tput_offered  Offered primary throughput used in DSA score
+                            calculation
+     */
     static sptr make(int period = 1,
                      bool primary = true,
                      double tput_offered = 0.0);
 
+    //! Reset DSA statistics
     virtual void reset_stats(bool reset) = 0;
 
+    //! Set the offered primary throughput used in DSA score calculation
     virtual void set_tput_offered(double tput_offered) = 0;
 
+    //! Get the offered primary throughput used in DSA score calculation
     virtual double get_tput_offered(void) = 0;
 };
 

include/gnuradio/cdc/insert_burst_c.h

@@ -15,9 +15,18 @@ namespace gr {
 namespace cdc {
 
 /*!
- * \brief <+description of block+>
+ * \brief Inserts a burst of IQ samples into a stream of zeros.
  * \ingroup cdc
  *
+ * Input:\n
+ * PDU pair with a data segment of complex IQ samples 
+ *
+ * Output:\n
+ * Stream of complex samples of current burst or zeros if no burst is present
+ *
+ * This block is a workaround to allow discontinuous bursts of IQ samples to
+ * be provided to the bladeRF. If no burst is available the block will produce
+ * zeros. 
  */
 class CDC_API insert_burst_c : virtual public gr::sync_block {
 public:

include/gnuradio/cdc/preamble_detect_cc.h

@@ -15,14 +15,42 @@ namespace gr {
 namespace cdc {
 
 /*!
- * \brief <+description of block+>
+ * \brief Search for symbol sequence within sample stream via normalized
+ *        correlation
  * \ingroup cdc
  *
+ * Input:\n
+ * Stream of complex samples.
+ *
+ * Output:\n
+ * Output stream of input complex samples delayed by sequence length\n
+ * Optional second output stream providing normalized correlator output
+ * 
+ * Both output streams are tagged at the beggining of the identified sequence
+ * with the following stream tags. 
+ *
+ * corr_start: normalized correlation value for peak\n
+ * corr_est:   normalized correlation value for peak\n
+ * chan_est:   inverse of LLS channel estimate from training seq\n
+ * phase_est:  hardcoded to zero (phase offset is handled by chan_est)\n
+ * time_est:   fractional timing sample offset
+ *
+ * Note: 'corr_start' tag is added at the detected peak and all other tags are
+ * delayed by mark_delay samples to account for possible group delay of downstream
+ * matched filter block.
+ *
  */
 class CDC_API preamble_detect_cc : virtual public gr::sync_block {
 public:
     typedef std::shared_ptr<preamble_detect_cc> sptr;
 
+    /*!
+     * \param sequence      Symbol sequence for which to search
+     * \param threshold     Normalized correlation threshold to declare sequence
+     *                      found (in range 0.0 to 1.0)
+     * \param mark_delay    Tag marking delay to account for possible group
+     *                      delay of downstream matched filter
+     */
     static sptr make(const std::vector<gr_complex>& sequence,
                      float threshold = 0.5,
                      unsigned int mark_delay = 0);

python/cdc/bindings/dsa_pu_scenario_cc_python.cc

@@ -14,7 +14,7 @@
 /* BINDTOOL_GEN_AUTOMATIC(0)                                                       */
 /* BINDTOOL_USE_PYGCCXML(0)                                                        */
 /* BINDTOOL_HEADER_FILE(dsa_pu_scenario_cc.h)                                        */
-/* BINDTOOL_HEADER_FILE_HASH(219f58bccfee90b520aae47f5b3325c2)                     */
+/* BINDTOOL_HEADER_FILE_HASH(121c7efa13fbb1a239fff084df87d434)                     */
 /***********************************************************************************/
 
 #include <pybind11/complex.h>

python/cdc/bindings/dsa_stats_python.cc

@@ -14,7 +14,7 @@
 /* BINDTOOL_GEN_AUTOMATIC(0)                                                       */
 /* BINDTOOL_USE_PYGCCXML(0)                                                        */
 /* BINDTOOL_HEADER_FILE(dsa_stats.h)                                        */
-/* BINDTOOL_HEADER_FILE_HASH(9bbbbaa16987fedac4730cab7eb42ec5)                     */
+/* BINDTOOL_HEADER_FILE_HASH(8da1b50a0f17925344f8411764cbfa3c)                     */
 /***********************************************************************************/
 
 #include <pybind11/complex.h>

python/cdc/bindings/insert_burst_c_python.cc

@@ -14,7 +14,7 @@
 /* BINDTOOL_GEN_AUTOMATIC(0)                                                       */
 /* BINDTOOL_USE_PYGCCXML(0)                                                        */
 /* BINDTOOL_HEADER_FILE(insert_burst_c.h)                                        */
-/* BINDTOOL_HEADER_FILE_HASH(993cbe534820c2e3aa3580dd71c90d9c)                     */
+/* BINDTOOL_HEADER_FILE_HASH(a75b060c39df43f9b3f0104d310fef57)                     */
 /***********************************************************************************/
 
 #include <pybind11/complex.h>

python/cdc/bindings/preamble_detect_cc_python.cc

@@ -14,7 +14,7 @@
 /* BINDTOOL_GEN_AUTOMATIC(0)                                                       */
 /* BINDTOOL_USE_PYGCCXML(0)                                                        */
 /* BINDTOOL_HEADER_FILE(preamble_detect_cc.h)                                        */
-/* BINDTOOL_HEADER_FILE_HASH(a9266ae8920e7062dd71159aa9a81dbd)                     */
+/* BINDTOOL_HEADER_FILE_HASH(96ae6f35f01d30edb86832d741baced5)                     */
 /***********************************************************************************/
 
 #include <pybind11/complex.h>