(doc) Update & improve documentation

README.adoc

+// Referencing the true README inside the modules.
+// This README on the front page just includes it.
+
+:imagesdir: doc/images
+
 include::doc/main.adoc[]
+

doc/main.adoc

@@ -6,11 +6,11 @@
 
 // ================================================================================
 == Description
+
 This module can generate sine waveform for multiple power supplies.
+It takes a stream of (PSCID, value) pair, computes the sine waveform signal and adds it to the value.
 It is built to work in association with ComCorr IP.
 
-The module outputs waveform as signed values on its TDATA output.
-The TUSER output carries the Identifier of the waveform.
 
 It is possible to generate up to `2**C_W_TIDX` (default 255) Identifiers.
 Each waveform has independents parameters:
@@ -25,11 +25,55 @@ The module generate data values every `TICKER_RATE` clock period.
 At each of this tick, the phase of all waveform is incremented and a new wave value is computed for each waveform.
 The values are output via the AXI-Stream Output, one value transaction by transfer.
 
+== Overview
+
+The module is a pipeline of blocks that compute the sine signal waveform for each PSCID.
+
+For a given PSCID, the basic scheme is
+* A phase accumulator increment each times this PSCID is at the input.
+* The increment value is user programmed, a constant phase can be added.
+* The DDS convert the phase to a normalized sine signal.
+* The sine signal is amplified and offset by user values.
+
+image::overview.png[Overview of the system]
+
+// ================================================================================
+== Detailed view
+
+=== Multi Phase Table
+
+This is basically a memory, addressed by the PSCID and retaining user settings for phase increment and phase offset.
+Upon reception of a PSCID, it pushes these settings to the pipeline, alongside the PSCID value.
+
+It is possible to source this block with a counter that send burst of PSCID value at a given rate.
+This allows generation of value even if there is no input stream, ie for test purpose
+
+=== Multi Phase Acc
+
+This bloc is a set of accumulator.
+Upon reception of a PSCID and phase increment & offset, it retrieves the last value of the accumulator, offset it and pushes it to the stream with the PSCID.
+This value is incremented and strored again for the next iteration.
+
+=== DDS
+
+A simple sine DDS. Xilinx core.
+
+=== Scaler
+
+This bloc receive the signal value and PSCID.
+From the PSCID it lookup for the scaling and offset factor to apply to the signal.
+
+The output of the DDS is multiplied by the scale, which is considered as a fixed point value, containing only decimals.
+(The DDS is configured to generate full scale sine values).
+The signal offset is then applied, aligned on the fixed point (no decimals).
+The final result is scrapped of decimals values.
+
 // ================================================================================
 == Runtime configuration
-The generator will compute and ouput values for Identifier from `TABLE_DEPTH` downto 0.
-Entries in the `TABLE_PHASE` and `TABLE_SCALE` for these Identifier shall be configured by the user.
-These two tables are addressed by the Identifier number.
+
+The generator will compute and ouput values from the PSCID at the input.
+Entries in the `TABLE_PHASE` and `TABLE_SCALE` for these PSCID shall be configured by the user.
+These two tables are addressed by the PSCID number.
 Data values pack configuration, as described below.
 
 .TABLE_PHASE_INCR data pack.
@@ -50,23 +94,15 @@ Data values pack configuration, as described below.
 | unused | Signal Offset | Signal Scale Factor
 |===
 
-The DDS contained in the module receive the phase value, computed from the sum of the accumulator and the *Phase Offset* configuration.
-The accumulator is incremented by the *Phase Increment* at each tick.
-The result roll over the max value.
-
-The output of the DDS is multiplied by the *Signal Scale Factor*, which is considered as a fixed point value, containing only decimals.
-(The DDS is configured to genrate full scale sine values).
-The *Signal Offset* is then applied, aligned on the fixed point (no decimals).
-The final result is scrapped of decimals values.
-
 // ================================================================================
 == AXIS output format
 The generator produces AXIS packets with a compatible format for COMCORR IP module.
 
 The AXIS contains:
 
-* TDATA: the sine waveform value (signed integer).
-* TUSER: the PSCID.
+* TDATA_VALUE: the sine waveform value (signed integer).
+* TDATA_PSCID: the PSCID.
+* TUSER: TUSER of input, delayed to stay in phase with data.
 * TVALID: data strobe.
 
 The AXIS **does not** contain **TREADY** input on this module.

doc/registers.adoc

-.Register
+.Registers
 [.tab-addr-reg,cols="5,1,1,2,1,9"]
 |===
 |Name | N | bits | type | RW | Description
 
-| ID                                       |    1 |   32 | uint |   RO | +++Module Identification Number+++  
-| VERSION                                  |    1 |   32 | uint |   RO | +++Module Version Number+++  
-| CONTROL                                  |    1 |    1 | uint |   RW | +++Control register+++  
-| TICKER_RATE                              |    1 |   32 | uint |   RW | +++Ticker rate register+++  
-| TABLE_DEPTH                              |    1 |    8 | uint |   RW | +++Table scan depth register+++  
+| ID                                       |    1 |   32 |     uint | RO | +++Module Identification Number+++ +
+| VERSION                                  |    1 |   32 |     uint | RO | +++Module Version Number+++ +
+| CONTROL                                  |    1 |    2 |     uint | RW | +++Control register+++ +
+    _enable_ticker_ [0:0] sw:RW uint : ++++++ +
+    _enable_input_ [1:1] sw:RW uint : ++++++ +
+| TICKER_RATE                              |    1 |   32 |     uint | RW | +++Ticker rate register+++ +
+| TABLE_DEPTH                              |    1 |    8 |     uint | RW | +++Table scan depth register+++ +
 |===
 
 .Memories
-[.tab-addr-mem,cols="5,2,1,2,1,8"]
+[.tab-addr-reg,cols="5,1,1,2,1,9"]
 |===
 |Name | N | bits | type | RW | Description
 
-| TABLE_PHASE_INCR                             |  256      |   31 | uint |   RW | +++Phase increment table+++ 
-| TABLE_PHASE_OFFS                             |  256      |   31 | uint |   RW | +++Phase offset and reset table+++ 
-| TABLE_SCALE                                  |  256      |   32 | uint |   RW | +++Signal scale and offset table+++ 
+| TABLE_PHASE_INCR                         |  256 |   32 | uint | RW | +++Phase increment table+++ +
+| TABLE_PHASE_OFFS                         |  256 |   32 | uint | RW | +++Phase offset and reset table+++ +
+| TABLE_SCALE                              |  256 |   32 | uint | RW | +++Signal scale and offset table+++ +
 |===