Added Libraries/AMBA_Fabrics/ and doc/How_to_Contrib

Libraries/AMBA_Fabrics/AXI4_Lite/AXI4L_Xactors.bsv

@@ -12,7 +12,7 @@ package AXI4L_Xactors;
 //     BSV FIFO-like interfaces (flow-controlled)
 //     ARM AXI4 signals (ready/valid protocol)
 
-// This code is adapted from similr AXI4 code provided by Joe Stoy
+// This code is adapted from similar AXI4 code provided by Joe Stoy
 
 // ================================================================
 // BSV library imports

Libraries/AMBA_Fabrics/AXI4_Stream/AXI4_Stream.bsv

@@ -1,4 +1,6 @@
 // Copyright (c) 2019 Bluespec, Inc.  All Rights Reserved
+//
+// SPDX-License-Identifier: BSD-3-Clause
 
 package AXI4_Stream;
 

Libraries/AMBA_Fabrics/Adapters/Makefile

@@ -9,7 +9,9 @@ LIBNAME=AMBA_Fabrics/Adapters
 include ../../common.mk
 
 # Requires files in Misc and AMBA_Fabrics/AXI4 and AMBA_Fabrics/AXI4_Lite
-BSCFLAGS += -p $(BUILDDIR)/../../Misc:$(BUILDDIR)/../../AMBA_Fabrics/AXI4:$(BUILDDIR)/../../AMBA_Fabrics/AXI4_Lite:+
+BSCFLAGS += -p $(BUILDDIR)/../../AMBA_Fabrics/AXI4:+ \
+	    -p $(BUILDDIR)/../../AMBA_Fabrics/AXI4_Lite:+ \
+	    -p $(BUILDDIR)/../../Misc:+
 
 .PHONY: build
 build:

Libraries/AMBA_Fabrics/Utils/ByteLane.bsv

@@ -1,4 +1,6 @@
 // Copyright (c) 2017-2019 Bluespec, Inc.  All Rights Reserved
+//
+// SPDX-License-Identifier: BSD-3-Clause
 
 package ByteLane;
 

doc/How_to_Contribute.adoc

@@ -1,15 +1,20 @@
 = How to Contribute to `bsc-contrib`
-:revnumber: v1.02
-:revdate: 2024-11-19
+:revnumber: v1.03
+:revdate: 2024-11-21
 :sectnums:
 
 // ================================================================
 
 Let's assume you want to contribute a new library `MyContrib`.  All
-your sources and documentation should be placed in a new sub-dir:
+your B-Lang (BSV/BH) sources and documentation should be placed in a
+new sub-dir:
 
     bsc-contrib/Libraries/MyContrib/
 
+If your BSV/BH code imports any Verilog, it should be placed in:
+
+    bsc-contrib/Verilog/
+
 If you also have unit-tests, they should be in a new sub-dir:
 
     bsc-contrib/testing/bsc.contrib/Unit_Test_MyContrib
@@ -28,18 +33,19 @@ We suggest the following "flow":
 
 * On GitHub, create a FORK of the original `bsc-contrib` repo, under your own account.
 * Clone your FORK to your work area (laptop, desktop, ...).
-* Create a new BRANCH.
-* Prepare your contribution in your new BRANCH, including formatting,
-  copyrights, licenses, build-and-install Makefiles and unit-tests.
-  See the sections below for details.
+* Create a new BRANCH in your clone of your FORK.
+* In this new BRANCH (in your clone of your FORK), prepare your
+  contribution, including formatting, copyrights, licenses,
+  build-and-install Makefiles and optional unit-tests. See the
+  sections below for details.
 * Commit your BRANCH.
 
 * Please "squash" any "uninteresting" older commits so that the PR
   contains only useful commits (that a future maintainer may find
   useful).  In most cases, one can squash everything into a single,
   final commit on top of the most recent `bsc-contrib` commit.
 
-* Push the commit up to your FORK.
+* Push the commit from your clone up to your FORK.
 * From your FORK, create a PR for the original `bsc-contrib` repo.
 
 // ================================================================
@@ -85,18 +91,24 @@ AsciiDoctor (`.adoc`) are automatically rendered by GitHub.
 // ================================================================
 == Makefiles for building and installing
 
