#
# 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 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.
#
# - HACK: ARCH is specified, when it should not be needed to, because
#   of current limitations of the Zephyr build system on resolving
#   ARCH from the BOARD specification. This is an historical carry
#   over that eventually should be cleared
#   (https://jira.zephyrproject.org/browse/ZEP-690 and
#   https://jira.zephyrproject.org/browse/ZEP-754).
#
# 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) Remove the existing config file
#
#     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.
#
# ^build \
#   mkdir -p %(srcdir)s/outdir-%(tchash)s-%(board)s; \
#   rm -f %(srcdir)s/outdir-%(tchash)s-%(board)s/.config

# (2) prepare the configuration for Quark SE / ARC BSPs
#
# (2.1) 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 "# Generated by Zephyr's TCF defaults.tc"   > %(srcdir)s/outdir-%(tchash)s-%(board)s/tcf_2.1.conf; \
#   echo 'CONFIG_ARC_INIT=y'                        >> %(srcdir)s/outdir-%(tchash)s-%(board)s/tcf_2.1.conf

# (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.
#
# @build [ quark_se_stub == 'yes'  and bsp_model == 'x86' ] \
#   echo "# Generated by Zephyr's TCF defaults.tc"  > %(srcdir)s/outdir-%(tchash)s-%(board)s/tcf_2.2.conf; \
#   echo 'CONFIG_ARC_INIT=n'                       >> %(srcdir)s/outdir-%(tchash)s-%(board)s/tcf_2.2.conf

# (2.3) To run only in the ARC core in certain Quark SE platforms, we need a
#       stub in the x86 core to start the ARC CPU.
#
#       It has to also be deployed, so we add said kernel to @images.
#
# (2.3.1) 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/tests/booting/stub \
#       BOARD=arduino_101 ARCH=x86 \
#       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
#
# (2.3.2) 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_c1000_devboard/.config; \
#   make -j -C $ZEPHYR_BASE/tests/booting/stub \
#       BOARD=quark_se_c1000_devboard \
#       O=%(srcdir_abs)s/outdir-%(tchash)s-stub-x86-quark_se_c1000_devboard
#
# @images [ type == "ah" and quark_se_stub == 'yes' and bsp_model == 'arc'] \
#   kernel-x86:%(srcdir)s/outdir-%(tchash)s-stub-x86-quark_se_c1000_devboard/zephyr.bin
#
# (2.3.3) 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_c1000_devboard/.config; \
#   make -j -C $ZEPHYR_BASE/tests/booting/stub \
#       BOARD=quark_se_c1000_devboard \
#       O=%(srcdir_abs)s/outdir-%(tchash)s-stub-x86-quark_se_c1000_devboard
#
# @images [ type == "ma" and quark_se_stub == 'yes' and bsp_model == 'arc'] \
#   kernel-x86:%(srcdir)s/outdir-%(tchash)s-stub-x86-quark_se_c1000_devboard/zephyr.bin
#
# (2.3.4) When running the ARC in Quark SE, we redirect the output to the
#         UART_1 (the same as the x86) to simplify the test setup (no
#         need to connect multiple console cables)
#
#         However, this makes it impossible to run independent test cases
#         at the same time (BSP model x86+arc) because they'd interfere
#         with each other.
#
# ^build [ quark_se_stub == 'yes'  and bsp == 'arc' ] \
#   echo "# Generated by Zephyr's TCF defaults.tc"   > %(srcdir)s/outdir-%(tchash)s-%(board)s/tcf_2.3.4.conf; \
#   echo 'CONFIG_UART_CONSOLE_ON_DEV_NAME="UART_1"' >> %(srcdir)s/outdir-%(tchash)s-%(board)s/tcf_2.3.4.conf
#
# (2.3.5) Quark SE: run test cases on x86 or ARC modes by default
#
#         This applies to test cases that are designed to run only in
#         one core, as Quark SE will share one serial port in our test
#         setup and the outputs will conflict and be a mess.
#
#         Test cases that need to run in both cores (BSP MODEl
#         x86+arc) can still request it by tagging '@targets
#         bsp_model:x86\+arc'
#
# @targets [ quark_se_stub == 'yes' ] bsp_model:^(x86|arc)$

# (3) Generate the initial configuration
#
#     Because to filter which test cases we can run, we need to see if
#     a CONFIG option is enabled or not.
#
# ^build \
#   make -j -C %(srcdir)s/ %(extra_args)s \
#       BOARD=%(board)s ARCH=%(bsp)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

# (4) General build and deploy commands that apply to all 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 ARCH=%(bsp)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 [Ff]atal fault in
# ^eval console-rx   %(console)s::fail Fatal essential task error
# ^eval console-rx   %(console)s::fail Fatal task error!
#
# 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.