CMSIS-Core(M) Doc: added info about deprecated symbols.

ARM-software · May 10, 2024 · 9d800cf · 9d800cf
1 parent 0b356d6
commit 9d800cf
Show file tree

Hide file tree

Showing 10 changed files with 80 additions and 39 deletions.
diff --git a/CMSIS/Core/Include/core_cm23.h b/CMSIS/Core/Include/core_cm23.h
@@ -1276,9 +1276,8 @@ typedef struct
 
 
 /**
-  \ingroup    CMSIS_core_register
-  \defgroup   CMSIS_register_aliases     Backwards Compatibility Aliases
-  \brief      Register alias definitions for backwards compatibility.
+  \defgroup   CMSIS_deprecated_aliases     Backwards Compatibility Aliases
+  \brief      Alias definitions present for backwards compatibility for deprecated symbols.
   @{
  */
 

diff --git a/CMSIS/Core/Include/core_cm3.h b/CMSIS/Core/Include/core_cm3.h
@@ -1398,9 +1398,8 @@ typedef struct
 
 
 /**
-  \ingroup    CMSIS_core_register
-  \defgroup   CMSIS_register_aliases     Backwards Compatibility Aliases
-  \brief      Register alias definitions for backwards compatibility.
+  \defgroup   CMSIS_deprecated_aliases     Backwards Compatibility Aliases
+  \brief      Alias definitions present for backwards compatibility for deprecated symbols.
   @{
  */
 

diff --git a/CMSIS/Core/Include/core_cm35p.h b/CMSIS/Core/Include/core_cm35p.h
@@ -2096,9 +2096,8 @@ typedef struct
 
 
 /**
-  \ingroup    CMSIS_core_register
-  \defgroup   CMSIS_register_aliases     Backwards Compatibility Aliases
-  \brief      Register alias definitions for backwards compatibility.
+  \defgroup   CMSIS_deprecated_aliases     Backwards Compatibility Aliases
+  \brief      Alias definitions present for backwards compatibility for deprecated symbols.
   @{
  */
 

diff --git a/CMSIS/Core/Include/core_cm4.h b/CMSIS/Core/Include/core_cm4.h
@@ -1577,9 +1577,8 @@ typedef struct
 
 
 /**
-  \ingroup    CMSIS_core_register
-  \defgroup   CMSIS_register_aliases     Backwards Compatibility Aliases
-  \brief      Register alias definitions for backwards compatibility.
+  \defgroup   CMSIS_deprecated_aliases     Backwards Compatibility Aliases
+  \brief      Alias definitions present for backwards compatibility for deprecated symbols.
   @{
  */
 

diff --git a/CMSIS/Core/Include/core_cm55.h b/CMSIS/Core/Include/core_cm55.h
@@ -3605,9 +3605,8 @@ typedef struct
 
 
 /**
-  \ingroup    CMSIS_core_register
-  \defgroup   CMSIS_register_aliases     Backwards Compatibility Aliases
-  \brief      Register alias definitions for backwards compatibility.
+  \defgroup   CMSIS_deprecated_aliases     Backwards Compatibility Aliases
+  \brief      Alias definitions present for backwards compatibility for deprecated symbols.
   @{
  */
 

diff --git a/CMSIS/Core/Include/core_cm7.h b/CMSIS/Core/Include/core_cm7.h
@@ -1796,9 +1796,8 @@ typedef struct
 
 
 /**
-  \ingroup    CMSIS_core_register
-  \defgroup   CMSIS_register_aliases     Backwards Compatibility Aliases
-  \brief      Register alias definitions for backwards compatibility.
+  \defgroup   CMSIS_deprecated_aliases     Backwards Compatibility Aliases
+  \brief      Alias definitions present for backwards compatibility for deprecated symbols.
   @{
  */
 

diff --git a/CMSIS/Core/Include/core_cm85.h b/CMSIS/Core/Include/core_cm85.h
@@ -3629,9 +3629,8 @@ typedef struct
 
 
 /**
-  \ingroup    CMSIS_core_register
-  \defgroup   CMSIS_register_aliases     Backwards Compatibility Aliases
-  \brief      Register alias definitions for backwards compatibility.
+  \defgroup   CMSIS_deprecated_aliases     Backwards Compatibility Aliases
+  \brief      Alias definitions present for backwards compatibility for deprecated symbols.
   @{
  */
 

