Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 2 commits into from
May 13, 2024
Merged

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

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9d800cf
CMSIS-Core(M) Doc: added info about deprecated symbols.
vovamarch May 10, 2024
c721187
Aligned deprecated group definitions across core header files
vovamarch May 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions CMSIS/Core/Include/core_cm23.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
@{
*/

Expand Down
5 changes: 2 additions & 3 deletions CMSIS/Core/Include/core_cm3.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
@{
*/

Expand Down
5 changes: 2 additions & 3 deletions CMSIS/Core/Include/core_cm35p.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
@{
*/

Expand Down
5 changes: 2 additions & 3 deletions CMSIS/Core/Include/core_cm4.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
@{
*/

Expand Down
5 changes: 2 additions & 3 deletions CMSIS/Core/Include/core_cm55.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
@{
*/

Expand Down
5 changes: 2 additions & 3 deletions CMSIS/Core/Include/core_cm7.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
@{
*/

Expand Down
5 changes: 2 additions & 3 deletions CMSIS/Core/Include/core_cm85.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
@{
*/

Expand Down
3 changes: 2 additions & 1 deletion CMSIS/Documentation/Doxygen/Core/Core.dxy.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
35 changes: 18 additions & 17 deletions CMSIS/Documentation/Doxygen/Core/src/history.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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:**

Expand All @@ -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:**

Expand All @@ -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
46 changes: 46 additions & 0 deletions CMSIS/Documentation/Doxygen/Core/src/ref_deprecated.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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


/** @} */
Loading