Prepared task description for histogram VHDL component development in ST HDL library.

libraries/dsp/st/doc/st_histogram.txt

+Title: Develop histogram component in VHDL
+Author: E. Kooistra
+
+Contents:
+1) Purpose
+2) Requirements
+3) Design
+4) Development
+5) References:
+
+
+1) Purpose
+
+The purpose of the component is to measure the histogram of ADC samples. The Python script
+try_histogram.py shows examples of histograms for typical ADC input signals:
+
+ 
+
+2) Requirements
+
+a) Data format
+The ADC samples arrive in a stream with the following fields:
+
+- data  : the samples
+- valid : new sample at this clock cycle
+- sync  : periodic trigger that defines the measurement interval
+
+b) Data width
+The samples have g_data_w bits, so in total there can be c_data_span = 2**g_data_w values
+
+c) Number of bins
+The histogram has g_nof_bins bins where g_nof_bins is a power of 2 and g_nof_bins <= c_data_span,
+so that c_data_span / g_nof_bins is an integer.
+
+d) Valid data
+Only samples that have valid = '1' contribute to the histogram
+
+e) Update interval
+The sync signal marks the end of the current histogram measurement and the start of a new 
+histogram measurement. At the sync all bin counts for the new sync interval are reset. During a
+sync interval for each valid input sample the corresponding bin count is incremented. At the sync
+the completed histogram measurements are preserved, so that they can be read via the M&C interface.
+
+f) Bin count width
+Typically the sync interval will be t_hist = 1 s and a clock rate of e.g. f_clk = 200 MHz, so then
+g_nof_data = f_clk / t_hist = 200e6. For a DC signal one bin can contain all counts, so the bin
+counts need a size of ceil_log2(g_nof_data) bits, e.g. c_bin_w = ceil_log2(200e6) = 28 bits. At
+the M&C interface the typical data width is c_word_w = 32 bits. Assume c_bin_w <= c_word_w = 32.
+
+g) Static parameters
+All parameters are static (i.e. generics in VHDL):
+
+- g_data_w
+- g_nof_bins
+- g_nof_data
+
+There are no dynamic parameters (i.e. paramters that could be controlled via the M&C interface).
+
+h) Monitoring (M&C)
+There is no control interface, because there are no dynamic parameters to set.
+The monitoring interface allows reading the preserved histogram measurements of the last
+measurement sync interval.
+
+
+
+3) Design
+The histogram function is a statistics function and therefor it can be placed in the st/ HDL 
+library ($GIT/libraries/dsp/st/) and called st_histogram.vhd.
+
+The histogram component will need a double buffer. One buffer contains the bin counts that are 
+being updated during the current sync interval and the other buffer contains the bin counts
+that were preserved from the previous sync interval. The buffer is a block RAM. The highest 
+W bits of the input data are used as address to read the bin counter from the buffer, then 
+increment the bin counter, and then write the bin counter back into the buffer. This scheme
+resembles the approach that is used in the st_sst.vhd power statistics function in the ST
+library. 
+
+The st_sst can integrate input samples continously without skipping samples. For the
+st_histogram it is probably not possible to count all input samples, because at the sync the
+bin counts for the last interval need to be preserved and the bin counts for the new interval
+have to be initialized to 0. Therefore it is allowed that the first g_nof_bins valid input
+samples of a sync interval are skipped. A sync interval has g_nof_data samples, so if 
+g_nof_data >> g_nof_bins, then it is acceptable to skip g_nof_bins input samples. For eaxmple
+with g_nof_data = 200e6 and g_nof_bins = 512 this is true. The difference between st_sst and
+st_histogram is that st_sst uses a regular index to address the bins whereas the st_histogram
+uses the arbitrary input data value as index. Hence with st_histogram many addresses will not
+occur during the first g_nof_bin samples of a sync interval and some addresses may not occur
+during a entire sync interval (because these data values do not occur), but still the bin
+count at all addresses has to be cleared at the start of the sync interval.
+
+
+
+4) Development
+
+All coding should be done on a branch in $GIT/hdl.
+
+a) In simulation
+   - implement the st_histogram.vhd and a corresponding testbench tb_st_histogram.vhd
+   - can use counter signal as test input or waveform generator (WG) to generate a sinus input.
+     The diag HDL library contains a WG.
+
+b) On hardware
+   - create a design based on the UniBoard board support package (BSP = unb_minimal) with a diag
+     WG and the st_histogram.vhd both connected to the MM bus.
+   - on a PC use a new Python script to read the histogram values and plot them.
+   - on a PC use an existing Python script to control the WG.
+   
+
+
+5) References
+
+a) $GIT/hdl/libraries/dsp/st/python/try_histogram.py
+b) $GIT/libraries/dsp/st/doc/ASTRON_RP_1397_Subband_Statistics_module.pdf  -- st_sst
+c) $GIT/libraries/base/common/src/vhdl/common_paged_ram_r_w.vhd  -- dual page buffer
+d) $GIT/libraries/base/diag/src/vhdl/mms_diag_wg_wideband.vhd   -- WG
+e) $GIT/libraries/base/dp/doc/ASTRON_RP_380_module_interface_records.pdf  -- streaming data (SOSI)

libraries/dsp/st/python/try_histogram.py

+###############################################################################
+#
+# Copyright 2019
+# ASTRON (Netherlands Institute for Radio Astronomy) <http://www.astron.nl/>
+# P.O.Box 2, 7990 AA Dwingeloo, The Netherlands
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+###############################################################################
+
+# Author: Eric Kooistra
+
+"""Try histogram
+
+Usage:
+> python try_histogram.py
+
+"""
+
+import numpy as np
+import matplotlib.pylab as plt
+
+figNr = 1
+
+# Parameters
+Nbins = 100
+dc = 0
+mu = 100
+sigma = 15
+
+# Sinus
+N = Nbins * 100
+t = 2 * np.pi * np.arange(0, N) / N
+a = dc + np.sin(t)
+
+# Plot histogram
+plt.figure(figNr)
+plt.hist(a, bins=Nbins)
+plt.xlabel('Sample values')
+plt.ylabel('Occurance')
+plt.title('Sinus (%d values)' % N)
+plt.grid(True)
+figNr += 1
+
+# Gaussian noise
+x = mu + sigma * np.random.randn(N)
+
+# Plot histogram
+plt.figure(figNr)
+plt.hist(x, bins=Nbins)
+plt.xlabel('Sample values')
+plt.ylabel('Occurance')
+plt.title('Gaussian noise (%d values)' % N)
+plt.grid(True)
+figNr += 1
+
+# Show plots
+plt.show()
+
+
+