RTXC Kernel ServicesV2 Decrypted

(1)

RTXC Kernel Services

Reference, Volume 2

Tasks, Semaphores, Queues,

Quadr

os

Systems Inc.

(2)

Disclaimer

Quadros Systems, Inc. makes no representations or warranties with respect to the contents or use of this manual, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Quadros Systems, Inc. reserves the right to revise this publication and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes. Quadros Systems, Inc. makes no representations or warranties with respect to any Quadros software, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Quadros Systems, Inc. reserves the right to make changes to any and all parts of Quadros software, at any time, without any obligation to notify any person or entity of such changes. Trademarks

Quadros is a registered trademark of Quadros Systems, Inc. RTXC, RTXC Quadros, and RTXC DSP are trademarks of Quadros Systems, Inc. Other product and company names mentioned in this document may be the trademarks or registered trademarks of their respective owners. Copyright

©

2002 Quadros Systems, Inc. All rights reserved. No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transmitted without the express written consent of the publisher.

Quadros Systems, Inc. 10450 Stancliff, Suite 110 Houston, TX 77099-4336 USA

RTXC Kernel Services Reference, Volume 2

Part Number: RTXC-KSRV2-0602 June 2002

(3)

KS_ExecuteTask ... 42 KS_GetTaskEnvArg ... 44 KS_GetTaskClassProp ... 47 KS_GetTaskID... 50 KS_GetTaskName... 51 KS_GetTaskPriority ... 53 KS_GetTaskProp ... 54 KS_GetTaskSema... 56 KS_GetTaskState... 58 KS_GetTickSlice... 60 INIT_TaskClassProp... 62 KS_LookupTask ... 64 KS_OpenTask... 66 XX_ResumeTask... 68 KS_SleepTask... 70 KS_SuspendTask ... 71 KS_TerminateTask ... 72 KS_UseTask ... 74 KS_YieldTask ... 76 C H A P T E R 3 Semaphore Services ... 79 KS_CloseSema ... 80 KS_DefSemaCount ... 82 KS_DefSemaName ... 84 KS_DefSemaProp ... 86 KS_GetSemaClassProp... 88 KS_GetSemaCount ... 90 KS_GetSemaName ... 92 KS_GetSemaProp ... 94 INIT_SemaClassProp ... 96 KS_LookupSema ... 98 KS_OpenSema ... 100 XX_SignalSema... 102 XX_SignalSemaM... 104 KS_TestSema ... 106 KS_TestSemaT ... 108 KS_TestSemaM... 110 KS_TestSemaMT ... 112 KS_TestSemaMW ... 115 KS_TestSemaW... 118

(5)

KS_UseSema ...120 C H A P T E R 4 Queue Services ...123 KS_CloseQueue ...124 KS_DefQueueName ...126 KS_DefQueueProp ...128 KS_DefQueueSema...130 KS_GetQueueClassProp ...134 KS_GetQueueData ...136 KS_GetQueueDataT ...138 KS_GetQueueDataW...140 KS_GetQueueName ...142 KS_GetQueueProp ...144 KS_GetQueueSema...146 INIT_QueueClassProp...148 KS_LookupQueue...150 KS_OpenQueue ...152 KS_PutQueueData...156 KS_PutQueueDataT ...158 KS_PutQueueDataW...160 KS_UseQueue...162 C H A P T E R 5 Mailbox Services ...165 KS_CloseMbox...166 KS_DefMboxName...168 KS_DefMboxProp...170 KS_DefMboxSema...172 KS_GetMboxClassProp ...176 KS_GetMboxName...178 KS_GetMboxProp ...180 KS_GetMboxSema...182 INIT_MboxClassProp...184 KS_LookupMbox ...186 KS_OpenMbox...188 KS_UseMbox ...191

(6)

KS_ReceiveMsgT... 202 KS_ReceiveMsgW ... 204 KS_SendMsg ... 206 KS_SendMsgT... 209 KS_SendMsgW ... 213 KS_TestAck ... 216 KS_TestAckT ... 218 KS_TestAckW... 220

C H A P T E R 7 Memory Partition Services... 223

XX_AllocBlk ... 224 KS_AllocBlkT ... 226 KS_AllocBlkW ... 228 KS_ClosePart... 230 KS_DefPartName... 232 KS_DefPartProp... 234 KS_DefPartSema... 236 KS_FreeBlk... 238 KS_GetFreeBlkCount ... 240 KS_GetPartClassProp ... 242 KS_GetPartName ... 244 KS_GetPartProp ... 246 KS_GetPartSema... 248 INIT_PartClassProp... 250 KS_LookupPart ... 252 KS_OpenPart... 254 KS_UsePart ... 256 C H A P T E R 8 Mutex Services ... 259 KS_CloseMutx... 260 KS_DefMutxName ... 262 KS_DefMutxProp ... 264 KS_DefMutxSema... 267 KS_GetMutxClassProp ... 270 KS_GetMutxName ... 272 KS_GetMutxOwner... 274 KS_GetMutxProp ... 276 KS_GetMutxSema... 278 INIT_MutxClassProp... 280 KS_LookupMutx... 282

(7)

KS_OpenMutx ...284 KS_ReleaseMutx ...286 KS_TestMutx...288 KS_TestMutxT ...290 KS_TestMutxW...294 KS_UseMutx ...296 C H A P T E R 9 Special Services...299 XX_AllocSysRAM ...300 XX_DefFatalErrorHandler ...302 XX_GetFreeSysRAMSize ...304 XX_GetFatalErrorHandler ...305 KS_GetSysProp...306 KS_GetVersion ...308 INIT_SysProp ...310 KS_Nop ...313 KS_UserService ...314

A P P E N D I X A Fatal Error Codes ...317

(8)

(9)

List of Tables

Table 1-1 Kernel Service Description Format...3

Table 1-2 Kernel Service Return Value Types ...6

Table 1-3 Task Services Summary ...8

Table 1-4 Semaphore Services Summary ...10

Table 1-5 Queue Services Summary ...12

Table 1-6 Mailbox Services Summary ...14

Table 1-7 Message Services Summary ...15

Table 1-8 Memory Partition Services Summary ...16

Table 1-9 Mutex Services Summary ...18

Table 1-10 Special Services Summary ...20

Table 2-1 Task Class Attributes and Masks ...48

Table 3-1 Semaphore Class Attributes and Masks...89

Table 4-1 Queue Class Attributes and Masks...135

Table 5-1 Mailbox Class Attributes and Masks...176

Table 7-1 Memory Partition Class Attributes and Masks ...243

Table 8-1 Mutex Class Attributes and Masks ...271

(10)

(11)

List of Examples

Example 2-1 Abort Task and Terminate...24

Example 2-2 Close Task When Signaled...26

Example 2-3 Define Task Properties ...28

Example 2-4 Define Task Name ...31

Example 2-5 Define Task Priorities ...33

Example 2-6 Task Properties Structure ...34

Example 2-7 Define Task Object Class Properties ...35

Example 2-8 Define Task Termination Semaphore ...37

Example 2-9 Define Tick Slice ...39

Example 2-10 Disable Task Scheduler ...40

Example 2-11 Enable Task Scheduler...41

Example 2-12 Execute Task ...43

Example 2-13 Read Task Environment Arguments ...46

Example 2-14 Read Task Object Class Properties ...49

Example 2-15 Read Current Task Number ...50

Example 2-16 Read Dynamic Task Name ...52

Example 2-17 Read and Change Task Priority...53

Example 2-18 Terminate Task and Release Its Stack ...55

Example 2-19 Read Task Termination Semaphore ...57

Example 2-20 Read Task State ...59

Example 2-21 Read Task Tick-Slice Quantum...60

Example 2-22 Object Class Properties Structure ...62

Example 2-23 Initialize Task Object Class ...63

Example 2-24 Look Up Task by Name...65

Example 2-25 Allocate Dynamic Task ...67

Example 2-26 Resume Suspended Task from Zone 3 ...69

(12)

Example 2-31 Yield to Another Task... 77

Example 3-1 Close Semaphore... 81

Example 3-2 Set Semaphore Count ... 83

Example 3-3 Assign Semaphore Name ... 85

Example 3-4 Semaphore Properties Structure ... 86

Example 3-5 Specify Semaphore Waiting Order... 87

Example 3-6 Class Properties Structure ... 88

Example 3-7 Read Semaphore Object Class Properties... 89

Example 3-8 Read Semaphore Count ... 91

Example 3-9 Read Semaphore Name... 93

Example 3-10 Read Semaphore Properties ... 95

Example 3-11 Initialize Semaphore Object Class ... 97

Example 3-12 Look Up Semaphore by Name... 99

Example 3-13 Allocate Dynamic Semaphore ... 101

Example 3-14 Signal Semaphore from Zone 3 ... 103

Example 3-15 Signal List of Semaphores from Zone 3 ... 105

Example 3-16 Test Semaphore ... 107

Example 3-17 Test Semaphore—Wait Number of Ticks for Signal ... 109

Example 3-18 Test List of Semaphores ... 111

Example 3-19 Test List of Semaphores—Wait Number of Ticks for Signal ... 114

Example 3-20 Test List of Semaphores—Wait for Signal... 117

Example 3-21 Test Semaphore—Wait for Signal... 119

Example 3-22 Read Semaphore Handle and Register It ... 121

Example 4-1 Close Queue... 125

Example 4-2 Assign Queue Name ... 127

Example 4-3 Queue Properties Structure ... 128

Example 4-4 Define Queue Object Class Properties... 129

Example 4-5 Associate Queue Event with Semaphore ... 132

Example 4-6 Read Queue Object Class Properties... 135

Example 4-7 Read Queue Entry... 137

Example 4-8 Read Queue Entry—Wait Number of Ticks If Necessary... 139

Example 4-9 Read Queue Entry—Wait If Necessary ... 141

Example 4-10 Read Dynamic Queue Name ... 143

Example 4-11 Read Queue Properties ... 145

Example 4-12 Read Queue Semaphore ... 147

Example 4-13 Initialize Queue Object Class ... 149

Example 4-14 Look Up Queue by Name... 151

Example 4-15 Allocate and Initialize Queue ... 154

Example 4-16 Put Data Into Queue ... 157

(13)

Example 4-18 Put Data Into Queue—Wait Until Queue Has Room...161

Example 4-19 Read Queue Handle and Register It ...163

Example 5-1 Close Mailbox ...167

Example 5-2 Assign Mailbox Name...169

Example 5-3 Mailbox Properties Structure ...170

Example 5-4 Define Mailbox Properties...171

Example 5-5 Define Mailbox Semaphore...174

Example 5-6 Read Mailbox Object Class Properties...177

Example 5-7 Read Mailbox Name ...179

Example 5-8 Read Mailbox Properties...181

Example 5-9 Read Mailbox Semaphore...183

Example 5-10 Initialize Mailbox Object Class...185

Example 5-11 Look Up Mailbox by Name ...187

Example 5-12 Allocate Mailbox ...189

Example 5-13 Read Mailbox Handle and Register It...192

Example 6-1 Acknowledge Message ...195

Example 6-2 Forward Message ...198

Example 6-3 Receive Next Message from a Mailbox ...201

Example 6-4 Receive Message—Wait Number of Ticks If Necessary...203

Example 6-5 Receive Message—Wait If Necessary ...205

Example 6-6 Send Message—Wait for Acknowledgment...208

Example 6-7 Send Message—Wait Number of Ticks for Acknowledgment ...212

Example 6-8 Send Message—Wait for Acknowledgment...214

Example 6-9 Test for Message Acknowledgment ...217

Example 6-10 Test for Message Acknowledgment—Wait Number of Ticks for Acknowledgment ...219

Example 6-11 Test for Acknowledgment and Wait if Necessary ...221

Example 7-1 Allocate Block of Memory...225

Example 7-2 Allocate Block of Memory—Wait Number of Ticks If Necessary.227 Example 7-3 Allocate Block of Memory—Wait If Necessary ...229

Example 7-4 Close Memory Partition...231

Example 7-5 Assign Memory Partition Name ...233

Example 7-6 Define Memory Partition Properties ...235

Example 7-7 Associate Semaphore With Memory Partition...237

Example 7-8 Allocate and Free Memory Block ...239

Example 7-9 Read Memory Partition Free Block Count ...241

(14)

Example 7-14 Read Memory Partition Semaphore... 249

Example 7-15 Initialize Memory Partition Object Class... 251

Example 7-16 Look Up Memory Partition by Name ... 253

Example 7-17 Allocate and Name Memory Partition... 255

Example 7-18 Read Memory Partition Handle and Register It... 257

Example 8-1 Close Mutex ... 261

Example 8-2 Close Mutex ... 263

Example 8-3 Define Mutex Properties ... 266

Example 8-4 Associate Semaphore with Mutex ... 268

Example 8-5 Read Mutex Object Class Properties ... 271

Example 8-6 Read Mutex Name ... 273

Example 8-7 Read Mutex Owner... 275

Example 8-8 Read Mutex Properties ... 277

Example 8-9 Read Mutex Semaphore ... 279

Example 8-10 Initialize Mutex Object Class... 281

Example 8-11 Look Up Mutex by Name ... 283

Example 8-12 Allocate and Name Mutex... 285

Example 8-13 Release Mutex ... 287

Example 8-14 Test Mutex for Ownership by Current Task ... 289

Example 8-15 Test Mutex—Wait Number of Ticks If Not Available ... 292

Example 8-16 Test Mutex—Wait If Not Available ... 295

Example 8-17 Read Mutex Handle and Register It ... 297

Example 9-1 Allocate System RAM from Zone 3... 301

Example 9-2 Define Fatal Error Function... 303

Example 9-3 Read Amount of Available System RAM from Zone 3 ... 304

Example 9-4 Read Fatal Error Function... 305

Example 9-5 Read System Properties ... 307

Example 9-6 Read Version Number... 309

Example 9-7 Initialize Kernel Properties ... 312

Example 9-8 Execute No-Operation Service ... 313

(15)

C H A P T E R

1 Introduction To RTXC/ms Kernel

Services

In This Chapter

We discuss the contents of this manual, then list the kernel services by class and briefly describe each service.

Using This Manual...2

Kernel Service Description Format ...2

Prototypes ...2

General Form of Kernel Service Call ...4

