1.1.3.1.1.1.2. test_automation.targets.fpga.fpga_controller

1.1.3.1.1.1.2.1. Attributes

logger

1.1.3.1.1.1.2.2. Classes

FPGAPlatformConfig	Structured configuration for an FPGA platform session.
FPGAController	FPGA controller implementing the Device interface.

1.1.3.1.1.1.2.3. Functions

load_fpga_controller_from_yaml(yaml_path, platform_name)

Create an FPGAController instance from a YAML configuration file.

1.1.3.1.1.1.2.4. Module Contents

test_automation.targets.fpga.fpga_controller.logger

class test_automation.targets.fpga.fpga_controller.FPGAPlatformConfig

Structured configuration for an FPGA platform session.

Parameters:

• platform_name – Logical platform name used for log directory naming.

• host – Remote hostname or IP address of the FPGA host.

• username – SSH username.

• password – Optional SSH password for password or interactive auth.

• port – SSH port.

• connect_timeout_s – SSH connection/auth timeout in seconds.

• ready_timeout_s – Timeout (seconds) for readiness checks.

• login_timeout_s – Timeout (seconds) for UART login detection and establishing a shell prompt.

• hpc_env_setup – Sequence of shell commands used to set up environment before launching the remote boot command.

• remote_cmd – Remote command used to start FPGA boot/run.

• remote_payload_path – Optional remote path to upload/extract a payload archive into.

• local_payload_path – Optional local archive path to upload to the remote host.

• log_dir – Optional override base directory for logs.

• log_prefix – Optional override prefix for log directory naming.

platform_name: str

host: str

username: str

password: str | None

port: int

connect_timeout_s: int

ready_timeout_s: int

login_timeout_s: int

hpc_env_setup: Sequence[str]

remote_cmd: str

remote_payload_path: str | None = None

local_payload_path: str | None = None

log_dir: str | None = None

log_prefix: str | None = None

class test_automation.targets.fpga.fpga_controller.FPGAController(cfg)

Bases: test_automation.utils.device.Device

FPGA controller implementing the Device interface.

This controller manages the lifecycle of a remote FPGA session over SSH. It is responsible for connecting to the FPGA host, optionally uploading required binaries, launching the configured remote command, monitoring system readiness, handling automated UART login, and exposing runtime state and logs to the test framework.

Parameters:

cfg (FPGAPlatformConfig)

cfg

net

_running = False

_login_uart: Tuple[str, int, int] | None = None

init()

Establish an SSH connection to the FPGA host.

Returns:

None

Raises:

RuntimeError – If SSH connectivity/authentication fails.

Return type:

None

start()

Start the FPGA boot workflow and login as root.

This method: - Launches the command in the background on the remote host - Waits for a login prompt on the UART - Sends the root login - Marks the controller as running

Returns:

None

Raises:

• RuntimeError – If not connected or login UART cannot be established.

• TimeoutError – If login prompt or shell prompt is not detected within configured timeout.

Return type:

None

stop()

Stop the FPGA run and collect logs.

This method attempts to wait briefly for remote command to exit, then downloads the current RUN_DIR logs into:

<CWD>/logs/<platform>_<timestamp>/remote_run_logs/

Finally, it disconnects the SSH session regardless of outcome.

Returns:

None

Return type:

None

reset()

Reset the FPGA by stopping and restarting the controller.

This is equivalent to calling stop(), init(), and start()

in sequence.

Returns:

None

Return type:

None

wait_ready(timeout_s=None)

Wait until the FPGA run directory is created.

This method blocks until remote command creates the RUN_DIR on the remote host, indicating that the FPGA boot has progressed far enough to be considered ready.

Parameters:

timeout_s (Optional[int]) – Maximum time to wait in seconds. If None, a default timeout is used.

Returns:

None

Return type:

None

is_running()

Check whether the FPGA controller is currently running.

Returns:

True if the controller is running, False otherwise.

Return type:

bool

get_ports()

Return exposed service ports for the FPGA. FPGA platforms do not currently expose network service ports.

Returns:

An empty mapping.

Return type:

Dict[str, int]

log_path()

Return the primary local boot log path.

Returns:

Path to the boot log file, or a fallback logs directory if unavailable.

Return type:

pathlib.Path

get_run_dir()

Return the remote run directory.

Returns:

Path to the RUN_DIR on the remote host, or None if unavailable.

Return type:

Optional[str]

get_login_uart()

Return UART details for the active login session.

Returns:

A tuple of (uart_log_path, vuart, pts).

Raises:

RuntimeError – If the login UART has not been established.

Return type:

Tuple[str, int, int]

run_sample_command(command)

Execute a command on the logged-in UART session.

Parameters:

command (str) – Shell command to execute.

Returns:

None

Return type:

None

test_automation.targets.fpga.fpga_controller.load_fpga_controller_from_yaml(yaml_path, platform_name, host=None)

Create an FPGAController instance from a YAML configuration file.

Parameters:

• yaml_path (pathlib.Path) – Path to the YAML configuration file.

• platform_name (str) – Name of the platform entry to load.

• host (Optional[str]) – Optional override host name/IP. If not provided, the YAML platform object’s host attribute is used.

Returns:

Constructed FPGAController instance.

Raises:

ValueError – If host cannot be resolved.

Return type:

FPGAController