test: Create YAML files for development/testing indirect memory views

test/protocol/run.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+
+set -e
+
+#---------------------------------------------------------------------------------------------------
+this_dir=$(dirname $(readlink -f "$0"))
+
+if ! [[ -d "${PWD}/.git" ]] || ! [[ -f "${PWD}/pyproject.toml" ]]; then
+    echo "ERROR: This script expects to be executed from the regio source directory." >&2
+    exit 1
+fi
+
+#---------------------------------------------------------------------------------------------------
+mmap_file='regio-protocol-test.none.bar0.bin'
+rm -f "${mmap_file}"
+
+dump_mmap_file() {
+    echo '================================================================================'
+    echo "==> hexdump of ${mmap_file}"
+    hexdump -C "${mmap_file}"
+    echo '================================================================================'
+}
+
+#---------------------------------------------------------------------------------------------------
+args=()
+args+=('-p none')
+args+=('-b all')
+args+=('-t mmap')
+args+=('--no-protocol-override')
+args+=('--indirect')
+
+cmd="regio-protocol-test ${args[@]}"
+
+#---------------------------------------------------------------------------------------------------
+# TODO: The following should be converted to a regio script.
+
+echo '===> Display of initial state'
+poetry run -- ${cmd} dump dev0.bar0
+dump_mmap_file
+
+echo '===> Modification of single view'
+poetry run -- ${cmd} eval \
+    sv=dev0.bar0.single_view \
+    sv.first=1 \
+    sv.second=2 \
+    sv.third=3
+
+echo '===> Display of single view'
+poetry run -- ${cmd} dump dev0.bar0
+dump_mmap_file
+
+echo '===> Modification of nested view'
+poetry run -- ${cmd} eval \
+    nv=dev0.bar0.nested_view \
+    nv0=nv.view_0 \
+    nv1=nv.view_1 \
+    nv0.first=0x11 \
+    nv0.second=0x12 \
+    nv0.third=0x13 \
+    nv1.first=0x14 \
+    nv1.second=0x15 \
+    nv1.third=0x16
+
+echo '===> Display of nested view'
+poetry run -- ${cmd} dump dev0.bar0
+dump_mmap_file
+
+echo '===> Modification of bus view'
+poetry run -- ${cmd} eval \
+    bv=dev0.bar0.bus_view \
+    bv0=bv.view_0 \
+    bv1=bv.view_1 \
+    bv0.first=0x21 \
+    bv0.second=0x22 \
+    bv0.third=0x23 \
+    bv1.first=0x24 \
+    bv1.second=0x25 \
+    bv1.third=0x26
+
+echo '===> Display of bus view'
+poetry run -- ${cmd} dump dev0.bar0
+dump_mmap_file
+
+echo '===> Modification of transparent views'
+for ((i=0; i<2; i++)); do
+    base=$((3 + i))
+    poetry run -- ${cmd} eval \
+        tv=dev0.bar0.transparent_view_${i} \
+        tv.first=0x${base}1 \
+        tv.second=0x${base}2 \
+        tv.third=0x${base}3
+done
+
+echo '===> Display of transparent views'
+poetry run -- ${cmd} dump dev0.bar0
+dump_mmap_file

test/protocol/setup.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+
+set -e
+
+#---------------------------------------------------------------------------------------------------
+this_dir=$(dirname $(readlink -f "$0"))
+
+if ! [[ -d "${PWD}/.git" ]] || ! [[ -f "${PWD}/pyproject.toml" ]]; then
+    echo "ERROR: This script expects to be executed from the regio source directory." >&2
+    exit 1
+fi
+
+#-------------------------------------------------------------------------------
+spec_dir="${this_dir}/spec"
+build_dir="${this_dir}/build"
+c_dir="${build_dir}/c"
+py_dir="${build_dir}/py"
+
+top="${spec_dir}/protocol_top.yaml"
+ir="${build_dir}/ir.yaml"
+
+rm -rf "${build_dir}"
+mkdir -p "${build_dir}"
+
+#-------------------------------------------------------------------------------
+echo "===> Setting up poetry"
+poetry install -vv --all-extras
+poetry run -- pip3 list
+
+#-------------------------------------------------------------------------------
+echo "===> Elaborating the top-level YAML ${top}"
+poetry run -- regio-elaborate -f top -i "${spec_dir}" -o "${ir}" "${top}"
+
+#-------------------------------------------------------------------------------
+echo "===> Generating C language header files in ${c_dir}"
+mkdir -p "${c_dir}"
+poetry run -- regio-generate -f top --recursive -g c -o "${c_dir}" "${ir}"
+
+#-------------------------------------------------------------------------------
+echo "===> Generating Python library files in ${py_dir}"
+mkdir -p "${py_dir}"
+poetry run -- regio-generate -f top --recursive -g py -o "${py_dir}" "${ir}"
+
+echo "===> Installing generated Python library"
+py_install="${build_dir}/py-install"
+cat <<_EOF >"${py_install}"
+#!/usr/bin/env bash
+set -e
+pushd "\$1/python"
+poetry install -vv --all-extras
+popd
+_EOF
+chmod +x "${py_install}"
+
+poetry run -- "${py_install}" "${py_dir}"
+poetry run -- pip3 list

test/protocol/spec/protocol_bus_client.yaml

@@ -0,0 +1,16 @@
+name: protocol_bus_client
+data_width: 8
+info: |
+  Example block for simulating a single layer of indirectly accessible registers hidden behind
+  a virtual bus. The registers within the client view are wrapped in a bus transaction object
+  and then passed on to the controller in the top-level address space.
+
+protocol:
+  name: slots
+  source: !include protocol_slots.py
+  class:
+    name: BusClientProtocol
+
+regs:
+  - name: transact
+    access: wo

test/protocol/spec/protocol_bus_controller.yaml

@@ -0,0 +1,18 @@
+name: protocol_bus_controller
+info: |
+  Example block for simulating a single layer of indirectly accessible registers hidden behind
+  a virtual bus. The bus address is used as the base slot at which all registers within a client
+  view are mapped.
+
+protocol:
+  name: slots
+  source: !include protocol_slots.py
+  class:
+    name: BusControllerProtocol
+
+regs:
+  - default:
+      width: 32
+      access: rw
+  - name: slots
+    count: 6

test/protocol/spec/protocol_bus_view.yaml

@@ -0,0 +1,26 @@
+name: protocol_bus_view
+visible: true
+data_width: 8
+info: |
+  Example decoder for simulating a single layer of indirectly accessible registers hidden behind
+  a virtual bus. The address of each interface is used as the bus address.
+
+blocks:
+  bus_client: &bus_client
+    !include protocol_bus_client.yaml
+  single_view: &single_view
+    !include protocol_single_view.yaml
+
+interfaces:
+  - name: client_0
+    block: *bus_client
+    address: 0x00
+    view:
+      name: view_0
+      block: *single_view
+  - name: client_1
+    block: *bus_client
+    address: 0x03
+    view:
+      name: view_1
+      block: *single_view

test/protocol/spec/protocol_nested_controller.yaml

@@ -0,0 +1,13 @@
+name: protocol_nested_controller
+info: Example block for simulating a two layers of indirectly accessible registers.
+
+protocol:
+  name: slots
+  source: !include protocol_slots.py
+
+regs:
+  - default:
+      width: 32
+      access: rw
+  - name: slots
+    count: 6

test/protocol/spec/protocol_nested_view.yaml

@@ -0,0 +1,23 @@
+name: protocol_nested_view
+visible: true
+info: Example decoder for simulating two layers of indirectly accessible registers.
+
+blocks:
+  single_controller: &single_controller
+    !include protocol_single_controller.yaml
+  single_view: &single_view
+    !include protocol_single_view.yaml
+
+interfaces:
+  - name: controller_0
+    block: *single_controller
+    address: 0x0000
+    view:
+      name: view_0
+      block: *single_view
+  - name: controller_1
+    block: *single_controller
+    address: 0x3000
+    view:
+      name: view_1
+      block: *single_view

test/protocol/spec/protocol_single_controller.yaml

@@ -0,0 +1,13 @@
+name: protocol_single_controller
+info: Example block for simulating a single layer of indirectly accessible registers.
+
+protocol:
+  name: slots
+  source: !include protocol_slots.py
+
+regs:
+  - default:
+      width: 32
+      access: rw
+  - name: slots
+    count: 3

test/protocol/spec/protocol_single_view.yaml

@@ -0,0 +1,25 @@
+name: protocol_single_view
+info: Example block for simulating indirectly accessible registers behind a view.
+
+regs:
+  - default:
+      width: 32
+      access: rw
+  - name: first
+    fields:
+      - name: lower
+        width: 16
+      - name: upper
+        width: 16
+  - name: second
+    fields:
+      - name: a_bit
+        width: 1
+      - name: a_pair
+        width: 2
+  - name: third
+    fields:
+      - name: a_nibble
+        width: 4
+      - name: a_triplet
+        width: 3