100% found this document useful (1 vote)

663 views351 pages

RTXC Kernel ServicesV2 Decrypted

Q: Could enabling the Dynamics attribute in system generation impact queue and mutex operations, and if so, how?

Enabling the Dynamics attribute impacts mutex and queue operations significantly. For mutex operations, it allows the allocation and naming of dynamic mutexes, enabling functionalities such as `KS_OpenMutx` and `KS_UseMutx`, which handle dynamic mutex names and their registration for task use . The time to perform operations like acquiring a mutex varies with the number of mutex names in use if the pointer to the mutex name is not null . For queues, similarly, enabling the Dynamics attribute is necessary for operations like `KS_OpenQueue` and `KS_UseQueue`, which manage dynamic queue names and registration . The time required to search and handle queues is affected by the number of names in use when the queue name pointer is not null . Therefore, enabling this attribute is crucial for handling dynamic allocation, naming, and efficient use of mutexes and queues.

Q: What risks are involved in using the FE_INVALID_MSG_PRIORITY error in mailbox services?

The use of the FE_INVALID_MSG_PRIORITY error in mailbox services involves several risks: 1. Incorrect interpretation of mailbox properties: When determining task waiting order, prioritizing tasks incorrectly due to misconfigured attributes can cause tasks to be deprived of receiving messages in the intended sequence. If tasks rely on priority for processing, a mistake in this setup can lead to unexpected behavior or reduced efficiency . 2. Improper error handling: Incorrect handling of the FE_ILLEGAL_MBOX error, which indicates an invalid mailbox ID, can cause system crashes or undefined behavior, as these errors must be recognized and properly addressed to maintain system stability . 3. Limited dynamic resources: Mismanagement or failure to properly handle errors related to dynamic mailboxes could result in the system running out of available mailboxes, leading to unsuccessful operations or potential deadlocks in communication processes .

Q: How does the KS_DefQueueName service handle duplicate names, and what impact could this have on queue management?

The KS_DefQueueName service allows for naming or renaming a dynamic queue using a specified name but does not check for duplicate names . This lack of duplication checks means that multiple dynamic queues can be assigned the same name, which could lead to confusion and difficulty in identifying and managing specific queues when performing operations like queue lookups or deletions .

Q: What would be the consequences of not verifying the existence of a queue before attempting to use KS_GetQueueName?

Not verifying the existence of a queue before using KS_GetQueueName can result in the following consequences: If the queue ID is invalid or does not correspond to an active queue, this could trigger a fatal error code (FE_ILLEGAL_QUEUE), resulting in the operation failing to fetch the queue name . Additionally, if the queue has not been initialized, attempts to use it may also generate an error (FE_UNINITIALIZED_QUEUE). Therefore, failing to verify the queue's existence can lead to errors and unsuccessful operation of the KS_GetQueueName function.

Q: What is the potential impact of using the KS_ReceiveMsg service if no message is available in the specified mailbox?

The potential impact of using the KS_ReceiveMsg service when no message is available in the specified mailbox is that the service returns a null pointer ((void *)0) to indicate the absence of messages. This allows the task to identify that no message was present and execute code to handle this situation . Similar guidance is provided in examples where, if no message is available, special code is executed to manage this condition .

Q: In what ways does the KS_GetQueueProp service facilitate observation of queue characteristics?

The KS_GetQueueProp service facilitates observation of queue characteristics by retrieving all the property values of a specified queue and storing them in a QUEUEPROP structure. These properties include the queue's base address, width, maximum depth, current size, and attributes, such as the waiting order (by priority or FIFO). This provides a comprehensive view of queue characteristics in a single operation, aiding in queue management and task synchronization .

Q: Discuss the implications of incorrectly handling QMessage envelopes in a KSPutQueueDataW system.

Incorrect handling of QMessage envelopes in a KSPutQueueDataW system can lead to several problems. If a queue ID is not valid, if the queue is not initialized, or if the source buffer is null, the system may generate fatal errors such as FE_ILLEGAL_QUEUE, FE_UNINITIALIZED_QUEUE, and FE_NULL_SORUCEBUFFER, respectively . A full queue will cause the KSPutQueueDataW service to block the current task until space is available, which can delay other processes waiting for execution . Additionally, mishandling could prevent data from being moved into the queue or cause the system to wait indefinitely if the condition to progress is not met .

Q: What method does the KS_CloseQueue service provide for dealing with queue-full and queue-empty conditions?

The KS_CloseQueue service does not directly address queue-full and queue-empty conditions. Instead, it focuses on ending the use of a dynamic queue by detaching the caller's use of it, and if the caller is the last user, releasing the queue back to the free pool for reuse . The Queue services manage queue-full and queue-empty conditions through automatic synchronization . This process involves task synchronization to wait until the queue has room when full or has data when empty, utilizing other queue services such as KS_PutQueueDataT or KS_GetQueueDataW , but KS_CloseQueue itself simply ends the association of the queue without managing these conditions.

Q: Explain how the KS_DefQueueProp service enhances the management of task queueing order.

The KS_DefQueueProp service enhances the management of task queueing order by allowing the definition of queue properties, including the order in which tasks wait for access to the queue. The service, through the QUEUEPROP structure, defaults the waiting order to task priority, but this can be changed to a chronological order by incorporating the ATTR_FIFO_ORDER constant into the attributes field . This flexibility in modifying the waiting order ensures that queue task management can be tailored to specific use cases, thereby optimizing task execution in various system conditions .

Q: How can the KS_OpenMutx service prevent the problem of running out of dynamic mutexes?

The KS_OpenMutx service prevents the exhaustion of dynamic mutexes by enabling allocation, naming, and obtaining the handle of a dynamic mutex only when a dynamic mutex is available and there is no existing mutex with a matching name. If a matching name already exists or all dynamic mutexes are in use, the service does not allocate a new mutex and returns an indication of an unsuccessful operation, thus preventing the risk of running out of dynamic mutexes . Additionally, enabling the Dynamics attribute of the Mutex class during system generation allows for the allocation of dynamic mutexes as needed, which can help manage and allocate resources efficiently .

Quadros Systems, Inc. Makes no representations or warranties with respect to the contents or use of this manual. Quadros systems, Inc. Specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transmitted without the express written consent of the publisher.

Uploaded by

Vladimir Rolbin

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

100% found this document useful (1 vote)

663 views351 pages

RTXC Kernel ServicesV2 Decrypted

Uploaded by

Vladimir Rolbin

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 351

Quadros

Systems Inc.

RTXC Kernel Services Reference, Volume 2

Tasks, Semaphores, Queues, Mailboxes, Messages, Memory Partitions, and Mutexes

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

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

CHAPTER 2

Contents

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 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 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 Message Services..............................................................................193 KS_AckMsg................................................................................194 KS_ForwardMsg ........................................................................196 KS_ReceiveMsg .........................................................................200

CHAPTER 5

CHAPTER 6

Contents

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

CHAPTER 8

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 Fatal Error Codes ..............................................................................317

APPENDIX A

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

Contents

vii

viii

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

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

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

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 SemaphoreWait Number of Ticks for Signal .................... 109 Test List of Semaphores .................................................................. 111 Test List of SemaphoresWait Number of Ticks for Signal ....... 114 Test List of SemaphoresWait for Signal..................................... 117 Test SemaphoreWait 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 EntryWait Number of Ticks If Necessary............. 139 Read Queue EntryWait 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 QueueWait Number of Ticks If Queue is Full .. 159

xii

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 QueueWait 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 MessageWait Number of Ticks If Necessary................203 Receive MessageWait If Necessary .............................................205 Send MessageWait for Acknowledgment...................................208 Send MessageWait Number of Ticks for Acknowledgment .....212 Send MessageWait for Acknowledgment...................................214 Test for Message Acknowledgment ................................................217 Test for Message AcknowledgmentWait Number of Ticks for Acknowledgment .......................................................219 Test for Acknowledgment and Wait if Necessary ..........................221 Allocate Block of Memory................................................................225 Allocate Block of MemoryWait Number of Ticks If Necessary.227 Allocate Block of MemoryWait 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

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

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 MutexWait Number of Ticks If Not Available ................... 292 Test MutexWait 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

xiv

RTXC Kernel Services Reference, Volume 2

CHAPTER

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

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

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 processors 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 Zones Synopsis Inputs Description Outputs Brief Functional Description The zonal prefixes supported by the service (IS_, TS_, KS_), if more than one.a The formal ANSI C declaration including argument prototyping. A brief description of each input argument. A complete description of what the service does, the data types it uses, and so on. A description of each argument modified by the service and each possible return value from the service. 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.

Example

Chapter 1: Introduction To RTXC/ms Kernel Services

Using This Manual

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

Name See Also Special Notes Brief Functional Description A list of related kernel services, if any, that could be examined in conjunction with the current function. 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_ TS_ KS_ Identifies a service callable from an exception handler in Zone 1. Identifies a thread-based service callable from Zone 2. 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:
<Verb><Class>[noun|property][suffix]

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

Using This Manual

description lists and describes the fatal errors that may be generated by the service. For a complete list of the error codes and the services that generate those codes, see Appendix A, Fatal Error Codes.
Table 1-2. Kernel Service Return Value Types
Symbol TASK THREAD PRIORITY TSLICE SEMA SEMACOUNT MBOX MSGENV QUEUE PART BLKSIZE MUTX EVNTSRC COUNTER ALARM TICKS EXCPTN KSRC Description Task handle Thread handle Priority of a task or a message Number of TICKS in the time quantum for a timesliced task Semaphore handle Number of signals that a semaphore has received Mailbox handle Message envelope Queue handle Memory partition handle Size of a block of memory in a partition Mutex handle Event Source handle Counter handle Alarm handle Units of time maintained by the system time base Exception handle 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 Semaphores Queues Mailboxes 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

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 KS_AbortTask KS_CloseTask KS_DefTaskEnvArg KS_DefTaskName KS_DefTaskPriority KS_DefTaskProp KS_DefTaskSema KS_DefTickSlice KS_DisableTaskScheduler KS_EnableTaskScheduler Description Abort the execution of a task. End the use of a dynamic task. Define the environment arguments for a task. Define the name of a previously opened dynamic task. Define a new priority for a task. Define the properties of a task. Associate a semaphore with the termination or abortion of a task. Define the tick-slice quantum for a task. Disable the task scheduler to prevent task context switching. Enable the scheduler to allow context switching between tasks. Zones Ref. 23 25 27 30 32 34 36 38 40 41

RTXC Kernel Services Reference, Volume 2

RTXC/ms Component Services

Table 1-3. Task Services Summary (continued)

Service KS_ExecuteTask KS_GetTaskEnvArg KS_GetTaskClassProp KS_GetTaskID KS_GetTaskName KS_GetTaskPriority KS_GetTaskProp KS_GetTaskSema KS_GetTaskState KS_GetTickSlice INIT_TaskClassProp KS_LookupTask KS_OpenTask XX_ResumeTask KS_SleepTask KS_SuspendTask KS_TerminateTask KS_UseTask KS_YieldTask Description Execute a task. Get the address of a tasks environment arguments. Get the Task object class properties. Get the handle of the Current Task. Get the name of a task. Get the priority of a task. Get the properties of a task. Get the handle of the semaphore associated with the termination or abortion of a task. Get the state of a task. Get the tick-slice quantum of a task. Initialize the Task object class properties. Look up a tasks name to get its handle. Allocate and name a dynamic task. Resume a task that was previously suspended. Put the Current Task to sleep for a period of time. Suspend a task. Terminate a task. Look up a dynamic task by name and mark it for use. Yield to the next ready task of the same priority. Zones Ref. 42 44 47 50 51 53 54 56 58 60 62 64 66 68 70 71 72 74 76

Chapter 1: Introduction To RTXC/ms Kernel Services

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 KS_CloseSema KS_DefSemaCount KS_DefSemaName Description End the use of a dynamic semaphore. Define a semaphore count. Define the name of a previously opened dynamic semaphore. Define the properties of a semaphore. Get the Semaphore object class properties. Get the current semaphore count. Get the name of a semaphore. Get the properties of a semaphore. Initialize the Semaphore object class properties. Look up a semaphores name to get its handle. Allocate and name a dynamic semaphore. Signal a semaphore. Signal multiple semaphores. Test a semaphore. Test a semaphore and wait for a specified number of ticks on a specified counter if the semaphore is not DONE. Zones Ref. 80 82 84 86 88 90 92 94 96 98 100 102 104 106 108

KS_DefSemaProp KS_GetSemaClassProp KS_GetSemaCount KS_GetSemaName KS_GetSemaProp INIT_SemaClassProp KS_LookupSema KS_OpenSema XX_SignalSema XX_SignalSemaM KS_TestSema KS_TestSemaT

RTXC Kernel Services Reference, Volume 2

RTXC/ms Component Services

Table 1-4. Semaphore Services Summary (continued)

Service KS_TestSemaM KS_TestSemaMT Description Test a list of semaphores. Test a list of semaphores and wait a specified number of ticks for a signal. Test a list of semaphores and wait for a signal. Test a semaphore and wait if the semaphore is not DONE. Look up a dynamic semaphore by name and mark it for use. Zones Ref. 110 112 115 118 120

KS_TestSemaMW KS_TestSemaW

KS_UseSema

Chapter 1: Introduction To RTXC/ms Kernel Services

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 KS_CloseQueue KS_DefQueueName Description End the use of a dynamic queue. Define the name of a previously opened dynamic queue. Define the properties of a queue. Associate a semaphore with a queue condition event. Get the Queue object class properties. Get the next entry from a queue. 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. Get the next entry from a queue. If the queue is empty, wait for an entry to become available. Get the name of a queue. Get the properties of a queue. Get the semaphore handle associated with a queue event. Initialize the Queue object class properties. Zones Ref. 124 126 128 130 134 136 138

KS_DefQueueProp KS_DefQueueSema

KS_GetQueueClassProp KS_GetQueueData KS_GetQueueDataT

KS_GetQueueDataW

140 142 144 146 148

KS_GetQueueName KS_GetQueueProp KS_GetQueueSema

INIT_QueueClassProp

RTXC Kernel Services Reference, Volume 2

RTXC/ms Component Services

Table 1-5. Queue Services Summary (continued)

Service KS_LookupQueue KS_OpenQueue KS_PutQueueData KS_PutQueueDataT Description Look up a queues name to get its handle. Allocate and name a dynamic queue. Put an entry into a queue. 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. Put an entry into a queue. If the queue is full, wait for the queue to have room for the entry. Look up a dynamic queue by name and mark it for use. Zones Ref. 150 152 156 158

KS_PutQueueDataW

160 162

KS_UseQueue

Chapter 1: Introduction To RTXC/ms Kernel Services

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 KS_CloseMbox KS_DefMboxName Description End the use of a dynamic mailbox. Define the name of a previously opened dynamic mailbox. Define the properties of a mailbox. Associate a semaphore with the Mailbox_Not_Empty event. Get the Mailbox object class properties. Get the name of a mailbox. Get the properties of a mailbox. Get the semaphore handle associated with a Mailbox_Not_Empty event. Initialize the Mailbox object class properties. Look up a mailboxs name to get its handle. Allocate and name a dynamic mailbox. Look up a dynamic mailbox by name and mark it for use. Zones Ref. 166 168 170 172 176 178 180 182 184 186 188 191

KS_DefMboxProp KS_DefMboxSema

KS_GetMboxClassProp KS_GetMboxName KS_GetMboxProp KS_GetMboxSema

INIT_MboxClassProp KS_LookupMbox KS_OpenMbox KS_UseMbox

RTXC Kernel Services Reference, Volume 2

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 KS_AckMsg KS_ReceiveMsg KS_ReceiveMsgT Description Acknowledge a message. Receive a message from a mailbox. Receive a message from a mailbox. If the mailbox is empty, wait a specified number of ticks for a message. Receive a message from a mailbox. If the mailbox is empty, wait for a message. Send a message to a mailbox asynchronously. Send a message to a mailbox synchronously and wait for a specified time for an acknowledgment. Send a message to a mailbox synchronously and wait for an acknowledgment. Test for message acknowledgment. Test for message acknowledgment and wait for a specified number of ticks for the acknowledgment. Test for message acknowledgment and wait for the acknowledgment. Zones Ref. 194 200 202 204 206 209 213 216 218 220

KS_ReceiveMsgW

KS_SendMsg KS_SendMsgT

KS_SendMsgW

KS_TestAck KS_TestAckT

KS_TestAckW

Chapter 1: Introduction To RTXC/ms Kernel Services

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 XX_AllocBlk KS_AllocBlkT Description Allocate a block of memory. Allocate a block of memory. If the partition is empty, wait for a specified number of ticks for an available block. Allocate a block of memory. If the partition is empty, wait for an available block. End the use of a dynamic partition. Define the name of a previously opened dynamic memory partition. Define the properties of a partition. Associate a semaphore with the Partition_Not_Empty event. Free a block of memory. Get the number of free blocks in a partition. Get the Memory Partition object class properties Get the name of a partition. Get the properties of a partition. Zones Ref. 224 226

KS_AllocBlkW

228 230 232 234 236 238 240 242 244 246

KS_ClosePart KS_DefPartName

KS_DefPartProp KS_DefPartSema

KS_FreeBlk KS_GetFreeBlkCount KS_GetPartClassProp KS_GetPartName KS_GetPartProp

RTXC Kernel Services Reference, Volume 2

RTXC/ms Component Services

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

Service KS_GetPartSema Description Get the semaphore associated with the Partition_Not_Empty event. Initialize the Partition object class properties. Look up a partitions name to get its handle. Allocate and name a dynamic partition. Look up a dynamic partition by name and mark it for use. Zones Ref. 248 250 252 254 256

INIT_PartClassProp KS_LookupPart KS_OpenPart KS_UsePart

Chapter 1: Introduction To RTXC/ms Kernel Services

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 KS_CloseMutx KS_DefMutxName KS_DefMutxProp KS_DefMutxSema Description End the use of a dynamic mutex. Define the name of a previously opened mutex. Define the properties of a mutex. Associate a semaphore with the Mutex_Not_Busy event. Get the Mutex object class properties. Get the name of a mutex. Get the owner of a mutex. Get the properties of a mutex. Get the semaphore handle associated with the Mutex_Not_Busy event. Initialize the Mutex object class properties. Look up a mutexs name to get its handle. Allocate and name a dynamic mutex. Release ownership of a mutex. Test the availability of a mutex and lock it if it is not busy. Zones Ref. 260 262 264 267 270 272 274 276 278 280 282 284 286 288

KS_GetMutxClassProp KS_GetMutxName KS_GetMutxOwner KS_GetMutxProp KS_GetMutxSema

INIT_MutxClassProp KS_LookupMutx KS_OpenMutx KS_ReleaseMutx KS_TestMutx

RTXC Kernel Services Reference, Volume 2

RTXC/ms Component Services

Table 1-9. Mutex Services Summary (continued)

Service KS_TestMutxT Description 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. Test the availability of a mutex. If the mutex is busy, wait for it to become available and then lock it. Look up a dynamic mutex by name and mark it for use. Zones Ref. 290

KS_TestMutxW

294 296

KS_UseMutx

Chapter 1: Introduction To RTXC/ms Kernel Services

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 XX_AllocSysRAM XX_DefFatalErrorHandler XX_GetFreeSysRAMSize XX_GetFatalErrorHandler KS_GetSysProp KS_GetVersion INIT_SysProp KS_Nop Description Allocate a block of system RAM. Establish the system error function. Get the size of free system RAM. Get the system error function. Get the system properties. Get the version number of the Kernel. Initialize the RTXC system properties. Execute the minimal path through the kernel dispatcher (no operation). Perform a user-defined kernel service. Zones Ref. 300 302 304 305 306 308 310 313 314

KS_UserService

RTXC Kernel Services Reference, Volume 2

CHAPTER

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

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

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

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); KS_TerminateTask (SELFTASK); /* RTXC Kernel Service prototypes */ /* defines TASKBX */ /* abort task TASKBX */ /* now terminate self */

See Also

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 Tasks use of the dynamic task specified in task. When closing the task, the kernel detaches the callers 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 Tasks 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

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" TASK dyntask; SEMA dynsema; KS_TestSemaW (dynsema); /* RTXC Kernel Service prototypes */ /* not SELFTASK (TASK)0 */ /* 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

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

void KS_DefTaskEnvArg (TASK task, const void *parg)

task parg

The number of the task being defined. A pointer to the environment arguments structure for the task.

Description

The KS_DefTaskEnvArg kernel service establishes a pointer to a structure containing parameters that define the environment of the task specified in task. The RTXC Kernel places no restrictions on the size or content of the environment structure. The service requires a task number and a pointer, parg, to the environment arguments structure for the specified task.
Note: To use this service, you must enable the Environment Arguments attribute of the Task class during system generation.

Output Errors

This service does not return a value. 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 tasks 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

KS_DefTaskEnvArg

After defining the dynamic tasks 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" #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; /* RTXC Kernel Service prototypes */ /* Memory Partitions */

