RL-ARM User's Guide

RL-ARM User's Guide
Overview...............................................................................................................................6
Product Description............................................................................................................7
Product Specification...........................................................................................................8
Technical Data...............................................................................................................9
Timing Specifications....................................................................................................1
!dvantages......................................................................................................................11
"our #irst $T% !pplication..................................................................................................1&
Theor' of Operation..............................................................................................................1(
Timer Tic) *nterrupt..........................................................................................................1+
S'stem Tas) ,anager........................................................................................................16
Tas) ,anagement.............................................................................................................17
*dle Tas).........................................................................................................................18
S'stem $esources............................................................................................................19
Scheduling Options...........................................................................................................&
Pre-emptive Scheduling.................................................................................................&1
$ound-$o.in Scheduling................................................................................................&&
/ooperative ,ultitas)ing...............................................................................................&0
Priorit' *nversion..............................................................................................................&(
$esource sharing..........................................................................................................&(
Priorit' inheritance.......................................................................................................&(
Stac) ,anagement...........................................................................................................&+
1ser Timers.....................................................................................................................&6
*nterrupt #unctions...........................................................................................................&7
/onfiguring $T% 2ernel..........................................................................................................&9
3asic $T% /onfiguration.....................................................................................................0
Tas)s..........................................................................................................................01
Stac) Si4e...................................................................................................................0&
Stac) /hec)ing............................................................................................................00
$un in Privileged ,ode..................................................................................................0(
5ardware Timer...........................................................................................................0+
$ound-$o.in ,ultitas)ing..............................................................................................06
1ser Timers.................................................................................................................07
#*#O 6ueue 3uffer........................................................................................................08
7rror #unction..............................................................................................................09
*dle8Tas)....................................................................................................................(
!dvanced $T% /onfiguration...............................................................................................(1
59 $esources $e:uired.................................................................................................(&
/onfiguration ,acros....................................................................................................(0
;i.rar' #iles.....................................................................................................................(+
1sing $T% 2ernel..................................................................................................................(6
9riting Programs..............................................................................................................(7
*nclude #iles................................................................................................................(8
Defining Tas)s.............................................................................................................(9
,ultiple *nstances........................................................................................................+
7<ternal $eferences......................................................................................................+1
1sing a ,ail.o<............................................................................................................+&
Sending 8-.it= 16-.it= and 0&-.it values......................................................................+&
Sending fi<ed si4e messages......................................................................................+&
#i<ed ,emor' .loc) memor' allocation functions..........................................................+&
Sending varia.le si4e messages.................................................................................+0
S9* #unctions.............................................................................................................+(
S>/ #unctions..............................................................................................................++
De.ugging.......................................................................................................................+7
S'stem *nfo.................................................................................................................+8
Tas) *nfo.....................................................................................................................+9
7vent >iewer...............................................................................................................6
1sage 5ints.....................................................................................................................61
#unction usage............................................................................................................61
!$, >ersion................................................................................................................6&
1sing *$6 interrupts.................................................................................................6&
1sing #*6 interrupts.................................................................................................6&
2
S'stem Startup........................................................................................................6&
/orte< >ersion.............................................................................................................6(
1sing *$6 interrupts.................................................................................................6(
S'stem Startup........................................................................................................6(
/reate ?ew $T% !pplication...............................................................................................6+
#unction $eference................................................................................................................67
7vent #lag ,anagement $outines........................................................................................68
,ail.o< ,anagement $outines............................................................................................69
,emor' !llocation $outines...............................................................................................7
,ute< ,anagement $outines..............................................................................................71
Semaphore ,anagement $outines......................................................................................7&
S'stem #unctions.............................................................................................................70
Tas) ,anagement $outines................................................................................................7(
Time ,anagement $outines...............................................................................................7+
1ser Timer ,anagement $outines.......................................................................................76
3
$eference............................................................................................................................78
8alloc8.o<.......................................................................................................................79
8calloc8.o<.....................................................................................................................8
8declare8.o<...................................................................................................................81
8declare8.o<8.................................................................................................................8&
8free8.o<........................................................................................................................80
8init8.o<.........................................................................................................................8(
8init8.o<8.......................................................................................................................8+
isr8evt8set......................................................................................................................86
isr8m.<8chec).................................................................................................................87
isr8m.<8receive...............................................................................................................88
isr8m.<8send..................................................................................................................89
isr8sem8send...................................................................................................................9
isr8ts)8get......................................................................................................................91
os8dl'8wait.....................................................................................................................9&
os8evt8clr.......................................................................................................................90
os8evt8get......................................................................................................................9(
os8evt8set.......................................................................................................................9+
os8evt8wait8and..............................................................................................................96
os8evt8wait8or................................................................................................................97
os8itv8set.......................................................................................................................98
os8itv8wait......................................................................................................................99
os8m.<8chec)...............................................................................................................1
os8m.<8declare.............................................................................................................11
os8m.<8init...................................................................................................................1&
os8m.<8send.................................................................................................................10
os8m.<8wait..................................................................................................................1(
os8mut8init...................................................................................................................1+
os8mut8release..............................................................................................................16
os8mut8wait..................................................................................................................18
os8sem8init...................................................................................................................11
os8sem8send.................................................................................................................111
os8sem8wait..................................................................................................................11&
os8s's8init....................................................................................................................110
os8s's8init8prio.............................................................................................................11(
os8s's8init8user.............................................................................................................11+
os8tmr8call....................................................................................................................116
os8tmr8create................................................................................................................117
os8tmr8)ill....................................................................................................................118
os8ts)8create.................................................................................................................119
os8ts)8create8e<............................................................................................................1&
os8ts)8create8user.........................................................................................................1&1
os8ts)8create8user8e<....................................................................................................1&&
os8ts)8delete.................................................................................................................1&(
os8ts)8delete8self..........................................................................................................1&+
os8ts)8pass...................................................................................................................1&6
os8ts)8prio....................................................................................................................1&7
os8ts)8prio8self.............................................................................................................1&8
os8ts)8self....................................................................................................................1&9
ts)8loc)........................................................................................................................10
ts)8unloc).....................................................................................................................101
4
RL-RTX
$;-$T%
This chapter descri.es the powerful 2eil $T% $eal-Time Operating S'stem @$T%-$TOSA designed for
microcontrollers .ased on !$,7BTD,*= !$,9B= and /orte<B-, /P1 cores. The $T% )ernel can .e
used for creating applications that perform multiple functions or tas)s simultaneousl'.
9hile it is certainl' possi.le to create real-time applications without an $TOS @.' e<ecuting one or
more tas)s in a loopA= there are numerous scheduling= maintenance= and timing issues that can .e
solved .etter with an $TOS. #or e<ample= an $TOS ena.les fle<i.le scheduling of s'stem resources
li)e /P1 and memor'= and offers methods to communicate .etween tas)s.
$T% programs are written using standard / constructs and are compiled with the $eal>iewC /ompiler.
The RTX.H header file defines the $T% functions and macros that allow declaring tas)s and accessing
all $TOS features easil'.
This chapter contains the following sectionsD
Overview
Provides an overview a.out the $;-$T% .asic functions= inter-process communication and
technical specifications.
Theory of Operation
Descri.es the resources and their management= such as scheduling= tas) and stac) management=
interrupts= and timers.
Configuring the RTX Kernel
Descri.es the .asic and advanced $T% configuration options= and lists the $;-$T% li.rar' files.
Using the RTX Kernel
Provides instructions for writing and de.ugging applications.
Function Reference
Descri.es the $T% functions.
The topic Create New RTX Application provides a step-.'-step introduction that e<plains 'ou how
to create $T% applications.
5
Overview
$;-$T% E Overview
The $T% )ernel is an eas' to use Real Time eXecutive @$T%A providing a set of / functions and macros
for .uilding real-time applications which are using tas)s running :uasi-parallel on the /P1.
This section includes the topicsD
Product Description - $T% provides functions to s'nchroni4e different tas)s= manage common
resources @li)e peripherals or memor' regionsA= and pass complete messages .etween tas)s.
Product Specification - ;ists technical and timing specifications.
!dvantages - ;ists some of the advantages when using the $T% )ernel.
6
Product Description
$;-$T% E Overview E Product Description
The $T% )ernel provides .asic functionalit' to start and stop concurrent tas)s @processesA. $T%
provides additional functions for inter-process communication. 1se the communication functions to
s'nchroni4e tas)s= manage common resources @li)e peripherals or memor' regionsA= and pass
complete messages .etween tas)s @round-ro.in schedulingA.
Developers can assign e<ecution priorities to tas)s. 9hen more tas)s e<ists in the read' list= the $T%
)ernel uses the e<ecution priorities to select the ne<t tas) to run @preemptive schedulingA.
The $T% )ernel provides several wa's for inter-process communication. These areD
Event flags
7vent flags are the primar' instrument for implementing tas) s'nchroni4ation. 7ach tas) has 16
event flags assigned to it. 5ence= tas) can selectivel' wait for 16 different events at the same time.
*n this case= the tas) can wait for all the selected flags @!?D-connectionA= or wait for an' one of the
selected flags @O$-connectionA.
7vent flags can .e set either .' tas)s or .' !$, interrupt functions. S'nchroni4e an e<ternal
as'nchronous event to an $T% )ernel tas) .' ma)ing the !$, interrupt function set a flag that the
tas) is waiting for.
Semaphores
*f more than one tas) needs to access a common resource= special means are re:uired in a real
time multitas)ing s'stem. Otherwise= accesses .' different tas)s might interfere and lead to
inconsistent data= or a peripheral element might function incorrectl'.
Semaphores are the primar' means of avoiding such access pro.lems. Semaphores @.inar'
semaphoresA are software o.Fects containing a virtual token. The )ernel gives the to)en to the
first tas) that re:uests it. ?o other tas) can o.tain the to)en until it is released .ac) into the
semaphore. Since onl' the tas) that has the to)en can access the common resource= it prevents
other tas)s from accessing and interfering with the common resource.
The $T% )ernel puts a tas) to sleep if the re:uested to)en is not availa.le in the semaphore. The
)ernel wa)es-up the tas) and puts it in the read' list as soon as the to)en is returned to the
semaphore. *t is posi.le to use a time-out to ensure the tas) does not sleep indefinitel'.
Mutexes
,utual e<clusion loc)s @mute<sA are an alternative to avoid s'nchroni4ation and memor' access
pro.lems. ,ute<es are software o.Fects that a tas) can use to loc) the common resource. Onl' the
tas) that loc)s the mute< can access the common resource. The )ernel .loc)s all other tas)s that
re:uest the mute< until the tas) that loc)ed the mute< unloc)s it.
Mailboxes
Tas)s can pass messages .etween each other using mail.o<es. This is usuall' the case when
implementing various high level protocols li)e T/P-*P= 1DP= and *SD?.
The message is simpl' a pointer to the .loc) of memor' containing a protocol message or frame.
*t is the programmerGs responsi.ilit' to d'namicall' allocate and free the memor' .loc) to prevent
memor' lea)s.
The $T% )ernel puts the waiting tas) to sleep if the message is not availa.le. The )ernel wa)es the
tas) up as soon as another tas) sends a message to the mail.o<.
7
Product Specification
$;-$T% E Overview E Product Specification
$T% 2ernel ;i.rar' can .e used with devices .ased onD
!$,7 and !$,9
/orte<-,H,1= /orte<-,0= /orte<-,(= and /orte<-$(
/orte<-, processor-.ased devices have e<tended $TOS features= which allows more ro.ust and fail-
proof $T% )ernel implementation. The main concept differences areD
!$,7 and !$,9 versions use the s'stem tas) manager to control tas) switches of all user tas)s.
Tas)s are e<ecuted in S'stem ,ode.
/orte<-, versions use s'stem calls that are all e<ecuted as SVC S'stem Supervisor /alls.
*n addition= refer toD
Technical Data - lists hardware re:uirements= $!, and code space= num.er of possi.le tas)s= ...
Timing Specifications - lists timing measurements @c'clesA for various $T% functions.
8
Technical Data
$;-$T% E Overview E Product Specification E Technical Data
Description !$,7BH!$,9B /orte<B-,
Defined Tas)s 1nlimited 1nlimited
!ctive Tas)s &+ ma< &+ ma<
,ail.o<es 1nlimited 1nlimited
Semaphores 1nlimited 1nlimited
,ute<es 1nlimited 1nlimited
Signals H 7vents 16 per tas) 16 per tas)
1ser Timers 1nlimited 1nlimited
/ode Space I(.& 2.'tes I(. 2.'tes
$!, Space for 2ernel 0 .'tes J
8 .'tes 1ser Stac)
0 .'tes J
1&8 .'tes ,ain Stac)
$!, Space for a Tas) Tas)Stac)Si4e J +& .'tes Tas)Stac)Si4e J +& .'tes
$!, Space for a ,ail.o< ,a<,essages K ( J 16 .'tes ,a<,essages K ( J 16 .'tes
$!, Space for a Semaphore 8 .'tes 8 .'tes
$!, Space for a ,ute< 1& .'tes 1& .'tes
$!, Space for a 1ser Timer 8 .'tes 8 .'tes
5ardware $e:uirements One on-chip timer S'sTic) timer
1ser tas) priorities 1 - &+( 1 - &+(
/onte<t switch time I+.0 Lsec M 6 ,54 I&.6 Lsec M 7& ,54
*nterrupt loc)out time I&.7 Lsec M 6 ,54 ?ot disa.led .' $T%
Note
Unlimited means that the $T% )ernel does not impose an' limitations on the num.er. 5owever= the
availa.le s'stem memor' resources limit the num.er of items 'ou can create.
The default configuration of the $T% )ernel allows 1 tas)s and 1 user timers. *t also disa.les
stac) chec)ing .' default.
*n the $T% )ernel= Event is simpl' another name for signal.
$!, re:uirements depend on the num.er of concurrentl' running tas)s.
The code and $!, si4e was calculated for MicoLib runtime li.rar'.
9
Timing Specifications
$;-$T% E Overview E Product Specification E Timing Specifications
#unction !$,7BH!$,9B
@c'clesA
/orte<B-,
@c'clesA
*nitiali4e s'stem @os8s's8initA= start tas) 17&1 11(7
/reate tas) @no tas) switchA 679 (0
/reate tas) @switch tas)A 787 (61
Delete tas) @os8ts)8deleteA (& &18
Tas) switch @.' os8ts)8delete8selfA (+8 &0
Tas) switch @.' os8ts)8passA 0&1 19&
Set event @no tas) switchA 1&8 89
Set event @switch tas)A 060 &1+
Send semaphore @no tas) switchA 16 7&
Send semaphore @switch tas)A 06( &17
Send message @no tas) switchA &18 117
Send message @switch tas)A (( &(1
Net own tas) identifier @os8ts)8selfA &0 6+
*nterrupt latenc' I16
Note
The ta.le for ARM7"/ARM9" $T% 2ernel li.rar' is measured on LPC2138 @!$,7A= code
e<ecution from internal flash with 4ero-c'cle latenc'.
The ta.le for Cortex"-M $T% 2ernel li.rar' is measured on LPC1768 @/orte<-,0A= code e<ecution
from internal flash with 4ero-c'cle latenc'.
The $T% 2ernel for the test is configured for 1 tas)s= 1 user timers and stac) chec)ing disa.led.
*nterrupt latenc' in ARM7"/ARM9" includes the *S$ prolog generated .' the compiler.
The $T% 2ernel li.rar' for Cortex"-M3/M4 does not disa.le interrupts. *nterrupt latenc' is the
same as without the $T% )ernel. *nterrupt latenc' for Cortex"-M0/M1 is I& c'cles.
Related Knowledgebase Articles
$;-!$,D $T% 27$?7; ,OD7 1S7D *? !$, /P1
10
Advantages
$;-$T% E Overview E !dvantages
The $T% )ernel is .ased on the idea of parallel tas)s @processesA. *n the $T% )ernel= the tas) that a
s'stem must fulfill is split up into several smaller tas)s that run concurrentl'. There are man'
advantages to using the $T% )ernelD
$eal world processes consist= usuall'= of several concurrent activities. This pattern can .e
represented in software .' using the $T% )ernel.
"ou can ma)e different activities occur at different times= for e<ample= Fust at the moment when
the' are needed. This is possi.le .ecause each activit' is pac)ed into a separate tas)= which can .e
e<ecuted on its own.
Tas)s can .e prioriti4ed.
*t is easier to understand and manage smaller pieces of code than one large piece of software.
Splitting up the software into independent parts reduces the s'stem comple<it'= the num.er of
errors= and even facilitates testing.
The $T% )ernel is scala.le. !dditional tas)s can .e added easil' at a later time.
The $T% )ernel offers services needed in man' real-time applications= for e<ample= good handling of
interrupts= periodical activation of tas)s= and time-limits on wait functions.
11
Your First RTX Application
$;-$T% E Overview E "our #irst $T% !pplication
This section demonstrates an e<ample of using the $T% )ernel for a simple application. The e<ample is
located in the folder \Keil\ARM\RL\RTX\Examples\RTX_ex1. The application must perform two
activities. The first activit' must continuousl' repeat + ms after the second activit' completes. The
second activit' must repeat & ms after the first activit' completes.
5ence= 'ou can implement these activities as two separate tas)s= called tas)1 and tas)&D
1. Place the code for the two activities into two separate functions @tas)1 and tas)&A. Declare the
two functions as tas)s using the )e'word __task @defined in $T;.5A which indicates a $T%
tas).
__task void task1 (void) {
.... place code of task 1 here ....
}
}
&. 9hen the s'stem starts up= the $T2 )ernel must start .efore running an' tas). To do this= call
the os_sys_init function in the / main function. Pass the function name of the first tas) as
the parameter to the os_sys_init function. This ensures that after the $T% )ernel initiali4es=
the tas) starts e<ecuting rather than continuing program e<ecution in the main function.
*n this e<ample= tas)1 starts first. 5ence= tas)1 must create tas)&. "ou can do this using the
os_tsk_create function.
os_tsk_create (task2, 0);
}
}
void main (void) {
os_sys_init (task1);
}
0. ?ow implement the timing re:uirements. Since .oth activities must repeat indefinitel'= place
the code in an endless loop in each tas). !fter the tas)1 activit' finishes= it must send a signal
to tas)&= and it must wait for tas)& to complete. Then it must wait for + ms .efore it can
perform the activit' again. "ou can use the os_dly_wait function to wait for a num.er of
s'stem intervals. The $T% )ernel starts a s'stem timer .' programming one of the on-chip
hardware timers of the !$, processors. 3' default= the s'stem interval is 1 ms and timer is
used @this is configura.leA.
"ou can use the os_evt_wait_or function to ma)e tas)1 wait for completion of tas)&= and
'ou can use the os_evt_set function to send the signal to tas)&. This e<amples uses .it &
@position 0A of the event flags to inform the other tas) when it completes.
tas)& must start & ms after tas)1 completes. "ou can use the same functions in tas)& to wait
and send signals to tas)1. The listing .elow shows all the statements re:uired to run the
e<ampleD
12
/ !ncl"de type and f"nction declarations for #$% /
&incl"de 'rtl.h'
/ id1, id2 (ill contain task identifications at r"n)time /
*+_$!, id1, id2;
/ -or(ard declaration of tasks. /
__task void task1 (void);
__task void task1 (void){
/ *.tain o(n system task identification n"m.er /
id1 / os_tsk_self();
/ 0reate task2 and o.tain its task identification n"m.er /
id2 / os_tsk_create (task2, 0);
for (;;) {
/ ... place code for task1 activity here ... /
/ +i1nal to task2 that task1 has compelted /
os_evt_set(020003, id2);
/ 4ait for completion of task2 activity. /
/ 02---- makes it (ait (itho"t timeo"t. /
/ 020003 represents .it 2. /
os_evt_(ait_or(020003, 02----);
/ 4ait for 50 ms .efore restartin1 task1 activity. /
os_dly_(ait(5);
}
}
for (;;) {
/ 4ait for completion of task1 activity. /
/ 02---- makes it (ait (itho"t timeo"t. /
/ 020003 represents .it 2. /
os_evt_(ait_or(020003, 02----);
/ 4ait for 20 ms .efore startin1 task2 activity. /
os_dly_(ait(2);
/ ... place code for task2 activity here ... /
/ +i1nal to task1 that task1 has compelted /
os_evt_set(020003, id1);
}
}
void main (void) {
/ +tart the #$% kernel, and then create and e2ec"te task1. /
os_sys_init(task1);
}
(. #inall'= to compile the code and lin) it with the $T% li.rar'= 'ou must select the $T% operating
s'stem for the proFect. #rom the main menu= select Project > Options for Target. Select
the Target ta.. Select $T% 2ernel for the Operating s'stem. 3uild the proFect to generate the
a.solute file. "ou can run the o.Fect file output from the lin)er either on 'our target or on the
L>ision Simulator.
13
Theory of Operation
$;-$T% E Theor' of Operation
The $T% )ernel uses and manages 'our target s'stemGs resources. This section descri.es the
resources and how the' are managed .' the $T% )ernel.
,an' aspects of the $T% )ernel can .e configured on a proFect .' proFect .asis. This is mentioned
where applica.le.
14
Timer Tick Interrupt
$;-$T% E Theor' of Operation E Timer Tic) *nterrupt
The $T% )ernel for !$,7B and !$,9B uses one of the standard !$, timers to generate a periodic
interrupt. $T% )ernel for /orte<B-, uses common S'sTic) timer. This interrupt is called the $T%
)ernel timer tic). #or some of the $T% li.rar' functions= 'ou must specif' timeouts and dela' intervals
in num.er of $T% )ernel timer tic)s.
The parameters for the $T% )ernel timer are selected in the RTX_Config.c configuration file. 7ach
!$, microcontroller famil' provides a different peripherals that are supported with different
RTX_Config.c files.
#or e<ample= the RTX_Config.c file for ?%P ;P/&1H;P/&& allows to use Timer or Timer 1 for
the $T% )ernel timer.
The timer clock value specifies the input cloc) fre:uenc' and depends on /P1 cloc) and !P3 cloc).
#or a device with /P1 cloc) 6 ,54 and >P3 divider ( the peripheral cloc) is 1+,54 and therefore the
value is set to 1+.
The time tick value specifies the interval of the periodic $T% interrupt. The value 1 us
configures timer tic) period of .1 seconds.
15
System Task Manager
$;-$T% E Theor' of Operation E S'stem Tas) ,anager
The tas) manager is a s'stem tas) that is e<ecuted on ever' timer tick interrupt. *t has the highest
assigned priorit' and does not get preempted. This tas) is .asicall' used to switch .etween user
tas)s.
The $T% tas)s are not reall' e<ecuted concurrentl'. The' are time-sliced. The availa.le /P1 time is
divided into time slices and the $T% )ernel assigns a time slice to each tas). Since the time slice is
short @default time slice is set to 1 msA it appears as though tas)s e<ecute simultaneousl'.
Tas)s e<ecute for the duration of their time-slice unless the tas)Gs time-slice is given up e<plicitl' .'
calling the os_tsk_pass or one of the wait li.rar' functions. Then the $T% 2ernel switches to the
ne<t tas) that is read' to run. "ou can set the duration of the time-slice in the RTX_Config .c
configuration file.
The task manager is the s'stem tic) timer tas) that manages all other tas)s. *t handles the tas)Gs
dela' timeouts and puts waiting tas)s to sleep. 9hen the re:uired event occurs= it puts the waiting
tas)s .ac) again into the read' state. This is wh' the tic) timer tas) must have the highest priorit'.
The tas) manager runs not onl' when the timer tic) interrupt occurs= .ut also when an interrupt calls
one of the isr_ functions. This is .ecause interrupts cannot ma)e the current tas) wait= and therefore
interrupts cannot perform tas) switching. 5owever= interrupts can generate the event= semaphore or
mail.o< message @using an isr_ li.rar' functionA that a higher priorit' tas) is waiting for. The higher
priorit' tas) must preempt the current tas)= .ut can do so onl' after the interrupt function completes.
The interrupt therefore forces the timer tic) interrupt= which runs when the current interrupt finishes.
The forced tic) timer interrupt starts the task manager @cloc) tas)A scheduler. The tas) scheduler
process all the tas)s and then puts the highest read' tas) into the running state. The highest priorit'
tas) can then continue with its e<ecution.
Note
The tic) timer tas) is an $T% s'stem tas) and is therefore created .' the s'stem.
The $T% li.rar' for Cortex"-M uses e<tended $TOS features of /orte<B-, devices. !ll $T%
s'stem functions are e<ecuted in svc mode.
16
Task Management
$;-$T% E Theor' of Operation E Tas) ,anagement
7ach $T% tas) is alwa's in e<actl' one state= which tells the disposition of the tas).
State Description
RUNNING The tas) that is currentl' running is in the RUNNING state. Onl' one tas) at a time
can .e in this state. The os_tsk_self() returns the Tas) *D @T*DA of the currentl'
e<ecuting tas).
READY Tas)s which are read' to run are in the READY state. Once the running tas) has
completed processing= $T% selects the ne<t read' tas) with the highest priority and
starts it.
WAIT_DLY Tas)s which are waiting for a dela' to e<pire are in the WAIT_DLY State. Once the
dela' has e<pired= the tas) is switched to the READY state. The os_dly_wait()
function is used to place a tas) in the WAIT_DLY state.
WAIT_ITV Tas)s which are waiting for an interval to e<pire are in the WAIT_ITV State. Once the
interval dela' has e<pired= the tas) is switched .ac) to the READY State. The
os_itv_wait() function is used to place a tas) in the WAIT_IVL State.
WAIT_OR Tas)s which are waiting for at least one event flag are in the WAIT_OR State. 9hen
the event occurs= the tas) is switched to the READY state. The os_evt_wait_or()
function is used to place a tas) in the WAIT_OR state.
WAIT_AND Tas)s which are waiting for all the set events to occur are in the WAIT_AND state.
9hen all event flags are set= the tas) is switched to the READY state. The
os_evt_wait_and() function is used to place a tas) in the WAIT_AND state.
WAIT_SEM Tas)s which are waiting for a semaphore are in the WAIT_SEM state. 9hen the to)en
is o.tained from the semaphore= the tas) is switched to the READY state. The
os_sem_wait() function is used to place a tas) in the WAIT_SEM state.
WAIT_MUT Tas)s which are waiting for a free mute< are in the WAIT_MUT state. 9hen a mute<
is released= the tas) ac:uire the mute< and switch to the $7!D" state. The
os_mut_wait() function is used to place a tas) in the WAIT_MUT state.
WAIT_MBX Tas)s which are waiting for a mail.o< message are in the WAIT_MBX state. Once the
message has arrived= the tas) is switched to the READY state. The os_mbx_wait()
function is used to place a tas) in the WAIT_MBX state.
Tas)s waiting to send a message when the mail.o< is full are also put into the
WAIT_MBX state. 9hen the message is read out from the mail.o<= the tas) is
switched to the READY state. *n this case the os_mbx_send() function is used to
place a tas) in the WAIT_MBX state.
INACTIVE Tas)s which have not .een started or tas)s which have .een deleted are in the
INACTIVE state. The os_tsk_delete() function places a tas) that has .een started
@with os_tsk_create()A into the INACTIVE state.
17
Idle Task
$;-$T% E Theor' of Operation E *dle Tas)
9hen no tas) is read' to run= the $T% )ernel e<ecutes the idle tas) os_idle_demon. The idle tas) is
simpl' an endless loop. #or e<ampleD
for (;;);
!$, devices provide an idle mode that reduces power consumption .' halting program e<ecution
until an interrupt occurs. *n this mode= all peripherals= including the interrupt s'stem= still continue to
wor).
The $T% )ernel initiates idle mode in the os8idle8demon tas) @when no other tas) is read' for
e<ecutionA. 9hen the $T% )ernel timer tick interrupt @or an' other interruptA occurs= the
microcontroller resumes program e<ecution.
"ou can add 'our own code to the os8idle8demon tas). The code e<ecuted .' the idle tas) can .e
configured in the RTX_Config.c configuration file.
Note
The idle tas) os_idle_demon is an $T% )ernel s'stem tas) and is therefore created .' the s'stem.
Do not use idle mode if 'ou are using the OT!N interface for de.ugging. Some !$, devices ma'
stop communicating over the OT!N interface when idle.
18
System Resources
$;-$T% E Theor' of Operation E S'stem $esources
$T% )ernel tas)s are identified .' their Tas) /ontrol 3loc) @T/3A. This is a d'namicall' allocated .loc)
of memor' where all tas) control and status varia.les are located. T/3 is allocated at runtime when
the tas) is created with the os_tsk_create or os_tsk_create_user function call.
The si4e of the T/3 memor' pool is defined in the RTX_Config.c configuration file= and it depends on
the num.er of concurrent running tas)s. This is not necessaril' the num.er of defined tas)s since
multiple instances of a tas) are supported .' the $T% )ernel.
The $T% )ernel also allocates the tas) its own stack. The stac) is allocated at runtime after the T/3
has .een allocated. The pointer to the stac) memor' .loc) is then written into the T/3.
19
Scheduling Options
$;-$T% E Theor' of Operation E Scheduling Options
$T% allows 'ou to .uild an application with three different )ernel-scheduling options. These areD
Pre-emptive scheduling
7ach tas) has a different priority and will run until it is pre-empted or has reached a .loc)ing OS
call.
Round-Robin scheduling
7ach tas) has the same priority and will run for a fi<ed period= or time slice= or until has reached a
.loc)ing OS call.
Co-operative multi-tasking
7ach tas) has the same priority and the $ound-$o.in is disa.led. 7ach tas) will run until it
reached a .loc)ing OS call or uses the os_tsk_pass() call.
The default scheduling option for $T% is $ound-$o.in Pre-emptive. #or most applications= this is the
most useful option.
20
Pre-emptive Scheduling
$;-$T% E Theor' of Operation E Scheduling Options E Pre-emptive Scheduling
$T% is a pre-emptive multitas)ing operating s'stem. *f a tas) with a higher priorit' than the
currentl' running tas) .ecomes read' to run= $T% suspends the currentl' running tas).
! preemptive tas) switch occurs whenD
the tas) scheduler is e<ecuted from the s'stem tick timer interrupt. Tas) scheduler processes the
delays of tas)s. *f the dela' for a tas) with a higher priorit' has e<pired= then the higher priorit'
tas) starts to e<ecute instead of currentl' running tas).
an event is set for a higher priorit' tas) .' the currentl' running tas) or .' an interrupt service
routine. The currentl' running tas) is suspended= and the higher priorit' tas) starts to run.
a to)en is returned to a semaphore= and a higher priorit' tas) is waiting for the semaphore to)en.
The currentl' running tas) is suspended= and the higher priorit' tas) starts to run. The to)en can
.e returned .' the currentl' running tas) or .' an interrupt service routine.
a mutex is released and a higher priorit' tas) is waiting for the mute<. The currentl' running tas)
is suspended= and the higher priorit' tas) starts to run.
a message is posted to a mailbox= and a higher priorit' tas) is waiting for the mail.o< message.
The currentl' running tas) is suspended= and the higher priorit' tas) starts to run. The message
can .e posted .' the currentl' running tas) or .' an interrupt service routine.
a mailbox is full= and a higher priorit' tas) is waiting to post a message to a mail.o<. !s soon as
the currentl' running tas) or an interrupt service routine ta)es a message out from the mail.o<=
the higher priorit' tas) starts to run.
the priority of the currentl' running tas) is reduced. *f another tas) is read' to run and has a
higher priorit' than the new priorit' of the currentl' running tas)= then the current tas) is
suspended immediatel'= and the higher priorit' tas) resumes its e<ecution.
The following e<ample demonstrates one of the tas) switching mechanisms. Tas) Fo.1 has a higher
priorit' than tas) Fo.&. 9hen Fo.1 starts= it creates tas) Fo.& and then enters the os_evt_wait_or
function. The $T% )ernel suspends Fo.1 at this point= and Fo.& starts e<ecuting. !s soon as Fo.& sets
an event flag for Fo.1= the $T% )ernel suspends Fo.& and then resumes Fo.1. Tas) Fo.1 then
increments counter cnt1 and calls the os_evt_wait_or function= which suspends it again. The )ernel
resumes Fo.&= which increments counter cnt& and sets an event flag for Fo.1. This process of tas)
switching continues indefinitel'.
&incl"de 6rtl.h7
*+_$!, tsk1,tsk2;
int cnt1,cnt2;
__task void 8o.1 (void);
__task void 8o.1 (void) {
os_tsk_prio (2);
tsk1 / os_tsk_self ();
os_tsk_create (8o.2, 1);
(hile (1) {
os_evt_(ait_or (020001, 02ffff);
cnt199;
}
}
(hile (1) {
os_evt_set (020001, tsk1);
cnt299;
}
}
void main (void) {
os_sys_init (8o.1);
21
(hile (1);
}
22
Round-Robin Scheduling
$;-$T% E Theor' of Operation E Scheduling Options E $ound-$o.in Scheduling
$T% can .e configured to use $ound-$o.in ,ultitas)ing @or tas) switchingA. $ound-$o.in allows :uasi-
parallel e<ecution of several tas)s. Tas)s are not reall' e<ecuted concurrentl' .ut are time-sliced
@the availa.le /P1 time is divided into time slices and $T% assigns a time slice to each tas)A. Since the
time slice is short @onl' a few millisecondsA it appears as though tas)s e<ecute simultaneousl'.
Tas)s e<ecute for the duration of their time-slice @unless the tas)Gs time slice is given upA. Then= $T%
switches to the ne<t tas) that is ready to run and has the same priority. *f no other tas) with the
same priorit' is read' to run= the currentl' running tas) resumes it e<ecution. The duration of a time
slice can .e defined in the RTX_config.c configuration file.
The following e<ample shows a simple $T% program that uses $ound-$o.in ,ultitas)ing. The two
tas)s in this program are counter loops. $T% starts e<ecuting tas) 1= which is the function named
job1. This function creates another tas) called job2. !fter job1 e<ecutes for its time slice= $T%
switches to job2. !fter job2 e<ecutes for its time slice= $T% switches .ac) to job1. This process
repeats indefinitel'.
&incl"de 6rtl.h7
int co"nter1;
int co"nter2;
os_tsk_create (8o.2, 0); / 0reate task 2 and mark it as ready /
(hile (1) { / loop forever /
co"nter199; / "pdate the co"nter /
}
}
(hile (1) { / loop forever /
}
}
void main (void) {
os_sys_init (8o.1); / !nitiali:e #$% ;ernel and start task 1 /
for (;;);
}
Note
$ather than wait for a tas)Gs time slice to e<pire= 'ou can use one of the system wait functions or
the os_tsk_pass function to signal to the $T% )ernel that it can switch to another tas). The s'stem
wait function suspends the current tas) @changes it to the WAIT_xxx stateA until the specified
event occurs. The tas) is then changed to the READY state. During this time= an' num.er of other
tas)s can run.
23
Cooperative Multitasking
$;-$T% E Theor' of Operation E Scheduling Options E /ooperative ,ultitas)ing
*f 'ou disa.le $ound-$o.in ,ultitas)ing 'ou must design and implement 'our tas)s so that the' wor)
cooperatively. Specificall'= 'ou must call the s'stem wait function li)e the os_dly_wait() function
or the os_tsk_pass() function somewhere in each tas). These functions signal the $T% )ernel to
switch to another tas).
The following e<ample shows a simple $T% program that uses /ooperative ,ultitas)ing. The $T%
)ernel starts e<ecuting tas) 1. This function creates tas) &. !fter counter1 is incremented once= the
)ernel switches to tas) &. !fter counter& is incremented once= the )ernel switches .ac) to tas) 1. This
process repeats indefinitel'.
&incl"de 6rtl.h7
int co"nter1;
int co"nter2;
os_tsk_create (task2, 0); / 0reate task 2 and mark it as ready /
for (;;) { / loop forever /
os_tsk_pass (); / s(itch to <task2< /
}
}
for (;;) { / loop forever /
os_tsk_pass (); / s(itch to <task1< /
}
}
void main (void) {
os_sys_init(task1); / !nitiali:e #$% ;ernel and start task 1 /
for (;;);
}
The difference .etween the s'stem wait function and os8ts)8pass is that the s'stem wait function
allows 'our tas) to wait for an event= while os8ts)8pass switches to another read' tas) immediatel'.
Note
*f the ne<t read' tas) has a lower priorit' than the currentl' running tas)= then calling
os_tsk_pass does not cause a tas) switch.
24
Priority Inversion
$;-$T% E Theor' of Operation E Priorit' *nversion
The $T% $eal Time Operating s'stem emplo's a priorit'-.ased preemptive scheduler. The $T%
scheduler assings each tas) a uni:ue priorit' level. The scheduler ensures that of those tasks that are
ready to run= the one with the highest priorit' is alwa's the tas) that is actuall' running.
3ecause tas)s share resourcs= events outside the schedulerGs control can prevent the highest priorit'
read' tas) from running when it should. *f this happens= a critical deadline could .e missed= causing
the s'stem to fail. Priority inversion is the term of a scenario in which the highest-priorit' read'
tas) fails to run when it should.
Resource sharing
Tas)s need to share resources to communicate and process data. !n' time two or more tas)s share a
recource= such as a memor' .uffer or a serial port= one of them will usuall' have a higher priorit'. The
higher-priorit' tas) e<pects to .e run as soon as it is read'. 5owever= if the lower-priorit' tas) is using
their shared resource when the higher-priorit' tas) .ecomes read' to run= the higher-priorit' tas)
must wait for the lower-priorit' tas) to finish with it.
Priority inheritance
To prevent priorit' inversions= the $T% $eal Time OS emplo's a Priority inheritance method. The
lower-priorit' tas) inherit the priorit' of an' higher-priorit' tas) pending on a resource the' share.
#or a short time= the lower-priorit' tas) runs at a priorit' of a higher-priorit' pending tas). The
priorit' change ta)es place as soon as the high-priorit' tas) .egins to pend. 9hen the lower-priorit'
tas) stops using a shared resource= itGs priorit' level returns to normal.
The $T% mutex o.Fects @,utual 7<clusive ;oc) o.FectsA emplo' the Priorit' inheritance.
25
Stack Management
$;-$T% E Theor' of Operation E Stac) ,anagement
The Stac) ,anagement of the $T% )ernel is designed for optimal memor' usage. The $T% )ernel
s'stem needs one stac) space for the tas) that is currentl' in the RUNNING stateD
Local StackD stores parameters= automatic varia.les= and function return addresses. On the !$,
device= this stac) can .e an'where. 5owever= for performance reasons= it is .etter to use the on-
chip $!, for the local stac).
9hen a tas) switch occursD
the conte<t of the currentl' running tas) is stored on the local stac) of the current tas)
the stac) is switched to that of the ne<t tas)
the conte<t of the new tas) is restored
the new tas) starts to run.
The ;ocal Stac) also holds the tas) conte<t of waiting or read' tas)s.
The other stac) spaces need to .e configured from the !$, startup file. !ll tas)s run in user mode.
The tas) scheduler switches the userHs'stem mode stac) .etween tas)s. #or this reason= the default
user/system mode stack @which is defined in the startup fileA is used until the first tas) is created
and started. The default stac) re:uirements are ver' small= so it is optimal to set the userHs'stem
stac) in the startup file to 64 bytes.
26
User Timers
$;-$T% E Theor' of Operation E 1ser Timers
1ser Timers are simple timer .loc)s that count down on ever' s'stem timer tic). The' are
implemented as single shot timers. This means 'ou cannot pause and restart these timers. 5owever=
'ou can create and )ill the user timers d'namicall' at runtime. *f 'ou do not )ill a user timer .efore it
e<pires= the $T% )ernel calls the user provided call.ac) function= os_tmr_call()= and then deletes the
timer when it e<pires.
! timeout value is defined when the timer is created .' the os_tmr_create() function.
The $T% )ernel calls the call.ac) function with the argument info. The user provides this argument
when creating the user timer. The $T% )ernel stores the argument in the timer control .loc). 9hen
the timer e<pires= this argument is passed .ac) to the user in the os_tmr_call() function. *f the user
)ills the timer .efore the timeout value e<pires= the $T% )ernel does not call the call.ac) function.
"ou can customi4e the call.ac) function os_tmr_call() in the RTX_Config.c configuration file.
Note
The call.ac) function= os_tmr_call= is called from the s'stem tas) scheduler. *t is recommended to
ma)e 'our os_tmr_call() function as small and fast as possi.le .ecause the call.ac) function
blocks the $T% tas) scheduler for the length of time it e<ecutes.
The function os_tmr_call .ehaves the same wa' as standard interrupt functions. *t is allowed to
call the isr_ functions to set an event= send a semaphore= or send a message to other tas)s. "ou
cannot call the os_ li.rar' functions from os_tmr_call().
27
Interrupt Functions
$;-$T% E Theor' of Operation E *nterrupt #unctions
$T% can wor) with interrupt functions in parallel. 5owever= it is .etter to avoid *$6 nesting. Nood
programming techni:ues use short interrupt functions that send signals or messages to $TOS tas)s.
9ith this practice= interrupt nesting .ecomes unimportant. This avoids common pro.lems with nested
interrupts where the user mode stac) usage .ecomes unpredicta.le.
The following figure shows how interrupts should .e handled with tas)s in the $T% )ernel s'stem. !n
*$6 function can send a signal or message to start a high priorit' tas).
*nterrupt functions are added to an !$, application in the same wa' as in an' other non-$T%
proFects.
Note
The FIQ interrupts are never disa.led .' the $T% )ernel.
"ou cannot call the isr_ li.rar' functions from the FIQ interrupt function.
The following e<ample shows how to use interrupts with the $T% )ernel. The interrupt function=
ext0_int= sends an event to process_task and e<its. The tas) process_task processes the e<ternal
interrupt event. *n this e<ample= process_task is simple and onl' counts the num.er of interrupt
events.
&define =>$_;=? 020001
*+_$!, pr_task;
int n"m_ints;
/))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))
=2ternal 0 !nterr"pt +ervice #o"tine
)))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))/
void e2t0_int (void) __ir@ {
isr_evt_set (=>$_;=?, pr_task); / +end event to <process_task< /
=%$!A$ / 0201; / Bckno(led1e !nterr"pt /
>!0>ectBddr / 0;
}
/))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))
$ask <process_task<
)))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))/
__task void process_task (void) {
n"m_ints / 0;
(hile (1) {
os_evt_(ait_or (=>$_;=?, 02ffff);
n"m_ints99;
28
}
}
/))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))
$ask <init_task<
)))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))/
__task void init_task (void) {
C!A+=D1 E/ F020000000G; / =na.le =!A$0 /
C!A+=D1 H/ 0200000001;
=%$I*,= / 020G; / =d1e tri11ered lo)7hi transition /
=%$C*DB# / 020G;
pr_task / os_tsk_create (process_task, 100);
>!0>ectBddr13 / (JG2)eint0_int; / $ask started, =na.le interr"pts /
>!0>ect0ntl13 / 0220 H 13;
os_tsk_delete_self (); / $erminate this task /
}
29
Configuring RTX Kernel
$;-$T% E /onfiguring $T% 2ernel
The $T% )ernel is eas' to customi4e for each application 'ou create. This section descri.es how 'ou
can configure the $T% )ernelGs features for 'our applications. *t containsD
3asic $T% /onfiguration
!dvanced $T% /onfiguration .
30
Basic RTX Configuration
$;-$T% E /onfiguring $T% 2ernel E 3asic $T% /onfiguration
The $T% )ernel must .e configured for the em.edded applications 'ou create. !ll configuration
settings are found in the RTX_Config.c file= which is located in the \Keil\ARM\Startup director'.
RTX_Config.c is configured differentl' for the different !$, devices. /onfiguration options in
RTX_Config.c allow 'ou toD
Specif' the num.er of concurrent running tas)s
Specif' the num.er of tas)s with user-provided stac)
Specif' the stac) si4e for each tas)
7na.le or disa.le the stac) chec)ing
7na.le or disa.le running tas)s in privileged mode
Specif' the /P1 timer num.er used as the s'stem tic) timer
Specif' the input cloc) fre:uenc' for the selected timer
Specif' the timer tic) interval
7na.le or disa.le the round-ro.in tas) switching
Specif' the time slice for the round-ro.in tas) switching
Define idle tas) operations
Specif' the num.er of user timers
Specif' code for the user timer call.ac) function
Specif' the #*#O 6ueue si4e
Specif' code for the runtime error function
There is no default configuration in the $;-$T% li.rar'. 5ence= 'ou must add the RTX_Config.c
configuration file to each proFect 'ou create.
To customi4e the $T% )ernelGs features= 'ou must change the configura.le settings in RTX_Config.c.
31
Tasks
$;-$T% E /onfiguring $T% 2ernel E 3asic $T% /onfiguration E Tas)s
The following #define@sA specif' how the $T% )ernel tas)s are configuredD
OS_TASKCNT specifies the ma<imum num.er of tas)s that can .e active at the same time. This
includes tas)s in an' state @running= waiting= or read'A other than the *?!/T*>7 state.
This information is used .' the $T% )ernel to reserve the memor' pool for the tas) control
varia.les. This num.er can .e higher than the num.er of defined tas)s in 'our application @one tas)
can run in multiple instancesA or lower if it is guaranteed that the num.er of created and running
tas)s will never e<ceed OS8T!S2/?T.
&define *+_$B+;0A$ K
OS_PRIVCNT specifies the num.er of tas)s with user-provided stac).
3' default= the $T% )ernel allocates a fi<ed si4e stac) to each tas). 5owever= the stac) re:uirement
can var' widel' .etween tas)s. #or e<ample= if a tas)Gs local varia.les include large .uffers= arra's=
or comple< structures= then the tas) re:uires a lot more stac). *f such a tas) tries to use more
stac) than the allocated stac)= it might overwrite the stac) of neigh.oring tas)s. This is .ecause the
fi<ed si4e stac)s of the tas)s are part of the common s'stem stac) and are contiguous. This leads to
malfunctioning of the $T% )ernel and is li)el' to cause a system crash. !n intuitive solution to this
pro.lem is to increase the fi<ed stac) si4e. 5owever= this increases the stac) si4e of ever' other
tas) that might not need the e<tra stac). To avoid this wastage of valua.le resource= a .etter
solution is to allocate a separate user-provided stac) for tas)s that re:uire a lot more stac).
The term user-provided= in this case= means that the memor' space for the tas)Gs stac) is
provided .' the user when the task is created. *t is not automaticall' assigned .' the )ernel. The
$T% )ernel uses OS8P$*>/?T to optimize the memor' usage. The )ernel will not reserve stac)
space for the tas)s with a user-provided stac).
&define *+_C#!>0A$ 0
Note
*n addition to OS8T!S2/?T user tas)s= the s'stem creates one s'stem tas) os_idle_demon. This
tas) is alwa's re:uired .' the $T% )ernel. Total num.er of concurrent running tas)s is
OS_TASKCNT+1 @num.er of user tas)s plus one s'stem tas)A.
32
Stack Size
$;-$T% E /onfiguring $T% 2ernel E 3asic $T% /onfiguration E Stac) Si4e
The stack usage of a particular tas) depends on its amount of local automatic varia.les and the
num.er of su.routine levels. *nterrupt functions do not use the stac) of the interrupted tas).
OS_STKSIZE specifies the amount of $!, allocated for the stac) of each tas). Stac) si4e is defined
in 10& @unsigned intA. 5owever= /onfiguration 9i4ard converts the specified si4e and displa's it in
.'tes. Stac) si4e with the following define is ( .'tes.
&define *+_+$;+!L= 100
On the full conte<t tas) switch= the $T% )ernel stores all !$, registers on the stac). #ull tas)
conte<t storing re:uires 64 bytes of stac).
Note
The Cortex-M4 with 5ardware #loating Point= needs additional 136 bytes on stac) for storing >#P
registers. This means the total si4e of the full conte<t store for /orte<-,( with #P is 200 bytes.
The Cortex-M4 tas)s= where the #loating Point arithmetics is not used= do not store the additional
>#P registers on conte<t save. This means= the' do not need additional 106 .'tes on the stac). The
full conte<t store for tas)s with no #loating Point calculations is still 64 bytes.
33
Stack Checking
$;-$T% E /onfiguring $T% 2ernel E 3asic $T% /onfiguration E Stac) /hec)ing
*t is possi.le that the stac) is e<hausted .ecause of man' nested su.routine calls or an e<tensive use
of large automatic varia.les.
*f Stac) /hec)ing is ena.led= the )ernel can detect the stac) e<haustion pro.lem and e<ecute the
system error function. The application will hang in an endless loop inside the error function with
parameter err_code set to OS_ERR_STK_OVF. "ou can identif' the tas) id with isr_tsk_get()
function. /hec) the Active Tasks de.ug dialog for the tas) name.
The solution to this pro.lem is to increase the stac) si4e for all tas)s in the configuration file. *f onl'
one tas) re:uires a .ig stac) and $!, is limited= 'ou can create this tas) with a user-provided stac)
space.
OS_STKCHECK ena.les the Stac) /hec)ing algorithm. *t must .e set to 1 to ena.le it or 0 to
disa.le it. *t is ena.led .' default.
&define *+_+$;0M=0; 1
Note
7na.led Stac) /hec)ing slightl' decreases the )ernel performance .ecause on ever' tas) switch
the )ernel needs to e<ecute additional code for stac) chec)ing.
On stac) overflow a runtime system error function is called.
34
Run in Privileged Mode
$;-$T% E /onfiguring $T% 2ernel E 3asic $T% /onfiguration E $un in Privileged ,ode
$T% ;i.rar' version for Cortex"-M devices allows to select the running mode of all user tas)s. 1ser
tas)s ma' run in two modesD
Unprivileged - Protected mode or
Privileged - 1nprotected mode.
*n privileged mode user ma' access and configure the s'stem and control registers li)e ?>*/
interrupt controller etc. This is however not allowed from unprivileged mode. !n access to ?>*/
registers from unprivileged mode will result in 5ard #ault.
OS_RUNPRIV ena.les running of all tas)s in Privileged mode. *t must .e set to 1 to ena.le it or 0
to disa.le it. *t is disa.led .' default.
&define *+_#JAC#!> 1
"ou can ena.le the privileged mode for old proFects. The e<isting code will run without an'
modifications when $T%8/onfig.c configuration file is replaced with a new one and a proFect is
recompiled for a new /orte<B-, $T% 2ernel li.rar'. Tas)s are not protected in privileged mode and
'ou ma' configure the s'stem for e<ample the interrupts from an' tas).
Privileged mode is disa.led .' default. This allows all tas)s to run in protected mode. The tas)s are
not allowed to change s'stem settings= change interrupts etc. The user has two optionsD
run the configuration code in privileged mode as __svc function from the tas)
run the configuration code .efore the )ernel is started when the device is still running in privileged
mode.
Note
The $T% 2ernel li.rar' for ARM7"/ARM9" does not allow this option .ecause of a different
concept.
35
Hardware Timer
$;-$T% E /onfiguring $T% 2ernel E 3asic $T% /onfiguration E 5ardware Timer
The following #defines specif' how the $T% )ernelGs hardware timer is configuredD
OS_TIMER specifies the on-chip timer used as a time-.ase for the real-time s'stem. *t delivers a
periodic interrupt that wa)es up a time-)eeping s'stem tas). The user can choose which timer
serves this purpose. 1se for Timer = or 1 for Timer 1.
&define *+_$!I=# 1
OS_CLOCK specifies the input cloc) fre:uenc' for the selected timer. This value is calculated asD
f@<talA H >P3D*>. 7<ample is for 1+ ,54 at M 6 ,54 /P1 cloc) and >P3D*> P (
&define *+_0D*0; 15000000
OS_TICK specifies the timer tic) interval in Lsec. $ecommended values are 1 to 1. The
resulting interval is from 1 ms to 1 ms. Default configuration is for 1 ms.
&define *+_$!0; 10000
Note
5ardware Timer configuration is re:uired onl' for ARM7" and ARM9" $T% ;i.rar' version.
TheCortex"-M version uses a common SysTick timer for all /orte<B-, device variants.
36
Round-Robin Multitasking
$;-$T% E /onfiguring $T% 2ernel E 3asic $T% /onfiguration E $ound-$o.in ,ultitas)ing
The following #define specif' how the $T% )ernel Round-Robin Multitasking is configuredD
OS_ROBIN ena.les the $ound-$o.in ,ultitas)ing. *t must .e set to 1 to ena.le it or 0 to disa.le it.
*t is ena.led .' default.
&define *+_#*N!A 1
OS_ROBINTOUT specifies the $ound-$o.in Timeout. This is the time-slice assigned to the
currentl' running tas). !fter this time-slice e<pires= the currentl' running tas) is suspended and the
ne<t tas) read' to run is resumed. *t is specified in num.er of s'stem timer tic)s.
&define *+_#*N!A$*J$ 5
37
User Timers
$;-$T% E /onfiguring $T% 2ernel E 3asic $T% /onfiguration E 1ser Timers
"ou can create and )ill user timers at runtime. "ou must specif' the ma<imum num.er of running
user timers and also the code for the os_tmr_call@A function.
OS_TIMERCNT specifies the num.er of user timers that can .e created and started. *f user timers
are not used= set this value to . This information is used .' $T% to reserve the memor' resources
for timer control .loc)s.
&define *+_$!I=#0A$ 5
The callback function os_tmr_call() is called when the user timer e<pires. *t is provided in the
RTX_Config.c configuration file as an empt' function. "ou must modif' it to suit 'our needs.
Parameter info is the parameter passed to the os_tmr_create() function when the timer was
created.
/))))))))))))))))))))))))))) os_tmr_call )))))))))))))))))))))))))))))))))))/
void os_tmr_call (J1K info) {
/ $his f"nction is called (hen the "ser timer has e2pired. /
/ Carameter 'info' is the parameter defined (hen the timer (as created. /
/ M=#=O incl"de here optional "ser code to .e e2ec"ted on timeo"t. /
info / info;
}
38
FIFO Queue Buffer
$;-$T% E /onfiguring $T% 2ernel E 3asic $T% /onfiguration E #*#O 6ueue 3uffer
The isr_ li.rar' function= when called from the interrupt handler= stores the re:uest t'pe and optional
parameter to the ISR FIFO Queue buffer to .e processed later= after the interrupt handler e<its.
The task manager is activated immediatel' after the *$6 handler has finished its e<ecution to
process the re:uests stored to the #*#O 6ueue .uffer. The si4e of this .uffer needed= depends on the
num.er of isr8 functions= that are called within the interrupt handler.
#or e<ample= if there is onl' one interrupt handler in 'our proFect and calls one isr_evt_set()= the
#*#O 6ueue .uffer si4e of ( entries is sufficient. *f there are more interrupts used in the proFect that
use the isr8 communication with $T% )ernel or= one interrupt handler that calls several isr8 li.rar'
functions= the #*#O 6ueue .uffer si4e needs to .e increased. The interrupts= that do not use isr8
li.rar' functions are not counted here.
Default #*#O 6ueue .uffer si4e is 16 entries. This should .e enough for a t'pical $T% proFect.
OS_FIFOSZ specifies the num.er of entries that can .e stored to the #*#O 6ueue .uffer. Default
si4e is 16 entries.
&define *+_-!-*+L 1K
Note
On #*#O 6ueue .uffer overflow a runtime system error function is called.
See the Rtx_Config.c configuration file for the possi.le configuration settings.
39
Error Function
$;-$T% E /onfiguring $T% 2ernel E 3asic $T% /onfiguration E 7rror #unction
Some s'stem error conditions can .e detected during runtime. *f $T% )ernel detects a runtime error=
it calls the os_error() runtime error function.
void os_error (JG2 err_code) {
/ $his f"nction is called (hen a r"ntime error is detected. /
*+_$!, err_task;
s(itch (err_code) {
case *+_=##_+$;_*>-O
/ !dentify the task (ith stack overflo(. /
err_task / isr_tsk_1et();
.reak;
case *+_=##_-!-*_*>-O
.reak;
case *+_=##_IN%_*>-O
.reak;
}
for (;;);
}
The error code is passed to this function as a parameter err_codeD
7rror /ode Description
OS87$$8ST28O># The stac) chec)ing has detected a stac) overflow for the currentl' running tas).
OS87$$8#*#O8O># The *S$ #*#O 6ueue .uffer overflow is detected.
OS87$$8,3%8O># The mail.o< overflow is detected for isr8m.<8send@A function.
The runtime error function must contain an infinite loop to prevent further program e<ecution. "ou
can use an emulator to step over infinite loop and trace into the code introducing a runtime error. #or
the overflow errors this means 'ou need to increase the si4e of the o.Fect causing an overflow.
$;-!$,D T$!?S*T*O? #$O, OS8ST28O>7$#;O9@A TO OS87$$O$@A
$;-!$,D 7$$O$D ;6&187D 1?D7#*?7D S",3O; OS87$$O$
40
Idle_Task
$;-$T% E /onfiguring $T% 2ernel E 3asic $T% /onfiguration E *dle Tas)
9hen no tas)s are read' to run= the $T% )ernel e<ecutes the idle tas) with the name
os_idle_demon(). 3' default this tas) is an empt' end-less loop that does nothing. *t onl' waits
until another tas) .ecomes read' to run.
"ou ma' change the code of os_idle_demon() to put the /P1 into a power-saving or idle mode.
,ost RTX_Config.c files define the macro 8idle8@A that contains the code to put the /P1 into a
power-saving mode.
Example:
/))))))))))))))))))))))))))) os_idle_demon )))))))))))))))))))))))))))))))))/
__task void os_idle_demon (void) {
/ $he idle demon is a system task. !t is r"nnin1 (hen no other task is /
/ ready to r"n (idle sit"ation). !t m"st not terminate. $herefore it /
/ sho"ld contain at least an endless loop. /
for (;;) {
_idle_(); / enter lo()po(er mode /
}
}
Note
On some devices= the *D;7 .loc)s de.ugging via the OT!N interface. Therefore OT!N de.uggers
such as 1;*?2 ma' not wor) when 'ou are using /P1 power-saving modes.
#or using power-saving modes= some devices ma' re:uire additional configuration @such as cloc)
configuration settingsA.
$;-!$,D 1S*?N *D;7 ,OD7 O? ST$9 9*T5 $T% 27$?7;
41
Advanced RTX Configuration
$;-$T% E /onfiguring $T% 2ernel E !dvanced $T% /onfiguration
$;-!$, provides several versions of the RTX_Config.c file for !$,7BH!$,9B $T% 2ernel li.rar'.
7ach one configures the $T% )ernel for a specific !$, device variant that $;-!$, supports. 5owever
the !$, famil' of devices is growing :uic)l'= and it is possi.le that $;-!$, does not contain the
configuration file for the device 'ou use. *n this case= 'ou can ta)e the RTX_Config.c file for the ?%P
device as a template and modif' it for 'our particular !$, device. This file is located in
the\Keil\ARM\Startup\Philips director'.
!ll hardware dependent definitions are e<tracted from the code and defined with macros. This ma)es
it possi.le to customi4e the configuration without modif'ing the code.
Note
$T% 2ernel li.rar' for /orte<B-, has onl' one configuration file which is common for all /orte<B-,
device variants.
42
HW Resources Required
$;-$T% E /onfiguring $T% 2ernel E !dvanced $T% /onfiguration E 59 $esources $e:uired
*n order to run the $T% )ernel= the following hardware resources are re:uired from an !$, deviceD
Peripheral Timer for generating periodic tic)s. *t is .etter to use a peripheral timer with an auto-
reload function. $T% also supports timers with manual timer @or counterA reload. 5owever= this can
generate Fitter and inaccurac' in the long run. The $T% )ernel needs a count-up timer. *f the timer
used is a count-down timer= 'ou need to convert the timer value.
Timer Interrupts to interrupt the e<ecution of a tas) and to start the s'stem tas) scheduler.
Forced Interrupts to force a timer interrupt when isr_ functions are used. *f an isr_ function is
called= the )ernel forces the timer interrupt immediatel' after the interrupt ends. The forced timer
interrupt activates the tas) scheduler. *t is possi.le that a tas) has .ecome read'. *f this tas) has a
higher priorit' than the currentl' running tas)= a tas) switch must occur.
43
Configuration Macros
$;-$T% E /onfiguring $T% 2ernel E !dvanced $T% /onfiguration E /onfiguration ,acros
!ll hardware related configuration options are descri.ed with configuration macros. Some of the
macros @for e<ample OS_TID_ and OS_TIM_A are used onl' to simplif' the code. The' are not used
in all of the configuration files. 1sing configuration macros allows eas' customi4ation of the
configuration for the different peripheral timers supported .' an !$, device.
The following configuration macros are introducedD
@e<amples are for Philips ;P/&1<< devices - Timer A
OS_TRV macro specifies the timer reload value for the peripheral timer. Peripheral timer counts up
to a reload value= then then overflows to = and then generates a tic) interrupt. The reload value
should .e calculated to generate the desired interval length @for e<ample 1 msA.
&define *+_$#> ((JG2)(((do".le)*+_0D*0;(do".le)*+_$!0;)/1=K))1)
OS_TVAL macro is used to read the current timer value for a count-up timer. The $T% )ernel uses
it to chec) whether a timer interrupt is a periodic timer interrupt or a software forced interrupt.
&define *+_$>BD $0$0 / $imer >al"e /
#or a countdown timer= 'ou must convert the return value. This is an e<ample for a 16-.it count-
down timerD
&define *+_$>BD (02---- ) $0>BD) / $imer >al"e /
OS_TOVF specifies a timer overflow flag. The $T% )ernel uses it together with the OS8T>!; macro
to differentiate .etween the periodic timer interrupts and forced timer interrupts.
&define *+_$*>- ($0!# E 1) / *verflo( -la1 /
OS_TREL() macro specifies a code se:uence to reload a peripheral timer on overflow. 9hen a
peripheral timer has an auto-reload functionalit'= this macro is left empt'.
&define *+_$#=D() ; / $imer #eload /
OS_TFIRQ() specifies a code se:uence to force a timer interrupt. This must .e a software
triggered interrupt if the peripheral timer does not allow manual setting of an overflow flag. *f
manual setting is possi.le= this macro should set a peripheral timer overflow flag= which will cause a
timer interrupt.
&define *+_$-!#P() >!0+oft!nt / *+_$!I_; / -orce !nterr"pt /
OS_TIACK() is used to ac)nowledge an interrupt from the timer interrupt function to release the
timer interrupt logic.
&define *+_$!B0;() $0!# / 1; / !nterr"pt Bck / Q
>!0+oft!nt0lr / *+_$!I_; Q
>!0>ectBddr / 0;
OS_TINIT() macro is used to initiali4e the peripheral timerHcounter= setup a timer mode= and set a
timer reload. Timer interrupts are also activated here .' ena.ling a peripheral timer interrupt. This
code is e<ecuted from the os_sys_init() function.
&define *+_$!A!$() $0I#0 / *+_$#>; / !nitiali:ation / Q
$0I0# / G; Q
$0$0# / 1; Q
>!0,ef>ectBddr / (JG2)os_def_interr"pt; Q
>!0>ectBddr15 / (JG2)os_clock_interr"pt; Q
>!0>ect0ntl15 / 0220 H *+_$!,_;
OS_LOCK() macro disa.les timer tic) interrupts. *t is used to avoid interrupting the s'stem tas)
scheduler. This macro should disa.le .oth the periodic timer interrupts and the forced interrupts.
This code is e<ecuted from the tsk_lock() function.
&define *+_D*0;() >!0!nt=n0lr / *+_$!I_; / $ask Dock /
44
OS_UNLOCK() macro ena.les the timer tic) interrupts. The code se:uence specified here should
ena.le the periodic timer interrupts and the forced interrupts. This code is e<ecuted from
tsk_unlock() function.
&define *+_JAD*0;() >!0!nt=na.le / *+_$!I_; / $ask Jnlock /
45
Library Files
$;-$T% E /onfiguring $T% 2ernel E ;i.rar' #iles
$;-$T% includes eleven li.rar' filesD
RTX_ARM_L.LIB for microcontrollers .ased on !$,7TD,*B and !$,9B - ;ittle 7ndian.
RTX_ARM_B.LIB for microcontrollers .ased on !$,7TD,*B and !$,9B - 3ig 7ndian.
RTX_CM1.LIB for microcontrollers .ased on /orte<B-, and /orte<B-,1 - ;ittle 7ndian.
RTX_CM1_B.LIB for microcontrollers .ased on /orte<B-, and /orte<B-,1 - 3ig 7ndian.
RTX_CM3.LIB for microcontrollers .ased on /orte<B-,0 - ;ittle 7ndian.
RTX_CM3_B.LIB for microcontrollers .ased on /orte<B-,0 - 3ig 7ndian.
RTX_CM3X.LIB for microcontrollers .ased on /orte<B-,0 without e<clusive access instructions
;D$7%HST$7%H/;$7% - ;ittle 7ndian.
RTX_CM4.LIB for microcontrollers .ased on /orte<B-,( - ;ittle 7ndian.
RTX_CM4_B.LIB for microcontrollers .ased on /orte<B-,( - 3ig 7ndian.
RTX_CR4.LIB for microcontrollers .ased on /orte<B-$( - ;ittle 7ndian.
RTX_CR4_B.LIB for microcontrollers .ased on /orte<B-$( - 3ig 7ndian.
!ll $;-!$, li.raries are located in the \Keil\ARM\RV31\LIB\ folder. Depending on the target device
selected for 'our proFect= the appropriate li.rar' file is automaticall' included into the lin) process
when the $T% )ernel operating s'stem is selected for 'our proFect.
The RTX_Lib_ARM.uvproj and RTX_Lib_CM.uvproj proFects found in the \Keil\ARM\RL\RTX\
folder are used to .uild the $;-$T% li.raries.
Note
"ou should not e<plicitl' include an' of the $;-$T% li.raries in 'our application. That is done
automaticall' when 'ou use the Vision IDE.
$;-!$,D *?/O,P;7T7 T!S2 ;*ST D*SP;!" 9*T5 3*N 7?D*!?
46
Using RTX Kernel
$;-$T% E 1sing $T% 2ernel
To use $T% 2ernel for !$,7BH!$,9B or /orte<B-, .ased applications= 'ou must .e a.le to
successfull' create $T% applications= compile and lin) them.
47
Writing Programs
$;-$T% E 1sing $T% 2ernel E 9riting Programs
9hen 'ou write programs for $;-$T%= 'ou can define $T% tas)s using the __task )e'word. "ou can
use the $T% )ernel routines whose protot'pes are declared in RTL.h.
48
Include Files
$;-$T% E 1sing $T% 2ernel E 9riting Programs E *nclude #iles
The $T% )ernel re:uires the use of onl' the RTL.h include file. !ll library routines and constants are
defined in this header file. "ou can include it in 'our source files as followsD
&incl"de 6rtl.h7
49
Defining Tasks
$;-$T% E 1sing $T% 2ernel E 9riting Programs E Defining Tas)s
$eal-Time or multitas)ing applications are composed of one or more tas)s that perform specific
operations. The $T% )ernel supports a ma<imum of &++ tas)s.
Tas)s are simpl' / functions that have a void return t'pe= have a void argument list= and are
declared using the __task function attri.ute. #or e<ampleD
__task void f"nc (void);
Where
func is the name of the tas).
The following e<ample defines the function tas)1 as a tas). This tas) increments a counter indefinitel'.
(hile (1) {
co"nter099;
}
}
Note
!ll tas)s must .e implemented as endless loops. ! tas) must never return.
The __task function attri.ute must prefix the tas) function declaration in $T% )ernel version 0.(
and newer.
50
Multiple Instances
$;-$T% E 1sing $T% 2ernel E 9riting Programs E ,ultiple *nstances
The $T% )ernel ena.les 'ou to run multiple copies of the same tas) at the same time. These are called
multiple instances of the same tas). "ou can simpl' create and run the same tas) several times.
This is often re:uired when 'ou design a protocol .ased stac) @li)e *SD? D channel stac)A.
The following e<ample shows 'ou how the function tas)& can run in multiple instances.
&incl"de 6rtl.h7
*+_$!, tsk_1, tsk2_1, tsk2_2, tsk2_G;
int cnt;
for (;;) {
os_dly_(ait (2);
cnt99;
}
}
/ $his task (ill create G instances of task2 /
tsk2_1 / os_tsk_create (task2, 0);
tsk2_2 / os_tsk_create (task2, 0);
tsk2_G / os_tsk_create (task2, 0);
/ $he 8o. is done, delete <task1< /
os_tsk_delete_self ();
}
void main (void) {
os_sys_init(task1);
for (;;);
}
Note
7ach instance of the same tas) must have a uni:ue tas) *D.
51
External References
$;-$T% E 1sing $T% 2ernel E 9riting Programs E 7<ternal $eferences
The semaphore and mailbox o.Fects are referenced .' the $T% )ernel as t'peless o.Fect pointers
and are t'pecast inside the specific $T% )ernel module. #or semaphores and tas) handles= this is not a
pro.lem. The pro.lem is when referencing the mail.o<= which is declared using the macro
os_mbx_declare(). That is wh' the OS_MBX t'pe is defined. "ou have to use the OS8,3% o.Fect
t'pe identifier to reference mail.o<es in e<ternal modules.
5ere is an e<ample of how the e<ternal $T% )ernel o.Fects are referencedD
e2tern *+_$!, tsk1;
e2tern *+_+=I semaphore1;
e2tern *+_IJ$ m"te21;
e2tern *+_IN% mail.o21;
The following e<ample shows 'ou how to ma)e a reference to a mailbox from a different /-module.
/-,odule with a mailbox1 declarationD
&incl"de 6rtl.h7
os_m.2_declare (mail.o21, 20);
void ms1;
os_m.2_init (mail.o21, si:eof (mail.o21));
ms1 / alloc();
/ set messa1e content here /
os_m.2_send (mail.o21, ms1);
..
}
/-,odule with a mailbox1 referenceD
&incl"de 6#$D.h7
e2tern *+_IN% mail.o21;
void ms1;
..
os_m.2_(ait (mail.o21, Ems1, 02ffff);
/ process messa1e content here /
free (ms1);
..
}
52
Using a Mailbox
$;-$T% E 1sing $T% 2ernel E 9riting Programs E 1sing a ,ail.o<
The $T% )ernel message o.Fects are simpl' pointers to a .loc) of memor' where the relevant
information is stored. There is no restriction regarding the message si4e or content. The $T% )ernel
handles onl' the pointer to this message.
Sending 8-bit, 16-bit, and 32-bit values
3ecause the $T% )ernel passes onl' the pointer from the sending tas) to the receiving tas)= we can
use the pointer itself to carr' simple information li)e passing a character from a serial receive
interrupt routine. !n e<ample can .e found in the serial.c interrupt driven serial interface module for
the Traffic example. "ou must cast the char to a pointer li)e in the following e<ampleD
os_m.2_send (send_m.2, (void )c, 02ffff);
Sending fixed size messages
To send fi<ed si4e messages= 'ou must allocate a .loc) of memor' from the d'namic memor' pool=
store the information in it= and pass its pointer to a mail.o<. The receiving tas) receives the pointer
and restores the original information from the memor' .loc)= and then releases the allocated memor'
.loc).
Fixed Memory block memory allocation functions
$T% has ver' powerful fixed memory block memor' allocation routines. The' are thread safe and
full' reentrant. The' can .e used with the $T% )ernel with no restriction. *t is .etter to use the fi<ed
memor' .loc) allocation routines for sending fi<ed si4e messages. The memor' pool needs to .e
properl' initiali4ed to the si4e of message o.FectsD
32-bit valuesD initiali4e to (-.'te .loc) si4e.
_init_.o2 (mpool, si:eof(mpool), 3);
any size messagesD initiali4e to the si4e of message o.Fect.
_init_.o2 (mpool, si:eof(mpool), si:eof(str"ct messa1e));
#or 8-.it and 16-.it messages= it is .etter to use a parameter casting and convert a message value
directl' to a pointer.
The following e<ample shows 'ou how to send fi<ed si4e messages to a mail.o< @see the mail.o<
e<ample for more informationA. The message si4e is 8 .'tes @two unsigned intsA.
&incl"de 6rtl.h7
os_m.2_declare (Is1No2, 1K); / ,eclare an #$% mail.o2 /
JG2 mpoolR1K(2si:eof(JG2))/3 9 GS; / #eserve a memory for 1K messa1es /
__task void rec_task (void);
__task void send_task (void) {
/ $his task (ill send a messa1e. /
JG2 mptr;
os_tsk_create (rec_task, 0);
os_m.2_init (Is1No2, si:eof(Is1No2));
mptr / _alloc_.o2 (mpool); / Bllocate a memory for the messa1e /
mptrR0S / 02G215fedc; / +et the messa1e content. /
mptrR1S / 0200000015;
os_m.2_send (Is1No2, mptr, 02ffff); / +end a messa1e to a <Is1No2< /
53
}
__task void rec_task (void) {
/ $his task (ill receive a messa1e. /
JG2 rptr, rec_valR2S;
os_m.2_(ait (Is1No2, Erptr, 02ffff); / 4ait for the messa1e to arrive. /
rec_valR0S / rptrR0S; / +tore the content to <rec_val< /
rec_valR1S / rptrR1S;
_free_.o2 (mpool, rptr); / #elease the memory .lock /
}
void main (void) {
_init_.o2 (mpool, si:eof(mpool), si:eof(JG2));
os_sys_init(send_task);
}
Sending variable size messages
To send a message o.Fect of varia.le si4e= 'ou must use the memor' allocation functions for the
varia.le si4e memor' .loc)s. The $>/T li.rar' provides these functions in stdlib.h
Note
The fixed block memor' allocation functions are fully reentrant. The variable length memor'
allocation functions are not reentrant. Therefore the s'stem timer interrupts need to .e disa.led
during the e<ecution of the malloc@A or free@A function. #unction tsk_lock() disa.les timer
interrupts and function tsk_unlock() ena.les timer interrupts.
54
SWI Functions
$;-$T% E 1sing $T% 2ernel E 9riting Programs E S9* #unctions
Software *nterrupt @S9*A functions are functions that run in Supervisor ,ode of ARM7" and ARM9"
core and are interrupt protected. S9* functions can accept arguments and can return values. The'
are used in the same wa' as other functions.
The difference is hidden to the user and is handled .' the $eal>iew /-compiler. *t generates different
code instructions to call S9* functions. S9* functions are called .' e<ecuting the S9* instruction.
9hen e<ecuting the S9* instruction= the controller changes the running mode to a Supervisor ,ode
and .loc)s an' further *$6 interrupt re:uests. ?ote that the #*6 interrupts are not disa.led in this
mode. 9hen the !$, controller leaves this mode= interrupts are ena.led again.
*f 'ou want to use S9* functions in 'our $T% )ernel proFect= 'ou need toD
1. /op' the SWI_Table.s file to 'our proFect folder and include it into 'our proFect.
This file is located in the \Keil\ARM\RL\RTX\SRC\ARM folder.
&. Declare a function with a __swi(x) attri.ute. 1se the first S9* num.er= starting from 8= that
is free.
void __s(i(T) inc_5.it (JG2 cp);
0. 9rite a function implementation and convert the function name into a __SWI_x function
name. This name is referenced later .' the lin)er from SWI_Table.s module.
void __+4!_T (JG2 cp) {
/ B protected f"nction to increment a 5).it co"nter. /
cp / (cp 9 1) E 021-;
}
(. !dd the function __SWI_x to the S9* function ta.le in the SWI_Table.s module.
#irst import it from other modulesD
; !mport "ser +4! f"nctions here.
!IC*#$ __+4!_T
then add a reference to it into the ta.leD
; !nsert "ser +4! f"nctions here. +4! 0..U are "sed .y #$D ;ernel.
,0, __+4!_T ; +4! T Jser -"nction
+. "our SWI function should now loo) li)e thisD
void __s(i(T) inc_5.it (JG2 cp);
void __+4!_T (JG2 cp) {
cp / (cp 9 1) E 021-;
}
Note
S9* functions 0..7 are reserved for the $T% )ernel.
Do not leave gaps when num.ering S9* functions. The' must occup' a continuous range of
num.ers starting from 8.
S9* functions can still .e interrupted .' FIQ interrupts.
$;-!$,D $T% 27$?7; ,OD7 1S7D *? !$, /P1
55
SVC Functions
$;-$T% E 1sing $T% 2ernel E 9riting Programs E S>/ #unctions
Software *nterrupt @S>/A functions are functions that run in Privileged 5andler ,ode of Cortex"-M
core. S>/ functions can accept arguments and can return values. The' are used in the same wa' as
other functions.
The difference is hidden to the user and is handled .' the $eal>iew /-compiler. *t generates different
code instructions to call S>/ functions. S>/ functions are called .' e<ecuting the S>/ instruction.
9hen e<ecuting the S>/ instruction= the controller changes the running mode to a Privileged 5andler
,ode.
*nterrupts are not disabled in this mode. *n order to protect S>/ function from interrupts= 'ou need
to include the disa.leHena.le intrinsic functions __disable_irq() and __enable_irq() in 'our code.
"ou ma' use S>/ functions to access protected peripherals= for e<ample to configure ?>*/ and
interrupts. This is re:uired if 'ou run tas)s in unprivileged @protectedA mode and 'ou need to change
interrupts from the tas).
*f 'ou want to use S>/ functions in 'our $T% )ernel proFect= 'ou need toD
1. /op' the SVC_Table.s file to 'our proFect folder and include it into 'our proFect.
This file is located in the \Keil\ARM\RL\RTX\SRC\CM folder.
&. Declare a function with a __svc(x) attri.ute. 1se the first S>/ num.er= starting from 1= that
is free.
void __svc(1) inc_5.it (JG2 cp);
0. 9rite a function implementation and convert the function name into a __SVC_x function
name. This name is referenced later .' the lin)er from SVC_Table.s module. "ou need also to
disa.leHena.le interrupts.
void __+>0_1 (JG2 cp) {
__disable_irq();
cp / (cp 9 1) E 021-;
__enable_irq();
}
(. !dd the function __SVC_x to the S>/ function ta.le in the SVC_Table.s module.
#irst import it from other modulesD
; !mport "ser +>0 f"nctions here.
!IC*#$ __+>0_1
then add a reference to it into the ta.leD
; !nsert "ser +>0 f"nctions here. +>0 0 "sed .y #$D ;ernel.
,0, __+>0_1 ; "ser +>0 f"nction
+. "our SVC function should now loo) li)e thisD
void __svc(1) inc_5.it (JG2 cp);
void __+>0_1 (JG2 cp) {
__disable_irq();
cp / (cp 9 1) E 021-;
__enable_irq();
}
Note
S>/ function 0 is reserved for the $T% )ernel.
Do not leave gaps when num.ering S>/ functions. The' must occup' a continuous range of
num.ers starting from 1.
56
S>/ functions can still .e interrupted.
$T% must .e initialized .efore S>/ functions are called.
57
Debugging
$;-$T% E 1sing $T% 2ernel E De.ugging
The L>ision Simulator allows 'ou to run and test 'our $T% )ernel applications. $T% )ernel applications
load Fust li)e non-$T% programs. ?o special commands or options are re:uired for de.ugging.
! kernel-aware dialog displa's all aspects of the RTX kernel and the tas)s in 'our program. The
simulator can .e used also with 'our target hardware= if 'ou are using a 1;*?2 OT!N interface on 'our
target= to de.ug 'our application.
Note
"ou can have source level debugging if 'ou enter the following S7T varia.le into the de.uggerD
+=$ +#0/0OQ;eilQB#IQ#DQ#$%Q+#0
58
System Info
$;-$T% E 1sing $T% 2ernel E De.ugging E S'stem *nfo
Neneral information a.out the s'stem resources and tas) usage is displa'ed .' e<panding the
System propert' in the RTX Tasks and System dialog. "ou can use it to optimi4e 'our $T%
application.
Select RTX Tasks and System from the OS Support item in the Debug menu to displa' this dialog.
59
Task Info
$;-$T% E 1sing $T% 2ernel E De.ugging E Tas) *nfo
Detailed information a.out each running tas) is displa'ed when 'ou e<pand the Tasks propert' in the
RTX Tasks and System dialog. ?ote that one tas) can run in multiple instances. !ll active tas)s are
listed in this dialog.
Select RTX Tasks and System from the OS Support item in the Debug menu to displa' this dialog.
ID is the Tas) *dentification >alue assigned when the tas) was started.
Name is the name of the tas) function.
Priority is the current tas) priorit'.
State is the current state of the task.
Delay is the dela' timeout value for the tas).
Event Value specifies the event flags set for the tas).
Event Mask specifies the event flags mas) for the events that the tas) is waiting for.
Stack Load specifies the usage of the tas)Gs stack.
L>*S*O? D731NN7$D D*SP;!"*?N $T% 27$?7; >*797$
60
Event Viewer
$;-$T% E 1sing $T% 2ernel E De.ugging E 7vent >iewer
The 7vent >iewer displa's a chronological histor' of tas)-switching events allowing to e<amine when
tas)s e<ecuted and for how long.
Select Debug - OS Support - Event Viewer to displa' this window.
61
Usage Hints
$;-$T% E 1sing $T% 2ernel E 1sage 5ints
5ere are a few hints to help 'ou if 'ou run into pro.lems when using the $T% )ernel.
Function usage
#unctions that .egin with os_ can .e called from a tas) .ut not from an interrupt service routine.
#unctions that .egin with isr_ can .e called from an IRQ interrupt service routine .ut not from a
tas).
?ever call isr_ functions from FIQ @!$,7B= !$,9BA interrupt functions or from the tas).
?ever call tsk_lock() or tsk_unlock() from an interrupt function.
3efore the )ernel starts= never ena.le an' IRQ interrupt that calls isr_ functions.
3ecause of a two different implementations of $T% 2ernel ;i.rar' further hints depend on the ;i.rar'
version .eing usedD
ARM7"/ARM9" Version
Cortex"-M Version
62
ARM Version
$;-$T% E 1sing $T% 2ernel E 1sage 5ints E !$, >ersion
5ere are a few hints specific for !$,7BH!$,9B li.rar' version.
Using IRQ interrupts
"ou can use IRQ interrupts with no limitation. $T% )ernel uses onl' one timer interrupt to generate
periodic timer ticks and activate the tas) scheduler.
IRQ interrupts are disa.led .' $T% for a ver' short time @a few Lseconds ma<imumA.
$T% )ernel uses Software Interrupts to protect a critical code section from interrupts.
Software interrupts 0-7 are used .' $T% and cannot .e used in 'our application.
$T% uses its own SWI Handler which is automaticall' lin)ed from the li.rar'. *f 'ou include another
S9* handler @li)e that found in the SWI.S fileA into 'our proFect= $T% could fail. $emove an' user-
created S9* handler from 'our proFect to resolve the Data !.ort.
/hec) the IRQ stack size configured from the startup file if 'ou see sporadic crashes of 'our
application. The *$6 stac) usage depends on the comple<it' of 'our additional interrupt functions.
Using FIQ interrupts
!$,7BH!$,9B #ast *nterrupts are not used .' the $T% )ernel. "ou ma' freel' use FIQ interrupts in
'ou application in parallel with the )ernel.
FIQ interrupts are never disabled .' $T%.
"ou cannot call an' )ernel s'stem function from the #*6 *nterrupt 5andler.
System Startup
$T% )ernel uses a separate stac) for each tas) it creates. The stac) si4e is configured in the
configuration file. 5owever= .efore the )ernel is started .' the os_sys_init() function= the stac) that
is configured in the startup file STARTUP.S for the 1ser ,ode is used. 9hen the $T% )ernel is up and
running= the 1ser ,ode stac) is used for the tas) manager - an $T% tas) scheduler.
,inimum stac) si4es for $T% )ernel configured in STARTUP.S areD
Supervisor ,ode 32 bytes @<&A
*nterrupt ,ode 64 bytes @<(A
1ser ,ode 80 bytes @<+A
Supervisor Mode stac) is used when SWI functions are called. *f 'ou are using 'our own comple<
88swi functions= 'ou might also need to increase the si4e of this stac).
Interrupt Mode stac) is used on timer tic) interrupts. This interrupt activates the s'stem tas)
scheduler. The scheduler uses the 1serHS'stem ,ode stac) defined in STARTUP.S and runs in S'stem
,ode. *f 'ou are using interrupts in 'our application= 'ou should increase the si4e of the *nterrupt
,ode stac). ! stac) si4e of &+6 .'tes is a good choice for a start. *f the interrupt stac) overflows= the
application might crash.
User Mode stac) is used until the )ernel is started. *t is .etter to initiali4e the user application from
the first tas) which is created and started .' the os_sys_init() function call.
"ou can initiali4e simple IO= li)e configure the port pins and ena.le !D converter= .efore the
os_sys_init() function is called. The init8*O@A function must .e small and must not use man' local
varia.les .ecause the 1ser ,ode stac) can overflow otherwise.
void main (void) {
/ Mere a simple !* may .e initiali:ed. /
init_!* ();
63
/ $he pro1ram e2ec"tion shall never reach this point. /
for (;;);
}
*t is .etter to do a complex initialization from the first tas) that starts. *n this case= the stac) for
this tas) is used= which is in general much .igger than 1ser ,ode stac).
/ Mere the interr"pts and more comple2 !* may .e initiali:ed. /
!nit_0BA ();
..
}
64
Cortex Version
$;-$T% E 1sing $T% 2ernel E 1sage 5ints E /orte< >ersion
5ere are a few hints specific for /orte<B-, li.rar' version.
Using IRQ interrupts
"ou can use IRQ interrupts with no limitation. $T% )ernel uses onl' one timer interrupt to generate
periodic timer ticks and activate the tas) scheduler. *nterrupt priorit' grouping can .e used with
some restrictions specified .elow.
IRQ interrupts are never disa.led .' $T% 2ernel.
Software interrupt 0 is used .' $T% and cannot .e used in 'our application.
$T% uses its own SVC Handler which is automaticall' lin)ed from the li.rar'. *f 'ou include another
S>/ handler @li)e that found in the SVC.S fileA into 'our proFect= $T% could fail. $emove an' user-
created S>/ handler from 'our proFect to resolve the 5ard #ault.
9hen interrupt priority grouping is used= the P$*N$O1P must .e set .efore the os_sys_init()
function is called. $T% )ernel reads the value of P$*N$O1P to correctl' set internal interrupt pre-
emption priorities.
The lowest two pre-emption priorities are reserved for $T% )ernel= all remaining pre-emption
priorities are availa.le to use in 'our application.
!llowed values for PRIGROUP are from 0 to 6. The P$*N$O1P value 7 will cause $T% to fail.
/hec) the Main Stack size configured from the startup file if 'ou see sporadic crashes of 'our
application. The $T% 2ernel for /orte<B-, is implemented as a S'stem Service /alls. !ll S>/ calls
use a ,ain Stac).
System Startup
$T% )ernel uses a separate stac) for each tas) it creates. The stac) si4e is configured in the
configuration file. 5owever= .efore the )ernel is started .' the os_sys_init() function= the stac) that
is configured in the startup file STARTUP.S for the ,ain Stac) is used.
Stac) si4e used .' $T% )ernel is configured in STARTUP.S. ,inimum si4e is 128 bytes= however 256
bytes is recommended when interrupts are used.
Main stac) is also used when SVC functions are called. *f 'ou are using 'our own comple< __svc
functions= 'ou might also need to increase the si4e of this stac).
"ou can initiali4e simple IO= li)e configure the port pins and ena.le !D converter= ena.le interrupts=
.efore the os_sys_init() function is called. The init8*O@A function is e<ecuted in privileged mode. *t
is recommended to configure peripherals in this function and use unprivileged mode for the tas)s.
void main (void) {
/ Mere a simple !* may .e initiali:ed. /
init_!* ();
/ $he code e2ec"tion sho"ld never reach this point. /
for (;;);
}
65
Create New RTX Application
$;-$T% E 1sing $T% 2ernel E /reate ?ew $T% !pplication
This section descri.es how to create a new application that uses the $T% )ernel.
1. #irst= create a new project in the L>ision *D7 .' selecting Project > New Project.
&. *n the Create New Project window= select a new director' for 'our proFect and enter a name
for 'our proFect.
0. *n the Select e!"ce for Tar#et window= select 'our target !$, device and clic) O2. !llow
L>ision to cop' and add the device startup file to 'our proFect. This creates a .asic L>ision
proFect.
(. ?ow setup the project to use the $T% )ernel. To do this= select Project > Options for
Target. Then select $T% 2ernel for the Operating system and clic) O2.
+. /op' the $T%8/onfig.c configuration file for 'our target device from the
\Keil\ARM\Startup\ director'D
for ARM7"/ARM9" devices= cop' the configuration file for 'our specific device. *f the file
does not e<ist for 'our specific device= then cop' the file from the Philips folder and modif' it
to suit 'our device.
for Cortex-M" devices= cop' a generic RTX_Conf_CM.c configuration file.
6. ,odif' the device startup file for ARM7"/ARM9" devices to ena.le S9*85andler function
@no change re:uired for Cortex-M" devicesAD
/omment out the following line from the startup fileD
+4!_Mandler N +4!_Mandler
!dd the following line to the startup fileD
!IC*#$ +4!_Mandler
This change prevents the code from sitting in a loop when a S9* interrupt occurs. The change
allows the right function to run when a S9* interrupt occurs.
7. /op' the retarget.c file from \Keil\ARM\Startup\ to 'our proFect director'= and add it to
'our proFect. The main purpose of this file is to avoid the use of semihosting S9*s. Thus the
file must contain the followingD
&incl"de 6rt_misc.h7
&pra1ma import(__"se_no_semihostin1_s(i)
void _tty(rch(int ch) {
// Aot "sed (Ao *"tp"t)
}
void _sys_e2it(int ret"rn_code) {
la.elO 1oto la.el; / endless loop /
}
Depending on 'our application= 'ou might have to retarget more functions. #or e<ample if 'ou
use the $;-#lash#S li.rar'= 'ou can o.tain retarget.c from the
\Keil\ARM\RL\FlashFS\SRC\ director'. ?ow the proFect is setup to use the $T% )ernel.
Note
#or MicroLIB runtime li.rar' 'ou do not need a retarget.c in 'our proFect.
8. ?ow 'ou must configure the RTX kernel for the needs of 'our application .' ma)ing the
re:uired changes in the RTX_Config.c file.
9. Create the application source files if the' do not alread' e<ist. !dd these source files to
the proFect. "ou can do this in the proFect wor)space of L>ision .' right clic)ing on the Source
Nroup and selecting Add Files to Group.
1. 3uild 'our application using Project > Build Target.
66
11. *f 'ou proFect .uilds successfull'= 'ou can download it to 'our hardware or run it using the
L>ision Simulator. "ou can also de.ug the application using Debug > Start Debug
Session.
!$,D S7T1P P$OO7/TS 9*T5 $T% 27$?7;
67
Function Reference
$;-$T% E #unction $eference
The $T% functions are grouped into the following categoriesD
7vent #lag ,anagement
,ail.o< ,anagement
,emor' !llocation #unctions
,ute< ,anagement
Semaphore ,anagement
S'stem #unctions
Tas) ,anagement
Time ,anagement
1ser Timer ,anagement
68
Event Flag Management Routines
$;-$T% E #unction $eference E 7vent #lag ,anagement $outines
7vent flag management routines ena.le tas)s to send and wait for events from other tas)s.
$outine !ttri.utes Description
os_evt_clr /lears one or more event flags of a tas).
os_evt_get $etrieves the event flags that caused os_evt_wait_or to complete.
os_evt_set Sets one or more event flags of a tas).
os_evt_wait_and 9aits for one or more event flags to .e set.
os_evt_wait_or 9aits for an' one event flag to .e set.
isr_evt_set Sets one or more event flags of a tas).
69
Mailbox Management Routines
$;-$T% E #unction $eference E ,ail.o< ,anagement $outines
os_mbx_check Determines the num.er of messages that can still .e added to the
mail.o<.
os_mbx_declare /reates a mail.o< o.Fect.
os_mbx_init *nitiali4es a mail.o< so that it can .e used.
os_mbx_send Sends a message to a mail.o<.
os_mbx_wait Nets the ne<t message from a mail.o<= or waits if the mail.o< is
empt'.
isr_mbx_check Determines the num.er of messages that can still .e added to the
mail.o<.
isr_mbx_receive Nets the ne<t message from a mail.o<.
isr_mbx_send Sends a message to a mail.o<.
Note
The mail.o< management routines ena.le 'ou to send and receive messages .etween tas)s using
mail.o<es.
The os_mbx_declare routine is implemented as a macro.
70
Memory Allocation Routines
$;-$T% E #unction $eference E ,emor' !llocation $outines
_declare_box /reates a memor' pool of fi<ed si4e .loc)s with (-.'te alignment.
_declare_box8 /reates a memor' pool of fi<ed si4e .loc)s with 8-.'te alignment.
_init_box *nitiali4es a memor' pool with (-.'te aligned .loc)s.
_init_box8 *nitiali4es a memor' pool with 8-.'te aligned .loc)s.
_alloc_box $eentrant !llocates a memor' .loc) from a memor' pool.
_calloc_box $eentrant !llocates a memor' .loc) from a memor' pool= and clears the contents
of the .loc) to .
_free_box $eentrant $eturns a memor' .loc) .ac) to its memor' pool.
Note
The memor' allocation routines ena.le 'ou to use the s'stem memor' d'namicall' .' creating
memor' pools and using fi<ed si4e .loc)s from the memor' pools.
The _init_box8= _declare_box and _declare_box8 routines are implemented as macros.
71
Mutex Management Routines
$;-$T% E #unction $eference E ,ute< ,anagement $outines
os_mut_init *nitiali4es a mute< o.Fect.
os_mut_release $eleases a mute< o.Fect.
os_mut_wait 9aits for a mute< o.Fect to .ecome availa.le.
?ote
The mute< management routines ena.le 'ou to use mute<es to s'nchroni4e the activities of the
various tas)s and to protect shared varia.les from corruption.
The priority inheritance method is used in mute< management routines to eliminate priority
inversion pro.lems.
72
Semaphore Management Routines
$;-$T% E #unction $eference E Semaphore ,anagement $outines
os_sem_init *nitiali4es a semaphore o.Fect.
os_sem_send Sends a signal @to)enA to the semaphore.
os_sem_wait 9aits for a signal @to)enA from the semaphore.
isr_sem_send Sends a signal @to)enA to the semaphore.
Note
The semaphore management routines ena.le 'ou to use semaphores to s'nchroni4e the activities of
the various tas)s and to protect shared varia.les from corruption.
$;-!$,D !/61*$7H$7;7!S7 O$ 3*?!$" S7,!P5O$7 *? $T% 27$?7;
73
System Functions
$;-$T% E #unction $eference E S'stem #unctions
tsk_lock Disa.les tas) switching.
tsk_unlock 7na.les tas) switching.
Note
The s'stem functions ena.le 'ou to control the timer interrupt and tas) switching.
74
Task Management Routines
$;-$T% E #unction $eference E Tas) ,anagement $outines
os_sys_init *nitiali4es and starts $;-$T%.
os_sys_init_prio *nitiali4es and starts $;-$T% assigning a priorit' to the
starting tas).
os_sys_init_user *nitiali4es and starts $;-$T% assigning a priorit' and custom
stac) to the starting tas).
os_tsk_create /reates and starts a new tas).
os_tsk_create_ex /reates= starts= and passes an argument pointer to a new
tas).
os_tsk_create_user /reates= starts= and assigns a custom stac) to a new tas).
os_tsk_create_user_ex /reates= starts= assigns a custom stac)= and passes an
argument pointer to a new tas).
os_tsk_delete Stops and deletes a tas).
os_tsk_delete_self Stops and deletes the currentl' running tas).
os_tsk_pass Passes control to the ne<t tas) of the same priorit'.
os_tsk_prio /hanges a tas)Gs priorit'.
os_tsk_prio_self /hanges the currentl' running tas)Gs priorit'.
os_tsk_self O.tains the tas) *D of the currentl' running tas).
isr_tsk_get O.tains the tas) *D of the interrupted tas).
Note
The tas) management routines ena.le 'ou to start the $T% )ernel= create and delete various t'pes
of tas)s= and control their e<ecution priorities.
75
Time Management Routines
$;-$T% E #unction $eference E Time ,anagement $outines
os_dly_wait Pauses the calling tas) for a specified interval.
os_itv_set 7na.les the calling tas) for periodic wa)e up.
os_itv_wait Pauses the calling tas) until the periodic wa)e up interval e<pires.
Note
The time management routines ena.le 'ou to pause and restart tas)s using a timer.
76
User Timer Management Routines
$;-$T% E #unction $eference E 1ser Timer ,anagement $outines
os_tmr_create Starts a countdown timer to call the os_tmr_call function.
os_tmr_kill !.orts a user defined timer.
os_tmr_call 1ser customi4a.le function that gets called when the user defined
timer e<pires.
Note
The user timer management routines ena.le 'ou to use timers to control when a user
customi4a.le function runs.
77
Library Reference
;i.rar' $eference
The $eal-Time ;i.rar' provides more than + predefined functions and macros 'ou ma' use in 'our
!$,C real-time programs. The li.rar' ma)es em.edded software development easier .' providing
routines that perform common real-time tas)s.
78
Reference
;i.rar' $eference E $eference
The following pages descri.e the routines in the $eal-Time ;i.rar'. $outines are listed in alpha.etical order
and each is divided into several sectionsD
Summary 3riefl' descri.es the routineGs effect= lists include file@sA containing its declaration and
protot'pe= illustrates the s'nta<= and descri.es an' arguments.
Description Provides a detailed description of the routine and how it is used.
Return Value Descri.es the value returned .' the routine.
See Also ?ames related routines.
Example Nives a function or program fragment demonstrating proper use of the function.
79
_alloc_box
;i.rar' $eference E $eference E 8alloc8.o<
Summary
&incl"de 6rtl.h7
void _alloc_.o2 (
void .o2_mem ); / +tart address of the memory pool /
Description The _alloc_box function allocates a .loc) of memor' from the memor' pool that
.egins at the address $o%_&e&.
The _alloc_box function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
"ou must initiali4e the memor' pool using the _init_box function .efore performing
an' other operation on the memor' pool.
The _alloc_box function is reentrant and thread-safe. "ou can call it from the main
function and from an *$6 interrupt function with no restriction.
Return Value The _alloc_box function returns a pointer to the allocated .loc) if a .loc) was
availa.le. *f there was no availa.le .loc)= it returns a ?1;; pointer.
See Also _calloc_box, _free_box, _init_box
Example
&incl"de 6rtl.h7
/ #eserve a memory for G2 .locks of 20).ytes. /
JG2 mpoolRG25 9 GS;
void mem.o2_test (void) {
JT .o2;
JT c.o2;
_init_.o2 (mpool, si:eof (mpool), 20);
.o2 / _alloc_.o2 (mpool);
/ $his .lock is initiali:ed to 0. /
c.o2 / _calloc_.o2 (mpool);
..
_free_.o2 (mpool, .o2);
_free_.o2 (mpool, c.o2);
}
80
_calloc_box
;i.rar' $eference E $eference E 8calloc8.o<
Summary
&incl"de 6rtl.h7
void _calloc_.o2 (
void .o2_mem ); / +tart address of the memory pool /
Description The _calloc_box function allocates a .loc) of memor' from the memor' pool that
.egins at the address $o%_&e& and initiali4es the entire memor' .loc) to .
The _calloc_box function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
"ou must initiali4e the memor' pool using the _init_box function .efore performing
an' other operation on the memor' pool.
The _calloc_box function is reentrant and thread-safe. "ou can call it from the
main function and from an *$6 interrupt function with no restriction.
Return Value The _calloc_box function returns a pointer to the allocated .loc) if a .loc) was
availa.le. *f there was no availa.le .loc)= it returns a ?1;; pointer.
See Also _alloc_box= _free_box= _init_box
Example
&incl"de 6rtl.h7
JG2 mpoolRG25 9 GS;
JT .o2;
JT c.o2;
..
}
81
_declare_box
;i.rar' $eference E $eference E 8declare8.o<
Summary
&incl"de 6rtl.h7
&define _declare_.o2( Q
pool, Q / Aame of the memory pool varia.le. /
si:e, Q / A"m.er of .ytes in each .lock. /
cnt ) Q / A"m.er of .locks in the memory pool. /
JG2 poolR((si:e9G)/3)(cnt) 9 GS
Description The _declare_box macro declares an arra' of .'tes that can .e used as a memor'
pool for fi<ed .loc) allocation.
The argument pool specifies the name of the memor' pool varia.le= which can .e
used .' the memor' .loc) allocation routines. The argument s"'e specifies the si4e of
the .loc)s= in .'tes. The argument cnt specifies the num.er of .loc)s re:uired in the
memor' pool.
The _declare_box macro is part of $;-$T%. The definition is in rtl.h.
Note
The macro rounds up the value of s"'e to the ne<t multiple of ( to give the .loc)s a
(-.'te alignment.
The macro also declares an additional 1& .'tes at the start of the memor' pool to
store internal pointers and si4e information a.out the memor' pool.
Return Value The 8declare8.o< macro does not return an' value.
See Also _alloc_box, _calloc_box, _free_box, _init_box
Example
&incl"de 6rtl.h7
_declare_.o2(mpool,20,G2);
JT .o2;
JT c.o2;
..
}
82
_declare_box8
;i.rar' $eference E $eference E 8declare8.o<8
Summary
&incl"de 6rtl.h7
&define _declare_.o2T( Q
pool, Q / Aame of the memory pool varia.le. /
si:e, Q / A"m.er of .ytes in each .lock. /
cnt ) Q / A"m.er of .locks in the memory pool. /
JK3 poolR((si:e9U)/T)(cnt) 9 2S
Description The _declare_box8 macro declares an arra' of .'tes that can .e used as a memor'
pool for allocation of fi<ed .loc)s with 8-.'te alignment.
The argument pool specifies the name of the memor' pool varia.le that is used .' the
memor' .loc) allocation routines. The argument s"'e specifies the si4e of the .loc)s=
in .'tes. The argument cnt specifies the num.er of .loc)s re:uired in the memor'
pool.
The _declare_box8 macro is part of $;-$T%. The definition is in rtl.h.
Note
The macro rounds up the value of s"'e to the ne<t multiple of 8 to give the .loc)s
an 8-.'te alignment.
The macro also declares an additional 16 .'tes at the start of the memor' pool to
store internal pointers and si4e information a.out the memor' pool.
Return Value The _declare_box8 macro does not return an' value.
See Also _alloc_box, _calloc_box, _free_box, _init_box8
Example
&incl"de 6rtl.h7
/ #eserve a memory for 25 .locks of G0).ytes. /
_declare_.o2T(mpool,G0,25);
JT .o2;
JT c.o2;
_init_.o2T (mpool, si:eof (mpool), G0);
/ <.o2< and <c.o2< are al(ays T).yte ali1ned. /
..
}
83
_free_box
;i.rar' $eference E $eference E 8free8.o<
Summary
&incl"de 6rtl.h7
int _free_.o2 (
void .o2_mem, / +tart address of the memory pool /
void .o2 ); / Cointer to the .lock to free /
Description The _free_box function returns a memor' .loc)= which was allocated using
_alloc_box or _calloc_box= .ac) to the memor' pool where it was o.tained from.
The $o% argument specifies the address of the memor' .loc) to .e freed.
The $o%_&e& argument specifies the start address of the memor' pool where the
.loc) was o.tained from.
The _free_box function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
*f 'ou return the memor' .loc) to a memor' pool that did not provide the memor'
.loc)= serious memor' errors might occur.
The _free_box function is reentrant and thread-safe. "ou can call it from the main
function and from an *$6 interrupt function with no restriction.
Return Value The _free_box function returns if the memor' .loc) was successfull' returned to
the memor' pool. *f there was an error while freeing the .loc)= it returns 1.
See Also _alloc_box, _calloc_box, _init_box
Example
&incl"de 6rtl.h7
JG2 mpoolRG25 9 GS;
JT .o2;
JT c.o2;
..
}
84
_init_box
;i.rar' $eference E $eference E 8init8.o<
Summary
&incl"de 6rtl.h7
int _init_.o2 (
JG2 .o2_si:e, / A"m.er of .ytes in the memory pool /
JG2 .lk_si:e ); / A"m.er of .ytes in each .lock of the pool /
Description The _init_box function initiali4es a fi<ed .loc) si4e memor' pool. 9hen the memor'
pool is initiali4ed= the $T% )ernel handles memor' re:uests .' allocating a .loc) of
memor' from the memor' pool.
The $o%_&e& specifies the start address of the memor' pool= and this address must
.e (-.'te aligned.
The $o%_s"'e argument specifies the si4e of the memor' pool= in .'tes.
The $lk_s"'e argument specifies the si4e= in .'tes= of the .loc)s in the memor' pool.
"ou can set the .loc) si4e to an' value from 1 to $o%_s"'e-1&. 5owever= the $lk_s"'e is
rounded up to the ne<t multiple of ( to maintain (-.'te address alignment of the
.loc)s. #or e<ample if 'ou initiali4e a memor' pool for 1-.'te .loc)s= the _init_box
function actuall' initiali4es the memor' pool for 1&-.'te .loc)s.
The _init_box function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
The first 1& .'tes from the memor' pool are reserved for storing pointers and si4e
information that can .e used .' the functions that handle the memor' pool. The
$o%_s"'e must therefore .e more than 1& .'tes long.
*f the start address is not (-.'te aligned= the memor' pool handling functions might
fail.
Return Value The _init_box function returns if the memor' pool was initiali4ed without an'
pro.lem. *f there was an initiali4ation error= it returns 1.
See Also _alloc_box, _calloc_box, _declare_box, _free_box
Example
&incl"de 6rtl.h7
_declare_.o2(mpool,20,G2);
JT .o2;
JT c.o2;
..
}
85
_init_box8
;i.rar' $eference E $eference E 8init8.o<8
Summary
&incl"de 6rtl.h7
int _init_.o2T (
JG2 .o2_si:e, / A"m.er of .ytes in the memory pool /
JG2 .lk_si:e ); / A"m.er of .ytes in each .lock of the pool /
Description The _init_box8 function initiali4es a fi<ed .loc) si4e memor' pool with 8-.'te
alignment. 9hen the memor' pool is initiali4ed= the $T% )ernel handles memor'
re:uests .' allocating a .loc) of memor' from the memor' pool.
The $o%_&e& specifies the start address of the memor' pool= and this address must
.e 8-.'te aligned.
The $o%_s"'e argument specifies the si4e of the memor' pool= in .'tes.
The $lk_s"'e argument specifies the si4e= in .'tes= of the .loc)s in the memor' pool.
"ou can set the .loc) si4e to an' value from 1 to $o%_s"'e-16. 5owever= the $lk_s"'e is
rounded up to the ne<t multiple of 8= to maintain 8-.'te alignment of the .loc)s. #or
e<ample if 'ou initiali4e a memor' pool for 1-.'te .loc)s= the _init_box8 function
actuall' initiali4es the memor' pool for 16-.'te .loc)s.
The _init_box8 function is implemented as a macro and is part of $;-$T%. The
definition is in rtl.h.
Note
The first 16 .'tes from the memor' pool are reserved for storing pointers and si4e
information that can .e used .' the functions that handle the memor' pool. The
$o%_s"'e must therefore .e more than 16 .'tes long.
*f the start address is not 8-.'te aligned= the memor' pool handling functions might
fail.
Return Value The _init_box8 function returns if the memor' pool was initiali4ed without an'
pro.lem. *f there was an initiali4ation error= it returns 1.
See Also _alloc_box, _calloc_box, _declare_box8, _free_box
Example
&incl"de 6rtl.h7
/ #eserve a memory for 25 .locks of G0).ytes. /
_declare_.o2T(mpool,G0,25);
JT .o2;
JT c.o2;
_init_.o2T (mpool, si:eof (mpool), G0);
/ <.o2< and <c.o2< are al(ays T).yte ali1ned. /
..
}
86
isr_evt_set
;i.rar' $eference E $eference E isr8evt8set
Summary
&incl"de 6rtl.h7
void isr_evt_set (
J1K event_fla1s, / Nit pattern of event fla1s to set /
*+_$!, task ); / $he task that the events apply to /
Description The isr_evt_set function sets the event flags for the task identified .' the function
argument. The function onl' sets the event flags whose corresponding .it is set to 1 in
the e!ent_fla#s argument.
The isr_evt_set function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
"ou can call the isr_evt_set function onl' from the *$6 interrupt service routine.
"ou cannot call it from the #*6 interrupt service routine.
9hen the isr_evt_set function is called too fre:uentl'= it forces too man' tic) timer
interrupts and the tas) manager tas) scheduler is e<ecuted most of the time. *t
might happen that two isr_evt_set functions for the same tas) are called .efore
the tas) gets a chance to run from one of the event waiting functions
@os8evt8wait8A. Of course one event is lost .ecause event flags are not counting
o.Fects.
Return Value The isr_evt_set function does not return an' value.
See Also os_evt_clr, os_evt_set, os_evt_wait_and, os_evt_wait_or
Example
&incl"de 6rtl.h7
void timer1 (void) __ir@ {
..
isr_evt_set (02000T, tsk1);
..
}
87
isr_mbx_check
;i.rar' $eference E $eference E isr8m.<8chec)
Summary
&incl"de 6rtl.h7
*+_#=+JD$ isr_m.2_check (
*+_!, mail.o2 ); / $he mail.o2 to check for free space /
Description The isr_mbx_check function determines the num.er of messages that can still .e
added into the &a"l$o% identified .' the function argument. "ou can avoid losing the
message .' calling the isr_mbx_check function to chec) for availa.le space in the
mail.o< .efore calling the isr_mbx_send function to send a message.
The isr_mbx_check function is in the $;-$T% li.rar'. The protot'pe is defined in
rtl.h.
Note
"ou can call the isr_mbx_check function onl' from the *$6 interrupt service
routine. "ou cannot call it from the #*6 interrupt service routine.
9hen sending more than one message from *S$= the mail.o< might overflow=
.ecause the isr_mbx_send puts the messages in the fifo :ueue= not directl' to the
mail.o<.
Return Value The isr_mbx_check function returns the num.er of message entries in the mail.o<
that are free.
See Also isr_mbx_send, os_mbx_declare, os_mbx_init
Example
&incl"de 6rtl.h7
..
if (isr_m.2_check (mail.o21) V/ 0) {
isr_m.2_send (mail.o21, ms1);
}
..
}
7<ample for sending more than one message from *S$D
&incl"de 6rtl.h7
int i,free;
..
free / isr_m.2_check (mail.o21);
for (i / 0; i 6 1K; i99) {
if (free 7 0) {
free));
}
}
..
}
88
isr_mbx_receive
;i.rar' $eference E $eference E isr8m.<8receive
Summary
&incl"de 6rtl.h7
*+_#=+JD$ isr_m.2_receive (
*+_!, mail.o2, / $he mail.o2 to p"t the messa1e in /
void messa1e ); / Docation to store the messa1e pointer /
Description The isr_mbx_receive function gets a pointer to a message from the &a"l$o% if the
mail.o< is not empt'. The function puts the message pointer from the mail.o< into
the location pointed .' the &essa#e argument. The isr_mbx_receive function does
not cause the current tas) to sleep even if there is no message in the mail.o<. 5ence
this function can .e called from an interrupt function.
"ou can use the isr_mbx_receive function to receive a message or a protocol frame
@for e<ample T/P-*P= 1DP= and *SD?A in an interrupt function.
The isr_mbx_receive function is in the $;-$T% li.rar'. The protot'pe is defined in
rtl.h.
Note
"ou must declare and initiali4e the mail.o< o.Fect .efore 'ou perform an' operation
on it.
"ou can call the isr_mbx_receive function onl' from *$6 interrupt functions. "ou
cannot call it from the #*6 interrupt function.
9hen 'ou get the message from the mail.o<= 'ou must free the memor' .loc)
containing the message to avoid running out of memor'.
9hen 'ou get the message from the mail.o<= space is created in the mail.o< for a
new message.
Return Value The isr_mbx_receive function returns the completion valueD
$eturn >alue Description
OS8$8,3% ! message was availa.le and was read from the mail.o<.
OS8$8O2 ?o message was availa.le in the mail.o<.
See Also isr_mbx_send, os_mbx_declare, os_mbx_init, os_mbx_wait
Example
&incl"de 6rtl.h7
void ms1;
void =ther!nt (void) __ir@ {
..
if (isr_m.2_receive (mail.o21, Ems1) // *+_#_IN%) {
/ $ransmit =thernet frame. /
}
else {
/ Ao messa1e (as availa.le, stop transmitter /
}
..
}
89
isr_mbx_send
;i.rar' $eference E $eference E isr8m.<8send
Summary
&incl"de 6rtl.h7
void isr_m.2_send (
void messa1e_ptr ); / Cointer to the messa1e /
Description The isr_mbx_send function puts the pointer to the message &essa#e_ptr in the
&a"l$o% if the mail.o< is not alread' full. The isr_mbx_send function does not cause
the current tas) to sleep even if there is no space in the mail.o< to put the message.
9hen an interrupt receives a protocol frame @for e<ample T/P-*P= 1DP= or *SD?A= 'ou
can call the isr_mbx_send function from the interrupt to pass the protocol frame as
a message to a tas).
The isr_mbx_send function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
on it.
"ou can call the isr_mbx_send function onl' from *$6 interrupt functions. "ou
cannot call it from #*6 interrupt functions.
*f the &a"l$o% is full= the $T% )ernel ignores the message since it cannot .e put into
the mail.o<= and calls the error function. Thus .efore sending a message using
isr_mbx_send= 'ou must use the isr_mbx_check function to chec) if the mail.o<
is full.
Return Value The isr_mbx_send function does not return an' value.
See Also isr_mbx_check, isr_mbx_receive, os_mbx_declare, os_mbx_init
Example
&incl"de 6#$D.h7
..
..
}
90
isr_sem_send
;i.rar' $eference E $eference E isr8sem8send
Summary
&incl"de 6rtl.h7
void isr_sem_send (
*+_!, semaphore ); / $he semaphore (hose token co"nt is incremented /
Description The isr_sem_send function increments the num.er of to)ens in the se&aphore o.Fect.
The isr_sem_send function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
"ou must initiali4e the semaphore o.Fect using the os_sem_init function .efore 'ou can
perform an' operation on the semaphore.
"ou can call the isr_sem_send function onl' from *$6 interrupt functions and not from
the #*6 interrupt function.
Return Value The isr_sem_send function does not return an' value.
See Also os_sem_init, os_sem_send, os_sem_wait
Example
&incl"de 6rtl.h7
*+_+=I semaphore1;
..
isr_sem_send (semaphore1);
..
}
91
isr_tsk_get
;i.rar' $eference E $eference E isr8ts)8get
Summary
&incl"de 6rtl.h7
*+_$!, isr_tsk_1et (void);
Description The isr_tsk_get function identifies the interrupted tas) .' returning its tas) *D.
The isr_tsk_get function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Return Value The isr_tsk_get function returns the tas) identifier num.er @T*DA of the interrupted
tas).
See Also os_tsk_self
Example
&incl"de 6rtl.h7
void os_error (JG2 err_code) {
/ $his f"nction is called (hen a r"ntime error is detected. /
*+_$!, err_task;
s(itch (err_code) {
case *+_=##_+$;_*>-O
/ !dentify the task (ith stack overflo(. /
err_task / isr_tsk_1et();
.reak;
case *+_=##_-!-*_*>-O
.reak;
case *+_=##_IN%_*>-O
.reak;
}
for (;;);
}
$;-!$,D T$!?S*T*O? #$O, OS8ST28O>7$#;O9@A TO OS87$$O$@A
92
os_dly_wait
;i.rar' $eference E $eference E os8dl'8wait
Summary
&incl"de 6rtl.h7
void os_dly_(ait (
J1K delay_time ); / Den1th of time to pa"se /
Description The os_dly_wait function pauses the calling tas). The argument delay_t"&e specifies
the length of the pause and is measured in num.er of s'stem8tic)s. "ou can set the
delay_t"&e to an' value .etween 1 and <###7.
The os_dly_wait function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
"ou cannot intermi< with a single tas) the wait method os_itv_wait () and
os_dly_wait ().
Return Value The os_dly_wait function does not return an' value.
See Also os_itv_set, os_itv_wait
Example
&incl"de 6rtl.h7
..
os_dly_(ait (20);
..
}
$;-!$,D 9$O?N T*,*?N 9*T5 OS8*T>8S7T@A
93
os_evt_clr
;i.rar' $eference E $eference E os8evt8clr
Summary
&incl"de 6rtl.h7
void os_evt_clr (
J1K clear_flags, / Nit pattern of event fla1s to clear /
Description The os_evt_clr function clears the event flags for the tas) identified .' the function
argument. The function onl' clears the event flags whose corresponding .it is set to 1
in the clear_fla#s argument.
The os_evt_clr function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Return Value The os_evt_clr function does not return an' value.
See Also isr_evt_set, os_evt_set, os_evt_wait_and, os_evt_wait_or
Example
&incl"de 6rtl.h7
..
os_evt_clr (020002, tsk2);
..
}
94
os_evt_get
;i.rar' $eference E $eference E os8evt8get
Summary
&incl"de 6rtl.h7
J1K os_evt_1et (void);
Description "ou can use the os_evt_get function to identif' the event that caused the
os_evt_wait_or function to complete.
The os_evt_get function identifies this event .' setting the corresponding flag in the
returned value. *f more than one event occurred simultaneousl'= all their flags are set
in the returned value.
The os_evt_get function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
9hen the os_evt_wait_or function has .een waiting on more than one event= it is
not immediatel' )nown which event caused the os_evt_wait_or function to
return. This is wh' the os_evt_get function is useful.
Return Value The os_evt_get function returns a .it pattern that identifies the events that caused
the os_evt_wait_or function to complete.
See Also os_evt_wait_or
Example
&incl"de 6#$D.h7
J1K ret_fla1s;
if (os_evt_(ait_or (02000G, 500) // *+_#_=>$) {
ret_fla1s / os_evt_1et ();
printf('=vents W032 received.Qn',ret_fla1s);
}
..
}
95
os_evt_set
;i.rar' $eference E $eference E os8evt8set
Summary
&incl"de 6rtl.h7
void os_evt_set (
J1K event_fla1s, / Nit pattern of event fla1s to set /
Description The os_evt_set function sets the event flags for the task identified .' the function
argument. The function onl' sets the event flags whose corresponding .it is set to 1
in the e!ent_fla#s argument.
The os_evt_set function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Return Value The os_evt_set function does not return an' value.
See Also isr_evt_set, os_evt_clr, os_evt_wait_and, os_evt_wait_or
Example
&incl"de 6rtl.h7
..
os_evt_set (02000G, tsk2);
..
}
96
os_evt_wait_and
;i.rar' $eference E $eference E os8evt8wait8and
Summary
&incl"de 6rtl.h7
*+_#=+JD$ os_evt_(ait_and (
J1K (ait_fla1s, / Nit pattern of events to (ait for /
J1K timeo"t ); / Den1th of time to (ait for event /
Description The os_evt_wait_and function waits for all the events specified in the wa"t_fla#s to
occur. The function onl' waits on events whose corresponding flags have .een set to 1
in the wa"t_fla#s parameter. The function can wait on as man' as 16 different events.
"ou can use the t"&eout argument to specific the length of time after which the
function must return even if none of the events have occurred. "ou can use an' value
of timeout with the e<ception of <####= which 'ou can use to specif' an indefinite
timeout. The unit of measure of the t"&eout argument is the num.er of s'stem
intervals.
The os_evt_wait_and function returns when all of the events specified in the
wa"t_fla#s have occurred or when the timeout e<pires. *f all events specified in
wa"t_fla#s have arrived= this function clears them .efore the function returns. The
function actuall' clears the events whose corresponding flags have .een set to 1 in
the wa"t_fla#s parameter. The other event flags are not changed.
The os_evt_wait_and function is in the $;-$T% li.rar'. The protot'pe is defined in
rtl.h.
Note
7ach tas) has its own 16 .it wait flag.
Return Value The os_evt_wait_and function returns a value to indicate whether an event
occurred or the timeout e<pired.
OS_R_EVT !ll the flags specified .' wait_flags have .een set.
OS_R_TMO The timeout has e<pired.
See Also os_evt_get= os_evt_wait_or
Example
&incl"de 6rtl.h7
*+_#=+JD$ res"lt;
res"lt / os_evt_(ait_and (02000G, 500);
if (res"lt // *+_#_$I*) {
printf('=vent (ait timeo"t.Qn');
}
else {
printf('=vent received.Qn');
}
..
}
97
os_evt_wait_or
;i.rar' $eference E $eference E os8evt8wait8or
Summary
&incl"de 6rtl.h7
*+_#=+JD$ os_evt_(ait_or (
J1K (ait_fla1s, / Nit pattern of events to (ait for /
J1K timeo"t ); / Den1th of time to (ait for event /
Description The os_evt_wait_or function waits for one of the events specified in the wa"t_fla#s
to occur. The function onl' waits on events whose corresponding flags have .een set
to 1 in the wa"t_fla#s parameter. The function can wait on as man' as 16 different
events.
"ou can use the t"&eout argument to specific the length of time after which the
function must return even if none of the events have occurred. "ou can use an' value
of timeout with the e<ception of <####= which 'ou can use to specif' an indefinite
timeout. The unit of measure of the t"&eout argument is the num.er of s'stem
intervals.
The os_evt_wait_or function returns when at least one of the events specified in the
wa"t_fla#s has occurred or when the timeout e<pires. The event flag or flags that
caused the os_evt_wait_or function to complete are cleared .efore the function
returns. "ou can identif' those event flags with os_evt_get function later.
The os_evt_wait_or function is in the $;-$T% li.rar'. The protot'pe is defined in
rtl.h.
Note
7ach tas) has its own 16 .it wait flag.
Return Value The os_evt_wait_or function returns a value to indicate whether an event occurred
or the timeout e<pired.
OS8$87>T !t least one of the flags specified .' wa"t_fla#s has .een set.
OS8$8T,O The timeout has e<pired.
See Also os_evt_get, os_evt_wait_and
Example
&incl"de 6rtl.h7
*+_#=+JD$ res"lt;
res"lt / os_evt_(ait_or (02000G, 500);
if (res"lt // *+_#_$I*) {
printf('=vent (ait timeo"t.Qn');
}
else {
printf('=vent received.Qn');
}
..
}
98
os_itv_set
;i.rar' $eference E $eference E os8itv8set
Summary
&incl"de 6rtl.h7
void os_itv_set (
J1K interval_time ); / $ime interval for periodic (ake)"p /
Description The os_itv_set function sets up the calling tas) for periodic wa)e-up after a time
interval specified .' "nter!al_t"&e. "ou must use the os_itv_wait function to wait for
the completion of the time interval. The time interval is measured in units of s'stem
tic)s= and 'ou can set it to an' value .etween 1 and <7###.
The os_itv_set function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Return Value The os_itv_set function does not return an' value.
See Also os_dly_wait, os_itv_wait
Example
&incl"de 6rtl.h7
..
os_itv_set (50);
..
}
99
os_itv_wait
;i.rar' $eference E $eference E os8itv8wait
Summary
&incl"de 6rtl.h7
void os_itv_(ait (void);
Description The os_itv_wait function waits for a periodic time interval after which the $T% )ernel
wa)es up the calling tas). "ou must set the time interval using the os_itv_set
function.
'ou can use the os_itv_wait function to perform a Fo. at regular intervals
independent of the e<ecution time of the tas).
The os_itv_wait function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
"ou cannot intermi< with a single tas) the wait method os_itv_wait () and
os_dly_wait ().
Return Value The os_itv_wait function does not return an' value.
See Also os_dly_wait, os_itv_set
Example
&incl"de 6rtl.h7
..
os_itv_set (20);
for (;;) {
os_itv_(ait ();
/ do some actions at re1"lar time intervals /
}
}
$;-!$,D 9$O?N T*,*?N 9*T5 OS8*T>8S7T@A
100
os_mbx_check
;i.rar' $eference E $eference E os8m.<8chec)
Summary
&incl"de 6rtl.h7
*+_#=+JD$ os_m.2_check (
*+_!, mail.o2 ); / $he mail.o2 to check for free space /
Description The os_mbx_check function determines the num.er of messages that can still .e
added into the &a"l$o% identified .' the function argument. "ou can avoid .loc)ing
the current tas) .' calling the os_mbx_check function to chec) for availa.le space in
the mail.o< .efore calling the os_mbx_send function to send a message.
The os_mbx_check function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Return Value The os_mbx_check function returns the num.er of message entries in the mail.o<
that are free.
See Also isr_mbx_check, os_mbx_declare, os_mbx_send
Example
&incl"de 6rtl.h7
..
if (os_m.2_check (mail.o21) // 0) {
printf('Iail.o2 is f"ll.Qn');
}
..
}
101
os_mbx_declare
;i.rar' $eference E $eference E os8m.<8declare
Summary
&incl"de 6rtl.h7
&define os_m.2_declare( Q
name, Q / Aame of the mail.o2 /
cnt ) Q / A"m.er of messa1e entries /
JG2 name R3 9 cntS
Description The os_mbx_declare macro defines a mail.o< o.Fect. The argument na&e is the
name of the mail.o< o.Fect. The argument cnt is the num.er of messages that can .e
entered into the mail.o< o.Fect. ! cnt value of & is sufficient in most cases.
The os_mbx_declare macro is part of $;-$T%. The definition is in rtl.h.
Return Value The os_mbx_declare macro does not return an' value.
See Also os_mbx_init
Example
&incl"de 6rtl.h7
/ ,eclare a mail.o2 for 20 messa1es. /
..
os_m.2_init (mail.o21, si:eof(mail.o21));
..
}
102
os_mbx_init
;i.rar' $eference E $eference E os8m.<8init
Summary
&incl"de 6rtl.h7
void os_m.2_init (
*+_!, mail.o2, / $he mail.o2 to initiali:e /
J1K m.2_si:e ); / A"m.er of .ytes in the mail.o2 /
Description The os_mbx_init function initiali4es the &a"l$o% o.Fect identified .' the function
argument.
The argument &$%_s"'e specifies the si4e of the mail.o<= in .'tes. 5owever= the
num.er of message entries in the mail.o< is defined .' the os_mbx_declare macro.
The os_mbx_init function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
"ou must declare and initiali4e the mail.o< .efore 'ou perform an' operation on it.
Return Value The os_mbx_init function does not return an' value.
See Also os_mbx_declare
Example
&incl"de 6rtl.h7
/ ,eclare a mail.o2 for 20 messa1es. /
..
..
}
103
os_mbx_send
;i.rar' $eference E $eference E os8m.<8send
Summary
&incl"de 6rtl.h7
*+_#=+JD$ os_m.2_send (
void messa1e_ptr, / Cointer to the messa1e /
J1K timeo"t ); / 4ait time for mail.o2 to .e free /
Description The os_mbx_send function puts the pointer to a message= &essa#e_ptr= in the
&a"l$o%= if the mail.o< is not alread' full.
*f the mail.o< is full= the $T% )ernel puts the calling tas) to sleep. The t"&eout
specifies the length of time the tas) can wait for a space to .ecome availa.le in the
mail.o<. The )ernel wa)es up the tas) either when the timeout has e<pired or when a
space .ecomes availa.le in the mail.o<.
"ou can set the timeout to an' value .etween and <###7. "ou can set the timeout
to <#### for an indefinite timeout.
The os_mbx_send function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
on it.
The unit of measure of the t"&eout argument is num.ers of s'stem intervals.
The &essa#e_ptr points to a .loc) of allocated memor' holding a message of an'
t'pe. The .loc) of memor' is allocated when the message is created and freed .'
the destination tas) when the message is received.
Return Value The function returns the completion valueD
OS8$8O2 The message has .een put in the mail.o<.
See Also isr_mbx_send, os_mbx_check, os_mbx_declare, os_mbx_init, os_mbx_wait
Example
&incl"de 6#$D.h7
*+_$!, tsk1, tsk2;
void ms1;
..
tsk2 / os_tsk_create (task2, 0);
ms1 / alloc();
/ set messa1e content here/
os_m.2_send (mail.o21, ms1, 02----);
..
}
void ms1;
..
os_m.2_(ait (mail.o21, Ems1, 02ffff);
/ process messa1e content here /
free (ms1);
..
104
}
105
os_mbx_wait
;i.rar' $eference E $eference E os8m.<8wait
Summary
&incl"de 6rtl.h7
*+_#=+JD$ os_m.2_(ait (
*+_!, mail.o2, / $he mail.o2 to 1et messa1e from /
void messa1e, / Docation to store the messa1e pointer /
J1K timeo"t ); / 4ait time for messa1e to .ecome availa.le /
Description The os_mbx_wait function gets a pointer to a message from the &a"l$o% if the
mail.o< is not empt'. The function puts the message pointer from the mail.o< into
the location pointed .' the &essa#e argument.
*f the mail.o< is empt'= the $T% )ernel puts the calling tas) to sleep. The t"&eout
specifies the length of time the tas) can wait for a message. The )ernel wa)es up the
tas) either when the timeout e<pires or when a message .ecomes availa.le in the
mail.o<.
"ou can set the timeout to an' value .etween and <###7. "ou can set the timeout
to <#### for an indefinite timeout. *f 'ou specif' the t"&eout to = the calling tas)
continues immediatel' even if there are higher priorit' tas)s in the read' list=
irrespective of whether a message is present in the mail.o< or not.
The os_mbx_wait function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
on it.
The unit of measure of the t"&eout argument is num.ers of s'stem intervals.
9hen 'ou get the message from the mail.o<= 'ou must free the memor' .loc)
containing the message to avoid running out of memor'.
9hen 'ou get the message from the mail.o<= space is created in the mail.o< for a
new message.
Return Value The os_mbx_wait function returns a completion valueD
OS8$8,3% The tas) has waited until a message was put in the mail.o<.
OS8$8T,O The timeout specified .' timeout has e<pired .efore a message was
availa.le in the mail.o<.
OS8$8O2 ! message was availa.le in the mail.o<= and the tas) continues
without waiting.
See Also isr_mbx_receive, os_mbx_declare, os_mbx_init, os_mbx_send
Example
&incl"de 6rtl.h7
__task void task1 (void){
void ms1;
..
if (os_m.2_(ait (mail.o21, Ems1, 10) // *+_#_$I*) {
printf ('4ait messa1e timeo"tVQn');
}
else {
/ process messa1e here /
free (ms1);
}
..
}
106
107
os_mut_init
;i.rar' $eference E $eference E os8mut8init
Summary
&incl"de 6rtl.h7
void os_m"t_init (
*+_!, m"te2 ); / $he m"te2 to initiali:e /
Description The os_mut_init function initiali4es the &ute% o.Fect identified .' the function
argument.
The os_mut_init function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
"ou must define the mute< o.Fect of t'pe OS8,1T. "ou can use the name of the
mute< o.Fect to identif' it during operation.
Return Value The os_mut_init function does not return an' value.
See Also os_mut_release, os_mut_wait
Example
&incl"de 6rtl.h7
*+_IJ$ m"te21;
..
os_m"t_init (m"te21);
..
}
108
os_mut_release
;i.rar' $eference E $eference E os8mut8release
Summary
&incl"de 6rtl.h7
*+_#=+JD$ os_m"t_release (
*+_!, m"te2 ); / $he m"te2 to release /
Description The os_mut_release function decrements the internal counter of the &ute%
identified .' the function argument in order to release the mute<. Onl' when the
internal counter of the mute< is 4ero= the mute< is reall' free to .e ac:uired .'
another tas).
The mute< o.Fect )nows the tas) that currentl' owns it. 5ence the owning tas) can
ac:uire and loc) the mute< as man' times as needed using the os_mut_wait
function. 9hen a tas) that owns a mute< tries to ac:uire it again= the tas) does not
get .loc)ed= .ut the mute<Gs internal counter is incremented. The tas) that ac:uired
the mute< must release the mute< as man' times as it was ac:uired= so that the
internal counter of the mute< is decremented to .
This function also restores the original tas)Gs priorit' if priority inheritance has .een
applied to the owning tas) of the mute< and his priorit' has .een temporar' raised.
The os_mut_release function is in the $;-$T% li.rar'. The protot'pe is defined in
rtl.h.
Note
"ou must initiali4e the mute< o.Fect using the os_mut_init function .efore 'ou can
perform an' operation on it.
Return Value The os_mut_release function returns the completion valueD
OS8$8O2 The mute< was successfull' released
OS8$8?O2 !n error occurred. This can .e either .ecause the internal counter of the
mute< is not or .ecause the calling tas) is not the owner of the
mute<.
See Also os_mut_init, os_mut_wait
Example
&incl"de 6rtl.h7
*+_IJ$ m"te21;
void f1 (void) {
os_m"t_(ait (m"te21, 02ffff);
..
/ 0ritical re1ion 1 /
..
/ f2() (ill not .lock the task. /
f2 ();
os_m"t_release (m"te21);
}
void f2 (void) {
..
..
}
..
f1 ();
109
..
}
..
f2 ();
..
}
110
os_mut_wait
;i.rar' $eference E $eference E os8mut8wait
Summary
&incl"de 6rtl.h7
*+_#=+JD$ os_m"t_(ait (
*+_!, m"te2, / $he m"te2 to ac@"ire /
J1K timeo"t ); / Den1th of time to (ait /
Description The os_mut_wait function tries to ac:uire the &ute% identified .' the function
argument. *f the mute< has not .e loc)ed .' another tas)= the calling tas) ac:uires
and loc)s the mute< and might continue immediatel'. *f the mute< has .een loc)ed .'
another tas)= then the $T% )ernel puts the calling tas) to sleep until the mute<
.ecomes unloc)ed or until the t"&eout e<pires.
"ou can specif' an' value .etween and <###7 for the t"&eout argument. "ou must
set t"&eout to <#### for an indefinite timeout period.
*f 'ou specif' a value of for the t"&eout= the calling tas) continues immediatel' even
if there is a higher priorit' tas) in the read' list.
This function also raises the priorit' of the owning tas) of the mute<= if it is lower than
the priorit' of the calling tas). This programming method is called priority
inheritance and is used to eliminate priorit' inversion pro.lems. 9hen a mute< is
released= the original priorit' of the owning tas) will .e restored.
The os_mut_wait function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
Timeout is measured in num.er of s'stem intervals.
"ou must initiali4e the mute< o.Fect using the os_mut_init function .efore 'ou can
perform an' operation on it.
Return Value The os_mut_wait function returns the completion valueD
OS8$8,1T The tas) waited until the mute< was released and has now ac:uired and
loc)ed the mute<.
OS8$8O2 The mute< was availa.le and the os_mut_wait function returned to
the calling tas) immediatel'.
See Also os_mut_init, os_mut_release
Example
&incl"de 6rtl.h7
*+_IJ$ m"te21;
void f1 (void) {
..
..
/ f2() (ill not .lock the task. /
f2 ();
}
void f2 (void) {
..
..
}
111
..
f1 ();
..
}
..
f2 ();
..
}
112
os_sem_init
;i.rar' $eference E $eference E os8sem8init
Summary
&incl"de 6rtl.h7
void os_sem_init (
*+_!, semaphore, / $he semaphore o.8ect to initiali:e /
J1K token_co"nt ); / !nitial n"m.er of tokens /
Description The os_sem_init function initiali4es the se&aphore o.Fect identified .' the function
argument.
The argument token_count determines the num.er of to)ens stored in the semaphore
initiall'.
The os_sem_init function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
"ou must define the semaphore o.Fect of t'pe OS8S7,. "ou can use the name of
the semaphore o.Fect to identif' it during operation.
Return Value The os_sem_init function does not return an' value.
See Also isr_sem_send, os_sem_send, os_sem_wait
Example
&incl"de 6rtl.h7
*+_+=I semaphore1;
..
os_sem_init (semaphore1, 0);
os_sem_send (semaphore1);
..
}
113
os_sem_send
;i.rar' $eference E $eference E os8sem8send
Summary
&incl"de 6rtl.h7
*+_#=+JD$ os_sem_send (
*+_!, semaphore ); / $he semaphore (hose token co"nt is incremented /
Description The os_sem_send function increments the num.er of to)ens in the se&aphore o.Fect
identified .' the function argument.
The os_sem_send function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
"ou must initiali4e the semaphore o.Fect using the os_sem_init function .efore 'ou can
perform an' operation on the semaphore.
Return Value The os_sem_send function alwa's returns OS8$8O2.
See Also isr_sem_send, os_sem_init, os_sem_wait
Example
&incl"de 6rtl.h7
*+_+=I semaphore1;
..
os_sem_init (semaphore1, 0);
os_sem_send (semaphore1);
..
}
114
os_sem_wait
;i.rar' $eference E $eference E os8sem8wait
Summary
&incl"de 6rtl.h7
*+_#=+JD$ os_sem_(ait (
*+_!, semaphore, / $he semaphore to 1et the token from /
J1K timeo"t ); / Den1th of time to (ait for the token /
Description The os_sem_wait function re:uests a to)en from the se&aphore identified .' the
function argument. *f the to)en count in the semaphore is more than 4ero= the
function gives a to)en to the calling tas) and decrements the to)en count in the
semaphore. The calling tas) might then continue immediatel' or is put in the read'
list depending on the priorities of other tas)s in the read' list and the value of
t"&eout(
*f the to)en count in the semaphore is 4ero= the calling tas) is put to sleep .' the $T%
)ernel. 9hen a to)en .ecomes availa.le in the semaphore or when the timeout period
e<pires= the $T% )ernel wa)es the tas) and puts it in the read' list .
"ou can specif' an' value .etween and <###7 for the t"&eout argument. "ou must
set t"&eout to <#### for an indefinite timeout period.
*f 'ou specif' a value of for the t"&eout= the calling tas) continues immediatel' even
if there is a higher priorit' tas) in the read' list.
The os_sem_wait function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
Timeout is measured in num.er of s'stem intervals.
"ou must initiali4e the semaphore o.Fect using the os_sem_init function .efore
'ou can perform an' operation on the semaphore.
Return Value The os_sem_wait function returns a completion valueD
OS8$8S7, The calling tas) has waited until a semaphore .ecame availa.le.
OS8$8T,O The timeout e<pired .efore the to)en .ecame availa.le.
OS8$8O2 ! to)en was availa.le and the function returned immediatel'.
See Also isr_sem_send, os_sem_init, os_sem_send
Example
&incl"de 6rtl.h7
*+_+=I semaphore1;
..
os_sem_(ait (semaphore1, 02ffff);
..
}
115
os_sys_init
;i.rar' $eference E $eference E os8s's8init
Summary
&incl"de 6rtl.h7
void os_sys_init (
void (task)(void) ); / $ask to start /
Description The os_sys_init function initiali4es and starts the Real)T"&e e*ecut"!e @$T%A )ernel.
The task argument points to the tas) function to start after the )ernel is initiali4ed.
The $T% )ernel gives the tas) a default priorit' of 1.
The os_sys_init function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
The os_sys_init function must .e called from the main / function.
The $T2 )ernel uses the default stac) si4e= which is defined in rtx_config.c= for the
tas).
Return Value The os_sys_init function does not return. Program e<ecution continues with the tas)
identified .' the task argument.
See Also os_sys_init_prio, os_sys_init_user
Example
&incl"de 6rtl.h7
void main (void) {
os_sys_init (task1); / start the kernel /
(hile(1); / (ill never come here /
}
116
os_sys_init_prio
;i.rar' $eference E $eference E os8s's8init8prio
Summary
&incl"de 6rtl.h7
void os_sys_init_prio (
void (task)(void), / $ask to start /
JT priority); / $ask priority (1)253) /
Description The os_sys_init_prio function initiali4es and starts the Real)T"&e e*ecut"!e @$T%A
)ernel.
The task argument points to the tas) to start after the )ernel is initiali4ed.
The pr"or"ty argument specifies the priorit' for the task. The default tas) priorit' is 1.
Priorit' is reserved for the *dle Tas). *f a value of is specified for the pr"or"ty= it is
automaticall' replaced with a value of 1. Priorit' &++ is also reserved.
The os_sys_init_prio function is in the $;-$T% li.rar'. The protot'pe is defined in
rtl.h.
Note
The os_sys_init_prio function must .e called from the main / function.
tas).
Priorit' value of &++ represents the most important tas).
Return Value The os_sys_init_prio function does not return. Program e<ecution continues with
the tas) identified .' the task argument.
See Also os_sys_init, os_sys_init_user
Example
&incl"de 6rtl.h7
void main (void) {
os_sys_init_prio (task1, 10);
(hile(1);
}
117
os_sys_init_user
;i.rar' $eference E $eference E os8s's8init8user
Summary
&incl"de 6rtl.h7
void os_sys_init_"ser (
void (task)(void), / $ask to start /
JT priority, / $ask priority (1)253) /
void stack, / $ask stack /
J1K si:e); / +tack si:e /
Description The os_sys_init_user function initiali4es and starts the Real)T"&e e*ecut"!e @$T%A
)ernel. 1se this function when 'ou must specif' a large stac) for the starting tas).
The task argument points to the tas) function to start after the )ernel is initiali4ed.
The pr"or"ty argument specifies the priorit' for the task( The default tas) priorit' is 1.
Priorit' is reserved for the *dle Tas). *f a value of is specified for the pr"or"ty= it is
automaticall' replaced with a value of 1. Priorit' &++ is also reserved.
The stack argument points to a memor' .loc) reserved for the stac) to use for the
task. The s"'e argument specifies the si4e of the stac) in .'tes.
The os_sys_init_user function is in the $;-$T% li.rar'. The protot'pe is defined in
rtl.h.
Note
The os_sys_init_user function must .e called from the main / function.
The stac) must .e aligned at an 8-.'te .oundar' and must .e declared as an arra'
of t'pe 16( @unsigned long longA.
The default stac) si4e is defined in rtx_config.c.
Return Value The os_sys_init_user function does not return. Program e<ecution continues with
the tas) identified .' the task argument.
See Also os_sys_init, os_sys_init_prio
Example
&incl"de 6rtl.h7
static JK3 stk1R300/TS; / 300).yte stack /
void main (void) {
os_sys_init_"ser (task1, 10, Estk1, si:eof(stk1));
(hile(1);
}
!$,//D P$*?T# O1TP1TS . #O$ #;O!T >!$*!3;7S
118
os_tmr_call
;i.rar' $eference E $eference E os8tmr8call
Summary
void os_tmr_call (
J1K info ); / !dentification of an e2pired timer. /
Description The os_tmr_call function is a user defined function that gets called .' the $T%
)ernelGs task manager tas) scheduler= when the user defined timer e<pires. !fter the
os_tmr_call function returns= the tas) manager deletes this user timer.
The "nfo argument contains the value that was specified when the timer was created
using os_tmr_create.
The os_tmr_call function is part of $;-$T%. The protot'pe is defined in rtl.h. "ou can
customi4e the function in rt<8config.c.
Note
"ou can call an' of the isr_ s'stem functions from the os_tmr_call function= .ut
'ou cannot call an' of the os_ s'stem functions.
Do not call os_tmr_kill for an e<pired user timer.
Return Value The os_tmr_call function does not return an' value.
See Also os_tmr_create, os_tmr_kill
Example
void os_tmr_call (J1K info) {
s(itch (info) {
case 1O / $he s"pervised task is locked, /
/ recovery actions re@"ired. /
.reak;
case 2O / $he second task is locked. /
.reak;
..
}
}
119
os_tmr_create
;i.rar' $eference E $eference E os8tmr8create
Summary
&incl"de 6rtl.h7
*+_!, os_tmr_create (
J1K tcnt, / Den1th of the timer. /
J1K info ); / Br1"ment to the call.ack f"nction. /
Description The os_tmr_create function sets up and starts a timer. 9hen the timer e<pires= the
$T% )ernel calls the user defined os_tmr_call call.ac) function and passes "nfo as an
argument to the os_tmr_call function.
The tcnt argument specifies the length of timer= in num.er of s'stem tic)s. "ou can
specif' tcnt to an' value .etween 1 and <####.
The os_tmr_create function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Return Value The os_tmr_create function returns a timer *D if the timer was successfull' created.
Otherwise= it returns ?1;;.
See Also os_tmr_call, os_tmr_kill
Example
&incl"de 6rtl.h7
*+_$!, tsk1;
*+_!, tmr1;
..
tmr1 / os_tmr_create (10, 1);
if (tmr1 // AJDD) {
printf ('-ailed to create "ser timer.Qn');
}
..
}
120
os_tmr_kill
;i.rar' $eference E $eference E os8tmr8)ill
Summary
&incl"de 6rtl.h7
*+_!, os_tmr_kill (
*+_!, timer ); / !, of the timer to kill /
Description The os_tmr_kill function deletes the t"&er identified .' the function argument. t"&er
is a user timer that was created using the os_tmr_create function. *f 'ou delete the
timer .efore it e<pires= the os_tmr_call call.ac) function does not get called.
The os_tmr_kill function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
Do not call os_tmr_kill for an e<pired user timer. *t has alread' .een deleted .'
the s'stem.
Return Value The os_tmr_kill function returns ?1;; if the timer is )illed successfull'. Otherwise= it
returns the t"&er value.
See Also os_tmr_call, os_tmr_create
Example
&incl"de 6rtl.h7
*+_$!, tsk1;
*+_!, tmr1;
..
if (os_tmr_kill (tmr1) V/ AJDD) {
printf ('Qn$his timer is not on the list.');
}
else {
printf ('Qn$imer killed.');
}
..
}
121
os_tsk_create
;i.rar' $eference E $eference E os8ts)8create
Summary
&incl"de 6rtl.h7
*+_$!, os_tsk_create (
void (task)(void), / $ask to create /
JT priority ); / $ask priority (1)253) /
Description The os_tsk_create function creates the tas) identified .' the task function pointer
argument and then adds the tas) to the read' :ueue. *t d'namicall' assigns a tas)
identifier value @T*DA to the new tas).
The pr"or"ty argument specifies the priorit' for the tas). The default tas) priorit' is 1.
Priorit' is reserved for the *dle Tas). *f a value of is specified for the priorit'= it is
automaticall' replaced with a value of 1. Priorit' &++ is also reserved. *f the new tas)
has a higher priorit' than the currentl' e<ecuting tas)= then a tas) switch occurs
immediatel' to e<ecute the new tas).
The os_tsk_create function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
tas).
Return Value The os_tsk_create function returns the tas) identifier value @T*DA of the new tas). *f
the function fails= for e<ample due to an invalid argument= it returns .
See Also os_tsk_create_ex, os_tsk_create_user, os_tsk_create_user_ex
Example
&incl"de 6rtl.h7
*+_$!, tsk1, tsk2;
..
tsk2 / os_tsk_create (task2, 1);
..
}
..
}
122
os_tsk_create_ex
;i.rar' $eference E $eference E os8ts)8create8e<
Summary
&incl"de 6rtl.h7
*+_$!, os_tsk_create_e2 (
void (task)(void ), / $ask to create /
void ar1v ); / Br1"ment to the task /
Description The os_tsk_create_ex function creates the tas) identified .' the task function
pointer argument and adds the tas) to the read' :ueue. The function d'namicall'
assigns a tas) identifier value @T*DA to the new tas). The os_tsk_create_ex function
is an e<tension to the os_tsk_create function that ena.les 'ou to pass an argument
to the tas).
The ar#! argument is passed directl' to the tas) when it starts. !n argument to a tas)
can .e useful to differentiate .etween multiple instances of the same tas).
The os_tsk_create_ex function is in the $;-$T% li.rar'. The protot'pe is defined in
rtl.h.
Note
tas).
Return Value The os_tsk_create_ex function returns the tas) identifier value @T*DA of the new
tas). *f the function fails= for e<ample due to an invalid argument= it returns .
See Also os_tsk_create, os_tsk_create_user, os_tsk_create_user_ex
Example
&incl"de 6rtl.h7
*+_$!, tsk1, tsk2_0, tsk2_1;
int paramR2S / {0, 1};
..
tsk2_0 / os_tsk_create_e2 (task2, 1, EparamR0S);
tsk2_1 / os_tsk_create_e2 (task2, 1, EparamR1S);
..
}
__task void task2 (void ar1v) {
..
s(itch ((int )ar1v) {
case 0O
printf('$his is a first instance of task2.Qn');
.reak;
case 1O
printf('$his is a second instance of task2.Qn');
.reak;
}
..
}
123
os_tsk_create_user
;i.rar' $eference E $eference E os8ts)8create8user
Summary
&incl"de 6rtl.h7
*+_$!, os_tsk_create_"ser(
void (task)(void), / $ask to create /
void stk, / Cointer to the task<s stack /
J1K si:e ); / A"m.er of .ytes in the stack /
Description The os_tsk_create_user function creates the tas) identified .' the tas) function
pointer argument and then adds the tas) to the read' :ueue. *t d'namicall' assigns a
tas) identifier value @T*DA to the new tas). This function ena.les 'ou to provide a
separate stac) for the tas). This is useful when a tas) needs a .igger stac) for its
local varia.les.
The stk argument is a pointer to the memor' .loc) reserved for the stac) of this tas).
The s"'e argument specifies the num.er of .'tes in the stac).
The os_tsk_create_user function is in the $;-$T% li.rar'. The protot'pe is defined in
rtl.h.
Note
The stac) must .e aligned at an 8-.'te .oundar'= and must .e declared as an arra'
of t'pe 16( @unsigned long longA.
Return Value The os_tsk_create_user function returns the tas) identifier value @T*DA of the new
tas). *f the function fails= for e<ample due to an invalid argument= it returns .
See Also os_tsk_create, os_tsk_create_ex, os_tsk_create_user_ex
Example
&incl"de 6rtl.h7
*+_$!, tsk1,tsk2;
static JK3 stk2R300/TS;
..
/ 0reate task 2 (ith a .i11er stack /
tsk2 / os_tsk_create_"ser (task2, 1, Estk2, si:eof(stk2));
..
}
/ 4e need a .i11er stack here. /
JT ."fR200S;
..
}
!$,//D P$*?T# O1TP1TS . #O$ #;O!T >!$*!3;7S
124
os_tsk_create_user_ex
;i.rar' $eference E $eference E os8ts)8create8user8e<
Summary
&incl"de 6rtl.h7
*+_$!, os_tsk_create_"ser_e2 (
void (task)(void ), / $ask to create /
void stk, / Cointer to the task<s stack /
J1K si:e, / +i:e of stack in .ytes /
void ar1v ); / Br1"ment to the task /
Description The os_tsk_create_user_ex function creates the tas) identified .' the task function
pointer argument and then adds the tas) to the read' :ueue. *t d'namicall' assigns a
tas) identifier value @T*DA to the new tas). This function ena.les 'ou to provide a
separate stac) for the tas). This is useful when a tas) needs a .igger stac) for its
local varia.les. The os_tsk_create_user_ex function is an e<tension to the
os_tsk_create_user function that ena.les 'ou to pass an argument to the tas).
The stk argument is a pointer to the memor' .loc) reserved for the stac) of this tas).
The s"'e argument specifies the num.er of .'tes in the stac).
The ar#! argument is passed directl' to the tas) when it starts. !n argument to a tas)
can .e useful to differentiate .etween multiple instances of the same tas). ,ultiple
instances of the same tas) can .ehave differentl' .ased on the argument.
The os_tsk_create_user_ex function is in the $;-$T% li.rar'. The protot'pe is
defined in rtl.h.
Note
The stac) stk must .e aligned at an 8-.'te .oundar' and must .e declared as an
arra' of t'pe 16( @unsigned long longA.
Return Value The os_tsk_create_user_ex function returns the tas) identifier value @T*DA of the
new tas). *f the function fails= for e<ample due to an invalid argument= it returns .
See Also os_tsk_create, os_tsk_create_ex, os_tsk_create_user
Example
&incl"de 6rtl.h7
*+_$!, tsk1,tsk2_0,tsk2_1;
static JK3 stk2R2SR300/TS;
..
/ 0reate task 2 (ith a .i11er stack /
tsk2_0 / os_tsk_create_"ser_e2 (task2, 1,
Estk2R0S, si:eof(stk2R0S),
(void )0);
tsk2_1 / os_tsk_create_"ser_e2 (task2, 1,
Estk2R1S, si:eof(stk2R1S),
(void )1);
..
}
__task void task2 (void ar1v) {
/ 4e need a .i11er stack here. /
JT ."fR200S;
125
..
s(itch ((int)ar1v) {
case 0O
printf('$his is a first instance of task2.Qn');
.reak;
case 1O
printf('$his is a second instance of task2.Qn');
.reak;
}
..
}
!$,//D P$*?T# O1TP1TS . #O$ #;O!T >!$*!3;7S
126
os_tsk_delete
;i.rar' $eference E $eference E os8ts)8delete
Summary
&incl"de 6rtl.h7
*+_#=+JD$ os_tsk_delete (
*+_$!, task_id ); / !d of the task to delete /
Description *f a tas) has finished all its wor) or is not needed an'more= 'ou can terminate it using
the os_tsk_delete function. The os_tsk_delete function stops and deletes the tas)
identified .' task_"d.
The os_tsk_delete function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
*f task_"d has a value of = the tas) that is currentl' running is stopped and
deleted. The program e<ecution continues with the tas) with the ne<t highest
priorit' in the read' :ueue.
Deleting a tas) frees all d'namic memor' resources allocated to that tas).
Return Value The os_tsk_delete function returns OS8$8O2 if the tas) was successfull' stopped
and deleted. *n all other cases= for e<ample if the tas) with task_"d does not e<ist or
is not running= the function returns OS8$8?O2.
See Also os_tsk_delete_self
Example
&incl"de 6rtl.h7
*+_$!, tskG;
tskG / os_tsk_create (taskG, 0);
..
if (os_tsk_delete (tskG) // *+_#_*;) {
printf('Qn<task G< deleted.');
}
else {
printf ('Qn-ailed to delete <task G<.');
}
}
__task void taskG (void) {
..
}
127
os_tsk_delete_self
;i.rar' $eference E $eference E os8ts)8delete8self
Summary
&incl"de 6rtl.h7
void os_tsk_delete_self (void);
Description The os_tsk_delete_self function stops and deletes the currentl' running tas). The
program e<ecution continues with the tas) with the ne<t highest priorit' in the read'
:ueue.
The os_tsk_delete_self function is in the $;-$T% li.rar'. The protot'pe is defined in
rtl.h.
Note
Deleting a tas) frees all d'namic memor' resources allocated to that tas).
Return Value The os_tsk_delete_self function does not return. The program e<ecution continues
with the tas) with the ne<t highest priorit' in the read' :ueue.
See Also os_tsk_delete
Example
&incl"de 6rtl.h7
..
os_tsk_delete_self();
}
128
os_tsk_pass
;i.rar' $eference E $eference E os8ts)8pass
Summary
&incl"de 6rtl.h7
void os_tsk_pass (void);
Description The os_tsk_pass function passes control to the ne<t tas) of the same priorit' in the
read' :ueue. *f there is no tas) of the same priorit' in the read' :ueue= the current
tas) continues and no tas) switching occurs.
The os_tsk_pass function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
"ou can use this function to implement a tas) switching s'stem .etween several
tas)s of the same priorit'.
Return Value The os_tsk_pass function does not return an' value.
See Also os_tsk_prio, os_tsk_prio_self
Example
&incl"de 6rtl.h7
*+_$!, tsk1;
..
os_tsk_pass();
..
}
129
os_tsk_prio
;i.rar' $eference E $eference E os8ts)8prio
Summary
&incl"de 6rtl.h7
*+_#=+JD$ os_tsk_prio (
*+_$!, task_id, / !, of the task /
JT ne(_prio ); / Ae( priority of the task (1)253) /
Description The os_tsk_prio function changes the e<ecution priorit' of the tas) identified .' the
argument task_"d.
*f the value of new_pr"o is higher than the priorit' of the currentl' e<ecuting tas)= a
tas) switch occurs to ena.le the tas) identified .' task_"d to run. *f the value of
new_pr"o is lower than the priorit' of the currentl' e<ecuting tas)= then the currentl'
e<ecuting tas) resumes its e<ecution.
*f the value of task_"d is = the priorit' of the currentl' running tas) is changed to
new_pr"o.
The os_tsk_prio function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
The value of new_pr"o can .e an'thing from 1 to &+(.
The new priorit' sta's in effect until 'ou change it.
Priorit' is reserved for the idle tas). *f priorit' is specified to the function= it is
automaticall' replaced with the value of 1 .' the $T% )ernel. Priorit' &++ is also
reserved.
! higher value for new_pr"o indicates a higher priorit'.
Return Value The os_tsk_prio function returns one of these valuesD
OS8$8O2 The priorit' of a tas) has .een successfull' changed.
OS8$8?O2 The tas) with task_"d does not e<ist or has not .een started.
See Also os_tsk_pass, os_tsk_prio_self
Example
&incl"de 6#$D.h7
*+_$!, tsk1,tsk2;
..
os_tsk_prio_self (5);
/ 0han1in1 the priority of task2 (ill ca"se a task s(itch. /
os_tsk_prio(tsk2, 10);
..
}
..
/ 0han1e priority of this task (ill ca"se task s(itch. /
os_tsk_prio_self (1);
..
}
130
os_tsk_prio_self
;i.rar' $eference E $eference E os8ts)8prio8self
Summary
&incl"de 6rtl.h7
*+_#=+JD$ os_tsk_prio_self (
JT ne(_prio ); / Ae( priority of task (1)253) /
Description The os_tsk_prio_self macro changes the priorit' of the currentl' running tas) tonew8prio.
The os_tsk_prio_self function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
The value of new_pr"o can .e an'thing from 1 to &+(.
The new priorit' sta's in effect until 'ou change it.
Priorit' is reserved for the idle tas). *f priorit' is specified to the function= it is
automaticall' replaced with the value of 1 .' the $T% )ernel. Priorit' &++ is also reserved.
! higher value for new_pr"o indicates a higher priorit'.
Return Value The os_tsk_prio_self function alwa's returns OS8$8O2.
See Also os_tsk_pass, os_tsk_prio
Example
&incl"de 6rtl.h7
*+_$!, tsk1;
..
os_tsk_prio_self(10); / !ncrease its priority, for the critical section /
.. / $his is a critical section /
..
os_tsk_prio_self(2); / ,ecrease its priority at end of critical section
/
..
}
131
os_tsk_self
;i.rar' $eference E $eference E os8ts)8self
Summary
&incl"de 6rtl.h7
*+_$!, os_tsk_self (void);
Description The os_tsk_self function identifies the currentl' running tas) .' returning its tas)
*D.
The os_tsk_self function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Return Value The os_tsk_self function returns the tas) identifier num.er @T*DA of the currentl'
running tas).
See Also isr_tsk_get, os_tsk_create, os_tsk_create_user
Example
&incl"de 6rtl.h7
*+_$!, tsk1;
tsk1 / os_tsk_self();
..
}
132
tsk_lock
;i.rar' $eference E $eference E ts)8loc)
Summary
&incl"de 6rtl.h7
void tsk_lock (void);
Description The tsk_lock function disa.les the $T% )ernel timer interrupts and there.' disa.les
tas) switching.
The task_lock function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
?ested calls of tsk_lock function are not supported.
/alling tsk_lock function from an interrupt handler is not allowed.
#or the duration when the timer interrupts are disa.led= the $T% )ernel tas)
scheduler is .loc)ed= timeouts do not wor)= and the $ound $o.in tas) scheduling is
also .loc)ed. 5ence= it is highl' recommended that disa.ling of the $T% )ernel
timer interrupts is )ept to a ver' short time period.
Return Value The tsk_lock function does not return an' value.
See Also tsk_unlock
Example
&incl"de 6rtl.h7
void free_mem (void ptr) {
/ <free()< is not reentrant. /
tsk_lock ();
free (ptr);
tsk_"nlock ();
}
133
tsk_unlock
;i.rar' $eference E $eference E ts)8unloc)
Summary
&incl"de 6rtl.h7
void tsk_"nlock (void);
Description The tsk_unlock function ena.les the $T% )ernel timer interrupts and there.' ena.les
tas) switching if the' had .een disa.led .' the tsk_lock function.
The tsk_unlock function is in the $;-$T% li.rar'. The protot'pe is defined in rtl.h.
Note
/alling tsk_lock function from an interrupt handler is not allowed.
Return Value The tsk_unlock function does not return an' value.
See Also tsk_lock
Example
&incl"de 6rtl.h7
void free_mem (void ptr) {
/ <free()< is not reentrant. /
tsk_lock ();
free (ptr);
tsk_"nlock ();
}
134
135

RL-ARM User's Guide

Diunggah oleh

Informasi Dokumen

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

RL-ARM User's Guide

Diunggah oleh

Hak Cipta:

Format Tersedia

RL-ARM User's Guide

Anda mungkin juga menyukai

RL-ARM User&#39;s Guide

Diunggah oleh

Informasi Dokumen

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

RL-ARM User&#39;s Guide

Diunggah oleh

Hak Cipta:

Format Tersedia

RL-ARM User's Guide

Anda mungkin juga menyukai

RL-ARM User's Guide

RL-ARM User's Guide