..
 # SPDX-FileCopyrightText: Copyright (c) 2024, Linaro Limited.
 #
 # SPDX-License-Identifier: MIT

##############################
Getting Started with KV260
##############################

This document explains how to build, deploy, and boot the Cassini distro on
Xilinx KV260 Platform.

*********************
Building KV260 Images
*********************

.. note::

  When building on ``main`` branch, the preparation script:
  ``kas/scripts/generate_kv260_env.py``
  must be executed before attempting the following steps. This script
  pins the SHAs for layers involved in KV260 build according to the
  |TRS manifest|_ to follow the same update pace as meta-trustedsubstrate.

  This script needs ``defusedxml`` Python library to be installed.

The provided kas configuration files: ``kas/kv260-psa.yml`` and ``kas/kv260-edk2.yml``
can be used to build images which target KV260 using U-Boot or EDK-II as BL33 respectively.

To build an image with default options using U-Boot:

.. code-block:: console

  kas build --update kas/cassini.yml:kas/kv260-psa.yml

or using EDK-II:

.. code-block:: console

  kas build --update kas/cassini.yml:kas/kv260-edk2.yml

Both builds will produce the firmware images here:

  ``build/tmp/deploy/images/zynqmp-kria-starter-psa/ImageA.bin``

  ``build/tmp/deploy/images/zynqmp-kria-starter-psa/ImageB.bin``

And a Cassini distribution image here:

  ``build/tmp/deploy/images/zynqmp-kria-starter-psa/cassini-image-base-zynqmp-kria-starter-psa.rootfs.wic.gz``

  ``build/tmp/deploy/images/zynqmp-kria-starter-psa/cassini-image-base-zynqmp-kria-starter-psa.rootfs.wic.bmap``

For other build options, refer to :doc:`../developer_manual/build_system`

***********************
Flashing the Firmware
***********************

1. Connect KV260 Ethernet port to **the host machine**

2. Power up the device while holding **FWUEN** button

3. In a browser, visit: ``http://192.168.0.111/``, this will open **Xilinx tool** for flashing the firmware

4. Upload ImageA.bin and ImageB.bin

5. Reset the device

  .. note::

    The ethernet port on **the host machine** must be configured
    to have an IP address on the same network as ``192.168.0.111``.
    For example:

    * IP address: ``192.168.0.110``
    * Subnet mask: ``255.255.0.0``

******************************************
Flashing the Distro Image
******************************************

1. Insert the SD card into **the host machine**

2. Check if the SD card is seen by **the host machine** via ``lsblk``.

  This will output, for example:

  .. code-block:: shell

    NAME        MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
    <sd card>   179:0    0    16G  0 disk
    ├─p1        179:1    0   256M  0 part
    └─p2        179:2    0   512M  0 part

3. Flash the image onto the SD card using ``bmap-tools``:

  .. code-block:: shell

    sudo bmaptool copy --bmap cassini-image-base-zynqmp-kria-starter-psa.rootfs.wic.bmap cassini-image-base-zynqmp-kria-starter-psa.rootfs.wic.gz /dev/<sd card>

4. Eject the SD card from **the host machine**, and insert it into KV260

**************************************************
Connecting to the serial port
**************************************************

1. Connect a cable between the USB port of **the host machine** and
   the micro-USB port of KV260 and then power on the device.

2. Check for new TTY USB devices detected by **the host machine**,
   via:

  .. code-block:: shell

    ls /dev/ttyUSB*

  This will output, for example:

  .. code-block:: shell

    /dev/ttyUSB0
    /dev/ttyUSB1
    /dev/ttyUSB2
    /dev/ttyUSB3

  * ``ttyUSB1`` is used for logs of both secure and non-secure sides.
  * PMU uses one of the other ports, while the rest are not used
    at the moment.

3. Connect to the serial console using any terminal client (picocom, minicom, or screen should all work).

  .. code-block:: shell

    sudo picocom -b 115200 /dev/ttyUSB1