View source for POD Tutorial

 {{Under_Construction}}

{{Warning| Figures are not up to date}}

== Introduction ==

In this first tutorial, we will learn how to use POD with a simple example project for an [[APF9328]] board.
The project is described in figure 1. It is composed of 3 virtual components:
*  '''blink''' : blink is the instance name of a led (virtual component) that can «blink» by simply writing a value in a register.
*  '''push''' : push is the instance name of a button (virtual component) that can generate an interrupt when pushed/released. The state of the button can be read in a register.
*  '''i2c''' : i2c is the instance name of the i2cocore virtual component (from OpenCores.org). This component is an i2c bus controller.

[[image:exemple-i2cledbutton.png|center|frame|400px|'''figure 1''' - ''Project example for tutorial'']]

== Installation ==

See [[POD installation guide]] to learn how to install it.

{{Note| This tutorial is written for apf27_dev a LED is already soldered on fpga. The fpga bank1 must be powered with 3.3V (connect pin 39 and pin 1 on J20 header)}}

== POD ==

If POD is [[POD_installation_guide | correctly installed]], simply type :
<pre class="host">
$ pod 
POD> 
</pre>

=== Playing with POD ===

POD is a console program composed of several environments described in figure 2.

[[image:podenvironment.png|center|frame|250px|'''figure 2''' - ''POD console architecture'']]

To enter in an environment, simply write its name from the parent environment.

<pre class="host">
POD> synthesis 
POD.synthesis> 
</pre>

For a complete list of the available commands type ''help''
<pre class="pod">
POD> help

Documented commands (type help <topic>):
========================================
EOF               create            history         ls              shell     
addbusclock       delbusconnection  info            printxml        simulation
addinstance       delinstance       intercon        quit            source    
autoconnectbus    delpinconnection  listcomponents  report          synthesis 
check             description       listforce       savehistory     top       
closeproject      driver            listinstances   saveproject     version   
connectbus        eof               listinterfaces  selectplatform
connectinterface  exit              listmasters     setaddr       
connectpin        getmapping        listplatforms   setforce      
connectport       help              load            setgeneric    

</pre>

A short help description is although available for each command.

<pre class="pod">
POD> help listcomponents
 listcomponents [componenttype]
        List components available in the library
        
POD> 
</pre>

Command completion and argument completion can be done by using the <TAB> key :

<pre class="host">
POD> help list<TAB>
listcomponents  listinterfaces  listplatforms   
listinstances   listmasters  
POD> help list
</pre>

System commands can be used with «!» before:
<pre class="host">
POD> !echo "POD is really useful"
POD is really useful
POD> 
</pre>

=== Project creation ===

[[image:exemple-empty.png|center|frame|400px|'''figure 3''' - ''Empty i2cledbutton project'']]

To create a project, enter the ''create'' command in the ''project'' environment:
<pre style="host">
POD> create i2cledbutton
Project i2cledbutton created
POD:i2cledbutton> 
</pre>

The ''i2cledbutton'' project is now created and saved. 

The target platform has to be selected by means of the ''selectplatform'' command :

<pre style="host">
project:i2cledbutton> selectplatform standard.apf27
[INFO]   : No platform in project
Component platform added as apf27
Component imx27_wb16_wrapper added as imx27_wb16_wrapper00
Component rstgen_syscon added as rstgen_syscon00
Component irq_mngr added as irq_mngr00

project:i2cledbutton> 
</pre>

By selecting this platform, several components will be automaticaly added by POD:
* '''imx27_wb16_wrapper''': this component is used to convert the i.MX27 processor bus to the wishbone (16bits data) bus.
* '''rstgen_syscon''' : this component manages the clock and the reset for the design.
* '''irq_mngr''' : this is a wishbone16 slave which manages the interrupts generated by the other components and which propagates them to the processor.

[[image:exemple-platform.png|center|frame|400px|'''figure 4''' - ''Platform loaded with their default components'']]

=== Adding components ===

Components are organized by category in the library, to list the categories, use ''listcomponents'':

<pre style="host">
project:i2cledbutton> listcomponents 
components  logics   syscons     test   wrappers
</pre>

And to list the components under a category use ''listcomponents'' again with the category name in parameter:

<pre style="host">
project:i2cledbutton> listcomponents components
sp_vision_configure      bram              uart16750   spartan_selectmap
industrial_output        anybus_interface  simplegpio  button           
industrial_serial_input  led               uart16550   sja1000          
i2cocore                 pod_gpio          irq_mngr  
</pre>

The components will be loaded with the command ''addinstances'':
<pre style="host">
POD:i2cledbutton> help addinstance
 addinstance <componenttype>.<componentname>.[componentversion] [newinstancename]
        Add component in project
