LEON Enhancement Tutorial

The LEON P1754 processor is a synthesisable VHDL model of a 32-bit processor with an instruction set according to the IEEE-1754 standard. The IEEE1754 standard is compatible with the SPARC V8 instruction set. The full source code of this processor is freely available under the GNU LGPL license.

This Tutorial explains in brief the process of adding a custom AMBA-compliant slave module into the LEON VHDL core. It requires about 16MB of diskspace.

1. Login to behemoth.ece.ncsu.edu. Any other UNIX machine would do, as long as the /opt/rtems directory exists on that machine. This directory will be where the LECCS toolset should have been installed.
2. Create a new directory, eg. "leon_tut". "cd" to this directory. Download the 1.1.10 version of the LEON Processor from http://www.gaisler.com/bin/leon2-1.0.10.tar.gz. Extract the files:
   
   
   • gunzip leon2-1.0.10.tar.gz
   • tar xvf leon2-1.0.10.tar
   • rm leon2-1.0.10.tar (to save space)
   • cd leon2-1.0.10
3. The LEON Users Manual can be accessed at the following location: (Windows, Unix)
   Section 1.4 (Pg.8) shows the Block Diagram of LEON. Keep this diagram handy when performing the Tutorial.
   The goal of this tutorial is to create an AMBA-compliant slave and connect it to the AMBA APB bus in the diagram. All connections of our new block would be made similar to that of the Timers module as seen in the diagram. Thus, during the different steps, it would be worthwhile to compare all the code that would be written to the corresponding code for the Timers module.
4. Section 10 (Pg.65) of the Users Manual shows the VHDL Model Structure. In summary, the leon directory contains the LEON VHDL Code, tbench directory contains the testbench components, and tsource contains the C/Assembly code to be run on the LEON Processor.
5. The VHDL Code that we have consists of a lot of configurable and optional parts. The first step would be to configure them according to our needs. Refer to Section 2.2 (Pg.11) of the Users Manual. Execute "make xconfig". This will open up the TK GUI Window for selection of different configuration options.
6. Click on Optional Modules and select the "Y" option for the Watchdog. We would not be using the Watchdog Timer as such, but this is to just give a feel of how the VHDL model can be configured. Explore the other Windows/Options, but leave the settings at their default values. Click on "Save and exit" at the main menu.
7. As indicated during the closing of the GUI, execute "make dep" to create the leon/device.vhd file which would have all your configuration options saved.
8. Lets run the default test that is provided with the LEON Model, without changing any portion of it. Refer to Section 2.3 (Pg.11) of the Users Manual. This test runs some basic tests on the Model. It detects the optional modules that are absent and does not run those tests. Execute:
   
   
   • add modelsim
   • setenv MODELSIM modelsim.ini
   • make all
   This will create the proper work directory and compile the Model and Testbench VHDL code.
9. Execute "vsim tb_func32" at the UNIX Prompt and "run -a" at the VSIM Prompt. The test will successfully end with the following message: "Test completed OK, halting with failure. Failure: TEST COMPLETED OK, ending with FAILURE". This actually means that the test passed correctly! Due to some issues with VHDL Simulation, this was the method chosen to end the test. Exit Modelsim.
10. The AMBA Users Manual can be accessed at the following location: (Windows, Unix)
    Section 5.2 (Pgs.170-172) shows the basic Read, Write Transfer Cycles for an AMBA-APB bus. We will have to use this protocol to communicate with the new slave.
11. Let us look at the new slave module to be inserted into the LEON. To simplify things, let us consider that this slave module consists of just 2 registers, which have to be accessed by the LEON Processor. Download this tworeg_slave.vhd file into the leon directory. Refer to the comments in this file to understand its function. We do not have any non-AMBA signals for this module; possible noteworthy additions could be an interrupt signal and connections to the Debug Module in the chip.
12. Now to insert these 2 32-bit registers into the Memory Map of LEON (Sec 6.1, Pg.27 of LEON Users Manual). Looking at the constant apbslvcfg_tkconfig defined in leon/device.vhd, we can decide to allocate address range 0x300-0x3FC to our Register File. From the Processors point of view, this would be addresses 0x80000300-0x800003CC. Download this changed device.vhd file into the leon directory. Remember that our Register File now has an index of 14 into the list of APB slaves. The changes in this and the rest of the changed files are clearly marked using comments.
13. Let us connect this Register File into the actual Processor core (leon/mcore.vhd) file. Remember we will be imitating most of the connections of the Timer module. Download this changed mcore.vhd file into the leon directory.
14. We instantiated the Register File, but are yet to declare it as a component for VHDL syntax. Lets do that in the leon/ambacomp.vhd file. Download this changed ambacomp.vhd file into the leon directory.
15. All the changes to the VHDL Code are now ready. Its time to change the Makefiles for the VHDL compilation. The Makefile in the top leon2-1.0.10 directory actually leaves the compilation task to the 2 Makefiles, once each in the leon and tbench directories. We will have to add the name of our new source file into the first Makefile. Download this changed Makefile file into the leon directory.
16. Make sure current directory is leon2-1.0.10 and execute "make all". This should compile the new changed LEON VHDL Code.
17. Its now time to change the C/Assembly code that will run on this modified processor. Where does this current software exist? It is present in the tsource directory. The C and Assembly files in this directory are compiled using the GCC SPARC Cross-Compiler. (This Compiler will be present in the /opt/rtems directory. If this directory does not exist, login to behemoth.ece.ncsu.edu to complete the tutorial). The sparc-rtems-gcc command is used to compile the C/Assembly files and make an executable. The sparc-rtems-objcopy and sparc-rtems-objdump commands then separate out different sections from the executable and dump them into the ram.dat and rom.dat files. These .dat files will be read by the VHDL testbench and the instructions will be fetched and executed by the LEON Processor.
18. The default testcase for our previous run was the leon_test.c program. To simplify matters, and not bother with changing the Makefile, lets make the changes required to this file itself. Download this changed leon_test.c file into the tsource directory. The testcase now comments out all the previous tests that were run, and instead just performs a single write and read from each of the 2 Registers in the Register File. This test just illustrates how to access these new registers.
    To compile this program, and create the .dat files, execute:
    
    
    • cd tsource
    • setenv PATH /opt/rtems/bin:${PATH}
    • make
    • cd ..
19. Copy this signals.do TCL file into the leon2-1.0.10 directory. As before, execute "vsim tb_func32" to invoke Modelsim. Execute "do signals.do" to bring up the Waveform window and list of important signals. Execute "run -a" to start the simulation.
20. Here is a snapshot of the time (25480 ns) when the LEON Processor writes into the first Register from the Register File. The waveform window that came up during simulation should have the same signals. Note that of all the APB Slave signals, we are interested in the Slave with Index 14. Exit Modelsim when you are done.
21. That's it! That finishes the introductory tutorial on getting started with LEON Simulations and adding new slave modules to it. More links about the LEON Processor can be found at the MUSE SOC Website.