PetaLinux Platform From Scratch

The goal of tutorial is to create a new PetaLinux ready MicroBlaze design from scratch and building a PetaLinux kernel image. This documentation uses ML401 development board as example, but is broadly applicable to any BSB-supported development board.

PetaLinux on MicroBlaze Hardware Platform Requirements
The minimum requirements to build a PetaLinux ready hardware platform are

MicroBlaze soft core processor
Interrupt controller
Standard input and output devices
External memory controller
ROM – not volatile data (optional ) such as Flash memory
RAM – accessible data section such as home dir, an example of this is DDR-SDRAM
If you wish to use XMD to download the PetaLinux solution images, you need to have Microprocessor Debug Module enabled to use of JTAG for downloading uClinux into the board. The download link can be either use FSL (allows faster download speed) or debug interface via OPB bus.

Note: Without a Flash memory device, you are required to download the kernel image every time you power up the hardware.

Hardware Overview
The hardware platform consist of followings

MicroBlaze with I/D Cache
8K of BRAM – used for First Stage Bootloader
Interrupt Controller
EMC for Flash
Ethernet – Networking support
UART – standard input/output devices
MDM – used for debugging
Certain core and software parameters must be set correctly in order to build a successful MicroBlaze-PetaLinux hardware design.

This section provides a step by step guide to setting up the PetaLinux environment and a PetaLinux ready hardware design on ML401 development board.

System Setup
This section provides a step by step guide to setting up the PetaLinux environment and the ML401 development board.

System Requirements
It is expected that PetaLinux development will be performed on a “workstation-class” PC. Minimum recommended specifications are:

PENTIUM4 2GHz CPU clock or equivalent
1 Gbyte RAM
5 Gbyte of free HDD space
Smaller memory, or slower CPUs can be used, however time to build a complete PetaLinux system will be negatively impacted.

The following external peripheral support is also required on the host machine.

A serial port (or USB-serial dongle) for terminal display
A Network connection between development board and host computer
A Xilinx-supported JTAG configuration solution (only one of the following is required need?)
A spare serial port for Xilinx Platform Cable III
A parallel port for Xilinx Platform Cable IV
A spare usb port for Xilinx USB Platform Cable IV
Environment Setup
Host Machine
The following must be installed on the development machine.

Xilinx EDK/ISE tools with the latest service packs
TFTP server service
RedHat Enterprise Linux 3 and clones – VMWare / CoLinux? OK
Note: For installing Xilinx’s EDK 8.1 and ISE 8.1 tools with latest service packs, follow the instructions as per provided in the Xilinx’s EDK8.1 Getting Started Guide.

Install PetaLinux
Refer to the PetaLinux Installation Guide for details.

Run PetaLinux Setup Script
Before using PetaLinux, it is required to run the or settings.csh script to set up the appropriate environment variables. This sets up the path and the PETALINUX variable, so the build system knows where everything is located.

$ cd petalinux
$ source ./
Note use the appropriate script for your shell environment.

Adding your Custom Platform to PetaLinux
There are 2 main tasks when it comes to adding a new platform support into PetaLinux. First is to create a new vendor / platform variant in the PetaLinux build framework and the other is to build a system design for your custom platform into PetaLinux. This section will discuss howto add a new platform support into PetaLinux.

Create a New Vendor Platform Variant
Using petalinux-new-platform Script
PetaLinux provides a platform creation script to allow users to easily create a new vendor platform variant in PetaLinux. Refer to the PetaLinux Tools Chapter of the User Guide for more information on this script.

Use the ‘petalinux-new-platform’ script to create a new vendor and platform combination for your target system.

$ cd $PETALINUX/software/petalinux-dist
$ petalinux-new-platform -v MyVendorName -p MyPlatformName -k 2.6
New platform for MyVendorName MyPlatformName successfully created
The above example will create a new platform “MyPlatformName” under the new vendor “MyVendorName” for the 2.6 kernel. Substitute these values as per appropriate.

The petalinux-remove-platform script can be used to remove any wrongly created platform.

Select your Vendor & Platform
Now that the software and hardware components of the project has been added to PetaLinux. The next step is to select your vendor and platform as the current build target, this allows the user to edit and subsequently save the settings configured for this platform.

Use the menuconfig tool to select your vendor and platform variant from the Vendor/Product Selection menu. The menuconfig can be started from the petalinux-dist directory.

$ cd $PETALINUX/software/petalinux-dist
$ make menuconfig
The user should see the Vendor/Product Selection menu similar to the example give below.

