Segger embOS-MPU, Manual

Page 1: ...Time Operating System CPU Compiler specifics for Cortex M using IAR Embedded Workbench Document UM01065 Software Version 5 8 2 1 Revision 0 Date February 3 2020 A product of SEGGER Microcontroller GmbH www segger com ...

Page 2: ...ty or fitness for a particular purpose Copyright notice You may not extract portions of this manual or modify the PDF file in any way without the prior written permission of SEGGER The software described in this document is furnished under a license and may only be used or copied in accordance with the terms of such a license 2010 2020 SEGGER Microcontroller GmbH Monheim am Rhein Germany Trademark...

Page 3: ...ctions that are not yet documented Print date February 3 2020 Software Revision Date By Description 5 8 2 1 0 200203 TS New software version 5 8 2 0 0 200106 TS Chapter MPU support updated 5 8 0 0 0 191030 TS Chapter MPU support updated 5 02 0 180629 MC New software version 4 30 0 161202 TS New software version 4 26 1 0 160928 MC New software version 4 26 0 160908 MC First version embOS MPU for Co...

Page 4: ...4 embOS MPU for Cortex M and IAR 2010 2020 SEGGER Microcontroller GmbH ...

Page 5: ...nctions and macros that the product offers It assumes you have a working knowledge of the C language Knowledge of assembly programming is not required Typographic conventions for syntax This manual uses the following typographic conventions Style Used for Body Body text Keyword Text that you enter at the command prompt or that appears on the display that is system functions file or pathnames Param...

Page 6: ...6 embOS MPU for Cortex M and IAR 2010 2020 SEGGER Microcontroller GmbH ...

Page 7: ...system libraries 22 4 2 Thread safe system libraries 22 4 3 Thread Local Storage TLS 24 4 4 ARM erratum 837070 26 5 Stacks 27 5 1 Task stack for Cortex M 28 5 2 System stack for Cortex M 28 5 3 Interrupt stack for Cortex M 28 6 Interrupts 29 6 1 What happens when an interrupt occurs 30 6 2 Defining interrupt handlers in C 30 6 3 Interrupt vector table 30 6 4 Interrupt stack switching 31 6 5 Zero l...

Page 8: ...ctor Floating Point support 45 9 MPU support 46 9 1 Introduction 47 9 2 Supervisor call 47 9 3 Fault exceptions 47 9 4 Alignment 47 9 5 Memory Attributes 48 9 5 1 Modifying memory attributes of default task regions 49 9 6 Cache maintenance 49 9 7 Changing memory attributes for privileged tasks 49 9 8 OS_MPU_ExtendTaskContext 50 9 9 MPU types 50 9 10 Buffer for MPU sanity check 50 9 11 Cortex M XN ...

Page 9: ...apter 1 Using embOS This chapter describes how to start with and use embOS You should follow these steps to become familiar with embOS embOS MPU for Cortex M and IAR 2010 2020 SEGGER Microcontroller GmbH ...

Page 10: ...uld use and modify to write your application So follow the instructions of section First Steps on page 11 You should do this even if you do not intend to use the IDE for your application development to become familiar with embOS If you do not or do not want to work with the IDE you should Copy either all or only the library file that you need to your work directory The advantage is that when switc...

Page 11: ...ur application for example c work Copy the whole folder Start which is part of your embOS distribution into your work directory Clear the read only attribute of all files in the new Start folder Open one sample workspace project in Start BoardSupport DeviceManufacturer CPU with your IDE for example by double clicking it Build the project It should be built without any error or warning messages Aft...

Page 12: ...er GmbH The Embedded Experts END OF HEADER File OS_StartLEDBlink c Purpose embOS sample program running two simple tasks each toggling a LED of the target hardware as configured in BSP c include RTOS h include BSP h static OS_STACKPTR int StackHP 128 StackLP 128 Task stacks static OS_TASK TCBHP TCBLP Task control blocks static void HPTask void while 1 BSP_ToggleLED 0 OS_TASK_Delay 50 static void L...

Page 13: ..._Init is part of the embOS library and written in assembler you can there fore only step into it in disassembly mode It initializes the relevant OS variables OS_InitHW is part of RTOSInit c and therefore part of your application Its primary purpose is to initialize the hardware required to generate the system tick interrupt for embOS Step through it to see what is done OS_Start should be the last ...

Page 14: ...points in the two tasks as shown below As OS_Start is part of the embOS library you can step through it in disassembly mode only Click GO step over OS_Start or step into OS_Start in disassembly mode until you reach the highest priority task embOS MPU for Cortex M and IAR 2010 2020 SEGGER Microcontroller GmbH ...

Page 15: ...therefore start the idle loop which is an endless loop always executed if there is nothing else to do no task is ready no interrupt routine or timer executing You will arrive there when you step into the OS_TASK_Delay function in disassembly mode OS_Idle is part of RTOSInit c You may also set a breakpoint there before step ping over the delay in LPTask embOS MPU for Cortex M and IAR 2010 2020 SEGG...

Page 16: ...asks you will see that they continue execution after the given delay As can be seen by the value of embOS timer variable OS_Global Time shown in the Watch window HPTask continues operation after expiration of the 50 system tick delay embOS MPU for Cortex M and IAR 2010 2020 SEGGER Microcontroller GmbH ...

Page 17: ...Chapter 2 Build your own application This chapter provides all information to set up your own embOS project embOS MPU for Cortex M and IAR 2010 2020 SEGGER Microcontroller GmbH ...

Page 18: ... C standard This is re quired for some embOS internal variables Your main function has to initialize embOS by calling OS_Init and OS_InitHW prior to any other embOS functions that are called 2 3 Change library mode For your application you might want to choose another library For debugging and program development you should use an embOS debug library For your final application you may wish to use ...

Page 19: ...Chapter 3 Libraries This chapter includes CPU specific information such as CPU modes and available libraries embOS MPU for Cortex M and IAR 2010 2020 SEGGER Microcontroller GmbH ...

Page 20: ...d Debug dp Debug profiling Stack check dt Debug profiling Stack check trace dpl Debug profiling Stack check built with low optimization level Errata Specifies whether a workaround for ARM errata was applied _837070 Erratum 837070 applied No workaround applied Example os7m_tl__dp a is the library for a project using Cortex M3 core thumb mode little endian mode with debug and profiling support Note ...

Page 21: ...Chapter 4 CPU and compiler specifics embOS MPU for Cortex M and IAR 2010 2020 SEGGER Microcontroller GmbH ...

Page 22: ... in the project To support thread safe file i o functionality the source module xmtx2 c has to be added The embOS libraries compiled for and with the IAR compiler workbench V6 come with all code required to automatically handle the thread safe system libraries when the source module xmtx c and xmtx2 c from the embOS shipment are included in the project Note that thread safe system library and file...

Page 23: ...dule xmtx3 c has to be added The embOS libraries compiled for and with the IAR compiler workbench V8 come with all code required to automatically handle the thread safe system libraries when the source module xmtx c xmtx2 c and xmtx3 c from the embOS shipment are included in the project Note that thread safe system library file i o and C dynamic lock support is required only when non thread safe f...

Page 24: ...tions asctime localtime gmtime mktime multibyte functions mbrlen mbrtowc mbsrtowc mbtowc wcrtomb wcsrtomb wctomb rand functions rand srand etc functions atexit strtok C exception engine 4 3 1 OS_TASK_SetContextExtensionTLS Description OS_TASK_SetContextExtensionTLS may be called from a task to initialize and use thread local storage This API is not available in embOS library mode OS_LIBMODE_SAFE P...

Page 25: ...c to LPTask OS_TASK_Delay 200 int main void errno 0 errno not specific to any task OS_Init Initialize embOS OS_InitHW Initialize required hardware OS_TASK_CREATE TCBHP HP Task 100 HPTask StackHP OS_TASK_CREATE TCBLP LP Task 50 LPTask StackLP OS_Start Start embOS return 0 embOS MPU for Cortex M and IAR 2010 2020 SEGGER Microcontroller GmbH ...

Page 26: ...the embOS source code instead of the library please add the define USE_ERRATUM_837070 set to 1 to the C and assembler preprocessor settings This workaround sets PRIMASK before writing to BASEPRI and unconditionally clears it af terwards If the previous value of PRIMASK shall be retained after modification of BASEPRI the OS_PRESERVE_PRIMASK definition may be set to 1 in the C and assembler preproce...

Page 27: ...Chapter 5 Stacks This chapter describes how embOS uses the different stacks of the Cortex M CPU embOS MPU for Cortex M and IAR 2010 2020 SEGGER Microcontroller GmbH ...

Page 28: ...tack size required by embOS is about 160 bytes stack check profiling build However since the system stack is also used by the application before the start of multitasking the call to OS_Start and because softwaretimers and C level interrupt handlers also use the system stack the actual stack requirements depend on the application The size of the system stack can be changed by modifying the project...

Page 29: ...mes with a built in vectored interrupt controller which supports up to 240 external interrupt sources The real number of interrupt sources depends on the specific target CPU embOS MPU for Cortex M and IAR 2010 2020 SEGGER Microcontroller GmbH ...