-`make all` at the top level descends recursively into sub-dirs.  In a
-leaf-level library dir the Makefile contains a `build` target to
-compile the source file(s) in that dir.  The corresponding object
-files get copied into the installation directory (default
-`bsc-contrib/inst`).  You can also specify other files to be copied
-(include files, config files, ...).  This `make` is performed for
-installation, but also repeatedly automatically by CI (continuous
-integration), to check that it succeeds.
+`make all` at the top level descends recursively into all sub-dirs of
+`Libraries` and `Verilog`.  In a leaf-level library dir the Makefile
+contains a `build` target to compile source file(s) that are in that
+dir.  The corresponding object files get copied into the installation
+directory (default `bsc-contrib/inst`).  You can also specify other
+files to be copied (include files, config files, ...).
+
+If you added any files to the `Verilog/` dir, add those filenames to
+the `VERI_FILES` list in the `Verilog/Makefile`.
+
+The top-level `make all` is performed for installation, but is also
+repeated automatically during CI (continuous integration) to check
+that it succeeds.
 
-NOTE: This just compiles sources, it does not build executables.  See
-      separate "Unit Tests" section for building unit-test executables
-      and running them.  Those are also performed by CI.
+NOTE: In the `Library` sub-dirs, this just compiles sources, it does
+      not build executables.  See separate "Unit Tests" section for
+      building unit-test executables and running them.  Those are also
+      performed by CI.
 
 // ----------------------------------------------------------------
 
@@ -154,7 +166,7 @@ You can optionally add unit tests for your library source files; these
 unit tests are run automatically and repeatedly as part of CI
 (Continuous Integration).
 
-NOTE: `bsc-contrib`'s unit-testing is performed as part of the main
+NOTE: `bsc-contrib` 's unit-testing is performed as part of the main
       `bsc` compiler's testing of standard libraries, using the same
       infrastructure.  The infrastructure has more ways to configure
       testing than described in this section; please see the `bsc`
@@ -164,11 +176,12 @@ Add your unit tests to `bsc-contrib/testing/bsc.contrib/`.  You can
 study any of the existing unit tests in that directory for guidance.
 Briefly:
 
-* Add a sub-dir for a new unit-test (let's call it TEST here for discussion).
+* Add a sub-dir for a new set of unit-tests for the new library (it
+  can have sub-dirs for more detailed structure):
 
-    bsc-contrib/testing/bsc.contrib/TEST
+    bsc-contrib/testing/bsc.contrib/MyContrib/
 
-* In TEST:
+* In this dir:
 
 ** Each top-level test driver module should be in a file `Foo.bsv` or
    `Foo.bs`, and the module should be called `sysFoo`, with an `Empty`
@@ -178,10 +191,11 @@ Briefly:
    test, not library files), they can be placed here, too.
 
 ** Create a file `sysFoo.out.expected` containing output expected when
-   it is run +
+   it is run.
++
 If different output is expected from Bluesim vs. Verilog sim (e.g.,
-$time can be slightly different), you can instead have separate files
-for each:
+  `$time` can be slightly different), you can instead have separate
+  files for each:
 
 *** for Bluesim: `sysFoo.c.out.expected`
 *** for Verilog: `sysFoo.v.out.expected`
@@ -192,17 +206,17 @@ for each:
 
 Please run your tests before submitting a PR.
 
-See the "Testing" section of the README in `bsc-contrib` for
-information on how to run them (you have to copy `bsc-contrib` into
-the `bsc` repo and run it there).
+See the "Testing" section of the link:../README.md[README] in
+`bsc-contrib` for information on how to run them (you have to copy
+`testing/bsc-contrib` into the `bsc` repo and run it there).
 
 NOTE: (Future restructuring plans) +
       We would like unit tests for
       library `MyContrib` to be located along with its sources, i.e.,
       under `Libraries/MyContrib`, instead of separately in
-      `testing/bsc.contrib/TEST`.  The current structure exists
+      `testing/bsc.contrib/MyContrib`.  The current structure exists
       because it is derived from historical roots where `bsc-contrib`
-      's testing is done along with `bsc` 's testing using shared
+      's testing was done along with `bsc` 's testing using shared
       infrastructure in the `bsc` repo.
 
 // ================================================================

doc/How_to_Contribute.html

@@ -438,23 +438,32 @@
 <div id="header">
 <h1>How to Contribute to <code>bsc-contrib</code></h1>
 <div class="details">
