CMSIS-Core(A): Fixed references in documentation.

CMSIS/DoxyGen/Core_A/core_A.dxy

@@ -750,12 +750,18 @@ WARN_LOGFILE           =
 # Note: If this tag is empty the current directory is searched.
 
 INPUT                  = src/Overview.txt \
-						 src/Using.txt \
-						 src/Template.txt \
+                         src/Using.txt \
+                         src/Template.txt \
+                         src/MISRA.txt \
+                         src/Ref_SystemAndClock.txt \
                          ../../Core_A/Include/core_ca.h \
                          src/core_ca.txt \
                          ../../Core_A/Include/cmsis_armcc.h \
-                         src/cmsis_armcc.txt
+                         src/cmsis_armcc.txt \
+                         ../../../Device/ARM/ARMCA9/Include/ARMCA9.h \
+                         ../../../Device/ARM/ARMCA9/Include/mem_ARMCA9.h \
+                         ../../../Device/ARM/ARMCA9/Include/system_ARMCA9.h \
+                         ../../../Device/ARM/ARMCA9/Source/AC6/startup_ARMCA9.c
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

CMSIS/DoxyGen/Core_A/src/MISRA.txt

@@ -0,0 +1,65 @@
+/** \page coreMISRA_Exceptions_pg MISRA-C Deviations
+CMSIS-Core (Cortex-A) uses the common coding rules for CMSIS components that are documented under 
+<a href="../../General/html/index.html"><b>Introduction</b></a>.
+
+
+CMSIS-Core (Cortex-A) violates the following MISRA-C:2004 rules:
+
+TO BE EVALUATED
+*/
+/*  
+- Required Rule 8.5, object/function definition in header file.<br>
+  Violated since function definitions in header files are used for function inlining'. 
+   
+- Advisory Rule 12.4, Side effects on right hand side of logical operator.<br>
+  Violated because volatile is used for core register definitions. 
+   
+- Advisory Rule 14.7, Return statement before end of function.<br>
+  Violated to simplify code logic. 
+
+- Required Rule 18.4, declaration of union type or object of union type: '{...}'.<br>
+  Violated since unions are used for effective representation of core registers.
+   
+- Advisory Rule 19.4, Disallowed definition for macro.<br>
+  Violated since macros are used for assembler keywords. 
+   
+- Advisory Rule 19.7, Function-like macro defined.<br>
+  Violated since function-like macros are used to generate more efficient code. 
+   
+- Advisory Rule 19.16, all preprocessing directives must be valid.<br>
+  Violated to set default settings for macros. 
+*/
+
+/**
+CMSIS-Core (Cortex-A) violates the following MISRA-C:2012 rules:
+
+TO BE EVALUATED
+*/
+/*
+- Directive 4.9, function-like macro defined.<br>
+  Violated since function-like macros are used to generate more efficient code. 
+   
+- Rule 1.3, multiple use of '#/##' operators in macro definition.<br>
+  Violated since function-like macros are used to generate more efficient code. 
+   
+- Rule 11.4, conversion between a pointer and integer type.<br>
+  Violated because of core register access. 
+   
+- Rule 11.6, cast from unsigned long to pointer.<br>
+  Violated because of core register access. 
+   
+- Rule 13.5, side effects on right hand side of logical operator.<br>
+  Violated because of shift operand is used in macros and functions. 
+   
+- Rule 14.4, conditional expression should have essentially Boolean type.<br>
+  Violated since macros with several instructions are used.
+  
+- Rule 15.5, return statement before end of function.<br>
+  Violated to simplify code logic. 
+
+- Rule 20.10, '#/##' operators used.<br>
+  Violated since function-like macros are used to generate more efficient code. 
+   
+- Rule 21.1, reserved to the compiler.<br>
+  Violated since macros with leading underscores are used. 
+*/   

CMSIS/DoxyGen/Core_A/src/Ref_SystemAndClock.txt