diff --git a/CMSIS/Documentation/Doxygen/Core/Core.dxy.in b/CMSIS/Documentation/Doxygen/Core/Core.dxy.in
@@ -669,7 +669,7 @@ SORT_MEMBER_DOCS       = YES
 # this will also influence the order of the classes in the class list.
 # The default value is: NO.
 
-SORT_BRIEF_DOCS        = NO
+SORT_BRIEF_DOCS        = YES
 
 # If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the
 # (brief and detailed) documentation of class members so that constructors and
@@ -950,6 +950,7 @@ INPUT                  = ./src/mainpage.md \
                          ./src/ref_debug.txt \
                          ./src/ref_trustzone.txt \
                          ./src/ref_cm7_cache.txt \
+                         ./src/ref_deprecated.txt \
                          ./src/ref_data_structs.txt
 
 # This tag can be used to specify the character encoding of the source files

diff --git a/CMSIS/Documentation/Doxygen/Core/src/history.md b/CMSIS/Documentation/Doxygen/Core/src/history.md
@@ -378,18 +378,19 @@ The table below provides information about the changes delivered with specific v
     </tr>
 </table>
 
-\anchor core6_changes
-<h1>Breaking changes in CMSIS-Core v6 header files</h1>
+\section core6_changes Breaking changes in CMSIS-Core 6
 
 \ref cmsis_standard_files in CMSIS-Core v6.0.0 have received a number of changes that are incompatible with CMSIS-Core v5.6.0.
 
 In summary, following types of incompatible changes are present:
 
-- struct member is renamed in an existing structure (e.g. NVIC->PR -> NVIC->IPR)
-- struct name is changed (e.g. CoreDebug_Type -> DCB_Type)
-- define name is changed (e.g. CoreDebug_DEMCR_TRCENA_Msk -> DCB_DEMCR_TRCENA_Msk)
+ - struct member is renamed in an existing structure (e.g. NVIC->PR -> NVIC->IPR)
+ - struct name is changed (e.g. CoreDebug_Type -> DCB_Type)
+ - define name is changed (e.g. CoreDebug_DEMCR_TRCENA_Msk -> DCB_DEMCR_TRCENA_Msk)
 
