RTXC Kernel ServicesV2 Decrypted

June 21, 2002

RTXC Kernel Services Reference, Volume 2

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

QuadrosSystems Inc.

®

June 21, 2002

Disclaimer

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

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

Trademarks

Quadros is a registered trademark of Quadros Systems, Inc. RTXC, RTXC Quadros, and RTXC DSP are trademarks of Quadros Systems, Inc.

Other product and company names mentioned in this document may be the trademarks or registered trademarks of their respective owners.

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

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

RTXC Kernel Services Reference, Volume 2Part Number: RTXC-KSRV2-0602June 2002RTXC Kernel, Version 1.0

Contents iii

June 21, 2002

Contents

C H A P T E R 1 Introduction To RTXC/ms Kernel Services ..........................................1

Using This Manual........................................................................2Kernel Service Description Format........................................2Prototypes ................................................................................2General Form of Kernel Service Call .....................................4Arguments to Kernel Services................................................5Kernel Service Return Codes .................................................5Diagnostic Mode and Fatal Errors .........................................5Kernel Service Classes ............................................................7

RTXC/ms Component Services.....................................................8Task Management Services....................................................8Semaphore Services..............................................................10Queue Services......................................................................12Mailbox Services....................................................................14Message Services...................................................................15Memory Partition Management Services............................16Mutex Management Services ...............................................18Special Services .....................................................................20

C H A P T E R 2 Task Services.......................................................................................21

KS_AbortTask ..............................................................................23KS_CloseTask ..............................................................................25KS_DefTaskEnvArg.....................................................................27KS_DefTaskName .......................................................................30KS_DefTaskPriority.....................................................................32KS_DefTaskProp .........................................................................34KS_DefTaskSema ........................................................................36KS_DefTickSlice ..........................................................................38KS_DisableTaskScheduler ..........................................................40KS_EnableTaskScheduler ...........................................................41

iv RTXC Kernel Services Reference, Volume 2

June 21, 2002

KS_ExecuteTask .......................................................................... 42KS_GetTaskEnvArg .................................................................... 44KS_GetTaskClassProp ................................................................ 47KS_GetTaskID............................................................................. 50KS_GetTaskName....................................................................... 51KS_GetTaskPriority .................................................................... 53KS_GetTaskProp ......................................................................... 54KS_GetTaskSema........................................................................ 56KS_GetTaskState......................................................................... 58KS_GetTickSlice.......................................................................... 60INIT_TaskClassProp................................................................... 62KS_LookupTask .......................................................................... 64KS_OpenTask.............................................................................. 66XX_ResumeTask......................................................................... 68KS_SleepTask.............................................................................. 70KS_SuspendTask ........................................................................ 71KS_TerminateTask ..................................................................... 72KS_UseTask ................................................................................ 74KS_YieldTask .............................................................................. 76

C H A P T E R 3 Semaphore Services ........................................................................... 79

KS_CloseSema ............................................................................ 80KS_DefSemaCount ..................................................................... 82KS_DefSemaName ..................................................................... 84KS_DefSemaProp ....................................................................... 86KS_GetSemaClassProp............................................................... 88KS_GetSemaCount ..................................................................... 90KS_GetSemaName ..................................................................... 92KS_GetSemaProp ....................................................................... 94INIT_SemaClassProp ................................................................. 96KS_LookupSema......................................................................... 98KS_OpenSema .......................................................................... 100XX_SignalSema......................................................................... 102XX_SignalSemaM..................................................................... 104KS_TestSema ............................................................................ 106KS_TestSemaT .......................................................................... 108KS_TestSemaM......................................................................... 110KS_TestSemaMT ...................................................................... 112KS_TestSemaMW ..................................................................... 115KS_TestSemaW......................................................................... 118

Contents v

June 21, 2002

KS_UseSema .............................................................................120

C H A P T E R 4 Queue Services .................................................................................123

KS_CloseQueue .........................................................................124KS_DefQueueName ..................................................................126KS_DefQueueProp ....................................................................128KS_DefQueueSema...................................................................130KS_GetQueueClassProp ...........................................................134KS_GetQueueData ....................................................................136KS_GetQueueDataT ..................................................................138KS_GetQueueDataW.................................................................140KS_GetQueueName ..................................................................142KS_GetQueueProp ....................................................................144KS_GetQueueSema...................................................................146INIT_QueueClassProp..............................................................148KS_LookupQueue......................................................................150KS_OpenQueue .........................................................................152KS_PutQueueData.....................................................................156KS_PutQueueDataT ..................................................................158KS_PutQueueDataW.................................................................160KS_UseQueue............................................................................162

C H A P T E R 5 Mailbox Services ...............................................................................165

KS_CloseMbox...........................................................................166KS_DefMboxName....................................................................168KS_DefMboxProp......................................................................170KS_DefMboxSema.....................................................................172KS_GetMboxClassProp .............................................................176KS_GetMboxName....................................................................178KS_GetMboxProp ......................................................................180KS_GetMboxSema.....................................................................182INIT_MboxClassProp................................................................184KS_LookupMbox .......................................................................186KS_OpenMbox...........................................................................188KS_UseMbox .............................................................................191

C H A P T E R 6 Message Services..............................................................................193

KS_AckMsg................................................................................194KS_ForwardMsg ........................................................................196KS_ReceiveMsg .........................................................................200

vi RTXC Kernel Services Reference, Volume 2

June 21, 2002

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

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

XX_AllocBlk .............................................................................. 224KS_AllocBlkT ............................................................................ 226KS_AllocBlkW........................................................................... 228KS_ClosePart............................................................................. 230KS_DefPartName...................................................................... 232KS_DefPartProp........................................................................ 234KS_DefPartSema....................................................................... 236KS_FreeBlk................................................................................ 238KS_GetFreeBlkCount ............................................................... 240KS_GetPartClassProp ............................................................... 242KS_GetPartName...................................................................... 244KS_GetPartProp ........................................................................ 246KS_GetPartSema....................................................................... 248INIT_PartClassProp.................................................................. 250KS_LookupPart ......................................................................... 252KS_OpenPart............................................................................. 254KS_UsePart ............................................................................... 256

C H A P T E R 8 Mutex Services ................................................................................. 259

KS_CloseMutx........................................................................... 260KS_DefMutxName.................................................................... 262KS_DefMutxProp ...................................................................... 264KS_DefMutxSema..................................................................... 267KS_GetMutxClassProp ............................................................. 270KS_GetMutxName .................................................................... 272KS_GetMutxOwner................................................................... 274KS_GetMutxProp ...................................................................... 276KS_GetMutxSema..................................................................... 278INIT_MutxClassProp................................................................ 280KS_LookupMutx........................................................................ 282

Contents vii

June 21, 2002

KS_OpenMutx ...........................................................................284KS_ReleaseMutx ........................................................................286KS_TestMutx..............................................................................288KS_TestMutxT ...........................................................................290KS_TestMutxW..........................................................................294KS_UseMutx ..............................................................................296

C H A P T E R 9 Special Services.................................................................................299

XX_AllocSysRAM......................................................................300XX_DefFatalErrorHandler ........................................................302XX_GetFreeSysRAMSize..........................................................304XX_GetFatalErrorHandler ........................................................305KS_GetSysProp..........................................................................306KS_GetVersion ..........................................................................308INIT_SysProp ............................................................................310KS_Nop ......................................................................................313KS_UserService .........................................................................314

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

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

viii RTXC Kernel Services Reference, Volume 2

June 21, 2002

List of Tables ix

June 21, 2002

List of Tables

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

x RTXC Kernel Services Reference, Volume 2

June 21, 2002

List of Examples xi

June 21, 2002

List of Examples

Example 2-1 Abort Task and Terminate.................................................................24Example 2-2 Close Task When Signaled................................................................26Example 2-3 Define Task Properties ......................................................................28Example 2-4 Define Task Name .............................................................................31Example 2-5 Define Task Priorities ........................................................................33Example 2-6 Task Properties Structure ..................................................................34Example 2-7 Define Task Object Class Properties ................................................35Example 2-8 Define Task Termination Semaphore ..............................................37Example 2-9 Define Tick Slice ................................................................................39Example 2-10 Disable Task Scheduler .....................................................................40Example 2-11 Enable Task Scheduler.......................................................................41Example 2-12 Execute Task .......................................................................................43Example 2-13 Read Task Environment Arguments ................................................46Example 2-14 Read Task Object Class Properties ...................................................49Example 2-15 Read Current Task Number ..............................................................50Example 2-16 Read Dynamic Task Name ................................................................52Example 2-17 Read and Change Task Priority.........................................................53Example 2-18 Terminate Task and Release Its Stack ..............................................55Example 2-19 Read Task Termination Semaphore .................................................57Example 2-20 Read Task State ..................................................................................59Example 2-21 Read Task Tick-Slice Quantum.........................................................60Example 2-22 Object Class Properties Structure .....................................................62Example 2-23 Initialize Task Object Class ...............................................................63Example 2-24 Look Up Task by Name......................................................................65Example 2-25 Allocate Dynamic Task ......................................................................67Example 2-26 Resume Suspended Task from Zone 3 ............................................69Example 2-27 Put Current Task to Sleep .................................................................70Example 2-28 Suspend Task .....................................................................................71Example 2-29 Terminate Task ..................................................................................73Example 2-30 Read Task Handle and Register It ....................................................75

xii RTXC Kernel Services Reference, Volume 2

June 21, 2002

Example 2-31 Yield to Another Task........................................................................ 77Example 3-1 Close Semaphore............................................................................... 81Example 3-2 Set Semaphore Count ....................................................................... 83Example 3-3 Assign Semaphore Name ................................................................. 85Example 3-4 Semaphore Properties Structure ...................................................... 86Example 3-5 Specify Semaphore Waiting Order................................................... 87Example 3-6 Class Properties Structure ................................................................ 88Example 3-7 Read Semaphore Object Class Properties........................................ 89Example 3-8 Read Semaphore Count .................................................................... 91Example 3-9 Read Semaphore Name..................................................................... 93Example 3-10 Read Semaphore Properties ............................................................. 95Example 3-11 Initialize Semaphore Object Class ................................................... 97Example 3-12 Look Up Semaphore by Name.......................................................... 99Example 3-13 Allocate Dynamic Semaphore ........................................................ 101Example 3-14 Signal Semaphore from Zone 3 ..................................................... 103Example 3-15 Signal List of Semaphores from Zone 3 ........................................ 105Example 3-16 Test Semaphore ............................................................................... 107Example 3-17 Test Semaphore—Wait Number of Ticks for Signal .................... 109Example 3-18 Test List of Semaphores.................................................................. 111Example 3-19 Test List of Semaphores—Wait Number of Ticks for Signal ....... 114Example 3-20 Test List of Semaphores—Wait for Signal..................................... 117Example 3-21 Test Semaphore—Wait for Signal.................................................. 119Example 3-22 Read Semaphore Handle and Register It ...................................... 121Example 4-1 Close Queue..................................................................................... 125Example 4-2 Assign Queue Name ....................................................................... 127Example 4-3 Queue Properties Structure ............................................................ 128Example 4-4 Define Queue Object Class Properties........................................... 129Example 4-5 Associate Queue Event with Semaphore ....................................... 132Example 4-6 Read Queue Object Class Properties.............................................. 135Example 4-7 Read Queue Entry............................................................................ 137Example 4-8 Read Queue Entry—Wait Number of Ticks If Necessary............. 139Example 4-9 Read Queue Entry—Wait If Necessary .......................................... 141Example 4-10 Read Dynamic Queue Name .......................................................... 143Example 4-11 Read Queue Properties ................................................................... 145Example 4-12 Read Queue Semaphore ................................................................. 147Example 4-13 Initialize Queue Object Class ......................................................... 149Example 4-14 Look Up Queue by Name................................................................ 151Example 4-15 Allocate and Initialize Queue ......................................................... 154Example 4-16 Put Data Into Queue ....................................................................... 157Example 4-17 Put Data Into Queue—Wait Number of Ticks If Queue is Full .. 159

List of Examples xiii

June 21, 2002

Example 4-18 Put Data Into Queue—Wait Until Queue Has Room...................161Example 4-19 Read Queue Handle and Register It ...............................................163Example 5-1 Close Mailbox ...................................................................................167Example 5-2 Assign Mailbox Name......................................................................169Example 5-3 Mailbox Properties Structure ..........................................................170Example 5-4 Define Mailbox Properties...............................................................171Example 5-5 Define Mailbox Semaphore.............................................................174Example 5-6 Read Mailbox Object Class Properties............................................177Example 5-7 Read Mailbox Name.........................................................................179Example 5-8 Read Mailbox Properties..................................................................181Example 5-9 Read Mailbox Semaphore................................................................183Example 5-10 Initialize Mailbox Object Class........................................................185Example 5-11 Look Up Mailbox by Name..............................................................187Example 5-12 Allocate Mailbox ...............................................................................189Example 5-13 Read Mailbox Handle and Register It.............................................192Example 6-1 Acknowledge Message.....................................................................195Example 6-2 Forward Message .............................................................................198Example 6-3 Receive Next Message from a Mailbox ...........................................201Example 6-4 Receive Message—Wait Number of Ticks If Necessary................203Example 6-5 Receive Message—Wait If Necessary .............................................205Example 6-6 Send Message—Wait for Acknowledgment...................................208Example 6-7 Send Message—Wait Number of Ticks for Acknowledgment .....212Example 6-8 Send Message—Wait for Acknowledgment...................................214Example 6-9 Test for Message Acknowledgment................................................217Example 6-10 Test for Message Acknowledgment—Wait Number of

Ticks for Acknowledgment .......................................................219Example 6-11 Test for Acknowledgment and Wait if Necessary ..........................221Example 7-1 Allocate Block of Memory................................................................225Example 7-2 Allocate Block of Memory—Wait Number of Ticks If Necessary.227Example 7-3 Allocate Block of Memory—Wait If Necessary ..............................229Example 7-4 Close Memory Partition...................................................................231Example 7-5 Assign Memory Partition Name .....................................................233Example 7-6 Define Memory Partition Properties ..............................................235Example 7-7 Associate Semaphore With Memory Partition...............................237Example 7-8 Allocate and Free Memory Block ....................................................239Example 7-9 Read Memory Partition Free Block Count .....................................241Example 7-10 Read Memory Partition Object Class Properties ...........................243Example 7-11 Read Memory Partition Name ........................................................245Example 7-12 Memory Partition Properties Structure..........................................246Example 7-13 Read Memory Partition Properties .................................................247

xiv RTXC Kernel Services Reference, Volume 2

June 21, 2002

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

Chapter 1: Introduction To RTXC/ms Kernel Services 1

June 21, 2002

C H A P T E R 1 Introduction To RTXC/ms Kernel

Services

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

Using This Manual...............................................................................2Kernel Service Description Format ...............................................2Prototypes ......................................................................................2General Form of Kernel Service Call .............................................4Arguments to Kernel Services ....................................................... 5Kernel Service Return Codes ......................................................... 5Diagnostic Mode and Fatal Errors ................................................ 5Kernel Service Classes ...................................................................7

RTXC/ms Component Services ...........................................................8Task Management Services...........................................................8Semaphore Services .................................................................... 10Queue Services ............................................................................ 12Mailbox Services.......................................................................... 14Message Services .........................................................................15Memory Partition Management Services ................................... 16Mutex Management Services...................................................... 18Special Services ...........................................................................20

2 RTXC Kernel Services Reference, Volume 2

Using This Manual

June 21, 2002

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


Using This Manual

June 21, 2002

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

Similarly, there may be syntactical differences between C compilers from different manufacturers. For example, one C compiler may use the key words near and far to permit different memory models due to the processor’s architecture, whereas a compiler targeted to a different processor may not require the near and far keywords.

Table 1-1. Kernel Service Description Format

Name Brief Functional Description

Zones The zonal prefixes supported by the service (IS_, TS_, KS_), if more than one.a

Synopsis The formal ANSI C declaration including argument prototyping.

Inputs A brief description of each input argument.

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

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

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

SELFTASK is used in many of the examples to denote the Current Task. It is defined in rtxcapi.h as (TASK)0.

SELFTHREAD is used in many of the examples to denote the Current Thread. It is defined in rtxcapi.h as (THREAD)0.

The putline function moves the content of a character buffer to an assumed console device.


Using This Manual

June 21, 2002

General Form of Kernel Service Call

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

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

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

Some services are callable from all three zones, others from zones 2 and 3, and still others from Zone 2 or Zone 3 only. The detailed descriptions of the services in this book include the zones from which the service can be called if it can be called from more than one.

Following the service prefix is the name of the RTXC Kernel service. The service prefix should prevent the name from being misidentified by a linker with some similarly-named function in the runtime library of the compiler. In general, name is composed as follows:

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

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

Special Notes Additional notes and technical comments, if any.

a. Services that support more than one zone are listed with an XX_prefix. The XX_ prefix is not a valid prefix, only a placeholder.

b. The code examples in this manual often refer to functions orentities outside the given code fragment used in the example. Thefunctions or entities so referenced may be real or assumed withinthe actual context of the code example but are not shown. Thepurpose of such references is to add coherence to the examplerather than to imply a particular methodology or usage.

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

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

KS_ Identifies a service callable from Zone 3.

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

Name Brief Functional Description


Using This Manual

June 21, 2002

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

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

Arguments to Kernel Services

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

Kernel Service Return Codes

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

Diagnostic Mode and Fatal Errors

The RTXC Kernel provides a diagnostic mode of operation to speed 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

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

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

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


Using This Manual

June 21, 2002

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

Table 1-2. Kernel Service Return Value Types

Symbol Description

TASK Task handle

THREAD Thread handle

PRIORITY Priority of a task or a message

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

SEMA Semaphore handle

