Easy Custom IP access with application development based on mmap

Hi !

In the previous post we've started Linux Software development with PEEK and POKE commands.

3.1 - Very Low Level access with Peek and Poke

Now we are going a step further by developping a test application, which will use existing stuff underneath, in order to limit complexity for now !

The test application will be based on mmap (Memory Map) to get easily access to our custom IP hardware ressources.


As this post is quite long, here are the main sections of this post for a quick jump :

• Step 1 : "Hello World !" template application with PetaLinux
• Step 2 : Write the test application for our Custom IP using PetaLinux
• Step 3 : Run the test application for our Custom IP on the MiniZed board

Step 1 : "Hello World !" template application with PetaLinux

The PetaLinux toolset is very powerfull and among all its functionalities we will use here its application development capability.

Stage 1

A Linux application is for PetaLinux a component, so it handles everything to create it.

As it is a nice tool, it will provide us a simple "hello world" template in C.

We will go through the process of generating a Linux application with PetaLinux, using this example application. Then we will go to our own test application.

So, first step, create the application using the C template from PetaLinux. Use the following command :

Oups ! Its seems that PetaLinux is quite sensible to the name syntax !!

Let's try a simple name with this command:

Ok the application template is created.

Stage 2

User application folders are located in the /project-spec/meta-user/recipes-apps/ folder.

Let's see what is generated in this folder.

This folder contains :

- The .bb file, this is a bitbake recipe file which is a Yocto stuff. It is some kind of a makefile that handles what is needed to be included, compiles and generates the output package to be installed.

- A readme file for some explainations,

- And the files folder, this is where are the source files.

The source files folder contains the Makefile and the template source for the "hello World" which is shown below.

Stage 3

Now the application is created, let's compile it.

We will use the PetaLinux compilation comand as follow:

Compilation is Ok, so the tool created all the needed files.


Now that the application is available, we will add it to the rootfs and the regenerate the output image files to be downloaded onto the MiniZed board.

Stage 4

To add an application to the rootfs we have to configure the rootfs !

The previous steps provided everything neccessary to insert the application in the system, so the system will detect the application automatically. We only have to click on it to have it included in the rootfs !

So first, let's open the rootfs configuration menu from PetaLinux with the following command:

The configuration menu opens.

Scroll down to the apps line, press enter.

The list of the available applications is shown. Our testmmap application is in the list, but it is not selected.

Scroll down to the testmmap line and press enter.

Then exit the configuration menu by pressing several times escape until you get the save request pop up.

Select Yes and press enter.

Stage 5

Ok, rootfs' configuration has been modified, now it has to be generated again to include the modifications.

The following command will do everything for us.

It will re generate the modified images and copy them in the output folders, ready to be downloaded !

Fine!

Everything is now ready for testing on the MiniZed board.

Download the images onto the board.

Open the console terminal with Putty and let's check if the system knows our testmmap application.

Just type testmmap to launch the application and check that the Hello World ! is generated.

YES !!

Everything worked fine.

The point here is that we've seen how to handle the generation of an application using PetaLinux.

So now, let's try to write our test application for our custom IP.

Step 2 : Write the test application for our Custom IP using PetaLinux

Stage 1

I will now replace the "Hello World" template application with a test application based on MMAP that I will call testmmap.

I will detail the source code I used in the testmmap.c to blink the LED driven by my custom IP LED_TEST_IP.

So, first, to get access to the custom IP mapping, we've got to open the /dev/mem virtual file, which will provide us an access to the system memory.

Stage 2

Ok, the system's physical memory mapping can be accessed.

To reach it, we will use the mmap system call.

It will map in the user space a page of the system's virtual memory corresponding to the page of the physical memory of our custom IP.

In return to the system call, we will get a pointer to the base address of the virtual memory page. Then we can use the offsets defined for the physical mapping of the registers inside the custom IP.

Stage 3

To end the mmap stuff here, we'll jump over the user function for now and have a look at the end of the application, where the file is closed and the mapped memory is given back.

Stage 4

Ok, back to the user code, in our case let's make the LED blink !

I created a parameter structure that is intended to contain the configuration / status of each instance of the custom IP. In our case it only needs to contain the base address of the custom IP internal mapping.

So, at the beginning of the main I declare the structure instance for my custom IP.

And last step, I initialize it with the virtual address retrieved from the mmap call.

Stage 5

Now everything is ready to play with the custom IP !!

As a test example I will put the custom IP in the blinking mode.

For that, I created the SetLedBlink function, and so I call it to execute the custom IP's registers configuration sequence.

If you look at it, it is a simple address pointer manipulation !

Ok, the testmmap.c is complete.

Now let's compile it and test it on the MiniZed board !!

Step 3 : Run the test application for our Custom IP on the MiniZed board

Stage 1

The first thing to do before launching the compilation is to clear the previous compilation environment.

I don't know why, but if I don't do this step, compilation step will stop in error.....

So use the following command to clean the previous compilation environment for the testmmap application.

Stage 2

Then you can launch the application compilation step.

Use the following command.

Stage 3

Ok, compilation went fine.

Now let's generate the image file including our testmmap application in the rootfs.

Use the following command.

Be aware that it can be quite long to generate the files. For me it took about 12 minutes.

Stage 4

Ok, generation went fine.

Now let's download the files to the MiniZed board.

Use the following command.

Be aware that it can be quite long to download the files using JTAG. For me it took about 5 minutes.

The -v option prints out more information, especially the time estimated for each step.

mtvl@mtvl-VirtualBox:~/fpga/test_proj_petalinux$ petalinux-boot -v --jtag --fpga --kernel
INFO: Use bitstream: "/home/mtvl/fpga/test_proj_petalinux/images/linux/system.bit.
INFO: Please use --fpga --bitstream  to specify a bitstream if you want to use other bitstream.
INFO: Append dtb - /home/mtvl/fpga/test_proj_petalinux/images/linux/system.dtb and other options to boot zImage
XSDB Script:
INFO: Launching XSDB for file download and boot.
INFO: This may take a few minutes, depending on the size of your image.

connect
puts stderr "INFO: Configuring the FPGA..."
puts stderr "INFO: Downloading bitstream: /home/mtvl/fpga/test_proj_petalinux/images/linux/system.bit to the target."
fpga "/home/mtvl/fpga/test_proj_petalinux/images/linux/system.bit"
targets -set -nocase -filter {name =~ "arm*#0"}

source /home/mtvl/fpga/test_proj_petalinux/project-spec/hw-description/ps7_init.tcl; ps7_post_config
catch {stop}
set mctrlval [string trim [lindex [split [mrd 0xF8007080] :] 1]]
puts "mctrlval=$mctrlval"
puts stderr "INFO: Downloading ELF file: /home/mtvl/fpga/test_proj_petalinux/images/linux/zynq_fsbl.elf to the target."
dow "/home/mtvl/fpga/test_proj_petalinux/images/linux/zynq_fsbl.elf"
after 2000
con
after 3000; stop
targets -set -nocase -filter {name =~ "arm*#0"}
puts stderr "INFO: Downloading ELF file: /home/mtvl/fpga/test_proj_petalinux/images/linux/u-boot.elf to the target."
dow "/home/mtvl/fpga/test_proj_petalinux/images/linux/u-boot.elf"
after 2000
con
after 2000; stop
targets -set -nocase -filter {name =~ "arm*#0"}

rst -processor; after 2000
puts stderr "INFO: Loading image: /home/mtvl/fpga/test_proj_petalinux/images/linux/system.dtb at 0x08008000"
dow -data "/home/mtvl/fpga/test_proj_petalinux/images/linux/system.dtb" 0x08008000
after 2000
rwr r2 0x08008000
targets -set -nocase -filter {name =~ "arm*#0"}
puts stderr "INFO: Loading image: /home/mtvl/fpga/test_proj_petalinux/images/linux/zImage at 0x00008000"
dow -data "/home/mtvl/fpga/test_proj_petalinux/images/linux/zImage" 0x00008000
after 2000
rwr pc 0x00008000
con
after 5000
exit
rlwrap: warning: your $TERM is 'xterm-256color' but rlwrap couldn't find it in the terminfo database. Expect some problems.: Inappropriate ioctl for device
attempting to launch hw_server                                                                                             

****** Xilinx hw_server v2018.3
  **** Build date : Nov 15 2018-19:35:59
    ** Copyright 1986-2018 Xilinx, Inc. All Rights Reserved.

INFO: hw_server application started
INFO: Use Ctrl-C to exit hw_server application

INFO: To connect to this hw_server instance use url: TCP:127.0.0.1:3121

