Versal Evaluation Board - System Controller - Update 5 and prior Archive
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
- 1 Overview
- 2 Getting Started
- 2.1 BEAM
- 2.1.1 Overview
- 2.1.2 Board and Requirements
- 2.1.3 Board setup and Connections
- 2.1.4 Launching the GUI
- 2.1.5 GUI Pages
- 2.1.5.1 BEAM Home
- 2.1.5.2 Test The Board
- 2.1.5.2.1 Board Settings
- 2.1.5.2.2 Note: Limitation in Setting Clocks through GUI
- 2.1.5.2.3 Setting Boot Mode through GUI
- 2.1.5.2.4 Board Interface Test
- 2.1.5.3 Obtain Linux Prompt
- 2.1.5.4 Run Demos & Designs
- 2.1.5.5 Develop using Tools
- 2.1.5.6 Help
- 2.1.5.7 About
- 2.1.6 Retrieving the BEAM log file
- 2.2 System Controller Application
- 2.2.1 Board Configuration Files
- 2.2.1.1 8A34001 Configuration Files
- 2.2.1.2 Steps to upload new clock files
- 2.2.1 Board Configuration Files
- 2.1 BEAM
- 3 SC Platform Updates
- 3.1 Linux Image Updates
- 3.2 Firmware Updates
- 3.3 Image Update Tools
- 3.3.1 Image Recovery
- 3.3.2 Linux FW Image Update
- 3.3.2.1 Boot FW update with xmutil
- 3.3.2.2 Boot FW status with xmutil
- 4 SC Fan Control
- 5 Debug Tips
- 6 BoardUI
- 6.1 Command Line Switch
- 6.1.1 BEAM to legacy BoardUI
- 6.1.2 BoardUI to BEAM
- 6.2 GUI Switch
- 6.1 Command Line Switch
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.
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.
VCK190/VMK180 use a dedicated SC implementation that is not covered by this page. For the VCK190/VMK180 SC information, refer to the VCK190/VMK180 BEAM Tool Wiki.
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.
VPK120/VPK180 - The VPK120 and VPK180 includes a BOOTMODE switch (SW11) for the SC that must be set to QSPI32 boot mode (set SW11 to ON,OFF,ON,ON) for factory deployed out-of-box functionality. For further details, see the "Default Switch Settings" section of the respective evaluation board user guide.
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.
Note that VCK190/VMK180 boards use SD1 boot mode while the common Versal SC implementation uses QSPI32. The picture below shows QSPI32 boot mode switch configuration. For VCK190/VMK180 SC boot mode see the dedicated Wiki.
Set up a Tera Term session between a Windows PC COM port and the serial port on the evaluation board.
Download and install a terminal application such as Tera Term. Refer to Tera Term Terminal Emulator Installation Guide (UG1036) for more information.
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.
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.
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.
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.
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:
Enter the keyboard sequence as indicated EXT<Enter key><Tab key> to gain access to the command prompt.
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.
Please follow the below instructions to set a static IP address in the Windows PC.
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.
Go to: Control Panel\Network and Internet\Network Connections and open Properties
Make sure that the last digit of the IP Address on the Windows PC is different to what is being set on the Board.
Make sure that the default gateway has the last digit as one, the rest should be the same as the IP Address field.
Refer to the snapshot below for IP Settings:
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:
sudo ifconfig eth0 192.168.1.11
Verify/check the IP address of the board on the Tera Term session using the below command:
sudo ifconfig
Ping the Windows PC with the below command via the Tera Term session. Press Ctrl + C to stop ping on Tera Term.
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.
Card | Common Clocks |
---|---|
VPK180 | GTCLK1_OUT[7:0] |
| GTCLK2_OUT[7:0] |
VHK158 | GTCLK1_OUT1 |
| GTCLK1_OUT[3:2] |
| GTCLK1_OUT[7:6] |
| GTCLK1_OUT8 / GTCLK1_OUT10 |
| GTCLK2_OUT[3:2] |
| GTCLK2_OUT6_DDR1 / GTCLK2_OUT7_DDR7 |
| GTCLK2_REF_CLK |
| GTCLK2_OUT10 |
VEK280 | SYS_CLK_[2:0] |
| GTCLK1_OUT[7:6] |
| GTCLK1_OUT8 |
| PS_REF |
| GTCLK1_OUT11 |
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:
/usr/share/system-controller-app/board
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:
/usr/share/system-controller-app/BIT/clock_files/
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
Connect to your evaluation platform using the JTAG / UART connector (refer to the “Component Location” section of your User Guide)
Using TeraTerm (UG1036) or similar, connect a terminal to the last port number that shows up, in this example, COM6
Turn on the power (SW13)
Once you get the IP address
Connect to the System Controller using SCP with a tool like WinSCP
If you get a password error:
If you have closed your TeraTerm (or similar), reconnect to the last com port. Use login petalinux/petalinux
You will be required to change the password
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.Back in the terminal, login if necessary
Check that the files you copied are present
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/.
Enter in the password you set
Double check that the clock files are present
Now reboot the system controller - DO NOT CLOSE your terminal application
Once the System Controller has booted, navigate to the web address presented
Navigate the menus:
Select the each of the clock files for each selector, in this case “VPK180_625MHz_8A34001_20230103.tcs” and “VPK180_625MHz_8A34001_20230103.txt”
Finally, click Set
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.
SC Linux Image | Description & Updates | Board Supported | Download Link |
---|---|---|---|
SC Update 0 (2021.2 base) | Early Access BEAM release | VPK120ES | None - Factory deployed only |
SC Update 1 (2022.1 base) | Initial BEAM production release | VPK120ES, VPK120, VPK180ES | |
SC Update 2 (2022.2 base) | BEAM based active fan control | VPK120ES, VPK120, VPK180ES, VPK180, VHK158ES | |
SC Update 3 (2022.2 base) | BEAM, SC fan control, bug fixes & feature enhancements | VPK120ES, VPK120, VPK180ES, VPK180, VHK158ES, VEK280ES | |
SC Update 4 (2022.2 base) | BEAM, SC fan Control, various bug fixes & feature enhancements | VPK120ES, VPK120, VPK180ES, VPK180, VHK158ES, VEK280ES | |
SC Update 5 (2022.2 base) | Add support for VEK280, bug fix release | VPK120ES, VPK120, VPK180ES, VPK180, VHK158ES, VEK280ES, VEK280 | |
SC Update 5B (2022.2 base) | Add support for VHK158 | VHK158 |
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.
SC Boot FW Image | Description | Download Link |
---|---|---|
2021.2 SC BOOT.BIN Image | 2021.2 SC Boot FW | None - Factory deployed only |
2022.1 SC BOOT.BIN Image | 2022.1 SC Boot FW | |
2022.2 SC BOOT.BIN Image | 2022.2 SC Boot FW |
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:
Download the boot firmware update from the table above. It should be a Xilinx BOOT.BIN file.
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.
Execute “sudo xmutil bootfw_update -i <path to boot.bin>”.
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.
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.
Board | Fan Tach Jumper | Fan Ctrl Jumper |
---|---|---|
VPK120 | J348 Pin 1-2 | J347 Pin 1-2 |
VPK180 | J348 Pin 1-2 | J347 Pin 1-2 |
VEK280 | J348 Pin 1-2 | J347 Pin 1-2 |
VHK158 | J348 Pin 1-2 | J347 Pin 1-2 |
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:
User has set the physical jumpers correctly
User has a corresponding Versal DUT BSP default image loaded with the corresponding Versal DUT boot mode set correctly
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:
Supported board with properly configured PDI loaded to Versal DUT. Temperature is displayed in upper left corner.
Supported board without a properly configured PDI loaded to Versal DUT. Temperature is not displayed and value is noted as "-".
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:
Enable SysMon I2C external interface
Set SysMon I2C external I2C address to 0x18
Next, set the I2C Bus to the appropriate IO pins “PCM_MIO 39..40”
Debug Tips
The following are failure modes and debug tip:
Failure Description | Failure Remedy |
---|---|
SC BEAM is displaying Versal temperature but not actively regulating fan speed. |
|
SC BEAM is not displaying Versal temperature ("-") and is not actively controlling the SC fan. |
|
SC console shows the following message: /usr/sbin/fancontrol: line 543: read: read error: 0: Input/output error Error reading temperature from ///sys/class/hwmon/hwmon1/temp1_input Aborting, restoring fans... Verify fans have returned to full speed |
|
SC BEAM is displaying a "NA" | This is a board that is not supported with SC based remote temperature read nor active fan control. |
SC based fan control appears to be lost when loading a new PDI, while BEAM GUI temperature read is showing temperature reading. | Restart the the fancontrol process on the SC console. |
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
Disable BEAM application:
Enable legacy BoardUI:
Power cycle the board
BoardUI to BEAM
Exit and kill the BoardUI/Board Framework application:
At Linux prompt enter: ext<enter key><tab key>
At login prompt, login with user petalinux
Set root privileges: sudo su
Enable the BEAM application
Disable Board Framework / BoardUI from starting:
Power cycle the board
GUI Switch
The switch between BEAM and BoardUI/BoardFramework can also be accomplished with the BoardUI GUI buttons shown below.
© Copyright 2019 - 2022 Xilinx Inc. Privacy Policy