OpenCores

Using make

The build utility "make" is used to control which source files are compiled. The file "makefile" controls the actions of the make utility. Each target in the file "makefile" consists of a left justified target name followed by a colon. Following the colon is an optional list of dependancies. The lines after the target must start with the TAB character. These lines specify the commands used to build this target.

For example, to compile the count test program type:

C:\mlite\tools>make count
This will cause the utility "make" to read the file "makefile" for the target "count":
count:
	$(AS_MIPS) -o boot.o boot.asm
	$(GCC_MIPS) count.o
	$(GCC_MIPS) no_os.s
	$(LD_MIPS) -Ttext 0 -e entry -Map test.map -s -N -o test.axf boot.o count.o no_os.o
	convert_bin.exe
	$(CP) code.txt $(VHDL_DIR)
This causes the files boot.asm, count.c, and no_os.c to be compiled and linked. AS_MIPS is defined elsewhere in the makefile.

You can use the GNU version of make. Additional information can be found at Wikipedia.

Compiling the helper utilities

First, the helper utilities need to be compiled. (See the overview tab for pre-compiled versions of these helper utilities.)

C:\mlite\tools>gmake
convert.c
tracehex.c
bintohex.c
ram_image.c
make targets = count, opcodes, pi, test, run, tohex, bootldr, toimage, etermip

Compiling count.c

The program "count.c" can be used to test the CPU emulator. To compile "count.c":

C:\mlite\tools>gmake count
..\gccmips_elf\as -o boot.o boot.asm
..\gccmips_elf\gcc -O2 -Wall -c -s  count.c
..\gccmips_elf\gcc -O2 -Wall -c -s  no_os.c
..\gccmips_elf\ld -Ttext 0 -eentry -Map test.map -s -N -o test.axf \
        boot.o count.o no_os.o
..\gccmips_elf\objdump --disassemble test.axf > test.lst
convert_bin.exe
test.axf -> code.txt & test.bin
Entry=0x0
copy code.txt ..\vhdl
        1 file(s) copied.
This created the files "code.txt" and "test.bin" which the simulators can use. Try running the program using a C based simulator of the Plasma CPU:
C:\mlite\tools>gmake run
mlite.c
Plasma emulator
Read 2640 bytes.
pid=0 userMode=0, epc=0x0
00 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
08 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
16 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
24 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
 fffffff0 00000000      SLL $00 $00 $00 $00 0000
 fffffff4 00000000      SLL $00 $00 $00 $00 0000
 fffffff8 00000000      SLL $00 $00 $00 $00 0000
 fffffffc 00000000      SLL $00 $00 $00 $00 0000
*00000000 3c1c0001      LUI $00 $28 $00 $00 0001
 00000004 279c8a40    ADDIU $28 $28 $17 $09 8a40
 00000008 3c050000      LUI $00 $05 $00 $00 0000
 0000000c 24a50a50    ADDIU $05 $05 $01 $09 0a50
 00000010 3c040000      LUI $00 $04 $00 $00 0000
 00000014 24840c70    ADDIU $04 $04 $01 $17 0c70
 00000018 3c1d0000      LUI $00 $29 $00 $00 0000
 0000001c 27bd0c58    ADDIU $29 $29 $01 $17 0c58
 00000020 aca00000       SW $05 $00 $00 $00 0000
1=Debug 2=Trace 3=Step 4=BreakPt 5=Go 6=Memory 7=Watch 8=Jump 9=Quit>
Hit '5' to run:
0000000003: three
0000000009: nine
0000000027: twenty seven
0000000081: eighty one
0000000243: two hundred forty three
0000000729: seven hundred twenty nine
0000002187: two thousand one hundred eighty seven
0000006561: six thousand five hundred sixty one
0000019683: nineteen thousand six hundred eighty three
0000059049: fifty nine thousand forty nine
0000177147: one hundred seventy seven thousand one hundred forty seven
0000531441: five hundred thirty one thousand four hundred forty one
...
This same program can be simulated on a VHDL simulator by compiling the VHDL in mlite/vhdl and using the file "code.txt" as the input program. The file "output.txt" will be created with the text above.

Testing Opcodes

All of the opcodes can be tested by compiling and running opcodes.asm:

C:\mlite\tools>gmake opcodes
..\gccmips_elf\as -o opcodes.o opcodes.asm
..\gccmips_elf\ld -Ttext 0 -eentry -Map test.map -s -N -o test.axf opcodes.o
convert_bin.exe
test.axf -> code.txt & test.bin
Entry=0x0
copy code.txt ..\vhdl
        1 file(s) copied.

