BRK1900 Linux Image

Resources

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 and rootfs partitions in the Wic file. Our provided Wic file 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 2 GB and EXT4 with 4 GB. When using the 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 will 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 our provided PetaLinux source files and rebuilding. More information regarding root file system behavior can be found at UG1144

Applications

The following applications are Baked into the BRK1900 image:

  • syzygy-ecm1900 – An application implementing the SYSYGY Standard on 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/check the clock outputs of the Si5338 on the BRK1900.

These applications are baked into the BRK1900 image and are located in the /usr/bin/ directory. The clock applications set the default frequencies specified at BRK1900 Peripherals and Clock Generator. If new frequencies are desired please follow the instructions in the “Start-Up Script” section.

Packages

Our provided 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
  • Python3
  • Vim
  • Dropbear SSH
  • I2C-Tools
  • Ethtool
  • Wpa-Supplicant
  • cpp
  • gcc
  • g++
  • make
  • packagegroup-core-buildessential

Additional tools may be added to the image by cloning, modifying, and building the PetaLinux project using the provided BRK1900 PetaLinux sources. Read the “Image Edits and Modifications” section below for instructions on how to modify and build these sources.

Start-Up Script

An 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 can be modified as desired and is located at the following location of the root file system on the BRK1900 image:

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

Si5338 Programmable Clock Oscillator (BRK1900)

As it is provided to you, the initializer script will run the provided set-clock-brk1900 application to configure the Si5338 programmable clock oscillator to the frequencies shown in the ‘Si5338 Programmable Clock section’ at BRK1900 Peripherals.

If you desire frequencies other than the defaults then you may modify our provided Silicon Labs Clock Builder Pro project file with your desired frequencies and rebuild the application using the makefile on the BRK1900’s Linux Image. You’ll substitute out the following header file on the root file system on the BRK1900 image with the newly generated header file from Silicon Labs ClockBuilderPro:

[/home/root/tools/set-clock-brk1900/BRK1900-Si5338-Regs.h
Code language: JavaScript (javascript)

Please ensure that the newly generated header file goes by the name BRK1900-Si5338-Regs.h as set-clock-brk1900.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-brk1900
Code language: JavaScript (javascript)

Once these steps are complete, you can reboot your ECM1900 and notice your desired frequencies take effect at startup. You may alternatively update the BRK1900-Si5338-Regs.h header file in our provided PetaLinux sources and rebuild the image.

Si5341 Programmable Clock Oscillator (ECM1900)

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 BRK1900’s Linux Image. You’ll substitute out the following header file on the root file system on the BRK1900 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. You may alternatively update the ECM1900-Si5338-Regs.h header file in our provided PetaLinux sources and rebuild the image.

VIO/VCCO Rails – SYZYGY

As it is provided to you, the initializer script will run the provided syzygy-ecm1900 application to run the SYZYGY solver which queries attached MCU’s (onboard SYZYGY PODs) and sets voltages accordingly to the SYZYGY Standard. If no SYZYGY pods are found the ‘syzygy-ecm1900’ application will set the VIO rail to the lowest allowable voltage for its rail. This is 1.2V for VIO1 through VIO4. Please see the ‘VIO/VCCO I/0 Bank Associations’ section at Powering the ECM1900 for more information about setting/overwriting the programmable VIO

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 2021.2 to build the provided BRK1900 PetaLinux sources. The provided BRK1900.wic image was built using the following:

  • Ubuntu 18.04.04
  • PetaLinux 2021.2
  • Vivado 2021.2

PetaLinux 2021.2 works only with hardware designs exported from Vivado Design Suite 2021.2. Ubuntu 18.04.4 is listed under the supported OS for PetaLinux 2021.2. More information regarding PetaLinux can be found at UG1144.

Instructions to install PetaLinux:

1. Boot up a PetaLinux supported Linux distribution OS.

2. Install the required packages for PetaLinux by following the “Quick Installation steps for packages” located within the 2021.2_PetaLinux_Package_List.xlsx attachment at PetaLinux 2021.2 – Product Update Release Notes and Known Issues.

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

sudo dpkg-reconfigure dash

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

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

Instructions to build with PetaLinux:

1. Clone the design-resources repository to acquire the brk1900 PetaLinux sources.

git clone https://github.com/opalkelly-opensource/design-resources
Code language: PHP (php)

2. Set up the PetaLinux working environment with the following command

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

3. Change directories to the brk1900 folder from the design-resources repository.

cd <path-to-design-resources-clone>/BoardTools/BRK1900/PetaLinux
Code language: HTML, XML (xml)

4. After making the desired changes then build the project with the following command:

petalinux-build

5. Generate the boot image with the following command:

petalinux-package --boot --u-boot --format BIN --force

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

petalinux-package --wic

7. The generated image will be located in the <path-to-design-resources-clone>/BoardTools/BRK1900/PetaLinux /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 IP. Our IP configuration settings can be found at ZYNQMP Processing System. You may also use our provided TCL preset file extracted from our configuration of the IP. The provided TCL preset is linked in the “Resources” section. You can apply this preset to the IP by following the instructions in our Getting Started Guide.

When exporting the XSA hardware definition from Vivado to use within PetaLinux, you must ensure the versions are the same. PetaLinux 2021.2 works only with hardware designs exported from Vivado Design Suite 2021.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)