PCIShell - A PCI simulation shell

Introduction

PCIShell is a command line based shell for simulating PCI based traffic. By using PCIShell, it is possible to measure bus performance as a function of the PCI bus master and target parameters.
The master and targets models incorporated in PCIShell are very generic and many of their parameters can be controlled.
PCIShell can generate cycle dumps, REQ/GNT dumps, statistical dumps, or transaction dumps.

PCISHell commands

The following commands are supported by PCIShell:

help
This command dumps a list of all the PCIShell commands.
exit
This command is used to exit PCIShell.
list
This command dumps a list of all the PCI masters and PCI targets currently defined.
new master|target <name>
This command creates a new master or target device.
delete <name>
This command creates deletes an existing master or target device.
This command is currently not implemented.
reset
This command resets all the devices currently instantiated.
run <num>
This command runs the simulation for <num> cycles.
set <object> <option> <value>
This command sets <option> to <value> for <object>.
status <object>
This command dumps all the current values for all the options supported by <object>.
mon 0|1
This command turns on or off cycle dumps.
req 0|1
This command turns on or off REQ# signal dump for all masters.
gnt 0|1
This command turns on or off GNT# signal dump for all masters.

Command entry

In addition to the commands above, PCIShell supports the following constructs:

Comments

Comments begin with the # symbol, and may appear on an empty line, or at the end of an existing line. For example:

# This is a full line comment
help # dump a list of all commands

Subroutines

It is possible to run other scripts from the hard disk from within the current script, by preceding the filename with @. It is also possible to optionally specify arguments, following the filename. For example:

@clearall.cmd # This should clear everything
@setrange.cmd tb.x 0 100 # set address range for tb.x to 0 through 100

Arguments are referenced withing subroutines using the %0, %1, ... notation.

External commands

External commands can be run by prefixing them with the ! symbol. For example:

! dir # display current directory
!notepad x.cmd # edit file x.cmd

The white space between the ! symbol and the command is optional.

Initial script

When PCISHell starts, is automatically tries to open a file named pcisim.cmd, and if found, is is run as a script. When it is done, the program continues accepting commands from the standard input. If the file is not found, no error is reported.

Opbject options

General options

`minmax_rw`

minmax_rw is a set of 4 options, specifying a numerical value made of 2 min/max pairs, one for read, one for write. The 4 options are usually called:

xxx_min_read
xxx_max_read
xxx_min_write
xxx_max_write

Where xxx is the name of the specific options.

`debug`

This parameter is common to all the objects, and may take a value of 0 or 1. Selecting a value of 1 may cause more debugging messages to be displayed during simulation, if the object actually supports this flag.

Common Master and Target options

The following options are supported by both the PCI master model and the PCI target model:

`burst_length`

This minmax_rw option controls the random burst length for the target or master device. Values are measured in PCI clock cycles. Each device's burst length is generated randomly for each PCI transaction accodring to these parameters, and the transaction type (read or write).
The actual settings are:

burst_length_min_read
burst_length_max_read
burst_length_min_write
burst_length_max_write

`initial_wait_state`

This minmax_rw option controls the length of the device latency for the first word transferred in a burst. Values are measured in PCI clock cycles. Each device's initial_wait_state is generated by a random function for each PCI transaction accodring to these parameters, and the transaction type (read or write).
The actual settings are:

initial_wait_state_min_read
initial_wait_state_max_read
initial_wait_state_min_write
initial_wait_state_max_write

`burst_wait_state`

This minmax_rw option controls the length of the device latency for the all the words transferred in a burst, except the first one. Values are measured in PCI clock cycles. Each device's burst_wait_state is generated by a random function for each PCI transaction accodring to these parameters, and the transaction type (read or write).
The actual settings are:

burst_wait_state_min_read
burst_wait_state_max_read
burst_wait_state_min_write
burst_wait_state_max_write

PCI Master options

The following options are supported by the PCI master model:

`transaction_count`

This parameter controls how many full burst will be performed by the master until it stops. a full burst may be broken into smaller bursts by either the master's or the target's burst_length parameters, but these smaller bursts counts only as one full burst.

`read_probability`

This parameter controls the probabilities for generating a memory read or write write command on the PCI bus by the master. The value is measured in percentage, and is in the range of 0 to 100. The actual decision on a PCI memory read or PCI memory write command is done by a random function using the odds defined above.

`master_base_address`

This parameter controls the lowest address for which the PCI master may generate a memory request. The actual address is generated randomly for every PCI transaction.

`master_address_length`

This parameter controls the length of the memory block for which PCI memory read or PCI memory write requests are generated. The actual address is generated randomly for every PCI transaction.

Summary and conclusions

It is possible to use PCIShell to run simulations of typical PCI traffic. In case of a unique PCI device timing characteristics, it is possible to modify the existing PCI devices to incorporate the special requirements very easily.