scmRTOS v3 AVR/GCC Release Notes

Author: Harry E.Zhurov, Oleksandr O.Redchuk
Date: $Date $
Revision: $Rev $
Info:See main scmRTOS User's Manual for details

contents


Preamble

Release includes a sample set that contains three samples and RTOS sources. The purpose of the sample set is to show use examples and primary RTOS functionality and features.


General Description

RTOS consists of three parts:

Common part contains main RTOS definitions and declarations such as RTOS kernel, interprocess communication services and little support library. All Common sources stand at Common subfolder (see below).

Target-dependent part describes target processor and toolkit features of the RTOS:

Project-dependent part includes two header files:

scmRTOS_CONFIG.h describes project-level RTOS configuration macros.

scmRTOS_TARGET_CFG.h contains project-level tuning code, in particular System Timer and context switch software interrupt stuff. Default, WatchDog Timer is used as System Timer, and Analog Comparator Interrupt as Software Context Switch Interrupt. The user can change these setting to more project-suitable if need.


Sample Structure

The sample consists of three parts:

EventFlag sample brings test on speed. OS::TEventFlag is the simplest and fastest service of the RTOS. In this example program control flow transferred from timer interrupt service routine (ISR) to waiting process. Dedicated processor's pin is set to '1' before signalling of the EventFlag and set to '0' inside waiting process. So, positive pulse width on this pin corresponds with program control flow transfer time. Another five pins are set to '1' or '0' on various events, detailed description and oscillograms see in ./1-EventFlag/doc/1-EventFlag-scope.html

OS::message sample demonstrates ability to send arbitrary information from ISRs and processes to processes. In the example one process waits the message and timer ISR and another process send the message. Message content is different in each case, so, process-receiver can distinguish the source of the message.

Sample with OS::channel shows a message queue. Since the message can have arbitrary type, current example uses pointers to class types. In the example two more priority processes "delegate" some actions to the third (low-priority) process. See scmRTOS documentation Appendix section for more details about this mechanism.

Contents of all parts is the same: test project and RTOS sources. Each located in its own folder.

Structure of test project folder (folders are in brackets '[]'):

[makefiles]       - common project-independent makefiles for avr-gcc and avreal
[src]             - test project sources
[exe]             - executable product[s]
[lst]             - listings and other temporary text files
[obj]             - objects and other intermediate files
makefile	  - project make script

folders [exe], [lst], [obj] are not saved in repository and created during compilation process

Structure of the RTOS folder:

scmRTOS
  Common           - common RTOS sources
  AVR              - portable part

Usage

AVR/GCC port intended to be used with avr-gcc v3.4.x and later versions. Work with versions before v3.4 not tested, versions before 3.0 are not supported.

There are two variants of usage. The first variant is checking out sample set from the SourceForge repository. The second one is downloading the release archive and using it locally.

Working with Repository

Initially, after checkout from repository the folders

scmRTOS/Common
scmRTOS/AVR

are empty. User has to switch these folders manually to appropriate repository folders:

scmRTOS/Common to $REP$/Common
scmRTOS/AVR    to $REP$/Ports/AVR/GCC

where $REP$ is proper branch of the repository.

After this working copy is ready to build.

Working with Release

In this case no extra actions required. User can build the samples at this point.

Standalone RTOS sources

There is one more way to usage RTOS (RTOS only, not the whole release). To do this the user has to create local folders for RTOS sources - for Common part and for Port part as well. For example, create at user's project folder subfolder scmRTOS (or with any other suitable name); inside this subfolder create subfolders for Common and Port sources; set to this subfolders svn:externals [1] properties that will link these subfolders to the appropriate folders in external (SourceForge) repository.

In this way, user gets the ability to synchronize its project RTOS sources with main RTOS repository.


Building

Using make

Just run make in the sample root folder (folder where makefile located)

$PROMPT$>make
make will build the project
$PROMPT$>make run
make will rebuild project if needed and download project into target board using avreal (use make fuses at first time programming).

makefile customisation

You can change some variables in project makefile:
AVRGCC=c:/WinAVR-20071221
This variable point to toolkit root folder and can be changed for compiling by another version of avr-gcc.
MAKE_SMALLEST_HEX = Y
'Y' - on compiler and linker switches for relaxation and unused code/data objects removing. This option can be used only with avr-gcc v4.0 and later.
TRG = message
Target name (base name for .elf, .hex and .eep files).
MCU := atmega168
Processor model.
TRGPGMEXT = hex eep
Space-separated list of target files extensions. `hex' and `eep' are allowed values. Place `eep' here if .eeprom section actually used and $(TRG).eep file needed. Variable used for generating target names in makefiles/avr-gcc.mak and `run' target avreal command line arguments in makefiles/avreal.mak.
FUSES = bodlevel=5,cksel=2,ckdiv8=off,sut=0
Fuse list for avreal -f swicth. No spaces allowed inside value string.
AVREAL_OPT= -n
Additional avreal options - for example, erase counter or chip lock switch.
F_CPU=8000000
Processor clock frequency in Hz. Used for C-compiler F_CPU define and avreal -o switch.

Another variables are clear for gcc users.


[1]For more details about svn:externals see Subversion documentation.
[2]For example, step-up to scons or step-down to simple bat file.