# avhclient

**Repository Path**: mirrors_ARM-software/avhclient

## Basic Information

- **Project Name**: avhclient
- **Description**: DEPRECATED: Arm Virtual Hardware Client
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-04-02
- **Last Updated**: 2026-05-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

DEPRECATED
==========

Use the `Foundation Components for MLOps Systems <https://github.com/ARM-software/AVH-MLOps/tree/main>`_ or `Arm-Examples/AVH_CI_Template <https://github.com/Arm-Examples/AVH_CI_Template>`_ instead.

For more information refer to the `AVH-FVP documentation - Infrastructure <https://arm-software.github.io/AVH/main/infrastructure/html/index.html>`_.

-----

|build-badge| |test-badge| |cov-badge| |python-badge|
|wheel-badge| |pypi-badge| |license-badge|

.. |build-badge| image:: https://img.shields.io/github/workflow/status/ARM-software/avhclient/Build/main?style=flat
    :target: https://github.com/ARM-software/avhclient/actions/workflows/build.yml?query=event%3Apush+branch%3Amain+is%3Acompleted
    :alt: GitHub main-branch Build Workflow Status
.. |test-badge| image:: https://img.shields.io/testspace/tests/ARM-software/ARM-software:avhclient/main?compact_message
    :target: https://ARM-software.testspace.com/spaces/156681
    :alt: Unit tests results
.. |cov-badge| image:: https://img.shields.io/codecov/c/github/ARM-software/avhclient?style=flat
    :target: https://app.codecov.io/gh/ARM-software/avhclient/branch/main
    :alt: Codecov coverage report
.. |python-badge| image:: https://img.shields.io/pypi/pyversions/arm-avhclient?style=flat
    :target: https://pypi.org/project/arm-avhclient/
    :alt: PyPI - Python Version
.. |wheel-badge| image:: https://img.shields.io/pypi/wheel/arm-avhclient?style=flat
    :target: https://pypi.org/project/arm-avhclient/
    :alt: PyPI - Wheel
.. |pypi-badge| image:: https://img.shields.io/pypi/v/arm-avhclient?style=flat
    :target: https://pypi.org/project/arm-avhclient/
    :alt: PyPI
.. |license-badge| image:: https://img.shields.io/pypi/l/arm-avhclient?style=flat
    :target: https://pypi.org/project/arm-avhclient/
    :alt: PyPI - License

Arm Virtual Hardware Client (avhclient)
=======================================

The **Arm Virtual Hardware Client** (avhclient) is a python module that provides an interface for deploying and using  `Arm Virtual Hardware (AVH) <https://www.arm.com/products/development-tools/simulation/virtual-hardware>`_.

It enables uniform implementation of CI operations in various environments with reference examples provided for the following use cases:

* Jenkins CI pipelines
* GitHub-Actions workflows
* Local use with AVH targets

Other environments can be supported using demonstrated concepts as well.

**Example projects using AVH Client**

* `AVH-GetStarted <https://github.com/ARM-software/AVH-GetStarted>`_
* `CMSIS-RTOS2-Validation <https://github.com/ARM-software/CMSIS-RTOS2_Validation>`_
* `TensorFlow Lite for Microcontrollers <https://github.com/tensorflow/tflite-micro>`_

****

Installation
------------

Local installation
##################

Installing (development snapshot) directly from GitHub `main` branch::

    pip install git+https://github.com/ARM-software/avhclient.git@main
    
Docker container
################

Instead of installing Python and the AVH Client module into the local environment one
can use pre-built Docker images::

   docker pull ghcr.io/arm-software/avhclient

****

Backend Setup
-------------
avhclient can control different backends with Arm Virtual Hardware. Following options are currently available:

* ``aws`` (default) - interacts with AVH AMI available through `AWS Marketplace <https://arm-software.github.io/AVH/main/infrastructure/html/index.html#AWS>`_
* ``local`` - operates with AVH Targets installed locally.

The backend can be specified with ``-b`` option preceding the actual avhclient command.

Depending on the backend certain environment setup is expected.

AWS Backend Setup
#################

