..
 # SPDX-FileCopyrightText: <text>Copyright 2026 Arm Limited and/or its
 # affiliates <open-source-office@arm.com></text>
 #
 # SPDX-License-Identifier: MIT


#############
FPGA Platform
#############

.. _fpga_prerequisites:

Prerequisites
*************

To run tests on FPGA hardware, make sure to have:

1. SSH access

   Make sure to have SSH access to the remote host where the FPGA is connected.
   The framework interacts with the FPGA through this host (remote execution).

2. FPGA host specification

   The FPGA hostname must be provided when running pytest using:

   ``--host <hostname>``

3. Payload archive availability

   The local payload archive specified in the YAML configuration must be available.
   This archive should contain FPGA bootable images generated from the
   software reference stack build.

Configuration
*************

FPGA platforms are defined in a YAML configuration file and must include:

- ``type: fpga``
- ``username``
- ``port`` (optional)
- ``local_payload_path``
- ``remote_payload_path``
- ``boot_cmd``

The host name is not read from YAML and must be provided through the command
line using ``--host <fpga_hostname>``.

Running Sample FPGA Test
************************

Follow all the steps in :ref:`fpga_prerequisites` and :ref:`Installation` before running tests.
The following command runs the sample FPGA boot test using the default FPGA config:

.. code-block:: bash

   $ pytest -s test_automation/tests/test_fpga_boot.py \
     --config test_automation/test_automation/configs/fpga_config.yaml \
     --platform <platform_name> \
     --host <fpga_hostname>


A successful sample FPGA boot test run should produce output similar to the following:

.. code-block:: none

   ==================================================== test session starts =====================================================
   ...

   test_automation/tests/test_fpga_boot.py
   SETUP    S fpga_device
         tests/test_fpga_boot.py::TestFPGABoot::test_boot_artifacts_present (fixtures used: fpga_device, request).
         tests/test_fpga_boot.py::TestFPGABoot::test_sample_command_check_in_uart (fixtures used: fpga_device, request).
         tests/test_fpga_boot.py::TestFPGABoot::test_uart_role_mapping (fixtures used: fpga_device, request).
         tests/test_fpga_boot.py::TestFPGABoot::test_scp_boot_completed (fixtures used: fpga_device, request).
         tests/test_fpga_boot.py::TestFPGABoot::test_detect_scp_safety_uart (fixtures used: fpga_device, request).
         tests/test_fpga_boot.py::TestFPGABoot::test_detect_rse_uart (fixtures used: fpga_device, request).
         tests/test_fpga_boot.py::TestFPGABoot::test_any_uart_contains_el3_exit (fixtures used: fpga_device, request).
         tests/test_fpga_boot.py::TestFPGABoot::test_detect_linux_uart (fixtures used: fpga_device, request).
         tests/test_fpga_boot.py::TestFPGABoot::test_uart_mapping_summary (fixtures used: fpga_device, request).
   TEARDOWN S fpga_device

   =============================================== 9 passed in 545.37s (0:09:05) ================================================

The sample test typically completes within 9-10 minutes on a standard host
system (but may vary depending on host system performance).

During execution, the framework:

- Establishes an SSH connection.
- Uploads the payload archive.
- Launches the configured boot command.
- Detects the RUN_DIR.
- Logs in automatically after detecting the login prompt.
- Downloads the complete RUN_DIR logs after execution.

Add New Test Cases for FPGA
***************************

FPGA tests use the ``fpga_device`` fixture and validate behavior using
boot artifacts, UART logs, and remote execution utilities.

Example:

.. code-block:: python

   class TestMyFPGAExample:
       def test_boot_artifacts_present(self, fpga_device):
           run_dir = fpga_device.get_run_dir()
           assert run_dir
           bootlog = fpga_device.log_path()
           assert bootlog.exists()
           assert bootlog.stat().st_size > 0

.. note::

   - Refer to the common "Add New Test Cases" section for generic test structure guidance.
   - Use ``fpga_device`` for FPGA-specific test flows.
   - Prefer existing FPGA helper methods such as ``get_run_dir()``,
     ``log_path()``, ``run_sample_command()``, and ``get_login_uart()`` where applicable.
   - Use ``fpga_device.net`` helpers for UART log scanning and remote log inspection.