TEF020-S001-01.00.01/en

T-Kernel Specification
TEF020–S001–01.00.00/en
TEF020-S001-01.00.01/en

c 2002–2014
Copyright ©°2002–2005 by
by T-Engine
T-Engine Forum
Copyright

TEF020-S001-01.00.01/en

Notice:Please note that the year and version number in the copyright notice inthe footer of each page of the document has not been edited.
So please read this document with the understanding that the intended
year and the version number should read as follows:

T-Kernel Speciﬁcation
SpecificationVersion
Version1.00.01
1.00.00
Copyright ©°Forum
c 2002–2014
Copyright
2002–2005bybyT-Engine
T-Engine
Forum
TRON
Architecture:
DesignedbyKen
Sakamura
TRON Architecture: Designed by Ken Sakamura

Copyright © 2002–2005 by T-Engine ForumTEF020-S001-01.00.00/en

TEF020-S001-01.00.01/en

Contents
History of Revisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
System Call Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Index of T-Kernel API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

viii
ix
xi

1 T-Kernel Overview
1.1 Position of T-Kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 Scalability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1
1
2

2 Concepts Underlying the T-Kernel Specification
2.1 Meaning of Basic Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 Task States and Scheduling Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.1 Task States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.2 Task Scheduling Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 Interrupt Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4 Task Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5 System States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.1 System States While Non-task Portion Is Executing . . . . . . . . . . . . . . . .
2.5.2 Task-Independent Portion and Quasi-Task Portion . . . . . . . . . . . . . . . . .
2.6 Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.7 Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.7.1 Address Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.7.2 Nonresident Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.7.3 Protection Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5
5
6
6
9
11
12
12
12
13
14
15
15
15
16

3 Common T-Kernel Specifications
3.1 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.1 General Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.2 Other Defined Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 System Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.1 System Call Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.2 System Calls Possible from Task-Independent Portion . . . . . . . . . . . . . . .
3.2.3 Restricting System Call Invocation . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.4 Modifying a Parameter Packet . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.5 Function Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.6 Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.7 Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.8 Relative Time and System Time . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3 High-Level Language Support Routines . . . . . . . . . . . . . . . . . . . . . . . . . . .

17
17
17
18
19
19
19
20
20
21
21
21
22
23

iii

TEF020-S001-01.00.01/en

iv

CONTENTS

4 T-Kernel/OS Functions
4.1 Task Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cre tsk (Create Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk del tsk (Delete Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk sta tsk (Start Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk ext tsk (Exit Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk exd tsk (Exit and Delete Task) . . . . . . . . . . . . . . . . . . . . . . . . .
tk ter tsk (Terminate Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk chg pri (Change Task Priority) . . . . . . . . . . . . . . . . . . . . . . . . .
tk chg slt (Change Task Slice-time) . . . . . . . . . . . . . . . . . . . . . . . .
tk get tsp (Get Task Space) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk set tsp (Set Task Space) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk get rid (Get Task Resource ID) . . . . . . . . . . . . . . . . . . . . . . . . .
tk set rid (Set Task Resource ID) . . . . . . . . . . . . . . . . . . . . . . . . .
tk get reg (Get Task Registers) . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk set reg (Set Task Registers) . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk get cpr (Get Task Co-processor Registers) . . . . . . . . . . . . . . . . . . .
tk set cpr (Set Task Co-processor Registers) . . . . . . . . . . . . . . . . . . .
tk inf tsk (Get Task Information) . . . . . . . . . . . . . . . . . . . . . . . . .
tk ref tsk (Reference Task Status) . . . . . . . . . . . . . . . . . . . . . . . . .
4.2 Task-Dependent Synchronization Functions . . . . . . . . . . . . . . . . . . . . . . . . .
tk slp tsk (Sleep Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk wup tsk (Wakeup Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk can wup (Cancel Wakeup Task) . . . . . . . . . . . . . . . . . . . . . . . . . .
tk rel wai (Release Wait) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk sus tsk (Suspend Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk rsm tsk (Resume Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk frsm tsk (Force Resume Task) . . . . . . . . . . . . . . . . . . . . . . . . . .
tk dly tsk (Delay Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk sig tev (Signal Task Event) . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk wai tev (Wait Task Event) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk dis wai (Disable Task Wait) . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk ena wai (Enable Task Wait) . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3 Task Exception Handling Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk def tex (Define Task Exception Handler) . . . . . . . . . . . . . . . . . . . .
tk ena tex (Enable Task Exception) . . . . . . . . . . . . . . . . . . . . . . . .
tk dis tex (Disable Task Exception) . . . . . . . . . . . . . . . . . . . . . . . .
tk ras tex (Raise Task Exception) . . . . . . . . . . . . . . . . . . . . . . . . .
tk end tex (End Task Exception Handler) . . . . . . . . . . . . . . . . . . . . .
tk ref tex (Reference Task Exception Status) . . . . . . . . . . . . . . . . . . .
4.4 Synchronization and Communication Functions . . . . . . . . . . . . . . . . . . . . . . .
4.4.1 Semaphore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cre sem (Create Semaphore) . . . . . . . . . . . . . . . . . . . . . .
tk del sem (Delete Semaphore) . . . . . . . . . . . . . . . . . . . . . .
tk sig sem (Signal Semaphore) . . . . . . . . . . . . . . . . . . . . . .
tk wai sem (Wait on Semaphore) . . . . . . . . . . . . . . . . . . . . .
tk ref sem (Reference Semaphore Status) . . . . . . . . . . . . . . . .
4.4.2 Event Flag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cre flg (Create Event Flag) . . . . . . . . . . . . . . . . . . . . . .
tk del flg (Delete Event Flag) . . . . . . . . . . . . . . . . . . . . . .
c 2002–2005 by T-Engine Forum
Copyright °

25
26
27
31
32
33
34
35
37
39
41
42
43
44
45
46
47
48
49
50
53
54
55
56
57
59
61
61
63
64
65
66
68
69
70
72
72
73
74
76
77
78
79
81
82
83
85
86
87
89

TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

CONTENTS

4.5

4.6

4.7

v

tk set flg (Set Event Flag) . . . . . . . . . . . . . . . . . . . . . . . .
tk clr flg (Clear Event Flag) . . . . . . . . . . . . . . . . . . . . . . .
tk wai flg (Wait Event Flag) . . . . . . . . . . . . . . . . . . . . . . .
tk ref flg (Reference Event Flag Status) . . . . . . . . . . . . . . . .
4.4.3 Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cre mbx (Create Mailbox) . . . . . . . . . . . . . . . . . . . . . . .
tk del mbx (Delete Mailbox) . . . . . . . . . . . . . . . . . . . . . . . .
tk snd mbx (Send Message to Mailbox) . . . . . . . . . . . . . . . . . .
tk rcv msg (Receive Message from Mailbox) . . . . . . . . . . . . . . .
tk ref mbx (Reference Mailbox Status) . . . . . . . . . . . . . . . . . .
Extended Synchronization and Communication Functions . . . . . . . . . . . . . . . . .
4.5.1 Mutex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cre mtx (Create Mutex) . . . . . . . . . . . . . . . . . . . . . . . .
tk del mtx (Delete Mutex) . . . . . . . . . . . . . . . . . . . . . . . . .
tk loc mtx (Lock Mutex) . . . . . . . . . . . . . . . . . . . . . . . . .
tk unl mtx (Unlock Mutex) . . . . . . . . . . . . . . . . . . . . . . . .
tk ref mtx (Refer Mutex Status) . . . . . . . . . . . . . . . . . . . . .
4.5.2 Message Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cre mbf (Create Message Buffer) . . . . . . . . . . . . . . . . . . . .
tk del mbf (Delete Message Buffer) . . . . . . . . . . . . . . . . . . . .
tk snd mbf (Send Message to Message Buffer) . . . . . . . . . . . . . .
tk rcv mbf (Receive Message from Message Buffer) . . . . . . . . . . .
tk ref mbf (Get Message Buffer Status) . . . . . . . . . . . . . . . . .
4.5.3 Rendezvous Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cre por (Create Port for Rendezvous) . . . . . . . . . . . . . . . . .
tk del por (Delete Port for Rendezvous) . . . . . . . . . . . . . . . . .
tk cal por (Call Port for Rendezvous) . . . . . . . . . . . . . . . . . .
tk acp por (Accept Port for Rendezvous) . . . . . . . . . . . . . . . .
tk fwd por (Forward Rendezvous to Other Port) . . . . . . . . . . . .
tk rpl rdv (Reply Rendezvous) . . . . . . . . . . . . . . . . . . . . . .
tk ref por (Reference Port Status) . . . . . . . . . . . . . . . . . . . .
Memory Pool Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.1 Fixed-size Memory Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cre mpf (Create Fixed-size Memory Pool) . . . . . . . . . . . . . .
tk del mpf (Delete Fixed-size Memory Pool) . . . . . . . . . . . . . . .
tk get mpf (Get Fixed-size Memory Block) . . . . . . . . . . . . . . .
tk rel mpf (Release Fixed-size Memory Block) . . . . . . . . . . . . .
tk ref mpf (Reference Fixed-size Memory Pool Status) . . . . . . . . .
4.6.2 Variable-size Memory Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cre mpl (Create Variable-size Memory Pool) . . . . . . . . . . . . .
tk del mpl (Delete Variable-size Memory Pool) . . . . . . . . . . . . .
tk get mpl (Get Variable-size Memory Block) . . . . . . . . . . . . . .
tk rel mpl (Release Variable-size Memory Block) . . . . . . . . . . . .
tk ref mpl (Reference Variable-size Memory Pool Status) . . . . . . .
Time Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.7.1 System Time Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk set tim (Set Time) . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk get tim (Get Time) . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk get otm (Get Operating Time) . . . . . . . . . . . . . . . . . . . . .
4.7.2 Cyclic Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

c 2002–2005 by T-Engine Forum
Copyright °

90
90
92
95
96
98
100
101
103
105
106
107
109
111
112
114
115
116
118
121
122
124
126
128
130
132
133
135
139
143
145
147
148
149
151
152
154
155
156
157
160
161
163
164
165
166
167
168
169
170

TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

vi

CONTENTS
tk cre cyc (Create Cyclic Handler) . . . . . . . . . . . . . . . . . . . .
tk del cyc (Delete Cyclic Handler) . . . . . . . . . . . . . . . . . . . .
tk sta cyc (Start Cyclic Handler) . . . . . . . . . . . . . . . . . . . . .
tk stp cyc (Stop Cyclic Handler) . . . . . . . . . . . . . . . . . . . . .
tk ref cyc (Reference Cyclic Handler Status) . . . . . . . . . . . . . .
4.7.3 Alarm Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cre alm (Create Alarm Handler) . . . . . . . . . . . . . . . . . . . .
tk del alm (Delete Alarm Handler) . . . . . . . . . . . . . . . . . . . .
tk sta alm (Start Alarm Handler) . . . . . . . . . . . . . . . . . . . .
tk stp alm (Stop Alarm Handler) . . . . . . . . . . . . . . . . . . . . .
tk ref alm (Reference Alarm Handler Status) . . . . . . . . . . . . . .
4.8 Interrupt Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk def int (Define Interrupt Handler) . . . . . . . . . . . . . . . . . . . . . . .
tk ret int (Return from Interrupt Handler) . . . . . . . . . . . . . . . . . . . .
4.9 System Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk rot rdq (Rotate Ready Queue) . . . . . . . . . . . . . . . . . . . . . . . . . .
tk get tid (Get Task Identifier) . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk dis dsp (Disable Dispatch) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk ena dsp (Enable Dispatch) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk ref sys (Reference System Status) . . . . . . . . . . . . . . . . . . . . . . . .
tk set pow (Set Power Mode) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk ref ver (Reference Version Information) . . . . . . . . . . . . . . . . . . . .
4.10 Subsystem Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk def ssy (Define Subsystem) . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk sta ssy (Call Startup Function of Sub-System) . . . . . . . . . . . . . . . . .
tk cln ssy (Call Cleanup Function of Sub-System) . . . . . . . . . . . . . . . .
tk evt ssy (Call Event Function of Sub-System) . . . . . . . . . . . . . . . . . .
tk ref ssy (Reference Subsystem Status) . . . . . . . . . . . . . . . . . . . . . .
tk cre res (Create Resource Group) . . . . . . . . . . . . . . . . . . . . . . . .
tk del res (Delete Resource Group) . . . . . . . . . . . . . . . . . . . . . . . .
tk get res (Get Resource Management Block) . . . . . . . . . . . . . . . . . . .

171
174
175
176
177
178
179
181
182
183
184
186
187
190
192
193
195
196
198
199
201
203
206
207
213
213
214
215
216
218
219

5 T-Kernel/SM Functions
5.1 System Memory Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.1 System Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk get smb (Allocate System Memory Block) . . . . . . . . . . . . . .
tk rel smb (Release System Memory Block) . . . . . . . . . . . . . . .
tk ref smb (Reference System Memory Block) . . . . . . . . . . . . . .
5.1.2 Memory Allocation Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Vmalloc (Allocate Nonresident Memory) . . . . . . . . . . . . . . . . .
Vcalloc (Allocate Nonresident Memory Elements) . . . . . . . . . . .
Vrealloc (Reallocate Nonresident Memory) . . . . . . . . . . . . . . .
Vfree (Release Nonresident Memory) . . . . . . . . . . . . . . . . . . .
Kmalloc (Allocate Resident Memory) . . . . . . . . . . . . . . . . . . .
Kcalloc (Allocate Resident Memory Elements) . . . . . . . . . . . . .
Krealloc (Reallocate Resident Memory) . . . . . . . . . . . . . . . . .
Kfree (Release Resident Memory) . . . . . . . . . . . . . . . . . . . . .
5.2 Address Space Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.1 Address Space Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SetTaskSpace (Set Task Space) . . . . . . . . . . . . . . . . . . . . . .

221
222
222
222
222
222
223
223
223
223
223
223
223
223
223
224
224
224

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

CONTENTS
Address Space Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ChkSpaceR (Check Read Access Privilege) . . . . . . . . . . . . . . . .
ChkSpaceRW (Check Read-Write Access Privilege) . . . . . . . . . . . .
ChkSpaceRE (Check Read-Execute Access Privilege) . . . . . . . . . . .
ChkSpaceBstrR (Check Read Access Privilege (String)) . . . . . . . . .
ChkSpaceBstrRW (Check Read-Write Access Privilege (String)) . . . .
ChkSpaceTstrR (Check Read Access Privilege (TRON Code)) . . . . .
ChkSpaceTstrRW (Check Read-Write Access Privilege (TRON Code)) .
5.2.3 Lock Address Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LockSpace (Lock Address Space) . . . . . . . . . . . . . . . . . . . . .
UnlockSpace (Unlock Address Space) . . . . . . . . . . . . . . . . . . .
5.2.4 Get Physical Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CnvPhysicalAddr (Get Physical Address) . . . . . . . . . . . . . . . .
5.2.5 Map Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MapMemory (Map Memory) . . . . . . . . . . . . . . . . . . . . . . . . .
UnmapMemory (Unmap Memory) . . . . . . . . . . . . . . . . . . . . . .
Device Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.1 Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.2 Application Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk opn dev (Open Device) . . . . . . . . . . . . . . . . . . . . . . . . .
tk cls dev (Close Device) . . . . . . . . . . . . . . . . . . . . . . . . .
tk rea dev (Read Device) . . . . . . . . . . . . . . . . . . . . . . . . .
tk srea dev (Synchronous Read) . . . . . . . . . . . . . . . . . . . . .
tk wri dev (Write Device) . . . . . . . . . . . . . . . . . . . . . . . . .
tk swri dev (Synchronous Write) . . . . . . . . . . . . . . . . . . . . .
tk wai dev (Wait Device) . . . . . . . . . . . . . . . . . . . . . . . . .
tk sus dev (Suspend Device) . . . . . . . . . . . . . . . . . . . . . . .
tk get dev (Get Device Name) . . . . . . . . . . . . . . . . . . . . . .
tk ref dev (Reference Device by Device Name) . . . . . . . . . . . . .
tk oref dev (Reference Device by Device Descriptor) . . . . . . . . . .
tk lst dev (Get Registered Device Information) . . . . . . . . . . . . .
tk evt dev (Send Driver Request Event) . . . . . . . . . . . . . . . . .
5.3.3 Device Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk def dev (Register Device) . . . . . . . . . . . . . . . . . . . . . . .
tk ref idv (Reference Device Initialization Information) . . . . . . . .
5.3.4 Device Driver Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.5 Attribute Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.6 Device Event Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.7 Device Suspend/Resume Processing . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.8 Special Properties of Disk Devices . . . . . . . . . . . . . . . . . . . . . . . . . .
Interrupt Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.1 CPU Interrupt Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DI (Disable Interrupts) . . . . . . . . . . . . . . . . . . . . . . . . . . .
EI (Enable Interrupts) . . . . . . . . . . . . . . . . . . . . . . . . . . .
isDI (Get Interrupt Disable Status) . . . . . . . . . . . . . . . . . . . .
5.4.2 Control of Interrupt Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DINTNO (Get Interrupt Definition Number) . . . . . . . . . . . . . . . .
EnableInt (Enable Interrupt (Level)) . . . . . . . . . . . . . . . . . . .
DisableInt (Disable Interrupt) . . . . . . . . . . . . . . . . . . . . . .
ClearInt (Clear Interrupts) . . . . . . . . . . . . . . . . . . . . . . . .
5.2.2

5.3

5.4

vii

c 2002–2005 by T-Engine Forum
Copyright °

224
225
225
225
225
225
225
225
225
225
225
226
226
226
226
227
228
228
230
231
232
232
233
233
234
234
235
237
237
237
237
238
238
239
240
240
245
247
248
249
250
250
250
250
250
251
251
251
251
251

TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

viii

CONTENTS
EndOfInt (Issue End of Interrupt) . . . . . . . . . . . . . . . . . . . . .
CheckInt (Check Interrupt) . . . . . . . . . . . . . . . . . . . . . . . .
IO Port Access Support Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.5.1 IO Port Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
out w (Write Word Data) . . . . . . . . . . . . . . . . . . . . . . . . . .
out h (Write Half-Word Data) . . . . . . . . . . . . . . . . . . . . . . .
out b (Write Byte Data) . . . . . . . . . . . . . . . . . . . . . . . . . .
in w (Read Word Data) . . . . . . . . . . . . . . . . . . . . . . . . . .
in h (Read Half-Word Data) . . . . . . . . . . . . . . . . . . . . . . . .
in b (Read Byte Data) . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.5.2 Micro wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
WaitUsec (Microwait (Nanoseconds)) . . . . . . . . . . . . . . . . . . .
WaitNsec (Microwait (Microseconds)) . . . . . . . . . . . . . . . . . . .
Power Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
low pow (Enter Low-Power Mode) . . . . . . . . . . . . . . . . . . . . .
off pow (Suspend System) . . . . . . . . . . . . . . . . . . . . . . . . .
System Configuration Information Management Functions . . . . . . . . . . . . . . . . .
5.7.1 System Configuration Information Acquisition . . . . . . . . . . . . . . . . . . .
tk get cfn (Get Numeric String) . . . . . . . . . . . . . . . . . . . . .
tk get cfs (Get Character String) . . . . . . . . . . . . . . . . . . . .
5.7.2 Standard System Configuration Information . . . . . . . . . . . . . . . . . . . . .
Subsystem and Device Driver Starting . . . . . . . . . . . . . . . . . . . . . . . . . . . .

251
252
253
253
253
253
253
253
253
253
253
253
253
254
254
254
255
255
255
256
256
258

6 T-Kernel/DS Functions
6.1 Kernel Internal State Reference Functions . . . . . . . . . . . . . . . . . . . . . . . . . .
td lst tsk (Reference Object ID List) . . . . . . . . . . . . . . . . . . . . . . .
td lst sem (Reference Object Id List) . . . . . . . . . . . . . . . . . . . . . . . .
td lst flg (Reference Object Id List) . . . . . . . . . . . . . . . . . . . . . . . .
td lst mbx (Reference Object ID List) . . . . . . . . . . . . . . . . . . . . . . .
td lst mtx (Reference Object Id List) . . . . . . . . . . . . . . . . . . . . . . . .
td lst mbf (Reference Object Id List) . . . . . . . . . . . . . . . . . . . . . . . .
td lst por (Reference Object ID List) . . . . . . . . . . . . . . . . . . . . . . .
td lst mpf (Reference Object Id List) . . . . . . . . . . . . . . . . . . . . . . . .
td lst mpl (Reference Object Id List) . . . . . . . . . . . . . . . . . . . . . . . .
td lst cyc (Reference Object ID List) . . . . . . . . . . . . . . . . . . . . . . .
td lst alm (Reference Object Id List) . . . . . . . . . . . . . . . . . . . . . . . .
td lst ssy (Reference Object Id List) . . . . . . . . . . . . . . . . . . . . . . . .
td rdy que (Get Task Precedence) . . . . . . . . . . . . . . . . . . . . . . . . . .
td sem que (Reference Queue) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td flg que (Reference Queue) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td mbx que (Reference Queue) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td mtx que (Reference Queue) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td smbf que (Reference Queue) . . . . . . . . . . . . . . . . . . . . . . . . . . .
td rmbf que (Reference Queue) . . . . . . . . . . . . . . . . . . . . . . . . . . .
td cal que (Reference Queue) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td acp que (Reference Queue) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td mpf que (Reference Queue) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td mpl que (Reference Queue) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td ref tsk (Reference Task State) . . . . . . . . . . . . . . . . . . . . . . . . . .
td ref sem (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . .

261
262
263
263
263
263
263
263
263
263
263
263
263
263
264
265
265
265
265
265
265
265
265
265
265
266
268

5.5

5.6

5.7

5.8

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

CONTENTSix

td ref flg (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . .
td ref mbx (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . .
td ref mtx (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . .
td ref mbf (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . .
td ref por (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . .
td ref mpf (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . .
td ref mpl (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . .
td ref cyc (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . .
td ref alm (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . .
td ref ssy (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . .
td ref tex (Reference Task Exception Status) . . . . . . . . . . . . . . . . . . .
td inf tsk (Reference Task Statistics) . . . . . . . . . . . . . . . . . . . . . . .
td get reg (Get Task Register) . . . . . . . . . . . . . . . . . . . . . . . . . . .
td set reg (Set Task Register) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td ref sys (Reference System Status) . . . . . . . . . . . . . . . . . . . . . . . .
td get tim (Get System Time) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td get otm (Get System Operating Time) . . . . . . . . . . . . . . . . . . . . .
td ref dsname (Refer to DS Object Name) . . . . . . . . . . . . . . . . . . . . .
td set dsname (Set DS Object Name) . . . . . . . . . . . . . . . . . . . . . . . .
Trace Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td_hok_svc
td
hoc svc (Define System Call/Extended SVC Hook Routine) . . . . . . . . .
td_hok_dsp
hoc dsp (Define Task Dispatch Hook Routine) . . . . . . . . . . . . . . . . .
td
hoc int (Define Interrupt Handler Hook Routine) . . . . . . . . . . . . . . .
td
td_hok_int

268
268
268
268
268
268
268
268
268
268
271
272
273
274
275
276
277
278
280
281
282
284
286

7 Reference
7.1 List of C Language Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
T-Kernel/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
T-Kernel/SM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
T-Kernel/DS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2 List of Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

289
289
289
292
293
294

6.2

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

x

c 2002–2005 by T-Engine Forum
Copyright °CONTENTS

TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

List of Figures
1.1

Position of T-Kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1

2.1
2.2
2.3
2.4
2.5
2.6
2.7
2.8

Task State Transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Precedence in Initial State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Precedence After Task B Goes To RUN State . . . . . . . . . . . . . . . . . . . . . . . .
Precedence After Task B Goes To WAIT State . . . . . . . . . . . . . . . . . . . . . . .
Precedence After Task B WAIT State Is Released . . . . . . . . . . . . . . . . . . . . . .
Classification of System States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Interrupt Nesting and Delayed Dispatching . . . . . . . . . . . . . . . . . . . . . . . . .
Address Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

9
10
11
11
11
13
14
15

3.1

Behavior of High-Level Language Support Routine . . . . . . . . . . . . . . . . . . . . .

23

4.1 Multiple Tasks Waiting for One Event Flag . . . . . . . . . . . . . . . . . . . . . . . . .
4.2 Format of Messages Using a Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3 Synchronous Communication by Message Buffer . . . . . . . . . . . . . . . . . . . . . .
4.4 Synchronous Communication Using Message Buffer of bufsz = 0 . . . . . . . . . . . . .
4.5 Rendezvous Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6 Sample ADA-like Program Using select Statement . . . . . . . . . . . . . . . . . . . . .
4.7 Using Rendezvous to Implement ADA select Function . . . . . . . . . . . . . . . . . . .
4.8 Server Task Operation Using tk fwd por . . . . . . . . . . . . . . . . . . . . . . . . . .
4.9 Precedence Before Issuing tk rot rdq . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.10 Precedence After Issuing tk rot rdq (tskpri = 2) . . . . . . . . . . . . . . . . . . . . .
4.11 maker Field Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.12 prid Field Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.13 spver Field Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.14 T-Kernel Subsystems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.15 Subsystems and Resource Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

94
96
116
120
129
136
137
142
194
194
203
204
204
206
216

5.1

Device Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

xi

TEF020-S001-01.00.01/en

xii

c 2002–2005 by T-Engine Forum
Copyright °LIST OF FIGURES

TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

List of Tables
2.1

State Transitions Distinguishing Invoking Task and Other Tasks . . . . . . . . . . . . .

8

4.1
4.2
4.3

Target Task State and Execution Result (tk ter tsk) . . . . . . . . . . . . . . . . . . .
Values of tskwait and wid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Task States and Results of tk rel wai Execution . . . . . . . . . . . . . . . . . . . . . .

35
51
58

xiii

TEF020-S001-01.00.01/en

xiv

HISTORY OF REVISIONSHistory of Revisions
Version 1.00.00• Add functions to reference and set DS object name (td ref dsname() and td set dsname()).
Add TA DSNAME attribute totk cre tsk(), tk cre sem(), tk cre flg(), tk cre mbx(), tk cre mbf(), tk cre por(),tk cre mtx(), tk cre mpl(), tk cre mpf(), tk cre cyc(), tk cre alm().
• Add exclusive read mode (TD REXCL) to device open (tk opn dev()).

Version 1.B0.02• Enable/disable task exception (tk ena tex / tk dis tex) can be performed also for tasks in
DORMANT state. They do not return E OBJ error.
• Delete description that maker code is assigned by TRON Association in version reference(tk ref ver).
• Add “Overall notice and supplement” at toe top of the chapter of T-Kernel/SM.
• Describe that in get physical address (CnvPhysicalAddr) if it is not possible to make memory
cached off partly by a hardware limitation, this API flush the cache memory.
• Add functions (MapMemory, UnmapMemory) to map physical address space to logical space.
• Get system configuration information (tk get cfn and tk get cfs) become to be called fromany protection level.
• Describe that an entry routine (main function) for subsystems and device drivers is calledfrom a task which belongs to the system resource group.
• Correct that protection level violation error of T-Kernel/DS API is E OCAV; not E CTX.
• Correct general mistakes.

Version 1.B0.01• Add task start address (task) to TD RTSK structure.
• Correct that it is implementation-depended whether tk snd mbf() with tmout=TMO POL ispossible or not in task-independent part or in dispatch disabled state.
• Describe that in td hok svc() if one defined/undefined a hook routine after calling systemcall or extended SVC, then enter() or leave() may not be called.
• Describe that the maximum value of subsystem ID is implementation-depended.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

SYSTEM CALL NOTATION

xv

System Call Notation
In the parts of this specification that describe system calls, the specification of each system call is
explained in the format illustrated below.

System call nameSummary description
Summary description[C Language Interface]
Indicates the C language interface for invoking the system call.
[Parameters]
Describes the system call parameters, that is, the information passed to the OS when the system call is
executed.
[Return Parameters]
Describes the system call return parameters, that is, the information returned by the OS when executionof the system call ends.
[Error Codes]
Describes the errors that can be returned by the system call.
• The following error codes are common to all system calls and are not included in the error code
listings for each system call.
E SYS, E NOSPT, E RSFN, E MACV, E OACV
• Error code E CTX is included in the error code listings for individual system calls only when theconditions for its occurrence are clear (e.g., system calls that enter WAIT state). Depending on
the implementation, however, the E CTX error code may be returned by other system calls as well.
The implementation-specific occurrences of E CTX are not included in the error code specifications
for individual system calls.
[Description]
Describes the system call functions.
When the values to be passed in a parameter are selected from various choices, the following notation
is used in the parameter descriptions.
( x || y || z ) : Set one of x, y, or z.
x | y : Both x and y can be set at the same time (in which case the logical sum of x
and y is taken).
([x]) : x is optional.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

xvi

SYSTEM CALL NOTATION
Example:When wfmode := (TWF ANDW || TWF ORW) | [TWF CLR], wfmode can be specified in any of
the following four ways.
TWF_ANDWTWF_ORW(TWF_ANDW | TWF_CLR)(TWF_ORW | TWF_CLR)[Additional Notes]
Supplements the description by noting matters that need special attention or caution, etc.
[Rationale for the Specification]
Explains the reason for adopting a particular specification.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

INDEX OF T-KERNEL API

xvii

Index of T-Kernel API
The T-Kernel API (system call, extended SVC, library, macro) described in this specification are listed
below in alphabetical order.
CheckInt (Check Interrupt) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ChkSpaceBstrR (Check Read Access Privilege (String)) . . . . . . . . . . . . . . . . . .
ChkSpaceBstrRW (Check Read-Write Access Privilege (String)) . . . . . . . . . . . . . .
ChkSpaceR (Check Read Access Privilege) . . . . . . . . . . . . . . . . . . . . . . . . . .
ChkSpaceRE (Check Read-Execute Access Privilege) . . . . . . . . . . . . . . . . . . . .
ChkSpaceRW (Check Read-Write Access Privilege) . . . . . . . . . . . . . . . . . . . . .
ChkSpaceTstrR (Check Read Access Privilege (TRON Code)) . . . . . . . . . . . . . .
ChkSpaceTstrRW (Check Read-Write Access Privilege (TRON Code)) . . . . . . . . . .
ClearInt (Clear Interrupts) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CnvPhysicalAddr (Get Physical Address) . . . . . . . . . . . . . . . . . . . . . . . . . .
DI (Disable Interrupts) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DINTNO (Get Interrupt Definition Number) . . . . . . . . . . . . . . . . . . . . . . . . .
DisableInt (Disable Interrupt) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EI (Enable Interrupts) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EnableInt (Enable Interrupt (Level)) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EndOfInt (Issue End of Interrupt) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
in b (Read Byte Data) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
in h (Read Half-Word Data) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
in w (Read Word Data) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
isDI (Get Interrupt Disable Status) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Kcalloc (Allocate Resident Memory Elements) . . . . . . . . . . . . . . . . . . . . . . .
Kfree (Release Resident Memory) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Kmalloc (Allocate Resident Memory) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Krealloc (Reallocate Resident Memory) . . . . . . . . . . . . . . . . . . . . . . . . . .
LockSpace (Lock Address Space) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
low pow (Enter Low-Power Mode) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MapMemory (Map Memory) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
off pow (Suspend System) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
out b (Write Byte Data) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
out h (Write Half-Word Data) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
out w (Write Word Data) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SetTaskSpace (Set Task Space) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td acp que (Reference Queue) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td cal que (Reference Queue) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td flg que (Reference Queue) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td get otm (Get System Operating Time) . . . . . . . . . . . . . . . . . . . . . . . . . .
td get reg (Get Task Register) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td get tim (Get System Time) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td_hok_dsp
td
hoc dsp (Define Task Dispatch Hook Routine) . . . . . . . . . . . . . . . . . . . . .
td_hok_int
td
hoc int (Define Interrupt Handler Hook Routine) . . . . . . . . . . . . . . . . . . .
td_hok_svc
td hoc svc (Define System Call/Extended SVC Hook Routine) . . . . . . . . . . . . . .
td inf tsk (Reference Task Statistics) . . . . . . . . . . . . . . . . . . . . . . . . . . .
td lst alm (Reference Object Id List) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td lst cyc (Reference Object ID List) . . . . . . . . . . . . . . . . . . . . . . . . . . .
td lst flg (Reference Object Id List) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
c 2002–2005 by T-Engine Forum
Copyright °

252
225
225
225
225
225
225
225
251
226
250
251
251
250
251
251
253
253
253
250
223
223
223
223
225
254
226
254
253
253
253
224
265
265
265
277
273
276
284
286
282
272
263
263
263

TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

xviii

INDEX OF T-KERNEL API
td lst mbf (Reference Object Id List) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td lst mbx (Reference Object ID List) . . . . . . . . . . . . . . . . . . . . . . . . . . .
td lst mpf (Reference Object Id List) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td lst mpl (Reference Object Id List) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td lst mtx (Reference Object Id List) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td lst por (Reference Object ID List) . . . . . . . . . . . . . . . . . . . . . . . . . . .
td lst sem (Reference Object Id List) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td lst ssy (Reference Object Id List) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td lst tsk (Reference Object ID List) . . . . . . . . . . . . . . . . . . . . . . . . . . .
td mbx que (Reference Queue) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td mpf que (Reference Queue) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td mpl que (Reference Queue) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td mtx que (Reference Queue) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td rdy que (Get Task Precedence) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td ref alm (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td ref cyc (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td ref dsname (Refer to DS Object Name) . . . . . . . . . . . . . . . . . . . . . . . . .
td ref flg (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td ref mbf (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td ref mbx (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td ref mpf (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td ref mpl (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td ref mtx (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td ref por (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td ref sem (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td ref ssy (Reference Object Status) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td ref sys (Reference System Status) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td ref tex (Reference Task Exception Status) . . . . . . . . . . . . . . . . . . . . . . .
td ref tsk (Reference Task State) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td rmbf que (Reference Queue) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td sem que (Reference Queue) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td set dsname (Set DS Object Name) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td set reg (Set Task Register) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
td smbf que (Reference Queue) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk acp por (Accept Port for Rendezvous) . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cal por (Call Port for Rendezvous) . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk can wup (Cancel Wakeup Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk chg pri (Change Task Priority) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk chg slt (Change Task Slice-time) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cln ssy (Call Cleanup Function of Sub-System) . . . . . . . . . . . . . . . . . . . .
tk clr flg (Clear Event Flag) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cls dev (Close Device) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cre alm (Create Alarm Handler) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cre cyc (Create Cyclic Handler) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cre flg (Create Event Flag) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cre mbf (Create Message Buffer) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cre mbx (Create Mailbox) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cre mpf (Create Fixed-size Memory Pool) . . . . . . . . . . . . . . . . . . . . . . . .
tk cre mpl (Create Variable-size Memory Pool) . . . . . . . . . . . . . . . . . . . . . .
tk cre mtx (Create Mutex) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

c 2002–2005 by T-Engine Forum
Copyright °

263
263
263
263
263
263
263
263
263
265
265
265
265
264
268
268
278
268
268
268
268
268
268
268
268
268
275
271
266
265
265
280
274
265
135
133
56
37
39
213
90
232
179
171
87
118
98
149
157
109

TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

INDEX OF T-KERNEL API

xix

tk cre por (Create Port for Rendezvous) . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cre res (Create Resource Group) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cre sem (Create Semaphore) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk cre tsk (Create Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk def dev (Register Device) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk def int (Define Interrupt Handler) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk def ssy (Define Subsystem) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk def tex (Define Task Exception Handler) . . . . . . . . . . . . . . . . . . . . . . . .
tk del alm (Delete Alarm Handler) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk del cyc (Delete Cyclic Handler) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk del flg (Delete Event Flag) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk del mbf (Delete Message Buffer) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk del mbx (Delete Mailbox) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk del mpf (Delete Fixed-size Memory Pool) . . . . . . . . . . . . . . . . . . . . . . . .
tk del mpl (Delete Variable-size Memory Pool) . . . . . . . . . . . . . . . . . . . . . .
tk del mtx (Delete Mutex) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk del por (Delete Port for Rendezvous) . . . . . . . . . . . . . . . . . . . . . . . . . .
tk del res (Delete Resource Group) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk del sem (Delete Semaphore) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk del tsk (Delete Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk dis dsp (Disable Dispatch) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk dis tex (Disable Task Exception) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk dis wai (Disable Task Wait) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk dly tsk (Delay Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk ena dsp (Enable Dispatch) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk ena tex (Enable Task Exception) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk ena wai (Enable Task Wait) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk end tex (End Task Exception Handler) . . . . . . . . . . . . . . . . . . . . . . . . .
tk evt dev (Send Driver Request Event) . . . . . . . . . . . . . . . . . . . . . . . . . .
tk evt ssy (Call Event Function of Sub-System) . . . . . . . . . . . . . . . . . . . . . .
tk exd tsk (Exit and Delete Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk ext tsk (Exit Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk frsm tsk (Force Resume Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk fwd por (Forward Rendezvous to Other Port) . . . . . . . . . . . . . . . . . . . . . .
tk get cfn (Get Numeric String) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk get cfs (Get Character String) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk get cpr (Get Task Co-processor Registers) . . . . . . . . . . . . . . . . . . . . . . .
tk get dev (Get Device Name) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk get mpf (Get Fixed-size Memory Block) . . . . . . . . . . . . . . . . . . . . . . . . .
tk get mpl (Get Variable-size Memory Block) . . . . . . . . . . . . . . . . . . . . . . .
tk get otm (Get Operating Time) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk get reg (Get Task Registers) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk get res (Get Resource Management Block) . . . . . . . . . . . . . . . . . . . . . . .
tk get rid (Get Task Resource ID) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk get smb (Allocate System Memory Block) . . . . . . . . . . . . . . . . . . . . . . . .
tk get tid (Get Task Identifier) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk get tim (Get Time) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk get tsp (Get Task Space) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk inf tsk (Get Task Information) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk loc mtx (Lock Mutex) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
c 2002–2005 by T-Engine Forum
Copyright °

130
216
79
27
239
187
207
70
181
174
89
121
100
151
160
111
132
218
81
31
196
72
66
63
198
72
68
74
238
214
34
33
61
139
255
256
47
237
152
161
169
45
219
43
222
195
168
41
49
112

TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

xx

INDEX OF T-KERNEL API
tk lst dev (Get Registered Device Information) . . . . . . . . . . . . . . . . . . . . . .
tk opn dev (Open Device) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk oref dev (Reference Device by Device Descriptor) . . . . . . . . . . . . . . . . . . .
tk ras tex (Raise Task Exception) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk rcv mbf (Receive Message from Message Buffer) . . . . . . . . . . . . . . . . . . . .
tk rcv msg (Receive Message from Mailbox) . . . . . . . . . . . . . . . . . . . . . . . .
tk rea dev (Read Device) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk ref alm (Reference Alarm Handler Status) . . . . . . . . . . . . . . . . . . . . . . .
tk ref cyc (Reference Cyclic Handler Status) . . . . . . . . . . . . . . . . . . . . . . .
tk ref dev (Reference Device by Device Name) . . . . . . . . . . . . . . . . . . . . . .
tk ref flg (Reference Event Flag Status) . . . . . . . . . . . . . . . . . . . . . . . . . .
tk ref idv (Reference Device Initialization Information) . . . . . . . . . . . . . . . . .
tk ref mbf (Get Message Buffer Status) . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk ref mbx (Reference Mailbox Status) . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk ref mpf (Reference Fixed-size Memory Pool Status) . . . . . . . . . . . . . . . . . .
tk ref mpl (Reference Variable-size Memory Pool Status) . . . . . . . . . . . . . . . . .
tk ref mtx (Refer Mutex Status) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk ref por (Reference Port Status) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk ref sem (Reference Semaphore Status) . . . . . . . . . . . . . . . . . . . . . . . . . .
tk ref smb (Reference System Memory Block) . . . . . . . . . . . . . . . . . . . . . . .
tk ref ssy (Reference Subsystem Status) . . . . . . . . . . . . . . . . . . . . . . . . . .
tk ref sys (Reference System Status) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk ref tex (Reference Task Exception Status) . . . . . . . . . . . . . . . . . . . . . . .
tk ref tsk (Reference Task Status) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk ref ver (Reference Version Information) . . . . . . . . . . . . . . . . . . . . . . . .
tk rel mpf (Release Fixed-size Memory Block) . . . . . . . . . . . . . . . . . . . . . . .
tk rel mpl (Release Variable-size Memory Block) . . . . . . . . . . . . . . . . . . . . .
tk rel smb (Release System Memory Block) . . . . . . . . . . . . . . . . . . . . . . . .
tk rel wai (Release Wait) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk ret int (Return from Interrupt Handler) . . . . . . . . . . . . . . . . . . . . . . . .
tk rot rdq (Rotate Ready Queue) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk rpl rdv (Reply Rendezvous) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk rsm tsk (Resume Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk set cpr (Set Task Co-processor Registers) . . . . . . . . . . . . . . . . . . . . . . . .
tk set flg (Set Event Flag) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk set pow (Set Power Mode) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk set reg (Set Task Registers) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk set rid (Set Task Resource ID) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk set tim (Set Time) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk set tsp (Set Task Space) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk sig sem (Signal Semaphore) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk sig tev (Signal Task Event) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk slp tsk (Sleep Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk snd mbf (Send Message to Message Buffer) . . . . . . . . . . . . . . . . . . . . . . .
tk snd mbx (Send Message to Mailbox) . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk srea dev (Synchronous Read) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk sta alm (Start Alarm Handler) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk sta cyc (Start Cyclic Handler) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk sta ssy (Call Startup Function of Sub-System) . . . . . . . . . . . . . . . . . . . . .
tk sta tsk (Start Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

c 2002–2005 by T-Engine Forum
Copyright °

237
231
237
73
124
103
232
184
177
237
95
240
126
105
155
164
115
145
85
222
215
199
76
50
203
154
163
222
57
190
193
143
61
48
90
201
46
44
167
42
82
64
54
122
101
233
182
175
213
32

TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

INDEX OF T-KERNEL API

xxi

tk stp alm (Stop Alarm Handler) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk stp cyc (Stop Cyclic Handler) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk sus dev (Suspend Device) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk sus tsk (Suspend Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk swri dev (Synchronous Write) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk ter tsk (Terminate Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk unl mtx (Unlock Mutex) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk wai dev (Wait Device) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk wai flg (Wait Event Flag) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk wai sem (Wait on Semaphore) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk wai tev (Wait Task Event) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk wri dev (Write Device) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tk wup tsk (Wakeup Task) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UnlockSpace (Unlock Address Space) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UnmapMemory (Unmap Memory) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Vcalloc (Allocate Nonresident Memory Elements) . . . . . . . . . . . . . . . . . . . . .
Vfree (Release Nonresident Memory) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Vmalloc (Allocate Nonresident Memory) . . . . . . . . . . . . . . . . . . . . . . . . . .
Vrealloc (Reallocate Nonresident Memory) . . . . . . . . . . . . . . . . . . . . . . . .
WaitNsec (Microwait (Microseconds)) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
WaitUsec (Microwait (Nanoseconds)) . . . . . . . . . . . . . . . . . . . . . . . . . . . .

c 2002–2005 by T-Engine Forum
Copyright °

183
176
235
59
234
35
114
234
92
83
65
233
55
225
227
223
223
223
223
253
253

TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

xxii

c 2002–2005 by T-Engine Forum
Copyright °INDEX OF T-KERNEL API

TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

Chapter 1

T-Kernel Overview
1.1

Position of T-Kernel

The position of T-Kernel in the overall T-Engine system is shown in Figure 1.1.

Application #1

Subsystem #1

...

#2

...

#2

6

DeviceDriver #1...
#2

Middleware?
6

T-Kernel/OS
T-Kernel/DS
T-Kernel/SM

T-Kernel?

T-Monitor

Figure 1.1: Position of T-Kernel
T-Kernel generally refers to all of T-Kernel Operating System (T-Kernel/OS), T-Kernel System Manager (T-Kernel/SM), and T-Kernel Debugger Support (T-Kernel/DS); but in some cases T-Kernel/OS
only (narrow definition) is called T-Kernel.
T-Kernel Operating System (T-Kernel/OS) provides the following kinds of functions.
• Task control functions• Task communication functions• Memory management functions• Exception/interrupt control functions
1

TEF020-S001-01.00.01/en

2

CHAPTER 1. T-KERNEL OVERVIEW• Time management functions• Subsystem management functions

T-Kernel System Manager (T-Kernel/SM) provides the following kinds of functions.
• System memory management functions• Address space management functions• Device management functions• Interrupt management functions• I/O port access support functions• Power management functions• System configuration information management functions
T-Kernel Debugger Support (T-Kernel/DS) provides the following kinds of functions exclusively fordebugging use.
• Kernel internal state reference• Trace

1.2

Scalability

T-Kernel is a real-time kernel for embedded system use, applicable to a wide range of systems large andsmall. It is aimed at enhancing portability of software such as device drivers and middleware.
The T-Kernel specification is designed to be applicable even to large-scale systems. The approach ofdefining subsets to this end, with functions specified in some subsets but not mandatory in others forsmall-scale systems, has the disadvantage of hampering portability of device drivers, middleware andother software. Functional requirements also vary widely from one target system to another, making it
difficult to settle on workable subset specifications.
The T-Kernel specification does not adopt a level division or other subset approach. In principle, alloperating systems compliant with the T-Kernel specification must implement the specification in it
entirety. A target system, however, that does not need all the OS functions is free to implement a
scaled-down version of the OS. It is also acceptable to offer T-Kernel users the option of leaving out
functions not used in a target system. The important point here is that it is the user, not the OSprovider, who decides which functions to omit.
T-Kernel providers• The entire specification must be implemented. Scaled-down implementations for specifictarget systems are allowed.
• Providing users with the means for removing or skipping unnecessary functions is also allowed.
Middleware providers

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

1.2. SCALABILITY

3• Middleware must be designed to meet all the T-Kernel requirements. It cannot be limited to
specific target systems but must be applicable to a variety of systems and scales.
• Providing users with the means for removing or skipping unnecessary functions is allowed.
A “scaled-down implementation” means one that does not provide the entire range of specified functions
but does not behave abnormally (return error, etc.) if a non-implemented function is called. It is
important, in other words, that middleware developed for large-scale systems provide an environment
enabling it to run without problem on other systems. For example, a system that does not use an MMU
can implement the T-Kernel/SM LockSpace() as follows.
#define LockSpace(addr, len)

(E_OK)

The absence of an MMU does not, however, make it allowable not to implement LockSpace() or to
return the error code E NOSPT.
At the same time, when middleware is created, leaving out LockSpace() from an implementation because
the target system does not use an MMU would prevent the middleware from supporting a system that
does use an MMU.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4

c 2002–2005 by T-Engine Forum
Copyright °CHAPTER 1. T-KERNEL OVERVIEW

TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

Chapter 2

Concepts Underlying the T-Kernel
Specification
2.1

Meaning of Basic Terminology

1. Task, invoking task
The basic logical unit of concurrent program execution is called a “task”. Whereas the programs
assigned to one task are executed in sequence, programs assigned to different tasks can be executedin parallel. This concurrent processing is a conceptual phenomenon, from the standpoint of applications; in actual implementation it is accomplished by time-sharing among tasks as controlled
by the kernel.
A task that invokes a system call is called the “invoking task”.
2. Dispatch, dispatcher
The switching of tasks executed by the processor is called “dispatching” (or task dispatching). The
kernel mechanism by which dispatching is realized is called a “dispatcher” (or task dispatcher).
3. Scheduling, scheduler
The processing to determine which task to execute next is called “scheduling” (or task scheduling).
The kernel mechanism by which scheduling is realized is called a “scheduler” (or task scheduler).
Generally a scheduler is implemented inside system call processing or in the dispatcher.
4. Context
The environment in which a program runs is generally called “context”. For a context to becalled identical, at the very least the processor operation mode must be the same and the stackspace must be the same (part of the same contiguous area). Note that context is a conceptual
matter from the standpoint of applications; even when processing must be executed in independent
contexts, in actual implementation both contexts may sometimes use the same processor operation
mode and the same stack space.
5. Precedence
The relationship among different processing requests that determines their order of execution iscalled “precedence”. When a higher-precedence process becomes ready for execution while a lowprecedence process is in progress, as a general rule the higher-precedence process is run ahead of
the other process.
5

TEF020-S001-01.00.01/en

CHAPTER 2. CONCEPTS UNDERLYING THE T-KERNEL SPECIFICATION

6
Additional Note

Priority is a parameter assigned by an application to control the order of task or message processing.
Precedence, on the other hand, is a concept used in the specification to make clear the order in which
processing is to be executed. Precedence among tasks is determined based on task priority.

2.2

Task States and Scheduling Rules

2.2.1

Task States

Task states are classified primarily into the five below. Of these, Wait state in the broad sense is further
classified into three states. Saying that a task is in a Run state means it is in either RUN state or
READY state.
(a) RUN state
The task is currently being executed. When a task-independent portion is executing, except whenotherwise specified, the task that was executing prior to the start of task-independent portion
execution is said to be in RUN state.
(b) READY state
The task has completed preparations for running, but cannot run because a task with higher
precedence is running. In this state, the task is able to run whenever it becomes the task with thehighest precedence among the tasks in READY state.
(c) Wait states
The task cannot run because the conditions for running are not in place. In other words, the task
is waiting for the conditions for its execution to be met. While a task is in one of the Wait states,
the program counter and register values, and the other information representing the program
execution state, are saved. When the task resumes running from this state, the program counter,registers and other values revert to their values immediately prior to going to the Wait state. This
state is subdivided into the following three states.
(c.1) WAIT state
Execution is stopped because a system call was invoked that interrupts execution of the invoking
task until some condition is met.
(c.2) SUSPEND state
Execution was forcibly interrupted by another task.
(c.3) WAIT-SUSPEND state
The task is in both WAIT state and SUSPEND state at the same time. WAIT-SUSPEND state
results when another task requests suspension of a task already in WAIT state
T-Kernel makes a clear distinction between WAIT state and SUSPEND state. A task cannot go
to SUSPEND state on its own.
(d) DORMANT state
The task has not yet been started or has completed execution. While a task is in DORMANT state,
information presenting its execution state is not saved. When a task is started from DORMANT
state, execution starts from the task start address. Except when otherwise specified, the registervalues are not saved.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

2.2. TASK STATES AND SCHEDULING RULES

7(e) NON-EXISTENT state
A virtual state before a task is created, or after it is deleted, and is not registered in the system.
Depending on the implementation, there may also be transient states that do not fall into any of theabove categories (see section 2.5 on page 12).
When a task going to READY state has higher precedence than the currently running task, a dispatch
may occur at the same time as the task goes to READY state and it may make an immediate transition to RUN state. In such a case the task that was in RUN state up to that time is said to havebeen preempted by the task newly going to RUN state. Note also that in explanations of system callfunctions, even when a task is said to go to READY state, depending on the task precedence it may go
immediately to RUN state.
Task starting means transferring a state from DORMANT state to READY state. A task is therefore
said to be in “started” state if it is in any state other than DORMANT or NON-EXISTENT. Task exit
means that a task in started state goes to DORMANT state.
Task wait release means that a task in WAIT state goes to READY state, or a task in WAIT-SUSPEND
state goes to SUSPEND state. The resumption of a suspended task means that a task in SUSPEND
state goes to READY state, or a task in WAIT-SUSPEND state goes to WAIT state.
Task state transitions in a typical implementation are shown in Figure 2.1.
Depending on the implementation, there may be other states besides those shown here.
A feature of T-Kernel is the clear distinction made between system calls that perform operations affecting
the invoking task and those whose operations affect other tasks (see Table 2.1). The reason for this is
to clarify task state transitions and facilitate understanding of system calls. This distinction between
system call operations in the invoking task and operations affecting other tasks can also be seen as a
distinction between state transitions from RUN state and those from other states.
Additional Note
WAIT state and SUSPEND state are orthogonally related, in that a request for transition to SUSPEND
state cannot have any effect on the conditions for task wait release. That is, the task wait releaseconditions are the same whether the task is in WAIT state or WAIT-SUSPEND state. Thus even
if transition to SUSPEND state is requested for a task that is in a state of waiting to acquire someresource (semaphore resource, memory block, etc.), and the task goes to WAIT-SUSPEND state, theconditions for allocation of the resource do not change but remain the same as before the request to go
to SUSPEND state.
Rationale for the Specification
The reason the T-Kernel specification makes a distinction between WAIT state (wait caused by the
invoking task) and SUSPEND state (wait caused by another task) is that these states sometimes overlap.
By distinguishing this overlapped state as WAIT-SUSPEND state, the task state transitions become
clearer and system calls are easier to understand. On the other hand, since a task in WAIT state cannot
invoke a system call, different types of WAIT state (e.g., waiting for wakeup, or waiting to acquire asemaphore resource) will never overlap. Since there is only one kind of wait state caused by anothertask (SUSPEND state), the T-Kernel specification treats overlapping of SUSPEND states as nesting,thereby achieving clarity of task state transitions.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

8

CHAPTER 2. CONCEPTS UNDERLYING THE T-KERNEL SPECIFICATION

Operations in invoking task
(transitions from RUN state)

Operations on other tasks(transitions from other states)

tk slp tsk

tk sus tsk

RUN
↓
WAIT
tk ext tsk

READY
WAIT
↓
↓
SUSPEND WAIT-SUSPEND
tk ter tsk

Task exit

RUN↓
DORMANTtk exd tsk

READY WAIT↓↓
DORMANTtk del tsk

Task deletion

RUN↓
NON-EXISTENTDORMANT↓NON-EXISTENT

Task transition toa wait state(including
SUSPEND)

Table 2.1: State Transitions Distinguishing Invoking Task and Other Tasks

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

2.2. TASK STATES AND SCHEDULING RULES-

Dispatching

READY
¾

state
6 6

9

Preemption

6
Release
wait

state
Wait
condition¾
Terminate(tk ter tsk)

WAIT
state

6
Resume(tk rsm tsk,
tk frsm tsk)

Suspend(tk sus tsk)
-

RUN

?
WAIT-SUSPENDED
Terminate(tk ter tsk)

stateSuspend(tk sus tsk)-

Release wait?
SUSPEND
state

Resume(tk rsm tsk,
tk frsm tsk)

6

Start
(tk sta tsk)
Terminate(tk ter tsk)

DORMANT-

6

Delete(tk del tsk)?
NON-EXISTENT
state

Terminate¾¾
Exit (tk ext tsk)

state

Create(tk cre tsk)

Terminate(tk ter tsk)

Exit and delete¾(tk exd tsk)

Figure 2.1: Task State Transitions

2.2.2

Task Scheduling Rules

The T-Kernel specification adopts a preemptive priority-based scheduling method based on priority
levels assigned to each task. Tasks having the same priority are scheduled on a FCFS (First Come First
Served) basis. Specifically, task precedence is used as the task scheduling rule, and precedence amongc 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

CHAPTER 2. CONCEPTS UNDERLYING THE T-KERNEL SPECIFICATION

10

tasks is determined as follows based on the priority of each task. If there are multiple tasks that can berun, the one with the highest precedence goes to RUN state and the others go to READY state.
In determining precedence among tasks, of those tasks having different priority levels, that with thehighest priority has the highest precedence. Among tasks having the same priority, the one first goingto a run state (RUN state or READY state) has the highest precedence. It is possible, however, to usea system call to change the precedence among tasks having the same priority.
When the task with the highest precedence changes from one task to another, a dispatch occurs immediately and the task in RUN state is switched over. If no dispatch occurs, however, the switching of thetask in RUN state is held off until dispatch occurs.
Additional Note
According to the scheduling rules adopted in the T-Kernel specification, so long as there is a highprecedence task in a run state, a task with lower precedence will simply not run. That is, unless thehighest-precedence goes to WAIT state or for other reason cannot run, other tasks are not run. This is afundamental difference from TSS (Time Sharing System) scheduling in which multiple tasks are treatedequally. It is possible, however, to issue a system call changing the precedence among tasks having thesame priority. An application can use such a system call to realize round-robin scheduling, which is atypical kind of TSS scheduling.
precedence
priority- Task A-

hPriority 2i- Task B- Task C?
Low hPriority 3i- Task E-

Hight hPriority 1i
6- Task D-

Figure 2.2: Precedence in Initial State
Figure 2.2 and following illustrate how the task that first goes to a run state (RUN state or READY
state) gains precedence among tasks having the same priority. Figure 2.2 shows the precedence among
tasks after Task A of priority 1, Task E of priority 3, and Tasks B, C and D of priority 2 are started inthat order. The task with the highest precedence, Task A, goes to RUN state.
When Task A exits, Task B with the next-highest precedence goes to RUN state (Figure 2.3). When
Task A is again started, Task B is preempted and reverts to READY state; but since Task B went toa run state earlier than Task C and Task D, it still has the highest precedence among tasks with thesame priority. In other words, the task precedence reverts to that in Figure 2.2.
Next, consider what happens when Task B goes to WAIT state in the conditions in Figure 2.3. Sincetask precedence is defined among tasks that can be run, the precedence among tasks becomes as shownin Figure 2.4. Thereafter when the Task B wait state is released, Task B went to run state after Task
C and Task D, and thus assumes the lowest precedence among tasks of the same priority (Figure 2.5).
Summarizing the above, immediately after a task that went from READY state to RUN state reverts
to READY state, it has the highest precedence among tasks of the same priority; but after a task goesfrom RUN state to WAIT state and then the wait is released, its precedence is the lowest among tasksof the same priority.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

2.3. INTERRUPT HANDLING

11

precedence
priority
Hight hPriority 1i
6hPriority 2i- Task B- Task C?
Low hPriority 3i- Task E-- Task D-

Figure 2.3: Precedence After Task B Goes To RUN State
precedence
priority
Hight hPriority 1i
6hPriority 2i- Task C- Task D?
Low hPriority 3i- Task E--

Figure 2.4: Precedence After Task B Goes To WAIT State
Note that after a task goes from SUSPEND state to a run state, it has the lowest precedence among
tasks of the same priority. In a virtual memory system, since a task is made to wait for paging by putting
the task in SUSPEND state, in such a system the task precedence changes as a result of a paging wait.
precedence
priority
Hight hPriority 1i
6hPriority 2i- Task C- Task D?
Low hPriority 3i- Task E-- Task B-

Figure 2.5: Precedence After Task B WAIT State Is Released

2.3

Interrupt HandlingInterrupts in the T-Kernel specification include both external interrupts from devices and interrupts
due to CPU exceptions. One interrupt handler may be defined for each interrupt number. Interrupt
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

CHAPTER 2. CONCEPTS UNDERLYING THE T-KERNEL SPECIFICATION

12

handlers can be designed for direct starting, basically without OS intervention, or for starting via ahigh-level language support routine.

2.4

Task Exception Handling

The T-Kernel specification defines task exception handling functions for dealing with exceptions. Notethat exceptions other than those in the CPU are treated as interrupts.
A task exception handling function is one that invokes a system call requesting task exception handling,interrupts execution by the specified task, and runs a task exception handler. Execution of the task
exception handler takes place in the same context as the interrupted task. Upon return from the task
exception handler, the interrupted processing continues. One task exception handler per task can beregistered with an application.

2.5

System States

2.5.1

System States While Non-task Portion Is Executing

When programming tasks to run on T-Kernel, the changes in task states can be tracked by looking at
a task state transition diagram. In the case of routines such as interrupt handlers or extended SVC
handlers, however, the user must perform programming at a level closer to the kernel than tasks. In thiscase consideration must be made also of system states while a nontask portion is executing, otherwise
programming cannot be done properly. An explanation of T-Kernel system states is therefore given
here.
System states are classified as in Figure 2.6. Of these, a “transient state” is equivalent to OS runningstate (system call execution). From the standpoint of the user, it is important that each of the system
calls issued by the user be executed indivisibly, and that the internal states while a system call is
executing cannot be seen by the user. For this reason the state while the OS running is considered a“transient state” and internally it is treated as a blackbox. In the following cases, however, a transientstate is not executed indivisibly.
• When memory is being allocated or freed in the case of a system call that gets or releases memory(while a T-Kernel/SM system memory management function is called).
• In a virtual memory system, when nonresident memory is accessed in system call processing.
When a task is in a transient state such as these, the behavior of a task termination (tk ter tsk) systemcall is not guaranteed. Moreover, task suspension (tk sus tsk) may cause a deadlock or other problem
by stopping without clearing the transient state. Accordingly, as a rule tk ter tsk and tk sus tsk
cannot be used in programs. These system calls should be used only in a subsystem such as a virtual
memory system or debugger that is so close to being an OS that it can be thought of as part of the OS.
A task-independent portion and quasi-task portion are states while a handler is executing. The part ofa handler that runs in a task context is a quasi-task portion, and the part with a context independentof a task is a task-independent portion. An extended SVC handler, which processes extended system
calls defined by the user, is a quasi-task portion, whereas an interrupt handler or time event handler
triggered by an external interrupt is a task-independent portion. In a quasi-task portion, tasks have thesame kinds of state transitions as ordinary tasks and system calls can be issued even in WAIT state.
A transient state, task-independent portion, and quasi-task portion are together called a nontask portion.
When ordinary task programs are running, outside of these, this is “task portion running” state.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

2.5. SYSTEM STATES

13
Transient state
OS running, etc.

System state

Nontask portion
running

Task-independent portion running
Interrupt handler, etc.
Quasi-task portion running
Extended SVC handler(OS extended part, etc.)

Task portion running

Figure 2.6: Classification of System States

2.5.2

Task-Independent Portion and Quasi-Task Portion

A feature of a task-independent portion (interrupt handlers, time event handlers, etc.) is that it ismeaningless to identify the task that was running immediately prior to entering a task-independent
portion, and the concept of “invoking task” does not exist. Accordingly, a system call that enters
WAIT state, or one that is issued implicitly specifying the invoking task, cannot be called fromth atask-independent portion. Moreover, since the currently running task cannot be identified in a taskindependent portion, there is no task switching (dispatching). If dispatching is necessary, it is delayed
until processing leaves the task-independent portion. This is called delayed dispatching.
If dispatching were to take place in the interrupt handler, which is a task-independent portion, the restof the interrupt handler routine would be left over for execution after the task started by the dispatching,causing problems in case of interrupt nesting. This is illustrated in Figure 2.7.
In the example shown, Interrupt X is raised during Task A execution, and while its interrupt handler isrunning, a higher-priority interrupt Y is raised. In this case, if dispatching were to occur immediately
on return from interrupt Y (1), starting Task B, the processing of parts (2) to (3) of Interrupt A would
be put off until after Task B, with parts (2) to (3) executed only after Task A goes to RUN state. The
danger is that the low-priority Interrupt X handler would be preempted not only by a higher-priority
interrupt but even by Task B started by that interrupt. There would no longer be any guarantee of theinterrupt handler execution maintaining priority over task execution, making it impossible to write aninterrupt handler. This is the reason for introducing the principle of delayed dispatching.
A feature of a quasi-task portion, on the other hand, is that the task executing prior to entering thequasi-task portion (the requesting task) can be identified, making it possible to define task states justas in the task portion; moreover, it is possible to enter WAIT state while in a quasi-task portion.
Accordingly, dispatching occurs in a quasi-task portion in the same way as in ordinary task execution.
As a result, even though the OS extended part and other quasi-task portion is a nontask portion, its
execution does not necessarily have priority at all times over the task portion. This is in contrast tointerrupt handlers, which must always be given execution precedence over tasks.
The following two examples illustrate the difference between a task-independent portion and quasi-task
portion.
• An interrupt is raised while Task A (priority 8=low) is running, and in its interrupt handler(task-independent portion) tk wup tsk is issued for Task B (priority 2=high). In accord with theprinciple of delayed dispatching, however, dispatching does not yet occur at this point. Instead,after tk wup tsk execution, first the remaining parts of the interrupt handler are executed. Only
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

CHAPTER 2. CONCEPTS UNDERLYING THE T-KERNEL SPECIFICATION

14

when tk ret int is executed at the end of the interrupt handler does dispatching occur, causing
Task B to run.
• An extended system call is executed in Task A (priority 8=low), and in its extended SVC handler(quasi-task portion) tk wup tsk is issued for Task B (priority 2=high). In this case the principleof delayed dispatching is not applied, so dispatching occurs in tk wup tsk processing. Task A
goes to READY state in a quasi-task portion, and Task B goes to RUN state. Task B is therefore
executed before the rest of the extended SVC handler is completed. The rest of the extended SVC
handler is executed after dispatching occurs again and Task A goes to RUN state.

: Task portion
Task A(low priority)

Task B(high priority): Task-independent portion
Interrupt X(low priority)

Interrupt Y(high priority)-

Interrupt

Interrupt
nestingtk wup tsk B(2) ¾

tk ret int (1)tk wup tsk C(4) ¾

tk ret int (3)• If dispatching does not take place at (1), the remainder of the handler routine for Interrupt X ((2)
to (3)) ends up being put off until later.
Figure 2.7: Interrupt Nesting and Delayed Dispatching

2.6

Objects“Object” is the general term for resources handled by T-Kernel. Besides tasks, objects include memory
pools, semaphores, event flags, mailboxes and other synchronization and communication mechanisms,
as well as time event handlers (cyclic handlers and alarm handlers).
Attributes can generally be specified when an object is created. Attributes determine detailed differencesin object behavior or the object initial state. When TA XXXXX is specified for an object, that object iscalled a “TA XXXXX attribute object”. If there is no particular attribute to be defined, TA NULL (= 0) is
specified. Generally there is no interface provided for reading attributes after an object is registered.
In an object or handler attribute value, the lower bits indicate system attributes and the upper bits
indicate implementation-dependent attributes. This specification does not define the bit position atwhich the upper and lower distinction is to be made. In principle, however, the system attributec 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

2.7. MEMORY

15

portion is assigned from the least significant bit (LSB) toward the most significant bit (MSB), andimplementation-dependent attributes from the MSB toward the LSB. Bits not defining any attributemust be cleared to 0.
In some cases an object may contain extended information. Extended information is specified when theobject is registered. Information passed in parameters when an object starts execution has no effect on
T-Kernel behavior. Extended information can be read by calling an object status reference system call.

2.7

Memory2.7.1

Address Space

Memory addressable space is distinguished as system space (shared space) or task space (user space).
System space can be accessed equally by all tasks, whereas a task space is accessible only by the tasks
belonging to it (see Figure 2.8). Multiple tasks may in some cases belong to the sametask space.
The logical address space of task space and system space depends on the CPU (and MMU) limitations and is therefore implementation-dependent, but in principle task space should be assigned to low
addresses and system space to high addresses.
Logical addresses (examples)
0x00000000
0x3fffffff

Task space#1

Task space#2...

Task space#n0x40000000
System space
0x7fffffff
Figure 2.8: Address Space
Since interrupt handlers and other task-independent software are not tasks, they do not have a task
space of their own. Instead, while in a task-independent portion they belong to the task executing
just before entering the task-independent portion. This is the same as the task space of the currently
running task returned by tk get tid. When there is no task in RUN state, task space is undefined.
T-Kernel does not create or manage address space. Normally T-Kernel is used along with a subsystem
for handling address space management and the like.
In a system with no MMU (or not using an MMU), essentially task space does not exist.

2.7.2

Nonresident Memory

Memory may be resident or nonresident.
When nonresident memory is accessed, data is copied to that memory from a disk or other storage. It
therefore requires complicated processing such as disk access by a device driver.
Accordingly, when nonresident memory is accessed, the device driver, etc., must be in operational state.
Access is not possible during dispatch disabled or interrupts disabled state, or while a task-independent
portion is executing.
Similarly, in OS internal processing, it is necessary to avoid accessing nonresident memory in a criticalsection. One such case would be when the memory address passed in a system call parameter points
to nonresident memory. Whether or not system call parameters are allowed to indicate nonresident
memory is an implementation-dependent matter.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

CHAPTER 2. CONCEPTS UNDERLYING THE T-KERNEL SPECIFICATION

16

Data transfer from a disk or the like due to nonresident memory access is not performed by T-Kernel.
Normally T-Kernel is used along with subsystems that handle virtual memory management and othersuch processing.
In a system that does not use virtual memory, system call parameters or the like pointing to nonresident
memory can be ignored, treating all memory as resident.

2.7.3

Protection Levels

T-Kernel assumes four levels of memory protection, from 0 to 3.
• Level 0 has the highest privilege and level 3 the lowest.
• Access can be made only to memory at the currently running protection level or lower.
• Changing from one protection level to another is accomplished by invoking a system call or extended SVC, or by interrupt or CPU exception.
The uses of each protection level are as follows.

Protection level01
2
3

OS, subsystems, device drivers, etc.
System application tasks(reserved)
User application tasks

A nontask portion (task-independent portion, quasi-task portion, etc.) runs at protection level 0. Onlya task portion can run at protection levels 1 to 3. A task portion can also run at protection level 0.
Some MMUs support only two protection levels, privileged and user level. In such a case protectionlevels 0 to 2 are assigned to privileged level, and protection level 3 to the user level, as if there were 4
levels. In a system with no MMU, all protection levels 0 to 3 are treated as identical.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

Chapter 3

Common T-Kernel Specifications
3.1

Data Types

3.1.1

General Data Types

typedef chartypedef short
typedef int
typedef unsigned chartypedef unsigned short
typedef unsigned int

B;
H;
W;
UB;
UH;
UW;

/* signed 8-bit integer *//* signed 16-bit integer *//* signed 32-bit integer *//* unsigned 8-bit integer *//* unsigned 16-bit integer *//* unsigned 32-bit integer */typedef chartypedef short
typedef int
typedef void

VB;
VH;
VW;
*VP;

/* 8-bit data without a fixed type *//* 16-bit data without a fixed type *//* 32-bit data without a fixed type *//* pointer to data without a fixed type */typedef volatile B
typedef volatile H
typedef volatile W
typedef volatile UB
typedef volatile UH
typedef volatile UW

_B;
_H;
_W;
_UB;
_UH;
_UW;

/* volatile declaration */typedef int
typedef unsigned int

INT;
UINT;

/* signed integer of processor bit width*//* unsigned integer of processor bit width*/

typedef INT
typedef INT

ID;
MSEC;

/* general ID *//* general time (milliseconds)*/

typedef void
typedef INT(*FP)();(*FUNCP)();/* general function address *//* general function address */static/* local symbol definition *//* global symbol definition *//* global symbol reference */#define LOCAL#define EXPORT#define IMPORT

extern17

TEF020-S001-01.00.01/en

18

CHAPTER 3. COMMON T-KERNEL SPECIFICATIONS/** Boolean values*
TRUE = 1 is defined, but any value other than 0 is TRUE.
*
A decision such as bool == TRUE must be avoided for this reason.
*
Instead use bool != FALSE.
*/
typedef INT
BOOL;#define TRUE
1/* True */#define FALSE
0/* False *//** TRON character codes*/
typedef UHTC;#define TNULL((TC)0)/* TRON character code *//* TRON code string termination */• VB, VH, and VW differ from B, H, and W in that the former mean only the bit width is known, notthe contents of the data type, whereas the latter clearly indicate integer type.
• Processor bit width must be 32 bits or above. INT and UINT must therefore always have a widthof 32 bits or more.
• BOOL defines TRUE = 1, but any value other than 0 is also TRUE. For this reason a decision such asbool == TRUE must be avoided. Instead use bool != FALSE.
[Additional Notes]
Parameters such as stksz, wupcnt, and message size that clearly do not take negative values are alsoin principle signed integer (INT) data type. This is in keeping with the overall TRON rule that integers
should be treated as signed numbers to the extent possible. As for the timeout (TMO tmout) parameter,
its being a signed integer enables the use of TMO FEVR(= −1) having special meaning. Parameters with
unsigned data type are those treated as bit patterns (object attribute, event flag, etc.).

3.1.2

Other Defined Data Types

The following names are used for other data types that appear frequently or have special meaning, inorder to make the parameter meaning clear.
typedef INT
typedef INT
typedef UINT
typedef INT
typedef INT
typedef INT
typedef UINT

FN;
RNO;
ATR;
ER;
PRI;
TMO;
RELTIM;

typedef struct systim {Whi;
UW lo;} SYSTIM;/* Function code *//* Rendezvous number *//* Object/handler attributes *//* Error code *//* Priority *//* Timeout *//* Relative time *//* System time *//* High 32 bits *//* Low 32 bits */c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

3.2. SYSTEM CALLS

19/** Common constants*/#define NULL
#define TA_NULL#define TMO_POL#define TMO_FEVR

0
0
0
(-1)

/* Null pointer *//* No special attributes indicated *//* Polling *//* Eternal wait */• A data type that combines two or more data types is represented by its main data type. For
example, the value returned by tk cre tsk can be a task ID or error code, but since it is mainly
a task ID, the data type is ID.

3.2

System Calls

3.2.1

System Call Format

T-Kernel adopts C as the standard high-level language, and standardizes interfaces for system call
execution from C language routines.
The method for interfacing at the assembly language level is implementation-dependent and not standardized here. Calling by means of a C language interface is recommended even when an assembly
language program is created. In this way portability is assured for programs written in assembly language even if the OS changes, so long as the CPU is the same.
The following common rules are established for system call interfaces.
• All system calls are defined as C functions.
• A function return code of 0 or a positive value indicates normal completion, while negative values
are used for error codes.
All system call interfaces are provided as libraries. C language macros, in-line functions and in-line
assembly code are not used. The reason is that C macros and in-line functions can be used only froma C program. Moreover, since in-line functions and in-line assembly are not standard C features, theirfunctioning is in many cases compiler-dependent, diminishing portability.

3.2.2

System Calls Possible from Task-Independent Portion

It must be possible to issue the following system calls from a task-independent portion and in dispatch
disabled state. Whether other system calls can be issued from a task-independent portion or in dispatch
disabled state is implementation-dependent.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

20

CHAPTER 3. COMMON T-KERNEL SPECIFICATIONS
tk sta tsk
tk wup tsk
tk rel wai
tk sus tsk
tk sig sem
tk set flg
tk sig tev
tk rot rdq
tk get tid
tk sta cyc
tk stp cyc
tk sta alm
tk stp alm
tk ref tsk
tk ref cyc
tk ref alm
tk ref sys
tk ret int

3.2.3

Start task
Wakeup task
Release wait
Suspend task
Signal semaphore
Set event flag
Send event to task
Rotate task queueGet task ID
Start cyclic handler
Stop cyclic handler
Start alarm handler
Stop alarm handler
Reference task status
Reference cyclic handler status
Reference alarm handler status
Reference system status
Return from interrupt handler

Restricting System Call Invocation

The protection levels at which a system call is invokable can be restricted. In this case, if a system call
is issued from a task (task portion) running at lower than the specified protection level, the error code
E OACV is returned.
Extended SVC calling cannot be restricted.
If, for example, system call issuing from a protection level lower than 1 is prohibited, system calls cannot
be made from tasks running at protection levels 2 and 3. Tasks running at those levels will only be able
to make extended SVC calls, and are programmed using subsystem functions only.
This kind of restriction is used when T-Kernel is combined with an upper OS, to prevent tasks basedon the upper OS specification from directly accessing T-Kernel functions. It allows T-Kernel to be used
as a micro-kernel.
The protection level restriction on system call invocation is set using the system configuration information management functions (see 5.7 on page 255).

3.2.4

Modifying a Parameter Packet

Some parameters passed to system calls use a packet format. The packet format parameters are of two
kinds, either input parameters passing information to a system call (e.g., T CTSK) or output parameters
returning information from a system call (e.g., T RTSK).
Additional information that is implementation-dependent can be added to a parameter packet. It
is not allowable, however, to change the data types and order of information defined in the standard
specification or to delete any of this information. When implementation-dependent information is added,
it must be positioned after the standard defined information.
When implementation-dependent information is added to a packet of input information passed to asystem call (T CTSK, etc.), if the system call is invoked while this additional information is not yet
initialized (memory contents indeterminate), the system call must still function normally.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

3.2. SYSTEM CALLS

21

Ordinarily a flag indicating that valid values are set in the additional information is defined in theattribute flag implementation-dependent area included in the standard specification. When that flagis set (1), the additional information is to be used; and when the flag is not set (0), the additional
information is not initialized (memory contents indeterminate) and the default settings are to be used.
The reason for this specification is to ensure that a program developed within the scope of the standard
specification will be able to run on an OS with implementation-dependent functional extensions, simply
by recompiling.

3.2.5

Function Codes

Function codes are numbers assigned to each system call and used to identify the system call.
The system call function codes are not specified here but are to be defined in implementation.
See at tk def ssy on extended SVC function codes.

3.2.6

Error Codes

System call return codes are in principle to be signed integers. When an error occurs, a negative error
code is returned; and if processing is completed normally, E OK (= 0) or a positive value is returned.
The meaning of returned values in the case of normal completion is specified separately for each systemcall. An exception to this principle is that there are some system calls that do not return when called.
A system call that does not return is declared in the C language API as having no return code (that is,a void type function).
An error code consists of the main error code and sub error code. The low 16 bits of the error code are
the sub error code, and the remaining high bits are the main error code. Main error codes are classified
into error classes based on the necessity of their detection, the circumstances in which they occur andother factors. Since T-Kernel/OS does not use a sub error code, these bits are always 0.
#define MERCD(er)#define SERCD(er)#define ERCD(mer, ser)

3.2.7

( (ER)(er) >> 16 ) /* Main error code */( (H)(er) )/* Sub error code */( (ER)(mer) << 16 | (ER)(UH)(ser) )Timeout

A system call that may enter WAIT state has a timeout function. If processing is not completed by thetime the specified timeout interval has elapsed, the processing is canceled and the system call returns
error code E TMOUT.
In accord with the principle that there should be no side-effects from calling a system call if that systemcall returns an error code, the calling of a system call that times out should in principle result in nochange in system state. An exception to this is when the functioning of the system call is such thatit cannot return to its original state if processing is canceled. This is indicated in the system call
description.
If the timeout interval is set to 0, a system call does not enter even when a situation arises in which
it would ordinarily go to WAIT state. In other words, a system call with timeout set to 0 when it isinvoked has no possibility of entering WAIT state. Invoking a system call with timeout set to 0 is called
polling; that is, a system call that performs polling has no chance of entering WAIT state.
The descriptions of individual system calls as a rule describe the behavior when there is no timeout (inother words, when an endless wait occurs). Even if the system call description says that the system call“enters WAIT state” or “is put in WAIT state”, if a timeout is set and that time interval elapses before

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

22

CHAPTER 3. COMMON T-KERNEL SPECIFICATIONS

processing is completed, the WAIT state is released and the system call returns error code E TMOUT. In
the case of polling, the system call returns E TMOUT without entering WAIT state.
Timeout (TMO type) is made as a positive integer, or as TMO POL (= 0) for polling, or as TMO FEVR(= −1) for endless wait. If a timeout interval is set, the timeout processing must be guaranteed to takeplace even after the specified interval from the system call issuing has elapsed.
[Additional Notes]
Since a system call that performs polling does not enter WAIT state, there is no change in the precedenceof the task calling it.
In a general implementation, when the timeout is set to 1, timeout processing takes place on the second
time tick after a system call is invoked. Since a timeout of 0 cannot be specified (0 being allocated to
TMO POL), in this kind of implementation timeout does not occur on the initial time tick after the systemcall is invoked.

3.2.8

Relative Time and System Time

When the time of an event occurrence is specified relative to another time, such as the time when asystem call was invoked, relative time (RELTIM type) is used. If relative time is used to specify event
occurrence time, it is necessary to guarantee that the event processing will take place after the specified
time has elapsed from the time base. Relative time (RELTIM type) is also used for e.g. event occurrence.
In such cases the method of interpreting the specified relative time is determined for each case.
When time is specified as an absolute value, system time (SYSTIM type) is used. The T-Kernel specification provides a function for setting system time, but even if the system time is changed using thisfunction, there is no change in the real world time (actual time) at which an event occurred that was
specified using relative time. What changes is the system time at which an event occurred that was
specified as relative time.
• SYSTIM: System time
Time base 1 millisecond, 64-bit signed integer

typedef struct systim {Whi; /* high 32 bits */UW lo; /* low 32 bits */} SYSTIM;• RELTIM: Relative time
Time base 1 millisecond, 32-bit or higher unsigned integer (UINT)
typedef UINTRELTIM;• TMO: Timeout time Time base 1 millisecond, 32-bit or higher signed integer (INT)
typedef INT

TMO;Endless wait can be specified as TMO FEVR = (−1).

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

23

3.3. HIGH-LEVEL LANGUAGE SUPPORT ROUTINES
Additional Note

Timeout or other such processing must be guaranteed to occur after the time specified as RELTIM or
TMO has elapsed. For example, if the timer interrupt cycle is 1 ms and a timeout of 1 ms is specified,timeout occurs on the second timer interrupt. (The first timer interrupt does not exceed 1 ms.)

3.3

High-Level Language Support Routines

High-level language support routine capability is provided so that even if a task or handler is written in
high-level language, the kernel-related processing can be kept separate from the language environmentrelated processing. Whether or not a high-level language support routine is used is specified in TA HLNG,
one of the object attributes and handler attributes.
When TA HLNG is not specified, a task or handler is started directly from the start address passed in aparameter to tk cre tsk or tk def ???; whereas when TA HLNG is specified, first the high-level language
startup processing routine (high-level language support routine) is started, then from this routine anindirect jump is made to the task start address or handler address passed in a parameter to tk cre tsk
or tk def ???. Viewed from the OS, the task start address or handler address is a parameter pointing to
the high-level language support routine. Separating the kernel processing from the language environment
processing in this way facilitates support for different language environments.
Use of high-level language support routines has the further advantage that when a task or handler iswritten as a C language function, a system call for task exit or return from a handler can be executed
automatically, simply by performing a function return (return or “}”).
In a system that uses an MMU, however, whereas it is relatively easy to realize a high-level language
support routine in the case of an interrupt handler or the like that runs at the same protection level
as the OS, it is more difficult in the case of a task or task exception handler running at a different
protection level than the OS. For this reason, when a high-level language support routine is used fora task, there is no guarantee that the task will exit by a return from the function. In the case of atask exception handler, the high-level language support routine is supplied as source code and is to beembedded in the user program.
The internal working of a high-level language support routine is as illustrated in Figure 3.1.
Handler as seen from T-Kernel
T-KernelHigh-level language
support routine-

C function representing
handler-

JSR, etc.
¾
T-Kernel ¾

TRAPA[tk ret int]
return()Figure 3.1: Behavior of High-Level Language Support Routine

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

24

c 2002–2005 by T-Engine Forum
Copyright °CHAPTER 3. COMMON T-KERNEL SPECIFICATIONSTEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

Chapter 4

T-Kernel/OS Functions
This chapter describes in detail the system calls provided by the T-Kernel Operating System (TKernel/OS).

25

TEF020-S001-01.00.01/en

26

4.1

CHAPTER 4. T-KERNEL/OS FUNCTIONSTask Management Functions

Task management functions are functions that directly manipulate or reference task states. Functions
are provided for creating and deleting a task, for task starting and exit, canceling a task start request,changing task priority, and referencing task state. A task is an object identified by an ID number calleda task ID. Task states and scheduling rules are explained at 2.2.
For control of execution order, a task has a base priority and current priority. When simply “taskpriority” is talked about, this means the current priority. The base priority of a task is initialized as
the startup priority when a task is started. If the mutex function is not used, the task current priority
is always identical to its base priority. For this reason, the current priority immediately after a task
is started is the task startup priority. When the mutex function is used, the current priority is set as
discussed at 4.5.1.
The kernel does not perform processing for freeing of resources acquired by a task (semaphore resources,
memory blocks, etc.) upon task exit, other than mutex unlocking. Freeing of task resources is the
responsibility of the application.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.1. TASK MANAGEMENT FUNCTIONS

27

tk cre tsk
Create Task
[C Language Interface]
ID tskid = tk_cre_tsk ( T_CTSK *pk_ctsk ) ;[Parameters]
T CTSK*

pk ctsk

Information about the task to be createdpk ctsk detail:
VP
ATR
FP
PRI
INT
INT
VP
VP
INT
ID
UB

exinf
tskatrtask
itskpristksz
sstkszstkptr
uatb
lsid
resid
dsname[8]Extended information
Task attributes
Task start address
Initial task priority
Stack size (bytes)
System stack size (bytes)
User stack pointerTask space page table
Logical space ID
Resource ID
DS object name

(Other implementation-dependent parameters may be added beyond this point.)[Return Parameters]
ID

tskid
or

Task ID
Error Code[Error Codes]
E NOMEM
E LIMITE RSATRE NOSPT
E PAR
E ID
E NOCOP

Insufficient memory (memory for control block or user stack cannot be allocated)
Number of tasks exceeds the system limit
Reserved attribute (tskatr is invalid or cannot be used), or the specified co-processor
does not exist
Unsupported function (when TA USERSTACK or TA TASKSPACE is not supported)
Parameter error
Invalid resource ID (resid)
The specified co-processor cannot be used (not installed, or abnormal operation detected)

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

28

CHAPTER 4. T-KERNEL/OS FUNCTIONS[Description]
Creates a task, assigning to it a task ID number. This system call allocates a TCB (Task Control Block)to the created task and initializes it based on itskpri, task, stksz and other parameters.
After the task is created, it is initially in DORMANT state.
itskpri specifies the initial priority at the time the task is started.
Task priority values are specified from 1 to 140, with the smaller numbers indicating higher priority.
exinf can be used freely by the user to insert miscellaneous information about the task. The information
set here is passed to the task as startup parameter information and can be referred to by calling
tk ref tsk. If a larger area is needed for indicating user information, or if the information may need to
be changed after the task is created, this can be done by allocating separate memory for this purpose
and putting the memory packet address in exinf. The OS pays no attention to the contents of exinf.
tskatr indicates system attributes in its low bits and implementation-dependent information in thehigh bits. The system attributes part of tskatr is as follows.
tskatr := (TA_ASM || TA_HLNG)| [TA_SSTKSZ] | [TA_USERSTACK] | [TA_TASKSPACE] | [TA_RESID]| [TA_DSNAME]| (TA_RNG0 || TA_RNG1 || TA_RNG2 || TA_RNG3)| [TA_COP0] | [TA_COP1] | [TA_COP2] | [TA_COP3] | [TA_FPU]
TA ASMTA HLNGTA SSTKSZTA USERSTACKTA TASKSPACETA RESIDTA DSNAMETA RNGn
TA COPnTA FPU

Indicates that the task is written in assembly language
Indicates that the task is written in high-level language
Specifies the system stack size
Points to the user stack
Points to the task space
Specifies the resource group to which the task belongs
Specifies DS object nameIndicates that the task runs at protection level nSpecifies use of the nth co-processor (including floating point co-processor or
DSP)
Specifies use of a floating point co-processor (when a co-processor specified in
TA COPn is a general-purpose FPU particularly for floating point processing
and not dependent on the CPU)

The function for specifying implementation-dependent attributes can be used, for example, to specify
that a task is subject to debugging. One use of the remaining system attribute fields is for indicating
multiprocessor attributes in the future.
#define TA_ASM#define TA_HLNG#define TA_SSTKSZ#define TA_USERSTACK#define TA_TASKSPACE#define TA_RESID#define TA_DSNAME#define TA_RNG0#define TA_RNG1

0x00000000
0x00000001
0x00000002
0x00000004
0x00000008
0x00000010
0x00000040
0x00000000
0x00000100

c 2002–2005 by T-Engine Forum
Copyright °/* Assembly program*//* High-level language program *//* System stack size*//* User stack pointer*//* Task space pointer*//* Task resource group*//* DS object name*//* Run at protection level 0*//* Run at protection level 1*/
TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.1. TASK MANAGEMENT FUNCTIONS#define TA_RNG2#define TA_RNG3#define TA_COP0#define TA_COP1#define TA_COP2#define TA_COP3

0x00000200
0x00000300
0x00001000
0x00002000
0x00004000
0x00008000/* Run at protection level 2/* Run at protection level 3/* Use ID=0 coprocessor/* Use ID=1 coprocessor/* Use ID=2 coprocessor/* Use ID=3 coprocessor

29
*/
*/
*/
*/
*/
*/

When TA HLNG is specified, starting the task jumps to the task address not directly but by going througha high-level language environment configuration program (high-level language support routine). The
task takes the following form in this case.
void task( INT stacd, VP exinf ){/*(processing)*/tk_ext_tsk(); or tk_exd_tsk();}/* Exit task */The startup parameters passed to the task include the task startup code stacd specified in tk sta tsk,
and the extended information exinf specified in tk cre tsk.
The task cannot (must not) be terminated by a simple return from the function, otherwise the operation
will be indeterminate (implementation-dependent).
The form of the task when the TA ASM attribute is specified in implementation-dependent, but stacd
and exinf must be passed as startup parameters.
The task runs at the protection level specified in the TA RNGn attribute. When a system call or extended
SVC is called, the protection level goes to 0, then goes back to its original level upon return from thesystem call or extended SVC.
Each task has two stack areas, a system stack and user stack. The user stack is used at the protectionlevel specified in TA RNGn , while the system stack is used at protection level 0. When the calling of asystem call or extended SVC causes the protection level to change, the stack is also switched.
Note that a task running at TA RNG0 does not switch protection levels, so there is no stack switchingeither. When TA RNG0 is specified, the combined total of the user stack size and system stack size is thesize of one stack, employed as both a user stack and system stack.
When TA SSTKSZ is specified, sstksz is valid. If TA SSTKSZ is not specified, sstksz is ignored and thedefault size applies.
When TA USERSTACK is specified, stkptr is valid. In this case a user stack is not provided by the OS,
but must be allocated by the caller. stksz must be set to 0. If TA USERSTACK is not specified, stkptr
is ignored. Note that if TA RNG0 is set, TA USERSTACK cannot be specified.
When TA TASKSPACE is specified, uatb and lsid are valid and are set as task space. If TA TASKSPACE
is not specified, uatb and lsid are ignored and task space is undefined. During the time task space isundefined, only system space can be accessed; access to task (user) space is not allowed. Whether or
not TA TASKSPACE was specified, task space can be changed after a task is created. Note that when task
space is changed, in no case does it revert to the task space set at task creation, even when the task
returns to DORMANT state, but the task always uses the most recently set task space.
When TA RESID is specified, resid is valid and specifies the resource group to which the task belongs.
If TA RESID is not specified, resid is ignored and the task belongs to the system resource group. Notethat if the resource group of a task is changed, in no case does it revert to the resource group set attask creation, even when the task returns to DORMANT state, but the task always retains the mostrecently set resource group (see tk cre res).
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

30

CHAPTER 4. T-KERNEL/OS FUNCTIONSWhen TA DSNAME is specified, dsname is valid and specifies the DS object name. DS object name isused to identify objects by debugger, and it is handled only by T-Kernel/DS API, td ref dsname andtd set dsname. For more details refer to td ref dsname and td set dsname. If TA DSNAME is not
specified, dsname is ignored. Then td ref dsname and td set dsname return E OBJ error.
[Additional Notes]
A task runs either at the protection level set in TA RNGn or at protection level 0. For example, a task
for which TA RNG3 is specified in no case runs at protection level 1 or 2.
In a system with separate interrupt stack, interrupt handlers also use the system stack. An interrupt
handler runs at protection level 0.
The system stack default size is decided taking into account the amount taken up by system call execution
and, in a system with separate interrupt stack, the amount used by interrupt handlers.
The system stack is system space resident memory used at protection level 0. If TA USERSTACK is not
specified, the user stack is system space resident memory used at the protection level specified in the
TA RNGn attribute. If TA USERSTACK is specified, the user stack memory attributes are as specified by
the caller of this system call. Task space may be made nonresident memory. The definition of TA COPn
is dependent on the CPU and other hardware and is not portable. TA FPU is provided as a portable
notation method only for the definition in TA COPn of a floating point processor. If, for example, thefloating point processor is TA COP0, then TA FPU = TA COP0. If there is no particular need to specify useof a co-processor for floating point operations, TA FPU = 0 is set.
Even in a system without an MMU, for the sake of portability all attributes including TA RNGn mustbe accepted. It is possible, for example, to handle all TA RNGn as equivalent to TA RNG0, but error mustnot be returned. In the case of TA USERSTACK and TA TASKSPACE, however, E NOSPT may be returned,
since there are many cases where these cannot be supported without an MMU.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.1. TASK MANAGEMENT FUNCTIONS

31

tk del tsk
Delete Task
[C Language Interface]
ER ercd = tk_del_tsk ( ID tskid ) ;[Parameters]
ID

tskid

Task ID[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXSE OBJNormal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Invalid object state (the task is not in DORMANT state)[Description]
Deletes the task specified in tskid.
This system call changes the state of the task specified in tskid from DORMANT state to NONEXISTENT state (no longer exists in the system), releasing the TCB and stack area that were assigned
to the task. The task ID number is also released. When this system call is issued for a task not in
DORMANT state, error code E OBJ is returned.
This system call cannot specify the invoking task. If the invoking task is specified, error code E OBJ isreturned since the invoking task is not in DORMANT state. The invoking task is deleted not by thissystem call but by the tk exd tsk system call.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

32

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk sta tsk
Start Task
[C Language Interface]
ER ercd = tk_sta_tsk ( ID tskid, INT stacd ) ;[Parameters]
ID
INT

tskid
stacd

Task ID
Task start code

[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXSE OBJNormal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Invalid object state (the task is not in DORMANT state)[Description]
Starts the task specified in tskid.
This system call changes the state of the specified task from DORMANT state to READY state.
Parameters to be passed to the task when it starts can be set in stacd. These parameters can bereferred to from the started task, enabling use of this feature for simple message passing.
The task priority when it starts is the task startup priority (itskpri) specified when the started task
was created.
Start requests by this system call are not queued. If this system call is issued while the target task is ina state other than DORMANT state, the system call is ignored and error code E OBJ is returned to thecalling task.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.1. TASK MANAGEMENT FUNCTIONS

33

tk ext tsk
Exit Task[C Language Interface]void tk_ext_tsk ( ) ;[Parameters]
None[Return Parameters]
Does not return to the context issuing the system call.
[Error Codes]
The following error can be detected; but since this system call does not return to the context issuing
the system call even when error is detected, an error code cannot be passed directly in a system callreturn parameter. The behavior in case an error occurs is implementation-dependent.
E CTX

Context error (issued from task-independent portion or in dispatch disabled state)[Description]
Exits the invoking task normally and changes its state to DORMANT state.
[Additional Notes]
When a task terminates by tk ext tsk, the resources acquired by the task up to that time (memory
blocks, semaphores, etc.) are not automatically freed. The user is responsible for releasing such resources
before the task exits.
tk ext tsk is a system call that does not return to the context from which it was called. Even if anerror code is returned when an error of some kind is detected, normally no error checking is performedin the context from which the system call was invoked, leaving the possibility that the program willhang. For this reason these system calls do not return even if error is detected.
As a rule, the task priority and other information included in the TCB is reset when the task returns
to DORMANT state. If, for example, the task priority is changed by tk chg pri and later terminatedby tk ext tsk, the task priority reverts to the startup priority (itskpri) specified when the task wasstarted. It does not keep the task priority in effect at the time tk ext tsk was executed.
System calls that do not return to the calling context are those named tk ret ??? or tk ext ???
(tk exd ???).

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

34

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk exd tsk
Exit and Delete Task
[C Language Interface]void tk_exd_tsk ( ) ;[Parameters]
None.
[Return Parameters]
Does not return to the context issuing the system call.
[Error Codes]
The following error can be detected; but since this system call does not return to the context issuing
the system call even when error is detected, an error code cannot be passed directly in a system callreturn parameter. The behavior in case an error occurs is implementation-dependent.
E CTX

Context error (issued from task-independent portion or in dispatch disabled state)[Description]
Terminates the invoking task normally and also deletes it.
This system call changes the state of the invoking task to NON-EXISTENT state (no longer exists inthe system).
[Additional Notes]
When a task terminates by tk exd tsk, the resources acquired by the task up to that time (memory
blocks, semaphores, etc.) are not automatically freed. The user is responsible for releasing such resources
before the task exits.
tk exd tsk is a system call that does not return to the context from which it was called. Even if anerror code is returned when an error of some kind is detected, normally no error checking is performedin the context from which the system call was invoked, leaving the possibility that the program willhang. For this reason these system calls do not return even if error is detected.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.1. TASK MANAGEMENT FUNCTIONS

35

tk ter tsk
Terminate Task
[C Language Interface]
ER ercd = tk_ter_tsk ( ID tskid ) ;[Parameters]
ID

tskid

Task ID[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXSE OBJNormal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Invalid object state (the target task is in DORMANT state or is the invoking task)[Description]
Forcibly terminates the task specified in tskid.
This system call changes the state of the target task specified in tskid to DORMANT state.
Even if the target task was in a wait state (including SUSPEND state), the wait state is released andthe task is terminated. If the target task was in some kind of queue (semaphore wait, etc.), executing
tk ter tsk results in its removal from the queue.
This system call cannot specify the invoking task. If the invoking task is specified, error code E OBJ isreturned
The relationships between target task states and the results of executing tk ter tsk are summarizedin Table 4.1.
Target Task State
RUN or READY state(except for invoking task)
RUN state(invoking task)
WAIT state
DORMANT state
NON-EXISTENT state

tk ter tsk ercd Parameter
E OK
E OBJ
E OK
E OBJ
E NOEXS

Processing
Forced termination
No operation
Forced termination
No operation
No operation

Table 4.1: Target Task State and Execution Result (tk ter tsk)

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

36

CHAPTER 4. T-KERNEL/OS FUNCTIONS[Additional Notes]
When a task is terminated by tk ter tsk, the resources acquired by the task up to that time (memory
blocks, semaphores, etc.) are not automatically freed. The user is responsible for releasing such resources
before the task terminates.
As a rule, the task priority and other information included in the TCB are reset when the task returns
to DORMANT state. If, for example, the task priority is changed by tk chg pri and later terminatedby tk ter tsk, the task priority reverts to the startup priority (itskpri) specified when the task wasstarted. It does not keep the task priority in effect at the time tk ter tsk was executed.
Forcible termination of another task is intended for use only by a debugger or a few other tasks closely
related to the OS. As a rule, this system call is not to be used by ordinary applications or middleware,
for the following reason.
Forced termination occurs regardless of the running state of the target task.
If, for example, a task were forcibly terminated while the task was calling a middleware function, thetask would terminate right while the middleware was executing. If such a situation were allowed, normal
operation of the middleware could not be guaranteed.
This is an example of how task termination cannot be allowed when the task status (what it is executing)is unknown. Ordinary applications therefore must not use the forcible termination function.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.1. TASK MANAGEMENT FUNCTIONS

37

tk chg pri
Change Task Priority[C Language Interface]
ER ercd = tk_chg_pri ( ID tskid, PRI tskpri ) ;[Parameters]
ID
PRI

tskid
tskpri

Task ID
Task priority[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS
E PAR
E ILUSE

Normal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Parameter error (tskpri is invalid or cannot be used)
Illegal use (upper priority limit exceeded)[Description]
Changes the base priority of the task specified in tskid to the value specified in tskpri. The current
priority of the task also changes as a result.
Task priority values are specified from 1 to 140, with the smaller numbers indicating higher priority.
When TSK SELF (= 0) is specified in tskid, the invoking task is the target task. Note, however, thatwhen tskid = TSK SELF is specified in a system call issued from a task-independent portion, error code
E ID is returned. When TPRI INI (= 0) is specified as tskpri, the target task base priority is changed
to the initial priority when the task was started (itskpri).
A priority changed by this system call remains valid until the task is terminated. When the task reverts
to DORMANT state, the task priority before its exit is discarded, with the task again assigned to theinitial priority when the task was started (itskpri). A priority changed while the task is already in
DORMANT state, however, becomes valid, so that the task has the new priority as its initial priority
the next time it is started.
If as a result of this system call execution the target task current priority matches the base priority (thiscondition is always met when the mutex function is not used), processing is as follows.
If the target task is in a run state, the task precedence changes according to its priority. The target
task has the lowest precedence among tasks of the same priority after the change.
If the target task is in some kind of priority-based queue, the order in that queue changes in accord with
the new task priority. Among tasks of the same priority after the change, the target task is queued at
the end.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

38

CHAPTER 4. T-KERNEL/OS FUNCTIONS

If the target task has locked a TA CEILING attribute mutex or is waiting for a lock, and the base priority
specified in tskpri is higher than any of the ceiling priorities, error code E ILUSE is returned.
[Additional Notes]
In some cases when this system call results in a change in the queued order of the target task in a taskpriority-based queue, it may be necessary to release the wait state of another task waiting in that queue(in a message buffer send queue, or in a queue waiting to acquire a variable-size memory pool).
In some cases when this system call results in a base priority change while the target task is waiting fora TA INHERIT attribute mutex lock, dynamic priority inheritance processing may be necessary.
When a mutex function is not used and the system call is issued specifying the invoking task as thetarget task, setting the new priority to the base priority of the invoking task, the order of execution of
the invoking task becomes the lowest among tasks of the same priority. This system call can therefore
be used to relinquish execution privilege.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.1. TASK MANAGEMENT FUNCTIONS

39

tk chg slt
Change Task Slice-time[C Language Interface]
ER ercd = tk_chg_slt ( ID tskid, RELTIM slicetime ) ;[Parameters]ID
RELTIMtskid
slice-time

Task ID
Time slice (ms)[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Parameter error (slicetime is invalid)[Description]
Changes the time slice of the task specified in tskid to the value specified in slicetime.
The time slice function is used for round robin scheduling of tasks. When a task runs continuously forthe length of time specified in slicetime or longer, its precedence is switched to the lowest among tasksof the same priority, automatically yielding the execution privilege to the next task.
Setting slicetime = 0 indicates unlimited time, and the task does not automatically yield execution
privilege.
When a task is created, by default it is set to slicetime = 0. The invoking task can be specified by
setting tskid = TSK SELF = 0.
Note, however, that when a system call is issued from a task-independent portion and tskid =TSK SELF = 0 is specified, error code E ID is returned.
The time slice as changed by this system call remains valid until the task is terminated. When thetask reverts to DORMANT state, the time slice before termination is discarded, and the value at thetime of task creation (slicetime = 0) is assigned. A time slice changed while the task is already in
DORMANT state, however, becomes valid, being applied the next time the task is started.
[Additional Notes]
The time while execution privilege is preempted by a higher-priority task does not count in the continuous run time; moreover, even if execution privilege is preempted by a higher-priority task, the run time
is not treated as discontinuous. In other words, the time while execution privilege is preempted by ahigher-priority task is ignored for the purposes of counting run time.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

40

CHAPTER 4. T-KERNEL/OS FUNCTIONS

If the specified task is the only one running at its priority, the time slice is effectively meaningless andthe task runs continuously.
If a task of slicetime = 0 is included in tasks of the same priority, as soon as that task obtains execution
right, round robin scheduling is stopped.
The method of counting run time is implementation-dependent, but does not need to be especiallyprecise. In fact, applications should not expect very high precision.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.1. TASK MANAGEMENT FUNCTIONS

41

tk get tsp
Get Task Space[C Language Interface]
ER ercd = tk_get_tsp ( ID tskid, T_TSKSPC *pk_tskspc ) ;[Parameters]
ID

tskid

Task ID[Return Parameters]
T TSKSPC
ER

tskspcercd

Task space information
Error code

typedef struct t_tskspc {VP
uatb;
Task space page table address
INT
lsid;
Task space ID (logical space ID)} T_TSKSPC;[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Parameter error (the return parameter packet address cannot be used)[Description]
Gets the current task space information for the task specified in tskid.
The invoking task can be specified by setting tskid = TSK SELF = 0. Note, however, that when asystem call is issued from a task-independent portion and tskid = TSK SELF = 0 is specified, error code
E ID is returned.
[Additional Notes]
The accuracy of T TSKSPC (uatb, lsid) is implementation-dependent, but the above definitions should
be followed to the extent possible.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

42

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk set tsp
Set Task Space[C Language Interface]
ER ercd = tk_set_tsp ( ID tskid, T_TSKSPC *pk_tskspc ) ;[Parameters]ID
T TSKSPC

tskid
tskspcTask ID
Task space

typedef struct t_tskspc {uatb;
Task space page table address
VP
INT
lsid;
Task space ID (logical space ID)} T_TSKSPC;[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Parameter error (pk tskspc is invalid or cannot be used)[Description]
Sets the task space of the task specified in tskid.
The invoking task can be specified by setting tskid = TSK SELF = 0. Note, however, that when asystem call is issued from a task-independent portion and tskid = TSK SELF = 0 is specified, error code
E ID is returned.
The OS is not aware of the effects of task space changes. If, for example, a task space is changed
while a task is using it for its execution, the task may hang or encounter other problems. The caller is
responsible for avoiding such problems.
[Additional Notes]
The accuracy of T TSKSPC (uatb, lsid) is implementation-dependent, but the above definitions should
be followed to the extent possible.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.1. TASK MANAGEMENT FUNCTIONS

43

tk get rid
Get Task Resource ID[C Language Interface]
ID resid = tk_get_rid ( ID tskid ) ;[Parameters]
ID

tskid

Task ID[Return Parameters]
ID

resid
or

Resource ID
Error Code[Error Codes]
E OK
E ID
E NOEXSE OBJNormal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Task does not belong to a resource group[Description]
Returns the resource group to which the task specified in tskid currently belongs.
The invoking task can be specified by setting tskid = TSK SELF = 0. Note, however, that when asystem call is issued from a task-independent portion and tskid = TSK SELF = 0 is specified, error code
E ID is returned.
[Additional Notes]
If a resource group is deleted, this system call may return the resource ID of the deleted resource group.
Whether or not an error code (E OBJ) is returned is implementation-dependent. (See tk cre res,tk del res.)c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

44

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk set rid
Set Task Resource ID[C Language Interface]
ID oldid = tk_set_rid ( ID tskid, ID resid ) ;[Parameters]
ID
ID

tskid
resid

Task ID
New resource ID[Return Parameters]
ID

oldid
or

Old resource ID
Error Code[Error Codes]
E OK
E ID
E NOEXS

Normal completion
Invalid ID number (tskid or resid is invalid or cannot be used)
Object does not exist (the task specified in tskidor resid does not exist)[Description]
Changes the current resource group of the task specified in tskid to the resource group specified inresid. The resource ID of the old resource group before the change is passed in a return parameter.
The invoking task can be specified by setting tskid = TSK SELF = 0. Note, however, that when asystem call is issued from a task-independent portion and tskid = TSK SELF = 0 is specified, error code
E ID is returned.
[Additional Notes]
In some cases error is not returned even if resid was previously deleted. Whether or not an error code
(E NOEXS) is returned is implementation-dependent. In principle it is the responsibility of the caller not
to specify a deleted resource group.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.1. TASK MANAGEMENT FUNCTIONS

45

tk get reg
Get Task Registers[C Language Interface]
ER ercd = tk_get_reg ( ID tskid, T_REGS *pk_regs, T_EIT *pk_eit, T_CREGS *pk_cregs ) ;[Parameters]
ID

tskid

Task ID[Return Parameters]
T REGST EIT
T CREGSER

pk regs
pk eitpk cregs
ercd

General registers
Registers saved when EIT occurs
Control registers
Error code

The contents of T REGS, T EIT, and T CREGS are defined for each CPU and implementation.
[Error Codes]
E OK
E ID
E NOEXS
E OBJ
E CTX

Normal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Invalid object state (called for the invoking task)
Context error (called from task-independent portion)[Description]
Gets the current register contents of the task specified in tskid.
If NULL is set in pk regs, pk eit, or pk cregs, the corresponding registers are not referenced.
The referenced register values are not necessarily the values at the time the task portion was executing.
If this system call is issued for the invoking task, error code E OBJ is returned.
[Additional Notes]
In principle, all registers in the task context can be referenced. This includes not only physical CPU
registers but also those treated by the OS as virtual registers.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

46

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk set reg
Set Task Registers[C Language Interface]
ER ercd = tk_set_reg ( ID tskid, T_REGS *pk_regs, T_EIT *pk_eit, T_CREGS *pk_cregs ) ;[Parameters]ID
T REGST EIT
T CREGStskid
pk regs
pk eitpk cregs

Task ID
General registers
Registers saved when EIT occurs
Control registers

The contents of T REGS, T EIT, and T CREGS are defined for each CPU and implementation.
[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS
E OBJ
E CTX
E PAR

Normal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Invalid object state (called for the invoking task)
Context error (called from task-independent portion)
Invalid register value (implementation-dependent)[Description]
Sets the current register contents of the task specified in tskid.
If NULL is set in pk regs, pk eit, or pk cregs, the corresponding registers are not referenced.
The set register values are not necessarily the values while the task portion is executing. The OS is notaware of the effects of register value changes. It is possible, however, that some registers or register bits
cannot be changed if the OS does not allow such changes (implementation-dependent).
If this system call is issued for the invoking task, error code E OBJ is returned.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.1. TASK MANAGEMENT FUNCTIONS

47

tk get cpr
Get Task Co-processor Registers[C Language Interface]
ER ercd = tk_get_cpr ( ID tskid, INT copno, T_COPREGS *pk_copregs ) ;[Parameters]
ID
INT

tskid
copno

Task ID
Co-processor number (0 to 3)[Return Parameters]
T COPREGSER

pk copregs
ercd

typedef union {T_COP0REG
T_COP1REG
T_COP2REG
T_COP3REG} T_COPREG;

Co-processor registers
Error code
cop0;
cop1;
cop2;
cop3;

Co-processor number 0 register
Co-processor number 1 register
Co-processor number 2 register
Co-processor number 3 register

The contents of T COPn REG are defined for each CPU and implementation.
[Error Codes]
E OK
E ID
E NOEXS
E OBJ
E CTX
E PAR

Normal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Invalid object state (called for the invoking task)
Context error (called from task-independent portion)
Parameter error (copno is invalid or the specified co-processor does not exist)[Description]
Gets the current contents of the register specified in copno of the task specified in tskid.
The referenced register values are not necessarily the values at the time the task portion was executing.
If this system call is issued for the invoking task, error code E OBJ is returned.
[Additional Notes]
In principle, all registers in the task context can be referenced. This includes not only physical CPU
registers but also those treated by the OS as virtual registers.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

48

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk set cpr
Set Task Co-processor Registers[C Language Interface]
ER ercd = tk_set_cpr ( ID tskid, INT copno, T_COPREGS *pk_copregs ) ;[Parameters]ID
INT
T COPREGS

tskid
copno
pk copregs

Task ID
Co-processor number (0 to 3)
Co-processor registers[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS
E OBJ
E CTX
E PAR

Normal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Invalid object state (called for the invoking task)
Context error (called from task-independent portion)
Parameter error (copno is invalid or the specified co-processor does not exist), or the set
register value is invalid (implementation-dependent)[Description]
Sets the contents of the register specified in copno of the task specified in tskid.
The set register values are not necessarily the values while the task portion is executing. The OS is notaware of the effects of register value changes. It is possible, however, that some registers or register bits
cannot be changed if the OS does not allow such changes (implementation-dependent).
If this system call is issued for the invoking task, error code E OBJ is returned.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.1. TASK MANAGEMENT FUNCTIONS

49

tk inf tsk
Get Task Information[C Language Interface]
ER ercd = tk_inf_tsk ( ID tskid, T_ITSK *pk_itsk, BOOL clr ) ;[Parameters]ID
T ITSK*BOOL

tskid
pk itskclr

Task ID
Address of packet for returning task information
Clear task information[Return Parameters]
ER

ercd

Error code

pk itsk detail:RELTIMRELTIM

stime
utime

Cumulative system-level run time (ms)Cumulative user-level run time (ms)(Other implementation-dependent parameters may be added beyond this point.)[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Parameter error (the return parameter packet address cannot be used)[Description]
Gets statistical information for the task specified in tskid.
If clr = TRUE 6= 0, the cumulative information is reset (cleared to 0) after getting the information.
The invoking task can be specified by setting tskid = TSK SELF = 0. Note, however, that when asystem call is issued from a task-independent portion and tskid = TSK SELF = 0 is specified, error code
E ID is returned.
[Additional Notes]
The system-level run time is that while running at TA RNG0, and the user-level run time is that whilerunning at protection levels other than TA RNG0. A task created to run at TA RNG0 is therefore counted
entirely as system-level run time.
The method of counting run time is implementation-dependent, but does not need to be especiallyprecise. In fact, applications should not expect very high precision.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

50

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk ref tsk
Reference Task Status[C Language Interface]
ER ercd = tk_ref_tsk ( ID tskid, T_RTSK *pk_rtsk ) ;[Parameters]ID
T RTSK*tskid
pk rtsk

Task ID
Address of packet for returning task status[Return Parameters]
ER

ercd

Error code

pk rtsk detail:
VP
PRI
PRI
UINT
UINT
ID
INT
INT
RELTIM
UINT
UINT
UINT

exinf
tskpritskbpritskstattskwaitwid
wupcntsuscntslicetime
waitmask
texmask
tskevent

Extended information
Current task priority
Base priority
Task state
Wait factor
Waiting object ID
Queued wakeup requests
Nested suspend requests
Maximum continuous run time allowed (ms)Disabled wait factors
Allowed task exceptions
Task events(Other implementation-dependent parameters may be added beyond this point.)[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Parameter error (the return parameter packet address cannot be used)[Description]
Gets the state of the task specified in tskid.
tskstat takes the following values.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.1. TASK MANAGEMENT FUNCTIONS
tskstat:TTS RUNTTS RDY
TTS WAITTS SUSTTS WASTTS DMT
TTS NODISWAI

0x00010x00020x00040x00080x000c0x00100x0080

51
RUN
READY
WAIT
SUSPEND
WAIT-SUSPENDDORMANT
Wait state disabled

Task states such as TTS RUN and TTS WAI are expressed by corresponding bits, which is useful when
making a complex state decision (e.g., deciding that the state is one of either RUN or READY state).
Note that of the above states, TTS WAS is a combination of TTS SUS and TTS WAI, but TTS SUS is nevercombined with other states (TTS RUN, TTS RDY, TTS DMT). In the case of TTS WAI (including TTS WAS),
if wait states are disabled by tk dis wai, TTS NODISWAI is set. TTS NODISWAI is never combined withstates other than TTS WAI.
When tk ref tsk is executed for an interrupted task from an interrupt handler, RUN (TTS RUN) is
returned as tskstat.
When tskstat is TTS WAI (including TTS WAS), the values of tskwait and wid are as shown in Table 4.2.
tskwaitTTW SLPTTW DLY
TTW SEMTTW FLGTTW MBX
TTW MTXTTW SMBF
TTW RMBF
TTW CALTTW ACPTTW RDV(TTW CAL|TTW RDV)TTW MPFTTW MPL
TTW EV1TTW EV2TTW EV3TTW EV4TTW EV5TTW EV6TTW EV7TTW EV8Value
0x00000001
0x00000002
0x00000004
0x00000008
0x00000040
0x00000080
0x00000100
0x00000200
0x00000400
0x00000800
0x00001000
0x00001400
0x00002000
0x00004000
0x00010000
0x00020000
0x00040000
0x00080000
0x00100000
0x00200000
0x00400000
0x00800000

Description
Wait caused by tk slp tsk
Wait caused by tk dly tsk
Wait caused by tk wai sem
Wait caused by tk wai flg
Wait caused by tk rcv mbx
Wait caused by tk loc mtx
Wait caused by tk snd mbf
Wait caused by tk rcv mbf
Wait on rendezvous call
Wait for rendezvous acceptance
Wait for rendezvous completion
Wait on rendezvous call or wait for rendezvous completion
Wait for tk get mpf
Wait for tk get mpl
Wait for task event #1
Wait for task event #2
Wait for task event #3
Wait for task event #4
Wait for task event #5
Wait for task event #6
Wait for task event #7
Wait for task event #8

wid
0
0
semid
flgid
mbxid
mtxid
mbfid
mbfid
porid
porid
0
0
mpfi
mplid
0
0
0
0
0
0
0
0

Table 4.2: Values of tskwait and wid
When tskstat is not TTS WAI (including TTS WAS), both tskwait and wid are 0.
waitmask is the same bit array as tskwait.
For a task in DORMANT state, wupcnt = 0, suscnt = 0, and tskevent = 0.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

52

CHAPTER 4. T-KERNEL/OS FUNCTIONS

The invoking task can be specified by setting tskid = TSK SELF = 0. Note, however, that when asystem call is issued from a task-independent portion and tskid = TSK SELF = 0 is specified, error code
E ID is returned.
When the task specified with tk ref tsk does not exist, error code E NOEXS is returned.
[Additional Notes]
Even when tskid = TSK SELF is specified with this system call, the ID of the invoking task is not known.
Use tk get tid to find out the ID of the invoking task.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.2. TASK-DEPENDENT SYNCHRONIZATION FUNCTIONS

4.2

53

Task-Dependent Synchronization Functions

Task-dependent synchronization functions achieve synchronization among tasks by direct manipulationof task states. They include functions for task sleep and wakeup, for canceling wakeup requests, forforcibly releasing task WAIT state, for changing a task state to SUSPEND state, for delaying executionof the invoking task, and for disabling task WAIT state.
Wakeup requests for a task are queued. That is, when it is attempted to wake up a task that is not
sleeping, the wakeup request is remembered, and the next time the task is to go to a sleep state (waiting
for wakeup), it does not enter that state. The queuing of task wakeup requests is realized by having thetask keep a task wakeup request queuing count. When the task is started, this count is cleared to 0.
Suspend requests for a task are nested. That is, if it is attempted to suspend a task already in SUSPEND
state (including WAIT-SUSPEND state), the request is remembered, and later when it is attempted toresume the task in SUSPEND state (including WAIT-SUSPEND state), it is not resumed. The nestingof suspend requests is realized by having the task keep a suspend request nesting count. When the task
is started, this count is cleared to 0.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

54

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk slp tsk
Sleep Task
[C Language Interface]
ER ercd = tk_slp_tsk ( TMO tmout ) ;[Parameters]
TMO

tmout

Timeout[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E PAR
E RLWAIE DISWAIE TMOUTE CTXNormal completion
Parameter error (tmout ≤ (−2))
Wait state released (tk rel wai received in wait state)
Wait released by wait disabled state
Polling failed or timeout
Context error (issued from task-independent portion or in dispatch disabled state)[Description]
Changes the state of the invoking task from RUN state to sleep state (WAIT for tk wup tsk).
If tk wup tsk is issued for the invoking task before the time specified in tmout has elapsed, this systemcall completes normally. If timeout occurs before tk wup tsk is issued, error code E TMOUT is returned.
Specifying tmout = TMO FEVR = (−1) means endless wait. In this case, the task stays in waiting state
until tk wup tsk is issued.
[Additional Notes]
Since tk slp tsk is a system call that puts the invoking task into a wait state, tk slp tsk can never
be nested. It is possible, however, for another task to issue tk sus tsk for a task that was put in a waitstate by tk slp tsk. In this case the task goes to WAIT-SUSPEND state.
For simply delaying a task, tk dly tsk should be used rather than tk slp tsk.
The task sleep function is intended for use by applications and as a rule should not be used by middleware.
The reason is that attempting to achieve synchronization by putting a task to sleep in two or moreplaces would cause confusion, leading to mis-operation. For example, if sleep were used by both anapplication and middleware for synchronization, a wakeup request might arise in the application while
middleware has the task sleeping. In such a situation, normal operation would not be possible in either
the application or middleware. Proper task synchronization is not possible because it is not clear where
the wait for wakeup originated. Task sleep is often used as a simple means of task synchronization.
Applications should be able to use it freely, which means as a rule it should not be used by middleware.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.2. TASK-DEPENDENT SYNCHRONIZATION FUNCTIONS

55

tk wup tsk
Wakeup Task
[C Language Interface]
ER ercd = tk_wup_tsk ( ID tskid ) ;[Parameters]
ID

tskid

Task ID[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXSE OBJ
E QOVR

Normal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Invalid object state (called for the invoking task or for a task in DORMANT state)
Queuing or nesting overflow (too many queued wakeup requests in wupcnt)[Description]
If the task specified in tskid was put in WAIT state by tk slp tsk, this system call releases the WAIT
state.
This system call cannot be called for the invoking task. If the invoking task is specified, error code
E OBJ is returned.
If the target task has not called tk slp tsk and is not in WAIT state, the wakeup request by tk wup tsk
is queued. That is, the calling of tk wup tsk for the target task is recorded, then when tk slp tsk iscalled after that, the task does not go to WAIT state. This is what is meant by queuing of wakeup
requests.
The queuing of wakeup requests works as follows. Each task keeps a wakeup request queuing count(wupcnt) in its TCB.
Its initial value (when tk sta tsk is executed) is 0. When tk wup tsk is issued for a task not sleeping(not in WAIT state), the count is incremented by 1; but each time tk slp tsk is executed, the countis decremented by 1. When tk slp tsk is executed for a task whose wakeup queuing count is 0, thequeuing count does not go into negative territory but rather the task goes to WAIT state.
It is always possible to queue tk wup tsk one time (wupcnt = 1), but the maximum queuing count(wupcnt) is implementation-dependent and may be set to any appropriate value of 1 or above. In otherwords, issuing tk wup tsk once for a task not in WAIT state does not return error, but whether error isreturned for the second or subsequent time tk wup tsk is called is an implementation-dependent matter.
When calling tk wup tsk causes wupcnt to exceed the maximum allowed value, error code E QOVR isreturned.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

56

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk can wup
Cancel Wakeup Task
[C Language Interface]
INT wupcnt = tk_can_wup ( ID tskid ) ;[Parameters]
ID

tskid

Task ID[Return Parameters]
INT

wupcntor

Number of queued wakeup requests
Error Code[Error Codes]
E OK
E ID
E NOEXSE OBJNormal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Invalid object state (called for a task in DORMANT state)[Description]
Passes in the return parameter the wakeup request queuing count (wupcnt) for the task specified intskid, at the same time canceling all wakeup requests. That is, this system call clears the wakeup
request queuing count (wupcnt) to 0 for the specified task.
The invoking task can be specified by setting tskid = TSK SELF = 0. Note, however, that when asystem call is issued from a task-independent portion and tskid = TSK SELF = 0 is specified, error code
E ID is returned.
[Additional Notes]
When processing is performed that involves cyclic wakeup of a task, this system call is used to determine
whether the processing was completed within the allotted time. Before processing of a prior wakeup
request is completed and tk slp tsk is called, the task monitoring this calls tk can wup. If wupcnt in
the return parameter is 1 or above, this means the previous wakeup request was not processed within
the allotted time. A processing delay or other measure can then be taken accordingly.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.2. TASK-DEPENDENT SYNCHRONIZATION FUNCTIONS

57

tk rel wai
Release Wait
[C Language Interface]
ER ercd = tk_rel_wai ( ID tskid ) ;[Parameters]
ID

tskid

Task ID[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXSE OBJNormal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Invalid object state (called for a task not in WAIT state (including when called for the
invoking task, or for a task in DORMANT state))[Description]
If the task specified in tskid is in some kind of wait state (not including SUSPEND state), forcibly
releases that state.
This system call returns error code E RLWAI to the task whose WAIT state was released.
Wait release requests by tk rel wai are not queued. That is, if the task specified in tskid is already in
WAIT state, the WAIT state is cleared; but if it is not in WAIT state when this system call is issued,
error code E OBJ is returned to the caller. Likewise, error code E OBJ is returned when this system call
is issued specifying the invoking task.
The tk rel wai system call does not release a SUSPEND state. If it is issued for a task in WAITSUSPEND state, the task goes to SUSPEND state. If it is necessary to release SUSPEND state, theseparate system call tk frsm tsk is used. The states of the target task when tk rel wai is called andthe results of its execution in each state are shown in Table 4.3.
[Additional Notes]
A function similar to timeout can be realized by using an alarm handler or the like to issue this systemcall after a given task has been in WAIT state for a set time.
The main differences between tk rel wai and tk wup tsk are the following.
• Whereas tk wup tsk releases only WAIT state effected by tk slp tsk, tk rel wai releases also
WAIT state caused by other factors (tk wai flg, tk wai sem, tk rcv msg, tk get blk, etc.).

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

58

CHAPTER 4. T-KERNEL/OS FUNCTIONS
Target Task StateRun state (RUN, READY)(not for invoking task)
RUN state(for invoking task)
WAIT state
DORMANT state
NON-EXISTENT state

tk rel tsk ercd Parameter
E OBJ

Processing
No operation

E OBJ

No operation

E OK
E OBJ
E NOEXS

Wait released∗
No operation
No operation∗ Error code E RLWAI is returned to the target task. The target task is guaranteed to bereleased from its wait state without any resource allocation (without the wait release conditions
being met).

Table 4.3: Task States and Results of tk rel wai Execution• Seen from the task in WAIT state, release of the WAIT state by tk wup tsk returns a Normal
completion (E OK), whereas release by tk rel wai returns an error code (E RLWAI).
• Wakeup requests by tk wup tsk are queued if tk slp tsk has not yet been executed. If tk rel wai
is issued for a task not in WAIT state, error code E OBJ is returned.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.2. TASK-DEPENDENT SYNCHRONIZATION FUNCTIONS

59

tk sus tsk
Suspend Task
[C Language Interface]
ER ercd = tk_sus_tsk ( ID tskid ) ;[Parameters]
ID

tskid

Task ID[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS
E OBJ
E CTX
E QOVR

Normal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Invalid object state (called for the invoking task or for a task in DORMANT state)
A task in RUN state was specified in dispatch disabled state
Queuing or nesting overflow (too many nested requests in suscnt)[Description]
Puts the task specified in tskid in SUSPEND state and interrupts execution by the task.
SUSPEND state is released by issuing system call tk rsm tsk or tk frsm tsk.
If tk sus tsk is called for a task already in WAIT state, the state goes to a combination of WAIT stateand SUSPEND state (WAIT-SUSPEND state). Thereafter when the task wait release conditions aremet, the task goes to SUSPEND state. If tk rsm tsk is issued for the task in WAIT-SUSPEND state,
the task state reverts to WAIT state.
Since SUSPEND state means task interruption by a system call issued by another task, this system callcannot be issued for the invoking task. If the invoking task is specified, error code E OBJ is returned.
When this system call is issued from a task-independent portion, if a task in RUN state is specified
while dispatching is disabled, error code E CTX is returned.
If tk sus tsk is issued more than once for the same task, the task is put in SUSPEND state multiple
times. This is called nesting of suspend requests. In this case, the task reverts to its original state only
when tk rsm tsk has been issued for the same number of times as tk sus tsk (suscnt). Accordingly,
nesting of the pair tk sus tsk — tk rsm tsk is possible.
The nesting of suspend requests (issuing tk sus tsk two or more times for the same task) and limits
on nesting count are implementation-dependent.
If tk sus tsk is issued multiple times in a system that does not allow suspend request nesting, or if thenesting count exceeds the allowed limit, error code E QOVR is returned.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

60

CHAPTER 4. T-KERNEL/OS FUNCTIONS[Additional Notes]
When a task is in WAIT state for resource acquisition (semaphore wait, etc.) and is also in SUSPEND
state, the resource allocation (semaphore allocation, etc.) takes place under the same conditions as
when the task is not in SUSPEND state. Resource allocation is not delayed by the SUSPEND state,
and there is no change whatsoever in the priority of resource allocation or release from WAIT state. In
this way SUSPEND state is in an orthogonal relation with other processing and task states.
In order to delay resource allocation to a task in SUSPEND state (temporarily lower its priority), theuser can employ tk sus tsk and tk rsm tsk in combination with tk chg pri.
Task suspension is intended only for very limited uses closely related to the OS, such as page fault
processing in a virtual memory system or breakpoint processing in a debugger. As a rule it should not
be used in ordinary applications or in middleware.
The reason is that task suspension takes place regardless of the target task running state. If, for example,
a task is put in SUSPEND state while it is calling a middleware function, the task will be stopped in
the course of middleware internal processing. In some cases middleware performs resource management
or other mutual exclusion control. If a task stops inside middleware while it has resources allocated,other tasks may not be able to use that middleware. This situation can cause a chain reactions, withother tasks stopping and leading to system-wide deadlock.
For this reason a task must not be stopped without knowing its status (what it is doing at the time),and ordinary tasks should not use the task suspension function.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.2. TASK-DEPENDENT SYNCHRONIZATION FUNCTIONS

61

tk rsm tsk
tk frsm tsk
Resume Task
Force Resume Task
[C Language Interface]
ER ercd = tk_rsm_tsk ( ID tskid ) ;ER ercd = tk_frsm_tsk ( ID tskid ) ;[Parameters]
ID

tskid

Task ID[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXSE OBJNormal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Invalid object state (the specified task is not in SUSPEND state (including when thissystem call specifies the invoking task or a task in DORMANT state))[Description]
Releases the SUSPEND state of the task specified in tskid.
If the target task was earlier put in SUSPEND state by the tk sus tsk system call, this system callreleases that SUSPEND state and resumes the task execution.
When the target task is in a combined WAIT state and SUSPEND state (WAIT-SUSPEND state),
executing tk rsm tsk releases only the SUSPEND state, putting the task in WAIT state.
This system call cannot be issued for the invoking task. If the invoking task is specified, error code
E OBJ is returned.
Executing tk rsm tsk one time clears only one nested suspend request (suscnt). If tk sus tsk was
issued more than once for the target task (suscnt ≥ 2), the target task remains in SUSPEND stateeven after tk rsm tsk is executed. When tk frsm tsk is issued, on the other hand, all suspend requests
are released (suscnt is cleared to 0) even if tk sus tsk was issued more than once (suscnt ≥ 2). The
SUSPEND state is always cleared, and unless the task was in WAIT-SUSPEND state its execution
resumes.
[Additional Notes]
After a task in RUN state or READY state is put in SUSPEND state by tk sus tsk and then resumedby tk rsm tsk or tk frsm tsk, the task has the lowest precedence among tasks of the same priority.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

62

CHAPTER 4. T-KERNEL/OS FUNCTIONS

When, for example, the following system calls are executed for tasks A and B of the same priority, theresult is as indicated below.
tk_sta_tsk (tskid=task_A, stacd_A);
tk_sta_tsk (tskid=task_B, stacd_B);/* By the rule of FCFS, precedence becomes task_A --> task_B. */tk_sus_tsk (tskid=task_A);
tk_rsm_tsk (tskid=task_A);/* In this case precedence becomes task_B --> task_A.

c 2002–2005 by T-Engine Forum
Copyright °*/TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.2. TASK-DEPENDENT SYNCHRONIZATION FUNCTIONS

63

tk dly tsk
Delay Task
[C Language Interface]
ER ercd = tk_dly_tsk ( RELTIM dlytim ) ;[Parameters]
RELTIM

dlytimDelay time

[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E NOMEME PAR
E CTX
E RLWAIE DISWAI

Normal completion
Insufficient memory
Parameter error (dlytim is invalid)Context error (issued from task-independent portion or in dispatch disabled state)
Wait state released (tk rel wai received in wait state)
Wait released by wait disabled state[Description]
Temporarily stops execution of the invoking task and waits for time dlytim to elapse. The state while
the task waits for the delay time to elapse is a WAIT state and is subject to release by tk rel wai.
If the task issuing this system call goes to SUSPEND state or WAIT-SUSPEND state while it is waiting
for the delay time to elapse, the time continues to be counted in the SUSPEND state.
The time base for dlytim (time unit) is the same as that for system time (= 1 ms).
[Additional Notes]
This system call differs from tk slp tsk in that normal completion, not an error code, is returned when
the delay time elapses and tk dly tsk terminates. Moreover, the wait is not released even if tk wup tsk
is executed during the delay time. The only way to terminate tk dly tsk before the delay time elapses
is by calling tk ter tsk or tk rel wai.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

64

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk sig tev
Signal Task Event[C Language Interface]
ER ercd = tk_sig_tev ( ID tskid, INT tskevt ) ;[Parameters]
ID
INT

tskid
tskevtTask ID
Task event number (1 to 8)[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS
E OBJ
E PAR

Normal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Invalid object state (called for a task in DORMANT state)Parameter error (tskevt is invalid)[Description]
Sends the task event specified in tskevt to the task specified in tskid. There are eight task event types
stored for each task, specified by numbers 1 to 8.
The task event send count is not saved, only whether the event occurs or not.
The invoking task can be specified by setting tskid = TSK SELF = 0. Note, however, that when asystem call is issued from a task-independent portion and tskid = TSK SELF = 0 is specified, error code
E ID is returned.
[Additional Notes]
The task event function is used for synchronization much like tk slp tsk and tk wup tsk, but differsfrom the use of those system calls in the following ways.
• The wakeup request (task event) count is not kept.
• Wakeup requests can be classified by the eight event types.
Using the same event type for synchronization in two or more places in the same task would cause
confusion. Event type allocation should be clearly defined. The task event function is intended foruse in middleware, and as a rule should not be used in ordinary applications. Use of tk slp tsk andtk wup tsk is recommended for applications.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.2. TASK-DEPENDENT SYNCHRONIZATION FUNCTIONS

65

tk wai tev
Wait Task Event[C Language Interface]
INT tevptn = tk_wai_tev ( INT waiptn, TMO tmout ) ;[Parameters]
INT
TMO

waiptntmout

Task event pattern
Timeout[Return Parameters]
INT

tevptnor

Task event status when wait released
Error Code[Error Codes]
E OK
E PAR
E RLWAIE DISWAIE TMOUTE CTXNormal completion
Parameter error (waiptn or tmout is invalid)
Wait state released (tk rel wai received in wait state)
Wait released by wait disabled state
Polling failed or timeout
Context error (issued from task-independent portion or in dispatch disabled state)[Description]
Waits for the occurrence of one of the task events specified in waiptn.
When the wait is released by a task event, the task events specified in waiptn are cleared (raised task
event &= ~waiptn).
The task event status occurring when the wait was released (the state before clearing) is passed in the
return code (tevptn).
The parameters waiptn and tevptn consist of logical OR values of the bits for each task event in theform 1 << (task event number − 1).
A maximum wait time (timeout) can be set in tmout. If the tmout time elapses before the wait releasecondition is met (tk sig tev is not executed), the system call terminates, returning timeout error code
E TMOUT. Only positive values can be set in tmout. The time base for tmout (time unit) is the same asthat for system time (= 1 ms). When TMO POL = 0 is set in tmout, this means 0 was specified as thetimeout value, and E TMOUT is returned without entering WAIT state even if no task event occurs.
When TMO FEVR = (−1) is set in tmout, this means infinity was specified as the timeout value, and thetask continues to wait for a task event without timing out.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

66

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk dis wai
Disable Task Wait
[C Language Interface]
INT tskwait = tk_dis_wai ( ID tskid, UINT waitmask ) ;[Parameters]
ID
UINT

tskid
waitmask

Task ID
Task wait disabled setting[Return Parameters]INT

tskwaitor

Task state after task wait disabled
Error Code[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Parameter error (waitmask is invalid)[Description]
Disables waits for the wait factors set in waitmask by the task specified in tskid.
If the task is already waiting for a factor specified in waitmask, that wait is released.
waitmask is specified as the logical OR of any combination of the following wait factors.
#define TTW_SLP#define TTW_DLY#define TTW_SEM#define TTW_FLG#define TTW_MBX#define TTW_MTX#define TTW_SMBF#define TTW_RMBF#define TTW_CAL#define TTW_ACP#define TTW_RDV#define TTW_MPF#define TTW_MPL#define TTW_EV1#define TTW_EV2#define TTW_EV3

0x00000001
0x00000002
0x00000004
0x00000008
0x00000040
0x00000080
0x00000100
0x00000200
0x00000400
0x00000800
0x00001000
0x00002000
0x00004000
0x00010000
0x00020000
0x00040000

c 2002–2005 by T-Engine Forum
Copyright °/* Wait caused by sleep*//* Wait for task delay*//* Wait for semaphore*//* Wait for event flag*//* Wait for mailbox*//* Wait for mutex*//* Wait for message buffer sending*//* Wait for message buffer receipt*//* Wait on rendezvous call*//* Wait for rendezvous acceptance*//* Wait for rendezvous completion*//* Wait for fixed-size memory pool*//* Wait for variable-size memory pool *//* Wait for task event #1*//* Wait for task event #2*//* Wait for task event #3*/
TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.2. TASK-DEPENDENT SYNCHRONIZATION FUNCTIONS#define TTW_EV4#define TTW_EV5#define TTW_EV6#define TTW_EV7#define TTW_EV8#define TTX_SVC

0x00080000
0x00100000
0x00200000
0x00400000
0x00800000
0x80000000/* Wait for task event #4/* Wait for task event #5/* Wait for task event #6/* Wait for task event #7/* Wait for task event #8/* Extended SVC disabled

67
*/
*/
*/
*/
*/
*/

TTX SVC is a special parameter disabling not task wait but the calling of an extended SVC. If TTX SVC
is specified when a task attempts to call an extended SVC, E DISWAI is returned without calling theextended SVC. This parameter does not have the effect of terminating an already called extended SVC.
A tskwait value of 0 means the task has not entered WAIT state (or the wait was released). If tskwait
is not 0, this means the task is in WAIT state for a cause other than those disabled in waitmask.
When a task wait is cleared by tk dis wai or the task is prevented from entering WAIT state while thissystem call is in effect, E DISWAI is returned. When a system call for which there is the possibility ofentering a WAIT state is invoked during wait disabled state, E DISWAI is returned even if the processing
could be performed without waiting.
For example, even if message buffer space is available when tk snd mbf is called and message buffer
sending is possible without entering a WAIT state, E DISWAI is returned and the message is not sent.
A wait disable set while an extended SVC is executing will be cleared automatically upon return fromthe extended SVC to its caller. It is automatically cleared also when an extended SVC is called, revertingto the original setting upon return from the extended SVC. A wait disable setting is cleared also when
the task reverts to DORMANT state. The setting made while a task is in DORMANT state, however,is valid and the wait disable is applied the next time the task is started.
In the case of semaphores and most other objects, TA NODISWAI can be specified when the object iscreated. An object created with TA NODISWAI specified cannot have waits disabled, and rejects any wait
disable attempt by tk dis wai.
The invoking task can be specified by setting tskid = TSK SELF = 0. Note, however, that when asystem call is issued from a task-independent portion and tskid = TSK SELF = 0 is specified, error code
E ID is returned.
[Additional Notes]
The wait disable function is provided for preventing execution of an extended SVC handler and is foruse mainly (though not exclusively) in break functions.
Wait disable in the case of a rendezvous is more complex than other cases. Essentially, wait disabledstate is detected based on a change in the rendezvous wait state, then the wait is released. Some specificexamples are given here.
When waiting by TTW CAL is not disabled but TTW RDV waits are disabled, a task enters into wait on
rendezvous call state; but when the rendezvous is accepted and a wait for rendezvous completion would
normally begin, the wait is released and E DISWAI is returned. At this time a message is sent to thereceiving task, the receiving task declares acceptance of the message and the task goes to rendezvous
established state. Only when the accepting task replies (tk rpl rdv) does it become clear that there
is no other task in the rendezvous, and error code E OBJ is returned. Wait disable applies also when arendezvous is forwarded. In that case the attribute of the destination rendezvous port applies. That is,if the TA NODISWAI attribute is specified for the destination port, wait disable is rejected. If TTW CAL
wait is disabled after going to wait for rendezvous completion state, and a rendezvous is forwarded inthat state, the state goes to WAIT on rendezvous call as a result of the forwarding, so wait is disabled
by TTW CAL. In that case E DISWAI is returned to both the rendezvous calling task (tk cal por) andforwarding task (tk fwd por).

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

68

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk ena wai
Enable Task Wait
[C Language Interface]
ER ercd = tk_ena_wai ( ID tskid ) ;[Parameters]
ID

tskid

Task ID[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS

Normal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)[Description]
Releases all wait disable conditions set by tk dis wai for the task specified in tskid.
The invoking task can be specified by setting tskid = TSK SELF = 0. Note, however, that when asystem call is issued from a task-independent portion and tskid = TSK SELF = 0 is specified, error code
E ID is returned.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.3. TASK EXCEPTION HANDLING FUNCTIONS

4.3

69

Task Exception Handling Functions

Task exception handling functions handle exception events occurring in a task, in the context of thattask, interrupting normal task processing.
A task exception handler is executed as a part of the task where the task exception occurred, in thecontext of that task and at the protection level specified when the task was created. The task states ina task exception handler, except for those states concerning task exceptions, are the same as the states
when running an ordinary task portion; and the same system calls are available.
A task exception handler can be started only when the target task is running a task portion. If the task
is running any other portion when a task exception is raised, the task exception handler is started only
after the task returns to the task portion. If a quasi-task portion (extended SVC) is executing whena task exception is raised, a break function corresponding to that extended SVC is called. The breakfunction interrupts the extended SVC processing, and the task returns to the task portion.
Requested task exceptions are cleared when the task exception handler is called (when the task exception
handler starts running).
Task exceptions are specified by task exception codes from 0 to 31, of which 0 is the highest priority
and 31 the lowest. Task exception code 0 is handled differently from the others, as explained below.
Task exception codes 1 to 31 :• These task exception handlers are not nested. A task exception (other than task exception
code 0) raised while a task exception handler is running will be made pending.
• On return from a task exception handler, the task resumes from the point where processing
was interrupted by the exception.
• It is also possible to use longjmp() or the like to jump to any point in the task without
returning from the task exception handler.
Task exception code 0:• This exception can be nested even while a task exception handler is executing for an exceptionof task exception code 1 to 31. Execution of task exception code 0 handlers is not nested.
• A task exception handler runs after setting the user stack pointer to the initial setting when
the task was started. In a system without a separate user stack and system stack, however,the stack pointer is not reset to its initial setting.
• A task exception code 0 handler does not return to task processing. The task must be
terminated.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

70

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk def tex
Define Task Exception Handler[C Language Interface]
ER ercd = tk_def_tex ( ID tskid, T_DTEX *pk_dtex ) ;[Parameters]ID
T DTEX*tskid
pk dtex

Task ID
Task exception handler definition information

pk dtex detail:
ATR
FP

texatrtexhdrTask exception handler attributes
Task exception handler address(Other implementation-dependent parameters may be added beyond this point.)[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E NOMEM
E ID
E NOEXSE OBJ
E RSATR
E PAR

Normal completion
Insufficient memory (memory for control block cannot be allocated)
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Invalid object state (the task specified in tskid runs at protection level 0 (TA RNG0))
Reserved attribute (texatr is invalid or cannot be used)
Parameter error (pk dtex is invalid or cannot be used)[Description]
Defines a task exception handler for the task specified in tskid. Only one task exception handler can be
defined per task; if one is already defined, the last-defined handler is valid. Setting pk dtex = NULL
cancels a definition.
Defining or canceling a task exception handler clears pending task exception requests and disables alltask exceptions.
The parameter texatr indicates system attributes in is low bits and implementation-dependent attributes in its high bits. The texatr system attributes are not assigned in the present version, andsystem attributes are not used.
A task exception handler takes the following form.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.3. TASK EXCEPTION HANDLING FUNCTIONS

71

void texhdr( INT texcd ){/*Task exception handling*//* Task exception handler termination */if ( texcd == 0 ) {tk_ext_tsk() or tk_exd_tsk();} else {tk_end_tex();return or longjmp();}}A task exception handler behaves only like a TA ASM attribute object and cannot be called via a high-level
language support routine. The entry part of the task exception handler must be written in assembly
language. The OS vendor must provide the assembly language source of the entry routine for callingthe above C language task exception handler. That is, source code equivalent to a high-level language
support routine must be provided.
A task set to protection level TA RNG0 when it is created cannot use task exceptions.
[Additional Notes]
At the time a task is created, no task exception handler is defined and task exceptions are disabled.
When a task reverts to DORMANT state, the task exception handler definition is canceled and task
exceptions are disabled. Pending task exceptions are cleared. It is possible, however, to define a task
exception handler for a task in DORMANT state.
Task exceptions are software interrupts raised by tk ras tex, with no direct relation to CPU exceptions.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

72

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk ena tex
tk dis tex
Enable Task Exception
Disable Task Exception[C Language Interface]
ER ercd = tk_ena_tex ( ID tskid, UINT texptn ) ;ER ercd = tk_dis_tex ( ID tskid, UINT texptn ) ;[Parameters]
ID
UINT

tskid
texmask

Task ID
Task exception pattern[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist or no task exception
handler is defined)
Parameter error (texptn is invalid or cannot be used)[Description]
Enables or disables task exceptions for the task specified in tskid.
The parameter texptn is a logical OR bit array representing task exception codes in the form 1 <<task exception code.
tk ena tex enables the task exceptions specified in texptn. tk dis tex disables the task exceptions
specified in texptn. If the current exception enabled status is texmask, it changes as follows.
Enable:Disable:texmask |= texptn
texmask &= ~texptn

A disabled task exception is ignored, and is not made pending.
If exceptions are disabled for a task while there are pending task exceptions, the pending task exception
requests are discarded (their pending status is cleared).
Task exceptions cannot be enabled for a task with no task exception handler defined.
These system calls are applicable to tasks in DORMANT state.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.3. TASK EXCEPTION HANDLING FUNCTIONS

73

tk ras tex
Raise Task Exception[C Language Interface]
ER ercd = tk_ras_tex ( ID tskid, INT texcd ) ;[Parameters]
ID
INT

tskid
texcd

Task ID
Task exception code (0 to 31)[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS
E OBJ
E PAR
E CTX

Normal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist or no task exception
handler is defined)
Invalid object state (called for a task in DORMANT state)Parameter error (texcd is invalid or cannot be used)
Context error (issued from task-independent portion or in dispatch disabled state)[Description]
Raises the task exception specified in texcd for the task specified in tskid.
If a task exception handler is already running in the task specified in tskid, the newly raised task
exception is made pending. If an exception is pending, a break function is not executed even if thetarget task is executing an extended SVC. In the case of texcd = 0, however, exceptions are not madepending even if the target task is executing an exception handler. If the target task is running a task
exception handler for an exception of task exception codes 1 to 31, the task exception is accepted; and if
an extended SVC is executing, a break function is called. If the target task is running a task exception
handler for an exception of task exception code 0, task exceptions are ignored.
The invoking task can be specified by setting tskid = TSK SELF = 0.
If this system call is issued from a task-independent portion, error code E CTX is returned.
[Additional Notes]
If the target task is executing an extended SVC, the break handler or the extended SVC runs in thecontext that called tk ras tex. In such a case tk ras tex does not return control until the breakfunction processing ends. Task exceptions raised in the task that called tk ras tex while the breakfunction is running are held until the break function ends.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

74

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk end tex
End Task Exception Handler[C Language Interface]
INT texcd = tk_end_tex ( BOOL enatex ) ;[Parameters]
BOOL

enatex

Task exception handler calling enabled flag

[Return Parameters]
INT

texcd
or

Raised exception code
Error Code[Error Codes]
E OK
E CTX

Normal completion
Context error (called for other than a task exception handler or task exception code 0(detection is implementation-dependent))[Description]
Ends a task exception handler and enables the new task exception handler. If there are pending task
exceptions, the highest-priority task exception code among them is passed in the return code. If there
are no pending task exceptions, 0 is returned.
If enatex = FALSE and there are pending task exception, calling the new task exception handler is
not allowed. In this case, the exception handler specified in return code texcd is in running state upon
return from tk end tex. If there are no pending task exceptions, calling the new task exception handler
is allowed.
If enatex = TRUE, calling the new task exception handler is allowed regardless of whether there are
pending task exceptions. Even if there are pending task exceptions, the task exception handler is interminated status.
There is no way of ending a task exception handler other than by calling tk end tex. A task exception
handler continues executing from the time it is started until tk end tex is called. Even if return ismade from a task exception handler without calling tk end tex, the task exception handler will still berunning at the point of return. Similarly, even if longjmp is used to get out of a task exception handler
without calling tk end tex, the task exception handler will still be running at the jump destination.
Calling tk end tex while task exceptions are pending results in a new task exception being accepted.
At this time even when tk end tex is called from an extended SVC handler, a break function cannot becalled for that extended SVC handler. If extended SVC calls are nested, then when the extended SVC
nesting goes down one level, the break function corresponding to the extended SVC return destination
can be called. Calling of a task exception handler takes place upon return to the task portion. The
tk end tex system call cannot be issued in the case of task exception code 0, since the task exception
handler cannot be ended. The behavior when tk end tex is called for a handler of task exception code
0 is undefined (implementation-dependent).
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.3. TASK EXCEPTION HANDLING FUNCTIONS

75

This system call cannot be issued from other than a task exception handler. The behavior when it iscalled from other than a task exception handler is undefined (implementation-dependent).
[Additional Notes]
When tk end tex (TRUE) is set and there are pending task exceptions, another task exception handler
call is made immediately following tk end tex. Moreover, for that reason a task exception handler iscalled without restoring the stack, giving rise to possible stack overflow. Ordinarily tk end tex (FALSE)
can be used, and processing looped as illustrated below while there are task exceptions pending.
void texhdr( INT texcd ){if ( texcd == 0 ) tk_exd_tsk();do {/*Task exception handling*/} while ( (texcd = tk_end_tex(FALSE)) > 0 );}Strictly speaking, if a task exception were to occur during the interval after 0 is returned by tk ena tex
ending the loop and before exit from texhdr, the possibility exists of reentering texhdr without restoring
the stack. Since task exceptions are software driven, however, ordinarily they do not occur with norelation to tasks; so in practice this is not a problem.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

76

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk ref tex
Reference Task Exception Status[C Language Interface]
ER ercd = tk_ref_tex ( ID tskid, T_RTEX *pk_rtex ) ;[Parameters]
ID
T RTEX*tskid
pk rtex

Task ID
Address of packet for returning task exception status[Return Parameters]
ER

ercd

Error code

pk rtex detail:
UINT
UINT

pendtextexmask

Pending task exceptions
Allowed task exceptions(Other implementation-dependent parameters may be added beyond this point.)[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task specified in tskid does not exist)
Parameter error (the return parameter packet address cannot be used)[Description]
Gets the status of task exceptions for the task specified in tskid.
pendtex indicates the currently pending task exceptions. A raised task exception is indicated in pendtex
from the time the task exception is raised until its task exception handler is called.
texmask indicates allowed task exceptions.
Both pendtex and texmask are bit arrays of the form 1 << task exception code.
The invoking task can be specified by setting tskid = TSK SELF = 0. Note, however, that when asystem call is issued from a task-independent portion and tskid = TSK SELF = 0 is specified, error code
E ID is returned.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.4. SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

4.4

77

Synchronization and Communication Functions

Synchronization and communication functions use objects independent of tasks used to synchronize tasks
and achieve communication between tasks. The objects available for these purposes include semaphores,
event flags, and mailboxes.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

78

4.4.1

CHAPTER 4. T-KERNEL/OS FUNCTIONS

Semaphore

A semaphore is an object indicating the availability of a resource and its quantity as a numerical value.
A semaphore is used to realize mutual exclusion control and synchronization when using a resource.
Functions are provided for creating and deleting a semaphore, acquiring and returning resources corresponding to semaphores, and referencing semaphore status. A semaphore is an object identified by an
ID number called a semaphore ID.
A semaphore contains a resource count indicating whether the corresponding resource exists and inwhat quantity, and a queue of tasks waiting to acquire the resource. When a task (the task making
event notification) returns m resources, it increments the semaphore resource count by m. When a task(the task waiting for an event) acquires n resources, it decreases the semaphore resource count by n. If
the number of semaphore resources is insufficient (i.e., further reducing the semaphore resource countwould cause it to go into negative territory), a task attempting to acquire resources goes into WAIT
state until the next time resources are returned. A task waiting for semaphore resources is put in thesemaphore queue.
To prevent too many resources from being returned to a semaphore, a maximum resource count canbe set for each semaphore. Error is reported if it is attempted to return resources to a semaphore thatwould cause this maximum count to be exceeded.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.4. SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

79

tk cre sem
Create Semaphore[C Language Interface]IDsemid = tk_cre_sem ( T_CSEM *pk_csem ) ;[Parameters]
T CSEM*

pk csem

Information about the semaphore to be createdpk csem detail:
VP
ATR
INT
INT
UB

exinf
sematrisemcnt
maxsemdsname[8]Extended information
Semaphore attributes
Initial semaphore countMaximum semaphore countDS object name

(Other implementation-dependent parameters may be added beyond this point.)[Return Parameters]
ID

semid
or

Semaphore ID
Error Code[Error Codes]
E OK
E NOMEM
E LIMITE RSATR
E PAR

Normal completion
Insufficient memory (memory for control block cannot be allocated)
Semaphore count exceeds the system limit
Reserved attribute (sematr is invalid or cannot be used)
Parameter error (pk csem is invalid; isemcnt or maxsem is negative or invalid)[Description]
Creates a semaphore, assigning to it a semaphore ID.
This system call allocates a control block to the created semaphore, setting the initial count to isemcnt
and maximum count (upper limit) to maxsem. It must be possible to set maxsem to at least 65535.
Whether values above 65536 can be set is implementation-dependent.
exinf can be used freely by the user to set miscellaneous information about the created semaphore.
The information set in this parameter can be referenced by tk ref sem. If a larger area is needed forindicating user information, or if the information may need to be changed after the semaphore is created,
this can be done by allocating separate memory for this purpose and putting the memory packet address
in exinf. The OS pays no attention to the contents of exinf.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

80

CHAPTER 4. T-KERNEL/OS FUNCTIONS

sematr indicates system attributes in its low bits and implementation-dependent information in thehigh bits. The system attributes part of sematr is as follows.
sematr:= (TA_TFIFO || TA_TPRI) | (TA_FIRST || TA_CNT) | [TA_DSNAME]| [TA_NODISWAI]TA TFIFO
TA TPRI
TA FIRSTTA CNTTA DSNAMETA NODISWAI

Tasks are queued in FIFO order
Tasks are queued in priority order
The first task in the queue has precedence
Tasks with fewer requests have precedence
Specifies DS object name
Wait disabling by tk dis wai is prohibited

The queuing order of tasks waiting for a semaphore can be specified in TA TFIFO or TA TPRI. If theattribute is TA TFIFO, tasks are ordered by FIFO, whereas TA TPRI specifies queuing of tasks in orderof their priority setting.
TA FIRST and TA CNT specify precedence of resource acquisition. TA FIRST and TA CNT do not change theorder of the queue, which is determined by TA TFIFO or TA TPRI. When TA FIRST is specified, resources
are allocated starting from the first task in the queue regardless of request count. As long as the firsttask in the queue cannot obtain the requested number of resources, tasks behind it in the queue areprevented from obtaining resources.
TA CNT means resources are assigned based on the order in which tasks are able to obtain the requested
number of resources. The request counts are checked starting from the first task in the queue, and tasks
to which their requested amount can be allocated receive resources. This is not the same as allocatingin order of fewest requests.
When TA DSNAME is specified, dsname is valid and specifies the DS object name. DS object name isused to identify objects by debugger, and it is handled only by T-Kernel/DS API, td ref dsname andtd set dsname. For more details refer to td ref dsname and td set dsname. If TA DSNAME is not
specified, dsname is ignored. Then td ref dsname and td set dsname return E OBJ error.
#define TA_TFIFO
0x00000000#define TA_TPRI
0x00000001#define TA_FIRST
0x00000000#define TA_CNT
0x00000002#define TA_DSNAME
0x00000040#define TA_NODISWAI 0x00000080

c 2002–2005 by T-Engine Forum
Copyright °/* manage queue by FIFO*//* manage queue by priority*//* first task in queue has precedence*//* tasks with fewer requests have precedence *//* DS object name*//* reject wait disabling*/

TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.4. SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

81

tk del sem
Delete Semaphore[C Language Interface]
ER ercd = tk_del_sem ( ID semid ) ;[Parameters]
ID

semid

Semaphore ID[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS

Normal completion
Invalid ID number (semid is invalid or cannot be used)
Object does not exist (the semaphore specified in semid does not exist)[Description]
Deletes the semaphore specified in semid.
The semaphore ID and control block area are released as a result of this system call.
This system call completes normally even if there is a task waiting for condition fulfillment in thesemaphore, but error code E DLT is returned to the task in WAIT state.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

82

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk sig sem
Signal Semaphore[C Language Interface]
ER ercd = tk_sig_sem ( ID semid, INT cnt ) ;[Parameters]
ID
INT

semid
cnt

Semaphore ID
Resource return count[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXSE QOVR
E PAR

Normal completion
Invalid ID number (semid is invalid or cannot be used)
Object does not exist (the semaphore specified in semid does not exist)
Queuing or nesting overflow (semcnt over limit)
Parameter error (cnt ≤ 0)

[Description]
Returns to the semaphore specified in semid the number of resources indicated in cnt. If there is atask waiting for the semaphore, its request count is checked and resources allocated if possible. A task
allocated resources goes to READY state. In some conditions more than one task may be allocatedresources and put in READY state.
If the semaphore count increases to the point where the maximum count (maxcnt) would be exceededby the return of more resources, error code E QOVR is returned. In this case no resources are returned
and the count (semcnt) does not change.
[Additional Notes]
Error is not returned even if semcnt goes over the semaphore initial count (isemcnt). When semaphores
are used not for mutual exclusion control but for synchronization (like tk wup tsk and tk slp tsk),
the semaphore count (semcnt) will sometimes go over the initial setting (isemcnt). The semaphore
function can be used for mutual exclusion control by setting isemcnt and the maximum semaphorecount (maxsem) to the same value and checking for error occurring when the count increases.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.4. SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

83

tk wai sem
Wait on Semaphore[C Language Interface]
ER ercd = tk_wai_sem ( ID semid, INT cnt, TMO tmout ) ;[Parameters]
ID
INT
TMO

semid
cnt
tmout

Semaphore ID
Resource request counttimeout[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXSE PAR
E DLT
E RLWAIE DISWAIE TMOUTE CTXNormal completion
Invalid ID number (semid is invalid or cannot be used)
Object does not exist (the semaphore specified in semid does not exist)
Parameter error (tmout ≤ (−2), cnt ≤ 0)
The object being waited for was deleted (the specified semaphore was deleted while
waiting)
Wait state released (tk rel wai received in wait state)
Wait released by wait disabled state
Polling failed or timeout
Context error (issued from task-independent portion or in dispatch disabled state)[Description]
Gets from the semaphore specified in semid the number of resources indicated in cnt. If the requested
resources can be allocated, the task issuing this system call does not enter WAIT state but continues
executing. In this case the semaphore count (semcnt) is decreased by the size of cnt. If the resources
are not available, the task issuing this system call enters WAIT state, and is put in the queue of tasks
waiting for the semaphore. The semaphore count (semcnt) for this semaphore does not change in thiscase.
A maximum wait time (timeout) can be set in tmout. If the tmout time elapses before the wait releasecondition is met (tk sig sem is not executed), the system call terminates, returning timeout error code
E TMOUT.
Only positive values can be set in tmout. The time base for tmout (time unit) is the same as that forsystem time (= 1 ms).
When TMO POL = 0 is set in tmout, this means 0 was specified as the timeout value, and E TMOUT is
returned without entering WAIT state even if no resources are acquired.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

84

CHAPTER 4. T-KERNEL/OS FUNCTIONSWhen TMO FEVR = (−1) is set in tmout, this means infinity was specified as the timeout value, and thetask continues to wait for resource acquisition without timing out.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.4. SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

85

tk ref sem
Reference Semaphore Status[C Language Interface]
ER ercd = tk_ref_sem ( ID semid, T_RSEM *pk_rsem ) ;[Parameters]ID
T RSEM*semid
pk rsem

Semaphore ID
Address of packet for returning status information

pk rsem detail:
VP
ID
INT

exinf
wtsk
semcntExtended information
Waiting task information
Semaphore count(Other implementation-dependent parameters may be added beyond this point.)[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (semid is invalid or cannot be used)
Object does not exist (the semaphore specified in semid does not exist)
Parameter error (the return parameter packet address cannot be used)[Description]
References the status of the semaphore specified in semid, passing in the return parameters the current semaphore count (semcnt), information on tasks waiting for the semaphore (wtsk), and extended
information (exinf).
wtsk indicates the ID of a task waiting for the semaphore. If there are two or more such tasks, the IDof the task at the head of the queue is returned. If there are no waiting tasks, wtsk = 0 is returned.
If the specified semaphore does not exist, error code E NOEXS is returned.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

86

4.4.2

CHAPTER 4. T-KERNEL/OS FUNCTIONSEvent Flag

An event flag is an object used for synchronization, consisting of a pattern of bits used as flags toindicate the existence of the corresponding event. Functions are provided for creating and deleting an
event flag, for event flag setting and clearing, event flag waiting, and event flag status reference. An
event flag is identified by an ID number, called an event flag ID.
In addition to the bit pattern indicating the existence of corresponding events, an event flag has a queueof tasks waiting for the event flag. The event flag bit pattern is sometimes called simply event flag. The
event notifier sets or clears the specified bits of the event flag. A task can be made to wait for all orsome of the event flag bits to be set. A task waiting for an event flag is put in the queue of that eventflag.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.4. SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

87

tk cre flg
Create Event Flag
[C Language Interface]
ID flgid = tk_cre_flg ( T_CFLG *pk_cflg ) ;[Parameters]
T CFLG*

pk cflg

Information about the event flag to be created

pk cflg detail:
VP
ATR
UINT
UB

exinf
flgatr
iflgptndsname[8]Extended information
Event flag attributes
Initial event flag pattern
DS object name

(Other implementation-dependent parameters may be added beyond this point.)[Return Parameters]
ID

flgid
or

Event flag ID
Error Code[Error Codes]
E OK
E NOMEM
E LIMITE RSATR
E PAR

Normal completion
Insufficient memory (memory for control block cannot be allocated)
Number of event flags exceeds the system limit
Reserved attribute (flgatr is invalid or cannot be used)
Parameter error (pk cflg is invalid)[Description]
Creates an event flag, assigning to it an event flag ID.
This system call allocates a control block to the created event flag and sets its initial value to iflgptn.
An event flag handles one word’s worth of bits as a group. All operations are performed in single word
units.
exinf can be used freely by the user to set miscellaneous information about the created event flag.
The information set in this parameter can be referenced by tk ref flg. If a larger area is needed forindicating user information, or if the information may need to be changed after the event flag is created,
this can be done by allocating separate memory for this purpose and putting the memory packet address
in exinf. The OS pays no attention to the contents of exinf.
flgatr indicates system attributes in its low bits and implementation-dependent information in thehigh bits. The system attributes part of flgatr is as follows.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

88

CHAPTER 4. T-KERNEL/OS FUNCTIONS
flgatr:= (TA_TFIFO || TA_TPRI) | (TA_WMUL || TA_WSGL) | [TA_DSNAME]| [TA_NODISWAI]TA TFIFO
TA TPRITA WSGLTA WMULTA DSNAMETA NODISWAI

Tasks are queued in FIFO order
Tasks are queued in priority order
Waiting for multiple tasks is not allowed (Wait Single Task)
Waiting for multiple tasks is allowed (Wait Multiple Task)
Specifies DS object name
Wait disabling by tk dis wai is prohibited

When TA WSGL is specified, multiple tasks cannot be in WAIT state at the same time. Specifying TA WMUL
allows waiting by multiple tasks at the same time.
The queuing order of tasks waiting for an event flag can be specified in TA TFIFO or TA TPRI. If theattribute is TA TFIFO, tasks are ordered by FIFO, whereas TA TPRI specifies queuing of tasks in orderof their priority setting.
When TA WSGL is specified, however, since tasks cannot be queued, TA TFIFO or TA TPRI makes nodifference.
When multiple tasks are waiting for an event flag, tasks are checked in order from the head of the queue,
and the wait is released for tasks meeting the conditions. The first task to have its WAIT state released
is therefore not necessarily the first in the queue. If multiple tasks meet the conditions, wait state isreleased for each of them.
When TA DSNAME is specified, dsname is valid and specifies the DS object name. DS object name isused to identify objects by debugger, and it is handled only by T-Kernel/DS API, td ref dsname andtd set dsname. For more details refer to td ref dsname and td set dsname. If TA DSNAME is not
specified, dsname is ignored. Then td ref dsname and td set dsname return E OBJ error.
#define TA_TFIFO
0x00000000#define TA_TPRI
0x00000001#define TA_WSGL
0x00000000#define TA_WMUL
0x00000008#define TA_DSNAME
0x00000040#define TA_NODISWAI 0x00000080

c 2002–2005 by T-Engine Forum
Copyright °*//* manage queue by FIFO/* manage queue by priority*//* prohibit multiple task waiting *//* allow multiple task waiting*//* DS object name*//* prohibit wait disabling*/

TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.4. SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

89

tk del flg
Delete Event Flag
[C Language Interface]
ER ercd = tk_del_flg ( ID flgid ) ;[Parameters]
ID

flgid

Event flag ID[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS

Normal completion
Invalid ID number (flgid is invalid or cannot be used)
Object does not exist (the event flag specified in flgid does not exist)[Description]
Deletes the event flag specified in flgid.
Issuing this system call releases the corresponding event flag ID and control block memory space.
This system call is completed normally even if there are tasks waiting for the event flag, but error code
E DLT is returned to each task in WAIT state.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

90

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk set flg
tk clr flg
Set Event Flag
Clear Event Flag
[C Language Interface]
ER ercd = tk_set_flg ( ID flgid, UINT setptn ) ;ER ercd = tk_clr_flg ( ID flgid, UINT clrptn ) ;[Parameters]
For tk set flg
ID
flgid
UINT setptn

Event flag ID
Bit pattern to be set

For tk clr flg
ID
flgid
UINT clrptn

Event flag ID
Bit pattern to be cleared[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS

Normal completion
Invalid ID number (flgid is invalid or cannot be used)
Object does not exist (the event flag specified in flgid does not exist)[Description]
tk set flg sets the bits indicated in setptn in a one-word event flag specified in flgid. That is, alogical sum is taken of the values of the event flag specified in flgid and the values indicated in setptn.
tk clr flg clears the bits of the one-word event flag based on the corresponding zero bits of clrptn.
That is, a logical product is taken of the values of the event flag specified in flgid and the values
indicated in clrptn.
After event flag values are changed by tk set flg, if the condition for releasing the wait state of atask that called tk wai flg is met, the WAIT state of that task is cleared, putting it in RUN state or
READY state (or SUSPEND state if the waiting task was in WAIT-SUSPEND state).
Issuing tk clr flg never results in wait conditions being released for a task waiting for the specified
event flag; that is, dispatching never occurs with tk clr flg.
Nothing will happen to the event flag if all bits of setptn are cleared to 0 with tk set flg or if all bitsof clrptn are set to 1 with tk clr flg. No error will result in either case.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.4. SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

91

Multiple tasks can wait for a single event flag if that event flag has the TA WMUL attribute. The event
flag in that case has a queue for the waiting tasks. A single tk set flg call for such an event flag may
result in the release of multiple waiting tasks.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

92

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk wai flg
Wait Event Flag
[C Language Interface]
ER ercd = tk_wai_flg ( ID flgid, UINT waiptn, UINT wfmode, UINT *p_flgptn, TMO tmout ) ;[Parameters]
ID
UINT
UINT
TMO

flgid
waiptnwfmodetmout

Event flag ID
Wait bit pattern
Wait release condition
timeout[Return Parameters]
ER
UINT

ercd
flgptnError code
Event flag bit pattern[Error Codes]
E OK
E ID
E NOEXS
E PAR
E OBJ
E DLT
E RLWAIE DISWAIE TMOUTE CTXNormal completion
Invalid ID number (flgid is invalid or cannot be used)
Object does not exist (the event flag specified in flgid does not exist)
Parameter error (waiptn = 0, wfmode is invalid, or tmout ≤ (−2))
Invalid object state (multiple tasks are waiting for an event flag with TA WSGL attribute)
The object being waited for was deleted (the specified event flag was deleted while waiting)Wait state released (tk rel wai received in wait state)
Wait released by wait disabled state
Polling failed or timeout
Context error (issued from task-independent portion or in dispatch disabled state)[Description]
Waits for the event flag specified in flgid to be set, fulfilling the wait release condition specified in
wfmode.
If the event flag specified in flgid already meets the wait release condition set in wfmode, the waitingtask continues executing without going to WAIT state.
wfmode is specified as follows.
wfmode := (TWF_ANDW || TWF_ORW) | [TWF_CLR || TWF_BITCLR]

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.4. SYNCHRONIZATION AND COMMUNICATION FUNCTIONSTWF ANDWTWF ORWTWF CLRTWF BITCLR

0x00
0x01
0x10
0x20

93

AND wait condition
OR wait condition
Clear allClear condition bit only

If TWF ORW is specified, the issuing task waits for any of the bits specified in waiptn to be set for the
event flag specified in flgid (OR wait). If TWF ANDW is specified, the issuing task will wait for all of thebits specified in waiptn to be set for the event flag specified in flgid (AND wait).
If TWF CLR specification is not specified, the event flag values will remain unchanged even after theconditions have been satisfied and the task has been released from WAIT state. If TWF CLR is specified,
all bits of the event flag will be cleared to 0 once wait conditions of the waiting task have been met. If
TWF BITCLR is specified, then when the conditions are met and the task is released from WAIT state, only
the bits matching the event flag wait release conditions are cleared to 0 (event flag values &= ~waitrelease conditions).
The return parameter flgptn returns the value of the event flag after the WAIT state of a task has
been released due to this system call. If TWF CLR or TWF BITCLR was specified, the value before event
flag bits were cleared is returned. The value returned by flgptn fulfills the wait release conditions of
this system call. The contents of flgptn are indeterminate if the wait is released due to timeout or thelike.
A maximum wait time (timeout) can be set in tmout. If the tmout time elapses before the wait releasecondition is met, the system call terminates, returning timeout error code E TMOUT.
Only positive values can be set in tmout. The time base for tmout (time unit) is the same as that forsystem time (= 1 ms).
When TMO POL = 0 is set in tmout, this means 0 was specified as the timeout value, and E TMOUT is
returned without entering WAIT state even if the condition is not met.
When TMO FEVR = (−1) is set in tmout, this means infinity was specified as the timeout value, and thetask continues to wait for the condition to be met without timing out.
In the case of a timeout, the event flag bits are not cleared even if TWF CLR or TWF BITCLR was specified.
Setting waiptn to 0 results in Parameter error E PAR.
A task cannot execute tk wai flg for an event flag having the TA WSGL attribute while another task
is waiting for it. Error code E OBJ will be returned for the task issuing the subsequent tk wai flg,
regardless of whether that task would have gone to WAIT state; i.e., regardless of whether the wait
release conditions would be met.
If an event flag has the TA WMUL attribute, multiple tasks can wait for it at the same time. Waiting tasks
can be queued, and the WAIT states of multiple tasks can be released by issuing tk set flg just once.
If multiple tasks are queued for an event flag with TA WMUL attribute, the behavior is as follows.
• Tasks are queued in either FIFO or priority order. (Release of wait state does not always startfrom the head of the queue, however, depending on factors such as waiptn and wfmode settings.)• If TWF CLR or TWF BITCLR was specified by a task in the queue, the event flag is cleared when thattask is released from WAIT state.
• Tasks later in the queue than a task specifying TWF CLR or TWF BITCLR will see the event flag after
it has already been cleared.
If multiple tasks having the same priority are released from waiting simultaneously as a result of
tk set flg, the order of tasks in the ready queue (precedence) after release will continue to be thesame as their original order in the event flag queue.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

94

CHAPTER 4. T-KERNEL/OS FUNCTIONS[Additional Notes]
If a logical sum of all bits is specified as the wait release condition when tk wai flg is called (waiptn=0xfff...
ff, wfmode=TWF ORW), it is possible to transfer messages using one-word bit patterns in combination withtk set flg. However, it is not possible to send a message containing only 0s for all bits. Moreover, if
the next message is sent before a previous message has been read by tk wai flg, the previous message
will be lost; that is, message queuing is not possible.
Since setting waiptn = 0 will result in an E PAR error, it is guaranteed that the waiptn of tasks waiting
for an event flag will not be 0. The result is that if tk set flg sets all bits of an event flag to 1, thetask at the head of the queue will always be released from waiting no matter what its wait condition is.
The ability to have multiple tasks wait for the same event flag is useful in situations like the following.
Suppose, for example, that Task B and Task C are waiting for tk wai flg calls (2) and (3) until Task
A issues (1) tk set flg. If multiple tasks are allowed to wait for the event flag, the result will be thesame regardless of the order in which system calls (1)(2)(3) are executed (see Figure 4.1). On the other
hand, if multiple task waiting is not allowed and system calls are executed in the order (2), (3), (1), an
E OBJ error will result from the execution of (3) tk wai flg.

[Task A](1) tk set flg[Task B]

[Task C](2) tk wai flg(3) tk wai flg(no clear)(no clear)

Figure 4.1: Multiple Tasks Waiting for One Event Flag

[Rationale for the Specification]
The reason for returning E PAR error for specifying waiptn = 0 is that if waiptn = 0 were allowed, itwould not be possible to get out of WAIT state regardless of the subsequent event flag values.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.4. SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

95

tk ref flg
Reference Event Flag Status[C Language Interface]
ER ercd = tk_ref_flg ( ID flgid, T_RFLG *pk_rflg ) ;[Parameters]ID
T RFLG*

flgid
pk rflg

Event flag ID
Address of packet for returning status information[Return Parameters]
ER

ercd

Error code

pk rflg detail:
VP
ID
UINT

exinf
wtsk
flgptnExtended information
Waiting task information
Event flag bit pattern(Other implementation-dependent parameters may be added beyond this point.)[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (flgid is invalid or cannot be used)
Object does not exist (the event flag specified in flgid does not exist)
Parameter error (the return parameter packet address cannot be used)[Description]
References the status of the event flag specified in flgid, passing in the return parameters the current
flag pattern (flgptn), waiting task information (wtsk), and extended information (exinf).
wtsk returns the ID of a task waiting for this event flag. If more than one task is waiting (only when
the TA WMUL was specified), the ID of the first task in the queue is returned. If there are no waiting
tasks, wtsk = 0 is returned. If the specified event flag does not exist, error code E NOEXS is returned.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

96

4.4.3

CHAPTER 4. T-KERNEL/OS FUNCTIONS

Mailbox

A mailbox is an object used to achieve synchronization and communication by passing messages insystem (shared) memory space. Functions are provided for creating and deleting a mailbox, sending
and receiving messages in a mailbox, and referencing the mailbox status. A mailbox is an object
identified by an ID number called a mailbox ID.
A mailbox has a message queue for sent messages, and a task queue for tasks waiting to receive messages.
At the message sending end (making event notification), messages to be sent go in the message queue.
On the message receiving end (waiting for event notification), a task fetches one message from themessage queue. If there are no queued messages, the task goes to a state of waiting for receipt from the
mailbox until the next message is sent. Tasks waiting for message receipt from a mailbox are put in thetask queue of that mailbox.
Since the contents of messages using this function are in memory shared by the sending and receivingsides, only the start address of a message located in this shared space is actually sent and received. The
contents of the messages themselves are not copied. T-Kernel manages messages in the message queue
by means of a link list. An application program must allocate space at the beginning of a message to besent, for link list use by T-Kernel. This area is called the message header. The message header and themessage body together are called a message packet. When a system call sends a message to a mailbox,
the start address of the message packet (pk msg) is passed in a parameter. When a system call receives
a message from a mailbox, the start address of the message packet is passed in a return parameter. If
messages are assigned a priority in the message queue, the message priority (msgpri) of each message
must be specified in the message header (see Figure 4.2). The user puts the message contents not at
the beginning of the packet but after the header part (msgcont in the figure).

pk msg →Message header∗ May include message priority (msgpri)

Message content (msgcont)Figure 4.2: Format of Messages Using a Mailbox
T-Kernel overwrites the contents of the header when a message is put in the message queue (except
for the message priority area). An application, on the other hand, must not overwrite the header of amessage in the queue (including the message priority area). The behavior if an application overwrites
the message header is not defined. This restriction applies not only to the direct writing of a message
header by an application program, but also to the passing of a header address to T-Kernel and having
T-Kernel overwrite the message header with the contents. Accordingly, the behavior when a message
already in the message queue is again sent to a mailbox is undefined.
[Additional Notes]
Since the application program allocates the message header space for this mailbox function, there is nolimit on the number of messages that can be queued. A system call sending a message does not enterc 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.4. SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

97

WAIT state.
Memory blocks allocated dynamically from a fixed-size memory pool or variable-size memory pool, or
else a statically allocated area can be used for message packets; but these must not be located in task
space.
Generally, a sending task allocates a memory block from a memory pool, sending that as a message
packet. After a task on the receiving end fetches the message, it returns the memory block directly toits memory pool.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

98

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk cre mbx
Create Mailbox[C Language Interface]
ID mbxid = tk_cre_mbx ( T_CMBX* pk_cmbx ) ;[Parameters]
T CMBX*

pk cmbx

Information about the mailbox to be createdpk cmbx detail:
VP
ATR
UB

exinf
mbxatrdsname[8]Extended information
Mailbox attributes
DS object name

(Other implementation-dependent parameters may be added beyond this point.)[Return Parameters]
ID

mbxid
or

Mailbox ID
Error Code[Error Codes]
E OK
E NOMEM
E LIMITE RSATR
E PAR

Normal completion
Insufficient memory (memory for a control block or buffer cannot be allocated)
Number of mailboxes exceeds the system limit
Reserved attribute (mbxatr is invalid or cannot be used)
Parameter error (pk cmbx is invalid)[Description]
Creates a mailbox, assigning to it a mailbox ID.
This system call allocates a control block, etc. for the created mailbox.
exinf can be used freely by the user to set miscellaneous information about the created mailbox. The
information set in this parameter can be referenced by tk ref mbx. If a larger area is needed forindicating user information, or if the information may need to be changed after the mailbox is created,
this can be done by allocating separate memory for this purpose and putting the memory packet address
in exinf. The OS pays no attention to the contents of exinf.
mbxatr indicates system attributes in its low bits and implementation-dependent information in thehigh bits. The system attributes part of mbxatr is as follows.
mbxatr:= (TA_TFIFO || TA_TPRI) | (TA_MFIFO || TA_MPRI)| [TA_DSNAME] | [TA_NODISWAI]

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.4. SYNCHRONIZATION AND COMMUNICATION FUNCTIONSTA TFIFO
TA TPRITA MFIFOTA MPRITA DSNAMETA NODISWAI

99

Tasks are queued in FIFO order
Tasks are queued in priority orderMessages are queued in FIFO orderMessages are queued in priority orderSpecifies DS object name
Wait disabling by tk dis wai is prohibited

The queuing order of tasks waiting for a mailbox can be specified in TA TFIFO or TA TPRI. If the attribute
is TA TFIFO, tasks are ordered by FIFO, whereas TA TPRI specifies queuing of tasks in order of theirpriority setting.
TA MFIFO and TA MPRI are used to specify the order of messages in the message queue (messages waiting
to be received). If the attribute is TA MFIFO, messages are ordered by FIFO; TA MPRI specifies queuingof messages in priority order. Message priority is set in a special field in the message packet. Message
priority is specified by positive values, with 1 indicating the highest priority and higher numbers indicating successively lower priority. The largest value that can be expressed in the PRI type is the lowest
priority. Messages having the same priority are ordered as FIFO.
When TA DSNAME is specified, dsname is valid and specifies the DS object name. DS object name isused to identify objects by debugger, and it is handled only by T-Kernel/DS API, td ref dsname andtd set dsname. For more details refer to td ref dsname and td set dsname. If TA DSNAME is not
specified, dsname is ignored. Then td ref dsname and td set dsname return E OBJ error.
#define TA_TFIFO
0x00000000#define TA_TPRI
0x00000001#define TA_MFIFO
0x00000000#define TA_MPRI
0x00000002#define TA_DSNAME
0x00000040#define TA_NODISWAI 0x00000080/* manage task queue by FIFO*//* manage task queue by priority*//* manage message queue by FIFO*//* manage message queue by priority *//* DS object name*//* reject wait disabling*/[Additional Notes]
The body of a message passed by the mailbox function is located in system (shared) memory; only its
start address is actually sent and received. For this reason a message must not be located in task space.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

100

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk del mbx
Delete Mailbox[C Language Interface]
ER ercd = tk_del_mbx ( ID mbxid ) ;[Parameters]
ID

mbxid

Mailbox ID[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS

Normal completion
Invalid ID number (mbxid is invalid or cannot be used)
Object does not exist (the mailbox specified in mbxid does not exist)[Description]
Deletes the mailbox specified in mbxid.
Issuing this system call releases the mailbox ID and control block memory space, etc., associated withthe mailbox.
This system call completes normally even if there are tasks waiting for messages in the deleted mailbox,
but error code E DLT is returned to each of the tasks in WAIT state. Even if there are messages still inthe deleted mailbox, the mailbox is deleted without returning an error code.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.4. SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

101

tk snd mbx
Send Message to Mailbox[C Language Interface]
ER ercd = tk_snd_mbx ( ID mbxid, T_MSG *pk_msg ) ;[Parameters]ID
T MSG*

mbxid
pk msgMailbox ID
Message packet address[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (mbxid is invalid or cannot be used)
Object does not exist (the mailbox specified in mbxid does not exist)
Parameter error (pk msg is a value that cannot be used)[Description]
Sends the message packet having pk msg as its start address to the mailbox specified in mbxid. The
message packet contents are not copied; only the start address (pk msg) is passed at the time of message
receipt.
If tasks are already waiting for messages in the same mailbox, the WAIT state of the task at the head of
the queue is released, and the pk msg passed to tk snd mbx is sent to that task, becoming a parameter
returned by tk rcv mbx. If there are no tasks waiting for messages in the specified mailbox, the sent
message goes in the message queue of that mailbox. In neither case does the task issuing tk snd mbx
enter WAIT state.
pk msg is the start address of the packet containing the message, including header. The message header
has the following format.
typedef struct t_msg {?
?
} T_MSG;/* Implementation-dependent contents (fixed size) */typedef struct t_msg_pri {T_MSG
msgque;/* message queue area */PRI
msgpri;/* message priority*/} T_MSG_PRI;

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

102

CHAPTER 4. T-KERNEL/OS FUNCTIONS

The message header is T MSG (if TA MFIFO attribute is specified) or T MSG PRI (if TA MPRI). In either casethe message header has a fixed size, which can be obtained by sizeof(T MSG) or sizeof(T MSG PRI).
The actual message must be put in the area after the header. There is no limit on message size, which
may be variable-length.
[Additional Notes]
Messages are sent by tk snd mbx regardless of the status of the receiving tasks. In other words, message
sending is asynchronous. What waits in the queue is not the task itself, but the sent message. So while
there are queues of waiting messages and receiving tasks, the sending task does not go to WAIT state.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.4. SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

103

tk rcv msg
Receive Message from Mailbox[C Language Interface]
ER ercd = tk_rcv_mbx ( ID mbxid, T_MSG **ppk_msg, TMO tmout ) ;[Parameters]
ID
TMO

mbxid
tmout

Mailbox ID
timeout[Return Parameters]ER
T MSG*

ercd
pk msgError code
Start address of message packet[Error Codes]
E OK
E ID
E NOEXSE PAR
E DLT
E RLWAIE DISWAIE TMOUTE CTXNormal completion
Invalid ID number (mbxid is invalid or cannot be used)
Object does not exist (the mailbox specified in mbxid does not exist)
Parameter error (tmout ≤ (−2))
The object being waited for was deleted (the mailbox was deleted while waiting)Wait state released (tk rel wai received in wait state)
Wait released by wait disabled state
Polling failed or timeout
Context error (issued from task-independent portion or in dispatch disabled state)[Description]
Receives a message from the mailbox specified in mbxid. If no messages have been sent to the mailbox(the message queue is empty), the task issuing this system call enters WAIT state and is queued formessage arrival. If there are messages in the mailbox, the task issuing this system call fetches the firstmessage in the message queue, passing this in the return parameter pk msg.
A maximum wait time (timeout) can be set in tmout. If the tmout time elapses before the wait releasecondition is met (no message arrives), the system call terminates, returning timeout error code E TMOUT.
Only positive values can be set in tmout. The time base for tmout (time unit) is the same as that forsystem time (= 1 ms).
When TMO POL = 0 is set in tmout, this means 0 was specified as the timeout value, and E TMOUT is
returned without entering WAIT state even if no message arrives.
When TMO FEVR = (−1) is set in tmout, this means infinity was specified as the timeout value, and thetask continues to wait for message arrival without timing out.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

104

CHAPTER 4. T-KERNEL/OS FUNCTIONS[Additional Notes]
pk msg is the start address of the packet containing the message, including header. The message header
is T MSG (if TA MFIFO attribute is specified) or T MSG PRI (if TA MPRI).

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.4. SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

105

tk ref mbx
Reference Mailbox Status[C Language Interface]
ER ercd = tk_ref_mbx ( ID mbxid, T_RMBX *pk_rmbx ) ;[Parameters]ID
T RMBX*mbxid
pk rmbx

Mailbox ID
Address of packet for returning status information[Return Parameters]
ER

ercd

Error code

pk rmbx detail:VPID
T MSG*

exinf
wtsk
pk msgExtended information
Waiting task information
Start address of next message packet to be received(Other implementation-dependent parameters may be added beyond this point.)[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (mbxid is invalid or cannot be used)
Object does not exist (the mailbox specified in mbxid does not exist)
Parameter error (the return parameter packet address cannot be used)[Description]
References the status of the mailbox specified in mbxid, passing in the return parameters the next
message to be received (the first message in the message queue), waiting task information (wtsk), andextended information (exinf).
wtsk indicates the ID of a task waiting for the mailbox. If there are multiple waiting tasks, the ID of
the first task in the queue is returned. If there are no waiting tasks, wtsk = 0 is returned.
If the specified mailbox does not exist, error code E NOEXS is returned.
pk msg indicates the message that will be received the next time tk rcv mbx is issued. If there are no
messages in the message queue, pk msg = NULL is returned. At least one of pk msg = NULL andwtsk = 0 is always true for this system call.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

106

CHAPTER 4. T-KERNEL/OS FUNCTIONS

4.5

Extended Synchronization and Communication Functions

Extended synchronization and communication functions use objects independent of tasks to realize moresophisticated synchronization and communication between tasks. The functions specified here include
mutex, message buffer, and rendezvous port functions.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.5. EXTENDED SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

4.5.1

107

Mutex

A mutex is an object for mutual exclusion control among tasks that use shared resources. Priority
inheritance mutexes and priority ceiling mutexes are supported, as tools for managing the problem of
unbounded priority inversion that can occur in mutual exclusion control. Functions are provided for
creating and deleting a mutex, locking and unlocking a mutex, and referencing mutex status. A mutex
is identified by an ID number called a mutex ID.
A mutex has a status (locked or unlocked) and a queue for tasks waiting to lock the mutex. For eachmutex, T-Kernel keeps track of the tasks locking it; and for each task, it keeps track of the mutexes it
has locked. Before a task uses a resource, it locks a mutex corresponding to that resource. If the mutex
is already locked by another task, the task waits for the mutex to become unlocked. Tasks in mutex lockwaiting state are put in the mutex queue. When a task finishes with a resource, it unlocks the mutex.
A mutex with TA INHERIT(= 0x02) specified as mutex attribute supports priority inheritance protocol,
while one with TA CEILING(= 0x03) specified supports priority ceiling protocol. When a priority ceiling
mutex is created, a ceiling priority is assigned to it, indicating the base priority of the task having thehighest base priority among the tasks able to lock that mutex. If a task having a higher base priority
than the ceiling priority of the mutex tries to lock it, error code E ILUSE is returned. If tk chg pri isissued in an attempt to set the base priority of a task locking a priority ceiling mutex to a value higher
than the ceiling priority of that mutex, E ILUSE is returned by the tk chg pri system call.
When these protocols are used, unbounded priority inversion is prevented by changing the current
priority of a task in a mutex operation. Strict adherence to the priority inheritance protocol andpriority ceiling protocol requires that the task current priority must always be changed to match thepeak value of the following priorities. This is called strict priority control.
• The task base priority.
• When tasks lock priority inheritance mutexes, the current priority of the task having the highest
current priority of the tasks waiting for those mutexes.
• When tasks lock priority ceiling mutexes, the ceiling priority of the mutex having the highest
ceiling priority among those mutexes.
Note that when the current priority of a task waiting for a priority inheritance mutex changes as theresult of a base priority change brought about by mutex operation or tk chg pri, it may be necessary tochange the current priority of the task locking that mutex. This is called dynamic priority inheritance.
Further, if this task is waiting for another priority inheritance mutex, dynamic priority inheritanceprocessing may be necessary also for the task locking that mutex.
The T-Kernel specification defines, in addition to the above strict priority control, a simplified priority
control limiting the situations in which the current priority is changed. The choice between the twois an implementation-dependent matter. In the simplified priority control, whereas all changes in the
direction of raising the task current priority are carried out, changes in the direction of lowering thatpriority are made only when a task is no longer locking any mutexes. (In this case the task current
priority reverts to the base priority.) More specifically, processing to change the current priority isneeded only in the following circumstances.
• When a task with a higher current priority than that of the task locking a priority inheritance
mutex starts waiting for that mutex.
• When a task waiting for a priority inheritance mutex is changed to a higher current priority thanthat of the task locking that mutex.
• When a task locks a priority ceiling mutex having a higher ceiling priority than the task’s current
priority.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

108

CHAPTER 4. T-KERNEL/OS FUNCTIONS• When a task is no longer locking any mutexes.

When the current priority of a task is changed in connection with a mutex operation, the following
processing is performed. If the task whose priority changed is in a run state, the task precedence ischanged in accord with the new priority. Its precedence among other tasks having the same priority isimplementation-dependent. Likewise, if the task whose priority changed is waiting in a queue of somekind, its order in that queue is changed based on its new priority. Its order among other tasks having
the same priority is implementation-dependent.
When a task terminates and there are mutexes still locked by that task, all the mutexes are unlocked. The
order in which multiple locked mutexes are unlocked is implementation-dependent. See the descriptionof tk unl mtx for the specific processing involved.
[Additional Notes]
A TA TFIFO attribute mutex or TA TPRI attribute mutex has functionality equivalent to that of asemaphore with a maximum of one resource (binary semaphore). The main differences are that amutex can be unlocked only by the task that locked it, and a mutex is automatically unlocked when thetask locking it terminates.
The term “priority ceiling protocol” is used here in a broad sense. The protocol described here is not
the same as the algorithm originally proposed. Strictly speaking, it is what is otherwise referred to asa highest locker protocol or by other names.
When the change in current priority of a task due to a mutex operation results in that task’s order
being changed in a priority-based queue, it may be necessary to release the waiting state of other tasks
waiting for that task or for that queue.
[Rationale for the Specification]
The precedence of tasks having the same priority as the result of a change in task current priority in amutex operation is left as implementation-dependent, for the following reason.
Depending on the application, the mutex function may lead to frequent changes in current priority. It
would not be desirable for this to result in constant task switching, which is what would happen if theprecedence were made the lowest each time among tasks of the same priority. Ideally task precedence
rather than priority should be inherited, but that results in large overhead in implementation. This
aspect of the specification is therefore made an implementation-dependent matter.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.5. EXTENDED SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

109

tk cre mtx
Create Mutex[C Language Interface]
ID mtxid = tk_cre_mtx ( T_CMTX *pk_cmtx ) ;[Parameters]
T CMTX*

pk cmtx

Information about the mutex to be createdpk cmtx detail:
VP
ATR
PRI
UB

exinf
mtxatrceilpridsname[8]Extended information
Mutex attributes
Mutex ceiling priority
DS object name

(Other implementation-dependent parameters may be added beyond this point.)[Return Parameters]
ID

mtxid
or

Mutex ID
Error Code[Error Codes]
E OK
E NOMEM
E LIMITE RSATR
E PAR

Normal completion
Insufficient memory (memory for control block cannot be allocated)
Number of mutexes exceeds the system limit
Reserved attribute (mtxatr is invalid or cannot be used)
Parameter error (pk cmtx or ceilpri is invalid)[Description]
Creates a mutex, assigning to it a mutex ID.
exinf can be used freely by the user to set miscellaneous information about the created mutex. The
information set in this parameter can be referenced by tk ref mtx. If a larger area is needed forindicating user information, or if the information may need to be changed after the mutex is created,
this can be done by allocating separate memory for this purpose and putting the memory packet address
in exinf. The OS pays no attention to the contents of exinf.
mtxatr indicates system attributes in its low bits and implementation-dependent information in thehigh bits. The system attributes part of mtxatr is as follows.
mtxatr:= (TA_TFIFO || TA_TPRI || TA_INHERIT || TA_CEILING)| [TA_DSNAME]| [TA_NODISWAI]

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

110

CHAPTER 4. T-KERNEL/OS FUNCTIONSTA TFIFO
TA TPRITA INHERITTA CEILINGTA DSNAMETA NODISWAI

Tasks are queued in FIFO order
Tasks are queued in priority order
Priority inheritance protocol
Priority ceiling protocol
Specifies DS object name
Wait disabling by tk dis wai is prohibited

When the TA TFIFO attribute is specified, the order of the mutex task queue is FIFO. If TA TPRI,TA INHERIT, or TA CEILING is specified, tasks are ordered by their priority. TA INHERIT indicates thatpriority inheritance protocol is used, and TA CEILING specifies priority ceiling protocol.
Only when TA CEILING is specified does ceilpri have validity, setting the mutex ceiling priority.
When TA DSNAME is specified, dsname is valid and specifies the DS object name. DS object name isused to identify objects by debugger, and it is handled only by T-Kernel/DS API, td ref dsname andtd set dsname. For more details refer to td ref dsname and td set dsname. If TA DSNAME is not
specified, dsname is ignored. Then td ref dsname and td set dsname return E OBJ error.
#define TA_TFIFO
0x00000000#define TA_TPRI
0x00000001#define TA_INHERIT 0x00000002#define TA_CEILING 0x00000003#define TA_DSNAME
0x00000040#define TA_NODISWAI 0x00000080

c 2002–2005 by T-Engine Forum
Copyright °/* manage task queue by FIFO*//* manage task queue by priority *//* priority inheritance protocol *//* priority ceiling protocol*//* DS object name*//* reject wait disabling*/

TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.5. EXTENDED SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

111

tk del mtx
Delete Mutex[C Language Interface]
ER ercd = tk_del_mtx ( ID mtxid ) ;[Parameters]
ID

mtxid

Mutex ID

[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS

Normal completion
Invalid ID number (mtxid is invalid or cannot be used)
Object does not exist (the mutex specified in mtxid does not exist)[Description]
Deletes the mutex specified in mtxid.
Issuing this system call releases the mutex ID and control block memory space allocated to the mutex.
This system call completes normally even if there are tasks waiting to lock the deleted mutex, but error
code E DLT is returned to each of the tasks in WAIT state.
When a mutex is deleted, a task locking the mutex will have fewer locked mutexes. If the mutex was a
priority inheritance mutex or priority ceiling mutex, it is possible that the priority of the task locking
it will change as a result of its deletion.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

112

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk loc mtx
Lock Mutex[C Language Interface]
ER ercd = tk_loc_mtx ( ID mtxid, TMO tmout ) ;[Parameters]
ID
TMO

mtxid
tmout

Mutex ID
timeout[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXSE PAR
E DLT
E RLWAIE DISWAIE TMOUTE CTX
E ILUSE

Normal completion
Invalid ID number (mtxid is invalid or cannot be used)
Object does not exist (the mutex specified in mtxid does not exist)
Parameter error (tmout ≤ (−2))
The object being waited for was deleted (the mutex was deleted while waiting for a lock)Wait state released (tk rel wai received in wait state)
Wait released by wait disabled state
Polling failed or timeout
Context error (issued from task-independent portion or in dispatch disabled state)
Illegal use (multiple lock, or upper priority limit exceeded)[Description]
Locks the mutex specified in mtxid. If the mutex can be locked immediately, the task issuing this systemcall continue executing without entering WAIT state, and the mutex goes to locked status. If the mutex
cannot be locked, the task issuing this system call enters WAIT state. That is, the task is put in thequeue of this mutex.
A maximum wait time (timeout) can be set in tmout. If the tmout time elapses before the wait releasecondition is met, the system call terminates, returning timeout error code E TMOUT. Only positive values
can be set in tmout. The time base for tmout (time unit) is the same as that for system time (= 1 ms).
When TMO POL = 0 is set in tmout, this means 0 was specified as the timeout value, and E TMOUT is
returned without entering WAIT state even if the resource cannot be locked. When TMO FEVR = (−1)
is set in tmout, this means infinity was specified as the timeout value, and the task continues wait tountil the resource is locked.
If the invoking task has already locked the specified mutex, error code E ILUSE (multiple lock) is returned.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.5. EXTENDED SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

113

If the specified mutex is a priority ceiling mutex and the base priority2 of the invoking task is higher
than the ceiling priority of the mutex, error code E ILUSE (upper priority limit exceeded) is returned.
[Additional Notes]
Priority inheritance mutex (TA INHERIT attribute)
If the invoking task is waiting to lock a mutex and the current priority of the task currently
locking that mutex is lower than that of the invoking task, the priority of the locking task israised to the same level as the invoking task. If the wait ends before the waiting task can obtaina lock (timeout or other reason), the priority of the task locking that mutex can be lowered(implementation-dependent option) to the highest of the following three priorities.
a. The highest priority among the current priorities of task waiting to lock the mutex.
b. The highest priority among all the other mutexes locked by the task currently locking thismutex.
c. The base priority of the locking task.
Priority ceiling mutex (TA CEILING attribute)
If the invoking task obtains a lock and its current priority is lower than the mutex ceiling priority,
the priority of the invoking task is raised to the mutex ceiling priority.

2 Base priority: The task priority before it is automatically raised by the mutex. This is the priority last set bytk chg pri (including while the mutex is locked), or if tk chg pri has never been issued, the priority set when the task
was created.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

114

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk unl mtx
Unlock Mutex[C Language Interface]
ER ercd = tk_unl_mtx ( ID mtxid ) ;[Parameters]
ID

mtxid

Mutex ID

[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXSE ILUSE

Normal completion
Invalid ID number (mtxid is invalid or cannot be used)
Object does not exist (the mutex specified in mtxid does not exist)
Illegal use (not a mutex locked by the invoking task)[Description]
Unlocks the mutex specified in mtxid. If there are tasks waiting to lock the mutex, the WAIT state of
the task at the head of the queue for that mutex is released and that task locks the mutex.
If a mutex that was not locked by the invoking task is specified, error code E ILUSE is returned.
[Additional Notes]
If the unlocked mutex is a priority inheritance mutex or priority ceiling mutex, task priority must be
lowered as follows. If as a result of this operation the invoking task no longer has any locked mutexes,
the invoking task priority is lowered to its base priority. If the invoking task continues to have locked
mutexes after this operation, the invoking task priority is lowered to whichever of the following priority
levels is highest.
a. The highest priority of all remaining locked mutexes.
b. The base priority.
Note that the lowering of priority when locked mutexes remain is an implementation-dependent optional
specification.
If a task terminates (goes to DORMANT state or NON-EXISTENT state) without explicitly unlocking
mutexes, all its locked mutexes are automatically unlocked.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.5. EXTENDED SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

115

tk ref mtx
Refer Mutex Status[C Language Interface]
ER ercd = tk_ref_mtx ( ID mtxid, T_RMTX *pk_rmtx ) ;[Parameters]ID
T RMTX*mtxid
pk rmtx

Mutex ID
Address of packet for returning status information[Return Parameters]
ER

ercd

Error code

pk rmtx detail:
VP
ID
ID

exinf
htsk
wtsk

Extended information
ID of task locking the mutex
ID of tasks waiting to lock the mutex(Other implementation-dependent parameters may be added beyond this point.)[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (mtxid is invalid or cannot be used)
Object does not exist (the mutex specified in mtxid does not exist)
Parameter error (the return parameter packet address cannot be used)[Description]
References the status of the mutex specified in mtxid, passing in the return parameters the task currently
locking the mutex (htsk), tasks waiting to lock the mutex (wtsk), and extended information (exinf).
htsk returns the ID of the task locking the mutex. If no task is locking it, htsk = 0 is returned.
wtsk indicates the ID of a task waiting to lock the mutex. If there are multiple waiting tasks, the ID of
the task at the head of the queue is returned. If no tasks are waiting, wtsk = 0 is returned.
If the specified mutex does not exist, error code E NOEXS is returned.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

116

CHAPTER 4. T-KERNEL/OS FUNCTIONS

4.5.2

Message Buffer

A message buffer is an object for achieving synchronization and communication by the passing ofvariable-size messages. Functions are provided for creating and deleting a message buffer, sending
and receiving messages using a message buffer, and referencing message buffer status. A message buffer
is an object identified by an ID number called a message buffer ID.
A message buffer keeps a queue of messages waiting to be sent (send queue) and a queue of tasks waiting
for message receipt (receive queue). It also has a message buffer space for holding sent messages. The
message sender (the side making event notification) copies to the message buffer a message it wants
to send. If there is insufficient space in the message buffer area, the message is queued for sending
until enough space is available. A task waiting to send a message to the message buffer is put in thesend queue. On the message receipt side (waiting for event notification), one message is fetched fromthe message buffer. If the message buffer has no messages, the task enters WAIT state until the next
message is sent. A task waiting for receipt from a message buffer is put in the receive queue of thatmessage buffer.
A synchronous message function can be realized by setting the message buffer space size to 0. In thatcase both the sending task and receiving task wait for a system call to be invoked by each other, andthe message is passed when both sides issue system calls.
[Additional Notes]
The message buffer functioning when the size of the message buffer space is set to 0 is explained here
using the example in Figure 4.3. In this example Task A and Task B run asynchronously.
• If Task A calls tk snd mbf first, it goes to WAIT state until Task B calls tk rcv mbf. In this case
Task A is put in the message buffer send queue (a).
• If Task B calls tk rcv mbf first, on the other hand, Task B goes to WAIT state until Task A calls
tk snd mbf. Task B is put in the message buffer receive queue (b).
• At the point where both Task A has called tk snd mbf and Task B has called tk rcv mbf, amessage is passed from Task A to Task B; then both tasks go from WAIT state to a run state.
Task A

Task B

Task A

Task Btk snd mbf

tk rcv mbf

Send waiting state

Receive waiting state- tk rcv mbf(a) tk snd mbf called firsttk snd mbf-(b) tk rcv mbf called first

Figure 4.3: Synchronous Communication by Message Buffer
Tasks waiting to send to a message buffer send messages in their queued order. Suppose Task A wanting
to send a 40-byte message to a message buffer, and Task B wanting to send a 10-byte message, are queued
in that order. If another task receives a message opening 20 bytes of space in the message buffer, Task
B is still required to wait until Task A sends its message.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.5. EXTENDED SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

117

A message buffer is used to pass variable-size messages by copying them. It is the copying of messages
that makes this function different from the mailbox function.
It is assumed that the message buffer will be implemented as a ring buffer.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

118

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk cre mbf
Create Message Buffer[C Language Interface]
ID mbfid = tk_cre_mbf ( T_CMBF *pk_cmbf ) ;[Parameters]
T CMBF*pk cmbf

Information about the message buffer to be createdpk cmbf detail:
VP
ATR
INT
INT
UB

exinf
mbfatrbufsz
maxmszdsname[8]Extended information
Message buffer attributes
Message buffer size (in bytes)
Maximum message size (in bytes)
DS object name

(Other implementation-dependent parameters may be added beyond this point.)[Return Parameters]
ID

mbfid
or

Message buffer ID
Error Code[Error Codes]
E OK
E NOMEM
E LIMITE RSATR
E PAR

Normal completion
Insufficient memory (memory for control block or ring buffer area cannot be allocated)
Number of message buffers exceeds the system limit
Reserved attribute (mbfatr is invalid or cannot be used)
Parameter error (pk cmbf is invalid, or bufsz or maxmsz is negative or invalid)[Description]
Creates a message buffer, assigning to it a message buffer ID.
This system call allocates a control block to the created message buffer. Based on the information
specified in bufsz, it allocates a ring buffer area for message queue use (for messages waiting to bereceived).
A message buffer is an object for managing the sending and receiving of variable-size messages. If differsfrom a mailbox (mbx) in that the contents of the variable-size messages are copied when the message issent and received. It also has a function for putting the sending task in WAIT state when the buffer isfull.
exinf can be used freely by the user to set miscellaneous information about the created message buffer.
The information set in this parameter can be referenced by tk ref mbf. If a larger area is needed for
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.5. EXTENDED SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

119

indicating user information, or if the information may need to be changed after the message buffer iscreated, this can be done by allocating separate memory for this purpose and putting the memory packet
address in exinf. The OS pays no attention to the contents of exinf.
mbfatr indicates system attributes in its low bits and implementation-dependent information in thehigh bits. The system attributes part of mbfatr is as follows.
mbfatr:= (TA_TFIFO || TA_TPRI) | [TA_DSNAME] | [TA_NODISWAI]TA TFIFO
TA TPRITA DSNAMETA NODISWAI

Tasks waiting to send are queued in FIFO order
Tasks waiting to send are queued in priority orderSpecifies DS object name
Wait disabling by tk dis wai is prohibited

The queuing order of tasks waiting for a message to be sent when the buffer is full can be specified in
TA TFIFO or TA TPRI. If the attribute is TA TFIFO, tasks are ordered by FIFO, whereas TA TPRI specifies
queuing of tasks in order of their priority setting. Messages themselves are queued in FIFO order only.
Tasks waiting for message receipt from a message buffer are likewise queued in FIFO order only.
When TA DSNAME is specified, dsname is valid and specifies the DS object name. DS object name isused to identify objects by debugger, and it is handled only by T-Kernel/DS API, td ref dsname andtd set dsname. For more details refer to td ref dsname and td set dsname. If TA DSNAME is not
specified, dsname is ignored. Then td ref dsname and td set dsname return E OBJ error.
#define TA_TFIFO
0x00000000#define TA_TPRI
0x00000001#define TA_DSNAME
0x00000040#define TA_NODISWAI 0x00000080/* manage task queue by FIFO*//* manage task queue by priority *//* DS object name*//* reject wait disabling*/[Additional Notes]
When there are multiple tasks waiting to send messages, the order in which their messages are sent
when buffer space becomes available is always in their queued order. If, for example, a Task A wanting
to send a 30-byte message is queued with a Task B wanting to send a 10-byte message, in the order
A-B, even if 20 bytes of message buffer space becomes available, Task B never sends its message before
Task A.
The ring buffer in which messages are queued also contains information for managing each message.
For this reason the total size of queued messages will ordinarily not be identical to the ring buffer size
specified in bufsz. Normally the total message size will be smaller than bufsz. In this sense bufsz
does not strictly represent the total message capacity.
It is possible to create a message buffer with bufsz = 0. In this case communication using the message
buffer is completely synchronous between the sending and receiving tasks. That is, if either tk snd mbf
or tk rcv mbf is executed ahead of the other, the task executing the first system call goes to WAIT
state. When the other system call is executed, the message is passed (copied), then both tasks resume
running.
In the case of a bufsz = 0 message buffer, the specific functioning is as follows.
• In Figure 4.4, Task A and Task B operate asynchronously. If Task A arrives at point (1) first andexecutes tk snd mbf(mbfid), Task A goes to send wait state until Task B arrives at point (2).
If tk ref tsk is issued for Task A in this state, tskwait=TTW SMBF is returned. If, on the otherc 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

120

CHAPTER 4. T-KERNEL/OS FUNCTIONS
hand, Task B gets to point (2) first and calls tk rcv mbf(mbfid), Task B goes to receive wait state
until Task A gets to point (1). If tk ref tsk is issued for Task B in this state, tskwait=TTW RMBF
is returned.
• At the point where both Task A has executed tk snd mbf(mbfid) and Task B has executedtk rcv mbf(mbfid), a message is passed from Task A to Task B, their wait states are released
and both tasks resume running.

Task A

Task B(1)
tk snd mbf(mbfid)(2)
tk rcv mbf(mbfid)
Message send wait (TTW SMBF) if wait entered at (1)Message receive wait (TTW RMBF) if wait entered at (2)Figure 4.4: Synchronous Communication Using Message Buffer of bufsz = 0
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.5. EXTENDED SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

121

tk del mbf
Delete Message Buffer[C Language Interface]
ER ercd = tk_del_mbf ( ID mbfid ) ;[Parameters]
ID

mbfid

Message buffer ID[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS

Normal completion
Invalid ID number (mbfid is invalid or cannot be used)
Object does not exist (the message buffer specified in mbfid does not exist)[Description]
Deletes the message buffer specified in mbfid.
Issuing this system call releases the corresponding message buffer and control block memory space, as
well as the message buffer space.
This system call completes normally even if there were tasks queued in the message buffer for message
receipt or message sending, but error code E DLT is returned to the tasks in WAIT state. If there aremessages left in the message buffer when it is deleted, the message buffer is deleted anyway. No error
code is returned and the messages are discarded.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

122

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk snd mbf
Send Message to Message Buffer[C Language Interface]
ER ercd = tk_snd_mbf ( ID mbfid, VP msg, INT msgsz, TMO tmout ) ;[Parameters]
ID
INT
VP
TMO

mbfid
msgsz
msg
tmout

Message buffer ID
Send message size (in bytes)
Start address of send message packet
timeout[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXSE PAR
E DLT
E RLWAIE DISWAIE TMOUTE CTXNormal completion
Invalid ID number (mbfid is invalid or cannot be used)
Object does not exist (the message buffer specified in mbfid does not exist)
Parameter error (msgsz ≤ 0, msgsz > maxmsz,value that cannot be used in msg, or
tmout ≤ (−2))
The object being waited for was deleted (message buffer was deleted while waiting)Wait state released (tk rel wai received in wait state)
Wait released by wait disabled state
Polling failed or timeout
Context error (issued from task-independent portion or in dispatch disabled state)[Description]
Sends the message at the address specified in msg to the message buffer specified in mbfid. The message
size is indicated in msgsz. This system call copies msgsz bytes starting from msg to the message queueof message buffer mbfid. The message queue is implemented as a ring buffer.
If msgsz is larger than the maxmsz specified with tk cre mbf, error code E PAR is returned.
If there is not enough available buffer space to accommodate message msg in the message queue, thetask issuing this system call goes to send wait state and is queued waiting for buffer space to become
available (send queue). Waiting tasks are queued in either FIFO or priority order, depending on theattribute made with tk cre mbf.
A maximum wait time (timeout) can be set in tmout. If the tmout time elapses before the wait releasecondition is met (before there is sufficient buffer space), the system call terminates, returning timeout
error code E TMOUT.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.5. EXTENDED SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

123

Only positive values can be set in tmout. The time base for tmout (time unit) is the same as that forsystem time (= 1 ms).
When TMO POL = 0 is set in tmout, this means 0 was specified as the timeout value, and E TMOUT is
returned without entering WAIT state if there is not enough buffer space.
When TMO FEVR = (−1) is set in tmout, this means infinity was specified as the timeout value, and thetask continues to wait for buffer space to become available, without timing out. A message of size 0
cannot be sent. When msgsz ≤ 0 is specified, error code E PAR is returned.
When this system call is invoked from a task-independent portion or in dispatch disabled state, error
code E CTX is returned; but in the case of tmout = TMO POL, there may be implementations where
execution from a task-independent portion or in dispatch disabled state is possible.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

124

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk rcv mbf
Receive Message from Message Buffer[C Language Interface]
INT msgsz = tk_rcv_mbf ( ID mbfid, VP msg, TMO tmout ) ;[Parameters]
ID
VP
TMO

mbfid
msg
tmout

Message buffer ID
Start address of receive message packet
timeout[Return Parameters]
INT

msgsz
or

Received message size
Error Code[Error Codes]
E OK
E ID
E NOEXSE PAR
E DLT
E RLWAIE DISWAIE TMOUTE CTXNormal completion
Invalid ID number (mbfid is invalid or cannot be used)
Object does not exist (the message buffer specified in mbfid does not exist)
Parameter error (value that cannot be used in msg, or tmout ≤ (−2))
The object being waited for was deleted (message buffer was deleted while waiting)Wait state released (tk rel wai received in wait state)
Wait released by wait disabled state
Polling failed or timeout
Context error (issued from task-independent portion or in dispatch disabled state)[Description]
Receives a message from the message buffer specified in mbfid, putting it in the location specified in
msg.
This system call copies the contents of the first queued message in the message buffer specified in mbfid,
and copies it to an area of msgsz bytes starting at address msg.
If no message has been sent to the message buffer specified in mbfid (the message queue is empty), thetask issuing this system call goes to WAIT state and is put in the receive queue of the message buffer
to wait for message arrival. Tasks in the receive queue are ordered by FIFO only.
A maximum wait time (timeout) can be set in tmout. If the tmout time elapses before the wait releasecondition is met (before a message arrives), the system call terminates, returning timeout error code
E TMOUT.
Only positive values can be set in tmout. The time base for tmout (time unit) is the same as that forsystem time (= 1 ms).

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.5. EXTENDED SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

125

When TMO POL = 0 is set in tmout, this means 0 was specified as the timeout value, and E TMOUT is
returned without entering WAIT state even if there is no message.
When TMO FEVR = (−1) is set in tmout, this means infinity was specified as the timeout value, and thetask continues to wait for message arrival without timing out.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

126

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk ref mbf
Get Message Buffer Status[C Language Interface]
ER ercd = tk_ref_mbf ( ID mbfid, T_RMBF *pk_rmbf ) ;[Parameters]ID
T RMBF*mbfid
pk rmbf

Message buffer ID
Address of packet for returning status information[Return Parameters]
ER

ercd

Error code

pk rmbf detail:
VP
ID
ID
INT
INT
INT

exinf
wtsk
stsk
msgsz
frbufsz
maxmszExtended information
Waiting task information
Send task information
Size of the next message to be received (in bytes)
Free buffer size (in bytes)
Maximum message size (in bytes)(Other implementation-dependent parameters may be added beyond this point.)[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (mbfid is invalid or cannot be used)
Object does not exist (the message buffer specified in mbfid does not exist)
Parameter error (the return parameter packet address cannot be used)[Description]
References the status of the message buffer specified in mbfid, passing in the return parameters sending
task information (stsk), the size of the next message to be received (msgsz), free buffer size (frbufsz),
maximum message size (maxmsz), waiting task information (wtsk), and extended information (exinf).
wtsk indicates the ID of a task waiting for receipt from the message buffer. The ID of a task waiting
to send to the message buffer is indicated in stsk. If multiple tasks are waiting in the message buffer
queues, the ID of the task at the head of the queue is returned. If no tasks are waiting, 0 is returned.
If the specified message buffer does not exist, error code E NOEXS is returned.
The size of the message at the head of the queue (the next message to be received) is returned in msgsz.
If there are no queued messages, msgsz = 0 is returned. A message of size 0 cannot be sent. At least oneof msgsz = 0 and wtsk = 0 is always true for this system call. frbufsz indicates the free space in thec 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.5. EXTENDED SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

127

ring buffer of which the message queue consists. This value indicates the approximate size of messages
than can be sent. maxmsz returns the maximum message size as specified with tk cre mbf.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

128

4.5.3

CHAPTER 4. T-KERNEL/OS FUNCTIONS

Rendezvous Port

Rendezvous is a function for synchronization and communication between tasks, supporting the procedures for making processing requests by one task to another and for returning the processing result tothe requesting task. The object for which both of these tasks wait is called a rendezvous port. The
rendezvous function is typically used to realize task communication in a client/server model, but canalso support more flexible synchronization and communication models.
Functions are provided for creating and deleting a rendezvous port, issuing a processing request to arendezvous port (call rendezvous), accepting a processing request from a rendezvous port (accept rendezvous), returning the processing result (reply rendezvous), forwarding an accepted processing request
to another rendezvous port (forward rendezvous to other port), and referencing rendezvous port status
and rendezvous status. A rendezvous port is identified by an ID number called a rendezvous port ID.
A task issuing a processing request to a rendezvous port (the client-side task) calls a rendezvous, specifying a message (called a call message) with information about the rendezvous port, the rendezvous
conditions, and the processing being requested. The task accepting a processing request on a rendezvous
port (the server-side task) accepts the rendezvous, specifying the rendezvous port and rendezvous conditions.
The rendezvous conditions are indicated in a bit pattern. If the bitwise logical AND of the bit patterns
on both sides (the rendezvous conditions bit pattern of the task calling a rendezvous for a rendezvous
port and the rendezvous conditions bit pattern of the accepting task) is not 0, the rendezvous is established. The state of the task calling the rendezvous is WAIT on rendezvous call until the rendezvous isestablished. The state of the task accepting a rendezvous is WAIT on rendezvous acceptance until therendezvous is established.
When a rendezvous is established, a call message is passed from the task that called the rendezvous to
the accepting task. The state of the task calling the rendezvous goes to WAIT for rendezvous completion
until the requested processing is completed. The task accepting the rendezvous is released from WAIT
state and it performs the requested processing. Upon completion of the requested processing, the task
accepting the rendezvous passes the result of the processing in a reply message to the calling task andends the rendezvous. At this point the WAIT state of the task that called the rendezvous is released.
A rendezvous port has separate queues for tasks waiting on rendezvous call (call queue) and tasks waiting
on rendezvous acceptance (accept queue). Note, however, that after a rendezvous is established, bothtasks that formed the rendezvous are detached from the rendezvous port. In other words, a rendezvous
port does not have a queue for tasks waiting for rendezvous completion. Nor does it keep information
about the task performing the requested processing.
T-Kernel assigns an object number to identify each rendezvous when more than one is established at thesame time. The rendezvous object number is called the rendezvous number. The method of assigning
rendezvous numbers is implementation-dependent, but at a minimum information must be included forspecifying the task that called the rendezvous. Numbers must also be uniquely assigned to the extent
possible; for example, even if the same task makes multiple rendezvous calls, the first rendezvous andsecond rendezvous must have different rendezvous numbers assigned.
[Additional Notes]
Rendezvous is a synchronization and communication function introduced in the ADA programming
language, based on Communicating Sequential Processes (CSP). In ADA, however, the rendezvous
function is part of the language specification and therefore has a different role than in T-Kernel, which isa real-time kernel specification. The rendezvous ports provided by the real-time kernel are OS primitives
by which an ADA rendezvous capability is implemented. Since the ADA rendezvous function differsfrom that in the T-Kernel specification in a number of ways, the T-Kernel-specification rendezvous
functions cannot necessarily be used to implement the ADA rendezvous.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.5. EXTENDED SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

129

Rendezvous operation is explained here using the example in Figure 4.5. In this figure Task A and Task
B are running asynchronously.
• If Task A first calls tk cal por, Task A goes to WAIT state until Task B calls tk acp por. The
state of Task A at this time is WAIT on rendezvous call (a).
• If, on the other hand, Task B first calls tk acp por, Task B goes to WAIT state until Task A calls
tk cal por. The stat of Task B at this time is WAIT on rendezvous acceptance (b).
• A rendezvous is established when both Task A has called tk cal por and Task B has calledtk acp por. At this time Task A remains in WAIT state while the WAIT state of Task B isreleased. The state of Task A is WAIT for rendezvous completion.
• The Task A WAIT state is released when Task B calls tk rpl rdv. Thereafter both tasks enter arun state.
TASK ATASK BTASK Atk cal por

TASK Btk acp por

wait on call
- tk acp por

wait on acceptancetk cal por

wait on completion

wait on completion¾¾

tk rpl rdv(a) tk cal por called firsttk rpl rdv(b) tk acp por called first

Figure 4.5: Rendezvous Operation
As an example of a specific method for assigning rendezvous object numbers, the ID number of the task
calling the rendezvous can go in the low bits of the rendezvous number, with the high bits used for asequential number.
[Rationale for the Specification]
While it is true that the rendezvous functionality can be achieved through a combination of othersynchronization and communication functions, better efficiency and ease of programming are achievedby having a dedicated function for cases where the communication involves an acknowledgment. One
advantage of the rendezvous function is that since both tasks wait until message passing is completed,no memory space needs to be allocated for storing messages.
The reason for assigning unique rendezvous numbers even when the same task does the calling is asfollows. It is possible that a task, after establishing a rendezvous and going to WAIT state for its
completion, will have its WAIT state released due to timeout or forcible release by another task, thenagain call a rendezvous and have that rendezvous established. If the same number were assigned to boththe first and second rendezvous, attempting to terminate the first rendezvous would end up terminating
the second rendezvous. If separate numbers are assigned to the two rendezvous and the task in WAIT
state for rendezvous completion is made to remember the number of the rendezvous for which it iswaiting, error will be returned when the attempt is made to terminate the first rendezvous.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

130

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk cre por
Create Port for Rendezvous[C Language Interface]
ID porid = tk_cre_por ( T_CPOR *pk_cpor ) ;[Parameters]
T CPOR*

pk cporInformation about the rendezvous port to be createdpk cpor detail:
VP
ATR
INT
INT
UB

exinf
poratrmaxcmsz
maxrmsz
dsname[8]Extended information
Rendezvous port attributes
Maximum call message size (in bytes)
Maximum reply message size (in bytes)
DS object name

(Other implementation-dependent parameters may be added beyond this point.)[Return Parameters]
ID

porid
or

Port ID
Error Code[Error Codes]
E OK
E NOMEM
E LIMITE RSATR
E PAR

Normal completion
Insufficient memory (memory for control block cannot be allocated)
Number of rendezvous ports exceeds the system limit
Reserved attribute (poratr is invalid or cannot be used)
Parameter error (pk cpor is invalid; maxcmsz or maxrmsz is negative or invalid)[Description]
Creates a rendezvous port, assigning to it a rendezvous port ID number.
This specification allocates a control block to the created rendezvous port. A rendezvous port is anobject used as an OS primitive for implementing a rendezvous capability.
exinf can be used freely by the user to set miscellaneous information about the created rendezvous
port. The information set in this parameter can be referenced by tk ref por. If a larger area is needed
for indicating user information, or if the information may need to be changed after the rendezvous port
is created, this can be done by allocating separate memory for this purpose and putting the memory
packet address in exinf. The OS pays no attention to the contents of exinf.
poratr indicates system attributes in its low bits and implementation-dependent information in the highbits. The system attributes part of poratr is as follows.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.5. EXTENDED SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

131

poratr:= (TA_TFIFO || TA_TPRI) | [TA_DSNAME] | [TA_NODISWAI]TA TFIFO
TA TPRITA DSNAMETA NODISWAI

Tasks waiting on call are queued in FIFO order
Tasks waiting on call are queued in priority orderSpecifies DS object name
Wait disabling by tk dis wai is prohibited

TA TFIFO and TA TPRI attributes specify the queuing order of tasks waiting on a rendezvous call. Tasks
waiting on rendezvous acceptance are queued in FIFO order only.
When TA DSNAME is specified, dsname is valid and specifies the DS object name. DS object name isused to identify objects by debugger, and it is handled only by T-Kernel/DS API, td ref dsname andtd set dsname. For more details refer to td ref dsname and td set dsname. If TA DSNAME is not
specified, dsname is ignored. Then td ref dsname and td set dsname return E OBJ error.
#define TA_TFIFO
0x00000000#define TA_TPRI
0x00000001#define TA_DSNAME
0x00000040#define TA_NODISWAI 0x00000080

c 2002–2005 by T-Engine Forum
Copyright °/* manage task queue by FIFO*//* manage task queue by priority *//* DS object name*//* reject wait disabling*/

TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

132

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk del por
Delete Port for Rendezvous[C Language Interface]
ER ercd = tk_del_por ( ID porid ) ;[Parameters]
ID

porid

Rendezvous port ID[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS

Normal completion
Invalid ID number (porid is invalid or cannot be used)
Object does not exist (the rendezvous port specified in porid does not exist)[Description]
Deletes the rendezvous port specified in porid.
Issuing this system call releases the ID number and control block space allocated to the rendezvous port.
This system call completes normally even if there are tasks waiting on rendezvous acceptance (tk acp por)or rendezvous port call (tk cal por) at the specified rendezvous port, but error code E DLT is returnedto the tasks in WAIT state.
Deletion of a rendezvous port by tk del por does not affect tasks for which rendezvous is alreadyestablished. In this case, nothing is reported to the task accepting the rendezvous (not in WAIT state),and the state of the task calling the rendezvous (WAIT for rendezvous completion) remains unchanged.
When the task accepting the rendezvous issues tk rpl rdv, that system call will execute normally even
if the port on which the rendezvous was established has been deleted.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.5. EXTENDED SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

133

tk cal por
Call Port for Rendezvous[C Language Interface]
INT rmsgsz = tk_cal_por ( ID porid, UINT calptn, VP msg, INT cmsgsz, TMO tmout ) ;[Parameters]
ID
UINT
VP
INT
TMO

porid
calptnmsg
cmsgsztmout

Rendezvous port ID
Call bit pattern (indicating conditions of the caller)
Message packet address
Call message size (in bytes)
timeout[Return Parameters]
INT

rmsgszor

Reply message size (in bytes)
Error Code[Error Codes]
E OK
E ID
E NOEXSE PAR
E DLT
E RLWAIE DISWAIE TMOUTE CTXNormal completion
Invalid ID number (porid is invalid or cannot be used)
Object does not exist (the rendezvous port specified in porid does not exist)
Parameter error ( cmsgsz < 0, cmsgsz > maxcmsz, calptn = 0, value that cannot be
used in msg, tmout ≤ (−2) )The object being waited for was deleted (the rendezvous port was deleted while waiting)Wait state released (tk rel wai received in wait state)
Wait released by wait disabled state
Polling failed or timeout
Context error (issued from task-independent portion or in dispatch disabled state)[Description]
Issues a rendezvous call for a rendezvous port.
The specific operation of tk cal por is as follows. A rendezvous is established if there is a task waiting
to accept a rendezvous at the port specified in porid and rendezvous conditions between that task
and the task issuing this call overlap. In this case, the task waiting to accept the rendezvous enters
READY state while the state of the task issuing tk cal por is WAIT for rendezvous completion. The
task waiting for rendezvous completion is released from WAIT state when the other (accepting) task
executes tk rpl rdv. The tk cal por system call completes at this time.
If there is no task waiting to accept a rendezvous at the port specified in porid, or if there is a task but
conditions for establishing a rendezvous are not satisfied, the task issuing tk cal por is placed at thec 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

134

CHAPTER 4. T-KERNEL/OS FUNCTIONS

end of the call queue of that port and enters WAIT state on rendezvous call. The order of tasks in thecall queue is either FIFO or priority order, depending on the attribute made when calling tk cre por.
The decision on rendezvous establishment is made by checking conditions in the bit patterns acpptn of
the accepting task and calptn of the calling task. A rendezvous is established if the bitwise logical ANDof these two bit patterns is not 0. Parameter error E PAR is returned if calptn is 0, since no rendezvous
can be established in that case.
When a rendezvous is established, the calling task can send a message (a call message) to the accepting
task. The size of the call message is specified in cmsgsz. In this operation cmsgsz bytes startingat address msg as specified by the calling task when calling tk cal por are copied to address msg as
specified by the accepting task when calling tk acp por.
Similarly, when the rendezvous completes, the accepting task may send a message (reply message) tothe calling task. In this operation, the contents of a reply message specified by the accepting task whencalling tk rpl rdv are copied to address msg as specified by the calling task when calling tk cal por.
The size of the reply message rmsgsz is set in a tk cal por return parameter. The original contents ofthe message area passed in msg by tk cal por end up being overwritten by the reply message received
when tk rpl rdv executes.
Note that it is possible message contents will be destroyed when a rendezvous is forwarded, since an area
no larger than maxrmsz starting from the address msg as specified with tk cal por is used as a buffer.
It is therefore necessary to reserve a memory space of at least maxrmsz starting from msg, regardless ofthe expected size of the reply message, whenever there is any possibility that a rendezvous requested bytk cal por might be forwarded (See the description of tk fwd por for details).
Error code E PAR is returned when cmsgsz exceeds the size maxcmsz specified with tk cre por. Thiserror checking is made before a task enters WAIT state on rendezvous call; and if error is detected, thetask executing tk cal por does not enter WAIT state.
A maximum wait time (timeout) can be set in tmout. If the tmout time elapses before the wait releasecondition is met (rendezvous is not established), the system call terminates, returning timeout error
code E TMOUT.
Only positive values can be set in tmout. The time base for tmout (time unit) is the same as that forsystem time (= 1 ms).
When TMO POL = 0 is set in tmout, this means 0 was specified as the timeout value, and E TMOUT is
returned without entering WAIT state if there is no task waiting on a rendezvous at the rendezvous port,
or if the rendezvous conditions are not met. When TMO FEVR = (−1) is set in tmout, this means infinity
was specified as the timeout value, and the task continues to wait for a rendezvous to be establishedwithout timing out. In any case, tmout indicates the time allowed for a rendezvous to be established,
and does not apply to the time from rendezvous establishment to rendezvous completion.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.5. EXTENDED SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

135

tk acp por
Accept Port for Rendezvous[C Language Interface]
INT cmsgsz = tk_acp_por ( ID porid, UINT acpptn, RNO *p_rdvno, VP msg, TMO tmout ) ;[Parameters]
ID
UINT
VP
TMO

porid
acpptnmsg
tmout

Rendezvous port ID
Accept bit pattern (indicating conditions for acceptance)
Message packet address
timeout[Return Parameters]
ER
RNO
INT

ercd
rdvno
cmsgszError code
Rendezvous number
Call message size (in bytes)[Error Codes]
E OK
E ID
E NOEXSE PAR
E DLT
E RLWAIE DISWAIE TMOUTE CTXNormal completion
Invalid ID number (porid is invalid or cannot be used, or porid is a rendezvous port ofanother node)
Object does not exist (the rendezvous port specified in porid does not exist)
Parameter error (acpptn = 0, value that cannot be used in msg, or tmout ≤ (−2))
The object being waited for was deleted (the rendezvous port was deleted while waiting)Wait state released (tk rel wai received in wait state)
Wait released by wait disabled state
Polling failed or timeout
Context error (issued from task-independent portion or in dispatch disabled state)[Description]
Accepts a rendezvous on a rendezvous port.
The specific operation of tk acp por is as follows. A rendezvous is established if there is a task queued
for a rendezvous call at the port specified in porid and if rendezvous conditions of that task and thetask issuing this call overlap. In this case, the task queued for a rendezvous call is removed from thequeue, and its state changes from WAIT on rendezvous call to WAIT for rendezvous completion. The
task issuing tk acp por continues executing.
If there is no task waiting to call a rendezvous at the port specified in porid, or if there is a task
but conditions for establishing a rendezvous are not satisfied, the task issuing tk acp por will enter
WAIT state on rendezvous acceptance for that port. No error results if there is already another task
in WAIT state on rendezvous acceptance at this time; the task issuing tk acp por is placed in thec 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

136

CHAPTER 4. T-KERNEL/OS FUNCTIONS

accept queue. It is possible to conduct multiple rendezvous operations on the same port at the sametime. Accordingly, no error results even if the next rendezvous is carried out while another task is still
conducting a rendezvous (before tk rpl rdv is called for a previously established rendezvous) at theport specified in porid.
The decision on rendezvous establishment is made by checking conditions in the bit patterns acpptn of
the accepting task and calptn of the calling task. A rendezvous is established if the bitwise logical ANDof these two bit patterns is not 0. If the first task does not satisfy these conditions, each subsequenttask in the call queue is checked in succession. If calptn and acpptn are assigned the same non-zerovalue, rendezvous is established unconditionally. Parameter error E PAR is returned if acpptn is 0, sinceno rendezvous can be established in that case. All processing before a rendezvous is established is fully
symmetrical on the calling and accepting ends.
When a rendezvous is established, the calling task can send a message (a call message) to the accepting
task. The contents of the message specified by the calling task are copied to an area starting from msg
specified by the accepting task when tk acp por is called. The call message size cmsgsz is passed in a
return parameter of tk acp por.
A task accepting rendezvous can establish more than one rendezvous at a time. That is, a task that has
accepted one rendezvous using tk acp por may execute tk acp por again before executing tk rpl rdv
on the first rendezvous. The port specified for the second tk acp por call at this time may be thesame port as the first rendezvous or a different one. It is even possible for a task already conducting
a rendezvous on a given port to execute tk acp por again on the same port and conduct multiple
rendezvous on the same port at the same time. Of course, the calling tasks will be different in each case.
The return parameter rdvno passed by tk acp por is information used to distinguish different rendezvous when more than one has been established at a given time. It is used as a return parameterby tk rpl rdv when a rendezvous completes. It is also passed as a parameter to tk fwd por when
forwarding a rendezvous. Although the exact contents of rdvno are implementation-dependent, it isexpected to include information specifying the calling task on the other end of the rendezvous.
A maximum wait time (timeout) can be set in tmout. If the tmout time elapses before the wait releasecondition is met (rendezvous is not established), the system call terminates, returning timeout error
code E TMOUT.
Only positive values can be set in tmout. The time base for tmout (time unit) is the same as that forsystem time (= 1 ms).
When TMO POL = 0 is set in tmout, this means 0 was specified as the timeout value, and E TMOUT is
returned without entering WAIT state if there is no task waiting for a rendezvous call at the rendezvous
port, or if the rendezvous conditions are not met.
When TMO FEVR = (−1) is set in tmout, this means infinity was specified as the timeout value, and thetask continues to wait for a rendezvous to be established without timing out.
selectwhen condition_A
accept entry_A do ... end;orwhen condition_B
accept entry_B do ... end;orwhen condition_C
accept entry_C do ... end;
end select;Figure 4.6: Sample ADA-like Program Using select Statementc 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.5. EXTENDED SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

137[Additional Notes]
The ability to queue tasks accepting rendezvous is useful when multiple servers perform the sameprocessing concurrently. This capability also takes advantage of the task-independent nature of ports.
If a task accepting a rendezvous terminates abnormally for some reason before completing its rendezvous(before issuing tk rpl rdv), the task calling for the rendezvous by issuing tk cal por will continue
waiting indefinitely for rendezvous completion without being released. To avoid such a situation, tasks
accepting rendezvous should execute a tk rpl rdv or tk rel wai call when they terminate abnormally,
as well as notifying the task calling for the rendezvous that the rendezvous ended in error.
rdvno contains information specifying the calling task in the rendezvous, but unique numbers should
be assigned to the extent possible. Even if different rendezvous are conducted between the same tasks,
a different rdvno value should be assigned to the first and second rendezvous to avoid problems like thefollowing.
• Rather than entry A, entry B, and entry C each corresponding to one rendezvous port, the entire selectstatement corresponds to one rendezvous port.
• entry A, entry B, and entry C correspond to calptn and acpptn bits 2^0, 2^1, and 2^2.
• A select statement in a typical ADA program looks like the following.
ptn := 0;
if condition_A then ptn := ptn + 2^0 endif;
if condition_B then ptn := ptn + 2^1 endif;
if condition_C then ptn := ptn + 2^2 endif;
tk_acp_por(acpptn := ptn);• If the program contains in addition to the select statement a simple entry A accept with no select,
tk_acp_por(acpptn := 2^0);can be executed. If it is desired to have entry A, entry B, and entry C wait unconditionally by OR logic,
tk_acp_por(acpptn := 2^2+2^1+2^0);can be executed.
• If the call on the rendezvous calling side is for entry A,
tk_cal_por(calptn := 2^0);can be executed; and if the call is for entry C,
tk_cal_por(calptn := 2^2);
can be executed.

Figure 4.7: Using Rendezvous to Implement ADA select Function
If a task that called tk cal por and is waiting for rendezvous completion has its WAIT state releasedby tk rel wai or by tk ter tsk + tk sta tsk or the like, conceivably it may execute tk cal por asecond time, resulting in establishment of a rendezvous. If the same rdvno value is assigned to the first
rendezvous and the subsequent one, then if tk rpl rdv is executed for the first rendezvous it will end up
terminating the second one. By assigning rdvno numbers uniquely and having the task in WAIT state
for rendezvous completion remember the number of the expected rdvno, it will be possible to detect theerror when tk rpl rdv is called for the first rendezvous.
One possible method of assigning rdvno numbers is to put the ID number of the task calling therendezvous in the low bits of rdvno, using the high bits for a sequential number.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

138

CHAPTER 4. T-KERNEL/OS FUNCTIONS

The capability of setting rendezvous conditions in calptn and acpptn can be applied to implement a
rendezvous selective acceptance function like the ADA select function. A specific processing approachequivalent to an ADA select statement (Figure 4.6) is shown in Figure 4.7.
The ADA select function is provided only on the accepting end, but it is also possible to implement a
select function on the calling end by specifying multiple bits in calptn.
[Rationale for the Specification]
The reason for specifying separate system calls tk cal por and tk acp por even though the conditions
for establishing a rendezvous mirror each other on the calling and accepting sides is because processing
required after a rendezvous is established differs for the tasks on each side. That is, whereas the callingtask enters WAIT state after the rendezvous is established, the accepting task enters READY state.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.5. EXTENDED SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

139

tk fwd por
Forward Rendezvous to Other Port[C Language Interface]
ER ercd = tk_fwd_por ( ID porid, UINT calptn, RNO rdvno, VP msg, INT cmsgsz ) ;[Parameters]
ID
UINT
RNO
VP
INT

porid
calptnrdvno
msg
cmsgszRendezvous port ID
Call bit pattern (indicating conditions of the caller)
Rendezvous number before forwarding
Message packet address
Call message size (in bytes)[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS
E PAR
E OBJ
E CTX
E DISWAI

Normal completion
Invalid ID number (porid is invalid or cannot be used, or porid is a rendezvous port ofanother node)
Object does not exist (the rendezvous port specified in porid does not exist)
Parameter error (cmsgsz < 0, cmsgsz > maxcmsz after forwarding, cmsgsz > maxrmsz
before forwarding, calptn = 0, or value that cannot be used in msg)
Invalid object state (rdvno is invalid, or maxrmsz (after forwarding) > maxrmsz (before
forwarding))
Context error (issued from task-independent portion (implementation-dependent error))
Wait released by wait disabled state[Description]
Forward an accepted rendezvous to another rendezvous port.
The task issuing this system call (here “Task X”) must have accepted the rendezvous specified in porid;i.e., this system call can be issued only after executing tk acp por. In the discussion that follows,
the rendezvous calling task is “Task Y”, and the rendezvous number passed in a return parameter by
tk acp por is rdvno. After tk fwd por is issued in this situation, the rendezvous between Task X andTask Y is released, and all processing thereafter is the same as if Task Y had called for a rendezvous on
another port (rendezvous port B) passed to this system call in porid.
The specific operations of tk fwd por are as follows.
1. The rendezvous specified in rdvno is released.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

140

CHAPTER 4. T-KERNEL/OS FUNCTIONS

2. Task Y goes to WAIT state on rendezvous call for the rendezvous port specified in porid. The
bit conditions representing the call select conditions in this case are not those given in the calptn
specified by Task Y when it called tk cal por, but those in the calptn specified by Task X when
it called tk fwd por. The state of Task Y goes from WAIT for rendezvous completion back to
WAIT on rendezvous call.
3. Then if a rendezvous for the rendezvous port specified in porid is accepted, a rendezvous isestablished between the accepting task and Task Y. Naturally, if there is a task already waiting
to accept a rendezvous on the rendezvous port specified in porid and the rendezvous conditions
are met, executing tk fwd por will immediately cause a rendezvous to be established.
Here too, as with calptn, the message sent to the accepting task when the rendezvous is establishedis that specified in tk fwd por by Task X, not that specified in tk cal por by Task Y.
4. After the new rendezvous has completed, the reply message returned to the calling task by
tk rpl rdv is copied to the area specified in the msg parameter passed to tk cal por by Task Y,
not to the area specified in the msg parameter passed to tk fwd por by Task X.
Essentially the following situation:
Executing tk fwd por (porid=portB, calptn=ptnB, msg=mesB)
after tk cal por (porid=portA, calptn=ptnA, msg=mesA)
is the same as the following:
Executing tk cal por (porid=portB, calptn=ptnB, msg=mesB).
Note that it is not necessary to log the history of rendezvous forwarding.
If tk ref tsk is executed for a task that has returned to WAIT on rendezvous call due to tk fwd por
execution, the value returned in tskwait is TTW CAL. Here wid is the ID of the rendezvous port to which
the rendezvous was forwarded.
tk fwd por execution completes immediately; in no case does this system call go to a WAIT state. A task
issuing tk fwd por loses any relationship to the rendezvous port on which the forwarded rendezvous
was established, the forwarding destination (the port specified in porid), and the tasks conducting
rendezvous on these ports.
Error code E PAR is returned if cmsgsz is larger than maxcmsz of the rendezvous port after forwarding.
This error is checked before the rendezvous is forwarded. If this error occurs, the rendezvous is not
forwarded and the rendezvous specified in rdvno is not released.
The send message specified with tk fwd por is copied to another memory space (such as the message
area specified with tk cal por) when tk fwd por is executed. Accordingly, even if the contents of themessage area specified in the msg parameter passed to tk fwd por are changed before the forwarded
rendezvous is established, the forwarded rendezvous will not be affected.
When a rendezvous is forwarded by tk fwd por, maxrmsz of the rendezvous port after forwarding (specified in porid) must be no larger than maxrmsz of the rendezvous port on which the rendezvous wasestablished before forwarding. If maxrmsz of the rendezvous port after forwarding is larger than maxrmsz
of the rendezvous port before forwarding, this means the destination rendezvous port was not suitable,
and error code E OBJ is returned. The task calling the rendezvous readies a reply message receiving
area based on the maxrmsz of the rendezvous port before forwarding. If the maximum size for the reply
message increases when the rendezvous is forwarded, this may indicate that an unexpectedly large reply
message is being returned to the calling rendezvous port, which would cause problems. For this reason
a rendezvous cannot be forwarded to a rendezvous port having a larger maxrmsz.
Similarly, cmsgsz indicating the size of the message sent by tk fwd por must be no larger than maxrmsz
of the rendezvous port on which the rendezvous was established before forwarding. This is because it
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.5. EXTENDED SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

141

is assumed that the message area specified with tk cal por will be used as a buffer in implementing
tk fwd por. If cmsgsz is larger than maxrmsz of the rendezvous port before forwarding, error code
E PAR is returned(See Additional Note for details).
It is not necessary to issue tk fwd por and tk rpl rdv from a task-independent portion, but it is possible
to issue these system calls from dispatch disabled or interrupts disabled state. This capability can beused to perform processing that is inseparable from tk fwd por or tk rpl rdv. Whether or not error
checking is made for issuing of these system calls from a task-independent portion is implementationdependent.
When as a result of tk fwd por Task Y that was in WAIT state for rendezvous completion reverts to
WAIT on rendezvous call, the timeout until rendezvous establishment is always treated as Wait forever(TMO FEVR).
The rendezvous port being forwarded to may be the same port used for the previous rendezvous (therendezvous port on which the rendezvous specified in rdvno was established). In this case, tk fwd por
cancels the previously accepted rendezvous. Even in this case, however, the call message and calptn
parameters are changed to those passed to tk fwd por by the accepting task, not those passed totk cal por by the calling task.
It is possible to forward a rendezvous that has already been forwarded.
[Additional Notes]
A server task operation using tk fwd por is illustrated in Figure 4.8.
Generally tk fwd por is executed by server distribution tasks (tasks for distributing server-accepted
processing to other tasks) as shown in Figure 4.8. Accordingly, a server distribution task that has
executed tk fwd por must go on to processing for acceptance of the next request regardless of whether
the forwarded rendezvous is established or not. The tk fwd por message area in this case is used forprocessing the next request, making it necessary to ensure that changes to the contents of this message
area will not affect the previously forwarded rendezvous. For this reason, after tk fwd por is executed,
it must be possible to modify the contents of the message area indicated in msg passed to tk fwd poreven before the forwarded rendezvous is established.
In order to fulfill this requirement, in implementation it is allowed to use the message area specified withtk cal por as a buffer. That is, in the tk fwd por processing, it is permissible to copy the call messages
specified with tk fwd por to the message area indicated in msg when tk cal por was called, and for thetask calling tk fwd por to change the contents of the message area. When a rendezvous is established,
the message placed in the tk cal por message area is passed to the accepting task, regardless of whether
the rendezvous is one that was forwarded from another port.
The following specifications are made to allow this sort of implementation to be used.
• If there is a possibility that a rendezvous requested by tk cal por may be forwarded, a memory
space of at least maxrmsz bytes must be allocated starting from msg (passed to tk cal por),regardless of the expected reply message size.
• The send message size cmsgsz passed to tk fwd por must be no larger than maxrmsz of therendezvous port before forwarding.
• If a rendezvous is forwarded using tk fwd por, maxrmsz of the destination port rendezvous mustnot be larger than maxrmsz of the port before forwarding.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

142

CHAPTER 4. T-KERNEL/OS FUNCTIONS

Requesting Task X

Extended SVC¾??? ???

tk cal por

SVC
acceptport?

tk acp por

Server distribution tasks

Preprocessing?

?

?

Process
B serverport

Process
C serverport

tk fwd por tk fwd por tk fwd por -?
WAIT onrendezvous
call or forcompletion

Process
A serverport

tk acp por tk acp por tk acp por

6

?

6

6

?

?

Process A
Server
Task

Process B
Server
Task

Process C
Server
Task

?

?

?

tk rpl rdv tk rpl rdv tk rpl rdv¾• Bold outlines indicate rendezvous ports (rendezvous entries)• While it is possible to use tk cal por in place of tk fwd por, this results in rendezvous nesting. Assuming
it is acceptable for requesting Task X to resume execution after the processing of server tasks A to C iscompleted, use of tk fwd por does away with the need for rendezvous nesting and results in more efficient
operations.

Figure 4.8: Server Task Operation Using tk fwd por[Rationale for the Specification]
The tk fwd por specification is designed not to require logging a history of rendezvous forwarding, so
as to reduce the number of states that must be kept track of in the system as a whole. Applications
that require such a log to be kept can use nested pairs of tk cal por and tk acp por rather than using
tk fwd por.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.5. EXTENDED SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

143

tk rpl rdv
Reply Rendezvous[C Language Interface]
ER ercd = tk_rpl_rdv ( RNO rdvno, VP msg, INT rmsgsz ) ;[Parameters]
RNO
VP
INT

rdvno
msg
rmsgszRendezvous number
Reply message packet address
Reply message size (in bytes)[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E PAR
E OBJ
E CTX

Normal completion
Parameter error (rmsgsz < 0, rmsgsz > maxrmsz, or value that cannot be used in msg)
Invalid object state (rdvno is invalid)Context error (issued from task-independent portion (implementation-dependent error))[Description]
Returns a reply to the calling task in the rendezvous, ending the rendezvous.
The task issuing this system call (here “Task X”) must be engaged in a rendezvous; that is, this systemcall can be issued only after executing tk acp por. In the discussion that follows, the rendezvous callingtask is “Task Y”, and the rendezvous number passed in a return parameter by tk acp por is rdvno.
When tk rpl rdv is executed in this situation, the rendezvous state between Task X and Task Y isreleased, and the Task Y state goes from WAIT for rendezvous completion back to READY state.
When a rendezvous is ended by tk rpl rdv, accepting Task X can send a reply message to calling Task
Y. The contents of the message specified by the accepting task are copied to the memory space specified
in msg passed by Task Y to tk cal por. The size of the reply message rmsgsz is passed as a tk cal por
return parameter.
Error code E PAR is returned if rmsgsz is larger than maxrmsz specified with tk cre por. When thiserror is detected, the rendezvous is not ended and the task that called tk cal por remains in WAIT
state for rendezvous completion.
It is not necessary to issue tk fwd por and tk rpl rdv from a task-independent portion, but it is possible
to issue these system calls from dispatch disabled or interrupts disabled state. This capability can beused to perform processing that is inseparable from tk fwd por or tk rpl rdv. Whether or not error
checking is made for issuing of these system calls from a task-independent portion is implementationdependent.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

144

CHAPTER 4. T-KERNEL/OS FUNCTIONS[Additional Notes]
If a task calling a rendezvous aborts for some reason before completion of the rendezvous (before
tk rpl rdv is executed), the accepting task has no direct way of knowing of the abort. In such acase, error code E OBJ is returned to the rendezvous accepting task when it executes tk rpl rdv.
After a rendezvous is established, tasks are in principle detached from the rendezvous port and haveno need to reference information about each other. However, since the value of maxrmsz, used whenchecking the length of the reply message sent using tk rpl rdv, is dependent on the rendezvous port,
the task in rendezvous must record this information somewhere. One possible implementation would beto put this information in the TCB of the calling task after it goes to WAIT state, or in another areathat can be referenced from the TCB, such as a stack area.
[Rationale for the Specification]
The parameter rdvno is passed to tk rpl rdv and tk fwd por as information for distinguishing one
established rendezvous from another, but the rendezvous port ID (porid) used when establishing arendezvous is not specified. This is based on the design principle that tasks are no longer related torendezvous ports after a rendezvous has been established.
Error code E OBJ rather than E PAR is returned for an invalid rdvno. This is because rdvno itself is anobject indicating the task that called the rendezvous.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.5. EXTENDED SYNCHRONIZATION AND COMMUNICATION FUNCTIONS

145

tk ref por
Reference Port Status[C Language Interface]
ER ercd = tk_ref_por ( ID porid, T_RPOR *pk_rpor ) ;[Parameters]
ID
T RPOR*porid
pk rporRendezvous port ID
Start address of packet for returning status information[Return Parameters]
ER

ercd

Error codepk rpor detail:
VP
ID
ID
INT
INT

exinf
wtsk
atsk
maxcmsz
maxrmsz

Extended information
Waiting task information
Accept task information
Maximum call message size (in bytes)
Maximum reply message size (in bytes)(Other implementation-dependent parameters may be added beyond this point.)[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (porid is invalid or cannot be used)
Object does not exist (the rendezvous port specified in porid does not exist)
Parameter error (the return parameter packet address cannot be used)[Description]
References the status of the rendezvous port specified in porid, passing in return parameters information
about the accepting task (atsk), information about a task waiting on a rendezvous call (wtsk), maximum
message sizes (maxcmsz, maxrmsz), and extended information (exinf).
wtsk indicates the ID of a task in WAIT state on rendezvous call at the rendezvous port. If there is notask waiting on rendezvous call, wtsk = 0 is returned. atsk indicates the ID of a task in WAIT state
on rendezvous acceptance at the rendezvous port. If there is no task waiting for rendezvous acceptance,
atsk = 0 is returned. If there are multiple tasks waiting on rendezvous call or acceptance at thisrendezvous port, the ID of the task at the head of the call queue and accept queue is returned.
If the specified rendezvous port does not exist, error code E NOEXS is returned.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

146

CHAPTER 4. T-KERNEL/OS FUNCTIONS[Additional Notes]
This system call cannot be used to get information about tasks involved in a currently establishedrendezvous.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.6. MEMORY POOL MANAGEMENT FUNCTIONS

4.6

147

Memory Pool Management Functions

Memory pool management functions provide software-based management of memory pools and memory
block allocation.
There are fixed-size memory pools and variable-size memory pools, which are considered separate objects
and require separate sets of system calls for their operation. Memory blocks allocated from a fixed-size
memory pool are all of one fixed size, whereas memory blocks from a variable-size memory pool can beof various sizes.
The memory managed by the memory pool management functions is all in system space; there is no
T-Kernel function for managing task space memory.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

148

4.6.1

CHAPTER 4. T-KERNEL/OS FUNCTIONSFixed-size Memory Pool

A fixed-size memory pool is an object used for dynamic management of fixed-size memory blocks.
Functions are provided for creating and deleting a fixed-size memory pool, getting and returning memory
blocks in a fixed-size memory pool, and referencing the status of a fixed-size memory pool. A fixed-size
memory pool is an object identified by an ID number called a fixed-size memory pool ID.
A fixed-size memory pool has a memory space used as the fixed-size memory pool (called a fixedsize memory pool area or simply memory pool area), and a queue for tasks waiting for memory block
allocation. A task wanting to allocate a memory block from a fixed-size memory pool that lacks sufficientavailable memory space goes to WAIT state for fixed-size memory block until memory blocks are returnedto the pool. A task in this state is put in the task queue of the fixed-size memory pool.
[Additional Notes]
When memory blocks of various sizes are needed from fixed-size memory pools, it is necessary to provide
multiple memory pools of different sizes.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.6. MEMORY POOL MANAGEMENT FUNCTIONS

149

tk cre mpf
Create Fixed-size Memory Pool[C Language Interface]
ID mpfid = tk_cre_mpf ( T_CMPF *pk_cmpf ) ;[Parameters]
T CMPF*pk cmpf

Information about the memory pool to be createdpk cmpf detail:
VP
ATR
INT
INT
UB

exinf
mpfatr
mpfcntblfsz
dsname[8]Extended information
Memory pool attributes
Memory pool block countMemory block size (in bytes)
DS object name

(Other implementation-dependent parameters may be added beyond this point.)[Return Parameters]
ID

mpfid
or

Fixed-size memory pool ID
Error Code[Error Codes]
E OK
E NOMEM
E LIMITE RSATR
E PAR

Normal completion
Insufficient memory (memory for control block or memory pool area cannot be allocated)
Number of fixed-size memory pools exceeds the system limit
Reserved attribute (mpfatr is invalid or cannot be used)
Parameter error (pk cmpf is invalid; mpfsz or blfsz is negative or invalid)[Description]
Creates a fixed-size memory pool, assigning to it a fixed-size memory pool ID.
This system call allocates a memory space for use as a memory pool based on the information specifiedin parameters mpfcnt and blfsz, and assigns a control block to the memory pool. A memory block ofsize blfsz can be allocated from the created memory pool by calling the tk get mpf system call.
exinf can be used freely by the user to set miscellaneous information about the created memory pool.
The information set in this parameter can be referenced by tk ref mpf. If a larger area is needed
for indicating user information, or if the information may need to be changed after the memory poolis created, this can be done by allocating separate memory for this purpose and putting the memory
packet address in exinf. The OS pays no attention to the contents of exinf.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

150

CHAPTER 4. T-KERNEL/OS FUNCTIONS

mpfatr indicates system attributes in its low bits and implementation-dependent information in thehigh bits. The system attributes part of mpfatr is as follows.
mpfatr:= (TA_TFIFO || TA_TPRI) | [TA_DSNAME] | [TA_NODISWAI]| (TA_RNG0 || TA_RNG1 || TA_RNG2 || TA_RNG3)
TA TFIFO
TA TPRITA RNGnTA DSNAMETA NODISWAI

Tasks waiting for memory allocation are queued in FIFO order
Tasks waiting for memory allocation are queued in priority order
Memory access privilege is set to protection level nSpecifies DS object name
Wait disabling by tk dis wai is prohibited#define TA_TFIFO
0x00000000#define TA_TPRI
0x00000001#define TA_DSNAME
0x00000040#define TA_NODISWAI 0x00000080#define TA_RNG00x00000000#define TA_RNG1
0x00000100#define TA_RNG2
0x00000200#define TA_RNG3
0x00000300/* manage task queue by FIFO*//* manage task queue by priority *//* DS object name*//* reject wait disabling*//* protection level 0*//* protection level 1*//* protection level 2*//* protection level 3*/

The queuing order of tasks waiting for memory block allocation from a memory pool can be specified in
TA TFIFO or TA TPRI. If the attribute is TA TFIFO, tasks are ordered by FIFO, whereas TA TPRI specifies
queuing of tasks in order of their priority setting.
TA RNGn is specified to limit the protection levels at which memory can be accessed. Only tasks runningat the same or higher protection level than the one specified can access the allocated memory. If a taskrunning at a lower protection level attempts access, a CPU protection fault exception is raised. For
example, memory allocated from a memory pool specified as TA RNG1 can be accessed by tasks runningat levels TA RNG0 or TA RNG1, but not by tasks running at levels TA RNG2 or TA RNG3.
The created memory pool is in resident memory in system space. There is no T-Kernel function for
creating a memory pool in task space.
When TA DSNAME is specified, dsname is valid and specifies the DS object name. DS object name isused to identify objects by debugger, and it is handled only by T-Kernel/DS API, td ref dsname andtd set dsname. For more details refer to td ref dsname and td set dsname. If TA DSNAME is not
specified, dsname is ignored. Then td ref dsname and td set dsname return E OBJ error.
[Additional Notes]
In the case of a fixed-size memory pool, separate memory pools must be provided for different block
sizes. That is, if various memory block sizes are required, memory pools must be created for each blocksize.
For the sake of portability, the TA RNGn attribute must be accepted even by a system without an MMU.
It is possible, for example, to treat all TA RNGn as equivalent to TA RNG0; but error must not be returned.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.6. MEMORY POOL MANAGEMENT FUNCTIONS

151

tk del mpf
Delete Fixed-size Memory Pool[C Language Interface]
ER ercd = tk_del_mpf ( ID mpfid ) ;[Parameters]
ID

mpfid

Fixed-size memory pool ID[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS

Normal completion
Invalid ID number (mpfid is invalid or cannot be used)
Object does not exist (the fixed-size memory pool specified in mpfid does not exist)[Description]
Deletes the fixed-size memory pool specified in mpfid.
No check or notification is made as to whether there are tasks using memory allocated from this memory
pool. The system call completes normally even if not all blocks have been returned to the pool.
Issuing this system call releases the memory pool ID number, the control block memory space and thememory pool space itself.
This system call completes normally even if there are tasks waiting for memory block allocation fromthe deleted memory pool, but error code E DLT is returned to the tasks in WAIT state.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

152

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk get mpf
Get Fixed-size Memory Block[C Language Interface]
ER ercd = tk_get_mpf ( ID mpfid, VP *p_blf, TMO tmout ) ;[Parameters]
ID
TMO

mpfid
tmout

Fixed-size memory pool ID
timeout[Return Parameters]
ER
VP

ercd
blf

Error code
Memory block start address[Error Codes]
E OK
E ID
E NOEXSE PAR
E DLT
E RLWAIE DISWAIE TMOUTE CTXNormal completion
Invalid ID number (mpfid is invalid or cannot be used)
Object does not exist (the fixed-size memory pool specified in mpfid does not exist)
Parameter error (tmout ≤ (−2))
The object being waited for was deleted (the memory pool was deleted while waiting)Wait state released (tk rel wai received in wait state)
Wait released by wait disabled state
Polling failed or timeout
Context error (issued from task-independent portion or in dispatch disabled state)[Description]
Gets a memory block from the fixed-size memory pool specified in mpfid. The start address of theallocated memory block is returned in blf. The size of the allocated memory block is the value specified
in the blfsz parameter when the fixed-size memory pool was created.
The allocated memory is not cleared to zero, and the memory block contents are indeterminate.
If a block cannot be allocated from the specified memory pool, the task that issued tk get blf is putin the queue of tasks waiting for memory allocation from that memory pool, and waits until memory
can be allocated.
A maximum wait time (timeout) can be set in tmout. If the tmout time elapses before the wait releasecondition is met (memory space does not become available), the system call terminates, returning
timeout error code E TMOUT.
Only positive values can be set in tmout. The time base for tmout (time unit) is the same as that forsystem time (= 1 ms).
When TMO POL = 0 is set in tmout, this means 0 was specified as the timeout value, and E TMOUT is
returned without entering WAIT state even if memory cannot be allocated.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.6. MEMORY POOL MANAGEMENT FUNCTIONS

153

When TMO FEVR = (−1) is set in tmout, this means infinity was specified as the timeout value, and thetask continues to wait for memory allocation without timing out.
The queuing order of tasks waiting for memory block allocation is either FIFO or task priority order,
depending on the memory pool attribute.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

154

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk rel mpf
Release Fixed-size Memory Block[C Language Interface]
ER ercd = tk_rel_mpf ( ID mpfid, VP blf ) ;[Parameters]
ID
VP

mpfid
blf

Fixed-size memory pool ID
Memory block start address[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (mpfid is invalid or cannot be used)
Object does not exist (the fixed-size memory pool specified in mpfid does not exist)
Parameter error (blf is invalid, or block returned to wrong memory pool)[Description]
Returns the memory block specified in blf to the fixed-size memory pool specified in mpfid.
Executing tk rel mpf may enable memory block acquisition by another task waiting to allocate memory
from the memory pool specified in mpfid, releasing the WAIT state of that task.
When a memory block is returned to a fixed-size memory pool, it must be the same fixed-size memory
pool from which the block was allocated. If an attempt to return a memory block to a different
memory pool is detected, error code E PAR is returned. Whether this error detection is made or not is
implementation-dependent.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.6. MEMORY POOL MANAGEMENT FUNCTIONS

155

tk ref mpf
Reference Fixed-size Memory Pool Status[C Language Interface]
ER ercd = tk_ref_mpf ( ID mpfid, T_RMPF *pk_rmpf ) ;[Parameters]ID
T RMPF*

mpfid
pk rmpf

Fixed-size memory pool ID
Address of packet for returning status information[Return Parameters]
ER

ercd

Error code

pk rmpf detail:
VP
ID
INT

exinf
wtsk
frbcntExtended information
Waiting task information
Free block count(Other implementation-dependent parameters may be added beyond this point.)[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (mpfid is invalid or cannot be used)
Object does not exist (the fixed-size memory pool specified in mpfid does not exist)
Parameter error (the return parameter packet address cannot be used)[Description]
References the status of the fixed-size memory pool specified in mpfid, passing in return parameters thecurrent free block count frbcnt, waiting task information (wtsk), and extended information (exinf).
wtsk indicates the ID of a task waiting for memory block allocation from this fixed-size memory pool.
If multiple tasks are waiting for the fixed-size memory pool, the ID of the task at the head of the queueis returned. If there are no waiting tasks, wtsk = 0 is returned.
If the fixed-size memory pool specified with tk ref mpf does not exist, error code E NOEXS is returned.
At least one of frbcnt = 0 and wtsk = 0 is always true for this system call.
[Additional Notes]
Whereas frsz returned by tk ref mpl gives the total free memory size in bytes, frbcnt returns thenumber of unused memory blocks.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

156

4.6.2

CHAPTER 4. T-KERNEL/OS FUNCTIONS

Variable-size Memory Pool

A variable-size memory pool is an object for dynamically managing memory blocks of any size. Functions
are provided for creating and deleting a variable-size memory pool, allocating and returning memory
blocks in a variable-size memory pool, and referencing the status of a variable-size memory pool. A
variable-size memory pool is an object identified by an ID number called a variable-size memory poolID.
A variable-size memory pool has a memory space used as the variable-size memory pool (called avariable-size memory pool area or simply memory pool area), and a queue for tasks waiting for memory
block allocation. A task wanting to allocate a memory block from a variable-size memory pool thatlacks sufficient available memory space goes to WAIT state for variable-size memory block until memory
blocks are returned to the pool. A task in this state is put in the task queue of the variable-size memory
pool.
[Additional Notes]
When tasks are waiting for memory block allocation from a variable-size memory pool, they are served inqueued order. If, for example, Task A requesting a 400-byte memory block from a variable-size memory
pool is queued along with Task B requesting a 100-byte block, in A-B order, then even if 200 bytes ofspace are free, Task B is made to wait until Task A has acquired the requested memory block.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.6. MEMORY POOL MANAGEMENT FUNCTIONS

157

tk cre mpl
Create Variable-size Memory Pool[C Language Interface]
ID mplid = tk_cre_mpl ( T_CMPL *pk_cmpl ) ;[Parameters]
T CMPL*pk cmplInformation about the variable-size memory pool to be createdpk cmpf detail:
VP
ATR
INT
UB

exinf
mplatrmplsz
dsname[8]Extended information
Memory pool attributes
Memory pool size (in bytes)
DS object name

(Other implementation-dependent parameters may be added beyond this point.)[Return Parameters]
ID

mplid
or

Variable-size memory pool ID
Error Code[Error Codes]
E OK
E NOMEM
E LIMITE RSATR
E PAR

Normal completion
Insufficient memory (memory for control block or memory pool area cannot be allocated)
Number of variable-size memory pools exceeds the system limit
Reserved attribute (mplatr is invalid or cannot be used)
Parameter error (pk cmpl is invalid, or mplsz is negative or invalid)[Description]
Creates a variable-size memory pool, assigning to it a variable-size memory pool ID.
This system call allocates a memory space for use as a memory pool, based on the information inparameter mplsz, and allocates a control block to the created memory pool.
exinf can be used freely by the user to set miscellaneous information about the created memory pool.
The information set in this parameter can be referenced by tk ref mpl. If a larger area is needed
for indicating user information, or if the information may need to be changed after the memory poolis created, this can be done by allocating separate memory for this purpose and putting the memory
packet address in exinf. The OS pays no attention to the contents of exinf.
mplatr indicates system attributes in its low bits and implementation-dependent information in thehigh bits. The system attributes part of mplatr is as follows.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

158

CHAPTER 4. T-KERNEL/OS FUNCTIONS
mplatr:= (TA_TFIFO || TA_TPRI) | [TA_DSNAME] | [TA_NODISWAI]| (TA_RNG0 || TA_RNG1 || TA_RNG2 || TA_RNG3)
TA TFIFO
TA TPRITA RNGnTA DSNAMETA NODISWAI

Tasks waiting for memory allocation are queued in FIFO order
Tasks waiting for memory allocation are queued in priority order
Memory access privilege is set to protection level nSpecifies DS object name
Wait disabling by tk dis wai is prohibited#define TA_TFIFO
0x00000000#define TA_TPRI
0x00000001#define TA_DSNAME
0x00000040#define TA_NODISWAI 0x00000080#define TA_RNG00x00000000#define TA_RNG1
0x00000100#define TA_RNG2
0x00000200#define TA_RNG3
0x00000300/* manage task queue by FIFO*//* manage task queue by priority *//* DS object name*//* reject wait disabling*//* protection level 0*//* protection level 1*//* protection level 2*//* protection level 3*/

The queuing order of tasks waiting to acquire memory from a memory pool can be specified in TA TFIFO
or TA TPRI. If the attribute is TA TFIFO, tasks are ordered by FIFO, whereas TA TPRI specifies queuingof tasks in order of their priority setting.
When tasks are queued waiting for memory allocation, memory is allocated in the order of queuing.
Even if other tasks in the queue are requesting smaller amounts of memory than the task at the head of
the queue, they do not acquire memory blocks before the first task. If, for example, Task A requestinga 400-byte memory block from a variable-size memory pool is queued along with Task B requesting a
100-byte block, in A-B order, then even if 200 bytes of space are free, Task B is made to wait until Task
A has acquired the requested memory block.
TA RNGn is specified to limit the protection levels at which memory can be accessed. Only tasks runningat the same or higher protection level than the one specified can access the allocated memory. If a taskrunning at a lower protection level attempts access, a CPU protection fault exception is raised. For
example, memory allocated from a memory pool specified as TA RNG1 can be accessed by tasks runningat levels TA RNG0 or TA RNG1, but not by tasks running at levels TA RNG2 or TA RNG3.
The created memory pool is in resident memory in system space. There is no T-Kernel function for
creating a memory pool in task space.
When TA DSNAME is specified, dsname is valid and specifies the DS object name. DS object name isused to identify objects by debugger, and it is handled only by T-Kernel/DS API, td ref dsname andtd set dsname. For more details refer to td ref dsname and td set dsname. If TA DSNAME is not
specified, dsname is ignored. Then td ref dsname and td set dsname return E OBJ error.
[Additional Notes]
If the task at the head of the queue waiting for memory allocation has its WAIT state forcibly released,
or if a different task becomes the first in the queue as a result of a change in task priority, memory
allocation is attempted to that task. If memory can be allocated, the WAIT state of that task is released.
In this way it is possible under some circumstances for memory allocation to take place and task WAIT
state to be released even when memory is not released by tk rel mpl.
For the sake of portability, the TA RNGn attribute must be accepted even by a system without an MMU.
It is possible, for example, to treat all TA RNGn as equivalent to TA RNG0; but error must not be returned.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.6. MEMORY POOL MANAGEMENT FUNCTIONS

159[Rationale for the Specification]
The capability of creating multiple memory pools can be used for memory allocation as needed for error
handling or in emergencies, etc.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

160

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk del mpl
Delete Variable-size Memory Pool[C Language Interface]
ER ercd = tk_del_mpl ( ID mplid ) ;[Parameters]
ID

mplid

Variable-size memory pool ID[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS

Normal completion
Invalid ID number (mplid is invalid or cannot be used)
Object does not exist (the variable-size memory pool specified in mplid does not exist)[Description]
Deletes the variable-size memory pool specified in mplid.
No check or notification is made as to whether there are tasks using memory allocated from this memory
pool. The system call completes normally even if not all blocks have been returned to the pool.
Issuing this system call releases the memory pool ID number, the control block memory space and thememory pool space itself.
This system call completes normally even if there are tasks waiting for memory block allocation fromthe deleted memory pool, but error code E DLT is returned to the tasks in WAIT state.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.6. MEMORY POOL MANAGEMENT FUNCTIONS

161

tk get mpl
Get Variable-size Memory Block[C Language Interface]
ER ercd = tk_get_mpl ( ID mplid, INT blksz, VP *p_blk, TMO tmout ) ;[Parameters]
ID
INT
TMO

mplid
blksz
tmout

Variable-size memory pool ID
Memory block size (in bytes)
Timeout[Return Parameters]
ER
VP

ercd
blk

Error code
Block start address[Error Codes]
E OK
E ID
E NOEXSE PAR
E DLT
E RLWAIE DISWAIE TMOUTE CTXNormal completion
Invalid ID number (mplid is invalid or cannot be used)
Object does not exist (the variable-size memory pool specified in mplid does not exist)
Parameter error (tmout ≤ (−2))
The object being waited for was deleted (the memory pool was deleted while waiting)Wait state released (tk rel wai received in wait state)
Wait released by wait disabled state
Polling failed or timeout
Context error (issued from task-independent portion or in dispatch disabled state)[Description]
Gets a memory block of size blksz (bytes) from the variable-size memory pool specified in mplid. The
start address of the allocated memory block is returned in blk.
The allocated memory is not cleared to zero, and the memory block contents are indeterminate.
If memory cannot be allocated, the task issuing this system call enters WAIT state.
A maximum wait time (timeout) can be set in tmout. If the tmout time elapses before the wait releasecondition is met (memory space does not become available), the system call terminates, returning
timeout error code E TMOUT.
Only positive values can be set in tmout. The time base for tmout (time unit) is the same as that forsystem time (= 1 ms).
When TMO POL = 0 is set in tmout, this means 0 was specified as the timeout value, and E TMOUT is
returned without entering WAIT state even if memory cannot be allocated.
When TMO FEVR = (−1) is set in tmout, this means infinity was specified as the timeout value, and thetask continues to wait for memory allocation without timing out.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

162

CHAPTER 4. T-KERNEL/OS FUNCTIONS

The queuing order of tasks waiting for memory block allocation is either FIFO or task priority order,
depending on the memory pool attribute.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.6. MEMORY POOL MANAGEMENT FUNCTIONS

163

tk rel mpl
Release Variable-size Memory Block[C Language Interface]
ER ercd = tk_rel_mpl ( ID mplid, VP blk ) ;[Parameters]
ID
VP

mplid
blf

Variable-size memory pool ID
Memory block start address[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (mplid is invalid or cannot be used)
Object does not exist (the variable-size memory pool specified in mplid does not exist)
Parameter error (blk is invalid, or block returned to wrong memory pool)[Description]
Returns the memory block specified in blk to the variable-size memory pool specified in mplid.
Executing tk rel mpl may enable memory block acquisition by another task waiting to allocate memory
from the memory pool specified in mplid, releasing the WAIT state of that task.
When a memory block is returned to a variable-size memory pool, it must be the same variable-size
memory pool from which the block was allocated. If an attempt to return a memory block to a different
memory pool is detected, error code E PAR is returned. Whether this error detection is made or not is
implementation-dependent.
[Additional Notes]
When memory is returned to a variable-size memory pool in which multiple tasks are queued, multiple
tasks may be released at the same time depending on the amount of memory returned and their requested
memory size. The task precedence among tasks of the same priority after their WAIT state is releasedin such a case is the order in which they were queued.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

164

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk ref mpl
Reference Variable-size Memory Pool Status[C Language Interface]
ER ercd = tk_ref_mpl ( ID mplid, T_RMPL *pk_rmpl ) ;[Parameters]ID
T RMPL*

mplid
pk rmplVariable-size memory pool ID
Address of packet for returning status information[Return Parameters]
ER

ercd

Error code

pk rmpl detail:
VP
ID
INT
INT

exinf
wtsk
frsz
maxsz

Extended information
Waiting task information
Free memory size (in bytes)
Maximum memory space size (in bytes)(Other implementation-dependent parameters may be added beyond this point.)[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (mplid is invalid or cannot be used)
Object does not exist (the variable-size memory pool specified in mplid does not exist)
Parameter error (the return parameter packet address cannot be used)[Description]
References the status of the variable-size memory pool specified in mplid, passing in return parameters
the total size of free space frsz, the maximum size of memory immediately available maxsz, waitingtask information (wtsk), and extended information (exinf).
wtsk indicates the ID of a task waiting for memory block allocation from this variable-size memory
pool. If multiple tasks are waiting for the variable-size memory pool, the ID of the task at the head of
the queue is returned. If there are no waiting tasks, wtsk = 0 is returned.
If the variable-size memory pool specified with tk ref mpl does not exist, error code E NOEXS is returned.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.7. TIME MANAGEMENT FUNCTIONS

4.7

165

Time Management Functions

Time management functions are for performing time-dependent processing. They include functions for
system time management, cyclic handlers, and alarm handlers.
The general name used here for cyclic handlers and alarm handlers is time event handlers.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

166

4.7.1

CHAPTER 4. T-KERNEL/OS FUNCTIONS

System Time Management

System time management functions are for manipulating system time. Functions are provided for system
clock setting and reference, and for referencing system operating time.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.7. TIME MANAGEMENT FUNCTIONS

167

tk set tim
Set Time[C Language Interface]
ER ercd = tk_set_tim ( SYSTIM *pk_tim ) ;[Parameters]
SYSTIM*

pk timAddress of current time packet

pk tim detail:
SYSTIMsystimCurrent system time

[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E PAR

Normal completion
Parameter error (pk tim is invalid, or time setting is invalid)[Description]
Sets the system clock to the value specified in systim.
System time is expressed as cumulative milliseconds from 0:00:00 (GMT), January 1, 1985.
[Additional Notes]
The relative time specified in RELTIM or TMO does not change even if the system clock is changed bycalling tk set tim during system operation. For example, if a timeout is set to elapse in 60 seconds andthe system clock is advanced by 60 seconds by tk set tim while waiting for the timeout, the timeout
occurs not immediately but 60 seconds after it was set. Instead, tk set tim changes the system timeat which the timeout occurs.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

168

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk get tim
Get Time[C Language Interface]
ER ercd = tk_get_tim ( SYSTIM *pk_tim ) ;[Parameters]
SYSTIM*

pk timAddress of current time packet[Return Parameters]
ER

ercd

Error code

pk tim detail:
SYSTIMsystimCurrent system time

[Error Codes]
E OK
E PAR

Normal completion
Parameter error (pk tim is invalid)[Description]
Reads the current value of the system clock and returns in it systim.
System time is expressed as cumulative milliseconds from 0:00:00 (GMT), January 1, 1985.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.7. TIME MANAGEMENT FUNCTIONS

169

tk get otm
Get Operating Time[C Language Interface]
ER ercd = tk_get_otm ( SYSTIM *pk_tim ) ;[Parameters]
SYSTIM*

pk timAddress of packet returning operating time

pk tim detail:
SYSTIM

opetimSystem operating time

[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E PAR

Normal completion
Parameter error (pk tim is invalid)[Description]
Gets the system operating time (up time).
System operating time, unlike system time, indicates the length of time elapsed linearly since the system
was started. It is not affected by clock settings made by tk set tim.
System operating time must have the same precision as system time.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

170

4.7.2

CHAPTER 4. T-KERNEL/OS FUNCTIONS

Cyclic Handler

A cyclic handler is a time event handler started at regular intervals. Cyclic handler functions are provided
for creating and deleting a cyclic handler, activating and deactivating a cyclic handler operation, andreferencing cyclic handler status. A cyclic handler is an object identified by an ID number called a cyclic
handler ID.
The time interval at which a cyclic handler is started (cycle time) and the cycle phase are specified
for each cyclic handler when it is created. When a cyclic handler operation is requested, T-Kernel
determines the time at which the cyclic handler should next be started based on the cycle time andcycle phase set for it. When a cyclic handler is created, the time when it is to be started next is the timeof its creation plus the cycle phase. When the time comes to start a cyclic handler, exinf, containing
extended information about the cyclic handler, is passed to it as a starting parameter. The time when
the cyclic handler is started plus its cycle time becomes the next start time. Sometimes when a cyclic
handler is activated, the next start time will be newly set.
In principle the cycle phase of a cyclic handler is no longer than its cycle time. The behavior if the cycle
phase is made longer than the cycle time is implementation-dependent.
A cyclic handler has two activation states, active and inactive. While a cyclic handler is inactive, it
is not started even when its start time arrives, although calculation of the next start time does takeplace. When a system call for activating a cyclic handler is called (tk sta cyc), the cyclic handler goesto active state, and the next start time is decided if necessary. When a system call for deactivating acyclic handler is called (tk stp cyc), the cyclic handler goes to inactive state. Whether a cyclic handler
upon creation is active or inactive is decided by a cyclic handler attribute.
The cycle phase of a cyclic handler is a relative time specifying the first time the cyclic handler is to be
started, in relation to the time when the system call creating it was invoked. The cycle time of a cyclic
handler is likewise a relative time, specifying the next time the cyclic handler is to be started in relation
to the time it should have started (not the time it started). For this reason, the intervals between times
the cyclic handler is started will individually be shorter than the cycle time in some cases, but theiraverage over a longer time span will match the cycle time.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.7. TIME MANAGEMENT FUNCTIONS

171

tk cre cycCreate Cyclic Handler[C Language Interface]
ID cycid = tk_cre_cyc ( T_CCYC *pk_ccyc ) ;[Parameters]
T CCYC*pk ccyc

Address of cyclic handler definition packet

pk ccyc detail:
VP
ATR
FP
RELTIMRELTIMUB

exinf
cycatrcychdrcyctimcycphsdsname[8]Extended information
Cyclic handler attributes
Cyclic handler address
Cycle time
Cycle phase
DS object name

(Other implementation-dependent parameters may be added beyond this point.)[Return Parameters]
ID

cycid
or

Cyclic handler ID
Error Code[Error Codes]
E OK
E NOMEM
E LIMITE RSATR
E PAR

Normal completion
Insufficient memory (memory for control block cannot be allocated)
Number of cyclic handlers exceeds the system limit
Reserved attribute (cycatr is invalid or cannot be used)
Parameter error (pk ccyc, cychdr, cyctim, or cycphs is invalid or cannot be used)[Description]
Creates a cyclic handler, assigning to it a cyclic handler ID. A cyclic handler is a handler running at
specified intervals as a task-independent portion.
exinf can be used freely by the user to set miscellaneous information about the created cyclic handler.
The information set in this parameter can be referenced by tk ref cyc. If a larger area is needed forindicating user information, or if the information may need to be changed after the cyclic handler iscreated, this can be done by allocating separate memory for this purpose and putting the memory packet
address in exinf. The OS pays no attention to the contents of exinf.
cycatr indicates system attributes in its low bits and implementation-dependent information in thehigh bits. The system attributes part of cycatr is as follows.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

172

CHAPTER 4. T-KERNEL/OS FUNCTIONS
cycatr := (TA_ASM || TA_HLNG) | [TA_STA] | [TA_PHS] | [TA_DSNAME]
TA ASMTA HLNGTA STATA PHSTA DSNAME

The handler is written in assembly language
The handler is written in high-level language
Activate immediately upon cyclic handler creation
Save the cycle phase
Specifies DS object name#define TA_ASM#define TA_HLNG#define TA_STA#define TA_PHS#define TA_DSNAME

0x00000000
0x00000001
0x00000002
0x00000004
0x00000040/* assembly program*//* high-level language program*//* activate cyclic handler*//* save cyclic handler cycle phase *//* DS object name*/cychdr specifies the cyclic handler start address, cyctim the cycle time, and cycphs the cycle phase.
When the TA HLNG attribute is specified, the cyclic handler is started via a high-level language support
routine. The high-level language support routine takes care of saving and restoring register values. The
cyclic handler terminates by a simple return from a function. The cyclic handler takes the following
format when the TA HLNG attribute is specified.
void cychdr( VP exinf ){/*Processing*/
return; /* Exit cyclic handler*/}
The cyclic handler format when the TA ASM attribute is specified is implementation-dependent, but
exinf must be passed in a starting parameter.
cycphs indicates the length of time until the cyclic hander is initially started after being created bytk cre cyc. Thereafter it is started periodically at the interval set in cyctim. If zero is specified forcycphs, the cyclic handler starts immediately after it is created. Zero cannot be specified for cyctim.
The starting of the cyclic handler for the nth time occurs after at least chcphs + chctim × (n − 1) time
has elapsed from the cyclic handler creation.
When TA STA is specified, the cyclic handler goes to active state immediately on creation, and starts at
the intervals noted above. If TA STA is not specified, the cycle time is calculated but the cyclic handler
is not actually started.
When TA PHS is specified, then even if tk sta cyc is called activating the cyclic handler, the cycle time
is not reset, and the cycle time calculated as above from the time of cyclic handler creation continues
to apply. If TA PHS is not specified, calling tk sta cyc resets the cycle time and the cyclic handler isstarted at cyctim intervals measured from the time tk sta cyc was called. Note that the resetting ofcycle time by tk sta cyc does not affect cycphs. In this case the starting of the cyclic handler for thenth time occurs after at least cyctim × n has elapsed from the calling of tk sta cyc.
Even if a system call is invoked from a cyclic handler and this causes the task in RUN state up tothat time to go to another state, with a different task going to RUN state, dispatching (task switching)
does not occur while the cyclic handler is running. Completion of execution by the cyclic handler has
precedence even if dispatching is necessary; only when the cyclic handler terminates does the dispatch
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.7. TIME MANAGEMENT FUNCTIONS

173

take place. In other words, a dispatch request occurring while a cyclic handler is running is not processed
immediately, but is delayed until the cyclic handler terminates. This is called delayed dispatching.
A cyclic handler runs as a task-independent portion. As such, it is not possible to call in a cyclic handlera system call that can enter WAIT state, or one that is intended for the invoking task.
When TA DSNAME is specified, dsname is valid and specifies the DS object name. DS object name isused to identify objects by debugger, and it is handled only by T-Kernel/DS API, td ref dsname andtd set dsname. For more details refer to td ref dsname and td set dsname. If TA DSNAME is not
specified, dsname is ignored. Then td ref dsname and td set dsname return E OBJ error.
[Additional Notes]
Once a cyclic handler is defined, it continues to run at the specified cycles either until tk stp cyc iscalled to deactivate it or until it is deleted. There is no parameter to specify the number of cycles intk cre cyc.
When multiple time event handlers or interrupt handlers operate at the same time, it is an implementationdependent matter whether to have them run serially (after one handler exits, another starts) or nested(one handler operation is suspended, another runs, and when that one finishes the previous one resumes).
In either case, since time event handlers and interrupt handlers run as task-independent portion, theprinciple of delayed dispatching applies.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

174

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk del cyc
Delete Cyclic Handler[C Language Interface]
ER ercd = tk_del_cyc ( ID cycid ) ;[Parameters]
ID

cycid

Cyclic handler ID[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS

Normal completion
Invalid ID number (cycid is invalid or cannot be used)
Object does not exist (the cyclic handler specified in cycid does not exist)[Description]
Deletes a cyclic handler.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.7. TIME MANAGEMENT FUNCTIONS

175

tk sta cyc
Start Cyclic Handler[C Language Interface]
ER ercd = tk_sta_cyc ( ID cycid ) ;[Parameters]
ID

cycid

Cyclic handler ID[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS

Normal completion
Invalid ID number (cycid is invalid or cannot be used)
Object does not exist (the cyclic handler specified in cycid does not exist)[Description]
Activates a cyclic handler, putting it in active state.
If the TA PHS attribute was specified, the cycle time of the cyclic handler is not reset when the cyclic
handler goes to active state. If it was already in active state when this system call was executed, it
continues unchanged in active state.
If the TA PHS attribute was not specified, the cycle time is reset when the cyclic handler goes to active
state. If it was already in active state, it continues in active state but its cycle time is reset. In thiscase, the next time the cyclic handler starts is after cyctim has elapsed.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

176

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk stp cyc
Stop Cyclic Handler[C Language Interface]
ER ercd = tk_stp_cyc ( ID cycid ) ;[Parameters]
ID

cycid

Cyclic handler ID[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS

Normal completion
Invalid ID number (cycid is invalid or cannot be used)
Object does not exist (the cyclic handler specified in cycid does not exist)[Description]
Deactivates a cyclic handler, putting it in inactive state. It the cyclic handler was already in inactive
state, this system call has no effect (no operation).

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.7. TIME MANAGEMENT FUNCTIONS

177

tk ref cyc
Reference Cyclic Handler Status[C Language Interface]
ER ercd = tk_ref_cyc ( ID cycid, T_RCYC *pk_rcyc ) ;[Parameters]ID
T RCYC*cycid
pk rcyc

Cyclic handler ID
Address of packet for returning status information[Return Parameters]
ER

ercd

Error code

pk rcyc detail:VP
RELTIMUINT

exinf
lfttimcycstatExtended information
Time remaining until the next start time
Cyclic handler activation state(Other implementation-dependent parameters may be added beyond this point.)[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (cycid is invalid or cannot be used)
Object does not exist (the cyclic handler specified in cycid does not exist)
Parameter error (the return parameter packet address cannot be used)[Description]
References the status of the cyclic handler specified in cycid, passing in return parameters the cyclic
handler activation state cycstat, the time remaining until the next start lfttim, and extended information exinf.
The following information is returned in cycstat.
cycstat:= (TCYC_STP | TCYC_STA)
TCYC STP
TCYC STA

The cyclic handler is inactive
The cyclic handler is active#define TCYC_STP#define TCYC_STA

0x00
0x01

/* cyclic handler is inactive *//* cyclic handler is active*/

If the cyclic handler specified in cycid does not exist, error code E NOEXS is returned.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

178

4.7.3

CHAPTER 4. T-KERNEL/OS FUNCTIONS

Alarm Handler

An alarm handler is a time event handler that starts at a specified time. Functions are provided for
creating and deleting an alarm handler, activating and deactivating the alarm handler, and referencing
the alarm handler status. An alarm handler is an object identified by an ID number called an alarm
handler ID.
The time at which an alarm handler starts (called the alarm time) can be set independently for each
alarm handler. When the alarm time arrives, exinf, containing extended information about the alarm
handler, is passed to it as a starting parameter.
After an alarm handler is created, initially it has no alarm time set and is in inactive state. The alarmtime is set when the alarm handler is activated by calling tk sta alm, as relative time from the timethat system call is executed. When tk stp alm is called deactivating the alarm handler, the alarm time
setting is canceled. Likewise, when an alarm time arrives and the alarm handler runs, the alarm time
is canceled and the alarm handler becomes inactive.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.7. TIME MANAGEMENT FUNCTIONS

179

tk cre alm
Create Alarm Handler[C Language Interface]
ID almid = tk_cre_alm ( T_CALM *pk_calm ) ;[Parameters]
T CALM*pk calm

Address of alarm handler definition packet

pk calm detail:
VP
ATR
FP
UB

exinf
almatralmhdrdsname[8]Extended information
Alarm handler attributes
Alarm handler address
DS object name[Return Parameters]
ID

almid
or

Alarm handler ID
Error Code[Error Codes]
E OK
E NOMEM
E LIMITE RSATR
E PAR

Normal completion
Insufficient memory (memory for control block cannot be allocated)
Number of alarm handlers exceeds the system limit
Reserved attribute (almatr is invalid or cannot be used)
Parameter error (almno, pk calm, or almhdr is invalid or cannot be used)[Description]
Creates an alarm handler, assigning to it an alarm handler ID. An alarm handler is a handler runningat the specified time as a task-independent portion.
exinf can be used freely by the user to set miscellaneous information about the created alarm handler.
The information set in this parameter can be referenced by tk ref alm. If a larger area is needed forindicating user information, or if the information may need to be changed after the alarm handler iscreated, this can be done by allocating separate memory for this purpose and putting the memory packet
address in exinf. The OS pays no attention to the contents of exinf.
almatr indicates system attributes in its low bits and implementation-dependent information in thehigh bits. The system attributes part of almatr is as follows.
almatr := (TA_ASM || TA_HLNG) | [TA_DSNAME]

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

180

CHAPTER 4. T-KERNEL/OS FUNCTIONSTA ASMTA HLNGTA DSNAME

The handler is written in assembly language
The handler is written in high-level language
Specifies DS object name#define TA_ASM#define TA_HLNG#define TA_DSNAME

0x00000000
0x00000001
0x00000040/* assembly program/* high-level language program/* DS object name

*/
*/
*/

almhdr specifies the alarm handler start address.
When the TA HLNG attribute is specified, the alarm handler is started via a high-level language support
routine. The high-level language support routine takes care of saving and restoring register values. The
alarm handler terminates by a simple return from a function. The alarm handler takes the following
format when the TA HLNG attribute is specified.
void almhdr( VP exinf ){/*Processing*/
return; /* exit alarm handler */}The alarm handler format when the TA ASM attribute is specified is implementation-dependent, but exinf
must be passed in a starting parameter.
Even if a system call is invoked from an alarm handler and this causes the task in RUN state up tothat time to go to another state, with a different task going to RUN state, dispatching (task switching)
does not occur while the alarm handler is running. Completion of execution by the alarm handler
has precedence even if dispatching is necessary; only when the alarm handler terminates does thedispatch take place. In other words, a dispatch request occurring while an alarm handler is running is
not processed immediately, but is delayed until the alarm handler terminates. This is called delayed
dispatching.
An alarm handler runs as a task-independent portion. As such, it is not possible to call in an alarm
handler a system call that can enter WAIT state, or one that is intended for the invoking task.
When TA DSNAME is specified, dsname is valid and specifies the DS object name. DS object name isused to identify objects by debugger, and it is handled only by T-Kernel/DS API, td ref dsname andtd set dsname. For more details refer to td ref dsname and td set dsname. If TA DSNAME is not
specified, dsname is ignored. Then td ref dsname and td set dsname return E OBJ error.
[Additional Notes]
When multiple time event handlers or interrupt handlers operate at the same time, it is an implementationdependent matter whether to have them run serially (after one handler exits, another starts) or nested(one handler operation is suspended, another runs, and when that one finishes the previous one resumes).
In either case, since time event handlers and interrupt handlers run as task-independent portion, theprinciple of delayed dispatching applies.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.7. TIME MANAGEMENT FUNCTIONS

181

tk del alm
Delete Alarm Handler[C Language Interface]
ER ercd = tk_del_alm ( ID almid ) ;[Parameters]
ID

almid

Alarm handler ID[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS

Normal completion
Invalid ID number (almid is invalid or cannot be used)
Object does not exist (the alarm handler specified in almid does not exist)[Description]
Deletes an alarm handler.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

182

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk sta alm
Start Alarm Handler[C Language Interface]
ER ercd = tk_sta_alm ( ID almid, RELTIM almtim ) ;[Parameters]ID
RELTIMalmid
almtimAlarm handler ID
Alarm handler start time (alarm time)[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS

Normal completion
Invalid ID number (almid is invalid or cannot be used)
Object does not exist (the alarm handler specified in almid does not exist)[Description]
Sets the alarm time of the alarm handler specified in almid to the time given in almtim, putting thealarm handler in active state. almtim is specified as relative time from the time of calling tk sta alm.
After the time specified in almtim has elapsed, the alarm handler starts. If the alarm handler is alreadyactive when this system call is invoked, the existing almtim setting is canceled and the alarm handler isactivated anew with the alarm time specified here.
If almtim = 0 is set, the alarm handler starts as soon as it is activated.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.7. TIME MANAGEMENT FUNCTIONS

183

tk stp alm
Stop Alarm Handler[C Language Interface]
ER ercd = tk_stp_alm ( ID almid ) ;[Parameters]
ID

almid

Alarm handler ID[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS

Normal completion
Invalid ID number (almid is invalid or cannot be used)
Object does not exist (the alarm handler specified in almid does not exist)[Description]
Cancels the alarm time of the alarm handler specified in almid, putting it in inactive state. If it was
already in inactive state, this system call has no effect (no operation).

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

184

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk ref alm
Reference Alarm Handler Status[C Language Interface]
ER ercd = tk_ref_alm ( ID almid, T_RALM *pk_ralm ) ;[Parameters]ID
T RALM*almid
pk ralm

Alarm handler ID
Address of packet for returning status information[Return Parameters]
ER

ercd

Error code

pk ralm detail:VP
RELTIMUINT

exinf
lfttimalmstatExtended information
Time remaining until the handler starts
Alarm handler activation state(Other implementation-dependent parameters may be added beyond this point.)[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (almid is invalid or cannot be used)
Object does not exist (the alarm handler specified in almid does not exist)
Parameter error (the return parameter packet address cannot be used)[Description]
References the status of the alarm handler specified in almno, passing in return parameters the timeremaining until the handler starts lfttim, and extended information exinf.
The following information is returned in almstat.
almstat:= (TALM_STP | TALM_STA)
TALM STPTALM STA

Thg alarm handler is inactive
The alarm handler is active#define TALM_STP#define TALM_STA

0x00
0x01

/* alarm handler is inactive *//* alarm handler is active*/

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.7. TIME MANAGEMENT FUNCTIONS

185

If the alarm handler is active (TALM STA), lfttim returns the relative time until the alarm handler isscheduled to start. This value is within the range almtim ≥ lfttim ≥ 0 specified with tk sta alm.
Since lfttim is decremented with each timer interrupt, lfttim = 0 means the alarm handler will startat the next timer interrupt. If the alarm handler is inactive (TALM STP), lfttim is indeterminate.
If the alarm handler specified with tk ref alm in almid does not exist, error code E NOEXS is returned.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

186

CHAPTER 4. T-KERNEL/OS FUNCTIONS

4.8

Interrupt Management Functions

Interrupt management functions are for defining and manipulating handlers for external interrupts andCPU exceptions.
An interrupt handler runs as a task-independent portion. System calls can be invoked in a taskindependent portion in the same way as in a task portion, but the following restriction applies to systemcall issuing in a task-independent portion.
• A system call that implicitly specifies the invoking task, or one that may put the invoking task in
WAIT state cannot be issued. Error code E CTX is returned in such cases.
During task-independent portion execution, task switching (dispatching) does not occur. If systemcall processing results in a dispatch request, the dispatch is delayed until processing leaves the taskindependent portion. This is called delayed dispatching.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.8. INTERRUPT MANAGEMENT FUNCTIONS

187

tk def int
Define Interrupt Handler[C Language Interface]
ER ercd = tk_def_int ( UINT dintno, T_DINT *pk_dint ) ;[Parameters]UINT
T DINT*

dintnopk dint

Interrupt definition number
Packet of interrupt handler definition information

pk dint detail:
ATR
FP

intatrinthdrInterrupt handler attributes
Interrupt handler address(Other implementation-dependent parameters may be added beyond this point.)[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E NOMEME RSATR
E PAR

Normal completion
Insufficient memory (memory for control block cannot be allocated)
Reserved attribute (intatr is invalid or cannot be used)
Parameter error (dintno, pk dint, or inthdr is invalid or cannot be used)[Description]
Defines an interrupt handler for interrupt definition number dintno, and enables use of the interrupt
handler. Here “interrupts” include both external interrupts from a device and CPU exceptions.
This system call maps the interrupt definition number indicated in dintno to the interrupt handler
address and attributes.
The specific significance of dintno is defined separately for each implementation, but generally it means
an interrupt vector number.
intatr indicates system attributes in its low bits, with the high bits used for implementation-dependent
attributes. The system attributes part of intatr is specified in the following format.
intatr := (TA_ASM || TA_HLNG)TA ASMTA HLNG

The handler is written in assembly language
The handler is written in high-level language#define TA_ASM 0x00000000#define TA_HLNG 0x00000001/* assembly program *//* high-level language program */c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

188

CHAPTER 4. T-KERNEL/OS FUNCTIONSWhen the TA ASM attribute is specified, in principle the OS is not involved in interrupt handler starting.
When an interrupt is raised, the interrupt handling function in the CPU hardware (depending on
the implementation, processing by T-Monitor may be included) directly starts the interrupt handler
defined by this system call. Accordingly, processing for saving and restoring registers used by theinterrupt handler is necessary at the beginning and end of the interrupt handler. An interrupt handler
is terminated by execution of the tk ret int system call or by the CPU interrupt return instruction(or equivalent means).
Provision of a means for return from an interrupt handler without using tk ret int and without OSintervention is mandatory. Note that if tk ret int is not used, delayed dispatching is not necessary.
Support for return from an interrupt handler using tk ret int is mandatory, and in this case delayed
dispatching is necessary.
When the TA HLNG attribute is specified, the interrupt handler is started via a high-level language
support routine. The high-level language support routine takes care of saving and restoring registervalues. The interrupt handler terminates by a simple return from a function. The interrupt handler
takes the following format when the TA HLNG attribute is specified.
void inthdr( UINT dintno ){/*Processing*/
return; /* exit interrupt handler */}The parameter dintno passed to an interrupt handler is a number identifying the interrupt that was
raised, and is the same as that specified with tk def int. Depending on the implementation, otherinformation about the interrupt may be passed in addition to dintno. If such information is used, it
must be defined for each implementation in a second parameter or subsequent parameters passed to theinterrupt handler.
If the TA HLNG attribute is specified, it is assumed that the CPU interrupt flag will be set to interrupts
disabled state from the time the interrupt is raised until the interrupt handler is called. In other words,
as soon as an interrupt is raised, the state goes to multiple interrupts disabled, and this state remains
when the interrupt handler is called. If multiple interrupts are enabled, the interrupt handler must
include processing that enables interrupts by manipulating the CPU interrupt flag.
Also in the case of the TA HLNG attribute, upon entry into the interrupt handler, system call issuingmust be possible. Note, however, that assuming standard provision of the functionality described above,
extensions are allowable such as adding a function for entering an interrupt handler with multiple
interrupts enabled.
When the TA ASM attribute is specified, the state upon entry into the interrupt handler is defined for each
implementation. Such matters as the stack and register status upon interrupt handler entry, whether
system calls can be made, the method of invoking system calls, and the method of returning from theinterrupt handler without OS intervention must all be defined explicitly.
In the case of the TA ASM attribute, depending on the implementation there may be cases where interrupt
handler execution is not considered to be a task-independent portion. In such a case the following points
need to be noted carefully.
• If interrupts are enabled, there is a possibility that task dispatching will occur.
• When a system call is invoked, it will be processed as having been called from a task portion or
quasi-task portion.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.8. INTERRUPT MANAGEMENT FUNCTIONS

189

If a method is provided for performing some kind of operation in an interrupt handler to have it detected
as task-independent portion, that method must be indicated for each implementation.
Whether the TA HLNG or TA ASM attribute is specified, upon entry into an interrupt handler, the logicalspace at the time the interrupt occurred is retained. No processing takes place upon return fromthe interrupt handler for restoring the logical space to its state at the time the interrupt was raised.
Switching logical spaces inside the interrupt handler is not prohibited, but the OS is not aware of theeffects of logical space switching.
Even if a system call is invoked from an interrupt handler and this causes the task in RUN state up tothat time to go to another state, with a different task going to RUN state, dispatching (task switching)
does not occur while the interrupt handler is running. Completion of execution by the interrupt handler
has precedence even if dispatching is necessary; only when the interrupt handler terminates does thedispatch take place. In other words, a dispatch request occurring while an interrupt handler is running is
not processed immediately, but is delayed until the interrupt handler terminates. This is called delayed
dispatching.
An interrupt handler runs as a task-independent portion. As such, it is not possible to call in aninterrupt handler a system call that can enter WAIT state, or one that is intended for the invoking task.
When pk dint = NULL is set, a previously defined interrupt handler is canceled. When the handler for
an interrupt is canceled, the default handler defined by T-Monitor is used.
It is possible to redefine an interrupt handler for an interrupt number already having a defined handler.
It is not necessary first to cancel the definition for that number. Defining a new handler for a dintno
already having an interrupt handler defined does not return error.
[Additional Notes]
The various specifications governing the TA ASM attribute are mainly concerned with achieving an interrupt hook. For example, when an exception is raised due to illegal address access, ordinarily aninterrupt handler defined in a higher-level program detects this and performs the error processing; but
in the case of debugging, in place of error processing by a higher-level program, a T-Monitor interrupt
handler does the processing and starts a debugger. In this case the interrupt handler defined by thehigher-level program hooks the T-Monitor interrupt handler. After that, depending on the situation,either interrupt handling is passed off to T-Monitor or the other program does the processing on its
own.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

190

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk ret int
Return from Interrupt Handler[C Language Interface]void tk_ret_int ( ) ;• Although this system call is defined in the form of a C language interface, it will not be called inthis format if a high-level language support routine is used.
[Parameters]
None.
[Return Parameters]• Does not return to the context issuing the system call.
[Error Codes]• The following kind of error may be detected, but no return is made to the context issuing thesystem call even if the error is detected. For this reason the error code cannot be passed directly
as a system call return parameter. The behavior if error is detected is implementation-dependent.
E CTX

Context error (issued from other than an interrupt handler (implementation-dependent
error))[Description]
Exits an interrupt handler.
System calls invoked from an interrupt handler do not result in dispatching while the handler is running;
instead, the dispatching is delayed until tk ret int is called ending the interrupt handler processing(delayed dispatching). Accordingly, tk ret int results in the processing of all dispatch requests madewhile the interrupt handler was running.
tk ret int is invoked only if the interrupt handler was defined specifying the TA ASM attribute. In thecase of a TA HLNG attribute interrupt handler, the functionality equivalent to tk ret int is executed
implicitly in the high-level language support routine, so tk ret int is not (must not be) called explicitly.
As a rule, the OS is not involved in the starting of a TA ASM attribute interrupt handler. When aninterrupt is raised, the defined interrupt handler is started directly by the CPU hardware interrupt
processing function. The saving and restoring of registers used by the interrupt handler must therefore
be taken care of in the interrupt handler.
For the same reason, the stack and register states at the time tk ret int is issued must be the sameas those at the time of entry into the interrupt handler. Because of this, in some cases function codes
cannot be used in tk ret int, in which case tk ret int can be implemented using a trap instructionof another vector separate from that used for other system calls.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.8. INTERRUPT MANAGEMENT FUNCTIONS

191[Additional Notes]
tk ret int is a system call that does not return to the context from which it was called. Even if anerror code is returned when an error of some kind is detected, normally no error checking is performedin the context from which the system call was invoked, leaving the possibility that the program willhang. For this reason these system calls do not return even if error is detected.
Using an assembly-language return (REIT) instruction instead of tk ret int to exit the interrupt handler
is possible if it is clear no dispatching will take place on return from the handler (the same task isguaranteed to continue executing), or if there is no need for dispatching to take place.
Depending on the CPU architecture and method of configuring the OS, it may be possible to perform
delayed dispatching even when an interrupt handler exits using an assembly-language REIT instruction.
In such cases it is allowable for the assembly-language REIT instruction to be interpreted as if it were atk ret int system call.
Performing of E CTX error checking when tk ret int is called from a time event handler is implementationdependent. Depending on the implementation, control may return from a different type of handler.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

192

4.9

CHAPTER 4. T-KERNEL/OS FUNCTIONS

System Management Functions

System management functions are functions for changing and referencing system states. Functions areprovided for rotating task precedence in a queue, getting the ID of the task in RUN state, disablingand enabling task dispatching, referencing context and system states, setting low-power mode, andreferencing the T-Kernel version.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.9. SYSTEM MANAGEMENT FUNCTIONS

193

tk rot rdq
Rotate Ready Queue[C Language Interface]
ER ercd = tk_rot_rdq ( PRI tskpri ) ;[Parameters]
PRI

tskpri

Task priority[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E PAR

Normal completion
Parameter error (tskpri is invalid)[Description]
Rotates the precedence among tasks having the priority specified in tskpri.
This system call changes the precedence of tasks in RUN or READY state having the specified priority,
so that the task with the highest precedence among those tasks is given the lowest precedence.
By setting tskpri = TPRI RUN = 0, this system call rotates the precedence of tasks having the priority
level of the task currently in RUN state. When tk rot rdq is called from an ordinary task, it rotates theprecedence of tasks having the same priority as the invoking task. When calling from a cyclic handler
or other task-independent portion, it is also possible to call tk rot rdq (tskpri = TPRI RUN).
[Additional Notes]
If there are no tasks in a run state having the specified priority, or only one such task, the system callcompletes normally with no operation (no error code is returned).
When this system call is issued in dispatch enabled state, specifying as the priority either TPRI RUN or
the current priority of the invoking task, the precedence of the invoking task will be the lowest among
tasks of the same priority. In this way the system call can be used to relinquish execution privilege.
In dispatch disabled state, the task with highest precedence among tasks of the same priority is notalways the currently executing task. The precedence of the invoking task will therefore not always
become the lowest among tasks having the same priority when the above method is used in dispatch
disabled state.
Examples of tk rot rdq execution are given in Figure 4.9 and Figure 4.10. When this system call isissued in the state shown in Figure 4.9 specifying tskpri = 2, the new precedence order becomes thatin Figure 4.10, and Task C becomes the executing task.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

194

CHAPTER 4. T-KERNEL/OS FUNCTIONS

priority
High
6
?
Low

1
2

-

[Task B] - [Task C] - [Task D]

3-[Task E]

Figure 4.9: Precedence Before Issuing tk rot rdq

priority
High
6
?
Low

1
2

-

[Task C] - [Task D] - [Task B]

3-[Task E]• Task C executes next.
Figure 4.10: Precedence After Issuing tk rot rdq (tskpri = 2)

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.9. SYSTEM MANAGEMENT FUNCTIONS

195

tk get tid
Get Task Identifier[C Language Interface]
ID tskid = tk_get_tid ( ) ;[Parameters]
None[Return Parameters]
ID

tskid

ID of the task in RUN state[Error Codes]
None[Description]
Gets the ID number of the task currently in RUN state. Unless the task-independent portion is executing,the current RUN state task will be the invoking task.
If there is no task currently in RUN state, 0 is returned.
[Additional Notes]
The task ID returned by tk get tid is identical to runtskid returned by tk ref sys.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

196

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk dis dsp
Disable Dispatch[C Language Interface]
ER ercd = tk_dis_dsp ( ) ;[Parameters]
None[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E CTX

Normal completion
Context error (issued from task-independent portion)[Description]
Disables task dispatching. Dispatch disabled state remains in effect until tk ena dsp is called enablingtask dispatching. While dispatching is disabled, the invoking task does not change from RUN state to
READY state or to WAIT state. External interrupts, however, are still enabled, so even in dispatch
disabled state an interrupt handler can be started. In dispatch disabled state, the running task can bepreempted by an interrupt handler, but not by another task.
The specific operations during dispatch disabled state are as follows.
• Even if a system call issued from an interrupt handler or by the task that called tk dis dsp results
in a task going to READY state with a higher priority than the task that called tk dis dsp, thattask will not be dispatched. Dispatching of the higher-priority task is delayed until dispatch
disabled state ends.
• If the task that called tk dis dsp issues a system call that may cause the invoking task to be put
in WAIT state (e.g., tk slp tsk or tk wai sem), error code E CTX is returned.
• When system status is referenced by tk ref sys, TSS DDSP is returned in sysstat.
If tk dis dsp is called for a task already in dispatch disabled state, that state continues with no error
code returned. No matter how many times tk dis dsp is called, calling tk ena dsp just one timeis enough to enable dispatching again. The operation when the pair of system calls tk dis dsp andtk ena dsp are nested must therefore be managed by the user as necessary.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.9. SYSTEM MANAGEMENT FUNCTIONS

197[Additional Notes]
A task in RUN state cannot go to DORMANT state or NON-EXISTENT state while dispatching is
disabled. If tk ext tsk or tk exd tsk is called for a task in RUN state while interrupts or dispatchingis disabled, error code E CTX is detected. Since, however, tk ext tsk and tk exd tsk are system callsthat do not return to their original context, such errors are not passed in return parameters by thesesystem calls.
Use of dispatch disabled state for mutual exclusion control among tasks is possible only if the systemdoes not have a multiprocessor configuration.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

198

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk ena dsp
Enable Dispatch[C Language Interface]
ER ercd = tk_ena_dsp ( ) ;[Parameters]
None[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E CTX

Normal completion
Context error (issued from task-independent portion)[Description]
Enables task dispatching.
This system call cancels the disabling of dispatching by the tk dis dsp system call.
If tk ena dsp is called for a task not in dispatch disabled state, the dispatch enabled state continues
and no error code is returned.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.9. SYSTEM MANAGEMENT FUNCTIONS

199

tk ref sys
Reference System Status[C Language Interface]
ER ercd = tk_ref_sys ( T_RSYS *pk_rsys ) ;[Parameters]
T RSYS*

pk rsys

Address of packet for returning status information[Return Parameters]
ER

ercd

Error code

pk rsys detail:
INT
ID
ID

sysstatruntskidschedtskid

System status
ID of task currently in RUN state
ID of task scheduled to run next

(Other implementation-dependent parameters may be added beyond this point.)[Error Codes]
E OK
E PAR

Normal completion
Parameter error (the return parameter packet address cannot be used)[Description]
Gets the current system execution status, passing in return parameters such information as the dispatch
disabled state and whether a task-independent portion is executing.
The following values are returned in sysstat.
sysstat := ( TSS_TSK | [TSS_DDSP] | [TSS_DINT] )|| ( TSS_QTSK | [TSS_DDSP] | [TSS_DINT] )|| ( TSS_INDP )TSS TSKTSS DDSPTSS DINTTSS INDPTSS QTSK

Task portion executing
Dispatch disabledInterrupts disabled
Task-independent portion executing
Quasi-task portion executing

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

200

CHAPTER 4. T-KERNEL/OS FUNCTIONS#define TSS_TSK#define TSS_DDSP#define TSS_DINT#define TSS_INDP#define TSS_QTSK

0
1
2
4
8

/* Task portion executing/* Dispatch disabled/* Interrupts disabled/* Task-independent portion executing/* Quasi-task portion executing

*/
*/
*/
*/
*/

The ID of the task currently in RUN state is returned in runtskid, while schedtskid indicates the
ID of the next task scheduled to go to RUN state. Normally runtskid = schedtskid, but this is notnecessarily true if, for example, a higher-priority task was wakened during dispatch disabled state. If
there is no such task, 0 is returned.
It must be possible to invoke this system call from an interrupt handler or time event handler.
[Additional Notes]
Depending on the OS implementation, the information returned by tk ref sys is not necessarily guaranteed to be accurate at all times.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.9. SYSTEM MANAGEMENT FUNCTIONS

201

tk set pow
Set Power Mode
[C Language Interface]
ER ercd = tk_set_pow ( UINT powmode ) ;[Parameters]
UINT

powmodLow-power mode

[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E PAR
E QOVRE OBJNormal completion
Parameter error (value that cannot be used in powmode)
Low-power mode disable count overflow
TPW ENALOWPOW was requested with low-power mode disable count at 0

[Description]
The following two power-saving functions are supported.
• Switching to low-power mode when the system is idle
When there are no tasks to be executed, the system switches to a low-power mode provided in
hardware. Low-power mode is a function for reducing power use during very short intervals, suchas from one timer interrupt to the next. This is accomplished, for example, by lowering the CPU
clock frequency. It does not require complicated mode-switching in software but is implemented
mainly using hardware functionality.
• Automatic power-off
When the operator performs no operations for a certain length of time, the system automaticallycuts the power and goes to suspended state. If there is a start request (interrupt, etc.) from aperipheral device or if the operator turns on the power, the system resumes from the state when
the power was cut. In the case of a power supply problem such as low battery, the system likewise
cuts the power and goes to suspended state.
In suspended state, the power is cut to peripheral devices and circuits as well as to the CPU, but
the main memory contents are retained.
tk set pow sets the low-power mode.
powmode:= ( TPW_DOSUSPEND || TPW_DISLOWPOW || TPW_ENALOWPOW )c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

202

CHAPTER 4. T-KERNEL/OS FUNCTIONSTPW DOSUSPENDTPW DISLOWPOW
TPW ENALOWPOW

Suspended state
Switching to low-power mode disabled
Switching to low-power mode enabled (default)#define TPW_DOSUSPEND#define TPW_DISLOWPOW#define TPW_ENALOWPOW

123

Suspended state
Switching to low-power mode disabled
Switching to low-power mode enabled (default)• TPW DOSUSPEND
Execution of all tasks and handlers is stopped, peripheral circuits (timers, interrupt controllers,etc.) are stopped, and the power is cut (suspended). (off pow is called.)
When power is turned back on, peripheral circuits are restarted, execution of all tasks and handlers
is resumed, operations resume from the point before power was cut, and the system call returns.
If for some reason the resume processing fails, normal startup processing (for reset) is performed
and the system boots fresh.
• TPW DISLOWPOW
Switching to low-power mode in the dispatcher is disabled. (low pow is not called.)• TPW ENALOWPOW
Switching to low-power mode in the dispatcher is enabled. (low pow is called). The default at
system startup is low-power mode enabled (TPW ENALOWPOW).
Each time TPW DISLOWPOW is specified, the request count is taken. Low-power mode is enabled only
when TPW ENALOWPOW is requested for as many times as TPW DISLOWPOW was requested. The maximum
request count is implementation-dependent, but a count of at least 255 times must be possible.
[Additional Notes]
off pow and low pow are T-Kernel/SM functions. See 5.6 for details.
T-Kernel does not detect power supply problems or other factors for suspending the system. Actual
suspension requires suspend processing in each of the peripheral devices (device drivers). The system issuspended not by calling tk set pow directly but by use of the T-Kernel/SM suspend function.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.9. SYSTEM MANAGEMENT FUNCTIONS

203

tk ref ver
Reference Version Information[C Language Interface]
ER ercd = tk_ref_ver ( T_RVER *pk_rver ) ;[Parameters]
T RVER*

pk rverStart address of version information packet[Return Parameters]
ER

ercd

Error code

pk rver detail:
UH
UH
UH
UH
UH

maker
prid
spver
prver
prno[4]

T-Kernel maker code
T-Kernel ID
Specification version
T-Kernel version
T-Kernel products management information[Error Codes]
E OK
E PAR

Normal completion
Parameter error (the return parameter packet address cannot be used)[Description]
Gets information about the T-Kernel version in use, returning that information in the packet specifiedin pk rver. The following information can be obtained.
maker is the maker code of the T-Kernel implementing vendor. The maker field has the format shownin Figure 4.11.

[maker]maker

Figure 4.11: maker Field Format
prid is a number indicating the T-Kernel type. The prid format is shown in Figure 4.12.
Assignment of values to prid is left up to the vendor implementing T-Kernel. Note, however, that thisis the only number distinguishing product types, and that vendors should give careful thought to how
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

204

CHAPTER 4. T-KERNEL/OS FUNCTIONS

they assign these numbers, doing so in a systematic way. In that way the combination of maker codeand prid becomes a unique identifier of the T-Kernel type.

[prid]
prid

Figure 4.12: prid Field Format
The upper 4 bits of spver give the TRON specification series. The low 12 bits indicate the T-Kernel
specification version implemented. The format of spver is shown in Figure 4.13.
If, for example, a product conforms to the T-Kernel specification Ver 1.02.xx, spver is as follows.
MAGIC
SpecVerS
spver

= 0x7
= 0x102= 0x7102(T-Kernel)(Ver 1.02)

If a product implements the T-Kernel specification draft version Ver 1.B0.xx, spver is as follows.
MAGIC
SpecVerS
spver

= 0x7
= 0x1B0= 0x71B0(T-Kernel)(Ver 1.B0)[spver]
SpecVer

MAGIC

MAGIC: A number identifying the TRON specification series
0x0
0x1
0x2
0x3
0x4
0x5
0x6
0x7

TRON common (TAD, etc.)
ITRON1, ITRON2
BTRON
CTRON
reservedµITRONµBTRON
T-Kernel

SpecVer: The version of the TRON specification on which the product is based. This is given as athree-digit packed-format BCD code. In the case of a draft version, the letter A, B, or C may
appear in the second digit. In this case the corresponding hexadecimal form of A, B, or C isinserted.

Figure 4.13: spver Field Format
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.9. SYSTEM MANAGEMENT FUNCTIONS

205

prver is the version number of the T-Kernel implementation. The specific values assigned to prver areleft to the T-Kernel implementing vendor to decide.
prno is a return parameter for use in indicating T-Kernel product management information, productnumber or the like. The specific meaning of values set in prno is left to the T-Kernel implementing
vendor to decide.
[Additional Notes]
The format of the packet and structure members for getting version information is mostly uniform acrossthe various TRON specifications, but the CPU information and variation descriptors are not specified.
The value obtained by tk ref ver in SpecVer is the first three digits of the specification version number.
The numbers after that indicate minor revisions such as those issued to correct misprints and the like,and are not obtained by tk ref ver. For the purpose of matching to the specification contents, the first
three numbers of the specification version are sufficient.
An OS implementing a draft version may have A, B, or C as the second number of SpecVer. It must
be noted that in such cases the specification order of release may not correspond exactly to higher andlower SpecVer values. For example, specifications may be released in the following order:
Ver 1.A1 → Ver 1.A2 → Ver 1.B1 → Ver 1.C1 → Ver 1.00 → Ver 1.01 → · · ·In this example, when going from Ver 1.Cx to Ver 1.00, SpecVer goes from a higher to a lower value.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

206

4.10

CHAPTER 4. T-KERNEL/OS FUNCTIONS

Subsystem Management Functions

Subsystems consist of extended SVC handlers, break functions, startup functions, cleanup functions,
event functions, and resource control blocks. SVC handlers (Figure4.14).
An extended SVC handler accepts requests from applications and other programs as an application
programming interface (API) for a subsystem.
A break function, a startup function, a cleanup function, and an event function accept requests fromOS.

Applications/Subsystems/Device Drivers/Other↓
Extended SVC
Subsystem
Startup Cleanup
↑

↑

Break

Event

↑

↑

Resource
control
block #1

Resource
control
block #2···

T-KernelFigure 4.14: T-Kernel Subsystems

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.10. SUBSYSTEM MANAGEMENT FUNCTIONS

207

tk def ssy
Define Subsystem[C Language Interface]
ER ercd = tk_def_ssy ( ID ssid, T_DSSY *pk_dssy ) ;[Parameters]ID
T DSSY*ssid
pk dssy

Subsystem ID
Subsystem definition information

pk dssy detail:
ATR
PRI
FP
FP
FP
FP
FP
INT

ssyatrssyprisvchdrbreakfnstartupfn
cleanupfn
eventfn
resblksz

Subsystem attributes
Subsystem priority
Extended SVC handler address
Break function address
Startup function address
Cleanup function address
Event handling function address
Resource control block size (in bytes)(Other implementation-dependent parameters may be added beyond this point.)[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOMEME RSATRE PAR
E OBJ
E NOEXS

Normal completion
Invalid ID number (ssid is invalid or cannot be used)
Insufficient memory (memory for control block cannot be allocated)
Reserved attribute (svcatr is invalid or cannot be used)
Parameter error (pk dssy is invalid or cannot be used)ssid is already defined (when pk dssy 6= NULL)
ssid is not defined(when pk dssy = NULL)[Description]
Defines subsystem ssid.
One subsystem ID must be assigned to one subsystem without overlapping with other subsystems. The
OS does not have a function for assigning these automatically.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

208

CHAPTER 4. T-KERNEL/OS FUNCTIONS

Subsystem IDs 1 to 9 are reserved for T-Kernel use. 10 to 255 are numbers used by middleware, etc.
The maximum usable subsystem ID value is implementation-dependent and may be lower than 255 insome implementations.
ssyatr indicates system attributes in its low bits and implementation-dependent attributes in the highbits. The system attributes in ssyatr are not assigned in this version, and no system attributes areused.
ssypri indicates the subsystem priority. The startup function, cleanup function, and event handling
function are called in order of priority. The order of calling when priority is the same is undefined.
Subsystem priority 1 is the highest priority, with larger numbers indicating lower priorities. The rangeof priorities that can be specified is implementation-dependent, but it must be possible to assign at least
priorities 1 to 16.
NULL can be specified in breakfn, startupfn, cleanupfn, and eventfn, in which case the corresponding function will not be called.
Specifying pk dssy = NULL deletes a subsystem definition. The ssid subsystem resource control block
will also be deleted.
• Resource control block
The resource control block defines groups of resources and manages them by their attributes andother factors. Each resource group is allocated its own memory space of the size specified in
resblksz. If resblksz = 0 is specified, no resource control block is allocated; but a resource ID(see tk cre res) is assigned even in this case.
Each task belongs to one resource group or another. When a task makes a request to a subsystem
and resources are allocated to that task in the subsystem, the allocation information is stored
in the resource control block. The subsystem decides what kinds of resources to register in the
resource control block and how they are to be registered.
The OS is not involved in the contents of the resource control block; it can be used freely by thesubsystem. The size specified in resblksz should, however, be as small as possible. If a larger
memory block is needed, the subsystem must allocate that memory on its own and register its
address in the resource control block.
A resource control block is resident memory located in shared (system) space.
• Extended SVC handler
An extended SVC handler accepts requests from applications and other programs as an application
programming interface (API) for a subsystem. It can be called in the same way as an ordinary
system call, and is normally invoked using a trap instruction or the like.
The format of an extended SVC handler is as follows.
INT svchdr( VP pk_para, FN fncd ){/*Branching by fncd*/
return retcode; /* exit extended SVC handler */}fncd is a function code. The low 8 bits of the instruction code are the subsystem ID. The remaining
high bits can be used in any way by the subsystem. Ordinarily they are used as a function code

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.10. SUBSYSTEM MANAGEMENT FUNCTIONS

209

inside the subsystem. A function code must be a positive value, so the most significant bit isalways 0.
pk para points to a packet of parameters passed to this system call. The packet format can bedecided by the subsystem. Generally a format like the stack passed to a C language function isused, which in many cases is the same format as a C language structure.
The return code passed by an extended SVC handler is passed to the caller transparently as thefunction return code. As a rule, negative values are error codes and 0 or positive values are thereturn code for normal completion. If an extended SVC call fails for some reason, OS error code
(negative value) is returned to the caller without invoking the extended SVC handler, so it is best
to avoid confusion with these values.
The format by which an extended SVC is called is dependent on the OS implementation. As asubsystem API, however, it must be specified in a C language function format independent of the
OS implementation. The subsystem must provide an interface library for converting from the C
language function format to the OS-dependent extended SVC calling format.
An extended SVC handler runs as a quasi-task portion. It can be called from a task-independent
portion, and in this case the extended SVC handler also runs as a task-independent portion.
• Break function
A break function is a function called when a task exception is raised for a task while an extended
SVC handler is executing.
When a break function is called, the processing by the extended SVC handler running at the time
the task exception was raised must be stopped promptly and control must be returned from theextended SVC handler to its caller. The processing for stopping the processing by the currently
running extended SVC handler is called a break function.
The format of a break function is as follows.
void breakfn( ID tskid ){/*Stop the running extended SVC handler*/}
tskid is the ID of the task where the task exception was raised.
A break function is called when a task exception is raised by tk ras tex. If extended SVC handler
calls are nested, then when return is made from an extended SVC handler and the nesting level
drops by 1, the extended SVC handler corresponding to the return destination is the one called.
A break function is called one time only for one extended SVC handler per one task exception.
If another nested extended SVC call is made while a task exception is raised, no break function iscalled for the called extended SVC handler.
A break function runs as a quasi-task portion. Its task context is either that of the task thatcalled tk ras tex or that of the task where the task exception was raised (the task running an
extended SVC handler). In the former case, the break function runs when tk ras tex is called,
while in the latter case the break function runs when extended SVC nesting is reduced by one
level. This means it is possible that the task executing the break function will be different from thetask executing the extended SVC handler. In such a case the break function and extended SVC
handler run concurrently as controlled by task scheduling. It is thus conceivable that the extended
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

210

CHAPTER 4. T-KERNEL/OS FUNCTIONSSVC handler will return to its caller before the break function finished executing, but in thatcase the extended SVC handler waits at the point right before returning, until the break function
completes. How this wait state maps to the task state transitions is implementation-dependent,
but preferably it should remain in READY state (a READY state that does not go to RUN state).
The precedence of a task may change while it is waiting for a break function to complete, but
how task precedence is treated is implementation-dependent. Similarly, an extended SVC handler
cannot call an extended SVC until break function execution completes. In other words, during
the time from the raising of a task interrupt until the break function completes, the affected task
must stay in the extended SVC handler that was executing at the time of the task exception.
If a break function and extended SVC handler run in different task contexts and the break function
task priority is lower than the extended SVC handler task priority, the task priority of the breakfunction is raised to the same priority as the extended SVC handler task only during the time
while the break handler is executing. On the other hand, if the break function task priority is
the same as or higher than that of the extended SVC handler, the priority does not change. The
priority that gets changed is the current priority; the base priority stays the same. The change
in priority occurs only right before entry into the break function; any changes after that in theextended SVC handler task priority are not followed up by further changes in priority of the breakfunction task. In no case does a change in the break function priority while a break function isrunning result in a priority change in the extended SVC handler task. At the same time there is
no restriction on priority changes because a break function is running. When the break function
completes, the current priority of its task reverts to base priority. If a mutex was locked, however,the priority reverts to that as adjusted by the mutex. (In other words, the ability is provided toadjust the current priority at the entry and exit of the break function only; other than that, thepriority is the same as when an ordinary task is running.)• Startup function
A startup function is called by issuing the tk sta ssy system call. It performs resource control
block initialization processing.
The format of a startup function is as follows.
void startupfn( ID resid, INT info ){/*Resource control block initialization processing*/}
resid is the ID of the resource group to be initialized, and info is a parameter that can be usedin any way. Both are passed to tk sta ssy.
Even if initialization of the resource control block fails for some reason, the startup function must
be terminated normally. If the resource control block could not be initialized, then when an API(extended SVC) that cannot be executed normally as a result is called, error is passed in the returncode of that API.
A startup function runs as a quasi-task portion in the context of the task that called tk sta ssy.

• Cleanup function
A cleanup function is called by issuing the tk cln ssy system call, and performs resource releaseprocessing.
The format of a cleanup function is as follows.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.10. SUBSYSTEM MANAGEMENT FUNCTIONS

211

void cleanupfn( ID resid, INT info ){/*Resource release processing*/}
resid is the ID of the resource group subject to resource release, while info is a parameter thatcan be used freely. Both are parameters passed to tk cln ssy.
Even if resource release fails for some reason, the cleanup function must be terminated normally.
The error handling, such as logging of errors, can be decided for each subsystem.
After the cleanup function completes its processing, the resource control block is automatically
cleared to 0. If no cleanup function was defined (cleanupfn = NULL), the tk cln ssy system call
clears the resource control block to 0.
A cleanup function runs as a quasi-task portion in the context of the task that called tk cln ssy.
• Event handling function
An event handling function is called by issuing the tk evt ssy system call. It processes various
requests made to a subsystem. Note that it does not carry the obligation to process all requests
for all subsystems. If processing is not required, it can simply return E OK without performing any
operation.
The format of an event handling function is as follows.
ER eventfn( INT evttyp, ID resid, INT info ){/*Event processing*/
return ercd;}
evttyp indicates the request type, resid gives the ID of the resource group, and info is a parameterthat can be used freely. All these parameters are passed to tk evt ssy. If the system call is notinvoked for any particular resource group, resid can be set to 0.
If processing completes normally, E OK is passed in the return code; otherwise an error code
(negative value) is returned.
The following event types evttyp are defined. See 5.3 for details.
#define TSEVT_SUSPEND_BEGIN#define TSEVT_SUSPEND_DONE#define TSEVT_RESUME_BEGIN#define TSEVT_RESUME_DONE#define TSEVT_DEVICE_REGIST#define TSEVT_DEVICE_DELETE

1
2
3
4
5
6

/* before suspending device*//* after suspending device*//* before resuming device*//* after resuming device*//* device registration notice *//* device deletion notice*/

An event handling function runs as a quasi-task portion in the context of the task that calledtk evt ssy.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

212

CHAPTER 4. T-KERNEL/OS FUNCTIONS[Additional Notes]
Extended SVC handlers as well as break functions, startup functions, cleanup functions and event
handling functions all have the equivalent of the TA HLNG attribute only. There is no means of specifying
the TA ASM attribute.
Prior to initialization of a resource control block by a startup function, and after resource release by acleanup function, the behavior if an extended SVC is called by a task belonging to that resource groupis dependent on the subsystem implementation. The OS does not make any attempt to prevent thiskind of call. Basically it is necessary to avoid calling an extended SVC before calling a startup function
and after calling a cleanup function.
There may be cases where, for some reason or other, a break function, cleanup function or event handling
function is called without first calling a startup function. These functions must execute normally even insuch a case. A resource control block is cleared to 0 when it is first created and when cleanup processing
is executed by tk cln ssy. Accordingly, even if it was not initialized properly by a startup function,
the resource control block can still be assumed to have been cleared to 0.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.10. SUBSYSTEM MANAGEMENT FUNCTIONS

213

tk sta ssy
tk cln ssy
Call Startup Function of Sub-System
Call Cleanup Function of Sub-System[C Language Interface]
ER ercd = tk_sta_ssy ( ID ssid, ID resid, INT info ) ;ER ercd = tk_cln_ssy ( ID ssid, ID resid, INT info ) ;[Parameters]
ID
ID
INT

ssid
resid
info

Subsystem ID
Resource ID
Any parameter[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXSE CTXNormal completion
Invalid ID number (ssid or resid is invalid or cannot be used)
Object does not exist (the subsystem specified in ssid is not defined)
Context error (issued from task-independent portion or in dispatch disabled state)[Description]
Calls the startup function/cleanup function of the subsystem specified in ssid.
Specifying ssid = 0 makes the system call applicable to all currently defined subsystems. In this casethe startup/cleanup functions of each subsystem are called in sequence.
tk sta ssy: Calls in order starting from the highest subsystem priority.
tk cln ssy: Calls in order starting from the lowest subsystem priority.
The order among subsystems having the same priority is not defined.
If there are dependency relationships among different subsystems, the subsystem priority must therefore
be set with those relationships in mind. If, for example, subsystem B uses functions in subsystem A,
then the priority of subsystem A must be set higher than that of subsystem B.
Even if these system calls are issued for a subsystem with no startup function or cleanup function
defined, those functions are simply not called; no error results.
If during startup/cleanup function execution a task exception is raised for the task that called tk sta ssy
or tk cln ssy, the task exception is held until the startup/cleanup function completes its processing.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

214

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk evt ssy
Call Event Function of Sub-System[C Language Interface]
ER ercd = tk_evt_ssy ( ID ssid, INT evttyp, ID resid, INT info ) ;[Parameters]
ID
INT
ID
INT

ssid
evttypresid
info

Subsystem ID
Event request type
Resource ID
Any parameter[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS
E CTX
Other

Normal completion
Invalid ID number (ssid, resid is invalid or cannot be used)
Object does not exist (the subsystem specified in ssid is not defined)
Context error (issued from task-independent portion or in dispatch disabled state)
Error code returned by the event handling function[Description]
Calls the event handling function of the subsystem specified in ssid.
Specifying ssid = 0 makes the system call applicable to all currently defined subsystems. In this casethe event handling function of each subsystem is called in sequence.
When evttyp is an odd number: Calls in order starting from the highest subsystem priority.
When evttyp is an even number: Calls in order starting from the lowest subsystem priority.
The order among subsystems having the same priority is not defined.
If this system call is issued for a subsystem with no event handling function defined, the function is
simply not called; no error results.
If this system call is not invoked for any particular resource group, resid = 0 is specified.
If the event handling function returns an error, the error code is passed transparently in the systemcall return code. When ssid = 0 and an event handler returns an error, the event handling functionsof all other subsystems continue to be called. In the system call return code, only one error code isreturned even if more than one event handling function returned an error. It is not possible to know
which subsystem’s event handling function returned the error.
If during event handling function execution a task exception is raised for the task that called tk evt ssy,
the task exception is held until the event handling function completes its processing.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.10. SUBSYSTEM MANAGEMENT FUNCTIONS

215

tk ref ssy
Reference Subsystem Status[C Language Interface]
ER ercd = tk_ref_ssy ( ID ssid, T_RSSY *pk_rssy ) ;[Parameters]ID
T RSSY*ssid
pk rssy

Subsystem ID
Subsystem definition information[Return Parameters]
ER

ercd

Error code

pk rssy detail:
PRI
INT

ssypriresblksz

Subsystem priority
Resource control block size (in bytes)(Other implementation-dependent parameters may be added beyond this point.)[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (ssid is invalid or cannot be used)
Object does not exist (the subsystem specified in ssid is not defined)
Parameter error (pk rssy is invalid or cannot be used)[Description]
References information about the status of the subsystem specified in ssid. resblksz returns the sizeof the resource control block specified with tk def ssy. If the subsystem specified in ssid does not exist,
E NOEXS is returned.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

216

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk cre res
Create Resource Group[C Language Interface]
ID resid = tk_cre_res ( ) ;[Parameters]
None[Return Parameters]
ID

resid
or

Resource ID
Error Code[Error Codes]
E OK
E LIMITE NOMEM

Normal completion
Number of resource groups exceeds the system limit
Insufficient memory (memory for control block cannot be allocated)[Description]
Creates a new resource group, assigning to it a resource control block and resource ID.
Resource IDs are assigned in common for the entire system. A separate resource control block is createdfor each subsystem (see Figure 4.15).
Resource ID
#1

#2

#3

Subsystem A

ResBlkResBlkResBlkSubsystem B

ResBlkResBlkResBlkSubsystem C

ResBlkResBlkResBlkFigure 4.15: Subsystems and Resource Groups
In some cases a new subsystem will be defined when a resource group is already created. Even in sucha case, it is necessary to create a resource control block of an already existing resource group for the
newly registered subsystem. In other words, there may be cases where resource control block creationmust be performed by tk def ssy. For example, if a new subsystem ID is defined in a situation like thatc 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.10. SUBSYSTEM MANAGEMENT FUNCTIONS

217

shown in Figure 4.15, resource control blocks with resource IDs #1, #2, and #3 must automatically becreated for the subsystem.
[Additional Notes]
A resource ID is in some cases used also as a logical space ID (lsid). Resource IDs should therefore be
assigned values that can be used directly as logical space IDs or that can easily be converted for use as
logical space IDs.
A system resource group always exists as a special resource group. One system resource group always
exists, moreover, from the time the system boots, without waiting for creation by tk cre res. The
system resource group cannot be deleted. Other than the requirement that it must always exist, asystem resource group is no different from other resource groups.
Resource control block creation might be implemented in either of the following ways.
(A) At the time of subsystem definition (tk def ssy), create as many resource control blocks as the
maximum number of resource groups, and use tk cre res simply to assign them.
(B) Use tk cre res to create as many resource control blocks as there are subsystems and assign
them.
Since the specification requires clearing a resource control block to 0 when it is initially created, thetiming of this clearing to 0 differs between methods (A) and (B). This difference should not have much ofan effect; but since method (A) will have fewer cases of clearing to 0, subsystems must be implemented
assuming (A). Method (A) is also recommended for the OS implementation.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

218

CHAPTER 4. T-KERNEL/OS FUNCTIONS

tk del res
Delete Resource Group[C Language Interface]
ER ercd = tk_del_res ( ID resid ) ;[Parameters]
ID

resid

Resource ID[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS

Normal completion
Invalid ID number (resid is invalid or cannot be used)
Object does not exist (the resource specified in resid does not exist)[Description]
Deletes the resource control blocks of the resource group specified in resid, and releases the resource
ID.
The resource control blocks of all subsystems are deleted.
[Additional Notes]
Resources are deleted even if there are still tasks belonging to a resource to be deleted. In principle,
resource deletion must be performed after exit and deletion of all tasks belonging to the resources. The
behavior is not guaranteed if a resource is deleted while a task belonging to that resource remains andis calling a subsystem (extended SVC). Likewise, the behavior is not guaranteed if a task belonging toa deleted resource calls a subsystem (extended SVC).
The timing for actual resource control block deletion is implementation-dependent. (See tk cre res.)
The system resource group cannot be deleted (error code E ID is returned).

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

4.10. SUBSYSTEM MANAGEMENT FUNCTIONS

219

tk get res
Get Resource Management Block[C Language Interface]
ER ercd = tk_get_res ( ID resid, ID ssid, VP *p_resblk ) ;[Parameters]
ID
ID

resid
ssid

Resource ID
Subsystem ID[Return Parameters]
VP
ER

resblkercd

Resource control block
Error code

[Error Codes]
E OK
E ID
E NOEXS
E PAR

Normal completion
Invalid ID number (resid or ssid is invalid or cannot be used)
Object does not exist (the resource specified in resid or ssid does not exist)
Parameter error (value that cannot be used in p resblk)[Description]
Gets the address of the resource control block of resource group resid for subsystem ssid.
[Additional Notes]
E OK might be returned even if this system call is issued for a deleted resource ID. Whether or not error(E NOEXS) is returned in this case is implementation-dependent.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

220

c 2002–2005 by T-Engine Forum
Copyright °CHAPTER 4. T-KERNEL/OS FUNCTIONSTEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

Chapter 5

T-Kernel/SM Functions
Details of the functions provided by T-Kernel System Manager (T-Kernel/SM) are described in thischapter.

Overall notice and supplement• In principle, functions whose name are tk — is extended SVC, others are library functions (including in-line functions) or macros of the C language.
• Some libraries and macros call some extended SVC or system calls indirectly.
• Error codes such as E PAR, E MACV, and E NOMEM that always have the possibility of occurring are
not described here unless there is some special reason for doing so.
• Except where otherwise noted, extended SVC and libraries of T-Kernel/SM can not be called froma task-independent portion and while dispatching and interrupts are disabled. There may be some
limitations, however, imposed by particular implementations (E CTX) .
• Extended SVC and libraries of T-Kernel/SM can not be invoked from a lower protection level
than that at which T-Kernel/OS system calls can be invoked (lower than TSVCLimit)(E OACV).
• Extended SVC and libraries of T-Kernel/SM are reentrant except that the special explanation is
given. But some functions make exclusive control internally.
• Detection of error codes E PAR, E MACV, and E CTX is implementation-dependent; these may notalways be detected as error. For this reason, the service calls must not be invoked in such a waythat these errors might occur.

221

TEF020-S001-01.00.01/en

222

CHAPTER 5. T-KERNEL/SM FUNCTIONS

System Memory Management Functions

5.1

System memory management functions manage all the memory allocated dynamically by T-Kernel(system memory). This includes memory used internally by T-Kernel as well as task stacks, message
buffers, and memory pools.
System memory is managed in memory block units. The block size is normally the page size defined for
the MMU. A system that does not use an MMU can set any desired block size, but a size in the rangeof around 1 KB to 4 KB is recommended. Block size can be learned by calling tk ref smb.
System memory is allocated in the system space. T-Kernel does not manage task space memory.
System memory management functions are called as extended SVC. They are for use not only in TKernel but also in applications, subsystems and device drivers. In the case of T-Kernel internal use, thecalling of these functions without going through extended SVC calls is an implementation-dependent
option.

5.1.1

System Memory Allocation• ER tk_get_smb( VP *addr, INT nblk, UINT attr )Allocates a memory space of a size accommodating the number of contiguous memory blocks
specified in nblk, and having the attributes specified in attr. The start address of the allocatedmemory space is returned in addr.
attr := (TA_RNG0 || TA_RNG1 || TA_RNG2 || TA_RNG3) | [TA_NORESIDENT]#define TA_NORESIDENT#define TA_RNG0#define TA_RNG1#define TA_RNG2#define TA_RNG3

0x00000010
0x00000000
0x00000100
0x00000200
0x00000300/* nonresident*//* protection level 0 *//* protection level 1 *//* protection level 2 *//* protection level 3 */The acquired memory does not belong to a resource group. If memory could not be allocated,
E NOMEM is returned.
• ER tk_rel_smb( VP addr )Releases the memory specified by the start address addr. addr must be the address obtained bytk get smb.
• ER tk_ref_smb( T_RSMB *pk_rsmb )Gets information about system memory.
typedef struct t_rsmb {INT blksz;/* block size (in bytes)*/
INT total;/* total block count*/
INT free;/* remaining free block count *//* Implementation-dependent information may be added beyond this point.*/} T_RSMB;
When virtual memory is used, there may be cases where the total block and remaining freeblock counts cannot be decided unequivocally. In such cases the contents of total and free are
implementation-dependent, but preferably they should be values such that free ÷ total gives auseful estimate of the remaining memory capacity.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

5.1. SYSTEM MEMORY MANAGEMENT FUNCTIONS

5.1.2

223

Memory Allocation Libraries

Since system memory is allocated in block units, libraries are provided for dividing up those blocks foruse.
• void*Vmalloc( size_t size )• void*Vcalloc( size_t nmemb, size_t size )• void*Vrealloc( void *ptr, size_t size )• voidVfree( void *ptr )• void*Kmalloc( size_t size )• void*Kcalloc( size_t nmemb, size_t size )• void*Krealloc( void *ptr, size_t size )• voidKfree( void *ptr )The functions are equivalent to the standard C libraries malloc, calloc, realloc, free and soon. V— means the function is for nonresident memory and K— for resident memory; in both cases
the memory is assigned to the TSVCLimit protection level.
These functions cannot be called from a task-independent portion or while dispatching or interrupts
are disabled. The behavior if they are called in those situations is undefined. (System failure is apossibility.)c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

224

CHAPTER 5. T-KERNEL/SM FUNCTIONS

Address Space Management Functions

5.2

Memory access privilege is held as access privilege information for each task. Essentially access privilege
information indicates the right to access at the protection level immediately before an extended SVC iscalled. If, for example, a task is running at protection level 3 when it calls an extended SVC, its accessprivilege information indicates the right to access at protection level 3. Since the protection level whenan extended SVC is executing is protection level 0, in the case of nested calling of an extended SVC
from another extended SVC, access privilege information in the extended SVC for which a nested call
was made indicates the right to access at protection level 0.
Memory access privilege information is set as follows.
• Immediately after a task is started, its access privilege is that specified when the task was created.
• When an extended SVC is called, the access privilege at the protection level at which it was
running at the time of the call is set.
• Upon return from the extended SVC, the access privilege reverts to that at the time the extended
SVC was called.
• Executing SetTaskSpace() copies the current access privilege of the target task to the invoking
task.

5.2.1

Address Space Configuration• ER SetTaskSpace( ID tskid )Assigns to the invoking task the task space and access privilege information of the task specified
in tskid. As a result, both the invoking task and target task have the same task space and accessprivilege information.
Note that this copying of task space information applies only at the time the function is called; if
thereafter the task specified in tskid switches to a different address space and its access privilegechanges, the invoking task is not affected by those changes (its address space and access privilege
do not change accordingly). If the invoking task is calling an extended SVC, on return from theextended SVC its access privilege reverts to that prior to calling the extended SVC. Its task space,however, does not revert.
The task ID of the invoking task cannot be specified in tskid. However, if TSK SELF is used to
specify the invoking task, access privilege is set to the currently running protection level; task
space is not switched in this case.
E ID
E NOEXS
E OBJ

5.2.2

tskid is invalid
Object does not exist (the task specified in tskid does not exist)
Invoking task specified by other than TSK SELF

Address Space Checking

The following functions check whether access is allowed to the specified memory space, based on thecurrent access privilege information. If access cannot be made (no privilege or the memory does notexist), they return error code E MACV.
—R
—RW
—RE

Check for read access privilege.
Check for read and write access privilege.
Check for read and execute access privilege.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

5.2. ADDRESS SPACE MANAGEMENT FUNCTIONS

225• ER ChkSpaceR( VP addr, INT len )• ER ChkSpaceRW( VP addr, INT len )• ER ChkSpaceRE( VP addr, INT len )Checks access privilege to the memory space of len bytes from location addr.
• INT ChkSpaceBstrR( UB *str, INT max )• INT ChkSpaceBstrRW( UB *str, INT max )Checks access privilege to the memory space from str up to the string termination (’\0’) or up
to the number of characters (bytes) specified in max, whichever comes first. If max = 0 is set, max
is ignored and privilege is checked up to the string termination.
If access is allowed, the length of the string (in bytes) is returned. If the string termination occurred
up to the string length indicated in max, the length to the character before ’\0’ is returned; if max
characters occurred before the string termination, max is returned.
• INT ChkSpaceTstrR( TC *str, INT max )• INT ChkSpaceTstrRW( TC *str, INT max )typedef UHTC;#define TNULL((TC)0)/* TRON character code *//* TRON code string termination */Checks access privilege to the memory space from str up to the TRON Code string termination(TNULL) or up to the number of characters (TC count) specified in max, whichever comes first. If
max = 0 is set, max is ignored and privilege is checked up to the string termination.
If access is allowed, the length of the string (TC count) is returned. If the string termination
occurred up to the string length indicated in max, the length to the character before TNULL isreturned; if max characters occurred before the string termination, max is returned.
str must be an even-numbered address.

5.2.3

Lock Address Space

Generally memory is made resident or nonresident a page at a time and is managed in page units. For
this reason, in many cases the OS does not check for matching of locked and unlocked spaces. It is the
responsibility of the calling side to make sure the same spaces are specified in lock and unlock operations.
• ER LockSpace( VP addr, INT len )Locks (makes resident) the memory space of len bytes from location addr.
E MACVThe memory does not exist• ER UnlockSpace( VP addr, INT len )Unlocks (makes nonresident) the memory space of len bytes from location addr. If the same space
was locked more than once, it is not unlocked until the number of unlock operations equals thenumber of lock operations.
Note that it is not possible to unlock just part of a locked space.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

226

CHAPTER 5. T-KERNEL/SM FUNCTIONS

5.2.4

Get Physical Address• INT CnvPhysicalAddr( VP vaddr, INT len, VP *paddr )
vaddr
len
paddr
return code

Local address
Memory space size (in bytes)
Returns physical address
Returns size (in bytes) of physical address contiguous space, or error

Gets the physical address corresponding to logical address vaddr, returning the result in paddr.
This function also passes in the return code the size of contiguous space included in len bytes
from vaddr. Accordingly, only the space of the size passed in the return code starting from paddr
is valid.
The space for which the physical address is obtained must be locked (made resident).
On the assumption of DMA transfer, memory caching is turned off for the space whose physicaladdress is obtained (the memory space starting from paddr of the size passed in the return code).
When the space is made nonresident (unlocked), caching goes back on.
If it is not possible to make memory cached off partly by a hardware limitation, this API flush
the cache memory (that is, write back it and make it disable).
E MACV

5.2.5

The memory does not exist

Map Memory• ER MapMemory( VP paddr, INT len, UINT attr, VP *laddr )Maps len bytes area which starts from paddr in the physical address to logical area returning the
logical address in *laddr.
The logical address is not to be specified, automatically allocated.
If paddr = NULL is specified, some continuous memory in physical memory is automaticallyallocated and mapped to logical area.
The mapped logical area has attributes specified with attr
attr := (MM_USER || MM_SYTEM ) | [MM_READ] | [MM_WRITE] | [MM_EXECUTE] | [MM_CDIS]
MM USERMM SYSTEMMM READMM WRITE
MM EXECUTE
MM CDIS

User level access
System level access
Read access
Write access
Execution
Disable cache

These symbols differ from every machines. It requires these symbols to use. Some machines needother attributes except for these show above.
E LIMITE NOMEM

Insufficient logical area for mapping
Insufficient memory

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

5.2. ADDRESS SPACE MANAGEMENT FUNCTIONS

227• ER UnmapMemory( VP laddr )Unmaps logical area which allocated by MapMemory().
The logical address allocated by MapMemory() must be set to laddr. If some memory is allocatedby MapMemory(), the memory is also unmapped.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

228

CHAPTER 5. T-KERNEL/SM FUNCTIONS

Device Management Functions

5.3
5.3.1

Basic Concepts
Applications/Subsystems↓

Application interface (Extended SVC)↑
Device Management Functions
T-Kernel/SM↓↓
Device driver interface↑
Interface Layer
Logical Layer

Device Driver

Physical Layer↓

Figure 5.1: Device Management Functions(1) Device Name (UB* type)A device name is a string of up to 8 characters consisting of the following elements.
#define L_DEVNM 8/* Device name length */Type Name indicating the device type
Characters a to z and A to Z can be used.
Unit One letter indicating a physical device
Each unit is assigned a letter from a to z in order starting from a.
Subunit One to three digits indicating a logical device
Each subunit is assigned a number from 0 to 254 in order starting from 0.
Device names take the format type + unit + subunit. Some devices may not have a unit or subunit, inwhich case the corresponding field is omitted.
A name consisting of type + unit is called a physical device name. A name consisting of type + unit +subunit may be called a logical device name to distinguish it from a physical device name. If there isno subunit, the physical device name and logical device name are identical. The term “device name”
by itself means the logical device name.
A subunit generally refers to a partition on a hard disk, but can be used to mean other logical devices
as well.
Examples:
hda
hda0
fda
rsa
kbpd

Hard disk (entire disk)
Hard disk (1st partition)
Floppy disk
Serial port
Keyboard/pointing device

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

5.3. DEVICE MANAGEMENT FUNCTIONS

229(2) Device ID (ID type)
By registering a device (device driver) with T-Kernel/SM, a device ID (> 0) is assigned to the device(physical device name). Device IDs are assigned to each physical device. The device ID of a logical device
consists of the device ID assigned to the physical device to which is appended the subunit number + 1(1 to 255).
devid: The device ID assigned at device registration
devid
devid + n + 1

Physical device
The nth subunit (logical device)

Examples:
had
hda0
hda1

devid
devid + 1
devid + 2

Entire hard disk
1st partition of hard disk
2nd partition of hard disk

(3) Device Attribute (ATR type)
Device attributes are defined as follows, in order to classify devices by their properties.
IIII IIII IIII IIII PRxx xxxx KKKK KKKKThe high 16 bits are device-dependent attributes defined for each device.
The low 16 bits are standard attributes defined as follows.
#define TD_PROTECT#define TD_REMOVABLE

0x80000x4000/* P: write protection/* R: removable media*/*/#define TD_DEVKIND#define TD_DEVTYPE

0x00ff
0x00f0/* K: device/media kind/* device type*/*/#define TDK_UNDEF#define TDK_DISK

0x00000x0010/* device type/* undefined/unknown/* disk device

*/
*/
*/

#define TDK_DISK_UNDEF#define TDK_DISK_RAM#define TDK_DISK_ROM#define TDK_DISK_FLA#define TDK_DISK_FD#define TDK_DISK_HD#define TDK_DISK_CDROM

0x00100x00110x00120x00130x00140x00150x0016/* disk kind*//* miscellaneous disk*//* RAM disk (used as main memory) *//* ROM disk (used as main memory) *//* Flash ROM or other silicon disk *//* floppy disk*//* hard disk*//* CD-ROM*/

Currently no device types other than disks are defined. Other devices are assigned to undefined type
(TDK UNDEF). Note that device types are defined for the sake of distinguishing devices from the standpointof the user as necessary, such as when applications must change their processing based on the type ofdevice or media. Devices for which no such distinctions are necessary do not have to have a device typeassigned.
See the individual device driver specifications regarding device-dependent attributes.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

230

CHAPTER 5. T-KERNEL/SM FUNCTIONS(4) Device Descriptor (ID type)A device descriptor (> 0) is an identifier used for accessing a device, assigned by T-Kernel/SM when adevice is opened.
A device descriptor belongs to a resource group. Operations using a device descriptor can be performed
only by tasks belonging to the same resource group as the device descriptor. Error code (E OACV) is
returned for requests from tasks belonging to a different resource group.
(5) Request ID (ID type)
When an IO request is made to a device, a request ID (> 0) is assigned identifying the request. This
ID can be used to wait for IO completion.
(6) Data Number (INT type)
Device data is specified by a data number. Data is classified into device-specific data and attribute data
as follows.
Device-specific data: Data number ≥ 0
As device-specific data, the data numbers are defined separately for each device.
ExamplesDisk
Serial port

Data number = physical block number
Data number = 0 only

Attribute data: Data number < 0
Attribute data specifies driver or device state acquisition and setting modes, and special functions,etc.
Data numbers common to devices are defined, but device-dependent attribute data can also be
defined. Details are given later.

5.3.2

Application Interface

The functions below are provided as application interface functions, called as extended SVC. These
functions cannot be called from a task-independent portion or while dispatch or interrupts are disabled(E CTX).
ID tk_opn_dev( UB *devnm, UINT omode )ER tk_cls_dev( ID dd, UINT option )ID tk_rea_dev( ID dd, INT start, VP buf, INT size, TMO tmout )ER tk_srea_dev( ID dd, INT start, VP buf, INT size, INT *asize )ID tk_wri_dev( ID dd, INT start, VP buf, INT size, TMO tmout )ER tk_swri_dev( ID dd, INT start, VP buf, INT size, INT *asize )ID tk_wai_dev( ID dd, ID reqid, INT *asize, ER *ioerr, TMO tmout )INT tk_sus_dev( UINT mode )INT tk_get_dev( ID devid, UB *devnm )ID tk_ref_dev( UB *devnm, T_RDEV *rdev )ID tk_oref_dev( ID dd, T_RDEV *rdev )INT tk_lst_dev( T_LDEV *ldev, INT start, INT ndev )INT tk_evt_dev( ID devid, INT evttyp, VP evtinf )c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

5.3. DEVICE MANAGEMENT FUNCTIONS

231• ID tk_opn_dev( UB *devnm, UINT omode )devnm
Device nameomodeOpen mode
return code Device descriptor or error
Opens the device specified in devnm in the mode specified in omode, and prepares for device access.
The device descriptor is passed in the return code.
omode := (TD_READ || TD_WRITE || TD_UPDATE) | [TD_EXCL || TD_WEXCL]| [TD_NOLOCK]#define TD_READ#define TD_WRITE#define TD_UPDATE#define TD_EXCL#define TD_WEXCL#define TD_REXCL#define TD_NOLOCK

0x00010x00020x00030x01000x02000x04000x1000/* read only*//* write only*//* read/write*//* exclusive*//* exclusive write*//* exclusive read*//* lock (making resident) not necessary */TD READ Read only
TD WRITE Write only
TD UPDATE Sets read and write access mode.
When TD READ is set, tk wri dev() cannot be used.
When TD WRITE is set, tk rea dev() cannot be used.
TD EXCL Exclusive
TD WEXCL Exclusive write
TD REXCL Exclusive read
Sets the exclusive mode.
When TD EXCL is set, all concurrent opening is prohibited.
When TD WEXCL is set, concurrent opening in write mode (TD WRITE or TD UPDATE) is prohibited.
When TD REXCL is set, concurrent opening in read mode (TD READ or TD UPDATE) is prohibited.

Present Open Mode
No exclusive mode
TD WEXCLTD REXCLTD EXCLc 2002–2005 by T-Engine Forum
Copyright °

R
W
R
W
R
W
R
W

Concurrent Open Mode
No exclusive mode TD WEXCL TD EXCL
R
W
R
W
R
W
Yes
Yes
Yes Yes No No
Yes
Yes
No No No No
YesNo
Yes No No No
Yes
No
No No No No
No
Yes
No Yes No No
No
Yes
No No No No
No
No
No No No No
No
No
No No No No
TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

232

CHAPTER 5. T-KERNEL/SM FUNCTIONS
R = TD READ
Yes = Can be opened

W = TD WRITE or TD UPDATENo = Cannot be opened (E BUSY)TD NOLOCK Lock (making resident) not necessary
Indicates that a memory space (buf) specified in IO operations (tk rea dev and tk wri dev)
has already been locked (made resident) on the calling side and does not have to be locked
by the device driver. In this case the device driver does not (must not) lock the area. This isused e.g. to perform disk access for page in/page out in a virtual memory system. Generally
it does not need to be specified.
The device descriptor belongs to the resource group of the task that opened the device.
When a physical device is opened, the logical devices belonging to it are all treated as having been
opened in the same mode, and are processed as exclusive open.
E BUSYE NOEXSE LIMIT
Other

Device busy (exclusive open)
Device does not exist
Open count exceeds the limit
Errors returned by device driver• ER tk_cls_dev( ID dd, UINT option )ddoptionreturn code

Device descriptor
Close option
Error

Closes device descriptor dd.
If a request is being processed, the processing is aborted and the device is closed.
option := [TD_EJECT]#define TD_EJECT

0x0001/* eject media */TD EJECT Eject media
If the same device has not been opened by another task, the media is ejected. In the case ofdevices that cannot eject their media, the request is ignored.
The subsystem cleanup processing (tk cln ssy) closes all the device descriptors belonging to theresource group.
E ID
Other

dd is invalid or not open
Errors returned by device driver• ID tk_rea_dev( ID dd, INT start, VP buf, INT size, TMO tmout )
dd
start
buf
size
tmout
return code

Device descriptor
Read start location (≥ 0: Device-specific data, < 0: Attribute data)
Buffer location for putting the read data
Read size
Request acceptance timeout (ms)Request ID or error

Starts reading device-specific data or attribute data from the specified device. This function starts
reading only, returning to its caller without waiting for the read operation to finish. The spacec 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

5.3. DEVICE MANAGEMENT FUNCTIONS

233

specified in buf must be retained until the read operation completes. Read completion is waitedfor by tk wai dev.
The time required for read start processing differs with the device; return of control is not necessarily immediate.
In the case of device-specific data, the start and size units are decided for each device. With
attribute data, start is an attribute data number and size is in bytes. The attribute data of thedata number specified in start is read. Normally size must be at least as large as the size of theattribute data to be read. Reading of multiple attribute data in one operation is not possible.
When size = 0 is specified, actual reading does not take place but the current size of data thatcan be read is checked.
Whether or not a new request can be accepted while a read or write operation is in progress
depends on the device driver. If a new request cannot be accepted, the request is queued. The
timeout for request waiting is set in tmout. The TMO POL or TMO FEVR attribute can be specified
for tmout. Note that what times out is request acceptance. Once a request has been accepted,
this function does not time out.
E ID
E OACVE LIMITE TMOUTE ABORT
Other

dd is invalid or not open
Open mode is invalid (read not permitted)
Number of requests exceeds the limit
Busy processing other requests
Processing aborted
Errors returned by device driver• ER tk_srea_dev( ID dd, INT start, VP buf, INT size, INT *asize )Synchronous read. This is equivalent to the following.
ER tk_srea_dev( ID dd, INT start, VP buf, INT size, INT *asize ){ER er, ioer;
er = tk_rea_dev(dd, start, buf, size, TMO_FEVR);
if ( er > 0 ) {er = tk_wai_dev(dd, er, asize, &ioer, TMO_FEVR);
if ( er > 0 ) er = ioerr;}return er;}• ID tk_wri_dev( ID dd, INT start, VP buf, INT size, TMO tmout )
dd
start
buf
size
tmout
return code

Device descriptor
write start location (≥ 0: Device-specific data, < 0: Attribute data)
Buffer holding data to be written
Size of data to be written
Request acceptance timeout (ms)Request ID or error

Starts writing device-specific data or attribute data to a device. This function starts writing
only, returning to its caller without waiting for the write operation to finish. The space specified
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

234

CHAPTER 5. T-KERNEL/SM FUNCTIONS
in buf must be retained until the write operation completes. Write completion is waited for by
tk wai dev.
The time required for write start processing differs with the device; return of control is not necessarily immediate.
In the case of device-specific data, the start and size units are decided for each device. With
attribute data, start is an attribute data number and size is in bytes. The attribute data of thedata number specified in start is written. Normally size must be at least as large as the sizeof the attribute data to be written. Multiple attribute data cannot be written in one operation.
When size = 0 is specified, actual writing does not take place but the current size of data thatcan be written is checked.
Whether or not a new request can be accepted while a read or write operation is in progress
depends on the device driver. If a new request cannot be accepted, the request is queued. The
timeout for request waiting is set in tmout. The TMO POL or TMO FEVR attribute can be specified
for tmout. Note that what times out is request acceptance. Once a request has been accepted,
this function does not time out.
E ID
E OACVE RONLY
E LIMITE TMOUTE ABORT
Other

dd is invalid or not open
Open mode is invalid (write not permitted)
Read-only device
Number of requests exceeds the limit
Busy processing other requests
Processing aborted
Errors returned by device driver• ER tk_swri_dev( ID dd, INT start, VP buf, INT size, INT *asize )Synchronous write. This is equivalent to the following.
ER tk_swri_dev( ID dd, INT start, VP buf, INT size, INT *asize ){ER er, ioer;
er = tk_wri_dev(dd, start, buf, size, TMO_FEVR);
if ( er > 0 ) {er = tk_wai_dev(dd, er, asize, &ioer, TMO_FEVR);
if ( er > 0 ) er = ioer;}
return er;}• ID tk_wai_dev( ID dd, ID reqid, INT *asize, ER *ioer, TMO tmout )
dd
reqid
asize
ioer
tmout
return code

Device descriptor
Request ID
Returns the read/write data size
Returns IO error
Timeout (ms)Completed request ID or error

Waits for completion of request reqid for device dd.
If reqid = 0 is set, this function waits for completion of any pending request to dd.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

5.3. DEVICE MANAGEMENT FUNCTIONS

235

This function waits for completion only of requests currently processing when the function is called.
A request issued after tk wai dev was called is not waited for.
When multiple requests are being processed concurrently, the order of their completion is notnecessarily the same as the order of request but is dependent on the device driver. Processing
is, however, guaranteed to be performed in a sequence such that the result is consistent with theorder of requesting. When processing a read operation from a disk, for example, the sequence
might be changed as follows.
Block number request sequence
Block number processing sequence

1
1

4
2

3
3

2
4

5
5

Disk access can be made more efficient by changing the sequence as above with the aim of reducing
seek time and spin wait time.
The timeout for waiting for completion is set in tmout. The TMO POL or TMO FEVR attribute canbe specified for tmout. If a timeout error is returned (E TMOUT), tk wai dev must be called again
to wait for completion, since the request processing is ongoing.
When reqid > 0 and tmout = TMO FEVR are both set, the processing must be completed without
timing out.
If the requested processing results in error (IO error, etc.) ioer is stored rather than a returncode. The return code is used for errors when the request wait itself was not handled properly.
When error is passed in the return code, ioer has no meaning. Note also that if error is passedin the return code, tk wai dev must be called again to wait for completion, since the request
processing is ongoing.
If a task exception is raised during completion waiting by tk wai dev, the request in reqid isaborted and processing is completed. The result of aborting the requested processing is dependent
on the device driver. When reqid = 0 was set, however, requests are not aborted but are treatedas timeout. In this case E ABORT rather than E TMOUT is returned.
It is not possible for multiple tasks to wait for completion of the same request ID at the sametime. If there is a task waiting for request completion with reqid = 0 set, another task cannot
wait for completion for the same device descriptor. Similarly, if there is a task waiting for request
completion with reqid > 0 set, another task cannot wait for completion specifying reqid = 0.
E ID
E OBJ
E NOEXSE TMOUTE ABORT
Other

dd is invalid or not open
reqid is invalid or not a request for dd
Another task is already waiting for request reqid
No requests are being processed (only when reqid = 0)
Timeout (processing continues)
Processing aborted
Errors returned by device driver• INT tk_sus_dev( UINT mode )modereturn code

Mode
Suspend disable request count or error

Performs the processing specified in mode, then passes the resulting suspend disable request countin the return code.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

236

CHAPTER 5. T-KERNEL/SM FUNCTIONS
mode := ( (TD_SUSPEND | [TD_FORCE]) || TD_DISSUS || TD_ENASUS || TD_CHECK)#define TD_SUSPEND#define TD_DISSUS#define TD_ENASUS#define TD_CHECK#define TD_FORCE

0x00010x00020x00030x00040x8000/* suspend*//* disable suspension*//* enable suspension*//* get suspend disable request count *//* forcibly suspend*/

TD SUSPEND Suspend
If suspending is enabled, suspends processing. If suspending is disabled, returns E BUSY.
TD SUSPEND|TD FORCE Forcibly suspend
Suspends even in suspend disabled state.
TD DISSUS Disable suspension
Disables suspension.
TD ENASUS Enable suspension
Enables suspension.
If the enable request count is above the disable count for the resource group, no operation is
performed.
TD CHECK Get suspend disable countGets only the number of times suspend disable has been requested.
Suspension is performed in the following steps.
1. Processing prior to start of suspension in each subsystemtk_evt_ssy(0, TSEVT_SUSPEND_BEGIN, 0, 0)
2. Suspension processing in non-disk devices
3. Suspension processing in disk devices
4. Processing after completion of suspension in each subsystemtk_evt_ssy(0, TSEVT_SUSPEND_DONE, 0, 0)
5. SUSPEND state enteredtk_set_pow(TPW_DOSUSPEND)
Resumption from SUSPEND state is performed in the following steps.
1. Return from SUSPEND state Return from tk_set_pow(TPW_DOSUSPEND)
2. Processing prior to start of resumption in each subsystemtk_evt_ssy(0, TSEVT_RESUME_BEGIN, 0, 0)
3. Resumption processing in disk devices
4. Resumption processing in non-disk devices
5. Processing after completion of resumption in each subsystemtk_evt_ssy(0, TSEVT_RESUME_DONE, 0, 0)
The number of suspend disable requests is counted. Suspension is enabled only if the same
number of suspend enable requests is made. At system boot, the suspend disable count is 0
and suspension is enabled. There is only one suspend disable request count kept per system,
but the system keeps track of the resource group making the request. It is not possible to clear
suspend disable requests made in another resource group. When the cleanup function runs
in a resource group, all the suspend requests made in that group are cleared and the suspend
disable request count is reduced accordingly. The maximum suspend disable request countis implementation-dependent, but must be at least 255. When the upper limit is exceeded,
E QOVR is returned.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

5.3. DEVICE MANAGEMENT FUNCTIONS

237

E BUSY Suspend already disabled
E QOVR Suspend disable request count limit exceeded• ID tk_get_dev( ID devid, UB *devnm )
devid
devnm
return code

Device ID
Device name storage location
Device ID of physical device or error

Gets the device name of the device specified in devid and puts the result in devnm.
devid is the device ID of either a physical device or a logical device. If devid is a physical device,
the physical device name is put in devnm. If devid is a logical device, the logical device name isput in devnm. devnm requires a space of L DEVNM + 1 bytes or larger.
The device ID of the physical device to which device devid belongs is passed in the return code.
E NOEXS

The device specified in devid does not exist• ID tk_ref_dev( UB *devnm, T_RDEV *rdev )• ID tk_oref_dev( ID dd, T_RDEV *rdev )
devnm
dd
rdev
return code

Device name
Device descriptor
Device information
Device ID or error

typedef struct t_rdev {ATR devatr; /* device attributes */INT blksz; /* block size of device-specific data (-1: unknown) */INT nsub;/* subunit count */INT subno; /* 0: physical device: 1 to nsub: subunit number+1 *//* Implementation-dependent information may be added beyond this point.*/} T_RDEV;
Gets device information about the device specified in devnm or dd and puts the result in rdev.
If rdev = NULL is set, the device information is not stored. nsub indicates the number of physicaldevice subunits belonging to the device specified in devnm or dd.
The device ID of the device specified in devnm is passed in the return code. E NOEXS The device
specified in devnm does not exist.
• INT tk_lst_dev( T_LDEV *ldev, INT start, INT ndev )
ldev
start
ndev
return code

Location of registered device information (array)
Starting number
Number to acquire
Remaining device registration count or error

typedef struct t_ldev {ATR devatr;/* device attributes*/
INT blksz;/* device-specific data block size (-1: unknown) */INT nsub;/* subunits*/
UB devnm[L_DEVNM]; /* physical device name*/c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

238

CHAPTER 5. T-KERNEL/SM FUNCTIONS/* Implementation-dependent information may be added beyond this point.*/} T_LDEV;
Gets information about registered devices.
Registered devices are managed per physical device. The registered device information is therefore
also obtained per physical device.
When the number of registered devices is N , number are assigned serially to devices from 0 to
N − 1. Starting from the number specified in start in accord with this scheme, the number ofregistrations specified in ndev is acquired and put in ldev. The space specified in ldev must belarge enough to hold ndev registration information. The number of remaining registrations after
start ( N − start ) is passed in the return code. If the number of registrations from start is
fewer than ndev, all remaining registrations are stored. A value passed in return code less than orequal to ndev means all remaining registrations were obtained. Note that this numbering changes
as devices are registered and deleted. For this reason, accurate information may not always be
obtained if the acquisition is carried out over multiple operations.
E NOEXS

start exceeds the number of registered devices• INT tk_evt_dev( ID devid, INT evttyp, VP evtinf )devid
evttypevtinfreturn code

Event destination device ID
Driver request event type
Information for each event type
Return code from device driver or error

Sends a driver request event to the device (device driver) specified in devid.
The following driver request events are defined.
#define TDV_CARDEVT 1#define TDV_USBEVT 2/* PC Card event (see Card Manager) *//* USB event (see USB Manager)*/

The functioning of driver request events and the contents of evtinf are defined for each event
type.
E NOEXS
E PAR

5.3.3

The device specified in devid does not exist
Internal device manager events (evttyp < 0) cannot be specified

Device Registration

The following device registration information is defined in registering a device.
Device registration is performed for each physical device.
typedef struct t_ddev {VP exinf;/* extended information
ATR drvatr;/* driver attributes
ATR devatr;/* device attributes
INT nsub;/* subunits
INT blksz;/* block size of device-specific data (-1: unknown)
FP openfn;/* open countFP closefn;/* close countFP execfn;/* processing start function
FP waitfn;/* completion wait function
c 2002–2005 by T-Engine Forum
Copyright °

*/
*/
*/
*/
*/
*/
*/
*/
*/

TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

5.3. DEVICE MANAGEMENT FUNCTIONS

239*/
FP abortfn;/* abort processing function
FP eventfn;/* event function*//* Implementation-dependent information may be added beyond this point. */} T\_DDEV;
exinf is used to store any desired information. The value is passed to the processing functions. Device
management pays no attention to the contents.
drvatr sets device driver attribute information. The low bits indicate system attributes, and the highbits are used for implementation-dependent attributes. The implementation-dependent attribute portionis used, for example, to indicate validity flags when implementation-dependent data is added to T DDEV.
drvatr := [TDA_OPENREQ]#define TDA_OPENREQ 0x0001/* open/close each time */TDA OPENREQ
When a device is opened multiple times, normally openfn is called the first time it is opened andclosefn the last time it is closed.
If TDA OPENREQ is specified, then openfn/closefn will be called for all open/close operations evenin case of multiple openings.
Device attributes are specified in devatr. The details of device attribute setting are as noted above.
The number of subunits is set in nsub. If there are no subunits, 0 is specified.
blksz sets the block size of device-specific data in bytes. In the case of a disk device, this is the physicalblock size. It is set to 1 byte for a serial port, etc. For a device with no device-specific data it is set to
0. For an unformatted disk or other device whose block size is unknown, −1 is set.
If blksz ≤ 0, device-specific data cannot be accessed. When device-specific data is accessed by
tk rea dev or tk wri dev, size × blksz must be the size of the area being accessed, that is, thesize of buf.
openfn, closefn, execfn, waitfn, abortfn, and eventfn set the entry address of processing functions.
Details of the processing functions are discussed later.
• ID tk_def_dev( UB *devnm, T_DDEV *ddev, T_IDEV *idev )devnm
Physical device nameddev
Device registration information
idev
Returns device initialization information
return code Device ID or error
Registers a device with the device name set in devnm.
If a device with device name devnm is already registered, the registration is updated with new
information, in which case the device ID does not change.
When ddev = NULL is specified, device devnm registration is deleted.
The device initialization information is returned in idev.
This includes information set by default when the device driver is started, and can be used asnecessary.
When idev = NULL is set, device initialization information is not stored.
typedef struct t_idev {ID evtmbfid;/* event notification message buffer ID *//* Implementation-dependent information may be added beyond this point.*/} T_IDEV;
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

240

CHAPTER 5. T-KERNEL/SM FUNCTIONS
evtmbfid specifies the system default message buffer ID for event notification. If there is no
system default event notification message buffer, 0 is set.
Notification like the following is made to each subsystem when a device is registered or deleted.
devid is the device ID of the physical device registered or deleted.
Device registration or update:
Device deletion:
E LIMITE NOEXS

tk_evt_ssy(0, TSEVT_DEVICE_REGIST, 0, devid)
tk_evt_ssy(0, TSEVT_DEVICE_DELETE, 0, devid)

Number of registrations exceeds the system limit
The device specified in devnm does not exist (when ddev = NULL)• ER tk_ref_idv( T_IDEV *idev )idev
return code

Returns device initialization information
Error

Gets device initialization information.
The contents are the same as the information obtained by tk dev def().

5.3.4

Device Driver Interface

The device driver interface consists of processing functions specified when registering a device. These
functions are called by device management and run as a quasi-task portion. They must be reentrant.
The mutually exclusive calling of these processing functions is not guaranteed. If, for example, there
are simultaneous requests from multiple devices for the same device, different tasks might call the sameprocessing function at the same time. The device driver must apply mutual exclusion control in suchcases as necessary.
IO requests to a device driver are made by means of the following request packet mapped to a request
ID.
typedef struct t_devreq {structt_devreq *next; /* I: Link to request packet (NULL: termination) */VP
exinf;/* X: Extended information*/
ID
devid;/* I: Target device ID*/
INT
cmd:4;/* I: Request command*/
BOOL
abort:1;/* I: TRUE if abort request*/
BOOL
nolock:1;/* I: TRUE if lock (making resident) not needed */INT
rsv:26;/* I: reserved (always 0)*/
T_TSKSPC tskspc;/* I: Task space of requesting task*/
INT
start;/* I: Starting data number
*/
INT
size;
/* I: Request size
*/
VP
buf;
/* I: IO buffer address*/
INT
asize;/* O: Size of result*/ER
error;/* O: Error result*//* Implementation-dependent information may be added beyond this point.
*/} T_DEVREQ;
I indicates an input parameter and O an output parameter. Input parameters must not be changedby the device driver. Parameters other than input parameters (I) are initially cleared to 0 by device
management. After that, device management does not modify them.
next is used to link the request packet. In addition to use for keeping track of request packets in device
management, it is used also by the completion wait function (waitfn) and abort function (abortfn).
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

5.3. DEVICE MANAGEMENT FUNCTIONS

241

exinf can be used freely by the device driver. Device management does not pay attention to thecontents.
The device ID of the device to which the request is issued is specified in devid.
The request command is specified in cmd as follows.
cmd := (TDC_READ || TDC_WRITE)#define TDC_READ#define TDC_WRITE

1
2/* read request *//* write request */If abort processing is to be carried out, abort is set to TRUE right before calling the abort function(abortfn). abort is a flag indicating whether abort processing was requested, and does not indicatethat processing was aborted.
In some cases abort is set to TRUE even when the abort function (abortfn) is not called. Abort
processing is performed when a request with abort set to TRUE is actually passed to the device driver.
nolock indicates that the memory space specified in buf has already been locked (made resident) anddoes not need to be locked by the device driver. In this case the device driver must not lock the memory
space. (nolock is specified when there is a possibility of wrong operation if the device driver performs
a lock. Accordingly, when nolock = TRUE, the device driver must not lock the space.)
tskspc sets the task space of the requesting task. Since processing functions are called in the context
of the requesting task, tskspc is the same as the task space of the processing function. If, however, theactual IO processing (read/write in the space specified in buf) is performed by a separate task in thedevice driver, it is necessary to switch the task space of the task performing the IO processing to thetask space of the requesting task.
The start and size parameters specified with tk rea dev or tk wri dev are set transparently in startand size here.
The buf parameter specified with tk rea dev or tk wri dev is set in buf here.
The memory space specified in buf may be nonresident in some cases or task space in others. Care must
therefore be taken regarding the following points.
• Nonresident memory cannot be accessed from a task-independent portion or while dispatching orinterrupts are disabled.
• Task space memory cannot be accessed from another task space.
For these reasons, switching of task space or making memory space resident must be performed asnecessary. Special attention is needed when access is made by an interrupt handler. Generally it is best
not to access buf directly from an interrupt handler.
Before accessing the buf memory space, the validity of buf must be checked using an address space check
function (ChkSpace—, described later below).
The device driver sets in asize the value returned in asize by tk wai dev.
The device driver sets in error the error code passed by tk wai dev in its return code. E OK indicates anormal result.
• Open Function: ER openfn( ID devid, UINT omode, VP exinf )
devid
omode
exinf
return code

Device ID of the device to open
Open mode (same as tk opn dev)
Extended information set at device registration
Error

The open function openfn is called when tk opn dev is invoked.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

242

CHAPTER 5. T-KERNEL/SM FUNCTIONS
The function openfn performs processing to enable use of a device. Details of the processing aredevice-dependent; if no processing is needed, it does nothing. The device driver does not need toremember whether a device is open or not, nor is it necessary to treat as error the calling of anotherprocessing function simply because the device was not opened (openfn had not been called). If
another processing function is called for a device that is not open, the necessary processing canbe performed so long as there is no problem in device driver operation.
When openfn is used to perform device initialization or the like, in principle no processing shouldbe performed that causes a WAIT state. The processing and return from openfn must be as
prompt as possible. In the case of a device such as a serial port for which it is necessary to set thecommunication mode, for example, the device can be initialized when the communication mode is
set by tk wri dev. There is no need for openfn to initialize the device.
When the same device is opened multiple times, normally this function is called only for the firsttime. If, however, the driver attribute TDA OPENREQ is specified in device registration, this function
is called each time the device is opened.
The openfn function does not need to perform any processing with regard to multiple opening
or open mode, which are handled by device management. Likewise, omode is simply passed as
reference information; no processing relating to omode is required.

• Close Function: ER closefn( ID devid, UINT option, VP exinf )devid
optionexinf
return code

Device ID of the device to close
Close option (same as tk cls dev)
Extended information set at device registration
Error

The close function closefn is called when tk cls dev is invoked.
The closefn function performs processing to end use of a device. Details of the processing aredevice-dependent; if no processing is needed, it does nothing.
If the device is capable of ejecting media and TD EJECT is set in option, media ejection is performed.
When closefn is used to perform device shutdown processing or media ejection, in principle
no processing should be performed that causes a WAIT state. The processing and return fromclosefn must be as prompt as possible. If media ejection takes time, it is permissible to returnfrom closefn without waiting for the ejection to complete.
When the same device is opened multiple times, normally this function is called only the last time
it is closed. If, however, the driver attribute TDA OPENREQ is specified in device registration, thisfunction is called each time the device is closed. In this case TDA EJECT is specified in option only
for the last time.
The closefn function does not need to perform any processing with regard to multiple opening
or open mode, which are handled by device management.
• Processing Start Function: ER execfn( T_DEVREQ *devreq, TMO tmout, VP exinf )devreqtmout
exinf
return code

Request packet
Request acceptance timeout (ms)Extended information set at device registration
Error

The execfn function is called when tk rea dev or tk wri dev is invoked, and starts the processing
requested in devreq. This function starts the requested processing only, returning to its caller
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

5.3. DEVICE MANAGEMENT FUNCTIONS

243

without waiting for the processing to complete. The time required to start processing depends onthe device driver; this function does not necessarily complete immediately.
When new processing cannot be accepted, this function goes to WAIT state for request acceptance.
If the new request cannot be accepted within the time specified in tmout, the function times out.
The attribute TMO POL or TMO FEVR can be specified in tmout. If the function times out, E TMOUT is
passed in the execfn return code. Timeout applies to the request acceptance, not to the processing
after acceptance.
When error is passed in the execfn return code, the request is considered not to have been accepted
and the request packet is discarded.
If processing is aborted before the request is accepted (before the requested processing starts),
E ABORT is passed in the execfn return code and the request packet is discarded. If the abort
occurs after the processing has been accepted, E OK is returned for this function. The request
packet is not discarded until waitfn is executed and processing completes.
When abort occurs, the important thing is to return from execfn as quickly as possible. If
processing will end soon anyway without aborting, it is not necessary to abort.
• Completion Wait Function: INT waitfn( T_DEVREQ *devreq, INT nreq, TMO tmout, VP exinf )devreq
nreq
tmout
exinf
return code

Request packet list
Request packet count
Timeout (ms)Extended information set at device registration
Completed request packet number or error

The waitfn function is called when tk wai dev is invoked.
devreq is a list of request packets in a chain linked by devreq->next. This function waits forcompletion of any of the nreq request packets starting from devreq. The final next is not necessarily NULL, so the nreq must always be followed. The number of the completed request packet(which one after devreq) is passed in the return code. The first one is numbered 0 and the last
one is numbered nreq − 1. Here completion means any of normal completion, abnormal (error)
termination, or abort.
The time to wait until completion is set in tmout. TMO POL or TMO FEVR can be specified as thetmout attribute. If the wait times out, the requested processing continues. The waitfn returncode in case of timeout is E TMOUT. The request packet error parameter does not change. Notethat if return from waitfn occurs while the requested processing continues, error must be returnedin the waitfn return code; but the processing must be completed even when error is passed in
the return code, and a value other than error must not be returned if processing is ongoing. As
long as error is not passed in the waitfn return code, the request is considered to be pending
and no request packet is discarded. When the number of a request packet whose processing wascompleted is passed in the waitfn return code, the processing of that request is considered to becompleted and that request packet is discarded.
IO error and other device-related errors are stored in the request packet error parameter. Erroris passed in the waitfn return code when completion waiting did not take place properly. The
waitfn return code is set in the tk wai dev return code, whereas the request packet error value
is returned in ioer.
Abort processing differs depending on whether the wait is for completion of a single request(nreq = 1) or multiple requests (nreq > 1). When completion of a single request is being waitedfor, the request currently processing is aborted. When waiting for completion of multiple requests,
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

244

CHAPTER 5. T-KERNEL/SM FUNCTIONS
only the wait is aborted (wait release), not the requested processing itself. When a wait for
multiple requests is aborted (wait release), E ABORT is passed in the waitfn return code.
During a wait for request completion, an abort request may be set in the abort parameter ofa request packet. In such a case, if it is a single request, the request abort processing mustbe performed. If the wait is for multiple requests it is also preferable that abort processing be
executed, but it is also possible to ignore the abort flag.
When abort occurs, the important thing is to return from waitfn as quickly as possible. If
processing will end soon anyway without aborting, it is not necessary to abort.
As a rule, E ABORT is returned in the request packet error parameter when processing is aborted;
but a different error code may be returned as appropriate based on the device properties. It isalso permissible to return E OK on the basis that the processing right up to the abort is valid. If
processing completes normally to the end, E OK is returned even if there was an abort request.
• Abort Function: ER abortfn( ID tskid, T_DEVREQ *devreq, INT nreq, VP exinf )tskid
devreqnreq
exinf
return code

Task ID of the task executing execfn or waitfn
Request packet list
Request packet count
Extended information set at device registration
Error

The function abortfn causes execfn or waitfn to return promptly when the specified request
is being executed. Normally this means the request being processed is aborted. If, however, theprocessing can be completed soon without aborting, it may not have to be aborted. The important
thing is to return as quickly as possible from execfn or waitfn.
tskid indicates the task executing the request specified in devreq. In other words, it is the task
executing execfn or waitfn. devreq and nreq are the same as the parameters that were passed
to execfn or waitfn. In the case of execfn, nreq is always 1.
abortfn is called by a different task from the one executing execfn or waitfn. Since both tasks
run concurrently, mutual exclusion control must be performed as necessary. It is possible thatthe abortfn function will be called immediately before calling execfn or waitfn, or during returnfrom these functions. Measures must be taken to ensure proper operation in such cases. Before
abortfn is called, the abort flag in the request packet whose processing is to be aborted is set to
TRUE, enabling execfn or waitfn to know whether there is going to be an abort request. Notealso that abortfn can make use of tk dis wai for any object.
When waitfn is executing for multiple requests (nreq > 1), this is treated as a special casediffering as follows from other cases.
– Only the completion wait is aborted (wait release), not the requested processing.
– The abort flag is not set in the request packet (remains as abort = FALSE).
Aborting a request when execfn and waitfn are not executing is done not by calling abortfn but
by setting the request packet abort flag. If execfn is called when the abort flag is set, the request
is not accepted. If waitfn is called, abort processing is the same as that when abortfn is called.
If a request for which processing was started by execfn is aborted before waitfn was called to
wait for its completion, the completion of the aborted processing is notified when waitfn is called.
Even though processing was aborted, the request itself is not discarded until its completion has
been confirmed by waitfn.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

5.3. DEVICE MANAGEMENT FUNCTIONS

245

abortfn starts abort processing only, returning promptly without waiting for the abort to complete.
abortfn is called in the following cases.
– When a break function is executing after a task exception and the task that raised theexception requests abort processing, abortfn is used to abort the request being processed bythat task.
– When a device is being closed by tk cls dev and by subsystem cleanup processing, anda device descriptor was processing a request, abortfn is used to abort the request being
processed by that device descriptor.
• Event Handling Function: INT eventfn( INT evttyp, VP evtinf, VP exinf )evttypevtinfexinf
return code

Driver request event type
Information for each event type
Extended information set at device registration
Return code defined for each event type or error

The following driver request event types are defined. Those with positive values are called by
tk evt dev, and those with negative values are called inside device management.
#define TDV_SUSPEND (-1)#define TDV_RESUME (-2)#define TDV_CARDEVT
1#define TDV_USBEVT2p/* suspend*//* resume*//* PC Card event (see Card Manager *//* USB event (see USB Manager)*/

The processing performed by an event function is defined for each event type. Suspend and resume
processing are discussed later below.
When a device event is called by tk evt dev, the eventfn return code is set transparently as thetk evt dev return code.
Requests to event functions must be accepted even if another request is processing and must beprocessed as quickly as possible.

5.3.5

Attribute Data

Attribute data is classified broadly into the following three kinds of data.
• Common attributes
Attributes defined in common for all devices (device drivers).
• Device kind attributes
Attributes defined in common for devices (device drivers) of the same kind.
• Device-specific attributes
Attributes defined independently for each device (device driver).
For the device kind attributes and device-specific attributes, see the specifications for each device. Only
the common attributes are defined here.
Common attributes are assigned attribute data numbers in the range from −1 to −99. While common
attribute data numbers are the same for all devices, not all devices necessarily support all common
attributes. If an unsupported data number is specified, error code E PAR is returned.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

246

CHAPTER 5. T-KERNEL/SM FUNCTIONS#define TDN_EVENT#define TDN_DISKINFO#define TDN_DISPSPEC/* RW: event notification message buffer ID *//* R: disk information*//* R: display device specification
*/

(-1)
(-2)
(-3)

RW: read (tk rea dev)/write (tk wri dev) enabled
R: read (tk rea dev) only

TDN EVENT: Event Notification Message Buffer ID
Data type: ID
The ID of the message buffer used for device event notification. Since the system default message
buffer ID is passed in device registration, that ID is set as the initial setting when a driver isstarted.
If 0 is set, device events are not notified.
Device event notification is discussed later below.
TDN DISKINFO: Disk Information
Data type: DiskInfo
typedef enum {DiskFmt_STD
DiskFmt_2DD
DiskFmt_2HD
DiskFmt_CDROM} DiskFormat;
typedef struct {DiskFormat
UW
UW
UW
W
W
} DiskInfo;

= 0,
= 1,
= 2,
= 4,

format;protect:1;
removable:1;
rsv:30;
blocksize;
blockcount;/* standard (HD, etc.) *//* 2DD 720KB*//* 2HD 1.44MB*//* CD-ROM 640MB*//* format*//* protected status*//* removable*//* reserved (always 0) *//* block size in bytes *//* total block count*/See the disk driver specification for details.
TDN DISPSPEC: Display Device Specification
Data type: DEV SPEC
typedef struct {H
attr;/* device attributes*/
H
planes;/* number of planes*/Hpixbits;/* pixel bits (boundary/valid) */H
hpixels;/* horizontal pixels*/
H
vpixels;/* vertical pixels
*/
H
hres;
/* horizontal resolution
*/
H
vres;
/* vertical resolution*/Hcolor[4];/* color information*/H
resv[6];/* reserved*/} DEV_SPEC;
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

5.3. DEVICE MANAGEMENT FUNCTIONS

247

See the screen driver specification for details.

5.3.6

Device Event Notification

A device driver sends events occurring in devices to the event notification message buffer (TDN EVENT) as
device event notification. The system default event notification message buffer is specified at the timeof device registration, but can be changed later. The system default event notification message buffer
is defined in TDEvtMbfSz in system configuration information.
The following event types are defined.
typedef enum tdevttyp {TDE_unknown= 0,
TDE_MOUNT= 0x01,
TDE_EJECT= 0x02,
TDE_ILLMOUNT= 0x03,
TDE_ILLEJECT= 0x04,
TDE_REMOUNT= 0x05,
TDE_CARDBATLOW = 0x06,
TDE_CARDBATFAIL = 0x07,
TDE_REQEJECT= 0x08,
TDE_PDBUT= 0x11,
TDE_PDMOVE= 0x12,
TDE_PDSTATE= 0x13,
TDE_PDEXT= 0x14,
TDE_KEYDOWN= 0x21,
TDE_KEYUP= 0x22,
TDE_KEYMETA= 0x23,
TDE_POWEROFF= 0x31,
TDE_POWERLOW= 0x32,
TDE_POWERFAIL= 0x33,
TDE_POWERSUS= 0x34,
TDE_POWERUPTM= 0x35,
TDE_CKPWON= 0x41} TDEvtTyp;/* undefined*//* media mounted*//* media ejected*//* media illegally mounted*//* media illegally ejected*//* media remounted*//* card battery alarm*//* card battery failure*//* media eject request*//* PD button state change*//* PD move*//* PD state change*//* PD extended event*//* key down*//* key up*//* meta key state change*//* power switch off*//* low power alarm*//* power failure*//* auto suspend*//* clock update*//* auto power on notification */Device events are notified in the following format. The contents of event notification and size differ witheach event type.
typedef struct t_devevt {TDEvtTypevttyp;/* event type *//* Information specific to each event type is appended here. */} T_DEVEVT;The format of device event notification with device ID is as follows.
typedef struct t_devevt_id {TDEvtTypevttyp;/* event type */IDdevid;/* device ID *//* Information specific to each event type is appended here. */} T_DEVEVT_ID;

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

248

CHAPTER 5. T-KERNEL/SM FUNCTIONS

See the device driver specifications for event details.
Measures must be taken so that if event notification cannot be sent because the message buffer is full,the lack of notification will not adversely affect operation on the receiving end. One option is to holdthe notification until space becomes available in the message buffer, but in that case other device driverprocessing should not, as a rule, be allowed to fall behind as a result. Processing on the receiving end
should be designed to the extent possible to avoid message buffer overflow.

5.3.7

Device Suspend/Resume Processing

Device drivers suspend and resume device operations in response to the issuing of suspend/resume(TDV SUSPEND/TDV RESUME) events to the event handling function (eventfn). Suspend and resume
events are issued only to physical devices.
TDV SUSPEND: Suspend Device
evttyp = TDV SUSPEND
evtinf = NULL (none)
Suspension processing takes place in the following steps.
(A) If there is a request being processed at the time, the device driver waits for it to complete,pauses it or aborts. Which of these options to take depends on the device driver implementation. Since the suspension must be effected as quickly as possible, however, pause or abortshould be chosen if completion of the request will take time. Suspend events can be issued
only for physical devices, but the same processing is applied to all logical devices included in
the physical device.
Pause: Processing is suspended, then continues after the device resumes operation.
Abort: Processing is aborted just as when the abort function (abortfn) is executed, and is
not continued after the device resumes operation.
(B) New requests other than a resume event are not accepted.
(C) The device power is cut and other suspension processing is performed.
Abort should be avoided if at all possible because of its effects on applications. It should be used
only in such cases as long input waits from a serial port, or when interruption would be difficult.
Normally it is best to wait for completion of a request or, if possible, choose pause (suspension
and resumption).
Requests arriving at the device driver in suspend state are made to wait until operation resumes,
after which acceptance processing is performed. If the request does not involve access to thedevice, however, or otherwise can be processed even during suspension, a request may be acceptedwithout waiting for resumption.
TDV RESUME: Resume Device
evttyp = TDV RESUME
evtinf = NULL (none)
Resumption processing takes place as follows.
(A) The device power is turned back on, the device states are restored and other device resumption
processing is performed.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

5.3. DEVICE MANAGEMENT FUNCTIONS

249(B) Paused processing is resumed.
(C) Request acceptance is resumed.

5.3.8

Special Properties of Disk Devices

A disk device has a special role to play in a virtual memory system. In order to realize virtual memory,
the OS must call the disk driver for transferring data between memory and disk.
The need for the OS to perform data transfer with a disk arises when access is made to nonresident
memory and the memory contents must be read from the disk (page in). The OS calls the disk driverin this case.
If nonresident memory is accessed in the disk driver, the OS must likewise call the disk driver. In sucha case, if the disk driver treats the access to nonresident memory as a wait for page in, it is possiblethat the OS will again request disk access. Even then, the disk driver must be able to execute the later
OS request.
A similar case may arise in suspension processing. When access is made to nonresident memory duringsuspension processing and a disk driver is called, if that disk driver is already suspended, page in will
not be possible. To avoid such a situation, suspension processing should suspend other devices before
disk devices. If there are multiple disk devices, however, the order of their suspension is indeterminate.
For this reason, during suspension processing a disk driver must not access nonresident memory.
Because of the above limitations, a disk driver must not use (access) nonresident memory. It is possible,
however, that the IO buffer (buf) space specified with tk rea dev or tk wri dev will be nonresident
memory, since this is a memory location specified by the caller. In the case of IO buffers, therefore, itis necessary to make the memory space resident (see LockSpace) at the time of IO access.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

250

CHAPTER 5. T-KERNEL/SM FUNCTIONSInterrupt Management Functions

5.4

Interrupt handling is largely hardware-dependent, differing with each system, and therefore difficult tostandardize. The following are given as standard specifications, but it may not be possible to follow
these exactly on all systems. Implementors should strive to comply with these specifications to theextent possible; but where implementation is not feasible, full compliance is not mandatory. If functions
not in the standard specifications are added, however, the function names must be different from thosegiven here. In any case, DI(), EI(), and isDI() must be implemented in accord with the standard
specifications.
Interrupt management functions are provided as library functions or C language macros. These can becalled from a task-independent portion and while dispatching and interrupts are disabled.

5.4.1

CPU Interrupt Control

These functions are for CPU external interrupt flag control.
Generally they do not perform any operation on the interrupt controller.
DI() and EI() are C language macros.
• DI( UINT intsts )intsts

CPU interrupt status (details are implementation-dependent)
This is not a pointer.

Disables all external interrupts.
The status prior to disabling interrupts is stored in intsts.
• EI( UINT intsts )intsts

CPU interrupt status (details are implementation-dependent)

Enables all external interrupts.
More precisely, this macro restores the status in intsts. That is, the interrupt status reverts
to what it was before interrupts were disabled by DI(). If there were interrupts disabled at thetime DI() was executed, those interrupts are not enabled by EI(). All interrupts can be enabled,
however, by specifying 0 in intsts.
intsts must be either the values stored in it by DI() or 0. If any other value is specified, thebehavior is not guaranteed.
• BOOL isDI( UINT intsts )intsts

CPU interrupt status (details are implementation-dependent)

Return code:
TRUE (not 0):
FALSE:

Interrupts disabledInterrupts enabled

Gets the status of external interrupt disabling stored in intsts.
Interrupts disabled status is the status in which T-Kernel/OS determines that interrupts are
disabled.
intsts must by the value stored by DI(). If any other value is specified, the behavior is notguaranteed.
Sample usage:c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

5.4. INTERRUPT MANAGEMENT FUNCTIONS
void foo()
{
UINT

251

intsts;DI(intsts);if ( isDI(intsts) ) {/* Interrupts were already disabled at the time this function was called.*/} else {/* Interrupts were enabled at the time this function was called.
*/}
EI(intsts);
}

5.4.2

Control of Interrupt Controller

These functions control the interrupt controller.
Generally they do not perform any operation with respect to the CPU interrupt flag.
typedef UINTINTVEC;/* interrupt vector */The specific details of the interrupt vectors (INTVEC) are implementation-dependent. Preferably, however, they should be the same numbers as the interrupt definition numbers specified with tk def int,
or should allow for simple conversion to and from those numbers.
• UINT DINTNO( INTVEC intvec )Converts an interrupt vector to the corresponding interrupt definition number.
• void EnableInt( INTVEC intvec )• void EnableInt( INTVEC intvec, INT level )Enables the interrupt specified in intvec.
In a system that allows interrupt priority level to be specified, the level parameter can be used to
specify the interrupt priority level. The precise meaning of level is implementation-dependent.
Both methods with and without level must be provided.
• void DisableInt( INTVEC intvec )Disables the interrupt specified in intvec.
Generally, interrupts raised while interrupts are disabled are made pending, and are raised after
interrupts are enabled by EnableInt(). ClearInt() must be used if it is desired to clear interrupts
occurring in interrupts disabled state.
• void ClearInt( INTVEC intvec )Clears any interrupts raised for intvec.
• void EndOfInt( INTVEC intvec )Issues EOI (End Of Interrupt) to the interrupt controller intvec must be an interrupt for which
EOI can be issued. Generally this must be executed at the end of an interrupt handler.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

252

CHAPTER 5. T-KERNEL/SM FUNCTIONS• BOOL CheckInt( INTVEC intvec )Checks whether interrupt intvec has been raised.
If interrupt intvec has been raised, it returns TRUE (value other than 0), else FALSE.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

5.5. IO PORT ACCESS SUPPORT FUNCTIONS

5.5

253

IO Port Access Support Functions

IO port access support functions are provided as library functions or C language macros. These can becalled from a task-independent portion or while dispatching and interrupts are disabled.

5.5.1

IO Port AccessIn a system with separate IO space and memory space, an IO port access function accesses IO space.
In a system with memory-mapped IO only, an IO port access function accesses memory space. Using
these functions will improve software portability and readability even in a memory-mapped IO system.
—_w
—_h
—_b

Word (32-bit) units
Half-word (16-bit) units
Byte (8-bit) units• void out_w( INT port, UW data )• void out_h( INT port, UH data )• void out_b( INT port, UB data )port

IO port address data

Data to be written

Writes data to an IO port.
• UW in_w( INT port )• UH in_h( INT port )• UB in_b( INT port )port

IO port address return code

Data to be read

Reads data from an IO port.

5.5.2

Micro wait

• void WaitUsec( UINT usec )• void WaitNsec( UINT nsec )
usec
nsec

Wait time (microseconds)
Wait time (nanoseconds)

Performs a micro wait for the specified interval.
These waits occur in an ordinary busy loop, and as such are easily influenced by the runtime
environment, such as execution in RAM, execution in ROM, memory cache on or off, etc. These
wait times are therefore not very accurate.
These waits are not the same as an OS WAIT state. The system state remains as RUN state.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

254

CHAPTER 5. T-KERNEL/SM FUNCTIONS

5.6

Power Management Functions

Power management functions are called from T-Kernel/OS. See tk set pow.
The manner of calling these functions is implementation-dependent. Simple system calls are possible,
as is the use of a trap. Use of an extended SVC or other means that makes use of OS functions is notpossible, however. Providing these functions in T-Monitor is another option.
The specifications given here for low pow and off pow are reference specifications. Since these functions
are used only inside T-Kernel, other specifications may be devised as well. It is even possible todesign completely different specifications in order to realize more advanced power-saving features. If thefunctionality is similar to that specified here, however, it would be best to follow these specifications as
closely as practical.
• void low_pow( void )Switches to low-power mode and waits for an interrupt to be raised. This function is called fromthe task dispatcher, and performs the following processing.
(A) Goes to low-power mode.
(B) Waits for an external interrupt to be raised.
(C) When an external interrupt is raised, restores normal power mode and returns to its caller.
This function is called in interrupts disabled state. Interrupts must not be enabled. The speed of
response to an interrupt affects processing speed, and should be as fast as possible.
• void off_pow( void )Suspends the system. When a resume factor occurs, it resumes system operation.
This function is called from tk set pow, and performs the following processing.
(A) Puts the hardware in suspended state.
(B) Waits for a resume factor to occur.
(C) When a resume factor occurs, returns from suspended state and returns to its caller.
This function is called in interrupts disabled state. Interrupts must not be enabled. The device
drivers perform the suspending and resuming of peripherals and other devices.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

5.7. SYSTEM CONFIGURATION INFORMATION MANAGEMENT FUNCTIONS

5.7

255

System Configuration Information Management Functions

System configuration information management functions are provided for storing, managing and making
available information about the system configuration (maximum number of tasks, etc.) and any otherinformation. These are not functions for adding or modifying information when the system is running.
How the system configuration information is to be stored is not specified here, but it is generally put
in memory (ROM/RAM). This functionality is therefore not intended for storing large amounts of
information.
Standard definitions are specified for some system configuration information, but additional information
may be defined and used for applications, subsystems, or device drivers.
The format of system configuration information consists of a name and defined data as a set.
• NameThe name is a string of up to 16 characters.
Characters that can be used (UB) are a to z, A to Z, 0 to 9 and(under bar).

• Defined data
Data consists of numbers (integers) or character strings.
Characters that can be used (UB) are any characters other than 0x00 to 0x1F, 0x7F, or 0xFF
(character codes).
Sample:Name
SysVer
SysName5.7.1

Defined Data
10
T-Kernel Version 1.00

System Configuration Information Acquisition

System configuration information is acquired by using extended SVC. This function is used inside TKernel, and can also be used by applications, subsystems, device drivers and so on. Use inside T-Kernel
does not have to go through extended SVC; this choice is implementation-dependent.
• INT tk_get_cfn( UB *name, INT *val, INT max )
name
val
max
return code

Name
Array storing numeric strings
Number of elements in val array
Defined numeric information count or error

Gets numeric string information from system configuration information. This function gets up to
max items of numerical string information defined by the name specified in the name parameter andstores the acquired information in val. The number of items of defined numeric string information
is passed in the return code. If return code > max, this indicates that not all the information could
be stored. By specifying max = 0, the number of numeric strings can be found out without actually
storing them in val.
E NOEXS is returned if no information is defined with the name specified in the name parameter.
The behavior if the information defined as name is a character string is indeterminate.
This function can be invoked from any protection level, without being limited by the protectionlevel from which T-Kernel/OS system call can be invoked.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

256

CHAPTER 5. T-KERNEL/SM FUNCTIONS• INT tk_get_cfs( UB *name, UB *buf, INT max )
name
buf
max
return code

Name
Array storing character string
Maximum size of buf (in bytes)
Size of defined character string information (in bytes) or error

Gets character string information from system configuration information. This function gets up to
max characters of character string information defined by the name specified in the name parameterand stores the acquired information in buf. If the acquired character string is shorter than max
characters, it is terminated by ‘\0’ when stored. The length of the defined character string
information (not including ‘\0’) is passed in the return code. If return code > max, this indicatesthat not all the information could be stored. By specifying max = 0, the character string length
can be found out without actually storing anything in buf.
E NOEXS is returned if no information is defined with the name specified in the name parameter.
The behavior if the information defined as name is a numeric string is indeterminate.
This function can be invoked from any protection level, without being limited by the protectionlevel from which T-Kernel/OS system call can be invoked.

5.7.2

Standard System Configuration Information

The following information is defined as standard system configuration information. A standard information name is prefixed by T.
N:S:

Numeric string information
Character string information• Product information
S:

TSysName

System name (product name)• Maximum object counts
N:
N:
N:
N:
N:
N:
N:
N:
N:
N:
N:
N:
N:
N:

TMaxTskId
TMaxSemId
TMaxFlgId
TMaxMbxId
TMaxMtxId
TMaxMbfId
TMaxPorId
TMaxMpfId
TMaxMplId
TMaxCycId
TMaxAlmId
TMaxResId
TMaxSsyId
TMaxSsyPri

Maximum tasks
Maximum semaphores
Maximum event flags
Maximum mailboxes
Maximum mutexes
Maximum message buffers
Maximum rendezvous ports
Maximum fixed-size memory pools
Maximum variable-size memory pools
Maximum cyclic handlers
Maximum alarm handlers
Maximum resource groups
Maximum subsystems
Maximum subsystem priorities• Otherc 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

5.7. SYSTEM CONFIGURATION INFORMATION MANAGEMENT FUNCTIONS
N:
N:
N:

TSysStkSz
TSVCLimit
TTimPeriod

257

Default system stack size (in bytes)
Lowest protection level for system call invoking
Timer interrupt interval (ms)• Device management
N:
N:
N:
N:

TMaxRegDev
TMaxOpnDev
TMaxReqDev
TDEvtMbfSz

Maximum device registrations
Maximum device open countMaximum device requests
Event notification message buffer size (in bytes)
Maximum event notification message length (in bytes)

If TDEvtMbfSz is not defined or if the message buffer size is a negative value, an event notification
message buffer is not used.
When multiple values are defined for any of the above numeric strings, they are stored in the same order
as in the explanation.
Examples:tk_get_cfn("TDEvtMbfSz", val, 2)
val[0] = Event notification message buffer sizeval[1] = Maximum event notification message length

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

258

CHAPTER 5. T-KERNEL/SM FUNCTIONS

5.8

Subsystem and Device Driver Starting

Entry routines like the following are defined for subsystems and device drivers.
ER main( INT ac, UB *av[] ){if ( ac >= 0 ) {/* Subsystem/device driver start processing */} else {/* Subsystem/device driver termination processing */}return ercd;}
This entry routine simply performs startup processing or termination processing for a subsystem ordevice driver and does not provide any actual service. It must return to its caller as soon as the startup
processing or termination processing is performed. An entry routine must perform its processing as
quickly as possible and return to its caller.
An entry routine is called by the task which belongs to the system resource group at the time of normal
system startup or shutdown, and runs in the context of the OS start processing task or termination
processing task (protection level 0). In some OS implementations, it may run as a quasi-task portion.
In a system that supports dynamic loading of subsystems and device drivers, it may be called at othertimes besides system startup and shutdown.
When there are multiple subsystems and device drivers, entry routines are called one at a time for each,at system startup and shutdown. In no case are multiple entry routines called by different tasks at thesame time. Accordingly, if subsystem or device driver initialization needs to be performed in a certain
order, this order can be maintained by completing all necessary processing before returning from anentry routine.
The entry routine function name is normally main, but any other name may be used if, for example,
main cannot be used because of linking with the OS.
The methods of registering entry routines with the OS, specifying parameters, and specifying the orderin which entry routines are called are all dependent on the OS implementation.
• Startup processingac
Number of parameters (≥ 0)
av
Parameters (string)
return code Error
A value of ac ≥ 0 indicates startup processing. After performing the subsystem or device driverinitialization, it registers the subsystem or device driver.
Passing of a negative value (error) as the return code means the startup processing failed. Depending on the OS implementation, the subsystem or device driver may be deleted from memory,so error must not be returned while the subsystem or device driver is in registered state. The
registration must first be erased before returning error. Allocated resources must also be released.
They are not released automatically.
The parameters ac and av are the same as the parameters passed to the standard C language
main() function, with ac indicating the number of parameters and av indicating a parameter
string as an array of ac + 1 pointers. The array termination (av[ac]) is NULL.
av[0] is the name of the subsystem or device driver. Generally this is the file name of the subsystemor device driver, but the kind of name in which it is stored is implementation-dependent. It is also
possible to have no name (blank string "").
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

259

5.8. SUBSYSTEM AND DEVICE DRIVER STARTING
Parameters after av[1] are defined separately for each subsystem and device driver.

After exit from the entry routine, the character string space specified by av is deleted, so parametersmust be saved to a different location as needed.
• Termination processing
acav
return code

−1
NULL
Error

A value of ac < 0 indicates termination processing. After deleting the subsystem or device driver
registration, the entry routine releases allocated resources. If an error occurs during termination
processing, the processing must not be aborted but must be completed to the extent possible. If
some of the processing could not be completed normally, error is passed in the return code.
The behavior if termination processing is called while requests to the subsystem or device driverare being processed is dependent on the subsystem or device driver implementation. Generally
termination processing is called at system shutdown and requests are not issued during processing. For this reason, ordinarily behavior is not guaranteed in the case of requests issued duringtermination processing.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

260

c 2002–2005 by T-Engine Forum
Copyright °CHAPTER 5. T-KERNEL/SM FUNCTIONSTEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

Chapter 6

T-Kernel/DS Functions
This chapter gives detailed explanations of the functions provided by T-Kernel Debugger Support (TKernel/DS).
T-Kernel/DS provides functions enabling a debugger to reference T-Kernel internal states and run a
trace. The functions provided by T-Kernel/DS are only for debugger use and not for use by applications
or other programs.
[General cautions and notes]• Except where otherwise noted, T-kernel/DS service calls (td_—) can be called from a taskindependent portion and while dispatching and interrupts are disabled. There may be some
limitations, however, imposed by particular implementations.
• When T-Kernel/DS service calls (td_—) are invoked in interrupts disabled state, they are processed without enabling interrupts. Other OS states likewise remain unchanged during this processing. Changes in OS states may occur if a service call is invoked while interrupts or dispatchingare enabled, since the OS continues operating.
• T-Kernel/DS service calls (td_—) cannot be invoked from a lower protection level than that at
which T-Kernel/OS system calls can be invoked (lower than TSVCLimit)(E OACV).
• Error codes such as E PAR, E MACV, and E CTX that always have the possibility of occurring are notdescribed here unless there is some special reason for doing so.
• Detection of error codes E PAR, E MACV, and E CTX is implementation-dependent; these may notalways be detected as error. For this reason, the service calls must not be invoked in such a waythat these errors might occur.

261

TEF020-S001-01.00.01/en

262

6.1

CHAPTER 6. T-KERNEL/DS FUNCTIONS

Kernel Internal State Reference Functions

These functions enable a debugger to get T-Kernel internal states. They include functions for getting alist of objects, getting task precedence, getting the order in which tasks are queued, getting the statusof objects, system, and task registers, and getting time.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

6.1. KERNEL INTERNAL STATE REFERENCE FUNCTIONS

263

td lst tsk, td lst sem, td lst flg, td lst mbx
td lst mtx, td lst mbf, td lst por, td lst mpf
td lst mpl, td lst cyc, td lst alm, td lst ssy
Reference Object ID List
[C Language Interface]
INT ct = td_lst_tsk ( ID list[], INT nent ) ;INT ct = td_lst_sem ( ID list[], INT nent ) ;INT ct = td_lst_flg ( ID list[], INT nent ) ;INT ct = td_lst_mbx ( ID list[], INT nent ) ;INT ct = td_lst_mtx ( ID list[], INT nent ) ;INT ct = td_lst_mbf ( ID list[], INT nent ) ;INT ct = td_lst_por ( ID list[], INT nent ) ;INT ct = td_lst_mpf ( ID list[], INT nent ) ;INT ct = td_lst_mpl ( ID list[], INT nent ) ;INT ct = td_lst_cyc ( ID list[], INT nent ) ;INT ct = td_lst_alm ( ID list[], INT nent ) ;INT ct = td_lst_ssy ( ID list[], INT nent ) ;/* task*//* semaphore*//* event flag*//* mailbox*//* mutex*//* message buffer*//* rendezvous port*//* fixed-size memory pool*//* variable-size memory pool *//* cyclic handler*//* alarm handler*//* subsystem*/[Parameters]
ID
INT

list[]
nent

Location of object ID list
Maximum number of list entries[Return Parameters]
INT

ct
or

Number of objects used
Error Code[Description]
Gets a list of IDs of objects currently being used, and puts in list up to nent IDs. The number of objects
used is passed in the return code. If return code > nent, this means not all IDs could be got.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

264

CHAPTER 6. T-KERNEL/DS FUNCTIONS

td rdy que
Get Task Precedence[C Language Interface]
INT ct = td_rdy_que ( PRI pri, ID list[], INT nent ) ;[Parameters]
PRI
ID
INT

pri
list[]
nent

Task priority
Location of task ID list
Maximum number of list entries[Return Parameters]
INT

ct
or

Number of priority pri tasks in a run state
Error Code[Description]
Gets a list of IDs of the tasks in a run state (READY state or RUN state) whose task priority is pri,arranged in order from highest to lowest precedence.
This function stores in the location designated in list up to nent task IDs, arranged in order ofprecedence starting from the highest-precedence task ID at the head of the list.
The number of tasks in a run state with priority pri is passed in the return code. If return code > nent,
this means not all task IDs could be stored.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

6.1. KERNEL INTERNAL STATE REFERENCE FUNCTIONS

265

td sem que, td flg que, td mbx que, td mtx que
td smbf que, td rmbf que, td cal que, td acp que
td mpf que, td mpl que
Reference Queue[C Language Interface]*/
INT ct = td_sem_que ( ID semid, ID list[], INT nent ) ; /* semaphore
INT ct = td_flg_que ( ID flgid, ID list[], INT nent ) ; /* event flag*/
INT ct = td_mbx_que ( ID mbxid, ID list[], INT nent ) ; /* mailbox*/
INT ct = td_mtx_que ( ID mtxid, ID list[], INT nent ) ; /* mutex*/
INT ct = td_smbf_que ( ID mbfid, ID list[], INT nent ) ; /* message buffer send*/
INT ct = td_rmbf_que ( ID mbfid, ID list[], INT nent ) ; /* message buffer receive*/
INT ct = td_cal_que ( ID porid, ID list[], INT nent ) ; /* rendezvous call*/
INT ct = td_acp_que ( ID porid, ID list[], INT nent ) ; /* rendezvous accept*/
INT ct = td_mpf_que ( ID mpfid, ID list[], INT nent ) ; /* fixed-size memory pool*/
INT ct = td_mpl_que ( ID mplid, ID list[], INT nent ) ; /* variable-size memory pool */[Parameters]
ID
ID
INT

—id
list[]
nent

Object ID
Location of waiting task IDs
Maximum number of list entries[Return Parameters]
INT

ct
or

Number of waiting tasks
Error Code[Error Codes]
E ID
E NOEXS

Bad identifier
Object does not exist[Description]
Gets a list of IDs of tasks waiting for the object designated in —id.
This function stores in the location designated in list up to nent task IDs, arranged in the order in whichtasks are queued, starting from the first task in the queue. The number of queued tasks is passed in the
return code. If return code > nent, this means not all task IDs could be stored.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

266

CHAPTER 6. T-KERNEL/DS FUNCTIONS

td ref tsk
Reference Task State[C Language Interface]
ER ercd = td_ref_tsk ( ID tskid, TD_RTSK *rtsk );[Parameters]
ID
TD RTSK

tskid
rtsk

Task ID (TSK SELF can be designated)
Packet address for returning the task state[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXS

Normal completion
Bad identifier
Object does not exist[Description]
Gets the state of the task designated in tskid. This function is similar to tk ref tsk, with the task
start address and stack information added to the state information obtained.
typedef struct td_rtsk {VP
exinf;
PRI
tskpri;PRI
tskbpri;UINTtskstat;UINT
tskwait;
ID
wid;
INT
wupcnt;INTsuscnt;RELTIM slicetime;
UINT
waitmask;
UINT
texmask;
UINT
tskevent;
FP
task;
INT
stksz;
INT
sstksz;VP
istack;VP
isstack;} TD_RTSK;/* extended information*//* current priority*//* base priority*//* task state*//* wait factor*//* waiting object ID*//* queued wakeup request count*//* SUSPEND request nesting count*//* maximum continuous run time (ms)*//* masked wait factors*//* allowed task exceptions*//* raised task event*//* task start address*//* user stack size (in bytes)*//* system stack size (in bytes)*//* user stack pointer initial value*//* system stack pointer initial value */c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

6.1. KERNEL INTERNAL STATE REFERENCE FUNCTIONS

267

The stack area extends from the stack pointer initial value toward the low addresses for the number ofbytes designated as the stack size.
istack − stksz ≤ user stack area < istackisstack − sstksz ≤ system stack area < isstack
Note that the stack pointer initial value (istack, isstack) is not the same as its current position. The
stack area may be used even before a task is started. Calling td get reg gets the stack pointer current
position.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

268

CHAPTER 6. T-KERNEL/DS FUNCTIONS

td ref sem, td ref flg, td ref mbx, td ref mtx
td ref mbf, td ref por, td ref mpf, td ref mpl
td ref cyc, td ref alm, td ref ssy
Reference Queue[C Language Interface]
ER ercd = td_ref_sem ( ID semid, TD_RSEM *rsem );ER ercd = td_ref_flg ( ID flgid, TD_RFLG *rflg );ER ercd = td_ref_mbx ( ID mbxid, TD_RMBX *rmbx );ER ercd = td_ref_mtx ( ID mtxid, TD_RMTX *rmtx );ER ercd = td_ref_mbf ( ID mbfid, TD_RMBF *rmbf );ER ercd = td_ref_por ( ID porid, TD_RPOR *rpor );ER ercd = td_ref_mpf ( ID mpfid, TD_RMPF *rmpf );ER ercd = td_ref_mpl ( ID mplid, TD_RMPL *rmpl );ER ercd = td_ref_cyc ( ID cycid, TD_RCYC *rcyc );ER ercd = td_ref_alm ( ID almid, TD_RALM *ralm );ER ercd = td_ref_ssy ( ID ssid, TD_RSSY *rssy );/* semaphore*//* event flag*//* mailbox*//* mutex*//* message buffer*//* rendezvous port*//* fixed-size memory pool*//* variable-size memory pool *//* cyclic handler*//* alarm handler*//* subsystem*/[Parameters]
ID
TD R—

—id
r—

Object ID
Address of status information packet[Return Parameters]
ER ercd Error code
[Error Codes]
E OK
E ID
E NOEXS

Normal completion
Bad identifier
Object does not exist[Description]
Gets the status of an object. This is similar to tk ref —. The return packets are defined as follows.
/**Semaphore status information
td_ref_sem*/
typedef struct td_rsem {VP
exinf;/* extended information
*/
ID
wtsk;
/* waiting task ID*/
INT
semcnt;/* current semaphore count */} TD_RSEM;
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

6.1. KERNEL INTERNAL STATE REFERENCE FUNCTIONS

269/**Event flag status information td_ref_flg*/
typedef struct td_rflg {VP
exinf;/* extended information
*/
ID
wtsk;
/* waiting task ID*/
UINT
flgptn;/* current event flag pattern */} TD_RFLG;/**Mailbox status information td_ref_mbx*/
typedef struct td_rmbx {VP
exinf; /* extended information */ID
wtsk;/* waiting task ID*/
T_MSG*pk_msg;/* next message to be received */} TD_RMBX;/**Mutex status information*/
typedef struct td_rmtx {VPexinf;
ID
bhtsk;
ID
wtsk;} TD_RMTX;

td_ref_mtx/* extended information*//* locking task ID*//* ID of task waiting for lock *//** Message buffer status information td_ref_mbf*/
typedef struct td_rmbf {VP
exinf;/* extended information
*/
ID
wtsk;
/* receive waiting task ID
*/
ID
stsk;
/* send waiting task ID*/
INT
msgsz;/* size (in bytes) of next message to be received */INTfrbufsz;/* free buffer size (in bytes)*/
INT
maxmsz;/* maximum message length (in bytes)*/} TD_RMBF;/**Rendezvous port status information td_ref_por*/
typedef struct td_rpor {VPexinf;/* extended information
*/
ID
wtsk;
/* call waiting task ID
*/
ID
atsk;
/* acceptance waiting task ID*/
INT
maxcmsz;/* call message maximum length (in bytes)*/
INT
maxrmsz;/* accept message maximum length (in bytes) */} TD_RPOR;
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

270

CHAPTER 6. T-KERNEL/DS FUNCTIONS/**Fixed-size memory pool status information td_ref_mpf*/
typedef struct td_rmpf {VP
exinf;/* extended information */ID
wtsk;/* waiting task ID*/
INT
frbcnt;/* free block count*/} TD_RMPF;/**Variable-size memory pool status information
td_ref_mpl*/
typedef struct td_rmpl {VP
exinf;/* extended information
*/
ID
wtsk;
/* waiting task ID
*/
INT
frsz;
/* total free space (in bytes)*/
INT
maxsz;/* maximum contiguous free space (in bytes) */} TD_RMPL;/**Cyclic handler status information td_ref_cyc*/
typedef struct td_rcyc {VPexinf;/* extended information*/
RELTIM lfttim;/* time remaining until next handler start */UINT
cycstat;/* cyclic handler status*/} TD_RCYC;]/**Alarm handler status information
td_ref_alm*/
typedef struct td_ralm {VP
exinf;/* extended information*/
RELTIM lfttim;/* time remaining until next handler start */UINT
almstat;/* alarm handler status*/} TD_RALM;/**Subsystem status information
td_ref_ssy*/
typedef struct td_rssy {PRI
ssypri;/* subsystem priority*/
INT
resblksz; /* resource control block size (in bytes) */} TD_RSSY;

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

6.1. KERNEL INTERNAL STATE REFERENCE FUNCTIONS

271

td ref tex
Reference Task Exception Status[C Language Interface]
ER ercd = td_ref_tex ( ID tskid, TD_RTEX *pk_rtex );[Parameters]
ID
TD RTEX*tskid
pk rtex

Task ID (TSK SELF can be designated)
Packet address for returning the task exception status[Return Parameters]
ER

ercd

Error code

pk rtex detail:
UINT
UINT

pendtextexmask

Raised task exceptions
Allowed task exceptions[Error Codes]
E OK
E ID
E NOEXS

Normal completion
Bad identifier
Object does not exist[Description]
Gets the task exception status. This is similar to tk ref tex.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

272

CHAPTER 6. T-KERNEL/DS FUNCTIONS

td inf tsk
Reference Task Statistics[C Language Interface]
ER ercd = td_inf_tsk ( ID tskid, TD_ITSK *pk_itsk, BOOL clr );[Parameters]ID
TD ITSK*
BOOL

tskid
pk itskclr

Task ID (TSK SELF can be designated)
Packet address for returning task statistics
Task statistics clear flag

[Return Parameters]
ER

ercd

Error code

pk itsk detail:RELTIMRELTIM

stime
utime

Cumulative system-level run time (ms)Cumulative user-level run time (ms)[Error Codes]
E OK
E ID
E NOEXS

Normal completion
ID number is invalid
Object does not exist[Description]
Gets task statistics. This is similar to tk inf tsk. When clr = TRUE (6= 0), accumulated informationis reset (cleared to 0) after getting the statistics.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

6.1. KERNEL INTERNAL STATE REFERENCE FUNCTIONS

273

td get reg
Get Task Register[C Language Interface]
ER ercd = td_get_reg ( ID tskid, T_REGS *pk_regs, T_EIT *pk_eit, T_CREGS *pk_cregs ) ;[Parameters]
ID

tskid

Task ID (TSK SELF cannot be designated)[Return Parameters]
T REGST EIT
T CREGSER

pk regs
pk eitpk cregs
ercd

General register
Registers saved when exception is raised
Control register
Error code

The contents of T REGS, T EIT, and T CREGS are defined for each CPU and implementation.
[Error Codes]
E OK
E ID
E NOEXSE OBJNormal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task designated in tskid does not exist)
Invalid object state (issued for current RUN state task)[Description]
Gets the register values of the task designated in tskid. This is similar to tk get reg.
Registers cannot be referenced for the task currently in RUN state. Except when a task-independent
portion is executing, the current RUN state task is the invoking task.
When NULL is designated for regs, eit, or cregs, the corresponding register is not referenced.
The contents of T REGS, T EIT, and T CREGS are implementation-dependent.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

274

CHAPTER 6. T-KERNEL/DS FUNCTIONS

td set reg
Set Task Register[C Language Interface]
ER ercd = td_set_reg ( ID tskid, T_REGS *pk_regs, T_EIT *pk_eit, T_CREGS *pk_cregs ) ;[Parameters]ID
T REGST EIT
T CREGStskid
pk regs
pk eitpk cregs

Task ID (TSK SELF cannot be designated)
General registers
Registers saved when exception is raised
Control registers

The contents of T REGS, T EIT, and T CREGS are defined for each CPU and implementation.
[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E ID
E NOEXSE OBJNormal completion
Invalid ID number (tskid is invalid or cannot be used)
Object does not exist (the task designated in tskid does not exist)
Invalid object state (issued for current RUN state task)[Description]
Sets registers of the task designated in tskid. This is similar to tk set reg.
Registers cannot be set for the task currently in RUN state. Except when a task-independent portionis executing, the current RUN state task is the invoking task.
When NULL is designated for regs, eit, or cregs, the corresponding register is not set.
The contents of T REGS, T EIT, and T CREGS are implementation-dependent.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

6.1. KERNEL INTERNAL STATE REFERENCE FUNCTIONS

275

td ref sys
Reference System Status[C Language Interface]
ER ercd = td_ref_sys ( TD_RSYS *pk_rsys ) ;[Parameters]
TD RSYS*

pk rsys

Packet address for returning status information[Return Parameters]
ER

ercd

Error code

pk rsys detail:
INT
ID
ID

sysstatruntskidschedtskid

System status
ID of current RUN state task
ID of task scheduled to go to RUN state[Error Codes]
E OK

Normal completion[Description]
Gets the system status. This is similar to tk ref sys.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

276

CHAPTER 6. T-KERNEL/DS FUNCTIONS

td get tim
Get System Time[C Language Interface]
ER ercd = td_get_tim ( SYSTIM *tim, UNIT *ofs ) ;[Parameters]
SYSTIM*
UNIT*

tim
ofs

Packet address for returning current time (ms)Location for returning elapsed time from tim (nanoseconds)[Return Parameters]
ER & ercd &Error codetim detail:
Current time (ms)ofs detail:Elapsed time from tim (nanoseconds)[Error Codes]
E OK

Normal completion[Description]
Gets the current time as total elapsed milliseconds since 0:00:00 (GMT), January 1, 1985. The value
returned in tim is the same as that obtained by tk get tim. tim is the resolution of time interrupt
intervals (cycles), but even more precise time information is obtained in ofs as the elapsed time fromtim in nanoseconds. The resolution of ofs is implementation-dependent, but generally is the timer
hardware resolution.
Since tim is time counted based on timer interrupts, in some cases time is not refreshed, when a timer
interrupt cycle arrives while interrupts are disabled and the timer interrupt handler is not started (isdelayed). In such cases, the time as updated by the previous timer interrupt is returned in tim, andthe elapsed time from the previous timer interrupt is returned in ofs. Accordingly, in some cases ofs
will be a longer time than the timer interrupt cycle. The length of elapsed time that can be measured
by ofs depends on the hardware, but preferably it should be able to measure at least up to twice thetimer interrupt cycle ( 0 ≤ ofs < twice the timer interrupt cycle).
Note that the time returned in tim and ofs is the time at some point between the calling of and returnfrom td get tim. It is neither the time at which td get tim was called nor the time of return fromtd get tim. In order to obtain more accurate information, this function should be called in interrupts
disabled state.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

6.1. KERNEL INTERNAL STATE REFERENCE FUNCTIONS

277

td get otm
Get System Operating Time[C Language Interface]
ER ercd = td_get_otm ( SYSTIM *tim, UINT *ofs ) ;[Parameters]
SYSTIM*
UNIT*

tim
ofs

Packet address for returning operating time (ms)Location for returning elapsed time from tim (nanoseconds)[Return Parameters]
ER

ercd

Error codetim detail:Operating time (ms)ofs detail:Elapsed time from tim (nanoseconds)[Error Codes]
E OK

Normal completion[Description]
Gets the system operating time (uptime, as elapsed milliseconds since the system was booted). The
value returned in tim is the same as that obtained by tk get otm. tim is the resolution of time interrupt
intervals (cycles), but even more precise time information is obtained in ofs as the elapsed time fromtim in nanoseconds. The resolution of ofs is implementation-dependent, but generally is the timer
hardware resolution.
Since tim is time counted based on timer interrupts, in some cases time is not refreshed, when a timer
interrupt cycle arrives while interrupts are disabled and the timer interrupt handler is not started (isdelayed). In such cases, the time as updated by the previous timer interrupt is returned in tim, and theelapsed time from the previous timer interrupt is returned in ofs. Accordingly, in some cases ofs will
be a longer time than the timer interrupt cycle. The length of elapsed time that can be measured byofs depends on the hardware, but preferably it should be able to measure at least up to twice the timer
interrupt cycle (0 ≤ ofs < twice the timer interrupt cycle).
Note that the time returned in tim and ofs is the time at some point between the calling of and returnfrom td get otm. It is neither the time at which td get otm was called nor the time of return fromtd get otm. In order to obtain more accurate information, this function should be called in interrupts
disabled state.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

278

CHAPTER 6. T-KERNEL/DS FUNCTIONS

td ref dsname
Refer to DS Object Name[C Language Interface]
ER ercd = td_ref_dsname ( UINT type, ID id, UB *dsname ) ;[Parameters]
UINT
ID
UB

type
id
*dsnameobject typeobject ID
address to return DS object name[Return Parameters]ER

ercd
dsnameError code
DS object name, set at object creation or by td set dsname()[Error Codes]
E OK
E PAR
E NOEXSE OBJNormal completion
Invalid object typeObject does not exist
DS object name is not used

[Description]
Get DS object name (dsname), which is set at object creation. The object is specified by object type
(type) and object ID (id). Object types (type) are as follows:
TN TSKTN SEMTN FLGTN MBXTN MBFTN PORTN MTXTN MPLTN MPFTN CYCTN ALM

0x01
0x02
0x03
0x04
0x05
0x06
0x07
0x08
0x09
0x0a
0x0b

/* task *//* semaphore *//* event flag *//* mail box *//* message buffer *//* rendezvous port *//* mutex *//* variable-size memory pool *//* fixed-size memory pool *//* cyclic handler *//* alarm handler */DS object name is valid if TA DSNAME is set as object attribute. If DS object name is changed by
td set dsname(), then td ref dsname() refers to the new name. DS object name needs to satisfy thefollowing conditions, but character code range is not checked by T-Kernel.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

6.1. KERNEL INTERNAL STATE REFERENCE FUNCTIONS
character (UB) range:
name length:279

a – z, A – Z, 0 – 9
8 byte (NULL is filled if name length is less than 8 byte)

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

280

CHAPTER 6. T-KERNEL/DS FUNCTIONS

td set dsname
Set DS Object Name[C Language Interface]
ER ercd = td_set_dsname ( UINT type, ID id, UB *dsname ) ;[Parameters]
UINT
ID
UB

type
id
*dsnameobject typeobject ID
DS object name to be set[Return Parameters]
ER

ercd

Error code

[Error Codes]
E OK
E PAR
E NOEXSE OBJNormal completion
Invalid object typeObject does not exist
DS object name is not used

[Description]
Update DS object name (dsname), which is set at object creation. The object is specified by object type
(type) and object ID (id). Object types (type) are as same as that of td ref dsname(). DS object
name needs to satisfy the following conditions, but character code range is not checked by T-Kernel.
character (UB) range:
name length:a – z, A – Z, 0 – 9
8 byte (NULL is filled if name length is less than 8 byte)

DS object name is valid if TA DSNAME is set as object attribute. td set dsname() returns E OBJ error if
TA DSNAME attribute is not specified.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

6.2. TRACE FUNCTIONS

6.2

281

Trace Functions

These functions enable a debugger to trace program execution. Execution trace is performed by setting
hook routines.
• Return from a hook routine must be made after states have returned to where they were when
the hook routine was called. Restoring of registers, however, can be done in accord with the C
language function saving rules.
• In a hook routine, limitations on states must not be modified to make them less restrictive thanwhen the routine was called. For example, if the hook routine was called during interrupts disabledstate, interrupts must not be enabled.
• A hook routine was called at protection level 0.
• A hook routine inherits the stack at the time of the hook. Too much stack use may therefore causea stack overflow. The extent to which the stack can be used is not definite, since it differs withthe situation at the time of the hook. Switching to a separate stack in the hook routine would besafer.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

282

CHAPTER 6. T-KERNEL/DS FUNCTIONS

td hoc svc
td_hok_svc

Define System Call/Extended SVC Hook Routine[C Language Interface]
ER ercd = td_hok_svc ( TD_HSVC *hsvc ) ;[Parameters]
TD HSVC

hsvc

Hook routine definition information

enter
leave

Hook routine before calling
Hook routine after callinghsvc detail:FP
FP[Return Parameters]
ER

ercd

Error code

[Description]
Sets hook routines before and after the issuing of a system call or extended SVC. Setting NULL in hsvc
cancels a hook routine.
The objects of a trace are T-Kernel/OS system calls (tk_—) and extended SVC. Depending on theimplementation, generally tk ret int is not an object of a trace.
T-Kernel/DS service calls (td_—) are not objects of a trace.
A hook routine is called in the context from which the system call or extended SVC was called. For
example, the invoking task in a hook routine is the same as the task that invoked the system call or
extended SVC.
Since task dispatching and interrupts can occur inside system call processing, enter() and leave() are
not necessarily called in succession as a pair in every case. If a system call is one that does not return,leave() will not be called.
VP enter( FN fncd, TD_CALINF *calinf, ... )fncd

calinf...
return code

Function code
< 0 System call
≥ 0 Extended SVC
Caller information
Parameters (variable number)
Any value passed to leave()typedef struct td_calinf {As information for determining the address from which a system call or extended SVC was called, it ispreferable to include information for performing a stack back-trace. The contents are implementationdependent, but generally consist of register values such as stack pointer and program counter.
c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

6.2. TRACE FUNCTIONS

283} TD_CALINF;
This is called right before a system call or extended SVC. The value passed in the return code is passedtransparently to the corresponding leave(). This makes it possible to confirm the pairing of enter()and leave() calls or to pass any other information.
exinf = enter(fncd, &calinf, ... )ret = system call or extended SVC execution
leave(fncd , ret, exinf)• System call The parameters are the same as the system call parameters.
Example:For system call tk wai sem( ID semid, INT cnt, TMO tmout )enter(TFN_WAI_SEM, &calinf, semid, cnt, tmout)• Extended SVC The parameters are as in the packet passed to the extended SVC handler. fncd islikewise the same as that passed to the extended SVC handler.
enter( FN fncd, TD\_CALINF *calinf, VP pk\_para )void leave( FN fncd, INT ret, VP exinf )
fncd
ret
exinf

Function code
Return code of the system call or extended SVC
Any value returned by enter()This is called right after returning from a system call or extended SVC.
When a hook routine is set after a system call or extended SVC is called (while the system call or
extended SVC is executing), in some cases leave() only may be called without calling enter().
In such a case NULL is passed in exinf. If, on the other hand, a hook routine is canceled after asystem call or extended SVC is called, there may be cases when enter() is called but not leave().

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

284

CHAPTER 6. T-KERNEL/DS FUNCTIONS

td hoc dsp
td_hok_dsp

Define Task Dispatch Hook Routine[C Language Interface]
ER ercd = td_hok_dsp ( TD_HDSP *hdsp ) ;[Parameters]
TD HDSP

hdsp

Hook routine definition information

hdsp detail:FP exec Hook routine when execution starts
FP stop Hook routine when execution stops[Return Parameters]
ER

ercd

Error code

[Description]
Sets hook routines in the task dispatcher. A hook routine is canceled by setting NULL in hdsp.
The hook routines are called in dispatch disabled state. The hook routines must not invoke T-Kernel/OS
system calls (tk_—) or extended SVC. T-Kernel/DS service calls (td_—) may be invoked.
void exec( ID tskid, INT lsid )tskid Task ID of the started or resumed task
lsid
Logical ID of the task designated in tskid
This is called when the designated task starts execution or resumes. At the time exec() is called,
the task designated in tskid is already in RUN state and logical space has been switched. However,execution of the tskid task program code occurs after the return from exec().
void stop( ID tskid, INT lsid, UINT tskstat )tskid
Task ID of the executed or stopped task
lsid
Logical ID of the task designated in tskid
tskstat State of the task designated in tskid
This is called when the designated task executes or stops. tskstat indicates the task state after stopping,as one of the following states.
TTS RDY
TTS WAITTS SUSTTS WASTTS DM
0

READY state
WAIT state
SUSPEND state
WAIT-SUSPEND state
DORMANT state
NON-EXISTENT statec 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

6.2. TRACE FUNCTIONS

285

At the time stop() is called, the task designated in tskid has already entered the state indicated in
tskstat. The logical space is indeterminate.

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

286

CHAPTER 6. T-KERNEL/DS FUNCTIONS

td hoc int
td_hok_int

Define Interrupt Handler Hook Routine[C Language Interface]
ER ercd = td_hok_int ( TD_HINT *hint ) ;[Parameters]
TD HINT

hint

Hook routine definition information

enter
leave

Hook routine before calling handler
Hook routine after calling handler

hint detail:FP
FP[Return Parameters]
ER

ercd

Error code

[Description]
Sets hook routines before and after an interrupt handler is called. Hook routine setting cannot be done
independently for different exception or interrupt factors. One pair of hook routines is set in common
for all exception and interrupt factors.
Setting hint to NULL cancels the hook routines.
The hook routines are called as task-independent portion (part of the interrupt handler). Accordingly,
the hook routines can call only those system calls that can be invoked from a task-independent portion.
Note that hook routines can be set only for interrupt handlers defined by tk def int with the TA HLNG
attribute. A TA ASM attribute interrupt handler cannot be hooked by a hook routine. Hooking of a
TA ASM attribute interrupt handler is possible only by directly manipulating the exception/interrupt
vector table. The actual methods are implementation-dependent.
void enter( UINT dintno )void leave( UINT dintno )dintno Interrupt definition number
The parameters passed to enter() and leave() are the same as those passed to the exception/interrupt
handler. Depending on the implementation, information other than dintno may also be passed. A hookroutine is called as follows from a high-level language support routine.
enter(dintno);
inthdr(dintno); /* exception/interrupt handler */leave(dintno);

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

6.2. TRACE FUNCTIONS

287

enter() is called in interrupts disabled state, and interrupts must not be enabled. Since leave()assumes the status on return from inthdr(), the interrupts disabled or enabled status is indeterminate.
enter() can obtain only the same information as that obtainable by inthdr(). Information that cannot
be obtained by inthdr() cannot be obtained by enter(). The information that can be obtained byenter() and inthdr() is guaranteed by the specification to include dintno, but other information is
implementation-dependent. Note that since interrupts disabled state and other states may change while
leave() is running, leave() does not necessarily obtain the same information as that obtained byenter() or inthdr().

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

288

c 2002–2005 by T-Engine Forum
Copyright °CHAPTER 6. T-KERNEL/DS FUNCTIONSTEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

Chapter 7

Reference
7.1

List of C Language Interface

T-Kernel/OS
Task Management Functions
ID
ER
ER
void
void
ER
ER
ER
ER
ER
ID
ID
ER
ER
ER
ER
ER
ER

tskid = tk_cre_tsk ( T_CTSK *pk_ctsk );ercd = tk_del_tsk ( ID tskid );ercd = tk_sta_tsk ( ID tskid, INT stacd );tk_ext_tsk ( );tk_exd_tsk ( );ercd = tk_ter_tsk ( ID tskid );ercd = tk_chg_pri ( ID tskid, PRI tskpri );ercd = tk_chg_slt ( ID tskid, RELTIM slicetime );ercd = tk_get_tsp ( ID tskid, T_TSKSPC *pk_tskspc );ercd = tk_set_tsp ( ID tskid, T_TSKSPC *pk_tskspc );resid = tk_get_rid ( ID tskid );oldid = tk_set_rid ( ID tskid, ID resid );ercd = tk_get_reg ( ID tskid, T_REGS *pk_regs, T_EIT *pk_eit, T_CREGS *pk_cregs );ercd = tk_set_reg ( ID tskid, T_REGS *pk_regs, T_EIT *pk_eit, T_CREGS *pk_cregs );ercd = tk_get_cpr ( ID tskid, INT copno, T_COPREGS *pk_copregs );ercd = tk_set_cpr ( ID tskid, INT copno, T_COPREGS *pk_copregs );ercd = tk_inf_tsk ( ID tskid, T_ITSK *pk_itsk, BOOL clr );ercd = tk_ref_tsk ( ID tskid, T_RTSK *pk_rtsk );Task-Dependent Synchronization Functions
ER
ER
INT
ER
ER
ER
ER
ER
ER

ercd = tk_slp_tsk ( TMO tmout );ercd = tk_wup_tsk ( ID tskid );wupcnt = tk_can_wup ( ID tskid );ercd = tk_rel_wai ( ID tskid );ercd = tk_sus_tsk ( ID tskid );ercd = tk_rsm_tsk ( ID tskid );ercd = tk_frsm_tsk ( ID tskid );ercd = tk_dly_tsk ( RELTIM dlytim );ercd = tk_sig_tev ( ID tskid, INT tskevt );289

TEF020-S001-01.00.01/en

290

CHAPTER 7. REFERENCE
INT tevptn = tk_wai_tev ( INT waiptn, TMO tmout );INT tskwait = tk_dis_wai ( ID tskid, UINT waitmask );ER
ercd = tk_ena_wai ( ID tskid );Task Exception Handling Functions
ER
ER
ER
ER
INT
ER

ercd = tk_def_tex ( ID tskid, T_DTEX *pk_dtex );ercd = tk_ena_tex ( ID tskid, UINT texptn );ercd = tk_dis_tex ( ID tskid, UINT texptn );ercd = tk_ras_tex ( ID tskid, INT texcd );texcd = tk_end_tex ( BOOL enatex );ercd = tk_ref_tex ( ID tskid, T_RTEX *pk_rtex );Synchronization and Management Functions
ID
ER
ER
ER
ER
ID
ER
ER
ER
ER
ER
ID
ER
ER
ER
ER

semid = tk_cre_sem ( T_CSEM *pk_csem );
ercd = tk_del_sem ( ID semid );ercd = tk_sig_sem ( ID semid, INT cnt );ercd = tk_wai_sem ( ID semid, INT cnt, TMO tmout );ercd = tk_ref_sem ( ID semid, T_RSEM *pk_rsem );flgid = tk_cre_flg ( T_CFLG *pk_cflg );ercd = tk_del_flg ( ID flgid );ercd = tk_set_flg ( ID flgid, UINT setptn );ercd = tk_clr_flg ( ID flgid, UINT clrptn );ercd = tk_wai_flg ( ID flgid, UINT waiptn, UINT wfmode, UINT *p_flgptn, TMO tmout );ercd = tk_ref_flg ( ID flgid, T_RFLG *pk_rflg );mbxid = tk_cre_mbx ( T_CMBX* pk_cmbx );ercd = tk_del_mbx ( ID mbxid );ercd = tk_snd_mbx ( ID mbxid, T_MSG *pk_msg );ercd = tk_rcv_mbx ( ID mbxid, T_MSG **ppk_msg, TMO tmout );ercd = tk_ref_mbx ( ID mbxid, T_RMBX *pk_rmbx );Extended Synchronization and Communication Functions
ID
ER
ER
ER
ER
ID
ER
ER
INT
ER
ID
ER
INT
INT
ER
ER
ER

mtxid = tk_cre_mtx ( T_CMTX *pk_cmtx );ercd = tk_del_mtx ( ID mtxid );ercd = tk_loc_mtx ( ID mtxid, TMO tmout );ercd = tk_unl_mtx ( ID mtxid );ercd = tk_ref_mtx ( ID mtxid, T_RMTX *pk_rmtx );mbfid = tk_cre_mbf ( T_CMBF *pk_cmbf );ercd = tk_del_mbf ( ID mbfid );ercd = tk_snd_mbf ( ID mbfid, VP msg, INT msgsz, TMO tmout );msgsz = tk_rcv_mbf ( ID mbfid, VP msg, TMO tmout );ercd = tk_ref_mbf ( ID mbfid, T_RMBF *pk_rmbf );porid = tk_cre_por ( T_CPOR *pk_cpor );ercd = tk_del_por ( ID porid );rmsgsz = tk_cal_por ( ID porid, UINT calptn, VP msg, INT cmsgsz, TMO tmout );cmsgsz = tk_acp_por ( ID porid, UINT acpptn, RNO *p_rdvno, VP msg, TMO tmout );ercd = tk_fwd_por ( ID porid, UINT calptn, RNO rdvno, VP msg, INT cmsgsz );ercd = tk_rpl_rdv ( RNO rdvno, VP msg, INT rmsgsz );ercd = tk_ref_por ( ID porid, T_RPOR *pk_rpor );c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

291

7.1. LIST OF C LANGUAGE INTERFACE
Memory Pool Management Functions
ID
ER
ER
ER
ER
ID
ER
ER
ER
ER

mpfid = tk_cre_mpf ( T_CMPF *pk_cmpf );ercd = tk_del_mpf ( ID mpfid );ercd = tk_get_mpf ( ID mpfid, VP *p_blf, TMO tmout );ercd = tk_rel_mpf ( ID mpfid, VP blf );ercd = tk_ref_mpf ( ID mpfid, T_RMPF *pk_rmpf );mplid = tk_cre_mpl ( T_CMPL *pk_cmpl );ercd = tk_del_mpl ( ID mplid );ercd = tk_get_mpl ( ID mplid, W blksz, VP *p_blk, TMO tmout );ercd = tk_rel_mpl ( ID mplid, VP blk );ercd = tk_ref_mpl ( ID mplid, T_RMPL *pk_rmpl );Time Management Functions
ER
ER
ER
ID
ER
ER
ER
ER
ID
ER
ER
ER
ER

ercd = tk_set_tim ( SYSTIM *pk_tim );ercd = tk_get_tim ( SYSTIM *pk_tim );ercd = tk_get_otm ( SYSTIM *pk_tim );cycid = tk_cre_cyc ( T_CCYC *pk_ccyc );ercd = tk_del_cyc ( ID cycid );ercd = tk_sta_cyc ( ID cycid );ercd = tk_stp_cyc ( ID cycid );ercd = tk_ref_cyc ( ID cycid, T_RCYC *pk_rcyc );almid = tk_cre_alm ( T_CALM *pk_calm );
ercd = tk_del_alm ( ID almid );ercd = tk_sta_alm ( ID almid, RELTIM almtim );ercd = tk_stp_alm ( ID almid );ercd = tk_ref_alm ( ID almid, T_RALM *pk_ralm );Interrupt Management Functions
ER
void

ercd = tk_def_int ( UINT dintno, T_DINT *pk_dint );tk_ret_int ( );System Management Functions
ER
ID
ER
ER
ER
ER
ER

ercd = tk_rot_rdq ( PRI tskpri );tskid = tk_get_tid ( );ercd = tk_dis_dsp ( );ercd = tk_ena_dsp ( );ercd = tk_ref_sys ( T_RSYS *pk_rsys );ercd = tk_set_pow ( UINT powmode );ercd = tk_ref_ver ( T_RVER *pk_rver );Subsystem Management Functions
ER
ER
ER
ER

ercd = tk_def_ssy ( ID ssid, T_DSSY *pk_dssy );ercd = tk_sta_ssy ( ID ssid, ID resid, INT info );ercd = tk_cln_ssy ( ID ssid, ID resid, INT info );ercd = tk_evt_ssy ( ID ssid, INT evttyp, ID resid, INT info );c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

292

CHAPTER 7. REFERENCE
ER
ID
ER
ER

ercd = tk_ref_ssy ( ID ssid, T_RSSY *pk_rssy );resid = tk_cre_res ( );ercd = tk_del_res ( ID resid );ercd = tk_get_res ( ID resid, ID ssid, VP *p_resblk );T-Kernel/SM
System Memory Management FunctionsER
tk_get_smb ( VP *addr, INT nblk, UINT attr );ER
tk_rel_smb ( VP addr );void*
Vmalloc ( size_t size );void*
Vcalloc ( size_t nmemb, size_t size );void*
Vrealloc ( void *ptr, size_t size );void
Vfree ( void *ptr );void*
Kmalloc ( size_t size );void*
Kcalloc ( size_t nmemb, size_t size );void*
Krealloc ( void *ptr, size_t size );void
Kfree ( void *ptr );Address Space Management Functions
ER
SetTaskSpace ( ID tskid );ER
ChkSpaceR ( VP addr, INT len );ER
ChkSpaceRW ( VP addr, INT len );ER
ChkSpaceRE ( VP addr, INT len );INT
ChkSpaceBstrR ( UB *str, INT max );INT ChkSpaceBstrRW ( UB *str, INT max );INT
ChkSpaceTstrR ( TC *str, INT max );INT ChkSpaceTstrRW ( TC *str, INT max );ER
LockSpace ( VP addr, INT len );ER
UnlockSpace ( VP addr, INT len );INT CnvPhysicalAddr ( VP vaddr, INT len, VP *paddr );ER
MapMemory ( VP paddr, INT len, UINT attr, VP *laddr );ER
UnmapMemory ( VP laddr );Device Management Functions
ID
ER
ID
ER
ID
ER
ID
INT
ID
ID
ID
INT
INT

tk_opn_dev ( UB *devnm, UINT omode );tk_cls_dev ( ID dd, UINT option );tk_rea_dev ( ID dd, INT start, VP buf, INT size, TMO tmout );tk_srea_dev ( ID dd, INT start, VP buf, INT size, INT *asize );tk_wri_dev ( ID dd, INT start, VP buf, INT size, TMO tmout );tk_swri_dev ( ID dd, INT start, VP buf, INT size, INT *asize );tk_wai_dev ( ID dd, ID reqid, INT *asize, ER *ioer, TMO tmout );tk_sus_dev ( UINT mode );tk_get_dev ( ID devid, UB *devnm );tk_ref_dev ( UB *devnm, T_RDEV *rdev );tk_oref_dev ( ID dd, T_RDEV *rdev );tk_lst_dev ( T_LDEV *ldev, INT start, INT ndev );tk_evt_dev ( ID devid, INT evttyp, VP evtinf );c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

7.1. LIST OF C LANGUAGE INTERFACE
ID
ER

293

tk_def_dev ( UB *devnm, T_DDEV *ddev, T_IDEV *idev );tk_ref_idv ( T_IDEV *idev );Interrupt Management Functions

BOOL
UINT
void
void
void
void
BOOL

DI ( UINT intsts );EI ( UINT intsts );isDI ( UINT intsts );DINTNO ( INTVEC intvec );EnableInt ( INTVEC intvec [, INT level] );DisableInt ( INTVEC intvec );ClearInt ( INTVEC intvec );EndOfInt ( INTVEC intvec );CheckInt ( INTVEC intvec );IO Port Access Support Functions
void
void
void
UW
UH
UB
void
void

out_w ( INT port, UW data );out_h ( INT port, UH data );out_b ( INT port, UB data );in_w ( INT port );in_h ( INT port );in_b ( INT port );WaitUsec ( UINT usec );WaitNsec ( UINT nsec );Power Management Functions
void
void

low_pow ( void );off_pow ( void );System Configuration Information Management Functions
INT
INT

tk_get_cfn ( UB *name, INT *val, INT max );tk_get_cfs ( UB *name, UB *buf, INT max );T-Kernel/DS
Kernel Internal State Acquisition Functions
INT
INT
INT
INT
INT
INT
INT
INT
INT
INT
INT

ct = td_lst_tsk ( ID list[], INT nent );ct = td_lst_sem ( ID list[], INT nent );ct = td_lst_flg ( ID list[], INT nent );ct = td_lst_mbx ( ID list[], INT nent );ct = td_lst_mtx ( ID list[], INT nent );ct = td_lst_mbf ( ID list[], INT nent );ct = td_lst_por ( ID list[], INT nent );ct = td_lst_mpf ( ID list[], INT nent );ct = td_lst_mpl ( ID list[], INT nent );ct = td_lst_cyc ( ID list[], INT nent );ct = td_lst_alm ( ID list[], INT nent );c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

294

CHAPTER 7. REFERENCE
ct = td_lst_ssy ( ID list[], INT nent );ct = td_rdy_que ( PRI pri, ID list[], INT nent );ct = td_sem_que ( ID semid, ID list[], INT nent );ct = td_flg_que ( ID flgid, ID list[], INT nent );ct = td_mbx_que ( ID mbxid, ID list[], INT nent );ct = td_mtx_que ( ID mtxid, ID list[], INT nent );ct = td_smbf_que ( ID mbfid, ID list[], INT nent );ct = td_rmbf_que ( ID mbfid, ID list[], INT nent );ct = td_cal_que ( ID porid, ID list[], INT nent );ct = td_acp_que ( ID porid, ID list[], INT nent );ct = td_mpf_que ( ID mpfid, ID list[], INT nent );ct = td_mpl_que ( ID mplid, ID list[], INT nent );ercd = td_ref_tsk ( ID tskid, TD_RTSK *rtsk );ercd = td_ref_sem ( ID semid, TD_RSEM *rsem );
ercd = td_ref_flg ( ID flgid, TD_RFLG *rflg );ercd = td_ref_mbx ( ID mbxid, TD_RMBX *rmbx );ercd = td_ref_mtx ( ID mtxid, TD_RMTX *rmtx );ercd = td_ref_mbf ( ID mbfid, TD_RMBF *rmbf );ercd = td_ref_por ( ID porid, TD_RPOR *rpor );ercd = td_ref_mpf ( ID mpfid, TD_RMPF *rmpf );ercd = td_ref_mpl ( ID mplid, TD_RMPL *rmpl );ercd = td_ref_cyc ( ID cycid, TD_RCYC *rcyc );ercd = td_ref_alm ( ID almid, TD_RALM *ralm );
ercd = td_ref_ssy ( ID ssid, TD_RSSY *rssy );ercd = td_ref_tex ( ID tskid, TD_RTEX *pk_rtex );ercd = td_inf_tsk ( ID tskid, TD_ITSK *pk_itsk, BOOL clr );ercd = td_get_reg ( ID tskid, T_REGS *pk_regs, T_EIT *pk_eit, T_CREGS *pk_cregs );ercd = td_set_reg ( ID tskid, T_REGS *pk_regs, T_EIT *pk_eit, T_CREGS *pk_cregs );ercd = td_ref_sys ( TD_RSYS *pk_rsys );ercd = td_get_tim ( SYSTIM *tim, UNIT *ofs );ercd = td_get_otm ( SYSTIM *tim, UINT *ofs );ercd = td_ref_dsname ( UINT type, ID id, UB *dsname );ercd = td_set_dsname ( UINT type, ID id, UB *dsname );

INT
INT
INT
INT
INT
INT
INT
INT
INT
INT
INT
INT
ER
ER
ER
ER
ER
ER
ER
ER
ER
ER
ER
ER
ER
ER
ER
ER
ER
ER
ER
ER
ER

Trace Functions
ER
ER
ER

7.2

ercd = td_hok_svc ( TD_HSVC *hsvc );ercd = td_hok_dsp ( TD_HDSP *hdsp );ercd = td_hok_int ( TD_HINT *hint );List of Error Codes

Normal Completion Error Class (0)E OK

0Normal completion

Internal Error Class (5 to 8)
E SYSERCD(-5, 0)

System error

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

7.2. LIST OF ERROR CODES

295

An error of unknown cause affecting the system as a whole.
E NOCOP

The specified co-processor cannot be used (not installed, or abnormal operation
detected)

ERCD(-6, 0)This error code is returned when the specified co-processor is not installed in the currently
running hardware, or abnormal co-processor operation was detected.
Unsupported Error Class (9 to 16)
E NOSPT

ERCD(-9, 0)

Unsupported function

When some system call functions are not supported and such a function was specified, error
code E RSATR or E NOSPTS is returned. If E RSATR does not apply, error code E NOSPT isreturned.
E RSFN

Reserved function code number

ERCD(-10, 0)This error code is returned when it is attempted to execute a system call specifying areserved function code (undefined function code), and also when it is attempted to execute
an undefined extended SVC handler.
E RSATR

ERCD(-11, 0)Reserved attribute

This error code is returned when an undefined or unsupported object attribute is specified.
Checking for this error may be omitted if system-dependent optimization is implemented.
Parameter Error Class (17 to 24)
E PAR

ERCD(-17, 0)

Parameter error

Checking for this error may be omitted if system-dependent optimization is implemented.
E ID

ERCD(-18, 0)

Invalid ID number

E ID is an error that occurs only for objects having an ID number. Error code E PAR isreturned when a static error is detected for such as reserved number or out of range of suchas interrupt definition number.
Call Context Error Class (25 to 32)
E CTX

ERCD(-25, 0)Context error

This error indicates that the specified system call cannot be issued in the current context(task portion/task-independent portion or handler RUN state).
This error must be issued whenever there is a meaningful context error in issuing a systemcall, such as calling from a task-independent portion a system call that may put the invoking
task in WAIT state. Due to implementation limitations, there may be other system callsthat when called from a given context (such as an interrupt handler) will cause this error tobe returned.
E MACVERCD(-26, 0)

Memory cannot be accessed; memory access privilege error

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

296

CHAPTER 7. REFERENCE
Error detection is implementation-dependent.

E OACVERCD(-27, 0)

Object access privilege error

This error code is returned when a user task tries to manipulate a system object. The
definition of system objects and error detection are implementation-dependent.
E ILUSEERCD(-28, 0)

System call illegal use

Resource Constraint Error Class (33 to 40)
E NOMEMERCD(-33, 0)Insufficient memory

This error code is returned when there is insufficient memory (no memory) for allocating an
object control block space, user stack space, memory pool space, message buffer space or thelike.
E LIMITERCD(-34, 0)

System limit exceededThis error code is returned when it is attempted to create more of an object than the systemallows.
Object State Error Class (41 to 48)
E OBJ
E NOEXSE QOVRERCD(-41, 0)
ERCD(-42, 0)
ERCD(-43, 0)

Invalid object state
Object does not exist
Queuing or nesting overflow

Wait Error Class (49 to 56)
E RLWAIE TMOUTE DLTE DISWAIERCD(-49, 0)
ERCD(-50, 0)
ERCD(-51, 0)
ERCD(-52, 0)

WAIT state released
Polling failed or timeout
The object being waited for was deletedWait released by wait disabled state

Device Error Class (57 to 64) (T-Kernel/SM)
E IO

ERCD(-57, 0)

IO error• Error information specific to individual devices may be defined in E IO sub-codes.
E NOMDAERCD(-58, 0)

No media

Status Error Class (65 to 72) (T-Kernel/SM)
E BUSYE ABORT
E RONLY

ERCD(-65, 0)
ERCD(-66, 0)
ERCD(-67, 0)

Busy
Processing was aborted
Write protected

c 2002–2005 by T-Engine Forum
Copyright °TEF020–S001–01.00.00/en

TEF020-S001-01.00.01/en

TEF020-S001-01.00.01/en