Microchip Polarfire-SoC Yocto 'Board Support Package' (BSP) is based on OpenEmbedded (OE). The 'Polarfire SoC Yocto BSP' layer is build on top of the RISC-V Architectural layer (meta-riscv) to provide hardware specific features and additional disk images. Using Yocto 'Openembedded' you will build the following:
- RISC-V Toolchain
- Predefined Disk Images
- Bootloader Binaries (FSBL / U-Boot)
- Device Tree Binary (DTB)
- Linux Kernel Images
The complete User Guides for each development platform, containing board and boot instructions, are available for the following supported platforms:
- ICICLE-KIT-ES (Icicle Kit Engineering Sample) (Requires minimum Design Tag 2023.02)
- MPFS-VIDEO-KIT (PolarFire SoC Video Kit)
Before continuing, ensure that the prerequisite packages are present on your system. Please see the Host PC setup for Yocto section for further details.
This needs to be done every time you want a clean setup based on the latest BSP.
$ mkdir yocto-dev && cd yocto-dev
$ repo init -u https://github.com/polarfire-soc/polarfire-soc-yocto-manifests.git -b main -m default.xmlrepo sync
repo rebase. ./meta-polarfire-soc-yocto-bsp/polarfire-soc_yocto_setup.shUsing Yocto bitbake command and setting the MACHINE and image required.
MACHINE=icicle-kit-es bitbake mpfs-dev-cliFor instructions on how to copy the image to the eMMC or SD card refer to the Copy the created Disk Image to a flash device section.
Using Yocto bitbake command and setting the initramfs configuration file (conf/initramfs.conf) and the mpfs-initramfs-image
MACHINE=icicle-kit-es bitbake -R conf/initramfs.conf mpfs-initramfs-imageThe image generated from the command above can be used to boot Linux with a RAM-based root filesystem from the eMMC or SD card.
For instructions on how to copy the image to the eMMC or SD card refer to the Copy the created Disk Image to a flash device section.
The icicle-kit-es target machine provides support for building images suitable for programming to the oficially supported QSPI flash memories. The core-image-minimal-mtdutils generates a Linux image with either a .nand.mtdimg or .nor.mtdimg file extension in the build/tmp-glibc/deploy/images/icicle-kit-es/ directory.
For more information on how to enable QSPI support on PolarFire SoC, please refer to the booting from QSPI documentation.
When building core-image-minimal-mtdutils, images suitable for programming to a Winbond W25N01GV NAND flash memory will be generated by default.
Use the Yocto bitbake command to build the core-image-minimal-mtdutils image:
MACHINE=icicle-kit-es bitbake core-image-minimal-mtdutilsSupported machine target: icicle-kit-es
The created image is a '.nand.mtdimg', and is located in yocto-dev/build/tmp-glibc/deploy/images/<MACHINE>/ directory.
Note: The .nand.mtd image generated by the BSP triggers a "free space fixup" procedure in the kernel the very first time the
file system is mounted. Therefore, the first mount might take additional time to complete.
For instructions on how to transfer the image to the external QSPI flash memory refer to the Copy the created Disk Image to an external QSPI flash memory section.
To generate an image for the Micron MT25QL256 NOR flash memory, use the following setting in the Icicle Kit machine configuration file (conf/machine/icicle-kit-es.conf):
UBOOT_CONFIG = "mpfs_icicle_nor"
Next, use the Yocto bitbake command to build the core-image-minimal-mtdutils image:
MACHINE=icicle-kit-es bitbake core-image-minimal-mtdutilsThe created image is a '.nor.mtdimg', and is located in yocto-dev/build/tmp-glibc/deploy/images/<MACHINE>/ directory.
Supported machine target: icicle-kit-es
For instructions on how to transfer the image to the external QSPI flash memory refer to the Copy the created Disk Image to an external QSPI flash memory section.
Be very careful while picking /dev/sdX device! Look at dmesg, lsblk, GNOME Disks, etc. before and after plugging in your usb flash device/uSD/SD to find a proper device. Double check it to avoid overwriting any of system disks/partitions!
We recommend using the bmaptool utility to program the storage device. bmaptool is a generic tool for creating the block map (bmap) for a file and copying files using this block map. Raw system image files can be flashed a lot faster with bmaptool than with traditional tools, like "dd" or "cp".
The created disk image is a 'wic' file, and is located in yocto-dev/build/tmp-glibc/deploy/images/<MACHINE>/ directory,
- e.g., for mpfs-dev-cli image and machine icicle-kit-es, it will be located in
yocto-dev/build/tmp-glibc/deploy/images/icicle-kit-es/mpfs-dev-cli-icicle-kit-es.wic.
cd yocto-dev/build
bmaptool copy tmp-glibc/deploy/images/icicle-kit-es/mpfs-dev-cli-icicle-kit-es.wic /dev/sdXThe wic image uses a GUID Partition Table (GPT). GPT stores its primary GPT header at the start of the storage device, and a secondary GPT header at the end of the device. The wic creation scripts do not correctly place this secondary GPT header at the current time. To avoid later warnings about the GPT secondary header location, open the device with fdisk at this stage and rewrite the partition table:
fdisk /dev/sdXThis will output something like the following:
Welcome to fdisk (util-linux 2.34).
Changes will remain in memory only, until you decide to write them.
Be careful before using the write command.
GPT PMBR size mismatch (13569937 != 15273599) will be corrected by write.
The backup GPT table is not on the end of the device. This problem will be corrected by write.
Command (m for help):Press w to write the partition table and exit fdisk:
Command (m for help): w
The partition table has been altered.
Calling ioctl() to re-read partition table.
Syncing disks.Before proceeding with the steps shown below, make sure you have followed either the "Using a Winbond W25N01GV NAND flash memory" or "Using a Micron MT25QL256 NOR flash memory" sections in the booting from QSPI documentation.
Connect to UART0 (J11), and power on the board. Settings are 115200 baud, 8 data bits, 1 stop bit, no parity, and no flow control.
Press a key to stop automatic boot. In the HSS console, type qspi to select the QSPI interface and then type usbdmsc to expose the QSPI flash memory device as a block device.
Connect the board to your host PC using J16, located beside the SD card slot.
Once this is complete, on the host PC, use dmesg to check what the drive identifier for the QSPI flash memory device is.
$ dmesg | egrep "sd"The output should contain a line similar to one of the following lines:
[114353.477108] sd 11:0:0:0: [sdX] 65536 2048-byte logical blocks: (134 MB/128 MiB)
[114353.477111] sd 11:0:0:0: [sdX] Write Protect is off
[114353.477471] sd 11:0:0:0: [sdX] Mode Sense: 00 00 00 00sdX is the drive identifier that should be used in the following commands, where X should be replaced with the specific character from the output of the previous command.
Be very careful while picking /dev/sdX device! Look at dmesg, lsblk, GNOME Disks, etc. before and after plugging in your usb flash device/uSD/SD to find a proper device. Double check it to avoid overwriting any of system disks/partitions!
Once sure of the drive identifier, use the following command to copy your Linux image to the external QSPI flash memory device, replacing the X as appropriate:
For flashing a Linux image suitable for a Winbond W25N01GV NAND flash memory:
$ sudo dd if=tmp-glibc/deploy/images/icicle-kit-es/core-image-minimal-mtdutils-icicle-kit-es.nand.mtdimg of=/dev/sdXFor flashing a Linux image suitable for a Micron MT25QL256 NOR flash memory:
$ sudo dd if=tmp-glibc/deploy/images/icicle-kit-es/core-image-minimal-mtdutils-icicle-kit-es.nor.mtdimg of=/dev/sdXWhen the transfer has completed, press CTRL+C in the HSS serial console to return to the HSS console.
Wait for the image transfer to complete. A progress bar will be shown in the HSS serial console.
To boot into Linux, type boot in the HSS console. U-Boot and Linux will use UART1. When Linux boots, log in with the username root. There is no password required.
The MACHINE (board) option can be used to set the target board for which linux is built, and if left blank it will default to MACHINE=icicle-kit-es.
The following table details the available targets:
MACHINE |
Board Name |
|---|---|
MACHINE=icicle-kit-es |
ICICLE-KIT-ES, Icicle Kit engineering samples |
MACHINE=icicle-kit-es-amp |
ICICLE-KIT-ES, Icicle Kit engineering samples in AMP mode |
MACHINE=mpfs-video-kit |
MPFS250-VIDEO-KIT, PolarFire SoC Video Kit |
The icicle-kit-es-amp machine can be used to build the Icicle Kit engineering sample with AMP support. Please see the Asymmetric Multiprocessing (AMP) documentation for further details.
When building for different 'Machines' or want a 'clean' build, we recommend deleting the 'build' directory when switching. This will delete all cache / configurations and downloads.
cd yocto-dev
rm -rf build
The table below summarizes the most common Linux images that can be built using this BSP.
bitbake <image> argument |
Description |
|---|---|
core-image-minimal-dev |
A small console image with some development tools. |
core-image-minimal-mtdutils |
A small image with minimal MTD utilities to interact with QSPI flash devices |
mpfs-dev-cli |
A console image with development tools. |
mpfs-initramfs-image |
A small RAM-based Root Filesystem (initramfs) image |
For more information on available images refer to Yocto reference manual
Login with root account, there is no password set.
With the bitbake environment setup, execute the bitbake command in the following format to build the disk images.
MACHINE=<machine> bitbake <image>Example building the icicle-kit-es machine and the mpfs-dev-cli Linux image
MACHINE=icicle-kit-es bitbake mpfs-dev-cliTo work with individual recipes:
MACHINE=<MACHINE> bitbake <recipe> -c <command>View/Edit the Kernel menuconfig:
MACHINE=<MACHINE> bitbake mpfs-linux -c menuconfigRun the diffconfig command to prepare a configuration fragment. The resulting file fragment.cfg should be copied to meta-polarfire-soc-yocto-bsp/recipes-kernel/linux/files directory: Afterwards the mpfs-linux.bb src_uri should be updated to include the .cfg,
MACHINE=<MACHINE> bitbake mpfs-linux -c diffconfigAvailable BSP recipes:
- hss (Microchip Hart Software Services) payload generator
- u-boot-mpfs (PolarFire SoC U-Boot)
- mpfs-linux (Linux Kernel for PolarFire SoC)
Available commands:
- clean
- configure
- compile
- install
build/tmp-glibc/deploy/images/{MACHINE}
For Example the following is the path for the Icicle-kit-es
build/tmp-glibc/deploy/images/icicle-kit-es
This document assumes you are running on a modern Linux system. The process documented here was tested using Ubuntu 18.04 LTS. It should also work with other Linux distributions if the equivalent prerequisite packages are installed.
The BSP uses the Yocto RISCV Architecture Layer, and the Yocto release Kirkstone (Revision 4.0.5) (Released November 2022).
Make sure to install the repo utility first.
Detailed instructions for various distributions can be found in the "Required Packages for the Build Host" section in the Yocto Project Reference Manual.
**Note: Some extra packages are requried to support the Yocto 4.0.5 Release (codename “kirkstone”) compared to the prior release.**For Ubuntu 18.04 (or newer) install python3-distutils:
sudo apt install python3-distutils
You can install the bmap-tools package using the following command:
sudo apt-get install bmap-tools
Yocto Application Development and Extensible Software Development Kit (sSDK)
Kernel Documentation for v5.12
Yocto Flashing images using bmaptool
This project is licensed under the terms of the MIT license (please see LICENSE file in this directory for further details). By using the PolarFire SoC Yocto BSP layer in this repository, the user agrees to the terms and conditions from the licenses of the packages that are installed into the final image and that are covered by a commercial license. The user also acknowledges that it's their responsibility to make sure they hold the right to use code protected by commercial agreements, whether the commercially protected packages are selected by Microchips' PolarFire SoC BSPs or by them. Finally, the user acknowledges that it's their responsibility to make sure they hold the right to copy, use, modify, and re-distribute the intellectual property offered by this collection of meta-layers.
We sometimes get dependencies not building correctly. During the process do_wic_install payload may not be present.
For example after requesting a complete build:
MACHINE=icicle-kit-es bitbake mpfs-dev-cliIf u-boot or boot.src.uimg or payload.bin is missing, execute the following:
MACHINE=icicle-kit-es bitbake u-boot -c clean
MACHINE=icicle-kit-es bitbake u-boot -c installAnd finally a complete build:
MACHINE=icicle-kit-es bitbake mpfs-dev-cliListen uses inotify by default on Linux to monitor directories for changes. It's not uncommon to encounter a system limit on the number of files you can monitor. For example, Ubuntu Lucid's (64bit) inotify limit is set to 8192.
You can get your current inotify file watch limit by executing:
$ cat /proc/sys/fs/inotify/max_user_watchesWhen this limit is not enough to monitor all files inside a directory, the limit must be increased for Listen to work properly.
Run the following command:
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -pSee Other Dependencies for installation instructions.