Devel/v3 refactoring (paulscherrerinstitute#50)

* added refactoring scripts

* codebase refactor for version 3

* REFACTORING: remove tab and trailing white space

* REFACTORING: HDL done and documentation started

* DOC: refactoring md files architecture step 1

* REFACTORING: HDL done todo documentation

* FEATURE: added parse_library script for refactoring

* FEATURE: added blacklist option to parse_library.py

* toto

* REFACTOR: snake_case refacroring entire library

* CLEANUP: code cleaning

* CLEANUP

* DOC: missing link doc

* FEATURE: Add PWM block

* RELEASE: Add changelog and REAMDME

* DOC: errate correction on link

---------

Co-authored-by: Radoslaw Rybaniec <[email protected]>

Changelog.md

@@ -1,3 +1,10 @@
+## 3.0.0
+* Cleaning
+  * All codes have been unified for better readibility and all tabs have been removed 
+  * new script added to update your current project and replace instantiation with json database file
+* Added Features
+  * Added *psi\_common\_pwm*
+
 ## 2.17.1
 * Bugfixes
   * Merge: psi_common_tdm_par_fill merged to psi_common_tdm_par 

README.md

@@ -1,5 +1,8 @@
 # General Information
 
+New release of library to enhance readibility and unifying code through all files, new documentation organization.
+This version is not backward compatible but a script is given to help user to adapt code to new release.
+
 ## Maintainer
 Benoît Stef [[email protected]]
 
@@ -57,7 +60,7 @@ Alternatively the repository [psi\_fpga\_all](https://github.com/paulscherrerins
   * [PsiSim](https://github.com/paulscherrerinstitute/PsiSim) (2.1.0 or higher)
 * VHDL
   * [**psi\_common**](https://github.com/paulscherrerinstitute/psi_common)
-  * [psi\_tb](https://github.com/paulscherrerinstitute/psi_tb) (2.6.0 or higher)
+  * [psi\_tb](https://github.com/paulscherrerinstitute/psi_tb) (3.0.0 or higher)
 
 <!-- END OF PARSED SECTION -->
 

doc/README.md

@@ -0,0 +1,146 @@
+<img align="right" src="psi_logo.png">
+
+***
+## Introduction
+
+[read me first](old/ch1_introduction/ch1_introduction.md)
+
+**Quick syntax rules to push into the library:**
+
+ - **snake_case**
+ - remove **tab to white space**
+ - use of suffix for entity's signal following simple rules: **_i, _o and _io** respectively for input, output and inout
+ - entity, architecture, package, procedure, function, etc... ends as such: **end entity; end architecture,** etc...
+ - use of prefix to gather signal corresponding to same interface like: **adc**_clk_i, **adc**_data_i, **adc**_vld_i...
+ - name of architecture: **behav, struc, rtl**
+ - when strcutural architecture would be nice to link components with signal's prefixe name such as: fifo2filter_*  (e.g. component A to component B: compa2compb_)
+
+## 	Packages
+
+###	psi_common_array_pkg
+
+This package defines various array types that are not defined by VHDL natively. Some of these definitions are no more required in VHDL 2008 but since VHDL 2008 is not yet fully synthesizable, the package is kept.
+
+### psi_common_logic_pkg
+
+This package contains various logic functions (e.g. combinatorial conversions) that can be synthesized.
+
+###	psi_common_axi_pkg
+
+This package contains record definitions to allow representing a complete AXI interface including all ports by only two records (one in each direction). This helps improving the readability of entities with AXI interfaces.
+
+### psi_common_math_pkg
+
+This package contains various mathematical functions (e.g. log2). The functions are meant for calculating compile-time constants (i.e. constants, port-widths, etc.). They can potentially be synthesized as combinatorial functions but this is neither guaranteed nor will it lead to optimal results.
+
+## List of components available
+
+
+### Memory components
+
+Component 				                      | Source                                                      | Description
+----------------------------------------|-------------------------------------------------------------|:-------------------------------------------:
+Simple dual port RAM 										| [psi_common_sdp_ram.vhd](../hdl/psi_common_sdp_ram.vhd)	 		 	| [link](files/psi_common_sdp_ram.md)
+Simple dual port RAM with byte enable  	| [psi_common_sp_ram_be.vhd](../hdl/psi_common_sp_ram_be.vhd)    | [link](files/psi_common_sp_ram_be.md)
+True Dual port RAM  										| [psi_common_tdp_ram.vhd](../hdl/psi_common_tdp_ram.vhd)	  		| [link](files/psi_common_tdp_ram.md)
+True dual port RAM with byte enable  		| [psi_common_tdp_ram_be.vhd](../hdl/psi_common_tdp_ram_be.vhd)	| [link](files/psi_common_tdp_ram.md)
+
+***
+
+### FIFO components
+Component     				  | Source                                                      | Description
+------------------------|-------------------------------------------------------------|:-------------------------------------------:
+Asynchronous FIFO 			| [psi_common_async_fifo.vhd](../hdl/psi_common_async_fifo.vhd)	| [link](files/psi_common_async_fifo.md)
+Synchronous FIFO  			| [psi_common_sync_fifo.vhd](../hdl/psi_common_sync_fifo.vhd)    | [link](files/psi_common_sync_fifo.md)
+
+***
+
+### Clock domain crossing (CDC) components
+Component     					| Source                                                      | Description
+------------------------|-------------------------------------------------------------|:-------------------------------------------:
+Pulse clock crossing  (asynchronous pulse/vld transfer)	| [psi_common_pulse_cc.vhd](../hdl/psi_common_pulse_cc.vhd)   	  | [link](files/psi_common_pulse_cc.md)
+Simple clock crossing (asynchronous data value transfer) | [psi_common_simple_cc.vhd](../hdl/psi_common_simple_cc.vhd)   	  | [link](files/psi_common_simple_cc.md)
+Status clock crossing (asynchronous slow changing value transfer) | [psi_common_status_cc.vhd](../hdl/psi_common_status_cc.vhd) | [link](files/psi_common_status_cc.md)
+Synchronous CDC with AXI-S handshaking from **Lower** clock to **Higher** multiple integer clock frequency  | [psi_common_sync_cc_n2xn.vhd](../hdl/psi_common_sync_cc_n2xn.vhd)  |  [link](files/psi_common_sync_cc_n2xn.md)
+Synchronous CDC with AXI-S handshaking from **Higher** clock to **lower** multiple integer clock frequency  | [psi_common_sync_cc_xn2n.vhd](../hdl/psi_common_sync_cc_xn2n.vhd)   |  [link](files/psi_common_sync_cc_xn2n.md)
+Bit CDC  | [psi_common_bit_cc.vhd](../../hdl/psi_common_bit_cc.vhd)   | [link](files/psi_common_bit_cc.md)
+
+##### Other components that can be used as cdc
+- [psi_common_tdp_ram](files/psi_common_tdp_ram.md)
+- [psi_common_async_fifo](files/psi_common_async_fifo.md)
+
+***
+
+### Conversions components
+Component     				  | Source                                                      | Description
+------------------------|-------------------------------------------------------------|:-------------------------------------------:
+Data width conversion from a N-bits to a multiple N-bits 		| [psi_common_wconv_n2xn.vhd](../hdl/psi_common_wconv_n2xn.vhd)	| [link](files/psi_common_wconv_n2xn.md)
+Data width conversion from a multiple N-bits to a N-bits  	| [psi_common_wconv_x2nn.vhd](../hdl/psi_common_wconv_xn2n.vhd)    | [link](files/psi_common_wconv_xn2n.md)
+
+***
+
+### Time Division Multiplexing (TDM) data Handling components
+Component 					    | Source                                                      | Description
+------------------------|-------------------------------------------------------------|:-------------------------------------------:
+TDM data to parallel  	| [psi_common_tdm_par.vhd](../hdl/psi_common_tdm_par.vhd)   	|  [link](files/psi_common_tdm_par.md)
+Parallel to TDM data  	| [psi_common_par_tdm.vhd](../hdl/psi_common_par_tdm.vhd)  		|  [link](files/psi_common_par_tdm.md)
+TDM data to Parallel with configurable valid output channel number  |   [psi_common_tdm_par_cfg.vhd](../hdl/psi_common_tdm_par_cfg.vhd)  				|  [link](files/psi_common_tdm_par_cfg.md)
+TDM data multiplexer    | [psi_common_tdm_mux.vhd](../hdl/psi_common_tdm_mux.vhd)  | [link](files/psi_common_tdm_mux.md)
+Parallel to TDM with configurable valid output output channel |  [psi_common_par_tdm_cfg.vhd](../hdl/psi_common_par_tdm_cfg.vhd)  				|  [link](files/ch8_5_par_tdpsi_common_par_tdm_cfgm_cfg.md)
+TDM data to parallel with last support and completion  	| [psi_common_tdm_par_fill.vhd](../hdl/psi_common_tdm_par_fill.vhd)   			|  [link](files/psi_common_tdm_par_fill.md)
+***
+
+### Arbiters components
+Component					  | 									Source                                    | Description
+--------------------|-------------------------------------------------------------|:----------------------------------------:
+Priority  					| [psi_common_arb_priority.vhd](../hdl/psi_common_arb_priority.vhd)   | [link](files/psi_common_arb_priority.md)
+Round robin  			  | [psi_common_arb_round_robin.vhd](../hdl/psi_common_arb_round_robin.vhd)   | [link](files/psi_common_arb_round_robin.md)
+
+***
+
+### Interfaces components
+Package   								| 									Source                                    						  	| Description
+--------------------------|-----------------------------------------------------------------------------|:----------------------------------------:
+SPI master  							| [psi_common_spi_master.vhd](../hdl/psi_common_spi_master.vhd)   					  | [link](files/psi_common_spi_master.md)
+SPI master configurable width  | [psi_common_spi_master_cfg.vhd](../hdl/psi_common_spi_master_cfg.vhd)  		  |  [link](files/psi_common_spi_master_cfg.md)
+I2C master  							| [psi_common_i2c_master.vhd](../hdl/psi_common_i2c_master.vhd)   						| [link](files/psi_common_i2c_master.md)
+AXI master Simple   			| [psi_common_axi_master_simple.vhd](../hdl/psi_common_axi_master_simple.vhd) | [link](files/psi_common_axi_master_simple.md)
+AXI master Full  	  			| [psi_common_axi_master_full.vhd](../hdl/psi_common_axi_master_full.vhd) 		| [link](files/psi_common_axi_master_full.md)
+AXI slave IP (32 bits)	  | [psi_common_axi_slave_ipif.vhd](../hdl/psi_common_axi_slave_ipif.vhd)   		| [link](files/psi_common_axi_slave_ipif.md)
+AXI slave IP (64 bits)	  | [psi_common_axi_slave_ipif64.vhd](../hdl/psi_common_axi_slave_ipif64.vhd)   	 | N.A
+AXI multi pipeline stage  | [psi_common_axi_multi_pl_stage.vhd](../hdl/psi_common_axi_multi_pl_stage.vhd)  | N.A
+AXI slave Lite IP					| [psi_common_axilite_slave_ipif.vhd](../hdl/psi_common_axilite_slave_ipif.vhd)|[link](files/psi_common_axilite_slave_ipif.md)
+***
+
+### miscellaneous components
+Component         		      | Source                                                      | Description
+----------------------------|-------------------------------------------------------------|:-------------------------------------------:
+Delay settable via generics	| [psi_common_delay.vhd](../hdl/psi_common_delay.vhd)					| [link](files/psi_common_delay.md)
+Pipeline stage  			    	| [psi_common_pl_stage.vhd](../hdl/psi_common_pl_stage.vhd)   | [link](files/psi_common_pl_stage.md)
+Multi pipeline stage      	| [psi_common_multi_pl_stage.vhd](../hdl/psi_common_multi_pl_stage.vhd)   | [link](files/psi_common_multi_pl_stage.md)
+Sizable Ping pong buffer // & tdm (interface to stream continuously data into DPRAM)  	        | [psi_common_ping_pong.vhd](../hdl/psi_common_ping_pong.vhd) | [link](files/psi_common_ping_pong.md)
+Delay settable via register | [psi_common_delay_cfg.vhd](../hdl/psi_common_delay_cfg.vhd) | [link](files/psi_common_delay_cfg.md)
+Generic Watchdog 						| [psi_common_watchdog.vhd](../hdl/psi_common_watchdog.vhd)   | [link](files/psi_common_watchdog.md)
+Don't optimize (Xilinx) allows evaluating synthesis  | [psi_common_dont_opt.vhd](../hdl/psi_common_dont_opt.vhd)   | [link](files/psi_common_dont_opt.md)
+Generic Debouncer  					| [psi_common_debouncer.vhd](../hdl/psi_common_debouncer.vhd)  | [link](files/psi_common_debouncer.md)
+Analog Trigger Generator  	| [psi_common_trigger_analog.vhd](../hdl/psi_trigger_analog.vhd)  | [link](files/psi_trigger_analog.md)
+Digital Trigger Generator  	| [psi_common_trigger_digital.vhd](../hdl/psi_trigger_digital.vhd)  | [link](files/psi_trigger_digital.md)
+Dynamic Shifter             | [psi_common_dyn_sft.vhd](../hdl/psi_common_dyn_sft.vhd)     | [link](files/psi_common_dyn_sft.md)
+Pulse/Ramp generator        | [psi_common_ramp_gene.vhd](../hdl/psi_common_ramp_gene.vhd)     | [link](files/psi_common_ramp_gene.md)
+Pulse generator ctrl static | [psi_common_pulse_generator_ctrl_static.vhd](../hdl/psi_common_pulse_generator_ctrl_static.vhd)     | [link](files/psi_common_pulse_generator_ctrl_static.md)
+Parallel to serial  				| [psi_common_par_ser.vhd](../hdl/psi_common_par_ser.vhd)   | [link](files/psi_common_par_ser.md)
+Serial to parallel  				| [psi_common_ser_par.vhd](../hdl/psi_common_ser_par.vhd)   | [link](files/psi_common_ser_par.md)
+Find Min Max  							| [psi_common_find_min_max.vhd](../hdl/psi_common_find_min_max.vhd)   | [link](files/psi_common_find_min_max.md)
+Min Max Sum  						   	| [psi_common_find_min_max.vhd](../hdl/psi_common_min_max_sum.vhd)   | [link](files/psi_common_min_max_sum.md)
+PRBS  						  		  	| [psi_common_prbs.vhd](../hdl/psi_common_prbs.vhd)   | [link](files/psi_common_prbs.md)    
+PWM   						  		  	| [psi_common_pwm.vhd](../hdl/psi_common_pwm.vhd)   | [link](files/psi_common_pwm.md)     |  
+***
+
+### Packages
+
+Package    					| 									Source                                    |
+--------------------|-------------------------------------------------------------|
+Math  							| [psi_common_math_pkg.vhd](../hdl/psi_common_math_pkg.vhd)	 	|
+array 							| [psi_common_array_pkg.vhd](../hdl/psi_common_array_pkg.vhd) |
+logic								| [psi_common_logic_pkg.vhd](../hdl/psi_common_logic_pkg.vhd)	|
+AXI 							  | [psi_common_axi_pkg.vhd](../hdl/psi_common_axi_pkg.vhd)			|

doc/files/psi_common_arb_priority.md

@@ -0,0 +1,42 @@
+<img align="right" src="../psi_logo.png">
+
+***
+
+[**component list**](../README.md)
+
+# psi_common_arb_priority
+ - VHDL source: [psi_common_arb_priority](../../hdl/psi_common_arb_priority.vhd)
+ - Testbench source: [psi_common_arb_priority_tb.vhd](../../testbench/psi_common_arb_priority_tb/psi_common_arb_priority_tb.vhd)
+
+### Description
+
+This entity implements a priority arbiter. The left-most bit (highest bit) of the request vector that was asserted is granted (i.e. asserted in the grant vector). The arbiter is implemented using the very logic-
+and timing-efficient parallel prefix computation approach.
+
+The arbiter can be implemented with or without an output register. The waveform below shows its implementation without output register (*OutputRegister\_g = false*), since the delay would make the waveform less easy to read.
+
+<p align="center"><img src="psi_common_arb_priority_fig0.png"></p>
+
+### Generics
+| Name      | type      | Description         |
+|:----------|:----------|:--------------------|
+| size_g    | natural   | Size of the arbiter (number of input/output bits)
+| out_reg_g | boolean   | True = Registered output False = Combinatorial output
+| rst_pol_g | std_logic | reset polarity
+
+### Interfaces
+| Name    | In/Out   | Length   | Description                |
+|:--------|:---------|:---------|:---------------------------|
+| clk_i   | i        | 1        | Clock
+| rst_i   | i        | 1        | Reset (high active)
+| req_i   | i        | size_g   | Request input signals, The highest (left-most) bit has highest priority
+| grant_o | o        | size_g   | Grant output signal                       
+
+
+Parallel prefix computation is used to calculate a vector that contains a '1' on the highest-priority bit that was asserted and on all bits with lower priority. The vector then looks for example like this "0001111". The bit to assert in the *Grant* output can then be determined by finding the 0-1 edge inside that vector.
+
+The figure below shows the parallel prefix computation graphically.
+
+<p align="center"><img src="psi_common_arb_priority_fig1.png"></p>
+
+[**component list**](../README.md)

doc/files/psi_common_arb_round_robin.md

@@ -0,0 +1,39 @@
+<img align="right" src="../psi_logo.png">
+
+***
+
+[**component list**](../README.md)
+
+# psi_common_arb_round_robin
+ - VHDL source: [psi_common_arb_round_robin](../../hdl/psi_common_arb_round_robin.vhd)
+ - Testbench source: [psi_common_arb_round_robin_tb.vhd](../../testbench/psi_common_arb_round_robin_tb/psi_common_arb_round_robin_tb.vhd)
+
+### Description
+
+This entity implements a round-robin arbiter. If multiple bits are asserted in the request vector, the left-most bit is forwarded to the grant vector first. Next, the second left-most bit that is set is forwarded etc. Whenever at least one bit in the *Grant* vector is asserted, the *Grant\_Vld* handshaking signal is asserted to signal that a request was granted. The consumer of the *Grant* vector signalizes that the granted access was executed by pulling *Grant\_Rdy* high.
+
+Note that the round-robin arbiter is implemented without an output register. Therefore combinatorial paths between input and output exist and it is recommended to add a register-stage to the output as early as possible.
+
+<p align="center"><img src="psi_common_arb_round_robin_fig0.png"></p>
+
+Especially interesting is the part in orange. At this point the arbiter does not grant access to bit 3 because it already granted this request in the clock cycle before. However, it continues to grant access to the highest-priority (i.e. left-most) bit of the request vector that is still left of the bit set in the last *Grant* output. If the request vector asserts a higher priority this change is directly forwarded to the output. This is shown
+in the orange section of the waveform.
+
+### Generics
+| Name      | type      | Description      																  |
+|:----------|:----------|:--------------------------------------------------|
+| size_g    | natural   | Size of the arbiter (number of input/output bits) |
+| rst_pol_g | std_logic | reset polarity             											  |
+
+### Interfaces
+| Name        | In/Out   | Length   | Description                |
+|:------------|:---------|:---------|:---------------------------|
+| clk_i       | i        | 1        | Clock
+| rst_i       | i        | 1        | reset   
+| request_i   | i        | size_g   | Request input signals, The highest(left-most) bit has highest priority  
+| grant_o     | o        | size_g   | Grant output signal                       
+| grant_rdy_o | i        | 1        | AXI-S handshaking signal, Asserted whenever Grant != 0
+| grant_vld_o | o        | 1        | AXI-S handshaking signal The state of the  arbiter is updated  upon *Grant\_Rdy =   '1'*
+
+
+[**component list**](../README.md)