mastering.ch01

Mastering the FreeRTOS™ Real Time Kernel

This is the 161204 copy which does not yet cover FreeRTOS V9.0.0, FreeRTOS V10.0.0, or low power tick-less operation. Check https://www.FreeRTOS.org regularly for additional documentation and updates to this book. See https://www.FreeRTOS.org/FreeRTOS-V9.html for information on FreeRTOS V9.x.x. See https://www.freertos.org/FreeRTOS-V10.html for information on FreeRTOS V10.x.x. Applications created using FreeRTOS V9.x.x onwards can allocate all kernel objects statically at compile time, removing the need to include a heap memory manager.

This text is being provided for free. In return we ask that you use the business contact email link on https://www.FreeRTOS.org/contact to provide feedback, comments and corrections.** Thank you.

Mastering the FreeRTOS™ Real Time Kernel

A Hands-On Tutorial Guide

Richard Barry

Pre-release 161204 Edition. TBD.

All text, source code, and diagrams are the exclusive property of Amazon Web Services. unless otherwise noted inline.

© 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.

https://www.FreeRTOS.org

https://www.FreeRTOS.org/plus

https://www.FreeRTOS.org/labs

FreeRTOS™, FreeRTOS.org™ and the FreeRTOS logo are trademarks of Amazon Web Services. OPENRTOS® and SAFERTOS® are trademarks of WITTENSTEIN High Integrity Systems Ltd. All other brands or product names are the property of their respective holders.

To Caroline, India and Max.

List of Abbreviations

ADC	Analog to Digital Converter
API	Application Programming Interface
DMA	Direct Memory Access
FAQ	Frequently Asked Question
FIFO	First In First Out
HMI	Human Machine Interface
IDE	Integrated Development Environment
IRQ	Interrupt Request
ISR	Interrupt Service Routine
LCD	Liquid Crystal Display
MCU	Microcontroller
RMS	Rate Monotonic Scheduling
RTOS	Real-time Operating System
SIL	Safety Integrity Level
SPI	Serial Peripheral Interface
TCB	Task Control Block
UART	Universal Asynchronous Receiver/Transmitter

1 Preface

1.1 Multitasking in Small Embedded Systems

1.1.1 About the FreeRTOS Kernel

FreeRTOS is a collection of C libraries comprised of a real-time kernel and a set of modular libraries that implement complementary functionality.

Richard Barry originally developed FreeRTOS around 2003. Real-Time Engineers Ltd, Richard's company, continued FreeRTOS development in close partnership with the world's leading chip companies until Amazon Web Services (AWS) took stewardship of FreeRTOS 2016. Richard now continues his work on FreeRTOS as a senior principal engineer within the AWS FreeRTOS team.

The FreeRTOS kernel is ideally suited to deeply embedded real-time applications that use microcontrollers or small microprocessors. This type of application typically includes a mix of both hard and soft real-time requirements.

Soft real-time requirements state a time deadline—but breaching the deadline would not render the system useless. For example, responding to keystrokes too slowly might make a system seem annoyingly unresponsive without actually making it unusable.

Hard real-time requirements state a time deadline—and breaching the deadline would result in absolute failure of the system. For example, a driver's airbag has the potential to do more harm than good if it responded to crash sensor inputs too slowly.

The FreeRTOS kernel is a real-time kernel (or real-time scheduler) that enables applications built on FreeRTOS to meet their hard real-time requirements. It enables applications to be organized as a collection of independent threads of execution. For example, on a processor that has only one core, only a single thread of execution can execute at any one time. The kernel decides which thread to execute by examining the priority assigned to each thread by the application designer. In the simplest case, the application designer could assign higher priorities to threads that implement hard real-time requirements and lower priorities to threads that implement soft real-time requirements. Allocating priorities in that way would ensure hard real-time threads always execute ahead of soft real-time threads, but priority assignment decisions are not always that simplistic.

Do not be concerned if you do not fully understand the concepts in the previous paragraph yet. The following chapters provide a detailed explanation, with many examples, to help you understand how to use a real-time kernel, and FreeRTOS in particular.

1.1.2 Value Proposition

The unprecedented global success of the FreeRTOS kernel comes from its compelling value proposition; FreeRTOS is professionally developed, strictly quality controlled, robust, supported, does not contain any intellectual property ownership ambiguity, and is truly free to use in commercial applications without any requirement to expose your proprietary source code. Further, AWS's stewardship provides a global presence, expert security event response procedures, a large and diverse development team, expertise in formal verification, and long-term support – all while maintaining FreeRTOS as a hardware-, development tool-, and cloud service-neutral open-source project. FreeRTOS development is transparent and community-driven in GitHub, and does not require any special tooling.

You can take a product to market using FreeRTOS without even telling us, let alone paying any fees, and thousands of companies do just that. If at any time you would like to receive additional backup, or if your legal team requires additional written guarantees or indemnification, then our strategic partners provide simple low-cost commercial license options. Peace of mind comes with the knowledge that you can opt to take the commercial route whenever you choose.