C:\mlite\tools>gmake run
Plasma emulator
Read 3848 bytes.
pid=0 userMode=0, epc=0x0
00 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
08 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
16 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
24 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
 fffffff0 00000000      SLL $00 $00 $00 $00 0000
 fffffff4 00000000      SLL $00 $00 $00 $00 0000
 fffffff8 00000000      SLL $00 $00 $00 $00 0000
 fffffffc 00000000      SLL $00 $00 $00 $00 0000
*00000000 3c1c0001      LUI $00 $28 $00 $00 0001
 00000004 279c8ef4    ADDIU $28 $28 $17 $27 8ef4
 00000008 3c040000      LUI $00 $04 $00 $00 0000
 0000000c 24840f08    ADDIU $04 $04 $01 $28 0f08
 00000010 3c050000      LUI $00 $05 $00 $00 0000
 00000014 24a50f08    ADDIU $05 $05 $01 $28 0f08
 00000018 00000000      SLL $00 $00 $00 $00 0000
 0000001c 00000000      SLL $00 $00 $00 $00 0000
 00000020 10000009      BEQ $00 $00 $00 $00 0009
1=Debug 2=Trace 3=Step 4=BreakPt 5=Go 6=Memory 7=Watch 8=Jump 9=Quit> 5

Arith
aA
bA
cA
dA
eABCDE
fA
gABCDE
hA
iABCDEF
jAB
kAB
lAB
mA
nA
Branch
aAB
bABCDE
cABCD
dABCD
eABCDE
fABCD
...

ModelSim Simulations

ModelSim can be used to simulate the design.

1. Open ModelSim and select File -> New -> Project.
2. Type in a project name (like "mysim") and set the Project Location to the "trunk/vhdl" directory and click OK.
3. Next, select "Add Existing File", click browse, select all of the "*.vhd" files and click Open, then OK, then Close.
4. If you don't see the Workspace with the files listed then select View -> Workspace.
5. Next remove the following files from the Workspace: cache.vhd, plasma_3e.vhd, plasma_if.vhd, ram_ctrl.vhd, ram_xilinx.vhd, and ram_image.vhd. These files are used for synthesis but not simulation.
6. The order of compiling is important. Select Compile -> Compile Order.
7. Reorder the VHDL files so that "mlite_pack.vhd" is first and "tbench.vhd" is last then click OK.
8. Select Compile -> Compile All.
9. At the bottom of the Workspace select the Library tab.
10. Click on the plus sign next to "work" to see the VHDL entities.
11. Right click on "tbench" and select "Simulate". It will use "code.txt" as the input opcodes.
12. The Workspace "sim" tab is now open showing a directory of the VHDL entities. Select tbench -> u1_plasma. Right click on u1_plasma and select Add -> Add to Wave.
13. In the bottom window with the prompt type "run 10ms".
14. In the wave window right click on "/tbench/u1_plasma/cpu_address" and select Radix -> Hexidecimal. Do the same for "/tbench/u1_plasma/cpu_data_w" and "tbench/u1_plasma/cpu_data_r".
15. See that the opcode "3C1C0001" is fetched from address 0 and opcode "279C8Ef4" is fetched from address 4.
16. Look at the output file "output.txt" that was created from the simulation run.

Bootloader

Use the bootldr.c program to load programs into the FPGA:

C:\mlite\tools>gmake bootldr
..\gccmips_elf\as -o boot.o boot.asm
..\gccmips_elf\gcc -O2 -Wall -c -s  bootldr.c
..\gccmips_elf\gcc -O2 -Wall -c -s  no_os.c
..\gccmips_elf\ld -Ttext 0 -eentry -Map test.map -s -N -o test.axf \
        boot.o bootldr.o no_os.o
convert_bin.exe
test.axf -> code.txt & test.bin
Entry=0x0
copy code.txt ..\vhdl
        1 file(s) copied.
If you are using a Xilinx FPGA, use the program ram_image to merge the files vhdl/ram_xilinx.vhd and code.txt into the file vhdl/ram_image.vhd which can then be compiled into the FPGA image.
C:\mlite\tools>gmake toimage
ram_image.exe ../vhdl/ram_xilinx.vhd ../vhdl/code.txt ../vhdl/ram_image.vhd
If you are using a Altera FPGA, use the program tohex to create the code*.hex files:
C:\mlite\tools>gmake tohex
bintohex.exe test.bin
copy code*.hex ..\vhdl
code0.hex
code1.hex
code2.hex
code3.hex
        4 file(s) copied.

Xilinx Spartan3

