# PetaLinux Development Guide

## System Requirements

**Target Platform**: Zynq-based embedded systems
**Host Operating System**: Ubuntu Server 20.04 LTS
**Hardware Description**: Vivado-generated .xsa file (for custom hardware implementations)

## Initial Setup and Project Creation

### Environment Initialization

# Source the PetaLinux environment configuration
source <petalinux-installation-path>/settings.sh

### Project Instantiation

# Create a new Zynq-based embedded Linux project
petalinux-create --type project --template zynq --name <project_name>
cd <project_name>

### Importing XSA

petalinux-config --get-hw-description <xsa-path>

### Component Configuration

# Configure Linux kernel parameters
petalinux-config -c kernel

# Configure U-Boot bootloader settings
petalinux-config -c u-boot

# Configure packages and filesystem settings
petalinux-config -c rootfs

## Development Workflow

The PetaLinux development process follows a structured sequence of operations, each serving a specific function in the embedded system development lifecycle:

| Phase | Command | Function |
|-------|---------|----------|
| **Hardware Platform Definition** | Vivado design suite | Establish hardware architecture and generate system description |
| **Project Initialization** | `petalinux-create -t project` | Create project structure and metadata |
| **Hardware Integration** | `petalinux-config --get-hw-description` | Import and parse hardware description files |
| **System-Level Configuration** | `petalinux-config` | Define system parameters and build options |
| **Component Development** | `petalinux-create -t COMPONENT` | Develop custom software components |
| **Bootloader Configuration** | `petalinux-config -c u-boot` | Configure first-stage bootloader parameters |
| **Kernel Configuration** | `petalinux-config -c kernel` | Configure Linux kernel features and drivers |
| **Root Filesystem Configuration** | `petalinux-config -c rootfs` | Define userspace components and packages |
| **System Build** | `petalinux-build` | Compile and link all system components |
| **Deployment Packaging** | `petalinux-package` | Generate deployment-ready images |
| **System Verification** | `petalinux-boot` | Execute boot sequence for validation |
| **Project Migration** | `petalinux-upgrade` | Update existing projects to newer versions |
| **Development Toolchain** | `petalinux-devtool` | Access advanced Yocto development utilities |
| **Debug and Diagnostics** | `petalinux-util` | Utilize debugging and diagnostic tools |

## USB High-Speed Device Tree Configuration

For systems requiring USB high-speed connectivity, the device tree must be properly configured.
`<project_root>/project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi`

/include/ "system-conf.dtsi"
#include <dt-bindings/gpio/gpio.h>

/ {
    model = "BX-71 Development Board";
    
    usb_phy0: phy0@e0002000 {
        compatible = "ulpi-phy";
        #phy-cells = <0>;
        reg = <0xe0002000 0x1000>;
        view-port = <0x0170>;
        drv-vbus;
    };
};

&usb0 {
    dr_mode = "host";
    usb-phy = <&usb_phy0>;
    maximum-speed = "high-speed";
};

This configuration establishes the USB PHY controller and configures the USB interface for high-speed operation in host mode.

## System Build Process

Execute the complete system build from within the project directory:

petalinux-build

## Boot Image Generation

### Primary Boot Image Creation

Navigate to the build artifacts directory and generate the boot image:

cd images/linux/
petalinux-package --boot --fsbl zynq_fsbl.elf --fpga system.bit --u-boot --force

**Critical Note**: This operation must be executed from the `images/linux/` directory to ensure proper file path resolution.

The generated `BOOT.BIN` contains the First Stage Boot Loader (FSBL), FPGA bitstream, and U-Boot bootloader in the appropriate boot sequence.

## SD Card Deployment Configuration

### Boot Partition Setup
The SD card boot partition requires the following files:
- `boot.scr` - U-Boot script for automated boot sequence
- `BOOT.BIN` - Primary boot image containing FSBL, bitstream, and U-Boot
- `image.ub` - FIT (Flattened Image Tree) containing kernel and device tree

### Root Filesystem Deployment
1. Transfer the root filesystem archive to the rootfs partition:

   cp rootfs.tar.gz /media/<rootfs-partition>/

2. Extract the filesystem archive on the target partition:

   cd /media/<rootfs-partition>/
   tar -xzf rootfs.tar.gz

fdt addr 0x100000

3. Remove the archive file

   rm rootfs.tar.gz