UM01056 embOS MSP430 TICC · Chapters "Libraries" and "CPU and compiler specifics" intro-duced. 4.00 0 140617 SC First Version. 4 ... JTAG emulator for ARM cores USB driven JTAG interface

A product of SEGGER Microcontroller GmbH & Co. KG

embOS

Document: UM01056Software version 4.26

Revision: 0Date: October 18, 2016

CPU & Compilerspecifics for Texas Instru-

ments MSP430 CPUs using TI Code Composer

for MSP430

Real-TimeOperating System

www.segger.com

2

Disclaimer

Specifications written in this document are believed to be accurate, but are not guar-anteed to be entirely free of error. The information in this manual is subject tochange for functional or performance improvements without notice. Please make sureyour manual is the latest edition. While the information herein is assumed to beaccurate, SEGGER Microcontroller GmbH & Co. KG (SEGGER) assumes no responsibil-ity for any errors or omissions. SEGGER makes and you receive no warranties or con-ditions, express, implied, statutory or in any communication with you. SEGGERspecifically disclaims any implied warranty of merchantability or fitness for a particu-lar purpose.

Copyright notice

You may not extract portions of this manual or modify the PDF file in any way withoutthe prior written permission of SEGGER. The software described in this document isfurnished under a license and may only be used or copied in accordance with theterms of such a license.

© 2010 - 2016 SEGGER Microcontroller GmbH & Co. KG, Hilden / Germany

Trademarks

Names mentioned in this manual may be trademarks of their respective companies.

Brand and product names are trademarks or registered trademarks of their respec-tive holders.

Contact address

SEGGER Microcontroller GmbH & Co. KG

In den Weiden 11D-40721 Hilden

Germany

Tel.+49 2103-2878-0Fax.+49 2103-2878-28E-mail: [email protected]: http://www.segger.com

embOS for MSP430 CPUs and TI Code Composer Studio © 2010 - 2016 SEGGER Microcontroller GmbH & Co. KG

3

Manual versions

This manual describes the current software version. If any error occurs, inform usand we will try to assist you as soon as possible.Contact us for further information on topics or routines not yet specified.

Print date: October 18, 2016

Software Revision Date By Description

4.26 0 161018 RHChapters "Libraries" and "CPU and compiler specifics" intro-duced.

4.00 0 140617 SC First Version


4


5

About this document

Assumptions

This document assumes that you already have a solid knowledge of the following:

� The software tools used for building your application (assembler, linker, C com-piler)

� The C programming language� The target processor� DOS command line

If you feel that your knowledge of C is not sufficient, we recommend The C Program-ming Language by Kernighan and Richie (ISBN 0-13-1103628), which describes thestandard in C-programming and, in newer editions, also covers the ANSI C standard.

How to use this manualThis manual explains all the functions and macros that the product offers. It assumesyou have a working knowledge of the C language. Knowledge of assembly program-ming is not required.

Typographic conventions for syntax

This manual uses the following typographic conventions:

Style Used for

Body Body text.

KeywordText that you enter at the command-prompt or that appears on the display (that is system functions, file- or pathnames).

Parameter Parameters in API functions.

Sample Sample code in program examples.

Sample comment Comments in programm examples.

Reference Reference to chapters, sections, tables and figures or other docu-ments.

GUIElement Buttons, dialog boxes, menu names, menu commands.

Emphasis Very important sections.

Table 2.1: Typographic conventions


6

EMBEDDED SOFTWARE(Middleware)

emWinGraphics software and GUIemWin is designed to provide an effi-cient, processor- and display control-ler-independent graphical user interface (GUI) for any application that operates with a graphical display.

embOSReal Time Operating SystemembOS is an RTOS designed to offer the benefits of a complete multitasking system for hard real time applications with minimal resources.

embOS/IPTCP/IP stackembOS/IP a high-performance TCP/IP stack that has been optimized for speed, versatility and a small memory footprint.