</pre>

The second parameter is used to give the instance name of the component in the project.

<pre style="host">
POD:i2cledbutton> addinstance components.button push
Component button added as push

POD:i2cledbutton> addinstance components.led.wb16 blink
Component led added as blink

POD:i2cledbutton> addinstance components.i2cocore.wb16 i2c
Component i2cocore added as i2c
</pre>

Note: some components like the led may have several versions depending on the Wishbone bus size for example.

[[image:exemple-components.png|center|frame|400px|'''figure 4''' - ''Components loaded'']]

=== Internal pin connections ===

''push'' and ''i2c'' components have output pins to generate interrupts. These pins have
to be connected to the interrupt manager "irq_mngr00".


[[image:exemple-intconnection.png|center|frame|400px|'''figure 5''' - ''Internal interrupts connections'']]

A complete description of an instance in the project can be displayed with the ''info'' command:

<pre style="host">
project:i2cledbutton> info i2c
Instance name :i2c
Component  name :i2cocore
description : A simple button ip
->Generics
             id : 1
        wb_size : 16
->Interfaces
irq             :
     inta_o          s1
i2c             :
     scl             s1
     sda             s1
swb16            Base address:0x0
     rst_i           s1
     clk_i           s1
     adr_i           s4
     dat_i           s16
     dat_o           s16
     we_i            s1
     stb_i           s1
     ack_o           s1
     cyc_i           s1
project:i2cledbutton> 
</pre>

This command gives the interfaces, the ports and the size of the ports (s1, s16, ...). We want to 
connect the interrupt port pin number 0, named '''inta_o''' and part of the '''irq''' 
interface, to the ''irq_mngr00''.

<pre style="host">
POD:i2cledbutton> info irq_mngr00
Component name :irq_mngr00
Instance  name :irq_mngr
description : Manage interruptions.
->Generics
             id : 1
      irq_level : '1'
      irq_count : 1
->Interfaces
candr           :
     gls_clk         s1
     gls_reset       s1
swb16            Base address:0x0
     wbs_s1_address  s2
     wbs_s1_readdata s16
     wbs_s1_writedata s16
     wbs_s1_ack      s1
     wbs_s1_strobe   s1
     wbs_s1_cycle    s1
     wbs_s1_write    s1
irq             :
     irqport         s16
ext_irq         :
     gls_irq         s1
        pin 0: -> apf27.fpga.TIM1.0
</pre>

The targeted port in the irq_mngr is '''irqport''' part of the '''irq''' interface. To establish the connection, the ''connectpin'' command will be used:

<pre style="host">
POD:i2cledbutton> connectpin irq_mngr00.irq.irqport.0 i2c.irq.inta_o.0

</pre>

Same thing for the push button :

<pre style="host">
POD:i2cledbutton> connectpin irq_mngr00.irq.irqport.1 push.int_button.irq.0
pin connected
</pre>

The ''info'' command can be used to verify that the connection is correctly performed:

<pre style="host">
POD:i2cledbutton> info irq_mngr00
Component name :irq_mngr00
Instance  name :irq_mngr
description : Manage interruptions.
->Generics
             id : 1
      irq_level : '1'
      irq_count : 2
->Interfaces
candr           :
     gls_clk         s1
     gls_reset       s1
swb16            Base address:0x0
     wbs_s1_address  s2
     wbs_s1_readdata s16
     wbs_s1_writedata s16
     wbs_s1_ack      s1
     wbs_s1_strobe   s1
     wbs_s1_cycle    s1
     wbs_s1_write    s1
irq             :
     irqport         s16
        pin 0: -> i2c.irq.inta_o.0
        pin 1: -> push.int_button.irq.0
ext_irq         :
     gls_irq         s1
        pin 0: -> apf27.fpga.TIM1.0
</pre>

=== External pin connections ===