1.1.3 A Note About Terminology

In FreeRTOS, each thread of execution is called a 'task'. There is no consensus on terminology within the embedded community, but I prefer 'task' to 'thread,' as thread can have a more specific meaning in some fields of application.

1.1.4 Why Use an RTOS?

There are many well-established techniques for writing good embedded software without using a multithreading kernel. If the system under development is simple, then these techniques might provide the most appropriate solution. Using a kernel would likely be preferable in more complex cases, but where the crossover point occurs will always be subjective.

As already described, task prioritization can help ensure an application meets its processing deadlines, but a kernel can bring other less obvious benefits, too. Some of these are listed very briefly below.

• Abstracting away timing information

  The RTOS is responsible for execution timing and provides a time-related API to the application. That allows the structure of the application code to be more straightforward and the overall code size to be smaller.

• Maintainability/Extensibility

  Abstracting away timing details results in fewer interdependencies between modules and allows the software to evolve in a controlled and predictable way. Also, the kernel is responsible for the timing, so application performance is less susceptible to changes in the underlying hardware.

• Modularity

  Tasks are independent modules, each of which should have a well-defined purpose.

• Team development

  Tasks should also have well-defined interfaces, allowing easier development by teams.

• Easier testing

  Tasks that are well-defined independent modules with clean interfaces are easier to test in isolation.

• Code reuse

  Code designed with greater modularity and fewer interdependencies is easier to reuse.

• Improved efficiency

  Application code that uses an RTOS can be completely event-driven because no processing time needs to be wasted by polling for events that have not occurred.

  Countering the efficiency saving is the need to process the RTOS tick interrupt and switch execution from one task to another. However, applications that don't use an RTOS normally include some form of tick interrupt anyway.

• Idle time

  The automatically created Idle task executes when there are no application tasks that require processing. The Idle task can measure spare processing capacity, perform background checks, or place the processor into a low-power mode.

• Power Management

  The efficiency gains that result from using an RTOS allow the processor to spend more time in a low power mode.

  Power consumption can be decreased significantly by placing the processor into a low power state each time the Idle task runs. FreeRTOS also has a special tick-less mode. Using the tick-less mode allows the processor to enter a lower power mode than would otherwise be possible and remain in the low power mode for longer.

• Flexible interrupt handling

  Interrupt handlers can be kept very short by deferring processing to either a task created by the application writer or the automatically created RTOS daemon task.

• Mixed processing requirements

  Simple design patterns can achieve a mix of periodic, continuous, and event-driven processing within an application. In addition, hard and soft real-time requirements can be met by selecting appropriate task and interrupt priorities.

1.1.5 FreeRTOS Kernel Features

The FreeRTOS kernel has the following standard features:

• Pre-emptive or co-operative operation

• Optional time-slicing

• Very flexible task priority assignment

• Flexible, fast and light weight task notification mechanism

• Queues

• Binary semaphores

• Counting semaphores

• Mutexes

• Recursive mutexes

• Software timers

• Event groups

• Stream buffers

• Message buffers

• Tick hook functions

• Idle hook functions

• Stack overflow checking

• Trace macros

• Task run-time statistics gathering

• Optional commercial licensing and support

• Full interrupt nesting model (for some architectures)

• A tick-less capability for extreme low power applications (for some architectures)

• Software managed interrupt stack when appropriate (this can help save RAM)

• The ability to create RTOS objects using either statically or dynamically allocated memory

1.1.6 Licensing, and The FreeRTOS, OpenRTOS, and SafeRTOS Family

The FreeRTOS MIT open source license is designed to ensure:

• FreeRTOS can be used in commercial applications.

• FreeRTOS itself remains freely available to everybody.

• FreeRTOS users retain ownership of their intellectual property.

See https://www.FreeRTOS.org/license for the latest open source license information.

OpenRTOS is a commercially licensed version of FreeRTOS provided under license from Amazon Web Services by a third party.

SafeRTOS shares the same usage model as FreeRTOS, but has been developed in accordance with the practices, procedures, and processes necessary to claim compliance with various internationally recognized safety related standards.

1.2 Included Source Files and Projects

1.2.1 Obtaining the Examples that Accompany this Book

The zip file available for download from https://www.FreeRTOS.org/Documentation/code contains all the source code, pre-configured project files, and instructions necessary to build and execute the examples presented in this book. Note the zip file will not necessarily contain the most recent version of FreeRTOS.

The screenshots included in this book show the examples executing in a Microsoft Windows environment, using the FreeRTOS Windows port. The project that uses the FreeRTOS Windows port is pre-configured to build using the free Community edition of Visual Studio, available from https://www.visualstudio.com/. Note that while the FreeRTOS Windows port provides a convenient evaluation, test, and development platform, it does not provide true real-time behavior.