Getting Started Tutorial for the ML401 Board
Overview
This tutorial will provide an end-to-end guide to developing an embedded system solution using PetaLinux based on the ML401 development board. The topics addressed will include:
- Installation of PetaLinux
- Configuring PetaLinux for the target platform
- Building the target platform hardware reference design projects
- Configuring the system configuration parameters for the target platform
- Building of the bootloader, kernel and ramdisk images for the target platform
- Booting the target platform with the newly built images
- Configuring the target platform to automatic boot and as a complete re-bootable system.
The objective of this document is to provide a tutorial based guide to allow the user to become familiar with using PetaLinux for the development of their embedded system solution.
This document only cover the areas of development that is specific to using PetaLinux on the ML401, other supplementary documents maybe required. For more specific coverage of PetaLinux, refer to the PetaLinux User Guide.
System Setup
Install PetaLinux Environment
Install and setup the PetaLinux environment as per the Installation Procedures provided in the PetaLinux Installation Guide.
Run PetaLinux Setup Script
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.
Setting Up Hardware
This section outline the procedures for setting up the ML401 development board.
External Connectors
Connect the serial cable, RJ45 network cable, JTAG/Parallel cable and power cable to the ML401 board as per the ML401 User Guide.
Dip Switch Selector
Set the Selector switch SW12 to "SYSACE".
CFG Addr and Mode Dip Switch
Set the Configuration Address and Mode dip switch to JTAG mode. Set the dip switch as per the following table.
| Switch No | Value |
| SW1 | 0 |
| SW2 | 0 |
| SW3 | 0 |
| SW4 | 1 |
| SW5 | 0 |
| SW6 | 1 |
Building Reference Design
This section detail the steps required to configure and build the ML401 reference design.
PetaLinux also include pre-built images for the ML401 reference design. This allows the user to bootup the system without going through the manual build process as per outlined in this section. Refer to the Working with Pre-built Designs Documentation for more information.
Select Vendor & Platform
Follow the steps to select the Xilinx's ML401 platform in the PetaLinux build tree.
Go into the petalinux-dist directory.
$ cd $PETALINUX/software/petalinux-dist
Run make menuconfig to select the vendor and platform.
$ make menuconfig
Select the vendor and platform as per the below example.
This step will select the ML401 board as the current target platform to build for in PetaLinux.
┌─────────────────────── Vendor/Product 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 │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ --- Select the Vendor you wish to target │ │ │ │ (Xilinx) Vendor │ │ │ │ --- Select the Product you wish to target │ │ │ │ (ML401) Xilinx Products │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────────────────┤ │ <Select> < Exit > < Help > │ └─────────────────────────────────────────────────────────────────────────┘
Exit the Vendor/Product Selection submenu.
Select Kernel Version
Select the "Kernel/Library/Defaults Selection" menu.
Select the "Kernel Version" submenu as per the below example.
┌─────────────────── 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 > │ └─────────────────────────────────────────────────────────────────────────┘
Select version 2.4 or 2.6 kernel support.
┌────────────────────────── Kernel Version ──────────────────────────
│ Use the arrow keys to navigate this window or press the hotkey of │
│ the item you wish to select followed by the <SPACE BAR>. Press │
│ <?> for additional information about this option. │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ ( ) linux-2.4.x │ │
│ │ (X) linux-2.6.x │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────┤
│ <Select> < Help > │
└────────────────────────────────────────────────────────────────────┘
Save Configurations
Save and Exit the menuconfig.
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 if certain configuration needs to be included. The user can simply press "Enter" to all the prompt.
The initial configuration used for the 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.
Build the Hardware Project
Follow the steps to build the ML401 hardware project.
Note this example assumes that the Xilinx EDK/ISE 9.1 tools are installed. Use the appropriate reference design for your environment.
Go into the Xilinx-ML401-uclinux-ref-edk91 directory.
$ cd $PETALINUX/hardware/reference-designs/Xilinx-ML401-uclinux-ref-edk91
Generate the reference design build Makefiles.
This step will generate the required make files to build the hardware project.
$ xps -nw system.xmp % save make % exit
Build the configuration bitstreams.
This procedure will build the configuration bitstream of the hardware project, which will be used to download into the target FPGA device.
This procedure will take a while to complete.
$ make -f system.make bits
Check that the hardware build completed successfully.
If the hardware build failed. Resolve the problem and re-run step 3.
Build the project libraries and BSP.
This step will build the software libraries that are required to support the selected hardware platform.
$ make -f system.make libs
Build the first stage bootloader.
PetaLinux includes a 2-phase bootloader solution, refer to the PetaLinux Bootloader Solution Chapter of the User Guide for more information. This step will make the first stage bootloader.
$ make -f system.make program
Initialised the BRAM.
This step will update the bitstream with the BRAM initialisation information to allow the processor to start execution upon startup.
$ make -f system.make init_bram
For more information on Xilinx's Make commond set, refer to the Command Line Mode Chapter of the Embedded System Tools Guide.
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/reference_designs/Xilinx-ML401-uclinux-ref-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.
Configure the Linux Kernel
This reference design contains pre-configured kernel configurations. Hence, this step is not required and will be skipped.
Configure the Vendor Settings
PetaLinux provides a vendor specific configuration menu that can be set using the 'menuconfig' tool. The following example outline the steps to set the appropriate vendor specific settings.
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. <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 > │ └─────────────────────────────────────────────────────────────────────────┘
Save and exit the main menu
Do you wish to save your new kernel configuration?
< (Yes) > < No >
Under the Vendor/User Settings menu, select the System Settings submenu.
┌──────────────────────────────── Main Menu ────────────────────────────────┐ │ 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 │ │ ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ System Settings ---> │ │ │ │ Core Applications ---> │ │ │ │ Library Configuration ---> │ │ │ │ Flash Tools ---> │ │ │ │ Filesystem Applications ---> │ │ │ │ Network Applications ---> │ │ │ │ Miscellaneous Applications ---> │ │ │ │ BusyBox ---> │ │ │ │ Tinylogin ---> │ │ │ │ MicroWindows ---> │ │ │ │ Games ---> │ │ │ └───────────────┴(+)────────────────────────────────────────────────────┘ │ ├───────────────────────────────────────────────────────────────────────────┤ │ <Select> < Exit > < Help > │ └───────────────────────────────────────────────────────────────────────────┘
Update the Network Address configuration including the MAC address of the device to reflect your development network and enable the other options as per the below example.
┌────────────────────────────── System Settings ───────────────────────────────┐ │ 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 │ │ ┌──────────────────────────────────────────────────────────────────────────┐ │ │ │ Network Addresses ---> │ │ │ │ Default host name: "uclinux" │ │ │ │ Default root password: "root" │ │ │ │ (CRAMFS) Root filesystem type │ │ │ │ [*] Copy final image to tftpboot │ │ │ │ [*] Build u-boot │ │ │ │ Flash Partition Table ---> │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └──────────────────────────────────────────────────────────────────────────┘ │ ├──────────────────────────────────────────────────────────────────────────────┤ │ <Select> < Exit > < Help > │
Refer to the System Settings Configuration Menu Section of the User Guide for more information on the menu options.
Save and exit the configuration.
Do you wish to save your new kernel configuration?
< (Yes) > < No >
Build the Root Filesystem and Kernel Image
In the $PETALINUX/software/petalinux-dist directory execute the following commands to build the images.
Build the project dependencies
For 2.6 kernel there is no need to explicitly build the project dependencies.
For 2.4 kernel use the following command to build the project dependencies.
$ yes "" | make oldconfig dep
Build the Images
This step may take a while to complete.
$ make all
Check that the build complete successfully.
If the build failed, resolve the problem and repeat the previous step.
Output images
The output images will be in the following directories.
$PETALINUX/software/petalinux-dist/images or /tftpboot
Boot the ML401 Board
This section describes the steps to boot up the ML401 board with the newly built images.
Starting Kermit (Serial Console Program)
Start the kermit 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 the following instructions.
Setup the ML401 board
Setup the ML401 development board for bitstream download as per the ML401 User Guide.
Switch on power to the board.
Download the hardware bitstreams
On a different console as the kermit terminal, change into the Xilinx-ML401-uclinux-ref-edk91 directory and type the following command.
$ cd $PETALINUX/hardware/reference-designs/Xilinx-ML401-uclinux-ref-edk91 $ make -f system.make download
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.
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.
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, substitude 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.
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.
At this point of the tutorial the complete development cycle of using PetaLinux is shown. The next section will include procedures to setup the ML401 development board to be a auto-bootable embedded system.
U-Boot Board Configuration
NOTE: This section will erase the information stored in the on-board Flash device. Do not continue with this section if you don't want information in your Flash device to be erased or over-written. Xilinx provides factory default Flash images for the ML401 board on their website, this can be used to restore the original image on the Flash device if required.
This section will provide the steps to configure the ML401 development board to be an auto-bootable embedded system. With all the required bootloader and kernel images stored into the on-board Flash device. This is often required for most market ready embedded system based product.
The platform configuration procedures are simplified and automated by the U-Boot platform configuration script generated by PetaLinux. This script is automatically generated for any platform that is included into PetaLinux.
The script contains all the necessary system and platform configuration information such as the on-board peripherals OPB address maps, Flash partition table information, ethernet MAC address, IP address and Server IP address and location at which to install the bootloader and kernel images, to allow U-Boot to automatically configure the target platform. In this case the ML401 development board.
Refer to the Customizing U-Boot Section in the User Guide for more information on the U-Boot Configuration.
Below listed is a brief description of the steps taken as part of the configuration process:
- Setup U-Boot Environment Variables
- Setup Ethernet Connection
- Save U-Boot ENV to FLASH
NOTE: If a U-Boot environment exist on the Flash device, ensure that the environment variable "ethaddr" is unset/erased before proceeding with the following section. This is required as the "ethaddr" variable is locked within U-Boot's environment and cannot be reset at run time. Refer to the "Updating Ethernet MAC Address in U-Boot" Chapter of the User Guide for more information on erasing this variable.
Download the Configuration script (ub.config.img)
On the kermit window, type the following command.
U-Boot> loadb 0x10000000 ## Ready for binary (kermit) download to 0x10000000 at 115200 bps...
Note: The 0x10000000 is the address in SDRAM that can be used to temporary hold the configuration script image. This value is specific to your hardware SDRAM memory mappings and only needs to change if you are not using the ML401 reference design provided by PetaLinux. If you are not sure what to use, use the "clobstart" value in the ub.config file in the following directory.
$PETALINUX/software/petalinux-dist/u-boot/board/petalogix/microblaze-auto/ub.config
Send ub.config.img script via Kermit
On the Kermit window, hold down the "Control" and forward-slash ("\") keys simultaneously, then press "c" to activate the kermit prompt. Note this is different from the common "Control-C" key combination.
Ctrl\c
The following message or similar should appear on your console.
(Back at bennyc.itee.uq.edu.au) ---------------------------------------------------- (/usr/local/petalogix/projects/fs-boot/) C-Kermit>
Send the ub.config.img file. Execute the following command exactly.
(/usr/local/petalogix/projects/fs-boot/) C-Kermit> send /bin /tftpboot/ub.config.img
The above command will start transmitting the ub.config.img file. The transmission is comleted when the C-Kermit> prompt returns to the console.
Return to the U-Boot prompt
Type the following command to return to the U-Boot command prompt.
(/usr/local/petalogix/projects/fs-boot/) C-Kermit> connect
The following message or similar should apprear on the terminal window.
(/usr/local/petalogix/projects/fs-boot/) C-Kermit>connect Connecting to /dev/ttyS0, speed 115200 Escape character: Ctrl-\ (ASCII 28, FS): enabled Type the escape character followed by C to get back, or followed by ? to see other options. ---------------------------------------------------- ## Total Size = 0x00000512 = 1298 Bytes ## Start Addr = 0x10000000 U-Boot>
Run the ub.config.img script
To run the script issue the following command on the U-Boot prompt.
U-Boot> autoscr $(fileaddr)
Upon completion the following message or similar shall appear on the terminal window.
U-Boot> autoscr $(fileaddr) ## Executing script at 10000000 PetaLogix MicroBlaze-Auto Board Configuration --------------------------------------------- Network Configuration: MTD Configuration: Clobber DRAM Configuration: Bootloader Configuration: Kernel Configuration: Boot Configuration: Saving Configurations... Saving Environment to Flash... Un-Protected 1 sectors Erasing Flash... . done Erased 1 sectors Writing to Flash... done Configuration Completed U-Boot>
Download the U-Boot and Kernel Image into Flash
On the U-Boot prompt issue the following commands exactly as per the example.
Download the U-Boot binary image.
U-Boot> tftp $(clobstart) u-boot-s.bin
Unlock, erase and program the U-Boot image into the boot partition in Flash.
U-Boot> protect off $(bootstart) +$(bootsize) U-Boot> erase $(bootstart) +$(bootsize) U-Boot> cp.b $(clobstart) $(bootstart) $(filesize)
Download the kernel image.
U-Boot> tftp $(clobstart) image.ub
Un-protect, erase and program the Kernel image into the image partition in Flash.
This step will attempt to program the kernel image into the Flash device, depending on the Flash device used this step may take a while to complete. Note that the U-Boot cp command do not provide status information for the copy process.
U-Boot> protect off $(kernstart) +$(kernsize) U-Boot> erase $(kernstart) +$(kernsize) U-Boot> cp.b $(fileaddr) $(kernstart) $(filesize)
Note the above steps can also be automated, refer to the U-Boot Manual for more information on generating script files.
Auto-Boot the ML401 Embedded System
At this stage the ML401 board has been fully configured to become a auto-bootable embedded system. This section will describes the steps to initiate an automatic boot up of the ML401 board.
Download the hardware bitstreams.
$ make -f system.make download
This should see the ML401 embedded system progress through the booting of all its components to the final Linux kernel image boot. Boot messages will appear on the kermit window.
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 www.petalogix.com.
