STM32F10x 常用术语与规则

STM32F10x Standard Peripherals Library: Coding rules and conventions Copyright 2010 STMicroelectronics The STM32F10x Standard Peripherals Library uses rules and conventions described in the sections below. Acronyms (缩略词)The Table below describes the acronyms used in the firmware library. Acronym Peripheral/unit(外设或单元) ADC Analog/digital converter BKP(备份寄存器) Backup registers CAN Controller area network CEC Consumer Electronics Control CRC CRC calculation unit DAC Digital to analog converter DBGMCU Debug MCU DMA（高速数据通道，可以绕过cpu，加快数据搬运的速度，同时减少cpu的负载） DMA controller EXTI External interrupt/event controller FSMC Flexible static memory controller FLASH Flash memory GPIO General purpose I/O I2C Inter-integrated circuit I2S Inter-integrated sound IWDG Independent watchdog NVIC Nested vectored interrupt controller PWR Power controller RCC Reset and clock controller RTC Reset and clock controller SDIO SDIO interface SPI Serial peripheral interface SysTick System tick timer TIM Advanced-control, general-purpose or basic timer USART Universal synchronous asynchronous receiver transmitter WWDG Window watchdog Naming conventions （命名规则） The STM32F10x Standard Peripherals Library uses the following naming conventions: PPP refers to any peripheral acronym, for example ADC.（PPP指所有的外设）System and source/header file names are preceded by the prefix ‘stm32f10x_’. （系统的源代码或头文件命名时以stm32f10x_ 为前缀，这里的系统就是指st的stm32f10x这个库） Constants used in one file are defined within this file. A constant used in more than one file is defined in a header file. All constants are written in upper case. （常量都大写，多出使用的常量放在一个头文件中） Registers are considered as constants. Their names are in upper case. In most cases, the same acronyms as in the STM32F10x reference manual document are used. （寄存器当作常量的使用） Names of peripheral’s functions are preceded by the corresponding peripheral acronym in upper case followed by an underscore. The first letter in each word is in upper case, for example USART_SendData. Only one underscore is allowed in a function name to separate the peripheral acronym from the rest of the function name. （外设的接口函数定义时，此外设简写的大写加下划线_，再加剩下的字符，命名中的每个单词的受字母必须大写，且只能有一个下划线） Functions used to initialize the PPP peripheral according to parameters specified inPPP_InitTypeDef are named PPP_Init, for example TIM_Init. （外设初始化用的函数就是硬件接口简写_Init） Functions used to reset the PPP peripheral registers to their default values are namedPPP_DeInit, for example TIM_DeInit. (外设复位函数就是外设简写_DeInit) Functions used to fill the PPP_InitTypeDef structure with the reset values of each member are named PPP_StructInit, for example USART_StructInit. （外设的重置函数） Functions used to enable or disable the specified PPP peripheral are named PPP_Cmd, for exampleUSART_Cmd. （特殊外设的使能函数） Functions used to enable or disable an interrupt source of the specified PPP peripheral are named PPP_ITConfig, for example RCC_ITConfig. （外设作为中断源时的使能函数） Functions used to enable or disable the DMA interface of the specified PPP peripheral are namedPPP_DMAConfig, for example TIM_DMAConfig. （DMA的使能函数） Functions used to configure a peripheral function always end with the string ‘Config’, for example GPIO_PinRemapConfig. （配置外设的函数后面带有Config） Functions used to check whether the specified PPP flag is set or reset are namedPPP_GetFlagStatus, for example I2C_GetFlagStatus. （检测外设标记状态的函数） Functions used to clear a PPP flag are named PPP_ClearFlag, for example I2C_ClearFlag. （清除外设标记的函数） Functions used to check whether the specified PPP interrupt has occurred or not are named PPP_GetITStatus, for exampleI2C_GetITStatus. （检测外设中断是否发生的函数） Functions used to clear a PPP interrupt pending（悬而未决） bit are named PPP_ClearITPendingBit, for example I2C_ClearITPendingBit. （清除） Coding rules This section describes the coding rules used in the Standard Peripherals library. Variable types Specific variable types are already defined with a fixed type and size. These types are defined in the filestm32f10x.h  （特殊的变量类型在stm3210x.h中已经定义了固定的大小和类型） typedef enum {   FALSE = 0,   TRUE = !FALSE } bool; typedef enum {   RESET = 0,   SET = !RESET } FlagStatus, ITStatus, BitStatus; typedef enum {   DISABLE = 0,   ENABLE = !DISABLE } FunctionalState; typedef enum {   ERROR = 0,   SUCCESS = !ERROR } ErrorStatus; Peripheral’s registers Peripheral’s registers are accessed through a pointer of structure. Each peripheral has its own structure and pointer. All the structures and declarations are defined in the stm32f10x.h file. （外设寄存器的操作是通过指针来操作的，而寄存器全在stm32f10x.h中定义） Registers structure The example below illustrates the Serial Peripheral Interface (SPI)  registers structure declaration: typedef struct {   __IO uint16_t CR1;   uint16_t  RESERVED0;   __IO uint16_t CR2;   uint16_t  RESERVED1;   __IO uint16_t SR;   uint16_t  RESERVED2;   __IO uint16_t DR;   uint16_t  RESERVED3;   __IO uint16_t CRCPR;   uint16_t  RESERVED4;   __IO uint16_t RXCRCR;   uint16_t  RESERVED5;   __IO uint16_t TXCRCR;   uint16_t  RESERVED6;   __IO uint16_t I2SCFGR;   uint16_t  RESERVED7;   __IO uint16_t I2SPR;   uint16_t  RESERVED8;  } SPI_TypeDef; Register names are the register acronyms written in upper case for each peripheral. RESERVED indicates a reserved field (i being an integer that indexes the reserved field). Peripheral declaration The following example shows the declaration of the SPI peripheral: #define PERIPH_BASE ((u32)0x40000000) #define APB1PERIPH_BASE PERIPH_BASE #define APB2PERIPH_BASE (PERIPH_BASE + 0x10000) ... #define SPI2_BASE (APB1PERIPH_BASE + 0x3800) The peripheral registers are accessed as follows: SPI1->CR1 = 0x0001; Each peripheral has several dedicated registers which contain different flags. Registers are defined within a dedicated structure for each peripheral. Flags are defined as acronyms written in upper case and preceded by ‘PPP_FLAG_’. Flag definition is adapted to each peripheral case and defined in stm32f10x_ppp.h file. Registers bits （寄存器控制位） All the peripheral registers bits are defined as constants in the stm32f10x.h file. They are defined as acronyms written in upper-case into the form: PPP_<register_name>_<bit_name> Example: #define SPI_CR2_RXDMAEN                     ((uint8_t)0x01)  #define SPI_CR2_TXDMAEN                     ((uint8_t)0x02)  #define SPI_CR2_SSOE                        ((uint8_t)0x04)  #define SPI_CR2_ERRIE                       ((uint8_t)0x20)  #define SPI_CR2_RXNEIE                     ((uint8_t)0x40)  #define SPI_CR2_TXEIE                       ((uint8_t)0x80)  Bit-Banding （位绑定） The Cortex-M3 memory map includes two bit-band memory regions. These regions map each word in an alias region of memory to a bit in a bit-band region of memory. Writing to a word in the alias region has the same effect as a read-modify-write operation on the targeted bit in the bit-band region. All the STM32F10x peripheral registers are mapped in a bit-band region. This feature is consequently intensively used in functions which perform single bit set/reset in order to reduce and optimize code size. Mapping formula （映射准则） The mapping formula shows how to link each word in the alias region to a corresponding target bit in the bit-band region. The mapping formula is given below: bit_word_offset = (byte_offset x 32) + (bit_number + 4) bit_word_addr = bit_band_base + bit_word_offse t where: bit_word_offset is the position of the target bit in the bit-band memory region bit_word_addr is the address of the word in the alias memory region that maps to the targeted bit. bit_band_base is the starting address of the alias region byte_offset is the number of the byte in the bit-band region that contains the targeted bit bit_number is the bit position (0-7) of the targeted bit. Example of implementation The following example shows how to map the PLLON[24] bit of RCC_CR register in the alias region: #define PERIPH_BASE ((u32)0x40000000) #define PERIPH_BB_BASE ((u32)0x42000000) #define RCC_OFFSET (RCC_BASE - PERIPH_BASE) #define CR_OFFSET (RCC_OFFSET + 0x00) #define PLLON_BitNumber 0x18 #define CR_PLLON_BB (PERIPH_BB_BASE + (CR_OFFSET * 32 (PLLON_BitNumber * 4)) To code a function which enables/disables the PLL, the usual method is the following: ... #define CR_PLLON_Set ((u32)0x01000000) #define CR_PLLON_Reset ((u32)0xFEFFFFFF) ... void RCC_PLLCmd(FunctionalState NewState) { if (NewState != DISABLE) { RCC->CR |= CR_PLLON_Set; } else { RCC->CR &= CR_PLLON_Reset; } } Using bit-band access this function will be coded as follows: void RCC_PLLCmd(FunctionalState NewState) { *(vu32 *) CR_PLLON_BB = (u32)NewState; } Run-time checking The firmware library implements run-time failure detection by checking the input values of all library functions. The run-time checking is achieved by using an assert_param macro（维护参数宏定义）. This macro is used in all library functions which have at least an input parameter. It allows the user to check that the input value lies within the defined parameter values. EXTI_Init function example stm32f10x_exti.c void EXTI_Init(EXTI_InitTypeDef* EXTI_InitStruct) {     assert_param(IS_EXTI_MODE(EXTI_InitStruct->EXTI_Mode));   assert_param(IS_EXTI_TRIGGER(EXTI_InitStruct->EXTI_Trigger));   assert_param(IS_EXTI_LINE(EXTI_InitStruct->EXTI_Line));    assert_param(IS_FUNCTIONAL_STATE(EXTI_InitStruct->EXTI_LineCmd)); ... } stm32f10x_exti.h #define IS_EXTI_MODE(MODE) (((MODE) == EXTI_Mode_Interrupt) || ((MODE) == EXTI_Mode_Event)) #define IS_EXTI_TRIGGER(TRIGGER) (((TRIGGER) == EXTI_Trigger_Rising) || \                                   ((TRIGGER) == EXTI_Trigger_Falling) || \                                   ((TRIGGER) == EXTI_Trigger_Rising_Falling)) #define IS_EXTI_LINE(LINE) ((((LINE) & (uint32_t)0xFFF00000) == 0x00) && ((LINE) != (uint16_t)0x00)) If the expression passed to the assert_param macro is false, the assert_failed function is called, otherwise nothing happens. Two implementation of assert_failed function are provided, depending on USE_FULL_ASSERT define (declared in stm32f10x_conf.h file). "#define USE_FULL_ASSERT   1 " line is uncommented, if the expression passed to the assert_param macro is false, the assert_failed function  will have as input  the name of the source file and the source line number of the call that failed. "#define FULL_ASSERT   1" line is commented, if the expression passed to theassert_param macro is true, the assert_failed function will have takes no does not returns the name of the source file and the source line number of the call that failed. The assert_param macro is implemented in stm32f10x_conf.h as follows: #ifdef  USE_FULL_ASSERT   #define assert_param(expr) ((expr) ? (void)0 : assert_failed((uint8_t *)__FILE__, __LINE__))    void assert_failed(uint8_t* file, uint32_t line); #else    #define assert_param(expr) ((void)0) #endif The assert_failed function is implemented in the main.c file or in any other user C files and can be modified by the user in order to take action when an error occurs. #ifdef  USE_FULL_ASSERT void assert_failed(uint8_t* file, uint32_t line) {       while (1)   {   }