Connecting an external pin is done the same way as for an internal pin by giving the name of the platform in place of the instance name. In the '''apf27''' platform, the pin name 
can be found in FPGA schematic [http://www.armadeus.com/_downloads/apf27Dev/hardware/apf27_devfull_12.pdf]. 
The name of the interface is '''fpga''' for the apf27. In this example we will connect the button, the led and the i2c to the apf27DevFull connector X7 (figure 6). 

[[image:led_apf27_dev.png|center|frame|400px|'''figure 5''' - ''FPGA led connection on apf27Devfull'']]

We just have to connect the pins as following :

<pre style="host">
POD:i2cledbutton> connectpin blink.int_led.led.0 apf27.fpga.IO_L24P_1
POD:i2cledbutton> connectpin push.int_button.button.0 apf27.fpga.IO_L24N_1 
POD:i2cledbutton> connectpin i2c.i2c.sda apf27.fpga.IO_L20N_1
POD:i2cledbutton> connectpin i2c.i2c.scl apf27.fpga.IO_L20P_1
</pre>

[[image:exemple-extconnection.png|center|frame|400px|'''figure 6''' - ''external connections'']]

=== Bus and clock connections ===

* '''Bus'''

[[image:exemple-busconnection.png|center|frame|400px|'''figure 7''' - ''Wishbone bus connections'']]


To connect a bus, the master bus interface is used as first argument of the ''connectbus'' command, the second argument being the slave bus interface:

<pre style="host">
POD:i2cledbutton> connectbus imx27_wb16_wrapper00.mwb16 blink.swb16
setting base address 0x0 for  blink.swb16

POD:i2cledbutton> connectbus imx27_wb16_wrapper00.mwb16 push.swb16
setting base address 0x4 for  push.swb16

POD:i2cledbutton> connectbus imx27_wb16_wrapper00.mwb16 i2c.swb16
setting base address 0x20 for  i2c.swb16

POD:i2cledbutton> connectbus imx27_wb16_wrapper00.mwb16 irq_mngr00.swb16
setting base address 0x40 for  irq_mngr00.swb16
</pre>

* '''clock & reset'''

[[image:exemple-clockconnection.png|center|frame|400px|'''figure 8''' - ''Syscon connection'']]

Clock and reset are seen like a standard bus, to connect it, simply use connectbus:

<pre style="host">
project:i2cledbutton> connectbus rstgen_syscon00.candroutput imx27_wb16_wrapper00.candrinput
No addressing value in this type of bus
</pre>

* '''autoconnect'''

Bus and clock connections can be automatically performed with the ''autoconnect'' command. This command works only for "classical" architectures and with recognized busses.

<pre style="host">
POD:i2cledbutton> autoconnectbus
</pre>

=== Intercon generation ===

Once the connections done, the Intercons components has to be generated. Intercons are components
responsible for decoding the addresses and for routing bus signals. Intercons must be generated for each master bus.

* for wrapper master wishbone bus
<pre style="host">
POD> intercon imx27_wb16_wrapper00.mwb16
Intercon with name : imx27_wb16_wrapper00_mwb16_intercon Done
Component imx27_wb16_wrapper00_mwb16 added as imx27_wb16_wrapper00_mwb16_intercon
</pre>

* for syscon master candr bus
<pre style="host">
POD> intercon rstgen_syscon00.candroutput
Intercon with name : rstgen_syscon00_candroutput_intercon Done
Component rstgen_syscon00_candroutput added as rstgen_syscon00_candroutput_intercon
</pre>

[[image:exemple-intercon.png|center|frame|400px|'''figure 8''' - ''Intercon'']]

=== Top generation ===

[[image:exemple-top.png|center|frame|400px|'''figure 9''' - ''Top'']]

The Top component is the component responsible for connecting all instances in the FPGA. The Top can be generated with the ''top'' command

<pre style="host">
POD:i2cledbutton> top

Mapping for interface mwb16:
Address  | instance.interface             | size
---------------------------------------------------------
0x0 |                    blink.swb16 |          4
0x4 |                     push.swb16 |          4
0x08 |                       --void-- |         24
0x20 |                      i2c.swb16 |         32
0x40 |               irq_mngr00.swb16 |          8
---------------------------------------------------------

Top generated with name : top_i2cledbutton.vhd
</pre>

== Synthesis ==

In the '''apf27''' platform, the FPGA is a Spartan3A from Xilinx. This means that the synthesis of the project can only be done with ISE. Fortunately, Xilinx provides the ISE 
Webpack freely on its website [http://www.xilinx.com/ise/logic_design_prod/webpack.htm].

POD has to generate a project that ISE can understand. This can be accomplished from the synthesis environment :

<pre style="host">
POD:i2cledbutton-tutorial> synthesis
POD.synthesis> 
</pre>

Then the tool used for the synthesis has to be specified with the ''selecttoolchain'' command:

<pre style="host">
POD.synthesis> selecttoolchain ise
</pre>

After that we can generate an ISE project with the ''generateproject'' command.

<pre style="host">
POD> synthesis
POD.synthesis> selecttoolchain ise
POD.synthesis> generateproject
Make directory for imx27_wb16_wrapper
Make directory for rstgen_syscon
Make directory for irq_mngr
Make directory for button
Make directory for led
Make directory for i2cocore
Make directory for rstgen_syscon00_candroutput
Make directory for imx27_wb16_wrapper00_mwb16

Constraint file generated with name : /home/fabien/tmp/i2cledbutton/synthesis/i2cledbutton.ucf

TCL script generated with name : i2cledbutton.tcl
</pre>

As you can see, POD generates although a TCL script that can be executed by ISE. This script eases the synthesis process. 

[[image:exemple-ise.png|center|frame|400px|'''figure 10''' - ''Bitstream generation with ISE Webpack'']]

In the Tcl tab ('''1'''), change the default directory to the synthesis directory ('''2'''), find the tcl script you want to execute ('''3''', under Windows type ''dir'' instead of ''ls'') and start it with the ''source'' command ('''4''').

The resulting bitstream (binary FPGA synthetized code) ''top_i2cledbutton.bit'' can be found in the ''i2cledbutton_tutorial/objs'' directory.

== Simulation ==

If a simulation is required, POD can generate a template for the whole project. To do this, enter in the simulation environment :

<pre style="host">
POD.project:i2cledbutton_tutorial> simulation
POD.project:i2cledbutton_tutorial.simulation> 
</pre>

To generate the testbench and the makefile use the command:

<pre style="host">
POD.project:i2cledbutton_tutorial.simulation> generateproject

Testbench with name : /home/fabien/projectpod/software/pod/tests/i2cledbutton_tutorial/simulation/top_i2cledbutton_tutorial_tb.vhd Done

Makefile generated with name : /home/fabien/projectpod/software/pod/tests/i2cledbutton_tutorial/simulation/Makefile Done
</pre>

Now, you just have to modify the ''top_i2cledbutton_tutorial_tb.vhd'' file to add your own tests 
under the ''stimulis'' process.

<pre style="host">
stimulis : process
begin
-- write stimulis here
wait for 10 us;
assert false report "End of test" severity error;
end process stimulis;
</pre>

You can then start the simulation with ''make ghdl-simu'' and launch ''make ghdl-view'' to 
view the generated chronograms with gtkwave.

== Drivers ==
{{Warning| Drivers are note up to date}}

Numbers of components have a driver template for different operating systems. POD can
fill these templates with the informations contained in the project.

From the driver environment,

<pre style="host">
POD:i2cledbutton_tutorial> driver
POD:i2cledbutton_tutorial.driver> 
</pre>

choose the targeted platform:

<pre style="host">
POD:i2cledbutton_tutorial.driver> selecttoolchain armadeus
</pre>

And generate the driver project : 

<pre style="host">
POD:i2cledbutton_tutorial.driver> generateproject
No driver for imx9328_wb16_wrapper
No driver for rstgen_syscon
Create directory for irq_mngr driver
Create directory for button driver
Create directory for led driver
Create directory for i2cocore driver
No driver for imx9328_wb16_wrapper00_mwb16
Copy and fill template for irq_mngr
Copy and fill template for button
Copy and fill template for led
Copy and fill template for i2cocore
</pre>

Drivers are generated and can be found in the ''i2cledbutton_tutorial/drivers/'' directory. 
POD can copy this drivers to the right place in the software development tree. Select the path with ''selectprojecttree'' then copy the files with ''copydrivers'':

<pre style="host">
POD:i2cledbutton_tutorial.driver> selectprojecttree ~/armadeus/target/linux/modules/fpga/POD

POD:i2cledbutton_tutorial.driver> copydrivers
</pre>

To compile the drivers, go to your ''armadeus/'' directory then type ''make linux26-menuconfig''.

<pre class="config">
Device Drivers  --->
    Armadeus specific drivers  --->
        [*] Support for specific Armadeus drivers
        FPGA Drivers   --->
            <M>   Drivers generated by POD 
</pre>

<pre style="host">
$ make linux26-menuconfig
$ make
</pre>

== Test ==

Once [[Target_Software_Installation#FPGA_firmware_installation | bitstream is loaded]], run linux and modprobe pod linux module :
<pre class="apf">
# modprobe pod_irq_ocore
# modprobe pod_board_irq_mng
IRQ 256
IRQ 257
IRQ 258
IRQ 259
IRQ 260
IRQ 261
IRQ 262
IRQ 263
IRQ 264
IRQ 265
IRQ 266
IRQ 267
IRQ 268
IRQ 269
IRQ 270
IRQ 271
# modprobe g_led
# modprobe board_leds
# modprobe i2c-ocores-pod
# modprobe board_i2c
PM: Adding info for platform:ocores-i2c-pod.0
PM: Adding info for No Bus:i2c-2
PM: Adding info for No Bus:i2c-2
# modprobe gbutton
# modprobe board_i2c

</pre>

[[Category:POD]]