xtensa-build-zephyr.py: fix error message. Simplify and clarify cadence environment variables

scripts/set_xtensa_params.sh

@@ -11,6 +11,9 @@
 #
 # Not all variables are used in all use cases. Some are.
 #
+# Find some information about XTENSA_SYSTEM and XTENSA_CORE in
+# ./scripts/xtensa-build-zephyr.py --help
+#
 # The variables used by Zephyr are duplicated in
 # xtensa-build-zephyr.py, please keep in sync!
 

scripts/xtensa-build-zephyr.py

@@ -167,24 +167,37 @@ def parse_args():
 	global args
 	global west_top
 	parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter,
-			epilog=("This script supports XtensaTools but only when installed in a specific\n" +
-				"directory structure, example:\n" +
-				"myXtensa/\n" +
-				"└── install/\n" +
-				"       ├── builds/\n" +
-				"       │   ├── RD-2012.5{}/\n".format(xtensa_tools_version_postfix) +
-				"       │   │   └── Intel_HiFiEP/\n" +
-				"       │   └── RG-2017.8{}/\n".format(xtensa_tools_version_postfix) +
-				"       │       ├── LX4_langwell_audio_17_8/\n" +
-				"       │       └── X4H3I16w2D48w3a_2017_8/\n" +
-				"       └── tools/\n" +
-				"               ├── RD-2012.5{}/\n".format(xtensa_tools_version_postfix) +
-				"               │   └── XtensaTools/\n" +
-				"               └── RG-2017.8{}/\n".format(xtensa_tools_version_postfix) +
-				"                   └── XtensaTools/\n" +
-			"$XTENSA_TOOLS_ROOT=/path/to/myXtensa ...\n" +
-
-			f"\nSupported platforms: {list(platform_configs)}"), add_help=False)
+			epilog=(
+
+f"""This script supports XtensaTools but only when installed in a specific directory
+structure where a single --xtensa-core is registered per --xtensa-system registry, example
+below. Different layouts may or may not work.
+
+myXtensa/
+└── install/
+       ├── builds/
+       │   ├── RD-2012.5{xtensa_tools_version_postfix}
+       │   │   └── Intel_HiFiEP/config/        # XTENSA_SYSTEM registry
+       │   │        ├── default-params
+       │   │        └── Intel_HiFiEP-params    # single, default XTENSA_CORE per registry
+       │   └── RG-2017.8{xtensa_tools_version_postfix}
+       │       ├── LX4_langwell_audio_17_8/config/
+       │       │    ├── default-params
+       │       │    └── LX4_langwell_audio_17_8-params
+       │       └── X4H3I16w2D48w3a_2017_8/config/
+       │           ├── default-params
+       │           └── X4H3I16w2D48w3a_2017_8-params
+       └── tools/
+               ├── RD-2012.5{xtensa_tools_version_postfix}
+               │   └── XtensaTools
+               └── RG-2017.8{xtensa_tools_version_postfix}
+                   └── XtensaTools/
+
+$XTENSA_TOOLS_ROOT=/path/to/myXtensa ...
+
+Supported platforms: {list(platform_configs)}"""
+
+			), add_help=False)
 
 	parser.add_argument('-h', '--help', action='store_true', help='show help')
 	parser.add_argument("-a", "--all", required=False, action="store_true",
@@ -743,25 +756,36 @@ def build_platforms():
 			xtensa_tools_root_dir = pathlib.Path(xtensa_tools_root_dir)
 			if not xtensa_tools_root_dir.is_dir():
 				raise RuntimeError(f"Platform {platform} uses Xtensa toolchain."
-					"\nVariable XTENSA_TOOLS_VERSION points path that does not exist\n"
-					"or is not a directory")
+					f"\nVariable XTENSA_TOOLS_ROOT={xtensa_tools_root_dir} points "
+					"to a path that does not exist or is not a directory")
 
-			# set variables expected by zephyr/cmake/toolchain/xcc/generic.cmake
+			# Set environment variables expected by
+			# zephyr/cmake/toolchain/x*/*.cmake.  Note CMake cannot set (evil)
+			# build-time environment variables at configure time:
+			# https://gitlab.kitware.com/cmake/community/-/wikis/FAQ#how-can-i-get-or-set-environment-variables
+
+			# Top-level "switch". When undefined, the Zephyr build system
+			# automatically searches for the Zephyr SDK and ignores all the
+			# following variables.
 			platf_build_environ["ZEPHYR_TOOLCHAIN_VARIANT"] = platf_build_environ.get("ZEPHYR_TOOLCHAIN_VARIANT",
 				platform_dict["DEFAULT_TOOLCHAIN_VARIANT"])
-			XTENSA_TOOLCHAIN_PATH = str(pathlib.Path(xtensa_tools_root_dir, "install",
-				"tools").absolute())
-			platf_build_environ["XTENSA_TOOLCHAIN_PATH"] = XTENSA_TOOLCHAIN_PATH
+			platf_build_environ["XTENSA_TOOLCHAIN_PATH"] = str(
+				xtensa_tools_root_dir / "install" / "tools"
+			)
+			# Toolchain sub-directory
 			TOOLCHAIN_VER = platform_dict["XTENSA_TOOLS_VERSION"]
-			XTENSA_CORE = platform_dict["XTENSA_CORE"]
 			platf_build_environ["TOOLCHAIN_VER"] = TOOLCHAIN_VER
 
-			# Set variables expected by xcc toolchain. CMake cannot set (evil) build-time
-			# environment variables at configure time:
-			# https://gitlab.kitware.com/cmake/community/-/wikis/FAQ#how-can-i-get-or-set-environment-variables
-			XTENSA_BUILDS_DIR=str(pathlib.Path(xtensa_tools_root_dir, "install", "builds",
-				TOOLCHAIN_VER).absolute())
-			XTENSA_SYSTEM = str(pathlib.Path(XTENSA_BUILDS_DIR, XTENSA_CORE, "config").absolute())
+			# This XTENSA_SYSTEM variable was copied as is from XTOS
+			# scripts/xtensa-build-all.sh but it is not required by (recent?)
+			# toolchains when installed exactly as described in the --help (= a
+			# single --xtensa-core installed per --xtensa-system registry and maybe
+			# other constraints). Let's keep exporting it in case some build
+			# systems have their toolchains installed differently which might
+			# require it.  Note: "not needed" is different from "ignored"! The
+			# compiler fails when the value is incorrect.
+			builds_toolchainver = xtensa_tools_root_dir / "install" / "builds" / TOOLCHAIN_VER
+			XTENSA_SYSTEM = str(builds_toolchainver / platform_dict["XTENSA_CORE"] / "config")
 			platf_build_environ["XTENSA_SYSTEM"] = XTENSA_SYSTEM
 
 		platform_build_dir_name = f"build-{platform}"