alu_division

ALU Division

Introduction

ALU Division is a small example of a complete Bathtub environment. This example is included in the DVCon U.S. 2024 paper, “Gherkin Implementation in SystemVerilog Brings Agile Behavior-Driven Development to UVM.” The paper contains:

• The ALU Division Gherkin feature file
• Two step definitions
• The Bathtub UVM test

This sample environment contains just enough testbench to validate that the code samples in the paper are functional. Still, this example may be instructive.

EDA Playground

This complete example is available as an EDA Playground at bathtub_test_paper. It is open freely for viewing, but registration is required to run it.

Most the files from EDA Playground have been downloaded and committed to the GitHub repository here: https://github.com/williaml33moore/bathtub/tree/main/examples/alu_division. EDA Playground downloads the entire playground--input and output files--in a single directory called results. The entire results directory (minus a few unnecessary files) is committed in the repository for simplicity. We do not recommend storing everything in a single directory like this on an actual ASIC project.

Gherkin Feature File

The Bathtub flow begins with a Gherkin Feature File. Presumably teammates gather to discuss the behavior of a new feature, and formulate their findings in a plain text file like this. The ALU Division feature file is alu_division.feature:

# This Gherkin feature file's name is alu_division.feature

Feature: Arithmetic Logic Unit division operations

    The arithmetic logic unit performs integer division.

    Scenario: In 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

It's a complete, but very small sample that doesn't showcase all the features of the Gherkin language.

Comments begin with #. This comment helpfully demonstrates the convention that feature filenames end with the suffix “.feature.”

The Feature: line provides a title for the high-level feature. A feature file can have only one Feature: keyword.

The block following Feature: is free-form text for documentation purposes. It can span multiple lines.

A Scenario: is a concrete example of a discrete behavior, comprised of steps. The text is a description for documentation purposes.

The Given step is declarative and sets up this division’s operands.

The When step indicates the procedural operation being tested.

The Then step asserts the expected outcome. It is traditional to use the auxiliary verb “should” in Gherkin Then steps (“should be clear”) but it carries the same meaning as stronger verbs like “must” or “shall” in that it is considered an error if the assertion fails.

And is an alias for the preceding keyword that makes the scenario more readable than repeating the keyword Then. Gherkin has additional syntactic sugar step keywords But and *; the asterisk allows the user to create bullet lists of steps. Scenarios may have any number of Given, When, Then, And, But, and * steps in any combination.

The second scenario is an error case. Note that some lines are common between the two scenarios, differing only in literal values, illustrating that steps can be parameterized and reused across behaviors.

Leading and trailing whitespace is insignificant, but the prevailing convention is to indent keyword lines consistently.

Gherkin syntax consists solely of the keywords at the beginning of each line. The text following each keyword is arbitrary, not subject to any syntactic or grammatical requirements.