begriffs open source - cmsis/blob - CMSIS/DoxyGen/Core/src/Ref_Peripheral.txt

   1 /**************************************************************************************************/
   2 /**
   3     \defgroup   peripheral_gr    Peripheral Access
   4     \brief      Naming conventions and optional features for accessing peripherals.
   5     \details
   6
   7 The section below describes the naming conventions, requirements, and optional features for accessing device specific peripherals.
   8 Most of the rules also apply to the core peripherals.  The \ref device_h_pg contains typically these definition and also includes
   9 the core specific header files.
  10
  11 \ifnot FuSaRTS
  12 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.
  13 Refer to <a href="../../SVD/html/svd_SVDConv_pg.html"><b>SVDConv.exe</b></a> for more information.
  14 \endif
  15
  16 Each peripheral provides a data type definition with a name that is composed of:
  17   - an optional prefix <b>&lt;<i>device abbreviation&gt;</i>_</b>
  18   - <b>&lt;<i>peripheral name</i>&gt;</b>
  19   - postfix \b _Type or \b _TypeDef to identify a type definition.
  20
  21 Examples:
  22   - \b UART_TypeDef for the peripheral \b UART.
  23   - \b LPC_UART_TypeDef for the device family \b LPC and the peripheral \b UART.
  24
  25 The data type definition uses standard C data types defined by the ANSI C header file <stdint.h>.
  26
  27  - IO Type Qualifiers are used to specify the access to peripheral variables.
  28    IO Type Qualifier  | Type            | Description
  29    :------------------|:----------------|:------------
  30    \b __IM            | Struct member   | Defines 'read only' permissions
  31    \b __OM            | Struct member   | Defines 'write only' permissions
  32    \b __IOM           | Struct member   | Defines 'read / write' permissions
  33    \b __I             | Scalar variable | Defines 'read only' permissions
  34    \b __O             | Scalar variable | Defines 'write only' permissions
  35    \b __IO            | Scalar variable | Defines 'read / write' permissions
  36
  37 \note
  38 \b __IM, \b __OM, \b __IOM are added in CMSIS-Core V4.20 to enhance support for C++. Prior version used \b __I, \b __O, \b __IO also for struct member definitions.
  39
  40 The typedef <b>\<<i>device abbreviation</i>\>_UART_TypeDef</b> shown below defines the generic register layout for all UART channels in a device.
  41
  42 \code
  43 typedef struct
  44 {
  45   union {
  46   __IM  uint8_t  RBR;                 /* Offset: 0x000 (R/ )  Receiver Buffer Register            */
  47   __OM  uint8_t  THR;                 /* Offset: 0x000 ( /W)  Transmit Holding Register           */
  48   __IOM uint8_t  DLL;                 /* Offset: 0x000 (R/W)  Divisor Latch LSB                   */
  49         uint32_t RESERVED0;
  50   };
  51   union {
  52   __IOM uint8_t  DLM;                 /* Offset: 0x004 (R/W)  Divisor Latch MSB                   */
  53   __IOM uint32_t IER;                 /* Offset: 0x004 (R/W)  Interrupt Enable Register           */
  54   };
  55   union {
  56   __IM  uint32_t IIR;                 /* Offset: 0x008 (R/ )  Interrupt ID Register               */
  57   __OM  uint8_t  FCR;                 /* Offset: 0x008 ( /W)  FIFO Control Register               */
  58   };
  59   __IOM uint8_t  LCR;                 /* Offset: 0x00C (R/W)  Line Control Register               */
  60         uint8_t  RESERVED1[7];
  61   __IM  uint8_t  LSR;                 /* Offset: 0x014 (R/ )  Line Status Register                */
  62         uint8_t  RESERVED2[7];
  63   __IOM uint8_t  SCR;                 /* Offset: 0x01C (R/W)  Scratch Pad Register                */
  64         uint8_t  RESERVED3[3];
  65   __IOM uint32_t ACR;                 /* Offset: 0x020 (R/W)  Autobaud Control Register           */
  66   __IOM uint8_t  ICR;                 /* Offset: 0x024 (R/W)  IrDA Control Register               */
  67         uint8_t  RESERVED4[3];
  68   __IOM uint8_t  FDR;                 /* Offset: 0x028 (R/W)  Fractional Divider Register         */
  69         uint8_t  RESERVED5[7];
  70   __IOM uint8_t  TER;                 /* Offset: 0x030 (R/W)  Transmit Enable Register            */
  71         uint8_t  RESERVED6[39];
  72   __IM  uint8_t  FIFOLVL;             /* Offset: 0x058 (R/ )  FIFO Level Register                 */
  73 } LPC_UART_TypeDef;
  74 \endcode
  75
  76 To access the registers of the UART defined above, pointers to this register structure are defined.
  77 If more instances of a peripheral exist, the variables have a postfix (digit or letter) that identifies the peripheral.
  78
  79 \b Example:
  80 In this example \b LPC_UART2 and \b LPC_UART3 are two pointers to UARTs defined with above register structure.
  81 \n
  82 \code
  83 #define LPC_UART2             ((LPC_UART_TypeDef      *) LPC_UART2_BASE    )
  84 #define LPC_UART3             ((LPC_UART_TypeDef      *) LPC_UART3_BASE    )
  85 \endcode
  86
  87 \note
  88  - The prefix <b>LPC</b> is optional.
  89
  90 The registers in the various UARTs can now be referred in the user code as shown below:\n
  91 \code
  92  val = LPC_UART2->DR   // is the data register of UART1.
  93 \endcode
  94
  95 <hr>
  96
  97 \section core_cmsis_pal_min_reqs Minimal Requirements
  98 \details
  99  To access the peripheral registers and related function in a device, the files <b><i>device.h</i></b> and <b>core_cm<i>#</i>.h</b> define as a minimum:
 100 \n\n
 101 - The <b>Register Layout Typedef</b> for each peripheral that defines all register names.
 102   RESERVED is used to introduce space into the structure for adjusting the addresses of
 103   the peripheral registers.
 104 \n\n
 105 <b>Example:</b>
 106 \code
 107 typedef struct
 108 {
 109   __IOM uint32_t CTRL;                /* Offset: 0x000 (R/W)  SysTick Control and Status Register */
 110   __IOM uint32_t LOAD;                /* Offset: 0x004 (R/W)  SysTick Reload Value Register       */
 111   __IOM uint32_t VAL;                 /* Offset: 0x008 (R/W)  SysTick Current Value Register      */
 112   __IM  uint32_t CALIB;               /* Offset: 0x00C (R/ )  SysTick Calibration Register        */
 113 } SysTick_Type;
 114     \endcode
 115
 116
 117 - <b>Base Address</b> for each peripheral (in case of multiple peripherals
 118     that use the same <b>register layout typedef</b> multiple base addresses are defined).
 119     \n\n
 120 <b>Example:</b>
 121 \code
 122 #define SysTick_BASE (SCS_BASE + 0x0010)            /* SysTick Base Address     */
 123 \endcode
 124
 125
 126 - <b>Access Definitions</b> for each peripheral. In case of multiple peripherals that are using the same
 127     <b>register layout typdef</b>, multiple access definitions exist (LPC_UART0, LPC_UART2).
 128     \n\n
 129 <b>Example:</b>
 130 \code
 131 #define SysTick ((SysTick_Type *) Systick_BASE)    /* SysTick access definition */
 132 \endcode
 133
 134
 135 These definitions allow accessing peripheral registers with simple assignments.
 136
 137 - <b>Example:</b>
 138   \n
 139 \code
 140 SysTick->CTRL = 0;
 141 \endcode
 142
 143 <hr>
 144
 145 \section core_cmsis_pal_opts Optional Features
 146 \details
 147 Optionally, the file <b><i>device</i>.h</b> may define:
 148
 149 -  \ref core_cmsis_pal_bitfields and \#define constants that simplify access to peripheral registers.
 150         These constants may define bit-positions or other specific patterns that are required for
 151     programming peripheral registers. The identifiers should start with
 152     <b>&lt;<i>device abbreviation</i>&gt;_</b> and <b>&lt;<i>peripheral name</i>&gt;_</b>.
 153     It is recommended to use CAPITAL letters for \#define constants.
 154
 155 -   More complex functions (i.e. status query before
 156     a sending register is accessed). Again, these functions start with
 157     <b>&lt;<i>device abbreviation</i>&gt;_</b> and <b>&lt;<i>peripheral name</i>&gt;_</b>.
 158
 159 <hr>
 160
 161 \section core_cmsis_pal_bitfields Register Bit Fields
 162 \details
 163
 164 For Core Register, macros define the position and the mask value for a bit field. It is recommended to create such definitions also
 165 for other peripheral registers.
 166
 167 <b>Example:</b>
 168
 169 Bit field definitions for register CPUID in SCB (System Control Block).
 170
 171
 172 \code
 173 /* SCB CPUID Register Definitions */
 174 #define SCB_CPUID_IMPLEMENTER_Pos      24U                                       /*!< SCB CPUID: IMPLEMENTER Position */
 175 #define SCB_CPUID_IMPLEMENTER_Msk      (0xFFUL << SCB_CPUID_IMPLEMENTER_Pos)     /*!< SCB CPUID: IMPLEMENTER Mask */
 176
 177 #define SCB_CPUID_VARIANT_Pos          20U                                       /*!< SCB CPUID: VARIANT Position */
 178 #define SCB_CPUID_VARIANT_Msk          (0xFUL << SCB_CPUID_VARIANT_Pos)          /*!< SCB CPUID: VARIANT Mask */
 179
 180 #define SCB_CPUID_ARCHITECTURE_Pos     16U                                       /*!< SCB CPUID: ARCHITECTURE Position */
 181 #define SCB_CPUID_ARCHITECTURE_Msk     (0xFUL << SCB_CPUID_ARCHITECTURE_Pos)     /*!< SCB CPUID: ARCHITECTURE Mask */
 182
 183 #define SCB_CPUID_PARTNO_Pos            4U                                       /*!< SCB CPUID: PARTNO Position */
 184 #define SCB_CPUID_PARTNO_Msk           (0xFFFUL << SCB_CPUID_PARTNO_Pos)         /*!< SCB CPUID: PARTNO Mask */
 185
 186 #define SCB_CPUID_REVISION_Pos          0U                                       /*!< SCB CPUID: REVISION Position */
 187 #define SCB_CPUID_REVISION_Msk         (0xFUL /*<< SCB_CPUID_REVISION_Pos*/)     /*!< SCB CPUID: REVISION Mask */
 188 \endcode
 189
 190 The macros <b>_VAL2FLD(field, value)</b> and <b>_FLD2VAL(field, value)</b> enable access to bit fields.
 191 @{
 192 */
 193
 194 /**
 195 \def _VAL2FLD(field, value)
 196 \param         field        name of bit field.
 197 \param         value        value for the bit field. This parameter is interpreted as an uint32_t type.
 198 \brief Mask and shift a bit field value for assigning the result to a peripheral register.
 199 \details
 200 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
 201 assigning to a register.
 202
 203 <b>Example:</b>
 204 \code
 205   SCB->CPUID = _VAL2FLD(SCB_CPUID_REVISION, 0x3) | _VAL2FLD(SCB_CPUID_VARIANT, 0x3);
 206 \endcode
 207
 208 */
 209 #define _VAL2FLD(field, value)
 210
 211 /**
 212
 213 \def _FLD2VAL(field, value)
 214 \param         field        name of bit field.
 215 \param         value        value of the register. This parameter is interpreted as an uint32_t type.
 216 \brief Extract from a peripheral register value the a bit field value.
 217 \details
 218 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.
 219
 220 <b>Example:</b>
 221 \code
 222   id = _FLD2VAL(SCB_CPUID_REVISION, SCB->CPUID);
 223 \endcode
 224
 225 */
 226 #define _FLD2VAL(field, value)
 227
 228 /**
 229 @}
 230
 231 */