SEMACOUNT Number of signals that a semaphore has received

MBOX Mailbox handle

MSGENV Message envelope

QUEUE Queue handle

PART Memory partition handle

BLKSIZE Size of a block of memory in a partition

MUTX Mutex handle

EVNTSRC Event Source handle

COUNTER Counter handle

ALARM Alarm handle

TICKS Units of time maintained by the system time base

EXCPTN Exception handle

KSRC Kernel Service Return Code


Using This Manual

June 21, 2002

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.


RTXC/ms Component Services

June 21, 2002

RTXC/ms Component ServicesThe RTXC/ms component of the RTXC Kernel provides a multiple independent stack model for a fully pre-emptive, multitasking scheduler with a rich set of kernel services well suited to deterministic, hard real-time system requirements. The following sections describe the object classes supported in the RTXC/ms component and their related kernel services.

Task Management Services

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

Table 1-3. Task Services Summary

Service Description Zones Ref.

KS_AbortTask Abort the execution of a task. 23

KS_CloseTask End the use of a dynamic task. 25

KS_DefTaskEnvArg Define the environment arguments for a task.

27

KS_DefTaskName Define the name of a previously opened dynamic task.

30

KS_DefTaskPriority Define a new priority for a task. 32

KS_DefTaskProp Define the properties of a task. 34

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

36

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

KS_DisableTaskScheduler Disable the task scheduler to prevent task context switching.

40

KS_EnableTaskScheduler Enable the scheduler to allow context switching between tasks.

41



June 21, 2002

KS_ExecuteTask Execute a task. 42

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

44

KS_GetTaskClassProp Get the Task object class properties. 47

KS_GetTaskID Get the handle of the Current Task. 50

KS_GetTaskName Get the name of a task. 51

KS_GetTaskPriority Get the priority of a task. 53

KS_GetTaskProp Get the properties of a task. 54

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

56

KS_GetTaskState Get the state of a task. 58

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

INIT_TaskClassProp Initialize the Task object class properties. 62

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

KS_OpenTask Allocate and name a dynamic task. 66

XX_ResumeTask Resume a task that was previously suspended.

68

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

70

KS_SuspendTask Suspend a task. 71

KS_TerminateTask Terminate a task. 72

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

74

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

76

Table 1-3. Task Services Summary (continued)




June 21, 2002

Semaphore Services

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

Table 1-4. Semaphore Services Summary


KS_CloseSema End the use of a dynamic semaphore. 80

KS_DefSemaCount Define a semaphore count. 82

KS_DefSemaName Define the name of a previously opened dynamic semaphore.

84

KS_DefSemaProp Define the properties of a semaphore. 86

KS_GetSemaClassProp Get the Semaphore object class properties. 88

KS_GetSemaCount Get the current semaphore count. 90

KS_GetSemaName Get the name of a semaphore. 92

KS_GetSemaProp Get the properties of a semaphore. 94

INIT_SemaClassProp Initialize the Semaphore object class properties. 96

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

KS_OpenSema Allocate and name a dynamic semaphore. 100

XX_SignalSema Signal a semaphore. 102

XX_SignalSemaM Signal multiple semaphores. 104

KS_TestSema Test a semaphore. 106

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

108



June 21, 2002

KS_TestSemaM Test a list of semaphores. 110

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

112

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

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

118

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

120

Table 1-4. Semaphore Services Summary (continued)




June 21, 2002

Queue Services

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

Table 1-5. Queue Services Summary


KS_CloseQueue End the use of a dynamic queue. 124

KS_DefQueueName Define the name of a previously opened dynamic queue.

126

KS_DefQueueProp Define the properties of a queue. 128

KS_DefQueueSema Associate a semaphore with a queue condition event.

130

KS_GetQueueClassProp Get the Queue object class properties. 134

KS_GetQueueData Get the next entry from a queue. 136

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

138

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

140

KS_GetQueueName Get the name of a queue. 142

KS_GetQueueProp Get the properties of a queue. 144

KS_GetQueueSema Get the semaphore handle associated with a queue event.

146

INIT_QueueClassProp Initialize the Queue object class properties. 148



June 21, 2002

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

KS_OpenQueue Allocate and name a dynamic queue. 152

KS_PutQueueData Put an entry into a queue. 156

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

158

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

160

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

162

Table 1-5. Queue Services Summary (continued)




June 21, 2002

Mailbox Services

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

Table 1-6. Mailbox Services Summary


KS_CloseMbox End the use of a dynamic mailbox. 166

KS_DefMboxName Define the name of a previously opened dynamic mailbox.

168

KS_DefMboxProp Define the properties of a mailbox. 170

KS_DefMboxSema Associate a semaphore with the Mailbox_Not_Empty event.

172

KS_GetMboxClassProp Get the Mailbox object class properties. 176

KS_GetMboxName Get the name of a mailbox. 178

KS_GetMboxProp Get the properties of a mailbox. 180

KS_GetMboxSema Get the semaphore handle associated with a Mailbox_Not_Empty event.

182

INIT_MboxClassProp Initialize the Mailbox object class properties. 184

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

KS_OpenMbox Allocate and name a dynamic mailbox. 188

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

191



June 21, 2002

Message Services

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

Table 1-7. Message Services Summary


KS_AckMsg Acknowledge a message. 194

KS_ReceiveMsg Receive a message from a mailbox. 200

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

202

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

204

KS_SendMsg Send a message to a mailbox asynchronously. 206

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

209

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

213

KS_TestAck Test for message acknowledgment. 216

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

218

KS_TestAckW Test for message acknowledgment and wait for the acknowledgment.

220



June 21, 2002

Memory Partition Management Services

The Memory Management directives, listed in Table 1-8, provide a system-wide method of dynamically allocating and de-allocating memory blocks to tasks on an as-needed basis. Using these directives, multiple tasks can share a common pool of memory. For detailed descriptions, see Chapter 7, “Memory Partition Services.”

Table 1-8. Memory Partition Services Summary


XX_AllocBlk Allocate a block of memory. 224

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

226

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

228

KS_ClosePart End the use of a dynamic partition. 230

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

232

KS_DefPartProp Define the properties of a partition. 234

KS_DefPartSema Associate a semaphore with the Partition_Not_Empty event.

236

KS_FreeBlk Free a block of memory. 238

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

KS_GetPartClassProp Get the Memory Partition object class properties 242

KS_GetPartName Get the name of a partition. 244

KS_GetPartProp Get the properties of a partition. 246



June 21, 2002

KS_GetPartSema Get the semaphore associated with the Partition_Not_Empty event.

248

INIT_PartClassProp Initialize the Partition object class properties. 250

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

KS_OpenPart Allocate and name a dynamic partition. 254

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

256

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




June 21, 2002

Mutex Management Services

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

Table 1-9. Mutex Services Summary


KS_CloseMutx End the use of a dynamic mutex. 260

KS_DefMutxName Define the name of a previously opened mutex. 262

KS_DefMutxProp Define the properties of a mutex. 264

KS_DefMutxSema Associate a semaphore with the Mutex_Not_Busy event.

267

KS_GetMutxClassProp Get the Mutex object class properties. 270

KS_GetMutxName Get the name of a mutex. 272

KS_GetMutxOwner Get the owner of a mutex. 274

KS_GetMutxProp Get the properties of a mutex. 276

KS_GetMutxSema Get the semaphore handle associated with the Mutex_Not_Busy event.

278

INIT_MutxClassProp Initialize the Mutex object class properties. 280

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

KS_OpenMutx Allocate and name a dynamic mutex. 284

KS_ReleaseMutx Release ownership of a mutex. 286

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

288



June 21, 2002

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

290

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

294

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

296

Table 1-9. Mutex Services Summary (continued)




June 21, 2002

Special Services

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

Table 1-10. Special Services Summary


XX_AllocSysRAM Allocate a block of system RAM. 300

XX_DefFatalErrorHandler Establish the system error function. 302

XX_GetFreeSysRAMSize Get the size of free system RAM. 304

XX_GetFatalErrorHandler Get the system error function. 305

KS_GetSysProp Get the system properties. 306

KS_GetVersion Get the version number of the Kernel. 308

INIT_SysProp Initialize the RTXC system properties. 310

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

313

KS_UserService Perform a user-defined kernel service. 314

Chapter 2: Task Services 21

June 21, 2002

C H A P T E R 2 Task Services

In This ChapterWe 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


June 21, 2002

KS_LookupTask ................................................................................. 64

KS_OpenTask .................................................................................... 66

XX_ResumeTask ................................................................................ 68

KS_SleepTask..................................................................................... 70

KS_SuspendTask ................................................................................ 71

KS_TerminateTask..............................................................................72

KS_UseTask ....................................................................................... 74

KS_YieldTask...................................................................................... 76


KS_AbortTask

June 21, 2002

KS_AbortTask Abort the execution of a task.

Synopsis void KS_AbortTask (TASK task)

Input

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

This service is similar to the KS_TerminateTask service except that it sets the status of the task to ABORTED_BLOCK instead of INACTIVE. Such an identification may be valuable when tracking down a task gone awry during system diagnostic operations.

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

Warning: Other than the items mentioned above, tasks that are currently using kernel objects or have objects allocated to them are not cleaned up by the abort process. The programmer must ensure that the task releases all such system elements to the system before aborting the task. For example, a dynamic task should not abort itself if the task’s stack has been dynamically allocated from a memory partition because it would be difficult to recover the memory used for the stack. Repeated occurrences of such an event would cause a memory leak that could lead to eventual system failure.

Output This service does not return a value.

task The number of the task to abort.


KS_AbortTask

June 21, 2002

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

FE_ILLEGAL_TASK if the specified task ID is not valid.

FE_UNINITIALIZED_TASK if the specified task has not yet been initialized.

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

Example 2-1. Abort Task and Terminate

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

KS_AbortTask (TASKBX); /* abort task TASKBX */

KS_TerminateTask (SELFTASK); /* now terminate self */

See Also KS_TerminateTask, page 72


KS_CloseTask

June 21, 2002

KS_CloseTask End the use of a dynamic task.

Synopsis KSRC KS_CloseTask (TASK task)

Input

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

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

Output This service returns a KSRC value as follows:

RC_GOOD if the service was successful.

RC_STATIC_OBJECT if the specified task is not dynamic.

RC_OBJECT_NOT_INUSE if the specified task does not correspond to an active dynamic task.

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

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

Error This service may generate the following fatal error code:


task The number of the task to close.


KS_CloseTask

June 21, 2002

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

Example 2-2. Close Task When Signaled

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

TASK dyntask; /* not SELFTASK (TASK)0 */SEMA dynsema;

KS_TestSemaW (dynsema); /* wait for signal */

/* then close the task */if (KS_CloseTask (dyntask) != RC_GOOD){ ...something is wrong. Deal with it}...continue /* task closed successfully */

See Also KS_OpenTask,page 66KS_UseTask, page 74


KS_DefTaskEnvArg

June 21, 2002

KS_DefTaskEnvArg Define the environment arguments for a task.

Synopsis void KS_DefTaskEnvArg (TASK task, const void *parg)

Inputs

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

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

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





Example In Example 2-3 on page 28, the Current Task needs to spawn a dynamic task to operate on the port and channel specified by the port and chnl variables that were specified elsewhere. The dynamic task must be allocated dynamically and its identifier is stored in the dyntask variable. The dynamic task’s entry address is taskA and it requires a 256-byte stack that the Current Task allocates from the BLK256 memory partition. The dynamic task runs at priority 14.

task The number of the task being defined.

parg A pointer to the environment arguments structure for the task.


KS_DefTaskEnvArg

June 21, 2002

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

Example 2-3. Define Task Properties

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

#define STKSIZE 256#define DYNPRI 14

extern void taskA (void);

struct{ int port; int channel;} envargA; /* environment argument structure */

TASK dyntask;TASKPROP tprop;int port, chnl;

if (KS_OpenTask ((char *)0, &dyntask) != RC_GOOD){ ... Deal with problem with dynamic task allocation}else{ /* allocate space for task’s stack */ tprop.stackbase = (char *)KS_AllocBlkW (BLK256, (PEVENT *)0);

/* define task properties */ tprop.taskentry = taskA; tprop.stacksize = STKSIZE; tprop.priority = DYNPRI; KS_DefTaskProp (dyntask, &tprop);

/* define environment arguments */ envargA.port = port; envargA.channel = chnl; KS_DefTaskEnvArg (dyntask, &envargA);

/* start task */ KS_ExecuteTask (dyntask);}


KS_DefTaskEnvArg

June 21, 2002

See Also KS_DefTaskProp, page 34KS_GetTaskEnvArg, page 44


KS_DefTaskName

June 21, 2002

KS_DefTaskName Define the name of a previously opened dynamic task.

Synopsis KSRC KS_DefTaskName (TASK task, const char *pname)

Inputs

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


This service does not check for duplicate task names.


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.




pname A pointer to a null-terminated name string.


KS_DefTaskName

June 21, 2002

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


TASK dyntask;

if (KS_DefTaskName (dyntask, "NewTask") != RC_GOOD){ ... Probably is a static task. Deal with it here.}

... else the naming operation was successful. Continue

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


KS_DefTaskPriority

June 21, 2002

KS_DefTaskPriority Define a new priority for a task.

Synopsis void KS_DefTaskPriority (TASK task, PRIORITY priority)

Inputs

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

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

The Current Task may specify itself with a task value of zero (0).

If task is not the Current Task, a preemption occurs if the new priority of task is higher than that of the requesting task and task is in the Ready List.

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






priority The priority value for the task.


KS_DefTaskPriority

June 21, 2002

FE_ILLEGAL_PRIORITY if the specified priority value is out of range.

Example Example 2-5 changes the priority of the SERIALIN task from its current level to priority 3, and then changes the calling task to priority 6.

Example 2-5. Define Task Priorities

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

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

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

See Also KS_ExecuteTask, page 42KS_TerminateTask, page 72


KS_DefTaskProp

June 21, 2002

KS_DefTaskProp Define the properties of a task.

Synopsis void KS_DefTaskProp (TASK task, const TASKPROP *ptaskprop)

Inputs

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

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

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

Example 2-6. Task Properties Structure

typedef struct{ void (*taskentry)(void); /* initial entry point address */ char *stackbase; /* initial stack base */ ksize_t stacksize; /* initial stack size */ PRIORITY priority; /* initial priority */} TASKPROP;


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


FE_ILLEGAL_PRIORITY if the specified priority is out of range.


ptaskprop A pointer to a Task properties structure.


KS_DefTaskProp

June 21, 2002

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


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 54INIT_TaskClassProp, page 62KS_OpenTask, page 66


KS_DefTaskSema

June 21, 2002

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

Synopsis void KS_DefTaskSema (TASK task, SEMA sema)

Inputs

Description The KS_DefTaskSema kernel service associates the semaphore specified in sema with the termination and abortion events of the specified task, when sema is to be used in a subsequent test using the KS_TestSema kernel service or one of its variants. The service signals the semaphore when task is terminated or aborted.

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





FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.

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

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

sema The semaphore to associate with the task.


KS_DefTaskSema

June 21, 2002

Example 2-8. Define Task Termination Semaphore

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

KS_DefTaskSema (TASKA, GOSEMA);

KS_TestSemaW (GOSEMA);

... TASKA ended, begin processing now

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


KS_DefTickSlice

June 21, 2002

KS_DefTickSlice Define the tick-slice quantum for a task.

Synopsis void KS_DefTickSlice (TASK task, TSLICE ticks)

Inputs

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

The service requires a task number and a tick-slice quantum, ticks, as arguments. The tick quantum period is specified as a value of TSLICE type giving the number of clock ticks approximating the desired duration of the tick-slice quantum. A task number of zero (0) specifies the Current Task.

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

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

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

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





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


KS_DefTickSlice

June 21, 2002


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

Example 2-9. Define Tick Slice

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

/* define tick slice quantum as 100 ms */KS_DefTickSlice (SELFTASK, (TSLICE)100/CLKTICK);

... Task now in tick-sliced operation

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

See Also KS_GetTickSlice, page 60


KS_DisableTaskScheduler

June 21, 2002

KS_DisableTaskScheduler Disable the task scheduler to prevent task context switching.

Synopsis void KS_DisableTaskScheduler (void)

Inputs This service has no inputs.

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


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

Example 2-10. Disable Task Scheduler

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

KS_DisableTaskScheduler (); /* prevent preemption */

...perform some function

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

See Also KS_EnableTaskScheduler, page 41


KS_EnableTaskScheduler

June 21, 2002

KS_EnableTaskScheduler Enable the scheduler to allow context switching between tasks.

Synopsis void KS_EnableTaskScheduler (void)


Description The KS_EnableTaskScheduler kernel service enables the RTXC/ms Scheduler, which in turn permits task context switching to occur. If the application makes nested calls to KS_DisableTaskScheduler, then it must make an equal number of calls to KS_EnableTaskScheduler before context switching (preemption) starts again.

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


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

Example 2-11. Enable Task Scheduler


KS_DisableTaskScheduler (); /* prevent preemption */

...perform some function

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

See Also KS_DisableTaskScheduler, page 40


KS_ExecuteTask

June 21, 2002

KS_ExecuteTask Execute a task.

Synopsis KSRC KS_ExecuteTask (TASK task)

Input

Description The KS_ExecuteTask kernel service starts a specified task from its beginning address. The task must be in the INACTIVE state. If so, it is inserted into the Ready List with its program counter (PC) and stack pointer (SP) initialized to their starting values. The task’s starting address, initial priority, and stack pointer are specified during system generation or dynamically with the KS_DefTaskProp kernel service.

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

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


RC_GOOD if the task starts successfully.

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




Example In Example 2-12 on page 43, the Current Task starts the SHUTDOWN static task from its starting address.

