Subversion Repositories t400

README for the T400 uController project

=======================================

Version: $Id: README 179 2009-04-01 19:48:38Z arniml $

Introduction

------------

The T400 µController is an implementation of National's 4-bit COP400

microcontroller family architecture. It is intended to be used as a

replacement for the original chip in SOCs recreating legacy systems.

Its final target is to provide design variants that are compatible with the

COP420/421 and COP410L/411L family members. All of them derived from the

common t400_core design.

Download

--------

Download the latest stable release from the project homepage at OpenCores.org:

  http://www.opencores.org/projects.cgi/web/t400/overview/

You can get the latest version of the design files from CVS:

  http://www.opencores.org/pdownloads.cgi/list/t400

Please keep in mind that this is work in progress and might contain smaller or

bigger problems.

You should also check the Tracker for known bugs and see if they affect your

work.

Installation

------------

Once the directory structure is generated either by check-out from CVS or by

unpacking the tar-archive, the central project initialization file should be

set up. A template called init_project.template.sh is located in the sw

directory where a copy can be edited. Normally, only the definition for the

variable PROJECT_DIR has to be adjusted to the path where the directory

structure is located.

The commands for setting the necessary variables assume a bash/sh-like

shell. In case you run a different shell like csh or ksh, you should adjust

these commands as well.

The meaning of the variables is as follows:

  * PROJECT_DIR

    Points to the root of the project installation. All further references are

    derived from its setting.

  * MAKEFILES

    Identifies the global Makefile for compilation of tests.

These variables must be properly set whenever scripts or makefiles of the T400

project are executed that are related to verification tasks. Otherwise, you

will most likely encounter error messages.

NOTE: The concepts of the mentioned shells require that the init_project.sh is

      run in the context of the shell. I.e. you should 'source' the script

      instead of executing it like a command. This will make sure that the

      variable settings are really effective in the calling shell instance.

Directory Structure

-------------------

The project's directory structure follows the proposal of OpenCores.org.

t400

 |

 \--+-- rtl

    |    |

    |    +-- vhdl           : VHDL code containing the RTL description

    |    |    |               of the core.

    |    |    \-- system    : RTL VHDL code of sample systems.

    |    |

    |    \-- tech           : Technology specific files.

    |         |

    |         +-- cyclone   : Cyclone technology flavor.

    |         |

    |         +-- spartan   : Spartan technology flavor.

    |         |

    |         \-- generic   : Generic RTL designs.

    |

    +-- bench

    |    |

    |    \-- vhdl           : VHDL testbench code.

    |

    +-- sim

    |    |

    |    \-- rtl_sim        : Directory for running simulations.

    |

    +-- syn

    |    |

    |    \-- t421           : T421 toplevel example synthesis.

    |         |

    |         +-- ep1c12    : for Altera Cyclone.

    |         |

    |         \-- xc3s1000  : for Xilinx Spartan3.

    |

    \-- sw                  : General purpose scripts and files.

         |

         \-- verif          : The verification suite.

              |

              +-- include   : Global includes and makefiles.

              |

              +-- black_box : Black-box verification tests.

              |

              +-- int       : Interrupt verification tests.

              |

              \-- system    : General system level tests.

Compiling the VHDL Code

-----------------------

VHDL compilation and simulation tasks take place inside in sim/rtl_sim

directory. The project setup supports only the batch mode of certain

simulators. However, there should be no problems to integrate the testbench

and RTL code into arbitrary simulation environments.

The main file for compilation is Makefile which contains all information

regarding the dependencies of the source files and their compilation

order.

Compilation is based on the make-utility, thus invocation looks like this:

  $ make

This will call ghdl to analzye and elaborate the complete design hierarchy.

    Tristan Gingold's GHDL simulator/compiler, a VHDL front-end for gcc.

    http://ghdl.free.fr/

Make will analyze all VHDL files (RTL and testbench code) and elaborate all

testbench top-levels:

  * tb_t410_behav_c0

    Testbench for the T410 derivative.

    It instantiates the T410 system toplevel and is intended to exectue all

    verifcation tests tagged with 't41x'.

  * tb_t411_behav_c0

    Testbench for the T411 derivative.

    It instantiates the T411 system toplevel and is intended to exectue all

    verifcation tests tagged with 't41x'.

  * tb_t420_behav_c0

    The testbench for the T420 derivative.

    It instantiates the T420 system toplevel and is intended to execute all

    verification tests tagged with 't42x' and 't420'.

  * tb_t421_behav_c0

    The testbench for the T421 derivative.

    It instantiates the T421 system toplevel and is intended to execute all

    verification tests tagged with 't42x'.

  * tb_int_behav_c0

    The testbench for the interrupt verification suite.

    It instantiates the T420 system topevel and is intended to execute all

    verification tests tagged with 'int'.

  * tb_microbus_behav_c0

    The testbench for the microbus verification.

    It instantiates the T420 system toplevel in microbus configuration and is

    intended to execute all verifications tests tagged with 'mb'.

  * tb_prod_behav_c0

    The testbench for the production test.

    It instantiates the T420 system toplevel an checks D and P output ports

    for the patterns generated by the software as proposed in

      "Testing of COP400 Familiy Devices"

      National Semiconductor

      COP Note 7

      April 1991

The Makefile has a 'clean' target to delete all intermediate data:

  $ make clean

The basic simple sequence list can be found in COMPILE_LIST. This can be

useful to quickly set up the analyze stage of any compiler or

synthesizer. Especially when synthesizing the code, you want to skip the VHDL

configurations in *-c.vhd and everything below the bench/ directory.

Preparation of the ROM Files

----------------------------

