Merge remote-tracking branch 'origin/dev_corrfp' into dev_corrfp

README.adoc

+:imagesdir: doc/images
+include::doc/main.adoc[]

doc/main.adoc

-=  Documentation
+= CORRMATRIX Module
+
+|===
+| MODULE ID | 0x507E1730 | (1350440752)
+|===
+
+
+// ================================================================================
+== Description and overview
+
+This module perform FOFB correction computation:
+* Compute position error from the reference orbit
+* Apply a matrix multiplication to get the error in the corrector space
+* Filter the error for loop control
+* Stream the correction out
+
+image::overview.svg[]
+
+// ================================================================================
+== Details
+
+=== Matrix multiplication
+
+As data are input position by position (both plane simultaneously) it is possible to fetch matrix coefficients one at a time.
+All coefficients are stored in memory, all addressed by the BPM id of the position error at the input.
+Coefficient are mutliplied and accumulated. The result is then rounded and saturated.
+All width, rounding and saturation are declared in the VHDL package.
+
+Matrix multiplication result are output in parallel, all at the same time.
+
+The ID counter is programmed to signal the end of the matrix multiplication when the expected amount of data is received.
+
+image::matmult.svg[]
+
+=== Corrector filter
+
+For each matrix multiplication result, a fixed point IIR filter is implemented.
+It is a second ordrer filter.
+The input and output fixed point representation are the same and its definition does only matter for the rounded output `corrout`, which is `corrout_fp` rounded by `C_W_FP` bits
+Coefficient are represented as fixed points with `C_W_COR_COEF` total bits (with sign) including `C_W_COR_COEFFP` decimal bits (thus the lsb codes `2^C_W_COR_COEFFP`).
+
+Two of these filters are chained to allow a second order filter to be synthesized.
+
+A simple integrate and dump over 1024 points is computed on the output. Its result is outputed when the correction is stopped.
+This allow a "stop to mean" value (and not a stop tu current value).
+
+image::corr_iir.svg[]
+
+// ================================================================================
+== Registers
+
+include::regmap.adoc[]
+
+// ================================================================================
+== Future / TODO
+
+* Add a filter to avoid a duplicated BPM id to be counted in the matrix multiplication

doc/regmap.adoc

+.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_X                                |    1 |    2 |     uint | RW | +++X-plane control of the corrector.+++ +
+    _ENABLE_CORR_ [0:0] sw:RW uint : ++++++ +
+    _RST_CORR_ [1:1] sw:RW uint : ++++++ +
+| CONTROL_Y                                |    1 |    2 |     uint | RW | +++Y-plane control of the corrector.+++ +
+    _ENABLE_CORR_ [0:0] sw:RW uint : ++++++ +
+    _RST_CORR_ [1:1] sw:RW uint : ++++++ +
+| THRESH                                   |    1 |    2 |     uint | RW | +++Theshold autostop.+++ +
+    _ENABLE_ [0:0] sw:RW uint : ++++++ +
+    _RST_ [1:1] sw:RW uint : ++++++ +
+| STATUS                                   |    1 |    1 |     uint | RO | +++Global status of the corrector.+++ +
+| CORR_K1A_X                               |    1 |   17 |    int32 | RW | +++Correction coefficient A.+++ +
+| CORR_K1B_X                               |    1 |   17 |    int32 | RW | +++Correction coefficient B.+++ +
+| CORR_K1IC_X                              |    1 |   17 |    int32 | RW | +++Correction coefficient (inverse) C.+++ +
+| CORR_K1D_X                               |    1 |   17 |    int32 | RW | +++Correction coefficient D.+++ +
+| CORR_K2A_X                               |    1 |   17 |    int32 | RW | +++Correction coefficient A.+++ +
+| CORR_K2B_X                               |    1 |   17 |    int32 | RW | +++Correction coefficient B.+++ +
+| CORR_K2IC_X                              |    1 |   17 |    int32 | RW | +++Correction coefficient (inverse) C.+++ +
+| CORR_K2D_X                               |    1 |   17 |    int32 | RW | +++Correction coefficient D.+++ +
+| CORR_K1A_Y                               |    1 |   17 |    int32 | RW | +++Correction coefficient A.+++ +
+| CORR_K1B_Y                               |    1 |   17 |    int32 | RW | +++Correction coefficient B.+++ +
+| CORR_K1IC_Y                              |    1 |   17 |    int32 | RW | +++Correction coefficient (inverse) C.+++ +
+| CORR_K1D_Y                               |    1 |   17 |    int32 | RW | +++Correction coefficient D.+++ +
+| CORR_K2A_Y                               |    1 |   17 |    int32 | RW | +++Correction coefficient A.+++ +
+| CORR_K2B_Y                               |    1 |   17 |    int32 | RW | +++Correction coefficient B.+++ +
+| CORR_K2IC_Y                              |    1 |   17 |    int32 | RW | +++Correction coefficient (inverse) C.+++ +
+| CORR_K2D_Y                               |    1 |   17 |    int32 | RW | +++Correction coefficient D.+++ +
+| MM_ID_CNT                                |    1 |   16 |   uint16 | RW | +++Number of ID to count for matrix multiplication.+++ +
+| MULT_RATE                                |    1 |   16 |     uint | RO | +++Number of matric multiplication per seconds.+++ +
+|===
+
+
+.Memories
+[.tab-addr-reg,cols="5,1,1,2,1,9"]
+|===
+|Name | N | bits | type | RW | Description
+
+| REFORBITX                                |  256 |   32 | int32 | RW | +++X Reference orbit.+++ +
+| REFORBITY                                |  256 |   32 | int32 | RW | +++Y Reference orbit.+++ +
+| PSCIDTABLE                               |  128 |   32 | uint | RW | +++PSC identifier table.+++ +
+| MATRIXCOEF[100]                          |  256 |   32 | int32 | RW | +++Matrix multiplication coefficients.+++ +
+| ERRORBITX                                |  256 |   32 | int32 | RO | +++X Average orbit error+++ +
+| ERRORBITY                                |  256 |   32 | int32 | RO | +++Y Average orbit error+++ +
+| CORRCMD                                  |  256 |   32 | int32 | RO | +++Average correction, both planes+++ +
+|===
+
+
+
+