rtems: Fatal error for rtems_cache_disable_data()

On some targets or configurations, the data cache cannot be disabled.
The data cache may be necessary to provide atomic operations.  In SMP
configurations, the data cache may be required to ensure data coherency.

Close #5050.

cpukit/include/rtems/rtems/cache.h

@@ -10,7 +10,7 @@
 
 /*
  * Copyright (C) 2016 Pavel Pisa
- * Copyright (C) 2014, 2021 embedded brains GmbH & Co. KG
+ * Copyright (C) 2014, 2024 embedded brains GmbH & Co. KG
  * Copyright (C) 2000, 2008 On-Line Applications Research Corporation (OAR)
  *
  * Redistribution and use in source and binary forms, with or without
@@ -578,6 +578,14 @@ void rtems_cache_enable_data( void );
  *
  * @brief Disables the data cache.
  *
+ * @par Notes
+ * On some targets or configurations, calling this directive may cause a fatal
+ * error with a fatal source of INTERNAL_ERROR_CORE and fatal code of
+ * INTERNAL_ERROR_CANNOT_DISABLE_DATA_CACHE.   The data cache may be necessary
+ * to provide atomic operations. In SMP configurations, the data cache may be
+ * required to ensure data coherency.  See the BSP documentation in the *RTEMS
+ * User Manual* for more information.
+ *
  * @par Constraints
  * @parblock
  * The following constraints apply to this directive:

cpukit/include/rtems/score/interr.h

@@ -231,7 +231,8 @@ typedef enum {
   INTERNAL_ERROR_RTEMS_INIT_TASK_CONSTRUCT_FAILED = 42,
   INTERNAL_ERROR_IDLE_THREAD_CREATE_FAILED = 43,
   INTERNAL_ERROR_NO_MEMORY_FOR_IDLE_TASK_STORAGE = 44,
-  INTERNAL_ERROR_IDLE_THREAD_STACK_TOO_SMALL = 45
+  INTERNAL_ERROR_IDLE_THREAD_STACK_TOO_SMALL = 45,
+  INTERNAL_ERROR_CANNOT_DISABLE_DATA_CACHE = 46
 } Internal_errors_Core_list;
 
 typedef CPU_Uint32ptr Internal_errors_t;

spec/build/testsuites/validation/objcachedisabledata.yml

@@ -0,0 +1,14 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+build-type: objects
+cflags: []
+copyrights:
+- Copyright (C) 2024 embedded brains GmbH & Co. KG
+cppflags: []
+cxxflags: []
+enabled-by: true
+includes: []
+install: []
+links: []
+source:
+- testsuites/validation/tc-cache-disable-data.c
+type: build

spec/build/testsuites/validation/objcachenodisabledata.yml

@@ -0,0 +1,14 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+build-type: objects
+cflags: []
+copyrights:
+- Copyright (C) 2024 embedded brains GmbH & Co. KG
+cppflags: []
+cxxflags: []
+enabled-by: false
+includes: []
+install: []
+links: []
+source:
+- testsuites/validation/tc-cache-no-disable-data.c
+type: build

spec/build/testsuites/validation/validation-cache.yml

@@ -9,7 +9,11 @@ enabled-by: true
 features: c cprogram
 includes: []
 ldflags: []
-links: []
+links:
+- role: build-dependency
+  uid: objcachedisabledata
+- role: build-dependency
+  uid: objcachenodisabledata
 source:
 - testsuites/validation/tc-cache.c
 - testsuites/validation/ts-validation-cache.c

testsuites/validation/tc-cache-disable-data.c

@@ -0,0 +1,130 @@
+/* SPDX-License-Identifier: BSD-2-Clause */
+
+/**
+ * @file
+ *
+ * @ingroup RtemsCacheValCacheDisableData
+ */
+
+/*
+ * Copyright (C) 2024 embedded brains GmbH & Co. KG
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/*
+ * This file is part of the RTEMS quality process and was automatically
+ * generated.  If you find something that needs to be fixed or
+ * worded better please post a report or patch to an RTEMS mailing list
+ * or raise a bug report:
+ *
+ * https://www.rtems.org/bugs.html
+ *
+ * For information on updating and regenerating please refer to the How-To
+ * section in the Software Requirements Engineering chapter of the
+ * RTEMS Software Engineering manual.  The manual is provided as a part of
+ * a release.  For development sources please refer to the online
+ * documentation at:
+ *
+ * https://docs.rtems.org
+ */
+
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include <rtems.h>
+
+#include <rtems/test.h>
+
+/**
+ * @defgroup RtemsCacheValCacheDisableData \
+ *   spec:/rtems/cache/val/cache-disable-data
+ *
+ * @ingroup TestsuitesValidationCache
+ *
+ * @brief Tests some @ref RTEMSAPIClassicCache directives.
+ *
+ * This test case performs the following actions:
+ *
+ * - Call the rtems_cache_disable_data() and rtems_cache_enable_data()
+ *   directives.
+ *
+ * - Call the rtems_cache_disable_data() and rtems_cache_enable_data()
+ *   directives with maskable interrupts disabled.
+ *
+ * - Call the rtems_cache_invalidate_entire_data() directive with maskable
+ *   interrupts disabled.
+ *
+ * @{
+ */
+
+/**
+ * @brief Call the rtems_cache_disable_data() and rtems_cache_enable_data()
+ *   directives.
+ */
+static void RtemsCacheValCacheDisableData_Action_0( void )
+{
+  rtems_cache_disable_data();
+  rtems_cache_enable_data();
+}
+
+/**
+ * @brief Call the rtems_cache_disable_data() and rtems_cache_enable_data()
+ *   directives with maskable interrupts disabled.
+ */
+static void RtemsCacheValCacheDisableData_Action_1( void )
+{
+  rtems_interrupt_level level;
+
+  rtems_interrupt_local_disable(level);
+  rtems_cache_disable_data();
+  rtems_cache_enable_data();
+  rtems_interrupt_local_enable(level);
+}
+
+/**
+ * @brief Call the rtems_cache_invalidate_entire_data() directive with maskable
+ *   interrupts disabled.
+ */
+static void RtemsCacheValCacheDisableData_Action_2( void )
+{
+  rtems_interrupt_level level;
+
+  rtems_interrupt_local_disable(level);
+  rtems_cache_disable_data();
+  rtems_cache_invalidate_entire_data();
+  rtems_cache_enable_data();
+  rtems_interrupt_local_enable(level);
+}
+
+/**
+ * @fn void T_case_body_RtemsCacheValCacheDisableData( void )
+ */
+T_TEST_CASE( RtemsCacheValCacheDisableData )
+{
+  RtemsCacheValCacheDisableData_Action_0();
+  RtemsCacheValCacheDisableData_Action_1();
+  RtemsCacheValCacheDisableData_Action_2();
+}
+
+/** @} */