emFileFile systememFile is an embedded file system with FAT12, FAT16 and FAT32 support. Var-ious Device drivers, e.g. for NAND and NOR flashes, SD/MMC and Compact-Flash cards, are available.

USB-StackUSB device/host stackA USB stack designed to work on any embedded system with a USB control-ler. Bulk communication and most stan-dard device classes are supported.

SEGGER TOOLS

Flasher Flash programmerFlash Programming tool primarily for micro con-trollers.

J-LinkJTAG emulator for ARM coresUSB driven JTAG interface for ARM cores.

J-TraceJTAG emulator with traceUSB driven JTAG interface for ARM cores with Trace memory. supporting the ARM ETM (Embed-ded Trace Macrocell).

J-Link / J-Trace Related SoftwareAdd-on software to be used with SEGGER�s indus-try standard JTAG emulator, this includes flash programming software and flash breakpoints.

SEGGER Microcontroller GmbH & Co. KG developsand distributes software development tools and ANSI Csoftware components (middleware) for embedded sys-tems in several industries such as telecom, medicaltechnology, consumer electronics, automotive industryand industrial automation.

SEGGER�s intention is to cut software development timefor embedded applications by offering compact flexible and easy to use middleware,allowing developers to concentrate on their application.

Our most popular products are emWin, a universal graphic software package for embed-ded applications, and embOS, a small yet efficient real-time kernel. emWin, writtenentirely in ANSI C, can easily be used on any CPU and most any display. It is comple-mented by the available PC tools: Bitmap Converter, Font Converter, Simulator andViewer. embOS supports most 8/16/32-bit CPUs. Its small memory footprint makes itsuitable for single-chip applications.

Apart from its main focus on software tools, SEGGER develops and produces programmingtools for flash micro controllers, as well as J-Link, a JTAG emulator to assist in develop-ment, debugging and production, which has rapidly become the industry standard fordebug access to ARM cores.

Corporate Office:http://www.segger.com

United States Office:http://www.segger-us.com


7

Table of Contents

1 Using embOS...................................................................................................................9

1.1 Installation .............................................................................................101.2 First steps ..............................................................................................111.3 The example application OS_StartLEDBlink.c ...............................................121.4 Stepping through the sample application ....................................................13

2 Build your own application .............................................................................................17

2.1 Introduction............................................................................................182.2 Required files for an embOS......................................................................182.3 Change library mode................................................................................182.4 Select another CPU ..................................................................................18

3 Libraries .........................................................................................................................21

3.1 CPU modes .............................................................................................223.2 Naming conventions for prebuilt libraries ....................................................22

4 CPU and Compiler specifics ..........................................................................................23

4.1 Standard system libraries .........................................................................244.2 MSP430 clock specifics .............................................................................24

5 Stacks ............................................................................................................................25

5.1 Task stack ..............................................................................................265.2 System stack ..........................................................................................265.3 Interrupt stack ........................................................................................265.4 Stack specifies of the MSP430/MSP430X family............................................26

6 Interrupts........................................................................................................................27

6.1 What happens when an interrupt occurs?....................................................286.2 Defining interrupt handlers in C .................................................................286.3 Interrupt-stack........................................................................................28

7 Technical data................................................................................................................29

7.1 Memory requirements ..............................................................................30


8


9

Chapter 1

Using embOS

This chapter describes how to start with and use embOS for MSP430 cores and the TICode Composer for MSP430. You should follow these steps to become familiar withembOS.


10 CHAPTER 1 Using embOS

1.1 InstallationembOS is shipped as a zip-file in electronic form.

To install it, proceed as follows:

Extract the zip-file to any folder of your choice, preserving the directory structure ofthis file. Keep all files in their respective sub directories. Make sure the files are notread only after copying.act it to any folder of your choice, preserving the directorystructure of the zip-file.

Assuming that you are using TI Code Composer Studio to develop your application,no further installation steps are required. You will find prepared sample startprojects, which you should use and modify to write your application. So follow theinstructions of section �First steps� on page 11.

You should do this even if you do not intend to use the TI Code Composer Studio foryour 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 onlythe library-file that you need to your work-directory. The advantage is that whenswitching to an updated version of embOS later in a project, you do not affect olderprojects that use embOS, too. embOS does in no way rely on an IDE, it may be usedwithout the IDE using batch files or a make utility without any problem.


11

1.2 First stepsAfter installation of embOS you can create your first multitasking application. Youhave received several ready to go sample start workspaces and projects and everyother files needed in the subfolder Start. It is a good idea to use one of them as astarting point for all of your applications. The subfolder BoardSupport contains theworkspaces and projects which are located in manufacturer- and CPU-specific sub-folders.

To start with, you may use any project from BoardSupport subfolder:

To get your new application running, you should proceed as follows:

� Create a work directory for your 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\<DeviceManufactor>\<CPU> with your IDE (for example, by double clicking it).

� Build the project. It should be built without any error or warning messages.

After after building the start project, your the screen should look like this:

For additional information you should open the ReadMe.txt file which is part of everyspecific project. The ReadMe file describes the different configurations of the projectand gives additional information about specific hardware settings of the supportedeval boards, if required.



1.3 The example application OS_StartLEDBlink.cThe following is a printout of the example application OS_StartLEDBlink.c. It is agood starting point for your application. (Note that the file actually shipped with yourport of embOS may look slightly different from this one.)

What happens is easy to see:

After initialization of embOS; two tasks are created and started.The two tasks are activated and execute until they run into the delay, then suspendfor the specified time and continue execution.

/********************************************************************** SEGGER Microcontroller GmbH & Co. KG ** The Embedded Experts ***********************************************************************File : OS_StartLEDBlink.cPurpose : embOS sample program running two simple tasks, each toggling a LED of the target hardware (as configured in BSP.c).--------- END-OF-HEADER ----------------------------------------------*/

#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_Delay (50); }}

static void LPTask(void) { while (1) { BSP_ToggleLED(1); OS_Delay (200); }}

/********************************************************************* * * main()*/int main(void) { OS_IncDI(); /* Initially disable interrupts */ OS_InitKern(); /* Initialize OS */ OS_InitHW(); /* Initialize Hardware for OS */ BSP_Init(); /* Initialize LED ports */ /* You need to create at least one task before calling OS_Start() */ OS_CREATETASK(&TCBHP, "HP Task", HPTask, 100, StackHP); OS_CREATETASK(&TCBLP, "LP Task", LPTask, 50, StackLP); OS_Start(); /* Start multitasking */ return 0;}

/****** End Of File *************************************************/


13

1.4 Stepping through the sample applicationWhen starting the debugger, you will see the main() function (see example screen-shot below). The main() function appears as long as project option Run to main isselected, which it is enabled by default. Now you can step through the program.OS_IncDI() initially disables interrupts.OS_InitKern() 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.Because of the previous call of OS_IncDI(), interrupts are not enabled during execu-tion of OS_InitKern().OS_InitHW() is part of RTOSInit_*.c and therefore part of your application. Its pri-mary purpose is to initialize the hardware required to generate the system tick inter-rupt for embOS. Step through it to see what is done.

OS_Start() should be the last line in main, because it starts multitasking and doesnot return.

Before you step into OS_Start(), you should set two breakpoints in the two tasks asshown below.



When you step over OS_Start(), the next line executed is already in the highest pri-ority task created. (you may also step into OS_Start(), then stepping through thetask switching process in disassembly mode). In our small start program, HPTask()is the highest priority task and is therefore active.

If you continue stepping, you will arrive in the task that has lower priority:

Continue to step through the program, there is no other task ready for execution.embOS will therefore start the idle-loop, which is an endless loop always executed ifthere is nothing else to do (no task is ready, no interrupt routine or timer executing).


