Merge pull request #2 from WRoenninger/apb-structs

Setup proper APB4 infrastructure

.editorconfig

@@ -0,0 +1,22 @@
+# EditorConfig (http://editorconfig.org/)
+root = true
+
+# Default Settings
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+tab_width = 4
+trim_trailing_whitespace = true
+max_line_length = 100
+
+[Makefile]
+indent_style = tab
+
+[{*.sv,*.svh}]
+indent_size = 2
+
+[*.yml]
+indent_size = 2

.gitignore

@@ -1,5 +1,6 @@
 .*
 !.git*
+!/.editorconfig
 /build
 /Bender.lock
 /Bender.local

Bender.yml

@@ -1,6 +1,37 @@
 package:
   name: apb
-  authors: ["Fabian Schuiki <[email protected]>"]
+  authors:
+    - "Andreas Kurth <[email protected]>" # current maintainer
+    - "Fabian Schuiki <[email protected]>"
+    - "Wolfgang Roenninger <[email protected]>"
+
+dependencies:
+  common_cells: { git: "https://github.com/pulp-platform/common_cells.git", version: 1.16.2 }
+
+export_include_dirs:
+  - include
 
 sources:
+  # Source files grouped in levels. Files in level 0 have no dependencies on files in this
+  # package. Files in level 1 only depend on files in level 0, files in level 2 on files in
+  # levels 1 and 0, etc. Files within a level are ordered alphabetically.
+  # Level 0
+  - src/apb_pkg.sv
+  # Level 1
   - src/apb_intf.sv
+  # Level 2
+  - src/apb_regs.sv
+
+  - target: simulation
+    files:
+      - src/apb_test.sv
+
+  - target: test
+    files:
+      - test/tb_apb_regs.sv
+
+  - target: synth_test
+    files:
+      # Level 0
+      - test/synth_bench.sv
+

CHANGELOG.md

@@ -6,9 +6,26 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## Unreleased
 
+### Added
+- Add clocked `APB_DV` interface for design verification.
+- Define macros for APB typedefs.
+- Define macros for assigning APB interfaces.
+- Add `apb_regs` read-write registers with APB interface with optional read only mapping.
+- Add basic test infrastructure for APB modules.
+- Add contribution guidelines.
+- Add RTL testbenches for modules.
+- Add synthesis and simulation scripts.
+- `synth_bench`: add synthesis bench.
+
+### Changed
+- Rename `APB_BUS` interface to `APB`, change its parameters to constants, and remove `in` and `out` modports.
+
+### Fixed
+
+
 ## 0.1.0 - 2018-09-12
 ### Changed
 - Open source release.
 
 ### Added
-- Initial commit.
+- Initial commit.

CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contribution Guidelines
+
+## Coding Style
+
+All SystemVerilog code in this repository _must_ adhere to the [SystemVerilog Coding Style Guide by
+lowRISC](https://github.com/lowRISC/style-guides/blob/master/VerilogCodingStyle.md) and the
+following rules:
+
+- All module names _must_ start with `apb_`.
+
+- User-facing modules _must_ have SystemVerilog `struct`s as APB ports.  The concrete `struct` type
+  _must_ be defined as `parameter` to the module.  The fields of the `struct` _must_ correspond to
+  those defined by our [`typedef`
+  macros](https://github.com/pulp-platform/apb/blob/master/include/apb/typedef.svh).
+
+- User-facing modules _may_ come with a variant that has SystemVerilog interfaces as APB ports.
+  - Such an interface variant module _must not_ implement any functionality except wiring its
+    interfaces to the `struct` ports of the original module.
+  - The name of an interface variant _must_ be the name of the original module suffixed by `_intf`.
+  - The parameters of an interface variant must be formatted `ALL_CAPS`.
+
+
+## Collaboration Guidelines
+
+We follow [`pulp-platform`'s Collaboration
+Guidelines](https://github.com/pulp-platform/style-guidelines/blob/master/CONTRIBUTING.md).

README.md

@@ -1,3 +1,35 @@
 # APB
 
-This repository contains common functions and hardware modules for the Advanced Peripherals Bus (APB).
+This is the implementation of the AMBA APB4 protocol, version 2.0, developed as part of the PULP
+platform at ETH Zurich.
+
+Maintainer: Andreas Kurth <[email protected]>
+
+## Overview
+
+### Package / Macros
+
+|           Name                           |                     Description                                   |
+|------------------------------------------|-------------------------------------------------------------------|
+| [`apb_pkg`](src/apb_pkg.sv)              | Package with APB4 constants and type definitions                  |
+| [`apb/typedef`](include/apb/typedef.svh) | Macros which define the APB4 request/response structs             |
+| [`apb/assign`](include/apb/typedef.svh)  | Macros which assign/set/translates APB4 interfaces and structs    |
+
+### Interfaces
+
+|           Name                           |                     Description                                   |
+|------------------------------------------|-------------------------------------------------------------------|
+| [`APB`](src/apb_intf.sv)                 | APB4 interface with configurable address, data and sel widths     |
+| [`APB_DV`](src/apb_intf.sv)              | Clocked variant of `APB` for design verification                  |
+
+### Leaf Modules
+
+|           Name                           |                     Description                                   |
+|------------------------------------------|-------------------------------------------------------------------|
+| [`apb_regs`](src/apb_regs.sv)            | Read and write registers, with optional read only mapping         |
+
+### Verification and Simulation
+
+|           Name                           |                     Description                                   |
+|------------------------------------------|-------------------------------------------------------------------|
+| [`apb_driver`](src/apb_test.sv)          | APB driver (can act as either slave or master)                    |

include/apb/assign.svh

@@ -0,0 +1,115 @@
+// Copyright (c) 2018 ETH Zurich, University of Bologna
+//
+// Copyright and related rights are licensed under the Solderpad Hardware
+// License, Version 0.51 (the "License"); you may not use this file except in
+// compliance with the License.  You may obtain a copy of the License at
+// http://solderpad.org/licenses/SHL-0.51. Unless required by applicable law
+// or agreed to in writing, software, hardware and materials distributed under
+// this 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.
+
+`ifndef APB_ASSIGN_SVH_
+`define APB_ASSIGN_SVH_
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+// Assign an APB4 interface to another, as if you would do in `assign slv = mst;`.
+//
+// Usage example:
+// `APB_ASSIGN(slv, mst)
+`define APB_ASSIGN(dst, src)         \
+  assign dst.paddr   = src.paddr;    \
+  assign dst.pprot   = src.pprot;    \
+  assign dst.psel    = src.psel;     \
+  assign dst.penable = src.penable;  \
+  assign dst.pwrite  = src.pwrite;   \
+  assign dst.pwdata  = src.pwdata;   \
+  assign dst.pstrb   = src.pstrb;    \
+  assign src.pready  = dst.pready;   \
+  assign src.prdata  = dst.prdata;   \
+  assign src.pslverr = dst.pslverr;
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+// Internal implementation for assigning interfaces from structs, allows for standalone assignments
+// (with `opt_as = assign`) and assignments inside process (with `opt_as` void) with the same code.
+`define APB_FROM_REQ(opt_as, apb_if, req_struct) \
+  opt_as apb_if.paddr   = req_struct.paddr;      \
+  opt_as apb_if.pprot   = req_struct.pprot;      \
+  opt_as apb_if.psel    = req_struct.psel;       \
+  opt_as apb_if.penable = req_struct.penable;    \
+  opt_as apb_if.pwrite  = req_struct.pwrite;     \
+  opt_as apb_if.pwdata  = req_struct.pwdata;     \
+  opt_as apb_if.pstrb   = req_struct.pstrb;
+`define APB_FROM_RESP(opt_as, apb_if, resp_struct) \
+  opt_as apb_if.pready  = resp_struct.pready;      \
+  opt_as apb_if.prdata  = resp_struct.prdata;      \
+  opt_as apb_if.pslverr = resp_struct.pslverr;
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+// Setting an interface from request/response structs inside a process.
+//
+// Usage Example:
+// always_comb begin
+//   `APB_SET_FROM_REQ(my_if, my_req_struct)
+//   `APB_SET_FROM_RESP(my_if, my_resp_struct)
+// end
+`define APB_SET_FROM_REQ(apb_if, req_struct)  `APB_FROM_REQ(, apb_if, req_struct)
+`define APB_SET_FROM_RESP(apb_if, resp_struct) `APB_FROM_RESP(, apb_if, resp_struct)
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+// Assigning an interface from request/response structs outside a process.
+//
+// Usage Example:
+// `APB_ASSIGN_FROM_REQ(my_if, my_req_struct)
+// `APB_ASSIGN_FROM_RESP(my_if, my_resp_struct)
+`define APB_ASSIGN_FROM_REQ(apb_if, req_struct)  `APB_FROM_REQ(assign, apb_if, req_struct)
+`define APB_ASSIGN_FROM_RESP(apb_if, resp_struct) `APB_FROM_RESP(assign, apb_if, resp_struct)
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+// Internal implementation for assigning to structs from interfaces, allows for standalone
+// assignments (with `opt_as = assign`) and assignments inside processes (with `opt_as` void) with
+// the same code.
+`define APB_TO_REQ(opt_as, req_struct, apb_if) \
+  opt_as req_struct = '{                       \
+    paddr:   apb_if.paddr,                     \
+    pprot:   apb_if.pprot,                     \
+    psel:    apb_if.psel,                      \
+    penable: apb_if.penable,                   \
+    pwrite:  apb_if.pwrite,                    \
+    pwdata:  apb_if.pwdata,                    \
+    pstrb:   apb_if.pstrb                      \
+  };
+`define APB_TO_RESP(opt_as, resp_struct, apb_if) \
+  opt_as req_struct = '{                         \
+    pready:  apb_if.pready,                      \
+    prdata:  apb_if.prdata,                      \
+    pslverr: apb_if.pslverr                      \
+  };
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+// Setting to an interface request/response structs inside a process.
+//
+// Usage Example:
+// always_comb begin
+//   `APB_SET_TO_REQ(my_req_struct, my_if);
+//   `APB_SET_TO_RESP(my_resp_struct, my_if);
+// end
+`define APB_SET_TO_REQ(req_struct, apb_if)   `APB_TO_REQ(, req_struct, apb_if)
+`define APB_SET_TO_RESP(resp_struct, apb_if) `APB_TO_RESP(, resp_struct, apb_if)
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+// Assigning to an interface request/response structs outside a process.
+//
+// Usage Example:
+// `APB_ASSIGN_TO_REQ(my_req_struct, my_if);
+`define APB_ASSIGN_TO_REQ(req_struct, apb_if)   `APB_TO_REQ(assign, req_struct, apb_if)
+`define APB_ASSIGN_TO_RESP(resp_struct, apb_if) `APB_TO_RESP(assign, resp_struct, apb_if)
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+`endif

include/apb/typedef.svh

@@ -0,0 +1,44 @@
+// Copyright (c) 2020 ETH Zurich, University of Bologna
+//
+// Copyright and related rights are licensed under the Solderpad Hardware
+// License, Version 0.51 (the "License"); you may not use this file except in
+// compliance with the License.  You may obtain a copy of the License at
+// http://solderpad.org/licenses/SHL-0.51. Unless required by applicable law
+// or agreed to in writing, software, hardware and materials distributed under
+// this 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:
+// Wolfgang Roenninger  <[email protected]>
+
+// Macros to define APB4 Request/Response Structs
+
+`ifndef APB_TYPEDEF_SVH_
+`define APB_TYPEDEF_SVH_
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+// APB4 (v2.0) Request/Response Structs
+//
+// Usage Example:
+// `APB_TYPEDEF_REQ_T  ( apb_req_t,  addr_t, data_t, strb_t )
+// `APB_TYPEDEF_RESP_T ( apb_resp_t, data_t )
+`define APB_TYPEDEF_REQ_T(apb_req_t, addr_t, data_t, strb_t)  \
+  typedef struct packed {                                     \
+    addr_t          paddr;                                    \
+    apb_pkg::prot_t pprot;                                    \
+    logic           psel;                                     \
+    logic           penable;                                  \
+    logic           pwrite;                                   \
+    data_t          pwdata;                                   \
+    strb_t          pstrb;                                    \
+  } apb_req_t;
+`define APB_TYPEDEF_RESP_T(apb_resp_t, data_t) \
+  typedef struct packed {                      \
+    logic  pready;                             \
+    data_t prdata;                             \
+    logic  pslverr;                            \
+    } apb_resp_t;
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+`endif

scripts/compile_vsim.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# Copyright (c) 2014-2020 ETH Zurich, University of Bologna
+#
+# Copyright and related rights are licensed under the Solderpad Hardware
+# License, Version 0.51 (the "License"); you may not use this file except in
+# compliance with the License.  You may obtain a copy of the License at
+# http://solderpad.org/licenses/SHL-0.51. Unless required by applicable law
+# or agreed to in writing, software, hardware and materials distributed under
+# this 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.
+#
+# Fabian Schuiki      <[email protected]>
+# Andreas Kurth       <[email protected]>
+# Wolfgang Roenninger <[email protected]>
+
+set -e
+
+bender script vsim -t test --vlog-arg="-svinputport=compat" --vlog-arg="-override_timescale 1ns/1ps" > compile.tcl
+echo 'return 0' >> compile.tcl
+vsim -c -do 'exit -code [source compile.tcl]'

scripts/run_vsim.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+# Copyright (c) 2014-2020 ETH Zurich, University of Bologna
+#
+# Copyright and related rights are licensed under the Solderpad Hardware
+# License, Version 0.51 (the "License"); you may not use this file except in
+# compliance with the License.  You may obtain a copy of the License at
+# http://solderpad.org/licenses/SHL-0.51. Unless required by applicable law
+# or agreed to in writing, software, hardware and materials distributed under
+# this 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.
+#
+# Fabian Schuiki      <[email protected]>
+# Andreas Kurth       <[email protected]>
+# Wolfgang Roenninger <[email protected]>
+
+set -e
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+
+[ ! -z "$VSIM" ] || VSIM=vsim
+
+call_vsim() {
+	echo "run -all" | $VSIM "$@" | tee vsim.log 2>&1
+	grep "Errors: 0," vsim.log
+}
+
+call_vsim tb_apb_regs -64 -t 1ns -coverage -lib work -voptargs="+acc +cover=bcesfx"