3. Run Images on Target¶

3.1. Prerequisites¶

SD card image.
- Download Prebuilt Images and use the prebuilt petalinux-sdimage.wic.xz
- Alternatively build the petalinux-sdimage.wic.xz from the build tutorial.
Image flashing tool, for example:

OS	Program	Link
Windows	Balena Etcher	https://www.balena.io/etcher/
Linux	Balena Etcher	https://www.balena.io/etcher/

Terminal emulator, for example:

OS	Program	Link
Windows	teraterm	https://osdn.net/projects/ttssh2
Linux	picocom	https://github.com/npat-efault/picocom/releases

Chrome or Firebox browser:

OS	Program	Link
Windows / Linux	Chrome	https://www.google.com/chrome/
Windows / Linux	Firefox	https://www.mozilla.org

3.2. SD Card Creation¶

Plug uSD card (minimum 8 GB of size) in the host machine.
Flash petalinux-sdimage.wic.xz (locally built or downloaded prebuilt) in to the uSD card.
- Install and launch Balena Etcher (or any image writing tool) and follow the wizard.
  - Browse and select the petalinux-sdimage.wic.xz image as file to be flashed. (Balena Etcher will uncompress the .xz file automatically. Uncompress manually, if other tool is used)
  - Select target as uSD card
  - Click flash to write the image.

3.3. Board Setup¶

The following figure shows how to set up the VCK190 or VMK180 evaluation boards.

Board jumper and switch settings

This is a onetime setup and the board should have been delivered to you with this default settings, but it is good to double check for the first time when you get the board.

Make sure you remove J326 (7-8) jumper.
Setup SYSCTRL Boot mode switch SW11 to (ON,OFF,OFF,OFF) from switch bits 1 to 4 as shown in the above picture.
The Evaluation kit comes with an image pre-installed on the System Controller micro SD card. If for some reason the System Controller uSD card is corrupted or damaged, you can create new by flashing the prebuilt System Controller SD Image.
Setup Versal Boot Mode switch SW1 to (ON,OFF,OFF,OFF) from switch bits 1 to 4 as shown in the above picture.

Serial console settings

The Evaluation Boards come with a USB-C connector for JTAG+UART, and when connected three UART ports should be visible in Device Manager. They will not be identified by name, but they will correspond to the following:

Versal UART0
Versal UART1
System Controller UART

Connect a USB-C cable to the USB-UART connector. Since the COM ports are not identified by name, open three terminal emulators, and choose one COM port for each one using the following settings:

Baud Rate: 115200
Data: 8 bit
Parity: None
Stop: 1 bit
Flow Control: None

UART0 will be used for PLM, U-boot, and Linux on APU. UART1 will be used for RPU prints. System Controller UART will not be used, and can be closed once its terminal has been identified.

Ethernet IP settings

The JupyterLab Server IP address is fixed (static) at 192.168.0.10.

In order for this server to be seen by another computer, such as a laptop, the computer needs to be on the same subnet.

On Linux, type:

ifconfig

Note the Ethernet adapter name given, then type:

ifconfig <adapter> 192.168.0.xxx

where .xxx can be anything other than .10 which would conflict with the JupyterLab server.

On Windows, set the IP address from Control Panel as shown below.

3.4. First Boot configurations¶

3.4.1. Initial Boot¶

Follow these steps to boot the board into Linux.

Ensure all steps under the section ‘Board jumper and switch settings’ are verified.
Insert the prepared micro SD card into the Versal SD card slot (refer to Board Setup)
Make physical connections to ethernet, UART, and power as shown in the image.
Have the UART0 & UART1 terminal emulator connected.
Turn ON power switch SW13.
On Versal UART0 terminal, Versal device boot messages should appear starting with the message “Xilinx Versal Platform Loader and Manager”
Wait for about 60 seconds for boot to complete and login prompt to appear.
Enter petalinux as login and set a password of your choice on first boot.
Use these credentials for subsequent boots and to gain sudo privileges.

3.4.2. Initial Configurations¶

Following one time configurations are required to setup envirnoment to run the trd tests.

In case of static IP address configuration (which is default prebuilt images & build scripts), make sure to stop and disable the Network Time Synchronization service.

Enter following command:
```
sudo systemctl disable --now systemd-timesyncd.service
```
Enable and start the juputer service after first boot. The service will start automatically after subsequent reboots/restarts.

Enter following command:
```
sudo systemctl enable --now jupyter-setup
```

Note

This service might take about 90 seconds to start. Jupyter service requires the network to be online, hence the service can take up to 2-3 minutes to start on subsequent restarts as well.

Check status of the service:
```
systemctl status jupyter-setup
```

Output for the status of service:

plnx-vck190-prod:~$ systemctl status jupyter-setup
* jupyter-setup.service - jupyter setup scripts
     Loaded: loaded (/lib/systemd/system/jupyter-setup.service; enabled; vendor preset: disabled)
     Active: active (running) since Tue 2038-01-19 05:02:52 UTC; 29s ago
   Main PID: 882 (start-jupyter.s)
      Tasks: 2 (limit: 9216)
     Memory: 103.3M
     CGroup: /system.slice/jupyter-setup.service
             |-882 /bin/bash /sbin/start-jupyter.sh
             `-888 python3 /usr/bin/jupyter-lab --no-browser --allow-root --ip=192.168.0.10

[I 2022-03-24 21:31:59.626 LabApp] JupyterLab extension loaded from /usr/lib/python3.8/site-packages/jupyterlab
[I 2038-02-17 10:13:21.879 LabApp] JupyterLab application directory is /usr/share/jupyter/lab
[I 2038-02-17 10:13:21.896 ServerApp] jupyterlab | extension was successfully loaded.
[I 2038-02-17 10:13:21.896 ServerApp] Serving notebooks from local directory: /usr/share/notebooks/vssr-trd
[I 2038-02-17 10:13:21.897 ServerApp] Jupyter Server 1.13.5 is running at:
[I 2038-02-17 10:13:21.897 ServerApp] http://192.168.0.10:8888/lab
[I 2038-02-17 10:13:21.897 ServerApp]  or http://127.0.0.1:8888/lab
[I 2038-02-17 10:13:21.897 ServerApp] Use Control-C to stop this server and shut down all kernels (twice to skip
confirmation)

3.5. Connect to the JupyterLab Server¶

Follow these steps to connect to the jupyter-server using Chrome browser on the laptop.

Note: This demo is tested with Chrome browser, but Firefox should work as well.

Type the IP address of the Jupyter server in the browser address bar of the laptop:
```
http://192.168.0.10:8888
```
Enter the password vssr-trd

Click Log in button

Note: To stop and restart the Jupyter server, use the following commands:

sudo systemctl stop jupyter-setup.service
sudo systemctl start jupyter-setup.service

To look up the jupyter server IP address on the target, run:
```
sudo jupyter lab list
```

3.6. Run the TRD Notebook¶

This TRD includes a Jupyter notebook to demonstrate various restart options.

3.6.1. Start the Notebook¶

On the left pane (File browser pane) of the browser, double-click vssr-trd-widgets.ipynb to open the notebook.
Select menu Run > Run All Cells. This will start the TRD dashboard.

This will start the TRD dashboard in the notebook.

3.6.2. Using the Notebook¶

The notebook is laid out in a dashboard which allows to choose various TRD operations.

The top half of the notebook presents the general information about the notebook with links to documentation and sources.
The bottom half of the notebook has 2 panes
- Control & Status pane on the right: Which allows to perform various TRD actions and shows the live status of subsystem.
- Description pane on the left: Shows detailed description of current selection in the control pane. This is updated dynamically when the selection in Control pane changes. The following information is displayed:
  - Introduction and how the agent will normally perform this operation.
  - Behind the scene operation done by PLM and other intermediate layers.
  - How this operation can be triggered using the python module
  - Observation and what to expect.

3.6.3. Control Selections¶

Following TRD operations can be selected using the control pane.

Target	Action	Description
APU	Subsystem Restart	APU performs self (subsystem only) restart
	Watchdog Recovery	APU kills FPD watchdog to demonstrate recovery
	System Restart	APU performs full system restart
	Healthy Boot Test	APU demonstrate healthy boot based recovery
RPU	Subsystem Restart	RPU performs self (subsystem only) restart
	Watchdog Recovery	RPU kills LPD watchdog to demonstrate recovery
	System Restart	RPU performs full system restart
	Healthy Boot Test	RPU demonstrate healthy boot based recovery

After the selection Perform Action button triggers the selected action.

Refer to Restart Use Cases section in the Appendix for more details on each of the use cases.

3.7. Terminal based Testing¶

All the use cases can be tested even without Jupyter Notebook, through the terminal. A python script vssr-test provides menu based selection for variou use cases.

From the Uart0 terminal just type sudo vssr-test to execute this python script:

plnx-vssr-trd:~$ sudo vssr-test
Password:

Versal Restart TRD Testing. Choose the Test:

1. APU: Subsystem Restart
2. APU: System Restart
3. APU: Healthy Boot Test
4. APU: WDT Recovery
5. RPU: Subsystem Restart
6. RPU: System Restart
7. RPU: Healthy Boot Test
8. RPU: WDT Recovery
0. Exit

Enter your choice:

3.8. Troubleshooting¶

If after restarting the APU subsystem, the Jupyter notebook does not reconnect,wait for around 120-150 seconds and try hitting refresh (Normally F5 key).
If the petalinux image is configured to have dynamic (static in tutorial), then enter the new ip address (if the board ip is reassigned) after each reboot in the browser.
If after restarting the APU subsystem, you are prompted for the key again, make sure that cookies are enabled in your browser.