testsuites/validation/tc-cache-no-disable-data.c

@@ -0,0 +1,164 @@
+/* SPDX-License-Identifier: BSD-2-Clause */
+
+/**
+ * @file
+ *
+ * @ingroup RtemsCacheValCacheNoDisableData
+ */
+
+/*
+ * Copyright (C) 2024 embedded brains GmbH & Co. KG
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/*
+ * This file is part of the RTEMS quality process and was automatically
+ * generated.  If you find something that needs to be fixed or
+ * worded better please post a report or patch to an RTEMS mailing list
+ * or raise a bug report:
+ *
+ * https://www.rtems.org/bugs.html
+ *
+ * For information on updating and regenerating please refer to the How-To
+ * section in the Software Requirements Engineering chapter of the
+ * RTEMS Software Engineering manual.  The manual is provided as a part of
+ * a release.  For development sources please refer to the online
+ * documentation at:
+ *
+ * https://docs.rtems.org
+ */
+
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include <rtems.h>
+#include <setjmp.h>
+
+#include "tx-support.h"
+
+#include <rtems/test.h>
+
+/**
+ * @defgroup RtemsCacheValCacheNoDisableData \
+ *   spec:/rtems/cache/val/cache-no-disable-data
+ *
+ * @ingroup TestsuitesValidationCache
+ *
+ * @brief Tests some @ref RTEMSAPIClassicCache directives.
+ *
+ * This test case performs the following actions:
+ *
+ * - Call the rtems_cache_invalidate_entire_data() directive.
+ *
+ *   - Check that the right fatal error occurred.
+ *
+ * - Call the rtems_cache_invalidate_entire_data() directive.
+ *
+ * - Call the rtems_cache_invalidate_entire_data() directive with maskable
+ *   interrupts disabled.
+ *
+ * @{
+ */
+
+static jmp_buf fatal_before;
+
+static Atomic_Uint fatal_counter;
+
+static rtems_fatal_source fatal_source;
+
+static rtems_fatal_code fatal_code;
+
+static void FatalRecordAndJump(
+  rtems_fatal_source source,
+  rtems_fatal_code   code,
+  void              *arg
+)
+{
+  (void) arg;
+
+  fatal_source = source;
+  fatal_code = code;
+  _Atomic_Fetch_add_uint( &fatal_counter, 1, ATOMIC_ORDER_RELAXED );
+  longjmp( fatal_before, 1 );
+}
+
+/**
+ * @brief Call the rtems_cache_invalidate_entire_data() directive.
+ */
+static void RtemsCacheValCacheNoDisableData_Action_0( void )
+{
+  SetFatalHandler( FatalRecordAndJump, NULL );
+
+  if ( setjmp( fatal_before ) == 0 ) {
+    rtems_cache_disable_data();
+  }
+
+  SetFatalHandler( NULL, NULL );
+
+  /*
+   * Check that the right fatal error occurred.
+   */
+  T_eq_uint(
+    _Atomic_Load_uint( &fatal_counter, ATOMIC_ORDER_RELAXED ),
+    1
+  );
+  T_eq_int( fatal_source, INTERNAL_ERROR_CORE );
+  T_eq_ulong(
+    fatal_code,
+    INTERNAL_ERROR_CANNOT_DISABLE_DATA_CACHE
+  );
+}
+
+/**
+ * @brief Call the rtems_cache_invalidate_entire_data() directive.
+ */
+static void RtemsCacheValCacheNoDisableData_Action_1( void )
+{
+  rtems_cache_invalidate_entire_data();
+}
+
+/**
+ * @brief Call the rtems_cache_invalidate_entire_data() directive with maskable
+ *   interrupts disabled.
+ */
+static void RtemsCacheValCacheNoDisableData_Action_2( void )
+{
+  rtems_interrupt_level level;
+
+  rtems_interrupt_local_disable(level);
+  rtems_cache_invalidate_entire_data();
+  rtems_interrupt_local_enable(level);
+}
+
+/**
+ * @fn void T_case_body_RtemsCacheValCacheNoDisableData( void )
+ */
+T_TEST_CASE( RtemsCacheValCacheNoDisableData )
+{
+  RtemsCacheValCacheNoDisableData_Action_0();
+  RtemsCacheValCacheNoDisableData_Action_1();
+  RtemsCacheValCacheNoDisableData_Action_2();
+}
+
+/** @} */

