Merge pull request #29 from KeilChris/SDCMSIS-431

CMSIS-Core documentation for compiler specific #defines (SDCMSIS-431)

CMSIS/DoxyGen/Core/core.dxy

@@ -680,6 +680,7 @@ INPUT                  = src/Overview.txt \
                          src/UsingTrustZone.txt \
                          src/Template.txt \
                          src/MISRA.txt \
+                         src/Ref_CompilerControl.txt \
                          src/Ref_Peripheral.txt \
                          src/Ref_SystemAndClock.txt \
                          src/Ref_NVIC.txt \

CMSIS/DoxyGen/Core/src/Ref_CompilerControl.txt

@@ -0,0 +1,176 @@
+/**************************************************************************************************/
+/**
+\defgroup   compiler_conntrol_gr    Compiler Control
+\brief      Compiler specific \#defines in CMSIS-Core
+\details
+CMSIS-Core provides a set of compiler control \#defines that produce a consistent behavior, no matter which compiler is used
+to build the application code.
+@{
+*/
+
+/**************************************************************************************************/
+/**
+\def __ASM
+\brief Keyword passing information from the compiler to the assembler.
+\details
+The \b __ASM keyword can declare or define an embedded assembly function or incorporate inline assembly into a function
+(shown in the code example below).
+ 
+<b>Code Example:</b>
+\code
+// Reverse bit order of value
+ 
+__attribute__( ( always_inline ) ) __STATIC_INLINE uint32_t __RBIT(uint32_t value)
+{
+  uint32_t result;
+ 
+   __ASM volatile ("rbit %0, %1" : "=r" (result) : "r" (value) );
+   return(result);
+}
+\endcode
+
+*/
+#define __ASM
+
+/**************************************************************************************************/
+/**
+\def __INLINE
+\brief Keyword suggesting to the compiler that it compiles a C or C++ function inline.
+\details
+Inline functions offer a trade-off between code size and performance. By default, the compiler decides for itself whether to
+inline code or not.
+
+In most circumstances, the decision to inline a particular function is best left to the compiler. However, you can give the
+compiler a hint that a function is required to be inlined by using \b __INLINE. Still, the compiler can decide not to inline
+the function.
+
+<b> Code Example:</b>
+\code
+const uint32_t led_mask[] = {1UL << 4, 1UL << 5, 1UL << 6, 1UL << 7};
+ 
+/*------------------------------------------------------------------------------
+  Switch on LEDs
+ *------------------------------------------------------------------------------*/
+__INLINE static void LED_On (uint32_t led) {
+ 
+  PTD->PCOR   = led_mask[led];
+}
+\endcode
+
+*/
+#define __INLINE
+
+/**************************************************************************************************/
+/**
+\def __STATIC_INLINE
+\brief Keyword suggesting to the compiler that it compiles a C or C++ function statically inline.
+\details
+As for \ref __INLINE, the compiler may choose to inline the function. In addition, the compiler will add a locally scoped
+version of the function in the resulting object file. As you can have one static version of the function per object file, you
+may end up with multiple definitions of the same function. This will require more space.
+
+<b> Code Example:</b>
+\code
+// Set Priority Grouping
+ 
+__STATIC_INLINE void NVIC_SetPriorityGrouping(uint32_t PriorityGroup)
+{
+  uint32_t reg_value;
+  uint32_t PriorityGroupTmp = (PriorityGroup & (uint32_t)0x07);               /* only values 0..7 are used          */
+ 
+  reg_value  =  SCB->AIRCR;                                                   /* read old register configuration    */
+  reg_value &= ~(SCB_AIRCR_VECTKEY_Msk | SCB_AIRCR_PRIGROUP_Msk);             /* clear bits to change               */
+  reg_value  =  (reg_value                                 |
+                ((uint32_t)0x5FA << SCB_AIRCR_VECTKEY_Pos) |
+                (PriorityGroupTmp << 8));                                     /* Insert write key and priorty group */
+  SCB->AIRCR =  reg_value;
+}
+\endcode
+
+*/
+#define __STATIC_INLINE
+
+/**************************************************************************************************/
+/**
+\def __NO_RETURN
+\brief Informs the compiler that the function does not return.
+\details
+The compiler can perform optimizations by removing code that is never reached. If the function reaches an explicit or
+implicit return, \b __NO_RETURN is ignored and the compiler generates a warning.
+ 
+<b> Code Example:</b>
+\code
+// OS idle demon (running when no other thread is ready to run).
+ 
+__NO_RETURN void os_idle_demon (void);
+\endcode
+
+*/
+#define __NO_RETURN
+
+/**************************************************************************************************/
+/**
+\def __USED
+\brief Informs the compiler that a static variable is to be retained in the object file.
+\details
+Data marked with \b __USED is tagged in the object file to avoid removal by linker unused section removal. Static variables
+marked as used are emitted to a single section, in the order they are declared.
+ 
+<b> Code Example:</b>
+\code
+/* Export following defines to debugger. */
+__USED uint32_t const CMSIS_RTOS_API_Version = osCMSIS;
+__USED uint32_t const CMSIS_RTOS_RTX_Version = osCMSIS_RTX;
+__USED uint32_t const os_clockrate = OS_TICK;
+__USED uint32_t const os_timernum  = 0;
+\endcode
+
+*/
+#define __USED
+
+/**************************************************************************************************/
+/**
+\def __WEAK
+\brief Keyword instructing the compiler to export a function or variable weakly.
+\details
+Functions defined with \b __WEAK export their symbols weakly. A weakly defined function behaves like a normally defined
+function unless a nonweakly defined function of the same name is linked into the same image. If both a nonweakly defined
+function and a weakly defined function exist in the same image then all calls to the function resolve to call the nonweak
+function.
+
+Functions declared with \b __WEAK and then defined without \b __WEAK behave as nonweak functions.
+ 
+<b> Code Example:</b>
+\code
+__WEAK void SystemInit(void)
+{
+  SystemCoreSetup();
+  SystemCoreClockSetup(); 
+}
+\endcode
+
+*/
+#define __WEAK
+
+/**************************************************************************************************/
+/**
+\def __UNALIGNED_UINT32
+\brief Pointer to unaligned uint32_t variable.
+\details
+Defines a pointer to a uint32_t from an address that does not need to be aligned. This can then be used in read/write
+operations. The compiler will generate the appropriate access (aligned or non-aligned) depending on the underlying ARM
+processor core and compiler settings.
+ 
+<b> Code Example:</b>
+\code
+uint32_t val32;
+
+void test (uint8_t *ptr) {
+  __PACKED_UINT32_POINTER(ptr) = val32;
+}
+\endcode
+
+*/
+#define __UNALIGNED_UINT32
+
+/** @} */ /** end of compiler_conntrol_gr **/

CMSIS/DoxyGen/Core/src/Ref_Peripheral.txt

@@ -182,7 +182,9 @@ Bit field definitions for register CPUID in SCB (System Control Block).
 
 The macros <b>_VAL2FLD(field, value)</b> and <b>_FLD2VAL(field, value)</b> enable access to bit fields.
 @{
+*/
 
+/**
 \def _VAL2FLD(field, value)
 \param         field        name of bit field.
 \param         value        value for the bit field. This parameter is interpreted as an uint32_t type.