Workflow

Step 1: enroll

• Navigate to the SCA3S web-based interface; your login credentials are tied to your GitHub account.

• The first time you try to log in, you'll be prompted to install and authorise a GitHub App: this connects the SCA3S infrastructure to your GitHub account, e.g., allowing access to your repositories.

• You can verify the app has been installed, and, e.g., configure the access scope, via your GitHub settings.

Step 2: create user repository

• Either

  • the GitHub CLI, e.g.,

    gh repo fork ssh://[email protected]/scarv/sca3s-harness.git --clone='false'

    or

  • the GitHub UI, e.g., by

    • forking it, or
    • using it as a template.

Step 3: clone user repository

• Either use

  • the GitHub CLI, e.g.,

    gh repo clone sca3s-harness ./sca3s-harness

    noting that in the example above, it is possible to clone the repository at the same time as creating the fork, or

  • git itself, e.g.,

    git clone ssh://[email protected]/${USER}/sca3s-harness.git ./sca3s-harness

• Execute

  cd ./sca3s-harness
  source ./bin/conf.sh
  

  to configure the environment. For example, you should find that the REPO_HOME environment variable is set appropriately.

Step 4: develop target implementation

• Decide on the kernel your target implementation will include (the default is block); set the associated environment variable, e.g.,

  export KERNEL="block"

• Edit

  ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.h

  to specify parameters for the target implementation, noting that

  ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.h_harness

  is part of the provided harness and should remain unchanged.

• Edit

  ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.c

  to complete the target implementation itself, noting that

  ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.c_harness

  is part of the provided harness and should remain unchanged.

Step 5: build target implementation

• Decide on the board your target implementation will be built for (the default is giles); set the associated environment variable, e.g.,

  export BOARD="giles"

• Decide on the build context (the default is docker); set the associated environment variable, e.g.,

  export CONTEXT="docker"

• Either

  1. for a Docker-based build context, execute

     make      clean-harness
     make      build-harness

     or

  2. for a native build context, execute

     make      clean-harness
     make deps-fetch-harness
     make deps-build-harness
     make      build-harness

  which, if the build succeeds, should produce associated artifacts in ${REPO_HOME}/build/${BOARD}.

Step 6: commit target implementation

• Execute

  make         update

  to fetch and merge any changes from the upstream harness repository: it is important to do so, because a "stale" user repository might be rejected when later used.

• Execute

  git commit --all --message="updated target implementation"
  git push

  to commit and push all changes.

Step 7: use target implementation

Local

Remote: manual, web-based interface

• Navigate to the SCA3S web-based interface.

Remote: automatic, commit-based interface

• Automatic use is triggered by a commit into a specific branch in the user repository. There are two use-cases to consider, which involve the same mechanism and workflow, from a user perspective, but yield different outcomes:

  1. Submission of the target implementation to a CI-like process. This use-case means setting the branch identifier to

     export BRANCH="sca3s-ci"

     Note that CI is only possible for some kernels in some modes.

  2. Submission of the target implementation to a CTF-like contest. This use-case means setting the branch identifier to

     export BRANCH="sca3s-${CONTEST}"

     where ${CONTEST} denotes the contest name.

• Because there is no interaction with the user, the file

  ${REPO_HOME}/sca3s.json

  is used to capture configuration, e.g., environment variables, which would otherwise be set manually. For example, the default content

  { "BOARD" : "giles", "KERNEL" : "block", "CONF" : "" }

  means that automated use will match a case where the BOARD and KERNEL environment variables are manually set as above. Note that a contest-based branch, may cause such configuration to be overridden; the contest itself may relate to a specific board and/or kernel, for example, and therefore override those fields.

• For example:

  • Edit

    ${REPO_HOME}/sca3s.json

    to specify the configuration.

  • Execute

    git checkout -b ${BRANCH}

    to create a new branch.

  • Execute

    git commit --all --message="updated target implementation"
    git push

    to commit and push all changes, and thereby trigger use.