blob: 43282ef566ccae272de5295d474ff31c4789527d [file] [log] [blame]
#
# This file specifies defaults so the testcase running system knows
# how to build Zephyr apps.
#
# It looks all like comments so that it can also put this stuff inside
# Makefiles, shell scripts, python, C, etc...
#
# Things like:
#
## ^COMMAND ARGUMENTS
## @COMMAND ARGUMENTS
#
# are what the parser looks for. ^COMMAND means that if it fails or
# block, the list of COMMANDs will not continue being executed, @
# means the next commands still will be executed. Note the ## is so
# that the parser doesn't interpret it as a command, as we are
# documenting it.
# Variables
# ---------
#
# Every %(VARIABLE)s you are going to use or maybe override has to be
# defined; otherwise it'll throw a KeyError exception on you.
#
# Some are pre-filled by the system (see below), but others are
# user-defined and some test cases make use of it, so we define a
# default value (empty) here:
#
# @var extra_args
# Building
# --------
#
# - we always remove the configuration file to force it being
# re-generated. Why? because otherwise, in some cases,
# 'silentoldconfig' tries to update it with input from the user and
# fails. When it is not needed. So before we start mucking with it,
# remove it.
#
# - then we generate the init config -- why? because to filter which
# test cases we can run, we need to see if a CONFIG option is
# enabled or not.
#
# - We need to put the output of the compilation on a directory
# specific to the target and testcase we are building for because:
#
# - two targets, although the same hardware, might have differences
# that could be or not specified in the target's tags.
#
# - multiple paralallel builds for the same testcase PATH with
# different testcase names (especially those coming from
# testcase.ini) files can collide with each other.
#
# Thus is the `%(tchash)s` substitution, which is a unique hash
# for a combination of the testcase name, the target and the
# bsp_model.
# (1) First build step to generate the configuration:
#
# ^build \
# rm -f %(srcdir)s/outdir-%(tchash)s-%(board)s/.config; \
# mkdir -p %(srcdir)s/outdir-%(tchash)s-%(board)s; \
# make -j -C %(srcdir)s/ %(extra_args)s \
# BOARD=%(board)s O=outdir-%(tchash)s-%(board)s \
# initconfig
#
# Once we have the configuration generated, for Sanity Check test
# cases (and others) evaluate if we have to run or not based on
# configuration values. This is done by a Python function
# (tcfl.tc_tci.action_eval_skip). This looks at CONFIG_ options
# and decides if we are to skip for any reason.
#
# ^build @tcfl.tc_tci.action_eval_skip %(srcdir)s/outdir-%(tchash)s-%(board)s
# (2) Support for building/running multiple core SOC/platforms (like
# Quark SE); each core is called 'a BSP'.
#
# Some targets have multiple BSPs and need a stub in BSP1 for BSP2
# to work independently, so these first @build rules take care of
# that. How we handle this might change in the future.
#
# The hack for altering the configuration is dirty. Looking for
# better ones.
# (2.1) For running on Quark SE ARC only, we need to make a stub for
# the x86 core to pipe the serial from/to the ARC. It has to
# also be deployed, so we add said kernel to @images.
#
# (a) Arduino 101
#
# @build [ type == "arduino101" and quark_se_stub == 'yes' and bsp_model == 'arc' ] \
# rm -f %(srcdir_abs)s/outdir-%(tchash)s-stub-x86-arduino_101/.config; \
# make -j -C $ZEPHYR_BASE/samples/stub \
# BOARD=arduino_101 \
# O=%(srcdir_abs)s/outdir-%(tchash)s-stub-x86-arduino_101
#
# @images [ type == "arduino101" and quark_se_stub == 'yes' and bsp_model == 'arc'] \
# kernel-x86:%(srcdir)s/outdir-%(tchash)s-stub-x86-arduino_101/zephyr.bin
#
# (b) For Quark SE Devboard v1
#
# @build [ type == "ah" and quark_se_stub == 'yes' and bsp_model == 'arc' ] \
# rm -f %(srcdir_abs)s/outdir-%(tchash)s-stub-x86-quark_se_devboard/.config; \
# make -j -C $ZEPHYR_BASE/samples/stub \
# BOARD=quark_se_devboard \
# O=%(srcdir_abs)s/outdir-%(tchash)s-stub-x86-quark_se_devboard
#
# @images [ type == "ah" and quark_se_stub == 'yes' and bsp_model == 'arc'] \
# kernel-x86:%(srcdir)s/outdir-%(tchash)s-stub-x86-quark_se_devboard/zephyr.bin
#
# (c) For Quark SE Devboard
#
# @build [ type == "ma" and quark_se_stub == 'yes' and bsp_model == 'arc' ] \
# rm -f %(srcdir_abs)s/outdir-%(tchash)s-stub-x86-quark_se_devboard/.config; \
# make -j -C $ZEPHYR_BASE/samples/stub \
# BOARD=quark_se_devboard \
# O=%(srcdir_abs)s/outdir-%(tchash)s-stub-x86-quark_se_devboard
#
# @images [ type == "ma" and quark_se_stub == 'yes' and bsp_model == 'arc'] \
# kernel-x86:%(srcdir)s/outdir-%(tchash)s-stub-x86-quark_se_devboard/zephyr.bin
#
# (2.2) On Quark SE, when running the x86 core only we need to make
# sure the kernel doesn't wait for the ARC to initialize. So we
# do the initial config, pluck the CONFIG_ARC_INIT away and
# reconfigure before compiling. UGLY, but it works
#
# @build [ quark_se_stub == 'yes' and bsp_model == 'x86' ] \
# sed -i 's/^CONFIG_ARC_INIT.*//' \
# %(srcdir)s/outdir-%(tchash)s-%(board)s/.config; \
# make -j -C %(srcdir)s/ %(extra_args)s \
# BOARD=%(board)s O=outdir-%(tchash)s-%(board)s \
# olddefconfig
# (2.3) If we are running both cores at the same time, make sure
# ARC_INIT is set
#
# @build [ quark_se_stub == 'yes' and bsp_model == 'x86+arc' ] \
# echo CONFIG_ARC_INIT=y >> \
# %(srcdir)s/outdir-%(tchash)s-%(board)s/.config; \
# make -j -C %(srcdir)s %(extra_args)s \
# BOARD=%(board)s O=outdir-%(tchash)s-%(board)s \
# %(extra_args)s olddefconfig
# (2.4) Now the basic build and deploy commands that apply to all the
# platforms
#
# Note: we pass a RUNID that is a compositon of the RunID passed
# with '-i' to 'tcf run' (if passed) TCHASH (which is
# unique hash of the target and testcase name) -- this
# ensures that succesive test cases ran in the same target
# will have a different TC_RUNID. We will in
# tests/.tcdefaults (when using TC_PRINT_RUNID /
# TC_END_REPORT) to verify that the right image has been
# deployed to the target.
#
# @build \
# make -j -C %(srcdir)s %(extra_args)s \
# KCPPFLAGS=-DTC_RUNID=%(runid)s:%(tchash)s \
# BOARD=%(board)s O=outdir-%(tchash)s-%(board)s
#
# And deploy the kernel we just built
#
# @images kernel-%(bsp)s:%(srcdir)s/outdir-%(tchash)s-%(board)s/%(kernelname)s
# Cleaning up
# -----------
#
# This is only invoked when you give `--clean` or `-L` to `tcf run`
#
# @clean rm -rf %(srcdir)s/outdir-%(tchash)s-*
# Evaluation of the test case
# ---------------------------
#
# These are the steps performed to evaluate a test case / sample for
# success in execution. In here we only list the general ones that
# apply to all of them, but each testcase will have it's specific
# ones.
#
# (1) In general, before evaluating, reset/power-cycle/resume the
# target.
#
# `one-shot` means only once if we are running multiple BSPs and fail
# inmediately if it doesn't work):
#
# ^eval [ type:"(?!^emsk.*)" ] target-reset one-shot
#
# EMSKs get their firmware loaded into RAM; if we do a full reset,
# it is wiped, so we just do a raw reset (which means a CPU reset
# in this case) and resume
#
# ^eval [ type:"^emsk.*" ] debug-reset-halt one-shot
# ^eval [ type:"^emsk.*" ] debug-resume one-shot
#
# (2) Fail inmmediately (^) if we find these messages, that's bad
# stuff happening in the kernel.
#
# ^eval console-rx %(console)s::fail USAGE FAULT
# ^eval console-rx %(console)s::fail fatal fault in fiber
#
# For testcases under tests/, the .tcdefaults in there adds more steps
# to verify; test cases are picked up based on their
# testcase.ini. Each test case is then free to add more, if
# needed. Note than in samples, most of that information is going to
# be in .tc files.