Put ARGS code cleanup steps in Jira ticket description in args_cleanup.txt.

args_cleanup.txt

+-------------------------------------------------------------------------------
+--
+-- Copyright 2020
+-- ASTRON (Netherlands Institute for Radio Astronomy) <http://www.astron.nl/>
+-- P.O.Box 2, 7990 AA Dwingeloo, The Netherlands
+--
+-- Licensed under the Apache License, Version 2.0 (the "License");
+-- you may not use this file except in compliance with the License.
+-- You may obtain a copy of the License at
+--
+--     http://www.apache.org/licenses/LICENSE-2.0
+--
+-- Unless required by applicable law or agreed to in writing, software
+-- distributed under the License is distributed on an "AS IS" BASIS,
+-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+-- See the License for the specific language governing permissions and
+-- limitations under the License.
+--
+-------------------------------------------------------------------------------
+--
+-- Author: E. Kooistra
+-- Purpose: ARGS clean up steps
+--
+
+References
+[1] mm_port_naming.txt
+
+Jira tickets backlog to cleanup the ARGS code:
+
+L2SDP-251: Support new MMAP format in SDP
+- Compressed mmap. Use bash to remove redundant spaces from mmap file, before putting it in the FPGA system info ROM.
+
+L2SDP-255 : Cleanup the ARGS code:
+- Simplify ARGS code structure (minimize features, remove platform specific code)
+- Clean up ARGS parse checks and warnings
+- Clean up gen_rom_mmap.py (remove work arounds)
+
+  Cleanup details:
+  - Read ARGS yaml configuration into Python
+    - read in and parse yaml file (fpga or peripheral)
+      . check yaml syntax
+      . check ARGS syntax
+        - check that the keys in yaml are valid
+    - if fpga.yaml:
+      - read in and parse peripheral.yaml files that are used in the fpga.yaml file
+          - check that peripheral instantiations in fpga.yaml exist in the periperal.yaml
+          - check that parameter_overrides in fpga.yaml exist on the peripheral
+          - add default keys with their default value (typically None = not specified -->
+              let gen_* script fill in value dependent on the function of the gen_* script)
+      - evalutate/substitute the fpga.yaml peripheral parameters overrides
+        . put fields in address_offset order
+        . check valid values
+          - string naming rules (must start with an a-z,A_Z character)
+          - field address_offset multiple of MM_BUS_SIZE = 4 bytes
+          - field bit_offset + mm_width <= MM_BUS_WIDTH = 32 bit
+      ==> Common representation of register map in Python
+
+  - Simplify the ARGS code structure (using seperate, independent steps for parse, check, evaluate and generate)
+    - yaml parser
+      . yaml syntax
+    - ARGS parser
+      . ARGS syntax per file
+      . Remove platform specific code (AXI, Xilinx, QSYS) from core ARGS (= fpga.py, peripheral.py)
+      . if fpga.yaml:
+        . ARGS correctness between fpga and instantiated peripherals
+        . ARGS parameter overrides of peripherals in fpga
+        . do not fill in or calculate base address values, do that in generate script
+        . do not use structured naming, only support the manual naming:
+          - no structured mm_port_names naming in fpga.yaml (using peripheral_group as postfix)
+          - no structured field_name naming in peripheral.yaml (using field_group string as prefix)
+      . for peripheral.yaml:
+        . rename Register.py into reg.py and REG.
+        . keep field_group (no need for explicit field_group key, the implicit field_group key string is fine)
+        . do not distinghuis beteen mm_port_types (REG, RAM, FIFO), they all use fields
+        . do not unroll arrays (number_of_peripherals, number_of_mm_ports, number_of_fields)
+    ==> Minimal representation of fpga.yaml in Python that forms the base for generate scripts
+    - Generate scripts, e.g.
+      . for fpga.yaml
+        . derive MM addresses for fpga.yaml
+          . Separate getting MM bus base addresses from QSYS out of fpga.py (because it is Altera platform specfic)
+          . Separate calculating MM bus base addresses, based on peripheral and mm_port spans (see point 4k)
+        . gen_rom_mmap.py: generate MMAP file for fpga.yaml
+
+
+L2SDP- : Cleanup base address derivation:
+- Add separate code to derive MM addresses for fpga.yaml from QSYS mm_port base addresses
+- Add separate code to derive MM addresses for fpga.yaml from calculation based on peripheral
+  and mm_port spans (see 4k) in [1]
+
+L2SDP- : Jira story Generate markdown document for fpga.yaml:
+- Generate simple markdown document for fpga.yaml.
+  . With title, contents, sections, tables and based on evaluated parameter values.
+  . Instead of using Latex as in gen_doc.py, because markdown is simpler and thus easier to maintain.
+
+Future ARGS features:
+. Numbers (int, float) and boolean (True, TRUE, False) are supported as parameters values,
+  but strings are not (yet) supported.
+. For fpga.yaml
+  . Add instance_description key in fpga.yaml to support describing some peripheral instance specifics.
+  . generate MM bus HDL code for fpga.yaml
+. For peripheral.yaml:
+  . generate MM interface HDL code for a periperal in a periperal.yaml

slave_port_naming.txt

@@ -136,6 +136,7 @@ c) Remove structured MM port naming:
 d) Do not mix generic ARGS code with platform specific code:
    - Use dedicated new mm_port_type to support e.g. AXI Lite registers, so keep the mm_port_type REG generic
    - Remove mm_port_protocol
+   - Platform specific code (e.g. for AXI bus, Xilinx) should be in generate scripts, not in core ARGS code.
 e) field
    - use exaxt yaml names in the Python code, so then e.g ?:
      . periperal.name --> periperal.periperal_name
@@ -510,8 +511,6 @@ j) endianess per MM word (l, b) and for multi MM word (L, B)
    endianess column in mmap met enum of number?
 
 
-
-
 k) address calculation
   - Use base addresses from QSYS or calculate base addresses based on peripheral spans
   - MM port span is largest for all fields of ceil_log2(address offset of field + largest(width, radix_width) / 32)
@@ -527,51 +526,6 @@ k) address calculation
     span = 0 to use the calculated minimal required span. The span is the actual number of
     bytes (multiple of 4), the 2**span_w yields the occupied address space.
 
-l) ARGS steps
-  - read in and parse fpga.yaml file
-    . check yaml syntax
-    . check ARGS syntax
-      - check that the keys in fpga.yaml are valid
-  - read in and parse peripheral.yaml files that are used in the fpga.yaml file
-    . check yaml syntax
-    . check ARGS syntax
-      - check that the keys in peripheral.yaml are valid
-      - check that peripheral instantiations in fpga.yaml exist in the periperal.yaml
-      - check that parameter_overrides in fpga.yaml exist on the peripheral
-      - add default keys with their default value (typically None = not specified -->
-          let gen_* script fill in value dependent on the function of the gen_* script)
-  - evalutate/substitute the parameters overrides
-    . put fields in address_offset order
-    . check valid values
-      - string naming rules (must start with an a-z,A_Z character)
-      - field address_offset multiple of MM_BUS_SIZE = 4 bytes
-      - field bit_offset + mm_width <= MM_BUS_WIDTH = 32 bit
-    . do not unroll arrays (number_of_peripherals, number_of_mm_ports, number_of_fields)
-
-  - ARGS code structure
-    - Read ARGS yaml configuration into Python:
-      yaml parser,
-      fpga uses peripherals,
-      peripherals uses mm_ports,
-      there are multiple mm_port type (REG, RAM, FIFO) but they all use fields.
-    - Generate scripts, e.g.
-      . gen_rom_mmap.py: generate MMAP file for fpga.yaml
-      . gen_doc.py: generate ICD document file for fpga.yaml, better use markdown then
-                    LaTeX, because markdown is simpler and thus easier to maintain.
-      . generate MM bus base addresses for fpga.yaml, based on peripheral and mm_port spans
-      . get MM bus base addresses from QSYS for fpga.yaml
-      . generate MM bus HDL for fpga.yaml
-      . generate MM interface HDL for a periperal or all periperals in a periperal.yaml
-
-
-z) Other:
-  - Rename Register.py into reg.py and REG.
-  - Numbers (int, float) and boolean (True, TRUE, False) are supported as parameters values,
-    but strings are not (yet) supported.
-  - Add instance_description key in fpga.yaml to support describing some peripheral instance specifics.
-  - parameter_overrides does not yet check whether parameter actually exists on periperal
-
-   
 
 ###############################################################################
 #