Dr. Gilles SASSATELLI and Dr. Gabriel Marchesan ALMEIDA taught a FPGA class that used the Plasma CPU. The class notes contain an excellent tutorial for how to program the Plasma CPU into a Xilinx Spartan3 FPGA.

Terminal Program

You can use a terminal program such as the popular program Tera Term. Be sure to set the baud rate to 57600 baud, 8 bits, no parity, 1 stop bit, with NO flow control. When downloading a file using File->Send File be sure to check the "Binary" check box!

Compile the utility etermip to permit a serial port download of new programs and to permit Ethernet packets to be transfered between the PC and target. Be sure to download wpcap.lib from wpcap.lib first. The library wpcap.lib is used to obtain raw Ethernet packets:

C:\mlite\tools>gmake etermip
etermip.c
Get wpcap.lib from http://www.winpcap.org/
Compile the count program into high memory:
C:\Steve\vhdl\mlite\tools>gmake count2
..\gccmips_elf\as -o boot.o boot.asm
..\gccmips_elf\gcc -O2 -Wall -c -s  count.c
..\gccmips_elf\gcc -O2 -Wall -c -s  no_os.c
..\gccmips_elf\ld -Ttext 0x10000000 -eentry -Map test.map -s -N -o test.axf \
        boot.o count.o no_os.o
..\gccmips_elf\objdump --disassemble test.axf > test.lst
convert_bin.exe
test.axf -> code.txt & test.bin
Entry=0x10000000
copy code.txt ..\vhdl
        1 file(s) copied.
With the target board up and running start etermip to download the count program. If you have multiple Ethernet adaptors select the Ethernet adaptor to use:
C:\mlite\tools>gmake download
etermip.c
Get wpcap.lib from http://www.winpcap.org/
Reset board before downloading code
etermip
1. \Device\NPF_GenericDialupAdapter (Generic dialup adapter)
2. \Device\NPF_{F48E4C3B-C741-492E-8606-74DB529F31DC} (3Com EtherLink PCI)
inum = 2

listening on 3Com EtherLink PCI...
Sending test.bin (length=2640 bytes) to target...
Done downloading

Greetings from the bootloader Jun 19 2007 20:31:28:

Waiting for binary image linked at 0x10000000
Other Menu Options:
1. Memory read word
2. Memory write word
3. Memory read byte
4. Memory write byte
5. Jump to address
6. Raw memory read
7. Raw memory write
8. Checksum
9. Dump
>
0000000003: three
0000000009: nine
0000000027: twenty seven
0000000081: eighty one
0000000243: two hundred forty three
0000000729: seven hundred twenty nine
0000002187: two thousand one hundred eighty seven
0000006561: six thousand five hundred sixty one
0000019683: nineteen thousand six hundred eighty three
0000059049: fifty nine thousand forty nine
0000177147: one hundred seventy seven thousand one hundred forty seven
0000531441: five hundred thirty one thousand four hundred forty one
...

Video Demo

A Plasma CPU user uploaded a silent eight minute youtube video. It shows running the bootloader, downloading the web server application via the serial port, using ftp to copy files to the board, using telnet to copy the files to the web server flash directory, and then seeing the web server run.

Kernel

Plasma RTOS Build Instructions

Be sure to understand the Plasma Tools build instructions before trying to compile the Plasma RTOS or Plasma TCP/IP stack.

Plasma RTOS

The Plasma RTOS can be run in three different modes:
Object Create Delete Read Write
Thread OS_ThreadCreate( ) OS_ThreadExit( ) OS_ThreadPriorityGet( ) OS_ThreadPrioritySet( )
Semaphore OS_SemaphoreCreate( ) OS_SemaphoreDelete( ) OS_SemaphorePend( ) OS_SemaphorePost( )
Mutex OS_MutexCreate( ) OS_MutexDelete( ) OS_MutexPend( ) OS_MutexPost( )
MessageQueue OS_MQueueCreate( ) OS_MQueueDelete( ) OS_MQueueGet( ) OS_MQueueSend( )
Timer OS_TimerCreate( ) OS_TimerDelete( ) OS_TimerStop( ) OS_TimerStart( )
Heap OS_HeapCreate( ) OS_HeapDestroy( ) OS_HeapMalloc( ) OS_HeapFree( )
Interrupt OS_InterruptMaskSet( ) OS_InterruptMaskClear( ) OS_InterruptStatus( ) OS_InterruptRegister( )
TCP/IP IPOpen( ) IPClose( ) IPRead( ) IPWrite( )
File fopen( ) fclose( ) fread( ) fwrite( )

RTOS on PC

To compile for the PC platform and test the timers:
C:\>cd mlite\kernel