if (KS_OpenTask ((char *)0, &dyntask) != RC_GOOD) { ... Deal with problem with dynamic task allocation } else { /* allocate space for tasks 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); }

RTXC Kernel Services Reference, Volume 2

KS_DefTaskEnvArg

See Also

KS_DefTaskProp, page 34 KS_GetTaskEnvArg, page 44

Chapter 2: Task Services

KS_DefTaskName

KS_DefTaskName
Define the name of a previously opened dynamic task.

Synopsis Inputs

KSRC KS_DefTaskName (TASK task, const char *pname)

task pname

The number of the task being defined. A pointer to a null-terminated name string.

Description

The KS_DefTaskName kernel service names or renames the dynamic task specified in task. The service uses the null-terminated string pointed to by pname for the tasks 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.

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" 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 /* RTXC Kernel Service prototypes */

See Also

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

Chapter 2: Task Services

KS_DefTaskPriority

KS_DefTaskPriority
Define a new priority for a task.

Synopsis Inputs

void KS_DefTaskPriority (TASK task, PRIORITY priority)

task priority

The number of the task being defined. The priority value for the task.

Description

The KS_DefTaskPriority kernel service defines or changes the priority of task. The new priority may be any legal priority, either higher or lower than the tasks 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 Tasks assigned priority. The Current Task may specify itself with a task value of zero (0). If task is not the Current Task, a preemption occurs if the new priority of task is higher than that of the requesting task and task is in the Ready List. If task is in one or more priority-ordered wait lists, its position in those lists may change to reflect its new priority.

Output Errors

initialized.

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

KS_DefTaskProp

KS_DefTaskProp
Define the properties of a task.

Synopsis Inputs

void KS_DefTaskProp (TASK task, const TASKPROP *ptaskprop)

task ptaskprop

The number of the task being defined. A pointer to a Task properties structure.

Description

The KS_DefTaskProp kernel service defines the properties of the specified task by using the values contained in the TASKPROP structure pointed to by ptaskprop. If task is not in the inactive state, this function returns without making any changes to the properties of task. You may use this service on static or dynamically allocated tasks. It is typically used to define a static task during system startup or a dynamic task during runtime that has been previously allocated with the KS_OpenTask kernel service. Legal priority values are {1, 2, 126}. (Note that 0 is not a legal priority value). Example 2-6 shows the organization of the TASKPROP structure.

Example 2-6. Task Properties Structure

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

/* /* /* /*

initial initial initial initial

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

Output Error

This service does not return a value. This service may generate one of the following fatal error codes:
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.
FE_ZERO_STACKSIZE if the specified Task stack size is zero.

Example

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

Example 2-7. Define Task Object Class Properties

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

extern const KCLASSPROP taskclassprop; extern const TASKPROP taskprop[]; KSRC ksrc; int objnum; if ((ksrc = INIT_TaskClassProp (&taskclassprop)) != RC_GOOD) { printf ("Task class initialization failed %d", ksrc); return (ksrc); } for (objnum = 1; objnum <= taskclassprop.n_statics; objnum++) KS_DefTaskProp (objnum, &taskprop[objnum]);

See Also

KS_GetTaskProp, page 54 INIT_TaskClassProp, page 62 KS_OpenTask, page 66

Chapter 2: Task Services

KS_DefTaskSema

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

Synopsis Inputs

void KS_DefTaskSema (TASK task, SEMA sema)

task sema

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

Description

The KS_DefTaskSema kernel service associates the semaphore specified in sema with the termination and abortion events of the specified task, when sema is to be used in a subsequent test using the KS_TestSema kernel service or one of its variants. The service signals the semaphore when task is terminated or aborted.
Note: To use this service, you must enable the Semaphores attribute of the Task class during system generation.

Output Errors

initialized.
FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.

Example

In Example 2-8 on page 37, the Current Task has nothing to do until the TASKA task gets terminated or aborted. To synchronize with this event, the Current Task defines the GOSEMA semaphore for TASKA and then waits for that semaphore.

RTXC Kernel Services Reference, Volume 2

KS_DefTaskSema

Example 2-8. Define Task Termination Semaphore

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

KS_DefTaskSema (TASKA, GOSEMA); KS_TestSemaW (GOSEMA); ... TASKA ended, begin processing now

See Also

KS_GetTaskSema, page 56 KS_TestSema, page 106 KS_TestSemaT, page 108 KS_TestSemaW, page 118 KS_TestSemaM, page 110 KS_TestSemaMT, page 112 KS_TestSemaMW, page 115

Chapter 2: Task Services

KS_DefTickSlice

KS_DefTickSlice
Define the tick-slice quantum for a task.

Synopsis Inputs

void KS_DefTickSlice (TASK task, TSLICE ticks)

task ticks

The number of the task being defined. The number of clock ticks in the tick-slice quantum.

Description

The KS_DefTickSlice kernel service defines the number of ticks the specified task is permitted to run before it is forced to yield under tick-sliced scheduling. The service requires a task number and a tick-slice quantum, ticks, as arguments. The tick quantum period is specified as a value of TSLICE type giving the number of clock ticks approximating the desired duration of the tick-slice quantum. A task number of zero (0) specifies the Current Task. You can change the tick quantum at any time. If tick-slicing is not in operation for task (quantum = zero (0)) and ticks is non-zero, task immediately begins tick-sliced operation. A ticks value of zero (0) causes task to cease tick-sliced operation immediately. However, if tick slicing is already in effect, a new tick quantum does not take effect until the current tick quantum expires. If you must alter the quantum immediately, change the quantum to zero (0) and then to the desired value.
Note: To use this service, you must enable the Tick Slice attribute of the Task class during system generation.

Output Errors

This service does not return a value. This service may generate one of the following fatal error codes:
FE_ILLEGAL_TASK if the specified task ID is not valid.

RTXC Kernel Services Reference, Volume 2

KS_DefTickSlice

FE_UNINITIALIZED_TASK if the specified task has not yet been

initialized.

Example

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

Example 2-9. Define Tick Slice

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

/* define tick slice quantum as 100 ms */ KS_DefTickSlice (SELFTASK, (TSLICE)100/CLKTICK); ... Task now in tick-sliced operation /* turn off tick-sliced operation */ KS_DefTickSlice (SELFTASK, (TSLICE)0);

See Also

KS_GetTickSlice, page 60

Chapter 2: Task Services

KS_DisableTaskScheduler

KS_DisableTaskScheduler
Disable the task scheduler to prevent task context switching.

Synopsis Inputs Description

void KS_DisableTaskScheduler (void)

This service has no inputs. The KS_DisableTaskScheduler kernel service disables the kernel scheduler, which in turn prevents context switching between tasks. With context switching turned off, a task can execute without being preempted. Interrupts are not disabled, but a context switch does not occur. When an application makes nested calls to KS_DisableTaskScheduler, preemption does not resume until an equal number of KS_EnableTaskScheduler calls are made. This service does not return a value. Example 2-10 executes a section of code without being preempted.

Output Example

Example 2-10. Disable Task Scheduler

#include "rtxcapi.h" /* RTXC Kernel Services prototypes */ /* prevent preemption */

KS_DisableTaskScheduler (); ...perform some function

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

See Also

KS_EnableTaskScheduler, page 41

RTXC Kernel Services Reference, Volume 2

KS_EnableTaskScheduler

KS_EnableTaskScheduler
Enable the scheduler to allow context switching between tasks.

Synopsis Inputs Description

void KS_EnableTaskScheduler (void)

This service has no inputs. The KS_EnableTaskScheduler kernel service enables the RTXC/ms Scheduler, which in turn permits task context switching to occur. If the application makes nested calls to KS_DisableTaskScheduler, then it must make an equal number of calls to KS_EnableTaskScheduler before context switching (preemption) starts again. The RTXC Kernel enables the scheduler by default during system initialization.

Output Example

This service does not return a value. In Example 2-11, after performing some critical function with the scheduler disabled, the Current Task enables the scheduler.

Example 2-11. Enable Task Scheduler

#include "rtxcapi.h" /* RTXC Kernel Services prototypes */ /* prevent preemption */

KS_DisableTaskScheduler (); ...perform some function

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

See Also

KS_DisableTaskScheduler, page 40

Chapter 2: Task Services

KS_ExecuteTask

KS_ExecuteTask
Execute a task.

Synopsis Input Description

KSRC KS_ExecuteTask (TASK task)

task

The number of the task to execute.

The KS_ExecuteTask kernel service starts a specified task from its beginning address. The task must be in the INACTIVE state. If so, it is inserted into the Ready List with its program counter (PC) and stack pointer (SP) initialized to their starting values. The tasks starting address, initial priority, and stack pointer are specified during system generation or dynamically with the KS_DefTaskProp kernel service. If task is of higher priority than the requesting (current) task, a context switch is performed and the new task runs. If task is of lower or equal priority, control is returned to the caller.
Warning: A task value of zero (0) indicates self-execution. This is not advisable.

Output

This service returns a KSRC value as follows:

RC_GOOD if the task starts successfully. RC_TASK_NOT_INACTIVE if the specified task is in a state other than INACTIVE.

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-12 on page 43, the Current Task starts the SHUTDOWN static task from its starting address.

RTXC Kernel Services Reference, Volume 2

KS_ExecuteTask

Example 2-12. Execute Task

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

/* execute SHUTDOWN task */ if (KS_ExecuteTask (SHUTDOWN) != RC_GOOD) { ...task is not started because it is not in INACTIVE state } ...task successfully started executing

See Also

KS_TerminateTask, page 72

Chapter 2: Task Services

KS_GetTaskEnvArg

KS_GetTaskEnvArg
Get the address of a tasks environment arguments.

Synopsis Input Description

void * KS_GetTaskEnvArg (TASK task)

task

The number of the task being queried.

The KS_GetTaskEnvArg kernel service obtains a pointer to the structure containing the environment arguments for the specified task. To request the environment arguments for the Current Task, set task to zero (0). Any task may use this kernel service to get environment arguments that have been previously defined to the RTXC Kernel by the KS_DefTaskEnvArg service. Dynamic tasks use this service because they typically have an associated environment argument structure to specify the parameters they need for operation.
Note: To use this service, you must enable the Environment Arguments attributes of the Task class during system generation.

Output

This service returns a pointer to the specified tasks environment argument structure. If no such definition has been made, the service returns a null pointer ((void *)0). 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

Errors

initialized.

Example

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

RTXC Kernel Services Reference, Volume 2

KS_GetTaskEnvArg

should operate. It does this by obtaining the data from its environment argument structure, which contains the port and channel identifiers. The environment argument structure has been previously defined. While the example below is simple, it demonstrates some of the basic concepts in organizing a task that is dynamically allocated, defined, and executed. In contrast to a static task, the dynamic task is typically used in situations where each instance of the task serves one particular purpose. In this example, the purpose is to handle a single communications port and the channel on that port. Because other instances of the same task may already be in operation on other ports and channels, the task must determine who it is and what critical data it needs for operation. That data should be found in the tasks environment argument structure, the content of which was probably filled by the task that spawned the Current Task.

Chapter 2: Task Services

KS_GetTaskEnvArg

Example 2-13. Read Task Environment Arguments

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

void commchnl (void) { struct myargs { int port; /* port number */ int chnl; /* channel number */ }; struct myargs *envargs; int chnlstat; /* port/channel status */ /* first find out where to get the */ /* environment arguments */ envargs = KS_GetTaskEnvArg (SELFTASK); while ((chnlstat = get_chnl_stat (envargs->port, envargs->chnl)) != 0) { ... while the status is non zero, do some work with the port and channel to process the data stream } /* terminate when the status is 0 */ KS_TerminateTask (SELFTASK); }

See Also

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

KS_GetTaskClassProp

Table 2-1. Task Class Attributes and Masks

Attribute Static Names Dynamics Tick Slice Environment Arguments Task Semaphores Mask ATTR_STATIC_NAMES ATTR_DYNAMICS ATTR_TICKSLICE ATTR_TASK_ENV ATTR_TASK_SEMAPHORES

Output

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

Example

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

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

KS_GetTaskID

KS_GetTaskID
Get the handle of the Current Task.

Synopsis Inputs Description

TASK KS_GetTaskID (void)

This service has no inputs. 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. This service returns the handle of the Current Task. Example 2-15 gets the task number of the Current Task and outputs it to the console.

Output Example

Example 2-15. Read Current Task Number

#include <stdio.h> #include "rtxcapi.h" static char buf[128]; TASK mytaskid; mytaskid = KS_GetTaskID (); sprintf (buf, "Current Task ID is %d", mytaskid); putline (buf); /* standard i/o */ /* RTXC Kernel Service prototypes */

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 Example

This service may generate the following fatal error code:

FE_ILLEGAL_TASK if the specified task ID is not valid.

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

KS_GetTaskName

Example 2-16. Read Dynamic Task Name

#include <stdio.h> #include "rtxcapi.h" 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); /* standard i/o */ /* RTXC Kernel Service prototypes */

See Also

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 Description

PRIORITY KS_GetTaskPriority (TASK task)

task

The number of the task being queried.

The KS_GetTaskPriority kernel service obtains the current priority of the specified task. A task value of zero (0) specifies the Current Task. This service returns the priority of the specified task. 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

Output Errors

initialized.

Example

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

Example 2-17. Read and Change Task Priority

#include "rtxcapi.h" PRIORITY mypri; mypri = KS_GetTaskPriority (SELFTASK); /* raise Current Tasks priority by 2 */ KS_DefTaskPriority (SELFTASK, mypri - 2); /* RTXC Kernel Service prototypes */

See Also

KS_DefTaskPriority, page 32

Chapter 2: Task Services

KS_GetTaskProp

KS_GetTaskProp
Get the properties of a task.

Synopsis Inputs

void KS_GetTaskProp (TASK task, TASKPROP *ptaskprop)

task ptaskprop

The number of the task being queried. A pointer to a task property structure.

Description

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 Errors

This service returns the properties of the task in the property structure pointed to by ptaskprop. 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-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 tasks 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" 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); } /* RTXC Kernel Service prototypes */ /* defines BLK256 */

See Also

KS_DefTaskProp, page 34

Chapter 2: Task Services

KS_GetTaskSema

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

Synopsis Input Description

SEMA KS_GetTaskSema (TASK task)

task

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

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

KS_GetTaskState

KS_GetTaskState
Get the state of a task.

Synopsis Input Description Output

KSRC KS_GetTaskState (TASK task)

task

The number of the task being queried.

The KS_GetTaskState kernel service obtains the state of the static or dynamic task specified in task. 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

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

KS_GetTickSlice

KS_GetTickSlice
Get the tick-slice quantum of a task.

Synopsis Input Description

TSLICE KS_GetTickSlice (TASK task)

task

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 Errors

This service returns the specified tasks tick-slice quantum in units of system clock ticks as a TSLICE type value. 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 tasks 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);

RTXC Kernel Services Reference, Volume 2

KS_GetTickSlice

See Also

KS_DefTickSlice, page 38

Chapter 2: Task Services

INIT_TaskClassProp

INIT_TaskClassProp
Initialize the Task object class properties.

Synopsis Input Description

KSRC INIT_TaskClassProp (const KCLASSPROP *pclassprop)

pclassprop

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.

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

KS_LookupTask

KS_LookupTask
Look up a tasks name to get its handle.

Synopsis Inputs

KSRC KS_LookupTask (const char pname, TASK ptask)

pname ptask

A pointer to the null-terminated name string for the task. A pointer to a variable in which to store the matching tasks handle, if found.

Description

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.

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 <stdio.h> #include "rtxcapi.h" 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); } /* standard i/o */ /* RTXC Kernel Service prototypes */

See Also

KS_DefTaskName, page 30 KS_OpenTask, page 66

Chapter 2: Task Services

KS_OpenTask

KS_OpenTask
Allocate and name a dynamic task.

Synopsis Inputs

KSRC KS_OpenTask (const char pname, TASK ptask)

pname ptask

A pointer to the null-terminated name string for the task. A pointer to a variable in which to store the allocated tasks handle.

Description

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.

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.

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

Example

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

Example 2-25. Allocate Dynamic Task

#include "rtxcapi.h" 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 } /* RTXC Kernel Service prototypes */

See Also

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

Chapter 2: Task Services

XX_ResumeTask

XX_ResumeTask
Resume a task that was previously suspended.

Zones

IS_ResumeTask TS_ResumeTask KS_ResumeTask

void XX_ResumeTask (TASK task)

Synopsis Input Description

task

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 Errors

initialized.

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" KS_SuspendTask (AIREADER); ... perform some operations KS_ResumeTask (AIREADER); /* resume task AIREADER */ /* RTXC Kernel Service prototypes */ /* defines AIREADER */ /* suspend task AIREADER */

See Also

KS_SuspendTask, page 71

Chapter 2: Task Services

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 ticks

The counter associated with the interval defined by ticks. The number of ticks the Current Task should sleep.

Description Output Example

The KS_SleepTask kernel service blocks the Current Task for the specified number of ticks. This service does not return a value. 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);

RTXC Kernel Services Reference, Volume 2

KS_SuspendTask

KS_SuspendTask
Suspend a task.

Synopsis Input Description

void KS_SuspendTask (TASK task)

task

The number of the task to suspend.

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). This service does not return a value. 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

Output Errors

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" KS_SuspendTask (LKDETECT); KS_SuspendTask (SELFTASK); /* RTXC Kernel Service prototypes */ /* defines LKDETECT */ /* suspend LKDETECT task */ /* suspend self */

See Also

XX_ResumeTask, page 68 KS_ExecuteTask, page 42

Chapter 2: Task Services

KS_TerminateTask

KS_TerminateTask
Terminate a task.

Synopsis Input Description

void KS_TerminateTask (TASK task)

task

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 objects list of waiters. If task is waiting on a kernel object with an associated alarm, it is removed from that objects 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 Errors

initialized.

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" KS_TerminateTask (TASKBX); KS_TerminateTask (SELFTASK); /* RTXC Kernel Service prototypes */ /* defines TASKBX */ /* terminate task TASKBX */ /* now terminate self */

See Also

KS_CloseTask, page 25 KS_ExecuteTask, page 42

KS_DefTaskSema, page 36

Chapter 2: Task Services

KS_UseTask

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

Synopsis Inputs

KSRC KS_UseTask (const char pname, TASK ptask)

pname ptask

A pointer to a null-terminated name string. A pointer to a variable in which to store the tasks handle, if found.

Description

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

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 <stdio.h> #include "rtxcapi.h" 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); } /* standard i/o */ /* RTXC Kernel Service prototypes */

See Also

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

Chapter 2: Task Services

KS_YieldTask

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

Synopsis Inputs Description

KSRC KS_YieldTask (void)

This service has no inputs. 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:

RC_GOOD if the yield is successful. RC_NO_YIELD if no yield can occur.

Example

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

KS_YieldTask

RTXC Kernel Services Reference, Volume 2

CHAPTER

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

KS_CloseSema

KS_CloseSema
End the use of a dynamic semaphore.

Synopsis Input Description

KSRC KS_CloseSema (SEMA sema)

sema

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

The KS_CloseSema kernel service ends the Current Tasks use of the dynamic semaphore specified in sema. When closing the semaphore, the kernel detaches the calling tasks use of sema. If the caller is semas 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.

RC_OBJECT_INUSE if the Current Tasks 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 Example

This service may generate the following fatal error code:

FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.

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

KS_DefSemaCount

KS_DefSemaCount
Define a semaphore count.

Synopsis Inputs

void KS_DefSemaCount (SEMA sema, SEMACOUNT count)

sema count

The handle of the semaphore being defined. 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. This service does not return a value. 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

Output Errors

yet been initialized.

Example

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

KS_DefSemaName

KS_DefSemaName
Define the name of a previously opened dynamic semaphore.

Synopsis Inputs

KSRC KS_DefSemaName (SEMA sema, const char *pname)

sema pname

The handle of the semaphore being defined. A pointer to a null-terminated name string.

Description

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

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" SEMA dynsema; if (KS_DefSemaName (dynsema, "NewSema") != RC_GOOD) { ... Naming operation failed. Deal with it here } ... naming operation was successful. Continue /* RTXC Kernel Service prototypes */

See Also

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

Chapter 3: Semaphore Services

KS_DefSemaProp

KS_DefSemaProp
Define the properties of a semaphore.

Synopsis Inputs

void KS_DefSemaProp (SEMA sema, const SEMAPROP *psemaprop)

sema psemaprop

The handle of the semaphore being defined. A pointer to a semaphore properties structure.

Description

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

Signal Type

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.

RTXC Kernel Services Reference, Volume 2

KS_DefSemaProp

Output Error Example

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

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" 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 /* RTXC Kernel Service prototypes */

See Also

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

Chapter 3: Semaphore Services

KS_GetSemaClassProp

KS_GetSemaClassProp
Get the Semaphore object class properties.

Synopsis Input Description

const KCLASSPROP * KS_GetSemaClassProp (int *pint)

pint

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.

RTXC Kernel Services Reference, Volume 2

KS_GetSemaClassProp

Table 3-1. Semaphore Class Attributes and Masks

Attribute Static Names Dynamics Statistics Mask ATTR_STATIC_NAMES ATTR_DYNAMICS ATTR_STATISTICS

Output

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" 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 */ } /* RTXC Kernel Service prototypes */

See Also

INIT_SemaClassProp, page 96

Chapter 3: Semaphore Services

KS_GetSemaCount

KS_GetSemaCount
Get the current semaphore count.

Synopsis Input Description

SEMACOUNT KS_GetSemaCount (SEMA sema)

sema

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

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.

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.

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" SEMACOUNT count; if ((count = KS_GetSemaCount (AIDONE)) > (SEMACOUNT)0 ) { ... semaphore has been signaled, process something } else { ... no signals, do something else } /* RTXC Kernel Service prototypes */ /* defines AIDONE */

See Also

XX_SignalSema, page 102 KS_DefSemaCount, page 82

Chapter 3: Semaphore Services

KS_GetSemaName

KS_GetSemaName
Get the name of a semaphore.

Synopsis Input Description

char * KS_GetSemaName (SEMA sema)

sema

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 Example

This service may generate the following fatal error code:

FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.

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 <stdio.h> #include "rtxcapi.h" 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 */ /* standard i/o */ /* RTXC Kernel Service prototypes */

See Also

KS_DefSemaName, page 84 KS_OpenSema, page 100

Chapter 3: Semaphore Services

KS_GetSemaProp

KS_GetSemaProp
Get the properties of a semaphore.

Synopsis Inputs

void KS_GetSemaProp (SEMA sema, SEMAPROP *psemaprop)

sema psemaprop

The handle of the semaphore being queried. A pointer to the Semaphore properties structure in which to store the semaphores properties.

Description

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 Errors

This service returns the semaphores properties in the structure pointed to by psemaprop. 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

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" 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 /* RTXC Kernel Service prototypes */

See Also

KS_DefSemaProp, page 86

Chapter 3: Semaphore Services

INIT_SemaClassProp

INIT_SemaClassProp
Initialize the Semaphore object class properties.

Synopsis Input Description

KSRC INIT_SemaClassProp (const KCLASSPROP *pclassprop)

pclassprop

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

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" 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 } /* RTXC Kernel Service prototypes */

See Also

INIT_SysProp, page 310 KS_GetSemaClassProp, page 88

Chapter 3: Semaphore Services

KS_LookupSema

KS_LookupSema
Look up a semaphores name to get its handle.

Synopsis Inputs

KSRC KS_LookupSema (const char pname, SEMA psema)

pname psema

A pointer to a null-terminated name string. A pointer to a SEMA variable for storing the semaphore handle, if found.

Description

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

semaphores handle in the variable pointed to by psema.

RC_OBJECT_NOT_FOUND if the service finds no matching

semaphore name.

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" 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 } /* RTXC Kernel Service prototypes */

See Also

KS_DefSemaName, page 84 KS_OpenSema, page 100

Chapter 3: Semaphore Services

KS_OpenSema

KS_OpenSema
Allocate and name a dynamic semaphore.

Synopsis Inputs

KSRC KS_OpenSema (const char pname, SEMA psema)

pname psema

A pointer to a null-terminated name string. A pointer to a SEMA variable in which to store the allocated semaphores handle.

Description

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

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" 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 } /* RTXC Kernel Service prototypes */

See Also

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

Chapter 3: Semaphore Services

101

XX_SignalSema

XX_SignalSema
Signal a semaphore.

Zones

IS_SignalSema TS_SignalSema KS_SignalSema

void XX_SignalSema (SEMA sema)

Synopsis Input Description

sema

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 semas 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 Errors

This service does not return a value. 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

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" 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 /* RTXC Kernel Service prototypes */ /* defines CHARQ */ /* defines XOFF and XON */

See Also

XX_SignalSemaM, page 104

Chapter 3: Semaphore Services

103

XX_SignalSemaM

XX_SignalSemaM
Signal multiple semaphores.

Zones

IS_SignalSemaM TS_SignalSemaM KS_SignalSemaM

void XX_SignalSemaM (const SEMA *psemalist)

Synopsis Input Description

psemalist

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 Errors

yet been initialized.

104

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" const SEMA semalist[] = { SWITCH1, SWITCH2, CHNLDONE, (SEMA)0 } ... use multiplexor channel KS_SignalSemaM (semalist);/* signal multiple semaphores */ ... continue processing /* RTXC Kernel Service prototypes */ /*defines SWITCH1, SWITCH2, & CHNLDONE */

/* null terminator */

See Also

XX_SignalSema, page 102 KS_TestSemaM, page 110

Chapter 3: Semaphore Services

105

KS_TestSema

KS_TestSema
Test a semaphore.

Synopsis Input Description

KSRC KS_TestSema (SEMA sema)

sema

The handle of the semaphore to test.

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. This service returns a KSRC value as follows:
RC_GOOD if the service detects a signal (semaphore count was >

Output

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

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.

106

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

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

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

sema counter ticks

The handle of the semaphore to test. The counter associated with the tick interval defined by ticks. The number of ticks on the specified counter to wait for the signal.

Description

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 semas 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 semaphores count to decrement by one and the service returns to the calling task immediately.

Output

This service returns a KSRC value as follows:

RC_GOOD if a semaphore signal has occurred.

108

RTXC Kernel Services Reference, Volume 2

KS_TestSemaT

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

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-17, the Current Task needs to wait for a keypad character to be pressed, but it cant 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 SemaphoreWait 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

109

KS_TestSemaM

KS_TestSemaM
Test a list of semaphores.

Synopsis Input Description

SEMA KS_TestSemaM (const SEMA *psemalist)

psemalist

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

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

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 ticks

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

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

Description

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

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

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

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

114

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

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

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.

116

RTXC Kernel Services Reference, Volume 2

KS_TestSemaMW

Example 3-20. Test List of SemaphoresWait 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 */ KS_TestSema, page 106 KS_TestSemaM, page 110 KS_TestSemaMT, page 112 XX_SignalSema, page 102 XX_SignalSemaM, page 104

See Also

Chapter 3: Semaphore Services

117

KS_TestSemaW

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

Synopsis Input Description

void KS_TestSemaW (SEMA sema)

sema

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 Errors

yet been initialized.

Example

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.

118

RTXC Kernel Services Reference, Volume 2

KS_TestSemaW

Example 3-21. Test SemaphoreWait 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

119

KS_UseSema

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

Synopsis Inputs

KSRC KS_UseSema (const char pname, SEMA psema)

pname psema

A pointer to a null-terminated name string. A pointer to a SEMA variable for storing the semaphore handle, if found.

Description

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

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

120

RTXC Kernel Services Reference, Volume 2

KS_UseSema

Example 3-22. Read Semaphore Handle and Register It

#include "rtxcapi.h" 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 } /* RTXC Kernel Service prototypes */

See Also

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

Chapter 3: Semaphore Services

121

KS_UseSema

122

RTXC Kernel Services Reference, Volume 2

CHAPTER

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

123

KS_CloseQueue

KS_CloseQueue
End the use of a dynamic queue.

Synopsis Input Description

KSRC KS_CloseQueue (QUEUE queue)

queue

The handle of the queue to close.

The KS_CloseQueue kernel service ends the Current Tasks use of the specified dynamic queue. When closing the queue, the service detaches the callers 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.

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

124

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 Example

This service may generate the following fatal error code:

FE_ILLEGAL_QUEUE if the specified queue ID is not valid.

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" QUEUE dynqueue; SEMA dynsema; KS_TestSemaW (dynsema); KS_CloseQueue (dynqueue); /* RTXC Kernel Service prototypes */ /* handle of queue to be closed */ /* wait for signal */ /* then close the queue */

See Also

KS_OpenQueue, page 152 KS_UseQueue, page 162

Chapter 4: Queue Services

125

KS_DefQueueName

KS_DefQueueName
Define the name of a previously opened dynamic queue.

Synopsis Inputs

KSRC KS_DefQueueName (QUEUE queue, const char *pname)

queue pname

The handle of the queue being defined. A pointer to a null-terminated name string.

Description

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

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" QUEUE dynqueue; if (KS_DefQueueName (dynqueue, "NewQueue") != RC_GOOD) { ... Error in naming the queue. Deal with it here } ... naming operation was successful. Continue /* RTXC Kernel Service prototypes */

See Also

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

Chapter 4: Queue Services

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

This service does not return a value.

128

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

Example

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 <= queueclassprop.n_statics; objnum++) KS_DefQueueProp (objnum, &queueprop[objnum]);

See Also

KS_GetQueueProp, page 144 INIT_QueueClassProp, page 148 KS_OpenQueue, page 152

Chapter 4: Queue Services

129

KS_DefQueueSema

KS_DefQueueSema
Associate a semaphore with a queue condition event.

Synopsis Inputs

void KS_DefQueueSema (QUEUE queue, SEMA sema, QEVENT event)

queue sema event

The handle of the queue with which to associate the semaphore. The handle of the semaphore to associate with the queue. The queue event with which to associate the semaphore.

Description

The KS_DefQueueSema kernel service associates the semaphore specified in sema with an event, either Queue_Not_Empty (QNE) or Queue_Not_Full (QNF), of the specified queue. This action allows a task to synchronize with the occurrence of the queue event among a group of other events through the use of the KS_TestSemaM service or one of its variants. The Queue_Not_Empty and Queue_Not_Full events have enumerated values of QNE and QNF, respectively. You should use one of these values when specifying the event argument.
Note: To use this service, you must enable the Semaphores attribute of the Queue class during system generation.

You do not need to use a semaphores to synchronize with the queue events when using KS_GetQueueData, KS_PutQueueData or their variants. The RTXC Kernel provides that synchronization automatically and transparently.

Output Errors

This service does not return a value. This service may generate one of the following fatal error codes:
FE_ILLEGAL_QUEUE if the specified queue ID is not valid.

130

RTXC Kernel Services Reference, Volume 2

KS_DefQueueSema

FE_UNINITIALIZED_QUEUE if the specified queue 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.

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

Example

In Example 4-5 on page 132, the Current Task needs to associate the Queue_Not_Empty condition for the DATAQ1 and DATAQ2 queues with the GOT1 and GOT2 semaphores, respectively. Notice that the example does not check the return value of KS_GetQueueData. This procedure is acceptable because the example associates the QNE event with the semaphores. Because the QNE event indicates that data must be in the queue, the KSRC value of RC_QUEUE_EMPTY cannot occur.

Chapter 4: Queue Services

131

KS_DefQueueSema

Example 4-5. Associate Queue Event with Semaphore

#include "rtxcapi.h" #include "kqueue.h" #include "ksema.h" struct { int count; int values[8]; } entry; const SEMA semalist[] = { GOT1, GOT2, (SEMA)0 /* null terminated list */ }; SEMA cause; QEVENT event; KS_DefQueueSema (DATAQ1, GOT1, QNE); KS_DefQueueSema (DATAQ2, GOT2, QNE); cause = KS_TestSemaMW (semalist); switch (cause) { case GOT1: KS_GetQueueData (DATAQ1, &entry); ... do some processing break; case GOT2: KS_GetQueueData (DATAQ2, &entry); ... do some processing break; } /* end of switch */ ...continue /* RTXC Kernel Service prototypes */ /* defines DATAQ1 and DATAQ2 */ /* defines GOT1 and GOT2 */

132

RTXC Kernel Services Reference, Volume 2

KS_DefQueueSema

See Also

KS_GetQueueSema, page 146 KS_TestSema, page 106 KS_TestSemaT, page 108 KS_TestSemaW, page 118 KS_TestSemaM, page 110 KS_TestSemaMT, page 112 KS_TestSemaMW, page 115

Chapter 4: Queue Services

133

KS_GetQueueClassProp

KS_GetQueueClassProp
Get the Queue object class properties.

Synopsis Input Description

const KCLASSPROP * KS_GetQueueClassProp (int *pint)

pint

A pointer to a variable in which to store the number of available dynamic queues.

The KS_GetQueueClassProp kernel service obtains a pointer to the KCLASSPROP structure used by the INIT_QueueClassProp service during system initialization to initialize the Queue object class properties. If pint is not null ((int *)0), the service returns the number of available dynamic queues 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 Queue KCLASSPROP structure supports the class property attributes and masks listed in Table 4-1 on page 135.

Output

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

134

RTXC Kernel Services Reference, Volume 2

KS_GetQueueClassProp

Table 4-1. Queue Class Attributes and Masks

Attribute Static Names Dynamics Semaphores Mask ATTR_STATIC_NAMES ATTR_DYNAMICS ATTR_SEMAPHORES

Example

In Example 4-6, the Current Task needs access to the information contained in the KCLASSPROP structure for the Queue object class.

Example 4-6. Read Queue Object Class Properties

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

KCLASSPROP *pqueueclassprop; int free_dyn; /* Get the queue kernel object class properties */ if ((pqueueclassprop = KS_GetQueueClassProp (&free_dyn)) == (KCLASSPROP const *)0) { putline ("Queue Class not initialized"); } else { ... queue object class properties are available for use free_dyn contains the number of available dynamic queues }

See Also

INIT_QueueClassProp, page 148

Chapter 4: Queue Services

135

KS_GetQueueData

KS_GetQueueData
Get the next entry from a queue.

Synopsis Inputs

KSRC KS_GetQueueData (QUEUE queue, void *pdest)

queue pdest

The handle of the queue being queried. A pointer to the destination buffer.

Description

The KS_GetQueueData kernel service moves an entry from the specified queue to the destination buffer beginning at the address specified in pdest. Because the queue is a FIFO construct, this service moves the oldest entry from the queue. If the queue is empty, nothing can be moved from the queue and the service immediately returns a KSRC value with the appropriate indicator.

Output

This service returns a KSRC value of:

RC_GOOD if the service completes successfully. RC_QUEUE_EMPTY if the queue is empty at the time of the kernel

service request.

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_DESTBUFFER if the pointer to the destination buffer is

null.

Example

In Example 4-7 on page 137, the Current Task needs to get an entry containing several bytes of data from the DATAQ queue.

136

RTXC Kernel Services Reference, Volume 2

KS_GetQueueData

Example 4-7. Read Queue Entry

#include "rtxcapi.h" #include "kqueue.h" struct { int count; int values[8]; } entry; if (KS_GetQueueData (DATAQ1, &entry) == RC_GOOD) { ... do some processing } else { ... no data available, do something else } /* RTXC Kernel Service prototypes */ /* defines DATAQ1 */

See Also

KS_GetQueueDataT, page 138 KS_GetQueueDataW, page 140 KS_DefQueueSema, page 130

Chapter 4: Queue Services

137

KS_GetQueueDataT

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.

Synopsis Inputs

KSRC KS_GetQueueDataT (QUEUE queue, void *pdest, COUNTER counter, TICKS ticks)

queue pdest counter ticks

The handle of the queue being queried. A pointer to the destination buffer. The counter associated with the interval defined by ticks. The number of ticks on the specified counter to wait for a queue entry.

Description

The KS_GetQueueDataT kernel service moves an entry from the specified queue to the destination buffer beginning at the address specified in pdest. Because the queue is a FIFO construct, this service moves the oldest entry from the queue. If the queue is empty, 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 puts an entry into the queue through one of the kernel services, or The specified number of ticks elapses.

Output

This service returns a KSRC value of:

RC_GOOD if the service completes successfully. If pevent is not

null, the service stores the event indicators for any queue events that occur during the data movement in the variable pointed to by pevent.
RC_TICKOUT if the specified number of ticks elapses before the empty queue receives an entry.

138

RTXC Kernel Services Reference, Volume 2

KS_GetQueueDataT

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_DESTBUFFER if the pointer to the destination buffer is

null.

Example

Example 4-8 gets an entry from the DATAQ queue and stores it in the structure called entry. If DATAQ is empty, the task waits no longer than 250 msec relative to CLKCOUNTER for data to become available before proceeding.

Example 4-8. Read Queue EntryWait Number of Ticks If Necessary

#include #include #include #include "rtxcapi.h" "kqueue.h" "kcounter.h" "kproject.h" /* /* /* /* RTXC Kernel Service prototypes */ defines DATAQ */ defines CLKCOUNTER defines CLKTICK */

struct /* structure for receiving the dequeued entry */ int type; int value; } entry; /* get data from DATAQ */ if (KS_GetQueueDataT (DATAQ, &entry, CLKCOUNTER, (TICKS)250/CLKTICK) == RC_GOOD) { ... do something here with queue entry } else { ... wait counter expired. Deal with it here. }

See Also

KS_GetQueueData, page 136 KS_GetQueueDataW, page 140

Chapter 4: Queue Services

139

KS_GetQueueDataW

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

Synopsis Inputs

void KS_GetQueueDataW (QUEUE queue, void *pdest)

queue pdest

The handle of the queue being queried. A pointer to the destination buffer.

Description

The KS_GetQueueDataW kernel service moves an entry from the specified queue to the destination buffer beginning at the address specified in pdest. Because the queue is a FIFO construct, this service moves the oldest entry from the queue. If the queue is empty, the service blocks the Current Task. The Current Task remains blocked until a queue entry becomes available.

Output Errors

This service does not return a value. 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_DESTBUFFER if the pointer to the destination buffer is

null.

Example

Example 4-9 on page 141 gets an entry from the DATAQ static queue and stores it in the structure called entry. If DATAQ is empty, the task waits for data to become available before proceeding.

140

RTXC Kernel Services Reference, Volume 2

KS_GetQueueDataW

Example 4-9. Read Queue EntryWait If Necessary

#include "rtxcapi.h" #include "kqueue.h" /* RTXC Kernel Service prototypes */ /* defines DATAQ */

struct /* structure for receiving the dequeued entry */ { int type; int value; } entry; /* get data from DATAQ */ KS_GetQueueDataW (DATAQ, &entry); ... continue

See Also

KS_GetQueueData, page 136 KS_GetQueueDataT, page 138

Chapter 4: Queue Services

141

KS_GetQueueName

KS_GetQueueName
Get the name of a queue.

Synopsis Input Description

char * KS_GetQueueName (QUEUE queue)

queue

The handle of the queue being queried.

The KS_GetQueueName kernel service obtains a pointer to the null-terminated string containing the name of the specified queue. The queue may be static or dynamic.
Note: To use this service on static queues, you must enable the Static Names attribute of the Queue class during system generation.

Output

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

Error Example

This service may generate the following fatal error code:

FE_ILLEGAL_QUEUE if the specified queue ID is not valid.

In Example 4-10 on page 143, the Current Task needs to report the name of the dynamic queue specified in dynqueue.

142

RTXC Kernel Services Reference, Volume 2

KS_GetQueueName

Example 4-10. Read Dynamic Queue Name

#include <stdio.h> #include "rtxcapi.h" static char buf[128]; QUEUE dynqueue; char *pname; if ((pname = KS_GetQueueName (dynqueue)) == (char *)0) sprintf (buf, "Queue %d has no name", queueID); else sprintf (buf, "Queue %d name is %s", dynqueue, pname); putline (buf); /* standard i/o */ /* RTXC Kernel Service prototypes */

See Also

KS_DefQueueName, page 126 KS_OpenQueue, page 152

Chapter 4: Queue Services

143

KS_GetQueueProp

KS_GetQueueProp
Get the properties of a queue.

Synopsis Inputs

void KS_GetQueueProp (QUEUE queue, QUEUEPROP *pqueueprop)

queue

The handle of the queue being queried.

pqueueprop A pointer to a Queue properties structure.

Description

The KS_GetQueueProp kernel service obtains all of the property values of the specified queue in a single call. The service stores the property values in the QUEUEPROP structure pointed to by pqueueprop. Example 4-3 on page 128 shows the organization of the QUEUEPROP structure. This service does not return any information concerning queue event semaphores. For information about obtaining queue event semaphores, see KS_GetQueueSema on page 146. The value returned in attributes indicates the ordering of tasks waiting on the queue. If (attributes & ATTR_FIFO_ORDER) is not equal to 0, the service orders waiters chronologically. If (attributes & ATTR_FIFO_ORDER) equals 0, the service orders waiters by priority.

Output Errors

This service does not return a value. It stores the properties of the queue in the properties structure pointed to by pqueueprop. 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.

144

RTXC Kernel Services Reference, Volume 2

KS_GetQueueProp

Example

Example 4-11 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 4 entries.

Example 4-11. Read Queue Properties

#include "rtxcapi.h" #include "kqueue.h" #include "ksema.h" QUEUEPROP qprop; KS_GetQueueProp (CHARQ, &qprop);/* get CHARQ properties */ if (qprop.current_size > 20) KS_SignalSema (XOFF); if (qprop.current_size < 4) KS_SignalSema (XON); ... continue /* RTXC Kernel Service prototypes */ /* defines CHARQ */ /* defines XOFF and XON */

See Also

KS_DefQueueProp, page 128

Chapter 4: Queue Services

145

KS_GetQueueSema

KS_GetQueueSema
Get the semaphore handle associated with a queue event.

Synopsis Inputs

SEMA KS_GetQueueSema (QUEUE queue, QEVENT event)

queue event

The handle of the queue being queried. A queue event value.

Description

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.
FE_INVALID_QEVENT if the specified queue event value is not either QNF or QNE.

146

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; } 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 } /* RTXC Kernel Service prototypes */ /* defines MAINQNESEMAQ */ /* defines MAINQ */

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

See Also

KS_DefQueueSema, page 130

Chapter 4: Queue Services

147

INIT_QueueClassProp

INIT_QueueClassProp
Initialize the Queue object class properties.

Synopsis Input Description

KSRC INIT_QueueClassProp (const KCLASSPROP *pclassprop)

pclassprop

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

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.

148

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

149

KS_LookupQueue

KS_LookupQueue
Look up a queues name to get its handle.

Synopsis Inputs

KSRC KS_LookupQueue (const char pname, QUEUE pqueue)

pname pqueue

A pointer to a null-terminated name string. A pointer to a variable in which to store the queue handle, if found.

Description

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 queues handle in the variable pointed to by pqueue.

RC_OBJECT_NOT_FOUND if the service finds no matching queue

name.

150

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" 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 } /* RTXC Kernel Service prototypes */

See Also

KS_DefQueueName, page 126 KS_OpenQueue, page 152

Chapter 4: Queue Services

151

KS_OpenQueue

KS_OpenQueue
Allocate and name a dynamic queue.

Synopsis Inputs

KSRC KS_OpenQueue (const char pname, QUEUE pqueue)

pname pqueue

A pointer to a null-terminated name string. A pointer to a variable in which to store the queue handle.

Description

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

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.

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

Example

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

153

KS_OpenQueue

Example 4-15. Allocate and Initialize Queue

#include "rtxcapi.h" #include "kpart.h" KSRC ksrc; QUEUE dynqueue; PEVENT pevent; struct QUEUEPROP qprop; struct PARTPROP pprop; /* queue properties */ /* partition properties */ /* RTXC Kernel Service prototypes */ /* defines QUEBODY */

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

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

155

KS_PutQueueData

KS_PutQueueData
Put an entry into a queue.

Synopsis Inputs

KSRC KS_PutQueueData (QUEUE queue, const void *psource)

queue psource

The handle of the queue. A pointer to the source buffer.

Description

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

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

156

RTXC Kernel Services Reference, Volume 2

KS_PutQueueData

Example 4-16. Put Data Into Queue

#include "rtxcapi.h" #include "kqueue.h" 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. } /* RTXC Kernel Service prototypes */ /* defines DATAQ */

See Also

KS_PutQueueDataT, page 158 KS_PutQueueDataW, page 160

Chapter 4: Queue Services

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

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

queue psource counter ticks

The handle of the queue. A pointer to the source buffer. The counter associated with the tick interval defined by ticks. The number of ticks on the specified counter to wait for the queue to have room.

Description

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

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.

158

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 QueueWait Number of Ticks If Queue is Full
#include "rtxcapi.h" #include "kqueue.h" #include "kproject.h" 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. } /* RTXC Kernel Service prototypes */ /* DATAQ */ /* CLKTICK */

See Also

KS_PutQueueData, page 156 KS_PutQueueDataW, page 160

Chapter 4: Queue Services

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

void KS_PutQueueDataW (QUEUE queue, const void *psource)

queue psource

The handle of the queue. A pointer to the source buffer.

Description

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 Errors

been initialized.
FE_NULL_SORUCEBUFFER if the pointer to the source buffer is

null.

Example

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.

160

RTXC Kernel Services Reference, Volume 2

KS_PutQueueDataW

Example 4-18. Put Data Into QueueWait Until Queue Has Room
#include "rtxcapi.h" #include "kqueue.h" struct { int type; int value; } entry; /* enqueue packet of info into DATAQ */ KS_PutQueueDataW (DATAQ, &entry); ... continue /* RTXC Kernel Service prototypes */ /* defines DATAQ */

See Also

KS_PutQueueData, page 156 KS_PutQueueDataT, page 158

Chapter 4: Queue Services

161

KS_UseQueue

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

Synopsis Inputs

KSRC KS_UseQueue (const char pname, QUEUE pqueue)

pname pqueue

A pointer to a null-terminated name string. A pointer to a variable in which to store the queue handle.

Description

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

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

162

RTXC Kernel Services Reference, Volume 2

KS_UseQueue

Example 4-19. Read Queue Handle and Register It

#include "rtxcapi.h" 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 } /* RTXC Kernel Service prototypes */

See Also

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

Chapter 4: Queue Services

163

KS_UseQueue

164

RTXC Kernel Services Reference, Volume 2

CHAPTER

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

165

KS_CloseMbox

KS_CloseMbox
End the use of a dynamic mailbox.

Synopsis Input Description

KSRC KS_CloseMbox (MBOX mbox)

mbox

The handle of the mailbox.

The KS_CloseMbox kernel service ends the Current Tasks use of the dynamic mailbox specified in mbox. When closing the mailbox, the service detaches the callers 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.

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

166

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 Example

This service may generate the following fatal error code:

FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.

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" 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 /* RTXC Kernel Services prototypes */

See Also

KS_OpenMbox, page 188 KS_DefMboxProp, page 170

Chapter 5: Mailbox Services

167

KS_DefMboxName

KS_DefMboxName
Define the name of a previously opened dynamic mailbox.

Synopsis Inputs

KSRC KS_DefMboxName (MBOX mbox, const char *pname)

mbox pname

The handle of the mailbox being defined. A pointer to a null-terminated name string.

Description

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

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" MBOX dynmbox; if (KS_DefMboxName (dynmbox, "NewMbox") != RC_GOOD) { ... Naming operation failed. Deal with it here } ... naming operation was successful. Continue /* RTXC Kernel Services prototypes */

See Also

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

Chapter 5: Mailbox Services

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 Error

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

170

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" MBOX dynmbox; MBOXPROP mprop; KSRC ksrc; KS_GetMboxProp (dynmbox, &mprop); /* Get properties */ /* RTXC Kernel Services prototypes */

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

See Also

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

Chapter 5: Mailbox Services

171

KS_DefMboxSema

KS_DefMboxSema
Associate a semaphore with the Mailbox_Not_Empty event.

Synopsis Inputs

void KS_DefMboxSema (MBOX mbox, SEMA sema)

mbox sema

The handle of the mailbox being defined. The handle of a semaphore to associate with the mailbox.

Description

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 Errors

This service does not return a value. 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

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

173

KS_DefMboxSema

Example 5-5. Define Mailbox Semaphore

#include "rtxcapi.h" #include "kmbox.h" #include "ksema.h" 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 */ /* RTXC Kernel Services prototypes */ /* defines HPMAIL and LPMAIL */ /* defines GOTHP and GOTLP */

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

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

175

KS_GetMboxClassProp

KS_GetMboxClassProp
Get the Mailbox object class properties.

Synopsis Input Description

const KCLASSPROP * KS_GetMboxClassProp (int *pint)

pintA pointer to a variable in which to store the number of available dynamic mailboxes.
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

Attribute Static Names Dynamics Semaphores Mask ATTR_STATIC_NAMES ATTR_DYNAMICS ATTR_SEMAPHORES