[Vendor/Product Selection]→
— Select the Vendor you wish to target
(MyVendorName) Vendor
— Select the Product you wish to target
(MyPlatformName) MyVendorName Products
Save and exit from the configuration session.

Do you wish to save your new kernel configuration?
< (Yes) > < No >
As this is the first time this vendor and platform is selected, the kernel configuration tool may prompt the user for answers to whether certain configuration needs to be included. At this stage, the user can simply press “Enter” to all the prompt.

The initial configuration used for your new platform is a default configuration. This default configuration provide the user with a baseline to start configuring their platform, so as to shorten the configuration process.

Note that the default hardware configurations included for your platform is not correct, these values will be automatically updated by PetaLinux AutoConfig framework once the hardware project is built. The user can ignore them at this stage of the migration.

Create a Hardware Design Project Directory
1. Create a new directory in petalinux/hardware/user-platforms/XX-YY, Name should reflect vendor, board, and EDK version e.g. Xilinx-Spartan3E500-RevC-edk91 or or similar

$ cd $PETALINUX/hardware/user-platforms/
$ mkdir Customer-Project-demo-edk91
Note: Make sure that none of the directories in your directory path have spaces in them. For example, if you create a folder call “my demo” you will end up with an XST 426 error when you finally get to the generate netlist section.

2. Copy the edk_user_repository/bsp into /bsp in the project folder Create a symbolic link for Xilinx EDK tools to be able to access the PetaLinux BSP files.

$ cd $PETALINUX/hardware/user-platforms/Customer-Project-demo-edk91
$ ln -s ../../edk_user_repository edk_user_repository
Create A Base System
This Chapter provides a step by step procedure to create a simple PetaLinux ready hardware system using Xilinx Platform Studio. This involves configurating system hardware and software configurations.

Create A Base System Hardware Design
This section intended to serve as a step by step procedure to generate a basic hardware design using XPS – Base System Builder (BSB).

Using Base System Builder (BSB)
Go to $PETALINUX/hardware/user-platforms/Customer-Project-demo-edk91 directory. Start XPS by entering the command “xps” in the shell console

$ cd $PETALINUX/hardware/user-platforms/Customer-Project-demo-edk91
$ xps
Using Base System Builder
Use Base System Builder Wizard to create a new design project. Choose a directory on your hard drive where the project will reside. Choose browse to change the directory( “$PETALINUX/hardware/user-platforms/Customer-Project-demo-edk91/” is used for this instance).

Board select & Processor configuration
During board select & processor configuration, using the following attributes.

Attribute Value
Board Select
Vendor Xilinx*
Board Virtex 4 ML401 Evaluation Platform*
Version 1*
Processor Configuration
Reference Clock Frequency 100.00 MHz*
Processor-Bus Clock Frequency 66.67 MHz*
Reset Polarity Active LOW*
On-chip H/W debug module Enable
Local Memory 8K
Cache Enable Cache link**
Cached Memory DDR_SDRAM_64x32*
Make sure Processor-Bus Clock Frequency is greater/equal than/to the minimum operating frequency for DDR memory
* indicates development board dependants.
** Prefered.
Adding Periperals
Enable following periperals and add OPB Timer to the processor system and .

Attribute Value
RS232 Uart
Device Enable
Baudrate 115200
Interrupt Enable
Flash 2Mx32#
Device Enable
Device Enable
Ethernet MAC
Device Enable
DMA mode Simple DMA
Interrupt Enable
Device Enable
One timer present Enable
Bit Width 32
Interrupt Enable
# Development board dependants.

Processor Cache Setup
Configurating Instruction and Data cahce, suing following attributes:

Attribute Value
Dcache 8k
ICache 8k
Dcache from DDR_SDRAM_64MBx32#
Icache from DDR_SDRAM_64MBx32#
# Development board dependants.

Stand Input & Output and Test Application
Enable stand input & output and Test Application.

Attribute Value
STDIN RS232_Uart
Memory test Optional
Peripheral selftest Optional
Addding Hardware Platform Settting Without FSL
This scetion describes the steps to configurating debug module interrupt and connect to interrupt controller.

