|
|
README for the T48 uController project
|
README for the T48 uController project
|
======================================
|
======================================
|
Version: $Date: 2004-09-16 20:45:12 $
|
Version: $Date: 2004-09-16 20:45:12 $
|
|
|
|
|
Introduction
|
Introduction
|
------------
|
------------
|
|
|
The T48 µController core an is implementation of the MCS-48 microcontroller
|
The T48 µController core an is implementation of the MCS-48 microcontroller
|
family architecture. While being a controller core for SoC, it also aims for
|
family architecture. While being a controller core for SoC, it also aims for
|
code-compatability and cycle-accuracy so that it can be used as a drop-in
|
code-compatability and cycle-accuracy so that it can be used as a drop-in
|
replacement for any MCS-48 controller.
|
replacement for any MCS-48 controller.
|
It can be configured to better suit the requirements and characteristics of
|
It can be configured to better suit the requirements and characteristics of
|
the integrating system. On the other hand, nearly the full functionality of a
|
the integrating system. On the other hand, nearly the full functionality of a
|
stock 8048/8049 is available.
|
stock 8048/8049 is available.
|
|
|
|
|
Download
|
Download
|
--------
|
--------
|
|
|
Download the latest stable release from the project homepage at OpenCores.org:
|
Download the latest stable release from the project homepage at OpenCores.org:
|
|
|
http://www.opencores.org/projects.cgi/web/t48/overview/
|
http://www.opencores.org/projects.cgi/web/t48/overview/
|
|
|
You can get the latest version of the design files from CVS:
|
You can get the latest version of the design files from CVS:
|
|
|
http://www.opencores.org/pdownloads.cgi/list/t48
|
http://www.opencores.org/pdownloads.cgi/list/t48
|
|
|
Please keep in mind that this is work in progress and might contain smaller or
|
Please keep in mind that this is work in progress and might contain smaller or
|
bigger problems.
|
bigger problems.
|
You should also check the Tracker for known bugs and see if they affect your
|
You should also check the Tracker for known bugs and see if they affect your
|
work.
|
work.
|
|
|
|
|
Installation
|
Installation
|
------------
|
------------
|
|
|
Once the directory structure is generated either by check-out from CVS or by
|
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
|
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
|
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
|
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
|
variable PROJECT_DIR has to be adjusted to the path where the directory
|
structure is located.
|
structure is located.
|
The commands for setting the necessary variables assume a bash/sh-like
|
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
|
shell. In case you run a different shell like csh or ksh, you should adjust
|
these commands as well.
|
these commands as well.
|
|
|
The meaning of the variables is as follows:
|
The meaning of the variables is as follows:
|
|
|
* PROJECT_DIR
|
* PROJECT_DIR
|
Points to the root of the project installation. All further references are
|
Points to the root of the project installation. All further references are
|
derived from its setting.
|
derived from its setting.
|
|
|
* VERIF_DIR
|
* VERIF_DIR
|
Location of the verification suite.
|
Location of the verification suite.
|
|
|
* SIM_DIR
|
* SIM_DIR
|
Directory for running simulations.
|
Directory for running simulations.
|
|
|
These variables must be properly set whenever scripts or makefiles of the T48
|
These variables must be properly set whenever scripts or makefiles of the T48
|
project are executed. Otherwise, you will most likely encounter error
|
project are executed. Otherwise, you will most likely encounter error
|
messages.
|
messages.
|
|
|
NOTE: The concepts of the mentioned shells require that the init_project.sh is
|
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
|
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
|
instead of executing it like a command. This will make sure that the
|
variable settings are really effective in the calling shell instance.
|
variable settings are really effective in the calling shell instance.
|
|
|
|
|
Directory Structure
|
Directory Structure
|
-------------------
|
-------------------
|
|
|
The project's directory structure follows the proposal of OpenCores.org.
|
The project's directory structure follows the proposal of OpenCores.org.
|
|
|
t48
|
t48
|
|
|
|
|
\--+-- rtl
|
\--+-- rtl
|
| |
|
| |
|
| \-- vhdl : VHDL code containing the RTL description
|
| \-- vhdl : VHDL code containing the RTL description
|
| | of the core.
|
| | of the core.
|
| \-- system : RTL VHDL code of sample systems.
|
| \-- system : RTL VHDL code of sample systems.
|
|
|
|
|
+-- bench
|
+-- bench
|
| |
|
| |
|
| \-- vhdl : VHDL testbench code.
|
| \-- vhdl : VHDL testbench code.
|
|
|
|
|
+-- sim
|
+-- sim
|
| |
|
| |
|
| \-- rtl_sim : Directory for running simulations.
|
| \-- rtl_sim : Directory for running simulations.
|
|
|
|
|
\-- sw : General purpose scripts and files.
|
\-- sw : General purpose scripts and files.
|
|
|
|
|
+-- i8039emu : An MCS-48 emulator written in C.
|
+-- i8039emu : An MCS-48 emulator written in C.
|
|
|
|
|
\-- verif : The verification suite.
|
\-- verif : The verification suite.
|
|
|
|
|
+-- include : Global includes and makefiles.
|
+-- include : Global includes and makefiles.
|
|
|
|
|
+-- black_box : Black-box verification tests.
|
+-- black_box : Black-box verification tests.
|
|
|
|
|
+-- white_box : White-box verification tests.
|
+-- white_box : White-box verification tests.
|
|
|
|
|
\-- gp_sw : General purpose software.
|
\-- gp_sw : General purpose software.
|
|
|
|
|
Compiling the VHDL Code
|
Compiling the VHDL Code
|
-----------------------
|
-----------------------
|
|
|
VHDL compilation and simulation tasks take place inside in sim/rtl_sim
|
VHDL compilation and simulation tasks take place inside in sim/rtl_sim
|
directory. The project setup supports only the batch mode of certain
|
directory. The project setup supports only the batch mode of certain
|
simulators. However, there should be no problems to integrate the testbench
|
simulators. However, there should be no problems to integrate the testbench
|
and RTL code into arbitrary simulation environments.
|
and RTL code into arbitrary simulation environments.
|
|
|
The main file for compilation is Makefile.hier which contains all information
|
The main file for compilation is Makefile.hier which contains all information
|
regarding the dependencies of the source files and their compilation
|
regarding the dependencies of the source files and their compilation
|
order. There is a dedicated file for each supported simulator that maps the
|
order. There is a dedicated file for each supported simulator that maps the
|
generic information of Makefile.hier to object files specific to the given
|
generic information of Makefile.hier to object files specific to the given
|
simulator.
|
simulator.
|
|
|
Compilation is based on the make-utility, thus invocation looks like this:
|
Compilation is based on the make-utility, thus invocation looks like this:
|
|
|
$ make -f Makefile.
|
$ make -f Makefile.
|
|
|
where denotes one of the supported simulators:
|
where denotes one of the supported simulators:
|
|
|
* Makefile.ghdl
|
* Makefile.ghdl
|
Tristan Gingold's GHDL simulator/compiler, a VHDL front-end for gcc.
|
Tristan Gingold's GHDL simulator/compiler, a VHDL front-end for gcc.
|
http://ghdl.free.fr/
|
http://ghdl.free.fr/
|
|
|
* Makefile.simili
|
* Makefile.simili
|
VHDL Simili, a VHDL simulator by Symphony EDA
|
VHDL Simili, a VHDL simulator by Symphony EDA
|
http://www.symphonyeda.com/
|
http://www.symphonyeda.com/
|
|
|
Make will analyze all VHDL files (RTL and testbench code) and elaborate all
|
Make will analyze all VHDL files (RTL and testbench code) and elaborate all
|
three testbench top-levels if appropriate for the chosen simulator:
|
three testbench top-levels if appropriate for the chosen simulator:
|
|
|
* tb_behav_c0
|
* tb_behav_c0
|
The main testbench for regression testing.
|
The main testbench for regression testing.
|
Instantiates the plain t48_core and provides internal RAM (256 bytes) and
|
Instantiates the plain t48_core and provides internal RAM (256 bytes) and
|
ROM (2k bytes) plus 2k bytes of external ROM.
|
ROM (2k bytes) plus 2k bytes of external ROM.
|
|
|
* tb_t8048_behav_c0
|
* tb_t8048_behav_c0
|
The testbench for the t8048 sample system.
|
The testbench for the t8048 sample system.
|
|
|
* tb_t8039_behav_c0
|
* tb_t8039_behav_c0
|
The testbench for the 8039 sample system.
|
The testbench for the 8039 sample system.
|
|
|
Each Makefile has a 'clean' target to delete all intermediate data:
|
Each Makefile has a 'clean' target to delete all intermediate data:
|
|
|
$ make -f Makefile. clean
|
$ make -f Makefile. clean
|
|
|
The basic simple sequence list can be found in COMPILE_LIST. This can be
|
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
|
useful to quickly set up the analyze stage of any compiler or
|
synthesizer. Especially when synthesizing the code, you want to skip the VHDL
|
synthesizer. Especially when synthesizing the code, you want to skip the VHDL
|
configurations in *-c.vhd and everything below the bench/ directory.
|
configurations in *-c.vhd and everything below the bench/ directory.
|
|
|
Preparation of the ROM Files
|
Preparation of the ROM Files
|
----------------------------
|
----------------------------
|
|
|
All testbenches listed above need two files in hex-format. They contain the
|
All testbenches listed above need two files in hex-format. They contain the
|
program for the T48 core and are loaded into internal and external ROM at
|
program for the T48 core and are loaded into internal and external ROM at
|
simulation startup. Their existance is mandatory as they are referenced in the
|
simulation startup. Their existance is mandatory as they are referenced in the
|
VHDL code of the ROM model lpm_rom.vhd. In case they are missing, the
|
VHDL code of the ROM model lpm_rom.vhd. In case they are missing, the
|
simulation will stop immediately after elaborating the design.
|
simulation will stop immediately after elaborating the design.
|
|
|
These files are:
|
These files are:
|
|
|
* t48_rom.hex
|
* t48_rom.hex
|
Internal ROM contents at address range 000H to 7FFH.
|
Internal ROM contents at address range 000H to 7FFH.
|
Intel hex format, starting at address 000H.
|
Intel hex format, starting at address 000H.
|
|
|
* t48_ext_rom.hex
|
* t48_ext_rom.hex
|
External ROM contents at address range 800H to FFFH.
|
External ROM contents at address range 800H to FFFH.
|
Intel hex format, starting at address 000H.
|
Intel hex format, starting at address 000H.
|
|
|
The verification flow for the T48 project generates these two files
|
The verification flow for the T48 project generates these two files
|
automatically from the assembler source files.
|
automatically from the assembler source files.
|
|
|
All regression tests and the general purpose software is organized in a cell
|
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
|
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,
|
a dedicated directory where the assembler run takes place. In the future,
|
there will be more aspects to a cell.
|
there will be more aspects to a cell.
|
|
|
Assembling, linking and putting the hex-files in place is under the control of
|
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
|
the make-mechanism. E.g. to assemble the source code of a cell, issue the
|
following command:
|
following command:
|
|
|
$ make -f $VERIF_DIR/include/Makefile.cell
|
$ make -f $VERIF_DIR/include/Makefile.cell
|
|
|
This generates the linker file (test.p) and distributes its contents to the
|
This generates the linker file (test.p) and distributes its contents to the
|
required ROM files for internal and external program ROM. The target 'simu'
|
required ROM files for internal and external program ROM. The target 'simu'
|
copies these files automatically to the simulation directory. So most likely,
|
copies these files automatically to the simulation directory. So most likely,
|
for running a test case or any other software, you will want to issue:
|
for running a test case or any other software, you will want to issue:
|
|
|
$ make -f VERIF_DIR/include/Makefile.cell simu clean
|
$ make -f VERIF_DIR/include/Makefile.cell simu clean
|
|
|
The only supported assembler is Alfred Arnold's macroassembler AS. See
|
The only supported assembler is Alfred Arnold's macroassembler AS. See
|
|
|
http://john.ccac.rwth-aachen.de:8000/as/
|
http://john.ccac.rwth-aachen.de:8000/as/
|
|
|
|
|
Verification Environment
|
Verification Environment
|
------------------------
|
------------------------
|
|
|
The verification environment consists of a number of test programs. They are
|
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
|
all self-checking. I.e. after testing the targeted functionality, they emit a
|
pass/fail information. This information is detected by the testbench which
|
pass/fail information. This information is detected by the testbench which
|
stops the simulation and prints out the simulation result. This is the default
|
stops the simulation and prints out the simulation result. This is the default
|
mechanism for stopping the VHDL simulation.
|
mechanism for stopping the VHDL simulation.
|
|
|
Pass/fail is signalled by a certain sequence of the accumulator contents:
|
Pass/fail is signalled by a certain sequence of the accumulator contents:
|
|
|
1) Accumulator contains AAH
|
1) Accumulator contains AAH
|
2) Accumulator contains 55H
|
2) Accumulator contains 55H
|
3) Accumulator contains 01H -> Pass
|
3) Accumulator contains 01H -> Pass
|
Accumulator contains 00H -> Fail
|
Accumulator contains 00H -> Fail
|
|
|
The detection is modelled like a state machine and in case the sequence is of
|
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
|
bytes inside the accumulator does not match, the detection process restarts
|
from the beginning. This mechanism is part of all verification tests.
|
from the beginning. This mechanism is part of all verification tests.
|
|
|
The complete regression suite can be executed with the run_regression.pl
|
The complete regression suite can be executed with the run_regression.pl
|
script. For each test cell, it steps through the sequence
|
script. For each test cell, it steps through the sequence
|
|
|
1) Assemble the source code
|
1) Assemble the source code
|
2) Run the compiled VHDL design (currently only GHDL)
|
2) Run the compiled VHDL design (currently only GHDL)
|
3) Optionally perform a dump compare against the C-model
|
3) Optionally perform a dump compare against the C-model
|
|
|
It is highly recommended to redirect the output of run_regression.pl into a
|
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
|
file. Otherwise, analyzing the messages related to each test cell is almost
|
impossible.
|
impossible.
|
|
|