testsuites/validation/tc-cache.c

@@ -65,11 +65,10 @@
  *
  * This test case performs the following actions:
  *
- * - Call the rtems_cache_disable_data() and rtems_cache_enable_data()
- *   directives.
+ * - Call the rtems_cache_enable_data() directive.
  *
- * - Call the rtems_cache_disable_data() and rtems_cache_enable_data()
- *   directives with maskable interrupts disabled.
+ * - Call the rtems_cache_enable_data() directive with maskable interrupts
+ *   disabled.
  *
  * - Call the rtems_cache_disable_instruction() and
  *   rtems_cache_enable_instruction() directives.
@@ -91,9 +90,6 @@
  *   rtems_cache_unfreeze_instruction() directives with maskable interrupts
  *   disabled.
  *
- * - Call the rtems_cache_invalidate_entire_data() directive with maskable
- *   interrupts disabled.
- *
  * - Call the rtems_cache_invalidate_entire_instruction() directive.
  *
  * - Call the rtems_cache_invalidate_entire_instruction() directive with
@@ -287,25 +283,22 @@ static void CallGetInstructionSize( void )
 }
 
 /**
- * @brief Call the rtems_cache_disable_data() and rtems_cache_enable_data()
- *   directives.
+ * @brief Call the rtems_cache_enable_data() directive.
  */
 static void RtemsCacheValCache_Action_0( void )
 {
-  rtems_cache_disable_data();
   rtems_cache_enable_data();
 }
 
 /**
- * @brief Call the rtems_cache_disable_data() and rtems_cache_enable_data()
- *   directives with maskable interrupts disabled.
+ * @brief Call the rtems_cache_enable_data() directive with maskable interrupts
+ *   disabled.
  */
 static void RtemsCacheValCache_Action_1( void )
 {
   rtems_interrupt_level level;
 
   rtems_interrupt_local_disable(level);
-  rtems_cache_disable_data();
   rtems_cache_enable_data();
   rtems_interrupt_local_enable(level);
 }
