toolchain: Add the TOOLCHAIN_DEPRECATED macro

Add the `TOOLCHAIN_DEPRECATED` macro to encapsulate
the `__deprecated_version` implementation. It's provided
by both LLVM and GCC compilers.

Signed-off-by: James Roy <rruuaanng@outlook.com>

Author: rruuaanng

doc/releases/release-notes-4.2.rst

@@ -116,6 +116,10 @@ New APIs and options
   * :kconfig:option:`CONFIG_SRAM_VECTOR_TABLE` moved from ``zephyr/Kconfig.zephyr`` to
     ``zephyr/arch/Kconfig`` and added dependencies to it.
 
+* Toolchain
+
+  * :c:macro:`TOOLCHAIN_DEPRECATED`
+
 * Kernel
 
  * :c:macro:`K_TIMEOUT_ABS_SEC`

include/zephyr/toolchain.h

@@ -318,6 +318,18 @@
 #define TOOLCHAIN_ENABLE_IAR_WARNING(warning)
 #endif
 
+/**
+ * @def TOOLCHAIN_DEPRECATED
+ * @brief Marks a function or symbol as deprecated as of @p removal_version.
+ *
+ * @param removal_version Version of planned removal
+ */
+#if defined(__GNUC__) || defined(__llvm__)
+#define TOOLCHAIN_DEPRECATED(removal_version) __deprecated_version(removal_version)
+#else
+#define TOOLCHAIN_DEPRECATED(removal_version)
+#endif
+
 /*
  * Ensure that __BYTE_ORDER__ and related preprocessor definitions are defined,
  * and that they match the Kconfig option that is used in the code itself to