task The number of the task to execute.


KS_ExecuteTask

June 21, 2002

Example 2-12. Execute Task

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

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

See Also KS_TerminateTask, page 72


KS_GetTaskEnvArg

June 21, 2002

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

Synopsis void * KS_GetTaskEnvArg (TASK task)

Input

Description The KS_GetTaskEnvArg kernel service obtains a pointer to the structure containing the environment arguments for the specified task. To request the environment arguments for the Current Task, set task to zero (0).

Any task may use this kernel service to get environment arguments that have been previously defined to the RTXC Kernel by the KS_DefTaskEnvArg service. Dynamic tasks use this service because they typically have an associated environment argument structure to specify the parameters they need for operation.

Note: To use this service, you must enable the Environment Arguments attributes of the Task class during system generation.

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




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

task The number of the task being queried.


KS_GetTaskEnvArg

June 21, 2002

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

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

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


KS_GetTaskEnvArg

June 21, 2002

Example 2-13. Read Task Environment Arguments


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


KS_GetTaskClassProp

June 21, 2002

KS_GetTaskClassProp Get the Task object class properties.

Synopsis const KCLASSPROP * KS_GetTaskClassProp (int *pint)

Input

Description The KS_GetTaskClassProp kernel service obtains a pointer to the KCLASSPROP structure that was used during system initialization by the INIT_TaskClassProp service to initialize the Task object class properties.

If the pint pointer contains a non-zero address, the current number of unused dynamic tasks is stored in the indicated address. If pint contains a null pointer ((int *)0), the service ignores the parameter. If the Task object class properties do not include the Dynamics attribute, the service stores a value of zero (0) at the address contained in pint.

The KCLASSPROP structure has the following organization:

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

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

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


KS_GetTaskClassProp

June 21, 2002

Output If successful, this service returns a pointer to a KCLASSPROP structure.

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

If pint is not null ((int *)0), the service returns the number of available dynamic tasks in the variable pointed to by pint.

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

Table 2-1. Task Class Attributes and Masks

Attribute Mask

Static Names ATTR_STATIC_NAMES

Dynamics ATTR_DYNAMICS

Tick Slice ATTR_TICKSLICE

Environment Arguments ATTR_TASK_ENV

Task Semaphores ATTR_TASK_SEMAPHORES


KS_GetTaskClassProp

June 21, 2002

Example 2-14. Read Task Object Class Properties


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


KS_GetTaskID

June 21, 2002

KS_GetTaskID Get the handle of the Current Task.

Synopsis TASK KS_GetTaskID (void)


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

Output This service returns the handle of the Current Task.

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

Example 2-15. Read Current Task Number

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

static char buf[128];TASK mytaskid;

mytaskid = KS_GetTaskID ();

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


KS_GetTaskName

June 21, 2002

KS_GetTaskName Get the name of a task.

Synopsis char * KS_GetTaskName (TASK task)

Input

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

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

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

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



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



KS_GetTaskName

June 21, 2002

Example 2-16. Read Dynamic Task Name


static char buf[128];TASK dyntask;char *pname;

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

putline (buf);

See Also KS_DefTaskName, page 30KS_OpenTask, page 66


KS_GetTaskPriority

June 21, 2002

KS_GetTaskPriority Get the priority of a task.

Synopsis PRIORITY KS_GetTaskPriority (TASK task)

Input

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

Output This service returns the priority of the specified task.




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


PRIORITY mypri;

mypri = KS_GetTaskPriority (SELFTASK);

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

See Also KS_DefTaskPriority, page 32



KS_GetTaskProp

June 21, 2002

KS_GetTaskProp Get the properties of a task.

Synopsis void KS_GetTaskProp (TASK task, TASKPROP *ptaskprop)

Inputs

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); /* initial entry point addr. */ char *stackbase; /* initial stack base */ ksize_t stacksize; /* initial stack size */ PRIORITY priority; /* initial priority */} TASKPROP;

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




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 task’s stack space to the BLK256 memory partition from where it was initially allocated.


ptaskprop A pointer to a task property structure.


KS_GetTaskProp

June 21, 2002

Example 2-18. Terminate Task and Release Its Stack

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

TASK dyntask;static TASKPROP tprop;

/* first, get the task number of DynMuxTask2" */if (KS_LookupTask ("DynMuxTask2", &dyntask) != RC_GOOD){ ... Task "DynMuxTask2" does not exist.}else{ /* task was found, now get its properties */ KS_GetTaskProp (dyntask, &tprop);

/* terminate task */ KS_TerminateTask (dyntask);

/* Now free the block used for its stack */ KS_FreeBlk (BLK256, tprop.stackbase);}

See Also KS_DefTaskProp, page 34


KS_GetTaskSema

June 21, 2002

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

Synopsis SEMA KS_GetTaskSema (TASK task)

Input

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




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.



KS_GetTaskSema

June 21, 2002

Example 2-19. Read Task Termination Semaphore

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

SEMA semalist[] ={ OEVENT, /* other event */ (SEMA)0, /* tasksema, to be filled in below */ (SEMA)0 /* 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


KS_GetTaskState

June 21, 2002

KS_GetTaskState Get the state of a task.

Synopsis KSRC KS_GetTaskState (TASK task)

Input

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


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.




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.



KS_GetTaskState

June 21, 2002

Example 2-20. Read Task State

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


KS_GetTickSlice

June 21, 2002

KS_GetTickSlice Get the tick-slice quantum of a task.

Synopsis TSLICE KS_GetTickSlice (TASK task)

Input

Description The KS_GetTickSlice kernel service obtains the value of the tick-slice quantum for the specified task. If there has been no tick-slice quantum defined for task, the service returns a value of zero (0).

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

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




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

Example 2-21. Read Task Tick-Slice Quantum

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

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



KS_GetTickSlice

June 21, 2002

See Also KS_DefTickSlice, page 38


INIT_TaskClassProp

June 21, 2002

INIT_TaskClassProp Initialize the Task object class properties.

Synopsis KSRC INIT_TaskClassProp (const KCLASSPROP *pclassprop)

Input

Description 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


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



RC_NO_RAM if the initialization fails because there is insufficient system RAM available.

pclassprop A pointer to a Task object class properties structure.


INIT_TaskClassProp

June 21, 2002

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


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 310KS_GetTaskClassProp, page 47


KS_LookupTask

June 21, 2002

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

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

Inputs

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.

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

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


KS_LookupTask

June 21, 2002

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


TASK dyntask;static char buf[128];

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

See Also KS_DefTaskName, page 30KS_OpenTask, page 66


KS_OpenTask

June 21, 2002

KS_OpenTask Allocate and name a dynamic task.

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

Inputs

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


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.

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

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


KS_OpenTask

June 21, 2002

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.


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


KSRC ksrc;TASK dyntask;

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

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


XX_ResumeTask

June 21, 2002

XX_ResumeTask Resume a task that was previously suspended.

Zones IS_ResumeTask TS_ResumeTask KS_ResumeTask

Synopsis void XX_ResumeTask (TASK task)

Input

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





task The number of the task to resume.


XX_ResumeTask

June 21, 2002

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" /* RTXC Kernel Service prototypes */#include "ktask.h" /* defines AIREADER */

KS_SuspendTask (AIREADER); /* suspend task AIREADER */

... perform some operations

KS_ResumeTask (AIREADER); /* resume task AIREADER */

See Also KS_SuspendTask, page 71


KS_SleepTask

June 21, 2002

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

Synopsis void KS_SleepTask (COUNTER counter, TICKS ticks)

Inputs

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


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

Example 2-27. Put Current Task to Sleep

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */#include "kproject.h" /* defines CLKTICK */#include "kcounter.h" /* 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);

counter The counter associated with the interval defined by ticks.

ticks The number of ticks the Current Task should sleep.


KS_SuspendTask

June 21, 2002

KS_SuspendTask Suspend a task.

Synopsis void KS_SuspendTask (TASK task)

Input

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





Example In Example 2-28, the Current Task suspends the LKDETECT task and then suspends itself.

Example 2-28. Suspend Task

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

KS_SuspendTask (LKDETECT); /* suspend LKDETECT task */

KS_SuspendTask (SELFTASK); /* suspend self */

See Also XX_ResumeTask, page 68KS_ExecuteTask, page 42

task The number of the task to suspend.


KS_TerminateTask

June 21, 2002

KS_TerminateTask Terminate a task.

Synopsis void KS_TerminateTask (TASK task)

Input

Description 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 self-termination.

If task has previously been put to sleep, the sleep alarm is stopped. If task is waiting on some kernel object, it is removed from that object’s list of waiters. If task is waiting on a kernel object with an associated alarm, it is removed from that object’s list of waiters and the alarm is stopped.

If task is dynamic, it is not released to the free pool of dynamic tasks. A task can be released only by making a call to KS_CloseTask.

Warning: While it is possible to terminate another task, it should only be done when the terminator knows the act will not jeopardize system integrity. The termination process does not clean up tasks that are currently using or have allocated kernel objects. The programmer must ensure all such system elements are released to the system before termination.





task The number of the task to terminate.


KS_TerminateTask

June 21, 2002

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

Example 2-29. Terminate Task

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

KS_TerminateTask (TASKBX); /* terminate task TASKBX */

KS_TerminateTask (SELFTASK); /* now terminate self */

See Also KS_CloseTask, page 25KS_ExecuteTask, page 42KS_DefTaskSema, page 36


KS_UseTask

June 21, 2002

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

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

Inputs

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 task’s handle in the variable pointed to by ptask. This procedure allows the Current Task to reference the dynamic task successfully in subsequent kernel service calls.


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


RC_GOOD if the search and registration is successful. The service stores the matching task’s handle in the variable pointed to by ptask.

RC_STATIC_OBJECT if the specified name belongs to a static task.

RC_OBJECT_NOT_FOUND if the service finds no matching task name.

Example 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


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


KS_UseTask

June 21, 2002

console indicating the handle of the task if successful or an error message if unsuccessful.

Example 2-30. Read Task Handle and Register It


TASK dyntask;KSRC ksrc;static char buf[128];

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

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


KS_YieldTask

June 21, 2002

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

Synopsis KSRC KS_YieldTask (void)


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

Yielding when there is no other task at the same priority causes no change in the Ready List and the calling task resumes immediately.


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.


KS_YieldTask

June 21, 2002

Example 2-31. Yield to Another Task


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


KS_YieldTask

June 21, 2002

Chapter 3: Semaphore Services 79

June 21, 2002

C H A P T E R 3 Semaphore Services

In This ChapterWe 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


KS_CloseSema

June 21, 2002

KS_CloseSema End the use of a dynamic semaphore.

Synopsis KSRC KS_CloseSema (SEMA sema)

Input

Description The KS_CloseSema kernel service ends the Current Task’s use of the dynamic semaphore specified in sema. When closing the semaphore, the kernel detaches the calling task’s use of sema. If the caller is sema’s last user, the kernel releases the semaphore to the free pool of dynamic semaphores for reuse. If there is at least one other task using sema, the kernel does not release the semaphore to the free pool.

Be careful when closing a semaphore on which multiple tasks may be waiting. Closing the semaphore may cause waiters to be lost. However, you can avoid this problem if each task that uses the semaphore makes a KS_UseSema call before it begins using the semaphore and then makes a KS_CloseSema call when it is done using the semaphore.

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


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 Task’s use of the specified semaphore is closed but it remains open for use by other tasks.

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


KS_CloseSema

June 21, 2002

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



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

Example 3-1. Close Semaphore

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

SEMA dynsema; /* dynamic semaphore's handle */KSRC ksrc;

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 100KS_UseSema, page 120


KS_DefSemaCount

June 21, 2002

KS_DefSemaCount Define a semaphore count.

Synopsis void KS_DefSemaCount (SEMA sema, SEMACOUNT count)

Inputs

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.




FE_UNINITIALIZED_SEMA if the specified semaphore has not 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.

sema The handle of the semaphore being defined.

count The count value for the semaphore.


KS_DefSemaCount

June 21, 2002

Example 3-2. Set Semaphore Count

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


KS_DefSemaName

June 21, 2002

KS_DefSemaName Define the name of a previously opened dynamic semaphore.

Synopsis KSRC KS_DefSemaName (SEMA sema, const char *pname)

Inputs

Description The KS_DefSemaName kernel service names or renames the dynamic semaphore specified in sema. The service uses the null-terminated string pointed to by pname for the semaphore’s new name.

Static semaphores cannot be named or renamed under program control.


This service does not check for duplicate semaphore names.



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.






KS_DefSemaName

June 21, 2002

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


SEMA dynsema;

if (KS_DefSemaName (dynsema, "NewSema") != RC_GOOD){ ... Naming operation failed. Deal with it here}

... naming operation was successful. Continue

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


KS_DefSemaProp

June 21, 2002

KS_DefSemaProp Define the properties of a semaphore.

Synopsis void KS_DefSemaProp (SEMA sema, const SEMAPROP *psemaprop)

Inputs

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; /* Waiting Order & signal type */} SEMAPROP;

You may define the following semaphore attribute values:

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.


psemaprop A pointer to a semaphore properties structure.

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

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


KS_DefSemaProp

June 21, 2002




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

Example 3-5. Specify Semaphore Waiting Order


SEMA dynsema;SEMAPROP sprop;KSRC ksrc;

/* get current properties of the semaphore */KS_GetSemaProp (dynsema, &sprop);

/* use priority waiters */sprop.attributes &= ~ATTR_FIFO_ORDER;

KS_DefSemaProp (dynsema, &sprop); /* define properties */

... Continue

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


KS_GetSemaClassProp

June 21, 2002

KS_GetSemaClassProp Get the Semaphore object class properties.

Synopsis const KCLASSPROP * KS_GetSemaClassProp (int *pint)

Input

Description 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; /* number of static objects */ KOBJECT n_dynamics; /* number of dynamic objects */ short objsize; /* used for calculating offsets */ short totalsize; /* used to alloc object array RAM */ ksize_t namelen /* length of name string */ const char *pstaticnames;} KCLASSPROP;

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

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


KS_GetSemaClassProp

June 21, 2002


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


KCLASSPROP *psemaclass;int free_dyn;

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

See Also INIT_SemaClassProp, page 96

Table 3-1. Semaphore Class Attributes and Masks

Attribute Mask



Statistics ATTR_STATISTICS


KS_GetSemaCount

June 21, 2002

KS_GetSemaCount Get the current semaphore count.

Synopsis SEMACOUNT KS_GetSemaCount (SEMA sema)

Input

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




sema The handle of the semaphore being queried.


KS_GetSemaCount

June 21, 2002

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" /* RTXC Kernel Service prototypes */#include "ksema.h" /* defines AIDONE */

SEMACOUNT count;

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

See Also XX_SignalSema, page 102KS_DefSemaCount, page 82


KS_GetSemaName

June 21, 2002

KS_GetSemaName Get the name of a semaphore.

Synopsis char * KS_GetSemaName (SEMA sema)

Input

Description The KS_GetSemaName kernel service obtains a pointer to the null-terminated 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).



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



KS_GetSemaName

June 21, 2002

Example 3-9. Read Semaphore Name


static char buf[128];SEMA dynsema;char *pname;

if ((pname = KS_GetSemaName (dynsema)) == (char *)0 ) sprintf (buf, "Semaphore %d has no name\n", dynsema);else sprintf (buf, "Semaphore %d name is %s\n", dynsema, pname);

putline (buf); /* send message to console */

See Also KS_DefSemaName, page 84KS_OpenSema, page 100


KS_GetSemaProp

June 21, 2002

KS_GetSemaProp Get the properties of a semaphore.

Synopsis void KS_GetSemaProp (SEMA sema, SEMAPROP *psemaprop)

Inputs

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; /* Signal Type, Waiting Order */} SEMAPROP;

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




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.


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


KS_GetSemaProp

June 21, 2002

Example 3-10. Read Semaphore Properties


SEMA dynsema;SEMAPROP sprop; KS_GetSemaProp (dynsema, &sprop); /* get properties */

if (sprop.attributes & ATTR_FIFO_ORDER){ /* use priority mode*/ sprop.attributes &= ~ATTR_FIFO_ORDER;

/* define properties */ KS_DefSemaProp (dynsema, &sprop);}

... continue

See Also KS_DefSemaProp, page 86


INIT_SemaClassProp

June 21, 2002

INIT_SemaClassProp Initialize the Semaphore object class properties.

Synopsis KSRC INIT_SemaClassProp (const KCLASSPROP *pclassprop)

Input

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




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.

pclassprop A pointer to a Semaphore object class properties structure.


INIT_SemaClassProp

June 21, 2002

Example 3-11. Initialize Semaphore Object Class


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


/* Initialize the Semaphore kernel object class */ if ((ksrc = INIT_SemaClassProp (&semaclassprop)) != RC_GOOD) { putline ("No RAM for Semaphore init"); return (ksrc); /* end initialization process */ }


}

See Also INIT_SysProp, page 310KS_GetSemaClassProp, page 88


KS_LookupSema

June 21, 2002

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

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

Inputs

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 semaphore’s handle in the variable pointed to by psema. The service searches dynamic names, if any, first.

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

This service has no effect on the registration of the specified semaphore by the Current Task.

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


RC_GOOD if the search succeeds. The service stores the matching semaphore’s handle in the variable pointed to by psema.

RC_OBJECT_NOT_FOUND if the service finds no matching semaphore name.


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


KS_LookupSema

June 21, 2002

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


SEMA dynsema;

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

See Also KS_DefSemaName, page 84KS_OpenSema, page 100


KS_OpenSema

June 21, 2002

KS_OpenSema Allocate and name a dynamic semaphore.

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

Inputs

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.


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


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


KS_OpenSema

June 21, 2002

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


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