Arguments to Kernel Services ... 5

Kernel Service Return Codes ... 5

Diagnostic Mode and Fatal Errors ... 5

Kernel Service Classes ... 7

RTXC/ms Component Services ...8

Task Management Services...8

Semaphore Services ... 10

Queue Services ... 12

Mailbox Services ... 14

Message Services ...15

Memory Partition Management Services ... 16

Mutex Management Services... 18

(16)

Using This Manual

Note: The RTXC Kernel Services Reference, Volume 1 contains information needed by users of both the Single Stack and the Dual Mode configurations of the RTXC Kernel. If you purchase the Single Stack configuration (RTXC/ss only) of the RTXC Kernel, you receive only Volume 1 of this book.

The RTXC Kernel Services Reference, Volume 2 contains information needed by users of the Dual Mode

configuration of the RTXC Kernel. If you purchase the Dual Mode configuration (both RTXC/ss and RTXC/ms), you receive both Volume 1 and Volume 2.

Kernel services are the functions performed by a real time kernel. This manual describes the complete set of kernel services available in the RTXC Kernel. This section describes the types of information and the organization of that information in this manual.

Kernel Service Description Format

The remaining chapters of this manual describe each kernel service in detail. The chapters separate the services into classes or

subclasses, and the descriptions are in alphabetical order of the service name minus the service prefix within each class or subclass. Each description includes a complete explanation of the kernel service function, according to the topics listed in Table 1-1 on page 3.

Prototypes

The Synopsis section of each service description shows the formal ANSI C declaration and argument prototype for that service. These prototypes come from the rtxcapi.h file, which is included with each RTXC RTOS Software Development Kit (SDK). Because the RTXC Kernel is designed with portability in mind, the API defined in the rtxcapi.h file is essentially identical for all RTXC RTOS SDKs. However, there are differences between some of the processors on

(17)

Using This Manual

which the RTXC Kernel operates that lead to variations in the size of certain parameters used by the kernel services.

Similarly, there may be syntactical differences between C compilers from different manufacturers. For example, one C compiler may use the key words near and far to permit different memory models due

to the processor’s architecture, whereas a compiler targeted to a different processor may not require the near and far keywords.

Table 1-1. Kernel Service Description Format

Name Brief Functional Description

Zones The zonal prefixes supported by the service (IS_, TS_,

KS_), if more than one.a

Synopsis The formal ANSI C declaration including argument prototyping.

Inputs A brief description of each input argument.

Description A complete description of what the service does, the data types it uses, and so on.

Outputs A description of each argument modified by the service and each possible return value from the service.

Example One or more typical uses of the service. The examples assume the syntax of ANSI Standard C.b

SELFTASK is used in many of the examples to denote

the Current Task. It is defined in rtxcapi.h as

(TASK)0.

SELFTHREAD is used in many of the examples to

denote the Current Thread. It is defined in

(18)

Using This Manual

General Form of Kernel Service Call

The general form of an RTXC Kernel service function call is:

XX_name ([arg1][, arg2]...[, argn])

where the service prefix character string XX_ is one of the following:

Some services are callable from all three zones, others from zones 2 and 3, and still others from Zone 2 or Zone 3 only. The detailed descriptions of the services in this book include the zones from which the service can be called if it can be called from more than one. Following the service prefix is the name of the RTXC Kernel service. The service prefix should prevent the name from being misidentified by a linker with some similarly-named function in the runtime library of the compiler. In general, name is composed as follows:

<Verb><Class>[noun|property][suffix]

See Also A list of related kernel services, if any, that could be examined in conjunction with the current function.

Special Notes Additional notes and technical comments, if any. a. Services that support more than one zone are listed with an XX_

prefix. The XX_ prefix is not a valid prefix, only a placeholder. b. The code examples in this manual often refer to functions or

entities outside the given code fragment used in the example. The functions or entities so referenced may be real or assumed within the actual context of the code example but are not shown. The purpose of such references is to add coherence to the example rather than to imply a particular methodology or usage.

IS_ Identifies a service callable from an exception handler in Zone 1.

TS_ Identifies a thread-based service callable from Zone 2.

KS_ Identifies a service callable from Zone 3.

Table 1-1. Kernel Service Description Format (continued)

(19)

Using This Manual

where the strings within the angle brackets (<>) are mandatory and those within the brackets ([]) are optional. The vertical bar (|) indicates an OR. Therefore, the general composition of name is a verb, followed by the object class, followed by an optional noun or object property, followed by an optional suffix.

The optional suffix is one or more upper-case characters and is used as a qualifier for the service:

Arguments to Kernel Services

The RTXC Kernel service descriptions show the function prototypes with generalized RTXC arguments. Similarly, the descriptions show the values returned from kernel service functions symbolically as described in Table 1-2 on page 6.

Kernel Service Return Codes

Many of the RTXC Kernel services return a value that conveys information about the service’s operation. This value is the kernel service return code (KSRC) value. The Outputs section of each service description lists and describes the KSRC values for the service.

Diagnostic Mode and Fatal Errors

The RTXC Kernel provides a diagnostic mode of operation to speed

W Indicates an unconditional wait version of the service. For example, the KS_AllocBlkW service is the unconditional wait version of the KS_AllocBlk service.

T Indicates a tick-limited wait version of the service. For example, the

KS_AllocBlkT service is the tick-limited wait version of the

KS_AllocBlk service.

M Indicates a service to be performed on multiple semaphore objects. For example, KS_SignalSemaM signals multiple semaphores.

(20)

Using This Manual

description lists and describes the fatal errors that may be generated by the service. For a complete list of the error codes and the services that generate those codes, see Appendix A, “Fatal Error Codes.”

Table 1-2. Kernel Service Return Value Types

Symbol Description

TASK Task handle

THREAD Thread handle

PRIORITY Priority of a task or a message

TSLICE Number of TICKS in the time quantum for a time-sliced task

SEMA Semaphore handle

SEMACOUNT Number of signals that a semaphore has received

MBOX Mailbox handle

MSGENV Message envelope

QUEUE Queue handle

PART Memory partition handle

BLKSIZE Size of a block of memory in a partition

MUTX Mutex handle

EVNTSRC Event Source handle

COUNTER Counter handle

ALARM Alarm handle

TICKS Units of time maintained by the system time base

EXCPTN Exception handle

(21)

Using This Manual

Kernel Service Classes

The RTXC/ss component kernel services are divided into the following basic classes and subclasses:

` Thread Management

` Exception Management

` Pipe Management

` Event Source Management

` Counter Management

` Alarm Management

The RTXC/ms component kernel services are divided into the following basic classes and subclasses:

` Task Management

` Intertask Communication and Synchronization

Z Semaphores

Z Queues

Z Mailboxes

Z Messages

` Memory Partition Management

` Mutex Management

The RTXC Kernel also includes a number of kernel services that are independent of the object classes and are available for use in either component. These services are called Special Services.

The remaining sections describe each class and subclass. Each section includes a table listing all of the services within that class or subclass. The table contains a brief description of each service and a

(22)

RTXC/ms Component Services

The RTXC/ms component of the RTXC Kernel provides a multiple independent stack model for a fully pre-emptive, multitasking scheduler with a rich set of kernel services well suited to

deterministic, hard real-time system requirements. The following sections describe the object classes supported in the RTXC/ms component and their related kernel services.

Task Management Services

The Task Management services, listed in Table 1-3, allow for complete control of tasks and their respective interactions, including starting and stopping tasks and maintaining information about task states. For detailed descriptions, see Chapter 2, “Task Services.”

Table 1-3. Task Services Summary

Service Description Zones Ref.

KS_AbortTask Abort the execution of a task. 23

KS_CloseTask End the use of a dynamic task. 25

KS_DefTaskEnvArg Define the environment arguments for a task.

27

KS_DefTaskName Define the name of a previously opened dynamic task.

30

KS_DefTaskPriority Define a new priority for a task. 32

KS_DefTaskProp Define the properties of a task. 34

KS_DefTaskSema Associate a semaphore with the termination or abortion of a task.

36

KS_DefTickSlice Define the tick-slice quantum for a task. 38

KS_DisableTaskScheduler Disable the task scheduler to prevent task context switching.

40

KS_EnableTaskScheduler Enable the scheduler to allow context switching between tasks.

(23)

KS_ExecuteTask Execute a task. 42

KS_GetTaskEnvArg Get the address of a task’s environment arguments.

44

KS_GetTaskClassProp Get the Task object class properties. 47

KS_GetTaskID Get the handle of the Current Task. 50

KS_GetTaskName Get the name of a task. 51

KS_GetTaskPriority Get the priority of a task. 53

KS_GetTaskProp Get the properties of a task. 54

KS_GetTaskSema Get the handle of the semaphore associated with the termination or abortion of a task.

56

KS_GetTaskState Get the state of a task. 58

KS_GetTickSlice Get the tick-slice quantum of a task. 60

INIT_TaskClassProp Initialize the Task object class properties. 62

KS_LookupTask Look up a task’s name to get its handle. 64

KS_OpenTask Allocate and name a dynamic task. 66

XX_ResumeTask Resume a task that was previously suspended.

68

KS_SleepTask Put the Current Task to sleep for a period of time.

70

KS_SuspendTask Suspend a task. 71

KS_TerminateTask Terminate a task. 72

Table 1-3. Task Services Summary (continued)

(24)

Semaphore Services

The Semaphore kernel services, listed in Table 1-4, provide intertask synchronization between the calling task and other tasks through semaphores. For detailed descriptions, see Chapter 3, “Semaphore Services.”

Table 1-4. Semaphore Services Summary

KS_CloseSema End the use of a dynamic semaphore. 80

KS_DefSemaCount Define a semaphore count. 82

KS_DefSemaName Define the name of a previously opened dynamic semaphore.

84

KS_DefSemaProp Define the properties of a semaphore. 86

KS_GetSemaClassProp Get the Semaphore object class properties. 88

KS_GetSemaCount Get the current semaphore count. 90

KS_GetSemaName Get the name of a semaphore. 92

KS_GetSemaProp Get the properties of a semaphore. 94

INIT_SemaClassProp Initialize the Semaphore object class properties. 96

KS_LookupSema Look up a semaphore’s name to get its handle. 98

KS_OpenSema Allocate and name a dynamic semaphore. 100

XX_SignalSema Signal a semaphore. 102

XX_SignalSemaM Signal multiple semaphores. 104

KS_TestSema Test a semaphore. 106

KS_TestSemaT Test a semaphore and wait for a specified number of ticks on a specified counter if the semaphore is not DONE.

(25)

KS_TestSemaM Test a list of semaphores. 110

KS_TestSemaMT Test a list of semaphores and wait a specified number of ticks for a signal.

112

KS_TestSemaMW Test a list of semaphores and wait for a signal. 115

KS_TestSemaW Test a semaphore and wait if the semaphore is not

DONE.

118

KS_UseSema Look up a dynamic semaphore by name and mark it for use.

120

Table 1-4. Semaphore Services Summary (continued)

(26)

Queue Services

The Queue directives, listed in Table 1-5, provide a method of passing multiple-byte packets of information between tasks with automatic task synchronization of queue-full and queue-empty conditions. For detailed descriptions, see Chapter 4, “Queue Services.”

Table 1-5. Queue Services Summary

KS_CloseQueue End the use of a dynamic queue. 124

KS_DefQueueName Define the name of a previously opened dynamic queue.

126

KS_DefQueueProp Define the properties of a queue. 128

KS_DefQueueSema Associate a semaphore with a queue condition event.

130

KS_GetQueueClassProp Get the Queue object class properties. 134

KS_GetQueueData Get the next entry from a queue. 136

KS_GetQueueDataT Get the next entry from a queue. If the queue is empty, wait a specified number of ticks on a specified counter for an entry to become available.

138

KS_GetQueueDataW Get the next entry from a queue. If the queue is empty, wait for an entry to become available.

140

KS_GetQueueName Get the name of a queue. 142

KS_GetQueueProp Get the properties of a queue. 144

KS_GetQueueSema Get the semaphore handle associated with a queue event.

146

(27)

KS_LookupQueue Look up a queue’s name to get its handle. 150

KS_OpenQueue Allocate and name a dynamic queue. 152

KS_PutQueueData Put an entry into a queue. 156

KS_PutQueueDataT Put an entry into a queue. If the queue is full, wait for a specified number of ticks on a specified counter for the queue to have room for the entry.

158

KS_PutQueueDataW Put an entry into a queue. If the queue is full, wait for the queue to have room for the entry.

160

KS_UseQueue Look up a dynamic queue by name and mark it for use.

162

Table 1-5. Queue Services Summary (continued)

(28)

Mailbox Services

The Mailbox directives, listed in Table 1-6, provide methods of data passing between the calling task and other tasks using both static and dynamic mailboxes. For detailed descriptions, see Chapter 5, “Mailbox Services.”

Table 1-6. Mailbox Services Summary

KS_CloseMbox End the use of a dynamic mailbox. 166

KS_DefMboxName Define the name of a previously opened dynamic mailbox.

168

KS_DefMboxProp Define the properties of a mailbox. 170

KS_DefMboxSema Associate a semaphore with the

Mailbox_Not_Empty event.

172

KS_GetMboxClassProp Get the Mailbox object class properties. 176

KS_GetMboxName Get the name of a mailbox. 178

KS_GetMboxProp Get the properties of a mailbox. 180

KS_GetMboxSema Get the semaphore handle associated with a

Mailbox_Not_Empty event.

182

INIT_MboxClassProp Initialize the Mailbox object class properties. 184

KS_LookupMbox Look up a mailbox’s name to get its handle. 186

KS_OpenMbox Allocate and name a dynamic mailbox. 188

KS_UseMbox Look up a dynamic mailbox by name and mark it for use.

(29)

Message Services

The Message directives, listed in Table 1-7, provide a method of transferring large amounts of data between tasks with minimal overhead by passing only pointers (addresses) to the data. They also provide message receipt acknowledgment for task synchronization. The messages are passed between the calling task and other tasks through mailboxes.For detailed descriptions, see Chapter 6, “Message Services.”

Table 1-7. Message Services Summary

KS_AckMsg Acknowledge a message. 194

KS_ReceiveMsg Receive a message from a mailbox. 200

KS_ReceiveMsgT Receive a message from a mailbox. If the mailbox is empty, wait a specified number of ticks for a message.

202

KS_ReceiveMsgW Receive a message from a mailbox. If the mailbox is empty, wait for a message.

204

KS_SendMsg Send a message to a mailbox asynchronously. 206

KS_SendMsgT Send a message to a mailbox synchronously and wait for a specified time for an acknowledgment.

209

KS_SendMsgW Send a message to a mailbox synchronously and wait for an acknowledgment.

213

KS_TestAck Test for message acknowledgment. 216

KS_TestAckT Test for message acknowledgment and wait for a specified number of ticks for the acknowledgment.

(30)

Memory Partition Management Services

The Memory Management directives, listed in Table 1-8, provide a system-wide method of dynamically allocating and de-allocating memory blocks to tasks on an as-needed basis. Using these

directives, multiple tasks can share a common pool of memory. For detailed descriptions, see Chapter 7, “Memory Partition Services.”

Table 1-8. Memory Partition Services Summary

XX_AllocBlk Allocate a block of memory. 224

KS_AllocBlkT Allocate a block of memory. If the partition is empty, wait for a specified number of ticks for an available block.

226

KS_AllocBlkW Allocate a block of memory. If the partition is empty, wait for an available block.

228

KS_ClosePart End the use of a dynamic partition. 230

KS_DefPartName Define the name of a previously opened dynamic memory partition.

232

KS_DefPartProp Define the properties of a partition. 234

KS_DefPartSema Associate a semaphore with the

Partition_Not_Empty event.

236

KS_FreeBlk Free a block of memory. 238

KS_GetFreeBlkCount Get the number of free blocks in a partition. 240

KS_GetPartClassProp Get the Memory Partition object class properties 242

KS_GetPartName Get the name of a partition. 244

(31)

KS_GetPartSema Get the semaphore associated with the

Partition_Not_Empty event.

248

INIT_PartClassProp Initialize the Partition object class properties. 250

KS_LookupPart Look up a partition’s name to get its handle. 252

KS_OpenPart Allocate and name a dynamic partition. 254

KS_UsePart Look up a dynamic partition by name and mark it for use.

256

Table 1-8. Memory Partition Services Summary (continued)

(32)

Mutex Management Services

The Mutex directives, listed in Table 1-9, provide a method of managing and protecting logical resources. These services help a task gain and release exclusive control of an associated resource. Typical resources might include a shared database, non-reentrant code modules, specialized hardware, or an expensive laser printer. For detailed descriptions, see Chapter 8, “Mutex Services.”

Table 1-9. Mutex Services Summary

KS_CloseMutx End the use of a dynamic mutex. 260

KS_DefMutxName Define the name of a previously opened mutex. 262

KS_DefMutxProp Define the properties of a mutex. 264

KS_DefMutxSema Associate a semaphore with the Mutex_Not_Busy event.

267

KS_GetMutxClassProp Get the Mutex object class properties. 270

KS_GetMutxName Get the name of a mutex. 272

KS_GetMutxOwner Get the owner of a mutex. 274

KS_GetMutxProp Get the properties of a mutex. 276

KS_GetMutxSema Get the semaphore handle associated with the

Mutex_Not_Busy event.

278

INIT_MutxClassProp Initialize the Mutex object class properties. 280

KS_LookupMutx Look up a mutex’s name to get its handle. 282

KS_OpenMutx Allocate and name a dynamic mutex. 284

KS_ReleaseMutx Release ownership of a mutex. 286

KS_TestMutx Test the availability of a mutex and lock it if it is not busy.

(33)

KS_TestMutxT Test the availability of a mutex. If the mutex is busy, wait a specified number of ticks for it to become available and then lock it.

290

KS_TestMutxW Test the availability of a mutex. If the mutex is busy, wait for it to become available and then lock it.

294

KS_UseMutx Look up a dynamic mutex by name and mark it for use.

296

Table 1-9. Mutex Services Summary (continued)

(34)

Special Services

The Special services, listed in Table 1-10, perform special functions not based on the object classes. For detailed descriptions, see Chapter 9, “Special Services.”

Table 1-10. Special Services Summary

XX_AllocSysRAM Allocate a block of system RAM. 300

XX_DefFatalErrorHandler Establish the system error function. 302

XX_GetFreeSysRAMSize Get the size of free system RAM. 304

XX_GetFatalErrorHandler Get the system error function. 305

KS_GetSysProp Get the system properties. 306

KS_GetVersion Get the version number of the Kernel. 308

INIT_SysProp Initialize the RTXC system properties. 310

KS_Nop Execute the minimal path through the kernel dispatcher (no operation).

313

(35)

C H A P T E R

2 Task Services

In This Chapter

We describe the Task kernel services in detail. The Task kernel services start and stop tasks and maintain information about task states. KS_AbortTask ... 23 KS_CloseTask ... 25 KS_DefTaskEnvArg ... 27 KS_DefTaskName ...30 KS_DefTaskPriority ... 32 KS_DefTaskProp... 34 KS_DefTaskSema ... 36 KS_DefTickSlice... 38 KS_DisableTaskScheduler ... 40 KS_EnableTaskScheduler... 41 KS_ExecuteTask ...42 KS_GetTaskEnvArg ...44 KS_GetTaskClassProp...47 KS_GetTaskID ... 50 KS_GetTaskName ...51 KS_GetTaskPriority ... 53 KS_GetTaskProp... 54

(36)

KS_LookupTask ... 64 KS_OpenTask ... 66 XX_ResumeTask ... 68 KS_SleepTask... 70 KS_SuspendTask ... 71 KS_TerminateTask...72 KS_UseTask ... 74 KS_YieldTask... 76

(37)

KS_AbortTask

Abort the execution of a task.

Synopsis

void KS_AbortTask (TASK task)

Input

Description

The KS_AbortTask kernel service stops the specified task by blocking it from further operation. To start the task again, you must first terminate it with a call to KS_TerminateTask and then restart it with a call to KS_ExecuteTask.

This service is similar to the KS_TerminateTask service except that it sets the status of the task to ABORTED_BLOCK instead of INACTIVE. Such an identification may be valuable when tracking

down a task gone awry during system diagnostic operations. A task number of zero (0) indicates a request to abort the Current Task. In all cases following abortion of the requester, the next highest priority ready task executes.

Warning: Other than the items mentioned above, tasks that are currently using kernel objects or have objects allocated to them are not cleaned up by the abort process. The

programmer must ensure that the task releases all such system elements to the system before aborting the task. For example, a dynamic task should not abort itself if the task’s stack has been dynamically allocated from a memory partition because it would be difficult to recover the memory used for the stack. Repeated occurrences of such an event would cause a memory leak that could lead to eventual system failure.

(38)

KS_AbortTask

Errors

This service may generate one of the following fatal error codes:

` FE_ILLEGAL_TASK if the specified task ID is not valid.

` FE_UNINITIALIZED_TASK if the specified task has not yet been

initialized.

Example

In Example 2-1, the Current Task aborts the TASKBX task and then

terminates itself. Example 2-1. Abort Task and Terminate

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */ #include "ktask.h" /* defines TASKBX */

