FreeRTOS学习——接口宏portmacro.h，仅用于记录自己阅读与学习源码

FreeRTOS Kernel V10.5.1

portmacro版本：GCC/ARM_CM7

portmacro.h是什么

portmacro.h头文件，用于定义与特定硬件平台相关的数据类型和常量。

在移植过程中，portmacro.h文件是必须修改的文件之一。它主要负责为内核提供平台相关的定义，以确保在不同的硬件平台上正确运行FreeRTOS。

在portmacro.h中，会定义几个重要的类型。这些定义对于编写能够正确调度和管理任务的代码至关重要。此外，该文件还会包含关于中断处理的配置，以确保任务可以在中断触发时正确运行和切换。

移植FreeRTOS时，如果C编译器允许在C代码中插入汇编，并且支持用C语言编写的中断处理函数，那么port.asm文件的内容可以合并到port.c文件中，这样可以减少文件数量，简化项目结构

参考文章：
FreeRTOS 移植要点(1)

portmacro.h内容

我移植的是
GCC
ARM_CM7内核的接口

Type definitions

/* Type definitions. */#define portCHAR          char#define portFLOAT         float#define portDOUBLE        double#define portLONG          long#define portSHORT         short#define portSTACK_TYPE    uint32_t#define portBASE_TYPE     longtypedef portSTACK_TYPE   StackType_t;typedef long             BaseType_t;typedef unsigned long    UBaseType_t;#if ( configUSE_16_BIT_TICKS == 1 )typedef uint16_t     TickType_t;#define portMAX_DELAY              ( TickType_t ) 0xffff#elsetypedef uint32_t     TickType_t;#define portMAX_DELAY              ( TickType_t ) 0xffffffffUL/* 32位架构上的32-bit tick type* 所以读取它不需要临界区进行保护. */#define portTICK_TYPE_IS_ATOMIC    1#endif

当configUSE_16_BIT_TICKS为1时（在FreeRTOSConfig.h中配置）,TickType_t就是uint32_t否则TickType_t为uint16_t。

portTICK_TYPE_IS_ATOMIC

默认configUSE_16_BIT_TICKS为0，也就是使用32位的。这时会配置另一个宏portTICK_TYPE_IS_ATOMIC为1。翻译一下就是TICK_TYPE是原子性的，此宏用于标识时间片（tick）类型是否为原子类型的宏定义

首先什么是原子操作？
原子操作的定义：原子操作是指在多线程或多任务环境中，**一个操作要么完全执行成功，要么完全不执行，不会在中间被挂起或打断。**对于时间片操作，若标识为原子，在此期间所有对时间片的修改和读取都是一个不可分割的动作。

当portTICK_TYPE_IS_ATOMIC为1时，就是32位架构上的32-bit tick type，所以读取它不需要临界区进行保护

当宏定义为原子时，它可以保证当前的时间片计数在操作期间不会被修改，避免了由于并发访问导致的错误。

如果没有原子性保证，在进行时间片相关的操作（如增加或减少时间片计数）时可能会有其他任务进行切换或者中断服务例程被激活。这种情况下会对时间片的值产生竞争条件，导致数据不一致或错误的调度结果。

通过确保时间片相关的操作是原子的，可以提高系统的稳定性和可靠性，确保调度行为按照预期进行，避免由于任务切换产生的不可预测行为。

我们来看看如果portTICK_TYPE_IS_ATOMIC为0，会有如下定义，即增加了TICK_TYPE临界区宏，对时间片操作时，要进行保护

#if ( portTICK_TYPE_IS_ATOMIC == 0 )/* tick type非原子读取* portTICK_TYPE_IS_ATOMIC == 0.* 当tick count返回时映射临界区代码到标准临界区宏*/#define portTICK_TYPE_ENTER_CRITICAL()                      portENTER_CRITICAL()#define portTICK_TYPE_EXIT_CRITICAL()                       portEXIT_CRITICAL()#define portTICK_TYPE_SET_INTERRUPT_MASK_FROM_ISR()         portSET_INTERRUPT_MASK_FROM_ISR()#define portTICK_TYPE_CLEAR_INTERRUPT_MASK_FROM_ISR( x )    portCLEAR_INTERRUPT_MASK_FROM_ISR( ( x ) )
#else

