begriffs open source - cmsis/blob - CMSIS/DoxyGen/Core_A/src/core_ca.txt

   1 /**************************************************************************//**
   2  * @file     core_ca.txt
   3  * @brief    CMSIS Cortex-A Core Peripheral Access Layer Header File
   4  ******************************************************************************/
   5
   6 /* IO definitions (access restrictions to peripheral registers) */
   7 /**
   8 \defgroup   peripheral_gr    Peripheral Access
   9 \brief      Naming conventions and optional features for accessing peripherals.
  10 \details
  11 The section below describes the naming conventions, requirements, and optional features for accessing device specific peripherals.
  12 Most of the rules also apply to the core peripherals.  The \ref device_h_pg "Device Header File \<device.h>" contains typically these definition and also includes
  13 the core specific header files.
  14
  15 The definitions for \ref peripheral_gr can be generated using the <a href="../../SVD/html/index.html"><b>CMSIS-SVD</b></a> System View Description for Peripherals.
  16 Refer to <a href="../../SVD/html/svd_SVDConv_pg.html"><b>SVDConv.exe</b></a> for more information.
  17
  18 Each peripheral provides a data type definition with a name that is composed of:
  19   - an optional prefix <b>&lt;<i>device abbreviation&gt;</i>_</b>
  20   - <b>&lt;<i>peripheral name</i>&gt;</b>
  21   - postfix \b _Type or \b _TypeDef to identify a type definition.
  22
  23 Examples:
  24   - \b UART_TypeDef for the peripheral \b UART.
  25   - \b IMX_UART_TypeDef for the device family \b IMX and the peripheral \b UART.
  26
  27 The data type definition uses standard C data types defined by the ANSI C header file <stdint.h>.
  28
  29  - IO Type Qualifiers are used to specify the access to peripheral variables.
  30    IO Type Qualifier  | Type            | Description
  31    :------------------|:----------------|:------------
  32    \b __IM            | Struct member   | Defines 'read only' permissions
  33    \b __OM            | Struct member   | Defines 'write only' permissions
  34    \b __IOM           | Struct member   | Defines 'read / write' permissions
  35    \b __I             | Scalar variable | Defines 'read only' permissions
  36    \b __O             | Scalar variable | Defines 'write only' permissions
  37    \b __IO            | Scalar variable | Defines 'read / write' permissions
  38
  39 The typedef <b>\<<i>device abbreviation</i>\>_UART_TypeDef</b> shown below defines the generic register layout for all UART channels in a device.
  40
  41 \code
  42 typedef struct {
  43         __O  uint32_t UART_CR;            // Offset: 0x0000 ( /W) Control Register
  44         __IO uint32_t UART_MR;            // Offset: 0x0004 (R/W) Mode Register
  45         __O  uint32_t UART_IER;           // Offset: 0x0008 ( /W) Interrupt Enable Register
  46         __O  uint32_t UART_IDR;           // Offset: 0x000C ( /W) Interrupt Disable Register
  47         __I  uint32_t UART_IMR;           // Offset: 0x0010 (R/ ) Interrupt Mask Register
  48         __I  uint32_t UART_SR;            // Offset: 0x0014 (R/ ) Status Register
  49         __I  uint32_t UART_RHR;           // Offset: 0x0018 (R/ ) Receive Holding Register
  50         __O  uint32_t UART_THR;           // Offset: 0x001C ( /W) Transmit Holding Register
  51         __IO uint32_t UART_BRGR;          // Offset: 0x0020 (R/W) Baud Rate Generator Register
  52         __IO uint32_t UART_CMPR;          // Offset: 0x0024 (R/W) Comparison Register
  53         __IO uint32_t UART_RTOR;          // Offset: 0x0028 (R/W) Receiver Time-out Register
  54         __I  uint32_t RESERVED[46];       // Offset: 0x002C (R/ ) Reserved
  55         __IO uint32_t UART_WPMR;          // Offset: 0x00E4 (R/W) Write Protection Mode Register
  56 } IMX_UART_TypeDef;
  57 \endcode
  58
  59 To access the registers of the UART defined above, pointers to this register structure are defined.
  60 If more instances of a peripheral exist, the variables have a postfix (digit or letter) that identifies the peripheral.
  61
  62 \b Example:
  63 In this example, \b IMX_UART2 and \b IMX_UART3 are two pointers to UARTs defined with above register structure.
  64 \n
  65 \code
  66 #define IMX_UART2   ((IMX_UART_TypeDef *) IMX_UART2_BASE)
  67 #define IMX_UART3   ((IMX_UART_TypeDef *) IMX_UART3_BASE)
  68 \endcode
  69
  70 \note
  71  - The prefix <b>IMX</b> is optional.
  72
  73 The registers in the various UARTs can now be referred in the user code as shown below:\n
  74 \code
  75  val = IMX_UART2->SR   // is the Status Register of UART2.
  76 \endcode
  77
  78 <hr>
  79
  80 \section core_cmsis_pal_min_reqs Minimal Requirements
  81 \details
  82  To access the peripheral registers and related function in a device, the files <b><i>device.h</i></b> and <b>core_ca.h</b> define as a minimum:
  83 \n\n
  84 - The <b>Register Layout Typedef</b> for each peripheral that defines all register names.
  85   RESERVED is used to introduce space into the structure for adjusting the addresses of
  86   the peripheral registers.
  87 \n\n
  88 <b>Example:</b>
  89 \code
  90 typedef struct
  91 {
  92   __IOM uint32_t C_CTLR;              // Offset: 0x0000 (R/W) CPU Interface Control Register
  93   __IOM uint32_t C_PMR;               // Offset: 0x0004 (R/W) Interrupt Priority Mask Register
  94   __IOM uint32_t C_BPR;               // Offset: 0x0008 (R/W) Binary Point Register
  95   __IM  uint32_t C_IAR;               // Offset: 0x000C (R/ ) Interrupt Acknowledge Register
  96   __OM  uint32_t C_EOIR;              // Offset: 0x0010 ( /W) End Of Interrupt Register
  97   __IM  uint32_t C_RPR;               // Offset: 0x0014 (R/ ) Running Priority Register
  98   __IM  uint32_t C_HPPIR;             // Offset: 0x0018 (R/ ) Highest Priority Pending Interrupt Register
  99   __IOM uint32_t C_ABPR;              // Offset: 0x001C (R/W) Aliased Binary Point Register
 100   __IM  uint32_t C_AIAR;              // Offset: 0x0020 (R/ ) Aliased Interrupt Acknowledge Register
 101   __OM  uint32_t C_AEOIR;             // Offset: 0x0024 ( /W) Aliased End Of Interrupt Register
 102   __IM  uint32_t C_AHPPIR;            // Offset: 0x0028 (R/ ) Aliased Highest Priority Pending Interrupt Register
 103   __IOM uint32_t C_STATUSR;           // Offset: 0x002C (R/W) Error Reporting Status Register, optional
 104   __I   uint32_t RESERVED1[40];       // Offset: 0x0030 (R/ ) Reserved
 105   __IOM uint32_t C_APR[4];            // Offset: 0x00D0 (R/W) Active Priority Register
 106   __IOM uint32_t C_NSAPR[4];          // Offset: 0x00E0 (R/W) Non-secure Active Priority Register
 107   __I   uint32_t RESERVED2[3];        // Offset: 0x00F6 (R/ ) Reserved
 108   __IM  uint32_t C_IIDR;              // Offset: 0x00FC (R/ ) CPU Interface Identification Register
 109   __I   uint32_t RESERVED3[960];      // Offset: 0x0100 (R/ ) Reserved
 110   __OM  uint32_t C_DIR;               // Offset: 0x1000 ( /W) Deactivate Interrupt Register
 111 }  GICInterface_Type;
 112 \endcode
 113
 114
 115 - <b>Base Address</b> for each peripheral (in case of multiple peripherals
 116     that use the same <b>register layout typedef</b> multiple base addresses are defined).
 117     \n\n
 118 <b>Example:</b>
 119 \code
 120 #define GIC_INTERFACE_BASE (0xe8202000UL)   // GIC Interface Base Address
 121 \endcode
 122
 123
 124 - <b>Access Definitions</b> for each peripheral. In case of multiple peripherals that are using the same
 125     <b>register layout typedef</b>, multiple access definitions exist.
 126     \n\n
 127 <b>Example:</b>
 128 \code
 129 #define GICInterface   ((GICInterface_Type *) GIC_INTERFACE_BASE)   // GIC Interface Access Definition
 130 \endcode
 131
 132
 133 These definitions allow accessing peripheral registers with simple assignments.
 134
 135 - <b>Example:</b>
 136   \n
 137 \code
 138 GICInterface->C_CTLR |= 1;   // Enable Interface
 139 \endcode
 140
 141 <hr>
 142
 143 \section core_cmsis_pal_opts Optional Features
 144 \details
 145 Optionally, the file <b><i>device</i>.h</b> may define:
 146
 147 -  \ref core_cmsis_pal_bitfields and \#define constants that simplify access to peripheral registers.
 148         These constants may define bit-positions or other specific patterns that are required for
 149     programming peripheral registers. The identifiers should start with
 150     <b>&lt;<i>device abbreviation</i>&gt;_</b> and <b>&lt;<i>peripheral name</i>&gt;_</b>.
 151     It is recommended to use CAPITAL letters for \#define constants.
 152
 153 -   More complex functions (i.e. status query before
 154     a sending register is accessed). Again, these functions start with
 155     <b>&lt;<i>device abbreviation</i>&gt;_</b> and <b>&lt;<i>peripheral name</i>&gt;_</b>.
 156
 157 <hr>
 158
 159 \section core_cmsis_pal_bitfields Register Bit Fields
 160 \details
 161
 162 For Core Register, macros define the position and the mask value for a bit field.
 163
 164 <b>Example:</b>
 165
 166 Bit field definitions for register ACTLR in CP15.
 167
 168
 169 \code
 170 // CP15 Register ACTLR
 171 #define ACTLR_DDI_Pos                  28U
 172 #define ACTLR_DDI_Msk                  (1UL << ACTLR_DDI_Pos)
 173
 174 #define ACTLR_DDVM_Pos                 15U
 175 #define ACTLR_DDVM_Msk                 (1UL << ACTLR_DDVM_Pos)
 176
 177 #define ACTLR_L1PCTL_Pos               13U
 178 #define ACTLR_L1PCTL_Msk               (3UL << ACTLR_L1PCTL_Pos)
 179
 180 #define ACTLR_L1RADIS_Pos              12U
 181 #define ACTLR_L1RADIS_Msk              (1UL << ACTLR_L1RADIS_Pos)
 182
 183 #define ACTLR_L2RADIS_Pos              11U
 184 #define ACTLR_L2RADIS_Msk              (1UL << ACTLR_L2RADIS_Pos)
 185
 186 #define ACTLR_DODMBS_Pos               10U
 187 #define ACTLR_DODMBS_Msk               (1UL << ACTLR_DODMBS_Pos)
 188
 189 #define ACTLR_SMP_Pos                  6U
 190 #define ACTLR_SMP_Msk                  (1UL << ACTLR_SMP_Pos)
 191 \endcode
 192
 193 The macros <b>_VAL2FLD(field, value)</b> and <b>_FLD2VAL(field, value)</b> enable access to bit fields.
 194 @{
 195 */
 196
 197 /**
 198 \def _VAL2FLD(field, value)
 199 \param         field        name of bit field.
 200 \param         value        value for the bit field. This parameter is interpreted as an uint32_t type.
 201 \brief Mask and shift a bit field value for assigning the result to a peripheral register.
 202 \details
 203 The macro \ref _VAL2FLD uses the \#define's <i>_Pos</i> and <i>_Msk</i> of the related bit field to shift bit-field values for
 204 assigning to a register.
 205
 206 <b>Example:</b>
 207 \code
 208   ACTLR = _VAL2FLD(ACTLR_SMP, 0x1)
 209 \endcode
 210
 211 */
 212 #define _VAL2FLD(field, value)
 213
 214 /**
 215
 216 \def _FLD2VAL(field, value)
 217 \param         field        name of bit field.
 218 \param         value        value of the register. This parameter is interpreted as an uint32_t type.
 219 \brief Extract from a peripheral register value the a bit field value.
 220 \details
 221 The macro \ref _FLD2VAL uses the \#define's <i>_Pos</i> and <i>_Msk</i> of the related bit field to extract the value of a bit field from a register.
 222
 223 <b>Example:</b>
 224 \code
 225   i = _FLD2VAL(ACTLR_SMP, ACTLR);
 226 \endcode
 227
 228 */
 229 #define _FLD2VAL(field, value)
 230
 231 /** @} */
 232 /*end of group peripheral_gr */
 233
 234
 235 /*******************************************************************************
 236  *                 CMSIS definitions
 237  ******************************************************************************/
 238 /**
 239 \defgroup version_ctrl Version Control
 240 \brief Version symbols for CMSIS release specific C/C++ source code.
 241
 242 @{
 243 */
 244
 245 /*  CMSIS CA definitions */
 246 /**
 247 \def __CA_CMSIS_VERSION_MAIN
 248 \details
 249 Use this define to query the major version of CMSIS-Core(A) component.
 250
 251 \b Example:
 252 \code
 253 #if __CA_CMSIS_VERSION_MAIN < 5
 254 #error This code needs at least CMSIS-Core(A) version 5!
 255 #endif
 256 \endcode
 257
 258 \def __CA_CMSIS_VERSION_SUB
 259 \details
 260 Use this define to query the minor version of CMSIS-Core(A) component.
 261
 262 \b Example:
 263 \code
 264 #if __CA_CMSIS_VERSION_MAIN < 5
 265 #error This code needs at least CMSIS-Core(A) version 5!
 266 #else
 267 #if __CA_CMSIS_VERSION_SUB < 1
 268 #warning Using CMSIS-Core(A) version 5.0 compatibility functions.
 269 #endif
 270 #endif
 271 \endcode
 272
 273 \def __CA_CMSIS_VERSION
 274 \details
 275 Use this define to query the full version of CMSIS-Core(A) component.
 276
 277 | Bits    | Name          | Function                |
 278 | :------ | :------------ | :-----------------------|
 279 | [31:16] | MAIN          | __CA_CMSIS_VERSION_MAIN |
 280 | [15:0]  | SUB           | __CA_CMSIS_VERSION_SUB  |
 281
 282
 283 \b Example:
 284 \code
 285 #if __CA_CMSIS_VERSION < 0x00050001
 286 #error This code needs at least CMSIS-Core(A) version 5.1!
 287 #endif
 288 \endcode
 289
 290 \def __CA_REV
 291 \brief Contains the core revision for a Cortex-A class device.
 292 \details
 293 Use this define to query the core design revision number implemented in the selected device.
 294
 295 | Bits    | Name          | Function        |
 296 | :------ | :------------ | :---------------|
 297 | [15:8]  | REV           | Revision number |
 298 | [7:0]   | PATCH         | Patch number    |
 299
 300 \b Example:
 301 \code
 302 #if __CA_REV < 0x0201
 303 #error This code needs at least a core revision r2p1.
 304 #endif
 305 \endcode
 306
 307 \def __CORTEX_A
 308 \brief Contains the core family for a Cortex-A class device.
 309 \details
 310 Use this define to query the actual Cortex-A class device number implemented in the selected device.
 311
 312 \b Example:
 313 \code
 314 #if __CORTEX_A == 5
 315 #warning Running on Cortex-A5.
 316 #elif __CORTEX_A == 7
 317 #warning Running on Cortex-A7.
 318 #elif __CORTEX_A == 9
 319 #warning Running on Cortex-A9.
 320 #endif
 321 \endcode
 322
 323 */
 324 /** @} */
 325 /*end of group version_ctrl */
 326
 327 /**
 328 \defgroup CMSIS_Core_FunctionInterface Core Peripherals
 329 \brief
 330 \details
 331 Hardware Abstraction Layer.
 332    The Core-A function interface contains:
 333    - \ref FPU_functions
 334    - \ref GIC_functions
 335    - \ref L1_cache_functions
 336    - \ref L2_cache_functions
 337    - \ref MMU_functions
 338    - \ref PL1_timer_functions
 339    - \ref PTM_timer_functions
 340
 341 */
 342
 343 /* ##########################  FPU functions  ############################ */
 344 /**
 345 \defgroup FPU_functions Floating Point Unit Functions
 346 \ingroup CMSIS_Core_FunctionInterface
 347 \brief FPU Functions enable the use of Floating Point instructions and extensions.\n
 348 Reference: <a href="http://infocenter.arm.com/help/topic/com.arm.doc.ddi0406c/index.html">Architecture Reference Manual Reference Manual - ARMv7-A and ARMv7-R edition</a>.
 349 @{
 350 \fn __STATIC_INLINE __ASM void __FPU_Enable(void)
 351 @}
 352 */
 353
 354