POD Tutorial
Contents
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.
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 correctly installed, simply type :
$ pod POD>
Playing with POD
POD is a console program composed of several environments described in figure 2.
To enter in an environment, simply write its name from the parent environment.
POD> synthesis POD.synthesis>
For a complete list of the available commands type help
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
A short help description is although available for each command.
POD> help listcomponents
listcomponents [componenttype]
List components available in the library
POD>
Command completion and argument completion can be done by using the <TAB> key :
POD> help list<TAB> listcomponents listinterfaces listplatforms listinstances listmasters POD> help list
System commands can be used with «!» before:
POD> !echo "POD is really useful" POD is really useful POD>
Project creation
To create a project, enter the create command in the project environment:
POD> create i2cledbutton Project i2cledbutton created POD:i2cledbutton>
The i2cledbutton project is now created and saved.
The target platform has to be selected by means of the selectplatform command :
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>
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.
Adding components
Components are organized by category in the library, to list the categories, use listcomponents:
project:i2cledbutton> listcomponents components logics syscons test wrappers
And to list the components under a category use listcomponents again with the category name in parameter:
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
The components will be loaded with the command addinstances:
POD:i2cledbutton> help addinstance
addinstance <componenttype>.<componentname>.[componentversion] [newinstancename]
Add component in project
The second parameter is used to give the instance name of the component in the project.
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
Note: some components like the led may have several versions depending on the Wishbone bus size for example.
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".
A complete description of an instance in the project can be displayed with the info command:
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>
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.
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
The targeted port in the irq_mngr is irqport part of the irq interface. To establish the connection, the connectpin command will be used:
POD:i2cledbutton> connectpin irq_mngr00.irq.irqport.0 i2c.irq.inta_o.0
Same thing for the push button :
POD:i2cledbutton> connectpin irq_mngr00.irq.irqport.1 push.int_button.irq.0 pin connected
The info command can be used to verify that the connection is correctly performed:
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
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 [1]. 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).
We just have to connect the pins as following :
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
Bus and clock connections
- Bus
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:
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
- clock & reset
Clock and reset are seen like a standard bus, to connect it, simply use connectbus:
project:i2cledbutton> connectbus rstgen_syscon00.candroutput imx27_wb16_wrapper00.candrinput No addressing value in this type of bus
- autoconnect
Bus and clock connections can be automatically performed with the autoconnect command. This command works only for "classical" architectures and with recognized busses.
POD:i2cledbutton> autoconnectbus
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
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
- for syscon master candr bus
POD> intercon rstgen_syscon00.candroutput Intercon with name : rstgen_syscon00_candroutput_intercon Done Component rstgen_syscon00_candroutput added as rstgen_syscon00_candroutput_intercon
Top generation
The Top component is the component responsible for connecting all instances in the FPGA. The Top can be generated with the top command
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
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 [2].
POD has to generate a project that ISE can understand. This can be accomplished from the synthesis environment :
POD:i2cledbutton-tutorial> synthesis POD.synthesis>
Then the tool used for the synthesis has to be specified with the selecttoolchain command:
POD.synthesis> selecttoolchain ise
After that we can generate an ISE project with the generateproject command.
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
As you can see, POD generates although a TCL script that can be executed by ISE. This script eases the synthesis process.
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 :
POD.project:i2cledbutton_tutorial> simulation POD.project:i2cledbutton_tutorial.simulation>
To generate the testbench and the makefile use the command:
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
Now, you just have to modify the top_i2cledbutton_tutorial_tb.vhd file to add your own tests under the stimulis process.
stimulis : process begin -- write stimulis here wait for 10 us; assert false report "End of test" severity error; end process stimulis;
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 not 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,
POD:i2cledbutton_tutorial> driver POD:i2cledbutton_tutorial.driver>
choose the targeted platform:
POD:i2cledbutton_tutorial.driver> selecttoolchain armadeus
And generate the driver project :
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
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:
POD:i2cledbutton_tutorial.driver> selectprojecttree ~/armadeus/target/linux/modules/fpga/POD POD:i2cledbutton_tutorial.driver> copydrivers
To compile the drivers, go to your armadeus/ directory then type make linux26-menuconfig.
Device Drivers --->
Armadeus specific drivers --->
[*] Support for specific Armadeus drivers
FPGA Drivers --->
<M> Drivers generated by POD
$ make linux26-menuconfig $ make
Test
Once bitstream is loaded, run linux and modprobe pod linux module :
# 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