All testbenches listed above load the internal ROM of the controller from a

file in hex-format. Its existance is mandatory since it is referenced in the

VHDL code of the ROM model lpm_rom.vhd. In case it is missing, the

simulation will stop immediately after elaborating the design.

These files are:

  * rom_41x.hex

    Program ROM compiled for the T41x derivatives. Maximum size 512 bytes.

    Referenced by the t410_notri system.

    Enabled by the 't41x' tag.

  * rom_42x.hex

    Program ROM compiled for the T42x derivatives. Maximum size 1024 bytes.

    Referenced by the t420_notri system.

    Enabled by the 't42x', 't420', 'int', 'mb' and 'prod' tag.

The verification flow for the T400 project generates these two files

automatically from the assembler source files. Whenever the make process

locates one or more of the above tags, it assembles and links the source code

for the repsective derivative.

All regression tests and the general purpose software is organized in a cell

structure. Currently, this means that the software for a cell is contained in

a dedicated directory where the assembler run takes place. In the future,

there will be more aspects to a cell.

Assembling, linking and putting the hex-files in place is under the control of

the make-mechanism. E.g. to assemble the source code of a cell, issue the

following command:

  $ make

The above mention environment variable MAKEFILES enables execution of the make

process from within any subdirectory in the verification tree. This generates

the linker file (test_41x.p and test_42x.p) and derives hex-files which are

placed into the simulation directory. So most likely, for running a test case

or any other software, you will want to issue:

The only supported assembler is Alfred Arnold's macroassembler AS. See

  http://john.ccac.rwth-aachen.de:8000/as/

Verification Environment

------------------------

The verification environment consists of a number of test programs. They are

all self-checking. I.e. after testing the targeted functionality, they emit a

pass/fail information. This information is detected by the testbench which

stops the simulation and prints out the simulation result. This is the default

mechanism for stopping the VHDL simulation.

Pass/fail is signalled by a certain sequence of the L port contents:

(R denotes an optional value stored in A when calling the pass or fail

routines)

  1) L outputs 0x0R

  2) L outputs 0xaR

  3) L outputs 0x5R

  4) L outputs 0x0R -> Pass

     L outputs 0xfR -> Fail

The detection is modelled like a state machine and in case the sequence is of

bytes inside the accumulator does not match, the detection process restarts

from the beginning. This mechanism is part of all verification tests except

for the interrupt testbench.

The complete regression suite can be executed with the run_regression.pl

script. For each test cell, it steps through the sequence

  1) Assemble the source code

  2) Run the compiled VHDL design (currently only GHDL)

It is highly recommended to redirect the output of run_regression.pl into a

file. Otherwise, analyzing the messages related to each test cell is almost

impossible.

Clocking System

---------------

The main clock is supplied at input ck_i. To ease system integration, ck_i can

accept integer multiples of the target clock frequency. Input ck_en_i is used

to qualify rising edges on ck_i as active clock edges. When ck_i is supplied

with the target frequency, ck_en_i can be kept high constantly.

Generic Parameters

------------------

Most generic parameters are provided to set the numerous I/O options. Thus

such options are exhibited on the toplevel designs.

All generics are implemented with integer types to enable analysis of the RTL

code without tool restrictions. The related constants are defined in

t400_opt_pack-p.vhd.

  opt_type_g           : Derivative type - T420, T421, T410, T411

  opt_ck_div_g         : Internal divider on CK

  opt_cko_g            : Enable CKO as general purpose input

  opt_l_out_type_7_g   : Output driver type L[7]

  opt_l_out_type_6_g   : Output driver type L[6]

  opt_l_out_type_5_g   : Output driver type L[5]

  opt_l_out_type_4_g   : Output driver type L[4]

  opt_l_out_type_3_g   : Output driver type L[3]

  opt_l_out_type_2_g   : Output driver type L[2]

  opt_l_out_type_1_g   : Output driver type L[1]

  opt_l_out_type_0_g   : Output driver type L[0]

  opt_microbus_g       : Enable MICROBUS interface

  opt_d_out_type_3_g   : Output driver type D[3]

  opt_d_out_type_2_g   : Output driver type D[2]

  opt_d_out_type_1_g   : Output driver type D[1]

  opt_d_out_type_0_g   : Output driver type D[0]

  opt_g_out_type_3_g   : Output driver type G[3]

  opt_g_out_type_2_g   : Output driver type G[2]

  opt_g_out_type_1_g   : Output driver type G[1]

  opt_g_out_type_0_g   : Output driver type G[0]

  opt_so_output_type_g : Output driver type SO

  opt_sk_output_type_g : Output driver type SK

FPGA Implementation

-------------------

All of the design files contain pure RTL code. This is true even for the

technology specific power-on reset module. Two flavors exist, each of them

implementing the desired behavior in a way that is understood by the design

tools. The RAM for the data memory is described by generic RTL code as

well. It should be translated automatically by the tool chain to a technology

specific RAM macro.

There is a generic method for the program memory ROM as well, although this

project uses a flow where hex-files are loaded by lpm_rom.vhd as the default

method. Convert the ROM image to an RTL VHDL file with one of the two

following commands (either from hex or bin format):

  $ hex2rom -b [rom image file] rom_t41x 9l8s > rom_t41x.vhd

  $ hex2rom -b [rom image file] rom_t42x 10l8s > rom_t42x.vhd

The option -b specifies that  contains binary data. Skip this

option to process a file in hex format.

These resulting RTL representations are instantiated by t410_rom-struct-a.vhd

and t420_rom-struct-a.vhd. Altera and Xilinx design tools will detect and

extract the ROM and turn it into a memory macro.