Architecture specifics

/* Architecture specifics. */#define portSTACK_GROWTH      ( -1 )#define portTICK_PERIOD_MS    ( ( TickType_t ) 1000 / configTICK_RATE_HZ )#define portBYTE_ALIGNMENT    8#define portDONT_DISCARD      __attribute__( ( used ) )

portSTACK_GROWTH
portSTACK_GROWTH为 -1 ，这个定义表示堆栈是向下增长的，即从高地址向低地址增长。

portTICK_PERIOD_MS
其中configTICK_RATE_HZ 在FreeRTOSConfig.h中配置，默认为1000Hz，所以TICK周期也就是1ms。

portBYTE_ALIGNMENT
在 FreeRTOS 中使用 portBYTE_ALIGNMENT 进行内存对齐，可以确保任务栈、队列和其他数据结构的正确对齐。这通常与内存分配器的实现配合使用。例如，在使用动态内存分配时，如 pvPortMalloc，内存对齐可以保证分配到的内存块是按照指定的对齐方式返回。

如果 portBYTE_ALIGNMENT 被定义为 8，那么所有与 FreeRTOS 相关的数据结构和任务栈都会在内存中位于 8 字节的边界上。

portDONT_DISCARD
#define portDONT_DISCARD attribute((used)) 是一个用于防止编译器丢弃某些未使用变量或函数的宏定义。

在编译过程中，编译器会进行一些优化，包括去除那些被认为没有使用的代码（如未调用的函数或未使用的变量）。使用 attribute((used)) 可以告诉编译器，即使该变量或函数在代码中未被直接引用，也要保留它。

Scheduler utilities

/* Scheduler utilities. */#define portYIELD()                                 \{                                                   \/* 挂起 PendSV来请求上下文切换. */ \portNVIC_INT_CTRL_REG = portNVIC_PENDSVSET_BIT; \\/* Barriers are normally not required but do ensure the code is completely \* within the specified behaviour for the architecture. */ \__asm volatile ( "dsb" ::: "memory" );                     \__asm volatile ( "isb" );                                  \}#define portNVIC_INT_CTRL_REG     ( *( ( volatile uint32_t * ) 0xe000ed04 ) )#define portNVIC_PENDSVSET_BIT    ( 1UL << 28UL )#define portEND_SWITCHING_ISR( xSwitchRequired )    do { if( xSwitchRequired != pdFALSE ) portYIELD(); } while( 0 )#define portYIELD_FROM_ISR( x )                     portEND_SWITCHING_ISR( x )

taskYIELD就是portYIELD用来发起调度，切换任务

portYIELD做的就是挂起 PendSV来请求上下文切换

__asm volatile ( “dsb” ::: “memory” ); 和 __asm volatile ( “isb” );
这是使用内嵌汇编实现的一些特定指令，通常在嵌入式系统或对实时性能有严格要求的程序中使用。__asm volatile ( “dsb” ::: “memory” ); 和 __asm volatile ( “isb” ); 是 ARM 体系结构中用于内存屏障操作的指令。它们的作用如下：

dsb（Data Synchronization Barrier）：是一个数据同步屏障指令。
它的作用是确保在它之前的所有内存访问（读取或写入）在执行后续的指令之前完成。
通常用于确保数据的一致性，尤其是在多处理器系统中，确保一个处理器对内存的写入在另一个处理器读取之前完成。

isb（Instruction Synchronization Barrier）：是一个指令同步屏障指令。
它的作用是使得所有之前的指令都必须完成执行，之后再执行后续的指令。
一般用于整个流水线刷新，以确保新加载的指令在它之前的指令已经完成之后才能执行。

volatile 关键字
使用 volatile 关键字表明这些汇编语句是“易变”的，这意味着编译器不会对它们进行优化，即编译器每次运行时都会实际执行这些汇编代码，而不是在某些情况下跳过它。

::: “memory” 语法
这个语法中的 ::: “memory” 表示告诉编译器在执行这些指令时，内存的状态可能会发生变化。这提示编译器在这段代码之前和之后都不要做一些可能依赖于内存状态的优化。

portNVIC_INT_CTRL_REG
关于portNVIC_INT_CTRL_REG，首先找到cortex m7内核手册。内容如下：

将1写入此位是将PendSV异常挂起的唯一方法

Critical section management

/* Critical section management. */extern void vPortEnterCritical( void );extern void vPortExitCritical( void );#define portSET_INTERRUPT_MASK_FROM_ISR()         ulPortRaiseBASEPRI()#define portCLEAR_INTERRUPT_MASK_FROM_ISR( x )    vPortSetBASEPRI( x )#define portDISABLE_INTERRUPTS()                  vPortRaiseBASEPRI()#define portENABLE_INTERRUPTS()                   vPortSetBASEPRI( 0 )#define portENTER_CRITICAL()                      vPortEnterCritical()#define portEXIT_CRITICAL()                       vPortExitCritical()

Task function macros

/* Task function macros as described on the FreeRTOS.org WEB site.  These are* not necessary for to use this port.  They are defined so the common demo files* (which build with all the ports) will build. */#define portTASK_FUNCTION_PROTO( vFunction, pvParameters )    void vFunction( void * pvParameters )#define portTASK_FUNCTION( vFunction, pvParameters )          void vFunction( void * pvParameters )

这两个宏的主要目的是提供一种便捷的方式来声明和定义 FreeRTOS 的任务函数

Tickless idle/low power functionality

/* Tickless idle/low power functionality. */#ifndef portSUPPRESS_TICKS_AND_SLEEPextern void vPortSuppressTicksAndSleep( TickType_t xExpectedIdleTime );#define portSUPPRESS_TICKS_AND_SLEEP( xExpectedIdleTime )    vPortSuppressTicksAndSleep( xExpectedIdleTime )#endif

用来处理任务进入低功耗模式

如果支持低功耗模式configUSE_TICKLESS_IDLE == 1（在FreeRTOSConfig.h中配置），才会有这个函数vPortSuppressTicksAndSleep

Architecture specific optimisations

/* Architecture specific optimisations. */#ifndef configUSE_PORT_OPTIMISED_TASK_SELECTION#define configUSE_PORT_OPTIMISED_TASK_SELECTION    1#endif

通过启用 configUSE_PORT_OPTIMISED_TASK_SELECTION，FreeRTOS 可以在上下文切换时采用更高效的任务选择策略

但是在FreeRTOS.h中 if 没有define configUSE_PORT_OPTIMISED_TASK_SELECTION的话，会define为0 ？两处位置不一致，虽然这样不影响FreeRTOS的运行，因为在FreeRTOSConfig.h中已经define了这个宏。

（注：下面的Generic helper function； Check the configuration 还有 Store/clear the ready priorities in a bit map部分都是在configUSE_PORT_OPTIMISED_TASK_SELECTION被define 为 1 时才会编译的）

Generic helper function

/* Generic helper function. */__attribute__( ( always_inline ) ) static inline uint8_t ucPortCountLeadingZeros( uint32_t ulBitmap ){uint8_t ucReturn;__asm volatile ( "clz %0, %1" : "=r" ( ucReturn ) : "r" ( ulBitmap ) : "memory" );return ucReturn;}

这个函数通过内联汇编直接使用 ARM 指令 clz 来高效计算给定 32 位无符号整数的前导零数量。
attribute((always_inline))：强制内联此函数
clz %0, %1：这是 ARM 汇编指令，用于计算 ulBitmap 的前导零，并将结果存储在 ucReturn 中
“memory”：告知编译器可能改变内存

Check the configuration

/* Check the configuration. */#if ( configMAX_PRIORITIES > 32 )#error configUSE_PORT_OPTIMISED_TASK_SELECTION can only be set to 1 when configMAX_PRIORITIES is less than or equal to 32.  It is very rare that a system requires more than 10 to 15 difference priorities as tasks that share a priority will time slice.#endif