-[GitHub issue #122](https://github.com/ARM-software/CMSIS_6/issues/122) discusses how to resolve such incompatibilities.
+For the latest two types, CMSIS-Core v6.1 and higher provide also the original CMSIS 5 symbols as deprecated and so improve the backward compatibility. See section \ref deprecated_gr.
+
+Additionally, the [GitHub issue #122](https://github.com/ARM-software/CMSIS_6/issues/122) discusses how to resolve such incompatibilities.
 
 Below is detailed information about the changes relevant for each Cortex-M core.
 
@@ -418,10 +419,10 @@ Below is detailed information about the changes relevant for each Cortex-M core.
 - define names for ITM_TCR_* changed
 - define names for ITM_LSR_* changed
 - struct TPI_Type renamed to TPIU_Type
-- define names for TPI_*renamed to TPIU_*
+- define names for TPI_* renamed to TPIU_*
 - define names for FPU_MVFR0/1_* changed (Cortex-M4)
 - struct CoreDebug_Type renamed to DCB_Type
-- defines for CoreDebug_*renamed to DCB_*
+- defines for CoreDebug_* renamed to DCB_*
 
 **Cortex-M7:**
 
@@ -434,31 +435,31 @@ Below is detailed information about the changes relevant for each Cortex-M core.
 - define names for ITM_TCR_* changed
 - define names for ITM_LSR_* changed
 - struct TPI_Type renamed to TPIU_Type
-- define names for TPI_*renamed to TPIU_*
+- define names for TPI_* renamed to TPIU_*
 - define names for FPU_MVFR0/1_* changed
 - struct CoreDebug_Type renamed to DCB_Type
-- defines for CoreDebug_*renamed to DCB_*
+- defines for CoreDebug_* renamed to DCB_*
 
 **Cortex-M23:**
 
 - struct DWT_Type
   - member RESERVED0[6] replaced by CYCCNT, CPICNT, EXCCNT, SLEEPCNT, LSUCNT, FOLDCNT
   - other RESERVED members mainly removed
 - struct TPI_Type renamed to TPIU_Type
-- define names for TPI_*renamed to TPIU_*
+- define names for TPI_* renamed to TPIU_*
 - struct CoreDebug_Type removed (struct DCB_Type already existed)
-- defines CoreDebug_removed (defines DCB_ already existed)
+- defines CoreDebug_* removed (defines DCB_* already existed)
 
 **Cortex-M33:**
 
 - struct ITM_Type:
   - members LAR, LSR removed
   - members PIDx and CIDx removed
 - struct TPI_Type renamed to TPIU_Type
-- define names for TPI_*renamed to TPIU_*
+- define names for TPI_* renamed to TPIU_*
 - define names for FPU_MVFR0/1_* changed
 - struct CoreDebug_Type removed (struct DCB_Type already existed)
-- defines CoreDebug_removed (defines DCB_ already existed)
+- defines CoreDebug_* removed (defines DCB_* already existed)
 
 **Cortex-M55, Cortex-M85:**
 
@@ -472,11 +473,11 @@ Below is detailed information about the changes relevant for each Cortex-M core.
 - define names EWIC_* changed
 - struct TPI_Type renamed to TPIU_Type
   - members LAR, LSR replaced
-- define names for TPI_*renamed to TPIU_*
+- define names for TPI_* renamed to TPIU_*
 - struct PMU_Type
   - members PIDx and CIDx removed
 - struct CoreDebug_Type removed (struct DCB_Type already existed)
-- defines CoreDebug_removed (defines DCB_ already existed)
+- defines CoreDebug_* removed (defines DCB_* already existed)
 - struct DIB_Type
   - members DLAR, DLSR removed (replaced by RESERVED0[2])
-- defines for DIB_DLAR_*and DIB_DLSR_* removed
+- defines for DIB_DLAR_* and DIB_DLSR_* removed
diff --git a/CMSIS/Documentation/Doxygen/Core/src/ref_deprecated.txt b/CMSIS/Documentation/Doxygen/Core/src/ref_deprecated.txt
@@ -0,0 +1,46 @@
+/* ##################################### Debug In/Output function ############################### */
+/**
+\defgroup deprecated_gr Deprecated Symbols
+\brief List of deprecated symbols
+\details
+
+Deprecated items listed in this section are present in the \ref cmsis_standard_files starting from CMSIS-Core 6.1.0 and improve backward compatibility to CMSIS 5 based software.
+
+Note that these deprecated symbols do not resolve all potential breaking changes introduced in CMSIS 6. For more information also see \ref core6_changes. Whenever possible, it is recommended to update to new CMSIS 6 compliant symbols.
+
+\ref CMSIS_DISABLE_DEPRECATED can be defined to fully exclude the definitions of deprecated symbols from CMSIS-Core header files.
+
+@{
+*/
+
+/**
+\brief **[Deprecated]** Structure type to access the Core Debug Register.
+\details The **CoreDebug_Type** structure is present to enable backward compatibility for CMSIS 5 based projects. For new projects based on CMSIS 6, the DCB_Type shall be used instead.
+*/
+typedef struct
+{
+  __IOM uint32_t DHCSR;                  ///< Offset: 0x000 (R/W)  Debug Halting Control and Status Register
+  __OM  uint32_t DCRSR;                  ///< Offset: 0x004 ( /W)  Debug Core Register Selector Register
+  __IOM uint32_t DCRDR;                  ///< Offset: 0x008 (R/W)  Debug Core Register Data Register
+  __IOM uint32_t DEMCR;                  ///< Offset: 0x00C (R/W)  Debug Exception and Monitor Control Register
+  __OM  uint32_t DSCEMCR;                ///< Offset: 0x010 ( /W)  Debug Set Clear Exception and Monitor Control Register (Armv8.1-M only)
+  __IOM uint32_t DAUTHCTRL;              ///< Offset: 0x014 (R/W)  Debug Authentication Control Register (Armv8-M only)
+  __IOM uint32_t DSCSR;                  ///< Offset: 0x018 (R/W)  Debug Security Control and Status Register (Armv8-M only)
+} CoreDebug_Type;
+
+/**
+\def CoreDebug
+\brief **[Deprecated]** Core Debug configuration structure
+\details The **CoreDebug** configuration structure is present to enable backward compatibility for CMSIS 5 based projects. For new projects based on CMSIS 6, the **DCB** structure shall be used instead.
+*/
+#define CoreDebug           ((CoreDebug_Type *)     DCB_BASE)
+
+/**
+\def CMSIS_DISABLE_DEPRECATED
+\brief Disables deprecated items
+\details When CMSIS_DISABLE_DEPRECATED is defined in the project then definitions of deprecated items are excluded from the CMSIS-Core build.
+*/
+#define CMSIS_DISABLE_DEPRECATED
+
+
+/** @} */