diff --git a/libraries/dsp/st/doc/st_histogram.txt b/libraries/dsp/st/doc/st_histogram.txt new file mode 100644 index 0000000000000000000000000000000000000000..bbb26d12748f450a122045c38ee6e81884178f50 --- /dev/null +++ b/libraries/dsp/st/doc/st_histogram.txt @@ -0,0 +1,116 @@ +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) diff --git a/libraries/dsp/st/python/try_histogram.py b/libraries/dsp/st/python/try_histogram.py new file mode 100644 index 0000000000000000000000000000000000000000..d1949096b638c2aa5593ccbe1feb373a8a7dc295 --- /dev/null +++ b/libraries/dsp/st/python/try_histogram.py @@ -0,0 +1,71 @@ +############################################################################### +# +# 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() + + +