Migrating to PetaLinux from an existing uClinux environment
Overview
This document is targeted to users that already have an existing uClinux development environment for their target platform. This guide will provide details on how to migrate your target platform into PetaLinux, including support for first stage and u-boot bootloaders.
This document only cover the topics related to migrating your custom platform to PetaLinux, other supplementary documents maybe required. For more specific coverage of PetaLinux, refer to the PetaLinux User Guide.
Assumptions
This document makes the following assumptions:
- PetaLinux is already installed on a host machine. Refer to the PetaLinux Installation Guide for more information.
- Your custom platform Xilinx EDK hardware projects already exists.
Setup PetaLinux
Before using PetaLinux, it is required to run the settings.sh 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 ./settings.sh
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 import the Xilinx EDK hardware project files for your target platform into PetaLinux. This section will discuss both these topics.
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.
Architecture Specific Platform Changes
In some cases, a platform may include architecture specific changes, these files reside in the arch/microblaze/platform/ directory. Any changes to these files needs to be manually added to the new platform created in the PetaLinux source tree. In most situations, this will not be required.
For example, all architecture specific code for the above platform will be in the following directory.
$PETALINUX/software/petalinux-dist/linux-2.6.x/arch/microblaze/platform/MyVendorName-MyPlatformName
Add your Platform EDK Project
This section will provide procedures to add your custom platform Xilinx EDK project into PetaLinux.
Hardware Project Directory
PetaLinux include a hardware project place-holder directory to house all hardware projects. All hardware projects should reside in the following directory.
$PETALINUX/hardware/user-platforms
Copy your hardware platform project into the $PETALINUX/hardware/user-platforms directory.
$ cp -rf my_hardware_project $PETALINUX/hardware/user-platforms
The above example will copy recursively the my_hardware_project directory into the hardware directory in PetaLinux. The $PETALINUX environment variable will be resolved to the PetaLinux installation directory. The my_hardware_project refers to the directory containing the hardware project to be added.
Using PetaLinux BSP
PetaLinux now provides a new BSP to support the PetaLinux environment. This requires the integrated hardware project to use this BSP. This section outline the steps required to update your hardware project to use the PetaLinux BSP.
Update system.mss File
Update the OS_NAME and OS_VER parameters in the OS section of the "system.mss" file to use 'petalinux' and version '1.00.b'. Refer to the example below.
BEGIN OS PARAMETER OS_NAME = petalinux PARAMETER OS_VER = 1.00.b
Note: In some cases, the designer may also need to manually specify the Main Memory and Flash parameters in the software settings.
Update system.xmp File
The last step is to include the ModuleSearchPath variable in the system.xmp file. This will tell the Xilinx EDK tools where to locate the PetaLinux BSP files.
Update the "system.xmp" file to include the "ModuleSearchPath: ../../edk_user_repository/" string. Refer to the example below.
XmpVersion: 9.1.02 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. This step can be skipped if not required.
Ensure that your hardware project has a minimum of 8K BRAM.
Use the Xilinx Platform Studio tool to add a software application to your hardware project with the following attributes.
| Attribute | Value |
| Project Name | fs-boot |
| Processor | microblaze_0 |
Add the following source and header files to the 'fs-boot' application project. The FS-Boot files are located in the '$PETALINUX/hardware/fs-boot/' directory.
| 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 |
Use the attributes in the following table to set up the compiler options for FS-Boot. Refer to the Setting the Compiler Environment Variables Section of the Xilinx XPS Documentation.
| Attribute | Value |
| Environment | |
| 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) |
| Advance | |
| Other Compiler Options to Append | -Wall |
Set the 'Mark to Initialize BRAMs' option on the FS-Boot project. Ensure that no other application has this option set else the make -f system.make init_bram command will fail.
At this point the FS-Boot bootloader is added to the project. The user can now build the FS-Boot application.
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 DefaultInit: EXECUTABLE InitBram: 1 Active: 1 CompilerOptLevel: 2 GlobPtrOpt: 0 DebugSym: 1 ProfileFlag: 0 AsmOpt: LinkOpt: ProgStart: StackSize: 1k HeapSize: LinkerScript: ProgCCFlags: -Wall
Ensure that no other application has set the option ‘Mark to Initialize BRAMs’ enabled, else the init_bram make procedure will fail.
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.
Build your Hardware Project
After the platform has been selected, the hardware project can be built. This section provides details on doing this in PetaLinux.
The following steps can be used to build the your hardware project.
1. Go into your hardware project directory.
$ cd $PETALINUX/hardware/user-platforms/my_hardware_project
2. Generate the reference design build Makefiles.
$ xps -nw system.xmp % save make % exit
3. Build the configuration bitstreams.
This procedure will take a while to complete.
$ make -f system.make bits
4. Check that the hardware build completed successfully.
If the hardware build failed. Resolve the problem and re-run step 3.
5. Build the project libraries and BSP.
$ make -f system.make libs
6. Build any Application Program.
This step will also make the first stage bootloader if included.
$ make -f system.make program
7. Initialised the BRAM.
$ make -f system.make init_bram
Updating Hardware Settings using AutoConfig
As per mentioned in the earlier section, the default hardware configurations needs to be updated with your actual platform's hardware settings, this section will provide information on how to do this using AutoConfig.
To enable the AutoConfig framework within the PetaLinux environment, the following instruction needs to be executed to set up the link between your hardware and software project.
In your hardware directory, execute the following commands.
$ cd $PETALINUX/hardware/user-platforms/my_hardware_project $ 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 locations.
Adding your 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.
- Kernel/Library/Defaults Selection --->
- Customize Kernel Settings
- Customize Vendor/User Settings
This step is only required once for any new platform added. The user can refer to the System Settings Configuration Menu Section of the User Guide for more information on the System Settings menu options.
Once the configuration is done, the settings need to be saved as the default configuration for this platform. This can be done by selecting the Update Default Vendor Settings option. Save and exit from the configuration session when done.
┌─────────────────── Kernel/Library/Defaults Selection ─────────────────── │ Arrow keys navigate the menu. <Enter> selects submenus --->. │ │ Highlighted letters are hotkeys. Pressing <Y> includes, <N> excludes, │ │ <M> modularizes features. Press <Esc><Esc> to exit, <?> for Help. │ │ Legend: [*] built-in [ ] excluded <M> 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 │ │ │ │ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────────────────┤ │ <Select> < Exit > < Help > │ └─────────────────────────────────────────────────────────────────────────┘
Do you wish to save your new kernel configuration?
< (Yes) > < No >
Building the Root Filesystem and Kernel Image
To start the build process for the newly added platform, in the $PETALINUX/software/petalinux-dist directory execute the following commands to build the images.
1. Build the project dependencies
$ yes "" | make oldconfig dep
2. Build the Images
This step may take a while to complete.
$ make all
3. Check that the build complete successfully.
If the build failed, resolve the problem and repeat step 2.
4. Output images.
The output images will be in the following directories.
$PETALINUX/software/petalinux-dist/images or /tftpboot
For more information on the various output images refer to the Output Images Section of the PetaLinux User Guide.
Boot your Custom Board
The user can use the images generated in the /tftpboot or petalinux-dist/images directory to boot up their platform with their normal boot method.
This section describes the steps to boot up your custom board using the 2-phase boot offered by PetaLinux. This section can be skipped if not required.
Starting Kermit (Serial Console Program)
Kermit is used as the default console program to communicate with the target device. User can refer to the Installation Guide Section? of the PetaLinux User Guide for more information on installing Kermit.
Start the kermit console program.
$ kermit -c
Starting FS-Boot
FS-Boot is the first stage bootloader that is used for bootstrapping the full featured U-Boot into system memory. FS-Boot can be booted using your normal bitstream download process or the following instructions.
1. Board Setup.
Set up the your board for configuration bitstream download.
2. Download the hardware bitstreams.
On a different console as the kermit terminal, change into your hardware project directory and type the following command.
$ make -f system.make download
3. The FS-Boot banner appears.
The following FS-Boot banner or similar should appear on the kermit console when the bitstream download is completed.
================================================= FS-BOOT First Stage Bootloader (c) 2006 PetaLogix ================================================= FS-BOOT: System initialisation completed. FS-BOOT: Booting from FLASH. Press 's' for image download.
Starting U-Boot
4. Start U-Boot SREC image download
Type 's' on the kermit console window to start the serial SREC download of U-Boot binary image. The following FS-BOOT message should appear.
FS-BOOT: Waiting for SREC image....
Note: By default FS-Boot will wait for 3 seconds before it will start the auto boot process. Ensure, that the 's' key is pressed before that.
5. Send the U-Boot SREC image.
On a different console to the kermit window, type the following command to send the file to FS-BOOT.
$ cat /tftpboot/u-boot.srec > /dev/ttyS0
Note: The above example assumes that /dev/ttyS0 is used, substitute the serial device file name as per appropriate.
On the kermit window, you should see the "Spinning wheel" symbol when it is downloading the SREC image.
6. Download completion and booting U-Boot.
FS-Boot will automatically boot the downloaded U-Boot image when download is completed. The following message or similar should appear on the kermit window.
FS-BOOT: Waiting for SREC image....
FS-BOOT: Image download successful.
FS-BOOT: Warning image location differ from default boot location. Image will not boot automatically after POR.
FS-BOOT: Press 'n' to boot old image.
FS-BOOT: Use new image.
FS-BOOT: Booting image...
SDRAM :
U-Boot Start:0x13fc0000
Malloc Start:0x13f60000
Board Info Start:0x13f5ffd0
Boot Parameters Start:0x13f4ffd0
FLASH: 8 MB
ETHERNET: MAC:<NULL>
*** Warning - bad CRC, using default environment
U-Boot>
Note: The warning messages appears as the U-Boot environment is not configured. These warning message will not appear once the U-Boot board configuration is done.
Congratulations, at this point of the tutorial the complete development cycle of using PetaLinux is shown.
Further Support
Please refer to the PetaLinux User Guide for more information.
User questions can also be found on the microblaze-uclinux mailing list.
For technical support, contact PetaLogix at http://www.petalogix.com.
