Linux Image

Petalinux 2020.2 was used to create the Linux image for the ECM1900. The image is intended to be small and rather minimal, but does contain some helpful tools. An abridged list of tools installed in this image is:

  • Git
  • OpenSSH
  • Lighttpd web server
  • Python3
  • Vim
  • Libgpiod
  • I2C-Tools
  • Ethtool
  • Wpa-Supplicant
  • cpp
  • gcc
  • g++
  • make
  • packagegroup-core-buildessential

Additional tools may be added to the image by importing and modifying the Petalinux project using the provided BSP (Board Support Package) and then regenerating the Linux Image. The provided BSP will load the configuration and source files used to build the provided ecm1900.wic image.

Root File System

We have configured the PetaLinux project, and in turn our provided Linux image, to use an external file system to be located on a EXT4 partition on the SD card. We provide our Linux image in Wic format. Wic simplifies deploying images by including the required boot, rootfs, and related partitions in the image. Our Wic image includes the information within it to partition the SD card correctly. These partitioning commands are contained in the kickstart file (.wks) of the Petalinux Project. The default .wks file is FAT32 with 1 GB and EXT4 with 3 GB. When using this external file system configuration, boot requires all boot images to be located in the FAT32 partition, and the root file system to be mounted on the EXT4 partition.

The resulting behavior is that any modification to the root file system at runtime will persist between power cycles. Any user access, additions, deletions, or modification to the root file system happen on the non-volatile SD card EXT4 partition. This is in stark difference to the default PetaLinux image behavior in which the root file system is loaded into RAM, and any modifications are lost at power cycle. You may modify this behavior by reconfiguring a PetaLinux project imported with our provided BSP. More information regarding root file system behavior can be found at UG1144

Provided Tools and Applications

Baked into the ECM1900 image are the tools and applications located at the following GitHub repository: opalkelly-opensource/ecm1900tools

There you will find a summary of the following provided applications:

  • smartvio-ecm – An application implementing the SYSYGY Standard for the BRK1900. Can also be used to set the individual VCCO power rails on the ECM1900, please see the ‘VIO/VCCO I/0 Bank Associations’ section at Powering the ECM1900.
  • set-clock-ecm1900 – Application used to configure the clock outputs of the Si5341 on the ECM1900.
  • set-clock-brk1900 – Application used to configure the clock outputs of the Si5338 on the BRK1900.

These applications are baked into the ECM1900 image and are located in the /usr/bin/ directory. The clock applications are built to configure the Si5338 (BRK1900) and Si5341 (ECM1900) programmable clock oscillators to our default frequencies specified at BRK1900 Peripherals and Clock Generator respectively. If new frequencies are desired please follow the instructions located in the README at opalkelly-opensource/ecm1900tools.

Start-Up Script

An Opal Kelly initializer script auto runs in the later stages of boot to initialize the power rails and to program the onboard clock oscillator. This installation script is located at the following directory of the root file system of the ECM1900 image:

/etc/init.d/setclk-reboot-init

Si5341 Programmable Clock Oscillator

As it is provided to you, the initializer script will run the provided set-clock-ecm1900 application to configure the Si5341 programmable clock oscillator to the frequencies shown at the Clock Generator page. If you desire frequencies other than the defaults then you may modify our provided Silicon Labs ClockBuilderPro project file with your desired frequencies and rebuild the application using the build tools on the ECM1900’s Linux Image. You’ll substitute out the following header file on the root file system on the ECM1900 image with the newly generated header file from Silicon Labs ClockBuilderPro:

/home/root/tools/set-clock-ecm1900/ECM1900-Si5341-Regs.h
Code language: JavaScript (javascript)

Please ensure that the newly generated header file goes by the name ECM1900-Si5341-Regs.h as set-clock-ecm1900.cpp expects this. You’ll then “make” the application with the provided makefile and place/overwrite the newly compiled application to:

/usr/bin/set-clock-ecm1900
Code language: JavaScript (javascript)

Once these steps are complete, you can reboot your ECM1900 and notice your desired frequencies take effect at startup.

VIO/VCCO Rails

As it is provided to you, the initializer script has commented out commands to set the VIO1 (VCCO_87_88), VIO2 (VCCO_68), VIO3 (VCCO_67), and VIO4 (VCCO_28) power rails. The startup behavior of these rails are by default powered off. To modify this startup behavior, you can use Vim to modify the initializer script located at the following directory of the root file system of the ECM1900 image:

