defaults.tc - third_party/github/zephyrproject-rtos/zephyr - Git at Google

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