diff --git a/args_cleanup.txt b/args_cleanup.txt
new file mode 100644
index 0000000000000000000000000000000000000000..5e563a7b946447de193b605120e71bcd33a9b23f
--- /dev/null
+++ b/args_cleanup.txt
@@ -0,0 +1,102 @@
+-------------------------------------------------------------------------------
+--
+-- 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
diff --git a/slave_port_naming.txt b/slave_port_naming.txt
index 36d9661a7b891fa26eee05a276140b7ab6e3049f..aa4f0edf305796798f0c53750fa6a181b00170c4 100644
--- a/slave_port_naming.txt
+++ b/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
-
-
###############################################################################
#