Page 30: ...w Example Simple interrupt routine static void _Systick void OS_INT_EnterNestable Inform embOS that interrupt code is running OS_TICK_Handle May be interrupted OS_INT_LeaveNestable Inform embOS that interrupt handler is left 6 3 Interrupt vector table After reset ARM Cortex M CPUs use an initial interrupt vector table located in ROM at address 0x00 It contains the initial stack pointer as well as ...

Page 31: ...set up interrupt priorities requires different values for the priorities These values depend on the number of preemption levels of the specific chip A description is found in the chapter CMSIS 6 6 1 Interrupt priorities with Cortex M cores The Cortex M supports up to 256 levels of programmable priority with a maximum of 128 levels of preemption Most Cortex M chips have fewer supported levels for e...

Page 32: ...n higher priority levels than the embOS scheduler and the embOS system timer to allow preemption of theses interrupt handlers Interrupt handlers which require fast reaction may run on higher prior ities than 128 but must not call any embOS function zero latency interrupts We recom mend that application interrupts should run on a higher preemption level than the embOS scheduler at least at the seco...

Page 33: ...S that interrupt handler is left 6 7 2 OS_INT_EnterNestable Description Enables nesting Prototype void OS_INT_EnterNestable void Additional information OS_INT_EnterNestable allow nesting OS_INT_EnterNestable may be used as pro logue function when the interrupt handler may be preempted by any other interrupt han dler that runs on a higher interrupt priority An interrupt handler that starts with OS_...

Page 34: ...dr OS_ISR_HANDLER RAMVectorTableBaseAddr Parameters Parameter Description IsVectorTableInRAM Defines whether a RAM vector table is used 0 Vector table in Flash 1 Vector table in RAM NumInterrupts Number of implemented interrupts VectorTableBaseAddr Flash vector table address RAMVectorTableBaseAddr RAM vector table address Additional information This function must be called before OS_ARM_EnableISR ...

Page 35: ...ess of the interrupt handler Additional information Sets an interrupt handler in the RAM vector table Does nothing when the vector table is in Flash OS_ARM_InstallISRHandler copies the vector table from Flash to RAM when it is called for the first time and RAM vector table is enabled Example void OS_InitHW void OS_ARM_ISRInit 1u 82 OS_ISR_HANDLER __Vectors OS_ISR_HANDLER pRAMVectTable OS_ARM_Insta...

Page 36: ...t entry in the vector table Additional information This function just enables the interrupt inside the interrupt controller It does not enable the interrupt of any peripherals This has to be done elsewhere Note that the ISRIndex counts from 0 for the first entry in the vector table The first peripheral index therefore has the ISRIndex 16 because the first peripheral interrupt vector is located aft...

Page 37: ...rom 0 for the first entry in the vector table Additional information This function just disables the interrupt in the interrupt controller It does not disable the interrupt of any peripherals This has to be done elsewhere Note that the ISRIndex counts from 0 for the first entry in the vector table The first peripheral index therefore has the ISRIndex 16 because the first peripheral interrupt vecto...

Page 38: ...e refer to CPU specific manuals about allowed priority levels Note that the ISRIndex counts from 0 for the first entry in the vector table The first peripheral index therefore has the ISRIndex 16 because the first peripheral interrupt vector is located after the 16 generic vectors in the vector table This differs from index values used with CMSIS The priority value is independent of the chip speci...

Page 39: ...ddleware As SEGGER is one of the CMSIS partners embOS for Cortex M is fully CMSIS compliant embOS comes with a generic CMSIS start project which should run on any Cortex M3 CPU All other start projects even those not based on CMSIS are also fully CMSIS compliant and can be used as starting points for CPU specific CMSIS projects How to use the generic project and adding vendor specific files to thi...

Page 40: ...tains the initial reset sequence and contains exception handler and peripheral interrupt handler for all interrupts The handler functions are declared weak so they can be overwritten by the application which implements the application specific handler functionality The sample which comes with embOS only contains the generic exception vectors and handler and has to be replaced by the vendor specifi...

Page 41: ...nd lowest preemption priority ba a call of NVIC_SetPriority The embOS function OS_InitHW has to be called after initialization of embOS during main and is implemented in the RTOSInit c file SysTick_Handler The embOS timer interrupt handler called periodically by the interrupt generated from the SysTick timer The SysTick_Handler is declared weak in the CMSIS startup code and is replaced by the embO...

Page 42: ...ble the symbolic peripheral id numbers from the CPU specific CMSIS device header file may be used with CMSIS Note that using these IDs with the embOS functions will work only when 16 is added to the IDs from the CMSIS device header files 7 6 1 2 Different interrupt priority values Using embOS functions the interrupt priority value ranges from 0 to 255 and is written into the NVIC control registers...

