This page provides an overview of the functions and features available with the Versal Evaluation board System Controller (SC) function. The SC is an independent MPSoC based subsystem included on the Versal evaluation boards meant to aid users in the evaluation of the Versal device under test (DUT).

Table of Contents

Overview

The System Controller (SC) is implemented to be a cooperative and supporting component to the Versal DUT, while also allow full DUT operation independent of the SC. The “domains” shown in the example evaluation board functional diagram below provides an outline of the independent functions within each subsystem. The SC has a dedicated Ethernet, USB, and UART interface for user interaction, while the Versal DUT will have its own dedicated peripherals which will vary based on the Versal DUT and evaluation board. For the Versal DUT peripheral set, refer to the User Guide (UG) for the specific board you are working with.

Open

The SC design captured in this page uses a common architecture for the VPK120, VPK180, VHK158, and VEK280 Versal evaluation boards. It provides most functionality and user workflows in a board agnostic manner and any specific board references are for example only. The table in the WIC Image Downloads section provides downloadable images, boards supported, and corresponding updates information.

Getting Started

The System Controller (SC) ZU4 device has its boot firmware pre-loaded to the SC QSPI device at the factory and should boot upon initial power-on of the evaluation board. However, it is highly recommended to update to the latest build posted here. The SC will automatically start a web-based user interface called BEAM or Board Evaluation And Management tool. The BEAM tool provides a GUI based interaction with the board programmable features such as clocks, FMC functionality, power system configuration, and built-in-self-test (BIST) features.

SC Platform Updates

Linux Image Updates

The SC Linux is maintained in SC eMMC. The SC Linux is an image produced with the PetaLinux tool.

Firmware Updates

The core SC boot firmware is maintained in the SC QSPI memory device. Its image is provided as a BOOT.BIN in the table below. It can be updated as described in the Linux FW Image Update section below.

Image Update Tools

Image Recovery

The Image Recovery tools is a web-based tool that can be used to update either firmware or an new Linux image. The tool is launched by holding the SC FWUEN pushbutton during a power-on of the evaluation board. This will launch a web-based interface for updating either boot firmware in the QSPI image or updating a complete Linux image in the eMMC. The web-interface uses a static IP (default IP is 192.168.0.111) is printed to the SC UART which supports a web-based interface that is available on the SC dedicated Ethernet interface.

To update the Linux image download the desired SC Linux image and use the Image Recovery applicatoin “Image Wic (eMMC)” radial selection and the “Browse” button to select the downloaded <linux-image-name>.wic.

Open

To use the Image Update tool user needs to configure their PC with a corresponding IP of the same subnet and have a direct Ethernet connection to the SC Ethernet interface as shown in the diagram below.

Linux FW Image Update

The Linux FW Image Update is a utility to update the A/B partitions of firmware. This is accessed through an on-target management utility xmutil which provides bootfw_update and bootfw_status utility for updating and checking the status of the boot FW from Linux.

BEAM

Overview

BEAM is a web based GUI application to monitor and modify parameters of the evaluation board. The BEAM web page connects to a web server running on the system controller and provides a home screen which provides navigation to board specific test interfaces and related product pages.

The “Test the Board” page displays basic information such as board information, Versal DUT detected boot modes, a board overview and a link to product page. BEAM also provides an interface to a board settings and built-in-test (BIT) screens. The “Board Settings” tab provides an ability to monitor and modify clocks, a subset of power rails, and related functionality. BEAM also provides links to open other Jupyter notebook based tools, additional Wiki based information, and relevant downloads.

Board and Requirements

• Versal Evaluation Board Kit 

• Ethernet cable 

• PC with Ethernet interface and web-browser (e.g. Firefox or Chrome)

• Micro USB to USB-A Cable for VPK120 and USB-C cable for other boards

• Power adapter 

Board setup and Connections

