pcisim.txt

此代码用于生成测试PCI设备的Verilog代码（Verilog代码为一种硬件描述语言）。此代码可以直接运行于LINUX下。

/*
 * Copyright 2002 Picture Elements
 *    Stephen Williams <[e-mail]>
 *
 *    This source code is free software; you can redistribute it
 *    and/or modify it in source code form under the terms of the GNU
 *    General Public License as published by the Free Software
 *    Foundation; either version 2 of the License, or (at your option)
 *    any later version.
 *
 *    This program is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *    GNU General Public License for more details.
 *
 *    You should have received a copy of the GNU General Public License
 *    along with this program; if not, write to the Free Software
 *    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
 */


PCISIM OVERVIEW

The pcisim test bench is a collection of C and Verilog code that
together form a test bench library for PCI devices. It allows Verilog
programmers to write test benches for their PCI device models, and it
allows C programmers who are destined to write drivers to write C code
that communicates with the device much like a driver would.

The basic principle of pcisim is that the Verilog program can be built
up to simulate a complete PCI backplane, with stub devices
(i.e. memory, CPU, arbiter, etc.) that together provide a complete
operating environment for a PCI device under test. The built up
program is compiled to a single executable that can be run to simulate
the system.

The actions that occur on a backplane that are normally supplied by a
cpu running an operating system, are replaced with a stub device that
instead communicates with another process. This other process is a
program written in C that communicates with the model in much the same
way that a real CPU communicates with the host bridge of a PCI
device. This program is compiled separately and uses the libpcisim
library to communicate with the simulation.

* The Verilog Half

The Verilog simulation includes a device under test (DUT) that models
a PCI device. This subject device is the responsibility of the
programmer. The Verilog program usually includes a top level module
that models the PCI backplane, and connects all the standard PCI
devices together. The top level module is also the responsibility of
the programmer, although there is some help.

The components of a computer system that are not the device under test
or the backplane can be drawn from a module library included with
pcisim. These include memory devices, an arbiter, and the host
bridge. The arbiter is special (it only connects to REQ#, GNT# and
some of the control signals) but all the other models in the library
are PCI devices that can be hooked together by the backplane module.

* The C Half

The C programmer has been handed a compiled system model (written in
Verilog) and wishes to write code for it. The C programmer writes a
program that peeks and pokes the PCI bus of the model using the
library described in the pcisim.h header file. This interface should
be sufficient for C programmers trying to write end-to-end tests, and
also who want to start writing driver code for the target device.


WRITING THE VERILOG SIMULATION

The simulation program contains the device under test and all the
other components that make up a PCI system. The Verilog programmer
gets from pcisim the library modules in <pcisim>/ver. These modules
model most of the standard components of a PCI system. The Verilog
programmer writes a top level module that glues these components
together to form a system. The following is a complete example:

  module main;

     // Signals of the PCI BUS
     wire reset;
     tri1 frame, irdy, trdy, stop, devsel, par;
     wire [31:0] ad;
     wire [3:0]  c_be;
     wire [3:0]  req, gnt;

     reg clk = 1;
     always #16 clk = !clk;

     // This is the system arbiter.
     pci_arbiter arb(clk, reset, frame, irdy, req, gnt);

     // This is the device that talks to the host operating system.
     pci_master cpu(.CLK(clk), .RESET(reset),
		    .FRAME(frame), .IRDY(irdy), .TRDY(trdy),
		    .STOP(stop), .DEVSEL(devsel),
		    .AD(ad), .C_BE(c_be), .PAR(par),
		    .REQ(req[0]), .GNT(gnt[0]));

     // Need a memory device to act as a target.
     pci_memory #(.BAR0_MASK(32'hff000000)) mem1 (
		  .CLK(clk), .RESET(reset),
		  .FRAME(frame), .IRDY(irdy), .TRDY(trdy),
		  .STOP(stop), .DEVSEL(devsel), .IDSEL(ad[16]),
		  .AD(ad), .C_BE(c_be), .PAR(par));

  endmodule

This example doesn't include any devices other then the standard
memory and cpu, but this is enough to run a program. Compile this
program with the command:

  % iverilog -y<pcisim>/ver main.v

This produces the file "a.out", which can be run like so:

  % vvp -M<pcisim>/vpi -mpci a.out

This creates a pair of named pipes in the current directory, and waits
for the client application to start.


WRITING THE C TESTBENCH

The simulation does not do anything in isolation. The programmer must
write a test bench that invokes the simulation. The libpcisim library
function (and the <pcisim.h> header file) exist to help. The provide a
conventional API that the C programmer can use to peek and poke the
PCI bus.


LIBRARY MODULE REFERENCE

The pcisim module library includes modules needed to assemble complete
PCI based systems. These include models for CPU, memory and
backplane. The modules themselves are written in Verilog, so the best
place to look for the ports are in the source files. This
documentation summarizes how the device can be configured.

* pci_arbiter

	parameter width = <number>

The pci_arbiter module performs arbitration on a PCI backplane. The
arbiter has a configurable width, that sets the number of devices that
it can arbitrate.

* pci_master

This module represents a PCi master device written in C using the
libpcisim library. This module is the Verilog presence for that
device. There is no configuration for this device, it behaves as the C
programmer programs it.

* pci_memory

	parameter DEVICE_ID  = 32'h0000_12c5;
	parameter BAR0_MASK  = 32'hffff0000;
	parameter BAR0_FLAGS = 'h8;
	parameter IMAGE      = "memory.bin"
	parameter RETRY_RATE = 0;

This module represents a read/write memory device. It is target only,
and supports bursts and configuration commands. It's presence on the
PCI bus may be configured by parameters, as can its initial contents.

The memory device gets (and stores) its contents in a disk file. The
user may prefill that disk file with an initial image, and after the
simulation is complete, the disk file will contain the final contents
of the memory device.

    - DEVICE_ID
      This parameter is a 32bit number that specifies the contents of
      the 32bit device id configuration register.

    - BAR0_MASK
      This parameter sets the size of the device by masking the
      significant address bits. The default value 32'hffff0000, for
      example, defines the memory to be 64K bytes. You can set this to
      make the memory as large or small as desired.

    - BAR0_FLAGS
      These define the read-only flag bits of the bar. The default
      defines the device as a memory device that is prefetchable.

    - IMAGE
      The value of this parameter is the name of a disk file to ack as
      the memory image. This file must be read/writeable, as the
      simulation will read it to get the initial contents of the
      memory, and write it as the memory is changed.

    - RETRY_RATE

      Normally, read-memory commands will succeed. If this parmater is
      set to a non-0 value, then that is the inverse probability that
      any particular command will generate a RETRY instead of
      proceeding. For example, if the value is set to 9, then
      approximately 1 in 9 read commands will be retried.

      Retries occur randomly.

    - DISCON_RATE

      Normally, burst read/write to memory will be terminated by the
      master. If there is a non-zero DISCON_RATE, then the memory
      device will randomly issue disconnects. The +mem-discon-rate-X
      plusarg can override the DISCON_RATE.

$Log: pcisim.txt,v $
Revision 1.4  2004/01/20 18:21:31  steve
 Make memory device do random disconnects.

Revision 1.3  2002/10/16 16:59:55  steve
 License updates.

Revision 1.2  2002/08/10 18:00:31  steve
 Document the library modules.