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 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.
  12 Refer to <a href="../../SVD/html/svd_SVDConv_pg.html"><b>SVDConv.exe</b></a> for more information.
  13
  14 Each peripheral provides a data type definition with a name that is composed of:
  15   - an optional prefix <b>&lt;<i>device abbreviation&gt;</i>_</b>
  16   - <b>&lt;<i>peripheral name</i>&gt;</b>
  17   - postfix \b _Type or \b _TypeDef to identify a type definition.
  18
  19 Examples:
  20   - \b UART_TypeDef for the peripheral \b UART.
  21   - \b LPC_UART_TypeDef for the device family \b LPC and the peripheral \b UART.
  22
  23 The data type definition uses standard C data types defined by the ANSI C header file <stdint.h>.
  24
  25  - IO Type Qualifiers are used to specify the access to peripheral variables.
  26    IO Type Qualifier  | Type            | Description
  27    :------------------|:----------------|:------------
  28    \b __IM            | Struct member   | Defines 'read only' permissions
  29    \b __OM            | Struct member   | Defines 'write only' permissions
  30    \b __IOM           | Struct member   | Defines 'read / write' permissions
  31    \b __I             | Scalar variable | Defines 'read only' permissions
  32    \b __O             | Scalar variable | Defines 'write only' permissions
  33    \b __IO            | Scalar variable | Defines 'read / write' permissions
  34
  35 \note
  36 \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.
  37
  38 The typedef <b>\<<i>device abbreviation</i>\>_UART_TypeDef</b> shown below defines the generic register layout for all UART channels in a device.
  39
  40 \code
  41 typedef struct
  42 {
  43   union {
  44   __IM  uint8_t  RBR;                 /* Offset: 0x000 (R/ )  Receiver Buffer Register            */
  45   __OM  uint8_t  THR;                 /* Offset: 0x000 ( /W)  Transmit Holding Register           */
  46   __IOM uint8_t  DLL;                 /* Offset: 0x000 (R/W)  Divisor Latch LSB                   */
  47         uint32_t RESERVED0;
  48   };
  49   union {
  50   __IOM uint8_t  DLM;                 /* Offset: 0x004 (R/W)  Divisor Latch MSB                   */
  51   __IOM uint32_t IER;                 /* Offset: 0x004 (R/W)  Interrupt Enable Register           */
  52   };
  53   union {
  54   __IM  uint32_t IIR;                 /* Offset: 0x008 (R/ )  Interrupt ID Register               */
  55   __OM  uint8_t  FCR;                 /* Offset: 0x008 ( /W)  FIFO Control Register               */
  56   };
  57   __IOM uint8_t  LCR;                 /* Offset: 0x00C (R/W)  Line Control Register               */
  58         uint8_t  RESERVED1[7];
  59   __IM  uint8_t  LSR;                 /* Offset: 0x014 (R/ )  Line Status Register                */
  60         uint8_t  RESERVED2[7];
  61   __IOM uint8_t  SCR;                 /* Offset: 0x01C (R/W)  Scratch Pad Register                */
  62         uint8_t  RESERVED3[3];
  63   __IOM uint32_t ACR;                 /* Offset: 0x020 (R/W)  Autobaud Control Register           */
  64   __IOM uint8_t  ICR;                 /* Offset: 0x024 (R/W)  IrDA Control Register               */
  65         uint8_t  RESERVED4[3];
  66   __IOM uint8_t  FDR;                 /* Offset: 0x028 (R/W)  Fractional Divider Register         */
  67         uint8_t  RESERVED5[7];
  68   __IOM uint8_t  TER;                 /* Offset: 0x030 (R/W)  Transmit Enable Register            */
  69         uint8_t  RESERVED6[39];
  70   __IM  uint8_t  FIFOLVL;             /* Offset: 0x058 (R/ )  FIFO Level Register                 */
  71 } LPC_UART_TypeDef;
  72 \endcode
  73
  74 To access the registers of the UART defined above, pointers to this register structure are defined.
  75 If more instances of a peripheral exist, the variables have a postfix (digit or letter) that identifies the peripheral.
  76
  77 \b Example:
  78 In this example \b LPC_UART2 and \b LPC_UART3 are two pointers to UARTs defined with above register structure.
  79 \n
  80 \code
  81 #define LPC_UART2             ((LPC_UART_TypeDef      *) LPC_UART2_BASE    )
  82 #define LPC_UART3             ((LPC_UART_TypeDef      *) LPC_UART3_BASE    )
  83 \endcode
  84
  85 \note
  86  - The prefix <b>LPC</b> is optional.
  87
  88 The registers in the various UARTs can now be referred in the user code as shown below:\n
  89 \code
  90  val = LPC_UART2->DR   // is the data register of UART1.
  91 \endcode
  92
  93 <hr>
  94
  95 \section core_cmsis_pal_min_reqs Minimal Requirements
  96 \details
  97  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:
  98 \n\n
  99 - The <b>Register Layout Typedef</b> for each peripheral that defines all register names.
 100   RESERVED is used to introduce space into the structure for adjusting the addresses of
 101   the peripheral registers.
 102 \n\n
 103 <b>Example:</b>
 104 \code
 105 typedef struct
 106 {
 107   __IOM uint32_t CTRL;                /* Offset: 0x000 (R/W)  SysTick Control and Status Register */
 108   __IOM uint32_t LOAD;                /* Offset: 0x004 (R/W)  SysTick Reload Value Register       */
 109   __IOM uint32_t VAL;                 /* Offset: 0x008 (R/W)  SysTick Current Value Register      */
 110   __IM  uint32_t CALIB;               /* Offset: 0x00C (R/ )  SysTick Calibration Register        */
 111 } SysTick_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 SysTick_BASE (SCS_BASE + 0x0010)            /* SysTick 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 typdef</b>, multiple access definitions exist (LPC_UART0, LPC_UART2).
 126     \n\n
 127 <b>Example:</b>
 128 \code
 129 #define SysTick ((SysTick_Type *) Systick_BASE)    /* SysTick 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 SysTick->CTRL = 0;
 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. It is recommended to create such definitions also
 163 for other peripheral registers.
 164
 165 <b>Example:</b>
 166
 167 Bit field definitions for register CPUID in SCB (System Control Block).
 168
 169
 170 \code
 171 /* SCB CPUID Register Definitions */
 172 #define SCB_CPUID_IMPLEMENTER_Pos      24U                                       /*!< SCB CPUID: IMPLEMENTER Position */
 173 #define SCB_CPUID_IMPLEMENTER_Msk      (0xFFUL << SCB_CPUID_IMPLEMENTER_Pos)     /*!< SCB CPUID: IMPLEMENTER Mask */
 174
 175 #define SCB_CPUID_VARIANT_Pos          20U                                       /*!< SCB CPUID: VARIANT Position */
 176 #define SCB_CPUID_VARIANT_Msk          (0xFUL << SCB_CPUID_VARIANT_Pos)          /*!< SCB CPUID: VARIANT Mask */
 177
 178 #define SCB_CPUID_ARCHITECTURE_Pos     16U                                       /*!< SCB CPUID: ARCHITECTURE Position */
 179 #define SCB_CPUID_ARCHITECTURE_Msk     (0xFUL << SCB_CPUID_ARCHITECTURE_Pos)     /*!< SCB CPUID: ARCHITECTURE Mask */
 180
 181 #define SCB_CPUID_PARTNO_Pos            4U                                       /*!< SCB CPUID: PARTNO Position */
 182 #define SCB_CPUID_PARTNO_Msk           (0xFFFUL << SCB_CPUID_PARTNO_Pos)         /*!< SCB CPUID: PARTNO Mask */
 183
 184 #define SCB_CPUID_REVISION_Pos          0U                                       /*!< SCB CPUID: REVISION Position */
 185 #define SCB_CPUID_REVISION_Msk         (0xFUL /*<< SCB_CPUID_REVISION_Pos*/)     /*!< SCB CPUID: REVISION Mask */
 186 \endcode
 187
 188 The macros <b>_VAL2FLD(field, value)</b> and <b>_FLD2VAL(field, value)</b> enable access to bit fields.
 189 @{
 190 */
 191
 192 /**
 193 \def _VAL2FLD(field, value)
 194 \param         field        name of bit field.
 195 \param         value        value for the bit field. This parameter is interpreted as an uint32_t type.
 196 \brief Mask and shift a bit field value for assigning the result to a peripheral register.
 197 \details
 198 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
 199 assigning to a register.
 200
 201 <b>Example:</b>
 202 \code
 203   SCB->CPUID = _VAL2FLD(SCB_CPUID_REVISION, 0x3) | _VAL2FLD(SCB_CPUID_VARIANT, 0x3);
 204 \endcode
 205
 206 */
 207 #define _VAL2FLD(field, value)
 208
 209 /**
 210
 211 \def _FLD2VAL(field, value)
 212 \param         field        name of bit field.
 213 \param         value        value of the register. This parameter is interpreted as an uint32_t type.
 214 \brief Extract from a peripheral register value the a bit field value.
 215 \details
 216 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.
 217
 218 <b>Example:</b>
 219 \code
 220   id = _FLD2VAL(SCB_CPUID_REVISION, SCB->CPUID);
 221 \endcode
 222
 223 */
 224 #define _FLD2VAL(field, value)
 225
 226 /**
 227 @}
 228
 229 */