Attribute Value
Enable the UART Interface on OPB Disable
Interrtup Enable
Ensure the H/W version of opb_mdm is “2.01.a” (This step is only required for for Virtex 4-LX25 (XC4LX25) ES devices, please refer to Xilinx Answer Database).
Change the filter to “Bus Interface”
Double click on “debug_moudle” instance to edit its property.
Untick “Enable the UART Interface on OPB”.
Press “OK” to finish.
Change the filter to “Ports”, Expand debug_module’s tree
Enable Interrupt for debug_module by change it’s interrupt Net to “debug_module_interrupt”
Expand opb_intc_0’s tree and double click on Intr’s Net
Add debug_module_interrupt to Interrupt Controller, you can change the interrupt priority order if you wish.
Enabling FSL support (Optional)
This section describes the steps to enable a unidirectional Fast Simplex Link(FSL) to a MicroBlaze system for high speed download.If you don’t wish to use FSL as fast download link, please skip this section.

Change the filter to “Bus Connections” and expand debug_module’s tree
Add a “New Connection” to MFSL0
Click on “fsl_v20_0” and rename it to “fdlink” and you should see debug_module’s MFSL0 is change to “fdlink” as well.
Double Click on “debug_module” instance.
Tick “Enable Fast Download Write Port”.
Click “OK” to save setting.
Double click on “fdlink” instance.
Change “External Reset Active High” to ‘0’ .
Double click on “fdlink” instance.
Double click on “microblaze_0” instance and click on “Bus Interfaces” tab.
Change the Number of FSL links to ‘1’.
Click “OK” to continue.
Select “fdlink” as bus connection for “SFSL0”
Click on the “Ports” filter
In the fdlink section, add FSL_Clk port and change the FSL_Clk Net Name to “sys_clk_s”.
Add SYS_Rst port and change the SYS_Rst Net Name to “sys_rst_s”.
Inclduing PetaLinux BSP
This section decribes the methods to include the ModuleSearchPath variable in the system.xmp file. This will tell the Xilinx EDK tools where to locate the PetaLinux BSP files.

Attribute Value
Device and Repository
Periperheral Respository ./Customer-Project-demo-edk91/edk_user_repository
Click on Project menu -> Project Options, a Project Options dialog box is displayed.
In the Device and Repository tab, Set the Periperheral Respository to ./Customer-Project-demo-edk91/edk_user_repository
Click OK to accept the change.
Alternative way, update the “system.xmp” file to include the “ModuleSearchPath: edk_user_repository/” string. Refer to the example below.

XmpVersion: 9.1.01
IntStyle: default
ModuleSearchPath: edk_user_repository/
MHS File: system.mhs
MSS File: system.mss
NPL File: projnav/system.ise
Architecture: virtex4
Adding FS-Boot Bootloader
PetaLinux includes a 2-phase bootloader solution, refer to the !PetaLinux Bootloader Solutions Chapter of the User Guide for more information, this section will add the first stage bootloader to your project.

Select the Applications tab and double click “Add Software Application Project” to add a new software project.
An Add software Application Project box is displayed. Name the project “FS-Boot” and click OK.
Attribute Value
Project Name fs-boot
Processor microblaze_0
Right-click Sources under Project: FS-Boot and select Add Existing Files…
Browse to the $PETALINUX/hardware/fs-boot/ folder and select the fs-boot.c, srec.c and time.c files
Right-click Header under Project: FS-Boot and select Add Existing Files…
Browse to the $PETALINUX/hardware/fs-boot/ folder and select the fs-boot.h, srec.h and time.h files
Attribute Value
Source File fs-boot.c
Source File srec.c
Source File time.c
Header File fs-boot.h
Header File srec.h
Header File time.h
Right-click Project: FS-Boot and select “Set Compiler Options…”, a Set Compiler Options dialog is displayed
Within Environment tabl, ensure the Application Mode is set to Executable
Tick Use default Linker Script
Change the Stack Size to 1K
Click on “Debug and Optiomization” tab
Change the Optimization Level to “Size Optimized(-Os)
Click on “Advance” tab
Within “Other Compiler Options to Append” box, Add “-Wall” options to be appended to the compiler command
Click “OK” to save settings.
Attribute Value
Application Mode executable
Output ELF file default value
Linker Script Use default Linker Script
Stack Size 1K
Debug and Optimisation
Optimization Level Size Optimized (-Os)
Other Compiler Options to Append -Wall
Right-click on other projects and select Make Project Inactive
Repeat step 16 for all the project except Project: FS-Boot
Right-click “Project: FS-Boot” and select “Mark Initialize to BRAMs”
Alternative way to add FS-Boot Bootloader – Update the system.xmp File
To add FS-Boot Bootloader by including the following code in system.xmp file

SwProj: fs-boot
Processor: microblaze_0
Executable: fs-boot/executable.elf
Source: ../../fs-boot/fs-boot.c
Source: ../../fs-boot/srec.c
Source: ../../fs-boot/time.c
Header: ../../fs-boot/fs-boot.h
Header: ../../fs-boot/srec.h
Header: ../../fs-boot/time.h
InitBram: 1
Active: 1
CompilerOptLevel: 4
GlobPtrOpt: 0
DebugSym: 1
ProfileFlag: 0
StackSize: 1k
ProgCCFlags: -Wall
Ensure that no other application has set the option ‘Mark to Initialize BRAMs’ enabled, else the init_bram make procedure will fail.

System Software Settings
This section describes the basic PetaLinux software configurations within XPS.

Configuring system software settings with following attributes:

Attribute Value
Processor, Driver Parameters and Interrupt Handlers
xmdstub_peripheral none
OS & Library Settings petalinux
PetaLinux version 1.00.b
OS and Library
lmb_memory dlmb_cntlr
main_memory DDR_SDRAM_64MBx32
main_memory_bank 0
flash_memory FLASH_2MBx32
flash_memory_bank 0
stdout RS232_Uart
stdin RS232_Uart
In Xilinx Platform Studio, select “Project” tab and click on “Software Platform settings” submenu. A Software Platform Settings dialog is displayed.
Select “Processor, Driver Parameters and Interrupt Handlers” tab, change the xmdstub_peripheral to “none”.
Change CORE_CLOCK_FREQUENCY to ‘66666667’ (Processor clock frequency).
In the “OS & Library Settings” box, change the OS to “petalinux” and the OS version to “1.00.b”.
Click on “OS and Library” tab.
Change lmb_memory to “dlmb_cntlr”.
Change main_memory to “DDR_SDRAM_64MBx32”.
Change flash_memory to “FLASH_2MBx32”.
Change main_memory_bank and flash_memory_bank to ‘0’.
Set stdout and stdin to “RS232_Uart”.
Leave Target_DIR blank.
Press “OK” to finish.
Select the “Software” menu and “Generate Libraries and BSP” submenu.
Select the “Hardware” menu and “Generate Netlist” submenu, this will take a while.
Select the “Hardware” menu and “Generate Bitstream” submenu, this will take a while.
Hardware Testing
This section describes the steps to boot up the ML401 board with the newly built images.

Start the kermit program.
$ kermit -c
Once Generate Bitstream is finished, select the “Device Configuration” menu and “Download Bitstream” submenu, to download the bitstream into development board.
The DONE pin (LED) goes high when bitstream download is completed.
The following output should displayed in kermit.
FS-BOOT First Stage Bootloader (c) 2006 PetaLogix
FS-BOOT: System initialisation completed.
FS-BOOT: Booting from FLASH. Press ‘s’ for image download.
On the Kermit window, hold down the “Control” and forward-slash (“\”) keys simultaneously, then press “c” to activate the kermit prompt. Tyep “exit” in kermit prompt to exit Kermit
PetaLinux Configration
Setup AutoConfig
The AutoConfig technology allows automated synchronisation of hardware and software system configurations. To enable the AutoConfig framework within the PetaLinux environment, the following instruction needs to be executed to set up the link between the hardware and software project.

In the $PETALINUX/hardware/user-platforms/Customer-Project-demo-edk91 directory, execute the following commands.

$ petalinux-copy-autoconfig
This command will automatically detect your vendor and platform selection on your current PetaLinux tree and install the hardware AutoConfig files into the appropriate directories.

Platform Configurations
Next the user will have to reconfigure the platform settings of their custom platform into PetaLinux as per what was done previously for the old development environment. This step requires the user to run through the following configuration options.