这一部分是在configUSE_PORT_OPTIMISED_TASK_SELECTION为1时才会进行编译的，而使用优化任务选择，那么任务的优先级必须不能超过32，否则报错

Store/clear the ready priorities in a bit map

/* Store/clear the ready priorities in a bit map. */#define portRECORD_READY_PRIORITY( uxPriority, uxReadyPriorities )    ( uxReadyPriorities ) |= ( 1UL << ( uxPriority ) )#define portRESET_READY_PRIORITY( uxPriority, uxReadyPriorities )     ( uxReadyPriorities ) &= ~( 1UL << ( uxPriority ) )#define portGET_HIGHEST_PRIORITY( uxTopPriority, uxReadyPriorities )    uxTopPriority = ( 31UL - ( uint32_t ) ucPortCountLeadingZeros( ( uxReadyPriorities ) ) )

portRECORD_READY_PRIORITY
即把uxReadyPriorities 的uxPriority位置1

portRESET_READY_PRIORITY
即把uxReadyPriorities 的uxPriority位清0

portGET_HIGHEST_PRIORITY
这个是计算uxReadyPriorities 中 1 的最高位赋值给uxTopPriority
假如uxReadyPriorities 中bit 28 为1 ，bit29，bit30，bit31都为0。
那么经过函数ucPortCountLeadingZeros会返回前导零为3，所以uxTopPriority求得为28。

vPortRaiseBASEPRI

禁止中断 #define portDISABLE_INTERRUPTS() vPortRaiseBASEPRI()

我们来看vPortRaiseBASEPRI()的实现

portFORCE_INLINE static void vPortRaiseBASEPRI( void ){uint32_t ulNewBASEPRI;__asm volatile("	mov %0, %1												\n"\"	cpsid i													\n"\"	msr basepri, %0											\n"\"	isb														\n"\"	dsb														\n"\"	cpsie i													\n"\: "=r" ( ulNewBASEPRI ) : "i" ( configMAX_SYSCALL_INTERRUPT_PRIORITY ) : "memory");}

portFORCE_INLINE 强制内联函数
这个宏定义结合了 inline 关键字和 GCC 的 attribute((always_inline)) 特性，目的是告诉编译器，尽量将该函数内联到调用点，而不考虑正常内联规则下的限制。

: “=r” ( ulNewBASEPRI ) : “i” ( configMAX_SYSCALL_INTERRUPT_PRIORITY ) : “memory”

内嵌汇编语法设计成在 汇编指令块 之后跟随 操作数列表（输出、输入和修改列表），使得每个操作数都有明确的上下文，这样编译器能够清楚地了解在执行汇编指令时应使用哪些操作数。

每个操作数在操作数列表中的顺序与汇编语句中的占位符（如 %0, %1）一一对应。
%0 代表第一个操作数，%1 代表第二个操作数。

“=r” ( ulNewBASEPRI ) 是一个寄存器
“i” ( configMAX_SYSCALL_INTERRUPT_PRIORITY ) 这里configMAX_SYSCALL_INTERRUPT_PRIORITY 是一个立即数，会直接嵌入到汇编指令中。
“memory” 表示这个汇编代码块会对内存状态产生影响，编译器需要知道在这个块的前后，可能会有外部的内存访问或状态变化。这个声明会影响编译器对代码优化的决策。

%0 对应于 ulNewBASEPRI，其定义为 : “=r” ( ulNewBASEPRI )。r 是寄存器类型
%1 对应的是 configMAX_SYSCALL_INTERRUPT_PRIORITY，其定义为 : “i” ( configMAX_SYSCALL_INTERRUPT_PRIORITY )。“i” 表示这个操作数是一个立即数（immediate value），在汇编中将会在指令中直接使用。

mov %0, %1 这条指令把输入操作数 %1 的值（configMAX_SYSCALL_INTERRUPT_PRIORITY）移动到 ulNewBASEPRI 中。

