diff --git a/args_next_steps.txt b/args_next_steps.txt
index ca1eedb9ed8121e0972c8ccfe73f156ffb48193c..df15e6ae626d3c46a436202b25042de74cbae12c 100755
--- a/args_next_steps.txt
+++ b/args_next_steps.txt
@@ -1,67 +1,89 @@
-
-ARGS continuation --> ARGS2.0
-
-
-1) Work and build directory:
-2) CSP-LOW-CBF-000030_Automatic_Register_Generation_System is latest.
-3) Address and data formats for master, slave and user
-4) Definition of fields within slave data
-5) Definition of fields, field_group and field_name
-6) Regmap representation in FPGA ROM info
-
-Appendix 1) ARGS: Text from older versions of the document.
+-------------------------------------------------------------------------------
+--
+-- 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: How to continue ARGS for LOFAR2.0 --> ARGS2.0
+--
+-- Contents:
+--
+-- 1) Work and build directory:
+-- 2) CSP-LOW-CBF-000030_Automatic_Register_Generation_System is latest.
+-- 3) Address and data formats for master, slave and user
+-- 4) Definition of fields within slave data
+-- 5) Definition of fields, field_group and field_name
+-- 6) Regmap representation in FPGA ROM info
+-- 7) Remove use of word slave
+--
+-- Appendix 1) ARGS: Text from older versions of the document.
+--
###################################################################################################
# How to continue with ARGS
a) Use ARGS for the future (= unb2c), no effort to adapt ARGS for the past (= Apertif)
-. Keep ARGS and RadioHDL tools separate
-. Do support lock_base_address key
-. Do support fpga YAML regmap info in FPGA --> use propietory .mmap format --> see 6).
-. Choose to continue with ASTRON style for ARGS, but try to keep CSIRO style. Keep track of
+Done. Keep ARGS and RadioHDL tools separate
+Done. Do support lock_base_address key
+Done. Do support fpga YAML regmap info in FPGA --> use propietory .mmap format --> see 6).
+Done. Choose to continue with ASTRON style for ARGS, but try to keep CSIRO style. Keep track of
modifications in revision history table in ARGS doc in Confluence.
b) Work and build directory:
The work and build directory is independent of where ARGS is located and set when init_args is ran:
-. init_radiohdl looks for sources in $RADIOHDL_WORK and puts results in $RADIOHDL_BUILD_DIR/<build_set>/
-. init_args looks for sources in $ARGS_WORK and puts results in $ARGS_BUILD_DIR/args/<fpga_name>
+Done. init_radiohdl looks for sources in $RADIOHDL_WORK and puts results in $RADIOHDL_BUILD_DIR/<build_set>/
+Done. init_args looks for sources in $ARGS_WORK and puts results in $ARGS_BUILD_DIR/args/<fpga_name>
c) Documentation generation
- use LaTex
- potential alternatives (Tammo Jan): yaml multiline, yaml markdown
+- see Markdown generator using mdutil in Markdown/readme_markdown.txt
d) Purpose of ARGS (or any tool)
- what problem does it solve (what is the request or question is more important that the solution)
-TODO:
-. L2SDP-99 Port ARGS document to Confluence
-. L2SDP-98 Define .mmap format and add it to ARGS document in an appendix.
-
###################################################################################################
2) CSP-LOW-CBF-000030_Automatic_Register_Generation_System is latest.
Renamed:
-- system --> fpga
-- fpga.yaml: subsystem_name --> peripheral_group = name of a peripheral instance, used as
- instance_prefix
-- parameters --> parameters_override ?
-- software_value --> simulation_value ? software_value was a better name
+Done- system --> fpga
+Done- fpga.yaml: subsystem_name --> peripheral_group = name of a peripheral instance, manually
+ used as instance postfix in slave_port_name
+Done- parameters --> parameters_override
+CSIRO- software_value --> simulation_value ? software_value was a better name
Added:
-- slave_protocol (Axi LITE, FULL)
-- slave_span
-- user_width : for user side of RAM, if it differs from the MM side --> rename to user_word_width
+CSIRO- slave_protocol (Axi LITE, FULL)
+CSIRO- slave_span
+Done- user_width : for user side of RAM, if it differs from the MM side
Removed:
-- slave_prefix --> use slave_type , slave_postfix --> use peripheral_name
-- dual_clock --> should add that again
-- separate access modes for FIFO (FR and FW that are like RO and WO but without address increment)
+Done- slave_prefix --> use slave_type
+Done- slave_postfix --> use peripheral_name
+Done- dual_clock --> should add that again
+Done- separate access modes for FIFO (FR and FW that are like RO and WO but without address
+ increment). Wontdo, use RO and WO also for FIFO.
Changed:
- field_group string ('- -') --> see 5)
@@ -85,7 +107,7 @@ The number of bytes per address and the data size can differ at the interfaces:
master -- MM bus -- slave -- user
-The yaml files use byte addressing. Internally ARGS alos use byte addressing. However only
+The yaml files use byte addressing. Internally ARGS also use byte addressing. However only
word addressing is supported, so the byte addresses are always a multiple of 4. This is checked
when ARGS reads in the yaml files. For output files it depends on the application whether the
output file assumes byte addressing or word addressing.
@@ -101,8 +123,10 @@ Slave : --> see 4)
. the bit_offset and width can be denoted as [hi:lo], where lo = bit_offset and hi = lo + width -1
. a field can span multiple words and denoted as [hi:lo] where hi >= 32
. for a RAM there is one field per word. A field can span multiple words.
- . slave base_address is defined in MM word address format of the master, so with address word
- . slave address_offset is defined in MM word address format of the master, so not in field width units
+ . word addresses are specified in bytes, so must be a multiple of 4:
+ . the span is in bytes, but must be a multiple of 4
+ . slave base_address is in bytes, but must be a multiple of 4
+ . slave address_offset is in bytes, but must be a multiple of 4
###################################################################################################
@@ -122,16 +146,16 @@ The fields are should support:
. fields extending over word boundary
. field width > 32b
- * Example with various packed fields
- bit
- 31 0 word .mmap
- M M M M 0 M: address_offset = 0, bit_offset = 0, width = 48 --> [47:0]
- . . M M 1
- K K K K 2 K: address_offset = 2, bit_offset = 0, width = 48 --> [47:0]
- L L K K 3 L: address_offset = 3, bit_offset = 16, width = 32 --> [47:16]
- B a L L 4 a: address_offset = 4, bit_offset = 16, width = 1 --> [16:16]
- . C C B 5 B: address_offset = 4, bit_offset = 24, width = 16 --> [39:24]
- C: address_offset = 5, bit_offset = 8, width = 16 --> [23:8]
+ * Example with various packed fields
+ bit
+ 31 0 word .mmap
+ M M M M 0 M: address_offset = 0, bit_offset = 0, width = 48 --> [47:0]
+ . . M M 1
+ K K K K 2 K: address_offset = 8, bit_offset = 0, width = 48 --> [47:0]
+ L L K K 3 L: address_offset = 12, bit_offset = 16, width = 32 --> [47:16]
+ B a L L 4 a: address_offset = 16, bit_offset = 16, width = 1 --> [16:16]
+ . C C B 5 B: address_offset = 16, bit_offset = 24, width = 16 --> [39:24]
+ C: address_offset = 20, bit_offset = 8, width = 16 --> [23:8]
- RAM is an array of identical fields packed at incrementing addresses
. The array of fields has number_of_fields. It could also be defined as a list of
@@ -140,57 +164,57 @@ The fields are should support:
. w > 32b then field extends over multiple addresses and increments per ceil_log2(w / 32b)
* Example of a RAM with one field <= 32b per word (number_of_fields = 3)
- bit
- 31 0 word .mmap
- A 0 A[0]: address_offset = 0, bit_offset = 0, width = 14 --> [13:0]
- A 1 A[1]: address_offset = 1, bit_offset = 0, width = 14 --> [13:0]
- A 2 A[2]: address_offset = 2, bit_offset = 0, width = 14 --> [13:0]
+ bit
+ 31 0 word .mmap
+ A 0 A[0]: address_offset = 0, bit_offset = 0, width = 14 --> [13:0]
+ A 1 A[1]: address_offset = 4, bit_offset = 0, width = 14 --> [13:0]
+ A 2 A[2]: address_offset = 8, bit_offset = 0, width = 14 --> [13:0]
* Example of a RAM with one field > 32b per word (number_of_fields = 3)
- bit
- 31 0 word .mmap
- A 0 A[0}: address_offset = 0, bit_offset = 0, width = 48 --> [47:0]
- A 1
- A 2 A[1}: address_offset = 2, bit_offset = 0, width = 48 --> [47:0]
- A 3
- A 4 A[2}: address_offset = 3, bit_offset = 0, width = 48 --> [47:0]
- A 5
-
+ bit
+ 31 0 word .mmap
+ A 0 A[0}: address_offset = 0, bit_offset = 0, width = 48 --> [47:0]
+ A 1
+ A 2 A[1}: address_offset = 8, bit_offset = 0, width = 48 --> [47:0]
+ A 3
+ A 4 A[2}: address_offset = 16, bit_offset = 0, width = 48 --> [47:0]
+ A 5
+
- arrays of identical width fields that are part of REG or are a RAM with multiple fields per word.
. In a REG with multiple fields, there could be recurrent substructures. This could be supported
using a number_of_field_groups key, to avoid having to list them one by one.
* Example with array of recurrent fields (number_of_field_groups = 4)
- bit
- 31 0 word .mmap
- B A 0 A[0]: address_offset = 0, bit_offset = 0, width = 14 --> [13:0]
- B[0]: address_offset = 0, bit_offset = 16, width = 14 --> [29:16]
- B A 1 A[1]: address_offset = 1, bit_offset = 0, width = 14 --> [13:0]
- B[1]: address_offset = 1, bit_offset = 16, width = 14 --> [29:16]
- B A 2 A[2]: address_offset = 2, bit_offset = 0, width = 14 --> [13:0]
- B[2]: address_offset = 2, bit_offset = 16, width = 14 --> [29:16]
- B A 3 A[3]: address_offset = 3, bit_offset = 0, width = 14 --> [13:0]
- B[3]: address_offset = 3, bit_offset = 16, width = 14 --> [29:16]
-
+ bit
+ 31 0 word .mmap
+ B A 0 A[0]: address_offset = 0, bit_offset = 0, width = 14 --> [13:0]
+ B[0]: address_offset = 0, bit_offset = 16, width = 14 --> [29:16]
+ B A 1 A[1]: address_offset = 1, bit_offset = 0, width = 14 --> [13:0]
+ B[1]: address_offset = 1, bit_offset = 16, width = 14 --> [29:16]
+ B A 2 A[2]: address_offset = 2, bit_offset = 0, width = 14 --> [13:0]
+ B[2]: address_offset = 2, bit_offset = 16, width = 14 --> [29:16]
+ B A 3 A[3]: address_offset = 3, bit_offset = 0, width = 14 --> [13:0]
+ B[3]: address_offset = 3, bit_offset = 16, width = 14 --> [29:16]
+
. The advantage of being able to hold multiple fields per word is, that this improves the data
throughput for the master MM access, because otherwise a full 32b word is transported per
- single field. This could be supported using a number_of_field_groups key.
+ single field. This could be supported using a number_of_field_groups key.
* Example with 4 bytes per word (number_of_field_groups = 3)
bit
31 0 word
B B B B 0 B[ 0]: address_offset = 0, bit_offset = 0, width = 8 --> [7:0]
- B[ 1]: address_offset = 0, bit_offset = 8, width = 8 --> [15:8]
- B[ 2]: address_offset = 0, bit_offset = 16, width = 8 --> [23:16]
- B[ 3]: address_offset = 0, bit_offset = 24, width = 8 --> [31:24]
- B B B B 1 B[ 4]: address_offset = 1, bit_offset = 0, width = 8 --> [7:0]
- B[ 5]: address_offset = 1, bit_offset = 8, width = 8 --> [15:8]
- B[ 6]: address_offset = 1, bit_offset = 16, width = 8 --> [23:16]
- B[ 7]: address_offset = 1, bit_offset = 24, width = 8 --> [31:24]
- B B B B 2 B[ 8]: address_offset = 2, bit_offset = 0, width = 8 --> [7:0]
- B[ 9]: address_offset = 2, bit_offset = 8, width = 8 --> [15:8]
- B[10]: address_offset = 2, bit_offset = 16, width = 8 --> [23:16]
- B[11]: address_offset = 2, bit_offset = 24, width = 8 --> [31:24]
+ B[ 1]: address_offset = 0, bit_offset = 8, width = 8 --> [15:8]
+ B[ 2]: address_offset = 0, bit_offset = 16, width = 8 --> [23:16]
+ B[ 3]: address_offset = 0, bit_offset = 24, width = 8 --> [31:24]
+ B B B B 1 B[ 4]: address_offset = 1, bit_offset = 0, width = 8 --> [7:0]
+ B[ 5]: address_offset = 1, bit_offset = 8, width = 8 --> [15:8]
+ B[ 6]: address_offset = 1, bit_offset = 16, width = 8 --> [23:16]
+ B[ 7]: address_offset = 1, bit_offset = 24, width = 8 --> [31:24]
+ B B B B 2 B[ 8]: address_offset = 2, bit_offset = 0, width = 8 --> [7:0]
+ B[ 9]: address_offset = 2, bit_offset = 8, width = 8 --> [15:8]
+ B[10]: address_offset = 2, bit_offset = 16, width = 8 --> [23:16]
+ B[11]: address_offset = 2, bit_offset = 24, width = 8 --> [31:24]
Conclusion:
. the .mmap identifies a field as bit index range [hi:lo], where hi can be > 32
@@ -208,14 +232,14 @@ The fields key lists all fields in the slave.
The field_defaults is used to define the defaults for a group of fields, e.g. their bit_offset.
The field_group is used to define field_defaults for a group of fields. In the future the
-field_group could also be useful to add a field_group_description key. When ther is only 1
-field in a field_group, then it is somewhat redundant to also defeine a field_group.
+field_group could also be useful to add a field_group_description key. When there is only 1
+field in a field_group, then it is somewhat redundant to also define a field_group.
Therefore the field_group key string is optional, and this then results in '- -' for a
field_name. If the field_group is needed, but does not need a name, then this also results
in '- -'.
The field_group string is a key, but kind of implicite, because it gets a user specified name.
-To folow the general schema of the ARGS YAML files it is preferred to only use expliocite,
+To folow the general schema of the ARGS YAML files it is preferred to only use explicite,
so predefined keys. Such a key can still be optional.
Impliciete field_group key:
@@ -223,8 +247,8 @@ Impliciete field_group key:
- slave_name
fields : # list of fields in this slave
- "field_group" : # field_group string optional
- - field_defaults: {access_mode: RO, address_offset: 0x0}
- - field_name : string
+ - field_defaults: {access_mode: RO, address_offset: 0x0}
+ - field_name : string
width : int # = 32
- field_name : string
width : int # = 32
@@ -236,8 +260,8 @@ Explicite field_group key (can still be optional):
- slave_name
fields : # list of fields in this slave
- field_group : string : # field_group key optional
- - field_defaults: {access_mode: RO, address_offset: 0x0}
- - field_name : string
+ - field_defaults: {access_mode: RO, address_offset: 0x0}
+ - field_name : string
width : int # = 32
- field_name : string
width : int # = 32
@@ -259,10 +283,11 @@ is the same as this:
fields : # list of fields in this slave
- - field_name : string # field_group key optional
width : int # = 32
- field_name : string # field_group key optional
+ - field_name : string # field_group key optional
width : int # = 32
-
+
TODO: Add explicit field_group key, keep supporting implicit field_group key string.
+TODO: Add field_group_description
###################################################################################################
6) Regmap representation in FPGA ROM info
@@ -274,6 +299,25 @@ proper format (e.g. for parsing). Storing YAML takes more ROM than storing .mmap
The propietory .mmap format of ASTRON is more clear than the propietory .ccfg format of CSIRO.
+###################################################################################################
+7) Remove use of word slave
+
+Following CIPO - COPI, rename slave into peripheral and master into controller.
+
+A peripheral can have one or more MM ports on the MM bus:
+
+* slave --> peripheral
+ . slave_port_names --> peripheral_port_names
+ . slave_ports --> peripheral_ports
+
+* slave --> port
+ . MM slave --> MM port
+ . slave_name --> port_name
+ . number_of_slaves --> number_of_ports
+ . slave_type --> port_type
+ . slave_description --> port_description
+
+
###################################################################################################
Appendix 1) ARGS: Text from older versions of the document.
@@ -346,3 +390,4 @@ fpgaWriteField( registerName, 1 )
Note that the ARGS system configuration file also offers a slave_port_names key that allows a
user to assign any arbitrary slave port name, in case the structured naming scheme does not fit.
+
diff --git a/args_readme.txt b/args_readme.txt
index f191316d8fae41249319cf7e4a2bd1391749084f..469fba7826e5d5edcd276adc5b8f94eec37b0929 100644
--- a/args_readme.txt
+++ b/args_readme.txt
@@ -1,10 +1,32 @@
-This readme is an introduction to py_args_lib.
-
-Contents:
-1) Demo of py_args_lib
-2) How to develop new tool scripts that use py_args_lib
-3) Examples of tool scripts that use py_args_lib
-
+-------------------------------------------------------------------------------
+--
+-- 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: P. Donker
+-- Purpose: Introduction to py_args_lib
+--
+-- Contents:
+--
+-- 1) Demo of py_args_lib
+-- 2) How to develop new tool scripts that use py_args_lib
+-- 3) Examples of tool scripts that use py_args_lib
+--
1) Demo of py_args_lib