avhclient accesses AWS services via `Boto3 AWS SDK <https://github.com/boto/boto3>`_ and for that requires a set of parameters to be available in the environment.

AWS Credentials
***************
It is necessary to expose avhclient with the AWS credentials for your account.
You can either `export` your AWS credentials::

    export AWS_ACCESS_KEY_ID="YOUR_AWS_ACCESS_KEY_ID"
    export AWS_SECRET_ACCESS_KEY="YOUR_AWS_SECRET_ACCESS_KEY"
    export AWS_SESSION_TOKEN="YOUR_AWS_SESSION_TOKEN"

or create a AWS credential file on `~/.aws/credentials (Linux & Mac)` or `%USERPROFILE%\.aws\credentials (Windows)`::

    [default]
    aws_access_key_id=YOUR_AWS_ACCESS_KEY_ID
    aws_secret_access_key=YOUR_AWS_SECRET_ACCESS_KEY
    aws_session_token=YOUR_AWS_SESSION_TOKEN

More info `AWS CLI config and credentials <https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html>`_

AWS Account info
****************
In order for avhclient to create or access an AVH instance following parameters need to be defined in the execution environment of avhclient:

* When creating and running a **new AVH instance**:
    Mandatory info::

        export AWS_IAM_PROFILE='YOUR_IAM_PROFILE'
        export AWS_SECURITY_GROUP_ID='YOUR_AWS_SECURITY_GROUP_ID'
        export AWS_SUBNET_ID='YOUR_SECURITY_GROUP_ID'
        export AWS_S3_BUCKET_NAME='YOUR_B3_BUCKET_NAME'

    Optional info (examples)::

        export AWS_AMI_ID=DESIRED_AVH_AMI_ID
        export AWS_AMI_VERSION=1.1.2
        export AWS_EFS_DNS_NAME=fs-066cf410af2428e2f.efs.eu-west-1.amazonaws.com
        export AWS_EFS_PACKS_DIR=packs
        export AWS_KEEP_EC2_INSTANCES=true
        export AWS_KEY_NAME=YOUR_AWS_KEYPAIR_NAME
        export AWS_INSTANCE_TYPE=t2.micro
        export AWS_INSTANCE_NAME=MY_AVH_INSTANCE

    * If ``AWS_AMI_VERSION`` is not set, the avhclient will use the latest available version of AVH AMI.
    * If ``AWS_EFS_DNS_NAME`` is set, the AVH Client will try to mount it during the cloud-init phase. The only scenario supported for now is using Packs.
    * If ``AWS_EFS_PACKS_DIR`` is set, the mount path is relative to ``/home/ubuntu`` folder. Default folder is `packs` and if it exists locally will be then replaced by the EFS mount. Only used when ``AWS_EFS_DNS_NAME`` env is set.

    AWS Cloudformation can be used to create the AWS resources required for AVH operation, as shown `in this template <https://github.com/ARM-software/AVH-GetStarted/tree/main/infrastructure/cloudformation>`_

* When **reusing an AVH Instance**::

    export AWS_INSTANCE_ID=YOUR_INSTANCE

Local Backend Setup
###################

Operation with a local backend requires no specific environment parameters, but assumes that necessary toolchain, AVH targets and utilities are installed locally on the machine and configured for execution in command line.

****

Usage
-----

Getting Help
############

To get the brief descriptions of all commands and options available with avhclient execute::

    avhclient -h

You can also use option ``-h`` with a specific command to get help for it. For example for ``execute`` command::

    avhclient execute -h

Execute command
###############

* Create a new AWS AVH instance and run AVH project
    The ``execute`` command bundles all necessary steps to build your
    avh project:

    * ``prepare`` the backend.
    * ``upload`` your files
    * ``run`` your commands
    * ``download`` the results
    * ``cleanup`` the backend

    Inform the path for the `avh.yml` file for your AVH project (example)::

        avhclient -b aws execute --specfile AVH-GetStarted/basic/avh.yml

* You can also run in AVH commands in your local computer by selecting `local` backend::

        avhclient -b local execute --specfile AVH-GetStarted/basic/avh.yml

