bmstack
bmstack is part of BondMachine project. Within the project It is used to create stacks and queues distributed among several BondMachine cores. due to its generality it can also be used as standalone tool to produce HDL shared stacks and queues to be used in other projects. The HDL code is build using golang templates that creates the code starting from the following data structure. The comments describe the meaning of each field.
type Push struct { Agent string // The name of the agent that is pushing Tick uint64 // The tick at which the push occurs Value string // The value that is pushed } type Pop struct { Agent string // The name of the agent that is popping Tick uint64 // The tick at which the pop occurs } type TestBenchData struct { Pops []Pop // List of pops Pushes []Push // List of pushes TestSequence []string // Pushes and pops in order } type BmStack struct { ModuleName string // The name of the module DataSize int // The size of the data bus Depth int // The depth of the stack Senders []string // The names of the agents that can send data to the stack Receivers []string // The names of the agents that can receive data from the stack MemType string // "LIFO" for a stack or "FIFO" for a queue funcMap template.FuncMap // TestBench data TestBenchData }
API
The library can be used in two ways. The first one is from a go program. After creating a BmStack structure, the user can call the WriteHDL function to produce the HDL code. An example on how the library can be used this way can be seen in the go test file (bmstack_test.go).
func TestWriteHDL(t *testing.T) { // Create a new stack with 4 agents stack := BmStack{ ModuleName: "test", DataSize: 32, Depth: 8, Senders: []string{"sender1", "sender2"}, Receivers: []string{"receiver1", "receiver2"}, MemType: "LIFO" } // write the HDL code stack.WriteHDL()
The second part of the struct can be filled with test data. These data are used to produce a test bench for the stack. Using the test bench the user can verify the correctness of the stack. The test bench is produced by calling the WriteTestBench function.
func TestWriteTestBench(t *testing.T) { stack := BmStack{ // ... s.Pushes = []Push{ Push{"sender1", 200, "32'd1"}, } s.Pops = []Pop{ Pop{"receiver1", 60}, } } // write the test bench stack.WriteTestBench() }
The two functions (WriteHDL and WriteTestBench) return a string that contains the HDL code or an error if something went wrong (string, error). The provided go test file (bmstack_test.go) shows how the library can be used in this way. When invoked (go test), it produces the two files (bmstack.v and bmstack_tb.v).
CLI
the library also came with a companion CLI executable called bmstack that provides the basic interface to the library. This is the second Possible way to use it.
$ bmstack -h
Usage of bmstack:
-d Verbose
-data-width int
Width of the data bus (default 32)
-depth int
Depth of the stack/queue (default 8)
-hdl-file string
Name of the file to write the HDL to (empty string to disable) (default "stack.v")
-memory-type string
Memory type, either stack or queue (default "queue")
-random-stimulus int
Generate random stimulus including N pushes and pops for every agent (0 to disable)
-receivers string
Comma separated list of names of signal tags that will receive data from the stack/queue
-senders string
Comma separated list of names of signal tags that will send data to the stack/queue
-sim-length int
Length of the simulation in clock cycles (default 1000)
-stimulus-file string
Name of the JSON file to load the stimulus from (empty string to disable)
-tb-file string
Name of the file to write the testbench to (empty string to disable)
-v Verbose
Examples of usage:
Simulation
WIP
To see how the library is used in the BondMachine project, please refer to the BondMachine examples directory that contains many examples of BondMachines using stacks and queues.