Output

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

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

177

KS_GetMboxName

KS_GetMboxName
Get the name of a mailbox.

Synopsis Input Description

char * KS_GetMboxName (MBOX mbox)

mbox

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 Example

This service may generate the following fatal error code:

FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.

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

178

RTXC Kernel Services Reference, Volume 2

KS_GetMboxName

Example 5-7. Read Mailbox Name

#include <stdio.h> #include "rtxcapi.h" 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); /* standard i/o */ /* RTXC Kernel Services prototypes */

See Also

KS_DefMboxName, page 168 KS_OpenMbox, page 188

Chapter 5: Mailbox Services

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 Errors

been initialized.

Example

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

180

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" 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 /* RTXC Kernel Services prototypes */

See Also

KS_GetMboxProp, page 180

Chapter 5: Mailbox Services

181

KS_GetMboxSema

KS_GetMboxSema
Get the semaphore handle associated with a Mailbox_Not_Empty event.

Synopsis Input Description

SEMA KS_GetMboxSema (MBOX mbox)

mbox

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

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

182

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

183

INIT_MboxClassProp

INIT_MboxClassProp
Initialize the Mailbox object class properties.

Synopsis Input Description

KSRC INIT_MboxClassProp (const KCLASSPROP *pclassprop)

pclassprop

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

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.

184

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

185

KS_LookupMbox

KS_LookupMbox
Look up a mailboxs name to get its handle.

Synopsis Inputs

KSRC KS_LookupMbox (const char pname, MBOX pmbox)

pname pmbox

A pointer to a null-terminated name string. A pointer to a variable in which to store the mailbox handle, if found.

Description

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 mailboxs 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 mailboxs handle in the variable pointed to by pmbox.

RC_OBJECT_NOT_FOUND if the service finds no matching

mailbox name.

186

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 <stdio.h> #include "rtxcapi.h" static char buf[128]; 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 */ } /* standard i/o */ /* RTXC Kernel Services prototypes */ /* buffer space */

See Also

KS_DefMboxName, page 168 KS_OpenMbox, page 188

Chapter 5: Mailbox Services

187

KS_OpenMbox

KS_OpenMbox
Allocate and name a dynamic mailbox.

Synopsis Inputs

KSRC KS_OpenMbox (const char pname, MBOX pmbox)

pname pmbox

A pointer to a null-terminated name string. A pointer to a variable in which to store the mailbox handle.

Description

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

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" 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 } /* RTXC Kernel Services prototypes */

Chapter 5: Mailbox Services

189

KS_OpenMbox

See Also

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

190

RTXC Kernel Services Reference, Volume 2

KS_UseMbox

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

Synopsis Inputs

KSRC KS_UseMbox (const char pname, MBOX pmbox)

pname pmbox

A pointer to a null-terminated name string. A pointer to a variable in which to store the mailbox handle.

Description

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

191

KS_UseMbox

Example 5-13. Read Mailbox Handle and Register It

#include "rtxcapi.h" 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 } /* RTXC Kernel Services prototypes */

See Also

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

192

RTXC Kernel Services Reference, Volume 2

CHAPTER

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

193

KS_AckMsg

KS_AckMsg
Acknowledge a message.

Synopsis Input Description

void KS_AckMsg (MSGENV *pmsgenv)

pmsgenv

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 Errors Example

This service does not return a value. This service may generate the following fatal error code:
FE_NULL_MSGENV if the pointer to the message envelope is null.

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.

194

RTXC Kernel Services Reference, Volume 2

KS_AckMsg

Example 6-1. Acknowledge Message

#include "rtxcapi.h" #include "kmbox.h" 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); /* signal message processing done */ /* RTXC Kernel Services prototypes */ /* defines EMAIL */

See Also

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

195

KS_ForwardMsg

KS_ForwardMsg
Forward a message to a mailbox asynchronously.

Synopsis Inputs

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

mbox pmsgenv priority

The handle for the mailbox to which to send the message. A pointer to the message envelope. The priority of the message.

Description

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

RTXC Kernel Services Reference, Volume 2

KS_ForwardMsg

List at a position determined by its priority. If the receiving tasks 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 Errors

been initialized.
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

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

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

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

198

RTXC Kernel Services Reference, Volume 2

KS_ForwardMsg

Chapter 6: Message Services

199

KS_ReceiveMsg

KS_ReceiveMsg
Receive a message from a mailbox.

Synopsis Inputs

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

mbox pmsgenv

A handle for the mailbox from which the message is being received. A pointer to a message envelope pointer.

Description

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

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.

200

RTXC Kernel Services Reference, Volume 2

KS_ReceiveMsg

Example 6-3. Receive Next Message from a Mailbox

#include "rtxcapi.h" #include "kmbox.h" 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 } /* RTXC Kernel Services prototypes */ /* defines MYMAIL */

See Also

KS_ReceiveMsgT, page 202 KS_ReceiveMsgW, page 204

Chapter 6: Message Services

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

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

mbox pmsgenv counter ticks

A handle for the mailbox from which the message is being received. A pointer to a message envelope. The counter associated with the interval defined by ticks. The number of ticks on the specified counter to wait for a message.

Description

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

Output

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

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

203

KS_ReceiveMsgW

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

Synopsis Inputs

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

mbox pmsgenv

A handle for the mailbox from which the message is being received. A pointer to a message envelope pointer.

Description

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 mailboxs attributes. If the mailbox is empty, the service blocks the requesting task and waits for the mailbox to receive the next message.

Output Errors

This service returns a pointer to the body of the received message. 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

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.

204

RTXC Kernel Services Reference, Volume 2

KS_ReceiveMsgW

Example 6-5. Receive MessageWait If Necessary

#include "rtxcapi.h" #include "kmbox.h" void *pmsgbody; MSGENV *pmsgenv; /* receive next message from any task */ pmsgbody = KS_ReceiveMsgW (MYMAIL, &pmsgenv); ..continue /* RTXC Kernel Services prototypes */ /* defines MYMAIL */

See Also

KS_ReceiveMsg, page 200 KS_ReceiveMsgT, page 202

Chapter 6: Message Services

205

KS_SendMsg

KS_SendMsg
Send a message to a mailbox asynchronously.

Synopsis Inputs

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

mbox pmsgenv pmsgbody priority

A handle for the mailbox to which the message is being sent. A pointer to the message envelope. A pointer to the body of the message. The priority of the message.

Description

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 messages 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 tasks priority is higher than that of the sending or forwarding task, a preemption occurs.

206

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 Errors

been initialized.
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

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

207

KS_SendMsg

Example 6-6. Send MessageWait 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 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

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

208

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

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

mbox pmsgenv pmsgbody priority counter ticks

A handle for the mailbox to which to send the message. A pointer to the message envelope. A pointer to the body of the message. The priority value of the message. The counter associated with the interval defined by ticks. The number of ticks on counter to wait for an acknowledgment.

Description

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

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 tasks 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.
FE_ILLEGAL_COUNTER if the specified counter ID is not valid.

210

RTXC Kernel Services Reference, Volume 2

KS_SendMsgT

FE_UNINITIALIZED_COUNTER if the specified counter has not

yet been initialized.

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

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

211

KS_SendMsgT

Example 6-7. Send MessageWait 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

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

212

RTXC Kernel Services Reference, Volume 2

KS_SendMsgW

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

Synopsis Inputs

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

mbox pmsgenv pmsgbody priority

A handle for the mailbox to which the message is being sent. A pointer to the message envelope. A pointer to the body of the message. The priority value of the message.

Description

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 messages 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 tasks priority is higher than that of the sending or forwarding task, a preemption occurs.

Chapter 6: Message Services

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 Errors

been initialized.
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

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

RTXC Kernel Services Reference, Volume 2

KS_SendMsgW

See Also

KS_SendMsg, page 206 KS_SendMsgT, page 209

Chapter 6: Message Services

215

KS_TestAck

KS_TestAck
Test for message acknowledgment.

Synopsis Input Description

KSRC KS_TestAck (MSGENV *pmsgenv)

pmsgenv

A pointer to a message envelope.

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

Output

been acknowledged.

Error Example

This service may generate the following fatal error code:

FE_NULL_MSGENV if the pointer to the message envelope is null.

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.

216

RTXC Kernel Services Reference, Volume 2

KS_TestAck

Example 6-9. Test for Message Acknowledgment

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

217

KS_TestAckT

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

Synopsis Inputs

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

pmsgenv counter ticks

A pointer to a message envelope. The counter associated with the interval defined by ticks. The number of ticks on the specified counter to wait for an acknowledgment.

Description

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: The message is acknowledged by a receiving task, or The specified number of ticks elapses.

Output

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

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 AcknowledgmentWait Number of Ticks 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 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

219

KS_TestAckW

KS_TestAckW
Test for message acknowledgment and wait for the acknowledgment.

Synopsis Input Description

void KS_TestAckW (MSGENV *pmsgenv)

pmsgenv

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 Error Example

This service does not return a value. This service may generate the following fatal error code:
FE_NULL_MSGENV if the pointer to the message envelope is null.

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.

220

RTXC Kernel Services Reference, Volume 2

KS_TestAckW

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

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

221

KS_TestAckW

222

RTXC Kernel Services Reference, Volume 2

CHAPTER

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

223

XX_AllocBlk

XX_AllocBlk
Allocate a block of memory.

Zones

IS_AllocBlk TS_AllocBlk KS_AllocBlk

void * XX_AllocBlk (PART part)

Synopsis Inputs Description

part

A handle for a partition.

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

Output

Errors

been initialized.

Example

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.

224

RTXC Kernel Services Reference, Volume 2

XX_AllocBlk

Example 7-1. Allocate Block of Memory

#include "rtxcapi.h" #include "kpart.h" char *p; if ((p = (char *)KS_AllocBlk (PART1)) == (char *) 0) { ... Deal with no memory available } else { ... Allocation was successful } /* RTXC Kernel Service prototypes */ /* defines PART1 */

See Also

KS_AllocBlkT, page 226 KS_AllocBlkW, page 228

Chapter 7: Memory Partition Services

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

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

part counter ticks

A handle for a partition. The counter associated with the interval defined by ticks. The number of ticks on the specified counter to wait for an available block of memory.

Description

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:
FE_ILLEGAL_PART if the specified partition ID is not valid.

226

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 MemoryWait Number of Ticks If Necessary

#include "rtxcapi.h" #include "kproject.h" #include "kpart.h" 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. } /* RTXC Kernel Service prototypes */ /* defines CLKTICK */ /* defines PART1 */

See Also

XX_AllocBlk, page 224 KS_AllocBlkW, page 228

Chapter 7: Memory Partition Services

227

KS_AllocBlkW

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

Synopsis Input Description

void * KS_AllocBlkW (PART part)

part

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 Errors

This service returns a pointer to the allocated memory block. 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

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.

228

RTXC Kernel Services Reference, Volume 2

KS_AllocBlkW

Example 7-3. Allocate Block of MemoryWait If Necessary

#include "rtxcapi.h" #include "kpart.h" char *p; /* no return until requested memory is available */ p = (char *)KS_AllocBlkW (PART1); ...continue /* RTXC Kernel Service prototypes */ /* defines PART1 */

See Also

XX_AllocBlk, page 224 KS_AllocBlkT, page 226

Chapter 7: Memory Partition Services

229

KS_ClosePart

KS_ClosePart
End the use of a dynamic partition.

Synopsis Input Description

KSRC KS_ClosePart (PART part)

part

The handle for the partition being closed.

The KS_ClosePart kernel service ends the Current Tasks use of the dynamic memory partition specified in part. When closing the partition, the kernel detaches the callers 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 partitions 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 Tasks 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

RTXC Kernel Services Reference, Volume 2

KS_ClosePart

Error Example

This service may generate the following fatal error code:

FE_ILLEGAL_PART if the specified partition ID is not valid.

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" PART dynpart; SEMA dynsema; KS_TestSemaW (dynsema); /* wait for signal */ /* RTXC Kernel Service prototypes */

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

231

KS_DefPartName

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

Synopsis Inputs

KSRC KS_DefPartName (PART part, const char *pname)

part pname

The handle of the partition being defined. A pointer to a null-terminated name string.

Description

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

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" PART dynpart; if ((KS_DefPartName (dynpart, "NewPart")) != RC_GOOD) { ... something may be wrong. Deal with it here } ... naming operation was successful. Continue /* RTXC Kernel Service prototypes */

See Also

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

Chapter 7: Memory Partition Services

233

KS_DefPartProp

KS_DefPartProp
Define the properties of a partition.

Synopsis Inputs

void KS_DefPartProp (PART part, const PARTPROP *ppartprop)

part ppartprop

The handle of the partition being defined. A pointer to a Partition properties structure.

Description

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

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 Error

This service does not return a value. 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 <= partclassprop.n_statics; objnum++) KS_DefPartProp (objnum, &partprop[objnum]);

See Also

KS_GetPartProp, page 246 INIT_PartClassProp, page 250 KS_OpenPart, page 254

Chapter 7: Memory Partition Services

235

KS_DefPartSema

KS_DefPartSema
Associate a semaphore with the Partition_Not_Empty event.

Synopsis Inputs

void KS_DefPartSema (PART part, SEMA sema)

part sema

The handle of the partition being defined. The handle of the semaphore to associate with the partition.

Description

The KS_DefPartSema kernel service associates the semaphore specified in sema with the Partition_Not_Empty event of the partition specified in part. This action allows a task to synchronize with the occurrence of that 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 Partition class during system generation.

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

Output Errors

This service does not return a value. 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.
FE_ILLEGAL_SEMA if the specified semaphore ID is not valid. FE_UNINITIALIZED_SEMA if the specified semaphore has not

yet been initialized.

Example
236

In Example 7-7 on page 237, the Current Task associates the

RTXC Kernel Services Reference, Volume 2

KS_DefPartSema

Partition_Not_Empty condition for the PART1 and PART2 partitions with the HAVBLK1 and HAVBLK2 semaphores, respectively, so that it is notified if either one occurs indicating that blocks are available.
Example 7-7. Associate Semaphore With Memory Partition
#include "rtxcapi.h" #include "kpart.h" #include "ksema.h" const SEMA semalist[] = { HAVBLK1, HAVBLK2, (SEMA)0 }; SEMA cause; void *buf1, *buf2; /* RTXC Kernel Service prototypes */ /* defines PART1 and PART2 */ /* defines HAVBLK1 and HAVBLK2 */

/* null terminated list */

KS_DefPartSema (PART1, HAVBLK1); KS_DefPartSema (PART2, HAVBLK2); ... partitions are determined to be empty /* wait here for either partition to become not empty */ cause = KS_TestSemaMW (semalist); switch (cause) { case HAVBLK1: buf1 = KS_AllocBlk (PART1); /* get block */ ... do some processing break; case HAVBLK2: buf2 = KS_AllocBlk (PART2); /* get block */ ... do some processing break; } /* end of switch */ ... continue

See Also

KS_GetPartSema, page 248 KS_TestSema, page 106 KS_TestSemaT, page 108 KS_TestSemaW, page 118 KS_TestSemaM, page 110 KS_TestSemaMT, page 112 KS_TestSemaMW, page 115

Chapter 7: Memory Partition Services

237

KS_FreeBlk

KS_FreeBlk
Free a block of memory.

Synopsis Inputs

void KS_FreeBlk (PART part, void *pblk)

part pblk

The handle of a partition. A pointer to the block of memory to be freed.

Description

The KS_FreeBlk kernel service returns the block of memory pointed to by pblk to the free pool for the memory partition specified in part.
Warning: This service does not check to determine that the specified memory block to be released belongs in the designated partition. It is the programmers responsibility to be sure the block is freed ONLY to the partition from which it was allocated. If not, a partitions content can become corrupted with blocks of memory from other partitions.

However, there are two exceptions to this warning: 1. During system generation, you can define more than one partition having the same size blocks. You can then dynamically construct one large virtual partition by allocating the blocks from one partition and freeing them into another partition that then contains the aggregate number of blocks. 2. You may extend a partition by allocating similarly sized blocks of memory from the heap or from another RAM area within the systems address space and freeing them to a given partition.

Output

This service does not return a value.

238

RTXC Kernel Services Reference, Volume 2

KS_FreeBlk

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.
FE_NULL_PARTBLKPTR if the pointer to the block of memory is

null.

Example

Example 7-8 allocates a block of memory from the BUFFBLKS partition, uses it for a while as a character buffer, and then returns it to BUFFBLKS.

Example 7-8. Allocate and Free Memory Block

#include "rtxcapi.h" #include "kpart.h" char *p; /* get a block for temporary use */ p = (char *)KS_AllocBlkW (BUFFBLKS); ... use block for some operation /* free the block now */ KS_FreeBlk (BUFFBLKS, (void *)p); ... continue } /* RTXC Kernel Service prototypes */ /* defines BUFFBLKS */

See Also

XX_AllocBlk, page 224 KS_AllocBlkT, page 226 KS_AllocBlkW, page 228

Chapter 7: Memory Partition Services

239

KS_GetFreeBlkCount

KS_GetFreeBlkCount
Get the number of free blocks in a partition.

Synopsis Input Description

KCOUNT KS_GetFreeBlkCount (PART part)

part

The handle of the partition being queried.

The KS_GetFreeBlkCount kernel service obtains the number of free blocks at the time of the request in the partition specified in part.
Note: Be careful when using the KS_GetFreeBlkCount kernel service because interrupts may occur while the kernel is servicing the request. As a result, an interrupt service routine may allocate a block from the specified partition, or another task may preempt and use the specified partition. In either case, the number of available blocks may actually be different than that returned by the service.

Output

This service returns a number of the KCOUNT type equal to the number of blocks in the specified memory partition at the time of the service request. 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

Errors

been initialized.

Example

In Example 7-9 on page 241, the Current Task periodically reports on the approximate number of blocks remaining in the PART32 memory partition. The report period is 30 seconds and the report is made to the console.

240

RTXC Kernel Services Reference, Volume 2

KS_GetFreeBlkCount

Example 7-9. Read Memory Partition Free Block Count

#include #include #include #include <stdio.h> "rtxcapi.h" "kpart.h" "kproject.h" /* /* /* /* standard i/o */ RTXC Kernel Service prototypes */ defines PART32 */ defines CLKTICK */

static char buf[128]; KCOUNT nblks; for (;;) { /* wait for the report period */ KS_SleepTask (TIMEBASE, (TICKS)30000/CLKTICK); /* get block count */ nblks = KS_GetFreeBlkCount (PART32); sprintf (buf, "PART32 contains %d blocks", nblks); putline (buf); /* report block count */ }

Chapter 7: Memory Partition Services

241

KS_GetPartClassProp

KS_GetPartClassProp
Get the Memory Partition object class properties

Synopsis Input Description

const KCLASSPROP * KS_GetPartClassProp (int *pint)

pint

A pointer to a variable in which to store the number of available dynamic partitions.

The KS_GetPartClassProp kernel service obtains a pointer to the KCLASSPROP structure that was used during system initialization by the INIT_PartClassProp service to initialize the Partition object class properties. If pint is not null ((int *)0), the service returns the number of available dynamic partitions in the variable pointed to by 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 Partition KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 7-1 on page 243.

242

RTXC Kernel Services Reference, Volume 2

KS_GetPartClassProp

Table 7-1. Memory Partition Class Attributes and Masks

Attribute Static Names Dynamics Semaphores Statistics Mask ATTR_STATIC_NAMES ATTR_DYNAMICS ATTR_SEMAPHORES ATTR_STATISTICS

Output

If successful, this service returns a pointer to a KCLASSPROP structure. If the Partition class is not initialized, the service returns a null pointer ((KCLASSPROP *)0).

Example

In Example 7-10, the Current Task needs access to the information contained in the KCLASSPROP structure for the partition object class.

Example 7-10. Read Memory Partition Object Class Properties

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

KCLASSPROP *ppartclassprop; int free_dyn; /* Get the partition kernel object class properties */ if ((ppartclassprop = KS_GetPartClassProp (&free_dyn)) == (KCLASSPROP *)0) { putline ("Partition Class not initialized"); } else { ... partition object class properties are available for use "free_dyn" contains the number of free dynamic partitions }

See Also

INIT_PartClassProp, page 250

Chapter 7: Memory Partition Services

243

KS_GetPartName

KS_GetPartName
Get the name of a partition.

Synopsis Input Description

char * KS_GetPartName (PART part)

part

The handle of the partition being queried.

The KS_GetPartName kernel service obtains a pointer to the nullterminated string containing the name of the partition specified in part. The partition may be static or dynamic.
Note: To use this service on static partitions, you must enable the Static Names attribute of the Partition class during system generation.

Output

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

Error Example

This service may generate the following fatal error code:

FE_ILLEGAL_PART if the specified partition ID is not valid.

In Example 7-11 on page 245, the Current Task needs to report the name of the dynamic partition specified in dynpart.

244

RTXC Kernel Services Reference, Volume 2

KS_GetPartName

Example 7-11. Read Memory Partition Name

#include <stdio.h> #include "rtxcapi.h" static char buf[128]; PART dynpart; char *pname; if ((pname = KS_GetPartName (dynpart)) == (char *)0) sprintf (buf, "Partition %d has no name", dynpart); else sprintf (buf, "Partition %d name is %s", dynpart, pname); putline (buf); /* standard i/o */ /* RTXC Kernel Service prototypes */

See Also

KS_DefPartName, page 232 KS_OpenPart, page 254

Chapter 7: Memory Partition Services

245

KS_GetPartProp

KS_GetPartProp
Get the properties of a partition.

Synopsis Inputs

void KS_GetPartProp (PART part, PARTPROP *ppartprop)

part ppartprop

The handle of the partition being queried. A pointer to a Partition properties structure.

Description

The KS_GetPartProp kernel service obtains all of the property values of the partition specified in part in a single call. The service stores the property values in the PARTPROP structure pointed to by ppartprop. Example 7-12 shows the organization of the PARTPROP structure.

Example 7-12. Memory Partition Properties Structure

typedef struct { KATTR attributes; /* FIFO or Priority waiters */ char *base; /* root of free pool list */ ksize_t size; /* no. of bytes in a block */ KCOUNT count; /* initial no. of blocks in partition */ } PARTPROP;

The value returned for the partition attribute indicates the ordering of tasks waiting for memory from the partition: If (attributes & ATTR_FIFO_ORDER) is not equal to 0, waiters have chronological ordering. If (attributes & ATTR_FIFO_ORDER) equals 0, waiters are ordered by priority.

Output Errors

This service does not return a value. It stores the properties of the partition in the properties structure pointed to by ppartprop. This service may generate one of the following fatal error codes:
FE_ILLEGAL_PART if the specified partition ID is not valid.

246

RTXC Kernel Services Reference, Volume 2

KS_GetPartProp

FE_UNINITIALIZED_PART if the specified partition has not yet

been initialized.

Example

In Example 7-13, the Current Task needs to ensure that the properties of the dynamic partition specified in dynpart are defined such that any tasks waiting to receive a block of memory from the partition are ordered in descending order of task priority. The task first reads the existing properties of the partition and then forces priority order waiting.

Example 7-13. Read Memory Partition Properties

#include "rtxcapi.h" PART dynpart; PARTPROP pprop; KS_GetPartProp (dynpart, &pprop); /* get properties */ /* force priority mode */ pprop.partattr &= (~ATTR_FIFO_ORDER); KS_DefPartProp (dynpart, &pprop);/* redefine properties */ ... continue /* RTXC Kernel Service prototypes */