To connect to the SC, functions should interface to both the SC UART and the SC dedicated Ethernet interface. The VPK120 board image is shown below for reference but other boards aligned with the common SC implementation (for example, VPK180 or VHK158) operate and boot in the same manner. Refer to the Board Component Location section of the corresponding evaluation board User Guide for specific connection points on the board in use.

1. Set up a Tera Term session between a Windows PC COM port and the serial port on the evaluation board.

   1. Download and install a terminal application such as Tera Term. Refer to Tera Term Terminal Emulator Installation Guide (UG1036) for more information.

   2. Of the three COM ports that are assigned when connecting a cable to the debug port, connect your terminal program to the highest com port. Configure the port with 115200,8,n,1.

2. The System Controller boots with DHCP enabled by default. You can connect this to your LAN and access directly from any PC on the same network. You will see a message like the following on the Serial Console when the system boots.

3. Alternatively, the System Controller can bet setup with a Static IP address.

4. Login to the system controller using the serial terminal using the username petalinux and if prompted for a password, enter the password that you set up for the first time login.

   1. For the first time login, there will be a prompt to set a password. Set a password that you can remember for the next login.

   2. Create the file: /etc/systemd/network/20-wired.network

   3. [Match] Name=eth0 [Network] Address=192.168.1.11/24 Gateway=192.168.1.1

      This can be done in a 1 line command:

   4. printf "[Match]\nName=eth0\n\n[Network]\nAddress=192.168.1.11/24\nGateway=192.168.1.1\n" | sudo tee /etc/systemd/network/20-wired.network

   5. Reboot the system controller with “sudo reboot” for changes to take affect.

5. If you need to setup a static IP on your Host PC, Please follow the below instructions:

   1. Windows PC. https://support.microsoft.com/en-us/windows/change-tcp-ip-settings-bd0a07af-15f5-cd6a-363f-ca2b6f391ace#WindowsVersion=Windows_11

   2. MacOS https://support.apple.com/guide/mac-help/use-dhcp-or-a-manual-ip-address-on-mac-mchlp2718/mac

   3. Ubuntu Desktop https://help.ubuntu.com/lts/ubuntu-help/net-fixed-ip-address.html.en

   4. Example:

      1. IP address: 192.168.1.2 

         Subnet mask: 255.255.255.0 

         Default gateway: 192.168.1.1 

      2. Make sure that the last digit of the IP Address on the Windows PC is different to what is being set on the Board. 

      3. Make sure that the default gateway has the last digit as one, the rest should be the same as the IP Address field. 

6. Ping the Windows PC with the below command via the Tera Term session. Press Ctrl + C to stop ping on Tera Term. 

   1. ping <host_ip> 

Launching the GUI

On the Windows PC, Open the Chrome web browser. Enter address shown in the serial console into your Web Browser

GUI Pages

The BEAM tool GUI is a common portal for interfacing with the SC and Versal evaluation board platform. The BEAM tool will automatically launch the board specific version of BEAM for the board that it is running on. The images below are using a VPK120 BEAM instance as an example and your own board specific GUIs will differ slightly based on the board specific BEAM version.

BEAM Home

The above BEAM Tool GUI Home page is displayed on Chrome web browser once the loading is finished. The GUI contains Home, Help, About and various navigation options such as Test the board, Linux prompt, Demos & Design and Develop using Tools tabs. At the bottom right, the BEAM tool version is displayed.

The home screen contains pictures and links to the Versal product page. Click on the “Home” button located on the top-right to navigate to this screen from any other tabs.

Test The Board

The “Test the board” screen contains board image, device details, and boot mode. It contains navigation options to Board settings and Board interface test screens. 

The navigation options below “Versal Device Temp” are links to board settings and BIT screens. 

The large image at the center is a board image which shows labels of various components of VPK120.  

The top right section of the GUI displays Device information such as the device name, board part number, revision, serial number, and MAC address assignments.  

