pcireadme.txt

LEON3 SOC environment, PCI bridges.

*** PCI TESTBENCH README ***

*** GENERAL OVERVIEW ***

This GRPCI testbench contains modules, testcases and functions for a
complex PCI system. The top file (pci_top) represents the main PCI
bus, where any number of instances can be attached, either LEON
systems or testbench modules.

The actual PCI bus defined in the pci_top is a record (pci_type) of a
complete set of PCI signals. This record contains sub-records,
arranged in a logic sense that simplifies readability in the
code. Example, <pci.syst> is a sub-record containing pci system
signals, while <pci.err> contains error signals. When porting a design
unit to the main bus one can either port the entire bus <pci>, a
sub-record <pci.syst>, as well as explicit signals <pci.syst.clk>.

*** TEST MODULES ***

A number of test modules are included, and can act either as passive
components on the PCI bus, or as active, stimuli generating
modules. Below is a brief description of these modules. The complete
declaration of these modules can be found in
lib/gaisler/ambacomp/ambatest.vhd and lib/gaisler/pci/pci.vhd

pcitb_clkgen : PCI clock generator. Generates either a clock frequency
of 33MHz or 66MHz

pcitb_arb : PCI arbiter. Arbits the PCI bus. It uses a non-hieracal
queue arbiting sequence to minimize the REQ-to-GNT time.

pcitb_monitor : Monitors the traffic on the PCI bus, and generates
simulation interrupt if a failure is found.

pcitb_master : A PCI master that is triggered through test procedures.

pcitb_target : A PCI target that acts as a memory module on the PCI
bus. Can be read through test procedures.

pcitb_stimgen : The stimuli file where the main test process and
procedures are located.

ahbmst_em : An AMBA AHB master that is triggered through test
procedures.

ahbslv_em : An AMBA AHB slave that acts as a memory module on the AMBA
bus. Can be read through test procedures.

*** TEST PROCEDURES ***

Each test module contains a test vector (tbi,tbo), that is controlled
through existing procedures. These procedures are easily implemented
in a sequencial test harness, and feed the test modules with access
parameters and waits until the access completes or fails. These
procedures can easily be modified if a special access is wanted.

These functions are controlled by a record (ctrl), where the detailed
access information is stored. This record contains the following
parameters:

  address (The address of the current access. This can be either AHB
  address or PCI address) data (The access data. For a write access,
  this parameter is feeded before calling the procedure. For a read
  access, this is the return data after the procedure is done.)
  status (This contains information of the result when calling a
  procedure. (OK, ERROR or TIMEOUT)) no_words (This is the number of
  words that is transferred in the access.)  userfile (This is a
  true/false statement whether the access shall be controlled by
  existing file macro) usewfile (This is a true/false statement
  whether the read access result shall be stored in a file.)  rfile
  (This is the input name of the file that contains the control
  macro,(see below)) wfile (This is the input name of the file where
  the output data is stored.)

An example of an access:

    ctrl.address := conv_std_logic_vector(16#80000000#,32);
    ctrl.data := conv_std_logic_vector(16#12345678#,32);
    PCI_write_single(ctrl,tbi(0),tbo(0),dbglevel);


*** USING FILES ***

This testbench contains textio functions that can be used to simplify
the tests. Files can be used both as existing macros for complex
accesses, and as log files, where result data can be stored and, if
wanted, compared with existing data.

A condition where a macro file can be useful is where a specific
sequence of write data shall be transferred. When calling a test
procedure, only a single write data can be directly written to the
target. If a large set of write data shall be transferred, the
procedure must be iterated for each write data. When using a macro
file, all data can be stored in the file, and the procedure must only
be called once. This type of macro file can be used when accessing the
AHB master and PCI master test modules. The master will then continue
the access until all write data in the file is transferred on the bus.

All macro files must be built up in the same way so the master of the
access can interpret it. Thus the macro files for the PCI master and
the AHB master will differ. Below is a description of each valid macro
file type. Each file is line based why the headlines in the examples
below also are required. Note that two types of macro files can be
used with the AHB master module.

AHB MACRO FILE TYPE 1

1              [1=long file, 0=Short file]
--- TRANSFER 1 ---
2              [Transfer type. 0=idle, 1=busy, 2=Non-sequential, 3=Sequential]
1              [Burst type. 0=Single, 1=Incremental burst]
2              [Transfer size. 0=Byte, 1=Half-word, 2=Word, 3=Double-word]
0              [Protection control]
F0000100       [Address (Hex format)]
87654321       [Data (Hex format)]
--- TRANSFER 2 ---
1
1
2
0
F0000104
87654322
--- TRANSFER 3 ---
3
1
2
0
F0000104
87654322


AHB MACRO FILE TYPE 2 (ctrl signals are default values)

0              [1=long file, 0=Short file]
--- TRANSFER 1 ---
60000100       [Address (Hex format)]
12345678       [Data (Hex format)]
--- TRANSFER 2 ---
60000104
87654321
--- TRANSFER 3 ---
60000108
8765678A

PCI MACRO FILE TYPE 1

--- ADDRESS & COMMAND ---
00000000              [Address]
7                     [Command]
--- DATA ---
00000001
00000002
00000003


*** LOG FILES ***

When doing read accesses with much data, a log file can be useful to
check whether the received data matches the expected data. This log
function is is implemented in both the PCI master and PCI target test
modules, as well as in the AHB master and AHB slave test modules, even
though there is s small difference between the log functions. When
using a log file with a PCI/AHB master module, the log data represents
the data received in the actual access. When accessing the PCI target
or AHB slave modules, the log data only represents the memory contents
of the module.

The log files can either be containing decimal or hexadecimal values,
but normally hexadecimal values are used. A file comparing function is
included in the package which takes the contents of two files and
compare them row by row.