8.4. Command-Line Arguments: $test$plusargs vs $value$plusargs
Making testbenches configurable via command-line arguments enables reusable, flexible verification environments without code modification.
8.4.1 $test$plusargs - Boolean Flag Checking
Purpose: Check if a command-line argument (flag) exists
Returns: 1 if argument found, 0 otherwise
Syntax: `$test$plusargs("argument_name")`
Use Cases: Enable/disable features, modes, debug levels
Verilog
module plusargs_flags_demo;
initial begin
$display("Configuration Flags:");
$display("--------------------");
if ($test$plusargs("DEBUG"))
$display("✓ DEBUG mode enabled");
else
$display("✗ DEBUG mode disabled");
if ($test$plusargs("VERBOSE"))
$display("✓ VERBOSE output enabled");
else
$display("✗ VERBOSE output disabled");
if ($test$plusargs("COVERAGE"))
$display("✓ COVERAGE collection enabled");
else
$display("✗ COVERAGE collection disabled");
if ($test$plusargs("WAVE_DUMP")) begin
$display("✓ Waveform dump enabled");
$dumpfile("simulation.vcd");
$dumpvars(0, plusargs_flags_demo);
end
end
endmodule
Run Command Examples:
Verilog
vsim top +DEBUG +WAVE_DUMP
vsim top +VERBOSE +COVERAGE
vsim top (no flags)
8.4.2 $value$plusargs - Retrieve Parameter Values
Purpose: Get the VALUE associated with a command-line argument
Returns: 1 if found (value stored in variable), 0 if not found
Syntax: `$value$plusargs("NAME=format", variable)`
Supported Formats:
-
`%d` - Decimal integer
-
`%h` - Hexadecimal
-
`%o` - Octal
-
`%b` - Binary
-
`%s` - String
Verilog
module plusargs_values_demo;
integer timeout, num_tests;
reg [31:0] seed;
reg [8*50:1] test_name;
real freq_mhz;
initial begin
$display("=== Simulation Configuration ===");
// Integer with default
if ($value$plusargs("TIMEOUT=%d", timeout))
$display("Timeout: %0d cycles", timeout);
else begin
timeout = 10000; // Default
$display("Timeout: %0d cycles (default)", timeout);
end
// Hexadecimal seed
if ($value$plusargs("SEED=%h", seed))
$display("Random Seed: 0x%h", seed);
else begin
seed = $time;
$display("Random Seed: 0x%h (from time)", seed);
end
// String test name
if ($value$plusargs("TEST=%s", test_name))
$display("Test Suite: %s", test_name);
else
$display("Test Suite: default_suite");
// Number of tests
if ($value$plusargs("NUM_TESTS=%d", num_tests))
$display("Number of Tests: %0d", num_tests);
else begin
num_tests = 100;
$display("Number of Tests: %0d (default)", num_tests);
end
$display("===============================\n");
end
endmodule
Run Examples:
Verilog
vsim top +TIMEOUT=5000 +SEED=CAFE +TEST=smoke_test +NUM_TESTS=50
vsim top +SEED=1234 +NUM_TESTS=200
vsim top (all defaults)
8.4.3 Complete Configurable Testbench Example
Verilog
module configurable_testbench;
// Configuration parameters
integer timeout, num_iterations, verbosity;
reg [31:0] rand_seed;
reg debug_mode, coverage_mode;
// Test variables
integer pass_count, fail_count, i;
initial begin
// Parse command-line arguments
configure_testbench();
// Display configuration
display_configuration();
// Run tests
run_test_suite();
// Report results
report_results();
end
task configure_testbench;
begin
// Timeout configuration
if (!$value$plusargs("TIMEOUT=%d", timeout))
timeout = 10000;
// Number of test iterations
if (!$value$plusargs("ITERATIONS=%d", num_iterations))
num_iterations = 100;
// Random seed
if (!$value$plusargs("SEED=%h", rand_seed))
rand_seed = 32'hDEADBEEF;
// Debug mode
debug_mode = $test$plusargs("DEBUG");
// Coverage mode
coverage_mode = $test$plusargs("COVERAGE");
// Verbosity level
if ($test$plusargs("QUIET"))
verbosity = 0;
else if ($test$plusargs("VERBOSE"))
verbosity = 2;
else
verbosity = 1; // Normal
// Waveform dump
if ($test$plusargs("DUMP_WAVES")) begin
$dumpfile("waves.vcd");
$dumpvars(0, configurable_testbench);
end
end
endtask
task display_configuration;
begin
$display("\n╔══════════════════════════════════════╗");
$display("║ TESTBENCH CONFIGURATION ║");
$display("╠══════════════════════════════════════╣");
$display("║ Timeout : %-20d ║", timeout);
$display("║ Iterations : %-20d ║", num_iterations);
$display("║ Random Seed : 0x%-18h ║", rand_seed);
$display("║ Debug Mode : %-20s ║", debug_mode ? "ON" : "OFF");
$display("║ Coverage : %-20s ║", coverage_mode ? "ON" : "OFF");
$display("║ Verbosity : %-20d ║", verbosity);
$display("╚══════════════════════════════════════╝\n");
end
endtask
task run_test_suite;
integer test_result;
begin
pass_count = 0;
fail_count = 0;
for (i = 0; i < num_iterations; i = i + 1) begin
if (verbosity >= 2)
$display("[%0t] Running test iteration %0d/%0d",
$time, i+1, num_iterations);
// Simulate test (random pass/fail for demo)
test_result = $random(rand_seed) % 100;
if (test_result < 95) begin // 95% pass rate
pass_count = pass_count + 1;
if (verbosity >= 2)
$display(" ✓ PASS");
end else begin
fail_count = fail_count + 1;
if (verbosity >= 1)
$display(" ✗ FAIL at iteration %0d", i);
end
#10; // Test duration
end
end
endtask
task report_results;
begin
$display("\n╔══════════════════════════════════════╗");
$display("║ TEST RESULTS ║");
$display("╠══════════════════════════════════════╣");
$display("║ Total Tests : %-20d ║", num_iterations);
$display("║ Passed : %-20d ║", pass_count);
$display("║ Failed : %-20d ║", fail_count);
$display("║ Pass Rate : %5.2f%% ║",
(pass_count * 100.0) / num_iterations);
$display("╚══════════════════════════════════════╝\n");
if (fail_count == 0)
$display("🎉 ALL TESTS PASSED! 🎉\n");
else
$display("⚠️ SOME TESTS FAILED ⚠️\n");
end
endtask
endmodule
Usage Examples:
1. Quick smoke test:
vsim top +ITERATIONS=10 +QUIET
2. Full regression with debug:
vsim top +ITERATIONS=1000 +SEED=CAFE +DEBUG +VERBOSE +DUMP_WAVES
3. Coverage run:
vsim top +ITERATIONS=500 +COVERAGE +TIMEOUT=50000
4. Default configuration:
vsim top
Comparison Table