@@ -0,0 +1,88 @@
+/* ################################  System and Clock Configuration   ########################### */
+/**************************************************************************************************/
+/**
+\defgroup   system_init_gr   System and Clock Configuration
+\brief Functions for system and clock setup available in system_<i>device</i>.c.
+\details
+ARM provides a template file <b>system_<i>device</i>.c</b> that must be adapted by 
+the silicon vendor to match their actual device. As a <b>minimum requirement</b>, 
+this file must provide:
+ -  A device-specific system configuration function, \ref SystemInit().
+ -  A global variable that contains the system frequency, \ref SystemCoreClock. 
+
+The file configures the device and, typically, initializes the oscillator (PLL) that is part 
+of the microcontroller device. This file might export other functions or variables that provide 
+a more flexible configuration of the microcontroller system.
+
+
+\section system_init_code_ex_sec Code Example     
+The code below shows the usage of the variable \ref SystemCoreClock and the functions 
+SystemInit() and SystemCoreClockUpdate() with an arbitratry ARM Cortex-A9.
+    
+\code
+#include "ARMCA9.h"
+
+uint32_t coreClock_1 = 0;                       /* Variables to store core clock values */
+uint32_t coreClock_2 = 0;
+
+
+int main (void)  {
+
+  coreClock_1 = SystemCoreClock;                /* Store value of predefined SystemCoreClock */
+
+  SystemCoreClockUpdate();                      /* Update SystemCoreClock according to register settings */
+
+  coreClock_2 = SystemCoreClock;                /* Store value of calculated SystemCoreClock */
+
+  if (coreClock_2 != coreClock_1)  {            /* Without changing the clock setting both core clock values should be the same */ 
+    // Error Handling
+  }
+
+  while(1);
+}
+\endcode    
+    
+@{
+*/
+
+
+/**************************************************************************************************/
+/** 
+    \brief      Variable to hold the system core clock value
+    \details
+    Holds the system core clock, which is the system clock	frequency supplied to the SysTick 
+    timer and the processor core clock. This variable can be used by debuggers to query the 
+    frequency of the debug timer or to configure the trace clock speed.
+                     
+    \attention  Compilers must be configured to avoid removing this variable in case the application 
+                program is not using it. Debugging systems require the variable to be physically 
+                present in memory so that it can be examined to configure the debugger.
+*/
+uint32_t SystemCoreClock;
+
+
+/**************************************************************************************************/
+/** 
+    \brief      Function to Initialize the system.
+    \details    
+    Initializes the microcontroller system. Typically, this function configures the 
+                     oscillator (PLL) that is part of the microcontroller device. For systems 
+                     with a variable clock speed, it updates the variable \ref SystemCoreClock.
+                     SystemInit is called from the file <b>startup<i>_device</i></b>.
+*/
+void SystemInit (void);
+
+
+/**************************************************************************************************/
+/** 
+    \brief      Function to update the variable \ref SystemCoreClock
+    \details    
+    Updates the variable \ref SystemCoreClock and must be called whenever the core clock is changed 
+    during program execution. The function evaluates the clock register settings and calculates 
+    the current core clock.
+*/
+void SystemCoreClockUpdate (void);
+
+
+/** @} */  /* end group system_init_gr */
+

CMSIS/DoxyGen/Core_A/src/Template.txt

@@ -120,6 +120,7 @@ The device configuration of the template files is described in detail on the fol
   - \subpage startup_c_pg
   - \subpage system_c_pg
   - \subpage device_h_pg
+  - \subpage mem_h_pg
   - \subpage mmu_c_pg
 */
 
@@ -225,32 +226,38 @@ The \ref device_h_pg contains the following sections that are device specific:
 \section interrupt_number_sec Interrupt Number Definition
 
 \ref device_h_pg contains the enumeration \ref IRQn_Type that defines all exceptions and interrupts of the device.
-  - Negative IRQn values represent processor core exceptions (internal interrupts).
-  - Positive IRQn values represent device-specific exceptions (external interrupts). The first device-specific interrupt has the IRQn value 0.
-    The IRQn values needs extension to reflect the device-specific interrupt vector table in the \ref startup_s_pg.
-
+For devices implementing an ARM GIC these are defined as:
+  - IRQn 0-15 represents software generated interrupts (SGI), local to each processor core.
+  - IRQn 16-31 represents private peripheral interrupts (PPI), local to each processor core.
+  - IRQn 32-1019 represents shared peripheral interrups (SPI), routeable to all processor cores.
+  - IRQn 1020-1023 represents special interrupts, refer to the GIC Architecture Specification.
 \b Example:
 
-The following example shows the extension of the interrupt vector table for the LPC1100 device family.
+The following example shows the extension of the interrupt vector table for Cortex-A9 class device.
 
 \code
 typedef enum IRQn
 {
-/******  Cortex-M0 Processor Exceptions Numbers ***************************************************/
-  NonMaskableInt_IRQn           = -14,      /*!< 2 Non Maskable Interrupt                         */
-  HardFault_IRQn                = -13,      /*!< 3 Cortex-M0 Hard Fault Interrupt                 */
-  SVCall_IRQn                   = -5,       /*!< 11 Cortex-M0 SV Call Interrupt                   */
-  PendSV_IRQn                   = -2,       /*!< 14 Cortex-M0 Pend SV Interrupt                   */
-  SysTick_IRQn                  = -1,       /*!< 15 Cortex-M0 System Tick Interrupt               */
-
-/******  LPC11xx/LPC11Cxx Specific Interrupt Numbers **********************************************/
-  WAKEUP0_IRQn                  = 0,        /*!< All I/O pins can be used as wakeup source.       */
-  WAKEUP1_IRQn                  = 1,        /*!< There are 13 pins in total for LPC11xx           */
-  WAKEUP2_IRQn                  = 2,
-                 :       :
-                 :       :
-  EINT1_IRQn                    = 30,       /*!< External Interrupt 1 Interrupt                   */
-  EINT0_IRQn                    = 31,       /*!< External Interrupt 0 Interrupt                   */
+/******  SGI Interrupts Numbers                 ****************************************/
+  SGI0_IRQn            =  0,      
+  SGI1_IRQn            =  1,
+  SGI2_IRQn            =  2,
+       :                  :
+  SGI15_IRQn           = 15,
+
+/******  Cortex-A9 Processor Exceptions Numbers ****************************************/
+  GlobalTimer_IRQn     = 27,        /*!< Global Timer Interrupt                        */
+  PrivTimer_IRQn       = 29,        /*!< Private Timer Interrupt                       */
+  PrivWatchdog_IRQn    = 30,        /*!< Private Watchdog Interrupt                    */
+
+/******  Platform Exceptions Numbers ***************************************************/
+  Watchdog_IRQn        = 32,        /*!< SP805 Interrupt        */
+  Timer0_IRQn          = 34,        /*!< SP804 Interrupt        */
+  Timer1_IRQn          = 35,        /*!< SP804 Interrupt        */
+  RTClock_IRQn         = 36,        /*!< PL031 Interrupt        */
+  UART0_IRQn           = 37,        /*!< PL011 Interrupt        */
+       :                  :
+       :                  :
 } IRQn_Type;
 \endcode
 
@@ -792,3 +799,20 @@ The \ref system_Device_h_sec which is provided as part of the CMSIS specificatio
 \verbinclude "Include\Device.h"
 
 */
+
+/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
+/**
+\page mem_h_pg Memory Configuration Files mem_<device>.h
+
+\verbinclude "Include\mem_Device.h"
+
+*/
+
+/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
+/**
+\page mmu_c_pg Memory Management Unit Files mmu_<device>.c
+
+\verbinclude "Source\mmu_Device.c"
+
+*/
+

CMSIS/DoxyGen/Core_A/src/Using.txt

@@ -11,11 +11,11 @@ To use the CMSIS-Core-A the following files are added to the embedded applicatio
  - \ref mem_h_pg contains basic memory configurations.
  - \ref mmu_c_pg contains the memory management unit setup.
  
-\note The files \ref startup_c_pg, \ref system_c_pg, \ref mem_h_pg, and \ref mmu_h_pg may require application specific adaptations and therefore should be copied 
+\note The files \ref startup_c_pg, \ref system_c_pg, \ref mem_h_pg, and \ref mmu_c_pg may require application specific adaptations and therefore should be copied 
       into the application project folder prior configuration. The \ref device_h_pg is included in all source files that need device access 
 	  and can be stored on a central include folder that is generic for all projects.
 
-The \ref ResetHandler defined in \ref startup_c_pg is executed after reset. 
+The \ref Reset_Handler defined in \ref startup_c_pg is executed after reset. 
 The default initialization sequence is
  - set the vector base address register (\ref __set_VBAR),
  - set stacks for each exception mode (\ref __set_mode, \ref __set_SP),
@@ -31,10 +31,10 @@ and floating point unit. The variable \ref SystemCoreClock indicates the CPU clo
 
 The \ref device_h_pg is the central include file that the application programmer is using in the C/C++ source code. It provides the following features:
  - \ref peripheral_gr provides a standardized register layout for all peripherals. Optionally functions for device-specific peripherals may be available.
- - \ref GIC_gr can be accessed with standardized symbols and functions for the General Interrupt Controller (GIC) are provided.
- - \ref intrinsic_CPU_gr allow to access special instructions, for example for activating sleep mode or the NOP instruction.
- - \ref timer_gr Generic and Private Timer functions to configure and start a periodic timer interrupt.
- - \ref cache_gr Level 1 and Level 2 Cache controller functions to enable, disable, clean and invalidate caches.
+ - \ref GIC_functions can be accessed with standardized symbols and functions for the General Interrupt Controller (GIC) are provided.
+ - \ref CMSIS_Core_InstructionInterface allow to access special instructions, for example for activating sleep mode or the NOP instruction.
+ - \ref PL1_timer_functions "Generic" and \ref PTM_timer_functions "Private" Timer functions to configure and start a periodic timer interrupt.
+ - \ref L1_chache_functions "Level 1" and \ref L2_chache_functions "Level 2" Cache controller functions to enable, disable, clean and invalidate caches.
 
 \image html "CMSIS_CORE_A_Files_user.png" "CMSIS-Core-A User Files"
 
@@ -124,6 +124,13 @@ The table below lists the folder and device names of the ARM processors.
       <th>Processor</th>
       <th>Description</th>
     </tr>
+    <tr>
+      <td>".\Device\ARM\ARMCA5"</td>
+      <td>Cortex-A5</td>
+      <td>Contains \b Include and \b Source template files configured for the Cortex-A5 processor.
+	      The device name is ARMCA5 and the name of the \ref device_h_pg is <ARMCA5.h>.
+	  </td>
+    </tr>
     <tr>
       <td>".\Device\ARM\ARMCA7"</td>
       <td>Cortex-A7</td>

Device/ARM/ARMCA9/Include/ARMCA9.h

@@ -35,25 +35,26 @@ extern "C" {
 
 /* -------------------------  Interrupt Number Definition  ------------------------ */
 
+/** Device specific Interrupt IDs */
 typedef enum IRQn
 {
 /******  SGI Interrupts Numbers                 ****************************************/
-  SGI0_IRQn            =  0,
-  SGI1_IRQn            =  1,
-  SGI2_IRQn            =  2,
-  SGI3_IRQn            =  3,
-  SGI4_IRQn            =  4,
-  SGI5_IRQn            =  5,
-  SGI6_IRQn            =  6,
-  SGI7_IRQn            =  7,
-  SGI8_IRQn            =  8,
-  SGI9_IRQn            =  9,
-  SGI10_IRQn           = 10,
-  SGI11_IRQn           = 11,
-  SGI12_IRQn           = 12,
-  SGI13_IRQn           = 13,
-  SGI14_IRQn           = 14,
-  SGI15_IRQn           = 15,
+  SGI0_IRQn            =  0,        /*!< Software Generated Interrupt 0 */
+  SGI1_IRQn            =  1,        /*!< Software Generated Interrupt 1 */
+  SGI2_IRQn            =  2,        /*!< Software Generated Interrupt 2 */
+  SGI3_IRQn            =  3,        /*!< Software Generated Interrupt 3 */
+  SGI4_IRQn            =  4,        /*!< Software Generated Interrupt 4 */
+  SGI5_IRQn            =  5,        /*!< Software Generated Interrupt 5 */
+  SGI6_IRQn            =  6,        /*!< Software Generated Interrupt 6 */
+  SGI7_IRQn            =  7,        /*!< Software Generated Interrupt 7 */
+  SGI8_IRQn            =  8,        /*!< Software Generated Interrupt 8 */
+  SGI9_IRQn            =  9,        /*!< Software Generated Interrupt 9 */
+  SGI10_IRQn           = 10,        /*!< Software Generated Interrupt 10 */
+  SGI11_IRQn           = 11,        /*!< Software Generated Interrupt 11 */
+  SGI12_IRQn           = 12,        /*!< Software Generated Interrupt 12 */
+  SGI13_IRQn           = 13,        /*!< Software Generated Interrupt 13 */
+  SGI14_IRQn           = 14,        /*!< Software Generated Interrupt 14 */
+  SGI15_IRQn           = 15,        /*!< Software Generated Interrupt 15 */
 
 /******  Cortex-A9 Processor Exceptions Numbers ****************************************/
   GlobalTimer_IRQn     = 27,        /*!< Global Timer Interrupt                        */

Device/ARM/ARMCA9/Source/AC6/startup_ARMCA9.c

@@ -41,7 +41,13 @@
 /*----------------------------------------------------------------------------
   Internal References
  *----------------------------------------------------------------------------*/
+
+/** \brief Exception and Interrupt Handler Jumptable.
+*/
 void Vectors       (void) __attribute__ ((naked, section("RESET")));
+
+/** \brief Reset Handler
+*/
 void Reset_Handler (void) __attribute__ ((naked));
 
 /*----------------------------------------------------------------------------