See Also

KS_DefPartProp, page 234

Chapter 7: Memory Partition Services

247

KS_GetPartSema

KS_GetPartSema
Get the semaphore associated with the Partition_Not_Empty event.

Synopsis Input Description

SEMA KS_GetPartSema (PART part)

part

The handle of the partition being queried.

The KS_GetPartSema kernel service obtains the handle of the semaphore associated with the Partition_Not_Empty event of the static or dynamic partition specified in part. You must have previously associated the semaphore and the partition event through a call to KS_DefPartSema.
Note: To use this service, you must enable the Semaphores attribute of the Partition class during system generation.

Output

If the partition 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 partition event, the service returns a SEMA value of zero (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

In Example 7-14 on page 249, the Current Task needs to know the handle of the Partition_Not_Empty semaphore associated with the BLK256 static memory partition. If the return from KS_GetPartSema indicates there is no semaphore defined, the Current Task defines one using the BLK256NE semaphore, adds it to semalist, and waits for the indicated events.

248

RTXC Kernel Services Reference, Volume 2

KS_GetPartSema

Example 7-14. Read Memory Partition Semaphore

#include "rtxcapi.h" #include "ksema.h" #include "kpart.h" /* RTXC Kernel Service prototypes */ /* defines BLK256NE, OEVENT */ /* defines BLK256 */

static SEMA semalist[] = { OEVENT, /* other event */ (SEMA)0, /* PNE, to be filled in below */ (SEMA)0; /* null terminator */ } SEMA pnesema, cause; if ((pnesema = KS_GetPartSema (BLK256)) == (SEMA)0) { /* Partition_not_Empty sema undefined for BLK256 */ KS_DefPartSema (BLK256, BLK256NE); /* define one now */ pnesema = BLK256NE; } /* there is now a NE semaphore defined for partition */ /* BLK256. Store it in semalist */ semalist[1] = pnesema; /* and wait for either event to occur */ cause = KS_TestSemaMW (semalist);

See Also

KS_DefPartSema, page 236

Chapter 7: Memory Partition Services

249

INIT_PartClassProp

INIT_PartClassProp
Initialize the Partition object class properties.

Synopsis Input Description

KSRC INIT_PartClassProp (const KCLASSPROP *pclassprop)

pclassprop

A pointer to a Partition object class properties structure.

During the initialization procedure, you must define the kernel objects needed to perform the application. The INIT_PartClassProp kernel service allocates space for the Partition 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. 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 Partition KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 7-1 on page 243.

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

During system initialization, the startup code must initialize the Partition object class before using any kernel service for that class. In

250

RTXC Kernel Services Reference, Volume 2

INIT_PartClassProp

Example 7-15, the system generation process produced a KCLASSPROP structure containing the information about the kernel object necessary for its initialization. That structure is referenced externally to the code module in the example.
Example 7-15. Initialize Memory Partition Object Class
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */

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

See Also

INIT_SysProp, page 310 KS_GetPartClassProp, page 242

Chapter 7: Memory Partition Services

251

KS_LookupPart

KS_LookupPart
Look up a partitions name to get its handle.

Synopsis Inputs

KSRC KS_LookupPart (const char pname, PART ppart)

pname ppart

A pointer to a null-terminated name string. A pointer to a variable in which to store the partition handle if found.

Description

The KS_LookupPart kernel service obtains the handle of a static or dynamic partition 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 partition name or when it finds no match. The service also stores the matching memory partitions handle in the variable pointed to by ppart. The service searches dynamic names, if any, first.
Note: To use this service on static partitions, you must enable the Static Names attribute of the Partition class during system generation.

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

Output

This service returns a KSRC value as follows:

RC_GOOD if the search succeeds. The service also stores the

found partitions handle in the variable pointed to by ppart.

RC_OBJECT_NOT_FOUND if the service finds no matching

memory partition name.

252

RTXC Kernel Services Reference, Volume 2

KS_LookupPart

Example

In Example 7-16, the Current Task looks for the dynamic memory partition named DynPart2. If the partition is found, the Current Task displays its name and handle on the system console.

Example 7-16. Look Up Memory Partition by Name

#include <stdio.h> #include "rtxcapi.h" static char buf[128]; PART dynpart; /* lookup the partition name to see if it exists */ if (KS_LookupPart ("DynPart2", &dynpart) != RC_GOOD) { ... partition name not found. Deal with it } else { /* partition named "DynPart2" exists. */ /* Display its name and handle */ sprintf (buf, "Partition %d is DynPart2", dynpart); putline (buf); /* output the text */ } /* standard i/o */ /* RTXC Kernel Service prototypes */ /* buffer space */

See Also

KS_DefPartName, page 232 KS_OpenPart, page 254

Chapter 7: Memory Partition Services

253

KS_OpenPart

KS_OpenPart
Allocate and name a dynamic partition.

Synopsis Inputs

KSRC KS_OpenPart (const char pname, PART ppart)

pname ppart

A pointer to a null-terminated name string. A pointer to a variable in which to store the partition handle if found.

Description

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

If the pointer to the partition name is not null ((char *)0), the time required to perform this operation varies with the number of partition names in use. If the pointer to the partition name is null, no search of partition names takes place and the time to perform the

254

RTXC Kernel Services Reference, Volume 2

KS_OpenPart

service is fixed. You can define the partition name at a later time with a call to the KS_DefPartName 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 allocated partition in the variable pointed to by ppart.
RC_OBJECT_ALREADY_EXISTS if the name search finds another

memory partition whose name matches the given string.

RC_NO_OBJECT_AVAILABLE if the name search finds no match

but all dynamic memory partitions are in use.

Example

Example 7-17 allocates a dynamic partition and names it DynPart1.

Example 7-17. Allocate and Name Memory Partition

#include "rtxcapi.h" KSRC ksrc; PART dynpart; if ((ksrc = KS_OpenPart ("DynPart1", &dynpart)) != RC_GOOD) { if (ksrc == RC_OBJECT_ALREADY_EXISTS) putline ("DynPart1 partition name in use"); else if (ksrc == RC_NO_OBJECT_AVAILABLE) putline ("No dynamic partitions available"); else putline ("Partition object class not defined"); } else { /* partition was opened correctly. */ /* ok to use it now */ ...continue } /* RTXC Kernel Service prototypes */

See Also

KS_ClosePart, page 230 KS_LookupPart, page 252 KS_UsePart, page 256

Chapter 7: Memory Partition Services

255

KS_UsePart

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

Synopsis Inputs

KSRC KS_UsePart (const char pname, PART ppart)

pname ppart

A pointer to a null-terminated name string. A pointer to a variable in which to store the partition handle if found.

Description

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

The time required to perform this operation varies with the number of partition 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 memory partitions handle in the variable pointed to by ppart.
RC_STATIC_OBJECT if the specified name belongs to a static

memory partition.
RC_OBJECT_NOT_FOUND if the service finds no matching

partition name.

Example

Example 7-18 on page 257 locates a dynamic memory partition named DynPart1 and obtains its handle for subsequent use.

256

RTXC Kernel Services Reference, Volume 2

KS_UsePart

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

#include "rtxcapi.h" KSRC ksrc; PART dynpart; if ((ksrc = KS_UsePart ("DynPart1", &dynpart)) != RC_GOOD) { if (ksrc == RC_STATIC_OBJECT) putline ("DynPart1 is a static partition"); else putline ("Partition DynPart1 not found"); } else { ... partition was found and its handle is in dynpart. Okay to use it now } /* RTXC Kernel Service prototypes */

See Also

KS_DefPartProp, page 234 KS_DefPartName, page 232 KS_OpenPart, page 254

Chapter 7: Memory Partition Services

257

KS_UsePart

258

RTXC Kernel Services Reference, Volume 2

CHAPTER

Mutex Services

In This Chapter
We describe the Mutex kernel services in detail. The Mutex services help a task gain and release exclusive control of an associated resource. Typical resources might include a shared database, nonreentrant code modules, specialized hardware, or an expensive laser printer.
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 KS_OpenMutx ..................................................................................284 KS_ReleaseMutx...............................................................................286 KS_TestMutx ....................................................................................288 KS_TestMutxT ................................................................................. 290 KS_TestMutxW.................................................................................294 KS_UseMutx.................................................................................... 296

Chapter 8: Mutex Services

259

KS_CloseMutx

KS_CloseMutx
End the use of a dynamic mutex.

Synopsis Input Description

KSRC KS_CloseMutx (MUTX mutex)

mutex

A handle for a mutex.

The KS_CloseMutx kernel service ends the Current Tasks use of the specified dynamic mutex. When closing the mutex, the service detaches the callers use of it. If the caller is the last user of the mutex, the service releases the mutex to the free pool of dynamic mutexes for reuse. If there is at least one other task still using the mutex, the service does not release the mutex to the free pool but completes successfully.
Note: To use this service, you must enable the Dynamics attribute of the Mutex 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 mutex is not dynamic. RC_OBJECT_NOT_INUSE if the specified mutex does not

correspond to an active dynamic mutex.

RC_OBJECT_INUSE if the Current Tasks use of the specified

mutex is closed but the mutex 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.

Error

This service may generate the following fatal error code:

FE_ILLEGAL_MUTX if the specified mutex ID is not valid.

260

RTXC Kernel Services Reference, Volume 2

KS_CloseMutx

Example

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

Example 8-1. Close Mutex

#include "rtxcapi.h" MUTX dynmutx; SEMA dynsema; KS_TestSemaW (dynsema); KS_CloseMutx (dynmutx); /* wait for signal */ /* then close the mutex */ /* RTXC Kernel Service prototypes */

See Also

KS_OpenMutx, page 284

Chapter 8: Mutex Services

261

KS_DefMutxName

KS_DefMutxName
Define the name of a previously opened mutex.

Synopsis Inputs

KSRC KS_DefMutxName (MUTX mutex, const char *pname)

mutex pname

The handle of the mutex being defined. A pointer to a null-terminated name string.

Description

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

This service does not check for duplicate mutex names.

Output

This service returns a KSRC value as follows:

RC_GOOD if the service completes successfully. RC_STATIC_OBJECT if the mutex being named is static. RC_OBJECT_NOT_FOUND if the Dynamics attribute of the Mutex

class is not enabled.

RC_OBJECT_NOT_INUSE if the specified mutex does not

correspond to an active dynamic mutex.

Error Example

This service may generate the following fatal error code:

FE_ILLEGAL_MUTX if the specified mutex ID is not valid.

Example 8-2 on page 263 assigns the name NewMutx to the mutex specified in the dynmutx variable so other users may reference it by name.

262

RTXC Kernel Services Reference, Volume 2

KS_DefMutxName

Example 8-2. Close Mutex

#include <stdio.h> #include "rtxcapi.h" KSRC ksrc; MUTX dynmutx; if ((ksrc = KS_DefMutxName (dynmutx, "NewMutx")) != RC_GOOD) { if (ksrc == RC_OBJECT_NOT_FOUND) putline ("Dynamic Mutexes are not enabled"); else if (ksrc == RC_STATIC_OBJECT) { sprintf (buf, "Mutex %d is a static mutex", dynmutx); putline (buf); } else { sprintf (buf, "Mutex %d is not attached for use", dynmutx); putline (buf); } } ... naming operation was successful. Continue /* standard i/o */ /* RTXC Kernel Service prototypes */

See Also

KS_OpenMutx, page 284 KS_GetMutxName, page 272 KS_LookupMutx, page 282 KS_UseMutx, page 296

Chapter 8: Mutex Services

263

KS_DefMutxProp

KS_DefMutxProp
Define the properties of a mutex.

Synopsis Inputs

void KS_DefMutxProp (MUTX mutex, const MUTXPROP *pmutxprop)

mutex pmutxprop

The handle of the mutex being defined. A pointer to a Mutex properties structure.

Description

The KS_DefMutxProp kernel service defines the properties of the specified mutex using the values contained in the MUTXPROP structure pointed to by pmutxprop. The MUTXPROP structure has the following organization:

typedef struct { KATTR attributes; } MUTXPROP;

/* Waiting Order & Inversion */

You may assign the following mutex attribute values: Waiting Order
Indicates the order in which tasks wait for acquisition of the mutex. 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. Indicates the kernel should handle priority inversion. The default is no priority inversion processing. Inversion can be changed to enable priority inversion processing by ORing the ATTR_INVERSION constant into the attributes field.

Inversion

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

264

RTXC Kernel Services Reference, Volume 2

KS_DefMutxProp

Note: Define a mutexs properties only when the mutex is not busy.

This kernel service is not intended to permit unrestricted enabling and disabling of a mutexs Inversion attribute. Rather, it allows you to identify a mutex as requiring priority inversion processing whenever a lock attempt fails. While no restrictions are placed on its frequency of use, you should use this service before the first use of the mutex. If the Inversion attribute is enabled for priority inversion processing, you must have the Waiting Order attribute set to ~ATTR_FIFO_ORDER.

Output Error Example

This service does not return a value. This service may generate the following fatal error code:
FE_ILLEGAL_MUTX if the specified mutex ID is not valid.

In Example 8-3 on page 266, the Current Task enables priority inversion processing for the ALARMLST mutex. After the mutex attribute is defined, the task locks the mutex, uses it, and then releases it.

Chapter 8: Mutex Services

265

KS_DefMutxProp

Example 8-3. Define Mutex Properties

#include "rtxcapi.h" #include "kmutx.h" MUTXPROP mprop; mprop.mutxattr |= ATTR_INVERSION; /* enable priority inversion processing */ KS_DefMutxProp (ALARMLST, &mprop); /* inversion enabled (ON) */ KS_TestMutxW (ALARMLST); /* lock the mutex */ ... use the resource for something KS_ReleaseMutx (ALARMLST); /* release the mutex */ /* disable priority inversion */ KS_GetMutxProp (ALARMLST, &mprop); mprop.mutxattr &= ~ATTR_INVERSION; KS_DefMutxProp (ALARMLST, &mprop); ... continue /* RTXC Kernel Service prototypes */ /* defines ALARMLST */

See Also

KS_GetMutxProp, page 276 INIT_MutxClassProp, page 280 KS_OpenMutx, page 284

266

RTXC Kernel Services Reference, Volume 2

KS_DefMutxSema

KS_DefMutxSema
Associate a semaphore with the Mutex_Not_Busy event.

Synopsis Inputs

void KS_DefMutxSema (MUTX mutex, SEMA sema)

mutex sema

The handle of the mutex with which to associate the semaphore. The handle of the semaphore being associated with the mutex.

Description

The KS_DefMutxSema kernel service associates the semaphore specified in sema with the Mutex_Not_Busy event of the specified mutex. This action allows a task to synchronize with the occurrence of that 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 Mutex class during system generation.

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

Output Errors

This service does not return a value. This service may generate one of the following fatal error codes:
FE_ILLEGAL_MUTX if the specified mutex ID is not valid. FE_UNINITIALIZED_MUTX if the specified mutex 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.

Chapter 8: Mutex Services

267

KS_DefMutxSema

Example

In Example 8-4, the Current Task associates the Mutex_Not_Busy condition for the HPMUTX and LPMUTX mutexes with the GOTHP and GOTLP semaphores, respectively, so that it can be notified if either one occurs indicating that the corresponding mutex is available. This association lets the Current Task avoid having to poll the mutexes. Instead, the task can use KS_TestSemaM (or one of its variants) to wait for an available mutex. When the task continues upon detecting an unowned mutex, it identifies the mutex and performs some resource dependent processing. Upon completion of its processing, the task frees the mutex.

Example 8-4. Associate Semaphore with Mutex

#include "rtxcapi.h" #include "kmutx.h" #include "ksema.h" SEMA sema; const SEMA semalist[] = { GOTHP, GOTLP, (SEMA)0 /* list must be null terminated */ }; KS_DefMutxSema (HPMUTX, GOTHP); KS_DefMutxSema (LPMUTX, GOTLP); /* define semas for */ /* both mutexes */ /* RTXC Kernel Service prototypes */ /* defines HPMUTX and LPMUTX */ /* defines GOTHP and GOTLP */

/* now test for a signal and wait if there is none */ sema = KS_TestSemaMW (semalist); switch (sema) /* see which one was signaled */ { case GOTHP: /* need to lock the mutex */ if (KS_TestMutx (HPMUTX) != (TASK)0) { ...someone else grabbed it. Deal with that. } ... process data for HP resource KS_ReleaseMutx (HPMUTX); break; case GOTLP: /* need to lock the mutex */ if (KS_TestMutx (LPMUTX) != (TASK)0)

268

RTXC Kernel Services Reference, Volume 2

KS_DefMutxSema

{ ...someone else grabbed it. Deal with that. } ... process data for LP resource KS_ReleaseMutx (LPMUTX); break; } ... continue

See Also

KS_GetMutxSema, page 278 KS_TestMutx, page 288 KS_ReleaseMutx, page 286 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 8: Mutex Services

269

KS_GetMutxClassProp

KS_GetMutxClassProp
Get the Mutex object class properties.

Synopsis Input Description

const KCLASSPROP * KS_GetMutxClassProp (int *pint)

pint

A pointer to a variable in which to store the number of available dynamic mutexes.

The KS_GetMutxClassProp kernel service obtains a pointer to the KCLASSPROP structure that was used during system initialization by the INIT_MutxClassProp service to initialize the Mutex object class properties. If pint is not null ((int *)0), the service returns the number of available dynamic mutexes 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 Mutex KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 8-1 on page 271.

Output

If successful, this service returns a pointer to a KCLASSPROP structure. If the Mutex class is not initialized, the service returns a null pointer ((KCLASSPROP *)0).

270

RTXC Kernel Services Reference, Volume 2

KS_GetMutxClassProp

Table 8-1. Mutex Class Attributes and Masks

Attribute Static Names Dynamics Semaphores Inversion Statistics Mask ATTR_STATIC_NAMES ATTR_DYNAMICS ATTR_SEMAPHORES ATTR_INVERSION ATTR_STATISTICS

Example

In Example 8-5, the Current Task accesses the information contained in the KCLASSPROP structure for the Mutex object class.

Example 8-5. Read Mutex Object Class Properties

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

KCLASSPROP *pmutxclassprop; int free_dyn; /* Get the mutex kernel object class properties */ if ((pmutxclassprop = KS_GetMutxClassProp (&free_dyn)) == (KCLASSPROP *)0) { putline ("Mutex Class not initialized"); } else { ... mutex object class properties are available for use "free_dyn" contains the number of available dynamic mutexes }

See Also

INIT_MutxClassProp, page 280

Chapter 8: Mutex Services

271

KS_GetMutxName

KS_GetMutxName
Get the name of a mutex.

Synopsis Input Description

char * KS_GetMutxName (MUTX mutex)

mutex

The handle of the mutex being queried.

The KS_GetMutxName kernel service obtains a pointer to the nullterminated string containing the name of the specified mutex. The mutex may be static or dynamic.
Note: To use this service on static mutexes, you must enable the Static Names attribute of the Mutex class during system generation.

Output

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

Error Example

This service may generate the following fatal error code:

FE_ILLEGAL_MUTX if the specified mutex ID is not valid.

In Example 8-6 on page 273, the Current Task reports the name of the dynamic mutex specified in dynmutx.

272

RTXC Kernel Services Reference, Volume 2

KS_GetMutxName

Example 8-6. Read Mutex Name

#include <stdio.h> #include "rtxcapi.h" static char buf[128]; MUTX dynmutx; char *pname; if ((pname = KS_GetMutxName (dynmutx)) == (char *)0) sprintf (buf, "Mutex %d has no name", dynmutx); else sprintf (buf, "Mutex %d name is %s", dynmutx, pname); putline (buf); /* send buffer to console */ /* standard i/o */ /* RTXC Kernel Service prototypes */

See Also

KS_DefMutxName, page 262 KS_OpenMutx, page 284

Chapter 8: Mutex Services

273

KS_GetMutxOwner

KS_GetMutxOwner
Get the owner of a mutex.

Synopsis Inputs

TASK KS_GetMutxOwner (MUTX mutex, KCOUNT *pcount)

mutex pcount

The handle of the mutex being queried. A pointer to a variable in which to store the current nesting level of mutex locking.

Description

The KS_GetMutxOwner kernel service determines the owner, if any, of the specified mutex. If pcount is not null ((KCOUNT *)0), the service returns the count showing the current nesting level of mutex locking in the variable pointed to by pcount. This service returns the handle of the task that currently owns the specified mutex. If the mutex is not owned, the service returns a value of zero (0). This service may generate one of the following fatal error codes:
FE_ILLEGAL_MUTX if the specified mutex ID is not valid. FE_UNINITIALIZED_MUTX if the specified mutex has not yet

Output

Errors

been initialized.

Example

Usage of the printer as a system resource is governed by the PRINTER mutex. Example 8-7 on page 275 determines if the owner of the PRINTER mutex is the ALRMTASK Alarm Output task.

274

RTXC Kernel Services Reference, Volume 2

KS_GetMutxOwner

Example 8-7. Read Mutex Owner

#include "rtxcapi.h" #include "kmutx.h" #include "ktask.h" /* RTXC Kernel Service prototypes */ /* defines PRINTER */ /* defines ALRMTASK */

if (KS_GetMutxOwner (PRINTER, (KCOUNT *)0) == ALRMTASK) { ... do something if owner is ALRMTASK } else { ... do something else if mutex is unlocked or owned by a different task }

See Also

KS_TestMutx, page 288 KS_TestMutxT, page 290 KS_TestMutxW, page 294

Chapter 8: Mutex Services

275

KS_GetMutxProp

KS_GetMutxProp
Get the properties of a mutex.

Synopsis Inputs

void KS_GetMutxProp (MUTX mutex, MUTXPROP *pmutxprop)

mutex pmutxprop

The handle of the mutex being queried. A pointer to a Mutex properties structure.

Description

The KS_GetMutxProp kernel service obtains all of the property values of the specified mutex in a single call. The service stores the property values in the MUTXPROP structure pointed to by pmutxprop. The MUTXPROP structure has the following organization:

typedef struct { KATTR attributes; } MUTXPROP;

/* Waiting Order & Inversion */

The value returned for attributes describes: Waiting Order

Indicates the ordering of tasks waiting for acquisition of the mutex. If (attributes & ATTR_FIFO_ORDER) is not equal to 0, waiters have chronological ordering. If (attributes & ATTR_FIFO_ORDER) equals 0, waiters are ordered by priority.

Inversion

Indicates whether the kernel should apply priority inversion to the mutex: If (attributes & ATTR_INVERSION) is not equal to 0, the kernel applies priority inversion to the mutex. If (attributes & ATTR_INVERSION) equals 0, the kernel does not apply priority inversion to the mutex.

Output
276

This service does not return a value.

RTXC Kernel Services Reference, Volume 2

KS_GetMutxProp

Errors

This service may generate one of the following fatal error codes:
FE_ILLEGAL_MUTX if the specified mutex ID is not valid. FE_UNINITIALIZED_MUTX if the specified mutex has not yet

been initialized.

Example

In Example 8-8, the Current Task ensures that the Priority Inversion attribute of the dynamic mutex specified in dynmutx is defined so that the kernel handles mutex priority inversion should it occur. The task first reads the existing properties of the specified mutex and then forces priority inversion In the example, the mutex has not yet been used by any task.

Example 8-8. Read Mutex Properties

#include "rtxcapi.h" MUTX dynmutx; MUTXPROP mprop; /* RTXC Kernel Service prototypes */

/* structure to receive properties */

KS_GetMutxProp (dynmutx, &mprop); /* get properties */ if ((mprop.mutxattr & ATTR_INVERSION) == 0) { /* use priority mode */ mprop.mutxattr |= ATTR_INVERSION; /* define properties */ KS_DefMutxProp (dynmutx, &mprop); } ... continue

See Also

KS_DefMutxProp, page 264

Chapter 8: Mutex Services

277

KS_GetMutxSema

KS_GetMutxSema
Get the semaphore handle associated with the Mutex_Not_Busy event.

Synopsis Input Description

SEMA KS_GetMutxSema (MUTX mutex)

mutex

The handle of the mutex being queried.

The KS_GetMutxSema kernel service obtains the handle of the semaphore associated with the Mutex_Not_Busy event for the specified static or dynamic mutex. You must have previously associated the semaphore and the mutex event through a call to KS_GetMutxSema.
Note: To use this service, you must enable the Semaphores attribute of the Mutex class during system generation.

Output

If the mutex 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 mutex event, the service returns a SEMA value of zero (0).

Errors

This service may generate one of the following fatal error codes:
FE_ILLEGAL_MUTX if the specified mutex ID is not valid. FE_UNINITIALIZED_MUTX if the specified mutex has not yet

been initialized.

Example

In Example 8-9 on page 279, the Current Task needs to know the handle of the Mutex_Not_Busy semaphore associated with the MAINMUTX static mutex. If it finds a semaphore already defined, it waits on that event or another associated with the MTXSEMA2 semaphore. If there is no semaphore defined for MAINMUTX, the

278

RTXC Kernel Services Reference, Volume 2

KS_GetMutxSema

Current Task defines the MTXSEMA1 semaphore, adds it to semalist, and waits on either that event or the one associated with MTXSEMA2.
Example 8-9. Read Mutex Semaphore
#include "rtxcapi.h" #include "ksema.h" #include "kmutx.h" /* RTXC Kernel Service prototypes */ /* defines MTXSEMA1, MTXSEMA2 */ /* defines MAINMUTX */

SEMA cause; static SEMA semalist[] = { (SEMA)0, /* to be filled in /* MTXSEMA2, (SEMA)0 /* end-of-list */ }; if ((semalist[0] = KS_GetMutxSema (MAINMUTX)) == (SEMA)0) { /* no MNB semaphore defined for mutex MAINMUTX */ KS_DefMutxSema (MAINMUTX, MTXSEMA1); /* define one */ semalist[0] = MTXSEMA1; } /* there is now a MNB semaphore defined */ /* for mutex MAINMUTX */ /* wait for either event */ cause = KS_TestSemaMW (semalist); if (cause == semalist[0]) { ... handle the event associated with Mutex_Not_Busy semaphore on mutex MAINMUTX } else { ... handle event associated with MTXSEMA2 }

See Also

KS_DefMutxSema, page 267

Chapter 8: Mutex Services

279

INIT_MutxClassProp

INIT_MutxClassProp
Initialize the Mutex object class properties.

Synopsis Input Description

KSRC INIT_MutxClassProp (const KCLASSPROP *pclassprop)

pclassprop

A pointer to a Mutex object class properties structure.

During the RTXC Kernel initialization procedure, you must define the kernel objects needed by the kernel to perform the application. The INIT_MutxClassProp kernel service allocates space for the Mutex 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 Mutex KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 8-1 on page 271.

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

During system initialization, the startup code must initialize the Mutex 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 8-10 on page 281, that structure is referenced externally to the code module.

280

RTXC Kernel Services Reference, Volume 2

INIT_MutxClassProp

Example 8-10. Initialize Mutex Object Class

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

extern const SYSPROP sysprop; extern const KCLASSPROP mutxclassprop; KSRC userinit (void) { KSRC ksrc; /* initialize the kernel workspace and 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 Mutex kernel object class */ if ((ksrc = INIT_MutxClassProp (&mutxclassprop)) != RC_GOOD) { putline ("No RAM for Mutex init"); return (ksrc); /* end initialization process */ } ... Continue with system initialization }

See Also

INIT_SysProp, page 310 KS_GetMutxClassProp, page 270

Chapter 8: Mutex Services

281

KS_LookupMutx

KS_LookupMutx
Look up a mutexs name to get its handle.

Synopsis Inputs

KSRC KS_LookupMutx (const char pname, MUTX pmutex)

pname pmutex

A pointer to a null-terminated name string. A pointer to a variable in which to store the mutex handle.

Description

The KS_LookupMutx kernel service obtains the handle of the static or dynamic mutex 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 mutex name or when it finds no match. The service stores the matching mutexs handle in the variable pointed to by pmutex. The service searches dynamic names, if any, first.
Note: To use this service on static mutexes, you must enable the Static Names attribute of the Mutex class during system generation.

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

Output

This service returns a KSRC value as follows:

RC_GOOD if the search succeeds. The service also stores the

matching mutexs handle in the variable pointed to by pmutex.

RC_OBJECT_NOT_FOUND if the service finds no matching mutex

name.

Example

In Example 8-11 on page 283, the Current Task needs to use the resource protected by the dynamic mutex named Chnl2Mutx. If the

282

RTXC Kernel Services Reference, Volume 2

KS_LookupMutx

mutex is found, the Current Task uses KS_TestMutxW to become the owner of the associated resource.
Example 8-11. Look Up Mutex by Name
#include "rtxcapi.h" MUTX dynmutx; /* lookup the mutex name to see if it exists */ if (KS_LookupMutx ("Chnl2Mutx", &dynmutx) != RC_GOOD) { ... Mutex name not found. Deal with it } else /* mutex exists */ { /* gain exclusive access to the resource */ KS_TestMutxW (dynmutx); ...ok to use "Chnl2Mutx" resource now } /* RTXC Kernel Service prototypes */

See Also

KS_DefMutxName, page 262 KS_OpenMutx, page 284

Chapter 8: Mutex Services

283

KS_OpenMutx

KS_OpenMutx
Allocate and name a dynamic mutex.

Synopsis Inputs

KSRC KS_OpenMutx (const char pname, MUTX pmutex)

pname pmutex

A pointer to a null-terminated name string. A pointer to a variable in which to store the mutex handle.

Description

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

If the pointer to the mutex name is not null ((char *)0), the time required to perform this operation varies with the number of mutex names in use. If the pointer to the mutex name is null, no search of mutex names takes place and the time to perform the service is

284

RTXC Kernel Services Reference, Volume 2

KS_OpenMutx

fixed. You can define the mutex name at a later time with a call to the KS_DefMutxName 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 allocated mutex in the variable pointed to by pmutex.
RC_OBJECT_ALREADY_EXISTS if the name search finds another

mutex whose name matches the specified string.

RC_NO_OBJECT_AVAILABLE if the name search finds no match

but all dynamic mutexes are in use.

Example

Example 8-12 allocates a dynamic mutex and names it MuxChnl2Mutx. If the name is already being used, the example outputs a message on the console.

Example 8-12. Allocate and Name Mutex

#include "rtxcapi.h" KSRC ksrc; MUTX dynmutx; if ((ksrc = KS_OpenMutx ("MuxChnl2Mutx", &dynmutx)) != RC_GOOD) { if (ksrc == RC_OBJECT_ALREADY_EXISTS) putline ("MuxChnl2Mutx mutex name in use"); else if (ksrc == RC_NO_OBJECT_AVAILABLE) putline ("No dynamic mutexes available"); else putline ("Mutexes object class not defined"); } ... mutex was opened correctly. Okay to use it now /* RTXC Kernel Service prototypes */

See Also

KS_CloseMutx, page 260 KS_LookupMutx, page 282 KS_UseMutx, page 296

Chapter 8: Mutex Services

285

KS_ReleaseMutx

KS_ReleaseMutx
Release ownership of a mutex.

Synopsis Inputs Description

KSRC KS_ReleaseMutx (MUTX mutex)

mutex

The handle of the mutex being released.

The KS_ReleaseMutx kernel service releases the specified mutex. This service is the opposite of the KS_TestMutx service and its variants. Only the task that locked the mutex, known as the mutex owner, may release that mutex. Attempting to release a mutex that is not currently owned causes no change in the state of the mutex. Attempting to release a busy mutex that is not owned by the task requesting the release is not permitted and results in the service returning a value indicating the error. Typically, the lock and release of a mutex occurs in a pair. That is, for each KS_TestMutx call for a specific mutex, there should be a corresponding KS_ReleaseMutx for that same mutex by the locking task. However, the RTXC Kernel supports nested locks of a mutex by the same task. Nesting occurs when a mutex owner locks the mutex again, either deliberately or inadvertently. When unnesting, the owning task must issue the same number of releases as there are locks in the nest.

Output

This service returns a KSRC value as follows:

RC_GOOD if the mutex is released and not nested. RC_NESTED if the calling task is the mutex owner but has not

issued as many releases as locks.

RC_BUSY if the mutex is owned by another task. RC_ILLEGAL_USE if the mutex is not owned by any task.

286

RTXC Kernel Services Reference, Volume 2

KS_ReleaseMutx

Note: For return values of either RC_NESTED or RC_BUSY, the service optionally returns the current nesting level of the mutex at the address pointed to by pcount.

Errors

This service may generate one of the following fatal error codes:
FE_ILLEGAL_MUTX if the specified mutex ID is not valid. FE_UNINITIALIZED_MUTX if the specified mutex has not yet

been initialized.

Example

In Example 8-13, the Current Task needs to update a memory resident database without other tasks preempting the operation. Therefore, the task needs exclusive access to the database during the update operation. The database resource is associated with the DATABASE mutex. After performing the update, the task permits other tasks to access the database.

Example 8-13. Release Mutex

#include "rtxcapi.h" #include "kmutx.h" /* RTXC Kernel Service prototypes */ /* defines DATABASE */

/* grab resource by locking mutex */ KS_TestMutxW (DATABASE); ... update shared database /* release mutex */ KS_ReleaseMutx (DATABASE); ...continue

See Also

KS_TestMutx, page 288 KS_TestMutxT, page 290 KS_TestMutxW, page 294

Chapter 8: Mutex Services

287

KS_TestMutx

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

Synopsis Input Description

TASK KS_TestMutx (MUTX mutex)

mutex

The handle of the mutex being tested.

The KS_TestMutx kernel service requests or manages a logical or physical resource during a period of exclusive use. A resource can be anything, such as a shared database, non-reentrant code, a math coprocessor or emulator library, and so on. To gain exclusive use of the resource, the calling task associates a mutex with it and attempts to lock it with a call to this kernel service. The service tests the specified mutex. If the service finds the mutex to be idle, it marks the mutex as BUSY. If a task other than the calling task owns the mutex at the time of request, the service denies the request. The kernel supports nested lock requests by the current owner.

Output

This service returns a TASK type value containing either the handle of the task that owns the mutex or zero (0) if the mutex is not busy at the time of the request. The service also returns a value of zero (0) if the requesting task already owns the mutex. Because KS_TestMutx locks an idle mutex, a returned TASK value of zero (0) indicates the mutex is now (or still) owned by the requesting task. This service may generate one of the following fatal error codes:
FE_ILLEGAL_MUTX if the specified mutex ID is not valid. FE_UNINITIALIZED_MUTX if the specified mutex has not yet

Errors

been initialized.

Example

In Example 8-14 on page 289, the Current Task wants to output a system status report to the system printer without interspersed messages from other system monitors. When the report is finished, the task releases exclusive use of the printer.

288

RTXC Kernel Services Reference, Volume 2

KS_TestMutx

If the printer is unavailable, the example performs a code segment to handle the situation. In this example, the Current Task does not own the resource before calling KS_TestMutx.
Example 8-14. Test Mutex for Ownership by Current Task
#include "rtxcapi.h" #include "kmutx.h" /* RTXC Kernel Service prototypes */ /* defines PRINTER */

if (KS_TestMutx (PRINTER) != (TASK)0) { ...PRINTER is owned by another task. Deal with it. } else { ... PRINTER is now locked for exclusive use during printing of status report /* release PRINTER lock */ KS_ReleaseMutx (PRINTER); }

See Also

KS_TestMutxT, page 290 KS_TestMutxW, page 294 KS_ReleaseMutx, page 286

Chapter 8: Mutex Services

289

KS_TestMutxT

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.

Synopsis Inputs

TASK KS_TestMutxT (MUTX mutex, COUNTER counter, TICKS ticks)

mutex pcount counter ticks

The handle of the mutex being tested. A pointer to a variable in which to store the nesting level of the mutex. The counter associated with the interval defined by ticks. The number of ticks on the specified counter to wait for the mutex to become available.

Description

The KS_TestMutxT kernel service requests or manages a logical or physical resource during a period of exclusive use. A resource can be anything, such as a shared database, non-reentrant code, a math coprocessor or emulator library, and so on. To gain exclusive use of the resource, the calling task associates a mutex with it and attempts to lock it with a call to this kernel service. The service tests the specified mutex. If the service finds the mutex to be idle, it marks the mutex as BUSY. The kernel supports nested lock requests by the current owner. If a task other than the calling task owns the mutex at the time of request, the service blocks the calling task and starts an internal alarm for the interval specified in ticks on the specified counter. If the service blocks the calling task, the task remains blocked until one of two events occurs: The task currently using the mutex releases it and the calling task is the first waiter, or The specified number of ticks elapses.

Output

This service returns a TASK type value as follows:

290

RTXC Kernel Services Reference, Volume 2

KS_TestMutxT

If the calling task already owns the mutex, an internal alarm is not started and the service immediately returns a value of zero (0). If the service obtains ownership of the mutex for the calling task before the specified number of ticks elapses, the service returns a value of zero (0). If the specified number of ticks elapses, the service returns the handle of the task that owns the mutex when the counter expires.

Errors

This service may generate one of the following fatal error codes:
FE_ILLEGAL_MUTX if the specified mutex ID is not valid. FE_UNINITIALIZED_MUTX if the specified mutex 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 8-15 on page 292, the Current Task wants to output a system status report to the system printer without interspersed messages from other system monitors. When the report is finished, the task releases exclusive use of the printer. If the printer is unavailable for a period of five seconds relative to the SECCLK counter, the example executes a code segment to handle the situation and then tries it again.

Chapter 8: Mutex Services

291

KS_TestMutxT

Example 8-15. Test MutexWait Number of Ticks If Not Available

#include "rtxcapi.h" #include "kmutx.h" #include "kcounter.h" /* RTXC Kernel Service prototypes */ /* defines PRINTER */ /* defines SECCLK, SECTICK */

/* lock mutex for the Printer resource. Limit WAIT to 5 sec. */ while ((KS_TestMutxT (PRINTER, SECCLK, (TICKS)5/SECTICK)) != (TASK)0) { ... Mutex unavailable. Timeout occurred. Deal with it. } ...PRINTER mutex is now locked and no other task may gain access to it. /* free PRINTER lock */ KS_ReleaseMutx (PRINTER);

See Also

KS_TestMutx, page 288 KS_TestMutxW, page 294 KS_ReleaseMutx, page 286

292

RTXC Kernel Services Reference, Volume 2

KS_TestMutxT

Chapter 8: Mutex Services

293

KS_TestMutxW

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

Synopsis Input Description

void KS_TestMutxW (MUTX mutex)

mutex

The handle of the mutex being tested.

The KS_TestMutxW kernel service requests or manages a logical or physical resource during a period of exclusive use. A resource can be anything, such as a shared database, non-reentrant code, a math coprocessor or emulator library, and so on. To gain exclusive use of the resource, the calling task associates a mutex with it and attempts to lock it with a call to this kernel service. The service tests the specified mutex. If the service finds the mutex to be idle, it marks the mutex as BUSY. The kernel supports nested lock requests by the current owner. If a task other than the calling task owns the mutex at the time of request, the service blocks the calling task and waits until the current mutex owner releases it and the calling task is the first waiter for the mutex. If the calling task already owns the specified mutex, the service returns immediately with an indication of a successful completion.

Output Errors

been initialized.

Example

In Example 8-16 on page 295, the Current Task wants exclusive use of the system printer so that it can output a system status report without interspersed messages from other system monitors. When the report is finished, the task releases exclusive use of the printer.

294

RTXC Kernel Services Reference, Volume 2

KS_TestMutxW

If the printer is busy, the task does not proceed; instead, it waits unconditionally for the printer to become available.
Example 8-16. Test MutexWait If Not Available
#include "rtxcapi.h" #include "kmutx.h" KS_TestMutxW (PRINTER); ...PRINTER mutex is now owned by Current Task. Use it. /* free PRINTER mutex */ KS_ReleaseMutx (PRINTER); /* RTXC Kernel Service prototypes */ /* defines PRINTER */

See Also

KS_TestMutx, page 288 KS_TestMutxT, page 290 KS_ReleaseMutx, page 286

Chapter 8: Mutex Services

295

KS_UseMutx

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

Synopsis Inputs

KSRC KS_UseMutx (const char pname, MUTX pmutex)

pname pmutex

A pointer to a null-terminated name string. A pointer to a variable in which to store the mutex handle.

Description

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

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

Output

This service returns a KSRC value as follows:

RC_GOOD if the search is successful. The service also stores the

matching mutexs handle in the variable pointed to by pmutex.

RC_STATIC_OBJECT if the specified name belongs to a static

mutex.
RC_OBJECT_NOT_FOUND if the service finds no matching mutex

name.

Example

Example 8-17 on page 297 locates a dynamic mutex named DynMuxMutx3 and obtains its handle for subsequent use.

296

RTXC Kernel Services Reference, Volume 2

KS_UseMutx

Example 8-17. Read Mutex Handle and Register It

#include "rtxcapi.h" KSRC ksrc; MUTX dynmutx; if ((ksrc = KS_UseMutx ("DynMuxMutx3", &dynmutx)) != RC_GOOD) { if (ksrc == RC_STATIC_OBJECT) putline ("DynMuxMutx3 is a static mutex"); else putline ("Mutex DynMuxMutx3 name not found"); } ... mutex was found and its handle is in dynmutx. Okay to use it now /* RTXC Kernel Service prototypes */

See Also

KS_DefMutxProp, page 264 KS_DefMutxName, page 262 KS_OpenMutx, page 284

Chapter 8: Mutex Services

297

KS_UseMutx

298

RTXC Kernel Services Reference, Volume 2

CHAPTER

Special Services

In This Chapter
We describe the Special kernel services in detail. The Special services provide for user-defined extensions to the RTXC Kernel.
XX_AllocSysRAM..............................................................................300 XX_DefFatalErrorHandler ................................................................302 XX_GetFatalErrorHandler ................................................................ 305 XX_GetFreeSysRAMSize ..................................................................304 KS_GetSysProp.................................................................................306 KS_GetVersion .................................................................................308 INIT_SysProp ................................................................................... 310 KS_Nop..............................................................................................313 KS_UserService ................................................................................ 314

Chapter 9: Special Services

299

XX_AllocSysRAM

XX_AllocSysRAM
Allocate a block of system RAM.

Zones Synopsis Input Description

TS_AllocSysRAM KS_AllocSysRAM
void * XX_AllocSysRAM (ksize_t blksize)

blksize

The size in bytes of the block of RAM to allocate.

The XX_AllocSysRAM kernel service allocates a block of system RAM of size blksize. You define the amount of system RAM available to the kernel during the kernel generation process (that is, in the RTXCgen program). The kernel uses this RAM during RTXC Kernel initialization processing for its internal tables. The kernel keeps track of the amount of this RAM it needs and allows you to allocate any extra RAM from this area of memory.
Note: The RTXC Kernel provides no inverse function to release RAM allocated by this function.

Output

If successful, this service returns a pointer to the first address of the allocated block. If the size of the requested block exceeds the amount of available system RAM, the service returns a null pointer ((void *)0).

Example

In Example 9-1 on page 301, the application needs a 256-byte block of system RAM. If the allocation is successful, the pointer to the block is to be stored in the p pointer. If there is not enough free RAM available, the task must take the appropriate action.

300

RTXC Kernel Services Reference, Volume 2

XX_AllocSysRAM

Example 9-1. Allocate System RAM from Zone 3

#include "rtxcapi.h" void *p; if ((p = KS_AllocSysRAM (256)) == (void *)0) { ... Deal with no memory available } else { ... Allocation was successful } /* RTXC Kernel Services prototypes */

Chapter 9: Special Services

301

XX_DefFatalErrorHandler

XX_DefFatalErrorHandler
Establish the system error function.

Zones Synopsis Input Description

TS_DefFatalErrorHandler KS_DefFatalErrorHandler
void XX_DefFatalErrorHandler (int (*errfunc) (void *))

errfunc

The entry address for the error function.

The XX_DefFatalErrorHandler kernel service establishes a function to which the RTXC Kernel branches upon detection of a fatal error. The errfunc argument specifies the entry address for the error function. This service does not return a value. Example 9-2 on page 303 defines the kerror function for receiving all fatal RTXC Kernel usage errors. The specified error function requires two arguments as shown in the example: the handle of the Current Task at the time of the error, task, and a pointer to that tasks interrupt stack frame, pinfo. The error function returns an int type value. If the returned value is non-zero, the RTXC Kernel aborts the Current Task. The kernel ignores the error if the returned value is zero (0).

Output Example

302

RTXC Kernel Services Reference, Volume 2

XX_DefFatalErrorHandler

Example 9-2. Define Fatal Error Function

#include "rtxcapi.h" /* RTXC Kernel Services prototypes */

void fehandler (FEPACKET *fepacket); /* prototype for Error Handler */ KS_DefFatalErrorHandler (fehandler); /* define error handler function */ ... continue /* System Error Handler for Fatal RTXC Usage */ void fehandler (FEPACKET *fepacket) { ...Do what has to be done here: display the point of error, kill the system, whatever is suitable to the application return (1); /* have RTXC abort Current Task */ }

See Also

XX_GetFatalErrorHandler, page 305

Chapter 9: Special Services

303

XX_GetFreeSysRAMSize

XX_GetFreeSysRAMSize
Get the size of free system RAM.

Zones Synopsis Inputs Description Output Example

TS_GetFreeSysRAMSize KS_GetFreeSysRAMSize
ksize_t XX_GetFreeSysRAMSize (void)

This service has no inputs. The XX_GetFreeSysRAMSize kernel service determines the amount of free system RAM that is available to the user. The service returns the number of remaining free bytes of system RAM. The task in Example 9-3 needs to allocate 2000 bytes of system RAM. It obtains the amount of available system RAM and prints a message if there is less than 2000 bytes.

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

#include <stdio.h> #include "rtxcapi.h" static char buffer[128]; ksize_t freeRAM; if ((freeRAM = KS_GetFreeSysRAMSize ()) < 2000) { sprintf (buf, "Only %d free bytes of System RAM", freeRAM); putline (buf); } else { ... enough RAM available, continue initialization }

/* RTXC Kernel Services prototypes */

See Also

XX_AllocSysRAM, page 300

304

RTXC Kernel Services Reference, Volume 2

XX_GetFatalErrorHandler

XX_GetFatalErrorHandler
Get the system error function.

Zones Synopsis Inputs Description

TS_GetFatalErrorHandler KS_GetFatalErrorHandler
int (*)(void *)) XX_GetFatalErrorHandler (void)

