CODE TIME TECHNOLOGIES Port - ARM Cortex M3...2.20.51.20100809. This GNU toolset was part of the Raisonance integrated development environment (Ride 7), version 7.30.0169, with patch

Copyright Information

This document is copyright Code Time Technologies Inc. ©2011,2012. All rights reserved. No part of this document may be reproduced or distributed in any form by any means, or stored in a database or retrieval system, without the written permission of

Code Time Technologies Inc.

Code Time Technologies Inc. may have patents or pending applications covering the subject matter in this document. The furnishing of this document does not give you any license to these patents.

CODE TIME TECHNOLOGIES

Abassi RTOS

Porting Document

ARM Cortex-M3 – GCC

Disclaimer

Code Time Technologies Inc. provides this document “AS IS” without warranty of any kind, either expressed or implied, including,

but not limited to, the implied warranties of merchantability and fitness for a particular purpose.

Code Time Technologies Inc. does not warrant that the contents of this document will meet your requirements or that the document is error-free. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the

document. Code Time Technologies Inc. may make improvements and/or changes in the product(s) and/or program(s) described in

the document at any time. This document does not imply a commitment by Code Time Technologies Inc. to supply or make generally available the product(s) described herein.

ARM and Cortex are registered trademarks of ARM Limited. Stellaris and StellarisWare are registered trademarks of Texas Instruments. All other trademarks are the property of their respective owners.

Abassi RTOS Port – ARM Cortex-M3 – GCC 2012.05.21

Rev 1.6 Page 3

Table of Contents

1 INTRODUCTION ................................................................................................................................ 6

1.1 DISTRIBUTION CONTENTS ................................................................................................................. 6 1.2 LIMITATIONS ..................................................................................................................................... 6

2 TARGET SET-UP ................................................................................................................................ 7

2.1 OS_STACK_SIZE SET-UP ............................................................................................................... 8 2.2 INTERRUPT STACK SET-UP ................................................................................................................ 8 2.3 SATURATION BIT SET-UP ................................................................................................................... 8 2.4 LINKER SCRIPT FILE .......................................................................................................................... 9

3 INTERRUPTS .....................................................................................................................................10

3.1 INTERRUPT HANDLING .....................................................................................................................10 3.1.1 Interrupt Table Size .................................................................................................................10 3.1.2 Interrupt Installer ....................................................................................................................11

3.2 INTERRUPT PRIORITY AND ENABLING ..............................................................................................12 3.3 FAST INTERRUPTS .............................................................................................................................12 3.4 NESTED INTERRUPTS ........................................................................................................................14

4 STACK USAGE...................................................................................................................................16

5 SEARCH SET-UP ...............................................................................................................................17

6 CHIP SUPPORT .................................................................................................................................20

7 MEASUREMENTS .............................................................................................................................21

7.1 MEMORY ..........................................................................................................................................21 7.2 LATENCY ..........................................................................................................................................23

8 APPENDIX A: BUILD OPTIONS FOR CODE SIZE .....................................................................26

8.1 CASE 0: MINIMUM BUILD .................................................................................................................26 8.2 CASE 1: + RUNTIME SERVICE CREATION / STATIC MEMORY ..............................................................27 8.3 CASE 2: + MULTIPLE TASKS AT SAME PRIORITY ...............................................................................28 8.4 CASE 3: + PRIORITY CHANGE / PRIORITY INHERITANCE / FCFS / TASK SUSPEND .............................29 8.5 CASE 4: + TIMER & TIMEOUT / TIMER CALL BACK / ROUND ROBIN ..................................................30 8.6 CASE 5: + EVENTS / MAILBOXES ......................................................................................................31 8.7 CASE 6: FULL FEATURE BUILD (NO NAMES) .....................................................................................32 8.8 CASE 7: FULL FEATURE BUILD (NO NAMES / NO RUNTIME CREATION) ..............................................33 8.9 CASE 8: FULL BUILD ADDING THE OPTIONAL TIMER SERVICES .........................................................34


Rev 1.6 Page 4

List of Figures FIGURE 2-1 PROJECT FILE LIST ....................................................................................................................... 7


Rev 1.6 Page 5

List of Tables TABLE 1-1 DISTRIBUTION ............................................................................................................................... 6 TABLE 2-1 OS_STACK_SIZE ....................................................................................................................... 8 TABLE 2-2 OS_ISR_STACK .......................................................................................................................... 8 TABLE 2-3 SATURATION BIT CONFIGURATION ................................................................................................ 9 TABLE 2-4 LINKER SCRIPT .............................................................................................................................. 9 TABLE 3-1 ABASSI_CORTEXM3_GCC.S INTERRUPT TABLE SIZING ................................................................10 TABLE 3-2 OVERLOADING THE INTERRUPT TABLE SIZING FOR ABASSI.C .......................................................10 TABLE 3-3 ATTACHING A FUNCTION TO AN INTERRUPT .................................................................................11 TABLE 3-4 INVALIDATING AN ISR HANDLER ..................................................................................................11 TABLE 3-5 DISTRIBUTION INTERRUPT TABLE CODE ........................................................................................12 TABLE 3-6 LM3S1968 UART 0 / 1 FAST INTERRUPTS ...................................................................................13 TABLE 3-7 FAST INTERRUPT WITH DEDICATED STACK ..................................................................................14 TABLE 3-8 REMOVING INTERRUPT NESTING ...................................................................................................15 TABLE 3-9 PROPAGATING INTERRUPT NESTING ..............................................................................................15 TABLE 4-1 CONTEXT SAVE STACK REQUIREMENTS .......................................................................................16 TABLE 5-1 SEARCH ALGORITHM CYCLE COUNT ............................................................................................18 TABLE 7-1 “C” CODE MEMORY USAGE .........................................................................................................22 TABLE 7-2 ASSEMBLY CODE MEMORY USAGE ..............................................................................................22 TABLE 7-3 MEASUREMENT WITHOUT TASK SWITCH ......................................................................................23 TABLE 7-4 MEASUREMENT WITHOUT BLOCKING ...........................................................................................23 TABLE 7-5 MEASUREMENT WITH TASK SWITCH ............................................................................................24 TABLE 7-6 MEASUREMENT WITH TASK UNBLOCKING ....................................................................................24 TABLE 7-7 LATENCY MEASUREMENTS ..........................................................................................................25 TABLE 8-1: CASE 0 BUILD OPTIONS ................................................................................................................26 TABLE 8-2: CASE 1 BUILD OPTIONS ................................................................................................................27 TABLE 8-3: CASE 2 BUILD OPTIONS ................................................................................................................28 TABLE 8-4: CASE 3 BUILD OPTIONS ................................................................................................................29 TABLE 8-5: CASE 4 BUILD OPTIONS ................................................................................................................30 TABLE 8-6: CASE 5 BUILD OPTIONS ................................................................................................................31 TABLE 8-7: CASE 6 BUILD OPTIONS ................................................................................................................32 TABLE 8-8: CASE 7 BUILD OPTIONS ................................................................................................................33 TABLE 8-9: CASE 8 BUILD OPTIONS ................................................................................................................34


Rev 1.6 Page 6

1 Introduction

This document details the port of the Abassi RTOS to the ARM Cortex-M3 processor. The software suite

used for this specific port is the GNU “C” compiler version 4.5.1, and GNU assembler and linker version

2.20.51.20100809. This GNU toolset was part of the Raisonance integrated development environment

(Ride 7), version 7.30.0169, with patch 7.30.10.0169. This distribution should properly work with most

GNU toolsets for the ARM Cortex-M3.

1.1 Distribution Contents

The set of files supplied with this distribution are listed in Table 1-1 below:

Table 1-1 Distribution

File Name Description

Abassi.h Include file for the RTOS

Abassi.c RTOS “C” source file

Abassi_CORTEXM3_GCC.s RTOS assembly file for the ARM Cortex-M3 to use with

GCC

Abassi.ld Linker script file

Demo_1_EKLM3S1968_GCC.c Demo code that runs on the LM3S1968 evaluation board

Demo_2_EKLM3S1968_GCC.c Demo code that runs on the LM3S1968 evaluation board

AbassiDemo.h Build option settings for the demo code

1.2 Limitations

To optimize the reaction time of the Abassi RTOS components, it was decided to require the processor to

always operate in privileged mode (which is the default mode for Cortex-M microcontrollers) and to

always use the main stack pointer (MSP). The start-up code supplied in the distribution fulfills these

constraints and one must be careful to not change these settings in the application.

The SVCall interrupt (interrupt number -5) is not available as it is reserved for the OS, and the Abassi

RTOS uses it.


Rev 1.6 Page 7

2 Target Set-up

Very little is needed to configure the GCC toolset to use the Abassi RTOS in an application. All there is to

do is to add the files Abassi.c and Abassi_CORTEXM3_GCC.s in the source files of the application

project or makefile, and make sure the three configuration settings in the file Abassi_CORTEXM3_GCC.s

(OS_STACK_SIZE as described in Section 2.1, OS_ISR_STACK as described in Section 2.2, and

OS_HANDLE_PSR_Q as described in Section 2.3) are set according to the needs of the application. As well,

update the include file path in the C/C++ compiler preprocessor options with the location of Abassi.h.

There is no need to include a start-up file, as Abassi_CORTEXM3_GCC.s is the start-up file. A linker script

file is supplied with the distribution, as the start-up code is dependent on the definition of the start and end

of the different memory sections (see Section 2.4).

The following figure shows a project set-up for the Raisonance Ride 7:

Figure 2-1 Project File List

NOTE: The GCC libraries are not multithread-safe without the use of the -pthread command line

option. However, this option is not available for GCC built to generate ARM code. This means

the calls to libraries functions that are non-multithread-safe should be protected by a mutex. The

preferred way is to re-use the G_OSmutex for all non-multithread-safe function, as this will avoid

deadlocks. These functions are typically the dynamic memory management functions, some form

of the printf/scanf functions, file I/O, etc. If the GCC toolset used utilizes the newlib

libraries from Red Hat, you need to attach Abassi mutexes to the x_lock() and x_unlock()

multithread protection functions.


Rev 1.6 Page 8

2.1 OS_STACK_SIZE Set-up

The file Abassi_CORTEXM3_GCC.s contains the start-up code for “C” applications built with the GNU

toolset for the ARM that use the Abassi RTOS. There should be no other start-up file included in the

project.

There is a definition used to set-up the stack size for the function main(), which is the highest priority task

at start-up (known in Abassi as Adam&Eve). This definition is located at around line 30 in the

Abassi_CORTEXM3_GCC.s file, and is shown in the following table:

Table 2-1 OS_STACK_SIZE

.equ OS_STACK_SIZE, 1024 /* A&E (main) stack size in bytes/Set-up to your needs*/

A stack size of 1024 bytes is the value set in the distribution code; modify this value according to the needs

of the application.

The GCC assembler does not support a command line option that would allow the definition of an

assembler symbol. So, contrary to all other ports for the ARM Cortex-M3, modifying the value in the file

Abassi_CORTEXM3_GCC.s is the only possible method to set the stack size.

2.2 Interrupt Stack Set-up

It is possible, and is highly recommended, to use a hybrid stack when nested interrupts occur in an

application. Using this hybrid stack, specially dedicated to the interrupts, removes the need to allocate

extra room to the stack of every task in the application to handle the interrupt nesting. This feature is

controlled by the value set by the definition OS_ISR_STACK, located around line 35 in the file

Abassi_CORTEXM3_GCC.s. To disable this feature, set the definition of OS_ISR_STACK to a value of

zero. To enable it, and specify the hybrid stack size, set the definition of OS_ISR_STACK to the desired

size in bytes (see Section 4 for information on stack sizing). As supplied in the distribution, the hybrid

stack feature is enabled, and a stack size of 1024 bytes is allocated; this is shown in the following table:

Table 2-2 OS_ISR_STACK

.equ OS_ISR_STACK, 1024 /* If using a dedicated stack for the nested ISRs */

/* 0 if not used, otherwise size of stack in bytes */


assembler symbol. So, contrary to all other ports for the ARM Cortex M3, modifying the value in the file

Abassi_CORTEXM3_GCC.s is the only possible method to set the hybrid stack size.

2.3 Saturation Bit Set-up

In the ARM Cortex-M3 status register, there is a sticky bit to indicate if an arithmetic saturation or

overflow has occurred during a DSP instruction; this is the Q flag in the status register (bit #27). By

default, this bit is not kept localized at the task level as it needs extra processing during a context switch to

do so; instead, it is propagated across all tasks. This choice was made because most applications do not

care about the value of this bit.


Rev 1.6 Page 9

If this bit is relevant for an application, even in a single task, then it must be kept locally in each task. To

keep the meaning of the saturation bit localized, the token OS_HANDLE_PSR_Q must be set to a non-zero

value; to disable it, it must be set to a zero value. This is located at around line 30 in the file

Abassi_CORTEXM3_GCC.s. The distribution code disables the localization of the Q bit, setting the token

HANDLE_PSR_Q to zero, as shown in the following table:

Table 2-3 Saturation Bit configuration

.equ OS_HANDLE_PSR_Q, 0 /* If we keep the Q bit (saturation) on per tasks */


assembler symbol. So, contrary to all other ports for the ARM Cortex-M3, modifying the value in the file

Abassi_CORTEXM3_GCC.s is the only possible method to set the control of the saturation bit.

2.4 Linker Script file

The file Abassi.ld, supplied in the distribution, is the GNU ld linker script, which defines the memory

map of the target device. As the start-up code contained in the file Abassi_CortexM3_GCC.s needs to

know the start and end of code sections, there needs to be a one to one relationship in the section naming

between the linker script file and the start-up code. This is why the linker file Abassi.ld must be used

with Abassi_CORTEXM3_GCC.s. As supplied, the memory map applies to the Texas Instruments

LM3S1968 device. The following table shows the two lines in the file, around line 30, that need to be

modified to match your target device.

Table 2-4 Linker Script

MEMORY

{

ROM (rx) : ORIGIN = 0x00000000, LENGTH = 0x00040000

RAM (rwx) : ORIGIN = 0x20000000, LENGTH = 0x00010000

}


Rev 1.6 Page 10

3 Interrupts

The Abassi RTOS needs to be aware when kernel requests are performed inside or outside an interrupt

context. For all interrupt sources (except interrupt numbers less than -1) the Abassi RTOS provides an

interrupt dispatcher, which allows it to be interrupt-aware. This dispatcher achieves two goals. First, the

kernel uses it to know if a request occurs within an interrupt context or not. Second, using this dispatcher

reduces the code size, as all interrupts share the same code for the decision making of entering the kernel or

not at the end of the interrupt.

The distribution makes provision for 241 sources of interrupts, as specified by the token

OS_N_INTERRUPTS in the file Abassi_CortexM3_GCC.s, and the internal default value used by

Abassi.c. Even though the Nested Vectored Interrupt Controller (NVIC) peripheral supports a maximum

of 256 interrupts on the Cortex-M3, the first 15 entries of the interrupt vector table are hard mapped to

dedicated handlers (the interrupt number -1, which is attached to SysTick, is not hard mapped but is

handled by the ISR dispatcher).

3.1 Interrupt Handling

3.1.1 Interrupt Table Size

Most devices do not require all 256 interrupts, as they typically only handle between 64 and 128 sources of

interrupts. The interrupt table can be easily reduced to recover code space, and at the same time recover the

same amount of data memory. There are two files affected: in Abassi_CortexM3_GCC.s, the ARM

interrupt table itself must be shrunk, and the value used in the file Abassi.c, in order to reduce the ISR

dispatcher table look-up. The interrupt table size is defined by the token OS_N_INTERRUPTS in the file

Abassi_CortexM3_GCC.s around line 35. For the value used by Abassi.c, the default value can be

overloaded by defining the token OS_N_INTERRUPTS when compiling Abassi.c . The distribution table

size is set to 241; that is the NVIC maximum of 256 minus the 15 hard mapped exceptions.

For example, the LM3S1968 device from Texas Instruments uses only the first 64 entries of the interrupt

table (48 external interrupts plus the standard 16 exceptions). The 256 entries table can therefore be

reduced to 64. The value to set in Abassi_CortexM3_GCC.s files is 49, which is the total of 64

entries minus 15 (there are 15 hard mapped exceptions). The changes are shown in the following table:

Table 3-1 Abassi_CortexM3_GCC.s interrupt table sizing

…

.equ OS_N_INTERRUPTS, 49 /* # of entries in the int table mapped to ISRdispatch */

…

The overloading of the default interrupt vector look-up table used by Abassi.c is done by using the

compiler command line option –D and specifying the desired setting with the following:

Table 3-2 Overloading the interrupt table sizing for Abassi.c

gcc … -DOS_N_INTERRUPTS=49 …


Rev 1.6 Page 11

3.1.2 Interrupt Installer

Attaching a function to a regular interrupt is quite straightforward. All there is to do is use the RTOS

component OSisrInstall() to specify the interrupt number and the function to be attached to that

interrupt number. For example, Table 3-3 shows the code required to attach the SysTick interrupt to the

RTOS timer tick handler (TIMtick):

Table 3-3 Attaching a Function to an Interrupt

#include “Abassi.h”

…

OSstart();

…

OSisrInstall(-1, &TIMtick);

/* Set-up the count reload and enable SysTick interrupt */

… /* More ISR setup */

OSeint(1); /* Global enable of all interrupts */

NOTE: OSisrInstall() uses the interrupt number, NOT the interrupt vector number.

At start-up, once OSstart() has been called, all OS_N_INTERRUPTS interrupt handler functions are set to

a “do nothing” function, named OSinvalidISR(). If an interrupt function is attached to an interrupt

number using the OSisrInstall() component before calling OSstart(), this attachment will be

removed by OSstart(), so OSisrInstall() should never be used before OSstart() has ran. When an

interrupt handler is removed, it is very important and necessary to first disable the interrupt source, then the

handling function can be set back to OSinvalidISR(). This is shown in Table 3-4:

Table 3-4 Invalidating an ISR handler

#include “Abassi.h”

…

/* Disable the interrupt source */

OSisrInstall(Number, &OSinvalidISR);

…

When an application needs to disable/enable the interrupts, the RTOS supplied functions OSdint() and

OSeint() should be used.

The Nested Vectored Interrupt Controller (NVIC) on the Cortex-M3 does not clear the interrupt generated

by a peripheral; neither does the RTOS. If the generated interrupt is a pulse (as for the SysTick interrupt),

there is nothing to do to clear the interrupt request. However, if the generated interrupt is a level interrupt,

the peripheral generating the interrupt must be informed to remove the interrupt request. This operation

must be performed in the interrupt handler, otherwise the interrupt will be re-entered over and over.


Rev 1.6 Page 12

3.2 Interrupt Priority and Enabling

To properly configure interrupts, the interrupt priority must be set, and the peripheral configured to

generate interrupts and enable them. There is no software provided to perform these operations, as this

functionality is already available. First, ARM has defined the Cortex Microcontroller Software Interface

Standard (CMSIS), which provides everything required for programming the processor peripherals. A

search on the Web for the keyword “core_cm3.h” will deliver many sites where the “C” source code is

available. Second, most chip manufacturers provide code, including files implementing the CMSIS, to

configure the specifics on their devices.

3.3 Fast Interrupts

Fast interrupts are supported on this port. A fast interrupt is an interrupt that never uses any component

from Abassi, and as the name says, is desired to operate as fast as possible. . To set-up a fast interrupt, all

there is to do is to set the address of the interrupt function in the corresponding entry in the interrupt vector

table used by the Cortex-M3 processor. The area of the interrupt vector table to modify is located in the

file Abassi_CORTEXM3_GCC.s around line 70. For example, on a Texas Instruments LM3S1968 device,

UART #0 is attached to interrupt number 5 (interrupt vector number 21) and the UART #1 is attached to

the interrupt number 6 (interrupt vector number 22). The code to modify is located in the macro loop that

initializes the interrupt table that sets the ISR dispatcher as the default interrupt handler. All there is to do

is add checks on the token holding the interrupt number, such that, when the interrupt number value

matches the desired interrupt number, the appropriate address gets inserted in the table instead of the

address of ISRdispatch(). The original macro loop code and modified one are shown in the following

two tables:

Table 3-5 Distribution interrupt table code

.set INT_NMB, -1

.rept OS_N_INTERRUPTS /* Map all external interrupts to ISRdispatch() */

.word ISRdispatch

.set INT_NMB, INT_NMB+1

.endr


Rev 1.6 Page 13

Attaching a fast interrupt handler to the UART #0 and another one to UART #1, assuming the names of the

interrupt functions to attach are respectively UART0_IRQhandler() and UART1_IRQhandler(), is

shown in the following table:

Table 3-6 LM3S1968 UART 0 / 1 Fast Interrupts

.global USART0_IRQhandler

.global USART1_IRQhandler

…

.set INT_NMB, -1

.rept OS_N_INTERRUPTS /* Map all external interrupts to ISRdispatch() */

.if INT_NMB == 5 /* When is interrupt # 5, set UART #0 handler */

.word UART0_IRQhandler

.elseif INT_NMB == 6 /* When is interrupt # 6, set UART #1 handler */

.word UART1_IRQhandler

.else /* All others interrupt # set to ISRdispatch() */

.word ISRdispatch

.endif

.set INT_NMB, INT_NMB+1

.endr

…

It is important to add the .global statement, otherwise there will be an error during the assembly of the

file.

NOTE: If an Abassi component is used inside a fast interrupt, the application will misbehave.


Rev 1.6 Page 14

Even if the hybrid interrupt stack feature is enabled (see Section 2.2), fast interrupts will not use that stack.

This translates into the need to reserve room on all task stacks for the possible nesting of fast interrupts. To

make the fast interrupts also use a hybrid interrupt stack, a prologue and epilogue must be used around the

call to the interrupt handler. The prologue and epilogue code to add is almost identical to what is done in

the regular interrupt dispatcher. Reusing the example of the UART #0 on the LM3S1968 device, this

would look something like:

Table 3-7 Fast Interrupt with Dedicated Stack

…

.if INT_NMB == 5 /* When is interrupt # 5, set UART #0 handler */

.word UART0preHandler

…

…

.section .text.UART0preHandler

.align 2

.code 16

.thumb_func

.type OScontext, %function

EXTERN UART0handler

UART0preHandler:

cpsid I /* Disable ISR to protect against nesting */

mov r0, sp /* Memo current stack pointer */

ldr sp, =UART0_stack /* Stack dedicated to this fast interrupt */

cpsie I /* The stack is now hybrid, nesting safe */

push {r0, lr} /* Preserve original sp & EXC_RETURN */

bl UART0handler /* Enter the interrupt handler */

pop {r0, lr} /* Recover original sp & EXC_RETURN */

mov sp, r0 /* Recover pre-isr stack */

bx lr /* Exit from the interrupt */

…

…

.bss

.space UART0_stack_size /* Room for the fast interrupt stack */

UART0_stack:

…

The same code, with unique labels, must be repeated for each of the fast interrupts.

3.4 Nested Interrupts

The interrupt controller allows nesting of interrupts; this means an interrupt of higher priority will interrupt

the processing of an interrupt of lower priority. Individual interrupt sources can be set to one of 8 levels,

where level 0 is the highest and 7 is the lowest. This implies that the RTOS build option

OS_NESTED_INTS must be set to a non-zero value. The exception to this is an application where all

enabled interrupts handled by the RTOS ISR dispatcher are set, without exception, to the same priority;

then interrupt nesting will not occur. In that case, and only that case, can the build option

OS_NESTED_INTS be set to zero. As this latter case is quite unlikely, the build option OS_NESTED_INTS


Rev 1.6 Page 15

is always overloaded when compiling the RTOS for the ARM Cortex-M3. If the latter condition is

guaranteed, the overloading located after the pre-processor directive can be modified. The code affected in

Abassi.h is shown in Table 3-8 below and the line to modify is the one with #define

OX_NESTED_INTS 1:

Table 3-8 Removing interrupt nesting

#elif defined(__GNUC__) && defined(__ARM_ARCH_7M__)

#define OX_NESTED_INTS 0 /* The ARM has 8 nested (NIVC) interrupt levels */

Or if the build option OS_NESTED_INTS is desired to be propagated:

Table 3-9 Propagating interrupt nesting

#elif defined(__GNUC__) && defined(__ARM_ARCH_7M__)

#define OX_NESTED_INTS OS_NESTED_INTS

The Abassi RTOS kernel never disables interrupts, but there are a few very small regions within the

interrupt dispatcher where interrupts are temporarily disabled due to the nesting (a total of between 10 to 20

instructions).

The kernel is never entered as long as interrupt nesting exists. In all interrupt functions, when a RTOS

component that needs to access some kernel functionality is used, the request(s) is/are put in a queue. Only

once the interrupt nesting is over (i.e. when only a single interrupt context remains) is the kernel entered at

the end of the interrupt, when the queue contains one or more requests, and when the kernel is not already

active. This means that only the interrupt handler function operates in an interrupt context, and only the

time the interrupt function is using the CPU are other interrupts of equal or lower level blocked by the

interrupt controller.


Rev 1.6 Page 16

4 Stack Usage

The RTOS uses the tasks’ stack for two purposes. When a task is blocked or ready to run but not running,

the stack holds the register context that was preserved when the task got blocked or preempted. Also, when

an interrupt occurs, the register context of the running task must be preserved in order for the operations

performed during the interrupt to not corrupt the contents of the registers used by the task when it got

interrupted. For the Cortex-M3, the context save contents of a blocked or pre-empted task is different from

the one used in an interrupt. The following table lists the number of bytes required by each type of context

save operation:

Table 4-1 Context Save Stack Requirements

Description Context save

Blocked/Preempted task context save 40 bytes

Interrupt dispatcher context save (OS_ISR_STACK == 0) 40 bytes

Interrupt dispatcher context save (OS_ISR_STACK != 0) 48 bytes

The numbers for the interrupt dispatcher context save include the 32 bytes the processor pushes on the

stack when it enters the interrupt servicing.

When sizing the stack to allocate to a task, there are three factors to take in account. The first factor is

simply that every task in the application needs at least the area to preserve the task context when it is

preempted or blocked. Second, one must take into account how many levels of nested interrupts exist in

the application. As a worst case, all levels of interrupts may occur and becoming fully nested. So if N

levels of interrupts are used in the application, provision should be made to hold N times the size of an ISR

context save on each task stack, plus any added stack used by all the interrupt handler functions. Finally,

add to all this the stack required by the code implementing the task operation.

NOTE: The ARM Cortex M3 processor needs alignment on 8 bytes for some instructions accessing

memory. When stack memory is allocated, Abassi guarantees the alignment. This said, when

sizing OS_STATIC_STACK or OS_ALLOC_SIZE, make sure to take in account that all allocation

performed through these memory pools are by block size multiple of 8 bytes.

If the hybrid interrupt stack (see Section 2.2) is enabled, then the above description changes: it is only

necessary to reserve room on task stacks for a single interrupt context save (this excludes the interrupt

function handler stack requirements) and not the worst-case nesting. With the hybrid stack enabled, the

second, third, and so on interrupts use the stack dedicated to the interrupts. The hybrid stack is enabled

when the OS_ISR_STACK token in the file Abassi_CORTEXM3_GCC.s is set to a non-zero value (see

Section 2.2).


Rev 1.6 Page 17

5 Search Set-up

The Abassi RTOS build option OS_SEARCH_FAST offers three different algorithms to quickly determine

the next running task upon task blocking. The following table shows the measurements obtained for the

number of CPU cycles required when a task at priority 0 is blocked, and the next running task is at the

specified priority. The number of cycles includes everything, not just the search cycle count. The number

of cycles was measured using the SysTick peripheral, which decrements the counter once every CPU

cycle. The second column is when OS_SEARCH_FAST is set to zero, meaning a simple array traversing.

The third column, labeled Look-up, is when OS_SEARCH_FAST is set to 1, which uses an 8 bit look-up

table. Finally, the last column is when OS_SEARCH_FAST is set to 5 (GCC/Cortex-M3 int are 32 bits, so

2^5), meaning a 32 bit look-up table, further searched through successive approximation. The compiler

optimization for this measurement was set to -O3, meaning maximum optimization for speed. The RTOS

build options were set to the minimum feature set, except for option OS_PRIO_CHANGE set to non-zero.

The presence of this extra feature provokes a small mismatch between the result for a difference of priority

of 1, with OS_SEARCH_FAST set to zero, and the latency results in Section 7.2.

When the build option OS_SEARCH_ALGO is set to a negative value, indicating to use a 2-dimensional

linked list search technique instead of the search array, the number of CPU cycles is constant at 235 cycles.


Rev 1.6 Page 18

Table 5-1 Search Algorithm Cycle Count

Priority Linear search Look-up Approximation

1 225 262 305

2 233 268 305

3 238 274 306

4 243 280 305

5 248 286 306

6 253 292 306

7 258 298 307

8 263 269 305

9 268 279 306

10 273 285 306

11 278 291 307

12 283 297 306

13 288 303 307

14 293 309 307

15 298 315 308

16 303 277 305

17 308 287 306

18 313 293 306

19 318 299 307

20 323 305 306

21 328 311 307

22 333 317 307

23 338 323 308

24 343 283 306

When OS_SEARCH_FAST is set to 0, each extra priority level to traverse requires 5 CPU cycles. When

OS_SEARCH_FAST is set to 1, each extra priority level to traverse requires 6 CPU cycles, except when the

priority level is an exact multiple of 8; then there is a sharp reduction of CPU usage. Overall, setting

OS_SEARCH_FAST to 1 adds around 30 to 40 cycles of CPU for the search, compared to setting

OS_SEARCH_FAST to zero. But when the next ready to run priority is less than 8, 16, 24, … then there is an

extra 17 cycles needed, but without the 8 times 6 cycle accumulation. Finally, the third option, when

OS_SEARCH_FAST is set to 5, delivers a quasi-constant CPU usage, as the algorithm utilizes a successive

approximation search technique (when the delta is 32 or more, the CPU cycle count is 3201, for 64 or

more, it is 3291).


Rev 1.6 Page 19

The first observation, when looking at this table, is that the second option, when OS_SEARCH_FAST is set to

5, is overall for the first 20 some cases less CPU efficient than the first and second option, the ones when

OS_SEARCH_FAST is set to 0 or 1. So, the build option OS_SEARCH_FAST should never be set to 5, if there

are less than 20 priority levels in the applicaton. The other observation is that the first option

(OS_SEARCH_FAST set to 0) delivers better CPU performance than the second option (OS_SEARCH_FAST

set to 1) when the search spans less than 16 priority levels. So, if an application has tasks spanning less

than 16 priority levels, the build option OS_SEARCH_FAST should be set to 0; for all other cases, the build

option OS_SEARCH_FAST should be set to 1.

Setting the build option OS_SEARCH_ALGO to a non-negative value minimizes the time needed to change

the state of a task from blocked to ready to run, and not the time needed to find the next running task upon

blocking/suspending of the running task. If the application needs are such that the critical real-time

requirement is to get the next running task up and running as fast as possible, then set the build option

OS_SEARCH_ALGO to a negative value.


Rev 1.6 Page 20

6 Chip Support

No chip support is provided with the distribution code because, first, ARM has defined the Cortex

Microcontroller Software Interface Standard (CMSIS), which provides everything required for

programming the processor peripherals. A search on the web for the keyword “core_cm3.h” will deliver

many sites where the “C” source code is available. Second, most chip manufacturers provide code,

including files implementing the CMSIS, to configure the specifics on their devices.


Rev 1.6 Page 21

7 Measurements

This section gives an overview of the memory requirements and the CPU latency encountered when the

RTOS is used on the ARM Cortex-M3 and compiled with the GCC tool set. The CPU cycles are exactly

the CPU clock cycles, as the processor typically executes one instruction at every clock transition.

7.1 Memory

The memory numbers are supplied for the two limit cases of build options (and some in-between): the

smallest footprint is the RTOS built with only the minimal feature set, and the other with almost all the

features. For both cases, names are not part of the build. This feature was removed from the metrics

because it is highly probable that shipping products utilizing this RTOS will not include the naming of

descriptors, as its usefulness is mainly limited to debugging and making the opening/creation of

components run-time safe.

The code size numbers are expressed with “less than” as they have been rounded up to multiples of 25 for

the “C” code. These numbers were obtained using the beta release of the RTOS and may change. One

should interpret these numbers as the “very likely” numbers for the released version of the RTOS.

The code memory required by the RTOS includes the “C” code and assembly language code used by the

RTOS. The code optimization setting of the compiler that was used for the memory measurements is -Os,

which optimizes the size of the code generated. The debugging option was turned off as the debugging

sometimes restricts the optimizer.


Rev 1.6 Page 22

Table 7-1 “C” Code Memory Usage

Description Code Size

Minimal Build < 725 bytes

+ Runtime service creation / static memory < 950 bytes

+ Multiple tasks at same priority < 1050 bytes

+ Runtime priority change

+ Mutex priority inheritance

+ FCFS

+ Task suspension

< 1500 bytes

+ Timer & timeout

+ Timer call back

+ Round robin

< 2150 bytes

+ Events

+ Mailbox

< 3050 bytes

Full Feature Build (no names) < 3725 bytes

Full Feature Build (no names / no runtime creation) < 3300 bytes

Full Feature Build (no names / no runtime creation)

+ Timer services module

< 3200 bytes1

Table 7-2 Assembly Code Memory Usage

Description Size

Assembly code size 188 bytes

Vector table (per interrupt handler entry) +4 bytes

Hybrid Stack Enabled +12 bytes

Saturation Bit Enabled +24 bytes

“C” start-up (replaces standard start-up file) +52 bytes

There are two aspects when describing the data memory usage by the RTOS. First, the RTOS needs its

own data memory to operate, and second, most of the services offered by the RTOS require data memory

for each instance of the service. As the build options affect either the kernel memory needs or the service

descriptors (or both), an interactive calculator has been made available on Code Time Technologies

website.

1 This number should be largest than the previous one. But some reason, it looks like GCC does a better

code shrinkage when the time service module is present in the kernel than when not.


Rev 1.6 Page 23

7.2 Latency

Latency of operations has been measured on a Texas Instrument Stellaris EKK-LM3S1968 Evaluation

board populated with a 50 MHz LM3S1968 device. All measurements have been performed on the real

platform. This means the interrupt latency measurements had to be instrumented to read the SysTick

counter value. This instrumentation can add up to 5 or 6 cycles to the measurements. The code

optimization setting that was used for the latency measurements is -O3, which optimizes the code

generated for the best speed. The debugging option was turned off as the debugging sometimes restricts the

optimizer.

There are 5 types of latencies that are measured, and these 5 measurements are expected to give a very

good overview of the real-time performance of the Abassi RTOS for this port. For all measurements, three

tasks were involved:

1. Adam & Eve set to a priority value of 0;

2. A low priority task set to a priority value of 1;

3. The Idle task set to a priority value of 20.

The sets of 5 measurements are performed on a semaphore, on the event flags of a task, and finally on a

mailbox. The first 2 latency measurements use the component in a manner where there is no task

switching. The third measurements involve a high priority task getting blocked by the component. The

fourth measurements are about the opposite: a low priority task getting pre-empted because the component

unblocks a high priority task. Finally, the reaction to unblocking a task, which becomes the running task,

through an interrupt is provided.

The first set of measurements counts the number of CPU cycles elapsed starting right before the component

is used until it is back from the component. For these measurement there is no task switching. This means:

Table 7-3 Measurement without Task Switch

Start CPU cycle count

SEMpost(…); or EVTset(…); or MBXput();

Stop CPU cycle count

The second set of measurements, as for the first set, counts the number of CPU cycles elapsed starting right

before the component is used until it is back from the component. For these measurement there is no task

switching. This means:

Table 7-4 Measurement without Blocking


SEMwait(…, -1); or EVTwait(…, -1); or MBXget(…, -1);


The third set of measurements counts the number of CPU cycles elapsed starting right before the

component triggers the unblocking of a higher priority task until the latter is back from the component used

that blocked the task. This means:


Rev 1.6 Page 24

Table 7-5 Measurement with Task Switch

main()

{

…



…

}

TaskPrio1()

{

…


SEMpost(…); or EVTset(…); or MBXput(…);

…

}

The forth set of measurements counts the number of CPU cycles elapsed starting right before the

component blocks of a high priority task until the next ready to run task is back from the component it was

blocked on; the blocking was provoked by the unblocking of a higher priority task. This means:

Table 7-6 Measurement with Task unblocking

main()

{

…



…

}

TaskPrio1()

{

…

SEMpost(…); or EVTset(…); or MBXput(…);


…

}

The fifth set of measurements counts the number of CPU cycles elapsed from the beginning of an interrupt

using the component, until the task that was blocked becomes the running task and is back from the

component used that blocked the task. The interrupt latency measurement includes everything involved in

the interrupt operation, even the cycles the processor needs to push the interrupt context before entering the

interrupt code. The interrupt function, attached with OSisrInstall(), is simply a two line function that

uses the appropriate RTOS component followed by a return.

Table 7-7 lists the results obtained, where the cycle count is measured using the SysTick peripheral on the

Cortex-M3. This timer decrements its counter by 1 at every CPU cycle. As was the case for the memory

measurements, these numbers were obtained with a beta release of the RTOS. It is possible the released

version of the RTOS may have slightly different numbers.

The interrupt latency is the number of cycles elapsed when the interrupt trigger occurred and the ISR

function handler is entered. This includes the number of cycles used by the processor to set-up the interrupt

stack and branch to the address specified in the interrupt vector table. But for this measurement, the

LM3S1968 Timer 1 is used to trigger the interrupt and measure the elapsed time. The latency measurement

includes the cycles required to acknowledge the interrupt.


Rev 1.6 Page 25

The interrupt overhead without entering the kernel is the measurement of the number of CPU cycles used

between the entry point in the interrupt vector and the return from interrupt, with a “do nothing” function in

the OSisrInstall(). The interrupt overhead when entering the kernel is calculated using the results

from the third and fifth tests. Finally, the OS context switch is the measurement of the number of CPU

cycles it takes to perform a task switch, without involving the wrap-around code of the synchronization

component.

The hybrid interrupt stack feature was not enabled, neither was the saturation bit, in any of these tests.

In the following table, the latency numbers between parentheses are the measurements when the build

option OS_SEARCH_ALGO is set to a negative value. The regular number is the latency measurements when

the build option OS_SEARCH_ALGO is set to 0.

Table 7-7 Latency Measurements

Description Minimal Features Full Features

Semaphore posting no task switch 124 (142) 196 (213)

Semaphore waiting no blocking 135 (150) 212 (227)

Semaphore posting with task switch 191 (229) 321 (350)

Semaphore waiting with blocking 209 (225) 352 (359)

Semaphore posting in ISR with task switch 384 (427) 527 (555)

Event setting no task switch n/a 194 (209)

Event getting no blocking n/a 225 (240)

Event setting with task switch n/a 337 (364)

Event getting with blocking n/a 373 (378)

Event setting in ISR with task switch n/a 546 (572)

Mailbox writing no task switch n/a 245 (260)

Mailbox reading no blocking n/a 252 (267)

Mailbox writing with task switch n/a 366 (394)

Mailbox reading with blocking n/a 411 (418)

Mailbox writing in ISR with task switch n/a 586 (614)

Interrupt Latency 29 29

Interrupt overhead entering the kernel 193 (198) 206 (205)

Interrupt overhead NOT entering the kernel 50 50

Context switch 36 38


Rev 1.6 Page 26

8 Appendix A: Build Options for Code Size

8.1 Case 0: Minimum build

Table 8-1: Case 0 build options

#define OS_ALLOC_SIZE 0 /* When !=0, RTOS supplied OSalloc */

#define OS_COOPERATIVE 0 /* When 0: pre-emptive, when non-zero: cooperative */

#define OS_EVENTS 0 /* If event flags are supported */

#define OS_FCFS 0 /* Allow the use of 1st come 1st serve semaphore */

#define OS_IDLE_STACK 0 /* If IdleTask supplied & if so, stack size */

#define OS_LOGGING_TYPE 0 /* Type of logging to use */

#define OS_MAILBOX 0 /* If mailboxes are used */

#define OS_MAX_PEND_RQST 2 /* Maximum number of requests in ISRs */

#define OS_MTX_DEADLOCK 0 /* This test validates this */

#define OS_MTX_INVERSION 0 /* To enable protection against priority inversion */

#define OS_NAMES 0 /* != 0 when named Tasks / Semaphores / Mailboxes */

#define OS_NESTED_INTS 0 /* If operating with nested interrupts */

#define OS_PRIO_CHANGE 0 /* If a task priority can be changed at run time */

#define OS_PRIO_MIN 2 /* Max priority, Idle = OS_PRIO_MIN, AdameEve = 0 */

#define OS_PRIO_SAME 0 /* Support multiple tasks with the same priority */

#define OS_ROUND_ROBIN 0 /* Use round-robin, value specifies period in uS */

#define OS_RUNTIME 0 /* If create Task / Semaphore / Mailbox at run time */

#define OS_SEARCH_ALGO 0 /* If using a fast search */

#define OS_STARVE_PRIO 0 /* Priority threshold for starving protection */

#define OS_STARVE_RUN_MAX 0 /* Maximum Timer Tick for starving protection */

#define OS_STARVE_WAIT_MAX 0 /* Maximum time on hold for starving protection */

#define OS_STATIC_BUF_MBX 0 /* when OS_STATIC_MBOX != 0, # of buffer element */

#define OS_STATIC_MBX 0 /* If !=0 how many mailboxes */

#define OS_STATIC_NAME 0 /* If named mailboxes/semaphore/task, size in char */

#define OS_STATIC_SEM 0 /* If !=0 how many semaphores and mutexes */

#define OS_STATIC_STACK 0 /* if !=0 number of bytes for all stacks */

#define OS_STATIC_TASK 0 /* If !=0 how many tasks (excluding A&E and Idle) */

#define OS_TASK_SUSPEND 0 /* If a task can suspend another one */

#define OS_TIMEOUT 0 /* !=0 enables blocking timeout */

#define OS_TIMER_CB 0 /* !=0 gives the timer callback period */

#define OS_TIMER_SRV 0 /* !=0 includes the timer services module */

#define OS_TIMER_US 0 /* !=0 enables timer & specifies the period in uS */

#define OS_USE_TASK_ARG 0 /* If tasks have arguments */


Rev 1.6 Page 27

8.2 Case 1: + Runtime service creation / static memory




































Rev 1.6 Page 28

8.3 Case 2: + Multiple tasks at same priority




































Rev 1.6 Page 29

8.4 Case 3: + Priority change / Priority inheritance / FCFS / Task suspend




































Rev 1.6 Page 30

8.5 Case 4: + Timer & timeout / Timer call back / Round robin

















#define OS_ROUND_ROBIN 100000/* Use round-robin, value specifies period in uS */



















Rev 1.6 Page 31

8.6 Case 5: + Events / Mailboxes

















#define OS_ROUND_ROBIN 100000/* Use round-robin, value specifies period in uS */



















Rev 1.6 Page 32

8.7 Case 6: Full feature Build (no names)

















#define OS_ROUND_ROBIN -100000 /* Use round-robin, value specifies period in uS */



#define OS_STARVE_PRIO -3 /* Priority threshold for starving protection */

#define OS_STARVE_RUN_MAX -10 /* Maximum Timer Tick for starving protection */

#define OS_STARVE_WAIT_MAX -100 /* Maximum time on hold for starving protection */














Rev 1.6 Page 33

8.8 Case 7: Full feature Build (no names / no runtime creation)




































Rev 1.6 Page 34

8.9 Case 8: Full build adding the optional timer services



































Documents

CODE TIME TECHNOLOGIES Port - ARM Cortex M3...2.20.51.20100809. This GNU toolset was part of the Raisonance integrated development environment (Ride 7), version 7.30.0169, with patch