Replace build macro WARN_DEPRECATED with ERROR_DEPRECATED

This patch changes the build time behaviour when using deprecated API within
Trusted Firmware. Previously the use of deprecated APIs would only trigger a
build warning (which was always treated as a build error), when
WARN_DEPRECATED = 1. Now, the use of deprecated C declarations will always
trigger a build time warning. Whether this warning is treated as error or not
is determined by the build flag ERROR_DEPRECATED which is disabled by default.
When the build flag ERROR_DEPRECATED=1, the invocation of deprecated API or
inclusion of deprecated headers will result in a build error.

Also the deprecated context management helpers in context_mgmt.c are now
conditionally compiled depending on the value of ERROR_DEPRECATED flag
so that the APIs themselves do not result in a build error when the
ERROR_DEPRECATED flag is set.

NOTE: Build systems that use the macro WARN_DEPRECATED must migrate to
using ERROR_DEPRECATED, otherwise deprecated API usage will no longer
trigger a build error.

Change-Id: I843bceef6bde979af7e9b51dddf861035ec7965a

diff --git a/Makefile b/Makefile
index 3ac03ba1f1e0a58b6a02f5cbac314d3fd9fbdcca..7a4be44af7acbf4faf004ad2834b410e4f34149e 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -87,8 +87,8 @@ TRUSTED_BOARD_BOOT            := 0
 # By default, consider that the platform's reset address is not programmable.
 # The platform Makefile is free to override this value.
 PROGRAMMABLE_RESET_ADDRESS     := 0
-# Build flag to warn about usage of deprecated platform and framework APIs
-WARN_DEPRECATED                        := 0
+# Build flag to treat usage of deprecated platform and framework APIs as error.
+ERROR_DEPRECATED               := 0
 
 
 ################################################################################
@@ -346,7 +346,7 @@ $(eval $(call assert_boolean,SAVE_KEYS))
 $(eval $(call assert_boolean,TRUSTED_BOARD_BOOT))
 $(eval $(call assert_boolean,PROGRAMMABLE_RESET_ADDRESS))
 $(eval $(call assert_boolean,PSCI_EXTENDED_STATE_ID))
-$(eval $(call assert_boolean,WARN_DEPRECATED))
+$(eval $(call assert_boolean,ERROR_DEPRECATED))
 $(eval $(call assert_boolean,ENABLE_PLAT_COMPAT))
 
 
@@ -368,7 +368,7 @@ $(eval $(call add_define,USE_COHERENT_MEM))
 $(eval $(call add_define,TRUSTED_BOARD_BOOT))
 $(eval $(call add_define,PROGRAMMABLE_RESET_ADDRESS))
 $(eval $(call add_define,PSCI_EXTENDED_STATE_ID))
-$(eval $(call add_define,WARN_DEPRECATED))
+$(eval $(call add_define,ERROR_DEPRECATED))
 $(eval $(call add_define,ENABLE_PLAT_COMPAT))
 
 
@@ -404,6 +404,11 @@ all: msg_start
 msg_start:
        @echo "Building ${PLAT}"
 
+# Check if deprecated declarations should be treated as error or not.
+ifeq (${ERROR_DEPRECATED},0)
+    CFLAGS             +=      -Wno-error=deprecated-declarations
+endif
+
 # Expand build macros for the different images
 ifeq (${NEED_BL1},yes)
 $(eval $(call MAKE_BL,1))

diff --git a/bl31/context_mgmt.c b/bl31/context_mgmt.c
index a0fd1b6541dd95074060293b78165c74cacaddbd..6d405343093c6a4c55c53c1cb09b7d8a5a3692af 100644 (file)
--- a/bl31/context_mgmt.c
+++ b/bl31/context_mgmt.c
@@ -90,6 +90,14 @@ void cm_set_context_by_index(unsigned int cpu_idx, void *context,
        set_cpu_data_by_index(cpu_idx, cpu_context[security_state], context);
 }
 
+#if !ERROR_DEPRECATED
+/*
+ * These context management helpers are deprecated but are maintained for use
+ * by SPDs which have not migrated to the new API. If ERROR_DEPRECATED
+ * is enabled, these are excluded from the build so as to force users to
+ * migrate to the new API.
+ */
+
 /*******************************************************************************
  * This function returns a pointer to the most recent 'cpu_context' structure
  * for the CPU identified by MPIDR that was set as the context for the specified
@@ -114,6 +122,21 @@ void cm_set_context_by_mpidr(uint64_t mpidr, void *context, uint32_t security_st
                                                 context, security_state);
 }
 
+/*******************************************************************************
+ * The following function provides a compatibility function for SPDs using the
+ * existing cm library routines. This function is expected to be invoked for
+ * initializing the cpu_context for the CPU specified by MPIDR for first use.
+ ******************************************************************************/
+void cm_init_context(unsigned long mpidr, const entry_point_info_t *ep)
+{
+       if ((mpidr & MPIDR_AFFINITY_MASK) ==
+                       (read_mpidr_el1() & MPIDR_AFFINITY_MASK))
+               cm_init_my_context(ep);
+       else
+               cm_init_context_by_index(platform_get_core_pos(mpidr), ep);
+}
+#endif
+
 /*******************************************************************************
  * This function is used to program the context that's used for exception
  * return. This initializes the SP_EL3 to a pointer to a 'cpu_context' set for
@@ -260,20 +283,6 @@ void cm_init_my_context(const entry_point_info_t *ep)
        cm_init_context_common(ctx, ep);
 }
 
-/*******************************************************************************
- * The following function provides a compatibility function for SPDs using the
- * existing cm library routines. This function is expected to be invoked for
- * initializing the cpu_context for the CPU specified by MPIDR for first use.
- ******************************************************************************/
-void cm_init_context(unsigned long mpidr, const entry_point_info_t *ep)
-{
-       if ((mpidr & MPIDR_AFFINITY_MASK) ==
-                       (read_mpidr_el1() & MPIDR_AFFINITY_MASK))
-               cm_init_my_context(ep);
-       else
-               cm_init_context_by_index(platform_get_core_pos(mpidr), ep);
-}
-
 /*******************************************************************************
  * Prepare the CPU system registers for first entry into secure or normal world
  *

diff --git a/docs/user-guide.md b/docs/user-guide.md
index 7987d10ebeb0db9d44e7b5242ee6154bf0c622f9..a7a0c11f3d392c117028b16aa5f2f7af590ba0b8 100644 (file)
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -367,10 +367,10 @@ performed.
     and it governs the return value of PSCI_FEATURES API for CPU_SUSPEND
     smc function id.
 
-*   `WARN_DEPRECATED`: This option decides whether to warn the usage of
-    deprecated platform APIs and context management helpers within Trusted
-    Firmware. It can take the value 1 (warn the use of deprecated APIs) or
-    0. The default is 0.
+*   `ERROR_DEPRECATED`: This option decides whether to treat the usage of
+    deprecated platform APIs, helper functions or drivers within Trusted
+    Firmware as error. It can take the value 1 (flag the use of deprecated
+    APIs as error) or 0. The default is 0.
 
 #### ARM development platform specific build options
 

diff --git a/include/common/asm_macros.S b/include/common/asm_macros.S
index 128259f1940ab04cb6788ed925a9cdd15e67830a..a331c051af3f16244dd70fbe0b7343c4d676bc2a 100644 (file)
--- a/include/common/asm_macros.S
+++ b/include/common/asm_macros.S
@@ -101,10 +101,10 @@
 
        /*
         * Theses macros are used to create function labels for deprecated
-        * APIs. If WARN_DEPRECATED is non zero, the callers of these APIs
+        * APIs. If ERROR_DEPRECATED is non zero, the callers of these APIs
         * will fail to link and cause build failure.
         */
-#if WARN_DEPRECATED
+#if ERROR_DEPRECATED
        .macro func_deprecated _name
        func deprecated\_name
        .endm

diff --git a/include/plat/common/common_def.h b/include/plat/common/common_def.h
index 077080df3b40c0dcdb7648a9e6e1d9b236be9342..43c69cc83e12f7ebe36a98c49d9a8ff9e9f5c41e 100644 (file)
--- a/include/plat/common/common_def.h
+++ b/include/plat/common/common_def.h
@@ -69,15 +69,10 @@
 
 /*
  * Macros to wrap declarations of deprecated APIs within Trusted Firmware.
- * The callers of these APIs will continue to compile as long as the build
- * flag WARN_DEPRECATED is zero. Else the compiler will emit a warning
- * when the callers of these APIs are compiled.
+ * The callers of these APIs will continue to compile with a warning as long
+ * as the build flag ERROR_DEPRECATED is zero.
  */
-#if WARN_DEPRECATED
 #define __warn_deprecated      __attribute__ ((deprecated))
-#else
-#define __warn_deprecated
-#endif
 
 #endif /* __COMMON_DEF_H__ */