Merge pull request #19 from pulp-platform/add_yaml_include_support

Add support for YAML Includes and add modular config example

CHANGELOG.rst

@@ -15,6 +15,7 @@ Unreleased
 
 Added
 -----
+* Added support for modular config file using pyyaml !include directives.
 
 Changed
 -------

docs/config_file.rst

@@ -52,6 +52,12 @@ Configuration File Syntax
   configuration files. Especially the "anchor" and "reference" feature is quite
   usefull for this particular tool since it avoids copy-paste hell.
 
+.. note:: The YAML engine in padrick supports inclusions of external files to
+   modularize your config file. You can e.g. have a common config file to define
+   the peripherals in your system that you combine with your technology specific
+   YAML file. The examples folder contains an example config file that showcases
+   the feature.
+
   At the root, the configuration file contains three key-value pairs:
 
   - name: The name of the pad_frame to generate (usefull if there is more than

examples/kraken_padframe.yml

@@ -1,6 +1,9 @@
-name: kraken_padframe # This name is used as the prefix for all
-                         # auto-generated modules to avoid naming conflicts in
-                         # case multiple padframes are generated.n
+# This is another sample padframe configuration that was used for a real
+# tapeout. However, this config file does not showcase all of the available
+# features of padrick and might implement things in a way that have been made
+# simpler since. Have a look at the 'sample_padframe.yml' file for a more
+# up-to-date example of the config file format and it's features.
+name: kraken_padframe
 manifest_version: 2
 pad_domains:
   - name: aon # User defined name of the pad_domain

examples/modular_config/common_pad_signals.yml

@@ -0,0 +1,41 @@
+# This file defines the common pad signal names used in this project. The reason
+# we want to define these in a common place is, that if we stick to the same
+# signal names regardless the target platform/technology, we can leave the
+# port_groups specification untouched while only changing the pad_types. This
+# means that we should add all the pad signals to this file that might be used
+# in a peripheral connection in the port_groups section. Signals like 'driving
+# strenght' are probably not necessary to add here and are anyway highly
+# technology dependend in their semantic.
+- name: pad
+  size: 1
+  kind: pad
+
+- name: chip2pad
+  description: "Connects to pad's TX driver"
+  size: 1
+  kind: input
+  conn_type: dynamic
+  default_reset_value: 0
+  default_static_value: 1'b0
+
+- name: pad2chip
+  description: "The signal that connects to the pad's RX buffer"
+  size: 1
+  kind: output
+  conn_type: dynamic
+
+- name: rx_en
+  description: "RX enable, active high"
+  size: 1
+  kind: input
+  conn_type: static
+  default_reset_value: 1
+  default_static_value: 1'b1
+
+- name: tx_en
+  description: "TX driver enable, active low"
+  size: 1
+  kind: input
+  conn_type: dynamic
+  default_reset_value: 0
+  default_static_value: 1'b0

examples/modular_config/common_param_muxed_pads_count.yml

@@ -0,0 +1,4 @@
+# This file just defines the number pads that should be generated. It showcases
+# one way how you could automatically adjust the number of IO pads using e.g. a
+# Makefile target to modify this file.
+32

examples/modular_config/common_peripherals.yml

@@ -0,0 +1,77 @@
+# This file defines the peripherals of the SoC. For most SoC designs this file
+# would be completely platform agnostic so it can be shared for various
+# platforms.
+
+- name: gpio
+  output_defaults: 1'b0
+  ports:
+    - name: gpio{i:2d}
+      multiple: !include common_param_muxed_pads_count.yml
+      mux_groups: ["pad_io{i:2d}"]
+      description: "Bidirectional GPIO{i} signal"
+      connections:
+        chip2pad: gpio{i:2d}_out
+        gpio{i:2d}_in: pad2chip
+        tx_en: gpio{i:2d}_tx_en
+
+- name: i2c{i:1d}
+  multiple: 1
+  mux_groups: [all_gpios]
+  output_defaults:
+    sda_i: 1'b1
+    scl_i: 1'b1
+  ports:
+    - name: sda
+      description: "Bidirectional I2C SDA signal"
+      connections:
+        chip2pad: sda_o
+        sda_i: pad2chip
+        tx_en: sda_oe
+
+    - name: scl
+      description: "I2C clock signal"
+      connections:
+        chip2pad: scl_o
+        scl_i: pad2chip
+        tx_en: scl_oe
+
+- name: uart{i:1d}
+  multiple: 1
+  mux_groups: [all_gpios]
+  output_defaults:
+    rx_i: 1'b1
+  ports:
+    - name: rx
+      description: "UART RX signal"
+      connections:
+        chip2pad: 1'b1
+        rx_i: pad2chip
+        tx_en: 1'b0
+    - name: tx
+      description: "UART TX signal"
+      connections:
+        chip2pad: tx_o
+        tx_en: 1'b1
+
+- name: qspim{i:1d}
+  multiple: 1
+  mux_groups: [all_gpios]
+  output_defaults: 1'b0
+  ports:
+    - name: sdio{i:1d}
+      description: "IO data port of the SPI master peripheral"
+      multiple: 4
+      connections:
+        chip2pad: sd{i:1d}_o
+        sd{i:1d}_i: pad2chip
+        tx_en: sd{i:1d}_oe
+    - name: sck
+      connections:
+        chip2pad: sck_o
+        tx_en: 1'b1
+    - name: csn{i:1d}
+      description: "IO data port of the SPI master peripheral"
+      multiple: 4
+      connections:
+        chip2pad: csn{i:1d}_o
+        tx_en: 1'b1

examples/modular_config/modular_config_top.yml

@@ -0,0 +1,27 @@
+# This padframe config showcases how to write modular padframe config files for
+# easier reuse across different technologies or simulation/emulation targets.
+# The basis of it is the usage of the custom YAML directive !include <fle to
+# yaml, toml, ini, csv or txt file>. The directive also supports wildcard
+# inclusion of multiple files. Checkout the documentation of pyyaml-inlcude for
+# the complete syntax "https://pypi.org/project/pyyaml-include/".
+
+# This particular example defines the padframe for Xilinx Virtex 7 FPGAs. For an
+# ASIC version, you could write new my_asic_tech_padtypes.yml and
+# my_asic_tech_pads.yml files, create a copy of this file and change the include
+# paths.
+
+name: modular_padframe 
+manifest_version: 2
+pad_domains:
+  - name: domain
+    # Here we include some technology specific config file. This one defines the
+    # pad templates. If we want to change the technology we could just change
+    # the include path.
+    pad_types: !include xilinx_virtex7_padtypes.yml
+
+    pad_list: !include xilinx_virtex7_pads.yml
+
+    port_groups: !include common_peripherals.yml
+
+
+

examples/modular_config/xilinx_virtex7_pads.yml

@@ -0,0 +1,99 @@
+# This file specifies how many and what kind of pads we have in particular for
+# the FPGA target. Each target platform/technology would specify its own file
+# or, if you always want the same number of pads and muxing structure, you
+# specify one shared file for all platforms and always use the same generic
+# pad_type name (e.g. inout_pad, pull_down_pad etc.). In this example we assume
+# different pad structures for each platform so we use more specific pad type
+# names.
+
+- name: pad_ref_clk
+  description: "32kHz reference clock for on-chip PLLs"
+  pad_type: IBUFGDS
+  is_static: true
+  connections:
+    pad2chip: ref_clk
+
+- name: pad_clk_byp
+  description: |
+    PLL clock bypass enable, active-high. If asserted the PLLs VCO is bypassed
+    and the system uses the ref_clk directly
+  pad_type: IBUF
+  is_static: true
+  connections:
+    pad2chip: clk_byp
+    rx_en: 1'b1
+    tx_en: 1'b0
+
+- name: pad_reset_n
+  description:  |
+    Active-low asynchronous reset. Internally synchronized to rising edge.
+  pad_type: FEEDTHROUGH_INPUT
+  is_static: true
+  connections:
+    pad2chip: rst_n
+    rx_en: 1'b1
+    tx_en: 1'b0
+
+- name: pad_debug_en
+  description: |
+    Debug enable signal. Activates the obversvability of internal MRAM debug
+    signals on IO pads (debug role)
+  pad_type: IBUF
+  is_static: true
+  connections:
+    pad2chip: debug_mode_en
+    rx_en: 1'b1
+    tx_en: 1'b0
+
+- name: pad_jtag_tck
+  description: "JTAG clock input"
+  pad_type: FEEDTHROUGH_INPUT
+  is_static: true
+  connections:
+    pad2chip: jtag_tck
+    rx_en: 1'b1
+    tx_en: 1'b0
+
+- name: pad_jtag_trst
+  description: "JTAG interface reset"
+  pad_type: FEEDTHROUGH_INPUT
+  is_static: true
+  connections:
+    pad2chip: jtag_trst
+    rx_en: 1'b1
+    tx_en: 1'b0
+
+- name: pad_jtag_tms
+  description: "JTAG test mode select"
+  pad_type: FEEDTHROUGH_INPUT
+  is_static: true
+  connections:
+    pad2chip: jtag_tms
+    rx_en: 1'b1
+    tx_en: 1'b0
+
+- name: pad_jtag_tdi
+  description: "JTAG interface data input"
+  pad_type: FEEDTHROUGH_INPUT
+  is_static: true
+  connections:
+    pad2chip: jtag_tdi
+    rx_en: 1'b1
+    tx_en: 1'b0
+
+- name: pad_jtag_tdo
+  description: "JTAG interface data output"
+  pad_type: FEEDTHROUGH_OUTPUT
+  is_static: true
+  connections:
+    chip2pad: jtag_tdo
+    rx_en: 1'b0
+    tx_en: 1'b1
+
+
+- name: pad_io{i:2d}
+  mux_groups: [all_gpios, self]
+  description: "General purpose pad that can expose various internal peripherals"
+  multiple: !include common_param_muxed_pads_count.yml
+  pad_type: IOBUF
+  is_static: false

examples/modular_config/xilinx_virtex7_padtypes.yml

@@ -0,0 +1,105 @@
+# This file defines the available pad primitives for Xilinx Virtex 7 FPGAs. It
+# is part of the modular configuration example.
+- name: IOBUF
+  description: |
+    IOBUF primitive in Xilinx Ultrascale FPGAs. Although the primitive
+    only support output enable, we keep the same pad signal list in order
+    to not alter the register space of the auto-generated configuration
+    registers. If we would change the pad_signal list, we would end up
+    with different configuration registers which renders compiled binaries
+    that alter the pad configuraiton incompatible between ASIC version and
+    FPGA version.
+  template: |
+    IOBUF ${instance_name} (
+      .T(~${conn["tx_en"]}),
+      .I(${conn["chip2pad"]}),
+      .O(${conn["pad2chip"]}),
+      .IO(${conn["pad"]})
+    );
+  pad_signals: !include common_pad_signals.yml
+
+- name: IBUF
+  description: |
+    IBUF primitive in Xilinx Ultrascale FPGAs. We keep the same pad signal
+    list in order to not alter the register space of the auto-generated
+    configuration registers. If we would change the pad_signal list, we
+    would end up with different configuration registers which renders
+    compiled binaries that alter the pad configuraiton incompatible
+    between ASIC version and FPGA version.
+  template: |
+    IBUF ${instance_name} (
+      .O(${conn["pad2chip"]}),
+      .I(${conn["pad"]})
+    );
+  pad_signals: !include common_pad_signals.yml
+
+- name: OBUF
+  description: |
+    OBUF primitive in Xilinx Ultrascale FPGAs. We keep the same pad signal
+    list in order to not alter the register space of the auto-generated
+    configuration registers. If we would change the pad_signal list, we
+    would end up with different configuration registers which renders
+    compiled binaries that alter the pad configuraiton incompatible
+    between ASIC version and FPGA version.
+  template: |
+    OBUF ${instance_name} (
+      .I(${conn["chip2pad"]}),
+      .O(${conn["pad"]})
+    );
+  pad_signals: !include common_pad_signals.yml
+
+- name: IBUFGDS
+  description: |
+    Differential to single-ended clock conversion primitive in Xilinx Ultrascale  FPGAs.
+  template: |
+    IBUFGDS ${instance_name} (
+      .I(${conn["pad_p"]}),
+      .IB(${conn["pad_n"]}),
+      .O(${conn["pad2chip"]})
+    );
+  pad_signals:
+    - name: pad_p
+      size: 1
+      kind: pad
+
+    - name: pad_n
+      size: 1
+      kind: pad
+
+    - name: pad2chip
+      description: "The signal that connects to the pad's RX buffer"
+      size: 1
+      kind: output
+      conn_type: dynamic
+
+
+
+- name: FEEDTHROUGH_INPUT
+  description: |
+    Direct feedthrough by means of continuous assignment. This "pad" is
+    needed since certain pins (e.g. clock reference) must be directly
+    feedthrough withouth any IOBUF cells in between. We keep the same pad signal list
+    in order to not alter the register space of the auto-generated
+    configuration registers. If we would change the pad_signal list, we
+    would end up with different configuration registers which renders
+    compiled binaries that alter the pad configuraiton incompatible
+    between ASIC version and FPGA version.
+  template: |
+    // Dummy input pad ${instance_name}
+    assign ${conn["pad2chip"]} = ${conn["pad"]};
+  pad_signals: !include common_pad_signals.yml
+
+- name: FEEDTHROUGH_OUTPUT
+  description: |
+    Direct feedthrough by means of continuous assignment. This "pad" is
+    needed since certain pins (e.g. clock reference) must be directly
+    feedthrough withouth any IOBUF cells in between. We keep the same pad signal list
+    in order to not alter the register space of the auto-generated
+    configuration registers. If we would change the pad_signal list, we
+    would end up with different configuration registers which renders
+    compiled binaries that alter the pad configuraiton incompatible
+    between ASIC version and FPGA version.
+  template: |
+    // Dummy output pad ${instance_name}
+    assign ${conn["pad"]} = ${conn["chip2pad"]};
+  pad_signals: !include common_pad_signals.yml