vim /etc/init.d/setclk-reboot-init

Uncomment out the rails of interest and modify their voltage to what is desired. You can read additional comments located in the initializer scrip for information of the acceptable voltages of these rails that are limited by the I/O bank and voltage step-down ICs. An example of such a command is:

syzygy-ecm1900 -s -1 120 /dev/i2c-0

Writing an Image to SD

We provide our Linux image in Wic format. Wic simplifies deploying images by including the required boot, rootfs, and related partitions in the image. Writing the Wic image to the SD card is a low-level operation that usually requires command line usage or specialized applications that are not typically installed in Windows or macOS. This section is intended to be helpful but not necessarily comprehensive.

macOS and Windows

We recommend using Etcher or similar tools. Most of these tools support the Wic format.

Linux

  1. Determine the filesystem name corresponding to your SD card. One way to do this is to use the lsblk command before and after attaching your SD reader. The new filesystem in the listing will correspond to your SD card. It will have a name like “/dev/mmcblk0“.
  2. On the command line, copy the image to the disk using the commands below. This will take a couple minutes or longer.
# replace mmcblk0 in the command below with your SD card device. sudo dd bs=4096 if=sdimage.bin of=/dev/mmcblk0 sudo sync
Code language: PHP (php)

Image Edits and Modifications

If you require modifications to the Linux image you will need to download PetaLinux 2020.2 and import the provided ecm1900.bsp. The BSP will load the configuration and source files used to build the provided ECM1900 image. ecm1900.bsp and the ECM1900 image were built using the following:

  • Ubuntu 18.04.04
  • PetaLinux 2020.2
  • Vivado 2020.2

PetaLinux 2020.2 works only with hardware designs exported from Vivado Design Suite 2020.2. Ubuntu 18.04.4 is the latest supported OS for PetaLinux 2020.2 More information regarding PetaLinux can be found at UG1144(V2020.2)

Instructions to install PetaLinux:

1. Boot up Ubuntu 18.04.04 using whichever method.

2. Run plnx-env-setup.sh with root privileges to install the required packages for PetaLinux 2020.2. This script is located at AR73296.

sudo ./plnx-env-setup.sh

3. PetaLinux tools require bash, change the default system shell to bash with the following command:

sudo dpkg-reconfigure dash

4. Install PetaLinux 2020.2 using the following command to install:

./petalinux-v<petalinux-version>-final-installer.run [- d|--dir <INSTALL_DIR>]
Code language: HTML, XML (xml)

Instructions to build with PetaLinux:

1. Set Up PetaLinux Working Environment with the following command

source <path-to-installed-PetaLinux>/settings.sh
Code language: HTML, XML (xml)

2. To create a new PetaLinux project loaded with ecm1900.bsp use the following command:

petalinux-create -t project -s ecm1900.bsp
Code language: CSS (css)

3. After making the necessary changes then build the project with the following command:

petalinux-build

4. Package up the image for the SD card with the following command:

petalinux-package --wic

5. The generated image will be located in the <plnx-proj-dirctory>/images/linux directory under the name “petalinux-sdimage.wic”. You can then write this image to an SD card.

Instructions to import hardware design:

The Zynq UltraScale+ MPSoC IP is used to define the hardware of the processing system. You must use the IP Integrator within Vivado to configure the Zynq UltraScale+ MPSoC IP. Our Zynq UltraScale+ MPSoC IP configuration settings can be found at ZYNQMP Processing System. You may also use our provided TCL preset file that was used to configure the Zynq UltraScale+ MPSoC IP to the settings used to generate our ECM1900 image. The provided TCL scripts are located in our GitHub at opalkelly-opensource/ecm1900tools. You can follow the instructions in our Getting Started Guide for applying the TCL preset file.

When exporting the XSA hardware definition from Vivado to use within PetaLinux, you must ensure the versions are the same. PetaLinux 2020.2 works only with hardware designs exported from Vivado Design Suite 2020.2. To import a new XSA configuration into your PetaLinux project. Use the following example command inside your project folder:

petalinux-config --get-hw-description=Example.xsa
Code language: JavaScript (javascript)