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

System Controller Architecture

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. 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.

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.

Open

VPK120 SC Connections Example

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 board and Windows PC with Ethernet can be connected directly. Alternatively, the board can be in a network with a DHCP server running to provide the address. 

3. 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.

4. For some boards shipping from the factory, a login for the system controller console session will not appear, but instead the following banner appears in the console output:

   1. Enter the keyboard sequence as indicated EXT<Enter key><Tab key> to gain access to the command prompt.

5. If the board is in a network with a DHCP, jump to step 8. If the board is connected directly to the host, follow step 6 below. 

6. Please follow the below instructions to set a static IP address in the Windows PC. 

   1. Example: IP address: 192.168.1.2 

      Subnet mask: 255.255.255.0 

      Default gateway: 192.168.1.1 

      Follow the below steps on the Windows PC. 

      1. Go to: Control Panel\Network and Internet\Network Connections and open Properties
         
         

      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. 

      4. Refer to the snapshot below for IP Settings: 

7. On Tera term, enter the below command to override the IP address configured through the DHCP and to set the required static IP in the target board. use the below command to set the IP:

   1. sudo ifconfig eth0 192.168.1.11 

8. Verify/check the IP address of the board on the Tera Term session using the below command:

   1. sudo ifconfig 

9. 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 <ip of system_controller>:50002 in the address bar of the 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.  

Note: Limitation in Setting Clocks through GUI

Boards with an RC21008A clock synthesizer have some restrictions on what clocks can be controlled individually. Refer to the table below showing which clocks share a common output divider. Setting any clock in that group will result in all of these clocks changing.

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. 

Obtain Linux Prompt

This tab links to a Wiki page that contains instructions to fetch Linux console logs. For the EA and PP release the “Obtain Linux Prompt” is not supported.

Run Demos & Designs

Click the “Run Demos & Design” button on the home screen to obtain the above screen. This tab contains links to download BSP designs, the ACAP Cockpit, a Jupyter notebook based Power Advantage Tool demo, and Target Reference Designs (TRDs) with corresponding learn more links. Clicking on the link opens a new tab in your browser. As more and more designs for the evaluation kit are released, this tab will be updated to showcase them. For the EA release, refer to the EA lounge for BSP Designs and TRDs.

Develop using Tools

Click the “Develop using Tools” button in home screen to get to this screen. This tab contains links to various Xilinx tools to download, the developer site, libraries, etc. Clicking on each of the buttons will opens a link to the product page within a new tab in your browser.

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.

Retrieving the BEAM log file

The BEAM debug log file can be retrieved via SCP. Refer to Board Setup and Connections to obtain the IP address of the System Controller.

Use an application like WinSCP, or simply use SCP from the command line to retrieve the file /var/log/local3.log

Navigate to the root directory

Navigate to /var

Then to /var/log

Select the local3.log file and click download.

Click OK to confirm the transfer

Alternatively, you can do the followingfFrom the command line (replacing the IP with the correct IP for your System Controller):

scp petalinux@10.0.0.194:/var/log/local3.log .

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. Each performed operation is logged through syslog utility and can be referenced at /var/log/local3.log.

Board Configuration Files

Board specific configurations and data are managed as input files to sc_appd, which uses them configure the server to support different boards. These are captured in board configuration json files located in:

8A34001 Configuration Files

The 8A34001 clock files are referenced to program this device on the board. Users with custom design for this device will need to copy their clock files (tcs and txt files) to following directory:

A reboot is required for new clock files to be detected by the BEAM tool.

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

Steps to upload new clock files

1. Connect to your evaluation platform using the JTAG / UART connector (refer to the “Component Location” section of your User Guide)

2. Using TeraTerm (UG1036) or similar, connect a terminal to the last port number that shows up, in this example, COM6

3. Turn on the power (SW13)

4. Once you get the IP address

5. Connect to the System Controller using SCP with a tool like WinSCP

6. If you get a password error:

   1. If you have closed your TeraTerm (or similar), reconnect to the last com port. Use login petalinux/petalinux

   2. You will be required to change the password

7. Using your new password, connect to the System Controller and copy the files from inside the clock_files folder into your home folder.
   In this case, the intention is to place a 625 MHz clock on a VPK180 Evaluation Platform.

8. Back in the terminal, login if necessary

9. Check that the files you copied are present

10. From your home folder, execute the below privileged commands to copy the clock files into the clock_files location BEAM uses to list clock files:

    sudo cp *.tcs /usr/share/system-controller-app/BIT/clock_files/. sudo cp *.txt /usr/share/system-controller-app/BIT/clock_files/.

11. Enter in the password you set

12. Double check that the clock files are present

13. Now reboot the system controller - DO NOT CLOSE your terminal application

14. Once the System Controller has booted, navigate to the web address presented

15. Navigate the menus:

16. Test the Board → Board Settings → Set Clock

17. Select the each of the clock files for each selector, in this case “VPK180_625MHz_8A34001_20230103.tcs” and “VPK180_625MHz_8A34001_20230103.txt”

18. Finally, click Set

19. If you see a green checkbox to the right, you have successfully programmed the clock with your custom file!

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.

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.

Boot FW update with xmutil

The xmutil provides a utility to help in the update of the on-target boot firmware with the following steps:

1. Download the boot firmware update from the table above. It should be a Xilinx BOOT.BIN file.

2. Move the BOOT.BIN file to the SC target using FTP (or similar method). Note when copying file remotely you must copy it to the petalinux user directory.

3. Execute “sudo xmutil bootfw_update -i <path to boot.bin>”.

4. After the image write is completed issue a power-on reset. This can be accomplished by pressing the RESET push-button or power cycling the board.

5. After restart it is required by the user verify that Linux fully boots with the new boot FW to verify functionality. This is completed by executing “sudo xmutil bootfw_update -v” to validate successful boot against the new firmware. Note this must be completed on the platform restart immediately following the update, else the platform will fall back to the other boot partition on the next restart.

Boot FW status with xmutil

The xmutil also provides a “bootfw_status” command which can be used to identify which image is active, which image was last booted, and what image is going to be booted on the next boot. The version information noted from bootfw_status represents the factory installed version and will not change when you update individual boot partitions.

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.

BoardUI

BoardUI is a legacy Xilixn evaluation board tool that provided many of the same features as the BEAM tools outlined above. Evaluation boards are presently in a transition from BoardUI (also called Board Framework) as the primary SC application to BEAM. During this transition the legacy BoardUI tool will be available for a limited set of boards until the full feature set of BEAM is achieved.

Command Line Switch

BEAM to legacy BoardUI

1. Disable BEAM application:

2. Enable legacy BoardUI:

3. Power cycle the board

BoardUI to BEAM

1. Exit and kill the BoardUI/Board Framework application:

   1. At Linux prompt enter: ext<enter key><tab key>

   2. At login prompt, login with user petalinux

   3. Set root privileges: sudo su

2. Enable the BEAM application

3. Disable Board Framework / BoardUI from starting:

4. Power cycle the board

GUI Switch

The switch between BEAM and BoardUI/BoardFramework can also be accomplished with the BoardUI GUI buttons shown below.