cpsid i：这条指令会禁用中断（Clear Pending State Interrupt Disable），确保接下来的操作不会被中断打断。
msr basepri, %0：将新的优先级值（ulNewBASEPRI）写入 BASEPRI 寄存器。只有优先级高于这个值的中断才能被处理。
isb：指令同步屏障，确保前面的指令在继续执行之后的指令之前已经完成。
dsb：数据同步屏障，确保所有之前的内存访问操作已经完成，数据一致性得到保证。
cpsie i：重新启用中断，使得可以响应比 ulNewBASEPRI 所指定的优先级更高的中断。

vPortRaiseBASEPRI 函数通过设置 BASEPRI 寄存器的值，控制中断的响应，使得只允许响应更高优先级的中断。

BASEPRI寄存器
0：无影响
x：屏蔽优先级小于x（也就是优先级数值大于x）的中断

ulPortRaiseBASEPRI

portFORCE_INLINE static uint32_t ulPortRaiseBASEPRI( void ){uint32_t ulOriginalBASEPRI, ulNewBASEPRI;__asm volatile("	mrs %0, basepri											\n"\"	mov %1, %2												\n"\"	cpsid i													\n"\"	msr basepri, %1											\n"\"	isb														\n"\"	dsb														\n"\"	cpsie i													\n"\: "=r" ( ulOriginalBASEPRI ), "=r" ( ulNewBASEPRI ) : "i" ( configMAX_SYSCALL_INTERRUPT_PRIORITY ) : "memory");/* This return will not be reached but is necessary to prevent compiler* warnings. */return ulOriginalBASEPRI;}

ulPortRaiseBASEPRI是vPortRaiseBASEPRI的带返回值的版本

vPortRaiseBASEPRI：无返回值
ulPortRaiseBASEPRI：返回BASEPRI 寄存器修改之前的值

vPortSetBASEPRI

portFORCE_INLINE static void vPortSetBASEPRI( uint32_t ulNewMaskValue ){__asm volatile("	msr basepri, %0	"::"r" ( ulNewMaskValue ) : "memory");}

和vPortRaiseBASEPRI其实差不多的，只是
vPortRaiseBASEPRI是将configMAX_SYSCALL_INTERRUPT_PRIORITY 的值赋给 ulNewBASEPRI，这个值通常在 FreeRTOS 中用来作为系统调用中断的最大优先级。

而vPortSetBASEPRI是由参数传入的值

xPortIsInsideInterrupt

portFORCE_INLINE static BaseType_t xPortIsInsideInterrupt( void ){uint32_t ulCurrentInterrupt;BaseType_t xReturn;/* Obtain the number of the currently executing interrupt. */__asm volatile ( "mrs %0, ipsr" : "=r" ( ulCurrentInterrupt )::"memory" );if( ulCurrentInterrupt == 0 ){xReturn = pdFALSE;}else{xReturn = pdTRUE;}return xReturn;}

xPortIsInsideInterrupt 函数用于检测当前代码是否在中断服务例程中执行。它通过读取 ARM Cortex-M 架构的 IPSR 寄存器来判断当前的中断状态。

ulCurrentInterrupt：用于存储当前正在执行的中断编号
xReturn：用于存储函数的返回值，表示是否在中断中

mrs %0, ipsr：这是 ARM 汇编指令，用于从 IPSR 寄存器读取当前正在执行的中断编号。IPSR（Interrupt Program Status Register）寄存器存储当前中断的状态信息

“=r” ( ulCurrentInterrupt )：表示将读取的中断编号存储到 ulCurrentInterrupt 变量中

::“memory”：告知编译器，该指令可能会影响内存，防止编译器进行优化

如果 ulCurrentInterrupt 的值为 0，表示当前没有中断正在执行，因此将 xReturn 设置为 pdFALSE。
否则，设置 xReturn 为 pdTRUE，表明当前在中断上下文中。

IPSR 寄存器的低 9 位（Bit[8:0]）存储当前正在执行的中断的编号。如果处于处理异常的状态，它也会存储相应的异常编号。

当没有中断正在执行时，IPSR 的值为 0。当前执行的代码是在主程序中，而不是在中断服务例程中