* There are also backend specific info you can provide to the tool::

        avhclient -b aws -h (get full list)
        avhclient -b aws --instance-name MY_NEW_NAME execute --specfile AVH-GetStarted/basic/avh.yml (seeting a new AVH instance name)
        avhclient -b aws --ami-version 1.1.0 --specfile AVH-GetStarted/basic/avh.yml (Create a new AVH instance from a v1.1.0 AVH AMI)
        avhclient -b aws --ami-version >1.1.0 --specfile AVH-GetStarted/basic/avh.yml (Create a new AVH instance from a >v1.1.0 AVH AMI)

Execute with Docker
###################

To run avhclient in a Docker container one needs to create an environment file
(``env.txt``) with the following content::

    AWS_ACCESS_KEY_ID
    AWS_SECRET_ACCESS_KEY
    AWS_IAM_PROFILE
    AWS_SECURITY_GROUP_ID
    AWS_SUBNET_ID
    AWS_S3_BUCKET_NAME
    AWS_DEFAULT_REGION
    AWS_AMI_ID
    AWS_AMI_VERSION
    AWS_KEEP_EC2_INSTANCES
    AWS_KEY_NAME
    AWS_INSTANCE_TYPE
    AWS_INSTANCE_NAME

This environment file is used to forward the local environment variables into
the Docker container. Having this prepared one can run ``avhclient`` in a
container as follows::

    docker run --rm -i --env-file ./env.txt \
        -v $(pwd):/workspace \
        -w /workspace \
        ghcr.io/arm-software/avhclient \
        avhclient [..]

The arguments are the same as above. If one requires more files from the Docker
host to be mapped into the container, this can be done like::

    docker run --rm -i --env-file ./env.txt \
        -v $HOME/.ssh:/root/.ssh \
        -v $HOME/.aws:/root/.aws \
        -v $(pwd):/workspace \
        -w /workspace \
        ghcr.io/arm-software/avhclient \
        avhclient [..]

This exposes the local user's SSH and AWS config files to the container.

****

AVH YML file syntax
-------------------

avhclient ``execute`` command requires a specfile in YML format that describes details of individual steps to be executed on AVH. The file syntax is explained below.

A JSON schema for automatic checks and auto-completion is in `schema/avh.schema.json <schema/avh.schema.json>`_.

Fields
######

.. code-block::

        Format of the specfile:
                name: (optional) The name of the workload.
                workdir: (optional) The local directory to use as the workspace, defaults to specfile's parent.
                backend: (optional) Dictionary with backend specific parameters.
                  aws: (optional) Dictionary with AWS backend specific parameters. (see backend help)
                  local: (optional) Dictionary with local backend specific parameters. (see backend help)
                upload: (optional) List of glob patterns of files (relative to workdir) to be sent to the AVH backend. (see glob format)
                steps: (mandatory) List of steps to be executed on the AVH backend.
                  - run: String written into a bash script and executed on the AVH backend inside the workspace directory.
                download: (optional) List of glob patterns of files (relative to workdir) to be retrieved back from the AVH backend. (see glob format)
            Glob format:
                The list of glob patterns is evaluated in order.
                Wildcard '*' matches all files but no directory except hidden files (starting with '.').
                Wildcard '**' matches all files and directories except hidden files/directories (starting with '.').
                Inclusive matches (no prefix) are added to the file list.
                Exclusive (prefixed with '-:') matches are removed from current file list.

Example
#######

.. code-block::

    # yaml-language-server: $schema=https://raw.githubusercontent.com/ARM-software/avhclient/main/schema/avh.schema.json

    name: "AVH GetStarted Example"
    workdir: ./
    backend:
      aws:
        ami-version: ~=1.1
        instance-type: t2.micro
    upload:
      - RTE/**/*
      - -:RTE/**/RTE_Components.h
      - basic.debug.cprj
      - build.py
      - main.c
      - requirements.txt
      - retarget_stdio.c
      - vht_config.txt
      - README.md
    steps:
      - run: |
          pip install -r requirements.txt
          python build.py --verbose build run
    download:
      - RTE/**/RTE_Components.h
      - Objects/basic.axf
      - Objects/basic.axf.map
      - basic-*.xunit
      - basic-*.zip