Add missing MPU prototypes
This commit address the following issues with MPU prototypes:
1. Fix the decorator according to which MPU wrapper is used.
2. Add the missing prototypes for v1.
3. Add the corresponding mapping to mpu_wrappers.h.
4. Update MPU v1 wrappers for vTaskList and vTaskGetRunTimeStats.
This was reported here - https://forums.freertos.org/t/cortex-m55-and-16-region-mpu-support/21470/5.
Signed-off-by: Gaurav Aggarwal <aggarg@amazon.com>
Export the PRIVILEGED_FUNCTION, PRIVILEGED_DATA, and FREERTOS_SYSTEM_CALL
attributes to make it easier for end users to add their own privileged functions and
system calls.
This PR adds Access Control to kernel objects on a per task basis to MPU
ports. The following needs to be defined in the `FreeRTOSConfig.h` to
enable this feature:
```c
#define configUSE_MPU_WRAPPERS_V1 0
#define configENABLE_ACCESS_CONTROL_LIST 1
```
This PR adds the following new APIs:
```c
void vGrantAccessToTask( TaskHandle_t xTask,
TaskHandle_t xTaskToGrantAccess );
void vRevokeAccessToTask( TaskHandle_t xTask,
TaskHandle_t xTaskToRevokeAccess );
void vGrantAccessToSemaphore( TaskHandle_t xTask,
SemaphoreHandle_t xSemaphoreToGrantAccess );
void vRevokeAccessToSemaphore( TaskHandle_t xTask,
SemaphoreHandle_t xSemaphoreToRevokeAccess );
void vGrantAccessToQueue( TaskHandle_t xTask,
QueueHandle_t xQueueToGrantAccess );
void vRevokeAccessToQueue( TaskHandle_t xTask,
QueueHandle_t xQueueToRevokeAccess );
void vGrantAccessToQueueSet( TaskHandle_t xTask,
QueueSetHandle_t xQueueSetToGrantAccess );
void vRevokeAccessToQueueSet( TaskHandle_t xTask,
QueueSetHandle_t xQueueSetToRevokeAccess );
void vGrantAccessToEventGroup( TaskHandle_t xTask,
EventGroupHandle_t xEventGroupToGrantAccess );
void vRevokeAccessToEventGroup( TaskHandle_t xTask,
EventGroupHandle_t xEventGroupToRevokeAccess );
void vGrantAccessToStreamBuffer( TaskHandle_t xTask,
StreamBufferHandle_t xStreamBufferToGrantAccess );
void vRevokeAccessToStreamBuffer( TaskHandle_t xTask,
StreamBufferHandle_t xStreamBufferToRevokeAccess );
void vGrantAccessToMessageBuffer( TaskHandle_t xTask,
MessageBufferHandle_t xMessageBufferToGrantAccess );
void vRevokeAccessToMessageBuffer( TaskHandle_t xTask,
MessageBufferHandle_t xMessageBufferToRevokeAccess );
void vGrantAccessToTimer( TaskHandle_t xTask,
TimerHandle_t xTimerToGrantAccess );
void vRevokeAccessToTimer( TaskHandle_t xTask,
TimerHandle_t xTimerToRevokeAccess );
```
An unprivileged task by default has access to itself only and no other
kernel object. The application writer needs to explicitly grant an
unprivileged task access to all the kernel objects it needs. The best
place to do that is before starting the scheduler when all the kernel
objects are created.
For example, let's say an unprivileged tasks needs access to a queue and
an event group, the application writer needs to do the following:
```c
vGrantAccessToQueue( xUnprivilegedTaskHandle, xQueue );
vGrantAccessToEventGroup( xUnprivilegedTaskHandle, xEventGroup );
```
The application writer MUST revoke all the accesses before deleting a
task. Failing to do so will result in undefined behavior. In the above
example, the application writer needs to make the following 2 calls
before deleting the task:
```c
vRevokeAccessToQueue( xUnprivilegedTaskHandle, xQueue );
vRevokeAccessToEventGroup( xUnprivilegedTaskHandle, xEventGroup );
```
Memory Protection Unit (MPU) Enhancements
This commit introduces a new MPU wrapper that places additional
restrictions on unprivileged tasks. The following is the list of changes
introduced with the new MPU wrapper:
1. Opaque and indirectly verifiable integers for kernel object handles:
All the kernel object handles (for example, queue handles) are now
opaque integers. Previously object handles were raw pointers.
2. Saving the task context in Task Control Block (TCB): When a task is
swapped out by the scheduler, the task's context is now saved in its
TCB. Previously the task's context was saved on its stack.
3. Execute system calls on a separate privileged only stack: FreeRTOS
system calls, which execute with elevated privilege, now use a
separate privileged only stack. Previously system calls used the
calling task's stack. The application writer can control the size of
the system call stack using new configSYSTEM_CALL_STACK_SIZE config
macro.
4. Memory bounds checks: FreeRTOS system calls which accept a pointer
and de-reference it, now verify that the calling task has required
permissions to access the memory location referenced by the pointer.
5. System call restrictions: The following system calls are no longer
available to unprivileged tasks:
- vQueueDelete
- xQueueCreateMutex
- xQueueCreateMutexStatic
- xQueueCreateCountingSemaphore
- xQueueCreateCountingSemaphoreStatic
- xQueueGenericCreate
- xQueueGenericCreateStatic
- xQueueCreateSet
- xQueueRemoveFromSet
- xQueueGenericReset
- xTaskCreate
- xTaskCreateStatic
- vTaskDelete
- vTaskPrioritySet
- vTaskSuspendAll
- xTaskResumeAll
- xTaskGetHandle
- xTaskCallApplicationTaskHook
- vTaskList
- vTaskGetRunTimeStats
- xTaskCatchUpTicks
- xEventGroupCreate
- xEventGroupCreateStatic
- vEventGroupDelete
- xStreamBufferGenericCreate
- xStreamBufferGenericCreateStatic
- vStreamBufferDelete
- xStreamBufferReset
Also, an unprivileged task can no longer use vTaskSuspend to suspend
any task other than itself.
We thank the following people for their inputs in these enhancements:
- David Reiss of Meta Platforms, Inc.
- Lan Luo, Xinhui Shao, Yumeng Wei, Zixia Liu, Huaiyu Yan and Zhen Ling
of School of Computer Science and Engineering, Southeast University,
China.
- Xinwen Fu of Department of Computer Science, University of
Massachusetts Lowell, USA.
- Yuequi Chen, Zicheng Wang, Minghao Lin of University of Colorado
Boulder, USA.
It was possible for an unprivileged task to invoke any function with
privilege by passing it as a parameter to MPU_xTaskCreate,
MPU_xTaskCreateStatic, MPU_xTimerCreate, MPU_xTimerCreateStatic, or
MPU_xTimerPendFunctionCall.
This commit ensures that MPU_xTaskCreate and MPU_xTaskCreateStatic can
only create unprivileged tasks. It also removes the following APIs:
1. MPU_xTimerCreate
2. MPU_xTimerCreateStatic
3. MPU_xTimerPendFunctionCall
We thank Huazhong University of Science and Technology for reporting
this issue.
Signed-off-by: Gaurav Aggarwal <aggarg@amazon.com>
It was possible for a third party that had already independently gained
the ability to execute injected code to achieve further privilege
escalation by branching directly inside a FreeRTOS MPU API wrapper
function with a manually crafted stack frame. This commit removes the
local stack variable `xRunningPrivileged` so that a manually crafted
stack frame cannot be used for privilege escalation by branching
directly inside a FreeRTOS MPU API wrapper.
We thank Certibit Consulting, LLC, Huazhong University of Science and
Technology and the SecLab team at Northeastern University for reporting
this issue.
Signed-off-by: Gaurav Aggarwal <aggarg@amazon.com>
* Introduce configRUN_TIME_COUNTER_TYPE which enables developers to define the type used to hold run time statistic counters. Defaults to uint32_t for backward compatibility. #define configRUN_TIME_COUNTER_TYPE to a type (for example, uint64_t) in FreeRTOSConfig.h to override the default.
Introduce ulTaskGetIdleRunTimePercent() to complement the pre-existing ulTaskGetIdleRunTimeCounter(). Whereas the pre-existing function returns the raw run time counter value, the new function returns the percentage of the entire run time consumed by the idle task. Note the amount of idle time is only a good measure of the slack time in a system if there are no other tasks executing at the idle priority, tickless
idle is not used, and configIDLE_SHOULD_YIELD is set to 0.
* Add ultaskgetidleruntimepercent to lexicon.txt.
* Update History file.
Add the MPU version of ulTaskGetIdleRunTimePercent().
* Update include/FreeRTOS.h to correct comment as per aggarg@ suggestion.
* Fix alignment in mpu_wrappers.h.
Commit changes to mpu_prototypes.h which were missed from the original commit.
configSTACK_ALLOCATION_FROM_SEPARATE_HEAP was added recently in
https://github.com/FreeRTOS/FreeRTOS-Kernel/pull/267. This macro was
used in portable.h before its default value was defined, resulting in a
warning when built with -Wundef. This changes moves the default value
definition for configSTACK_ALLOCATION_FROM_SEPARATE_HEAP to portable.h
to ensure that it is defined before first use.
portUSING_MPU_WRAPPERS check in mpu_wrappers.h was updated in
https://github.com/FreeRTOS/FreeRTOS-Kernel/pull/285. The new check
results in a warning when built with -Wundef because
portUSING_MPU_WRAPPERS is not defined yet. This changes adds the default
value definition for portUSING_MPU_WRAPPERS to portable.h to ensure that
it is defined before first use.
Signed-off-by: Gaurav Aggarwal <aggarg@amazon.com>
This change removes the FreeRTOS System Calls (aka MPU wrappers) for the
following kernel APIs:
- xTaskCreateRestricted
- xTaskCreateRestrictedStatic
- vTaskAllocateMPURegions
A system call allows an unprivileged task to execute a kernel API which
is otherwise accessible to privileged software only. The above 3 APIs
can create a new task with a different MPU configuration or alter the
MPU configuration of an existing task. This an be (mis)used by an
unprivileged task to grant itself access to a region which it does not
have access to.
Removing the system calls for these APIs ensures that an unprivileged
task cannot execute this APIs. If an unprivileged task attempts to
execute any of these API, it will result in a Memory Fault.
Signed-off-by: Gaurav Aggarwal <aggarg@amazon.com>
This PR:
Changes the INCLUDE_vTaskDelayUntil compile time constant to INCLUDE_xTaskDelayUntil.
Updates FreeRTOS.h to ensure backward compatibility for projects that already have INCLUDE_vTaskDelayUntil defined.
Updates the MPU prototypes, wrapper and implementation to use the updated xTaskDelayUntil() function.
Tests to be checked into the FreeRTOS/FreeRTOS repository after this PR.
* Style: Change FreeRTOS websites in comments
* Style: Change freertos to FreeRTOS in comments
* Style: Remove broken link
Co-authored-by: Alfred Gedeon <gedeonag@amazon.com>
Gaurav-Aggarwal-AWS
Rahul Kar
Soren Ptak
chinglee-iot
Paul Bartell
Gaurav Aggarwal
Monika Singh
Anton Lagerholm
RichardBarry
alfred gedeon
Cobus van Eeden
David Chalco
David Chalco
alfred gedeon
Alfred Gedeon
Yuhui.Zheng