KS_AbortTask (TASKBX); /* abort task TASKBX */ KS_TerminateTask (SELFTASK); /* now terminate self */

(39)

KS_CloseTask

End the use of a dynamic task.

Synopsis

KSRC KS_CloseTask (TASK task)

Input

Description

The KS_CloseTask kernel service ends the Current Task’s use of the dynamic task specified in task. When closing the task, the kernel detaches the caller’s use of it. If the caller is the last user of the task, the kernel releases the closed task to the free pool of dynamic tasks for reuse. If there is at least one other task still referencing the task, the kernel does not release the task to the free pool but the service completes successfully.

Note: To use this service, you must enable the Dynamics attribute of the Task class during system generation.

Output

This service returns a KSRC value as follows:

` RC_GOOD if the service was successful.

` RC_STATIC_OBJECT if the specified task is not dynamic.

` RC_OBJECT_NOT_INUSE if the specified task does not

correspond to an active dynamic task.

` RC_OBJECT_INUSE if the Current Task’s use of the specified task

is closed but the task remains open for use by other tasks.

Note: The KSRC value does not necessarily indicate an error

condition. The calling task must interpret its meaning.

(40)

KS_CloseTask

Example

In Example 2-2, the Current Task waits on a signal from another task indicating that it is time to close an active dynamic task. The handle of the dynamic task is specified in dyntask. When the signal is

received, the Current Task closes the associated task. Example 2-2. Close Task When Signaled

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */ TASK dyntask; /* not SELFTASK (TASK)0 */

SEMA dynsema;

KS_TestSemaW (dynsema); /* wait for signal */ /* then close the task */

if (KS_CloseTask (dyntask) != RC_GOOD) {

...something is wrong. Deal with it }

...continue /* task closed successfully */

KS_DefTaskEnvArg

Define the environment arguments for a task.

Synopsis

void KS_DefTaskEnvArg (TASK task, const void *parg)

Inputs

Description

The KS_DefTaskEnvArg kernel service establishes a pointer to a structure containing parameters that define the environment of the task specified in task. The RTXC Kernel places no restrictions on the size or content of the environment structure.

The service requires a task number and a pointer, parg, to the environment arguments structure for the specified task.

Note: To use this service, you must enable the Environment

Arguments attribute of the Task class during system

generation.

Output

This service does not return a value.

Errors

initialized.

Example

In Example 2-3 on page 28, the Current Task needs to spawn a dynamic task to operate on the port and channel specified by the

port and chnl variables that were specified elsewhere. The dynamic

task The number of the task being defined.

(42)

KS_DefTaskEnvArg

After defining the dynamic task’s properties, the Current Task defines the channel and port environment arguments in a structure and makes that structure known to the dynamic task. The Current Task then executes the dynamic task.

Example 2-3. Define Task Properties

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */ #include "kpart.h" /* Memory Partitions */

#define STKSIZE 256 #define DYNPRI 14

extern void taskA (void); struct{

int port; int channel;

} envargA; /* environment argument structure */ TASK dyntask;

TASKPROP tprop; int port, chnl;

if (KS_OpenTask ((char *)0, &dyntask) != RC_GOOD) {

... Deal with problem with dynamic task allocation }

else {

/* allocate space for task’s stack */

tprop.stackbase = (char *)KS_AllocBlkW (BLK256, (PEVENT *)0); /* define task properties */

tprop.taskentry = taskA; tprop.stacksize = STKSIZE; tprop.priority = DYNPRI;

KS_DefTaskProp (dyntask, &tprop); /* define environment arguments */ envargA.port = port;

envargA.channel = chnl;

KS_DefTaskEnvArg (dyntask, &envargA); /* start task */

KS_ExecuteTask (dyntask); }

(43)

KS_DefTaskEnvArg

KS_DefTaskName

Define the name of a previously opened dynamic task.

Synopsis

KSRC KS_DefTaskName (TASK task, const char *pname)

Inputs

Description

The KS_DefTaskName kernel service names or renames the dynamic task specified in task. The service uses the null-terminated string pointed to by pname for the task’s new name. The kernel only stores pname internally, which means that the same array cannot be used to build multiple dynamic task names. Static tasks cannot be named or renamed under program control.

Note: To use this service, you must enable the Dynamics attribute of the Task class during system generation.

This service does not check for duplicate task names.

Output

` RC_GOOD if the service completes successfully.

` RC_STATIC_OBJECT if the task being named is static.

` RC_OBJECT_NOT_FOUND if the Dynamics attribute of the Task

class is not enabled.

` RC_OBJECT_NOT_INUSE if the dynamic task being named is still

in the free pool of dynamic tasks.

Error

This service may generate the following fatal error code:

FE_ILLEGAL_TASK if the specified task ID is not valid.

(45)

KS_DefTaskName

Example

Example 2-4 assigns the name NewTask to the task specified in the dyntask variable so other users may reference it by name.

Example 2-4. Define Task Name

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */ TASK dyntask;

if (KS_DefTaskName (dyntask, "NewTask") != RC_GOOD) {

... Probably is a static task. Deal with it here. }

... else the naming operation was successful. Continue

KS_DefTaskPriority

Define a new priority for a task.

Synopsis

void KS_DefTaskPriority (TASK task, PRIORITY priority)

Inputs

Description

The KS_DefTaskPriority kernel service defines or changes the priority of task. The new priority may be any legal priority, either higher or lower than the task’s current priority. Legal priority values are {1, 2, … 126}. Note that 0 is not a legal priority value.

To increase the priority of a task, you must assign it a lower priority value. For example, a task with a priority of 1 has a higher priority than a task whose priority is 2. If the Current Task assigns itself a lower priority value (that is, it becomes a higher priority task), no context switch occurs. However, if the Current Task assigns itself a higher priority value, making it a lower priority task, a context switch does occur if there is another task in the Ready List that has a priority less than or equal to the Current Task’s assigned priority.

The Current Task may specify itself with a task value of zero (0). If task is not the Current Task, a preemption occurs if the new priority of task is higher than that of the requesting task and task is in the Ready List.

If task is in one or more priority-ordered wait lists, its position in those lists may change to reflect its new priority.

Output

Errors

initialized.

(47)

KS_DefTaskPriority

` FE_ILLEGAL_PRIORITY if the specified priority value is out of

range.

Example

Example 2-5 changes the priority of the SERIALIN task from its

current level to priority 3, and then changes the calling task to priority 6.

Example 2-5. Define Task Priorities

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */ #include "ktask.h" /* defines SERIALIN */

KS_DefTaskPriority (SERIALIN, 3); /* new priority = 3 */ KS_DefTaskPriority (SELFTASK, 6); /* new priority = 6 */

KS_DefTaskProp

Define the properties of a task.

Synopsis

void KS_DefTaskProp (TASK task, const TASKPROP *ptaskprop)

Inputs

Description

The KS_DefTaskProp kernel service defines the properties of the specified task by using the values contained in the TASKPROP

structure pointed to by ptaskprop. If task is not in the inactive state, this function returns without making any changes to the properties of task. You may use this service on static or dynamically allocated tasks. It is typically used to define a static task during system startup or a dynamic task during runtime that has been previously allocated with the KS_OpenTask kernel service.

Legal priority values are {1, 2, … 126}. (Note that 0 is not a legal priority value).

Example 2-6 shows the organization of the TASKPROP structure.

Example 2-6. Task Properties Structure

typedef struct {

void (*taskentry)(void); /* initial entry point address */ char *stackbase; /* initial stack base */

ksize_t stacksize; /* initial stack size */ PRIORITY priority; /* initial priority */ } TASKPROP;

Output

Error

` FE_ILLEGAL_PRIORITY if the specified priority is out of range.

