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 read 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 use
- the GitHub CLI, e.g.,
```
gh repo fork ssh://git@github.com/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

gh repo clone sca3s-harness ./sca3s-harness -- -b sca3s

or

git itself, e.g.,

git clone -b sca3s https://github.com/${USER}/sca3s-harness.git ./sca3s-harness

where in both cases, the specific tag sca3s is checked-out.

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 type 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.

Edit
```
${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.manifest
```
to specify any additional files that supplement and thus support the implementation.

Step 5: build target implementation

Decide on the board type 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

for a native build context, execute

make CONTEXT="native"      clean-harness
make CONTEXT="native" deps-fetch-harness
make CONTEXT="native" deps-patch-harness
make CONTEXT="native" deps-build-harness
make CONTEXT="native"      build-harness

or

for a Docker-based build context, execute

make CONTEXT="docker"      clean-harness
make CONTEXT="docker"      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

Option #1: local use

If you don't have a physical board:
- Using the native board type implies use of the default GCC compiler, i.e., gcc, available in ${PATH}; the native build context performs the build process on the native, host platform.
- As such, this configuration will produce ${REPO_HOME}/build/native/target.elf which is executable on the host platform: execute it via
```
${REPO_HOME}/build/native/target.elf
```
  noting that interaction with it is explained by the driver documentation.
- Assuming the target implementation has no board-specific content (e.g., assembly language), this approach offers a relatively light-weight development method in the sense the whole development cycle is local.
If you do have a physical board:
- The build process will have produced various object files, e.g.,
```
${REPO_HOME}/build/${BOARD}/target.elf
${REPO_HOME}/build/${BOARD}/target.bin
${REPO_HOME}/build/${BOARD}/target.hex
```
- Using the appropriate programming infrastructure, you can program your board with one of them.

Option #2: remote, manual use via the web-based interface

Navigate to the SCA3S web-based interface.
Verify that the user repository is listed under the Profile menu item.
Submit an acquisition job (i.e., a request to generate a data set from the repository) via the Acquire\Submit Job menu item, selecting the user repository from the drop-down list in the Repository Information section.

Option #3: remote, automatic use via the 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, per the kernel documentation, CI is only possible for certain configurations.
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.
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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly