Download Mini OS User`s Guide

Mini OS User’s Guide
Mini OS User’s Guide
Ver1.4
Mini OS
Version: 1.4
Date: 01/02/2005
History
Data
Version
01/02/2005
17/12/2005
1.0
1.2
27/12/2005
1.4
Confidential
Author: Wan Hong
Description
Create the basic OS kernel code
Added message and event interface function,
added OS tick user hook function and user
configuration file.
Added statistics task to calculate the CPU
usage, added os_send_message_front () to enable
user to send a priority message, optimize code
for speed in os_task_switch ().
Author
Wang Hong
Wang Hong
Wang Hong
Page 2 of 13
Mini OS
Version: 1.4
Date: 01/02/2005
Contents
1.
OVERVIEW.........................................................................................................................................................4
1.1
1.2
OS SPECIFICATIONS........................................................................................................................................4
TARGET REQUIREMENTS ................................................................................................................................4
2.
REAL-TIME EMBEDDED PROGRAMS SINGLE-TASKING PROGRAMS ...........................................5
3.
THEORY OF OPERATION ..............................................................................................................................7
3.1
3.2
3.3
3.4
3.5
3.6
3.7
3.8
4.
TIMER TICK INTERRUPT..................................................................................................................................7
TASKS.............................................................................................................................................................7
TASK MANAGEMENT ......................................................................................................................................8
EVENTS ..........................................................................................................................................................8
TASK SCHEDULER ..........................................................................................................................................9
COOPERATIVE TASK SWITCHING .................................................................................................................. 10
IDLE TASK .................................................................................................................................................... 10
STACK MANAGEMENT .................................................................................................................................. 10
CONFIGURING MINI OS ............................................................................................................................... 11
4.1
CONFIGURATION .......................................................................................................................................... 11
4.1.1
Hardware Timer .................................................................................................................................. 11
4.1.2
Stack..................................................................................................................................................... 11
4.1.3
Misc ..................................................................................................................................................... 11
4.2
OPTIMIZING .................................................................................................................................................. 11
5.
USING MINI OS ............................................................................................................................................... 11
5.1
5.2
6.
INCLUDE FILES ............................................................................................................................................. 12
PROGRAMMING GUIDELINES ........................................................................................................................ 12
FUNCTION REFERENCE .............................................................................................................................. 12
6.1
6.2
6.3
6.4
6.5
6.6
6.7
6.8
6.9
6.10
6.11
6.12
6.13
6.14
6.15
6.16
6.17
OS_CREATE_TASK ........................................................................................................................................ 12
OS_WAIT ....................................................................................................................................................... 13
ISR_SEND_SIGNAL ........................................................................................................................................ 13
OS_SEND_SIGNAL ......................................................................................................................................... 13
OS_GET_SIGNAL ........................................................................................................................................... 13
OS_CLEAR_SIGNAL ....................................................................................................................................... 13
ISR_SEND_MESSAGE ..................................................................................................................................... 13
OS_SEND_MESSAGE ...................................................................................................................................... 13
OS_SEND_MESSAGE_FRONT.......................................................................................................................... 13
OS_GET_MESSAGE ........................................................................................................................................ 13
OS_RUNNING_TASK_ID ................................................................................................................................. 13
OS_SWITCH_TASK......................................................................................................................................... 13
OS_RESET_INTERVAL ................................................................................................................................... 13
OS_TIME_GET ............................................................................................................................................... 13
OS_TIME_SET ................................................................................................................................................ 13
OS_GET_STACK_USAGE ................................................................................................................................ 13
OS_GET_CPU_USAGE .................................................................................................................................... 13
Confidential
Author: Wan Hong
Page 3 of 13
Mini OS
Version: 1.4
Date: 01/02/2005
Mini OS
1.
Overview
Mini OS is a real-time operating system (RTOS), which allows you to create
applications that simultaneously perform multiple functions or tasks. This is
often required in an embedded application. While it is certainly possible to
create real-time programs without an RTOS (by executing one or more functions or
tasks in a loop) there are numerous scheduling, maintenance, and timing issues
that an RTOS like Mini OS can solve for you.
A real-time operating system (RTOS) allows flexible scheduling of system resources
like the CPU and memory and offers some way to communicate between tasks. Mini OS
is a powerful RTOS that is easy to use.
Mini OS programs are written using standard C constructs and compiled with the ICC
C Compiler (for Avr). Mini OS programs require only that you include a special
header file and link the Mini OS into your program.
1.1
OS Specifications
Parameter
Maximum Number of Defined Tasks
Maximum Number of Active Tasks
Required CODE Space
Required STACK Space
Required Data Space
Timer
Interrupt Latency
Context Switch Time
1.2
Limits
32
32
~2000 Bytes Max
4 Bytes/Task (task entry address and stack
pointer)
Signal + Timer: 2~3 Bytes/Task
Message: 4 Bytes/message (optional)
Timer 2 for Atmega8
100 Cycles or Less
100-600 Cycles
Target Requirements
Mini OS performs cooperative task switching (each tasks calls an operating system
routine). It supports task priorities but Preemptive task switching is not supported.
Interrupts:
Mini OS works in parallel with your interrupt functions. Interrupt service routines
may communicate with Mini OS tasks by sending signals using the isr_send_signal ()
function or by sending messages using the isr_send_message () function.
Interrupt routines must be implemented and enabled in your Mini OS application as they
would be in a standard, non-Mini OS application. There is no interrupt service routine
management in Mini OS.
Confidential
Author: Wan Hong
Page 4 of 13
Mini OS
Version: 1.4
Date: 01/02/2005
Mini OS uses Timer 2 and the Timer 2 interrupt. Globally disabling all interrupts or
the Timer 2 interrupt stops the operation of Mini OS. You should disable interrupts
for brief periods only.
Reentrant Functions:
Non-reentrant C functions may not be called from more than one task or interrupt
procedure. Non-reentrant C functions store their parameters and automatic variables
(local data) in static memory segments, which may be overwritten when the function is
called from multiple tasks simultaneously, or recursively.
You may invoke non-reentrant functions from multiple tasks if you ensure that they are
not called recursively (simultaneously). Usually this means that your non-reentrant
functions may not call any Mini OS system functions.
C functions which only use registers for parameter and automatic variables are
inherently reentrant and can be called without any restrictions from Mini OS.
Note that when you call the os services: os_wait () and os_switch_task (), local
variables the caller used should be considered being crashed unconditionally, so the
user should confirm that all the local variables (temporary variables, parameters etc.)
have been saved before calling those two os services, normally you can define the
temporary variables as static type and save parameters into static type variables.
Library Routines:
All C library routines that are reentrant may be used in all tasks without any
restrictions. For C library routines that are non-reentrant, the same restrictions
apply as for non-reentrant C functions.
2.
Real-Time Embedded Programs
Single-Tasking Programs
Both embedded and standard C programs start execution with the main C function. In an
embedded application, main is usually implemented as an endless loop and can be
thought of as a single task, which is executed continuously. For example:
void main (void)
{
while (1)
{
do_something ();
}
}
/* repeat forever */
/* execute the do_something 'task' */
In this example, the do_something function can be thought of as a single task. Since
there is only one task that executes, there is no need for multitasking capability or
a multitasking operating system.
Multi-Tasking Programs
Confidential
Author: Wan Hong
Page 5 of 13
Mini OS
Version: 1.4
Date: 01/02/2005
More sophisticated C programs may implement a pseudo-multitasking scheme where several
functions (or tasks) are called in a loop. For example:
void main (void)
{
int counter = 0;
while (1)
{
check_serial_io ();
process_serial_cmds ();
/* repeat forever */
/* check for serial input */
/* process serial input */
check_kbd_input ();
process_kbd_cmds ();
/* check for keyboard input */
/* process keyboard input */
adjust_ctrlr_parms ();
/* adjust the controller */
counter++;
}
/* increment counter */
}
In this example, each function performs a separate operation or task. The functions
(or tasks) are executed in order, one after another.
Scheduling starts to become an issue as more tasks are added. For example, if the
process_kbd_cmds function executes for a long time, the main loop may take too long to
get back around to the check_serial_io function and serial data may be lost. Of course,
the check_serial_io function can be called more often in the main loop to correct this
issue, but eventually this technique will not work.
Mini OS Programs
When you use Mini OS, you create a separate function task for each task in your
application. For example:
void check_serial_io_task (void)
{
/* This task checks for serial I/O */
}
void process_serial_cmds_task (void)
{
/* This task processes serial commands */
}
void check_kbd_io_task (void)
{
/* This task checks for keyboard I/O */
}
Confidential
Author: Wan Hong
Page 6 of 13
Mini OS
Version: 1.4
Date: 01/02/2005
void process_kbd_cmds_task (void)
{
/* This task processes keyboard commands */
}
void main (void)
{
os_create_task
os_create_task
os_create_task
os_create_task
(1,
(2,
(3,
(4,
serial_io_task);
serial_cmds_task);
kbd_io_task);
kbd_cmds_task);
/*
/*
/*
/*
Create
Create
Create
Create
serial_io Task */
serial_cmds Task */
kbd_io Task */
kbd_cmds Task */
while (1)
{
do_something ();
}
}
In this example, each function defines a Mini OS task. Mini OS programs do not have a.
Instead, Mini OS starts with main C function as task 0. In typical applications, task
0 simply creates all the other tasks.
3.
Theory of Operation
3.1
Timer Tick Interrupt
Mini OS uses the Atmega8/16 Timer 2 to generate a periodic interrupt. This interrupt
is the Mini OS Timer Tick. Timeout and interval values specified for the Mini OS
routines are measured using the Mini OS Timer Tick.
By default, the Mini OS Timer Tick interrupt occurs about every 16,000-machine cycles.
So, for an Atmega8/16 running at 4MHz, the period of the timer tick is 0.004 seconds.
The value may be changed in the os_config.h configuration file.
You may append your own code to the Mini OS Timer Tick Interrupt; refer to the
os_config.h configuration file for more information.
3.2
Tasks
Mini OS is basically a task switcher. To create a Mini OS program, you must create an
application with one or more task functions. The following details will help you more
quickly gain an understanding of Mini OS.
Tasks are defined in the C Programming Language using Mini OS os_create (task_id,
task_entry) function.
Mini OS maintains each task in exactly one state (Running, Ready or Waiting).
Only one task at a time may be in the Running State.
Many tasks may be in the Ready or Waiting States.
An Idle Task is always ready to run in the event that all of your defined tasks are
Confidential
Author: Wan Hong
Page 7 of 13
Mini OS
Version: 1.4
Date: 01/02/2005
blocked.
3.3
Task Management
Each Mini OS task is always in exactly one state, which tells the disposition of the
task.
State
RUNNING
READY
WAITING
DELETED
3.4
Description
The task that is currently running is in the RUNNING State. Only one
task at a time may be in this state. The os_running_task_id ()
returns the task number of the currently executing task.
Tasks that are ready to run are in the READY State. Once the Running
task has completed processing, Mini OS selects and starts the next
Ready task.
Tasks that are waiting for an event are in the WAITING State. Once
the event occurs, the task is switched to the READY State. The
os_wait () function is used to place a task in the WAITING State.
Tasks that have not been started or tasks that have not been deleted
are in the DELETED State.
Events
Events in a real-time operating system may be used to control the execution of tasks
in the program. A task may wait for events or may set event flags for other tasks.
The os_wait function allows a task to wait for one or more events.
1. A common event for which a task can wait is the Timeout. A timeout is simply a
number of clock ticks. While a task is waiting for a timeout, other tasks may
execute. Once the specified number of timer ticks has elapsed, the task may
continue execution.
2. A variant of the Timeout is the Interval. An interval is like a timeout except that
the specified number of clock ticks is relative to the last time the os_wait
function was invoked by the task. The Interval may be used to generate a task,
which is run on a regular, synchronous schedule (like once every second) regardless
of how long the task takes between calls to the os_wait function.
3. A Signal is a simple form of inter-task communication. A task can wait for another
task to send it a signal (with the os_send_signal and isr_send_signal functions).
4. A Message is another form of inter-task communication. A task can wait for another
task to send it a message (with the os_send_message, isr_send_message,
os_send_message_front and isr_send_message functions).
Each event has an associated event flag that Mini OS maintains. The following event
selectors may be used with the os_wait function to specify what to wait for:
Event Selector
K_IVL
K_TMO
Confidential
Author: Wan Hong
Description
Wait for the specified interval.
Wait for a specified timeout.
Page 8 of 13
Mini OS
Version: 1.4
Date: 01/02/2005
K_SIG
K_MSG
Wait for a signal.
Wait for a message.
When os_wait returns, the events that occurred are specified by the return value:
Return Value
EVENT_TMO
EVENT_SIG
EVENT_MSG
Description
A time-out has completed or an interval has elapsed.
A signal was received.
A message was received.
The os_wait function may wait for the following combinations of events:
1. K_SIG | K_TMO: os_wait delays the task until a signal is sent to it or until the
specified number of clock ticks has elapsed.
2. K_MSG | K_TMO: os_wait delays the task until a message is sent to it or until the
specified number of clock ticks has elapsed.
3. K_SIG | K_MSG: os_wait delays the task until a signal is sent to it or until a
message is sent to it.
4. K_SIG | K_MSG | K_TMO: os_wait delays the task until a signal is sent to it or
until a message is sent to it or until the specified number of clock ticks has
elapsed.
5. K_SIG | K_IVL: os_wait delays the task until a signal is sent to it or until the
specified interval has elapsed.
6. K_MSG | K_IVL: os_wait delays the task until a message is sent to it or until the
specified interval has elapsed.
7. K_SIG | K_MSG | K_IVL: os_wait delays the task until a signal is sent to it or
until a message is sent to it or until the specified interval has elapsed.
Note:
1. The K_IVL and K_TMO event selectors may not be combined.
3.5
Task Scheduler
The Task Scheduler is the part of Mini OS that assigns the processor to a task. The
Mini OS scheduler determines which task to run using to the following rules:
The current task is interrupted if:
1. If the task calls the os_wait function to wait for a time out (K_IVL or K_TMO)
combined with other event (K_SIG or K_MSG), and the task is already time out, it
will restart with the task without task switch, else the scheduler will determine
the next task to run.
Another task is started if:
1. No other task is running.
Confidential
Author: Wan Hong
Page 9 of 13
Mini OS
Version: 1.4
Date: 01/02/2005
2. The task to be started is in the READY State.
3.6
Cooperative Task Switching
You must design and implement your tasks so that they work cooperatively. Specifically,
you must call the os_wait function or the os_switch_task function somewhere in each
task. These functions signal Mini OS to switch to another task.
The difference between os_wait and os_switch_task is that os_wait allows your task to
wait for an event while os_switch_task switches to another ready task immediately.
3.7
Idle Task
When no task is ready to run, Mini OS executes an Idle Task. The Idle Task is simply
an endless loop.
It provides an idle mode that reduces power consumption by halting program execution
until an interrupt occurs. In this mode, all peripherals include the interrupt system
still continue operation.
When no task ready, the CPU may enter idle mode, and when CPU woke by any interrupt,
Mini OS will check if there is task ready to run, if no task is ready to run, Mini OS
will continue with the Idle Task.
3.8
Stack Management
Mini OS maintains a stack for each task using only the internal memory of the
Atmega8/16. When a task is running, it is given the maximum amount of stack space
possible. When a task switch occurs, the previous task stack is shrunk and relocated
and the stack for the current task is expanded and relocated.
The following figure illustrates the layout of internal memory for an example
application with three separate tasks.
Task 0 running
Stack Area
for Task 0
Task 1 running
---------Stack bottom
0x45f
Task 2 running
---------Stack bottom
0x45f
Stack Area
for Task 0
Stack Area
for Task 2
Stack top
----------
The top and bottom of the
os_config.h.
Confidential
Author: Wan Hong
Stack Area
for Task 2
---------Stack bottom
0x45f
Stack Area
for Task 1
Stack Area
for Task 1
Stack Area
for Task 1
Stack Area
for Task 0
Stack Area
for Task 2
Stack top
----------
Stack top
----------
stack may be specified in the
Page 10 of 13
Mini OS
4.
Version: 1.4
Date: 01/02/2005
Configuring Mini OS
Mini OS was designed to customize for each application you created.
4.1
Configuration
4.1.1
Hardware Timer
The following Equates specify how the Mini OS hardware timer is configured:
OS_TICKS_PER_SEC specifies the number of the timer interrupt generated in 1s. This
number may be a value from 100-500. Large numbers generate faster interrupts. This
number is used to calculate the reload value for the timer. The default setting is 100.
4.1.2
Stack
Several options are available for stack configuration. The following Equate define the
area of the internal RAM used for stack:
OS_STACK_TOP specifies the address of the top of the stack.
OS_STACK_BOTTOM specifies the address of the bottom of the stack.
4.1.3
Misc
OS_PRIORITY_EN enable task priority (task 0 is the highest priority task).
OS_MSG_PRIORITY_EN your application may call os_send_message_front () to send a
message has priority.
OS_CPU_HOOKS_EN user functions enable bit.
OS_TASK_STAT_EN statistics task enable bit.
OS_STK_CHK_EN stack check enable bit.
OS_MAX_TASK_N specifies the max task number.
OS_LOWEST_PRIO specifies the lowest priority that can be assigned (=OS_MAX_TASK_N-1).
OS_MAX_MSG_N specifies the max message number.
OS_MSG_MEM_TYP specifies the memory type for location of the message pool.
CPU_IDLE_CODE the code for decreasing power consumption.
4.2
Optimizing
There are several things you can do to optimize your Mini OS programs:
Avoid setting the OS_TICKS_PER_SEC too large. Setting the OS_TICKS_PER_SEC for the
timer tick to a large value increases the number of ticks per second but decreases the
amount of time available for tasks (because the timer tick interrupt takes 100-200
cycles to execute). Set the OS_TICKS_PER_SEC value low enough to minimize the effects
of the timer tick interrupt handler.
5.
Using Mini OS
To use Mini OS, you must be able to successfully create Mini OS programs and compile
Confidential
Author: Wan Hong
Page 11 of 13
Mini OS
Version: 1.4
Date: 01/02/2005
and link them.
5.1
Include Files
Mini OS requires the use of only one include file: OS.H. All OS routines and constants
are defined in this header file. You may include it in your Mini OS source files as
follows:
#include “os.h”
5.2
Programming Guidelines
There are a few rules you must follow when creating Mini OS programs.
Be sure to include the OS.H header file.
Your program must create a main C function as Task 0.
Task 0 is the first function in your program that executes. You must call the
os_create_task function from task 0 to run other tasks.
Task functions must never exit or return. The task must repeat using a while (1) or
similar construct.
6.
Function Reference
The following pages describe the Mini OS system functions.
Note:
Functions that begin with os_ may be called from a task but not from an interrupt
service routine.
Functions that begin with isr_ may be called from an interrupt service routine but not
from a task.
6.1
os_create_task
Summary:
#include “os.h”
char os_create_task (unsigned char task_id, void
(*task_entry)(void));
Description:
The os_create_task function starts the defined task function using
the task number specified by task_id. The task is marked as ready and
is executed according to the rules specified for Mini OS.
The os_create_task function returns a value of 0 if the task was
Return Value: successfully started. A value of -1 is returned if the task could not
be started or if no task was defined using the specified task number.
See Also:
#include “os.h”
#include <stdio.h>
Example:
Confidential
Author: Wan Hong
/* for printf */
void new_task (void)
{
…
}
Page 12 of 13
Mini OS
Version: 1.4
Date: 01/02/2005
void main (void)
{
…
if (os_create_task (2, new_task))
{
printf ("Couldn't start task 2\n");
}
…
}
6.2
os_wait
6.3
isr_send_signal
6.4
os_send_signal
6.5
os_get_signal
6.6
os_clear_signal
6.7
isr_send_message
6.8
os_send_message
6.9
os_send_message_front
6.10
os_get_message
6.11
os_running_task_id
6.12
os_switch_task
6.13
os_reset_interval
6.14
os_time_get
6.15
os_time_set
6.16
os_get_stack_usage
6.17
os_get_cpu_usage
Confidential
Author: Wan Hong
Page 13 of 13