Lines Matching full:the
10 This document describes the Xtensa port for FreeRTOS multitasking RTOS.
20 The Xtensa configurable architecture supports a vast space of processor
22 extensions defined in the TIE language, with certain minimum
24 your application for your Xtensa configuration. The port uses the Xtensa
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
31 This port includes optional reentrancy support for the 'newlib' and
37 for thread safety. The 'uclibc' library is not reentrant and does not
42 a supported board or the Xtensa instruction set simulator (ISS). There
43 are also a couple of test programs used in maintaining the port, which
46 FreeRTOS for Xtensa configurable processors requires the following minimum
49 - Interrupt option (implied by the timer interrupt option).
57 with the Xtensa Tools. This provides the board clock frequency and basic
58 polled drivers for the display and console device. Note that XTBSP
62 (a "raw" platform), but you will have to provide the clock frequency
69 The Xtensa port of FreeRTOS is available at this location:
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
79 The Xtensa port files are currently not included in the official package.
86 First install the FreeRTOS common package in a directory of your choosing.
87 The structure of that package will look like this:
108 The Xtensa Tools are available from Cadence as part of a processor
109 license. Be sure you have installed the Xtensa Tools and your processor
116 To build the FreeRTOS library and the example programs, go into the
117 directory 'demos/cadence/sim' and use the makefile in that directory.
118 "make all" will build all the examples. There is another makefile in
119 the 'lib/FreeRTOS/portable/XCC/Xtensa' directory that builds just the
122 By default, you will build for the Xtensa instruction set simulator. If
126 recommends doing functional development on the simulator because it
130 The provided makefile simplifies building FreeRTOS and the example
132 are detailed instructions in the comments at the top of the makefile.
134 The makefiles work on Windows and Linux and support incremental builds.
135 The build for each Xtensa configuration and target platform is placed in
137 incremental rebuilds. You may specify the root of the build area (if tou
138 want it to be elsewhere than under the source tree) by defining BLDROOT
139 either in the make command or your shell environment.
142 Building the FreeRTOS Library
147 You can use xt-make, which comes with the Xtensa Tools, to run the
150 Change directories to the Xtensa port directory:
154 Now build the FreeRTOS RTOS as a library (libfreertos.a) as follows:
158 which by default builds for the simulator (TARGET=sim), or:
162 which builds for a supported board. Note that the board type does not
163 need to be specified when building the FreeRTOS library.
165 If you are building for an Xtensa processor configuration that is not the
166 default you selected when you installed Xtensa Tools, you need to define the
167 environment variable XTENSA_CORE. If your configuration is not in the
169 need to define the environment variable XTENSA_SYSTEM. See tools manuals.
170 You can avoid defining these in your environment if you pass the variables
175 There are more details about build options in the comment in the Makefile.
177 After the library has been built, you must link your application with this
181 Building the FreeRTOS Examples
184 The provided examples are designed to run on the Xtensa instruction set
188 To build the examples for the default platform (simulator):
194 which is the same as
198 The boards currently supported are the Xilinx ML605 and KC705 FPGA
207 To build in a location other than the default, specify the new location
208 using the BLDROOT variable. Note that this makefile will invoke the
209 FreeRTOS library build makefile automatically, passing on the relevant
212 You can override the default compilation options by specifying the new
217 This compiles the examples and links them with the FreeRTOS library
218 libfreertos.a and the appropriate linker-support package (LSP) for your
219 target platform (you can override the LSP by adding LSP=<lsp> to the
220 xt-make command line). The resulting ELF files can be downloaded and
221 executed on the target. The example binaries appear in the platform
225 need to make certain modifications to the application to plug in and
226 invoke the reentrancy support. This allows each task to use the library
228 handlers to call the C library).
234 to a nonzero value either in xtensa_config.h or on the compiler's command
235 line. Note that the default xtensa_config.h provided with this port does
238 Then, you must also make sure to allocate extra space on the stack for
239 each task that will use the C library reentrant functions. This extra
240 space is to be allocated over and above the actual stack space required
241 by the task itself. The define
245 specifies the amount of extra space to be added on to the stack to allow
246 saving the context for the C library as well as the coprocessors if any.
248 (2000 + XT_STACK_EXTRA_CLIB) bytes for the stack.
254 The header file FreeRTOS.h, which is a part of the core FreeRTOS sources,
255 includes <reent.h> if thread safety for the C libraries is enabled. For
257 To work around this, the makefiles supplied with this port will copy the
258 reent.h header into the build directory during the build process. If you
260 to a location that is included in the list of include paths. This can be
261 the build directory or the directory that contains the Xtensa port source
268 To execute the example application on the simulator:
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).
276 To execute on the simulator using the Xplorer GUI based debugger:
282 instructions in the tools manuals. Be sure the board has been programmed
283 with the correct configuration and is set up to boot from RAM and debug
285 emulator to the serial port on the board with settings as described in
286 the board user manual, and see the output of printf on the terminal.
292 see any behavior specific to the platform (eg. display, printed output,
295 with the gdbio LSP. Refer to Xtensa tools documentation for details.
301 The application must ensure that every task has enough space for its
304 state, if any. Several factors influence the size of the stack required,
305 including the compiler optimization level and the use of the C library.
307 stack space. The tool xt-stack-usage is helpful in determining safe stack
310 Some macros are provided in xtensa_config.h to help determine the stack
311 size for tasks that do and do not use the C library. Use these as the
313 into account your configuration and use of the C library. In particular,
314 the define
318 defines the minimum stack size for any task. Be very careful if you try
320 all kinds of hard-to-debug errors. It is recommended that you enable the
323 WARNING: The newlib printf() function uses a lot of stack space. Be very
324 careful in using it. Optionally you can use the 'libxtutil' library for
327 the Xtensa Tools documentation.
333 Beginning with port version 1.2, the port uses a separate interrupt stack
335 reserve space on its stack to handle interrupts. The size of the interrupt
336 stack is controlled by the parameter "configISR_STACK_SIZE" defined in
343 The following are compiler switches are used by the provided
344 Makefile in building the FreeRTOS library and example application.
345 These can be modified by editing the Makefile or by overriding the
346 CFLAGS variable in the make command line, for example:
360 See the compiler / linker documentation for a full list of switches and
363 Many definitions can be provided at compile-time via the -D option
364 without editing the source code. Here are some of the more useful ones:
366 XT_USE_THREAD_SAFE_CLIB Enable support for the reentrancy to provide
367 thread-safety for the newlib and xclib libraries
370 Note, the follwing defines are unique to the Xtensa port so have names
373 XT_SIMULATOR Set this if building to run on the simulator.
381 Be sure to specify the correct LSP for the
382 board. See the example makefile for usage.
384 XT_CLOCK_FREQ=freq Specifies the target processor's clock
385 frequency in Hz. Used primarily to set the
386 timer that generates the periodic interrupt.
395 this undefined and compute the clock frequency
399 XT_TICK_PER_SEC=n Specifies the frequency of the periodic tick.
404 want to override the default. See xtensa_timer.h .
417 numbers at the same level. This works only for
425 The Xtensa architecture specifies two ABIs that determine how the general
426 purpose registers a0-a15 are used: the standard windowed ABI use with
427 the Xtensa windowed register file architecture, and the optional and
435 In the windowed ABI the registers of the current window are used as follows:
440 Note that complex or large arguments are passed on the
441 stack. Details are in the Xtensa Tools manuals.
443 There are no callee-save registers. The windowed hardware automatically
445 by rotating the register window. Hardware triggers window overflow and
446 underflow exceptions as necessary when registers outside the current
447 window need to be spilled to preallocated space in the stack frame, or
448 restored. Complete details are in the Xtensa manuals. The entire windowed
451 The Call0 ABI does not make use of register windows, relying instead
453 The Call0 ABI is more conventional and uses registers as follows:
458 Note that complex or large arguments are passed on the
459 stack. Details are in the Xtensa Tools manuals.
463 context switch occurs, and other registers are not saved at all (the caller
468 An Xtensa processor has other special registers independent of the ABI,
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
474 are either ignored by the compiler or treated as caller-saved, meaning
476 they must be saved and restored by the caller. Since solicited entry to
477 FreeRTOS is always made by a function call, FreeRTOS assumes the caller
482 As a consequence, the application developer should NOT assume that special
484 If multiple tasks use a register, the caller must save and restore it.
486 The saved context stack frames for context switches that occur as
490 of stack frames. The top of the suspended task's stack is pointed to
501 FreeRTOS run faster you can change the Makefile to enable the desired
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
509 cost of some performance. See the compiler manual for details.
511 The Xtensa architecture port-specific assembly files are coded with no
514 function, and also allows the debugger's stack trace to show the correct
515 function wherever the program counter is within that function. However
517 visible to the debugger, so the following limitations may be observed
520 - Disassembly will show the entire function, but will get out of sync and
525 the ".L" and ".Ln" prefixes from local labels if you want them visible.
526 They can also be made visible by passing the '-L' option to the assembler
527 and linker (see the assembler and linker manuals for details).
534 interrupt handlers installed at the appropriate exception and interrupt
535 vector locations. The Xtensa architecture supports several different
537 many of these are optional, and the vector locations are determined by
539 with specific vector locations.) The handlers provided use conditional
541 the code that is needed.
544 The amount of code space available at each of these locations is
546 code installed at the vector jumps to the corresponding handler,
547 usually in RAM. The exception and interrupt handlers are defined in
551 The handlers provided for low and medium priority interrupts are just
553 See the files xtensa_vectors.S and xtensa_api.h for more details of how
556 than a few which are always handled by the OS).
558 The high priority interrupt handlers provided may be considered templates
559 into which the application adds code to service specific interrupts.
560 The places where application handlers should be inserted are tagged with
561 the comment "USER_EDIT" in xtensa_vectors.S.
567 are handled. During interrupt and exception handling, the processor's
568 interrupt level (PS.INTLEVEL) is used to control the interrupt priority
570 individually by FreeRTOS (the application is free to access the INTENABLE
572 Xtensa HAL services). This approach provides the most deterministic
575 Software prioritization of interrupts at the same priority is controlled
576 by the definition of XT_USE_SWPRI. See above for a description of this
579 The following subsections describe the handling of each class of exception
585 All Xtensa 'general exceptions' come to the user, kernel, or double
586 exception vector. The exception type is identified by the EXCCAUSE
589 to the user vector. Exceptions taken at the other two vectors usually
592 Level 1 interrupts are identified at the beginning of the handler
596 to the coprocessor handler.
600 Having allocated the exception stack frame, the user exception handler
601 saves the current task state and sets up a C environment and enables
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
605 called. If the handler returns, the context is restored and control is
606 returned to the code that caused the exception. The user-defined handler
607 may alter the saved context, or any other system state, that allows the
610 If the cause is a level 1 (low-priority) or medium-priority interrupt,
611 the handler enables all interrupts above that priority level after
612 saving the task context. It then sets up the environment for C code
613 and then calls the handler (found in the handler table) for the
614 interrupt number. If the user has not specified a handler, then the
615 default handler will be called, which will terminate the program.
617 If the interrupt is for the system timer, it calls a special interrupt
618 handler for the system timer tick, which calls _frxt_timer_int then
619 clears its bit from the mask. This interrupt cannot be hooked by the
622 Finally, the handler calls _frxt_int_exit to allow FreeRTOS to perform
623 any scheduling necessary and return either to the interrupted task
626 If software prioritization is enabled, the handler will re-enable all
627 interrupts at the same level that are numerically higher than the current
628 one, before calling the user handler. This allows a higher priority
629 interrupt to pre-empt the lower priority handler.
634 a configuration-specific maximum interrupt level affected by the global
635 'exception mode' bit in the processor status word (PS.EXCM).
636 Interrupt levels above XCHAL_EXCM_LEVEL are of the high-priority class.
637 The Xtensa hardware documentation considers medium priority interrupts
641 Dispatch of medium-priority interrupts is discussed in the section
647 a configuration-specific maximum interrupt level affected by the
648 global 'exception mode' bit in the processor status word (PS.EXCM).
650 and are described here only for the sake of completeness. They must
660 only for the vectors that exist in your Xtensa processor configuration.
663 The vector code jumps to the corresponding first-level interrupt handler,
665 quickly to the interrupted task or lower priority handler.
670 exceptions should not happen. A stub is provided for the vector that
671 triggers the debugger (if connected) or calls _xt_panic to freeze the
676 Alloca exceptions are generated by the 'movsp' instruction, which
677 is used only in the windowed ABI. Its purpose is to allocate some
678 space on top of the stack. Because the window hardware may have
679 spilled some registers to the 16 byte "base save" area below the
680 stack pointer, it is necessary to protect those values. The alloca
688 The windowed ABI specifies that executing this instruction with
690 in the windowed register file to their pre-determined locations
691 on the caller's stack. The handler does exactly that, and skips
692 over the 'syscall' instruction before returning to the caller.
693 If a2 is non-zero, the handler returns a2 == -1 to the caller.
699 task's state is currently in the co-processor. Co-processors are
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
708 This restriction is intended to reduce the overhead of saving and
717 debugger or multiprocessor debug events ("breakin/breakout"). If the
719 the trigger event immediately halts the processor and gives control to
720 the OCD debugger. Otherwise control is transferred to the debug vector.
721 The debug vector handler calls the simulator if running on the ISS,
724 expected, so the debug handler calls _xt_panic to freeze the processor.
728 A double exception is a general exception that happens while the
730 bug in kernel code. The double exception vector handler triggers
731 the debugger (if connected) or calls _xt_panic to freeze the
736 Window overflow and underflow handlers are required for use of the
742 Optional hooks are provided in the user exception and low level
748 them. The interrupt/exception hooks are described in xtensa_rtos.h .
750 It is recommended that the application not make use of these hooks, but
753 and allows arguments to be passed to the handlers. Software prioritization
759 supported in a future release. Make sure that the option XT_USE_OVLY is