15

You will arrive there when you step into the OS_Delay() function in disassemblymode. OS_Idle() is part of RTOSInit*.c. You may also set a breakpoint there beforeyou step over the delay in LPTask.

f you set a breakpoint in one or both of our tasks, you will see that they continueexecution after the given delay.

As can be seen by the value of embOS timer variable OS_Global.Time, shown in theWatch window, HPTask continues operation after expiration of the 50 system tickdelay.




17

Chapter 2

Build your own application

This chapter provides all information to setup your own embOS project.


18 CHAPTER 2 Build your own application

2.1 IntroductionTo build your own application, you should always start with one of the supplied sam-ple start project. Therefore, select an embOS workspace as described in chapter Firststeps and modify the project to fit your needs. Using an embOS start project asstarting point has the advantage that all necessary files are included and all settingsfor the project are already done.

2.2 Required files for an embOSTo build an application using embOS, the following files from your embOS distributionare required and have to be included in your project:

� RTOS.h from subfolder Inc\.This header file declares all embOS API functions and data types and has to beincluded in any source file using embOS functions.

� RTOSInit_*.c from one target specific BoardSupport\<Manufac-turer>\<MCU>\ subfolder.It contains hardware-dependent initialization code for embOS. It initializes thesystem timer interrupt and optional communication for embOSView via UART orJTAG.

� One embOS library from the subfolder Lib\.� OS_Error.c from one target specific subfolder BoardSupport\<Manufac-

turer>\<MCU>\.The error handler is used if any debug library is used in your project.

� Additional CPU and compiler specific files may be required according to CPU.

When you decide to write your own startup code or use a __low_level_init() func-tion, ensure that non-initialized variables are initialized with zero, according to Cstandard. This is required for some embOS internal variables.Also ensure, that main() is called with the CPU running in supervisor or systemmode.Your main() function has to initialize embOS by a call of OS_InitKern() andOS_InitHW() prior any other embOS functions are called.You should then modify or replace the OS_StartLEDBlink.c source file in the sub-folder Application\.

2.3 Change library modeFor your application you might want to choose another library. For debugging andprogram development you should use an embOS-debug library. For your final appli-cation you may wish to use an embOS-release library or a stack check library.

Therefore you have to select or replace the embOS library in your project or target:

� If your selected library is already available in your project, just select the appro-priate configuration.

� To add a library, you may add the library to the existing Lib group. Exclude allother libraries from your build, delete unused libraries or remove them from theconfiguration.

� Check and set the appropriate OS_LIBMODE_* define as preprocessor optionand/ or modify the OS_Config.h file accordingly.

2.4 Select another CPUembOS contains CPU-specific code for various MSP430 CPUs. Manufacturer- and CPUspecific sample start workspaces and projects are located in the subfolders of theBoardSupport folder. To select a CPU which is already supported, just select theappropriate project from a CPU specific folder.If your MSP430 CPU is currently not supported, examine all RTOSInit.c files in the


19

CPU-specific subfolders and select one which almost fits your CPU. You may have tomodify OS_InitHW(), OS_COM_Init(), the interrupt service routines for embOS sys-tem timer tick and communication to embOSView and the low level initialization.


20 CHAPTER 2 Build your own application


21

Chapter 3

Libraries

This chapter describes the available embOS libraries.


22 CHAPTER 3 Libraries

3.1 CPU modesembOS for MSP430 CPUs supports all memory and code model combinations that TIsCode Composer Studio Compiler supports.

3.2 Naming conventions for prebuilt librariesembOS for MSP430 and TICC compiler comes with 21 different libraries, one for eachCPU variant/ data model / library mode combination. The library names follow thenaming convention for the system libraries from TICC compiler.

The libraries are named as follows:

<CPU><DataModel>_<LibMode>.lib

Example

430xl_SP.r43 is the embOS library for an MSP430X CPU with large memory modeland Stack check and Profiling functionality. It is located in the Start\Lib\ subdirec-tory.

Parameter Meaning Values

CPU Specifies the CPU variant 430: MSP430430x: MSP430x extended addr.

DataModelSelected data model, only for MSP430x CPUs

: small data modell: large data model

LibMode Specifies the library mode xr: Extreme Releaser: Releases: Stack checksp: Stack check + profilingd: Debugdp: Debug + profilingdt: Debug + profiling + trace


23

Chapter 4

CPU and Compiler specifics


24 CHAPTER 4 CPU and Compiler specifics

4.1 Standard system librariesembOS for MSP430 and TICC may be used with TICC standard libraries.

4.2 MSP430 clock specificsMSP 430 CPUs offer various options for CPU and peripheral clock generation. You mayhave to modify the embOS timer initialization function OS_InitHW() in RtosInit_*.cto fit your application.The sample OS_InitHW() routine in RTOSInit_XMS430F5438.c uses the internal RCoscillator as clock source selects this clock as source for embOS timer.

4.2.1 embOS timer clock sourceThe embOS timer may be driven from different clock sources. Per default, MCLK isused as clock source for timer.OS_IntHW() initializes the RC oscillator and DCO on MSP430 devices.

Using the RC oscillator:

Usage of RC oscillator and DCO has the advantage that no additional hardware isrequired. The disadvantage is, that exact frequency is nor guaranteed neither pre-cise.The frequency of MCLK has to be examined and OS_FSYS has to be adjusted to fityour application.

Using an external crystal:

Usage of an external Main clock generator crystal has the advantage, that frequencyis stable and precise. OS_InitHW() has to be modified to initialize the crystal oscilla-tor. Check OS_FSYS and set a value that corresponds to your crystal frequency.

4.2.2 Clock for UARTWhen using embOSView to analyze the target system, a USART has to be initializedfor serial communication. Per default, communication to embOSView is enabled anduses USART0.Different clock sources for baudrate generation may be used. For MSP430 devices,OS_COM_Init() initializes the auxiliary clock oscillator as clock source for USART.This ensures accurate baudrate up to 9600 baud.For MSP430x devices, the frequency of the internal oscillator is high enough to allowhigh baud rates using the fractional baud rate generator.

Using ACLK for UART:

ACLK as source for UART has the advantage, that baudrate is accurate up to 9600BAUD.

Using MCLK for UART on MSP430 devices:

MCLK may be used as clock source for the baudrate generator. Higher baudrates arepossible. When the RC oscillator is used for MCLK generation, the baudrate may beinstable. When a crystal is used for MCLK generation, baudrate is accurate and sta-ble. To use MCLK as source for baudrate generator, define OS_BAUDSRC_MCLK=1 asproject option. Baudrate generator settings will then be calculated derived fromOS_BAUDRATE and OS_FSYS.


25

Chapter 5

Stacks

This chapter describes the different stacks.


26 CHAPTER 5 Stacks

5.1 Task stackEach task uses its individual stack. The stack pointer is initialized and set every timea task is activated by the scheduler. The stack-size required for a task is the sum ofthe stack-size of all routines plus a basic stack size plus size used by exceptions.

The basic stack size is the size of memory required to store the registers of the CPUplus the stack size required by embOS-routines.

For the MSP430, the minimum stack size is about 30 bytes. As an MSP430 does notsupport its own interrupt stack, please note, that interrupts can also run on taskstacks. You may use embOSView together with an embOS stack check library to ana-lyze the total amount of task stack used in your application. We recommend at leasta minimum task stack size of 128 bytes.

5.2 System stackThe minimum system stack size required by embOS is about 60 bytes (stack check & pro-filing build). However, since the system stack is also used by the application before thestart of multitasking (the call to OS_Start()), and because software timers and C-levelinterrupt handlers also use the system stack, the actual stack requirements depend onthe application.