INFO: Configuring the FPGA...
INFO: Downloading bitstream: /home/mtvl/fpga/test_proj_petalinux/images/linux/system.bit to the target.
100%    1MB   1.1MB/s  00:01    
mctrlval=30800100
INFO: Downloading ELF file: /home/mtvl/fpga/test_proj_petalinux/images/linux/zynq_fsbl.elf to the target.
Downloading Program -- /home/mtvl/fpga/test_proj_petalinux/images/linux/zynq_fsbl.elf
 section, .text: 0x00000000 - 0x00009703
 section, .handoff: 0x00009704 - 0x0000974f
 section, .init: 0x00009750 - 0x00009767
 section, .fini: 0x00009768 - 0x0000977f
 section, .rodata: 0x00009780 - 0x00009a27
 section, .data: 0x00009a28 - 0x0000bd1f
 section, .mmu_tbl: 0x0000c000 - 0x0000ffff
 section, .init_array: 0x00010000 - 0x00010003
 section, .fini_array: 0x00010004 - 0x00010007
 section, .rsa_ac: 0x00010008 - 0x0001103f
 section, .bss: 0x00011040 - 0x0001248f
 section, .heap: 0x00012490 - 0x0001448f
 section, .stack: 0xffff0000 - 0xffffd3ff
100%    0MB   0.0MB/s  00:01    
Setting PC to Program Start Address 0x00000000
Successfully downloaded /home/mtvl/fpga/test_proj_petalinux/images/linux/zynq_fsbl.elf
INFO: Downloading ELF file: /home/mtvl/fpga/test_proj_petalinux/images/linux/u-boot.elf to the target.
Downloading Program -- /home/mtvl/fpga/test_proj_petalinux/images/linux/u-boot.elf
 section, .text: 0x00400000 - 0x004370ab
 section, .rodata: 0x004370b0 - 0x004442ef
 section, .hash: 0x004442f0 - 0x00444307
 section, .dtb.init.rodata: 0x00444310 - 0x004478df
 section, .data: 0x004478e0 - 0x00449653
 section, .got.plt: 0x00449654 - 0x0044965f
 section, .u_boot_list: 0x00449660 - 0x0044a41f
 section, .efi_runtime: 0x0044a420 - 0x0044a51f
 section, .efi_runtime_rel: 0x0044a520 - 0x0044a5af
 section, .rel.dyn: 0x0044a5b0 - 0x0045201f
 section, .bss_start: 0x0044a5b0 - 0x0044a5af
 section, .bss: 0x0044a5b0 - 0x0046798b
 section, .bss_end: 0x0046798c - 0x0046798b
100%    0MB   0.0MB/s  00:08    
Setting PC to Program Start Address 0x00400000
Successfully downloaded /home/mtvl/fpga/test_proj_petalinux/images/linux/u-boot.elf
INFO: Loading image: /home/mtvl/fpga/test_proj_petalinux/images/linux/system.dtb at 0x08008000
100%    0MB   0.0MB/s  00:00    
Successfully downloaded /home/mtvl/fpga/test_proj_petalinux/images/linux/system.dtb
INFO: Loading image: /home/mtvl/fpga/test_proj_petalinux/images/linux/zImage at 0x00008000
100%    9MB   0.0MB/s  04:18    
Successfully downloaded /home/mtvl/fpga/test_proj_petalinux/images/linux/zImage

INFO: SOC Silicon version is 3.1.
mtvl@mtvl-VirtualBox:~/fpga/test_proj_petalinux$

Now, just enter the name of the application, here testmmap. This will execute the application.

And the LED blinks !!

So that's it for this post.

Post Conclusion

Now we have :

- Used the comands from the Petalinux tool to generate a template application,
- Used the comands from the Petalinux tool to generate a user application,
- Configured the system to embed the test application in the rootfs,
- Used the MMAP system call in the C source file, to easily access from the user space the hardware resources of our custom IP, and thus, be abble to quickly start writing test code for our custom IP.


We've identified that the whole process from modifing the source code of the application to running it on the board needs the following commands :

petalinux-build -c testmmap -x do_clean
petalinux-build -c testmmap
petalinux-build -x package
petalinux-boot -v --jtag --fpga --kernel

But the main conclusion is that the whole process takes about 20 minutes for an iteration !!!!

So this method cannot be used for the active developments steps where you might need to test many modifications, which would lead to hugh developement time !

This should be reserved for basic operations, in the case where your system has not the network configuration ready.