The boot mode section displays the active boot mode and has option to change the boot mode to a different mode. Click on the dropdown beside the “Change” label in the boot mode section. It displays various boot modes available. Select the required boot mode and click on the “set” button to set the boot mode and reset. A loader is displayed while setting the boot mode. On successful set, a green tick mark is displayed beside the “set” button. On failure, a red colored cross icon is displayed. Once the boot mode is set, the updated boot mode is displayed beside “Active” label in the boot mode section. The Reset button applies power-on-reset. 

Note: To enable bootmodes, the Versal DUT switch [SW1] positions should be in the default bootmode positions [1111]. 

Board Settings 

Click on the “Board Settings” tab in the “Test the board” screen to display Board settings section. “Board settings” helps in monitoring and modifying various SCUI tabs. Click on the elements on the left to toggle between each tab.  

Click the “Get” button to get corresponding rail information. User can also click the “Get All” button to read all information for selected rails. Upon success, a green tick is displayed under the status column. On failure, a red cross is displayed. Hover over the status icon to display a status message for each status. There are also a few tabs with multiple sub-tabs presenting options to get, set, and reset system values. Click on the corresponding sub-tabs to display the corresponding control sections. Click the “Get” button to fetch the values of corresponding items. In the “Set” tab, click on the “Set” button to set the value. The “Restore” button will reset the values to the default settings.  

Uploading custom designs for 8A34001 clock chip

For more information on generating your own clock configuration files, refer to the Renesas Timing Commander website.

• Generate 3 output files (.tcs, .txt, and .bin) from Timing Commander utility for your design.

• Navigate the menus ‘TEST THE BOARD → Board Settings → Clock’, and click on ‘Upload clock files’ button.

• Upload the 3 files associated with your clock design from your host system to System Controller.

• Select ‘Set Clock’ tab (if programming is desired for current working session) or ‘Set Boot Clock’ tab (if programming is desired to remain persistent across a power-cycle), and click on ‘Frequency’ pull-down menu for 8A34001 clock:

• Select your custom clock design, and click ‘Set’.

• If you see a green checkbox to the right, you have successfully programmed the clock with your custom files!

Setting Boot Mode through GUI

The BEAM tool can set the boot mode (SW1) switch value, if this switch is physically set to the OFF position.  While off, the BEAM tool reads the following value from the switch: 

 A boot mode can now be set in the ‘Set GPIO' tab of GUI.  For example, if the 'sd1_ls' boot mode is desired, it can be set by entering 0xe and clicking the 'Set’ button:

 This setting can then be confirmed by reading the ‘SW1 Readback' GPIO lines in ‘Get GPIO' tab, through clicking the 'Get’ button for the 'SW1 Readback’: 

This setting remains in effect until the board is power-cycled, or 'SW1' GPIO lines are read back in 'Get GPIO' tab:

Reading back 'SW1' GPIO lines returns the setting to what the physical SW1 is set to. In the case of our example, is all switches set to the OFF position, meaning no active boot mode.

The same behavior applies to the SW3 switch.  A new SW3 setting can be set in 'Set GPIO' tab. As in the above example, the effect will remain until the board is power-cycled, or 'SW3' GPIO lines are read back in 'Get GPIO' tab.

Board Interface Test 

From the Home screen, click on the “Test The Board” panel and then click the “Board Interface Test” button to display the Board Interface Test (BIT) section. The BIT helps in running I2C/XSDB based board interface tests. This screen displays the available board interface tests. Click on the “Run” button to start the corresponding test. The progress bar displays the current status of the test running state. 

Some tests are manual and requires users to check the Versal console to view the expected result. When the user clicks on any manual tests, a pop-up is shown which contains expected results to be verified on the Versal console. When the user observes the expected result on the Versal console, they need to click on the “Pass” button inside the pop-up to mark the test Successful. Otherwise, clicking the “Fail” button will mark the test as failed. 

If the test is in progress, the progress bar color will be yellow. If the test fails, the color will be red and the color is green when the test passes. Please hover the mouse cursor on the “cross” or “tick” icon beside run button to see the status message of a test result. 