The size of the system stack is given in the linker commands as -stack_size or -stack andmay be defined in the project properties when using the TI Code Composer. We recom-mend a minimum system stack size of 128 bytes.

5.3 Interrupt stackUnfortunately MSP430 CPUs do not support a separate interrupt stack pointer. Inter-rupts use the stack of the running application. Therefore interrupts occupy additionalstack space on every task and on the system stack.

5.4 Stack specifies of the MSP430/MSP430X familyThe MSP430 family of microcontroller can address up to 64KB of memory. Becausethe stack-pointer can address the entire memory area, stacks can be located any-where in RAM.

The stack pointer of the MSP430X family of microcontroller can address the wholememory. Stacks can be located anywhere in RAM.


27

Chapter 6

Interrupts


28 CHAPTER 6 Interrupts

6.1 What happens when an interrupt occurs?� The CPU-core receives an interrupt request� As soon as the interrupts are enabled, the interrupt is accepted.� The CPU saves PC and flags on the stack.� The CPU jumps to the address specified in the vector table for the interrupt� service routine (ISR).� ISR: save registers� ISR: user-defined functionality� ISR: restore registers� ISR: Execute RETI command, restoring PC, Flags and continue interrupted pro-

gram� For details, please refer to Texas Instruments users manual.

6.2 Defining interrupt handlers in CRoutines defined with the keyword __interrupt automatically save & restore theregisters they modify and return with RETI.The interrupt vector number has to be given as additional parameter by a #pragmadirective prior the interrupt handler function.For a detailed description on how to define an interrupt routine in "C", refer to the C-Compiler user guide.

Example

Simple interrupt routine:

#prgama vector=12__interrupt void IntHandlerTimer(void) { IntCnt++;}

Interrupt-routine calling embOS functions:

#prgama vector=12 __interrupt void IntHandlerTimer(void) { OS_EnterInterrupt(); /* Inform embOS that interrupt function is running */ IntCnt++; OS_PutMailCond(&MB_Data, &IntCnt); OS_LeaveInterrupt();}

6.3 Interrupt-stackSince MSP430 CPUs do not provide a separate stack pointer for interrupts, everyinterrupt occupies additional stack space on the current stack. This may be the sys-tem stack or a task stack of a running task that is interrupted. The additional amountof necessary stack for all interrupts has to be reserved on all task stacks.

The current version of embOS for MSP430 does not support extra interrupt stack-switching in an interrupt routine.

OS_EnterIntStack() and OS_LeaveIntStack() are supplied for source compatibilityto other processors only and have no functionality.


29

Chapter 7

Technical data


30 CHAPTER 7 Technical data

7.1 Memory requirementsThese values are neither precise nor guaranteed but they give you a good idea of thememory-requirements. They vary depending on the current version of embOS. Theminimum ROM requirement for the kernel itself is about 2.500 bytes.

In the table below, which is for extreme release build, you can find minimum RAMsize requirements for embOS resources. Note that the sizes depend on selectedembOS library mode.

embOS resource RAM [bytes]

Task control block 14

Software timer 12

Resource semaphore 8

Counting semaphore 4

Mailbox 12

Queue 18

Task event 0

Event object 6


31

Index

CClock specifics .....................................24CPU modes ................................... 21�22

FFirst steps ..........................................11

IInstallation .........................................10interrupt handlers ................................28Interrupt stack ....................................26Interrupt vector table ...........................28Interrupts ...........................................27

MMemory requirements ..........................30

RRequired files or an embOS ...................18

SStacks ................................................25Syntax, conventions used ...................... 5System stack ......................................26

TTask stack ..........................................26


32 Index


Documents

UM01056 embOS MSP430 TICC · Chapters "Libraries" and "CPU and compiler specifics" intro-duced. 4.00 0 140617 SC First Version. 4 ... JTAG emulator for ARM cores USB driven JTAG interface