KSRC ksrc;SEMA dynsema;

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

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


XX_SignalSema

June 21, 2002

XX_SignalSema Signal a semaphore.

Zones IS_SignalSema TS_SignalSema KS_SignalSema

Synopsis void XX_SignalSema (SEMA sema)

Input

Description If the semaphore specified in sema has one or more waiters and a count value of 0, the count value of sema remains 0 and the waiters are processed according to sema’s signal type.

For each semaphore signaled, if its Signal Type attribute is in the default state, the service removes the SEMAPHORE_WAIT state of the first waiting task only. If Signal Type is set to ATTR_MULTIPLE_WAITERS, the service removes the SEMAPHORE_WAIT state for all tasks in the waiting list for the event.

If a waiting task becomes runnable as a result of the removal of its SEMAPHORE_WAIT state, the service places the task in the Ready List at a position dependent on its current priority.

If the semaphore has no waiters or has a non-zero count value, the XX_SignalSema kernel service simply increments the count value of the semaphore specified in sema and returns control to the calling task. The count value for sema never exceeds the maximum value for the SEMACOUNT type.





sema The handle of the semaphore to signal.


XX_SignalSema

June 21, 2002

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" /* RTXC Kernel Service prototypes */#include "kqueue.h" /* defines CHARQ */#include "ksema.h" /* defines XOFF and XON */

static QUEUEPROP qprop;

/* get CHARQ properties */KS_GetQueueProp (CHARQ, &qprop);

if (qprop.current_size > 20) KS_SignalSema (XOFF);if (qprop.current_size < 4) KS_SignalSema (XON);

... continue

See Also XX_SignalSemaM, page 104


XX_SignalSemaM

June 21, 2002

XX_SignalSemaM Signal multiple semaphores.

Zones IS_SignalSemaM TS_SignalSemaM KS_SignalSemaM

Synopsis void XX_SignalSemaM (const SEMA *psemalist)

Input

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





psemalist A pointer to a null-terminated semaphore list.


XX_SignalSemaM

June 21, 2002

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" /* RTXC Kernel Service prototypes */#include "ksema.h" /*defines SWITCH1, SWITCH2, & CHNLDONE */

const SEMA semalist[] ={ SWITCH1, SWITCH2, CHNLDONE, (SEMA)0 /* null terminator */}

... use multiplexor channel

KS_SignalSemaM (semalist);/* signal multiple semaphores */

... continue processing

See Also XX_SignalSema, page 102KS_TestSemaM, page 110


KS_TestSema

June 21, 2002

KS_TestSema Test a semaphore.

Synopsis KSRC KS_TestSema (SEMA sema)

Input

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


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

RC_NO_SIGNAL if the service detects a semaphore count less than or equal to zero (0).




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.

sema The handle of the semaphore to test.


KS_TestSema

June 21, 2002

Example 3-16. Test Semaphore

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */#include "ksema.h" /* 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 102XX_SignalSemaM, page 104


KS_TestSemaT

June 21, 2002

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

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

Inputs

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 sema’s count value is equal to zero (0), or

The specified number of ticks elapses.

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


RC_GOOD if a semaphore signal has occurred.


counter The counter associated with the tick interval defined by ticks.

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


KS_TestSemaT

June 21, 2002

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




FE_ILLEGAL_COUNTER if the specified counter ID is not valid.

FE_UNINITIALIZED_COUNTER if the specified counter has not yet been initialized.

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

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

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */#include "ksema.h" /* defines KEYPAD */#include "kcounter.h" /* defines MSCOUNTER */#include "kproject.h" /* 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 102XX_SignalSemaM, page 104KS_TestSema, page 106KS_TestSemaW, page 118


KS_TestSemaM

June 21, 2002

KS_TestSemaM Test a list of semaphores.

Synopsis SEMA KS_TestSemaM (const SEMA *psemalist)

Input

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






KS_TestSemaM

June 21, 2002

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" /* RTXC Kernel Service prototypes */#include "ksema.h" /* 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 106KS_TestSemaMW, page 115XX_SignalSema, page 102XX_SignalSemaM, page 104


KS_TestSemaMT

June 21, 2002

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

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

Inputs

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





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


KS_TestSemaMT

June 21, 2002

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.






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.


KS_TestSemaMT

June 21, 2002

However, if neither switch closes within the expected time of two seconds on counter[0], the task reads the lack of closure as a system malfunction and takes special action.

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

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */#include "ksema.h" /* defines SW1CLOSE, SW2CLOSE, KEYSW */#include "kproject.h" /* 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 106KS_TestSemaMW, page 115XX_SignalSema, page 102XX_SignalSemaM, page 104


KS_TestSemaMW

June 21, 2002

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

Synopsis SEMA KS_TestSemaMW (const SEMA *psemalist)

Input

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


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



KS_TestSemaMW

June 21, 2002

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.




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.


KS_TestSemaMW

June 21, 2002

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

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */#include "ksema.h" /* defines SWITCH1, SWITCH2, TIMERA */

SEMA cause;const SEMA semalist[] ={ SWITCH1, SWITCH2, TIMERA, (SEMA)0 /* null terminated list */};

for (;;){ /* test the semaphores and wait for any of 3 events */ cause = KS_TestSemaMW (semalist); switch (cause) { case SWITCH1: ... process SWITCH1 event... break;

case SWITCH2: ... process SWITCH2 event... break;

case TIMERA: ... process TIMERA event... break;

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

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


KS_TestSemaW

June 21, 2002

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

Synopsis void KS_TestSemaW (SEMA sema)

Input

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





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.



KS_TestSemaW

June 21, 2002

Example 3-21. Test Semaphore—Wait for Signal

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

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

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


KS_UseSema

June 21, 2002

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

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

Inputs

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 semaphore’s handle in the variable pointed to by psema. This procedure allows the Current Task to reference the dynamic semaphore successfully in subsequent kernel service calls.


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


RC_GOOD if the search and registration is successful. The service stores the matching semaphore’s handle in the variable pointed to by psema.

RC_STATIC_OBJECT if the specified name belongs to a static semaphore.

RC_OBJECT_NOT_FOUND if the service finds no matching semaphore name.

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


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


KS_UseSema

June 21, 2002

Example 3-22. Read Semaphore Handle and Register It


KSRC ksrc;SEMA dynsema;

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

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


KS_UseSema

June 21, 2002

Chapter 4: Queue Services 123

June 21, 2002

C H A P T E R 4 Queue Services

In This ChapterWe 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


KS_CloseQueue

June 21, 2002

KS_CloseQueue End the use of a dynamic queue.

Synopsis KSRC KS_CloseQueue (QUEUE queue)

Input

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

Be careful when closing a queue on which multiple tasks may be waiting. Closing the queue may cause waiters to be lost. However, you can avoid this problem if each task that uses the queue makes a KS_UseQueue call before it begins using the queue and then makes a KS_CloseQueue call when it is done using the queue.

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



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 Task’s use of the specified queue is closed but the queue remains open for use by other tasks.

queue The handle of the queue to close.


KS_CloseQueue

June 21, 2002



FE_ILLEGAL_QUEUE if the specified queue ID is not valid.

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

Example 4-1. Close Queue


QUEUE dynqueue; /* handle of queue to be closed */SEMA dynsema;


KS_CloseQueue (dynqueue); /* then close the queue */

See Also KS_OpenQueue, page 152KS_UseQueue, page 162


KS_DefQueueName

June 21, 2002

KS_DefQueueName Define the name of a previously opened dynamic queue.

Synopsis KSRC KS_DefQueueName (QUEUE queue, const char *pname)

Inputs

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 queue’s new name.

Static queues cannot be named or renamed under program control.


This service does not check for duplicate queue names.



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.



queue The handle of the queue being defined.



KS_DefQueueName

June 21, 2002

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


QUEUE dynqueue;

if (KS_DefQueueName (dynqueue, "NewQueue") != RC_GOOD){ ... Error in naming the queue. Deal with it here}


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


KS_DefQueueProp

June 21, 2002

KS_DefQueueProp Define the properties of a queue.

Synopsis void KS_DefQueueProp (QUEUE queue, const QUEUEPROP *pqueueprop)

Inputs

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; /* Waiting Order */ char *base; /* Address of queue body */ QWIDTH width; /* Width of an entry (bytes) */ KCOUNT depth; /* Maximum # of entries */ KCOUNT current_size; /* Current # of entries in the queue */} QUEUEPROP;

You may define the following queue attribute value:


queue The handle of the queue being defined.

pqueueprop A pointer to a Queue properties structure.

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.


KS_DefQueueProp

June 21, 2002



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


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 144INIT_QueueClassProp, page 148KS_OpenQueue, page 152


KS_DefQueueSema

June 21, 2002

KS_DefQueueSema Associate a semaphore with a queue condition event.

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

Inputs

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.




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

sema The handle of the semaphore to associate with the queue.

event The queue event with which to associate the semaphore.


KS_DefQueueSema

June 21, 2002




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.


KS_DefQueueSema

June 21, 2002

Example 4-5. Associate Queue Event with Semaphore

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */#include "kqueue.h" /* defines DATAQ1 and DATAQ2 */#include "ksema.h" /* defines GOT1 and GOT2 */

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


KS_DefQueueSema

June 21, 2002

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


KS_GetQueueClassProp

June 21, 2002

KS_GetQueueClassProp Get the Queue object class properties.

Synopsis const KCLASSPROP * KS_GetQueueClassProp (int *pint)

Input

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


The attributes element of the Queue KCLASSPROP structure supports the class property attributes and masks listed in Table 4-1 on page 135.


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.

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


KS_GetQueueClassProp

June 21, 2002

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


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

Table 4-1. Queue Class Attributes and Masks

Attribute Mask



Semaphores ATTR_SEMAPHORES


KS_GetQueueData

June 21, 2002

KS_GetQueueData Get the next entry from a queue.

Synopsis KSRC KS_GetQueueData (QUEUE queue, void *pdest)

Inputs

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_QUEUE_EMPTY if the queue is empty at the time of the kernel service request.




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.

queue The handle of the queue being queried.

pdest A pointer to the destination buffer.


KS_GetQueueData

June 21, 2002

Example 4-7. Read Queue Entry

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

struct{ int count; int values[8];} entry;

if (KS_GetQueueData (DATAQ1, &entry) == RC_GOOD){ ... do some processing}else{ ... no data available, do something else}

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


KS_GetQueueDataT

June 21, 2002

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 KSRC KS_GetQueueDataT (QUEUE queue, void *pdest, COUNTER counter, TICKS ticks)

Inputs

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


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.




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


KS_GetQueueDataT

June 21, 2002







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 Entry—Wait Number of Ticks If Necessary

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */#include "kqueue.h" /* defines DATAQ */#include "kcounter.h" /* defines CLKCOUNTER#include "kproject.h" /* 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 136KS_GetQueueDataW, page 140


KS_GetQueueDataW

June 21, 2002

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

Synopsis void KS_GetQueueDataW (QUEUE queue, void *pdest)

Inputs

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.






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.




KS_GetQueueDataW

June 21, 2002

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

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */#include "kqueue.h" /* 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 136KS_GetQueueDataT, page 138


KS_GetQueueName

June 21, 2002

KS_GetQueueName Get the name of a queue.

Synopsis char * KS_GetQueueName (QUEUE queue)

Input

Description 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 null-terminated name string.

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



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



KS_GetQueueName

June 21, 2002

Example 4-10. Read Dynamic Queue Name


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

See Also KS_DefQueueName, page 126KS_OpenQueue, page 152


KS_GetQueueProp

June 21, 2002

KS_GetQueueProp Get the properties of a queue.

Synopsis void KS_GetQueueProp (QUEUE queue, QUEUEPROP *pqueueprop)

Inputs

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





pqueueprop A pointer to a Queue properties structure.


KS_GetQueueProp

June 21, 2002

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" /* RTXC Kernel Service prototypes */#include "kqueue.h" /* defines CHARQ */#include "ksema.h" /* defines XOFF and XON */

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

See Also KS_DefQueueProp, page 128


KS_GetQueueSema

June 21, 2002

KS_GetQueueSema Get the semaphore handle associated with a queue event.

Synopsis SEMA KS_GetQueueSema (QUEUE queue, QEVENT event)

Inputs

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




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


event A queue event value.


KS_GetQueueSema

June 21, 2002

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" /* RTXC Kernel Service prototypes */#include "ksema.h" /* defines MAINQNESEMAQ */#include "kqueue.h" /* defines MAINQ */

SEMA semalist[] ={ (SEMA)0; /* QNE, to be filled in below */ (SEMA)0; /* null terminator */}

SEMA qnesema, cause;

if ((qnesema = KS_GetQueueSema (MAINQ, QNE)) == (SEMA)0){ /* no QNE semaphore defined for queue MAINQ */ KS_DefQueueSema (MAINQ, MAINQNESEMA, QNE); qnesema = MAINQNESEMA;}/* there is now a QNE semaphore defined for *//* queue MAINQ *//* store it in semalist */semalist[1] = qnesema;

/* and wait for either event to occur */cause = KS_TestSemaMW (semalist); /* wait for the event */switch (cause){ ... process the event according to the case of cause}

See Also KS_DefQueueSema, page 130


INIT_QueueClassProp

June 21, 2002

INIT_QueueClassProp Initialize the Queue object class properties.

Synopsis KSRC INIT_QueueClassProp (const KCLASSPROP *pclassprop)

Input

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


The attributes element of the Queue KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 4-1 on page 135.




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.

pclassprop A pointer to a Queue object class properties structure.


INIT_QueueClassProp

June 21, 2002

Example 4-13. Initialize Queue Object Class


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



/* 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 310KS_GetQueueClassProp, page 134


KS_LookupQueue

June 21, 2002

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

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

Inputs

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.


RC_GOOD if the search succeeds. The service also stores the matching queue’s handle in the variable pointed to by pqueue.

RC_OBJECT_NOT_FOUND if the service finds no matching queue name.


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


KS_LookupQueue

June 21, 2002

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


QUEUE dynqueue;QEVENT qevent;char data[4];

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

See Also KS_DefQueueName, page 126KS_OpenQueue, page 152


KS_OpenQueue

June 21, 2002

KS_OpenQueue Allocate and name a dynamic queue.

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

Inputs

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.


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.


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


KS_OpenQueue

June 21, 2002

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.


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.


KS_OpenQueue

June 21, 2002

Example 4-15. Allocate and Initialize Queue

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

KSRC ksrc;QUEUE dynqueue;PEVENT pevent;

struct QUEUEPROP qprop; /* queue properties */struct PARTPROP pprop; /* partition properties */

if ((ksrc = KS_OpenQueue ("DynDataQ2", &dynqueue)) != RC_GOOD){ if (ksrc == RC_OBJECT_ALREADY_EXISTS) putline ("DynDataQ2 queue name in use"); else if (ksrc == RC_NO_OBJECT_AVAILABLE) putline ("No dynamic queues available"); else putline ("The Queue Object Class is not defined");}else{ /* queue was opened correctly. */

/* get block of memory for queue body */ qprop.base = (char *)KS_AllocBlkW (QUEBODY, &pevent);

/* get partition’s properties to get size of block */ KS_GetPartProp (QUEBODY, &pprop);

/* fill in rest of queue properties */ qprop.depth = pprop.size / 4; qprop.width = 4; qprop.current_size = 0; /* queue is initially empty */

/* define queue now */ KS_DefQueueProp (dynqueue, &qprop);

... continue}


KS_OpenQueue

June 21, 2002

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


KS_PutQueueData

June 21, 2002

KS_PutQueueData Put an entry into a queue.

Synopsis KSRC KS_PutQueueData (QUEUE queue, const void *psource)

Inputs

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.



RC_QUEUE_FULL if the service failed to insert data into the specified queue.




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.

queue The handle of the queue.

psource A pointer to the source buffer.


KS_PutQueueData

June 21, 2002

Example 4-16. Put Data Into Queue


struct{ int type; int value;} entry;

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

See Also KS_PutQueueDataT, page 158KS_PutQueueDataW, page 160


KS_PutQueueDataT

June 21, 2002

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 KSRC KS_PutQueueDataT (QUEUE queue, const void *psource, COUNTER counter, TICKS ticks)

Inputs

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


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.



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




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


KS_PutQueueDataT

June 21, 2002






FE_NULL_SOURCEBUFFER if the pointer to the source buffer is null.

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

Example 4-17. Put Data Into Queue—Wait Number of Ticks If Queue is Full

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


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

See Also KS_PutQueueData, page 156KS_PutQueueDataW, page 160


KS_PutQueueDataW

June 21, 2002

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

Synopsis void KS_PutQueueDataW (QUEUE queue, const void *psource)

Inputs

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.





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.




KS_PutQueueDataW

June 21, 2002

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



/* enqueue packet of info into DATAQ */KS_PutQueueDataW (DATAQ, &entry);

... continue

See Also KS_PutQueueData, page 156KS_PutQueueDataT, page 158


KS_UseQueue

June 21, 2002

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

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

Inputs

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 queue’s handle in the variable pointed to by pqueue. This procedure allows the Current Task to reference the dynamic queue successfully in subsequent kernel service calls.


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


RC_GOOD if the search and registration is successful. The service also stores the matching queue’s handle in the variable pointed to by pqueue.

RC_STATIC_OBJECT if the specified name belongs to a static queue.

RC_OBJECT_NOT_FOUND if the service finds no matching queue name.

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


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


KS_UseQueue

June 21, 2002

Example 4-19. Read Queue Handle and Register It


KSRC ksrc;QUEUE dynqueue;

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

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


KS_UseQueue

June 21, 2002

Chapter 5: Mailbox Services 165

June 21, 2002

C H A P T E R 5 Mailbox Services

In This ChapterWe 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


KS_CloseMbox

June 21, 2002

KS_CloseMbox End the use of a dynamic mailbox.

Synopsis KSRC KS_CloseMbox (MBOX mbox)

Input

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

Be careful when closing a mailbox on which one or more tasks may be waiting. Closing the mailbox may cause waiters to be lost. However, you can avoid this problem if each task that uses the mailbox makes a KS_UseMbox call before it begins using the mailbox and then makes a KS_CloseMbox call when it is done using the mailbox.

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



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 Task’s use of the specified mailbox is closed but the mailbox remains open for use by other tasks.

mbox The handle of the mailbox.


KS_CloseMbox

June 21, 2002



FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.

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

Example 5-1. Close Mailbox


MBOX dynmbox;SEMA dynsema;KSRC ksrc;


/* then close the mailbox */if ((ksrc = KS_CloseMbox (dynmbox)) != RC_GOOD){ /* okay if other users exist */ if (ksrc != RC_OBJECT_INUSE) { ... mailbox cannot be closed. Deal with it here. }}/* Otherwise, mailbox closed and released to the *//* free pool */

... Continue

See Also KS_OpenMbox, page 188KS_DefMboxProp, page 170


KS_DefMboxName

June 21, 2002

KS_DefMboxName Define the name of a previously opened dynamic mailbox.

Synopsis KSRC KS_DefMboxName (MBOX mbox, const char *pname)

Inputs

Description The KS_DefMboxName kernel service names or renames the open dynamic mailbox specified in mbox. The service uses the null-terminated string pointed to by pname for the mailbox’s new name.

Static mailboxes cannot be named or renamed under program control.


This service does not check for duplicate task names.



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.



mbox The handle of the mailbox being defined.



KS_DefMboxName

June 21, 2002

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


MBOX dynmbox;

if (KS_DefMboxName (dynmbox, "NewMbox") != RC_GOOD){ ... Naming operation failed. Deal with it here}


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


KS_DefMboxProp

June 21, 2002

KS_DefMboxProp Define the properties of a mailbox.

Synopsis void KS_DefMboxProp (MBOX mbox, const MBOXPROP *pmboxprop)

Inputs

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; /* Waiting Order */} MBOXPROP;

You may define the following mailbox attribute value:






pmboxprop A pointer to a Mailbox properties structure.

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.


KS_DefMboxProp

June 21, 2002

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


MBOX dynmbox;MBOXPROP mprop;KSRC ksrc;

KS_GetMboxProp (dynmbox, &mprop); /* Get properties */

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

KS_DefMboxProp (dynmbox, &mprop); /* define properties */

... Continue

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


KS_DefMboxSema

June 21, 2002

KS_DefMboxSema Associate a semaphore with the Mailbox_Not_Empty event.

Synopsis void KS_DefMboxSema (MBOX mbox, SEMA sema)

Inputs

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.




FE_UNINITIALIZED_MBOX if the specified mailbox has not yet been initialized.




sema The handle of a semaphore to associate with the mailbox.


KS_DefMboxSema

June 21, 2002

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.


KS_DefMboxSema

June 21, 2002

Example 5-5. Define Mailbox Semaphore

#include "rtxcapi.h" /* RTXC Kernel Services prototypes */#include "kmbox.h" /* defines HPMAIL and LPMAIL */#include "ksema.h" /* defines GOTHP and GOTLP */

char *msg;MSGENV *penvelope;SEMA sema;

const SEMA semalist[] ={ GOTHP, GOTLP, (SEMA)0 /* list must be null terminated */};

KS_DefMboxSema (HPMAIL, GOTHP); /* define semas for */KS_DefMboxSema (LPMAIL, GOTLP); /* both mailboxes */

/* now test for a signal and wait if there is none */sema = KS_TestSemaMW (semalist);

switch (sema) /* see which one was signaled */{ case GOTHP: /* receive message in HPMAIL from any task */ msg = KS_ReceiveMsg (HPMAIL, &penvelope); ... process received message break;

case GOTLP: /* receive message in LPMAIL from any task */ msg = KS_ReceiveMsg (LPMAIL, &penvelope); ... process received message break;}/* acknowledge message receipt and processing */KS_AckMsg (penvelope);

... continue


KS_DefMboxSema

June 21, 2002

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


KS_GetMboxClassProp

June 21, 2002

KS_GetMboxClassProp Get the Mailbox object class properties.

Synopsis const KCLASSPROP * KS_GetMboxClassProp (int *pint)

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

Description The KS_GetMboxClassProp kernel service obtains a pointer to the KCLASSPROP structure that was used during system initialization by the INIT_MboxClassProp service to initialize the Mailbox object class properties. If pint is not null ((int *)0), the service returns the number of available dynamic mailboxes in the variable pointed to by pint.


The attributes element of the Mailbox KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 5-1.


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.

Table 5-1. Mailbox Class Attributes and Masks

Attribute Mask





KS_GetMboxClassProp

June 21, 2002

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


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


KS_GetMboxName

June 21, 2002

KS_GetMboxName Get the name of a mailbox.

Synopsis char * KS_GetMboxName (MBOX mbox)

Input

Description The KS_GetMboxName kernel service obtains a pointer to the null-terminated 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 null-terminated name string.

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



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

mbox The handle of the mailbox being queried.


KS_GetMboxName

June 21, 2002

Example 5-7. Read Mailbox Name

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


MBOX dynmbox;char *pname;

if ((pname = KS_GetMboxName (dynmbox)) == (char *)0) sprintf (buf, "Mailbox %d has no name", dynmbox);

else sprintf (buf, "Mailbox %d name is %s", dynmbox, pname);

putline (buf);

See Also KS_DefMboxName, page 168KS_OpenMbox, page 188


KS_GetMboxProp

June 21, 2002

KS_GetMboxProp Get the properties of a mailbox.

Synopsis void KS_GetMboxProp (MBOX mbox, MBOXPROP *pmboxprop)

Inputs

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.





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


pmboxprop A pointer to a Mailbox properties structure.


KS_GetMboxProp

June 21, 2002

properties of the specified mailbox and then forces priority order waiting.

Example 5-8. Read Mailbox Properties


MBOX dynmbox;MBOXPROP mboxprop;

KS_GetMboxProp (dynmbox, &mboxprop); /* get properties */

/* force priority Waiting Order */mboxprop.attributes &= (~ATTR_FIFO_ORDER);

/* define properties */KS_DefMboxProp (dynmbox, &mboxprop);

... continue

See Also KS_GetMboxProp, page 180


KS_GetMboxSema

June 21, 2002

KS_GetMboxSema Get the semaphore handle associated with a Mailbox_Not_Empty event.

Synopsis SEMA KS_GetMboxSema (MBOX mbox)

Input

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




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



KS_GetMboxSema

June 21, 2002

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" /* RTXC Kernel Services prototypes */#include "ksema.h" /* defines MBOX1SEMA, MBXSEMA2 */#include "kmbox.h" /* 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


INIT_MboxClassProp

June 21, 2002

INIT_MboxClassProp Initialize the Mailbox object class properties.

Synopsis KSRC INIT_MboxClassProp (const KCLASSPROP *pclassprop)

Input

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


The attributes element of the Mailbox KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 5-1 on page 176.




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.

pclassprop A pointer to a Mailbox object class properties structure.


INIT_MboxClassProp

June 21, 2002

Example 5-10. Initialize Mailbox Object Class


extern const SYSPROP sysprop;extern const KCLASSPROP mboxclassprop;




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


}

See Also INIT_SysProp, page 310KS_GetMboxClassProp, page 176


KS_LookupMbox

June 21, 2002

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

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

Inputs

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 mailbox’s handle in the variable pointed to by pmbox. The service searches dynamic names, if any, first.

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

This service has no effect on the use registration of the specified mailbox by the Current Task.

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


RC_GOOD if the search succeeds. The service also stores the matching mailbox’s handle in the variable pointed to by pmbox.

RC_OBJECT_NOT_FOUND if the service finds no matching mailbox name.


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


KS_LookupMbox

June 21, 2002

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


static char buf[128]; /* buffer space */

MBOX dynmbox;

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

See Also KS_DefMboxName, page 168KS_OpenMbox, page 188


KS_OpenMbox

June 21, 2002

KS_OpenMbox Allocate and name a dynamic mailbox.

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

Inputs

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.


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


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


KS_OpenMbox

June 21, 2002

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


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


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}


KS_OpenMbox

June 21, 2002

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


KS_UseMbox

June 21, 2002

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

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

Inputs

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 mailbox’s handle in the variable pointed to by pmbox. This procedure allows the Current Task to reference the dynamic mailbox successfully in subsequent kernel service calls.


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


RC_GOOD if the search and registration is successful. The service also stores the matching mailbox’s handle in the variable pointed to by pmbox.

RC_STATIC_OBJECT if the specified name belongs to a static mailbox.

RC_OBJECT_NOT_FOUND if the service finds no matching mailbox name.

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


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


KS_UseMbox

June 21, 2002

Example 5-13. Read Mailbox Handle and Register It


KSRC ksrc;MBOX dynmbox;

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

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

Chapter 6: Message Services 193

June 21, 2002

C H A P T E R 6 Message Services

In This ChapterWe 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


KS_AckMsg

June 21, 2002

KS_AckMsg Acknowledge a message.

Synopsis void KS_AckMsg (MSGENV *pmsgenv)

Input

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


Errors This service may generate the following fatal error code:

FE_NULL_MSGENV if the pointer to the message envelope is null.

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

pmsgenv A pointer to a message envelope.


KS_AckMsg

June 21, 2002

Example 6-1. Acknowledge Message

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

MSGENV *pmsgenv;char *pmsgbody;

/* get next message from mailbox EMAIL */pmsgbody = (char *)KS_ReceiveMsgW (EMAIL, &pmsgenv);

... process message using pmsgbody as pointer to body

KS_AckMsg (pmsgenv); /* signal message processing done */

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


KS_ForwardMsg

June 21, 2002

KS_ForwardMsg Forward a message to a mailbox asynchronously.

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

Inputs

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 message’s priority. If a task is waiting to receive a message from the mailbox, the kernel passes the message directly to the receiving task and unblocks it. If, as a result, the receiving task becomes ready to run, the kernel places it in the Ready

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

pmsgenv A pointer to the message envelope.

priority The priority of the message.


KS_ForwardMsg

June 21, 2002

List at a position determined by its priority. If the receiving task’s priority is higher than that of the sending or forwarding task, a preemption occurs.

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





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


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.


KS_ForwardMsg

June 21, 2002

Example 6-2. Forward Message

#include "rtxcapi.h" /* RTXC Kernel Services prototypes */#include "kmbox.h" /* defines MAILBOX3 & MAILBOX2 */

struct { int command; /* start of message body */ char data[10];} msgbody;

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 206KS_SendMsgW, page 213KS_SendMsgT, page 209


KS_ForwardMsg

June 21, 2002


KS_ReceiveMsg

June 21, 2002

KS_ReceiveMsg Receive a message from a mailbox.

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

Inputs

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 mailbox’s attributes.

Output This service returns a pointer to the message body if a message was in the mailbox.

If no message was available, the service returns a null pointer ((void *)0).




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.

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

pmsgenv A pointer to a message envelope pointer.


KS_ReceiveMsg

June 21, 2002

Example 6-3. Receive Next Message from a Mailbox

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

void *pmsgbody;MSGENV *pmsgenv;

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

See Also KS_ReceiveMsgT, page 202KS_ReceiveMsgW, page 204


KS_ReceiveMsgT

June 21, 2002

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

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

Inputs

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.


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


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




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


KS_ReceiveMsgT

June 21, 2002






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

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

#include "rtxcapi.h" /* RTXC Kernel Services prototypes */#include "kmbox.h" /* defines MYMAIL */#include "kproject.h" /* defines CLKTICK */

void *pmsgbodyMSGENV *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 200KS_ReceiveMsgW, page 204


KS_ReceiveMsgW

June 21, 2002

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

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

Inputs

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.


If the mailbox is empty, the service blocks the requesting task and waits for the mailbox to receive the next message.

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




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.


pmsgenv A pointer to a message envelope pointer.


KS_ReceiveMsgW

June 21, 2002

Example 6-5. Receive Message—Wait If Necessary

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

void *pmsgbody;MSGENV *pmsgenv;

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

..continue

See Also KS_ReceiveMsg, page 200KS_ReceiveMsgT, page 202


KS_SendMsg

June 21, 2002

KS_SendMsg Send a message to a mailbox asynchronously.

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

Inputs

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.


When sending or forwarding a message to a mailbox, there may or may not be a task waiting to receive it. If not, the kernel adds the message to the mailbox according to the message’s priority. If a task is waiting to receive a message from the mailbox, the kernel passes the message directly to the receiving task and unblocks it. If, as a result, the receiving task becomes ready to run, the kernel places it in the Ready List at a position determined by its priority. If the receiving task’s priority is higher than that of the sending or forwarding task, a preemption occurs.

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


pmsgbody A pointer to the body of the message.

priority The priority of the message.


KS_SendMsg

June 21, 2002

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.







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.


KS_SendMsg

June 21, 2002

Example 6-6. Send Message—Wait for Acknowledgment

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

MSGENV msgenv; /* Message envelope (required) */


... 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 209KS_SendMsgW, page 213KS_TestAck, page 216KS_TestAckT, page 218KS_TestAckW, page 220


KS_SendMsgT

June 21, 2002

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

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

Inputs

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.


When sending or forwarding a message to a mailbox, there may or may not be a task waiting to receive it. If not, the kernel adds the message to the mailbox according to the message’s priority. If a task is waiting to receive a message from the mailbox, the kernel passes the message directly to the receiving task and unblocks it. If, as a

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



priority The priority value of the message.


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


KS_SendMsgT

June 21, 2002

result, the receiving task becomes ready to run, the kernel places it in the Ready List at a position determined by its priority. If the receiving task’s priority is higher than that of the sending or forwarding task, a preemption occurs.

After putting the message into the mailbox or passing it on to a waiting receiver, the kernel service blocks the sending task and starts an internal alarm for the interval specified in ticks on the specified counter. The task remains blocked until one of the following conditions occurs:

The receiving task acknowledges receipt of the message.


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


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.






KS_SendMsgT

June 21, 2002




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.


KS_SendMsgT

June 21, 2002

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

#include "rtxcapi.h" /* RTXC Kernel Services prototypes */#include "kmbox.h" /* defines MAILBOX3 */#include "kproject.h" /* defines CLKTICK */

TICKS timeout = (TICKS)250/CLKTICK;MSGENV msgenv; /* Message envelope (required) */KSRC status;


...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 216KS_TestAckT, page 218KS_TestAckW, page 220KS_SendMsg, page 206KS_SendMsgW, page 213


KS_SendMsgW

June 21, 2002

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

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

Inputs

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.


When sending or forwarding a message to a mailbox, there may or may not be a task waiting to receive it. If not, the kernel adds the message to the mailbox according to the message’s priority. If a task is waiting to receive a message from the mailbox, the kernel passes the message directly to the receiving task and unblocks it. If, as a result, the receiving task becomes ready to run, the kernel places it in the Ready List at a position determined by its priority. If the receiving task’s priority is higher than that of the sending or forwarding task, a preemption occurs.

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



priority The priority value of the message.


KS_SendMsgW

June 21, 2002

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.







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 Message—Wait for Acknowledgment




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


KS_SendMsgW

June 21, 2002

See Also KS_SendMsg, page 206KS_SendMsgT, page 209


KS_TestAck

June 21, 2002

KS_TestAck Test for message acknowledgment.

Synopsis KSRC KS_TestAck (MSGENV *pmsgenv)

Input

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

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

RC_GOOD if the message has been acknowledged.

RC_NOT_RECEIVED if the message is still in the mailbox.

RC_NO_ACK if the message is not in the mailbox but has not yet been acknowledged.



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



KS_TestAck

June 21, 2002

Example 6-9. Test for Message Acknowledgment





/* 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 218KS_TestAckW, page 220KS_AckMsg, page 194


KS_TestAckT

June 21, 2002

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

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

Inputs

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



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.



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


KS_TestAckT

June 21, 2002





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

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





/* 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 216KS_TestAckW, page 220KS_AckMsg, page 194


KS_TestAckW

June 21, 2002

KS_TestAckW Test for message acknowledgment and wait for the acknowledgment.

Synopsis void KS_TestAckW (MSGENV *pmsgenv)

Input

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




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



KS_TestAckW

June 21, 2002

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





/* 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 216KS_TestAckT, page 218KS_AckMsg, page 194


KS_TestAckW

June 21, 2002

Chapter 7: Memory Partition Services 223

June 21, 2002

C H A P T E R 7 Memory Partition Services

In This ChapterWe 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


XX_AllocBlk

June 21, 2002

XX_AllocBlk Allocate a block of memory.

Zones IS_AllocBlk TS_AllocBlk KS_AllocBlk

Synopsis void * XX_AllocBlk (PART part)

Inputs

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

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


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

part A handle for a partition.


XX_AllocBlk

June 21, 2002

Example 7-1. Allocate Block of Memory

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

char *p;

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

See Also KS_AllocBlkT, page 226KS_AllocBlkW, page 228


KS_AllocBlkT

June 21, 2002

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

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

Inputs

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


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





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


KS_AllocBlkT

June 21, 2002




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

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

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

char *p;

/* no return until requested memory is available *//* or until internal alarm expires. */p = (char *)KS_AllocBlkT (PART1, TIMEBASE, (TICKS)50/CLKTICK);

if (p == (char *)0){ ... internal alarm expired, deal with it}else{ ... Memory allocated. Proceed.}

See Also XX_AllocBlk, page 224KS_AllocBlkW, page 228


KS_AllocBlkW

June 21, 2002

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

Synopsis void * KS_AllocBlkW (PART part)

Input

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

If there is no available block in the memory partition, the service blocks the requesting task with a PARTITION_WAIT until memory in the specified partition becomes available.

Output This service returns a pointer to the allocated memory block.




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.



KS_AllocBlkW

June 21, 2002

Example 7-3. Allocate Block of Memory—Wait If Necessary

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

char *p;

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

...continue

See Also XX_AllocBlk, page 224KS_AllocBlkT, page 226


KS_ClosePart

June 21, 2002

KS_ClosePart End the use of a dynamic partition.

Synopsis KSRC KS_ClosePart (PART part)

Input

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

You should not close a dynamic memory partition if there are tasks waiting on any of the partition’s events.

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



RC_STATIC_OBJECT if the specified partition is not dynamic.

RC_OBJECT_NOT_INUSE if the specified partition does not correspond to an active dynamic partition.

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


part The handle for the partition being closed.


KS_ClosePart

June 21, 2002



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

Example 7-4. Close Memory Partition


PART dynpart;SEMA dynsema;


/* 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 254KS_UsePart, page 256


KS_DefPartName

June 21, 2002

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

Synopsis KSRC KS_DefPartName (PART part, const char *pname)

Inputs

Description The KS_DefPartName kernel service names or renames the dynamic partition specified in part. The service uses the null-terminated string pointed to by pname for the partition’s new name.

Static partitions cannot be named or renamed under program control.


This service does not check for duplicate partition names.



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.



part The handle of the partition being defined.



KS_DefPartName

June 21, 2002

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


PART dynpart;

if ((KS_DefPartName (dynpart, "NewPart")) != RC_GOOD){ ... something may be wrong. Deal with it here}


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


KS_DefPartProp

June 21, 2002

KS_DefPartProp Define the properties of a partition.

Synopsis void KS_DefPartProp (PART part, const PARTPROP *ppartprop)

Inputs

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; /* Waiting Order */ char *base; /* root of free pool list */ ksize_t size; /* number of bytes in a block */ KCOUNT count; /* initial number of blocks in partition */} PARTPROP;

You may define the following partition attribute value:


ppartprop A pointer to a Partition properties structure.

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.



KS_DefPartProp

June 21, 2002

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


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


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


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 246INIT_PartClassProp, page 250KS_OpenPart, page 254


KS_DefPartSema

June 21, 2002

KS_DefPartSema Associate a semaphore with the Partition_Not_Empty event.

Synopsis void KS_DefPartSema (PART part, SEMA sema)

Inputs

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.







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


sema The handle of the semaphore to associate with the partition.


KS_DefPartSema

June 21, 2002

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" /* RTXC Kernel Service prototypes */#include "kpart.h" /* defines PART1 and PART2 */#include "ksema.h" /* defines HAVBLK1 and HAVBLK2 */

const SEMA semalist[] ={ HAVBLK1, HAVBLK2, (SEMA)0 /* null terminated list */};SEMA cause;void *buf1, *buf2;

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 248KS_TestSema, page 106KS_TestSemaT, page 108KS_TestSemaW, page 118KS_TestSemaM, page 110KS_TestSemaMT, page 112KS_TestSemaMW, page 115


KS_FreeBlk

June 21, 2002

KS_FreeBlk Free a block of memory.

Synopsis void KS_FreeBlk (PART part, void *pblk)

Inputs

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 programmer’s responsibility to be sure the block is freed ONLY to the partition from which it was allocated. If not, a partition’s 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 system’s address space and freeing them to a given partition.


part The handle of a partition.

pblk A pointer to the block of memory to be freed.


KS_FreeBlk

June 21, 2002




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" /* RTXC Kernel Service prototypes */#include "kpart.h" /* defines BUFFBLKS */

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}

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


KS_GetFreeBlkCount

June 21, 2002

KS_GetFreeBlkCount Get the number of free blocks in a partition.

Synopsis KCOUNT KS_GetFreeBlkCount (PART part)

Input

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




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.

part The handle of the partition being queried.


KS_GetFreeBlkCount

June 21, 2002

Example 7-9. Read Memory Partition Free Block Count

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


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


KS_GetPartClassProp

June 21, 2002

KS_GetPartClassProp Get the Memory Partition object class properties

Synopsis const KCLASSPROP * KS_GetPartClassProp (int *pint)

Input

Description 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 attributes element of the Partition KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 7-1 on page 243.

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


KS_GetPartClassProp

June 21, 2002


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


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

Table 7-1. Memory Partition Class Attributes and Masks

Attribute Mask






KS_GetPartName

June 21, 2002

KS_GetPartName Get the name of a partition.

Synopsis char * KS_GetPartName (PART part)

Input

Description The KS_GetPartName kernel service obtains a pointer to the null-terminated 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 null-terminated name string.

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



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



KS_GetPartName

June 21, 2002

Example 7-11. Read Memory Partition Name


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

See Also KS_DefPartName, page 232KS_OpenPart, page 254


KS_GetPartProp

June 21, 2002

KS_GetPartProp Get the properties of a partition.

Synopsis void KS_GetPartProp (PART part, PARTPROP *ppartprop)

Inputs

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) equals 0, waiters are ordered by priority.

Output This service does not return a value. It stores the properties of the partition in the properties structure pointed to by ppartprop.




ppartprop A pointer to a Partition properties structure.


KS_GetPartProp

June 21, 2002


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


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

See Also KS_DefPartProp, page 234


KS_GetPartSema

June 21, 2002

KS_GetPartSema Get the semaphore associated with the Partition_Not_Empty event.

Synopsis SEMA KS_GetPartSema (PART part)

Input

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




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.



KS_GetPartSema

June 21, 2002

Example 7-14. Read Memory Partition Semaphore

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */#include "ksema.h" /* defines BLK256NE, OEVENT */#include "kpart.h" /* 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


INIT_PartClassProp

June 21, 2002

INIT_PartClassProp Initialize the Partition object class properties.

Synopsis KSRC INIT_PartClassProp (const KCLASSPROP *pclassprop)

Input

Description 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 attributes element of the Partition KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 7-1 on page 243.




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

pclassprop A pointer to a Partition object class properties structure.


INIT_PartClassProp

June 21, 2002

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


extern const SYSPROP sysprop;extern const KCLASSPROP partclassprop;



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


}

See Also INIT_SysProp, page 310KS_GetPartClassProp, page 242


KS_LookupPart

June 21, 2002

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

Synopsis KSRC KS_LookupPart (const char *pname, PART *ppart)

Inputs

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 partition’s 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.


RC_GOOD if the search succeeds. The service also stores the found partition’s handle in the variable pointed to by ppart.

RC_OBJECT_NOT_FOUND if the service finds no matching memory partition name.


ppart A pointer to a variable in which to store the partition handle if found.


KS_LookupPart

June 21, 2002

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


static char buf[128]; /* buffer space */

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

See Also KS_DefPartName, page 232KS_OpenPart, page 254


KS_OpenPart

June 21, 2002

KS_OpenPart Allocate and name a dynamic partition.

Synopsis KSRC KS_OpenPart (const char *pname, PART *ppart)

Inputs

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.


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




KS_OpenPart

June 21, 2002

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


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


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}

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


KS_UsePart

June 21, 2002

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

Synopsis KSRC KS_UsePart (const char *pname, PART *ppart)

Inputs

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 partition’s 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.


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


RC_GOOD if the search and registration is successful. The service also stores the matching memory partition’s 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.




KS_UsePart

June 21, 2002

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


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}

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


KS_UsePart

June 21, 2002

Chapter 8: Mutex Services 259

June 21, 2002

C H A P T E R 8 Mutex Services

In This ChapterWe 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, non-reentrant 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


KS_CloseMutx

June 21, 2002

KS_CloseMutx End the use of a dynamic mutex.

Synopsis KSRC KS_CloseMutx (MUTX mutex)

Input

Description The KS_CloseMutx kernel service ends the Current Task’s use of the specified dynamic mutex. When closing the mutex, the service detaches the caller’s 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.



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 Task’s use of the specified mutex is closed but the mutex remains open for use by other tasks.



FE_ILLEGAL_MUTX if the specified mutex ID is not valid.

mutex A handle for a mutex.


KS_CloseMutx

June 21, 2002

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


MUTX dynmutx;SEMA dynsema;


KS_CloseMutx (dynmutx); /* then close the mutex */

See Also KS_OpenMutx, page 284


KS_DefMutxName

June 21, 2002

KS_DefMutxName Define the name of a previously opened mutex.

Synopsis KSRC KS_DefMutxName (MUTX mutex, const char *pname)

Inputs

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 mutex’s new name.

Static mutexes cannot be named or renamed under program control.


This service does not check for duplicate mutex names.



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.



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

mutex The handle of the mutex being defined.



KS_DefMutxName

June 21, 2002

Example 8-2. Close Mutex


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


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


KS_DefMutxProp

June 21, 2002

KS_DefMutxProp Define the properties of a mutex.

Synopsis void KS_DefMutxProp (MUTX mutex, const MUTXPROP *pmutxprop)

Inputs

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; /* Waiting Order & Inversion */} MUTXPROP;

You may assign the following mutex attribute values:

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.

mutex The handle of the mutex being defined.

pmutxprop A pointer to a Mutex properties structure.

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.

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


KS_DefMutxProp

June 21, 2002

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

This kernel service is not intended to permit unrestricted enabling and disabling of a mutex’s 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.




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


KS_DefMutxProp

June 21, 2002

Example 8-3. Define Mutex Properties

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

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

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


KS_DefMutxSema

June 21, 2002

KS_DefMutxSema Associate a semaphore with the Mutex_Not_Busy event.

Synopsis void KS_DefMutxSema (MUTX mutex, SEMA sema)

Inputs

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.




FE_UNINITIALIZED_MUTX if the specified mutex has not yet been initialized.



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

sema The handle of the semaphore being associated with the mutex.


KS_DefMutxSema

June 21, 2002

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" /* RTXC Kernel Service prototypes */#include "kmutx.h" /* defines HPMUTX and LPMUTX */#include "ksema.h" /* defines GOTHP and GOTLP */

SEMA sema;

const SEMA semalist[] ={ GOTHP, GOTLP, (SEMA)0 /* list must be null terminated */};

KS_DefMutxSema (HPMUTX, GOTHP); /* define semas for */KS_DefMutxSema (LPMUTX, GOTLP); /* both mutexes */

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


KS_DefMutxSema

June 21, 2002

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

See Also KS_GetMutxSema, page 278KS_TestMutx, page 288KS_ReleaseMutx, page 286KS_TestSema, page 106KS_TestSemaT, page 108KS_TestSemaW, page 118KS_TestSemaM, page 110KS_TestSemaMW, page 115KS_TestSemaMT, page 112


KS_GetMutxClassProp

June 21, 2002

KS_GetMutxClassProp Get the Mutex object class properties.

Synopsis const KCLASSPROP * KS_GetMutxClassProp (int *pint)

Input

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


The attributes element of the Mutex KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 8-1 on page 271.


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

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


KS_GetMutxClassProp

June 21, 2002

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


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

Table 8-1. Mutex Class Attributes and Masks

Attribute Mask




Inversion ATTR_INVERSION



KS_GetMutxName

June 21, 2002

KS_GetMutxName Get the name of a mutex.

Synopsis char * KS_GetMutxName (MUTX mutex)

Input

Description The KS_GetMutxName kernel service obtains a pointer to the null-terminated 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 null-terminated name string.

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



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

mutex The handle of the mutex being queried.


KS_GetMutxName

June 21, 2002

Example 8-6. Read Mutex Name



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

See Also KS_DefMutxName, page 262KS_OpenMutx, page 284


KS_GetMutxOwner

June 21, 2002

KS_GetMutxOwner Get the owner of a mutex.

Synopsis TASK KS_GetMutxOwner (MUTX mutex, KCOUNT *pcount)

Inputs

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.

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




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.


pcount A pointer to a variable in which to store the current nesting level of mutex locking.


KS_GetMutxOwner

June 21, 2002

Example 8-7. Read Mutex Owner

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */#include "kmutx.h" /* defines PRINTER */#include "ktask.h" /* 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 288KS_TestMutxT, page 290KS_TestMutxW, page 294


KS_GetMutxProp

June 21, 2002

KS_GetMutxProp Get the properties of a mutex.

Synopsis void KS_GetMutxProp (MUTX mutex, MUTXPROP *pmutxprop)

Inputs

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; /* Waiting Order & Inversion */} MUTXPROP;

The value returned for attributes describes:



pmutxprop A pointer to a Mutex properties structure.

Waiting Order Indicates the ordering of tasks waiting for acquisition of the mutex.


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.


KS_GetMutxProp

June 21, 2002




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


MUTX dynmutx;MUTXPROP mprop; /* 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


KS_GetMutxSema

June 21, 2002

KS_GetMutxSema Get the semaphore handle associated with the Mutex_Not_Busy event.

Synopsis SEMA KS_GetMutxSema (MUTX mutex)

Input

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




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



KS_GetMutxSema

June 21, 2002

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" /* RTXC Kernel Service prototypes */#include "ksema.h" /* defines MTXSEMA1, MTXSEMA2 */#include "kmutx.h" /* 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


INIT_MutxClassProp

June 21, 2002

INIT_MutxClassProp Initialize the Mutex object class properties.

Synopsis KSRC INIT_MutxClassProp (const KCLASSPROP *pclassprop)

Input

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


The attributes element of the Mutex KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 8-1 on page 271.




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.

pclassprop A pointer to a Mutex object class properties structure.


INIT_MutxClassProp

June 21, 2002

Example 8-10. Initialize Mutex Object Class


extern const SYSPROP sysprop;extern const KCLASSPROP mutxclassprop;

KSRC userinit (void){ KSRC ksrc;

/* initialize the kernel workspace and allocate RAM */ /* for required classes, etc. */


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


}

See Also INIT_SysProp, page 310KS_GetMutxClassProp, page 270


KS_LookupMutx

June 21, 2002

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

Synopsis KSRC KS_LookupMutx (const char *pname, MUTX *pmutex)

Inputs

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 mutex’s 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.


RC_GOOD if the search succeeds. The service also stores the matching mutex’s 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


pmutex A pointer to a variable in which to store the mutex handle.


KS_LookupMutx

June 21, 2002

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


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

}

See Also KS_DefMutxName, page 262KS_OpenMutx, page 284


KS_OpenMutx

June 21, 2002

KS_OpenMutx Allocate and name a dynamic mutex.

Synopsis KSRC KS_OpenMutx (const char *pname, MUTX *pmutex)

Inputs

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.


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




KS_OpenMutx

June 21, 2002

fixed. You can define the mutex name at a later time with a call to the KS_DefMutxName service.


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



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

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


KS_ReleaseMutx

June 21, 2002

KS_ReleaseMutx Release ownership of a mutex.

Synopsis KSRC KS_ReleaseMutx (MUTX mutex)

Inputs

Description 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 un-nesting, the owning task must issue the same number of releases as there are locks in the nest.


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.

mutex The handle of the mutex being released.


KS_ReleaseMutx

June 21, 2002

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.




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" /* RTXC Kernel Service prototypes */#include "kmutx.h" /* defines DATABASE */

/* grab resource by locking mutex */KS_TestMutxW (DATABASE);

... update shared database

/* release mutex */KS_ReleaseMutx (DATABASE);

...continue

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


KS_TestMutx

June 21, 2002

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

Synopsis TASK KS_TestMutx (MUTX mutex)

Input

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




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.

mutex The handle of the mutex being tested.


KS_TestMutx

June 21, 2002

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" /* RTXC Kernel Service prototypes */#include "kmutx.h" /* 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 290KS_TestMutxW, page 294KS_ReleaseMutx, page 286


KS_TestMutxT

June 21, 2002

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 TASK KS_TestMutxT (MUTX mutex, COUNTER counter, TICKS ticks)

Inputs

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


Output This service returns a TASK type value as follows:


pcount A pointer to a variable in which to store the nesting level of the mutex.


ticks The number of ticks on the specified counter to wait for the mutex to become available.


KS_TestMutxT

June 21, 2002

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.






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.


KS_TestMutxT

June 21, 2002

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

#include "rtxcapi.h" /* RTXC Kernel Service prototypes */#include "kmutx.h" /* defines PRINTER */#include "kcounter.h" /* 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 288KS_TestMutxW, page 294KS_ReleaseMutx, page 286


KS_TestMutxT

June 21, 2002


KS_TestMutxW

June 21, 2002

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

Synopsis void KS_TestMutxW (MUTX mutex)

Input

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





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.



KS_TestMutxW

June 21, 2002

If the printer is busy, the task does not proceed; instead, it waits unconditionally for the printer to become available.

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

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

KS_TestMutxW (PRINTER);

...PRINTER mutex is now owned by Current Task. Use it.

/* free PRINTER mutex */KS_ReleaseMutx (PRINTER);

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


KS_UseMutx

June 21, 2002

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

Synopsis KSRC KS_UseMutx (const char *pname, MUTX *pmutex)

Inputs

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 mutex’s 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.


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


RC_GOOD if the search is successful. The service also stores the matching mutex’s 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.




KS_UseMutx

June 21, 2002

Example 8-17. Read Mutex Handle and Register It



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

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


KS_UseMutx

June 21, 2002

Chapter 9: Special Services 299

June 21, 2002

C H A P T E R 9 Special Services

In This ChapterWe 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


XX_AllocSysRAM

June 21, 2002

XX_AllocSysRAM Allocate a block of system RAM.

Zones TS_AllocSysRAM KS_AllocSysRAM

Synopsis void * XX_AllocSysRAM (ksize_t blksize)

Input

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

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


XX_AllocSysRAM

