Verilog and SystemVerilog Stochastic Analysis Functions

Stochastic analysis is a useful tool in digital design and verification for modeling random processes and simulating real-world scenarios. In this beginner-friendly tutorial, we'll explore the Verilog and SystemVerilog stochastic analysis functions for managing queues. We'll learn how to create, modify, and gather information about queues using these functions, and discuss the role of status codes in queue management.

Imagine you're designing a system that simulates a coffee shop with multiple customers arriving and leaving. You can use the Verilog and SystemVerilog stochastic analysis functions to manage the queue of customers, simulating their service durations.

Creating New Queues with $q_initialize

To create a new queue, use the $q_initialize function. This function needs four input arguments:

1. A unique identifier (q_id) for the new queue.
2. The queue type (q_type): either First-In-First-Out (FIFO) or Last-In-First-Out (LIFO).
3. The maximum number of entries allowed in the queue (max_length).
4. A status code (status) to indicate the success or failure of the queue creation. This is an output.

Here's an example of creating a new FIFO queue with a maximum length of 5:

module CoffeeShopQueue;
  integer queueId;
  integer queueType = 1; // 1 for FIFO, 2 for LIFO
  integer maxLength = 5;
  integer status;

  initial begin
    $q_initialize(queueId, queueType, maxLength, status);
  end
endmodule

Adding Entries to the Queue with $q_add

To add an entry to the queue, use the $q_add function. This function needs four input arguments:

1. The queue identifier (q_id).
2. The job identifier (job_id), which represents the customer. This value is provided as input.
3. An additional user-defined piece of information (inform_id), such as the customer's item ID. This value is also provided as input.
4. A status code (status), which indicates whether adding the entry was successful or not. This is an output.

Here's an example of adding a customer to the coffee shop queue:

module CoffeeShopQueue;
  // ...
  integer customerNumber = 1;
  integer itemId = 10;

  initial begin
    $q_initialize(queueId, queueType, maxLength, status);
    $q_add(queueId, customerNumber, itemId, status);
  end
endmodule

Removing Entries from the Queue with $q_remove

The $q_remove function allows you to remove an entry from the queue. This function takes four arguments:

1. The queue identifier (q_id).
2. A job identifier (job_id) for the removed customer. This is an output.
3. An additional piece of information (inform_id) associated with the removed customer, such as their item ID. This is also an output.
4. A status code (status) to indicate the success or failure of removing the entry. This is an output.

Here's an example of removing a customer from the coffee shop queue:

module CoffeeShopQueue;
  // ...
  integer removedCustomer;
  integer removedItemId;

  initial begin
    $q_initialize(queueId, queueType, maxLength, status);
    $q_add(queueId, customerNumber, itemId, status);
    $q_remove(queueId, removedCustomer, removedItemId, status);
  end
endmodule

Checking Queue Availability with $q_full

The $q_full function checks if there is space available in the queue for a new entry. It returns 0 if there is space available, and 1 if the queue is full. This function has two arguments:

1. The queue identifier (q_id).
2. A status code (status) to indicate whether the availability check was successful or not. This is an output.

Here's an example of checking the availability of the coffee shop queue:

module CoffeeShopQueue;
  // ...
  integer isFull;

  initial begin
    $q_initialize(queueId, queueType, maxLength, status);
    $q_add(queueId, customerNumber, arrivalTime, status);
    isFull = $q_full(queueId, status);
  end
endmodule

$q_exam: Gathering Queue Statistics

The $q_exam function allows you to obtain statistical information about a specific queue. It takes four arguments:

1. The queue identifier (q_id).
2. An integer specifying the type of statistical information to retrieve (q_stat_code).
3. An output value (q_stat_value) that returns the requested statistical information.
4. A status code (status) indicating the success or failure of the queue examination process. This is an output.

The following table shows the possible values for q_stat_code and their corresponding returned information:

Below is an example of the CoffeeShopQueue module with $q_exam function calls for all the available q_stat_code values:

module CoffeeShopQueue;
  integer queueId;
  integer queueType = 1; // 1 for FIFO, 2 for LIFO
  integer maxLength = 5;
  integer status;

  // Customer information
  integer customerNumber;
  integer itemId;

  // Variables for storing queue exam results
  integer currentQueueLength;
  integer meanInterarrivalTime;
  integer maxQueueLength;
  integer shortestWaitTime;
  integer longestWaitTime;
  integer averageWaitTime;

  initial begin
    $q_initialize(queueId, queueType, maxLength, status);

    // First customer arrives at time 10
    #10;
    customerNumber = 1;
    itemId = 10;
    $q_add(queueId, customerNumber, itemId, status);
    $display("[%0t] Customer %0d arrives with item %0d", $time, customerNumber, itemId);

    // Second customer arrives at time 30
    #20;
    customerNumber = 2;
    itemId = 12;
    $q_add(queueId, customerNumber, itemId, status);
    $display("[%0t] Customer %0d arrives with item %0d", $time, customerNumber, itemId);

    // Third customer arrives at time 50
    #20;
    customerNumber = 3;
    itemId = 22;
    $q_add(queueId, customerNumber, itemId, status);
    $display("[%0t] Customer %0d arrives with item %0d", $time, customerNumber, itemId);

    // First customer is served at time 50
    $q_remove(queueId, customerNumber, itemId, status); // Now the customerNumber and itemId become output
    $display("[%0t] Customer %0d is served with item %0d", $time, customerNumber, itemId);

    // Second customer is served at time 60
    #10;
    $q_remove(queueId, customerNumber, itemId, status);
    $display("[%0t] Customer %0d is served with item %0d", $time, customerNumber, itemId);

    // Gather queue statistics at time 90
    #50;
    $q_exam(queueId, 1, currentQueueLength, status);   // Current queue length
    $q_exam(queueId, 2, meanInterarrivalTime, status); // Mean interarrival time
    $q_exam(queueId, 3, maxQueueLength, status);       // Maximum queue length
    $q_exam(queueId, 4, shortestWaitTime, status);     // Shortest wait time ever
    $q_exam(queueId, 5, longestWaitTime, status);      // Longest wait time for jobs still in the queue
    $q_exam(queueId, 6, averageWaitTime, status);      // Average wait time in the queue

    $display("Current queue length: %0d", currentQueueLength);  
    // 1 (customer 3 has not been served)

    $display("Mean interarrival time: %0d", meanInterarrivalTime); 
    // 16667 (10000 for customer 1 + 20000 for customer 2 + 20000 for customer 3) / 3

    $display("Maximum queue length: %0d", maxQueueLength); 
    // 3 (max 3 customers in history)

    $display("Shortest wait time ever: %0d", shortestWaitTime); 
    // 30000 (customer 2 waited for 30000 ps)

    $display("Longest wait time for jobs still in the queue: %0d", longestWaitTime); 
    // 60000 (customer 3 has not been served yet, and he has been waiting for 60000 ps)

    $display("Average wait time in the queue: %0d", averageWaitTime); 
    // 60000 (customer 3 is the only one in the queue at this time)
  end
endmodule

In this example, the CoffeeShopQueue module simulates a scenario where three customers arrive at a coffee shop and are served using a FIFO queue system. Customer 1 arrives at time 10 ns, customer 2 at time 30 ns, and customer 3 at time 50 ns. Customer 1 is served at time 50 ns, customer 2 at time 60 ns, and customer 3 remains unserved.

At time 90 ns, the $q_exam function is called with all the q_stat_code values to gather the statistical information about the queue. The results show the current queue length, mean interarrival time, maximum queue length, shortest wait time ever, longest wait time for jobs still in the queue, and average wait time in the queue.

Understanding Status Codes in Queue Management Tasks and Functions

All of the queue management tasks and functions return an output status code. The status code values and corresponding information are described in the table below:

By mastering the Verilog and SystemVerilog stochastic analysis functions, you can effectively manage queues and implement complex stochastic queueing models in your digital design and verification projects. These functions provide an easy-to-understand interface for queue creation, manipulation, examination, and statistics gathering, making your work more efficient and precise. Remember to pay close attention to the status codes to ensure your queue management tasks and functions are operating as expected.