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

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