Device Header File <device.h>

The Device Header File <device.h> contains the following sections that are device specific:
  • Interrupt Number Definition provides interrupt numbers (IRQn) for all exceptions and interrupts of the device.

  • Configuration of the Processor and Core Peripherals reflect the features of the device.

  • Device Peripheral Access Layer provides definitions for the Peripheral Access to all device peripherals. It contains all data structures and the address mapping for device-specific peripherals.

  • Access Functions for Peripherals (optional) provide additional helper functions for peripherals that are useful for programming of these peripherals. Access Functions may be provided as inline functions or can be extern references to a device-specific library provided by the silicon vendor.

NMSIS Core API describes the standard features and functions of the Device Header File <device.h> in detail.

Interrupt Number Definition

Device Header File <device.h> contains the enumeration IRQn_Type that defines all exceptions and interrupts of the device.
  • Negative IRQn values represent processor core exceptions (internal interrupts).

  • Positive IRQn values represent device-specific exceptions (external interrupts). The first device-specific interrupt has the IRQn value 0. The IRQn values needs extension to reflect the device-specific interrupt vector table in the Startup File startup_<device>.S.

The following example shows the extension of the interrupt vector table for the GD32VF103 device family.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
typedef enum IRQn {
    /******  N200 Processor Exceptions Numbers *********************************************/
    Reserved0_IRQn               =   0,     /*!<  Internal reserved                        */
    Reserved1_IRQn               =   1,     /*!<  Internal reserved                        */
    Reserved2_IRQn               =   2,     /*!<  Internal reserved                        */
    SysTimerSW_IRQn              =   3,     /*!<  System Timer SW interrupt                */
    Reserved3_IRQn               =   4,     /*!<  Internal reserved                        */
    Reserved4_IRQn               =   5,     /*!<  Internal reserved                        */
    Reserved5_IRQn               =   6,     /*!<  Internal reserved                        */
    SysTimer_IRQn                =   7,     /*!<  System Timer Interrupt                   */
    Reserved6_IRQn               =   8,     /*!<  Internal reserved                        */
    Reserved7_IRQn               =   9,     /*!<  Internal reserved                        */
    Reserved8_IRQn               =  10,     /*!<  Internal reserved                        */
    Reserved9_IRQn               =  11,     /*!<  Internal reserved                        */
    Reserved10_IRQn              =  12,     /*!<  Internal reserved                        */
    Reserved11_IRQn              =  13,     /*!<  Internal reserved                        */
    Reserved12_IRQn              =  14,     /*!<  Internal reserved                        */
    Reserved13_IRQn              =  15,     /*!<  Internal reserved                        */
    Reserved14_IRQn              =  16,     /*!<  Internal reserved                        */
    HardFault_IRQn               =  17,     /*!<  Hard Fault, storage access error         */
    Reserved15_IRQn              =  18,     /*!<  Internal reserved                        */

    /******  GD32VF103 Specific Interrupt Numbers ******************************************/
    WWDGT_IRQn                   =  19,     /*!< window watchDog timer interrupt           */
    LVD_IRQn                     =  20,     /*!< LVD through EXTI line detect interrupt    */
    TAMPER_IRQn                  =  21,     /*!< tamper through EXTI line detect           */
                 :       :
                 :       :
    CAN1_EWMC_IRQn               =  85,     /*!< CAN1 EWMC interrupt                       */
    USBFS_IRQn                   =  86,     /*!< USBFS global interrupt                    */
    SOC_INT_MAX,                            /*!< Number of total Interrupts                */
} IRQn_Type;

Configuration of the Processor and Core Peripherals

The Device Header File <device.h> configures the Nuclei N/NX Class Processors and the core peripherals with #define that are set prior to including the file nmsis_core.h.

The following tables list the #define along with the possible values for N200, N300, N600, NX600. If these #define are missing default values are used.

nmsis_core.h

Macros used in nmsis_core.h

#define

Value Range

Default

Description

__NUCLEI_N_REV OR
__NUCLEI_NX_REV
0x0100 |
0x0104

0x0100

  • For Nuclei N class device, define __NUCLEI_N_REV, for NX class device, define __NUCLEI_NX_REV.

  • Core revision number ([15:8] revision number, [7:0] patch number), 0x0100 -> 1.0, 0x0104 -> 1.4

__SYSTIMER_PRESENT

0 .. 1

1

Define whether Priviate System Timer is present or not. This SysTimer is a Memory Mapped Unit.

__SYSTIMER_BASEADDR

0x02000000

Base address of the System Timer Unit.

__ECLIC_PRESENT

0 .. 1

1

Define whether Enhanced Core Local Interrupt Controller (ECLIC) Unit is present or not

__ECLIC_BASEADDR

0x0C000000

Base address of the ECLIC unit.

__ECLIC_INTCTLBITS

1 .. 8

1

Define the number of hardware bits are actually implemented in the clicintctl registers.

__ECLIC_INTNUM

1 .. 1024

1

Define the total interrupt number(including the internal core interrupts) of ECLIC Unit

__PMP_PRESENT

0 .. 1

0

Define whether Physical Memory Protection (PMP) Unit is present or not.

__PMP_ENTRY_NUM

8 or 16

8

Define the numbers of PMP entries.

__FPU_PRESENT

0 .. 2

0

Define whether Floating Point Unit (FPU) is present or not.

  • 0: Not present

  • 1: Single precision FPU present

  • 2: Double precision FPU present

__DSP_PRESENT

0 .. 1

0

Define whether Digital Signal Processing Unit (DSP) is present or not.

__ICACHE_PRESENT

0 .. 1

0

Define whether I-Cache Unit is present or not.

__DCACHE_PRESENT

0 .. 1

0

Define whether D-Cache Unit is present or not.

__Vendor_SysTickConfig

0 .. 1

0

If __SYSTIMER_PRESENT is 1, then the __Vendor_SysTickConfig can be set to 0, otherwise it can only set to 1.

If this define is set to 1, then the default SysTick_Config and SysTick_Reload function is excluded.

In this case, the file Device.h must contain a vendor specific implementation of this function.

NMSIS Version and Processor Information

The following shows the defines in the nmsis_core.h file that may be used in the NMSIS-Core Device Templates to verify a minimum version or ensure that the right Nuclei N/NX class is used.

Device Peripheral Access Layer

The Device Header File <device.h> contains for each peripheral:
  • Register Layout Typedef

  • Base Address

  • Access Definitions

The section Peripheral Access shows examples for peripheral definitions.

Device.h Template File

Here we provided Device.h template file as below:

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
/*
 * Copyright (c) 2009-2019 Arm Limited. All rights reserved.
 * Copyright (c) 2019 Nuclei Limited. All rights reserved.
 *
 * SPDX-License-Identifier: Apache-2.0
 *
 * Licensed under the Apache License, Version 2.0 (the License); you may
 * not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an AS IS BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/******************************************************************************
 * @file     <Device>.h
 * @brief    NMSIS Nuclei N/NX Core Peripheral Access Layer Header File for
 *           Device <Device>
 * @version  V1.00
 * @date     17. Dec 2019
 ******************************************************************************/

#ifndef __<Device>_H__     /* TODO: replace '<Device>' with your device name */
#define __<Device>_H__

#ifdef __cplusplus
extern "C" {
#endif

/* TODO: replace '<Vendor>' with vendor name; add your doxygen comment   */
/** @addtogroup <Vendor>
  * @{
  */


/* TODO: replace '<Device>' with device name; add your doxygen comment   */
/** @addtogroup <Device>
  * @{
  */


/** @addtogroup Configuration_of_NMSIS
  * @{
  */



/* =========================================================================================================================== */
/* ================                                Interrupt Number Definition                                ================ */
/* =========================================================================================================================== */

typedef enum IRQn {
/* ========================================  Nuclei N/NX Specific Interrupt Numbers  ========================================= */

/* TODO: use this N/NX interrupt numbers if your device is a Nuclei N/NX device */
    Reserved0_IRQn            =   0,              /*!<  Internal reserved */
    Reserved1_IRQn            =   1,              /*!<  Internal reserved */
    Reserved2_IRQn            =   2,              /*!<  Internal reserved */
    SysTimerSW_IRQn           =   3,              /*!<  System Timer SW interrupt */
    Reserved3_IRQn            =   4,              /*!<  Internal reserved */
    Reserved4_IRQn            =   5,              /*!<  Internal reserved */
    Reserved5_IRQn            =   6,              /*!<  Internal reserved */
    SysTimer_IRQn             =   7,              /*!<  System Timer Interrupt */
    Reserved6_IRQn            =   8,              /*!<  Internal reserved */
    Reserved7_IRQn            =   9,              /*!<  Internal reserved */
    Reserved8_IRQn            =  10,              /*!<  Internal reserved */
    Reserved9_IRQn            =  11,              /*!<  Internal reserved */
    Reserved10_IRQn           =  12,              /*!<  Internal reserved */
    Reserved11_IRQn           =  13,              /*!<  Internal reserved */
    Reserved12_IRQn           =  14,              /*!<  Internal reserved */
    Reserved13_IRQn           =  15,              /*!<  Internal reserved */
    Reserved14_IRQn           =  16,              /*!<  Internal reserved */
    Reserved15_IRQn           =  17,              /*!<  Internal reserved */
    Reserved16_IRQn           =  18,              /*!<  Internal reserved */

/* ===========================================  <Device> Specific Interrupt Numbers  ========================================= */
/* TODO: add here your device specific external interrupt numbers. 19~1023 is reserved number for user. Maxmum interrupt supported
         could get from clicinfo.NUM_INTERRUPT. According the interrupt handlers defined in startup_Device.s
         eg.: Interrupt for Timer#1       eclic_tim0_handler   ->   TIM0_IRQn */
    <DeviceInterrupt>_IRQn    = 19,                /*!< Device Interrupt */

    SOC_INT_MAX,                                   /* Max SoC interrupt Number */
} IRQn_Type;

/* =========================================================================================================================== */
/* ================                                  Exception Code Definition                                ================ */
/* =========================================================================================================================== */

typedef enum EXCn {
/* =======================================  Nuclei N/NX Specific Exception Code  ======================================== */
    InsUnalign_EXCn          =   0,              /*!<  Instruction address misaligned */
    InsAccFault_EXCn         =   1,              /*!<  Instruction access fault */
    IlleIns_EXCn             =   2,              /*!<  Illegal instruction */
    Break_EXCn               =   3,              /*!<  Beakpoint */
    LdAddrUnalign_EXCn       =   4,              /*!<  Load address misaligned */
    LdFault_EXCn             =   5,              /*!<  Load access fault */
    StAddrUnalign_EXCn       =   6,              /*!<  Store or AMO address misaligned */
    StAccessFault_EXCn       =   7,              /*!<  Store or AMO access fault */
    UmodeEcall_EXCn          =   8,              /*!<  Environment call from User mode */
    MmodeEcall_EXCn          =  11,              /*!<  Environment call from Machine mode */
    NMI_EXCn                 = 0xfff,            /*!<  NMI interrupt*/
} EXCn_Type;

/* =========================================================================================================================== */
/* ================                           Processor and Core Peripheral Section                           ================ */
/* =========================================================================================================================== */

/* ===========================  Configuration of the Nuclei N/NX Processor and Core Peripherals  =========================== */
/* TODO: set the defines according your Device */
/* TODO: define the correct core revision
 *       __NUCLEI_N_REV if your device is a Nuclei-N Class device
 *       __NUCLEI_NX_REV if your device is a Nuclei-NX Class device
 */
#define __NUCLEI_N#_REV           0x0100                /*!< Core Revision rXpY, version X.Y, change N# to N for Nuclei N class cores, change N# to NX for Nuclei NX cores */
/* TODO: define the correct core features for the <Device> */
#define __ECLIC_PRESENT           1                     /*!< Set to 1 if ECLIC is present */
#define __ECLIC_BASEADDR          0x0C000000UL          /*!< Set to ECLIC baseaddr of your device */
#define __ECLIC_INTCTLBITS        8                     /*!< Set to 1 - 8, the number of hardware bits are actually implemented in the clicintctl registers. */
#define __ECLIC_INTNUM            51                    /*!< Set to 1 - 1024, total interrupt number of ECLIC Unit */
#define __SYSTIMER_PRESENT        1                     /*!< Set to 1 if System Timer is present */
#define __SYSTIMER_BASEADDR       0x02000000UL          /*!< Set to SysTimer baseaddr of your device */
#define __FPU_PRESENT             1                     /*!< Set to 0, 1, or 2, 0 not present, 1 single floating point unit present, 2 double floating point unit present */
#define __DSP_PRESENT             1                     /*!< Set to 1 if DSP is present */
#define __PMP_PRESENT             1                     /*!< Set to 1 if PMP is present */
#define __PMP_ENTRY_NUM           16                    /*!< Set to 8 or 16, the number of PMP entries */
#define __ICACHE_PRESENT          0                     /*!< Set to 1 if I-Cache is present */
#define __DCACHE_PRESENT          0                     /*!< Set to 1 if D-Cache is present */
#define __Vendor_SysTickConfig    0                     /*!< Set to 1 if different SysTick Config is used */

/** @} */ /* End of group Configuration_of_NMSIS */


#include <nmsis_core.h>
/* TODO: include your system_<Device>.h file
         replace '<Device>' with your device name */
#include "system_<Device>.h"                    /*!< <Device> System */


/* ========================================  Start of section using anonymous unions  ======================================== */
#if   defined (__GNUC__)
  /* anonymous unions are enabled by default */
#else
  #warning Not supported compiler type
#endif


/* =========================================================================================================================== */
/* ================                            Device Specific Peripheral Section                             ================ */
/* =========================================================================================================================== */


/** @addtogroup Device_Peripheral_peripherals
  * @{
  */

/* TODO: add here your device specific peripheral access structure typedefs
         following is an example for UART */

/* =========================================================================================================================== */
/* ================                                  UART                                                     ================ */
/* =========================================================================================================================== */

/**
  * @brief UART (UART)
  */
typedef struct {                            /*!< (@ 0x40000000) UART Structure                  */
  __IOM uint32_t   TXFIFO;                  /*!< (@ 0x00000000) UART TX FIFO                    */
  __IM  uint32_t   RXFIFO;                  /*!< (@ 0x00000004) UART RX FIFO                    */
  __IOM uint32_t   TXCTRL;                  /*!< (@ 0x00000008) UART TX FIFO control            */
  __OM  uint32_t   RXCTRL;                  /*!< (@ 0x0000000C) UART RX FIFO control            */
  __IM  uint32_t   IE;                      /*!< (@ 0x00000010) UART Interrupt Enable flag      */
  __IM  uint32_t   IP;                      /*!< (@ 0x00000018) TART Interrupt Pending flag     */
  __IM  uint32_t   DIV;                     /*!< (@ 0x00000018) UART Baudrate Divider           */
} <DeviceAbbreviation>_UART_TypeDef;

/*@}*/ /* end of group <Device>_Peripherals */


/* =========================================  End of section using anonymous unions  ========================================= */
#if defined (__GNUC__)
  /* anonymous unions are enabled by default */
#else
  #warning Not supported compiler type
#endif


/* =========================================================================================================================== */
/* ================                          Device Specific Peripheral Address Map                           ================ */
/* =========================================================================================================================== */


/* TODO: add here your device peripherals base addresses
         following is an example for timer */
/** @addtogroup Device_Peripheral_peripheralAddr
  * @{
  */

/* Peripheral and SRAM base address */
#define <DeviceAbbreviation>_FLASH_BASE         (0x00000000UL)                              /*!< (FLASH     ) Base Address */
#define <DeviceAbbreviation>_SRAM_BASE          (0x20000000UL)                              /*!< (SRAM      ) Base Address */
#define <DeviceAbbreviation>_PERIPH_BASE        (0x40000000UL)                              /*!< (Peripheral) Base Address */

/* Peripheral memory map */
#define <DeviceAbbreviation>UART0_BASE          (<DeviceAbbreviation>_PERIPH_BASE)          /*!< (UART 0  ) Base Address */
#define <DeviceAbbreviation>I2C_BASE            (<DeviceAbbreviation>_PERIPH_BASE + 0x0800) /*!< (I2C    ) Base Address */
#define <DeviceAbbreviation>GPIO_BASE           (<DeviceAbbreviation>_PERIPH_BASE + 0x1000) /*!< (GPIO    ) Base Address */

/** @} */ /* End of group Device_Peripheral_peripheralAddr */


/* =========================================================================================================================== */
/* ================                                  Peripheral declaration                                   ================ */
/* =========================================================================================================================== */


/* TODO: add here your device peripherals pointer definitions
         following is an example for uart0 */
/** @addtogroup Device_Peripheral_declaration
  * @{
  */
#define <DeviceAbbreviation>_UART0              ((<DeviceAbbreviation>_TMR_TypeDef *) <DeviceAbbreviation>UART0_BASE)


/** @} */ /* End of group <Device> */

/** @} */ /* End of group <Vendor> */

#ifdef __cplusplus
}
#endif

#endif  /* __<Device>_H__ */