Lines Matching +full:freertos +full:- +full:kernel
1 FreeRTOS Port for Xtensa Configurable and Diamond Processors
4 FreeRTOS Kernel Version 10.0.0
8 ------------
10 This document describes the Xtensa port for FreeRTOS multitasking RTOS.
11 For an introduction to FreeRTOS itself, please refer to FreeRTOS
14 This port currently works with FreeRTOS kernel version 10.0.0.
18 --------------------------------------------------
23 requirements. You must use Xtensa Tools to compile and link FreeRTOS and
26 NOTE: It may be possible to build and run this with the open-source
27 xtensa-linux tools provided you have the correct overlay for your Xtensa
33 thread-safety on a per task basis (for use in tasks only, not interrupt
46 FreeRTOS for Xtensa configurable processors requires the following minimum
48 - Timer interrupt option with at least one interruptible timer.
49 - Interrupt option (implied by the timer interrupt option).
50 - Exception Architecture 2 (XEA2). Please note that XEA1 is NOT supported.
60 interrupt-driven drivers - it is not specific to any RTOS. Note that
61 FreeRTOS can run on any Xtensa or Diamond board without this board support
63 and drivers for any on-board devices you want to use.
67 ------------
69 The Xtensa port of FreeRTOS is available at this location:
71 https://github.com/foss-xtensa/amazon-freertos
73 This download includes the core FreeRTOS source and include files needed
74 to build the port. You can also download the official release of FreeRTOS
77 https://github.com/aws/amazon-freertos
86 First install the FreeRTOS common package in a directory of your choosing.
90 |-- demos
91 | `-- cadence
92 | `-- sim
93 | |-- common
94 | | |-- application_code
95 | | | `-- cadence_code
96 | | `-- config_files
97 | `-- xplorer
98 `-- lib
99 |-- FreeRTOS
100 | `-- portable
101 | |-- Common
102 | |-- MemMang
103 | `-- XCC
104 | `-- Xtensa
105 `-- include
106 `-- private
113 Building FreeRTOS for Xtensa
114 ----------------------------
116 To build the FreeRTOS library and the example programs, go into the
119 the 'lib/FreeRTOS/portable/XCC/Xtensa' directory that builds just the
120 FreeRTOS library.
128 hardware drivers or real-time performance.
130 The provided makefile simplifies building FreeRTOS and the example
136 a subdirectory so several core and platform builds can co-exist even with
142 Building the FreeRTOS Library
143 -----------------------------
147 You can use xt-make, which comes with the Xtensa Tools, to run the
152 > cd lib/FreeRTOS/portable/XCC/Xtensa
154 Now build the FreeRTOS RTOS as a library (libfreertos.a) as follows:
156 > xt-make
160 > xt-make TARGET=board
163 need to be specified when building the FreeRTOS library.
171 you need to redefine into xt-make as follows:
173 > xt-make XTENSA_CORE=<your_config_name> XTENSA_SYSTEM=<your_registry> ...
178 library in order to use FreeRTOS.
181 Building the FreeRTOS Examples
182 ------------------------------
192 > xt-make all
196 > xt-make all TARGET=sim
201 > xt-make all TARGET=ml605
205 > xt-make all TARGET=kc705
209 FreeRTOS library build makefile automatically, passing on the relevant
215 > xt-make all TARGET=sim CFLAGS="-O2 -Os -g"
217 This compiles the examples and links them with the FreeRTOS library
218 libfreertos.a and the appropriate linker-support package (LSP) for your
220 xt-make command line). The resulting ELF files can be downloaded and
224 To build your application with thread-safe C library support, you
252 --------------
254 The header file FreeRTOS.h, which is a part of the core FreeRTOS sources,
266 -----------------------------------
270 > xt-run [--turbo] example.exe
272 The option --turbo provides much faster, but non-cycle-accurate simulation
273 (the --turbo option is only available with Xtensa Tools version 7 or later).
278 > xplorer --debug example.exe
299 ----------------
307 stack space. The tool xt-stack-usage is helpful in determining safe stack
320 all kinds of hard-to-debug errors. It is recommended that you enable the
321 FreeRTOS stack checking features during development.
325 output - it implements a subset of printf() that has smaller code size
331 ---------------
341 -----------------------------
344 Makefile in building the FreeRTOS library and example application.
348 > xt-make CFLAGS="-O2 -DXT_USE_THREAD_SAFE_CLIB"
350 -g Specifies debug information.
351 -c Specifies object code generation.
352 -On Sets compiler optimization level n (default -O0).
353 -mlongcalls Allows assembler and linker to convert call
356 -x assembler-with-cpp Passes .s and .S files through C preprocessor.
357 -Dmacro Define a preprocessor macro with no value.
358 -Dmacro=value Define a preprocessor macro with a value.
363 Many definitions can be provided at compile-time via the -D option
367 thread-safety for the newlib and xclib libraries
390 performance, but cannot provide real-time
423 -------------------------------
426 purpose registers a0-a15 are used: the standard windowed ABI use with
431 Xtensa processors may have other special registers (including co-processor
439 a3-7 = second through sixth arguments of call (in simple cases).
442 a8-a15 = available for use as temporaries.
443 There are no callee-save registers. The windowed hardware automatically
444 saves registers a0-a3 on a call4, a0-a8 on a call8, a0-a12 on a call12,
457 a3-7 = second through sixth arguments of call (in simple cases).
460 a8-a11 = scratch.
461 a12-a15 = callee-save (a function must preserve these for its caller).
462 On a FreeRTOS API call, callee-save registers are saved only when a task
464 does not expect them to be preserved). On an interrupt, callee-saved
465 registers might only be saved and restored when a task context-switch
469 depending on the configuration (including co-processor registers and other
470 TIE state) that are part of the task context. FreeRTOS preserves all such
471 registers over an unsolicited context-switch triggered by an interrupt.
472 However it does NOT preserve these over a solicited context-switch during
473 a FreeRTOS API call. This bears some explanation. These special registers
474 are either ignored by the compiler or treated as caller-saved, meaning
477 FreeRTOS is always made by a function call, FreeRTOS assumes the caller
478 has saved any of these registers that are "live". FreeRTOS avoids a lot
483 registers are preserved over a FreeRTOS API call such as vTaskDelay().
487 a result of interrupt handling (interrupt frame) or from task-level
491 by pxCurrentTCB->pxTopOfStack. A special location common to both stack
496 ------------------------------------------------------
498 By default FreeRTOS for Xtensa is built with debug (-g) and without
499 compiler optimizations (-O0). This makes debugging easier. Of course,
500 -O0 costs performance and usually also increases stack usage. To make
501 FreeRTOS run faster you can change the Makefile to enable the desired
502 optimizations or set a predefined optimization level (-O<level>) .
504 Maximum performance is achieved with -O3 -ipa, but that might increase
505 the footprint substantially. A good compromise is -O2. See the compiler
508 Minimal footprint is achieved by optimizing for space with -Os, at the
511 The Xtensa architecture port-specific assembly files are coded with no
512 file-scope labels inside functions (all labels inside functions begin with
519 - You cannot set a breakpoint on a local label inside a function.
520 - Disassembly will show the entire function, but will get out of sync and
524 Since FreeRTOS is provided in source form, it is not difficult to remove
526 They can also be made visible by passing the '-L' option to the assembler
531 --------------------------------
533 FreeRTOS provides a complete set of efficient exception and first-level
538 your processor configuration. (Note that Diamond cores are pre-configured
548 xtensa_vectors.S. They are not specific to FreeRTOS, but call into
549 FreeRTOS where appropriate via macros defined in xtensa_rtos.h .
552 dispatchers that save relevant state and call user-definable handlers.
554 to create and install application-specific user interrupt handlers.
555 Similarly, user-defined handlers can be installed for exceptions (other
563 This FreeRTOS port supports strict priority-based nesting of interrupts.
566 application-defined sequence before any lower priority interrupts
570 individually by FreeRTOS (the application is free to access the INTENABLE
580 and interrupt in more detail. Many have nothing to do with FreeRTOS but
585 All Xtensa 'general exceptions' come to the user, kernel, or double
590 indicate a kernel or application bug.
602 the high-priority class of interrupts (which do not interact with
603 FreeRTOS), then reads EXCCAUSE and uses the cause (number) to index
604 into a table of user-specified handlers. The correct handler is then
606 returned to the code that caused the exception. The user-defined handler
610 If the cause is a level 1 (low-priority) or medium-priority interrupt,
620 user-defined handler.
622 Finally, the handler calls _frxt_int_exit to allow FreeRTOS to perform
626 If software prioritization is enabled, the handler will re-enable all
629 interrupt to pre-empt the lower priority handler.
634 a configuration-specific maximum interrupt level affected by the global
636 Interrupt levels above XCHAL_EXCM_LEVEL are of the high-priority class.
638 to be a special case of high-priority interrupts, but from a software
641 Dispatch of medium-priority interrupts is discussed in the section
647 a configuration-specific maximum interrupt level affected by the
649 High priority handlers may not directly interact with FreeRTOS at all,
655 occasionally signal FreeRTOS. Please see Xtensa documentation.
662 level to minimize latency servicing very fast time-critical interrupts.
663 The vector code jumps to the corresponding first-level interrupt handler,
664 which then executes application-provided assembler code before returning
667 Kernel Exception Handler:
669 Kernel mode is not used in this port of FreeRTOS, and therefore kernel
672 processor should a kernel exception occur.
682 frame or entering FreeRTOS, by emulating a register underflow and
683 re-executing 'movsp'.
690 in the windowed register file to their pre-determined locations
693 If a2 is non-zero, the handler returns a2 == -1 to the caller.
695 Co-Processor Exception Handler:
697 A co-processor exception is generated when a task accesses a
698 co-processor that it does not "own". Ownership represents which
699 task's state is currently in the co-processor. Co-processors are
700 context-switched "lazily" (on demand) only when a non-owning task
701 uses a co-processor instruction, otherwise a task retains ownership
702 even when it is preempted from the main processor. The co-processor
703 exception handler performs the context-switch and manages ownership.
705 Co-processors may not be used by any code outside the context of a
706 task. A co-processor exception triggered by code that is not part
707 of a running task is a fatal error and FreeRTOS for Xtensa will panic.
709 restoring co-processor state (which can be quite large) and in
718 processor is running in OCD mode under control of an OCD-based debugger,
730 bug in kernel code. The double exception vector handler triggers
745 unless in a high-priority interrupt handler). These hooks are enabled
747 FreeRTOS build. However an application is free to take advantage of
752 to install application-specific handlers. This method is more convenient
758 Code overlays are currently not supported for FreeRTOS. This will be
763 -End-