Add IOs/Parameters explanation

README.md

@@ -15,8 +15,8 @@ An AXI4 crossbar implemented in SystemVerilog to build the foundation of a SOC.
 A crossbar is a circuit connecting multiple master and slave agents, mapped
 across a memory space. The core consists of a collection of switches, routing
 the master requests to the slaves and driving back completions to the agents.
-A crossbar is a common piece of logic to connect for instance in a SOC the
-processor(s) with its peripherals like memories, IOs, co-processors...
+A crossbar is a common piece of logic to connect in a SOC the
+processor(s) with the peripherals like memories, IOs, co-processors...
 
 
 ```
@@ -53,14 +53,13 @@ Features
 - Round-robin fair share
     - Non-blocking arbitration between requesters
     - Priority configurable per master interface
-- Timeout support, configurable per agent interface
 - AXI or AXI4-Lite mode:
     - LITE mode: route all signals described in AXI4-lite specification
     - FULL mode: route all signals described by AXI4 specification
     - The selected mode applies to global infrastructure
-- Masters routing can be defined to restrict slaves access
+- Routing table can be defined to restrict slaves access
     - Easily create enclosed and secured memory map
-    - Useful to save gate count
+    - Dedicate sensitive slaves only to trusted master agents
 - USER signal support
     - Configurable for each channel (AW, AR, W, B, R)
     - Common to all master/slave interfaces if activated
@@ -73,7 +72,7 @@ Features
     - Data width configurable, any width
     - ID width configurable, any width
 - Advanced clock/reset network
-    - Support both aynchronous and synchronous reset schema
+    - Support both aynchronous and synchronous reset schemes
     - Can handle clock domain crossing if needed, the core being fueled by its
       own clock domain
 - Route read/write requests by address decoding. All slave agents are mapped
@@ -84,6 +83,8 @@ Features
     - A master can be restricted to a memory map subset
     - An acccess to a forbidden area is completed by a DECERR
 - Switching logic IO interfaces can be pipelined to achieve timing closure easier
+- Don't garantee completion ordering when a master targets multiple slaves with the
+  same AXI ID (!). A master should use different IDs and reorder the completion by itself
 
 Further details can be found in:
 - the architecture [chapter](doc/architecture.md)
@@ -92,7 +93,7 @@ Further details can be found in:
 
 ## Verification environment
 
-The core is verified with a testbench relying on (pseudo) random driver and
+The core is verified with a testbench relying on pseudo-random driver and
 monitor to inject some traffic and verify its correctness. Please refer to the
 [dedicated chapter](./test/svut/README.md) for futher details and find hints
 to integrate the core in your own development. The flow relies on:
@@ -103,13 +104,14 @@ to integrate the core in your own development. The flow relies on:
 
 ## Development plan
 
-Limitations (current dev stage)
+Inbox:
 
-- No timeout support
-
-Inbox (possible next devs)
-
-- Support Verilator for CI
+- Full AXI ordering support
+    - if a master if targets two slaves with the same ID, the interconnect fowards
+      the completion in the order it receives them.
+    - put in place multiple queue per ID and manage reordering
+- Timeout support in switching logic
+- Support Verilator
 - Read-only or Write-only master to save gate count
 - Error injection in the core and tesbench
 - Implement statistics in testbench to track misrouting, address distribution,
@@ -121,14 +123,10 @@ Inbox (possible next devs)
 - Address translation service
 - Number of master and slave agents configurable
 - RTL generator to support any number of master / slave agents
-- Completion reordering to support of out-of-order responses
 - Interface datapath width conversion
-- AXI4/AXI4-lite converter
-- Full-STRB vs Partial-STRB mode
-    - Partial-STRB mode stores only first and last phase of a write request's payload STRBs,
-      all other dataphases are fully activated (WSTRBs=1)
-    - Full-STRB mode transports the complete STRBs dataphases as driven by a master
-    - Useful to save gate count
+- AXI4-to-AXI4-lite converter
+    - split AXI4 to multiple AXI4-lite requests
+    - gather AXI4-lite completion into a single AXI completion
 - 4KB boundary crossing checking, supported by a splitting mechanism
 
 

doc/architecture.md

@@ -71,7 +71,7 @@ the the completions from/to the agent.
 
 ## Clock and Reset Network
 
-## Clock
+### Clock
 
 The core uses and needs a reference clock for the internal switching logic. The
 higher the frequency is, the better will be the global bandwidth and latency
@@ -86,7 +86,7 @@ The user can also use the same clock for all the interfaces. In this
 configuration, all the agents connected to the core have to use the same clock
 than the interconnect switching logic.
 
-## Reset
+### Reset
 
 The core fully supports both asynchronous and synchronous reset. The choice
 between these two options depends to the technology targeted. Most of the time,
@@ -141,20 +141,21 @@ applies for both AXI4 and AXI4-lite configuration.
 
 ### Ordering rules
 
-The core supports outstanding requests, and so manages traffic queues. However,
-the core doesn't support reodering to enhance traffic and so the user can be
-sure the read or the write requests will be issued to the master interface(s)
+The core supports outstanding requests, and so manages traffic queues.
+
+The core doesn't support reodering to enhance quality of service and so the user
+can be sure the read or write requests will be issued to the master interface(s)
 in the same order than received on a slave interface.
 
+The core doesn't support read/write completion reodering, so a master issuing
+with the same ID some requests to different slaves can't be sure the completions
+will follow the original order if the slaves don't have the same pace to complete
+a request.
+
 Read and write traffic are totally uncorrelated, no ordering can be garanteed
 between the read / write channels.
 
-The odering rules mentioned above are applicable only on a slave interface, and
-so concurrent slaves traffic can be served in a different way than the requests
-are received.
-
-The odering rules mentioned above imply device or memory regions accesses are
-managed in the same way.
+The ordering rules mentioned above apply for device or memory regions.
 
 ### AXI4-lite specificities
 

doc/io_parameter.md

@@ -1 +1,107 @@
-# IO & Parameters
+# Inputs/Outputs & Parameters
+
+## Parameters
+
+- AXI_ADDR_W
+    - Address width for both read and write address channels
+    - Any value from 1 bit
+- AXI_ID_W
+    - ID width for both read and write address/completion channels
+    - Any value from 1 bit
+- AXI_DATA_W
+    - ID width for both read and write data channels
+    - Any value from 1 bit
+- MST_PIPELINE
+    - Enable pipeline stage on switching logic inputs from the master agents
+    - 1 = add the pipeline stage, otherwise 0
+- SLV_PIPELINE
+    - Enable pipeline stage on switching logic output to the slave agents
+    - 1 = add the pipeline stage, otherwise 0
+- AXI_SIGNALING
+    - Specify the protocol supported by the core. Apply to the whole topology
+    - 0 = AXI4-lite, 1 = AXI4
+- USER_SUPPORT
+    - Enable user specific sideband signal in all AXI channels. Apply to the whole topology
+    - 1 = support sideband signals, 0 = no sideband signals
+- AXI_AUSER_W
+    - Specify in bit the width of address sideband signals
+    - Apply to both read and write address channels
+    - Any value from 1 bit
+- AXI_WUSER_W
+    - Specify in bit the width of write data sideband signals
+    - Any value from 1 bit
+- AXI_BUSER_W
+    - Specify in bit the width of write response sideband signals
+    - Any value from 1 bit
+- AXI_RUSER_W
+    - Specify in bit the width of read data sideband signals
+    - Apply to both read and write address channels
+    - Any value from 1 bit
+
+Follow description of parameters common to all interfaces on which
+a master agent is connected:
+
+- MSTx_CDC
+    - Implement a CDC stage for master x
+    - 1 = activated, 0 = no CDC
+- MSTx_OSTDREQ_NUM
+    - Number of outstanding request supported for master x
+    - Any value from 1
+- MSTx_OSTDREQ_SIZE
+    - Number of dataphase of an outstanding request for master x
+    - Any from value between 1 and 256
+- MSTx_PRIORITY
+    - Priority a master will be garanteed in a switching
+    - Value between 0 (low priority) and 3 (high priority)
+- MSTx_ROUTES
+    - The slave agent a master can target
+    - 4 bits, one per slave. Bit0 is slave0, ..., bit3 is slave3
+- MSTx_ID_MASK
+    - A mask applied in slave completion channel to determine which master to route back the
+      BRESP/RRESP completions.
+    - Any value, width equal to `AXI_ID_W`
+
+Follow description of parameters common to all interfaces on which a 
+slave agent is connected:
+
+- SLVx_CDC
+    - Implement a CDC stage for slave x
+    - 1 = activated, 0 = no CDC
+- SLVx_OSTDREQ_NUM
+    - Number of outstanding request supported for slave x
+    - Any value from 1
+- SLVx_OSTDREQ_SIZE
+    - Number of dataphase of an outstanding request for slave x
+    - Any from value between 1 and 256
+- SLVx_START_ADDR
+    - Memory address from which a slave agent can be targeted
+    - Any value from 0 up to 2^`AXI_ADDR_W`/8
+- SLVx_END_ADDR
+    - Memory address up to which a slave agent can be targeted
+    - Any value from 0 up to 2^`AXI_ADDR_W`/8
+- SLVx_KEEP_BASE_ADDR
+    - When a reqeust is issued to a slave agent, the base address `SLVx_START_ADDR` is
+      is not removed from the `AxADDR` field
+
+## Input / Output
+
+### AXI4 / AXI4-lite
+
+The core complies with AXI4 and AXI4-lite signal definition. The specification of the protocol
+as well the signals list can be found on 
+[ARM website](https://developer.arm.com/documentation/ihi0022/latest/).
+
+### General Interface
+
+The following signals are the clock and reset necessary to switching logic to be functional.
+Only on reset must be driven, the other one needing to be tied to `0` for srst or `1` for aresetn.
+Refer to the [architecture chapter](architecture.md#clock-and-reset-network) for explanation.
+
+- aclk
+    - The clock for the switching logic and the internal buffers
+    - Any frequency
+- aresetn
+    - Active low, asynchronous reset. Must comply to AMBA specification, asynchronous assertion,
+      synchronous deassertion
+- srst
+    - Fully synchronous reset