@@ -384,25 +377,10 @@ static void RtemsCacheValCache_Action_7( void )
   rtems_interrupt_local_enable(level);
 }
 
-/**
- * @brief Call the rtems_cache_invalidate_entire_data() directive with maskable
- *   interrupts disabled.
- */
-static void RtemsCacheValCache_Action_8( void )
-{
-  rtems_interrupt_level level;
-
-  rtems_interrupt_local_disable(level);
-  rtems_cache_disable_data();
-  rtems_cache_invalidate_entire_data();
-  rtems_cache_enable_data();
-  rtems_interrupt_local_enable(level);
-}
-
 /**
  * @brief Call the rtems_cache_invalidate_entire_instruction() directive.
  */
-static void RtemsCacheValCache_Action_9( void )
+static void RtemsCacheValCache_Action_8( void )
 {
   rtems_cache_invalidate_entire_instruction();
 }
@@ -411,7 +389,7 @@ static void RtemsCacheValCache_Action_9( void )
  * @brief Call the rtems_cache_invalidate_entire_instruction() directive with
  *   maskable interrupts disabled.
  */
-static void RtemsCacheValCache_Action_10( void )
+static void RtemsCacheValCache_Action_9( void )
 {
   rtems_interrupt_level level;
 
@@ -423,7 +401,7 @@ static void RtemsCacheValCache_Action_10( void )
 /**
  * @brief Call the rtems_cache_flush_entire_data() directive.
  */
-static void RtemsCacheValCache_Action_11( void )
+static void RtemsCacheValCache_Action_10( void )
 {
   rtems_cache_flush_entire_data();
 }
@@ -432,7 +410,7 @@ static void RtemsCacheValCache_Action_11( void )
  * @brief Call the rtems_cache_flush_entire_data() directive with maskable
  *   interrupts disabled.
  */
-static void RtemsCacheValCache_Action_12( void )
+static void RtemsCacheValCache_Action_11( void )
 {
   rtems_interrupt_level level;
 
@@ -445,7 +423,7 @@ static void RtemsCacheValCache_Action_12( void )
  * @brief Call the rtems_cache_flush_multiple_data_lines() directive with a
  *   sample set of memory areas.
  */
-static void RtemsCacheValCache_Action_13( void )
+static void RtemsCacheValCache_Action_12( void )
 {
   CallFlushMultipleDataLines();
 }
@@ -454,7 +432,7 @@ static void RtemsCacheValCache_Action_13( void )
  * @brief Call the rtems_cache_flush_multiple_data_lines() directive with a
  *   sample set of memory areas with maskable interrupts disabled.
  */
-static void RtemsCacheValCache_Action_14( void )
+static void RtemsCacheValCache_Action_13( void )
 {
   rtems_interrupt_level level;
 
@@ -467,7 +445,7 @@ static void RtemsCacheValCache_Action_14( void )
  * @brief Call the rtems_cache_invalidate_multiple_data_lines() directive with
  *   a sample set of memory areas.
  */
-static void RtemsCacheValCache_Action_15( void )
+static void RtemsCacheValCache_Action_14( void )
 {
   CallInvalidateMultipleDataLines();
 }
@@ -476,7 +454,7 @@ static void RtemsCacheValCache_Action_15( void )
  * @brief Call the rtems_cache_invalidate_multiple_data_lines() directive with
  *   a sample set of memory areas with maskable interrupts disabled.
  */
-static void RtemsCacheValCache_Action_16( void )
+static void RtemsCacheValCache_Action_15( void )
 {
   rtems_interrupt_level level;
 
@@ -489,7 +467,7 @@ static void RtemsCacheValCache_Action_16( void )
  * @brief Call the rtems_cache_invalidate_multiple_instruction_lines()
  *   directive with a sample set of memory areas.
  */
-static void RtemsCacheValCache_Action_17( void )
+static void RtemsCacheValCache_Action_16( void )
 {
   CallInvalidateMultipleInstructionLines();
 }
@@ -499,7 +477,7 @@ static void RtemsCacheValCache_Action_17( void )
  *   directive with a sample set of memory areas with maskable interrupts
  *   disabled.
  */
-static void RtemsCacheValCache_Action_18( void )
+static void RtemsCacheValCache_Action_17( void )
 {
   rtems_interrupt_level level;
 
@@ -512,7 +490,7 @@ static void RtemsCacheValCache_Action_18( void )
  * @brief Call the rtems_cache_instruction_sync_after_code_change() directive
  *   with a sample set of memory areas.
  */
-static void RtemsCacheValCache_Action_19( void )
+static void RtemsCacheValCache_Action_18( void )
 {
   CallInstructionSyncAfterCodeChange();
 }
@@ -521,7 +499,7 @@ static void RtemsCacheValCache_Action_19( void )
  * @brief Call the rtems_cache_instruction_sync_after_code_change() directive
  *   with a sample set of memory areas with maskable interrupts disabled.
  */
-static void RtemsCacheValCache_Action_20( void )
+static void RtemsCacheValCache_Action_19( void )
 {
   rtems_interrupt_level level;
 
@@ -535,7 +513,7 @@ static void RtemsCacheValCache_Action_20( void )
  *   rtems_cache_get_instruction_line_size(), and the
  *   rtems_cache_get_maximal_line_size() directives.
  */
-static void RtemsCacheValCache_Action_21( void )
+static void RtemsCacheValCache_Action_20( void )
 {
   size_t data_line_size;
   size_t instruction_line_size;
@@ -564,7 +542,7 @@ static void RtemsCacheValCache_Action_21( void )
  *   rtems_cache_get_maximal_line_size() directives with maskable interrupts
  *   disabled.
  */
-static void RtemsCacheValCache_Action_22( void )
+static void RtemsCacheValCache_Action_21( void )
 {
   size_t data_line_size;
   size_t instruction_line_size;
@@ -594,7 +572,7 @@ static void RtemsCacheValCache_Action_22( void )
  * @brief Call the rtems_cache_get_data_cache_size() directive with increasing
  *   level starting with zero until it returns zero.
  */
-static void RtemsCacheValCache_Action_23( void )
+static void RtemsCacheValCache_Action_22( void )
 {
   CallGetDataSize();
 }
@@ -604,7 +582,7 @@ static void RtemsCacheValCache_Action_23( void )
  *   level starting with zero until it returns zero with maskable interrupts
  *   disabled.
  */
-static void RtemsCacheValCache_Action_24( void )
+static void RtemsCacheValCache_Action_23( void )
 {
   rtems_interrupt_level level;
 
@@ -617,7 +595,7 @@ static void RtemsCacheValCache_Action_24( void )
  * @brief Call the rtems_cache_get_instruction_cache_size() directive with
  *   increasing level starting with zero until it returns zero.
  */
-static void RtemsCacheValCache_Action_25( void )
+static void RtemsCacheValCache_Action_24( void )
 {
   CallGetInstructionSize();
 }
@@ -627,7 +605,7 @@ static void RtemsCacheValCache_Action_25( void )
  *   increasing level starting with zero until it returns zero with maskable
  *   interrupts disabled.
  */
-static void RtemsCacheValCache_Action_26( void )
+static void RtemsCacheValCache_Action_25( void )
 {
   rtems_interrupt_level level;
 
@@ -669,7 +647,6 @@ T_TEST_CASE( RtemsCacheValCache )
   RtemsCacheValCache_Action_23();
   RtemsCacheValCache_Action_24();
   RtemsCacheValCache_Action_25();
-  RtemsCacheValCache_Action_26();
 }
 
 /** @} */