June 21, 2002

Example 9-1. Allocate System RAM from Zone 3


void *p;

if ((p = KS_AllocSysRAM (256)) == (void *)0){ ... Deal with no memory available}else{ ... Allocation was successful}


XX_DefFatalErrorHandler

June 21, 2002

XX_DefFatalErrorHandler Establish the system error function.

Zones TS_DefFatalErrorHandler KS_DefFatalErrorHandler

Synopsis void XX_DefFatalErrorHandler (int (*errfunc) (void *))

Input

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


Example 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 task’s 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).

errfunc The entry address for the error function.


XX_DefFatalErrorHandler

June 21, 2002

Example 9-2. Define Fatal Error Function


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


XX_GetFreeSysRAMSize

June 21, 2002

XX_GetFreeSysRAMSize Get the size of free system RAM.

Zones TS_GetFreeSysRAMSize KS_GetFreeSysRAMSize

Synopsis ksize_t XX_GetFreeSysRAMSize (void)


Description The XX_GetFreeSysRAMSize kernel service determines the amount of free system RAM that is available to the user.

Output The service returns the number of remaining free bytes of system RAM.

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

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}

See Also XX_AllocSysRAM, page 300


XX_GetFatalErrorHandler

June 21, 2002

XX_GetFatalErrorHandler Get the system error function.

Zones TS_GetFatalErrorHandler KS_GetFatalErrorHandler

Synopsis int (*)(void *)) XX_GetFatalErrorHandler (void)


Description The XX_GetFatalErrorHandler kernel service returns a pointer to the function registered to handle fatal system conditions by a previous XX_DefFatalErrorHandler call.

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

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


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


KS_GetSysProp

June 21, 2002

KS_GetSysProp Get the system properties.

Synopsis const SYSPROP * KS_GetSysProp (void)


Description 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; /* system attributes */ unsigned long version; /* kernel version number */ char *sysrambase; /* base address of system RAM */ ksize_t sysramsize; /* size (bytes) of system RAM */ char *kernelstackbase; /* base address of kernel stack */ ksize_t kernelstacksize; /* size (bytes) of kernel stack */ unsigned long reserve1; /* reserved */ unsigned long reserve2; /* reserved */} SYSPROP;

Output The function always returns a pointer to a SYSPROP structure.

Example Example 9-5 on page 307 reads the clock rate that was established when the system was initialized and sends it to the console.


KS_GetSysProp

June 21, 2002

Example 9-5. Read System Properties


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

putline (buf);

... continue

See Also INIT_SysProp, page 310


KS_GetVersion

June 21, 2002

KS_GetVersion Get the version number of the Kernel.

Synopsis unsigned long KS_GetVersion (void)


Description The KS_GetVersion kernel service returns the version number of the RTXC Kernel.

Output The function returns a value that contains the version number formatted as follows:

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

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

Bits 31–16 System Use

Bits 15–08 Version number (hexadecimal)

Bits 07–00 Release number (hexadecimal)


KS_GetVersion

June 21, 2002

Example 9-6. Read Version Number


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


INIT_SysProp

June 21, 2002

INIT_SysPropInitialize the RTXC system properties.

Synopsis KSRC INIT_SysProp (const SYSPROP *psysprop)

Input

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

typedef struct{ KATTR attributes; /* system attributes */ unsigned long version; /* kernel version number */ char *sysrambase; /* base address of system RAM */ ksize_t sysramsize; /* size (bytes) of system RAM */ char *kernelstackbase; /* base address of kernel stack */ ksize_t kernelstacksize; /* size (bytes) of kernel stack */ unsigned long reserve1; /* reserved */ unsigned long reserve2; /* reserved */} SYSPROP;

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.

psysprop A pointer to a SYSPROP structure.


INIT_SysProp

June 21, 2002

Output The service returns a KSRC value as follows:


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.

Table 9-1. System Attributes and Masks

Attribute Mask

Tasks K_ATTR_TASKS

Threads K_ATTR_THREADS

Semaphores K_ATTR_SEMAPHORES

Queues K_ATTR_QUEUES

Mailboxes K_ATTR_MAILBOXES

Partitions K_ATTR_PARTITIONS

Pipes K_ATTR_PIPES

Mutexes K_ATTR_MUTEXES

Event Sources K_ATTR_SOURCES

Counters K_ATTR_COUNTERS

Alarms K_ATTR_ALARMS

Exceptions K_ATTR_EXCEPTIONS


INIT_SysProp

June 21, 2002

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


}

See Also KS_GetSysProp, page 306


KS_Nop

June 21, 2002

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

Synopsis void KS_Nop (void)


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


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

Example 9-8. Execute No-Operation Service



int i;TICKS timestamp, et; /* sleep for one tick to sync with clock */KS_SleepTask (TIMEBASE, 1);KS_ElapsedCounterTicks (TIMEBASE, &timestamp); /* initialize timestamp */for (i = 0; i < 10000; i++) KS_Nop ();

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


KS_UserService

June 21, 2002

KS_UserService Perform a user-defined kernel service.

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

Inputs

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 The KS_UserService function returns the value of the specified function as its own function value.

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

func A pointer to a function.

parg A pointer to an arbitrary structure.


KS_UserService

June 21, 2002

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


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


KS_UserService

June 21, 2002

Appendix A: Fatal Error Codes 317

June 21, 2002

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

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

FFE_ILLEGAL_COUNTER

The specified counter ID is not valid.KS_AllocBlkT 227KS_GetQueueDataT 139KS_PutQueueDataT 159KS_ReceiveMsgT 203KS_SendMsgT 210KS_TestAckT 219KS_TestMutxT 291KS_TestSemaMT 113KS_TestSemaT 109

FE_ILLEGAL_MBOXThe specified mailbox ID is not valid.KS_CloseMbox 167KS_DefMboxName 168KS_DefMboxProp 170KS_DefMboxSema 172KS_ForwardMsg 197KS_GetMboxName 178KS_GetMboxProp 180KS_GetMboxSema 182KS_ReceiveMsg 200KS_ReceiveMsgT 203KS_ReceiveMsgW 204KS_SendMsg 207KS_SendMsgT 210KS_SendMsgW 214

FE_ILLEGAL_MUTXThe specified mutex ID is not valid.KS_CloseMutx 260KS_DefMutxName 262KS_DefMutxProp 265KS_DefMutxSema 267KS_GetMutxName 272KS_GetMutxOwner 274KS_GetMutxProp 277KS_GetMutxSema 278KS_ReleaseMutx 287KS_TestMutx 288KS_TestMutxT 291KS_TestMutxW 294

FE_ILLEGAL_PARTThe specified partition ID is not valid.KS_AllocBlk 224KS_AllocBlkT 226KS_AllocBlkW 228KS_ClosePart 231KS_DefPartName 232KS_DefPartProp 235KS_DefPartSema 236KS_FreeBlk 239KS_GetFreeBlkCount 240KS_GetPartName 244KS_GetPartProp 246KS_GetPartSema 248

FE_ILLEGAL_PRIORITYThe specified priority value is out of range.


June 21, 2002

KS_DefTaskPriority 33KS_DefTaskProp 34

FE_ILLEGAL_QUEUEThe specified queue ID is not valid.KS_CloseQueue 125KS_DefQueueName 126KS_DefQueueProp 129KS_DefQueueSema 130KS_GetQueueData 136KS_GetQueueDataT 139KS_GetQueueDataW 140KS_GetQueueName 142KS_GetQueueProp 144KS_GetQueueSema 146KS_PutQueueData 156KS_PutQueueDataT 159KS_PutQueueDataW 160

FE_ILLEGAL_SEMAThe specified semaphore ID is not valid.KS_CloseSema 81KS_DefMboxSema 172KS_DefMutxSema 267KS_DefPartSema 236KS_DefQueueSema 131KS_DefSemaCount 82KS_DefSemaName 84KS_DefSemaProp 87KS_DefTaskSema 36KS_GetSemaCount 90KS_GetSemaName 92KS_GetSemaProp 94KS_TestSema 106KS_TestSemaM 110KS_TestSemaMT 113KS_TestSemaMW 116KS_TestSemaT 109KS_TestSemaW 118XX_SignalSema 102XX_SignalSemaM 104

FE_ILLEGAL_TASKThe specified task ID is not valid.KS_AbortTask 24KS_CloseTask 25KS_DefTaskEnvArg 27KS_DefTaskName 30KS_DefTaskPriority 32KS_DefTaskProp 34KS_DefTaskSema 36KS_DefTickSlice 38KS_ExecuteTask 42KS_GetTaskEnvArg 44KS_GetTaskName 51KS_GetTaskPriority 53KS_GetTaskProp 54KS_GetTaskSema 56KS_GetTaskState 58KS_GetTickSlice 60KS_SuspendTask 71KS_TerminateTask 72XX_ResumeTask 68

FE_INVALID_MSG_PRIORITYThe specified message priority value is not either URGENT or NORMAL.KS_ForwardMsg 197KS_SendMsg 207KS_SendMsgT 211KS_SendMsgW 214

FE_INVALID_QEVENTThe specified queue event value is not either QNF or QNE.KS_DefQueueSema 131KS_GetQueueSema 146

FE_NULL_DESTBUFFERThe pointer to the destination buffer is null.KS_GetQueueData 136KS_GetQueueDataT 139KS_GetQueueDataW 140

Appendix A: Fatal Error Codes 319

June 21, 2002

FE_NULL_MSGENVThe pointer to the message envelope is null.KS_AckMsg 194KS_ForwardMsg 197KS_SendMsg 207KS_SendMsgT 211KS_SendMsgW 214KS_TestAck 216KS_TestAckT 219KS_TestAckW 220

FE_NULL_PARTBASEThe specified partition base address is null.KS_DefPartProp 235

FE_NULL_PARTBLKPTRThe pointer to the block of memory is null.KS_FreeBlk 239

FE_NULL_QUEUEBASEThe specified queue base address is null.KS_DefQueueProp 129

FE_NULL_SOURCEBUFFERThe pointer to the source buffer is null.KS_PutQueueData 156KS_PutQueueDataT 159KS_PutQueueDataW 160

FE_NULL_STACKBASEThe specified Task stack base address is null.KS_DefTaskProp 35

FE_NULL_TASKENTRYThe specified Task entry address is null.KS_DefTaskProp 35

FE_UNINITIALIZED_COUNTERKS_AllocBlkT 227KS_GetQueueDataT 139KS_PutQueueDataT 159KS_ReceiveMsgT 203

KS_SendMsgT 211KS_TestAckT 219KS_TestMutxT 291KS_TestSemaMT 113KS_TestSemaT 109

FE_UNINITIALIZED_MBOXThe specified mailbox has not yet been initialized.KS_DefMboxSema 172KS_ForwardMsg 197KS_GetMboxProp 180KS_GetMboxSema 182KS_ReceiveMsg 200KS_ReceiveMsgT 203KS_ReceiveMsgW 204KS_SendMsg 207KS_SendMsgT 210KS_SendMsgW 214

FE_UNINITIALIZED_MUTXThe specified mutex has not yet been initialized.KS_DefMutxSema 267KS_GetMutxOwner 274KS_GetMutxProp 277KS_GetMutxSema 278KS_ReleaseMutx 287KS_TestMutx 288KS_TestMutxT 291KS_TestMutxW 294

FE_UNINITIALIZED_PARTThe specified partition has not yet been initialized.KS_AllocBlk 224KS_AllocBlkT 227KS_AllocBlkW 228KS_DefPartSema 236KS_FreeBlk 239KS_GetFreeBlkCount 240KS_GetPartProp 247


June 21, 2002

KS_GetPartSema 248FE_UNINITIALIZED_QUEUE

The specified queue has not yet been initialized.KS_DefQueueProp 129KS_DefQueueSema 131KS_GetQueueData 136KS_GetQueueDataT 139KS_GetQueueDataW 140KS_GetQueueProp 144KS_GetQueueSema 146KS_PutQueueData 156KS_PutQueueDataT 159KS_PutQueueDataW 160

FE_UNINITIALIZED_SEMAThe specified semaphore has not yet been initialized.KS_DefMboxSema 172KS_DefMutxSema 267KS_DefPartSema 236KS_DefQueueSema 131KS_DefSemaCount 82KS_GetSemaCount 90KS_GetSemaProp 94KS_TestSema 106KS_TestSemaM 110KS_TestSemaMT 113KS_TestSemaMW 116KS_TestSemaT 109KS_TestSemaW 118XX_SignalSema 102XX_SignalSemaM 104

FE_UNINITIALIZED_TASKThe specified task has not yet been initialized.KS_AbortTask 24KS_DefTaskEnvArg 27KS_DefTaskPriority 32KS_DefTaskSema 36

KS_DefTickSlice 39KS_ExecuteTask 42KS_GetTaskEnvArg 44KS_GetTaskPriority 53KS_GetTaskProp 54KS_GetTaskSema 56KS_GetTaskState 58KS_GetTickSlice 60KS_SuspendTask 71KS_TerminateTask 72XX_ResumeTask 68

FE_ZERO_PARTCOUNTThe specified partition block count is zero.KS_DefPartProp 235

FE_ZERO_PARTSIZEThe specified partition size is zero.KS_DefPartProp 235

FE_ZERO_QUEUEDEPTHThe specified queue depth is zero.KS_DefQueueProp 129

FE_ZERO_QUEUEWIDTHThe specified queue width is zero.KS_DefQueueProp 129

FE_ZERO_STACKSIZEThe specified task stack size is zero.KS_DefTaskProp 35

Index 321

June 21, 2002

Index

Aabortion, task semaphore 56acknowledging message 194allocating

mailbox 188memory block 224, 226, 228memory partition 254mutex 284queue 152semaphore 100task 66

allowing context switching 41attribute value

Signal Type 86Waiting Order 86

CC compiler syntactical differences 3classes, kernel service 7closing

mailbox 166memory partition 230mutex 260queue 124semaphore 80task 25

code examplesAbort Task and Terminate 24

Acknowledge Message 195Allocate and Free Memory Block 239Allocate and Initialize Queue 154Allocate and Name Memory Partition

255Allocate and Name Mutex 285Allocate Block of Memory 225Allocate Block of Memory—Wait If

Necessary 229Allocate Block of Memory—Wait

Number of Ticks If Necessary 227Allocate Dynamic Semaphore 101Allocate Dynamic Task 67Allocate Mailbox 189Allocate System RAM from Zone 3 301Assign Mailbox Name 169Assign Memory Partition Name 233Assign Queue Name 127Assign Semaphore Name 85Associate Queue Event with Semaphore

132Associate Semaphore With Memory

Partition 237Associate Semaphore with Mutex 268Class Properties Structure 88Close Mailbox 167Close Memory Partition 231Close Mutex 261, 263


June 21, 2002

Close Queue 125Close Semaphore 81Close Task When Signaled 26Define Fatal Error Function 303Define Mailbox Properties 171Define Mailbox Semaphore 174Define Memory Partition Properties 235Define Mutex Properties 266Define Queue Object Class Properties

129Define Task Name 31Define Task Object Class Properties 35Define Task Priorities 33Define Task Properties 28Define Task Termination Semaphore 37Define Tick Slice 39Disable Task Scheduler 40Enable Task Scheduler 41Execute Non-RTXC Function as Kernel

Service 315Execute No-Operation Service 313Execute Task 43Forward Message 198Initialize Kernel Properties 312Initialize Mailbox Object Class 185Initialize Memory Partition Object Class

251Initialize Mutex Object Class

mutexcode examples

Initialize Mutex ObjectClass 281

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

Look Up Queue by Name 151Look Up Semaphore by Name 99Look Up Task by Name 65Mailbox Properties Structure 170Memory Partition Properties Structure

246Object Class Properties Structure 62Put Current Task to Sleep 70Put Data Into Queue 157Put Data Into Queue—Wait Number of

Ticks If Queue is Full 159Put Data Into Queue—Wait Until

Queue Has Room 161Queue Properties Structure 128Read Amount of Available System RAM

from Zone 3 304Read and Change Task Priority 53Read Current Task Task Number 50Read Dynamic Queue Name 143Read Dynamic Task Name 52Read Fatal Error Function 305Read Mailbox Handle and Register It

192Read Mailbox Name 179Read Mailbox Object Class Properties

177Read Mailbox Properties 181Read Mailbox Semaphore 183Read Memory Partition Free Block

Count 241Read Memory Partition Handle and

Register It 257Read Memory Partition Name 245Read Memory Partition Object Class

Properties 243Read Memory Partition Properties 247Read Memory Partition Semaphore 249

Index 323

June 21, 2002

Read Mutex Handle and Register It 297Read Mutex Name 273Read Mutex Object Class Properties 271Read Mutex Owner 275Read Mutex Properties 277Read Mutex Semaphore 279Read Queue Entry 137Read Queue Entry—Wait If Necessary

141Read Queue Entry—Wait Number of

Ticks If Necessary 139Read Queue Handle and Register It 163Read Queue Object Class Properties 135Read Queue Properties 145Read Queue Semaphore 147Read Semaphore Count 91Read Semaphore Handle and Register It

121Read Semaphore Name 93Read Semaphore Object Class

Properties 89Read Semaphore Properties 95Read System Properties 307Read Task Environment Arguments 46Read Task Handle and Register It 75Read Task Object Class Properties 49Read Task State 59Read Task Termination Semaphore 57Read Task Tick-Slice Quantum 60Read Version Number 309Receive Message—Wait If Necessary

205Receive Message—Wait Number of

Ticks If Necessary 203Receive Next Message from a Mailbox

201Release Mutex 287

Resume Suspended Task from Zone 3 69

Semaphore Properties structure 86Send Message—Wait for

Acknowledgement 208, 214Send Message—Wait Number of Ticks