C:\mlite\kernel>gmake testrtos
rtos.c
libc.c
uart.c
rtos_test.c
math.c
testrtos.exe
Starting RTOS
SimIsr

1 CLib
2 Heap
3 Thread
4 Semaphore
5 Mutex
6 MQueue
7 Timer
8 Math
9 Syscall
> 7
TestTimer
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 Done.

1 CLib
2 Heap
3 Thread
4 Semaphore
5 Mutex
6 MQueue
7 Timer
8 Math
9 Syscall
> C

RTOS on Plasma CPU simulator

The Plasma RTOS can be compiled for the Plasma CPU and then run on the Plasma CPU simulator:
C:\mlite\kernel>gmake rtos
..\gccmips_elf\as -o boot.o ..\tools\boot.asm
..\gccmips_elf\gcc -O2 -Wall -c -s -I..\tools -msoft-float  rtos.c
..\gccmips_elf\gcc -O2 -Wall -c -s -I..\tools -msoft-float  libc.c
..\gccmips_elf\gcc -O2 -Wall -c -s -I..\tools -msoft-float  uart.c
..\gccmips_elf\gcc -O2 -Wall -c -s -I..\tools -msoft-float  rtos_test.c
..\gccmips_elf\gcc -O2 -Wall -c -s -I..\tools -msoft-float  math.c
..\gccmips_elf\ld -Ttext 0x10000000 -eentry -Map test.map -s -N -o test.axf \
boot.o rtos.o libc.o uart.o rtos_test.o math.o
..\tools\convert_bin
test.axf -> code.txt & test.bin
Entry=0x10000000
cp test.bin ..\tools

C:\mlite\kernel>gmake run
Plasma emulator
Read 24808 bytes.
pid=0 userMode=0, epc=0x0
00 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
08 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
16 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
24 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
 fffffff0 00000000      SLL $00 $00 $00 $00 0000
 fffffff4 00000000      SLL $00 $00 $00 $00 0000
 fffffff8 00000000      SLL $00 $00 $00 $00 0000
 fffffffc 00000000      SLL $00 $00 $00 $00 0000
*00000000 3c1c1001      LUI $00 $28 $02 $00 1001
 00000004 279ce0c7    ADDIU $28 $28 $28 $03 e0c7
 00000008 3c051000      LUI $00 $05 $02 $00 1000
 0000000c 24a560e8    ADDIU $05 $05 $12 $03 60e8
 00000010 3c041000      LUI $00 $04 $02 $00 1000
 00000014 24846830    ADDIU $04 $04 $13 $00 6830
 00000018 3c1d1000      LUI $00 $29 $02 $00 1000
 0000001c 27bd6818    ADDIU $29 $29 $13 $00 6818
 00000020 aca00000       SW $05 $00 $00 $00 0000
1=Debug 2=Trace 3=Step 4=BreakPt 5=Go 6=Memory 7=Watch 8=Jump 9=Quit> 5
Starting RTOS
SimIsr

1 CLib
2 Heap
3 Thread
4 Semaphore
5 Mutex
6 MQueue
7 Timer
8 Math
9 Syscall
> 7
TestTimer
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 Done.
C

Plasma RTOS on Plasma CPU in FPGA

The Plasma CPU can be run on the Plasma CPU in an FPGA after resetting the FPGA:
C:\mlite\kernel>gmake rtos
..\gccmips_elf\as -o boot.o ..\tools\boot.asm
..\gccmips_elf\gcc -O2 -Wall -c -s -I..\tools -msoft-float  rtos.c
..\gccmips_elf\gcc -O2 -Wall -c -s -I..\tools -msoft-float  libc.c
..\gccmips_elf\gcc -O2 -Wall -c -s -I..\tools -msoft-float  uart.c
..\gccmips_elf\gcc -O2 -Wall -c -s -I..\tools -msoft-float  rtos_test.c
..\gccmips_elf\gcc -O2 -Wall -c -s -I..\tools -msoft-float  math.c
..\gccmips_elf\ld -Ttext 0x10000000 -eentry -Map test.map -s -N -o test.axf \
boot.o rtos.o libc.o uart.o rtos_test.o math.o
..\tools\convert_bin
test.axf -> code.txt & test.bin
Entry=0x10000000
cp test.bin ..\tools

C:\mlite\kernel>gmake download
Reset board before downloading code
..\tools\etermip
1. \Device\NPF_GenericDialupAdapter (Generic dialup adapter)
2. \Device\NPF_{F48E4C3B-C741-492E-8606-74DB529F31DC} (3Com EtherLink PCI)
inum = 2