Page 43: ... the first peripheral interrupt vector which is ID number 16 for the embOS functions About these differences please refer to Different peripheral ID num bers on page 42 To enable and disable interrupts in general the embOS functions OS_IN T_IncDI and OS_INT_DecRI or other embOS functions described in the generic embOS manual should be used instead of the intrinsic functions from the CMSIS library ...

Page 44: ...Chapter 8 VFP support embOS MPU for Cortex M and IAR 2010 2020 SEGGER Microcontroller GmbH ...

Page 45: ...e of the embOS libraries with VFP support have to be used in the project The embOS libraries for VFP support require that the VFP is switched on during startup and remains switched on during program execution Using your own startup code ensure that the VFP is switched on during startup When the VFP unit is not switched on the embOS scheduler will fail The debug version of embOS checks whether the ...

Page 46: ...Chapter 9 MPU support This section describes the optional Memory Protection Unit MPU embOS MPU for Cortex M and IAR 2010 2020 SEGGER Microcontroller GmbH ...

Page 47: ... this file is part of your project 9 3 Fault exceptions If a task does an invalid operation an exception occurs With Cortex M this can either be a hard fault a memory manage fault a bus fault or a usage fault These faults are handled in HardFaultHandler S MemManageHandler S BusFaultHandler S and Usage FaultHandler S When working with your own project please ensure that these files are part of your...

Page 48: ...OS_MPU_AddRegion Define Explanation OS_ARM_CACHEMODE_STRONGLY_ORDERED Strongly ordered OS_ARM_CACHEMODE_SHAREABLE_DEVICE Shareable Device OS_ARM_CACHEMODE_WRITE_THROUGH Outer and Inner Write Through no Write Allocate OS_ARM_CACHEMODE_WRITE_BACK_NO_ALLOC Outer and Inner Write Back no Write Allo cate OS_ARM_CACHEMODE_NON_CACHEABLE Outer and Inner Non cacheable OS_ARM_CACHEMODE_WRITE_BACK_ALLOC Outer...

Page 49: ... context switch Since the RTOS itself or another task will run with different cache settings the instruction and data caches need to be cleaned and invalidated Please be aware that cache maintenance operations take some time which also increases the context switch time The actual context switch time depends on many factors e g the number of cache lines that must be written back to the memory Since...

Page 50: ...e MPU register values from the task stack Enable the MPU Enable data and instruction cache only when cache is available 9 9 MPU types embOS MPU supports different MPU implementations with and without cache These defines can be used with OS_MPU_EnableEx OS_MPU_Enable uses OS_ARMv7M_MPU_API Core Define ARMv7 M Cortex M0 M3 M4 M4F OS_ARMv7M_MPU_API ARMv7 M with Cache Cortex M7 M7F OS_ARMv7M_CACHE_MPU...

Page 51: ...ry regions as non executable Unfortunately this setting applies to both privileged and unprivileged states Therefore the XN bit also affects code which gets executed in an interrupt service routine that preempts an unprivileged task or code which is executed when an unprivileged task calls a device driver 9 12 Further information Please refer to the MPU chapter in the generic embOS manual It descr...

Page 52: ...Chapter 10 RTT and SystemView This chapter contains information about SEGGER Real Time Transfer and SEGGER Sys temView embOS MPU for Cortex M and IAR 2010 2020 SEGGER Microcontroller GmbH ...

Page 53: ...ay be used instead to visualize your application s debug output For more information on SEGGER Real Time Transfer refer to segger com jlink rtt 10 1 1 Shipped files related to SEGGER RTT All files related to SEGGER RTT are shipped inside the respective start project s Setup folder File Description SEGGER_RTT c Generic implementation of SEGGER RTT SEGGER_RTT html Generic implementation header file ...

Page 54: ...r to segger com systemview 10 2 1 Shipped files related to SEGGER SystemView All files related to SEGGER SystemView are shipped inside the respective start project s Setup folder File Description Global h Global type definitios required by SEGGER Sys temView SEGGER h Generic types and utility function header SEGGER_SYSVIEW c Generic implementation of SEGGER RTT SEGGER_SYSVIEW h Generic implementat...

Page 55: ...Chapter 11 Technical data This chapter lists technical data of embOS used with Cortex M CPUs embOS MPU for Cortex M and IAR 2010 2020 SEGGER Microcontroller GmbH ...

Page 56: ...OM requirement for the kernel itself is about 1 700 bytes In the table below which is for X Release build you can find minimum RAM size require ments for embOS resources Note that the sizes depend on selected embOS library mode embOS resource RAM bytes Task control block 308 Software timer 20 Mutex 16 Semaphore 8 Mailbox 24 Queue 32 Task event 0 Event object 12 embOS MPU for Cortex M and IAR 2010 ...