1/**
2\defgroup   peripheral_gr    Peripheral Access
3@{
4\brief      Naming conventions and optional features for accessing peripherals.
5\details
6
7The section below describes the naming conventions, requirements, and optional features for accessing device specific peripherals.
8Most of the rules also apply to the core peripherals.  The \ref device_h_pg contains typically these definition and also includes
9the core specific header files.
10
11\ifnot FuSaRTS
12The definitions for \ref peripheral_gr can be generated using the <a href="https://open-cmsis-pack.github.io/svd-spec/latest/index.html"><b>CMSIS-SVD</b></a> System View Description for Peripherals.
13Refer to <a href="https://open-cmsis-pack.github.io/svd-spec/latest/svd_SVDConv_pg.html"><b>SVDConv.exe</b></a> for more information.
14\endif
15
16Each 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
21Examples:
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
25The 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
40The 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
43typedef 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
76To access the registers of the UART defined above, pointers to this register structure are defined.
77If more instances of a peripheral exist, the variables have a postfix (digit or letter) that identifies the peripheral.
78
79\b Example:
80In 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
90The 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
107typedef 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
135These definitions allow accessing peripheral registers with simple assignments.
136
137- <b>Example:</b>
138  \n
139\code
140SysTick->CTRL = 0;
141\endcode
142
143<hr>
144
145\section core_cmsis_pal_opts Optional Features
146\details
147Optionally, 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
164For Core Register, macros define the position and the mask value for a bit field. It is recommended to create such definitions also
165for other peripheral registers.
166
167<b>Example:</b>
168
169Bit 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
190The 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
200The 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
201assigning 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
218The 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/** @} end of peripheral_gr */
232*/