listening on 3Com EtherLink PCI...
Sending test.bin (length=24808 bytes) to target...
Done downloading
Starting RTOS

1 CLib
2 Heap
3 Thread
4 Semaphore
5 Mutex
6 MQueue
7 Timer
8 Math
9 Syscall
> 7
TestTimer
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 Done.
C

Plasma TCP/IP Stack

The Plasma TCP/IP stack can be run in two modes:
  • Natively on the PC
  • On the Plasma CPU with the Plasma RTOS in the FPGA

TCP/IP stack on the PC

C:\mlite\kernel>gmake testip
tcpip.c
http.c
netutil.c
filesys.c
libc.c
etermip.c
libc.c
Try http://plasmb/.  Try telnet plasmb.  Try ftp plasmb.
testip.exe
1. \Device\NPF_GenericDialupAdapter (Generic dialup adapter)
2. \Device\NPF_{F48E4C3B-C741-492E-8606-74DB529F31DC} (3Com EtherLink PCI)
inum = 2

listening on 3Com EtherLink PCI...
T(99)IP=192.168.2.166 GW=192.168.2.1 DNS=192.168.2.123
If you don't have a DHCP server, you can set the IP address to 192.168.1.18 by changing tcpip.c:
   static uint8 ipAddressPlasma[] = {192, 168, 1, 18}; //changed by DHCP
Then open a web browser to http://plasmb/ or to the IP address specified in the DHCP response: http://192.168.2.166/:
Home Page
Welcome! Other myprog
You can connect to the target's FTP server:
C:\>echo This is a test file > test.txt

C:\>ftp plasmb
Connected to 192.168.2.166.
220 Connected to Plasma
User (157.254.39.166:(none)): PlasmaSend
331 Password?
Password: pass
230 Logged in
ftp> send test.txt
200 OK
150 File ready
226 Done
ftp: 22 bytes sent in 0.00Seconds 22000.00Kbytes/sec.
ftp> quit
221 Bye
You can also telnet to the target:
C:\mlite\kernel\telnet plasmb
Welcome to Plasma.
-> help
Commands: help, exit, cat, cp, ls, mkdir, rm, info, math, ping, ftp, tftp, show, clear, mkfile
-> mkdir mydir

-> ls
mydir  test.txt
-> cat test.txt
This is a test file

-> exit

Plasma TCP/IP stack running on Plasma CPU in FPGA

To run the Plasma TCP/IP in the FPGA:
C:\mlite\kernel>gmake rtos_tcpip
..\gccmips_elf\as -o boot.o ..\tools\boot.asm
..\gccmips_elf\gcc -O2 -Wall -c -s -I..\tools -msoft-float  rtos.c
..\gccmips_elf\gcc -O2 -Wall -c -s -I..\tools -msoft-float  libc.c
..\gccmips_elf\gcc -O2 -Wall -c -s -I..\tools -msoft-float  uart.c
..\gccmips_elf\gcc -O2 -Wall -c -s -I..\tools -msoft-float  rtos_test.c -DINCLUD
E_HTML -DINCLUDE_CONSOLE
..\gccmips_elf\gcc -O2 -Wall -c -s -I..\tools -msoft-float  math.c
..\gccmips_elf\gcc -O2 -Wall -c -s -I..\tools -msoft-float  tcpip.c
..\gccmips_elf\gcc -O2 -Wall -c -s -I..\tools -msoft-float  http.c -DINCLUDE_FIL
ESYS -DEXAMPLE_HTML
..\gccmips_elf\gcc -O2 -Wall -c -s -I..\tools -msoft-float  netutil.c
..\gccmips_elf\gcc -O2 -Wall -c -s -I..\tools -msoft-float  filesys.c
..\gccmips_elf\ld -Ttext 0x10000000 -eentry -Map test.map -s -N -o test.axf \
boot.o rtos.o libc.o uart.o rtos_test.o math.o tcpip.o \
http.o netutil.o filesys.o
..\tools\convert_bin
test.axf -> code.txt & test.bin
Entry=0x10000000
cp test.bin ..\tools

C:\mlite\kernel>gmake download
Reset board before downloading code
..\tools\etermip
1. \Device\NPF_GenericDialupAdapter (Generic dialup adapter)
2. \Device\NPF_{F48E4C3B-C741-492E-8606-74DB529F31DC} (3Com EtherLink PCI)
inum = 2

listening on 3Com EtherLink PCI...
Sending test.bin (length=50880 bytes) to target...
Done downloading
T(99)IP=192.168.2.166 GW=192.168.2.1 DNS=192.168.2.123
Then use the same commands as above but replace "plasmb" with "plasma".