RTXC Kernel ServicesV2 Decrypted

Quadros

®

Systems Inc.

RTXC Kernel Services Reference, Volume 2 Tasks, Semaphores, Queues, Mailboxes, Messages, Memory Partitions, and Mutexes

June 21, 2002

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 RTXC Kernel, Version 1.0

June 21, 2002

Contents

CHAPTER 1

Introduction To RTXC/ms Kernel Services ..........................................1 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 Special Services .....................................................................20

CHAPTER 2

Task Services.......................................................................................21 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

Contents

June 21, 2002

iii

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 CHAPTER 3

iv

June 21, 2002

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

RTXC Kernel Services Reference, Volume 2

KS_UseSema .............................................................................120 CHAPTER 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

CHAPTER 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

CHAPTER 6

Message Services..............................................................................193 KS_AckMsg................................................................................194 KS_ForwardMsg ........................................................................196 KS_ReceiveMsg .........................................................................200

Contents

June 21, 2002

v

KS_ReceiveMsgT....................................................................... 202 KS_ReceiveMsgW ..................................................................... 204 KS_SendMsg ............................................................................. 206 KS_SendMsgT........................................................................... 209 KS_SendMsgW ......................................................................... 213 KS_TestAck ............................................................................... 216 KS_TestAckT ............................................................................. 218 KS_TestAckW............................................................................ 220 CHAPTER 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

CHAPTER 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

vi

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_OpenMutx ...........................................................................284 KS_ReleaseMutx ........................................................................286 KS_TestMutx..............................................................................288 KS_TestMutxT ...........................................................................290 KS_TestMutxW..........................................................................294 KS_UseMutx ..............................................................................296 CHAPTER 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

APPENDIX A

Fatal Error Codes ..............................................................................317

I N D E X ..................................................................................................................................321

Contents

June 21, 2002

vii

viii

June 21, 2002

RTXC Kernel Services Reference, Volume 2

List of Tables

Table 1-1 Table 1-2 Table 1-3 Table 1-4 Table 1-5 Table 1-6 Table 1-7 Table 1-8 Table 1-9 Table 1-10 Table 2-1 Table 3-1 Table 4-1 Table 5-1 Table 7-1 Table 8-1 Table 9-1

Kernel Service Description Format.....................................................3 Kernel Service Return Value Types ...................................................6 Task Services Summary ......................................................................8 Semaphore Services Summary ........................................................10 Queue Services Summary ................................................................12 Mailbox Services Summary ..............................................................14 Message Services Summary .............................................................15 Memory Partition Services Summary ..............................................16 Mutex Services Summary .................................................................18 Special Services Summary ................................................................20 Task Class Attributes and Masks ......................................................48 Semaphore Class Attributes and Masks...........................................89 Queue Class Attributes and Masks.................................................135 Mailbox Class Attributes and Masks...............................................176 Memory Partition Class Attributes and Masks ..............................243 Mutex Class Attributes and Masks .................................................271 System Attributes and Masks..........................................................311

List of Tables

June 21, 2002

ix

x

June 21, 2002

RTXC Kernel Services Reference, Volume 2

List of Examples

Example 2-1 Example 2-2 Example 2-3 Example 2-4 Example 2-5 Example 2-6 Example 2-7 Example 2-8 Example 2-9 Example 2-10 Example 2-11 Example 2-12 Example 2-13 Example 2-14 Example 2-15 Example 2-16 Example 2-17 Example 2-18 Example 2-19 Example 2-20 Example 2-21 Example 2-22 Example 2-23 Example 2-24 Example 2-25 Example 2-26 Example 2-27 Example 2-28 Example 2-29 Example 2-30

Abort Task and Terminate.................................................................24 Close Task When Signaled................................................................26 Define Task Properties ......................................................................28 Define Task Name .............................................................................31 Define Task Priorities ........................................................................33 Task Properties Structure ..................................................................34 Define Task Object Class Properties ................................................35 Define Task Termination Semaphore ..............................................37 Define Tick Slice ................................................................................39 Disable Task Scheduler .....................................................................40 Enable Task Scheduler.......................................................................41 Execute Task .......................................................................................43 Read Task Environment Arguments ................................................46 Read Task Object Class Properties ...................................................49 Read Current Task Number ..............................................................50 Read Dynamic Task Name ................................................................52 Read and Change Task Priority.........................................................53 Terminate Task and Release Its Stack ..............................................55 Read Task Termination Semaphore .................................................57 Read Task State ..................................................................................59 Read Task Tick-Slice Quantum.........................................................60 Object Class Properties Structure .....................................................62 Initialize Task Object Class ...............................................................63 Look Up Task by Name......................................................................65 Allocate Dynamic Task ......................................................................67 Resume Suspended Task from Zone 3 ............................................69 Put Current Task to Sleep .................................................................70 Suspend Task .....................................................................................71 Terminate Task ..................................................................................73 Read Task Handle and Register It ....................................................75

List of Examples

June 21, 2002

xi

Example 2-31 Example 3-1 Example 3-2 Example 3-3 Example 3-4 Example 3-5 Example 3-6 Example 3-7 Example 3-8 Example 3-9 Example 3-10 Example 3-11 Example 3-12 Example 3-13 Example 3-14 Example 3-15 Example 3-16 Example 3-17 Example 3-18 Example 3-19 Example 3-20 Example 3-21 Example 3-22 Example 4-1 Example 4-2 Example 4-3 Example 4-4 Example 4-5 Example 4-6 Example 4-7 Example 4-8 Example 4-9 Example 4-10 Example 4-11 Example 4-12 Example 4-13 Example 4-14 Example 4-15 Example 4-16 Example 4-17

xii

June 21, 2002

Yield to Another Task........................................................................ 77 Close Semaphore............................................................................... 81 Set Semaphore Count ....................................................................... 83 Assign Semaphore Name ................................................................. 85 Semaphore Properties Structure ...................................................... 86 Specify Semaphore Waiting Order................................................... 87 Class Properties Structure ................................................................ 88 Read Semaphore Object Class Properties........................................ 89 Read Semaphore Count .................................................................... 91 Read Semaphore Name..................................................................... 93 Read Semaphore Properties ............................................................. 95 Initialize Semaphore Object Class ................................................... 97 Look Up Semaphore by Name.......................................................... 99 Allocate Dynamic Semaphore ........................................................ 101 Signal Semaphore from Zone 3 ..................................................... 103 Signal List of Semaphores from Zone 3 ........................................ 105 Test Semaphore ............................................................................... 107 Test Semaphore—Wait Number of Ticks for Signal .................... 109 Test List of Semaphores .................................................................. 111 Test List of Semaphores—Wait Number of Ticks for Signal ....... 114 Test List of Semaphores—Wait for Signal..................................... 117 Test Semaphore—Wait for Signal.................................................. 119 Read Semaphore Handle and Register It ...................................... 121 Close Queue..................................................................................... 125 Assign Queue Name ....................................................................... 127 Queue Properties Structure ............................................................ 128 Define Queue Object Class Properties........................................... 129 Associate Queue Event with Semaphore ....................................... 132 Read Queue Object Class Properties.............................................. 135 Read Queue Entry............................................................................ 137 Read Queue Entry—Wait Number of Ticks If Necessary............. 139 Read Queue Entry—Wait If Necessary .......................................... 141 Read Dynamic Queue Name .......................................................... 143 Read Queue Properties ................................................................... 145 Read Queue Semaphore ................................................................. 147 Initialize Queue Object Class ......................................................... 149 Look Up Queue by Name................................................................ 151 Allocate and Initialize Queue ......................................................... 154 Put Data Into Queue ....................................................................... 157 Put Data Into Queue—Wait Number of Ticks If Queue is Full .. 159

RTXC Kernel Services Reference, Volume 2

Example 4-18 Example 4-19 Example 5-1 Example 5-2 Example 5-3 Example 5-4 Example 5-5 Example 5-6 Example 5-7 Example 5-8 Example 5-9 Example 5-10 Example 5-11 Example 5-12 Example 5-13 Example 6-1 Example 6-2 Example 6-3 Example 6-4 Example 6-5 Example 6-6 Example 6-7 Example 6-8 Example 6-9 Example 6-10 Example 6-11 Example 7-1 Example 7-2 Example 7-3 Example 7-4 Example 7-5 Example 7-6 Example 7-7 Example 7-8 Example 7-9 Example 7-10 Example 7-11 Example 7-12 Example 7-13

Put Data Into Queue—Wait Until Queue Has Room...................161 Read Queue Handle and Register It ...............................................163 Close Mailbox ...................................................................................167 Assign Mailbox Name......................................................................169 Mailbox Properties Structure ..........................................................170 Define Mailbox Properties...............................................................171 Define Mailbox Semaphore.............................................................174 Read Mailbox Object Class Properties............................................177 Read Mailbox Name .........................................................................179 Read Mailbox Properties..................................................................181 Read Mailbox Semaphore................................................................183 Initialize Mailbox Object Class........................................................185 Look Up Mailbox by Name ..............................................................187 Allocate Mailbox ...............................................................................189 Read Mailbox Handle and Register It.............................................192 Acknowledge Message .....................................................................195 Forward Message .............................................................................198 Receive Next Message from a Mailbox ...........................................201 Receive Message—Wait Number of Ticks If Necessary................203 Receive Message—Wait If Necessary .............................................205 Send Message—Wait for Acknowledgment...................................208 Send Message—Wait Number of Ticks for Acknowledgment .....212 Send Message—Wait for Acknowledgment...................................214 Test for Message Acknowledgment ................................................217 Test for Message Acknowledgment—Wait Number of Ticks for Acknowledgment .......................................................219 Test for Acknowledgment and Wait if Necessary ..........................221 Allocate Block of Memory................................................................225 Allocate Block of Memory—Wait Number of Ticks If Necessary.227 Allocate Block of Memory—Wait If Necessary ..............................229 Close Memory Partition...................................................................231 Assign Memory Partition Name .....................................................233 Define Memory Partition Properties ..............................................235 Associate Semaphore With Memory Partition...............................237 Allocate and Free Memory Block ....................................................239 Read Memory Partition Free Block Count .....................................241 Read Memory Partition Object Class Properties ...........................243 Read Memory Partition Name ........................................................245 Memory Partition Properties Structure..........................................246 Read Memory Partition Properties .................................................247

List of Examples

June 21, 2002

xiii

Example 7-14 Example 7-15 Example 7-16 Example 7-17 Example 7-18 Example 8-1 Example 8-2 Example 8-3 Example 8-4 Example 8-5 Example 8-6 Example 8-7 Example 8-8 Example 8-9 Example 8-10 Example 8-11 Example 8-12 Example 8-13 Example 8-14 Example 8-15 Example 8-16 Example 8-17 Example 9-1 Example 9-2 Example 9-3 Example 9-4 Example 9-5 Example 9-6 Example 9-7 Example 9-8 Example 9-9

xiv

June 21, 2002

Read Memory Partition Semaphore............................................... 249 Initialize Memory Partition Object Class....................................... 251 Look Up Memory Partition by Name ............................................. 253 Allocate and Name Memory Partition............................................ 255 Read Memory Partition Handle and Register It............................ 257 Close Mutex ..................................................................................... 261 Close Mutex ..................................................................................... 263 Define Mutex Properties ................................................................. 266 Associate Semaphore with Mutex .................................................. 268 Read Mutex Object Class Properties .............................................. 271 Read Mutex Name ........................................................................... 273 Read Mutex Owner.......................................................................... 275 Read Mutex Properties .................................................................... 277 Read Mutex Semaphore .................................................................. 279 Initialize Mutex Object Class.......................................................... 281 Look Up Mutex by Name ................................................................ 283 Allocate and Name Mutex............................................................... 285 Release Mutex .................................................................................. 287 Test Mutex for Ownership by Current Task .................................. 289 Test Mutex—Wait Number of Ticks If Not Available ................... 292 Test Mutex—Wait If Not Available ................................................ 295 Read Mutex Handle and Register It ............................................... 297 Allocate System RAM from Zone 3................................................ 301 Define Fatal Error Function............................................................ 303 Read Amount of Available System RAM from Zone 3 ................. 304 Read Fatal Error Function............................................................... 305 Read System Properties .................................................................. 307 Read Version Number..................................................................... 309 Initialize Kernel Properties ............................................................. 312 Execute No-Operation Service ........................................................ 313 Execute Non-RTXC Function as Kernel Service............................. 315

RTXC Kernel Services Reference, Volume 2

CHAPTER

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 Special Services ...........................................................................20

Chapter 1: Introduction To RTXC/ms Kernel Services

June 21, 2002

1

Using This Manual

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

2

June 21, 2002

RTXC Kernel Services Reference, Volume 2

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 rtxcapi.h as (THREAD)0. The putline function moves the content of a character buffer to an assumed console device.

Chapter 1: Introduction To RTXC/ms Kernel Services

June 21, 2002

3

Using This Manual

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

Brief Functional Description

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.

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: 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.

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: [noun|property][suffix]

4

June 21, 2002

RTXC Kernel Services Reference, Volume 2

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: 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.

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 up the development process. When the application is generated in diagnostic mode, the RTXC Kernel performs numerous validity tests on the arguments being passed in kernel service calls. When an argument fails its validity test, the kernel passes a fatal error code to the system error function. The Errors section of each service

Chapter 1: Introduction To RTXC/ms Kernel Services

June 21, 2002

5

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

6

June 21, 2002

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 timesliced 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

KSRC

Kernel Service Return Code

RTXC Kernel Services Reference, Volume 2

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 cross-reference to the detailed description of the service in the reference chapters of this book.

Chapter 1: Introduction To RTXC/ms Kernel Services

June 21, 2002

7

RTXC/ms Component Services

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

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.

41

8

June 21, 2002

RTXC Kernel Services Reference, Volume 2

Zones

Ref.

RTXC/ms Component Services

Table 1-3. Task Services Summary (continued) Service

Description

Zones

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

KS_UseTask

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

74

KS_YieldTask

Yield to the next ready task of the same priority.

76

Chapter 1: Introduction To RTXC/ms Kernel Services

June 21, 2002

Ref.

9

RTXC/ms Component Services

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 Service

Description

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.

108

10

June 21, 2002

RTXC Kernel Services Reference, Volume 2

Zones

Ref.

RTXC/ms Component Services

Table 1-4. Semaphore Services Summary (continued) Service

Description

Zones

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

Chapter 1: Introduction To RTXC/ms Kernel Services

June 21, 2002

Ref.

11

RTXC/ms Component Services

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 Service

Description

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

INIT_QueueClassProp

Initialize the Queue object class properties.

148

12

June 21, 2002

RTXC Kernel Services Reference, Volume 2

Zones

Ref.

RTXC/ms Component Services

Table 1-5. Queue Services Summary (continued) Service

Description

Zones

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

Chapter 1: Introduction To RTXC/ms Kernel Services

June 21, 2002

Ref.

13

RTXC/ms Component Services

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 Service

Description

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.

191

14

June 21, 2002

RTXC Kernel Services Reference, Volume 2

Zones

Ref.

RTXC/ms Component Services

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 Service

Description

Zones

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.

218

KS_TestAckW

Test for message acknowledgment and wait for the acknowledgment.

220

Chapter 1: Introduction To RTXC/ms Kernel Services

June 21, 2002

Ref.

15

RTXC/ms Component Services

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 Service

Description

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

KS_GetPartProp

Get the properties of a partition.

246

16

June 21, 2002

RTXC Kernel Services Reference, Volume 2

Zones

Ref.

RTXC/ms Component Services

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

Description

Zones

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

Chapter 1: Introduction To RTXC/ms Kernel Services

June 21, 2002

Ref.

17

RTXC/ms Component Services

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 Service

Description

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.

288

18

June 21, 2002

RTXC Kernel Services Reference, Volume 2

Zones

Ref.

RTXC/ms Component Services

Table 1-9. Mutex Services Summary (continued) Service

Description

Zones

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

Chapter 1: Introduction To RTXC/ms Kernel Services

June 21, 2002

Ref.

19

RTXC/ms Component Services

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 Service

Description

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

KS_UserService

Perform a user-defined kernel service.

314

20

June 21, 2002

RTXC Kernel Services Reference, Volume 2

Zones

Ref.

CHAPTER

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 KS_GetTaskSema ............................................................................... 56 KS_GetTaskState ................................................................................ 58 KS_GetTickSlice ................................................................................ 60 INIT_TaskClassProp ..........................................................................62

Chapter 2: Task Services

June 21, 2002

21

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

22

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_AbortTask

KS_AbortTask Abort the execution of a task.

Synopsis Input Description

void KS_AbortTask (TASK task)

task

The number of the task to abort.

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.

Output

This service does not return a value.

Chapter 2: Task Services

June 21, 2002

23

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" #include "ktask.h" KS_AbortTask (TASKBX);

/* abort task TASKBX */

KS_TerminateTask (SELFTASK);

/* now terminate self */

See Also

24

June 21, 2002

/* RTXC Kernel Service prototypes */ /* defines TASKBX */

KS_TerminateTask, page 72

RTXC Kernel Services Reference, Volume 2

KS_CloseTask

KS_CloseTask End the use of a dynamic task.

Synopsis Input Description

KSRC KS_CloseTask (TASK task)

task

The number of the task to close.

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.

Error

This service may generate the following fatal error code: FE_ILLEGAL_TASK if the specified task ID is not valid.

Chapter 2: Task Services

June 21, 2002

25

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; SEMA dynsema;

/* not SELFTASK (TASK)0 */

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 */

See Also

26

June 21, 2002

KS_OpenTask,page 66 KS_UseTask, page 74

RTXC Kernel Services Reference, Volume 2

KS_DefTaskEnvArg

KS_DefTaskEnvArg Define the environment arguments for a task.

Synopsis Inputs

Description

void KS_DefTaskEnvArg (TASK task, const void *parg)

task

The number of the task being defined.

parg

A pointer to the environment arguments structure for the task.

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

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-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 must be allocated dynamically and its identifier is stored in the dyntask variable. The dynamic task’s entry address is taskA and it requires a 256-byte stack that the Current Task allocates from the BLK256 memory partition. The dynamic task runs at priority 14.

Chapter 2: Task Services

June 21, 2002

27

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" #include "kpart.h"

/* RTXC Kernel Service prototypes */ /* Memory Partitions */

#define STKSIZE 256 #define DYNPRI 14 extern void taskA (void); struct{ int port; int channel; } envargA; /* environment argument structure */ TASK TASKPROP int

dyntask; tprop; 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); }

28

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_DefTaskEnvArg

See Also

KS_DefTaskProp, page 34 KS_GetTaskEnvArg, page 44

Chapter 2: Task Services

June 21, 2002

29

KS_DefTaskName

KS_DefTaskName Define the name of a previously opened dynamic task.

Synopsis Inputs

Description

KSRC KS_DefTaskName (TASK task, const char *pname)

task

The number of the task being defined.

pname

A pointer to a null-terminated name string.

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

This service returns a KSRC value as follows: `

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.

30

June 21, 2002

RTXC Kernel Services Reference, Volume 2

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

See Also

KS_OpenTask, page 66 KS_GetTaskName, page 51 KS_LookupTask, page 64 KS_UseTask, page 74

Chapter 2: Task Services

June 21, 2002

31

KS_DefTaskPriority

KS_DefTaskPriority Define a new priority for a task.

Synopsis Inputs

Description

void KS_DefTaskPriority (TASK task, PRIORITY priority)

task

The number of the task being defined.

priority

The priority value for the task.

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

This service does not return a value.

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.

32

June 21, 2002

RTXC Kernel Services Reference, Volume 2

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" #include "ktask.h"

/* RTXC Kernel Service prototypes */ /* defines SERIALIN */

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

See Also

KS_ExecuteTask, page 42 KS_TerminateTask, page 72

Chapter 2: Task Services

June 21, 2002

33

KS_DefTaskProp

KS_DefTaskProp Define the properties of a task.

Synopsis Inputs

Description

void KS_DefTaskProp (TASK task, const TASKPROP *ptaskprop)

task

The number of the task being defined.

ptaskprop

A pointer to a Task properties structure.

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); char *stackbase; ksize_t stacksize; PRIORITY priority; } TASKPROP;

initial initial initial initial

entry point address */ stack base */ stack size */ priority */

Output

This service does not return a value.

Error

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

34

June 21, 2002

/* /* /* /*

`

FE_ILLEGAL_TASK if the specified task ID is not valid.

`

FE_ILLEGAL_PRIORITY if the specified priority is out of range.

RTXC Kernel Services Reference, Volume 2

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. `

Example

FE_ZERO_STACKSIZE if the specified Task stack size is zero.

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 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); }

See Also

46

June 21, 2002

KS_DefTaskEnvArg, page 27

RTXC Kernel Services Reference, Volume 2

KS_GetTaskClassProp

KS_GetTaskClassProp Get the Task object class properties.

Synopsis Input Description

const KCLASSPROP * KS_GetTaskClassProp (int *pint)

pint

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

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; KOBJECT n_dynamics; short objsize; short totalsize; ksize_t namelen; const char *pstaticnames; } KCLASSPROP;

/* /* /* /* /*

number of static objects */ number of dynamic objects */ used for calculating offsets */ used to alloc object array RAM */ length of the name string */

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

Chapter 2: Task Services

June 21, 2002

47

KS_GetTaskClassProp

Table 2-1. Task Class Attributes and Masks

Output

Attribute

Mask

Static Names

ATTR_STATIC_NAMES

Dynamics

ATTR_DYNAMICS

Tick Slice

ATTR_TICKSLICE

Environment Arguments

ATTR_TASK_ENV

Task Semaphores

ATTR_TASK_SEMAPHORES

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

48

June 21, 2002

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.

RTXC Kernel Services Reference, Volume 2

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 }

See Also

INIT_TaskClassProp, page 62

Chapter 2: Task Services

June 21, 2002

49

KS_GetTaskID

KS_GetTaskID Get the handle of the Current Task.

Synopsis

TASK KS_GetTaskID (void)

Inputs

This service has no 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 #include "rtxcapi.h"

/* standard i/o */ /* RTXC Kernel Service prototypes */

static char buf[128]; TASK mytaskid; mytaskid = KS_GetTaskID (); sprintf (buf, "Current Task ID is %d", mytaskid); putline (buf);

50

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_GetTaskName

KS_GetTaskName Get the name of a task.

Synopsis Input Description

char * KS_GetTaskName (TASK task)

task

The number of the task being queried.

The KS_GetTaskName kernel service obtains a pointer to the nullterminated 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 nullterminated 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.

Chapter 2: Task Services

June 21, 2002

51

KS_GetTaskName

Example 2-16. Read Dynamic Task Name #include #include "rtxcapi.h"

/* standard i/o */ /* 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);

See Also

52

June 21, 2002

KS_DefTaskName, page 30 KS_OpenTask, page 66

RTXC Kernel Services Reference, Volume 2

KS_GetTaskPriority

KS_GetTaskPriority Get the priority of a task.

Synopsis Input

PRIORITY KS_GetTaskPriority (TASK task)

task

The number of the task being queried.

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

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

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);

See Also

KS_DefTaskPriority, page 32

Chapter 2: Task Services

June 21, 2002

53

KS_GetTaskProp

KS_GetTaskProp Get the properties of a task.

Synopsis Inputs

Description

void KS_GetTaskProp (TASK task, TASKPROP *ptaskprop)

task

The number of the task being queried.

ptaskprop

A pointer to a task property structure.

The KS_GetTaskProp kernel service obtains all of the property values of the specified task in a single call. The task argument may specify a static or a dynamic task. The service stores the property values in the TASKPROP structure pointed to by ptaskprop. The TASKPROP structure has the following organization:

typedef struct { void (*taskentry)(void); char *stackbase; ksize_t stacksize; PRIORITY priority; } TASKPROP;

/* /* /* /*

initial initial initial initial

entry point addr. */ stack base */ stack size */ priority */

Output

This service returns the properties of the task in the property structure pointed to by ptaskprop.

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

54

June 21, 2002

In Example 2-18 on page 55, the Current Task needs to terminate a dynamic task named DynMuxTask2, which is known to be running. The Current Task must first call KS_TerminateTask to stop execution of the task, then release the terminated task’s stack space to the BLK256 memory partition from where it was initially allocated.

RTXC Kernel Services Reference, Volume 2

KS_GetTaskProp

Example 2-18. Terminate Task and Release Its Stack #include "rtxcapi.h" #include "kpart.h"

/* RTXC Kernel Service prototypes */ /* defines BLK256 */

TASK dyntask; static TASKPROP tprop; /* first, get the task number of DynMuxTask2" */ if (KS_LookupTask ("DynMuxTask2", &dyntask) != RC_GOOD) { ... Task "DynMuxTask2" does not exist. } else { /* task was found, now get its properties */ KS_GetTaskProp (dyntask, &tprop); /* terminate task */ KS_TerminateTask (dyntask); /* Now free the block used for its stack */ KS_FreeBlk (BLK256, tprop.stackbase); }

See Also

KS_DefTaskProp, page 34

Chapter 2: Task Services

June 21, 2002

55

KS_GetTaskSema

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

Synopsis Input

SEMA KS_GetTaskSema (TASK task)

task

Description

The number of the task being queried.

The KS_GetTaskSema kernel service obtains the handle of the semaphore associated with the termination or abortion of the static or dynamic task specified in task. You must have previously associated the semaphore and the task event through a call to the KS_DefTaskSema service. Note: To use this service, you must enable the Semaphores attribute of the Task class during system generation.

Output

If the task and semaphore association exists, this service returns the handle of the semaphore as a SEMA type value. If there is no such association for the task, this service returns a SEMA value of zero (0).

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

56

June 21, 2002

In Example 2-19 on page 57, the Current Task needs to know the handle of the semaphore associated with the termination or abortion of the dynamic task specified in dyntask. If the return from KS_GetTaskSema indicates there is no semaphore defined, the Current Task defines the TASKTERM semaphore, adds it to semalist, and waits for the indicated events.

RTXC Kernel Services Reference, Volume 2

KS_GetTaskSema

Example 2-19. Read Task Termination Semaphore #include "rtxcapi.h" #include "ksema.h" SEMA semalist[] = { OEVENT, (SEMA)0, (SEMA)0 }

/* RTXC Kernel Service prototypes */ /* defines TASKTERM, OEVENT */

/* other event */ /* tasksema, to be filled in below */ /* null terminator */

TASK dyntask; SEMA tasksema, cause; if ((tasksema = KS_GetTaskSema (dyntask)) == (SEMA)0) { /* Semaphore undefined for dyntask */ KS_DefTaskSema (dyntask, TASKTERM); /* define one now */ tasksema = TASKTERM; } /* there is now a semaphore defined for dyntask */ /* store it in semalist */ semalist[1] = tasksema; /* and wait for either event to occur */ cause = KS_TestSemaMW (semalist); ... continue processing according to cause of resumption

See Also

KS_DefTaskSema, page 36

Chapter 2: Task Services

June 21, 2002

57

KS_GetTaskState

KS_GetTaskState Get the state of a task.

Synopsis Input

KSRC KS_GetTaskState (TASK task)

task

The number of the task being queried.

Description

The KS_GetTaskState kernel service obtains the state of the static or dynamic task specified in task.

Output

This service returns a KSRC value as follows: `

RC_TASK_ACTIVE if the task has been previously made runnable

by a KS_ExecuteTask request and is currently runnable or blocked on a condition other that ABORT_BLOCK or INACTIVE. `

RC_TASK_INACTIVE if the task is currently in an INACTIVE

state. `

RC_TASK_ABORTED if the task is currently in an ABORT_BLOCK

state.

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

58

June 21, 2002

In Example 2-20 on page 59, the Current Task needs to know the state of a task if the task fails to begin execution properly following a call to KS_ExecuteTask.

RTXC Kernel Services Reference, Volume 2

KS_GetTaskState

Example 2-20. Read Task State #include "rtxcapi.h" #include "ktask.h"

/* RTXC Kernel Service prototypes */ /* defines TASKX */

if (KS_ExecuteTask (TASKX) != RC_GOOD ) { /* Task was not started, why? */ if (KS_GetTaskState (TASKX) == RC_TASK_ACTIVE) { ...TASKX was active. deal with it } else { ... TASKX was aborted. deal with it } } /* task TASKX was successfully started */ ... continue

Chapter 2: Task Services

June 21, 2002

59

KS_GetTickSlice

KS_GetTickSlice Get the tick-slice quantum of a task.

Synopsis Input

TSLICE KS_GetTickSlice (TASK task)

task

Description

The number of the task being queried.

The KS_GetTickSlice kernel service obtains the value of the tickslice quantum for the specified task. If there has been no tick-slice quantum defined for task, the service returns a value of zero (0). Note: To use this service, you must enable the Tick Slice attribute of the Task class during system generation.

Output

This service returns the specified task’s tick-slice quantum in units of system clock ticks as a TSLICE type value.

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

Example 2-21 gets the tick-slice quantum for the SCANR task. If the quantum has not been defined, it defines the task’s tick quantum as 100 msec.

Example 2-21. Read Task Tick-Slice Quantum #include "rtxcapi.h" #include "ktask.h" #include "kproject.h"

/* RTXC Kernel Service prototypes */ /* defines SCANR */ /* defines CLKTICK */

if (KS_GetTickSlice (SCANR) == (TICKS)0) KS_DefTickSlice (SCANR, (TICKS)100/CLKTICK);

60

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_GetTickSlice

See Also

KS_DefTickSlice, page 38

Chapter 2: Task Services

June 21, 2002

61

INIT_TaskClassProp

INIT_TaskClassProp Initialize the Task object class properties.

Synopsis Input

KSRC INIT_TaskClassProp (const KCLASSPROP *pclassprop)

pclassprop

Description

A pointer to a Task object class properties structure.

During the RTXC Kernel initialization procedure, you must define the kernel objects needed by the RTXC Kernel to perform the application. The INIT_TaskClassProp kernel service allocates space for the Task object class in system RAM. The amount of RAM to allocate, and all other properties of the class, are specified in the structure pointed to by pclassprop. Example 2-22 shows the organization of the KCLASSPROP structure.

Example 2-22. Object Class Properties Structure typedef struct { KATTR attributes; KOBJECT n_statics; KOBJECT n_dynamics; short objsize; short totalsize; ksize_t namelen; const char *pstaticnames; } KCLASSPROP;

/* /* /* /* /*

number of static objects */ number of dynamic objects */ used for calculating offsets */ used to alloc object array RAM */ length of the name string */

The attributes element of the Task property structure supports the attributes and corresponding masks listed in Table 2-1 on page 48.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the service completes successfully.

`

RC_NO_RAM if the initialization fails because there is insufficient

system RAM available.

62

June 21, 2002

RTXC Kernel Services Reference, Volume 2

INIT_TaskClassProp

Example

During system initialization, the startup code must initialize the Task object class before using any kernel service for that class. In Example 2-23 on page 63, the system generation process produced a KCLASSPROP structure containing the information about the kernel class necessary for its initialization. That structure is referenced externally to the code. The example outputs any error messages to the console.

Example 2-23. Initialize Task Object Class #include "rtxcapi.h"

/* RTXC Kernel Service prototypes */

extern const SYSPROP sysprop; extern const KCLASSPROP taskclassprop; KSRC userinit (void) { KSRC ksrc; static char buf[128]; /* initialize the kernel workspace, allocate RAM for required classes, etc. */ if ((ksrc = INIT_SysProp (&sysprop)) != RC_GOOD) { putline ("Kernel initialization failure"); return (ksrc); /* end initialization process */ } /* kernel is initialized */ /* Need to initialize the necessary kernel object classes */ /* Initialize the Task Kernel Object class */ if ((ksrc = INIT_TaskClassProp (&taskclassprop)) != RC_GOOD) { putline ("Insufficient RAM for Task init."); return (ksrc); /* end initialization process */ } ... Continue with system initialization }

See Also

INIT_SysProp, page 310 KS_GetTaskClassProp, page 47

Chapter 2: Task Services

June 21, 2002

63

KS_LookupTask

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

Synopsis Inputs

Description

KSRC KS_LookupTask (const char *pname, TASK *ptask)

pname

A pointer to the null-terminated name string for the task.

ptask

A pointer to a variable in which to store the matching task’s handle, if found.

The KS_LookupTask kernel service obtains the handle of a static or dynamic task whose name matches the null-terminated string pointed to by pname. The lookup process terminates when it finds a match between the specified string and a static or dynamic task name or when it finds no match. The service searches dynamic names, if any, first. If a match is found, the service stores the handle of the task in the variable pointed to by ptask. Note: To use this service on static tasks, you must enable the Static Names attribute of the Task class during system generation.

This service has no effect on the registration of the specified task by the Current Task. The time required to perform this operation varies with the number of task names in use.

Output

This service returns a value as follows: `

RC_GOOD if the search succeeds. The service stores the handle of

the task in the variable pointed to by ptask. `

RC_OBJECT_NOT_FOUND if the service finds no matching task

name.

64

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_LookupTask

Example

In Example 2-24, the Current Task needs to use the DynMuxTask2 dynamic task. If the task name is found, the example outputs the task handle to the console in a brief message.

Example 2-24. Look Up Task by Name #include #include "rtxcapi.h"

/* standard i/o */ /* RTXC Kernel Service prototypes */

TASK dyntask; static char buf[128]; /* lookup the task name to see if it exists */ if (KS_LookupTask ("DynMuxTask2", &dyntask) != RC_GOOD) { putline ("Task DynMuxTask2 name not found"); } else /* task exists */ { sprintf (buf, "DynMuxTask2 is task %d", dyntask); putline (buf); }

See Also

KS_DefTaskName, page 30 KS_OpenTask, page 66

Chapter 2: Task Services

June 21, 2002

65

KS_OpenTask

KS_OpenTask Allocate and name a dynamic task.

Synopsis Inputs

Description

KSRC KS_OpenTask (const char *pname, TASK *ptask)

pname

A pointer to the null-terminated name string for the task.

ptask

A pointer to a variable in which to store the allocated task’s handle.

The KS_OpenTask kernel service allocates, names, and obtains the handle of a dynamic task. If a dynamic task is available and there is no existing task, static or dynamic, with a name matching the nullterminated string pointed to by pname, the service allocates a dynamic task and applies the name referenced by pname to the new task. The service stores the handle of the new dynamic task in the variable pointed to by ptask. The kernel stores only the address of the name internally, which means that the same array cannot be used to build multiple dynamic task names. If pname is a null pointer ((char *)0), the service does not assign a name to the dynamic task. However, if pname points to a null string, the name is legal as long as no other task is already using a null string as its name. If the service finds an existing task with a matching name, it does not open a new task and returns a value indicating an unsuccessful operation. Note: To use this service, you must enable the Dynamics attribute of the Task class during system generation.

If the pointer to the task name is not null, the time required to perform this operation varies with the number of task names in use.

66

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_OpenTask

If the pointer to the task name is null, no search of task names takes place and the time to perform the service is fixed. You can define the task name at a later time with a call to the KS_DefTaskName service.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the service completes successfully. The service stores

the handle of the new dynamic task in the variable pointed to by ptask. `

RC_OBJECT_ALREADY_EXISTS if the name search finds another

task whose name matches the specified string. `

Example

RC_NO_OBJECT_AVAILABLE if the name search finds no match but all dynamic tasks are in use.

Example 2-25 allocates a dynamic task and names it DynMuxTask2.

Example 2-25. Allocate Dynamic Task #include "rtxcapi.h"

/* RTXC Kernel Service prototypes */

KSRC ksrc; TASK dyntask; if ((ksrc = KS_OpenTask ("DynMuxTask2", &dyntask)) != RC_GOOD) { if (ksrc == RC_OBJECT_ALREADY_EXISTS) putline ("DynMuxTask2 task name in use"); else if (ksrc == RC_NO_OBJECT_AVAILABLE) putline ("No dynamic tasks available"); else putline ("Tasks are not a defined class"); } else { ... task was opened correctly. Okay to use it now }

See Also

KS_CloseTask, page 25 KS_LookupTask, page 64 KS_UseTask, page 74

Chapter 2: Task Services

June 21, 2002

67

XX_ResumeTask

XX_ResumeTask Resume a task that was previously suspended.

Zones

IS_ResumeTask TS_ResumeTask KS_ResumeTask

Synopsis Input

void XX_ResumeTask (TASK task)

task

Description

The number of the task to resume.

The XX_ResumeTask kernel service clears the suspended state of the specified task caused by a previous call to the KS_SuspendTask service. If the resumed task becomes runnable, the kernel inserts it into the Ready List at a position dependent upon its priority. If a task requests the service and the resumed task is of higher priority than the requesting task, the kernel performs a context switch. Otherwise, the kernel returns control to the requesting task. The task argument must contain an actual task handle and cannot be zero (0) to indicate the Current Task. The calling task is obviously not suspended if it is making the kernel call. If task is zero, the call to XX_ResumeTask causes no change in the system and the Current Task continues without error. If an interrupt service routine makes the service request and the task becomes runnable, task cannot resume execution until the current interrupt has been completely serviced as well as all other outstanding interrupts, threads and higher priority runnable tasks.

Output

This service does not return a value.

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.

68

June 21, 2002

RTXC Kernel Services Reference, Volume 2

XX_ResumeTask

Example

In Example 2-26, a task suspends the AIREADER analog input task, performs some operations, and then resumes the analog input task.

Example 2-26. Resume Suspended Task from Zone 3 #include "rtxcapi.h" #include "ktask.h"

/* RTXC Kernel Service prototypes */ /* defines AIREADER */

KS_SuspendTask (AIREADER);

/* suspend task AIREADER */

... perform some operations KS_ResumeTask (AIREADER);

See Also

/* resume task AIREADER */

KS_SuspendTask, page 71

Chapter 2: Task Services

June 21, 2002

69

KS_SleepTask

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

Synopsis Inputs

void KS_SleepTask (COUNTER counter, TICKS ticks)

counter

The counter associated with the interval defined by ticks.

ticks

The number of ticks the Current Task should sleep.

Description

The KS_SleepTask kernel service blocks the Current Task for the specified number of ticks.

Output

This service does not return a value.

Example

In Example 2-27, the Current Task is put to sleep for a period of 100 msec. After some processing, the task is put to sleep again for a period of 50 msec.

Example 2-27. Put Current Task to Sleep #include "rtxcapi.h" #include "kproject.h" #include "kcounter.h"

/* RTXC Kernel Service prototypes */ /* defines CLKTICK */ /* defines COUNTER1 */

/* delay Current Task for 100 ms */ KS_SleepTask (COUNTER1, (TICKS)100/CLKTICK); ... continue processing after delay /* then do another delay for 50 ms */ KS_SleepTask (COUNTER1, (TICKS)50/CLKTICK);

70

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_SuspendTask

KS_SuspendTask Suspend a task.

Synopsis Input

void KS_SuspendTask (TASK task)

task

The number of the task to suspend.

Description

The KS_SuspendTask kernel service puts the specified task into a suspended state and removes it from the Ready List. The task remains in the suspended state until it is resumed by a call to the XX_ResumeTask service. A task may suspend itself by using a task value of zero (0).

Output

This service does not return a value.

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-28, the Current Task suspends the LKDETECT task and then suspends itself.

Example 2-28. Suspend Task #include "rtxcapi.h" #include "ktask.h"

/* RTXC Kernel Service prototypes */ /* defines LKDETECT */

KS_SuspendTask (LKDETECT);

/* suspend LKDETECT task */

KS_SuspendTask (SELFTASK);

/* suspend self */

See Also

XX_ResumeTask, page 68 KS_ExecuteTask, page 42

Chapter 2: Task Services

June 21, 2002

71

KS_TerminateTask

KS_TerminateTask Terminate a task.

Synopsis Input

void KS_TerminateTask (TASK task)

task

Description

The number of the task to terminate.

The KS_TerminateTask kernel service stops the specified task by removing it from the Ready List, if it is runnable, and by setting its status to INACTIVE. A task value of zero (0) indicates selftermination. If task has previously been put to sleep, the sleep alarm is stopped. If task is waiting on some kernel object, it is removed from that object’s list of waiters. If task is waiting on a kernel object with an associated alarm, it is removed from that object’s list of waiters and the alarm is stopped. If task is dynamic, it is not released to the free pool of dynamic tasks. A task can be released only by making a call to KS_CloseTask. Warning: While it is possible to terminate another task, it should only be done when the terminator knows the act will not jeopardize system integrity. The termination process does not clean up tasks that are currently using or have allocated kernel objects. The programmer must ensure all such system elements are released to the system before termination.

Output

This service does not return a value.

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.

72

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_TerminateTask

Example

In Example 2-29, the Current Task terminates the TASKBX task and then terminates itself.

Example 2-29. Terminate Task #include "rtxcapi.h" #include "ktask.h"

/* RTXC Kernel Service prototypes */ /* defines TASKBX */

KS_TerminateTask (TASKBX);

/* terminate task TASKBX */

KS_TerminateTask (SELFTASK);

/* now terminate self */

See Also

KS_CloseTask, page 25 KS_ExecuteTask, page 42

KS_DefTaskSema, page 36

Chapter 2: Task Services

June 21, 2002

73

KS_UseTask

KS_UseTask Look up a dynamic task by name and mark it for use.

Synopsis Inputs

Description

KSRC KS_UseTask (const char *pname, TASK *ptask)

pname

A pointer to a null-terminated name string.

ptask

A pointer to a variable in which to store the task’s handle, if found.

The KS_UseTask kernel service acquires the handle of a dynamic task by looking up the null-terminated string pointed to by pname in the list of task names. If there is a match, the service registers the task for future use by the Current Task and stores the matching task’s handle in the variable pointed to by ptask. This procedure allows the Current Task to reference the dynamic task successfully in subsequent kernel service calls. Note: To use this service, you must enable the Dynamics attribute of the Task class during system generation.

The time required to perform this operation varies with the number of task names in use.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the search and registration is successful. The service

stores the matching task’s handle in the variable pointed to by ptask. `

RC_STATIC_OBJECT if the specified name belongs to a static

task. `

RC_OBJECT_NOT_FOUND if the service finds no matching task

name.

Example

74

June 21, 2002

Example 2-30 on page 75 locates the DynMuxTask3 dynamic task by its name and obtains its handle. It then outputs a message to the

RTXC Kernel Services Reference, Volume 2

KS_UseTask

console indicating the handle of the task if successful or an error message if unsuccessful. Example 2-30. Read Task Handle and Register It #include #include "rtxcapi.h"

/* standard i/o */ /* RTXC Kernel Service prototypes */

TASK dyntask; KSRC ksrc; static char buf[128]; if ((ksrc = KS_UseTask ("DynMuxTask3", &dyntask)) != RC_GOOD) { if (ksrc == RC_STATIC_OBJECT) putline ("Task DynMuxTask3 is a static task"); else putline ("Task DynMuxTask3 not found"); } else { /* task was found and its handle is in dyntask. */ sprintf (buf, "DynMuxTask3 is task %d", dyntask); putline (buf); }

See Also

KS_DefTaskProp, page 34 KS_DefTaskName, page 30 KS_OpenTask, page 66

Chapter 2: Task Services

June 21, 2002

75

KS_YieldTask

KS_YieldTask Yield to the next ready task of the same priority.

Synopsis

KSRC KS_YieldTask (void)

Inputs

This service has no inputs.

Description

The KS_YieldTask kernel service voluntarily releases control by the Current Task without violating the policy of the highest priority runnable task being the Current Task. This service is useful only when there are two or more tasks operating at the same priority. When KS_YieldTask is called and there is one more task in the Ready List at the same priority, the calling task is removed from the Ready List and reinserted into the Ready List immediately following the last runnable task with the same priority. The task remains unblocked. Yielding when there is no other task at the same priority causes no change in the Ready List and the calling task resumes immediately.

Output

This service returns a KSRC value as follows:

Example

76

June 21, 2002

`

RC_GOOD if the yield is successful.

`

RC_NO_YIELD if no yield can occur.

In Example 2-31 on page 77, the Current Task has reached a point in its processing where it will yield to another task if that task is running at the same priority as the Current Task. If not, this kernel service operates without changing the Ready List.

RTXC Kernel Services Reference, Volume 2

KS_YieldTask

Example 2-31. Yield to Another Task #include "rtxcapi.h"

/* RTXC Kernel Service prototypes */

/* yield to next READY task at same priority */ if (KS_YieldTask () == RC_NO_YIELD) { ... no READY task exists at same priority level take whatever action is required } /* otherwise, the yield was successful and the next */ /* line of code following this comment will execute */ /* when the task next gains control of the CPU /*

Chapter 2: Task Services

June 21, 2002

77

KS_YieldTask

78

June 21, 2002

RTXC Kernel Services Reference, Volume 2

CHAPTER

3

Semaphore Services

In This Chapter We describe the Semaphore kernel services in detail. The Semaphore kernel services provide intertask synchronization between the calling task and other tasks through semaphores. 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 KS_UseSema .................................................................................... 120

Chapter 3: Semaphore Services

June 21, 2002

79

KS_CloseSema

KS_CloseSema End the use of a dynamic semaphore.

Synopsis Input

KSRC KS_CloseSema (SEMA sema)

sema

Description

The handle of the semaphore the Current Task should stop using.

The KS_CloseSema kernel service ends the Current Task’s use of the dynamic semaphore specified in sema. When closing the semaphore, the kernel detaches the calling task’s use of sema. If the caller is sema’s last user, the kernel releases the semaphore to the free pool of dynamic semaphores for reuse. If there is at least one other task using sema, the kernel does not release the semaphore to the free pool. Be careful when closing a semaphore on which multiple tasks may be waiting. Closing the semaphore may cause waiters to be lost. However, you can avoid this problem if each task that uses the semaphore makes a KS_UseSema call before it begins using the semaphore and then makes a KS_CloseSema call when it is done using the semaphore. Note: To use this service, you must enable the Dynamics attribute of the Semaphore class during system generation.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the service is successful.

`

RC_STATIC_OBJECT if the specified semaphore is not dynamic.

`

RC_OBJECT_NOT_INUSE if the specified semaphore does not

correspond to an active dynamic semaphore. `

80

June 21, 2002

RC_OBJECT_INUSE if the Current Task’s use of the specified semaphore is closed but it remains open for use by other tasks.

RTXC Kernel Services Reference, Volume 2

KS_CloseSema

Note: RC_OBJECT_INUSE does not necessarily indicate an error condition. The calling task must interpret its meaning.

Error

This service may generate the following fatal error code: FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.

Example

In Example 3-1, the Current Task waits on a signal from another task indicating that it is time to close a dynamic semaphore. The handle of the dynamic semaphore is specified in dynsema. When the signal is received on the ENDALL semaphore, the Current Task closes its use of the associated dynamic semaphore.

Example 3-1. Close Semaphore #include "rtxcapi.h" #include "ksema.h" SEMA dynsema; KSRC ksrc;

/* RTXC Kernel Service prototypes */ /* defines ENDALL */

/* dynamic semaphore's handle */

KS_TestSemaW (ENDALL); /* wait for signal */ /* then close the semaphore */ if ((ksrc = KS_CloseSema (dynsema)) != RC_GOOD) { ... may want to test return code and do something } ... dynamic semaphore is closed, continue

See Also

KS_OpenSema, page 100 KS_UseSema, page 120

Chapter 3: Semaphore Services

June 21, 2002

81

KS_DefSemaCount

KS_DefSemaCount Define a semaphore count.

Synopsis Inputs

void KS_DefSemaCount (SEMA sema, SEMACOUNT count)

sema

The handle of the semaphore being defined.

count

The count value for the semaphore.

Description

The KS_DefSemaCount kernel service manipulates the count of the semaphore specified in sema. The count argument may be any value. If count is less than or equal to the current semaphore count, the semaphore count is set to count. Otherwise, the semaphore is signaled a number of times equal to the difference between the current count and count.

Output

This service does not return a value.

Errors

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

FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.

`

FE_UNINITIALIZED_SEMA if the specified semaphore has not

yet been initialized.

Example

82

June 21, 2002

In Example 3-2 on page 83, the Current Task forces the count of the MYSEMA static semaphore to a PENDING (zero) value to ensure it is in a known condition before subsequent use. The task then increments the semaphore count to three and then to five.

RTXC Kernel Services Reference, Volume 2

KS_DefSemaCount

Example 3-2. Set Semaphore Count #include "rtxcapi.h" #include "ksema.h"

/* RTXC Kernel Service prototypes */ /* defines MYSEMA */

/* force count to zero (0) */ KS_DefSemaCount (MYSEMA, (SEMACOUNT)0); count = KS_GetSemaCount (MYSEMA); /* signal three times to bring count to 3 */ KS_DefSemaCount (MYSEMA, (SEMACOUNT)3); count = KS_GetSemaCount (MYSEMA); /* signal twice to bring count to 5 */ KS_DefSemaCount (MYSEMA, (SEMACOUNT)5); count = KS_GetSemaCount (MYSEMA);

See Also

KS_GetSemaCount, page 90

Chapter 3: Semaphore Services

June 21, 2002

83

KS_DefSemaName

KS_DefSemaName Define the name of a previously opened dynamic semaphore.

Synopsis Inputs

Description

KSRC KS_DefSemaName (SEMA sema, const char *pname)

sema

The handle of the semaphore being defined.

pname

A pointer to a null-terminated name string.

The KS_DefSemaName kernel service names or renames the dynamic semaphore specified in sema. The service uses the nullterminated string pointed to by pname for the semaphore’s new name. Static semaphores cannot be named or renamed under program control. Note: To use this service, you must enable the Dynamics attribute of the Semaphore class during system generation.

This service does not check for duplicate semaphore names.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the service completes successfully.

`

RC_STATIC_OBJECT if the semaphore being named is static.

`

RC_OBJECT_NOT_FOUND if the Dynamics attribute of the

Semaphore class is not enabled. `

RC_OBJECT_NOT_INUSE if the specified semaphore does not

correspond to an active dynamic semaphore.

Error

This service may generate the following fatal error code: FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.

84

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_DefSemaName

Example

In Example 3-3, the dynsema variable contains the handle of a previously opened semaphore. Assign the name NewSema to that dynamic semaphore so other users may reference it by name.

Example 3-3. Assign Semaphore Name #include "rtxcapi.h"

/* RTXC Kernel Service prototypes */

SEMA dynsema; if (KS_DefSemaName (dynsema, "NewSema") != RC_GOOD) { ... Naming operation failed. Deal with it here } ... naming operation was successful. Continue

See Also

KS_OpenSema, page 100 KS_GetSemaName, page 92 KS_LookupSema, page 98 KS_UseSema, page 120

Chapter 3: Semaphore Services

June 21, 2002

85

KS_DefSemaProp

KS_DefSemaProp Define the properties of a semaphore.

Synopsis Inputs

Description

void KS_DefSemaProp (SEMA sema, const SEMAPROP *psemaprop)

sema

The handle of the semaphore being defined.

psemaprop

A pointer to a semaphore properties structure.

The KS_DefSemaProp kernel service defines the properties of the semaphore specified in sema using the values contained in the SEMAPROP structure pointed to by psemaprop. Example 3-4 shows the organization of the SEMAPROP structure.

Example 3-4. Semaphore Properties Structure typedef struct { KATTR attributes; } SEMAPROP;

/* Waiting Order & signal type */

You may define the following semaphore attribute values:

Waiting Order

Indicates the order in which tasks wait to receive a signal on a semaphore. The default order is by task priority. Waiting Order can be changed to chronological ordering by ORing the ATTR_FIFO_ORDER constant into the attributes field.

Signal Type

Indicates which tasks in the waiting list should be notified of the signal. By default, the service signals only the first task in the waiter list. Signal Type can be changed to notify all tasks waiting on the semaphore by ORing the ATTR_MULTIPLE_WAITERS constant into the attributes field.

The default values for the Waiting Order and Signal Type attributes can be restored by ANDing the attributes field with ~ATTR_FIFO_ORDER or ~ATTR_MULTIPLE_WAITERS, respectively.

86

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_DefSemaProp

Output

This service does not return a value.

Error

This service may generate the following fatal error code: FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.

Example

In Example 3-5, the Current Task defines the properties of the dynamic semaphore specified in dynsema so that any tasks waiting for the event are ordered in descending order of task priority.

Example 3-5. Specify Semaphore Waiting Order #include "rtxcapi.h"

/* RTXC Kernel Service prototypes */

SEMA dynsema; SEMAPROP sprop; KSRC ksrc; /* get current properties of the semaphore */ KS_GetSemaProp (dynsema, &sprop); /* use priority waiters */ sprop.attributes &= ~ATTR_FIFO_ORDER; KS_DefSemaProp (dynsema, &sprop); /* define properties */ ... Continue

See Also

KS_GetSemaProp, page 94 INIT_SemaClassProp, page 96 KS_OpenSema, page 100

Chapter 3: Semaphore Services

June 21, 2002

87

KS_GetSemaClassProp

KS_GetSemaClassProp Get the Semaphore object class properties.

Synopsis Input

const KCLASSPROP * KS_GetSemaClassProp (int *pint)

pint

Description

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

The KS_GetSemaClassProp kernel service obtains a pointer to the KCLASSPROP structure which was used during system initialization by the INIT_SemaClassProp service to initialize the Semaphore object class properties. If the pint pointer contains a non-zero address, the current number of unused dynamic semaphores is stored in the indicated address. If pint contains a null pointer ((int *)0), the service ignores the parameter. Example 3-6 shows the organization of the KCLASSPROP structure.

Example 3-6. Class Properties Structure typedef struct { KATTR attributes; KOBJECT n_statics; KOBJECT n_dynamics; short objsize; short totalsize; ksize_t namelen const char *pstaticnames; } KCLASSPROP;

/* /* /* /* /*

number of static objects */ number of dynamic objects */ used for calculating offsets */ used to alloc object array RAM */ length of name string */

The attributes element of the Semaphore KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 3-1 on page 89.

88

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_GetSemaClassProp

Table 3-1. Semaphore Class Attributes and Masks

Output

Attribute

Mask

Static Names

ATTR_STATIC_NAMES

Dynamics

ATTR_DYNAMICS

Statistics

ATTR_STATISTICS

If successful, this service returns a pointer to a KCLASSPROP structure. If the Semaphore 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 semaphores in the variable pointed to by pint.

Example

In Example 3-7, the Current Task needs the information contained in the KCLASSPROP structure for the Semaphore object class.

Example 3-7. Read Semaphore Object Class Properties #include "rtxcapi.h"

/* RTXC Kernel Service prototypes */

KCLASSPROP *psemaclass; int free_dyn; /* Get the semaphore kernel object class properties */ if ((psemaclassprop = KS_GetSemaClassProp (&free_dyn)) == (const KCLASSPROP *)0) { putline ("Semaphore Class not initialized"); } else { ... /* semaphore object class properties are available for use */ /* "free_dyn" contains the number of available dynamic semas */ }

See Also

INIT_SemaClassProp, page 96

Chapter 3: Semaphore Services

June 21, 2002

89

KS_GetSemaCount

KS_GetSemaCount Get the current semaphore count.

Synopsis Input

SEMACOUNT KS_GetSemaCount (SEMA sema)

sema

Description

The handle of the semaphore being queried.

The KS_GetSemaCount kernel service obtains the count of the semaphore specified in sema. The state of the semaphore is determined by the value of the semaphore count. This service does not change the semaphore count. Warning: The count, and therefore the state, of the semaphore may actually change between the time the request is issued and the time the semaphore count is returned. An exception that alters the state of the semaphore may interrupt the system after the kernel service has completed but before control can be returned to the Current Task.

Output

Errors

This service returns a SEMACOUNT value indicating the semaphore state as follows: `

0 means the semaphore contains no unprocessed signals.

`

> 0 means the semaphore has signals that are unprocessed. The number of unprocessed signals is equal to the returned value.

`

< 0 means ignore the next SEMACOUNT signals.

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

FE_ILLEGAL_SEMA if the specified semaphore ID is not valid. FE_UNINITIALIZED_SEMA if the specified semaphore has not

yet been initialized.

90

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_GetSemaCount

Example

In Example 3-8, the Current Task wants to determine if the AIDONE semaphore received a signal without waiting for the next signal. If the semaphore has received a signal, the task performs some processing.

Example 3-8. Read Semaphore Count #include "rtxcapi.h" #include "ksema.h"

/* RTXC Kernel Service prototypes */ /* defines AIDONE */

SEMACOUNT count; if ((count = KS_GetSemaCount (AIDONE)) > (SEMACOUNT)0 ) { ... semaphore has been signaled, process something } else { ... no signals, do something else }

See Also

XX_SignalSema, page 102 KS_DefSemaCount, page 82

Chapter 3: Semaphore Services

June 21, 2002

91

KS_GetSemaName

KS_GetSemaName Get the name of a semaphore.

Synopsis Input

char * KS_GetSemaName (SEMA sema)

sema

Description

The handle of the semaphore being queried.

The KS_GetSemaName kernel service obtains a pointer to the nullterminated string containing the name of the semaphore specified in sema. The semaphore may be static or dynamic. Note: To use this service on static semaphores, you must enable the Static Names attribute of the Semaphore class during system generation.

Output

If the semaphore has a name, this service returns a pointer to the null-terminated name string. If the semaphore has no name, the service returns a null pointer ((char *)0).

Error

This service may generate the following fatal error code: FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.

Example

92

June 21, 2002

In Example 3-9 on page 93, the Current Task needs to report the name of the dynamic semaphore specified in dynsema.

RTXC Kernel Services Reference, Volume 2

KS_GetSemaName

Example 3-9. Read Semaphore Name #include #include "rtxcapi.h"

/* standard i/o */ /* RTXC Kernel Service prototypes */

static char buf[128]; SEMA dynsema; char *pname; if ((pname = KS_GetSemaName (dynsema)) == (char *)0 ) sprintf (buf, "Semaphore %d has no name\n", dynsema); else sprintf (buf, "Semaphore %d name is %s\n", dynsema, pname); putline (buf); /* send message to console */

See Also

KS_DefSemaName, page 84 KS_OpenSema, page 100

Chapter 3: Semaphore Services

June 21, 2002

93

KS_GetSemaProp

KS_GetSemaProp Get the properties of a semaphore.

Synopsis Inputs

Description

void KS_GetSemaProp (SEMA sema, SEMAPROP *psemaprop)

sema

The handle of the semaphore being queried.

psemaprop

A pointer to the Semaphore properties structure in which to store the semaphore’s properties.

The KS_GetSemaProp kernel service obtains all of the property values of the semaphore specified in sema in a single call. The service stores the property values in the SEMAPROP structure pointed to by psemaprop. The SEMAPROP structure has the following organization:

typedef struct_semaprop { KATTR attributes; } SEMAPROP;

/* Signal Type, Waiting Order */

Output

This service returns the semaphore’s properties in the structure pointed to by psemaprop.

Errors

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

FE_ILLEGAL_SEMA if the specified semaphore ID is not valid. FE_UNINITIALIZED_SEMA if the specified semaphore has not

yet been initialized.

Example

94

June 21, 2002

In Example 3-10 on page 95, the Current Task needs to ensure that the properties of the dynamic semaphore specified in dynsema are defined so that tasks waiting for the associated event are ordered in descending order of task priority. The task first reads the existing properties of the specified semaphore and then forces priority order waiting.

RTXC Kernel Services Reference, Volume 2

KS_GetSemaProp

Example 3-10. Read Semaphore Properties #include "rtxcapi.h"

/* RTXC Kernel Service prototypes */

SEMA dynsema; SEMAPROP sprop; KS_GetSemaProp (dynsema, &sprop); /* get properties */ if (sprop.attributes & ATTR_FIFO_ORDER) { /* use priority mode*/ sprop.attributes &= ~ATTR_FIFO_ORDER; /* define properties */ KS_DefSemaProp (dynsema, &sprop); } ... continue

See Also

KS_DefSemaProp, page 86

Chapter 3: Semaphore Services

June 21, 2002

95

INIT_SemaClassProp

INIT_SemaClassProp Initialize the Semaphore object class properties.

Synopsis Input

KSRC INIT_SemaClassProp (const KCLASSPROP *pclassprop)

pclassprop

Description

A pointer to a Semaphore object class properties structure.

During the RTXC Kernel initialization procedure, you must define the kernel objects needed by the RTXC Kernel to perform the application. The INIT_SemaClassProp kernel service allocates space for the Semaphore object class in system RAM. The amount of RAM to allocate, and all other properties of the class, are specified in the structure pointed to by pclassprop. Example 2-22 on page 62 shows the organization of the KCLASSPROP structure. The attributes element of the Semaphore KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 3-1 on page 89.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the service completes successfully.

`

RC_NO_RAM if the initialization fails because there is insufficient

system RAM available.

Example

96

June 21, 2002

During system initialization, the startup code must initialize the Semaphore object class before using any kernel service for that class. The system generation process produces a KCLASSPROP structure containing the information about the semaphore object class necessary for its initialization. Example 3-11 references that structure externally to the code module.

RTXC Kernel Services Reference, Volume 2

INIT_SemaClassProp

Example 3-11. Initialize Semaphore Object Class #include "rtxcapi.h"

/* RTXC Kernel Service prototypes */

static char buf[128]; /* created by system generation*/ extern const SYSPROP sysprop; extern const KCLASSPROP semaclassprop; KSRC userinit (void) { KSRC ksrc; /* initialize the kernel workspace, allocate RAM for required classes, etc. */ if ((ksrc = INIT_SysProp (&sysprop)) != RC_GOOD) { putline ("Kernel initialization failure\n"); return (ksrc); /* end initialization process */ } /* kernel is initialized */ /* Need to initialize the necessary kernel object classes */ /* Initialize the Semaphore kernel object class */ if ((ksrc = INIT_SemaClassProp (&semaclassprop)) != RC_GOOD) { putline ("No RAM for Semaphore init"); return (ksrc); /* end initialization process */ } ... Continue with system initialization }

See Also

INIT_SysProp, page 310 KS_GetSemaClassProp, page 88

Chapter 3: Semaphore Services

June 21, 2002

97

KS_LookupSema

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

Synopsis Inputs

Description

KSRC KS_LookupSema (const char *pname, SEMA *psema)

pname

A pointer to a null-terminated name string.

psema

A pointer to a SEMA variable for storing the semaphore handle, if found.

The KS_LookupSema kernel service obtains the handle of the static or dynamic semaphore whose name matches the null-terminated string pointed to by pname. The lookup process terminates when it finds a match between the specified string and a static or dynamic semaphore name or when it finds no match. The service stores the matching semaphore’s handle in the variable pointed to by psema. The service searches dynamic names, if any, first. Note: To use this service on static semaphores, you must enable the Static Names attribute of the Semaphore class during system generation.

This service has no effect on the registration of the specified semaphore by the Current Task. The time required to perform this operation varies with the number of semaphore names in use.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the search succeeds. The service stores the matching

semaphore’s handle in the variable pointed to by psema. `

RC_OBJECT_NOT_FOUND if the service finds no matching

semaphore name.

98

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_LookupSema

Example

In Example 3-12, the Current Task needs to use the Chnl2Sema dynamic semaphore. If the semaphore is found, it can then be used by the Current Task.

Example 3-12. Look Up Semaphore by Name #include "rtxcapi.h"

/* RTXC Kernel Service prototypes */

SEMA dynsema; /* lookup the semaphore name to get its handle */ if (KS_LookupSema ("Chnl2Sema ", &dynsema) != RC_GOOD) { ... Semaphore name not found. Deal with it } else /* got the handle for Chnl2Sema */ { ... Do something with the semaphore now }

See Also

KS_DefSemaName, page 84 KS_OpenSema, page 100

Chapter 3: Semaphore Services

June 21, 2002

99

KS_OpenSema

KS_OpenSema Allocate and name a dynamic semaphore.

Synopsis Inputs

Description

KSRC KS_OpenSema (const char *pname, SEMA *psema)

pname

A pointer to a null-terminated name string.

psema

A pointer to a SEMA variable in which to store the allocated semaphore’s handle.

The KS_OpenSema kernel services allocates, names, and obtains the handle of a dynamic semaphore. The service stores the handle of the new dynamic semaphore in the variable pointed to by psema. If there is no existing semaphore, static or dynamic, with a name matching the null-terminated string pointed to by pname, the service allocates a dynamic semaphore and applies the name referenced by pname to the new semaphore. The kernel stores only the address of the name internally, which means that the same array cannot be used to build multiple dynamic semaphore names. If the service finds an existing semaphore with a matching name, it does not open a new semaphore and returns a value indicating an unsuccessful operation. If pname is a null pointer ((char *)0), the service does not assign a name to the dynamic semaphore. However, if pname points to a null string, the name is legal as long as no other semaphore is already using a null string as its name. Note: To use this service, you must enable the Dynamics attribute of the Semaphore class during system generation.

If the pointer to the semaphore name is not null, the time required to perform this operation varies with the number of semaphore names in use. If the pointer to the semaphore name is null, no search of semaphore names takes place and the time to perform the

100

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_OpenSema

service is fixed. You can define the semaphore name at a later time with a call to the KS_DefSemaName service.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the service completes successfully. The service stores

the handle of the new dynamic semaphore in the variable pointed to by psema. `

RC_OBJECT_ALREADY_EXISTS if the name search finds another

semaphore whose name matches the specified string. `

RC_NO_OBJECT_AVAILABLE if the name search finds no match

but all dynamic semaphores are in use.

Example

Example 3-13 on page 101 allocates a dynamic semaphore and names it MuxChnl2Sema. If the name is in use, the example outputs a message on the console using the putline routine.

Example 3-13. Allocate Dynamic Semaphore #include "rtxcapi.h"

/* RTXC Kernel Service prototypes */

KSRC ksrc; SEMA dynsema; if ((ksrc = KS_OpenSema ("MuxChnl2Sema", &dynsema)) != RC_GOOD) { if (ksrc == RC_OBJECT_ALREADY_EXISTS) putline ("MuxChnl2Sema semaphore name in use"); else if (ksrc == RC_NO_OBJECT_AVAILABLE) putline ("No dynamic Semaphores available"); else putline ("Semaphore class is not defined"); } else { ... semaphore was opened correctly. Okay to use it now }

See Also

KS_CloseSema, page 80 KS_LookupSema, page 98 KS_UseSema, page 120

Chapter 3: Semaphore Services

June 21, 2002

101

XX_SignalSema

XX_SignalSema Signal a semaphore.

Zones

IS_SignalSema TS_SignalSema KS_SignalSema

Synopsis Input

void XX_SignalSema (SEMA sema)

sema

Description

The handle of the semaphore to signal.

If the semaphore specified in sema has one or more waiters and a count value of 0, the count value of sema remains 0 and the waiters are processed according to sema’s signal type. For each semaphore signaled, if its Signal Type attribute is in the default state, the service removes the SEMAPHORE_WAIT state of the first waiting task only. If Signal Type is set to ATTR_MULTIPLE_WAITERS, the service removes the SEMAPHORE_WAIT state for all tasks in the waiting list for the event. If a waiting task becomes runnable as a result of the removal of its SEMAPHORE_WAIT state, the service places the task in the Ready List at a position dependent on its current priority. If the semaphore has no waiters or has a non-zero count value, the XX_SignalSema kernel service simply increments the count value of the semaphore specified in sema and returns control to the calling task. The count value for sema never exceeds the maximum value for the SEMACOUNT type.

Output

This service does not return a value.

Errors

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

FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.

`

FE_UNINITIALIZED_SEMA if the specified semaphore has not

yet been initialized.

102

June 21, 2002

RTXC Kernel Services Reference, Volume 2

XX_SignalSema

Example

Example 3-14 looks at the current size of the CHARQ static queue and signals the XOFF semaphore if the queue contains more than 20 entries. It signals the XON semaphore if the current size of the queue is less than four entries.

Example 3-14. Signal Semaphore from Zone 3 #include "rtxcapi.h" #include "kqueue.h" #include "ksema.h"

/* RTXC Kernel Service prototypes */ /* defines CHARQ */ /* defines XOFF and XON */

static QUEUEPROP qprop; /* get CHARQ properties */ KS_GetQueueProp (CHARQ, &qprop); if (qprop.current_size > 20) KS_SignalSema (XOFF); if (qprop.current_size < 4) KS_SignalSema (XON); ... continue

See Also

XX_SignalSemaM, page 104

Chapter 3: Semaphore Services

June 21, 2002

103

XX_SignalSemaM

XX_SignalSemaM Signal multiple semaphores.

Zones

IS_SignalSemaM TS_SignalSemaM KS_SignalSemaM

Synopsis Input

void XX_SignalSemaM (const SEMA *psemalist)

psemalist

Description

A pointer to a null-terminated semaphore list.

The XX_SignalSemaM kernel service performs the same service as the XX_SignalSema service, except that it uses a list of semaphores associated with multiple events. The psemalist argument contains the address of the null-terminated semaphore list. For each semaphore handle in the semaphore list, XX_SignalSemaM signals the associated semaphore. For each semaphore signaled, if its Signal Type attribute is in the default state, the service removes the SEMAPHORE_WAIT state of the first waiting task only. If Signal Type is set to ATTR_MULTIPLE_WAITERS, the service removes the SEMAPHORE_WAIT state for all tasks in the waiting list for the event. If a waiting task becomes runnable as a result of the removal of its SEMAPHORE_WAIT state, the service places the task in the Ready List at a position dependent on its current priority. The count value for each semaphore referenced by psemalist never exceeds the maximum value for the SEMACOUNT type.

Output

This service does not return a value.

Errors

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

FE_ILLEGAL_SEMA if the specified semaphore ID is not valid. FE_UNINITIALIZED_SEMA if the specified semaphore has not

yet been initialized.

104

June 21, 2002

RTXC Kernel Services Reference, Volume 2

XX_SignalSemaM

Example

In Example 3-15, the Current Task signals the SWITCH1, SWITCH2, and CHNLDONE static semaphores to indicate completion of the use of a multiplexor channel.

Example 3-15. Signal List of Semaphores from Zone 3 #include "rtxcapi.h" #include "ksema.h"

/* RTXC Kernel Service prototypes */ /*defines SWITCH1, SWITCH2, & CHNLDONE */

const SEMA semalist[] = { SWITCH1, SWITCH2, CHNLDONE, (SEMA)0 }

/* null terminator */

... use multiplexor channel KS_SignalSemaM (semalist);/* signal multiple semaphores */ ... continue processing

See Also

XX_SignalSema, page 102 KS_TestSemaM, page 110

Chapter 3: Semaphore Services

June 21, 2002

105

KS_TestSema

KS_TestSema Test a semaphore.

Synopsis Input

KSRC KS_TestSema (SEMA sema)

sema

The handle of the semaphore to test.

Description

The KS_TestSema kernel service polls the status of the semaphore specified in sema and returns a value indicating whether it detected a signal on the specified semaphore. If the semaphore is in a DONE state, KS_TestSema decrements the count by one. It does not change the semaphore count if the count is less than or equal to zero.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the service detects a signal (semaphore count was >

0). `

RC_NO_SIGNAL if the service detects a semaphore count less

than or equal to zero (0).

Errors

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

FE_ILLEGAL_SEMA if the specified semaphore ID is not valid. FE_UNINITIALIZED_SEMA if the specified semaphore has not

yet been initialized.

Example

106

June 21, 2002

In Example 3-16 on page 107, the Current Task needs to poll the KEYPAD semaphore to determine if it has received a signal. If not, the task continues performing some other processing. If a signal is detected, some special event processing is required before proceeding.

RTXC Kernel Services Reference, Volume 2

KS_TestSema

Example 3-16. Test Semaphore #include "rtxcapi.h" #include "ksema.h"

/* RTXC Kernel Service prototypes */ /* defines KEYPAD */

/* test for KEYPAD hit event */ for (;;) { while (KS_TestSema (KEYPAD) == RC_NO_SIGNAL) { ... do some other operations until key is pressed } ... signal occurred, read the keypad and process the input character (s) }

See Also

XX_SignalSema, page 102 XX_SignalSemaM, page 104

Chapter 3: Semaphore Services

June 21, 2002

107

KS_TestSemaT

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

Synopsis Inputs

Description

KSRC KS_TestSemaT (SEMA sema, COUNTER counter, TICKS ticks)

sema

The handle of the semaphore to test.

counter

The counter associated with the tick interval defined by ticks.

ticks

The number of ticks on the specified counter to wait for the signal.

The KS_TestSemaT kernel service is similar to the KS_TestSemaW kernel service. It tests the semaphore specified in sema for having received a signal and either blocks the Current Task or immediately returns to it depending on the value of the semaphore count. While the semaphore count remains less than or equal to zero (0), the service blocks the Current Task and starts an internal alarm for the interval specified in ticks on the specified counter. The task continues to be blocked until one of two events occurs: `

A signal to the semaphore specified by sema occurs when sema’s count value is equal to zero (0), or

`

The specified number of ticks elapses.

If the semaphore count is greater than zero, it contains a value equal to the number of unprocessed signals the semaphore has received. In such a case, the test of the semaphore causes the semaphore’s count to decrement by one and the service returns to the calling task immediately.

Output

This service returns a KSRC value as follows: `

108

June 21, 2002

RC_GOOD if a semaphore signal has occurred.

RTXC Kernel Services Reference, Volume 2

KS_TestSemaT

`

Errors

RC_TICKOUT if the specified number of ticks elapses before the semaphore receives a signal.

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

FE_ILLEGAL_SEMA if the specified semaphore ID is not valid. FE_UNINITIALIZED_SEMA if the specified semaphore has not

yet been initialized. `

FE_ILLEGAL_COUNTER if the specified counter ID is not valid.

`

FE_UNINITIALIZED_COUNTER if the specified counter has not

yet been initialized.

Example

In Example 3-17, the Current Task needs to wait for a keypad character to be pressed, but it can’t wait for more than 100 msec using static counter MSCOUNTER because it has other jobs to do. It uses the KS_TestSemaT kernel service to perform a tick-limited wait on the KEYPAD event.

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

"rtxcapi.h" "ksema.h" "kcounter.h" "kproject.h"

/* /* /* /*

RTXC Kernel Service prototypes */ defines KEYPAD */ defines MSCOUNTER */ defines CLKTICK */

/* wait 100 msec for KEYPAD to be hit */ if (KS_TestSemaT (KEYPAD, MSCOUNTER, (TICKS)100/CLKTICK) == RC_GOOD) { ... keypad was hit, process the event } else { ... no keypad event and timeout happened }

See Also

XX_SignalSema, page 102 XX_SignalSemaM, page 104 KS_TestSema, page 106 KS_TestSemaW, page 118

Chapter 3: Semaphore Services

June 21, 2002

109

KS_TestSemaM

KS_TestSemaM Test a list of semaphores.

Synopsis Input

SEMA KS_TestSemaM (const SEMA *psemalist)

psemalist

Description

A pointer to a null-terminated semaphore list.

The KS_TestSemaM kernel service performs the same service as the KS_TestSema service, except that it uses a list of semaphores. The psemalist argument contains the address of a null-terminated semaphore list. The service first tests each semaphore in the list in succession. The first semaphore found that is in a DONE state ends the service and its handle is immediately reported to the requesting task. If no semaphore is found to be in a DONE state, a value of zero is reported to the requesting task to indicate no signals were present. Regardless of the states of the semaphores in the list, the service returns immediately to the requesting task. Note: It is illegal for a semaphore to occur more than once in the semaphore list.

Output

This service returns the handle of the semaphore receiving the event signal. If none of the semaphores in semaphore list contained an unprocessed signal, the service returns a value of zero.

Errors

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

FE_ILLEGAL_SEMA if the specified semaphore ID is not valid. FE_UNINITIALIZED_SEMA if the specified semaphore has not

yet been initialized.

110

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_TestSemaM

Example

In Example 3-18, the Current Task needs to know when any of three events occur. The SWITCH1 and SWITCH2 events are associated with switch closures, while the TIMERA event is associated with a timer. When any one event occurs, the task performs a code segment specific to that event.

Example 3-18. Test List of Semaphores #include "rtxcapi.h" #include "ksema.h"

/* RTXC Kernel Service prototypes */ /* defines SWITCH1, SWITCH2, TIMERA */

SEMA cause; const SEMA semalist[] = { SWITCH1, SWITCH2, TIMERA, (SEMA)0 /* null terminated list */ }; for (;;) { /* poll for any of 3 events */ cause = KS_TestSemaM (semalist); switch (cause) { case SWITCH1: ... process SWITCH1 event... break; case SWITCH2: ... process SWITCH2 event... break; case TIMERA: ... process TIMERA event... break; } /* end of switch */ } /* end of forever */

See Also

KS_TestSema, page 106 KS_TestSemaMW, page 115 XX_SignalSema, page 102 XX_SignalSemaM, page 104

Chapter 3: Semaphore Services

June 21, 2002

111

KS_TestSemaMT

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

Synopsis Inputs

SEMA KS_TestSemaMT (const SEMA *psemalist, COUNTER counter, TICKS ticks)

psemalist counter

A pointer to a null-terminated semaphore list. The counter associated with the tick interval defined by

ticks. ticks

Description

The number of ticks on counter to wait for the signal.

The KS_TestSemaMT kernel service performs the same function as the KS_TestSemaMW directive, except it uses a defined number of ticks on a specified counter to limit the duration of the waiting period. The KS_TestSemaMT service operates as a logical OR; the occurrence of any event associated with any one of the semaphores in the list causes resumption of the requesting task. The service puts each semaphore in the list pointed to by psemalist into a WAITING state if it is in a PENDING state, or leaves it in the WAITING state if it is already WAITING. If the service finds that no semaphore in the list contains a signal, the service blocks the calling task, removes it from the Ready List, and starts an internal alarm on the specified counter for the duration interval specified in ticks. The task continues to be blocked until one of two situations occurs: `

A signal to any one of the semaphores in the list pointed to by psemalist occurs, or

`

The specified number of ticks elapses.

Note: It is illegal for a semaphore to occur more than once in the semaphore list.

112

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_TestSemaMT

Output

If one of the semaphores is signaled before the specified number of ticks elapses, this service returns the handle of the semaphore associated with the triggering event. The service returns zero (0) if the specified number of ticks elapses. Note: If the service detects signals on multiple semaphores, it preserves the signaling order only for the first event. For example, a call to KS_TestSemaMT tests the A, B, and C semaphores and finds no signals. The service blocks the requesting task and starts a internal alarm. Now, suppose the C semaphore receives a signal before the specified number of ticks in the alarm elapses, but before the task can actually resume operation, the B and A semaphores receive signals. When the task actually regains CPU control, the KS_TestSemaMT service returns the handle of the C semaphore to identify it as having received the first signal. If the task makes a subsequent call to KS_TestSemaMT, the task is not blocked and the service returns the handle of the A semaphore. Another call to KS_TestSemaMT immediately returns the handle of the B semaphore.

Errors

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

FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.

`

FE_UNINITIALIZED_SEMA if the specified semaphore has not

yet been initialized. `

FE_ILLEGAL_COUNTER if the specified counter ID is not valid.

`

FE_UNINITIALIZED_COUNTER if the specified counter has not

yet been initialized.

Example

In Example 3-19 on page 114, the Current Task needs to know when either of two events occur. The SW1CLOSE and SW2CLOSE events are associated with switch closures, and either one, but only one, is expected to occur within two seconds after the occurrence of another event associated with the KEYSW semaphore. When either event happens, the task performs a code segment specific to that event.

Chapter 3: Semaphore Services

June 21, 2002

113

KS_TestSemaMT

However, if neither switch closes within the expected time of two seconds on counter[0], the task reads the lack of closure as a system malfunction and takes special action. Example 3-19. Test List of Semaphores—Wait Number of Ticks for Signal #include "rtxcapi.h" #include "ksema.h" #include "kproject.h"

/* RTXC Kernel Service prototypes */ /* defines SW1CLOSE, SW2CLOSE, KEYSW */ /* defines CLKTICK */

const SEMA closelist[] = { SW1CLOSE, SW2CLOSE, (SEMA)0 /* null terminated list */ }; SEMA cause; TICKS tmout = (TICKS)2000/CLKTICK; /* 2 sec timeout period */ /* counter[0] is the system clock */ for (;;) /* do this forever */ { /* wait for the key event to occur */ KS_TestSemaW (KEYSW); /* then wait up to 2 sec for either sw1 or sw2 to close */ if ((cause = KS_TestSemaMT (closelist,(COUNTER)0,tmout))!=(SEMA)0 ) { switch (cause) /* see what semaphore was signaled */ { case SW1CLOSE: ... process sw1 event... break; case SW2CLOSE: ... process sw2 event... break; } } /* end of switch */ else { ... timeout occurred. Failure requires special action } } /* end of forever */

See Also

114

June 21, 2002

KS_TestSema, page 106 KS_TestSemaMW, page 115 XX_SignalSema, page 102 XX_SignalSemaM, page 104

RTXC Kernel Services Reference, Volume 2

KS_TestSemaMW

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

Synopsis Input Description

SEMA KS_TestSemaMW (const SEMA *psemalist)

psemalist

A pointer to a null-terminated semaphore list.

The KS_TestSemaMW kernel service performs the same function as the KS_TestSemaW service, except that it uses a list of semaphores associated with the various events. The psemalist argument points to a null-terminated semaphore list. The service first tests each semaphore in the list in succession. If any semaphore referenced by psemalist is in a DONE state, the service returns the handle of the first semaphore in the list that was in a DONE state and the requesting task continues. If the service finds no DONE semaphore in the list, it blocks the requesting task and does not let it resume until one of the semaphores in the list receives a signal. The KS_TestSemaMW service operates as a logical OR; the occurrence of an event associated with any one of the semaphores in the list causes the requesting task to resume. Note: It is illegal for a semaphore to occur more than once in the semaphore list.

Output

This service returns the handle of the semaphore receiving the event signal. Note: If the service detects multiple signals on multiple semaphores, it preserves the signaling order only for the first event. For example, a call to KS_TestSemaMW tests the A, B, and C semaphores and finds no signals. The service blocks the requesting task and waits for a signal. Now, assume the C semaphore receives a signal, but before the

Chapter 3: Semaphore Services

June 21, 2002

115

KS_TestSemaMW

task can actually resume operation, the B and A semaphores receive signals. When the task actually regains CPU control, the KS_TestSemaMW service returns the handle of the C semaphore to identify it as having received the first signal. If the task makes a subsequent call to KS_TestSemaMW, the task is not blocked and the service returns the handle of the A semaphore. Another call to KS_TestSemaMW immediately returns the handle of the B semaphore.

Errors

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

FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.

`

FE_UNINITIALIZED_SEMA if the specified semaphore has not

yet been initialized.

Example

116

June 21, 2002

In Example 3-20 on page 117, the Current Task needs to know when any of three events occur. The SWITCH1 and SWITCH2 events are associated with switch closures while TIMERA is associated with a timer. When any one event occurs, the task performs a code segment specific to that event.

RTXC Kernel Services Reference, Volume 2

KS_TestSemaMW

Example 3-20. Test List of Semaphores—Wait for Signal #include "rtxcapi.h" #include "ksema.h"

/* RTXC Kernel Service prototypes */ /* defines SWITCH1, SWITCH2, TIMERA */

SEMA cause; const SEMA semalist[] = { SWITCH1, SWITCH2, TIMERA, (SEMA)0 /* null terminated list */ }; for (;;) { /* test the semaphores and wait for any of 3 events */ cause = KS_TestSemaMW (semalist); switch (cause) { case SWITCH1: ... process SWITCH1 event... break; case SWITCH2: ... process SWITCH2 event... break; case TIMERA: ... process TIMERA event... break; }

} /* end of switch */ /* end of forever */

See Also

KS_TestSema, page 106 KS_TestSemaM, page 110 KS_TestSemaMT, page 112 XX_SignalSema, page 102 XX_SignalSemaM, page 104

Chapter 3: Semaphore Services

June 21, 2002

117

KS_TestSemaW

KS_TestSemaW Test a semaphore and wait if the semaphore is not DONE.

Synopsis Input

void KS_TestSemaW (SEMA sema)

sema

Description

The handle of the semaphore to test.

The KS_TestSemaW kernel service tests the semaphore specified in sema for having received a signal and either blocks the Current Task or immediately returns to it depending on the value of the semaphore count. If the semaphore count is –n, the service blocks the calling task for n occurrences of the associated event. On the n + 1 occurrence of that event the service unblocks the calling task. If the semaphore count is greater than zero, it contains a value equal to the number of unprocessed signals. In such a case, the test of the semaphore causes the count to decrement by one and the service returns to the calling task immediately.

Output

This service does not return a value.

Errors

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

FE_ILLEGAL_SEMA if the specified semaphore ID is not valid. FE_UNINITIALIZED_SEMA if the specified semaphore has not

yet been initialized.

Example

118

June 21, 2002

In Example 3-21 on page 119, the Current Task needs to synchronize its operation with the occurrence of a keypad character being pressed. The event is associated with the KEYPAD semaphore.

RTXC Kernel Services Reference, Volume 2

KS_TestSemaW

Example 3-21. Test Semaphore—Wait for Signal #include "rtxcapi.h" #include "ksema.h"

/* RTXC Kernel Service prototypes */ /* defines KEYPAD */

KS_TestSemaW (KEYPAD); /* test semaphore and wait if no */ /* KEYPAD hit signal received */ ... signal received

See Also

XX_SignalSema, page 102 XX_SignalSemaM, page 104 KS_TestSemaM, page 110 KS_TestSemaMT, page 112 KS_TestSemaT, page 108

Chapter 3: Semaphore Services

June 21, 2002

119

KS_UseSema

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

Synopsis Inputs

Description

KSRC KS_UseSema (const char *pname, SEMA *psema)

pname

A pointer to a null-terminated name string.

psema

A pointer to a SEMA variable for storing the semaphore handle, if found.

The KS_UseSema kernel service acquires the handle of a dynamic semaphore by looking up the null-terminated string pointed to by pname in the list of semaphore names. If there is a match, the service registers the semaphore for future use by the Current Task and stores the matching semaphore’s handle in the variable pointed to by psema. This procedure allows the Current Task to reference the dynamic semaphore successfully in subsequent kernel service calls. Note: To use this service, you must enable the Dynamics attribute of the Semaphore class during system generation.

The time required to perform this operation varies with the number of semaphore names in use.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the search and registration is successful. The service

stores the matching semaphore’s handle in the variable pointed to by psema. `

RC_STATIC_OBJECT if the specified name belongs to a static

semaphore. `

RC_OBJECT_NOT_FOUND if the service finds no matching

semaphore name.

Example

120

June 21, 2002

Example 3-22 on page 121 locates a dynamic semaphore named DynMuxSema3 and obtains its handle for subsequent use.

RTXC Kernel Services Reference, Volume 2

KS_UseSema

Example 3-22. Read Semaphore Handle and Register It #include "rtxcapi.h"

/* RTXC Kernel Service prototypes */

KSRC ksrc; SEMA dynsema; if ((ksrc = KS_UseSema ("DynMuxSema3", &dynsema)) != RC_GOOD) { if (ksrc == RC_STATIC_OBJECT) putline ("DynMuxSema3 is a static semaphore"); else putline ("Semaphore DynMuxSema3 not found"); } else { ... semaphore was found and its handle is in dynsema. Okay to use it now }

See Also

KS_DefSemaProp, page 86 KS_DefSemaName, page 84 KS_OpenSema, page 100

Chapter 3: Semaphore Services

June 21, 2002

121

KS_UseSema

122

June 21, 2002

RTXC Kernel Services Reference, Volume 2

CHAPTER

4

Queue Services

In This Chapter We describe the Queue kernel services in detail. The Queue services provide a method of passing multiple-byte packets of information between tasks with automatic task synchronization of queue-full and queue-empty conditions. 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

Chapter 4: Queue Services

June 21, 2002

123

KS_CloseQueue

KS_CloseQueue End the use of a dynamic queue.

Synopsis Input

KSRC KS_CloseQueue (QUEUE queue)

queue

Description

The handle of the queue to close.

The KS_CloseQueue kernel service ends the Current Task’s use of the specified dynamic queue. When closing the queue, the service detaches the caller’s use of it. If the caller is the last user of the queue, the service releases the queue to the free pool of dynamic queues for reuse. If there is at least one other task still using the queue, the service does not release the queue to the free pool but the service completes successfully. Be careful when closing a queue on which multiple tasks may be waiting. Closing the queue may cause waiters to be lost. However, you can avoid this problem if each task that uses the queue makes a KS_UseQueue call before it begins using the queue and then makes a KS_CloseQueue call when it is done using the queue. Note: To use this service, you must enable the Dynamics attribute of the Queue class during system generation.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the service is successful.

`

RC_STATIC_OBJECT if the specified queue is not dynamic.

`

RC_OBJECT_NOT_INUSE if the specified queue does not

correspond to an active dynamic queue. `

124

June 21, 2002

RC_OBJECT_INUSE if the Current Task’s use of the specified queue is closed but the queue remains open for use by other tasks.

RTXC Kernel Services Reference, Volume 2

KS_CloseQueue

Note: RC_OBJECT_INUSE does not necessarily indicate an error condition. The calling task must interpret its meaning.

Error

This service may generate the following fatal error code: FE_ILLEGAL_QUEUE if the specified queue ID is not valid.

Example

In Example 4-1, the Current Task waits for a signal from another task indicating that it is time to close a dynamic queue. The handle of the dynamic queue is specified in dynqueue. When the signal is received, the Current Task closes the associated queue.

Example 4-1. Close Queue #include "rtxcapi.h"

/* RTXC Kernel Service prototypes */

QUEUE dynqueue; SEMA dynsema;

/* handle of queue to be closed */

KS_TestSemaW (dynsema);

/* wait for signal */

KS_CloseQueue (dynqueue);

/* then close the queue */

See Also

KS_OpenQueue, page 152 KS_UseQueue, page 162

Chapter 4: Queue Services

June 21, 2002

125

KS_DefQueueName

KS_DefQueueName Define the name of a previously opened dynamic queue.

Synopsis Inputs

Description

KSRC KS_DefQueueName (QUEUE queue, const char *pname)

queue

The handle of the queue being defined.

pname

A pointer to a null-terminated name string.

The KS_DefQueueName kernel service names or renames the specified dynamic queue. The service uses the null-terminated string pointed to by pname for the queue’s new name. Static queues cannot be named or renamed under program control. Note: To use this service, you must enable the Dynamics attribute of the Queue class during system generation.

This service does not check for duplicate queue names.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the service completes successfully.

`

RC_STATIC_OBJECT if the queue being named is static.

`

RC_OBJECT_NOT_FOUND if the Dynamics attribute of the Queue

class is not enabled. `

RC_OBJECT_NOT_INUSE if the specified queue does not

correspond to an active dynamic queue.

Error

This service may generate the following fatal error code: FE_ILLEGAL_QUEUE if the specified queue ID is not valid.

126

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_DefQueueName

Example

In Example 4-2, the dynqueue variable contains the handle of a previously opened queue. Assign the name NewQueue to that queue so other users may reference it by name.

Example 4-2. Assign Queue Name #include "rtxcapi.h"

/* RTXC Kernel Service prototypes */

QUEUE dynqueue; if (KS_DefQueueName (dynqueue, "NewQueue") != RC_GOOD) { ... Error in naming the queue. Deal with it here } ... naming operation was successful. Continue

See Also

KS_OpenQueue, page 152 KS_GetQueueName, page 142 KS_LookupQueue, page 150 KS_UseQueue, page 162

Chapter 4: Queue Services

June 21, 2002

127

KS_DefQueueProp

KS_DefQueueProp Define the properties of a queue.

Synopsis Inputs

void KS_DefQueueProp (QUEUE queue, const QUEUEPROP *pqueueprop)

queue

The handle of the queue being defined.

pqueueprop A pointer to a Queue properties structure.

Description

The KS_DefQueueProp kernel service defines the properties of the specified queue using the values contained in the QUEUEPROP structure pointed to by pqueueprop. Example 4-3 shows the organization of the QUEUEPROP structure.

Example 4-3. Queue Properties Structure typedef struct { KATTR attributes; char *base; QWIDTH width; KCOUNT depth; KCOUNT current_size; } QUEUEPROP;

/* /* /* /* /*

Waiting Order */ Address of queue body */ Width of an entry (bytes) */ Maximum # of entries */ Current # of entries in the queue */

You may define the following queue attribute value:

Waiting Order

Indicates the ordering of tasks waiting for access to the queue. The default order is by priority. Waiting Order can be changed to chronological ordering by ORing the ATTR_FIFO_ORDER constant into the attributes field. The default value for the Waiting Order attribute can be restored by ANDing the attributes field with ~ATTR_FIFO_ORDER.

Output

128

June 21, 2002

This service does not return a value.

RTXC Kernel Services Reference, Volume 2

KS_DefQueueProp

Errors

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

FE_ILLEGAL_QUEUE if the specified queue ID is not valid. FE_UNINITIALIZED_QUEUE if the specified queue has not yet

been initialized.

Example

`

FE_NULL_QUEUEBASE if the specified queue base address is null.

`

FE_ZERO_QUEUEWIDTH if the specified queue width is zero.

`

FE_ZERO_QUEUEDEPTH if the specified queue depth is zero.

During system initialization, the startup code must create and initialize the Queue kernel object class and then define all of the static queues to the system before the first use of queues by any task. Example 4-4 illustrates this process.

Example 4-4. Define Queue Object Class Properties #include "rtxcapi.h"

/* RTXC Kernel Service prototypes */

extern const KCLASSPROP queueclassprop; extern const QUEUEPROP queueprop[]; static char buf[128]; int objnum; if ((ksrc = INIT_QueueClassProp (&queueclassprop)) != RC_GOOD) { putline ("Queue class initialization failed"); return (ksrc); } /* if class inits successfully, define the queues to the system */ for (objnum = 1; objnum 20) KS_SignalSema (XOFF); if (qprop.current_size < 4) KS_SignalSema (XON); ... continue

See Also

KS_DefQueueProp, page 128

Chapter 4: Queue Services

June 21, 2002

145

KS_GetQueueSema

KS_GetQueueSema Get the semaphore handle associated with a queue event.

Synopsis Inputs

Description

SEMA KS_GetQueueSema (QUEUE queue, QEVENT event)

queue

The handle of the queue being queried.

event

A queue event value.

The KS_GetQueueSema kernel service obtains the handle of the semaphore associated with the queue event for the specified static or dynamic queue. The two possible queue events are Queue_Not_Empty (QNE) and Queue_Not_Full (QNF) and the value of event must be either QNE or QNF. You must have previously associated the semaphore and the queue event through a call to KS_DefQueueSema. Note: To use this service, you must enable the Semaphores attribute of the Queue class during system generation.

Output

If the queue event and semaphore association exists, this service returns the handle of the semaphore as a SEMA type value. If there is no such association for the queue event, the service returns a SEMA value of zero (0).

Errors

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

FE_ILLEGAL_QUEUE if the specified queue ID is not valid.

`

FE_UNINITIALIZED_QUEUE if the specified queue has not yet

been initialized. `

146

June 21, 2002

FE_INVALID_QEVENT if the specified queue event value is not either QNF or QNE.

RTXC Kernel Services Reference, Volume 2

KS_GetQueueSema

Example

In Example 4-12, the Current Task needs to know the handle of the Queue_Not_Empty semaphore associated with the MAINQ static queue. If the return from KS_GetQueueSema indicates there is not a QNE semaphore associated with MAINQ, the task defines MAINQNESEMA, adds it to semalist, and waits for the indicated events.

Example 4-12. Read Queue Semaphore #include "rtxcapi.h" #include "ksema.h" #include "kqueue.h" SEMA semalist[] = { (SEMA)0; (SEMA)0; }

/* RTXC Kernel Service prototypes */ /* defines MAINQNESEMAQ */ /* defines MAINQ */

/* QNE, to be filled in below */ /* null terminator */

SEMA qnesema, cause; if ((qnesema = KS_GetQueueSema (MAINQ, QNE)) == (SEMA)0) { /* no QNE semaphore defined for queue MAINQ */ KS_DefQueueSema (MAINQ, MAINQNESEMA, QNE); qnesema = MAINQNESEMA; } /* there is now a QNE semaphore defined for */ /* queue MAINQ */ /* store it in semalist */ semalist[1] = qnesema; /* and wait for either event to occur */ cause = KS_TestSemaMW (semalist); /* wait for the event */ switch (cause) { ... process the event according to the case of cause }

See Also

KS_DefQueueSema, page 130

Chapter 4: Queue Services

June 21, 2002

147

INIT_QueueClassProp

INIT_QueueClassProp Initialize the Queue object class properties.

Synopsis Input

KSRC INIT_QueueClassProp (const KCLASSPROP *pclassprop)

pclassprop

Description

A pointer to a Queue object class properties structure.

During the RTXC Kernel initialization procedure, you must define the kernel objects needed by the RTXC Kernel to perform the application. The INIT_QueueClassProp kernel service allocates space for the Queue object class in system RAM. The amount of RAM to allocate, and all other properties of the class, are specified in the KCLASSPROP structure pointed to by pclassprop. Example 2-22 on page 62 shows the organization of the KCLASSPROP structure. The attributes element of the Queue KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 4-1 on page 135.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the service completes successfully.

`

RC_NO_RAM if the initialization fails because there is insufficient

system RAM available.

Example

148

June 21, 2002

During system initialization, the startup code must initialize the Queue object class before using any kernel service for that class. The system generation process produces a KCLASSPROP structure containing the information about the kernel object necessary for its initialization. In Example 4-13 on page 149, that structure is referenced externally to the code module.

RTXC Kernel Services Reference, Volume 2

INIT_QueueClassProp

Example 4-13. Initialize Queue Object Class #include "rtxcapi.h"

/* RTXC Kernel Service prototypes */

extern const SYSPROP sysprop; extern const KCLASSPROP queueclassprop; KSRC userinit (void) { int objnum; KSRC ksrc; /* initialize the kernel workspace, allocate RAM */ /* for required classes, etc. */ if ((ksrc = INIT_SysProp (&sysprop)) != RC_GOOD) { putline ("Kernel initialization failure"); return (ksrc); /* end initialization process */ } /* kernel is initialized */ /* Need to initialize the necessary kernel object classes */ /* Initialize the Queue Kernel Object class */ if ((ksrc = INIT_QueueClassProp (&queueclassprop)) != RC_GOOD) { putline ("No RAM for Queue initialization"); return (ksrc); /* end initialization process */ } ... Continue with system initialization }

See Also

INIT_SysProp, page 310 KS_GetQueueClassProp, page 134

Chapter 4: Queue Services

June 21, 2002

149

KS_LookupQueue

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

Synopsis Inputs

Description

KSRC KS_LookupQueue (const char *pname, QUEUE *pqueue)

pname

A pointer to a null-terminated name string.

pqueue

A pointer to a variable in which to store the queue handle, if found.

The KS_LookupQueue kernel service obtains the handle of the static or dynamic queue whose name matches the null-terminated string pointed to by pname. The lookup process terminates when it finds a match between the specified string and a static or dynamic queue name or when it finds no match. The service searches dynamic names, if any, first. Note: To use this service on static queues, you must enable the Static Names attribute of the Queue class during system generation.

This service has no effect on the registration of the specified queue by the Current Task. The time required to perform this operation varies with the number of queue names in use.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the search succeeds. The service also stores the

matching queue’s handle in the variable pointed to by pqueue. `

RC_OBJECT_NOT_FOUND if the service finds no matching queue

name.

150

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_LookupQueue

Example

In Example 4-14, the Current Task needs to use the dynamic queue named DynChnl2Q. If the queue is found, the Current Task needs to get an entry from it.

Example 4-14. Look Up Queue by Name #include "rtxcapi.h"

/* RTXC Kernel Service prototypes */

QUEUE dynqueue; QEVENT qevent; char data[4]; /* lookup the queue name to see if it exists */ if (KS_LookupQueue ("DynChnl2Q", &dynqueue) != RC_GOOD) { ... queue name not found. Deal with it } else { /* queue named DynChnl2Q exists, get data from it, */ /* ignore queue events */ KS_GetQueueDataW (dynqueue, &data, &qevent); ... continue }

See Also

KS_DefQueueName, page 126 KS_OpenQueue, page 152

Chapter 4: Queue Services

June 21, 2002

151

KS_OpenQueue

KS_OpenQueue Allocate and name a dynamic queue.

Synopsis Inputs

Description

KSRC KS_OpenQueue (const char *pname, QUEUE *pqueue)

pname

A pointer to a null-terminated name string.

pqueue

A pointer to a variable in which to store the queue handle.

The KS_OpenQueue kernel service allocates, names, and obtains the handle of a dynamic queue if a dynamic queue is available and there is no existing queue, static or dynamic, with a name matching the null-terminated string pointed to by pname. If these conditions are satisfied, the service allocates a dynamic queue and applies the name referenced by pname to the new queue. The kernel stores only the address of the name internally, which means that the same array cannot be used to build multiple dynamic queue names. If pname is null ((char *)0), the service does not assign a name to the dynamic queue. However, if pname points to a null string, the name is legal as long as no other queue is already using a null string as its name. If the service finds an existing queue with a matching name, it does not open a new queue and returns a value indicating an unsuccessful operation. Note: To use this service, you must enable the Dynamics attribute of the Queue class during system generation.

If the pointer to the queue name is not null ((char *)0), the time required to perform this operation varies with the number of queue names in use.

152

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_OpenQueue

If the pointer to the queue name is null, no search of queue names takes place and the time to perform the service is fixed. You can define the queue name at a later time with a call to the KS_DefQueueName service.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the service completes successfully. The service stores

the handle of the new dynamic queue in the variable pointed to by pqueue. `

RC_OBJECT_ALREADY_EXISTS if the name search finds another

queue whose name matches the specified string. `

Example

RC_NO_OBJECT_AVAILABLE if the name search finds no match but all dynamic queues are in use.

Example 4-15 on page 154 allocates a dynamic queue and names it DynDataQ2. It also obtains a block from the QUEBODY memory partition, then defines the properties for the new queue: the width of each queue entry is four bytes, the depth is as many four-byte entries as can fit in the memory partition block, and the queue is initialized as empty.

Chapter 4: Queue Services

June 21, 2002

153

KS_OpenQueue

Example 4-15. Allocate and Initialize Queue #include "rtxcapi.h" #include "kpart.h"

/* RTXC Kernel Service prototypes */ /* defines QUEBODY */

KSRC ksrc; QUEUE dynqueue; PEVENT pevent; struct QUEUEPROP qprop; struct PARTPROP pprop;

/* queue properties */ /* partition properties */

if ((ksrc = KS_OpenQueue ("DynDataQ2", &dynqueue)) != RC_GOOD) { if (ksrc == RC_OBJECT_ALREADY_EXISTS) putline ("DynDataQ2 queue name in use"); else if (ksrc == RC_NO_OBJECT_AVAILABLE) putline ("No dynamic queues available"); else putline ("The Queue Object Class is not defined"); } else { /* queue was opened correctly. */ /* get block of memory for queue body */ qprop.base = (char *)KS_AllocBlkW (QUEBODY, &pevent); /* get partition’s properties to get size of block */ KS_GetPartProp (QUEBODY, &pprop); /* fill in rest of queue properties */ qprop.depth = pprop.size / 4; qprop.width = 4; qprop.current_size = 0; /* queue is initially empty */ /* define queue now */ KS_DefQueueProp (dynqueue, &qprop); ... continue }

154

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_OpenQueue

See Also

KS_CloseQueue, page 124 KS_LookupQueue, page 150 KS_UseQueue, page 162

Chapter 4: Queue Services

June 21, 2002

155

KS_PutQueueData

KS_PutQueueData Put an entry into a queue.

Synopsis Inputs

Description

KSRC KS_PutQueueData (QUEUE queue, const void *psource)

queue

The handle of the queue.

psource

A pointer to the source buffer.

The KS_PutQueueData kernel service moves data beginning at the address in psource into the specified queue if there is room in the queue. The width property of the queue determines the number of bytes moved. If queue is full, the service returns control to the requesting task immediately with a value indicating the insertion was unsuccessful.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the service completes successfully.

`

RC_QUEUE_FULL if the service failed to insert data into the

specified queue.

Errors

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

FE_ILLEGAL_QUEUE if the specified queue ID is not valid. FE_UNINITIALIZED_QUEUE if the specified queue has not yet

been initialized. `

FE_NULL_SORUCEBUFFER if the pointer to the source buffer is

null.

Example

156

June 21, 2002

Example 4-16 on page 157 moves data from the entry structure into the DATAQ static queue and ensures that the operation succeeded.

RTXC Kernel Services Reference, Volume 2

KS_PutQueueData

Example 4-16. Put Data Into Queue #include "rtxcapi.h" #include "kqueue.h"

/* RTXC Kernel Service prototypes */ /* defines DATAQ */

struct { int type; int value; } entry; /* enqueue packet of data into DATAQ */ if (KS_PutQueueData (DATAQ, &entry) == RC_GOOD) { ... data put into queue } } else { ... no room in queue. Deal with it here. }

See Also

KS_PutQueueDataT, page 158 KS_PutQueueDataW, page 160

Chapter 4: Queue Services

June 21, 2002

157

KS_PutQueueDataT

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.

Synopsis Inputs

Description

KSRC KS_PutQueueDataT (QUEUE queue, const void *psource, COUNTER counter, TICKS ticks)

queue

The handle of the queue.

psource

A pointer to the source buffer.

counter

The counter associated with the tick interval defined by ticks.

ticks

The number of ticks on the specified counter to wait for the queue to have room.

The KS_PutQueueDataT kernel service moves data into the specified FIFO queue from the source area beginning at the address in psource if there is room in the queue. If the queue is full, the service blocks the Current Task and starts an internal alarm for the interval specified in ticks on the specified counter. The task remains blocked until one of two conditions occurs: `

Another task removes an entry from the queue through a call to KS_GetQueueData or one of its variants, or

`

The specified number of ticks elapses.

When the full condition is cleared by another task removing an entry from the queue through a call to KS_GetQueueData or one of its variants, the service puts the new entry into the queue and unblocks the waiting task.

Output

158

June 21, 2002

This service returns a KSRC value as follows: `

RC_GOOD if the service completes successfully.

`

RC_TICKOUT if the specified number of ticks elapses before an entry is removed from the full queue.

RTXC Kernel Services Reference, Volume 2

KS_PutQueueDataT

Errors

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

FE_ILLEGAL_QUEUE if the specified queue ID is not valid. FE_UNINITIALIZED_QUEUE if the specified queue has not yet

been initialized. `

FE_ILLEGAL_COUNTER if the specified counter ID is not valid.

`

FE_UNINITIALIZED_COUNTER if the specified counter has not

yet been initialized. `

FE_NULL_SOURCEBUFFER if the pointer to the source buffer is

null.

Example

Example 4-17 inserts data found in the entry structure into the DATAQ queue. If the queue is full, it waits for 500 msec using the TIMEBASE counter or until the KS_PutQueueDataT operation is successful.

Example 4-17. Put Data Into Queue—Wait Number of Ticks If Queue is Full #include "rtxcapi.h" #include "kqueue.h" #include "kproject.h"

/* RTXC Kernel Service prototypes */ /* DATAQ */ /* CLKTICK */

struct { int type; int value; } entry; /* enqueue packet of info into DATAQ */ if (KS_PutQueueDataT (DATAQ, &entry, TIMEBASE, (TICKS)500/CLKTICK) == RC_GOOD) { ... queue operation was successful. Process the data } else { ... counter expired. Queue was full longer than 500 ms. Handle it here. }

See Also

KS_PutQueueData, page 156 KS_PutQueueDataW, page 160

Chapter 4: Queue Services

June 21, 2002

159

KS_PutQueueDataW

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

Synopsis Inputs

Description

void KS_PutQueueDataW (QUEUE queue, const void *psource)

queue

The handle of the queue.

psource

A pointer to the source buffer.

The KS_PutQueueDataW kernel service inserts an entry into the specified FIFO queue and returns to the requesting task. It moves data to the queue from the area beginning at the address in psource. If the queue is full, the service blocks the Current Task until the condition is removed. When the full condition is cleared by another task removing an entry from the queue, the service inserts the new entry into the queue and unblocks the requesting task.

Output

This service does not return a value.

Errors

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

FE_ILLEGAL_QUEUE if the specified queue ID is not valid. FE_UNINITIALIZED_QUEUE if the specified queue has not yet

been initialized. `

FE_NULL_SORUCEBUFFER if the pointer to the source buffer is

null.

Example

160

June 21, 2002

Example 4-18 on page 161 inserts data found in the entry structure into the DATAQ static queue. If the queue is full, it waits until the requested operation can succeed.

RTXC Kernel Services Reference, Volume 2

KS_PutQueueDataW

Example 4-18. Put Data Into Queue—Wait Until Queue Has Room #include "rtxcapi.h" #include "kqueue.h"

/* RTXC Kernel Service prototypes */ /* defines DATAQ */

struct { int type; int value; } entry; /* enqueue packet of info into DATAQ */ KS_PutQueueDataW (DATAQ, &entry); ... continue

See Also

KS_PutQueueData, page 156 KS_PutQueueDataT, page 158

Chapter 4: Queue Services

June 21, 2002

161

KS_UseQueue

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

Synopsis Inputs

Description

KSRC KS_UseQueue (const char *pname, QUEUE *pqueue)

pname

A pointer to a null-terminated name string.

pqueue

A pointer to a variable in which to store the queue handle.

The KS_UseQueue kernel service acquires the handle of a dynamic queue by looking up the null-terminated string pointed to by pname in the list of queue names. If there is a match, the service registers the queue for future use by the Current Task and stores the matching queue’s handle in the variable pointed to by pqueue. This procedure allows the Current Task to reference the dynamic queue successfully in subsequent kernel service calls. Note: To use this service, you must enable the Dynamics attribute of the Queue class during system generation.

The time required to perform this operation varies with the number of queue names in use.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the search and registration is successful. The service

also stores the matching queue’s handle in the variable pointed to by pqueue. `

RC_STATIC_OBJECT if the specified name belongs to a static

queue. `

RC_OBJECT_NOT_FOUND if the service finds no matching queue

name.

Example

162

June 21, 2002

Example 4-19 on page 163 locates a dynamic queue named DynMuxQ3 and obtains its handle for subsequent use.

RTXC Kernel Services Reference, Volume 2

KS_UseQueue

Example 4-19. Read Queue Handle and Register It #include "rtxcapi.h"

/* RTXC Kernel Service prototypes */

KSRC ksrc; QUEUE dynqueue; if ((ksrc = KS_UseQueue ("DynMuxQ3", &dynqueue)) != RC_GOOD) { if (ksrc == RC_OBJECT_NOT_FOUND) putline ("Queue DynMuxQ3 not found"); else putline ("Queue DynMuxQ3 is a static queue"); } else { ... queue was found and its handle is in dynqueue. Okay to use it now }

See Also

KS_DefQueueProp, page 128 KS_DefQueueName, page 126 KS_OpenQueue, page 152

Chapter 4: Queue Services

June 21, 2002

163

KS_UseQueue

164

June 21, 2002

RTXC Kernel Services Reference, Volume 2

CHAPTER

5

Mailbox Services

In This Chapter We describe the Mailbox kernel services in detail. The Mailbox kernel services provide data passing between the calling task and other tasks through mailboxes. 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

Chapter 5: Mailbox Services

June 21, 2002

165

KS_CloseMbox

KS_CloseMbox End the use of a dynamic mailbox.

Synopsis Input

KSRC KS_CloseMbox (MBOX mbox)

mbox

Description

The handle of the mailbox.

The KS_CloseMbox kernel service ends the Current Task’s use of the dynamic mailbox specified in mbox. When closing the mailbox, the service detaches the caller’s use of it. If the caller is the last user of the mailbox, the service releases the mailbox to the free pool of dynamic mailboxes for reuse. If there is at least one other task still using the mailbox, the service does not release the mailbox to the free pool but completes successfully. Be careful when closing a mailbox on which one or more tasks may be waiting. Closing the mailbox may cause waiters to be lost. However, you can avoid this problem if each task that uses the mailbox makes a KS_UseMbox call before it begins using the mailbox and then makes a KS_CloseMbox call when it is done using the mailbox. Note: To use this service, you must enable the Dynamics attribute of the Mailbox class during system generation.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the service is successful.

`

RC_STATIC_OBJECT if the specified mailbox is not dynamic.

`

RC_OBJECT_NOT_INUSE if the specified mailbox does not

correspond to an active dynamic mailbox. `

166

June 21, 2002

RC_OBJECT_INUSE if the Current Task’s use of the specified mailbox is closed but the mailbox remains open for use by other tasks.

RTXC Kernel Services Reference, Volume 2

KS_CloseMbox

Note: RC_OBJECT_INUSE does not necessarily indicate an error condition. The calling task must interpret its meaning.

Error

This service may generate the following fatal error code: FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.

Example

In Example 5-1, the Current Task waits on a signal from another task indicating that it is time to close a dynamic mailbox. The handle of the dynamic semaphore associated with the signal is specified in dynsema. The handle of the dynamic mailbox is specified in dynmbox. When the signal is received, the Current Task closes the dynamic mailbox even if there are other users.

Example 5-1. Close Mailbox #include "rtxcapi.h"

/* RTXC Kernel Services prototypes */

MBOX dynmbox; SEMA dynsema; KSRC ksrc; KS_TestSemaW (dynsema); /* wait for signal */ /* then close the mailbox */ if ((ksrc = KS_CloseMbox (dynmbox)) != RC_GOOD) { /* okay if other users exist */ if (ksrc != RC_OBJECT_INUSE) { ... mailbox cannot be closed. Deal with it here. } } /* Otherwise, mailbox closed and released to the */ /* free pool */ ... Continue

See Also

KS_OpenMbox, page 188 KS_DefMboxProp, page 170

Chapter 5: Mailbox Services

June 21, 2002

167

KS_DefMboxName

KS_DefMboxName Define the name of a previously opened dynamic mailbox.

Synopsis Inputs

Description

KSRC KS_DefMboxName (MBOX mbox, const char *pname)

mbox

The handle of the mailbox being defined.

pname

A pointer to a null-terminated name string.

The KS_DefMboxName kernel service names or renames the open dynamic mailbox specified in mbox. The service uses the nullterminated string pointed to by pname for the mailbox’s new name. Static mailboxes cannot be named or renamed under program control. Note: To use this service, you must enable the Dynamics attribute of the Mailbox class during system generation.

This service does not check for duplicate task names.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the service completes successfully.

`

RC_STATIC_OBJECT if the mailbox being named is static.

`

RC_OBJECT_NOT_FOUND if the Dynamics attribute of the Mailbox

class is not enabled. `

RC_OBJECT_NOT_INUSE if the specified mailbox does not

correspond to an active dynamic mailbox.

Error

This service may generate the following fatal error code: FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.

168

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_DefMboxName

Example

In Example 5-2, the dynmbox variable contains the handle of a previously opened mailbox. Assign the name NewMbox to that mailbox so other users may reference it by name.

Example 5-2. Assign Mailbox Name #include "rtxcapi.h"

/* RTXC Kernel Services prototypes */

MBOX dynmbox; if (KS_DefMboxName (dynmbox, "NewMbox") != RC_GOOD) { ... Naming operation failed. Deal with it here } ... naming operation was successful. Continue

See Also

KS_OpenMbox, page 188 KS_GetMboxName, page 178 KS_LookupMbox, page 186 KS_UseMbox, page 191

Chapter 5: Mailbox Services

June 21, 2002

169

KS_DefMboxProp

KS_DefMboxProp Define the properties of a mailbox.

Synopsis Inputs

void KS_DefMboxProp (MBOX mbox, const MBOXPROP *pmboxprop)

mbox

The handle of the mailbox being defined.

pmboxprop A pointer to a Mailbox properties structure.

Description

The KS_DefMboxProp kernel service defines the properties of the mailbox specified in mbox using the values contained in the MBOXPROP structure pointed to by pmboxprop. Example 5-3 shows the organization of the MBOXPROP structure.

Example 5-3. Mailbox Properties Structure typedef struct { KATTR attributes; } MBOXPROP;

/* Waiting Order */

You may define the following mailbox attribute value:

Waiting Order

Indicates the order in which tasks wait for access to a mailbox. The default order is by priority. Waiting Order can be changed to chronological ordering by ORing the ATTR_FIFO_ORDER constant into the attributes field.

The default value for the Waiting Order attribute can be restored by ANDing the attributes field with ~ATTR_FIFO_ORDER.

Output

This service does not return a value.

Error

This service may generate the following fatal error code: FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.

170

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_DefMboxProp

Example

In Example 5-4 on page 171, the Current Task defines the properties of the dynamic mailbox specified in dynmbox so that any tasks waiting to receive mail are ordered in descending order of task priority.

Example 5-4. Define Mailbox Properties #include "rtxcapi.h"

/* RTXC Kernel Services prototypes */

MBOX dynmbox; MBOXPROP mprop; KSRC ksrc; KS_GetMboxProp (dynmbox, &mprop);

/* Get properties */

/* use priority waiters */ mprop.attributes &= (~ATTR_FIFO_ORDER); KS_DefMboxProp (dynmbox, &mprop);

/* define properties */

... Continue

See Also

KS_GetMboxProp, page 180 INIT_MboxClassProp, page 184 KS_OpenMbox, page 188

Chapter 5: Mailbox Services

June 21, 2002

171

KS_DefMboxSema

KS_DefMboxSema Associate a semaphore with the Mailbox_Not_Empty event.

Synopsis Inputs

Description

void KS_DefMboxSema (MBOX mbox, SEMA sema)

mbox

The handle of the mailbox being defined.

sema

The handle of a semaphore to associate with the mailbox.

The KS_DefMboxSema kernel service associates the semaphore specified in sema with the Mailbox_Not_Empty event of the mailbox specified in mbox. This action permits a task to synchronize with the occurrence of the mailbox event among a group of other events through the use of the KS_TestSemaM service or one of its variants. Note: To use this service, you must enable the Semaphores attribute of the Mailbox class during system generation.

You do not need to use a semaphore to synchronize with the Mailbox_Not_Empty event unless you use it in conjunction with a multiple-event wait request. The RTXC Kernel provides that synchronization automatically and transparently.

Output

This service does not return a value.

Errors

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

FE_ILLEGAL_MBOX if the specified mailbox ID is not valid. FE_UNINITIALIZED_MBOX if the specified mailbox has not yet

been initialized. `

FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.

`

FE_UNINITIALIZED_SEMA if the specified semaphore has not

yet been initialized.

172

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_DefMboxSema

Example

In Example 5-5 on page 174, the Current Task is servicing the HPMAIL and LPMAIL mailboxes. It needs to synchronize with the next message being sent to either mailbox, both of which are currently empty. The choice is not to poll the mailboxes but rather to define mailbox semaphores for the Mailbox_Not_Empty events for both mailboxes. Then the task uses the KS_TestSemaM service (or one of its variants) to wait for mail to be sent to either mailbox. When the task detects the presence of mail, it identifies the mailbox having the mail, receives it, and processes it. Upon completion of its processing, the task acknowledges the message to notify the sender that processing is finished.

Chapter 5: Mailbox Services

June 21, 2002

173

KS_DefMboxSema

Example 5-5. Define Mailbox Semaphore #include "rtxcapi.h" #include "kmbox.h" #include "ksema.h"

/* RTXC Kernel Services prototypes */ /* defines HPMAIL and LPMAIL */ /* defines GOTHP and GOTLP */

char *msg; MSGENV *penvelope; SEMA sema; const SEMA semalist[] = { GOTHP, GOTLP, (SEMA)0 /* list must be null terminated */ }; KS_DefMboxSema (HPMAIL, GOTHP); KS_DefMboxSema (LPMAIL, GOTLP);

/* define semas for */ /* both mailboxes */

/* now test for a signal and wait if there is none */ sema = KS_TestSemaMW (semalist); switch (sema) /* see which one was signaled */ { case GOTHP: /* receive message in HPMAIL from any task */ msg = KS_ReceiveMsg (HPMAIL, &penvelope); ... process received message break; case GOTLP: /* receive message in LPMAIL from any task */ msg = KS_ReceiveMsg (LPMAIL, &penvelope); ... process received message break; } /* acknowledge message receipt and processing */ KS_AckMsg (penvelope); ... continue

174

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_DefMboxSema

See Also

KS_GetMboxSema, page 182 KS_ReceiveMsg, page 200 KS_TestSema, page 106 KS_TestSemaT, page 108 KS_TestSemaW, page 118 KS_TestSemaM, page 110 KS_TestSemaMW, page 115 KS_TestSemaMT, page 112

Chapter 5: Mailbox Services

June 21, 2002

175

KS_GetMboxClassProp

KS_GetMboxClassProp Get the Mailbox object class properties.

Synopsis

const KCLASSPROP * KS_GetMboxClassProp (int *pint)

Input

pintA pointer to a variable in which to store the number of available dynamic mailboxes.

Description

The KS_GetMboxClassProp kernel service obtains a pointer to the KCLASSPROP structure that was used during system initialization by the INIT_MboxClassProp service to initialize the Mailbox object class properties. If pint is not null ((int *)0), the service returns the number of available dynamic mailboxes in the variable pointed to by pint. Example 2-22 on page 62 shows the organization of the KCLASSPROP structure. The attributes element of the Mailbox KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 5-1.

Table 5-1. Mailbox Class Attributes and Masks

Output

Attribute

Mask

Static Names

ATTR_STATIC_NAMES

Dynamics

ATTR_DYNAMICS

Semaphores

ATTR_SEMAPHORES

If successful, this service returns a pointer to a KCLASSPROP structure. If the Mailbox class is not initialized, the service returns a null pointer ((KCLASSPROP *)0). If pint is not null, the service returns the number of available dynamic mailboxes in the variable pointed to by pint.

176

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_GetMboxClassProp

Example

In Example 5-6, the Current Task wants to gain access to the information contained in the KCLASSPROP structure for the Mailbox object class.

Example 5-6. Read Mailbox Object Class Properties #include "rtxcapi.h"

/* RTXC Kernel Services prototypes */

KCLASSPROP *pmboxclassprop; int *free_dyn; /* Get the mailbox kernel object class properties */ if ((pmboxclassprop = KS_GetMboxClassProp (&free_dyn)) == (KCLASSPROP *)0) { putline ("Mailbox Class not initialized"); } else { ... mailbox object class properties are available for use free_dyn contains the number of free dynamic mailboxes }

See Also

INIT_MboxClassProp, page 184

Chapter 5: Mailbox Services

June 21, 2002

177

KS_GetMboxName

KS_GetMboxName Get the name of a mailbox.

Synopsis Input

char * KS_GetMboxName (MBOX mbox)

mbox

Description

The handle of the mailbox being queried.

The KS_GetMboxName kernel service obtains a pointer to the nullterminated string containing the name of the mailbox specified in mbox. The mailbox may be static or dynamic. Note: To use this service on static mailboxes, you must enable the Static Names attribute of the Mailbox class during system generation.

Output

If the mailbox has a name, this service returns a pointer to the nullterminated name string. If the mailbox has no name, the service returns a null pointer ((char *)0).

Error

This service may generate the following fatal error code: FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.

Example

178

June 21, 2002

In Example 5-7 on page 179, the Current Task needs to report the name of the dynamic mailbox specified in dynmbox.

RTXC Kernel Services Reference, Volume 2

KS_GetMboxName

Example 5-7. Read Mailbox Name #include #include "rtxcapi.h"

/* standard i/o */ /* RTXC Kernel Services prototypes */

static char buf[128]; MBOX dynmbox; char *pname; if ((pname = KS_GetMboxName (dynmbox)) == (char *)0) sprintf (buf, "Mailbox %d has no name", dynmbox); else sprintf (buf, "Mailbox %d name is %s", dynmbox, pname); putline (buf);

See Also

KS_DefMboxName, page 168 KS_OpenMbox, page 188

Chapter 5: Mailbox Services

June 21, 2002

179

KS_GetMboxProp

KS_GetMboxProp Get the properties of a mailbox.

Synopsis Inputs

void KS_GetMboxProp (MBOX mbox, MBOXPROP *pmboxprop)

mbox

The handle of the mailbox being queried.

pmboxprop A pointer to a Mailbox properties structure.

Description

The KS_GetMboxProp kernel service obtains all of the property values of the mailbox specified in mbox in a single call. The service stores the property values in the MBOXPROP structure pointed to by pmboxprop. Example 5-3 on page 170 shows the organization of the MBOXPROP structure. The attributes property may have the following values:

Waiting Order indicates the ordering of tasks waiting for access to the mailbox. If (attributes & ATTR_FIFO_ORDER) is not equal to 0, waiters have chronological ordering. If (attributes & ATTR_FIFO_ORDER) equals 0, waiters are by priority.

Output

This service does not return a value.

Errors

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

FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.

`

FE_UNINITIALIZED_MBOX if the specified mailbox has not yet

been initialized.

Example

180

June 21, 2002

In Example 5-8 on page 181, the Current Task needs to ensure that the properties of the dynamic mailbox specified in dynmbox are defined such that any tasks waiting to receive mail are ordered in descending order of task priority. The task first reads the existing

RTXC Kernel Services Reference, Volume 2

KS_GetMboxProp

properties of the specified mailbox and then forces priority order waiting. Example 5-8. Read Mailbox Properties #include "rtxcapi.h"

/* RTXC Kernel Services prototypes */

MBOX dynmbox; MBOXPROP mboxprop; KS_GetMboxProp (dynmbox, &mboxprop); /* get properties */ /* force priority Waiting Order */ mboxprop.attributes &= (~ATTR_FIFO_ORDER); /* define properties */ KS_DefMboxProp (dynmbox, &mboxprop); ... continue

See Also

KS_GetMboxProp, page 180

Chapter 5: Mailbox Services

June 21, 2002

181

KS_GetMboxSema

KS_GetMboxSema Get the semaphore handle associated with a Mailbox_Not_Empty event.

Synopsis Input

SEMA KS_GetMboxSema (MBOX mbox)

mbox

Description

The handle of the mailbox being queried.

The KS_GetMboxSema kernel service obtains the handle of the semaphore associated with the Mailbox_Not_Empty event for the static or dynamic mailbox specified in mbox. You must have previously associated the semaphore with the mailbox event through a call to the KS_DefMboxSema service. Note: To use this service, you must enable the Semaphores attribute of the Mailbox class during system generation.

Output

If the mailbox event and semaphore association exists, this service returns the handle of the semaphore as a SEMA type value. If there is no such association for the mailbox event, the service returns a SEMA value of zero (0).

Errors

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

FE_ILLEGAL_MBOX if the specified mailbox ID is not valid. FE_UNINITIALIZED_MBOX if the specified mailbox has not yet

been initialized.

Example

182

June 21, 2002

In Example 5-9 on page 183, the Current Task needs to know the handle of the Mailbox_Not_Empty semaphore associated with the MAINMBOX static mailbox. If it finds a semaphore already defined, it waits on that event or another associated with the MBXSEMA2 semaphore. If there is no semaphore defined, the Current Task

RTXC Kernel Services Reference, Volume 2

KS_GetMboxSema

defines the MBOX1SEMA semaphore, adds it to semalist, and waits on either that event or the one associated with MBXSEMA2. Example 5-9. Read Mailbox Semaphore #include "rtxcapi.h" #include "ksema.h" #include "kmbox.h"

/* RTXC Kernel Services prototypes */ /* defines MBOX1SEMA, MBXSEMA2 */ /* defines MAINMBOX */

SEMA cause; static SEMA semalist[] = { 0, /* to be filled in /* MBXSEMA2, (SEMA)0 /* end-of-list */ }; if ((semalist[0] = KS_GetMboxSema (MAINMBOX)) == (SEMA)0) { /* no NE semaphore defined for mailbox MAINMBOX */ KS_DefMboxSema (MAINMBOX, MBOX1SEMA); /* define one */ semalist[0] = MBOX1SEMA; } /* there is now a NE semaphore defined for */ /* mailbox MAINMBOX */ /* wait for either event */ cause = KS_TestSemaMW (semalist); if (cause == semalist[0]) { ... MAINMBOX received a message } else ( ... MBXSEMA2 was signaled )

See Also

KS_DefMboxSema, page 172

Chapter 5: Mailbox Services

June 21, 2002

183

INIT_MboxClassProp

INIT_MboxClassProp Initialize the Mailbox object class properties.

Synopsis Input

KSRC INIT_MboxClassProp (const KCLASSPROP *pclassprop)

pclassprop

Description

A pointer to a Mailbox object class properties structure.

During the RTXC Kernel initialization procedure, you must define the kernel objects needed by the RTXC Kernel to perform the application. The INIT_MboxClassProp kernel service allocates space for the Mailbox object in system RAM. The amount of RAM to allocate, and all other properties of the class, are specified in the KCLASSPROP structure pointed to by pclassprop. Example 2-22 on page 62 shows the organization of the KCLASSPROP structure. The attributes element of the Mailbox KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 5-1 on page 176.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the service completes successfully.

`

RC_NO_RAM if the initialization fails because there is insufficient

system RAM available.

Example

184

June 21, 2002

During system initialization, the startup code must initialize the Mailbox object class before using any kernel service for that class. The system generation process produces a KCLASSPROP structure containing the information about the kernel object necessary for its initialization. In Example 5-10 on page 185, that structure is referenced externally to the code module.

RTXC Kernel Services Reference, Volume 2

INIT_MboxClassProp

Example 5-10. Initialize Mailbox Object Class #include "rtxcapi.h"

/* RTXC Kernel Services prototypes */

extern const SYSPROP sysprop; extern const KCLASSPROP mboxclassprop; KSRC userinit (void) { int objnum; KSRC ksrc; /* initialize the kernel workspace, allocate RAM */ /* for required classes, etc. */ if ((ksrc = INIT_SysProp (&sysprop)) != RC_GOOD) { putline ("Kernel initialization failure"); return (ksrc); /* end initialization process */ } /* kernel is initialized */ /* Need to initialize the necessary kernel object */ /* classes */ /* Initialize the Mailbox Kernel Object class */ if ((ksrc = INIT_MboxClassProp (&mboxclassprop)) != RC_GOOD) { putline ("No RAM for Mailbox initialization"); return (ksrc); /* end initialization process */ } ... Continue with system initialization }

See Also

INIT_SysProp, page 310 KS_GetMboxClassProp, page 176

Chapter 5: Mailbox Services

June 21, 2002

185

KS_LookupMbox

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

Synopsis Inputs

Description

KSRC KS_LookupMbox (const char *pname, MBOX *pmbox)

pname

A pointer to a null-terminated name string.

pmbox

A pointer to a variable in which to store the mailbox handle, if found.

The KS_LookupMbox kernel service obtains the handle of a static or dynamic mailbox whose name matches the null-terminated string pointed to by pname. The lookup process terminates when it finds a match between the specified string and a static or dynamic mailbox name or when it finds no match. The service stores the matching mailbox’s handle in the variable pointed to by pmbox. The service searches dynamic names, if any, first. Note: To use this service on static mailboxes, you must enable the Static Names attribute of the Mailbox class during system generation.

This service has no effect on the use registration of the specified mailbox by the Current Task. The time required to perform this operation varies with the number of mailbox names in use.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the search succeeds. The service also stores the

matching mailbox’s handle in the variable pointed to by pmbox. `

RC_OBJECT_NOT_FOUND if the service finds no matching

mailbox name.

186

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_LookupMbox

Example

In Example 5-11, the Current Task needs to use the dynamic mailbox named DynMbox2. If the mailbox is found, the Current Task needs to display its name and handle on the system console.

Example 5-11. Look Up Mailbox by Name #include #include "rtxcapi.h"

/* standard i/o */ /* RTXC Kernel Services prototypes */

static char buf[128];

/* buffer space */

MBOX dynmbox; /* lookup the mailbox name to see if it exists */ if (KS_LookupMbox ("DynMbox2", &dynmbox) != RC_GOOD) { ... mailbox name not found. Deal with it } else { /* mailbox named "DynMbox2" exists, */ /* display its name and handle */ sprintf (buf, "Mailbox %d is DynMbox2", dynmbox); putline (buf); /* output the text */ }

See Also

KS_DefMboxName, page 168 KS_OpenMbox, page 188

Chapter 5: Mailbox Services

June 21, 2002

187

KS_OpenMbox

KS_OpenMbox Allocate and name a dynamic mailbox.

Synopsis Inputs

Description

KSRC KS_OpenMbox (const char *pname, MBOX *pmbox)

pname

A pointer to a null-terminated name string.

pmbox

A pointer to a variable in which to store the mailbox handle.

The KS_OpenMbox kernel service allocates, names, and obtains the handle of a dynamic mailbox. If there is no existing mailbox name, static or dynamic, with a name matching the null-terminated string pointed to by pname, the service allocates a dynamic mailbox and applies the name referenced by pname to the new mailbox. The kernel stores only the address of the name internally, which means that the same array cannot be used to build multiple dynamic mailbox names. The service stores the handle of the new dynamic mailbox in the variable pointed to by pmbox. If pname is null ((char *)0), the service does not assign a name to the dynamic mailbox. However, if pname points to a null string, the name is legal as long as no other mailbox is already using a null string as its name. If the service finds an existing mailbox with a matching name, it does not open a new mailbox and returns a value indicating an unsuccessful operation. Note: To use this service, you must enable the Dynamics attribute of the Mailbox class during system generation.

If the pointer to the mailbox name is not null, the time required to perform this operation varies with the number of mailbox names in use. If the pointer to the mailbox name is null, no search of mailbox names takes place and the time to perform the

188

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_OpenMbox

service is fixed. You can define the mailbox name at a later time with a call to the KS_DefMboxName service.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the service completes successfully. The service also

stores the handle of the new dynamic mailbox in the variable pointed to by pmbox. `

RC_OBJECT_ALREADY_EXISTS if the name search finds another

mailbox whose name matches the specified string. `

RC_NO_OBJECT_AVAILABLE if the name search finds no match

but all dynamic mailboxes are in use.

Example

Example 5-12, allocates a dynamic mailbox and names it DynMbox1. After the mailbox is opened successfully, it can be used to receive a message.

Example 5-12. Allocate Mailbox #include "rtxcapi.h"

/* RTXC Kernel Services prototypes */

KSRC ksrc; MBOX dynmbox; char *msg; MSGENV *penvelope; if ((ksrc = KS_OpenMbox ("DynMbox1", &dynmbox)) != RC_GOOD) { if (ksrc == RC_OBJECT_ALREADY_EXISTS) putline ("DynMbox1 mailbox name in use"); else if (ksrc == RC_NO_OBJECT_AVAILABLE) putline ("No dynamic mailboxes available"); else putline ("Mailbox not a defined object class"); } else { /* mailbox was opened correctly. Use it now to receive a message */ msg = KS_ReceiveMsgW (dynmbox, &penvelope); ...continue }

Chapter 5: Mailbox Services

June 21, 2002

189

KS_OpenMbox

See Also

190

June 21, 2002

KS_CloseMbox, page 166 KS_LookupMbox, page 186 KS_UseMbox, page 191

RTXC Kernel Services Reference, Volume 2

KS_UseMbox

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

Synopsis Inputs

Description

KSRC KS_UseMbox (const char *pname, MBOX *pmbox)

pname

A pointer to a null-terminated name string.

pmbox

A pointer to a variable in which to store the mailbox handle.

The KS_UseMbox kernel service acquires the handle of a dynamic mailbox by looking up the null-terminated string pointed to by pname in the list of mailbox names. If there is a match, the service registers the mailbox for future use by the Current Task and stores the matching mailbox’s handle in the variable pointed to by pmbox. This procedure allows the Current Task to reference the dynamic mailbox successfully in subsequent kernel service calls. Note: To use this service, you must enable the Dynamics attribute of the Mailbox class during system generation.

The time required to perform this operation varies with the number of mailbox names in use.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the search and registration is successful. The service

also stores the matching mailbox’s handle in the variable pointed to by pmbox. `

RC_STATIC_OBJECT if the specified name belongs to a static

mailbox. `

RC_OBJECT_NOT_FOUND if the service finds no matching

mailbox name.

Example

Example 5-13 on page 192 locates a dynamic mailbox by the name of DynMbox1 and obtains its handle for subsequent use.

Chapter 5: Mailbox Services

June 21, 2002

191

KS_UseMbox

Example 5-13. Read Mailbox Handle and Register It #include "rtxcapi.h"

/* RTXC Kernel Services prototypes */

KSRC ksrc; MBOX dynmbox; if ((ksrc = KS_UseMbox ("DynMbox1", &dynmbox)) != RC_GOOD) { if (ksrc == RC_OBJECT_NOT_FOUND) putline ("Mailbox DynMbox1 not found"); else putline ("Mailbox DynMbox1 is a static mailbox"); } else { ... mailbox was found and its handle is in dynmbox. Okay to use it now }

See Also

192

June 21, 2002

KS_DefMboxProp, page 170 KS_DefMboxName, page 168 KS_OpenMbox, page 188

RTXC Kernel Services Reference, Volume 2

CHAPTER

6

Message Services

In This Chapter We describe the Message kernel services in detail. The Message kernel services provide for 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. KS_AckMsg....................................................................................... 194 KS_ForwardMsg ............................................................................... 196 KS_ReceiveMsg ............................................................................... 200 KS_ReceiveMsgT ..............................................................................202 KS_ReceiveMsgW............................................................................ 204 KS_SendMsg ................................................................................... 206 KS_SendMsgT ................................................................................. 209 KS_SendMsgW..................................................................................213 KS_TestAck....................................................................................... 216 KS_TestAckT..................................................................................... 218 KS_TestAckW ...................................................................................220

Chapter 6: Message Services

June 21, 2002

193

KS_AckMsg

KS_AckMsg Acknowledge a message.

Synopsis Input

void KS_AckMsg (MSGENV *pmsgenv)

pmsgenv

Description

A pointer to a message envelope.

The KS_AckMsg kernel service acknowledges completion of message processing for the message contained in the message envelope pointed to by pmsgenv. Acknowledging a message allows tasks sending synchronously to resume and tasks sending asynchronously to test for acknowledgment using some form of the KS_TestAck service. The calling task obtains the address of the message envelope by a call to the KS_ReceiveMsg, KS_ReceiveMsgT, or KS_ReceiveMsgW service. After handling the sending task, the service then signals the message acknowledge semaphore if one was specified by the sending task.

Output

This service does not return a value.

Errors

This service may generate the following fatal error code: FE_NULL_MSGENV if the pointer to the message envelope is null.

Example

194

June 21, 2002

Example 6-1 on page 195 receives a message by getting the pointer to the message body in pmsgbody and saves the pointer to the message envelope in pmsgenv. When finished processing the message body, it informs the sending task of the event.

RTXC Kernel Services Reference, Volume 2

KS_AckMsg

Example 6-1. Acknowledge Message #include "rtxcapi.h" #include "kmbox.h"

/* RTXC Kernel Services prototypes */ /* defines EMAIL */

MSGENV *pmsgenv; char *pmsgbody; /* get next message from mailbox EMAIL */ pmsgbody = (char *)KS_ReceiveMsgW (EMAIL, &pmsgenv); ... process message using pmsgbody as pointer to body KS_AckMsg (pmsgenv);

See Also

/* signal message processing done */

KS_ReceiveMsg, page 200 KS_ReceiveMsgT, page 202 KS_ReceiveMsgW, page 204 KS_SendMsg, page 206 KS_SendMsgT, page 209 KS_SendMsgW, page 213

Chapter 6: Message Services

June 21, 2002

195

KS_ForwardMsg

KS_ForwardMsg Forward a message to a mailbox asynchronously.

Synopsis Inputs

Description

void KS_ForwardMsg (MBOX mbox, MSGENV *pmsgenv, MSG_PRIORITY priority)

mbox

The handle for the mailbox to which to send the message.

pmsgenv

A pointer to the message envelope.

priority

The priority of the message.

The KS_ForwardMsg kernel service forwards a received message to the mailbox specified in mbox. The message envelope should be the same one attached to the message by the original sender and must be in RAM with its address pointed to by pmsgenv. This service is similar to KS_SendMsg except that it does not change the ID of the original sending task or the message body pointer in the message envelope. Thus, the task using KS_ForwardMsg does not need to wait for an acknowledgment from a receiver task. The original sending task will be the one to verify receipt of the message by the receiving task. Each message has a user-defined priority of either URGENT_MSG or NORMAL_MSG. If the sending or forwarding task does not explicitly define the priority (priority =(MSG_PRIORITY)0), the kernel assigns the message a priority of NORMAL_MSG. Using the message priority, the kernel adds each message to the specified mailbox. Messages of NORMAL_MSG priority are added to the mailbox in chronological (FIFO) order. For messages having an URGENT_MSG priority, the kernel adds them at the front of the list of messages in the mailbox (LIFO order). When forwarding a message to a mailbox, there may or may not be a task waiting to receive it. If not, the kernel adds the message to the mailbox according to the message’s priority. If a task is waiting to receive a message from the mailbox, the kernel passes the message directly to the receiving task and unblocks it. If, as a result, the receiving task becomes ready to run, the kernel places it in the Ready

196

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_ForwardMsg

List at a position determined by its priority. If the receiving task’s priority is higher than that of the sending or forwarding task, a preemption occurs. After putting the message into the mailbox or passing it on to a waiting receiver, the kernel service is complete. This kernel service never blocks the forwarding task even though it may be preempted.

Output

This service does not return a value.

Errors

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

FE_ILLEGAL_MBOX if the specified mailbox ID is not valid. FE_UNINITIALIZED_MBOX if the specified mailbox has not yet

been initialized.

Example

`

FE_INVALID_MSG_PRIORITY if the specified message priority value is not either URGENT or NORMAL.

`

FE_NULL_MSGENV if the pointer to the message envelope is null.

Example 6-2 on page 198 forwards a message at NORMAL priority to the MAILBOX3 static mailbox. The message is in a structure named msgbody.

Chapter 6: Message Services

June 21, 2002

197

KS_ForwardMsg

Example 6-2. Forward Message #include "rtxcapi.h" #include "kmbox.h" struct { int command; char data[10]; } msgbody;

/* RTXC Kernel Services prototypes */ /* defines MAILBOX3 & MAILBOX2 */ /* start of message body */

MSGENV *pmsgenv; /* pointer to Message envelope (required) */ struct msgbody *pmsgbody; /* pointer to message body ... receive a message from MAILBOX2 and see if it is to be forwarded pmsgbody = KS_ReceiveMsgW (MAILBOX2, &pmsgenv); if (message is to be forwarded) { /* forward message to MAILBOX3 at NORMAL_MSG priority */ KS_ForwardMsg (MAILBOX3, pmsgenv, NORMAL_MSG); } else { ... continue }

See Also

198

June 21, 2002

KS_SendMsg, page 206 KS_SendMsgW, page 213 KS_SendMsgT, page 209

RTXC Kernel Services Reference, Volume 2

KS_ForwardMsg

Chapter 6: Message Services

June 21, 2002

199

KS_ReceiveMsg

KS_ReceiveMsg Receive a message from a mailbox.

Synopsis Inputs

Description

void * KS_ReceiveMsg (MBOX mbox, MSGENV **pmsgenv)

mbox

A handle for the mailbox from which the message is being received.

pmsgenv

A pointer to a message envelope pointer.

The KS_ReceiveMsg kernel service reads a message from the mailbox specified in mbox and returns a pointer to the message body. A pointer to the message envelope pointer is given by pmsgenv. These two pointers give complete access to the message for both processing and acknowledgment. The messages are processed in the sequence they occur in the mailbox, as specified by the mailbox’s attributes.

Output

This service returns a pointer to the message body if a message was in the mailbox. If no message was available, the service returns a null pointer ((void *)0).

Errors

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

FE_ILLEGAL_MBOX if the specified mailbox ID is not valid. FE_UNINITIALIZED_MBOX if the specified mailbox has not yet

been initialized.

Example

200

June 21, 2002

In Example 6-3 on page 201, a task wants to receive the next message from any sender in the MYMAIL mailbox. If a message is received, it is processed and at the conclusion of processing, the sending task is notified. If no message is in the mailbox, the task executes special code to manage the situation.

RTXC Kernel Services Reference, Volume 2

KS_ReceiveMsg

Example 6-3. Receive Next Message from a Mailbox #include "rtxcapi.h" #include "kmbox.h"

/* RTXC Kernel Services prototypes */ /* defines MYMAIL */

void *pmsgbody; MSGENV *pmsgenv; /* receive next message from any task */ pmsgbody = KS_ReceiveMsg (MYMAIL, &pmsgenv); if (pmsgbody != (void *)0) { ... message received, process it ... KS_AckMsg (pmsgenv);/* acknowledge message processed */ } else { ... Deal with no message available }

See Also

KS_ReceiveMsgT, page 202 KS_ReceiveMsgW, page 204

Chapter 6: Message Services

June 21, 2002

201

KS_ReceiveMsgT

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

Synopsis Inputs

Description

void * KS_ReceiveMsgT (MBOX mbox, MSGENV **pmsgenv, COUNTER counter, TICKS ticks)

mbox

A handle for the mailbox from which the message is being received.

pmsgenv

A pointer to a message envelope.

counter

The counter associated with the interval defined by ticks.

ticks

The number of ticks on the specified counter to wait for a message.

The KS_ReceiveMsgT kernel service reads a message from the mailbox specified in mbox and returns a pointer to the message body. A pointer to the message envelope pointer is given by pmsgenv. These two pointers give complete access to the message for both processing and acknowledgment. The messages are processed in the sequence they occur in the mailbox, as specified by the mailbox’s attributes. If the mailbox is empty, the service blocks the requesting task and starts an internal alarm for the interval specified in ticks on the specified counter. The task remains blocked until either of two events occurs:

Output

`

Another task sends a message to the specified mailbox and that message meets the reception criteria of the waiting task, or

`

The specified number of ticks elapses.

This service returns a pointer to the body of the received message if one was in the mailbox. If the specified number of ticks elapses before the mailbox receives any mail, the service returns a null pointer ((void *)0).

202

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_ReceiveMsgT

Errors

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

FE_ILLEGAL_MBOX if the specified mailbox ID is not valid. FE_UNINITIALIZED_MBOX if the specified mailbox has not yet

been initialized. `

FE_ILLEGAL_COUNTER if the specified counter ID is not valid.

`

FE_UNINITIALIZED_COUNTER if the specified counter has not

yet been initialized.

Example

In Example 6-4, the Current Task attempts to receive the next message from the MYMAIL mailbox. If there is no mail in the mailbox, the task is to wait for up to 500 msec using the TIMEBASE counter for mail to arrive. If the 500 msec period elapses without receipt of mail, the task is to resume and perform a special code segment to handle the timeout situation.

Example 6-4. Receive Message—Wait Number of Ticks If Necessary #include "rtxcapi.h" #include "kmbox.h" #include "kproject.h"

/* RTXC Kernel Services prototypes */ /* defines MYMAIL */ /* defines CLKTICK */

void *pmsgbody MSGENV *pmsgenv; TICKS timeout = (TICKS)500/CLKTICK; /* receive next message from any task */ if ((pmsgbody = KS_ReceiveMsgT (MYMAIL, &pmsgenv, TIMEBASE, timeout)) == (void *)0) { ... timeout occurred. Deal with it here. } else { ... message received, process it. KS_AckMsg (pmsgenv); /* signal sender */ }

See Also

KS_ReceiveMsg, page 200 KS_ReceiveMsgW, page 204

Chapter 6: Message Services

June 21, 2002

203

KS_ReceiveMsgW

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

Synopsis Inputs

Description

void * KS_ReceiveMsgW (MBOX mbox, MSGENV **pmsgenv)

mbox

A handle for the mailbox from which the message is being received.

pmsgenv

A pointer to a message envelope pointer.

The KS_ReceiveMsgW kernel service reads a message from the mailbox specified in mbox and returns a pointer to the message body. A pointer to the message envelope pointer is given by pmsgenv. These two pointers give complete access to the message for both processing and acknowledgment. The messages are processed in the sequence they occur in the mailbox, as specified by the mailbox’s attributes. If the mailbox is empty, the service blocks the requesting task and waits for the mailbox to receive the next message.

Output

This service returns a pointer to the body of the received message.

Errors

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

FE_ILLEGAL_MBOX if the specified mailbox ID is not valid. FE_UNINITIALIZED_MBOX if the specified mailbox has not yet

been initialized.

Example

204

June 21, 2002

The task in Example 6-5 on page 205 receives the next available message from the MYMAIL mailbox. If there is no mail available, the task is to wait until a message is sent to the mailbox.

RTXC Kernel Services Reference, Volume 2

KS_ReceiveMsgW

Example 6-5. Receive Message—Wait If Necessary #include "rtxcapi.h" #include "kmbox.h"

/* RTXC Kernel Services prototypes */ /* defines MYMAIL */

void *pmsgbody; MSGENV *pmsgenv; /* receive next message from any task */ pmsgbody = KS_ReceiveMsgW (MYMAIL, &pmsgenv); ..continue

See Also

KS_ReceiveMsg, page 200 KS_ReceiveMsgT, page 202

Chapter 6: Message Services

June 21, 2002

205

KS_SendMsg

KS_SendMsg Send a message to a mailbox asynchronously.

Synopsis Inputs

Description

void KS_SendMsg (MBOX mbox, MSGENV *pmsgenv, void *pmsgbody, MSG_PRIORITY priority)

mbox

A handle for the mailbox to which the message is being sent.

pmsgenv

A pointer to the message envelope.

pmsgbody

A pointer to the body of the message.

priority

The priority of the message.

The KS_SendMsg kernel service sends a message asynchronously to the mailbox specified in mbox. The message envelope must be in RAM with its address pointed to by pmsgenv. The pmsgbody argument points to the body of the message, which can be in RAM or ROM. Each message has a user-defined priority of either URGENT_MSG or NORMAL_MSG. If the sending or forwarding task does not explicitly define the priority (priority =(MSG_PRIORITY)0), the kernel assigns the message a priority of NORMAL_MSG. Using the message priority, the kernel adds each message to the specified mailbox. Messages of NORMAL_MSG priority are added to the mailbox in chronological (FIFO) order. For messages having an URGENT_MSG priority, the kernel adds them at the front of the list of messages in the mailbox (LIFO order). When sending or forwarding a message to a mailbox, there may or may not be a task waiting to receive it. If not, the kernel adds the message to the mailbox according to the message’s priority. If a task is waiting to receive a message from the mailbox, the kernel passes the message directly to the receiving task and unblocks it. If, as a result, the receiving task becomes ready to run, the kernel places it in the Ready List at a position determined by its priority. If the receiving task’s priority is higher than that of the sending or forwarding task, a preemption occurs.

206

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_SendMsg

After putting the message into the mailbox or passing it on to a waiting receiver, the kernel service is complete. This kernel service never blocks the sending task even though the sending task may be preempted.

Output

This service does not return a value.

Errors

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

FE_ILLEGAL_MBOX if the specified mailbox ID is not valid. FE_UNINITIALIZED_MBOX if the specified mailbox has not yet

been initialized.

Example

`

FE_INVALID_MSG_PRIORITY if the specified message priority value is not either URGENT or NORMAL.

`

FE_NULL_MSGENV if the pointer to the message envelope is null.

Example 6-6 on page 208 sends a message asynchronously at NORMAL priority to the MAILBOX3 static mailbox. The message is in a structure named msgbody. After sending the message, the example performs other operations and waits for the completion of processing of the message.

Chapter 6: Message Services

June 21, 2002

207

KS_SendMsg

Example 6-6. Send Message—Wait for Acknowledgment #include "rtxcapi.h" #include "kmbox.h"

/* RTXC Kernel Services prototypes */ /* defines MAILBOX3 */

MSGENV msgenv;

/* Message envelope (required) */

struct { int command; char data[10]; } msgbody;

/* start of message body */

... fill in message body content /* send message to MAILBOX3 at a priority of NORMAL_MSG */ KS_SendMsg (MAILBOX3, &msgenv, &msgbody, NORMAL_MSG); ... do some more processing and then wait for the event associated with completion of message processing /* wait for message acknowledgment */ KS_TestAckW (&msgenv); ... continue

See Also

208

June 21, 2002

KS_SendMsgT, page 209 KS_SendMsgW, page 213 KS_TestAck, page 216 KS_TestAckT, page 218 KS_TestAckW, page 220

RTXC Kernel Services Reference, Volume 2

KS_SendMsgT

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

Synopsis Inputs

Description

KSRC KS_SendMsgT (MBOX mbox, MSGENV *pmsgenv, void *pmsgbody, MSG_PRIORITY priority, COUNTER counter, TICKS ticks)

mbox

A handle for the mailbox to which to send the message.

pmsgenv

A pointer to the message envelope.

pmsgbody

A pointer to the body of the message.

priority

The priority value of the message.

counter

The counter associated with the interval defined by ticks.

ticks

The number of ticks on counter to wait for an acknowledgment.

The KS_SendMsgT kernel service sends a message synchronously to the mailbox specified in mbox. The message envelope must be in RAM with its address pointed to by pmsgenv. The pmsgbody argument points to the body of the message, which can be in RAM or ROM. Each message has a user-defined priority of either URGENT_MSG or NORMAL_MSG. If the sending or forwarding task does not explicitly define the priority (priority =(MSG_PRIORITY)0), the kernel assigns the message a priority of NORMAL_MSG. Using the message priority, the kernel adds each message to the specified mailbox. Messages of NORMAL_MSG priority are added to the mailbox in chronological (FIFO) order. For messages having an URGENT_MSG priority, the kernel adds them at the front of the list of messages in the mailbox (LIFO order). When sending or forwarding a message to a mailbox, there may or may not be a task waiting to receive it. If not, the kernel adds the message to the mailbox according to the message’s priority. If a task is waiting to receive a message from the mailbox, the kernel passes the message directly to the receiving task and unblocks it. If, as a

Chapter 6: Message Services

June 21, 2002

209

KS_SendMsgT

result, the receiving task becomes ready to run, the kernel places it in the Ready List at a position determined by its priority. If the receiving task’s priority is higher than that of the sending or forwarding task, a preemption occurs. After putting the message into the mailbox or passing it on to a waiting receiver, the kernel service blocks the sending task and starts an internal alarm for the interval specified in ticks on the specified counter. The task remains blocked until one of the following conditions occurs: `

The receiving task acknowledges receipt of the message.

`

The specified number of ticks elapses.

`

The service returns a value indicating the form of completion.

Note: A duration of zero (0) ticks does not cause an internal alarm to be started and is, therefore, equivalent to the KS_SendMsgW service.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the message is successfully sent and processed

within the specified timeout duration. `

RC_TICKOUT if the specified number of ticks elapses and the message has not been received, that is, the message is still in the mailbox. If this situation occurs, the kernel removes the message from the mailbox.

`

RC_NO_ACK if the specified number of ticks elapses and the

message has been received but not yet acknowledged, that is, the message is not in the mailbox.

Errors

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

FE_ILLEGAL_MBOX if the specified mailbox ID is not valid. FE_UNINITIALIZED_MBOX if the specified mailbox has not yet