for Acknowledgement 212Set Semaphore Count 83Signal List of Semaphores from Zone 3

105Signal Semaphore from Zone 3 103Specify Semaphore Waiting Order 87Suspend Task 71Task Properties Structure 34Terminate Task 73Terminate Task and Release Its Stack 55Test for Acknowledgement and Wait if

Necessary 221Test for Message Acknowledgement 217Test for Message Acknowledgement—

Wait Number of Ticks for Acknowledgement 219

Test List of Semaphores 111Test List of Semaphores—Wait for

Signal 117Test List of Semaphores—Wait Number

of Ticks for Signal 114Test Mutex for Ownership by Current

Task 289Test Mutex—Wait If Not Available 295Test Mutex—Wait Number of Ticks If

Not Available 292Test Semaphore 107Test Semaphore—Wait for Signal 119Test Semaphore—Wait Number of

Ticks for Signal 109Yield to Another Task 77


June 21, 2002

context switchingallowing 41preventing 40

count, reading semaphore 90Current Task

in examples 3Current Thread

in examples 3

Ddefining

mailbox properties 170memory partition object class properties

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

Eenvironment arguments 44environment arguments structure 27, 44error function, system 302events

Mailbox_Not_Empty 172, 182Mutex_Not_Busy 267, 278Partition_Not_Empty 236, 248Queue_Not_Empty 130, 146Queue_Not_Full 130, 146

task abortion 36task termination 36

examples, list of xi

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

Hhandle

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

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

KKCLASSPROP structure

mailbox 176, 184memory partition 242, 250

Index 325

June 21, 2002

mutex 270, 280queue 134, 148semaphore 88, 96task 47, 62

kernel componentRTXC/ms 8

kernel servicearguments 5classes 7description format 2function call general form 4function prototypes 2INIT_MboxClassProp 184INIT_MutxClassProp 280INIT_PartClassProp 250INIT_QueueClassProp 148INIT_SemaClassProp 96INIT_SysProp 310INIT_TaskClassProp 62KS_AbortTask 23KS_AckMsg 194KS_AllocBlkT 226KS_AllocBlkW 228KS_CloseMbox 166KS_CloseMutx 260KS_ClosePart 230KS_CloseQueue 124KS_CloseSema 80KS_CloseTask 25KS_DefMboxName 168KS_DefMboxProp 170KS_DefMboxSema 172KS_DefMutxName 262KS_DefMutxProp 264KS_DefMutxSema 267KS_DefPartName 232KS_DefPartProp 234

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


June 21, 2002

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

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

Index 327

June 21, 2002

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

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


June 21, 2002

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

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

Llist of examples xilist of tables ix

Mmailbox

allocating 188closing 166code examples

Allocate Mailbox 189Assign Mailbox Name 169Close Mailbox 167Define Mailbox Properties 171Define Mailbox Semaphore 174Initialize Mailbox Object Class 185Look Up Mailbox by Name 187Read Mailbox Handle and Register It

192Read Mailbox Name 179Read Mailbox Object Class Properties

177

Index 329

June 21, 2002

Read Mailbox Properties 181Read Mailbox Semaphore 183

defining properties 170handle 186KCLASSPROP structure 176, 184Mailbox_Not_Empty event 172, 182MBOXPROP structure 170, 180name 178naming 168, 188object class properties 184properties 180reading object class properties 176registering 191services summary table 14

Mailbox servicesbrief description 14KS_CloseMbox 166KS_DefMboxName 168KS_DefMboxProp 170KS_DefMboxSema 172KS_GetMboxClassProp 176KS_GetMboxName 178KS_GetMboxProp 180KS_GetMboxSema 182INIT_MboxClassProp 184KS_LookupMbox 186KS_OpenMbox 188KS_UseMbox 191

Mailbox_Not_Empty event 172, 182MBOXPROP structure 170, 180memory block

allocating 224, 226, 228freeing 238obtaining number of 240

memory partitionallocating 254closing 230code examples

Allocate and Free Memory Block 239Allocate and Name Memory Partition

255Allocate Block of Memory 225Allocate Block of Memory—Wait If

Necessary 229Allocate Block of Memory—Wait

Number of Ticks If Necessary 227Assign Memory Partition Name 233Associate Semaphore With Memory

Partition 237Close Memory Partition 231Define Memory Partition Properties

235Initialize Memory Partition Object

Class 251Look Up Memory Partition by Name

253Read Memory Partition Free Block

Count 241Read Memory Partition Handle and

Register It 257Read Memory Partition Name 245Read Memory Partition Object Class

Properties 243Read Memory Partition Properties

247Read Memory Partition Semaphore

249defining object class properties 250defining properties 234handle 252KCLASSPROP structure 242, 250name 244, 252naming 232, 254obtaining number of free blocks 240Partition_Not_Empty event 236, 248PARTPROP structure 234, 246properties 246reading object class properties 242


June 21, 2002

registering 256services summary table 16

Memory Partition servicesbrief description 16XX_AllocBlk 224KS_AllocBlkT 226KS_AllocBlkW 228KS_ClosePart 230KS_DefPartName 232KS_DefPartProp 234KS_DefPartSema 236KS_FreeBlk 238KS_GetFreeBlkCount 240KS_GetPartClassProp 242KS_GetPartName 244KS_GetPartProp 246KS_GetPartSema 248INIT_PartClassProp 250KS_LookupPart 252KS_OpenPart 254KS_UsePart 256

messageacknowledging 194code examples

Acknowledge Message 195Forward Message 198Receive Message—Wait If Necessary

205Receive Message—Wait Number of

Ticks If Necessary 203Receive Next Message from a Mailbox

201Send Message—Wait for Acknowl-

edgement 208, 214Send Message—Wait Number of

Ticks for Acknowledgement 212Test for Acknowledgement and Wait

if Necessary 221

Test for Message Acknowledgement217

Test for Message Acknowledge-ment—Wait Number of Ticks forAcknowledgement 219

receiving 200, 202, 204sending 206, 209, 213services summary table 15testing for acknowledgment 216, 218,

220Message services

brief description 15KS_AckMsg 194KS_ForwardMsg 196KS_ReceiveMsg 200KS_ReceiveMsgT 202KS_ReceiveMsgW 204KS_SendMsg 206KS_SendMsgT 209KS_SendMsgW 213KS_TestAck 216KS_TestAckT 218KS_TestAckW 220

mutexallocating 284closing 260code examples

Allocate and Name Mutex 285Associate Semaphore with Mutex 268Close Mutex 261, 263Define Mutex Properties 266Look Up Mutex by Name 283Read Mutex Handle and Register It

297Read Mutex Name 273Read Mutex Object Class Properties

271Read Mutex Owner 275Read Mutex Properties 277

Index 331

June 21, 2002

Read Mutex Semaphore 279Release Mutex 287Test Mutex for Ownership by Current

Task 289Test Mutex—Wait If Not Available

295Test Mutex—Wait Number of Ticks If

Not Available 292defining object class properties 280defining properties 264handle 282KCLASSPROP structure 270, 280Mutex_Not_Busy event 267, 278MUTXPROP structure 264, 276name 272, 282naming 262, 284owner 274properties 276reading object class properties 270registering 296releasing 286services summary table 18testing availability 288, 290, 294

Mutex servicesbrief description 18KS_CloseMutx 260KS_DefMutxName 262KS_DefMutxProp 264KS_DefMutxSema 267KS_GetMutxClassProp 270KS_GetMutxName 272KS_GetMutxOwner 274KS_GetMutxProp 276KS_GetMutxSema 278INIT_MutxClassProp 280KS_LookupMutx 282KS_OpenMutx 284KS_ReleaseMutx 286

KS_TestMutx 288KS_TestMutxT 290KS_TestMutxW 294KS_UseMutx 296

Mutex_Not_Busy event 267, 278MUTXPROP structure 264, 276

Nname

mailbox 178memory partition 244, 252mutex 272, 282queue 142, 150reading semaphore 92task 51, 64

namingmailbox 168, 188memory partition 232, 254mutex 262, 284queue 126, 152semaphore 84, 100task 30, 66

no operation function 313

Oobject class properties

mailbox 176, 184memory partition 242, 250mutex 270, 280queue 134, 148semaphore 88, 96task 47, 62

owner of mutex 274

PPartition services. See Memory Partition

services


June 21, 2002

Partition_Not_Empty event 236, 248PARTPROP structure 234, 246preventing context switching 40priority level, task 53properties

mailbox 170, 180mailbox object class 176, 184memory partition 246memory partition object class 242, 250mutex 264, 276mutex object class 270, 280queue 128, 144queue object class 134semaphore 86, 94semaphore object class 88, 96system 306task 54task object class 47

Qqueue


Allocate and Initialize Queue 154Assign Queue Name 127Associate Queue Event with Sema-

phore 132Close Queue 125Define Queue Object Class Properties

129Initialize Queue Object Class 149Look Up Queue by Name 151Put Data Into Queue 157Put Data Into Queue—Wait Number

of Ticks If Queue is Full 159Put Data Into Queue—Wait Until

Queue Has Room 161

Read Dynamic Queue Name 143Read Queue Entry 137Read Queue Entry—Wait If Neces-

sary 141Read Queue Entry—Wait Number of

Ticks If Necessary 139Read Queue Handle and Register It

163Read Queue Object Class Properties

135Read Queue Properties 145Read Queue Semaphore 147

defining object class properties 148defining properties 128handle 150inserting entry 158, 160insertring entry 156KCLASSPROP structure 134, 148name 142, 150naming 126, 152obtaining next entry 136, 138, 140properties 144Queue_Not_Empty event 130, 146Queue_Not_Full event 130, 146QUEUEPROP structure 128, 144reading object class properties 134registering 162services summary table 12

Queue servicesbrief description 12KS_CloseQueue 124KS_DefQueueName 126KS_DefQueueProp 128KS_DefQueueSema 130KS_GetQueueClassProp 134KS_GetQueueData 136KS_GetQueueDataT 138KS_GetQueueDataW 140

Index 333

June 21, 2002

KS_GetQueueName 142KS_GetQueueProp 144KS_GetQueueSema 146INIT_QueueClassProp 148KS_LookupQueue 150KS_OpenQueue 152KS_PutQueueData 156KS_PutQueueDataT 158KS_PutQueueDataW 160KS_UseQueue 162

Queue_Not_Empty event 130, 146Queue_Not_Full event 130, 146QUEUEPROP structure 128, 144

RRAM

free 304obtaining size of free 304

readingmailbox object class properties 176memory partition object class properties

242mutex object class properties 270queue object class 134semaphore count 90semaphore name 92semaphore object class properties 88, 96semaphore properties 94task handle 50, 64task name 51task object class properties 47task priority level 53task properties 54task state 58task time-slice quantum 60

receiving message 200, 202, 204registering

mailbox 191memory partition 256mutex 296queue 162semaphore 120task 74

releasing mutex 286restarting task 23resuming task 68RTOS Software Development Kit 2RTXC/ms component 8rtxcapi.h file 2RTXCDSP Kernel version number 308

Sscheduler

disabling 40enabling 41

SDK. See RTOS Software Development KitSELFTASK 3SELFTHREAD 3semaphore


Allocate Dynamic Semaphore 101Assign Semaphore Name 85Close Semaphore 81Initialize Semaphore Object Class 97Look Up Semaphore by Name 99Read Semaphore Count 91Read Semaphore Handle and Regis-

ter It 121Read Semaphore Name 93Read Semaphore Object Class Proper-

ties 89Read Semaphore Properties 95Set Semaphore Count 83


June 21, 2002

Signal List of Semaphores from Zone3 105

Signal Semaphore from Zone 3 103Specify Semaphore Waiting Order 87Test List of Semaphores 111Test List of Semaphores—Wait for

Signal 117Test List of Semaphores—Wait Num-

ber of Ticks for Signal 114Test Semaphore 107Test Semaphore—Wait for Signal 119Test Semaphore—Wait Number of

Ticks for Signal 109defining count 82defining properties 86handle 98KCLASSPROP structure 88, 96naming 84, 100reading count 90reading name 92reading object class properties 88, 96reading properties 94registering 120SEMAPROP structure 86services summary table 10Signal Type attribute value 86signaling 102, 104testing 106, 110testing and waiting 108, 112, 118testing list and waiting 115Waiting Order attribute value 86

Semaphore servicesbrief description 10KS_CloseSema 80KS_DefSemaCount 82KS_DefSemaName 84KS_DefSemaProp 86KS_GetSemaClassProp 88

KS_GetSemaCount 90KS_GetSemaName 92KS_GetSemaProp 94INIT_SemaClassProp 96KS_LookupSema 98KS_OpenSema 100KS_TestSemaMT 112XX_SignalSema 102XX_SignalSemaM 104KS_TestSema 106KS_TestSemaM 110KS_TestSemaMW 115KS_TestSemaT 108KS_TestSemaW 118KS_UseSema 120

SEMAPROP structure 86sending message 206, 209, 213service prefix 4Signal Type attribute value, semaphore 86signaling semaphores 102, 104special service

code examplesAllocate System RAM from Zone 3

301Define Fatal Error Function 303Disable Task Scheduler 40Enable Task Scheduler 41Execute Non-RTXC Function as Ker-

nel Service 315Execute No-Operation Service 313Initialize Kernel Properties 312Read Amount of Available System

RAM from Zone 3 304Read Fatal Error Function 305Read System Properties 307Read Version Number 309

services summary table 20Special services

Index 335

June 21, 2002

brief description 20XX_AllocSysRAM 300XX_DefFatalErrorHandler 302XX_GetFatalErrorHandler 305XX_GetFreeSysRAMSize 304KS_GetSysProp 306KS_GetVersion 308INIT_SysProp 310KS_Nop 313KS_UserService 314

starting task 42stopping task 23structure

mailbox KCLASSPROP 176, 184MBOXPROP 170, 180memory partition KCLASSPROP 242,

250mutex KCLASSPROP 270, 280MUTXPROP 264, 276PARTPROP 234, 246queue KCLASSPROP 134, 148QUEUEPROP 128, 144semaphore KCLASSPROP 88, 96SEMAPROP 86SYSPROP 306, 310task environment arguments 27, 44task KCLASSPROP 47, 62TASKPROP 34, 54

suspending task 70, 71SYSPROP structure 306, 310system error function 302, 305system properties 306SYSPROP structure 306, 310

Ttable

Kernel Service Return Value Types 6

Mailbox Services Summary 14Memory Partition Services Summary 16Message Services Summary 15Mutex Services Summary 18Queue Services Summary 12Semaphore Services Summary 10Special Services Summary 20Task Services Summary 8

tables, list of ixtask

abortion event 36allocating 66closing 25code examples

Abort Task and Terminate 24Allocate Dynamic Task 67Close Task When Signaled 26Define Task Name 31Define Task Object Class Properties

35Define Task Priorities 33Define Task Properties 28Define Task Termination Semaphore

37Define Tick Slice 39Execute Task 43Initialize Task Object Class 63Look Up Task by Name 65Put Current Task to Sleep 70Read and Change Task Priority 53Read Current Task Task Number 50Read Dynamic Task Name 52Read Task Environment Arguments

46Read Task Handle and Register It 75Read Task Object Class Properties 49Read Task State 59Read Task Termination Semaphore

57


June 21, 2002

Read Task Tick-Slice Quantum 60Resume Suspended Task from Zone

3 69Suspend Task 71Terminate Task 73Terminate Task and Release Its Stack

55Yield to Another Task 77

defining environment arguments 27defining priority 32defining properties 34environment arguments 44environment arguments structure 27, 44KCLASSPROP structure 47, 62name 64naming 30, 66object class properties 62reading handle 50, 64reading name 51reading object class properties 47reading priority level 53reading properties 54reading semaphore handle 56reading state 58reading time-slice quantum 60registering 74resuming 68services summary table 8starting 42stopping and restarting 23suspending 70, 71TASKPROP structure 34, 54terminating 72termination event 36time-slice quantum 38yielding to next 76

Task servicesbrief description 8

KS_AbortTask 23KS_CloseTask 25KS_DefTaskEnvArg 27KS_DefTaskName 30KS_DefTaskPriority 32KS_DefTaskProp 34KS_DefTaskSema 36KS_DefTimeSlice 38KS_DisableTaskScheduler 40KS_EnableTaskScheduler 41KS_ExecuteTask 42KS_GetTaskClassProp 47KS_GetTaskEnvArg 44KS_GetTaskID 50KS_GetTaskName 51KS_GetTaskPriority 53KS_GetTaskProp 54KS_GetTaskSema 56KS_GetTaskState 58KS_GetTimeSlice 60INIT_TaskClassProp 62KS_LookupTask 64KS_OpenTask 66XX_ResumeTask 68KS_SleepTask 70KS_SuspendTask 71KS_TerminateTask 72KS_UseTask 74KS_YieldTask 76

TASKPROP structure 34, 54terminating task 72termination, task semaphore 56testing

list of semaphores 110, 112, 115mutex availability 288, 290, 294semaphore 106, 108, 118

Index 337

June 21, 2002

testing message for acknowledgment 216, 218, 220

time-slice quantum 60TS_AllocBlk 224TS_DefFatalErrorHandler 302TS_GetFatalErrorHandler 305TS_GetFreeSysRAMSize 304TS_ResumeTask 68TS_SignalSema 102TS_SignalSemaM 104

Uuser-defined kernel service 314

Vversion number, RTXCDSP Kernel 308

WWaiting Order attribute value

semaphore 86

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

Yyielding to next task 76

Zzones

listing services with more than one 4service prefix 4

Date post:	12-Oct-2014
Category:	Documents
Upload:	vladimir-rolbin
View:	201 times
Download:	8 times

RTXC Kernel ServicesV2 Decrypted

Documents