Memory Protection Unit (MPU) Enhancements (#705)

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.
123 files changed
tree: 8aeaae8581bdb4ad0870cb39fc478444bbfd2192
  1. .github/
  2. include/
  3. portable/
  4. .git-blame-ignore-revs
  5. .gitattributes
  6. .gitmodules
  7. CMakeLists.txt
  8. croutine.c
  9. event_groups.c
  10. GitHub-FreeRTOS-Kernel-Home.url
  11. History.txt
  12. LICENSE.md
  13. list.c
  14. manifest.yml
  15. queue.c
  16. Quick_Start_Guide.url
  17. README.md
  18. stream_buffer.c
  19. tasks.c
  20. timers.c
README.md

CMock Unit Tests codecov

Getting started

This repository contains FreeRTOS kernel source/header files and kernel ports only. This repository is referenced as a submodule in FreeRTOS/FreeRTOS repository, which contains pre-configured demo application projects under FreeRTOS/Demo directory.

The easiest way to use FreeRTOS is to start with one of the pre-configured demo application projects. That way you will have the correct FreeRTOS source files included, and the correct include paths configured. Once a demo application is building and executing you can remove the demo application files, and start to add in your own application source files. See the FreeRTOS Kernel Quick Start Guide for detailed instructions and other useful links.

Additionally, for FreeRTOS kernel feature information refer to the Developer Documentation, and API Reference.

Getting help

If you have any questions or need assistance troubleshooting your FreeRTOS project, we have an active community that can help on the FreeRTOS Community Support Forum.

To consume FreeRTOS-Kernel

Consume with CMake

If using CMake, it is recommended to use this repository using FetchContent. Add the following into your project‘s main or a subdirectory’s CMakeLists.txt:

  • Define the source and version/tag you want to use:
FetchContent_Declare( freertos_kernel
  GIT_REPOSITORY https://github.com/FreeRTOS/FreeRTOS-Kernel.git
  GIT_TAG        main #Note: Best practice to use specific git-hash or tagged version
)
  • Add a freertos_config library (typically an INTERFACE library) The following assumes the directory structure:
    • include/FreeRTOSConfig.h
add_library(freertos_config INTERFACE)

target_include_directories(freertos_config SYSTEM
INTERFACE
    include
)

target_compile_definitions(freertos_config
  INTERFACE
    projCOVERAGE_TEST=0
)
  • Configure the FreeRTOS-Kernel and make it available
    • this particular example supports a native and cross-compiled build option.
set( FREERTOS_HEAP "4" CACHE STRING "" FORCE)
# Select the native compile PORT
set( FREERTOS_PORT "GCC_POSIX" CACHE STRING "" FORCE)
# Select the cross-compile PORT
if (CMAKE_CROSSCOMPILING)
  set(FREERTOS_PORT "GCC_ARM_CA9" CACHE STRING "" FORCE)
endif()

FetchContent_MakeAvailable(freertos_kernel)

Consuming stand-alone - Cloning this repository

To clone using HTTPS:

git clone https://github.com/FreeRTOS/FreeRTOS-Kernel.git

Using SSH:

git clone git@github.com:FreeRTOS/FreeRTOS-Kernel.git

Repository structure

  • The root of this repository contains the three files that are common to every port - list.c, queue.c and tasks.c. The kernel is contained within these three files. croutine.c implements the optional co-routine functionality - which is normally only used on very memory limited systems.

  • The ./portable directory contains the files that are specific to a particular microcontroller and/or compiler. See the readme file in the ./portable directory for more information.

  • The ./include directory contains the real time kernel header files.

Code Formatting

FreeRTOS files are formatted using the “uncrustify” tool. The configuration file used by uncrustify can be found in the .github/uncrustify.cfg file.

Line Endings

File checked into the FreeRTOS-Kernel repository use unix-style LF line endings for the best compatbility with git.

For optmial compatibility with Microsoft Windows tools, it is best to enable the git autocrlf feature. You can eanble this setting for the current repository using the following command:

git config core.autocrlf true

Git History Optimizations

Some commits in this repository perform large refactors which touch many lines and lead to unwanted behavior when using the git blame command. You can configure git to ignore the list of large refactor commits in this repository with the followig command:

git config blame.ignoreRevsFile .git-blame-ignore-revs

Spelling

lexicon.txt contains words that are not traditionally found in an English dictionary. It is used by the spellchecker to verify the various jargon, variable names, and other odd words used in the FreeRTOS code base. If your pull request fails to pass the spelling and you believe this is a mistake, then add the word to lexicon.txt. Note that only the FreeRTOS Kernel source files are checked for proper spelling, the portable section is ignored.