Package: arm-avhclient
Arm Virtual Hardware Client (avhclient)TheArm Virtual Hardware Client(avhclient) is a python module that provides an interface for deploying and usingArm Virtual Hardware (AVH).It enables uniform implementation of CI operations in various environments with reference examples provided for the following use cases:Jenkins CI pipelinesGitHub-Actions workflowsLocal use with AVH targetsOther environments can be supported using demonstrated concepts as well.Example projects using AVH ClientAVH-GetStartedCMSIS-RTOS2-ValidationTensorFlow Lite for MicrocontrollersInstallationLocal installationInstalling (development snapshot) directly from GitHubmainbranch:pip install git+https://github.com/ARM-software/avhclient.git@mainDocker containerInstead 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/avhclientBackend Setupavhclient can control different backends with Arm Virtual Hardware. Following options are currently available:aws(default) - interacts with AVH AMI available throughAWS Marketplacelocal- operates with AVH Targets installed locally.The backend can be specified with-boption preceding the actual avhclient command.Depending on the backend certain environment setup is expected.AWS Backend Setupavhclient accesses AWS services viaBoto3 AWS SDKand for that requires a set of parameters to be available in the environment.AWS CredentialsIt is necessary to expose avhclient with the AWS credentials for your account.
You can eitherexportyour 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%.awscredentials (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_TOKENMore infoAWS CLI config and credentialsAWS Account infoIn 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 anew 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_INSTANCEIfAWS_AMI_VERSIONis not set, the avhclient will use the latest available version of AVH AMI.IfAWS_EFS_DNS_NAMEis set, the AVH Client will try to mount it during the cloud-init phase. The only scenario supported for now is using Packs.IfAWS_EFS_PACKS_DIRis set, the mount path is relative to/home/ubuntufolder. Default folder ispacksand if it exists locally will be then replaced by the EFS mount. Only used whenAWS_EFS_DNS_NAMEenv is set.AWS Cloudformation can be used to create the AWS resources required for AVH operation, as shownin this templateWhenreusing an AVH Instance:export AWS_INSTANCE_ID=YOUR_INSTANCELocal Backend SetupOperation 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.UsageGetting HelpTo get the brief descriptions of all commands and options available with avhclient execute:avhclient -hYou can also use option-hwith a specific command to get help for it. For example forexecutecommand:avhclient execute -hExecute commandCreate a new AWS AVH instance and run AVH projectTheexecutecommand bundles all necessary steps to build your
avh project:preparethe backend.uploadyour filesrunyour commandsdownloadthe resultscleanupthe backendInform the path for theavh.ymlfile for your AVH project (example):avhclient -b aws execute --specfile AVH-GetStarted/basic/avh.ymlYou can also run in AVH commands in your local computer by selectinglocalbackend:avhclient -b local execute --specfile AVH-GetStarted/basic/avh.ymlThere 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 DockerTo 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_NAMEThis environment file is used to forward the local environment variables into
the Docker container. Having this prepared one can runavhclientin 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 syntaxavhclientexecutecommand 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 inschema/avh.schema.json.FieldsFormat 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# 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