Help

The above Help page is displayed when clicked on “Help” on the right top in any screen. This page contains help information of various screens, applications and known issues and bugs.

About

The above About page is displayed when clicked on “About” on the right top in any screen. This page contains information about BEAM Tool.

Download Log Files

System Controller Application

System Controller Application (sc_app) is the back-end software layer for operations initiated by the BEAM tool relating to board telemetry, control, and test. The following diagram depicts different components of System Controller Application.

BEAM tool selections are passed to sc_app binary in form of sc_app commands, which in turn is passed to sc_appd server. The sc_appd server is invoked at boot time and is responsible for processing the commands and returning the results back to BEAM tool through sc_app client.

SC Fan Control

This section captures the implementation details of the Versal Evaluation Board System Controller based active fan control. It also captures important Versal DUT and board jumper configurations that must be adhered to for proper operation of the SC fan control feature.

Physical Board Jumpers

The Versal evaluation boards have been built with physical jumpers to provide board user selection between connecting the fan PWM control and tachometer signals to either SC or the Versal DUT. The SC fan control functionality is dependent on the board user having proper jumper configuration on their board.

Default Behavior

The SC and evaluation board default behavior will automatically start at time of SC boot and if the user has met the following requirements:

1. User has set the physical jumpers correctly

2. User has a corresponding Versal DUT BSP default image loaded with the corresponding Versal DUT boot mode set correctly

3. SC 2022.2 or later System Controller Linux image loaded to SC eMMC

Versal DUT Dependency

The Versal devices used in the evaluation boards discussed in this page only expose their temperature via its SysMon remote monitor I2C interface. For the Versal SysMon remote monitor to be active a device configuration file or "PDI" must be loaded to the Versal DUT with it enabling and configuring the I2C interface in the manner expected by SC. If no PDI is loaded, or if a PDI is loaded to the Versal DUT that does not include the SysMon external I2C interface enablement the SC has no manner to remotely read the Versal temperature. Remote temperature read scenarios are outlined in the figure below.

BEAM GUI Behavior

The BEAM GUI will display the Versal DUT temperature when it is available from the SysMon remote temperature interface. When the Versal remote temperature is not available the BEAM will not display a temperatur.  As the BEAM (sc_web) is a common GUI for both SC fan controlled enabled platforms discussed in this page, as well as legacy boards (VCK190/VMK180) there are three states of display:

1. Supported board with properly configured PDI loaded to Versal DUT. Temperature is displayed in upper left corner.

2. Supported board without a properly configured PDI loaded to Versal DUT. Temperature is not displayed and value is noted as "-".

3. Unsupported board. Temperature is displayed as "NA".

Vivado Board Files & PetaLinux Versal DUT BSPs

The evaluation boards in the scope of this page have had their Vivado board file and PetaLinux BSP configuration defaults include configuration of the Versal DUT SysMon remote I2C interface aligned with the SC fan control application requirements. For users customizing their own Vivado and PDI file generation the following Vivado CIPS based configurations must be met in order for SC fan control to function:

1. Enable SysMon I2C external interface

2. Set SysMon I2C external I2C address to 0x18

3. Next, set the I2C Bus to the appropriate IO pins “PCM_MIO 39..40”

Debug Tips

The following are failure modes and debug tip:

To restart the SC fan control process use the following command:

Debug Tips

This section outlines common debug tips & limitations of the System Controller and BEAM functionality.

• When reading back SFP information if an error is received, or information reported is incomplete check with your selected SFP part datasheet to ensure it supports the full set of SNIA management interface data. For example some of the management function information are sometimes left out in SFP loopback modules.

• SC Keeps getting new IP address on every boot.

  • This happens when the SC is using a randomized MAC address. If this is happening you should upgrade your QSPI image using the latest image in the Firmware Updates Section

System Controller Source Code

The System Controller code is all provided as open source code on GitHub. The table below lists the various repositories: