wip: Set version based on CORE_VERSION

docs/user_guide/ip_cores/creating_new_ip.rst

@@ -13,7 +13,7 @@ and ``axi_led_control_intel`` for Intel.
 Verilog File
 --------------------------------------------------------------------------------
 
-Lets say you want to make a new IP with the name ``<module_name>``.
+Let's say you want to make a new IP with the name ``<module_name>``.
 You must edit the verilog file so that it has the same name (e.g. ``axi_led_control.v``).
 After that, feel free to write the verilog code for your purpose.
 You can also use other instances of modules, but be sure to include them after,
@@ -177,9 +177,9 @@ Examples:
 Importing with Using Method
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The ``USING`` method allows to look-up a register map to import register and
+The ``USING`` method allows looking up a register map to import register and
 fields.
-A register map can look-up multiple register maps by repeating the method for
+A register map can look up multiple register maps by repeating the method for
 each register map, for example:
 
 .. code::
@@ -235,7 +235,7 @@ Some considerations:
 
 * Imported registers shall have non-imported fields, for example, when importing
   a register that is reserved for custom implementation.
-* Imported fields must be inside a imported register, since the field name is not
+* Imported fields must be inside an imported register, since the field name is not
   unique.
 * Multiple fields can be imported from a single ``FIELD`` group.
 * Multiple register maps can be used for lookup. Add each in a different ``USING``
@@ -287,6 +287,32 @@ use the generic adc/dac templates that include all available registers:
 * :git-hdl:`docs/regmap/adi_regmap_axi_adc_template.txt`
 * :git-hdl:`docs/regmap/adi_regmap_axi_dac_template.txt`
 
+Versioning
+--------------------------------------------------------------------------------
+
+IP cores versions should follow `Semantic Versioning <https://semver.org/>`
+``v<major>.<minor>.<patch>`` format.
+A fix increases the patch number, a feature the minor number, and a breaking
+change the major number. The first stable release version should be higher or
+equal to v1.0.0.
+
+Device tree compatible take the major number prefixed by ``v``, for example,
+for *axi_my_ip* v1.2.3, the *compatible* is *adi,axi-my-ip-v1* and the
+*dt-binding* filename is *adi,axi-my-ip.yaml* (no major suffix). Per the last
+paragraph, *adi,axi-my-ip-v0* is **never** appropriate. Software drivers parse
+the ``VERSION`` register for feature handling across versions. The patch number
+shouldn't have to be handled by software drivers, if it seems necessary to,
+consider incrementing the minor number instead.
+
+Due to AMD Xilinx old default IP core version, many IP cores bindings start at
+1.00.a. For compatibility, the patch value is kept, but should be treated as
+decimal instead of character.
+
+The IP-XACT version must have the format ``<major>.<minor>.<patch>``, e.g.
+``1.2.3`` (**no** ``v`` prefix). To set the IP-XACT version based on the
+``CORE_VERSION`` parameter, use the ``set_ip_version_from_file`` method
+(prefixed by each vendor format), passing the file that defines the parameter.
+
 Xilinx
 --------------------------------------------------------------------------------
 
@@ -813,7 +839,7 @@ trying to simulate most of the available options when creating a new IP.
 
       # Generating the IP given as first parameter on the path given as the second
       # parameter. Without the second parameter the IP will be generated in
-      # ./ltt directory and  in the default IP download directory of
+      # ./ltt directory and in the default IP download directory of
       # Lattice Propel Builder (~/PropelIPLocal) if the LATTICE_DEFAULT_PATHS
       # env variable is exported like:
       # 'export LATTICE_DEFAULT_PATHS=1' before running the script or running make.

library/axi_clkgen/axi_clkgen_ip.tcl

@@ -23,6 +23,7 @@ set_property used_in_synthesis false [get_files ./bd/bd.tcl]
 set_property used_in_synthesis false [get_files $ad_hdl_dir/library/scripts/adi_xilinx_device_info_enc.tcl]
 
 adi_ip_properties axi_clkgen
+adi_set_ip_version_from_file "$ad_hdl_dir/library/common/up_clkgen.v"
 adi_ip_bd axi_clkgen "bd/bd.tcl"
 
 set_property company_url {https://wiki.analog.com/resources/fpga/docs/axi_clkgen} [ipx::current_core]

library/axi_clock_monitor/axi_clock_monitor.v

@@ -91,7 +91,9 @@ module axi_clock_monitor #(
 
   // local parameters
 
-  localparam  PCORE_VERSION = 1;
+  localparam [31:0] CORE_VERSION = {16'h0000,     /* MAJOR */
+                                     8'h00,       /* MINOR */
+                                     8'h01};      /* PATCH */
   localparam [7:0] DIV_VALUE = (DIV_RATE == 4'd1) ? "1" :
                                (DIV_RATE == 4'd2) ? "2" :
                                (DIV_RATE == 4'd3) ? "3" :
@@ -192,7 +194,7 @@ module axi_clock_monitor #(
       if (up_rreq_s == 1'b1) begin
         case (up_raddr_i_s[4:0])
           /* Standard registers */
-          5'h00: up_rdata_int <= PCORE_VERSION;
+          5'h00: up_rdata_int <= CORE_VERSION;
           5'h01: up_rdata_int <= ID;
 
           /* Core configuration */

library/axi_clock_monitor/axi_clock_monitor_hw.tcl

@@ -19,6 +19,7 @@ ad_ip_files axi_clock_monitor [list \
   $ad_hdl_dir/library/intel/common/up_rst_constr.sdc \
   axi_clock_monitor.v \
 ]
+ad_set_ip_version_from_file "axi_clock_monitor.v"
 
 # parameters
 

library/axi_clock_monitor/axi_clock_monitor_ip.tcl

@@ -15,6 +15,7 @@ adi_ip_files axi_clock_monitor [list \
   "axi_clock_monitor.v" ]
 
 adi_ip_properties axi_clock_monitor
+adi_set_ip_version_from_file "axi_clock_monitor.v"
 
 set cc [ipx::current_core]
 set_property display_name {AXI Clock Monitor} $cc

library/axi_clock_monitor/axi_clock_monitor_ltt.tcl

@@ -10,9 +10,10 @@ set mod_data [ipl::parse_module ./axi_clock_monitor.v]
 set ip $::ipl::ip
 
 set ip [ipl::add_ports_from_module -ip $ip -mod_data $mod_data]
+set version [ipl::set_ip_version_from_file -file "axi_clock_monitor.v"]
 
 set ip [ipl::general \
-    -vlnv "analog.com:ip:axi_clock_monitor:1.0" \
+    -vlnv "analog.com:ip:axi_clock_monitor:$version" \
     -display_name "ADI AXI clock monitor" \
     -supported_products {*} \
     -supported_platforms {esi radiant} \

library/axi_dmac/axi_dmac_hw.tcl

@@ -56,6 +56,7 @@ ad_ip_files axi_dmac [list \
   axi_dmac.v \
   axi_dmac_constr.sdc \
 ]
+ad_set_ip_version_from_file "axi_dmac_regmap.v"
 
 # Disable dual-clock RAM read-during-write behaviour warning.
 set_qip_strings { "set_instance_assignment -name MESSAGE_DISABLE 276027 -entity axi_dmac_burst_memory" }

library/axi_dmac/axi_dmac_ip.tcl

@@ -54,6 +54,7 @@ adi_ip_infer_mm_interfaces axi_dmac
 adi_ip_ttcl axi_dmac "axi_dmac_constr.ttcl"
 adi_ip_sim_ttcl axi_dmac "axi_dmac_pkg_sv.ttcl"
 adi_ip_bd axi_dmac "bd/bd.tcl"
+adi_set_ip_version_from_file "axi_dmac_regmap.v"
 
 set_property company_url {https://wiki.analog.com/resources/fpga/docs/axi_dmac} [ipx::current_core]
 

library/axi_dmac/axi_dmac_ltt.tcl

@@ -15,8 +15,9 @@ set ip [ipl::general -ip $ip -display_name "AXI_DMA ADI"]
 set ip [ipl::general -ip $ip -supported_products {*}]
 set ip [ipl::general -ip $ip -supported_platforms {esi radiant}]
 set ip [ipl::general -ip $ip -href "https://analogdevicesinc.github.io/hdl/library/axi_dmac/index.html"]
+set version [ipl::set_ip_version_from_file -file "axi_dmac_regmap.v"]
 set ip [ipl::general \
-    -vlnv "analog.com:ip:axi_dmac:1.0" \
+    -vlnv "analog.com:ip:axi_dmac:$version" \
     -category "ADI" \
     -keywords "ADI IP" \
     -min_radiant_version "2023.2" \

library/axi_dmac/axi_dmac_regmap.v

@@ -147,7 +147,9 @@ module axi_dmac_regmap #(
   input [31:0] dbg_ids1
 );
 
-  localparam PCORE_VERSION = 'h00040564;
+  localparam [31:0] CORE_VERSION = {16'h0004,     /* MAJOR */
+                                     8'h05,       /* MINOR */
+                                     8'h64};      /* PATCH */
   localparam HAS_ADDR_HIGH = DMA_AXI_ADDR_WIDTH > 32;
   localparam ADDR_LOW_MSB = HAS_ADDR_HIGH ? 31 : DMA_AXI_ADDR_WIDTH-1;
 
@@ -245,7 +247,7 @@ module axi_dmac_regmap #(
   always @(posedge s_axi_aclk) begin
     if (up_rreq == 1'b1) begin
       case (up_raddr)
-      9'h000: up_rdata <= PCORE_VERSION;
+      9'h000: up_rdata <= CORE_VERSION;
       9'h001: up_rdata <= ID;
       9'h002: up_rdata <= up_scratch;
       9'h003: up_rdata <= 32'h444d4143; // "DMAC"

library/axi_fan_control/axi_fan_control.v

@@ -87,7 +87,7 @@ module axi_fan_control #(
   //local parameters
   localparam [31:0] CORE_VERSION            = {16'h0001,     /* MAJOR */
                                                 8'h00,       /* MINOR */
-                                                8'h61};      /* PATCH */ // 0.0.0
+                                                8'h61};      /* PATCH */
   localparam [31:0] CORE_MAGIC              = 32'h46414E43;    // FANC
 
   localparam        CLK_FREQUENCY           = 100000000;

library/axi_fmcadc5_sync/axi_fmcadc5_sync.v

@@ -117,7 +117,9 @@ module axi_fmcadc5_sync #(
 
   // version
 
-  localparam  [31:0]  PCORE_VERSION = 32'h00040063;
+  localparam [31:0] CORE_VERSION = {16'h0004,     /* MAJOR */
+                                     8'h00,       /* MINOR */
+                                     8'h63};      /* PATCH */
 
   // internal registers
 

library/axi_fmcadc5_sync/axi_fmcadc5_sync_ip.tcl

@@ -17,6 +17,7 @@ adi_ip_files axi_fmcadc5_sync [list \
   "axi_fmcadc5_sync.v" ]
 
 adi_ip_properties axi_fmcadc5_sync
+adi_set_ip_version_from_file "axi_fmcadc5_sync.v"
 
 adi_init_bd_tcl
 adi_ip_bd axi_fmcadc5_sync "bd/bd.tcl"

library/axi_gpreg/axi_gpreg.v

@@ -115,7 +115,9 @@ module axi_gpreg #(
 
   // version
 
-  localparam  [31:0]  PCORE_VERSION = 32'h00040063;
+  localparam [31:0] CORE_VERSION = {16'h0004,     /* MAJOR */
+                                     8'h00,       /* MINOR */
+                                     8'h63};      /* PATCH */
   localparam  integer BUF_ENABLE[7:0] = {BUF_ENABLE_7, BUF_ENABLE_6, BUF_ENABLE_5, BUF_ENABLE_4,
     BUF_ENABLE_3, BUF_ENABLE_2, BUF_ENABLE_1, BUF_ENABLE_0};
 

library/axi_gpreg/axi_gpreg_ip.tcl

@@ -21,6 +21,7 @@ adi_ip_files axi_gpreg [list \
 set_property FILE_TYPE SystemVerilog [get_files "axi_gpreg.v"]
 
 adi_ip_properties axi_gpreg
+adi_set_ip_version_from_file "axi_gpreg.v"
 adi_ip_ttcl axi_gpreg "axi_gpreg_constr.ttcl"
 
 set_property enablement_dependency {spirit:decode(id('MODELPARAM_VALUE.NUM_OF_IO')) > 0} \

library/axi_hdmi_rx/axi_hdmi_rx_ip.tcl

@@ -28,6 +28,7 @@ adi_ip_files axi_hdmi_rx [list \
   "axi_hdmi_rx_core.v" ]
 
 adi_ip_properties axi_hdmi_rx
+adi_set_ip_version_from_file "$ad_hdl_dir/library/common/up_hdmi_rx.v"
 
 set_property company_url {https://wiki.analog.com/resources/fpga/docs/axi_hdmi_rx} [ipx::current_core]
 

library/axi_hdmi_tx/axi_hdmi_tx_hw.tcl

@@ -42,6 +42,7 @@ ad_ip_files axi_hdmi_tx [list \
   axi_hdmi_tx.v \
   axi_hdmi_tx_constr.sdc \
   ]
+ad_set_ip_version_from_file "$ad_hdl_dir/library/common/up_hdmi_tx.v"
 
 # parameters
 

library/axi_hdmi_tx/axi_hdmi_tx_ip.tcl

@@ -31,6 +31,7 @@ adi_ip_files axi_hdmi_tx [list \
   "axi_hdmi_tx.v" ]
 
 adi_ip_properties axi_hdmi_tx
+adi_set_ip_version_from_file "$ad_hdl_dir/library/common/up_hdmi_tx.v"
 
 adi_init_bd_tcl
 adi_ip_bd axi_hdmi_tx "bd/bd.tcl"

library/axi_intr_monitor/axi_intr_monitor.v

@@ -63,7 +63,9 @@ module axi_intr_monitor (
   input   [ 2:0]  s_axi_arprot
 );
 
-  parameter VERSION = 32'h00010000;
+  localparam [31:0] CORE_VERSION = {16'h0001,     /* MAJOR */
+                                     8'h00,       /* MINOR */
+                                     8'h00};      /* PATCH */
 
   reg     [31:0]  up_rdata                    = 'd0;
   reg             up_wack                     = 'd0;
@@ -170,7 +172,7 @@ module axi_intr_monitor (
       up_rack <= up_rreq_s;
       if (up_rreq_s == 1'b1) begin
         case (up_raddr_s[3:0])
-          4'h0: up_rdata <= VERSION;
+          4'h0: up_rdata <= CORE_VERSION;
           4'h1: up_rdata <= scratch;
           4'h2: up_rdata <= control;
           4'h3: up_rdata <= {31'h0,interrupt};

library/axi_intr_monitor/axi_intr_monitor_ip.tcl

@@ -13,6 +13,7 @@ adi_ip_files axi_intr_monitor [list \
   "axi_intr_monitor.v" ]
 
 adi_ip_properties axi_intr_monitor
+adi_set_ip_version_from_file "axi_intr_monitor.v"
 
 ipx::infer_bus_interface irq xilinx.com:signal:interrupt_rtl:1.0 [ipx::current_core]
 

library/axi_laser_driver/axi_laser_driver.v

@@ -124,7 +124,7 @@ module axi_laser_driver #(
 
   localparam [31:0] CORE_VERSION = {16'h0001,     /* MAJOR */
                                      8'h00,       /* MINOR */
-                                     8'h61};      /* PATCH */ // 1.00.a
+                                     8'h61};      /* PATCH */
   localparam [31:0] CORE_MAGIC = 32'h4C534452;    // LSDR
 
   assign up_clk = s_axi_aclk;

library/axi_laser_driver/axi_laser_driver_hw.tcl

@@ -27,6 +27,7 @@ ad_ip_files axi_laser_driver [list \
   "axi_laser_driver_constr.sdc" \
   "axi_laser_driver_regmap.v" \
   "axi_laser_driver.v"]
+ad_set_ip_version_from_file "axi_laser_driver.v"
 
 # IP parameters
 

library/axi_laser_driver/axi_laser_driver_ip.tcl

@@ -18,6 +18,7 @@ adi_ip_files axi_laser_driver [list \
   "axi_laser_driver.v"]
 
 adi_ip_properties axi_laser_driver
+adi_set_ip_version_from_file "axi_laser_driver.v"
 adi_ip_ttcl axi_laser_driver "../axi_pulse_gen/axi_pulse_gen_constr.ttcl"
 
 set_property company_url {https://wiki.analog.com/resources/fpga/docs/axi_laser_driver} [ipx::current_core]

library/axi_pulse_gen/axi_pulse_gen.v

@@ -72,7 +72,7 @@ module axi_pulse_gen #(
 
   localparam [31:0] CORE_VERSION = {16'h0000,     /* MAJOR */
                                      8'h01,       /* MINOR */
-                                     8'h00};      /* PATCH */ // 0.01.0
+                                     8'h00};      /* PATCH */
   localparam [31:0] CORE_MAGIC = 32'h504c5347;    // PLSG
 
   // internal signals

library/axi_pulse_gen/axi_pulse_gen_ip.tcl

@@ -21,6 +21,7 @@ adi_ip_files axi_pulse_gen [list \
 
 adi_ip_properties axi_pulse_gen
 adi_ip_ttcl axi_pulse_gen "axi_pulse_gen_constr.ttcl"
+adi_set_ip_version_from_file "axi_pulse_gen.v"
 
 adi_ip_add_core_dependencies [list \
 	analog.com:$VIVADO_IP_LIBRARY:util_cdc:1.0 \

library/axi_pulse_gen/axi_pulse_gen_ltt.tcl

@@ -11,8 +11,10 @@ set ip $::ipl::ip
 
 set ip [ipl::add_ports_from_module -ip $ip -mod_data $mod_data]
 
+set version [ipl::set_ip_version_from_file -file "axi_pulse_gen.v"]
+
 set ip [ipl::general \
-    -vlnv "analog.com:ip:axi_pulse_gen:1.0" \
+    -vlnv "analog.com:ip:axi_pulse_gen:$version" \
     -display_name "ADI AXI Pulse generator" \
     -supported_products {*} \
     -supported_platforms {esi radiant} \

library/axi_pwm_gen/axi_pwm_gen_hw.tcl

@@ -22,6 +22,7 @@ ad_ip_files axi_pwm_gen [list \
   axi_pwm_gen_regmap.sv \
   axi_pwm_gen_1.v \
   axi_pwm_gen.sv]
+ad_set_ip_version_from_file "axi_pwm_gen.sv"
 
 # parameters
 

library/axi_pwm_gen/axi_pwm_gen_ip.tcl

@@ -20,6 +20,7 @@ adi_ip_files axi_pwm_gen [list \
   "axi_pwm_gen.sv"]
 
 adi_ip_properties axi_pwm_gen
+adi_set_ip_version_from_file "axi_pwm_gen.sv"
 adi_ip_ttcl axi_pwm_gen "axi_pwm_gen_constr.ttcl"
 
 set_property company_url {https://wiki.analog.com/resources/fpga/docs/axi_pwm_gen} [ipx::current_core]

library/axi_pwm_gen/axi_pwm_gen_ltt.tcl

@@ -10,9 +10,10 @@ set mod_data [ipl::parse_module ./axi_pwm_gen.sv]
 set ip $::ipl::ip
 
 set ip [ipl::add_ports_from_module -ip $ip -mod_data $mod_data]
+set version [ipl::set_ip_version_from_file -file "axi_pwm_gen.sv"]
 
 set ip [ipl::general \
-    -vlnv "analog.com:ip:axi_pwm_gen:1.0" \
+    -vlnv "analog.com:ip:axi_pwm_gen:$version" \
     -display_name "ADI AXI PWM generator" \
     -supported_products {*} \
     -supported_platforms {esi radiant} \

library/axi_tdd/axi_tdd_hw.tcl

@@ -25,6 +25,7 @@ ad_ip_files axi_tdd [list\
   axi_tdd_sync_gen.sv \
   axi_tdd.sv \
   axi_tdd_constr.sdc]
+ad_set_ip_version_from_file "axi_tdd_pkg.sv"
 
 # parameters
 

library/axi_tdd/axi_tdd_ip.tcl

@@ -21,6 +21,7 @@ adi_ip_files axi_tdd [list \
   "axi_tdd.sv" ]
 
 adi_ip_properties axi_tdd
+adi_set_ip_version_from_file "axi_tdd_pkg.sv"
 adi_ip_ttcl axi_tdd "axi_tdd_constr.ttcl"
 set_property display_name "ADI AXI TDD Controller" [ipx::current_core]
 set_property description "ADI AXI TDD Controller" [ipx::current_core]

library/axi_tdd/axi_tdd_pkg.sv

@@ -41,9 +41,10 @@ package axi_tdd_pkg;
     WAITING = 2'b10,
     RUNNING = 2'b11} state_t;
 
-  localparam
-    PCORE_VERSION = 32'h00020062,
-    PCORE_MAGIC   = 32'h5444444E; // "TDDN", big endian
+  localparam [31:0] CORE_VERSION = {16'h0002,     /* MAJOR */
+                                     8'h00,       /* MINOR */
+                                     8'h62};      /* PATCH */
+  localparam CORE_MAGIC   = 32'h5444444E; // "TDDN", big endian
 
   // register address offset
   localparam

library/axi_tdd/axi_tdd_regmap.sv

@@ -297,10 +297,10 @@ module axi_tdd_regmap #(
       up_rack <= up_rreq;
       if (up_rreq == 1'b1) begin
         case (up_raddr)
-          ADDR_TDD_VERSION         : up_rdata <= PCORE_VERSION;
+          ADDR_TDD_VERSION         : up_rdata <= CORE_VERSION;
           ADDR_TDD_ID              : up_rdata <= ID[31:0];
           ADDR_TDD_SCRATCH         : up_rdata <= up_scratch;
-          ADDR_TDD_IDENTIFICATION  : up_rdata <= PCORE_MAGIC;
+          ADDR_TDD_IDENTIFICATION  : up_rdata <= CORE_MAGIC;
           ADDR_TDD_INTERFACE       : up_rdata <= status_synth_params_s;
           ADDR_TDD_DEF_POLARITY    : up_rdata <= status_def_polarity_s;
           ADDR_TDD_CONTROL         : up_rdata <= {27'b0, up_tdd_sync_soft,