This service has no inputs. The XX_GetFatalErrorHandler kernel service returns a pointer to the function registered to handle fatal system conditions by a previous XX_DefFatalErrorHandler call. The service returns a pointer to the error function installed by a previous call to XX_DefFatalErrorHandler. If no error function has been installed, the kernel service returns a null function pointer ((int (*)(void *)) 0).

Output

Example

Example 9-4 needs to know if an error function has been defined. If not, XX_DefFatalErrorHandler is used to establish kerror, a function external to the Current Task, as the system error handler.

Example 9-4. Read Fatal Error Function

#include "rtxcapi.h" /* RTXC Kernel Services prototypes */

extern void fehandler (FEPACKET *fepacket); if (KS_GetFatalErrorHandler () == (void (*)(FEPACKET *fepacket))0) KS_DefFatalErrorHandler (fehandler); ...Error handler is now in place, continue

See Also

XX_DefFatalErrorHandler, page 302

Chapter 9: Special Services

305

KS_GetSysProp

KS_GetSysProp
Get the system properties.

Synopsis Inputs Description

const SYSPROP * KS_GetSysProp (void)

This service has no inputs. The KS_GetSysProp kernel service returns a pointer to a SYSPROP structure containing the system properties used to initialize the system through the INIT_SysProp service. The SYSPROP structure has the following organization:

typedef struct { KATTR attributes; unsigned long version; char *sysrambase; ksize_t sysramsize; char *kernelstackbase; ksize_t kernelstacksize; unsigned long reserve1; unsigned long reserve2; } SYSPROP;

/* /* /* /* /* /* /* /*

system attributes */ kernel version number */ base address of system RAM */ size (bytes) of system RAM */ base address of kernel stack */ size (bytes) of kernel stack */ reserved */ reserved */

Output Example

The function always returns a pointer to a SYSPROP structure. Example 9-5 on page 307 reads the clock rate that was established when the system was initialized and sends it to the console.

306

RTXC Kernel Services Reference, Volume 2

KS_GetSysProp

Example 9-5. Read System Properties

#include "rtxcapi.h" /* RTXC Kernel Services prototypes */

static char buf[128]; SYSPROP *psysprop = KS_GetSysProp (); putline (buf); ... continue

See Also

INIT_SysProp, page 310

Chapter 9: Special Services

307

KS_GetVersion

KS_GetVersion
Get the version number of the Kernel.

Synopsis Inputs Description Output

unsigned long KS_GetVersion (void)

This service has no inputs. The KS_GetVersion kernel service returns the version number of the RTXC Kernel. The function returns a value that contains the version number formatted as follows:
Bits 3116 Bits 1508 Bits 0700 System Use Version number (hexadecimal) Release number (hexadecimal)

Note: The developer defines bits 31 through 16 during system generation. This bit field is the developers version number for the application.

Example

Example 9-6 on page 309 obtains the RTXC Kernel version number and displays it on the console.

308

RTXC Kernel Services Reference, Volume 2

KS_GetVersion

Example 9-6. Read Version Number

#include <stdio.h> #include "rtxcapi.h" /* standard i/o */ /* RTXC Kernel Services prototypes */

static char buf[128]; union RTXCver { unsigned long version; struct { unsigned short sysnum; /* reserved for system use */ unsigned char ver; /* version number */ unsigned char rel; /* release number */ } vr; }curVR; curVR.version = KS_GetVersion (); /* get RTXC version */ sprintf (buf, "Current RTXC version.release is %d.%d", curVR.vr.ver, curVR.vr.rel); putline (buf); /* display version # */ ... continue

Chapter 9: Special Services

309

INIT_SysProp

INIT_SysProp
Initialize the RTXC system properties.

Synopsis Input Description

KSRC INIT_SysProp (const SYSPROP *psysprop)

psysprop

A pointer to a SYSPROP structure.

The INIT_SysProp service performs the required initialization procedure and must be called before any other RTXC kernel service or system function. It passes the system properties, as defined by the user during system generation and found in the SYSPROP structure pointed to by psysprop, to the kernel. The system properties specify information about how the RTXC Kernel is to operate. The SYSPROP structure has the following organization:

/* /* /* /* /* /* /* /*

system attributes */ kernel version number */ base address of system RAM */ size (bytes) of system RAM */ base address of kernel stack */ size (bytes) of kernel stack */ reserved */ reserved */

The system attributes specify the object classes that are defined for the application. The attributes element of the SYSPROP structure supports the attributes and corresponding masks listed in Table 9-1 on page 311.

310

RTXC Kernel Services Reference, Volume 2

INIT_SysProp

Table 9-1. System Attributes and Masks

Attribute Tasks Threads Semaphores Queues Mailboxes Partitions Pipes Mutexes Event Sources Counters Alarms Exceptions Mask K_ATTR_TASKS K_ATTR_THREADS K_ATTR_SEMAPHORES K_ATTR_QUEUES K_ATTR_MAILBOXES K_ATTR_PARTITIONS K_ATTR_PIPES K_ATTR_MUTEXES K_ATTR_SOURCES K_ATTR_COUNTERS K_ATTR_ALARMS K_ATTR_EXCEPTIONS

Output

The service returns a KSRC value as follows:

RC_GOOD if the service completes successfully. RC_VERSION_MISMATCH if the version number passed in the SYSPROP structure is different from the version stored within

the RTXC Kernel.

Example

During system initialization, the startup code must initialize the kernel properties before initializing the needed kernel object classes. The system generation process produces a structure of type SYSPROP that contains the information about the system necessary for its initialization. Example 9-7 on page 312 externally references that structure and outputs any error messages to the console.

Chapter 9: Special Services

311

INIT_SysProp

Example 9-7. Initialize Kernel Properties

#include "rtxcapi.h" /* RTXC KC prototypes */

extern const SYSPROP sysprop; KSRC userinit (void) { KSRC ksrc; static char buf[128]; /* initialize the system properties if ((ksrc = INIT_SysProp (&sysprop)) != RC_GOOD) { putline ("Kernel initialization failure\n"); return ksrc; /* end initialization process */ } /* kernel is initialized */ /* Proceed now with init of kernel object classes */ ... Continue with system initialization }

See Also

KS_GetSysProp, page 306

312

RTXC Kernel Services Reference, Volume 2

KS_Nop

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

Synopsis Inputs Description

void KS_Nop (void)

This service has no inputs. Although the KS_Nop function is included in the set of kernel services, it serves no useful purpose other than as a means of benchmarking performance for entry into and exit from the kernel. This service does not return a value. Example 9-8 performs 10,000 iterations of the KS_Nop kernel service and computes the elapsed time of those calls in units of system clock ticks using the TIMEBASE counter.

Output Example

Example 9-8. Execute No-Operation Service

#include <stdio.h> #include "rtxcapi.h" static char buf[128]; int i; TICKS timestamp, et; /* sleep for one tick to sync with clock */ KS_SleepTask (TIMEBASE, 1); KS_ElapsedCounterTicks (TIMEBASE, &timestamp); timestamp */ for (i = 0; i < 10000; i++) KS_Nop (); /* standard i/o */ /* RTXC Kernel Services prototypes */

/* initialize

/* read elapsed time after 10000 loops */ et = KS_ElapsedCounterTicks (TIMEBASE, &timestamp); sprintf (buf, "10000 KS_Nop calls in %d ticks", et); putline (buf); /* display the results */ ...continue

Chapter 9: Special Services

313

KS_UserService

KS_UserService
Perform a user-defined kernel service.

Synopsis Inputs

int KS_UserService (int (func) (void ), void *parg)

func parg

A pointer to a function. A pointer to an arbitrary structure.

Description

The KS_UserService kernel service executes the function pointed to by func as if it were a kernel service function. The service basically defines the function to be indivisible with respect to preemption. Interrupts are permitted and can be serviced during execution of the function. However, func cannot call other kernel services. The parg argument points to an arbitrary structure that is passed to the function when it is called. The KS_UserService service returns to the caller the return value from the specified function.

Output Example

The KS_UserService function returns the value of the specified function as its own function value. Example 9-9 on page 315 calls the copymem function to copy data from one area to another. The function needs to execute as though it were a kernel service to prevent the possibility of preemption. Arguments to the function are found in the args structure, the pointer to which is passed in the calling arguments to the function.

314

RTXC Kernel Services Reference, Volume 2

KS_UserService

Example 9-9. Execute Non-RTXC Function as Kernel Service

#include "rtxcapi.h" int status; struct copyarg { char *source; char *destination; int length; } args; extern int copymem (struct copyarg *); ... fill in values for args struct /* execute function copymem as a Kernel Service */ status = KS_UserService (copymem, &args); /* RTXC Kernel Services prototypes */

Chapter 9: Special Services

315

KS_UserService

316

RTXC Kernel Services Reference, Volume 2

APPENDIX

Fatal Error Codes

This appendix lists the fatal error codes returned by RTXC/ms kernel services.

F
FE_ILLEGAL_COUNTER The specified counter ID is not valid. KS_AllocBlkT 227 KS_GetQueueDataT 139 KS_PutQueueDataT 159 KS_ReceiveMsgT 203 KS_SendMsgT 210 KS_TestAckT 219 KS_TestMutxT 291 KS_TestSemaMT 113 KS_TestSemaT 109 FE_ILLEGAL_MBOX The specified mailbox ID is not valid. KS_CloseMbox 167 KS_DefMboxName 168 KS_DefMboxProp 170 KS_DefMboxSema 172 KS_ForwardMsg 197 KS_GetMboxName 178 KS_GetMboxProp 180 KS_GetMboxSema 182 KS_ReceiveMsg 200 KS_ReceiveMsgT 203 KS_ReceiveMsgW 204 KS_SendMsg 207 KS_SendMsgT 210 KS_SendMsgW 214

FE_ILLEGAL_MUTX The specified mutex ID is not valid. KS_CloseMutx 260 KS_DefMutxName 262 KS_DefMutxProp 265 KS_DefMutxSema 267 KS_GetMutxName 272 KS_GetMutxOwner 274 KS_GetMutxProp 277 KS_GetMutxSema 278 KS_ReleaseMutx 287 KS_TestMutx 288 KS_TestMutxT 291 KS_TestMutxW 294 FE_ILLEGAL_PART The specified partition ID is not valid. KS_AllocBlk 224 KS_AllocBlkT 226 KS_AllocBlkW 228 KS_ClosePart 231 KS_DefPartName 232 KS_DefPartProp 235 KS_DefPartSema 236 KS_FreeBlk 239 KS_GetFreeBlkCount 240 KS_GetPartName 244 KS_GetPartProp 246 KS_GetPartSema 248 FE_ILLEGAL_PRIORITY The specified priority value is out of range.

Appendix A: Fatal Error Codes

317

KS_DefTaskPriority 33 KS_DefTaskProp 34 FE_ILLEGAL_QUEUE The specified queue ID is not valid. KS_CloseQueue 125 KS_DefQueueName 126 KS_DefQueueProp 129 KS_DefQueueSema 130 KS_GetQueueData 136 KS_GetQueueDataT 139 KS_GetQueueDataW 140 KS_GetQueueName 142 KS_GetQueueProp 144 KS_GetQueueSema 146 KS_PutQueueData 156 KS_PutQueueDataT 159 KS_PutQueueDataW 160 FE_ILLEGAL_SEMA The specified semaphore ID is not valid. KS_CloseSema 81 KS_DefMboxSema 172 KS_DefMutxSema 267 KS_DefPartSema 236 KS_DefQueueSema 131 KS_DefSemaCount 82 KS_DefSemaName 84 KS_DefSemaProp 87 KS_DefTaskSema 36 KS_GetSemaCount 90 KS_GetSemaName 92 KS_GetSemaProp 94 KS_TestSema 106 KS_TestSemaM 110 KS_TestSemaMT 113 KS_TestSemaMW 116 KS_TestSemaT 109 KS_TestSemaW 118 XX_SignalSema 102 XX_SignalSemaM 104

FE_ILLEGAL_TASK The specified task ID is not valid. KS_AbortTask 24 KS_CloseTask 25 KS_DefTaskEnvArg 27 KS_DefTaskName 30 KS_DefTaskPriority 32 KS_DefTaskProp 34 KS_DefTaskSema 36 KS_DefTickSlice 38 KS_ExecuteTask 42 KS_GetTaskEnvArg 44 KS_GetTaskName 51 KS_GetTaskPriority 53 KS_GetTaskProp 54 KS_GetTaskSema 56 KS_GetTaskState 58 KS_GetTickSlice 60 KS_SuspendTask 71 KS_TerminateTask 72 XX_ResumeTask 68 FE_INVALID_MSG_PRIORITY The specified message priority value is not either URGENT or NORMAL. KS_ForwardMsg 197 KS_SendMsg 207 KS_SendMsgT 211 KS_SendMsgW 214 FE_INVALID_QEVENT The specified queue event value is not either QNF or QNE. KS_DefQueueSema 131 KS_GetQueueSema 146 FE_NULL_DESTBUFFER The pointer to the destination buffer is null. KS_GetQueueData 136 KS_GetQueueDataT 139 KS_GetQueueDataW 140

318

RTXC Kernel Services Reference, Volume 2

FE_NULL_MSGENV KS_SendMsgT 211 KS_TestAckT 219 The pointer to the message envelope is null. KS_TestMutxT 291 KS_AckMsg 194 KS_TestSemaMT 113 KS_ForwardMsg 197 KS_TestSemaT 109 KS_SendMsg 207 FE_UNINITIALIZED_MBOX KS_SendMsgT 211 The specified mailbox has not yet been initialized. KS_SendMsgW 214 KS_TestAck 216 KS_DefMboxSema 172 KS_TestAckT 219 KS_ForwardMsg 197 KS_TestAckW 220 KS_GetMboxProp 180 FE_NULL_PARTBASE KS_GetMboxSema 182 The specified partition base address is KS_ReceiveMsg 200 null. KS_ReceiveMsgT 203 KS_DefPartProp 235 KS_ReceiveMsgW 204 FE_NULL_PARTBLKPTR KS_SendMsg 207 The pointer to the block of memory is KS_SendMsgT 210 null. KS_SendMsgW 214 KS_FreeBlk 239 FE_UNINITIALIZED_MUTX FE_NULL_QUEUEBASE The specified mutex has not yet been initialized. The specified queue base address is null. KS_DefQueueProp 129 KS_DefMutxSema 267 FE_NULL_SOURCEBUFFER KS_GetMutxOwner 274 KS_GetMutxProp 277 The pointer to the source buffer is null. KS_PutQueueData 156 KS_GetMutxSema 278 KS_PutQueueDataT 159 KS_ReleaseMutx 287 KS_PutQueueDataW 160 KS_TestMutx 288 FE_NULL_STACKBASE KS_TestMutxT 291 KS_TestMutxW 294 The specified Task stack base address is null. FE_UNINITIALIZED_PART KS_DefTaskProp 35 The specified partition has not yet been initialized. FE_NULL_TASKENTRY The specified Task entry address is null. KS_AllocBlk 224 KS_DefTaskProp 35 KS_AllocBlkT 227 FE_UNINITIALIZED_COUNTER KS_AllocBlkW 228 KS_AllocBlkT 227 KS_DefPartSema 236 KS_GetQueueDataT 139 KS_FreeBlk 239 KS_PutQueueDataT 159 KS_GetFreeBlkCount 240 KS_ReceiveMsgT 203 KS_GetPartProp 247

Appendix A: Fatal Error Codes

319

KS_GetPartSema 248 FE_UNINITIALIZED_QUEUE The specified queue has not yet been initialized. KS_DefQueueProp 129 KS_DefQueueSema 131 KS_GetQueueData 136 KS_GetQueueDataT 139 KS_GetQueueDataW 140 KS_GetQueueProp 144 KS_GetQueueSema 146 KS_PutQueueData 156 KS_PutQueueDataT 159 KS_PutQueueDataW 160 FE_UNINITIALIZED_SEMA The specified semaphore has not yet been initialized. KS_DefMboxSema 172 KS_DefMutxSema 267 KS_DefPartSema 236 KS_DefQueueSema 131 KS_DefSemaCount 82 KS_GetSemaCount 90 KS_GetSemaProp 94 KS_TestSema 106 KS_TestSemaM 110 KS_TestSemaMT 113 KS_TestSemaMW 116 KS_TestSemaT 109 KS_TestSemaW 118 XX_SignalSema 102 XX_SignalSemaM 104 FE_UNINITIALIZED_TASK The specified task has not yet been initialized. KS_AbortTask 24 KS_DefTaskEnvArg 27 KS_DefTaskPriority 32 KS_DefTaskSema 36

KS_DefTickSlice 39 KS_ExecuteTask 42 KS_GetTaskEnvArg 44 KS_GetTaskPriority 53 KS_GetTaskProp 54 KS_GetTaskSema 56 KS_GetTaskState 58 KS_GetTickSlice 60 KS_SuspendTask 71 KS_TerminateTask 72 XX_ResumeTask 68 FE_ZERO_PARTCOUNT The specified partition block count is zero. KS_DefPartProp 235 FE_ZERO_PARTSIZE The specified partition size is zero. KS_DefPartProp 235 FE_ZERO_QUEUEDEPTH The specified queue depth is zero. KS_DefQueueProp 129 FE_ZERO_QUEUEWIDTH The specified queue width is zero. KS_DefQueueProp 129 FE_ZERO_STACKSIZE The specified task stack size is zero. KS_DefTaskProp 35

320

RTXC Kernel Services Reference, Volume 2

Index

A
abortion, task semaphore 56 acknowledging message 194 allocating mailbox 188 memory block 224, 226, 228 memory partition 254 mutex 284 queue 152 semaphore 100 task 66 allowing context switching 41 attribute value Signal Type 86 Waiting Order 86

C
C compiler syntactical differences 3 classes, kernel service 7 closing mailbox 166 memory partition 230 mutex 260 queue 124 semaphore 80 task 25 code examples Abort Task and Terminate 24

Acknowledge Message 195 Allocate and Free Memory Block 239 Allocate and Initialize Queue 154 Allocate and Name Memory Partition 255 Allocate and Name Mutex 285 Allocate Block of Memory 225 Allocate Block of MemoryWait If Necessary 229 Allocate Block of MemoryWait Number of Ticks If Necessary 227 Allocate Dynamic Semaphore 101 Allocate Dynamic Task 67 Allocate Mailbox 189 Allocate System RAM from Zone 3 301 Assign Mailbox Name 169 Assign Memory Partition Name 233 Assign Queue Name 127 Assign Semaphore Name 85 Associate Queue Event with Semaphore 132 Associate Semaphore With Memory Partition 237 Associate Semaphore with Mutex 268 Class Properties Structure 88 Close Mailbox 167 Close Memory Partition 231 Close Mutex 261, 263

Index

321

Close Queue 125 Close Semaphore 81 Close Task When Signaled 26 Define Fatal Error Function 303 Define Mailbox Properties 171 Define Mailbox Semaphore 174 Define Memory Partition Properties 235 Define Mutex Properties 266 Define Queue Object Class Properties 129 Define Task Name 31 Define Task Object Class Properties 35 Define Task Priorities 33 Define Task Properties 28 Define Task Termination Semaphore 37 Define Tick Slice 39 Disable Task Scheduler 40 Enable Task Scheduler 41 Execute Non-RTXC Function as Kernel Service 315 Execute No-Operation Service 313 Execute Task 43 Forward Message 198 Initialize Kernel Properties 312 Initialize Mailbox Object Class 185 Initialize Memory Partition Object Class 251 Initialize Mutex Object Class mutex

code examples Initialize Mutex Object Class 281

Initialize Queue Object Class 149 Initialize Semaphore Object Class 97 Initialize Task Object Class 63 Look Up Mailbox by Name 187 Look Up Memory Partition by Name 253 Look Up Mutex by Name 283

Look Up Queue by Name 151 Look Up Semaphore by Name 99 Look Up Task by Name 65 Mailbox Properties Structure 170 Memory Partition Properties Structure 246 Object Class Properties Structure 62 Put Current Task to Sleep 70 Put Data Into Queue 157 Put Data Into QueueWait Number of Ticks If Queue is Full 159 Put Data Into QueueWait Until Queue Has Room 161 Queue Properties Structure 128 Read Amount of Available System RAM from Zone 3 304 Read and Change Task Priority 53 Read Current Task Task Number 50 Read Dynamic Queue Name 143 Read Dynamic Task Name 52 Read Fatal Error Function 305 Read Mailbox Handle and Register It 192 Read Mailbox Name 179 Read Mailbox Object Class Properties 177 Read Mailbox Properties 181 Read Mailbox Semaphore 183 Read Memory Partition Free Block Count 241 Read Memory Partition Handle and Register It 257 Read Memory Partition Name 245 Read Memory Partition Object Class Properties 243 Read Memory Partition Properties 247 Read Memory Partition Semaphore 249

322

RTXC Kernel Services Reference, Volume 2

Read Mutex Handle and Register It 297 Read Mutex Name 273 Read Mutex Object Class Properties 271 Read Mutex Owner 275 Read Mutex Properties 277 Read Mutex Semaphore 279 Read Queue Entry 137 Read Queue EntryWait If Necessary 141 Read Queue EntryWait Number of Ticks If Necessary 139 Read Queue Handle and Register It 163 Read Queue Object Class Properties 135 Read Queue Properties 145 Read Queue Semaphore 147 Read Semaphore Count 91 Read Semaphore Handle and Register It 121 Read Semaphore Name 93 Read Semaphore Object Class Properties 89 Read Semaphore Properties 95 Read System Properties 307 Read Task Environment Arguments 46 Read Task Handle and Register It 75 Read Task Object Class Properties 49 Read Task State 59 Read Task Termination Semaphore 57 Read Task Tick-Slice Quantum 60 Read Version Number 309 Receive MessageWait If Necessary 205 Receive MessageWait Number of Ticks If Necessary 203 Receive Next Message from a Mailbox 201 Release Mutex 287

Resume Suspended Task from Zone 3 69 Semaphore Properties structure 86 Send MessageWait for Acknowledgement 208, 214 Send MessageWait Number of Ticks for Acknowledgement 212 Set Semaphore Count 83 Signal List of Semaphores from Zone 3 105 Signal Semaphore from Zone 3 103 Specify Semaphore Waiting Order 87 Suspend Task 71 Task Properties Structure 34 Terminate Task 73 Terminate Task and Release Its Stack 55 Test for Acknowledgement and Wait if Necessary 221 Test for Message Acknowledgement 217 Test for Message Acknowledgement Wait Number of Ticks for Acknowledgement 219 Test List of Semaphores 111 Test List of SemaphoresWait for Signal 117 Test List of SemaphoresWait Number of Ticks for Signal 114 Test Mutex for Ownership by Current Task 289 Test MutexWait If Not Available 295 Test MutexWait Number of Ticks If Not Available 292 Test Semaphore 107 Test SemaphoreWait for Signal 119 Test SemaphoreWait Number of Ticks for Signal 109 Yield to Another Task 77

Index

323

context switching allowing 41 preventing 40 count, reading semaphore 90 Current Task in examples 3 Current Thread in examples 3

task abortion 36 task termination 36 examples, list of xi

F
freeing memory block 238 function call, general form 4 function prototypes 2 function, system error 302