(49)

KS_DefTaskProp

` FE_NULL_TASKENTRY if the specified Task entry address is null.

` FE_NULL_STACKBASE if the specified Task stack base address is

null.

` FE_ZERO_STACKSIZE if the specified Task stack size is zero.

Example

During system initialization, the startup code must create and initialize the Task object class and define the properties of all the static tasks before the start of multitasking operations, as illustrated in Example 2-7.

Example 2-7. Define Task Object Class Properties

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */ extern const KCLASSPROP taskclassprop;

extern const TASKPROP taskprop[]; KSRC ksrc;

int objnum;

if ((ksrc = INIT_TaskClassProp (&taskclassprop)) != RC_GOOD) {

printf ("Task class initialization failed %d", ksrc); return (ksrc);

}

for (objnum = 1; objnum <= taskclassprop.n_statics; objnum++) KS_DefTaskProp (objnum, &taskprop[objnum]);

KS_DefTaskSema

Associate a semaphore with the termination or abortion of a task.

Synopsis

void KS_DefTaskSema (TASK task, SEMA sema)

Inputs

Description

The KS_DefTaskSema kernel service associates the semaphore specified in sema with the termination and abortion events of the specified task, when sema is to be used in a subsequent test using the

KS_TestSema kernel service or one of its variants. The service signals the semaphore when task is terminated or aborted.

Note: To use this service, you must enable the Semaphores attribute of the Task class during system generation.

Output

Errors

initialized.

` FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.

Example

In Example 2-8 on page 37, the Current Task has nothing to do until the TASKA task gets terminated or aborted. To synchronize with this

event, the Current Task defines the GOSEMA semaphore for TASKA

and then waits for that semaphore.

task The number of the task with which to associate the semaphore.

(51)

KS_DefTaskSema

Example 2-8. Define Task Termination Semaphore

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */ #include "ktask.h" /* defines TASKA */

#include "ksema.h" /* defines GOSEMA */ KS_DefTaskSema (TASKA, GOSEMA);

KS_TestSemaW (GOSEMA);

... TASKA ended, begin processing now

KS_DefTickSlice

Define the tick-slice quantum for a task.

Synopsis

void KS_DefTickSlice (TASK task, TSLICE ticks)

Inputs

Description

The KS_DefTickSlice kernel service defines the number of ticks the specified task is permitted to run before it is forced to yield under tick-sliced scheduling.

The service requires a task number and a tick-slice quantum, ticks, as arguments. The tick quantum period is specified as a value of

TSLICE type giving the number of clock ticks approximating the

desired duration of the tick-slice quantum. A task number of zero (0) specifies the Current Task.

You can change the tick quantum at any time. If tick-slicing is not in operation for task (quantum = zero (0)) and ticks is non-zero, task immediately begins tick-sliced operation.

A ticks value of zero (0) causes task to cease tick-sliced operation immediately.

However, if tick slicing is already in effect, a new tick quantum does not take effect until the current tick quantum expires. If you must alter the quantum immediately, change the quantum to zero (0) and then to the desired value.

Note: To use this service, you must enable the Tick Slice attribute of the Task class during system generation.

Output

Errors

(53)

KS_DefTickSlice

initialized.

Example

In Example 2-9, the Current Task begins tick-sliced operation with a tick quantum of 100 msec. After some period of tick-sliced

operation, the task ceases tick-sliced operation. Example 2-9. Define Tick Slice

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */ #include "kproject.h" /* defines CLKTICK */

/* define tick slice quantum as 100 ms */

KS_DefTickSlice (SELFTASK, (TSLICE)100/CLKTICK); ... Task now in tick-sliced operation

/* turn off tick-sliced operation */ KS_DefTickSlice (SELFTASK, (TSLICE)0);

(54)

KS_DisableTaskScheduler

Disable the task scheduler to prevent task context switching.

Synopsis

void KS_DisableTaskScheduler (void)

Inputs

This service has no inputs.

Description

The KS_DisableTaskScheduler kernel service disables the kernel scheduler, which in turn prevents context switching between tasks. With context switching turned off, a task can execute without being preempted. Interrupts are not disabled, but a context switch does not occur. When an application makes nested calls to

KS_DisableTaskScheduler, preemption does not resume until an equal number of KS_EnableTaskScheduler calls are made.

Output

Example

Example 2-10 executes a section of code without being preempted. Example 2-10. Disable Task Scheduler

#include "rtxcapi.h" /* RTXC Kernel Services prototypes */ KS_DisableTaskScheduler (); /* prevent preemption */

...perform some function

/* allow context switch to occur now */ KS_EnableTaskScheduler ();

(55)

KS_EnableTaskScheduler

Enable the scheduler to allow context switching between tasks.

Synopsis

void KS_EnableTaskScheduler (void)

Inputs

Description

The KS_EnableTaskScheduler kernel service enables the RTXC/ms Scheduler, which in turn permits task context switching to occur. If the application makes nested calls to

KS_DisableTaskScheduler, then it must make an equal number of calls to KS_EnableTaskScheduler before context switching (preemption) starts again.

The RTXC Kernel enables the scheduler by default during system initialization.

Output

Example

In Example 2-11, after performing some critical function with the scheduler disabled, the Current Task enables the scheduler. Example 2-11. Enable Task Scheduler

#include "rtxcapi.h" /* RTXC Kernel Services prototypes */ KS_DisableTaskScheduler (); /* prevent preemption */

...perform some function

/* allow context switch to occur now */ KS_EnableTaskScheduler ();

(56)

KS_ExecuteTask

Execute a task.

Synopsis

KSRC KS_ExecuteTask (TASK task)

Input

Description

The KS_ExecuteTask kernel service starts a specified task from its beginning address. The task must be in the INACTIVE state. If so, it

is inserted into the Ready List with its program counter (PC) and stack pointer (SP) initialized to their starting values. The task’s starting address, initial priority, and stack pointer are specified during system generation or dynamically with the

KS_DefTaskProp kernel service.

If task is of higher priority than the requesting (current) task, a context switch is performed and the new task runs. If task is of lower or equal priority, control is returned to the caller.

Warning: A task value of zero (0) indicates self-execution. This is not advisable.

Output

` RC_GOOD if the task starts successfully.

` RC_TASK_NOT_INACTIVE if the specified task is in a state other

than INACTIVE.

Errors

initialized.

Example

In Example 2-12 on page 43, the Current Task starts the SHUTDOWN

static task from its starting address.

(57)

KS_ExecuteTask

Example 2-12. Execute Task

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */ #include "ktask.h" /* defines task SHUTDOWN */

/* execute SHUTDOWN task */

if (KS_ExecuteTask (SHUTDOWN) != RC_GOOD) {

...task is not started because it is not in INACTIVE state

}

...task successfully started executing

(58)

KS_GetTaskEnvArg

Get the address of a task’s environment arguments.

Synopsis

void * KS_GetTaskEnvArg (TASK task)

Input

Description

The KS_GetTaskEnvArg kernel service obtains a pointer to the structure containing the environment arguments for the specified

task. To request the environment arguments for the Current Task, set task to zero (0).

Any task may use this kernel service to get environment arguments that have been previously defined to the RTXC Kernel by the

KS_DefTaskEnvArg service. Dynamic tasks use this service because they typically have an associated environment argument structure to specify the parameters they need for operation.

Note: To use this service, you must enable the Environment

Arguments attributes of the Task class during system

generation.

Output

This service returns a pointer to the specified task’s environment argument structure. If no such definition has been made, the service returns a null pointer ((void *)0).

Errors

initialized.

Example

In Example 2-13 on page 46, the Current Task is a communications channel driver and is an example of a task that may have multiple instances in operation. To run, it must determine the operational parameters (the communications port and channel) on which it

(59)

KS_GetTaskEnvArg

should operate. It does this by obtaining the data from its environment argument structure, which contains the port and channel identifiers. The environment argument structure has been previously defined.

While the example below is simple, it demonstrates some of the basic concepts in organizing a task that is dynamically allocated, defined, and executed. In contrast to a static task, the dynamic task is typically used in situations where each instance of the task serves one particular purpose. In this example, the purpose is to handle a single communications port and the channel on that port.

Because other instances of the same task may already be in operation on other ports and channels, the task must determine who it is and what critical data it needs for operation. That data should be found in the task’s environment argument structure, the content of which was probably filled by the task that spawned the Current Task.

(60)

KS_GetTaskEnvArg

Example 2-13. Read Task Environment Arguments

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */ void commchnl (void)

{

struct myargs {

int port; /* port number */ int chnl; /* channel number */ };

struct myargs *envargs;

int chnlstat; /* port/channel status */ /* first find out where to get the */

/* environment arguments */ envargs = KS_GetTaskEnvArg (SELFTASK);

while ((chnlstat = get_chnl_stat (envargs->port, envargs->chnl)) != 0)

{

... while the status is non zero, do some work with the port and channel to process the data stream }

/* terminate when the status is 0 */ KS_TerminateTask (SELFTASK);

}

(61)

KS_GetTaskClassProp

Get the Task object class properties.

Synopsis

const KCLASSPROP * KS_GetTaskClassProp (int *pint)

Input

Description

The KS_GetTaskClassProp kernel service obtains a pointer to the KCLASSPROP structure that was used during system initialization

by the INIT_TaskClassProp service to initialize the Task object class properties.

If the pint pointer contains a non-zero address, the current number of unused dynamic tasks is stored in the indicated address. If pint contains a null pointer ((int *)0), the service ignores the

parameter. If the Task object class properties do not include the

Dynamics attribute, the service stores a value of zero (0) at the

address contained in pint.

The KCLASSPROP structure has the following organization: typedef struct

{

KATTR attributes;

KOBJECT n_statics; /* number of static objects */ KOBJECT n_dynamics; /* number of dynamic objects */ short objsize; /* used for calculating offsets */ short totalsize; /* used to alloc object array RAM */ ksize_t namelen; /* length of the name string */ const char *pstaticnames;

} KCLASSPROP;

The attributes element of the Task property structure supports the class property attributes and corresponding masks listed in Table 2-1

pint A pointer to an integer variable in which to store the current number of unused dynamic tasks.

(62)

KS_GetTaskClassProp

Output

If successful, this service returns a pointer to a KCLASSPROP

structure.

If the Task class is not initialized, the service returns a null pointer ((KCLASSPROP *)0).

If pint is not null ((int *)0), the service returns the number of

available dynamic tasks in the variable pointed to by pint.

Example

In Example 2-14 on page 49, the Current Task needs access to the information contained in the KCLASSPROP structure for the Task

object class. Table 2-1. Task Class Attributes and Masks

Attribute Mask

Static Names ATTR_STATIC_NAMES

Dynamics ATTR_DYNAMICS

Tick Slice ATTR_TICKSLICE

Environment Arguments ATTR_TASK_ENV

(63)

KS_GetTaskClassProp

Example 2-14. Read Task Object Class Properties

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */ KCLASSPROP *ptaskclassprop;

int free_dyn;

/* Get the task kernel object class properties */ if ((ptaskclassprop = KS_GetTaskClassProp (&free_dyn)) == (KCLASSPROP *)0)

{

putline ("Task Class not initialized"); }

else {

...task object class properties are available for use and "free_dyn" contains the number of available dynamic tasks }

(64)

KS_GetTaskID

Get the handle of the Current Task.

Synopsis

TASK KS_GetTaskID (void)

Inputs

Description

The KS_GetTaskID kernel service obtains the identifier,

commonly referred to as the handle, of the calling task. This service is typically used by a dynamically created task that needs to have explicit knowledge of its handle. The handles of static tasks are found in the task header file created during system generation.

Output

This service returns the handle of the Current Task.

Example

Example 2-15 gets the task number of the Current Task and outputs it to the console.

Example 2-15. Read Current Task Number

#include <stdio.h> /* standard i/o */

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */ static char buf[128];

TASK mytaskid;

mytaskid = KS_GetTaskID ();

sprintf (buf, "Current Task ID is %d", mytaskid); putline (buf);

(65)

KS_GetTaskName

Get the name of a task.

Synopsis

char * KS_GetTaskName (TASK task)

Input

Description

The KS_GetTaskName kernel service obtains a pointer to the null-terminated string containing the name of the specified task. The task may be static or dynamic.

Note: To use this service on static tasks, you must enable the Static Names attribute of the Task class during system generation.

Output

If the task has a name, this service returns a pointer to the null-terminated name string.

If the task has no name, this service returns a null pointer ((char *)0).

Error

This service may generate the following fatal error code:

FE_ILLEGAL_TASK if the specified task ID is not valid.

Example

In Example 2-16 on page 52, the Current Task needs to report the name of the dynamic task specified in dyntask.

(66)

KS_GetTaskName

Example 2-16. Read Dynamic Task Name

#include <stdio.h> /* standard i/o */

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */ static char buf[128];

TASK dyntask; char *pname;

if ((pname = KS_GetTaskName (dyntask)) == (char *)0) sprintf (buf, "Task %d has no name", dyntask); else

sprintf (buf, "Task %d name is %s", dyntask, pname); putline (buf);

KS_GetTaskPriority

Get the priority of a task.

Synopsis

PRIORITY KS_GetTaskPriority (TASK task)

Input

Description

The KS_GetTaskPriority kernel service obtains the current priority of the specified task. A task value of zero (0) specifies the Current Task.

Output

This service returns the priority of the specified task.

Errors

initialized.

Example

Example 2-17 gets the priority of the Current Task and raises its priority by 2.

Example 2-17. Read and Change Task Priority

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */ PRIORITY mypri;

mypri = KS_GetTaskPriority (SELFTASK); /* raise Current Task’s priority by 2 */ KS_DefTaskPriority (SELFTASK, mypri - 2);

RTXC Kernel ServicesV2 Decrypted