been initialized. `

210

June 21, 2002

FE_ILLEGAL_COUNTER if the specified counter ID is not valid.

RTXC Kernel Services Reference, Volume 2

KS_SendMsgT

`

FE_UNINITIALIZED_COUNTER if the specified counter has not

yet been initialized.

Example

`

FE_INVALID_MSG_PRIORITY if the specified message priority value is not either URGENT or NORMAL.

`

FE_NULL_MSGENV if the pointer to the message envelope is null.

In Example 6-7 on page 212, the task synchronously sends a message to the MAILBOX3 static mailbox with an envelope address specified in msgenv and a message body in the msgbody structure. The priority of the message is URGENT. If the acknowledgment takes longer than 250 msec using the TIMEBASE counter, the example handles the situation with a special code segment.

Chapter 6: Message Services

June 21, 2002

211

KS_SendMsgT

Example 6-7. Send Message—Wait Number of Ticks for Acknowledgment #include "rtxcapi.h" #include "kmbox.h" #include "kproject.h"

/* RTXC Kernel Services prototypes */ /* defines MAILBOX3 */ /* defines CLKTICK */

TICKS timeout = (TICKS)250/CLKTICK; MSGENV msgenv; /* Message envelope (required) */ KSRC status; struct { int command; char data[10]; } msgbody;

/* start of message body */

...fill in message body content /* Send message synchronously to MAILBOX3 at priority URGENT */ /* Wait up to 250 ms for message to be processed */ if ((status = (KS_SendMsgT (MAILBOX3, &msgenv, &msgbody, URGENT, TIMEBASE, timeout)) == RC_GOOD) { ... message sent and processed successfully } else { ... message not completed within alarm period if (status == RC_NO_ACK) KS_TestAckW (&msgenv); /* wait until ack occurs */ else ...timeout occurred and msg was removed from mailbox ...Decide whether or not to re-send the msg }

See Also

212

June 21, 2002

KS_TestAck, page 216 KS_TestAckT, page 218 KS_TestAckW, page 220 KS_SendMsg, page 206 KS_SendMsgW, page 213

RTXC Kernel Services Reference, Volume 2

KS_SendMsgW

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

Synopsis Inputs

Description

void KS_SendMsgW (MBOX mbox, MSGENV *pmsgenv, void *pmsgbody, MSG_PRIORITY priority)

mbox

A handle for the mailbox to which the message is being sent.

pmsgenv

A pointer to the message envelope.

pmsgbody

A pointer to the body of the message.

priority

The priority value of the message.

The KS_SendMsgW kernel service sends a message synchronously to the mailbox specified in mbox. The message envelope must be in RAM with its address pointed to by pmsgenv. The pmsgbody argument points to the body of the message, which can be in RAM or ROM. Each message has a user-defined priority of either URGENT_MSG or NORMAL_MSG. If the sending or forwarding task does not explicitly define the priority (priority =(MSG_PRIORITY)0), the kernel assigns the message a priority of NORMAL_MSG. Using the message priority, the kernel adds each message to the specified mailbox. Messages of NORMAL_MSG priority are added to the mailbox in chronological (FIFO) order. For messages having an URGENT_MSG priority, the kernel adds them at the front of the list of messages in the mailbox (LIFO order). When sending or forwarding a message to a mailbox, there may or may not be a task waiting to receive it. If not, the kernel adds the message to the mailbox according to the message’s priority. If a task is waiting to receive a message from the mailbox, the kernel passes the message directly to the receiving task and unblocks it. If, as a result, the receiving task becomes ready to run, the kernel places it in the Ready List at a position determined by its priority. If the receiving task’s priority is higher than that of the sending or forwarding task, a preemption occurs.

Chapter 6: Message Services

June 21, 2002

213

KS_SendMsgW

After putting the message into the mailbox or passing it on to a waiting receiver, the kernel service blocks the sending task until the receiving task acknowledges it.

Output

This service does not return a value.

Errors

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

FE_ILLEGAL_MBOX if the specified mailbox ID is not valid. FE_UNINITIALIZED_MBOX if the specified mailbox has not yet

been initialized.

Example

`

FE_INVALID_MSG_PRIORITY if the specified message priority value is not either URGENT or NORMAL.

`

FE_NULL_MSGENV if the pointer to the message envelope is null.

In Example 6-8, the task synchronously sends a message to the MAILBOX3 static mailbox using an envelope located at the address given by the content of msgenv and whose body is contained in the msgbody structure. The priority of the message is NORMAL.

Example 6-8. Send Message—Wait for Acknowledgment #include "rtxcapi.h" #include "kmbox.h" MSGENV msgenv; struct { int command; char data[10]; } msgbody;

/* RTXC Kernel Services prototypes */ /* defines MAILBOX3 */

/* Message envelope (required) */ /* start of message body */

... fill in the message body content /* send message synchronously to MAILBOX3 at priority */ /* NORMAL_MSG and wait for the message to be processed */ KS_SendMsgW (MAILBOX3, &msgenv, &msgbody, NORMAL_MSG); ... continue after message is acknowledged

214

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_SendMsgW

See Also

KS_SendMsg, page 206 KS_SendMsgT, page 209

Chapter 6: Message Services

June 21, 2002

215

KS_TestAck

KS_TestAck Test for message acknowledgment.

Synopsis Input

KSRC KS_TestAck (MSGENV *pmsgenv)

pmsgenv

A pointer to a message envelope.

Description

The KS_TestAck kernel service tests the message whose envelope is pointed to by pmsgenv to determine if the message has been acknowledged. The service returns an indication of the state of the acknowledgment.

Output

This service returns a value of type KSRC as follows: `

RC_GOOD if the message has been acknowledged.

`

RC_NOT_RECEIVED if the message is still in the mailbox.

`

RC_NO_ACK if the message is not in the mailbox but has not yet

been acknowledged.

Error

This service may generate the following fatal error code: FE_NULL_MSGENV if the pointer to the message envelope is null.

Example

216

June 21, 2002

Example 6-9 on page 217 sends a message asynchronously, does some other processing, then polls to determine if the message has been acknowledged. If the service determines that the acknowledgment has not occurred, the example delays for five ticks of the TIMEBASE counter before polling again.

RTXC Kernel Services Reference, Volume 2

KS_TestAck

Example 6-9. Test for Message Acknowledgment #include "rtxcapi.h" #include "kmbox.h"

/* RTXC Kernel Services prototypes */ /* defines MAILBOX3 */

MSGENV msgenv;

/* Message envelope (required) */

struct { int command; char data[10]; } msgbody;

/* start of message body */

... fill in the message body content /* send message asynchronously to MAILBOX3 at */ /* NORMAL_MSG priority */ KS_SendMsg (MAILBOX3, &msgenv, &msgbody, NORMAL_MSG); ... do some other processing /* test now to see if message has been acknowledged */ while (KS_TestAck (&msgenv) != RC_GOOD) { KS_SleepTask (TIMEBASE, (TICKS)5); } ... continue after message is acknowledged

See Also

KS_TestAckT, page 218 KS_TestAckW, page 220 KS_AckMsg, page 194

Chapter 6: Message Services

June 21, 2002

217

KS_TestAckT

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

Synopsis Inputs

Description

KSRC KS_TestAckT (MSGENV *pmsgenv, COUNTER counter, TICKS ticks)

pmsgenv

A pointer to a message envelope.

counter

The counter associated with the interval defined by ticks.

ticks

The number of ticks on the specified counter to wait for an acknowledgment.

The KS_TestAckT kernel service tests the message whose envelope is pointed to by pmsgenv to determine if the message has been acknowledged. If the message has been acknowledged, the service returns a KSRC value of RC_GOOD. If the message has not been acknowledged, the kernel service blocks the Current Task and starts an internal alarm for the interval specified in ticks on the specified counter. The task remains blocked until either of two conditions occur:

Output

`

The message is acknowledged by a receiving task, or

`

The specified number of ticks elapses.

This service returns a KSRC value as follows: `

RC_GOOD if the message has been acknowledged.

`

RC_TICKOUT if the specified number of ticks elapses before the message is acknowledged and the message is still in the mailbox. If this situation occurs, the kernel removes the message from the mailbox.

`

RC_NO_ACK if the timeout expires and the message is not in the

mailbox but has not yet been acknowledged.

218

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_TestAckT

Errors

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

FE_NULL_MSGENV if the pointer to the message envelope is null.

`

FE_ILLEGAL_COUNTER if the specified counter ID is not valid.

`

FE_UNINITIALIZED_COUNTER if the specified counter has not

yet been initialized.

Example

Example 6-10 sends a message asynchronously and tests for message acknowledgment. If the service determines that the acknowledgment has not occurred, it waits for no more than five ticks on the TIMEBASE counter.

Example 6-10. Test for Message Acknowledgment—Wait Number of Ticks for Acknowledgment #include "rtxcapi.h" #include "kmbox.h"

/* RTXC Kernel Services prototypes */ /* defines MAILBOX3 */

MSGENV msgenv;

/* Message envelope (required) */

struct { int command; char data[10]; } msgbody;

/* start of message body */

... fill in the message body content /* send message asynchronously to MAILBOX3 at NORMAL_MSG priority*/ KS_SendMsg (MAILBOX3, &msgenv, &msgbody, NORMAL_MSG); if (KS_TestAckT (&msgenv, TIMEBASE, (TICKS)5) != RC_GOOD) { ... internal counter expired. Deal with it here. } ... continue when message is acknowledged

See Also

KS_TestAck, page 216 KS_TestAckW, page 220 KS_AckMsg, page 194

Chapter 6: Message Services

June 21, 2002

219

KS_TestAckW

KS_TestAckW Test for message acknowledgment and wait for the acknowledgment.

Synopsis Input

void KS_TestAckW (MSGENV *pmsgenv)

pmsgenv

Description

A pointer to a message envelope.

The KS_TestAckW kernel service tests the message whose envelope is pointed to by pmsgenv to determine if the message has been acknowledged. If the message has been acknowledged, the service returns control to the Current Task. If the message has not been acknowledged, the kernel service causes the calling task to be blocked until the message is acknowledged.

Output

This service does not return a value.

Error

This service may generate the following fatal error code: FE_NULL_MSGENV if the pointer to the message envelope is null.

Example

220

June 21, 2002

Example 6-11 on page 221 sends a message asynchronously, does some other processing, and then tests the message to determine if it has been acknowledged. If the service determines that the message has not been acknowledged, it waits for it.

RTXC Kernel Services Reference, Volume 2

KS_TestAckW

Example 6-11. Test for Acknowledgment and Wait if Necessary #include "rtxcapi.h" #include "kmbox.h"

/* RTXC Kernel Services prototypes */ /* defines MAILBOX3 */

MSGENV msgenv;

/* Message envelope (required) */

struct { int command; char data[10]; } msgbody;

/* start of message body */

... fill in the message body content /* send message asynchronously to MAILBOX3 at NORMAL_MSG priority*/ KS_SendMsg (MAILBOX3, &msgenv, &msgbody, NORMAL_MSG); ... do some processing before testing for acknowledgment /* wait if message not acknowledged */ KS_TestAckW (&msgenv); ... continue after message is acknowledged

See Also

KS_TestAck, page 216 KS_TestAckT, page 218 KS_AckMsg, page 194

Chapter 6: Message Services

June 21, 2002

221

KS_TestAckW

222

June 21, 2002

RTXC Kernel Services Reference, Volume 2

CHAPTER

7

Memory Partition Services

In This Chapter We describe the Partition kernel services in detail. The Partition services 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. 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

Chapter 7: Memory Partition Services

June 21, 2002

223

XX_AllocBlk

XX_AllocBlk Allocate a block of memory.

Zones

IS_AllocBlk TS_AllocBlk KS_AllocBlk

Synopsis Inputs

void * XX_AllocBlk (PART part)

part

A handle for a partition.

Description

The XX_AllocBlk kernel service allocates the next available block of memory from the partition specified in part and returns its address to the caller.

Output

This service returns a pointer to the allocated memory block. If there are no available blocks in the given partition, the partition is empty and the service returns a null pointer ((void *)0).

Errors

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

FE_ILLEGAL_PART if the specified partition ID is not valid. FE_UNINITIALIZED_PART if the specified partition has not yet

been initialized.

Example

224

June 21, 2002

In Example 7-1 on page 225, the caller needs a block of memory from the PART1 memory partition. If the allocation is successful, the pointer to the block is to be stored in the p character pointer. If there are no free blocks in the partition, the task must handle that situation.

RTXC Kernel Services Reference, Volume 2

XX_AllocBlk

Example 7-1. Allocate Block of Memory #include "rtxcapi.h" #include "kpart.h"

/* RTXC Kernel Service prototypes */ /* defines PART1 */

char *p; if ((p = (char *)KS_AllocBlk (PART1)) == (char *) 0) { ... Deal with no memory available } else { ... Allocation was successful }

See Also

KS_AllocBlkT, page 226 KS_AllocBlkW, page 228

Chapter 7: Memory Partition Services

June 21, 2002

225

KS_AllocBlkT

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

Synopsis Inputs

Description

void * KS_AllocBlkT (PART part, COUNTER counter, TICKS ticks)

part

A handle for a partition.

counter

The counter associated with the interval defined by ticks.

ticks

The number of ticks on the specified counter to wait for an available block of memory.

The KS_AllocBlkT kernel service allocates the next available block of memory from the partition specified in part and returns its address to the caller. If there is no available block in the memory partition, the service blocks the requesting task with a PARTITION_WAIT. At the same time, the service starts an internal alarm for the interval specified in ticks on the specified counter. The task remains blocked until either of two events occurs: `

A memory block in the specified partition becomes available, or

`

The specified number of ticks elapses.

If a block becomes available, the service returns the address of the allocated memory block to the caller. If, however, the specified number of ticks elapses and causes the task to resume, the service returns a null pointer ((void *)0).

Output

This service returns a pointer to the allocated memory block. If the specified number of ticks elapses before there is memory to allocate, the service returns a null pointer ((void *)0).

Errors

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

226

June 21, 2002

FE_ILLEGAL_PART if the specified partition ID is not valid.

RTXC Kernel Services Reference, Volume 2

KS_AllocBlkT

`

FE_UNINITIALIZED_PART if the specified partition has not yet

been initialized. `

FE_ILLEGAL_COUNTER if the specified counter ID is not valid.

`

FE_UNINITIALIZED_COUNTER if the specified counter has not

yet been initialized.

Example

Example 7-2 allocates a block of memory from the PART1 partition to be used for a character buffer. It stores the address of the block in the p character pointer. If there is no memory available at the time of the request, the example uses TIMEBASE to wait for a period of 50 msec for a block to become available before proceeding. If there is no memory available after 50 msec, it handles the situation with a special code segment.

Example 7-2. Allocate Block of Memory—Wait Number of Ticks If Necessary #include "rtxcapi.h" #include "kproject.h" #include "kpart.h"

/* RTXC Kernel Service prototypes */ /* defines CLKTICK */ /* defines PART1 */

char *p; /* no return until requested memory is available */ /* or until internal alarm expires. */ p = (char *)KS_AllocBlkT (PART1, TIMEBASE, (TICKS)50/CLKTICK); if (p == (char *)0) { ... internal alarm expired, deal with it } else { ... Memory allocated. Proceed. }

See Also

XX_AllocBlk, page 224 KS_AllocBlkW, page 228

Chapter 7: Memory Partition Services

June 21, 2002

227

KS_AllocBlkW

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

Synopsis Input

void * KS_AllocBlkW (PART part)

part

Description

A handle for a partition.

The KS_AllocBlkW kernel service allocates the next available block of memory from the partition specified in part and returns its address to the caller. If there is no available block in the memory partition, the service blocks the requesting task with a PARTITION_WAIT until memory in the specified partition becomes available.

Output

This service returns a pointer to the allocated memory block.

Errors

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

FE_ILLEGAL_PART if the specified partition ID is not valid. FE_UNINITIALIZED_PART if the specified partition has not yet

been initialized.

Example

228

June 21, 2002

In Example 7-3 on page 229, the Current Task allocates a block of memory from PART1 to be used for a character buffer and stores the address of the string in the p character pointer. If there is no memory available at the time of the request, the example waits for it to become available before proceeding. Upon successful allocation of the memory block, the task continues.

RTXC Kernel Services Reference, Volume 2

KS_AllocBlkW

Example 7-3. Allocate Block of Memory—Wait If Necessary #include "rtxcapi.h" #include "kpart.h"

/* RTXC Kernel Service prototypes */ /* defines PART1 */

char *p; /* no return until requested memory is available */ p = (char *)KS_AllocBlkW (PART1); ...continue

See Also

XX_AllocBlk, page 224 KS_AllocBlkT, page 226

Chapter 7: Memory Partition Services

June 21, 2002

229

KS_ClosePart

KS_ClosePart End the use of a dynamic partition.

Synopsis Input

KSRC KS_ClosePart (PART part)

part

Description

The handle for the partition being closed.

The KS_ClosePart kernel service ends the Current Task’s use of the dynamic memory partition specified in part. When closing the partition, the kernel detaches the caller’s use of it. If the caller is the last user of the partition, the kernel releases the partition to the free pool of dynamic partitions for reuse. If there is at least one other task still using the partition, the kernel does not release the partition to the free pool but the service completes successfully. You should not close a dynamic memory partition if there are tasks waiting on any of the partition’s events. Note: To use this service, you must enable the Dynamics attribute of the Partition class during system generation.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the service is successful.

`

RC_STATIC_OBJECT if the specified partition is not dynamic.

`

RC_OBJECT_NOT_INUSE if the specified partition does not

correspond to an active dynamic partition. `

RC_OBJECT_INUSE if the Current Task’s use of the specified partition is closed but the partition remains open for use by other tasks.

Note: RC_OBJECT_INUSE does not necessarily indicate an error condition. The calling task must interpret its meaning.

230

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_ClosePart

Error

This service may generate the following fatal error code: FE_ILLEGAL_PART if the specified partition ID is not valid.

Example

In Example 7-4, the Current Task waits on a signal from another task indicating that it is time to close a dynamic memory partition. The handle of the dynamic partition is specified in dynpart. When the signal is received, the Current Task closes the memory partition.

Example 7-4. Close Memory Partition #include "rtxcapi.h"

/* RTXC Kernel Service prototypes */

PART dynpart; SEMA dynsema; KS_TestSemaW (dynsema);

/* wait for signal */

/* then close the partition */ if (KS_ClosePart (dynpart) != RC_GOOD) { /* something is possibly wrong. Deal with it here */ } ... partition is closed. Continue

See Also

KS_OpenPart, page 254 KS_UsePart, page 256

Chapter 7: Memory Partition Services

June 21, 2002

231

KS_DefPartName

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

Synopsis Inputs

Description

KSRC KS_DefPartName (PART part, const char *pname)

part

The handle of the partition being defined.

pname

A pointer to a null-terminated name string.

The KS_DefPartName kernel service names or renames the dynamic partition specified in part. The service uses the nullterminated string pointed to by pname for the partition’s new name. Static partitions cannot be named or renamed under program control. Note: To use this service, you must enable the Dynamics attribute of the Partition class during system generation.

This service does not check for duplicate partition names.

Output

This service returns a KSRC value as follows: `

RC_GOOD if the service completes successfully.

`

RC_STATIC_OBJECT if the memory partition being named is

static. `

RC_OBJECT_NOT_FOUND if the Dynamics attribute of the

Partition class is not enabled. `

RC_OBJECT_NOT_INUSE if the specified partition does not

correspond to an active dynamic partition.

Error

This service may generate the following fatal error code: FE_ILLEGAL_PART if the specified partition ID is not valid.

232

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_DefPartName

Example

Example 7-5 assigns the name NewPart to the partition whose handle is in the dynpart variable so other users may reference it by name.

Example 7-5. Assign Memory Partition Name #include "rtxcapi.h"

/* RTXC Kernel Service prototypes */

PART dynpart; if ((KS_DefPartName (dynpart, "NewPart")) != RC_GOOD) { ... something may be wrong. Deal with it here } ... naming operation was successful. Continue

See Also

KS_OpenPart, page 254 KS_GetPartName, page 244 KS_LookupPart, page 252 KS_UsePart, page 256

Chapter 7: Memory Partition Services

June 21, 2002

233

KS_DefPartProp

KS_DefPartProp Define the properties of a partition.

Synopsis Inputs

Description

void KS_DefPartProp (PART part, const PARTPROP *ppartprop)

part

The handle of the partition being defined.

ppartprop

A pointer to a Partition properties structure.

The KS_DefPartProp kernel service defines the properties of the memory partition specified in part using the values contained in the PARTPROP structure pointed to by ppartprop. Members of the PARTPROP structure specify the current attributes of the partition, the base address of RAM used as the body of the memory partition, the size of the blocks in the partition, and the number of blocks. The PARTPROP structure has the following organization:

typedef struct { KATTR attributes; char *base; ksize_t size; KCOUNT count; } PARTPROP;

/* /* /* /*

Waiting Order */ root of free pool list */ number of bytes in a block */ initial number of blocks in partition */

You may define the following partition attribute value: Waiting Order

Indicates the ordering of tasks waiting for memory from the partition. The default order is by priority. Waiting Order can be changed to chronological ordering by ORing the ATTR_FIFO_ORDER constant into the attributes field. The default value for the Waiting Order attribute can be restored by ANDing the attributes field with ~ATTR_FIFO_ORDER.

234

June 21, 2002

RTXC Kernel Services Reference, Volume 2

KS_DefPartProp

The value of size, the block size argument, must be at least the size of a data pointer.

Output

This service does not return a value.

Error

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

FE_ILLEGAL_PART if the specified partition ID is not valid.

`

FE_NULL_PARTBASE if the specified partition base address is

null. `

FE_ZERO_PARTSIZE if the specified partition size is zero.

`

FE_ZERO_PARTCOUNT if the specified partition block count is

zero.

Example

During system initialization, the startup code must create and initialize the Partition object class and define all of the static partitions to the system before beginning multitasking operations, as shown in Example 7-6.

Example 7-6. Define Memory Partition Properties #include "rtxcapi.h"

/* RTXC Kernel Service prototypes */

extern const KCLASSPROP partclassprop; extern const PARTPROP partprop[]; int objnum; if ((ksrc = INIT_PartClassProp (&partclassprop)) != RC_GOOD) { printf ("Partition initialization failed: %d", ksrc); } for (objnum = 1; objnum