Start the menuconfig tool
$ cd $PETALINUX/software/petalinux-dist
$ make menuconfig
Select the Vendor/User Settings option.
┌─────────────────── Kernel/Library/Defaults Selection ───────────────────
│ Arrow keys navigate the menu. selects submenus —>. │
│ Highlighted letters are hotkeys. Pressing includes, excludes, │
modularizes features. Press to exit, for Help. │
│ Legend: [*] built-in [ ] excluded module < > module capable │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ (linux-2.6.x) Kernel Version │ │
│ │ (None) Libc Version │ │
│ │ [ ] Default all settings (lose changes) │ │
│ │ [ ] Customize Kernel Settings │ │
│ │ [*] Customize Vendor/User Settings (NEW) │ │
│ │ [ ] Update Default Vendor Settings │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
< Exit > < Help > │
Go back to “Main Menu” and select “General Setup —>”
Within “General Setup” menu, make sure “Networking support” is enabled
Go back to “Main Menu” and select “Processor type and features —>”
Within “Memory Technology Devices (MTD)” menu, select “RAM/ROM/Flash chip drivers —>”
┌──────────────────── Memory Technology Devices (MTD) ────────────────────┐
│ Arrow keys navigate the menu. selects submenus —>. │
│ Highlighted letters are hotkeys. Pressing includes, excludes, │
modularizes features. Press to exit, for Help. │
│ Legend: [*] built-in [ ] excluded module < > module capable │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ <*> Memory Technology Device (MTD) support │ │
│ │ [ ] Debugging │ │
│ │ <*> MTD partitioning support │ │
│ │ < > MTD concatenating support │ │
│ │ < > RedBoot partition table parsing │ │
│ │ < > uCbootstrap partition table parsing │ │
│ │ < > Command line partition table parsing │ │
│ │ — User Modules And Translation Layers │ │
│ │ <*> Direct char device access to MTD devices │ │
│ │ <*> Caching block device access to MTD devices │ │
│ │ < > FTL (Flash Translation Layer) support │ │
│ │ < > NFTL (NAND Flash Translation Layer) support │ │
│ │ < > INFTL (Inverse NAND Flash Translation Layer) support │ │
│ │ RAM/ROM/Flash chip drivers —> │ │
│ │ Mapping drivers for chip access —> │ │
│ │ Self-contained MTD device drivers —> │ │
│ │ NAND Flash Device Drivers —> │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
< Exit > < Help > │
Go back to “Memory Technology Devices (MTD)” menu and select “Mapping drivers for chip access —> ”
Ensure only “CFI Flash device PetaLinux AutoConfig” and “Generic uClinux RAM/ROM filesystem support” are selected
┌──────────────────── Mapping drivers for chip access ────────────────────┐
│ Arrow keys navigate the menu. selects submenus —>. │
│ Highlighted letters are hotkeys. Pressing includes, excludes, │
modularizes features. Press to exit, for Help. │
│ Legend: [*] built-in [ ] excluded module < > module capable │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ <*> CFI Flash device PetaLinux AutoConfig │ │
│ │ < > CFI Flash device in physical memory map │ │
│ │ < > CFI Flash device mapped by Arcturus uCbootstrap │ │
│ │ < > CFI Flash device mapped on SnapGear/SecureEdge │ │
│ │ < > CFI Flash device mapped on SnapGear/GEODE boards │ │
│ │ < > CFI Flash device mapped on SnapGear/SecureEdge (uClinux) │ │
│ │ < > CFI Flash device mapped on Microblaze/mbvanilla (uClinux) │ │
│ │ < > CFI Flash device mapped on MicroBlaze auto-config (uClinux) │ │
│ │ < > CFI Flash device mapped on Microblaze/ML40x (uClinux) │ │
│ │ < > CFI Flash device mapped on Microblaze/SUZAKU (uClinux) │ │
│ │ < > CFI Flash device mapped on Key Technology devices │ │
│ │ < > CFI Flash device mapped on SED SIOS III Core │ │
│ │ <*> Generic uClinux RAM/ROM filesystem support │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
< Exit > < Help > │
Enable “Ethernet (10 or 100Mbit)” and “Xilinx Ethernet driver”
┌──────────────────────── Ethernet (10 or 100Mbit) ───────────────────────┐
│ Arrow keys navigate the menu. selects submenus —>. │
│ Highlighted letters are hotkeys. Pressing includes, excludes, │
modularizes features. Press to exit, for Help. │
│ Legend: [*] built-in [ ] excluded module < > module capable │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ [*] Ethernet (10 or 100Mbit) (NEW) │ │
│ │ <*> Xilinx Ethernet driver (NEW) │ │
│ │ < > Sun LANCE support (NEW) │ │
│ │ < > Sun BigMAC 10/100baseT support (EXPERIMENTAL) (NEW) │ │
│ │ < > Sun QuadEthernet support (NEW) │ │
│ │ [ ] 3COM cards (NEW) │ │
│ │ [ ] Western Digital/SMC cards (NEW) │ │
│ │ [ ] Racal-Interlan (Micom) NI cards (NEW) │ │
│ │ [ ] Pocket and portable adapters (NEW) │ │
│ │ < > CNXT Emac support (NEW) │ │
│ │ [ ] FEC ethernet controller (of ColdFire 5272/5282/5280) (NEW) │ │
│ │ < > CS89x0 support (NEW) │ │
│ │ [ ] uCcs8900 support (NEW) │ │
│ │ < > AX88796 NE2000 compatible chipset (NEW) │ │
│ └─┴(+)────────────────────────────────────────────────────────────────┘ │