D
defining mailbox properties 170 memory partition object class properties 250 memory partition properties 234 mutex object class properties 280 mutex properties 264 queue object class properties 148 queue properties 128 semaphore count 82 semaphore properties 86 task environment arguments 27 task object class properties 62 task priority 32 task properties 34 task time-slice quantum 38

H
handle mailbox 186 memory partition 252 mutex 282 queue 150 semaphore 98 task 50, 64

I
INIT_MboxClassProp 184 INIT_MutxClassProp 280 INIT_PartClassProp 250 INIT_QueueClassProp 148 INIT_SemaClassProp 96 INIT_SysProp 310 INIT_TaskClassProp 62 inserting queue entry 156, 158, 160 IS_AllocBlk 224 IS_ResumeTask 68 IS_SignalSema 102 IS_SignalSemaM 104

E
environment arguments 44 environment arguments structure 27, 44 error function, system 302 events Mailbox_Not_Empty 172, 182 Mutex_Not_Busy 267, 278 Partition_Not_Empty 236, 248 Queue_Not_Empty 130, 146 Queue_Not_Full 130, 146

K
KCLASSPROP structure mailbox 176, 184 memory partition 242, 250

324

RTXC Kernel Services Reference, Volume 2

mutex 270, 280 queue 134, 148 semaphore 88, 96 task 47, 62 kernel component RTXC/ms 8 kernel service arguments 5 classes 7 description format 2 function call general form 4 function prototypes 2 INIT_MboxClassProp 184 INIT_MutxClassProp 280 INIT_PartClassProp 250 INIT_QueueClassProp 148 INIT_SemaClassProp 96 INIT_SysProp 310 INIT_TaskClassProp 62 KS_AbortTask 23 KS_AckMsg 194 KS_AllocBlkT 226 KS_AllocBlkW 228 KS_CloseMbox 166 KS_CloseMutx 260 KS_ClosePart 230 KS_CloseQueue 124 KS_CloseSema 80 KS_CloseTask 25 KS_DefMboxName 168 KS_DefMboxProp 170 KS_DefMboxSema 172 KS_DefMutxName 262 KS_DefMutxProp 264 KS_DefMutxSema 267 KS_DefPartName 232 KS_DefPartProp 234

KS_DefPartSema 236 KS_DefQueueName 126 KS_DefQueueProp 128 KS_DefQueueSema 130 KS_DefSemaCount 82 KS_DefSemaName 84 KS_DefSemaProp 86 KS_DefTaskEnvArg 27 KS_DefTaskName 30 KS_DefTaskPriority 32 KS_DefTaskProp 34 KS_DefTaskSema 36 KS_DefTimeSlice 38 KS_DisableTaskScheduler 40 KS_EnableTaskScheduler 41 KS_ExecuteTask 42 KS_ForwardMsg 196 KS_FreeBlk 238 KS_GetFreeBlkCount 240 KS_GetMboxClassProp 176 KS_GetMboxName 178 KS_GetMboxProp 180 KS_GetMboxSema 182 KS_GetMutxClassProp 270 KS_GetMutxName 272 KS_GetMutxOwner 274 KS_GetMutxProp 276 KS_GetMutxSema 278 KS_GetPartClassProp 242 KS_GetPartName 244 KS_GetPartProp 246 KS_GetPartSema 248 KS_GetQueueClassProp 134 KS_GetQueueData 136 KS_GetQueueDataT 138 KS_GetQueueDataW 140 KS_GetQueueName 142

Index

325

KS_GetQueueProp 144 KS_GetQueueSema 146 KS_GetSemaClassProp 88 KS_GetSemaCount 90 KS_GetSemaName 92 KS_GetSemaProp 94 KS_GetSysProp 306 KS_GetTaskClassProp 47 KS_GetTaskEnvArg 44 KS_GetTaskID 50 KS_GetTaskName 51 KS_GetTaskPriority 53 KS_GetTaskProp 54 KS_GetTaskSema 56 KS_GetTaskState 58 KS_GetTimeSlice 60 KS_GetVersion 308 KS_LookupMbox 186 KS_LookupMutx 282 KS_LookupPart 252 KS_LookupQueue 150 KS_LookupSema 98 KS_LookupTask 64 KS_Nop 313 KS_OpenMbox 188 KS_OpenMutx 284 KS_OpenPart 254 KS_OpenQueue 152 KS_OpenSema 100 KS_OpenTask 66 KS_PutQueueData 156 KS_PutQueueDataT 158 KS_PutQueueDataW 160 KS_ReceiveMsg 200 KS_ReceiveMsgT 202 KS_ReceiveMsgW 204 KS_ReleaseMutx 286

KS_SendMsg 206 KS_SendMsgT 209 KS_SendMsgW 213 KS_SleepTask 70 KS_SuspendTask 71 KS_TerminateTask 72 KS_TestAck 216 KS_TestAckT 218 KS_TestAckW 220 KS_TestMutx 288 KS_TestMutxT 290 KS_TestMutxW 294 KS_TestSema 106 KS_TestSemaM 110 KS_TestSemaMT 112 KS_TestSemaMW 115 KS_TestSemaT 108 KS_TestSemaW 118 KS_UseMbox 191 KS_UseMutx 296 KS_UsePart 256 KS_UseQueue 162 KS_UserService 314 KS_UseSema 120 KS_UseTask 74 KS_YieldTask 76 prefix 4 return value types table 6 user-defined 314 XX_AllocBlk 224 XX_AllocSysRAM 300 XX_DefFatalErrorHandler 302 XX_GetFatalErrorHandler 305 XX_GetFreeSysRAMSize 304 XX_ResumeTask 68 XX_SignalSema 102 XX_SignalSemaM 104

326

RTXC Kernel Services Reference, Volume 2

kernel service return code 5 KS_AbortTask 23 KS_AckMsg 194 KS_AllocBlk 224 KS_AllocBlkT 226 KS_AllocBlkW 228 KS_CloseMbox 166 KS_CloseMutx 260 KS_ClosePart 230 KS_CloseQueue 124 KS_CloseSema 80 KS_CloseTask 25 KS_DefFatalErrorHandler 302 KS_DefMboxName 168 KS_DefMboxProp 170 KS_DefMboxSema 172 KS_DefMutxName 262 KS_DefMutxProp 264 KS_DefMutxSema 267 KS_DefPartName 232 KS_DefPartProp 234 KS_DefPartSema 236 KS_DefQueueName 126 KS_DefQueueProp 128 KS_DefQueueSema 130 KS_DefSemaCount 82 KS_DefSemaName 84 KS_DefSemaProp 86 KS_DefTaskEnvArg 27 KS_DefTaskName 30 KS_DefTaskPriority 32 KS_DefTaskProp 34 KS_DefTaskSema 36, 56 KS_DefTimeSlice 38 KS_DisableTaskScheduler 40 KS_EnableTaskScheduler 41 KS_ExecuteTask 42

KS_ForwardMsg 196 KS_FreeBlk 238 KS_GetFatalErrorHandler 305 KS_GetFreeBlkCount 240 KS_GetFreeSysRAMSize 304 KS_GetMboxClassProp 176 KS_GetMboxName 178 KS_GetMboxProp 180 KS_GetMboxSema 182 KS_GetMutxClassProp 270 KS_GetMutxName 272 KS_GetMutxOwner 274 KS_GetMutxProp 276 KS_GetMutxSema 278 KS_GetPartClassProp 242 KS_GetPartName 244 KS_GetPartProp 246 KS_GetPartSema 248 KS_GetQueueClassProp 134 KS_GetQueueData 136 KS_GetQueueDataT 138 KS_GetQueueDataW 140 KS_GetQueueName 142 KS_GetQueueProp 144 KS_GetQueueSema 146 KS_GetSemaClassProp 88 KS_GetSemaCount 90 KS_GetSemaName 92 KS_GetSemaProp 94 KS_GetSysProp 306 KS_GetTaskClassProp 47 KS_GetTaskEnvArg 44 KS_GetTaskID 50 KS_GetTaskName 51 KS_GetTaskPriority 53 KS_GetTaskProp 54 KS_GetTaskSema 56

Index

327

KS_GetTaskState 58 KS_GetTimeSlice 60 KS_GetVersion 308 KS_LookupMbox 186 KS_LookupMutx 282 KS_LookupPart 252 KS_LookupQueue 150 KS_LookupSema 98 KS_LookupTask 64 KS_Nop 313 KS_OpenMbox 188 KS_OpenMutx 284 KS_OpenPart 254 KS_OpenQueue 152 KS_OpenSema 100 KS_OpenTask 66 KS_PutQueueData 156 KS_PutQueueDataT 158 KS_PutQueueDataW 160 KS_ReceiveMsg 200 KS_ReceiveMsgT 202 KS_ReceiveMsgW 204 KS_ReleaseMutx 286 KS_ResumeTask 68 KS_SendMsg 206 KS_SendMsgT 209 KS_SendMsgW 213 KS_SignalSema 102 KS_SignalSemaM 104 KS_SleepTask 70 KS_SuspendTask 71 KS_TerminateTask 72 KS_TestAck 216 KS_TestAckT 218 KS_TestAckW 220 KS_TestMutx 288 KS_TestMutxT 290

KS_TestMutxW 294 KS_TestSema 106 KS_TestSemaM 110 KS_TestSemaMT 112 KS_TestSemaMW 115 KS_TestSemaT 108 KS_TestSemaW 118 KS_UseMbox 191 KS_UseMutx 296 KS_UsePart 256 KS_UseQueue 162 KS_UserService 314 KS_UseSema 80, 120 KS_UseTask 74 KS_YieldTask 76 KSRC 5

L
list of examples xi list of tables ix

M
mailbox allocating 188 closing 166 code examples Allocate Mailbox 189 Assign Mailbox Name 169 Close Mailbox 167 Define Mailbox Properties 171 Define Mailbox Semaphore 174 Initialize Mailbox Object Class 185 Look Up Mailbox by Name 187 Read Mailbox Handle and Register It 192 Read Mailbox Name 179 Read Mailbox Object Class Properties 177

328

RTXC Kernel Services Reference, Volume 2

Read Mailbox Properties 181 Read Mailbox Semaphore 183 defining properties 170 handle 186 KCLASSPROP structure 176, 184 Mailbox_Not_Empty event 172, 182 MBOXPROP structure 170, 180 name 178 naming 168, 188 object class properties 184 properties 180 reading object class properties 176 registering 191 services summary table 14 Mailbox services brief description 14 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 Mailbox_Not_Empty event 172, 182 MBOXPROP structure 170, 180 memory block allocating 224, 226, 228 freeing 238 obtaining number of 240 memory partition allocating 254 closing 230 code examples

Allocate and Free Memory Block 239 Allocate and Name Memory Partition 255 Allocate Block of Memory 225 Allocate Block of MemoryWait If Necessary 229 Allocate Block of MemoryWait Number of Ticks If Necessary 227 Assign Memory Partition Name 233 Associate Semaphore With Memory Partition 237 Close Memory Partition 231 Define Memory Partition Properties 235 Initialize Memory Partition Object Class 251 Look Up Memory Partition by Name 253 Read Memory Partition Free Block Count 241 Read Memory Partition Handle and Register It 257 Read Memory Partition Name 245 Read Memory Partition Object Class Properties 243 Read Memory Partition Properties 247 Read Memory Partition Semaphore 249 defining object class properties 250 defining properties 234 handle 252 KCLASSPROP structure 242, 250 name 244, 252 naming 232, 254 obtaining number of free blocks 240 Partition_Not_Empty event 236, 248 PARTPROP structure 234, 246 properties 246 reading object class properties 242

Index

329

registering 256 services summary table 16 Memory Partition services brief description 16 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 message acknowledging 194 code examples Acknowledge Message 195 Forward Message 198 Receive MessageWait If Necessary 205 Receive MessageWait Number of Ticks If Necessary 203 Receive Next Message from a Mailbox 201 Send MessageWait for Acknowledgement 208, 214 Send MessageWait Number of Ticks for Acknowledgement 212 Test for Acknowledgement and Wait if Necessary 221

Test for Message Acknowledgement 217 Test for Message AcknowledgementWait Number of Ticks for Acknowledgement 219 receiving 200, 202, 204 sending 206, 209, 213 services summary table 15 testing for acknowledgment 216, 218, 220 Message services brief description 15 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 mutex allocating 284 closing 260 code examples Allocate and Name Mutex 285 Associate Semaphore with Mutex 268 Close Mutex 261, 263 Define Mutex Properties 266 Look Up Mutex by Name 283 Read Mutex Handle and Register It 297 Read Mutex Name 273 Read Mutex Object Class Properties 271 Read Mutex Owner 275 Read Mutex Properties 277

330

RTXC Kernel Services Reference, Volume 2

Read Mutex Semaphore 279 Release Mutex 287 Test Mutex for Ownership by Current Task 289 Test MutexWait If Not Available 295 Test MutexWait Number of Ticks If Not Available 292 defining object class properties 280 defining properties 264 handle 282 KCLASSPROP structure 270, 280 Mutex_Not_Busy event 267, 278 MUTXPROP structure 264, 276 name 272, 282 naming 262, 284 owner 274 properties 276 reading object class properties 270 registering 296 releasing 286 services summary table 18 testing availability 288, 290, 294 Mutex services brief description 18 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 KS_OpenMutx 284 KS_ReleaseMutx 286

KS_TestMutx 288 KS_TestMutxT 290 KS_TestMutxW 294 KS_UseMutx 296 Mutex_Not_Busy event 267, 278 MUTXPROP structure 264, 276

N
name mailbox 178 memory partition 244, 252 mutex 272, 282 queue 142, 150 reading semaphore 92 task 51, 64 naming mailbox 168, 188 memory partition 232, 254 mutex 262, 284 queue 126, 152 semaphore 84, 100 task 30, 66 no operation function 313

O
object class properties mailbox 176, 184 memory partition 242, 250 mutex 270, 280 queue 134, 148 semaphore 88, 96 task 47, 62 owner of mutex 274

P
Partition services. See Memory Partition services

Index

331

Partition_Not_Empty event 236, 248 PARTPROP structure 234, 246 preventing context switching 40 priority level, task 53 properties mailbox 170, 180 mailbox object class 176, 184 memory partition 246 memory partition object class 242, 250 mutex 264, 276 mutex object class 270, 280 queue 128, 144 queue object class 134 semaphore 86, 94 semaphore object class 88, 96 system 306 task 54 task object class 47

Q
queue allocating 152 closing 124 code examples Allocate and Initialize Queue 154 Assign Queue Name 127 Associate Queue Event with Semaphore 132 Close Queue 125 Define Queue Object Class Properties 129 Initialize Queue Object Class 149 Look Up Queue by Name 151 Put Data Into Queue 157 Put Data Into QueueWait Number of Ticks If Queue is Full 159 Put Data Into QueueWait Until Queue Has Room 161

Read Dynamic Queue Name 143 Read Queue Entry 137 Read Queue EntryWait If Necessary 141 Read Queue EntryWait Number of Ticks If Necessary 139 Read Queue Handle and Register It 163 Read Queue Object Class Properties 135 Read Queue Properties 145 Read Queue Semaphore 147 defining object class properties 148 defining properties 128 handle 150 inserting entry 158, 160 insertring entry 156 KCLASSPROP structure 134, 148 name 142, 150 naming 126, 152 obtaining next entry 136, 138, 140 properties 144 Queue_Not_Empty event 130, 146 Queue_Not_Full event 130, 146 QUEUEPROP structure 128, 144 reading object class properties 134 registering 162 services summary table 12 Queue services brief description 12 KS_CloseQueue 124 KS_DefQueueName 126 KS_DefQueueProp 128 KS_DefQueueSema 130 KS_GetQueueClassProp 134 KS_GetQueueData 136 KS_GetQueueDataT 138 KS_GetQueueDataW 140

332

RTXC Kernel Services Reference, Volume 2

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 Queue_Not_Empty event 130, 146 Queue_Not_Full event 130, 146 QUEUEPROP structure 128, 144

mailbox 191 memory partition 256 mutex 296 queue 162 semaphore 120 task 74 releasing mutex 286 restarting task 23 resuming task 68 RTOS Software Development Kit 2 RTXC/ms component 8 rtxcapi.h file 2 RTXCDSP Kernel version number 308

R
RAM free 304 obtaining size of free 304 reading mailbox object class properties 176 memory partition object class properties 242 mutex object class properties 270 queue object class 134 semaphore count 90 semaphore name 92 semaphore object class properties 88, 96 semaphore properties 94 task handle 50, 64 task name 51 task object class properties 47 task priority level 53 task properties 54 task state 58 task time-slice quantum 60 receiving message 200, 202, 204 registering

S
scheduler disabling 40 enabling 41 SDK. See RTOS Software Development Kit SELFTASK 3 SELFTHREAD 3 semaphore allocating 100 closing 80 code examples Allocate Dynamic Semaphore 101 Assign Semaphore Name 85 Close Semaphore 81 Initialize Semaphore Object Class 97 Look Up Semaphore by Name 99 Read Semaphore Count 91 Read Semaphore Handle and Register It 121 Read Semaphore Name 93 Read Semaphore Object Class Properties 89 Read Semaphore Properties 95 Set Semaphore Count 83

Index

333

Signal List of Semaphores from Zone 3 105 Signal Semaphore from Zone 3 103 Specify Semaphore Waiting Order 87 Test List of Semaphores 111 Test List of SemaphoresWait for Signal 117 Test List of SemaphoresWait Number of Ticks for Signal 114 Test Semaphore 107 Test SemaphoreWait for Signal 119 Test SemaphoreWait Number of Ticks for Signal 109 defining count 82 defining properties 86 handle 98 KCLASSPROP structure 88, 96 naming 84, 100 reading count 90 reading name 92 reading object class properties 88, 96 reading properties 94 registering 120 SEMAPROP structure 86 services summary table 10 Signal Type attribute value 86 signaling 102, 104 testing 106, 110 testing and waiting 108, 112, 118 testing list and waiting 115 Waiting Order attribute value 86 Semaphore services brief description 10 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 KS_TestSemaMT 112 XX_SignalSema 102 XX_SignalSemaM 104 KS_TestSema 106 KS_TestSemaM 110 KS_TestSemaMW 115 KS_TestSemaT 108 KS_TestSemaW 118 KS_UseSema 120 SEMAPROP structure 86 sending message 206, 209, 213 service prefix 4 Signal Type attribute value, semaphore 86 signaling semaphores 102, 104 special service code examples Allocate System RAM from Zone 3 301 Define Fatal Error Function 303 Disable Task Scheduler 40 Enable Task Scheduler 41 Execute Non-RTXC Function as Kernel Service 315 Execute No-Operation Service 313 Initialize Kernel Properties 312 Read Amount of Available System RAM from Zone 3 304 Read Fatal Error Function 305 Read System Properties 307 Read Version Number 309 services summary table 20 Special services

334

RTXC Kernel Services Reference, Volume 2

brief description 20 XX_AllocSysRAM 300 XX_DefFatalErrorHandler 302 XX_GetFatalErrorHandler 305 XX_GetFreeSysRAMSize 304 KS_GetSysProp 306 KS_GetVersion 308 INIT_SysProp 310 KS_Nop 313 KS_UserService 314 starting task 42 stopping task 23 structure mailbox KCLASSPROP 176, 184 MBOXPROP 170, 180 memory partition KCLASSPROP 242, 250 mutex KCLASSPROP 270, 280 MUTXPROP 264, 276 PARTPROP 234, 246 queue KCLASSPROP 134, 148 QUEUEPROP 128, 144 semaphore KCLASSPROP 88, 96 SEMAPROP 86 SYSPROP 306, 310 task environment arguments 27, 44 task KCLASSPROP 47, 62 TASKPROP 34, 54 suspending task 70, 71 SYSPROP structure 306, 310 system error function 302, 305 system properties 306 SYSPROP structure 306, 310

T
table Kernel Service Return Value Types 6

Mailbox Services Summary 14 Memory Partition Services Summary 16 Message Services Summary 15 Mutex Services Summary 18 Queue Services Summary 12 Semaphore Services Summary 10 Special Services Summary 20 Task Services Summary 8 tables, list of ix task abortion event 36 allocating 66 closing 25 code examples Abort Task and Terminate 24 Allocate Dynamic Task 67 Close Task When Signaled 26 Define Task Name 31 Define Task Object Class Properties 35 Define Task Priorities 33 Define Task Properties 28 Define Task Termination Semaphore 37 Define Tick Slice 39 Execute Task 43 Initialize Task Object Class 63 Look Up Task by Name 65 Put Current Task to Sleep 70 Read and Change Task Priority 53 Read Current Task Task Number 50 Read Dynamic Task Name 52 Read Task Environment Arguments 46 Read Task Handle and Register It 75 Read Task Object Class Properties 49 Read Task State 59 Read Task Termination Semaphore 57

Index

335

Read Task Tick-Slice Quantum 60 Resume Suspended Task from Zone 3 69 Suspend Task 71 Terminate Task 73 Terminate Task and Release Its Stack 55 Yield to Another Task 77 defining environment arguments 27 defining priority 32 defining properties 34 environment arguments 44 environment arguments structure 27, 44 KCLASSPROP structure 47, 62 name 64 naming 30, 66 object class properties 62 reading handle 50, 64 reading name 51 reading object class properties 47 reading priority level 53 reading properties 54 reading semaphore handle 56 reading state 58 reading time-slice quantum 60 registering 74 resuming 68 services summary table 8 starting 42 stopping and restarting 23 suspending 70, 71 TASKPROP structure 34, 54 terminating 72 termination event 36 time-slice quantum 38 yielding to next 76 Task services brief description 8

KS_AbortTask 23 KS_CloseTask 25 KS_DefTaskEnvArg 27 KS_DefTaskName 30 KS_DefTaskPriority 32 KS_DefTaskProp 34 KS_DefTaskSema 36 KS_DefTimeSlice 38 KS_DisableTaskScheduler 40 KS_EnableTaskScheduler 41 KS_ExecuteTask 42 KS_GetTaskClassProp 47 KS_GetTaskEnvArg 44 KS_GetTaskID 50 KS_GetTaskName 51 KS_GetTaskPriority 53 KS_GetTaskProp 54 KS_GetTaskSema 56 KS_GetTaskState 58 KS_GetTimeSlice 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 TASKPROP structure 34, 54 terminating task 72 termination, task semaphore 56 testing list of semaphores 110, 112, 115 mutex availability 288, 290, 294 semaphore 106, 108, 118

336

RTXC Kernel Services Reference, Volume 2

testing message for acknowledgment 216, 218, 220 time-slice quantum 60 TS_AllocBlk 224 TS_DefFatalErrorHandler 302 TS_GetFatalErrorHandler 305 TS_GetFreeSysRAMSize 304 TS_ResumeTask 68 TS_SignalSema 102 TS_SignalSemaM 104

semaphore 86

X
XX_AllocBlk 224 XX_AllocSysRAM 300 XX_DefFatalErrorHandler 302 XX_GetFatalErrorHandler 305 XX_GetFreeSysRAMSize 304 XX_ResumeTask 68 XX_SignalSema 102 XX_SignalSemaM 104

U
user-defined kernel service 314

Y
yielding to next task 76

V
version number, RTXCDSP Kernel 308

Z
zones listing services with more than one 4 service prefix 4

W
Waiting Order attribute value

Index

337

Common questions