Difference between revisions of "A simple design with Wishbone bus"

From ArmadeusWiki
Jump to: navigation, search
m
 
(74 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 
[[Category: FPGA]]
 
[[Category: FPGA]]
This article intended to explain how to design Wishbone compatible
 
components with simple example.
 
The VHDL design can be found in sourceforge
 
[http://armadeus.svn.sourceforge.net/viewvc/armadeus/trunk/firmware/Wisbone_example/ tree].
 
  
Description of wishbone structure for armadeus can be found [[FpgaArchitecture#Le_bus_Wishbone | here]] in french.
+
This article is intended to explain how to design Wishbone compatible components with simple example.
 +
The VHDL source code can be found in firmware/wishbone_example from  [https://gitlab.com/armadeus/armadeus-bsp our gitlab repository].
 +
 
 +
Description of the Wishbone structure for Armadeus APF boards can be found [[FpgaArchitecture#Le_bus_Wishbone | here]] (in french).
  
 
== General structure ==
 
== General structure ==
  
The main functionality of this component is to do the same things
+
The main functionality of this component is to allow to switch-on a LED when a button is pressed.
that [[FPGA_and_led | benoît]] project : switch on a led when a button is  
+
pressed.
+
  
But to learn about designing Wishbone component and linux driver, the design
+
When button is pressed, the component ''button'' send interrupt signal to
is little bit more complicated (!).
+
''irq_mngr''. ''irq_mngr'' will toggle a flag and send interruption to
 
+
'''i.MX''' processor. A Linux driver on '''i.MX''' will read ''irq_mngr'' and
When button is pressed, the component ''Wb_button'' send interrupt signal to ''irq_mngr''. ''irq_mngr'' will toggle a flag and send interruption to  
+
acknowledge irq by writing '1' on the corresponding register. And finally, Linux driver will
'''i.mx''' processor. A Linux driver on '''i.mx''' will read ''irq_mngr'' and
+
toggle LED value by writing in ''led'' register.
acknowledge irq by writing '1' on a register. And finally, Linux driver will  
+
toggle led value by writing on led register.
+
 
+
 
+
[[Image:Wb_buttonled_top.png|center|800px]]
+
  
 +
[[image:Wb_buttonled_top.png|700px|center|thumb|'''figure 1''' - ''Schematics of wishbone example. /!\ Bus signals are wrong for the APF51 because addr and data are multiplexed.'']]
  
 
''imx_wrapper'', ''syscon'' and ''irq_mngr'' are standards
 
''imx_wrapper'', ''syscon'' and ''irq_mngr'' are standards
 
ARMadeus-Wishbone IPs that just been instantiated in our design.
 
ARMadeus-Wishbone IPs that just been instantiated in our design.
  
''Wb_button'' and ''Wb_led'' are simple slave component we want to
+
''button'' and ''led'' are simple slave component we want to integrate in the FPGA.
integrate in the FPGA.
+
  
 
All these components are connected together with the 'glue logic' component ''intercon''.
 
All these components are connected together with the 'glue logic' component ''intercon''.
 +
 +
=== Wrapper ===
 +
The [http://armadeus.git.sourceforge.net/git/gitweb.cgi?p=armadeus/armadeus;a=blob;f=firmware/wishbone_example/src/wishbone_wrapper.vhd;h=d23110bac06cb121677e551c9eb5efc36b9e5981;hb=HEAD wrapper] is used to convert i.MX interface signals into Wishbone signals.
 +
 +
=== Intercon ===
 +
 +
The [http://armadeus.git.sourceforge.net/git/gitweb.cgi?p=armadeus/armadeus;a=blob;f=firmware/wishbone_example/src/intercon.vhd;h=dfa98f69ee2263a715945173e138c846e186981c;hb=HEAD  intercon] is a component used to manage signals between Wishbone master and slave components. This component decode Wishbone-master addresses and dispatch them to Wishbone-slave components.
 +
 +
[[image:Wb_intercon.png|center|500px|thumb|'''figure 2''' - ''Intercon internal structure'']]
  
 
== Wishbone slave application components ==
 
== Wishbone slave application components ==
  
=== Wb_led ===
+
In this example there are 3 Wishbone-slave components :
 +
 
 +
=== irq manager ===
 +
 
 +
Some components (here, only ''button'') generate interrupts, [http://armadeus.git.sourceforge.net/git/gitweb.cgi?p=armadeus/armadeus;a=blob;f=firmware/wishbone_example/src/irq_mngr.vhd;h=014735fb81478b668091beac08af358d6c61240c;hb=HEAD irq manager] is used to mux these interrupts for i.MX. The irq_mngr can manage up to 16 internal interrupts.
 +
 
 +
IRQ manager component has tree registers, one to enable interrupts, one for flags/acknowledge interrupts and one identification register :
 +
 
 +
{| align="center" border="1" cellpadding="5" cellspacing="0" summary="irq_mgr registers"
 +
|- style="background:#efefef;" align="center"
 +
! register !! function
 +
|-
 +
| mask
 +
| write '1' to allow irq
 +
|-
 +
| ack/pend
 +
| read for pending irq, write to acknowledge irq
 +
|-
 +
| id
 +
| identification register
 +
|}
 +
 
 +
=== wb_led ===
 +
 
 +
{{Note| On apf9328_devfull and on apf27_dev a LED is already soldered on fpga. <br> '''For apf27_dev the FPGA bank1 must be powered with 3.3V''' (connect pin 39 and pin 1 on J20 header (near Ethernet one)). For '''apf51Dev''' don't forget to power banks with jumper FPGA_Bank3 and FPGA_Bank1}}
 +
 
 +
This component is a simple 16-bit Wishbone slave output port, from [http://cdn.opencores.org/downloads/wbspec_b3.pdf wishbone specification example] (p110).
 +
 
 +
[[image:wbs_led.png|center|thumb|600px|'''figure 3''' - ''LED internal structure'']]
 +
 
 +
It is a simple register, that can be read and write. The LED is controlled with register pin 0.
 +
 
 +
The two registers are :
 +
 
 +
{| align="center" border="1" cellpadding="5" cellspacing="0" summary="wb_led registers"
 +
|- style="background:#efefef;" align="center"
 +
! register name !! (relative) address !! function
 +
|-
 +
| LED || 0x00 || Write '1' in LSB to shutdown LED
 +
|-
 +
| id || 0x02 || read identification number
 +
|}
 +
 
 +
=== wb_button ===
 +
 
 +
Wb_button component, is like ''led'' but in read only and with an edge detector to rise irq.
 +
 
 +
{{Note| On [[APF27Dev]] and [[APF51Dev]] a button is already soldered to a FPGA pin. Just don't forget to power corresponding FPGA bank.<br> For [[APF9328DevFull]] a button must be connected to IO_L01N_0 FPGA pin (connector X7/FPGA2, pin 1)}}
 +
[[image:wbs_button.png|center|thumb|500px|'''figure 4''' - ''Button internal structure'']]
 +
 
 +
The two registers are:
 +
 
 +
{| align="center" border="1" cellpadding="5" cellspacing="0" summary="wb_button registers"
 +
|- style="background:#efefef;" align="center"
 +
! register !! (relative) address !! function
 +
|-
 +
| id || 0x00 || read identification number
 +
|-
 +
| Button || 0x02 || read LSB to know button state
 +
|}
 +
 
 +
== Components drivers ==
 +
 
 +
Each component is driven by a Linux driver described above. All driver code is in armadeus directory in [http://armadeus.svn.sourceforge.net/viewvc/armadeus/trunk/target/linux/modules/fpga/wishbone_example/ target/linux/module/fpga/wishbone_example/].
 +
 
 +
Each component has an identification register with unique number. This number is used by driver when modprobed to unsure that device is present.
 +
 
 +
=== irq manager ===
 +
 
 +
The description of IRQ management module is available [[POD_Interrupt_handler | here]]. The module's source code can be found [http://armadeus.svn.sourceforge.net/viewvc/armadeus/trunk/target/linux/modules/fpga/wishbone_example/wb_irq_mngr/main.c?view=markup  here].
 +
 
 +
=== LED ===
 +
 
 +
LED driver is seen in Linux like a character driver. Writing in a ''/dev'' file will enable or disable the LED.
 +
 
 +
The driver is composed of two modules :
 +
 
 +
* '''led_ocore''' : this module implement generic LED driver mechanisms.
 +
* '''wb_example_led''' : This module describe specific datas for each LED-component available in design. These datas are described in structure ''plat_led_port'' and ''plat_led_device''. The module will register each LED with ''platform_device_register()'' function. When a ''plat_led_port'' device is registered, ''led_ocore'' driver will detect it and will probe it with ''led_probe'' function.
 +
 
 +
=== button ===
 +
 
 +
Button driver is seen in Linux like a character driver. When a process want to read value in button register, the driver will block reading until an interrupt occur.
 +
 
 +
Structure of button driver is similar to LED driver (two modules) :
 +
 
 +
* '''button_ocore''' : This module implements generic button driver mechanisms.
 +
* '''wb_example_button''' : Like LED module, this module describes specific data for each button-component available in design.
 +
 
 +
== Using the design ==
 +
 
 +
All code for this design is available in ARMadeus tree, [http://armadeus.svn.sourceforge.net/viewvc/armadeus/trunk/firmware/wishbone_example/ firmware] (VHDL) and [http://armadeus.svn.sourceforge.net/viewvc/armadeus/trunk/target/linux/modules/fpga/wishbone_example/ software] (Linux drivers).
 +
 
 +
=== Make the FPGA bitstream ===
 +
 
 +
ISE Webpack is mandatory to generate the bitstream, so [[ISE_WebPack_installation_on_Linux | its installation is required]]. Once bitstream has been generated, it can be downloaded in FPGA with [[Target_Software_Installation#FPGA_firmware_installation | U-Boot]] or [[FPGA_loader | Linux]].
 +
For '''apf51''', bitstream is under the directory '''firmware/wishbone_example/wishbone_example51/binaries/top_wishbone_example51_lx9.bin'''. For apf27 and apf9328 bitstream can be found in '''firmware/wishbone_example/wishbone_example9328_27/bin/'''.
 +
 
 +
=== Compile Linux drivers ===
 +
 
 +
To compile the drivers for this design select them in Linux menuconfig:
 +
<pre class="host">
 +
$ make linux-menuconfig
 +
</pre>
 +
 
 +
<pre class="config">
 +
    Device Drivers --->
 +
        Armadeus specific drivers --->
 +
            FPGA Drivers --->
 +
                [*]  Board designs
 +
                [*]    board drivers for wishbone example
 +
                <M>      board Button
 +
                <M>      board Led
 +
                <M>      board irq
 +
</pre>
 +
 
 +
and compile them:
 +
<pre class="host">
 +
$ make linux && make
 +
</pre>
 +
 
 +
Then reflash [[Target_Software_Installation#Linux_kernel_installation | Linux]] and  [[Target_Software_Installation#rootfs_installation | rootfs]] images.
 +
 
 +
=== Play with button and LED ===
 +
 
 +
==== Load modules ====
 +
 
 +
Modules must be loaded in right order with ''modprobe'' command :
 +
 
 +
* IRQ manager :
 +
<pre class="apf">
 +
# modprobe irq_ocore
 +
# modprobe wb_example_irq_mngr
 +
</pre>
 +
* Button generic module must be loaded before board module:
 +
<pre class="apf">
 +
# modprobe button_ocore
 +
# modprobe wb_example_buttons
 +
button button.0: BUTTON0: MAJOR: 249 MINOR: 0
 +
BUTTON0 loaded
 +
</pre>
 +
* LED generic module must be loaded before board module:
 +
<pre class="apf">
 +
# modprobe led_ocore
 +
# modprobe wb_example_led
 +
LED0: MAJOR: 248 MINOR: 0
 +
LED module LED0 insered
 +
</pre>
 +
 
 +
==== Device access ====
 +
 
 +
Devices access are done with special caracters file. These file must be created '''with major and minor number given when modules are loaded''' (see ''Load modules'' above) :
 +
 
 +
* Make LED access :
 +
<pre class="apf">
 +
# mknod /dev/led0 c LED_MAJOR_NUMBER 0
 +
</pre>
 +
* Make button access :
 +
<pre class="apf">
 +
# mknod /dev/button0 c BUTTON_MAJOR_NUMBER 0
 +
</pre>
 +
 
 +
Replace '''LED_MAJOR_NUMBER''' and '''BUTTON_MAJOR_NUMBER''' with correct major number given when modprobe is done.
 +
 
 +
==== Test LED ====
 +
 
 +
A test program is available in module directory:
 +
<pre class="host">
 +
target/linux/modules/fpga/board_designs/wishbone_example/wb_led/
 +
</pre>
 +
simply compile it with arm-linux-gcc compiler :
 +
 
 +
<pre class="host">
 +
$ make test
 +
</pre>
  
This component is a simple 16-bit Wishbone slave output port, from [http://www.opencores.org/projects.cgi/web/wishbone/wbspec_b3.pdf wishbone specification example] (p110).
+
Download ''testled'' binary on your APF, then test it :
 +
<pre class="apf">
 +
# ./testled /dev/led0
 +
Testing led driver
 +
Read 1
 +
Write 0
 +
Read 0
 +
Write 1
 +
Read 1
 +
Write 0
 +
Read 0
 +
</pre>
  
[[Image:wbs_led.png|center|600px]]
+
LED is blinking slowly.
  
It is a simple register, that can be read and write. The led is controled with register pin 0.
+
==== Test Button ====
  
[[Wb_led.vhd | The VHDL source code]]
+
A test program is available in directory:
 +
<pre class="host">
 +
target/linux/modules/fpga/board_designs/wishbone_example/wb_button/
 +
</pre>
 +
simply compile it in the directory with command:
 +
<pre class="host">
 +
$ make test
 +
</pre>
  
=== Wb_button ===
+
copy the ''testbutton'' binary in your target then launch it:
 +
<pre class="apf">
 +
# ./testbutton /dev/button0
 +
Testing button driver
 +
Read 1
 +
Read 0
 +
Read 1
 +
Read 0
 +
Read 1
 +
Read 0
 +
Read 0
 +
Read 1
 +
Read 0
 +
Read 1
 +
</pre>
  
Wb_button component, is like Wb_led but in read only and with an edge detector to rise irq.
+
Each time button is pushed or released, button state is printed out.
  
[[Image:wbs_button.png|center|500px]]
+
==== Switching LED with button ====
  
[[Wb_button.vhd | The VHDL source c]]ode
+
A simple program is available in wishbone example directory:
 +
<pre class="host">
 +
target/linux/modules/fpga/board_designs/wishbone_example/
 +
</pre>
 +
to switch on the LED when button is pressed.
  
== Drivers ==
+
To compile :
 +
<pre class="host">
 +
$ make test
 +
</pre>
  
=== Wb_led ===
+
To use it, simply type (after downloaded it under your target):
The Wb_led driver implements a character device with read(), write() system calls. It implements sys/led/status entry. Driver sources can be found in [http://armadeus.svn.sourceforge.net/viewvc/armadeus/trunk/target/linux/modules/fpga/Wb_led/ sourceforge].
+
  
=== Wb_button ===
+
<pre class="apf">
The Wb_button driver implements a character device with only read() system calls. If used as blocking read, it will return value only when button is push/release. Drivers sources are on [http://armadeus.svn.sourceforge.net/viewvc/armadeus/trunk/target/linux/modules/fpga/Wb_button/ sourceforge].
+
# ./push-led /dev/button0 /dev/led0
 +
Blink a led pushing button
 +
</pre>
  
== XML ==
+
Push the button to switch on/off the LED.

Latest revision as of 11:43, 30 June 2022


This article is intended to explain how to design Wishbone compatible components with simple example. The VHDL source code can be found in firmware/wishbone_example from our gitlab repository.

Description of the Wishbone structure for Armadeus APF boards can be found here (in french).

General structure

The main functionality of this component is to allow to switch-on a LED when a button is pressed.

When button is pressed, the component button send interrupt signal to irq_mngr. irq_mngr will toggle a flag and send interruption to i.MX processor. A Linux driver on i.MX will read irq_mngr and acknowledge irq by writing '1' on the corresponding register. And finally, Linux driver will toggle LED value by writing in led register.

figure 1 - Schematics of wishbone example. /!\ Bus signals are wrong for the APF51 because addr and data are multiplexed.

imx_wrapper, syscon and irq_mngr are standards ARMadeus-Wishbone IPs that just been instantiated in our design.

button and led are simple slave component we want to integrate in the FPGA.

All these components are connected together with the 'glue logic' component intercon.

Wrapper

The wrapper is used to convert i.MX interface signals into Wishbone signals.

Intercon

The intercon is a component used to manage signals between Wishbone master and slave components. This component decode Wishbone-master addresses and dispatch them to Wishbone-slave components.

figure 2 - Intercon internal structure

Wishbone slave application components

In this example there are 3 Wishbone-slave components :

irq manager

Some components (here, only button) generate interrupts, irq manager is used to mux these interrupts for i.MX. The irq_mngr can manage up to 16 internal interrupts.

IRQ manager component has tree registers, one to enable interrupts, one for flags/acknowledge interrupts and one identification register :

register function
mask write '1' to allow irq
ack/pend read for pending irq, write to acknowledge irq
id identification register

wb_led

Note Note: On apf9328_devfull and on apf27_dev a LED is already soldered on fpga.
For apf27_dev the FPGA bank1 must be powered with 3.3V (connect pin 39 and pin 1 on J20 header (near Ethernet one)). For apf51Dev don't forget to power banks with jumper FPGA_Bank3 and FPGA_Bank1


This component is a simple 16-bit Wishbone slave output port, from wishbone specification example (p110).

figure 3 - LED internal structure

It is a simple register, that can be read and write. The LED is controlled with register pin 0.

The two registers are :

register name (relative) address function
LED 0x00 Write '1' in LSB to shutdown LED
id 0x02 read identification number

wb_button

Wb_button component, is like led but in read only and with an edge detector to rise irq.

Note Note: On APF27Dev and APF51Dev a button is already soldered to a FPGA pin. Just don't forget to power corresponding FPGA bank.
For APF9328DevFull a button must be connected to IO_L01N_0 FPGA pin (connector X7/FPGA2, pin 1)
figure 4 - Button internal structure

The two registers are:

register (relative) address function
id 0x00 read identification number
Button 0x02 read LSB to know button state

Components drivers

Each component is driven by a Linux driver described above. All driver code is in armadeus directory in target/linux/module/fpga/wishbone_example/.

Each component has an identification register with unique number. This number is used by driver when modprobed to unsure that device is present.

irq manager

The description of IRQ management module is available here. The module's source code can be found here.

LED

LED driver is seen in Linux like a character driver. Writing in a /dev file will enable or disable the LED.

The driver is composed of two modules :

  • led_ocore : this module implement generic LED driver mechanisms.
  • wb_example_led : This module describe specific datas for each LED-component available in design. These datas are described in structure plat_led_port and plat_led_device. The module will register each LED with platform_device_register() function. When a plat_led_port device is registered, led_ocore driver will detect it and will probe it with led_probe function.

button

Button driver is seen in Linux like a character driver. When a process want to read value in button register, the driver will block reading until an interrupt occur.

Structure of button driver is similar to LED driver (two modules) :

  • button_ocore : This module implements generic button driver mechanisms.
  • wb_example_button : Like LED module, this module describes specific data for each button-component available in design.

Using the design

All code for this design is available in ARMadeus tree, firmware (VHDL) and software (Linux drivers).

Make the FPGA bitstream

ISE Webpack is mandatory to generate the bitstream, so its installation is required. Once bitstream has been generated, it can be downloaded in FPGA with U-Boot or Linux. For apf51, bitstream is under the directory firmware/wishbone_example/wishbone_example51/binaries/top_wishbone_example51_lx9.bin. For apf27 and apf9328 bitstream can be found in firmware/wishbone_example/wishbone_example9328_27/bin/.

Compile Linux drivers

To compile the drivers for this design select them in Linux menuconfig:

 $ make linux-menuconfig
    Device Drivers --->
        Armadeus specific drivers --->
            FPGA Drivers --->
                [*]   Board designs
                [*]     board drivers for wishbone example
                <M>       board Button
                <M>       board Led
                <M>       board irq

and compile them:

$ make linux && make

Then reflash Linux and rootfs images.

Play with button and LED

Load modules

Modules must be loaded in right order with modprobe command :

  • IRQ manager :
# modprobe irq_ocore
# modprobe wb_example_irq_mngr
  • Button generic module must be loaded before board module:
# modprobe button_ocore
# modprobe wb_example_buttons
button button.0: BUTTON0: MAJOR: 249 MINOR: 0
BUTTON0 loaded
  • LED generic module must be loaded before board module:
# modprobe led_ocore
# modprobe wb_example_led
LED0: MAJOR: 248 MINOR: 0
LED module LED0 insered

Device access

Devices access are done with special caracters file. These file must be created with major and minor number given when modules are loaded (see Load modules above) :

  • Make LED access :
# mknod /dev/led0 c LED_MAJOR_NUMBER 0
  • Make button access :
# mknod /dev/button0 c BUTTON_MAJOR_NUMBER 0

Replace LED_MAJOR_NUMBER and BUTTON_MAJOR_NUMBER with correct major number given when modprobe is done.

Test LED

A test program is available in module directory:

target/linux/modules/fpga/board_designs/wishbone_example/wb_led/

simply compile it with arm-linux-gcc compiler :

$ make test

Download testled binary on your APF, then test it :

# ./testled /dev/led0 
Testing led driver
Read 1
Write 0
Read 0
Write 1
Read 1
Write 0
Read 0

LED is blinking slowly.

Test Button

A test program is available in directory:

target/linux/modules/fpga/board_designs/wishbone_example/wb_button/

simply compile it in the directory with command:

$ make test

copy the testbutton binary in your target then launch it:

# ./testbutton /dev/button0
Testing button driver
Read 1
Read 0
Read 1
Read 0
Read 1
Read 0
Read 0
Read 1
Read 0
Read 1

Each time button is pushed or released, button state is printed out.

Switching LED with button

A simple program is available in wishbone example directory:

target/linux/modules/fpga/board_designs/wishbone_example/

to switch on the LED when button is pressed.

To compile :

$ make test

To use it, simply type (after downloaded it under your target):

# ./push-led /dev/button0 /dev/led0 
Blink a led pushing button

Push the button to switch on/off the LED.