-<span id="revnumber">version v1.02,</span>
-<span id="revdate">2024-11-19</span>
+<span id="revnumber">version v1.03,</span>
+<span id="revdate">2024-11-21</span>
 </div>
 </div>
 <div id="content">
 <div id="preamble">
 <div class="sectionbody">
 <div class="paragraph">
 <p>Let&#8217;s assume you want to contribute a new library <code>MyContrib</code>.  All
-your sources and documentation should be placed in a new sub-dir:</p>
+your B-Lang (BSV/BH) sources and documentation should be placed in a
+new sub-dir:</p>
 </div>
 <div class="literalblock">
 <div class="content">
 <pre>bsc-contrib/Libraries/MyContrib/</pre>
 </div>
 </div>
 <div class="paragraph">
+<p>If your BSV/BH code imports any Verilog, it should be placed in:</p>
+</div>
+<div class="literalblock">
+<div class="content">
+<pre>bsc-contrib/Verilog/</pre>
+</div>
+</div>
+<div class="paragraph">
 <p>If you also have unit-tests, they should be in a new sub-dir:</p>
 </div>
 <div class="literalblock">
@@ -497,12 +506,13 @@ <h2 id="_logistics">1. Logistics</h2>
 <p>Clone your FORK to your work area (laptop, desktop, &#8230;&#8203;).</p>
 </li>
 <li>
-<p>Create a new BRANCH.</p>
+<p>Create a new BRANCH in your clone of your FORK.</p>
 </li>
 <li>
-<p>Prepare your contribution in your new BRANCH, including formatting,
-copyrights, licenses, build-and-install Makefiles and unit-tests.
-See the sections below for details.</p>
+<p>In this new BRANCH (in your clone of your FORK), prepare your
+contribution, including formatting, copyrights, licenses,
+build-and-install Makefiles and optional unit-tests. See the
+sections below for details.</p>
 </li>
 <li>
 <p>Commit your BRANCH.</p>
@@ -514,7 +524,7 @@ <h2 id="_logistics">1. Logistics</h2>
 final commit on top of the most recent <code>bsc-contrib</code> commit.</p>
 </li>
 <li>
-<p>Push the commit up to your FORK.</p>
+<p>Push the commit from your clone up to your FORK.</p>
 </li>
 <li>
 <p>From your FORK, create a PR for the original <code>bsc-contrib</code> repo.</p>
@@ -596,14 +606,21 @@ <h2 id="_readme">4. README</h2>
 <h2 id="_makefiles_for_building_and_installing">5. Makefiles for building and installing</h2>
 <div class="sectionbody">
 <div class="paragraph">
-<p><code>make all</code> at the top level descends recursively into sub-dirs.  In a
-leaf-level library dir the Makefile contains a <code>build</code> target to
-compile the source file(s) in that dir.  The corresponding object
-files get copied into the installation directory (default
-<code>bsc-contrib/inst</code>).  You can also specify other files to be copied
-(include files, config files, &#8230;&#8203;).  This <code>make</code> is performed for
-installation, but also repeatedly automatically by CI (continuous
-integration), to check that it succeeds.</p>
+<p><code>make all</code> at the top level descends recursively into all sub-dirs of
+<code>Libraries</code> and <code>Verilog</code>.  In a leaf-level library dir the Makefile
+contains a <code>build</code> target to compile source file(s) that are in that
+dir.  The corresponding object files get copied into the installation
+directory (default <code>bsc-contrib/inst</code>).  You can also specify other
+files to be copied (include files, config files, &#8230;&#8203;).</p>
+</div>
+<div class="paragraph">
+<p>If you added any files to the <code>Verilog/</code> dir, add those filenames to
+the <code>VERI_FILES</code> list in the <code>Verilog/Makefile</code>.</p>
+</div>
+<div class="paragraph">
+<p>The top-level <code>make all</code> is performed for installation, but is also
+repeated automatically during CI (continuous integration) to check
+that it succeeds.</p>
 </div>
 <div class="admonitionblock note">
 <table>
@@ -612,9 +629,10 @@ <h2 id="_makefiles_for_building_and_installing">5. Makefiles for building and in
 <div class="title">Note</div>
 </td>
 <td class="content">
-This just compiles sources, it does not build executables.  See
-      separate "Unit Tests" section for building unit-test executables
-      and running them.  Those are also performed by CI.
+In the <code>Library</code> sub-dirs, this just compiles sources, it does
+      not build executables.  See separate "Unit Tests" section for
+      building unit-test executables and running them.  Those are also
+      performed by CI.
 </td>
 </tr>
 </table>
@@ -720,8 +738,8 @@ <h2 id="_optional_unit_tests">6. Optional Unit Tests</h2>
 <div class="title">Note</div>
 </td>
 <td class="content">
-<code>bsc-contrib&#8217;s unit-testing is performed as part of the main
-      `bsc</code> compiler&#8217;s testing of standard libraries, using the same
+<code>bsc-contrib</code> 's unit-testing is performed as part of the main
+      <code>bsc</code> compiler&#8217;s testing of standard libraries, using the same
       infrastructure.  The infrastructure has more ways to configure
       testing than described in this section; please see the <code>bsc</code>
       repo for more details (<a href="https://github.com/B-Lang-org/bsc" class="bare">https://github.com/B-Lang-org/bsc</a>).
@@ -737,15 +755,16 @@ <h2 id="_optional_unit_tests">6. Optional Unit Tests</h2>
 <div class="ulist">
 <ul>
 <li>
-<p>Add a sub-dir for a new unit-test (let&#8217;s call it TEST here for discussion).</p>
+<p>Add a sub-dir for a new set of unit-tests for the new library (it
+can have sub-dirs for more detailed structure):</p>
 <div class="literalblock">
 <div class="content">
-<pre>bsc-contrib/testing/bsc.contrib/TEST</pre>
+<pre>bsc-contrib/testing/bsc.contrib/MyContrib/</pre>
 </div>
 </div>
 </li>
 <li>
-<p>In TEST:</p>
+<p>In this dir:</p>
 <div class="ulist">
 <ul>
 <li>
@@ -759,10 +778,12 @@ <h2 id="_optional_unit_tests">6. Optional Unit Tests</h2>
 </li>
 <li>
 <p>Create a file <code>sysFoo.out.expected</code> containing output expected when
-   it is run<br>
-If different output is expected from Bluesim vs. Verilog sim (e.g.,
-$time can be slightly different), you can instead have separate files
-for each:</p>
+it is run.</p>
+<div class="paragraph">
+<p>If different output is expected from Bluesim vs. Verilog sim (e.g.,
+  <code>$time</code> can be slightly different), you can instead have separate
+  files for each:</p>
+</div>
 <div class="ulist">
 <ul>
 <li>
@@ -785,9 +806,9 @@ <h3 id="_running_unit_tests">6.1. Running unit tests</h3>
 <p>Please run your tests before submitting a PR.</p>
 </div>
 <div class="paragraph">
-<p>See the "Testing" section of the README in <code>bsc-contrib</code> for
-information on how to run them (you have to copy <code>bsc-contrib</code> into
-the <code>bsc</code> repo and run it there).</p>
+<p>See the "Testing" section of the <a href="../README.md">README</a> in
+<code>bsc-contrib</code> for information on how to run them (you have to copy
+<code>testing/bsc-contrib</code> into the <code>bsc</code> repo and run it there).</p>
 </div>
 <div class="admonitionblock note">
 <table>
@@ -800,9 +821,9 @@ <h3 id="_running_unit_tests">6.1. Running unit tests</h3>
       We would like unit tests for
       library <code>MyContrib</code> to be located along with its sources, i.e.,
       under <code>Libraries/MyContrib</code>, instead of separately in
-      <code>testing/bsc.contrib/TEST</code>.  The current structure exists
+      <code>testing/bsc.contrib/MyContrib</code>.  The current structure exists
       because it is derived from historical roots where <code>bsc-contrib</code>
-      's testing is done along with <code>bsc</code> 's testing using shared
+      's testing was done along with <code>bsc</code> 's testing using shared
       infrastructure in the <code>bsc</code> repo.
 </td>
 </tr>
@@ -814,8 +835,8 @@ <h3 id="_running_unit_tests">6.1. Running unit tests</h3>
 </div>
 <div id="footer">
 <div id="footer-text">
-Version v1.02<br>
-Last updated 2024-11-20 11:21:30 -0500
+Version v1.03<br>
+Last updated 2024-11-21 09:57:17 -0500
 </div>
 </div>
 </body>