Merge branch 'main' into pages

williaml33moore · Apr 9, 2024 · 4996d4b · 4996d4b
2 parents 3225763 + d78f27a
commit 4996d4b
Show file tree

Hide file tree

Showing 13 changed files with 81 additions and 27 deletions.
diff --git a/README.md b/README.md
@@ -2,47 +2,101 @@
 
 ![Bathtub_Logo](docs/assets/Bathtub_Logo.png)
 
-Bathtub is an open-source
+Bathtub is a free open-source
 SystemVerilog package
 based on UVM 
 that brings Agile Behavior-Driven Development (BDD)
 and Gherkin
 to the design and verification of integrated circuits,
 enabling executable specifications and true living documentation.
 
-This repo contains the following:
+## Behavior-Driven Development for Integrated Circuits
+BDD helps you and your colleagues bring your diverse perspectives--business, design, verification, software--to the specification of new RTL features for your ASIC, SoC, FPGA, and IP projects. Together, you create living documentation that not only describes the intent, but also automatically checks the behavior of the device.
+* Write your chip design specs in Cucumber-compliant Gherkin, the de facto standard plain text file format for executable specifications.
+* Give concrete examples in the Gherkin files that illustrate functionality and guide front-end design.
+* Bathtub reads and parses your Gherkin files and runs them as automated acceptance tests against your RTL.
+* When the tests pass, you know your RTL behaves as the specs say it should.
+* BDD is not just for software development anymore; IC design and verification can be Agile too!
 
-[Source code](https://github.com/williaml33moore/bathtub)
-: The Bathtub code is available open-source under the [M.I.T. license](https://github.com/williaml33moore/bathtub/blob/main/LICENSE).
-The repo is available for cloning and forking, but I don't expect to entertain pull requests until it has reached a more complete release milestone. Bathtub is written in SystemVerilog and requires a full-featured SystemVerilog simulator with UVM to run.
+```gherkin
+# Sample Gherkin feature file
 
-[Pages](https://williaml33moore.github.io/bathtub/)
-: Web pages, deployed and served from the [`pages`](https://github.com/williaml33moore/bathtub/tree/pages) branch to [https://williaml33moore.github.io/bathtub/](https://williaml33moore.github.io/bathtub/).
+Feature: Arithmetic Logic Unit division operations
 
-These easy-to-remember bookmarkable URLs all redirect you to the home page:
-* [bathtubBDD.dev](https://bathtubbdd.dev)
-* [bathtubBDD.com](http://bathtubbdd.com)
-* [bathtubBDD.org](http://bathtubbdd.org)
+    The arithmetic logic unit performs integer division.
+
+    Scenario: With integer division, the remainder is discarded
+        Given operand A is 15 and operand B is 4
+        When the ALU performs the division operation
+        Then the result should be 3
+        And the DIV_BY_ZERO flag should be clear
+
+    Scenario: Attempting to divide by zero results in an error
+        Given operand A is 10 and operand B is 0
+        When the ALU performs the division operation
+        Then the DIV_BY_ZERO flag should be raised
+```
+
+## Seamless Integration with Existing Verification Environments
+As a design verification engineer, you use Bathtub to translate the natural language Gherkin files into self-checking SystemVerilog tests that run on your chip's testbench so you can close the BDD loop and drive to tapeout with confidence.
+* Bathtub is written entirely in SystemVerilog and UVM open source code; there are no additional applications to install or integrate.
+* Run Bathtub natively in your SystemVerilog simulator as an extension of your DUT's UVM tests, e.g., `+UVM_TESTNAME=my_bathtub_test`.
+* Reuse all your current verification components, unchanged.
+* With convenient Bathtub macros, write parameterized step definitions in the form of simple UVM virtual sequence classes for all the _Given-When-Then_ steps in your Gherkin scenarios.
+* Include your Bathtub tests in your regression suites to validate changes to specs and RTL.
+* You're not limited to RTL; you can use BDD to document, implement, and unit-test stand-alone verification components or, for that matter, _any_ isolated SystemVerilog code.
+
+```sv
+// Sample step definition: a UVM virtual sequence class
+
+class set_operand_A_and_B_vseq extends alu_base_vsequence
+        implements bathtub_pkg::step_definition_interface;
 
-but you will note from the true URL in your web browser that these pages are served from GitHub.
+    `Given("operand A is %d and operand B is %d")
 
-[Issues](https://github.com/williaml33moore/bathtub/issues)
-: These are for tracking tasks and reporting bugs.
+    int operand_A, operand_B;
 
-[Discussions](https://github.com/williaml33moore/bathtub/discussions)
-: This is currently the preferred forum for community conversation about Bathtub. It requires a free GitHub account. You can sign up [here](https://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F%3Cuser-name%3E%2F%3Crepo-name%3E%2Fdiscussions%2Findex&source=header-repo&source_repo=williaml33moore%2Fbathtub_).
+   `uvm_object_utils(set_operand_A_and_B_vseq)
+    function new (string name="set_operand_A_and_B_vseq");
+        super.new(name);
+    endfunction : new
 
-[Wiki](https://github.com/williaml33moore/bathtub/wiki)
-: For technical documentation and user guides.
+    virtual task body();
+        // Extract the parameters
+        `step_parameter_get_args_begin()
+        operand_A = `step_parameter_get_next_arg_as(int);
+        operand_B = `step_parameter_get_next_arg_as(int);
+        `step_parameter_get_args_end
+
+        // Do the actual work using the API in the base sequence
+        super.set_operand_A(operand_A); 
+        super.set_operand_B(operand_B);
+    endtask : body
+endclass : set_operand_A_and_B_vseq
+```
+
+This repository contains the following:
+
+* [Code](https://github.com/williaml33moore/bathtub): Bathtub source code
+* [Wiki](https://github.com/williaml33moore/bathtub/wiki): Technical documentation and user guides
+* [Discussions](https://github.com/williaml33moore/bathtub/discussions): Join the conversation (requires a free [account](https://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F%3Cuser-name%3E%2F%3Crepo-name%3E%2Fdiscussions%2Findex&source=header-repo&source_repo=williaml33moore%2Fbathtub_))
+* [Issues](https://github.com/williaml33moore/bathtub/issues): Task and bug tracking
+
+Bathtub is written in SystemVerilog and requires a full-featured SystemVerilog simulator with UVM to run.
+
+This repository also hosts the Bathtub web site, deployed from the [`pages`](https://github.com/williaml33moore/bathtub/tree/pages) branch and served to [https://williaml33moore.github.io/bathtub/](https://williaml33moore.github.io/bathtub/).
+These easy-to-remember bookmarkable URLs all redirect you to the home page:
+* [bathtubBDD.dev](https://bathtubbdd.dev)
+* [bathtubBDD.com](http://bathtubbdd.com)
+* [bathtubBDD.org](http://bathtubbdd.org)
 
-Bathtub is a new work-in-progress so everything is incomplete today, but continuously improving.
+**B.A.T.H.T.U.B.**: \
+**B**DD \
+**A**utomated \
+**T**ests \
+**H**elping \
+**T**eams \
+**U**nderstand \
+**B**ehavior
 
-B.A.T.H.T.U.B.:
-- BDD
-- Automated
-- Tests
-- Helping
-- Teams
-- Understand
-- Behavior
 
diff --git a/bathtub_macros.sv → src/bathtub_macros.sv b/bathtub_macros.sv → src/bathtub_macros.sv
diff --git a/bathtub_pkg.sv → src/bathtub_pkg.sv b/bathtub_pkg.sv → src/bathtub_pkg.sv
diff --git a/gherkin_pkg.sv → src/gherkin_pkg.sv b/gherkin_pkg.sv → src/gherkin_pkg.sv
diff --git a/bathtub_pkg_test_suite/.gitkeep → test/bathtub_pkg_test_suite/.gitkeep b/bathtub_pkg_test_suite/.gitkeep → test/bathtub_pkg_test_suite/.gitkeep
diff --git a/bathtub_pkg_test_suite/README.txt → test/bathtub_pkg_test_suite/README.txt b/bathtub_pkg_test_suite/README.txt → test/bathtub_pkg_test_suite/README.txt
diff --git a/bathtub_pkg_test_suite/bathtub_unit_test.sv → ...thtub_pkg_test_suite/bathtub_unit_test.sv b/bathtub_pkg_test_suite/bathtub_unit_test.sv → ...thtub_pkg_test_suite/bathtub_unit_test.sv
diff --git a/...pkg_test_suite/bathtub_utils_unit_test.sv → ...pkg_test_suite/bathtub_utils_unit_test.sv b/...pkg_test_suite/bathtub_utils_unit_test.sv → ...pkg_test_suite/bathtub_utils_unit_test.sv
diff --git a/...ite/gherkin_document_printer_unit_test.sv → ...ite/gherkin_document_printer_unit_test.sv b/...ite/gherkin_document_printer_unit_test.sv → ...ite/gherkin_document_printer_unit_test.sv
diff --git a/...uite/gherkin_document_runner_unit_test.sv → ...uite/gherkin_document_runner_unit_test.sv b/...uite/gherkin_document_runner_unit_test.sv → ...uite/gherkin_document_runner_unit_test.sv
diff --git a/...b_pkg_test_suite/step_nature_unit_test.sv → ...b_pkg_test_suite/step_nature_unit_test.sv b/...b_pkg_test_suite/step_nature_unit_test.sv → ...b_pkg_test_suite/step_nature_unit_test.sv
diff --git a/...g_test_suite/step_parameters_unit_test.sv → ...g_test_suite/step_parameters_unit_test.sv b/...g_test_suite/step_parameters_unit_test.sv → ...g_test_suite/step_parameters_unit_test.sv
diff --git a/bathtub_pkg_test_suite/svunit.f → test/bathtub_pkg_test_suite/svunit.f b/bathtub_pkg_test_suite/svunit.f → test/bathtub_pkg_test_suite/svunit.f