RTXC Kernel Services Reference, Volume 2 Tasks, Semaphores, Queues, Mailboxes, Messages, Memory Partitions, and Mutexes Quadros Systems Inc. ®
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
Chapter 1: Introduction To RTXC/ms Kernel Services 3
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.
4 RTXC Kernel Services Reference, Volume 2
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
Chapter 1: Introduction To RTXC/ms Kernel Services 5
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.
6 RTXC Kernel Services Reference, Volume 2
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
Chapter 1: Introduction To RTXC/ms Kernel Services 7
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.
8 RTXC Kernel Services Reference, Volume 2
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
Chapter 1: Introduction To RTXC/ms Kernel Services 9
RTXC/ms Component Services
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)
Service Description Zones Ref.
10 RTXC Kernel Services Reference, Volume 2
RTXC/ms Component Services
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
Service Description Zones Ref.
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
Chapter 1: Introduction To RTXC/ms Kernel Services 11
RTXC/ms Component Services
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)
Service Description Zones Ref.
12 RTXC Kernel Services Reference, Volume 2
RTXC/ms Component Services
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
Service Description Zones Ref.
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
Chapter 1: Introduction To RTXC/ms Kernel Services 13
RTXC/ms Component Services
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)
Service Description Zones Ref.
14 RTXC Kernel Services Reference, Volume 2
RTXC/ms Component Services
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
Service Description Zones Ref.
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
Chapter 1: Introduction To RTXC/ms Kernel Services 15
RTXC/ms Component Services
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
Service Description Zones Ref.
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
16 RTXC Kernel Services Reference, Volume 2
RTXC/ms Component Services
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
Service Description Zones Ref.
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
Chapter 1: Introduction To RTXC/ms Kernel Services 17
RTXC/ms Component Services
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)
Service Description Zones Ref.
18 RTXC Kernel Services Reference, Volume 2
RTXC/ms Component Services
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
Service Description Zones Ref.
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
Chapter 1: Introduction To RTXC/ms Kernel Services 19
RTXC/ms Component Services
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)
Service Description Zones Ref.
20 RTXC Kernel Services Reference, Volume 2
RTXC/ms Component Services
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
Service Description Zones Ref.
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
22 RTXC Kernel Services Reference, Volume 2
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
Chapter 2: Task Services 23
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.
24 RTXC Kernel Services Reference, Volume 2
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
Chapter 2: Task Services 25
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:
FE_ILLEGAL_TASK if the specified task ID is not valid.
task The number of the task to close.
26 RTXC Kernel Services Reference, Volume 2
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
Chapter 2: Task Services 27
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.
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_TASK if the specified task ID is not valid.
FE_UNINITIALIZED_TASK if the specified task has not yet been initialized.
Example In Example 2-3 on page 28, the Current Task needs to spawn a dynamic task to operate on the port and channel specified by the port and chnl variables that were specified elsewhere. The dynamic task must be allocated dynamically and its identifier is stored in the dyntask variable. The dynamic task’s entry address is taskA and it requires a 256-byte stack that the Current Task allocates from the BLK256 memory partition. The dynamic task runs at priority 14.
task The number of the task being defined.
parg A pointer to the environment arguments structure for the task.
28 RTXC Kernel Services Reference, Volume 2
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);}
Chapter 2: Task Services 29
KS_DefTaskEnvArg
June 21, 2002
See Also KS_DefTaskProp, page 34KS_GetTaskEnvArg, page 44
30 RTXC Kernel Services Reference, Volume 2
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.
Note: To use this service, you must enable the Dynamics attribute of the Task class during system generation.
This service does not check for duplicate task names.
Output This service returns a KSRC value as follows:
RC_GOOD if the service completes successfully.
RC_STATIC_OBJECT if the task being named is static.
RC_OBJECT_NOT_FOUND if the Dynamics attribute of the Task class is not enabled.
RC_OBJECT_NOT_INUSE if the dynamic task being named is still in the free pool of dynamic tasks.
Error This service may generate the following fatal error code:
FE_ILLEGAL_TASK if the specified task ID is not valid.
task The number of the task being defined.
pname A pointer to a null-terminated name string.
Chapter 2: Task Services 31
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
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
TASK dyntask;
if (KS_DefTaskName (dyntask, "NewTask") != RC_GOOD){ ... Probably is a static task. Deal with it here.}
... else the naming operation was successful. Continue
See Also KS_OpenTask, page 66KS_GetTaskName, page 51KS_LookupTask, page 64KS_UseTask, page 74
32 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_TASK if the specified task ID is not valid.
FE_UNINITIALIZED_TASK if the specified task has not yet been initialized.
task The number of the task being defined.
priority The priority value for the task.
Chapter 2: Task Services 33
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
34 RTXC Kernel Services Reference, Volume 2
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;
Output This service does not return a value.
Error This service may generate one of the following fatal error codes:
FE_ILLEGAL_TASK if the specified task ID is not valid.
FE_ILLEGAL_PRIORITY if the specified priority is out of range.
task The number of the task being defined.
ptaskprop A pointer to a Task properties structure.
Chapter 2: Task Services 35
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
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
extern const KCLASSPROP taskclassprop;extern const TASKPROP taskprop[];
KSRC ksrc;int objnum;
if ((ksrc = INIT_TaskClassProp (&taskclassprop)) != RC_GOOD) { printf ("Task class initialization failed %d", ksrc); return (ksrc); } for (objnum = 1; objnum <= taskclassprop.n_statics; objnum++) KS_DefTaskProp (objnum, &taskprop[objnum]);
See Also KS_GetTaskProp, page 54INIT_TaskClassProp, page 62KS_OpenTask, page 66
36 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_TASK if the specified task ID is not valid.
FE_UNINITIALIZED_TASK if the specified task has not yet been initialized.
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.
Chapter 2: Task Services 37
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
38 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_TASK if the specified task ID is not valid.
task The number of the task being defined.
ticks The number of clock ticks in the tick-slice quantum.
Chapter 2: Task Services 39
KS_DefTickSlice
June 21, 2002
FE_UNINITIALIZED_TASK if the specified task has not yet been initialized.
Example In Example 2-9, the Current Task begins tick-sliced operation with a tick quantum of 100 msec. After some period of tick-sliced operation, the task ceases tick-sliced operation.
Example 2-9. Define Tick Slice
#include "rtxcapi.h" /* 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
40 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
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
Chapter 2: Task Services 41
KS_EnableTaskScheduler
June 21, 2002
KS_EnableTaskScheduler Enable the scheduler to allow context switching between tasks.
Synopsis void KS_EnableTaskScheduler (void)
Inputs This service has no inputs.
Description The KS_EnableTaskScheduler kernel service enables the RTXC/ms Scheduler, which in turn permits task context switching to occur. If the application makes nested calls to KS_DisableTaskScheduler, then it must make an equal number of calls to KS_EnableTaskScheduler before context switching (preemption) starts again.
The RTXC Kernel enables the scheduler by default during system initialization.
Output This service does not return a value.
Example In Example 2-11, after performing some critical function with the scheduler disabled, the Current Task enables the scheduler.
Example 2-11. Enable Task Scheduler
#include "rtxcapi.h" /* RTXC Kernel Services prototypes */
KS_DisableTaskScheduler (); /* prevent preemption */
...perform some function
/* allow context switch to occur now */KS_EnableTaskScheduler ();
See Also KS_DisableTaskScheduler, page 40
42 RTXC Kernel Services Reference, Volume 2
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.
Output This service returns a KSRC value as follows:
RC_GOOD if the task starts successfully.
RC_TASK_NOT_INACTIVE if the specified task is in a state other than INACTIVE.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_TASK if the specified task ID is not valid.
FE_UNINITIALIZED_TASK if the specified task has not yet been initialized.
Example In Example 2-12 on page 43, the Current Task starts the SHUTDOWN static task from its starting address.
task The number of the task to execute.
Chapter 2: Task Services 43
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
44 RTXC Kernel Services Reference, Volume 2
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).
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-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.
Chapter 2: Task Services 45
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.
46 RTXC Kernel Services Reference, Volume 2
KS_GetTaskEnvArg
June 21, 2002
Example 2-13. Read Task Environment Arguments
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
void commchnl (void){ struct myargs { int port; /* port number */ int chnl; /* channel number */ }; struct myargs *envargs; int chnlstat; /* port/channel status */
/* first find out where to get the */ /* environment arguments */ envargs = KS_GetTaskEnvArg (SELFTASK);
while ((chnlstat = get_chnl_stat (envargs->port, envargs->chnl)) != 0) { ... while the status is non zero, do some work with the port and channel to process the data stream }
/* terminate when the status is 0 */ KS_TerminateTask (SELFTASK); }
See Also KS_DefTaskEnvArg, page 27
Chapter 2: Task Services 47
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.
48 RTXC Kernel Services Reference, Volume 2
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
Chapter 2: Task Services 49
KS_GetTaskClassProp
June 21, 2002
Example 2-14. Read Task Object Class Properties
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
KCLASSPROP *ptaskclassprop;int free_dyn;
/* Get the task kernel object class properties */if ((ptaskclassprop = KS_GetTaskClassProp (&free_dyn)) == (KCLASSPROP *)0){ putline ("Task Class not initialized");}else{ ...task object class properties are available for use and "free_dyn" contains the number of available dynamic tasks}
See Also INIT_TaskClassProp, page 62
50 RTXC Kernel Services Reference, Volume 2
KS_GetTaskID
June 21, 2002
KS_GetTaskID Get the handle of the Current Task.
Synopsis TASK KS_GetTaskID (void)
Inputs This service has no inputs.
Description The KS_GetTaskID kernel service obtains the identifier, commonly referred to as the handle, of the calling task. This service is typically used by a dynamically created task that needs to have explicit knowledge of its handle. The handles of static tasks are found in the task header file created during system generation.
Output This service returns the handle of the Current Task.
Example Example 2-15 gets the task number of the Current Task and outputs it to the console.
Example 2-15. Read Current Task Number
#include <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);
Chapter 2: Task Services 51
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).
Error This service may generate the following fatal error code:
FE_ILLEGAL_TASK if the specified task ID is not valid.
Example In Example 2-16 on page 52, the Current Task needs to report the name of the dynamic task specified in dyntask.
task The number of the task being queried.
52 RTXC Kernel Services Reference, Volume 2
KS_GetTaskName
June 21, 2002
Example 2-16. Read Dynamic Task Name
#include <stdio.h> /* standard i/o */#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
static char buf[128];TASK dyntask;char *pname;
if ((pname = KS_GetTaskName (dyntask)) == (char *)0) sprintf (buf, "Task %d has no name", dyntask);else sprintf (buf, "Task %d name is %s", dyntask, pname);
putline (buf);
See Also KS_DefTaskName, page 30KS_OpenTask, page 66
Chapter 2: Task Services 53
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.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_TASK if the specified task ID is not valid.
FE_UNINITIALIZED_TASK if the specified task has not yet been initialized.
Example Example 2-17 gets the priority of the Current Task and raises its priority by 2.
Example 2-17. Read and Change Task Priority
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
PRIORITY mypri;
mypri = KS_GetTaskPriority (SELFTASK);
/* raise Current Task’s priority by 2 */KS_DefTaskPriority (SELFTASK, mypri - 2);
See Also KS_DefTaskPriority, page 32
task The number of the task being queried.
54 RTXC Kernel Services Reference, Volume 2
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.
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-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.
task The number of the task being queried.
ptaskprop A pointer to a task property structure.
Chapter 2: Task Services 55
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
56 RTXC Kernel Services Reference, Volume 2
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).
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_TASK if the specified task ID is not valid.
FE_UNINITIALIZED_TASK if the specified task has not yet been initialized.
Example In Example 2-19 on page 57, the Current Task needs to know the handle of the semaphore associated with the termination or abortion of the dynamic task specified in dyntask. If the return from KS_GetTaskSema indicates there is no semaphore defined, the Current Task defines the TASKTERM semaphore, adds it to semalist, and waits for the indicated events.
task The number of the task being queried.
Chapter 2: Task Services 57
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
58 RTXC Kernel Services Reference, Volume 2
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.
Output This service returns a KSRC value as follows:
RC_TASK_ACTIVE if the task has been previously made runnable by a KS_ExecuteTask request and is currently runnable or blocked on a condition other that ABORT_BLOCK or INACTIVE.
RC_TASK_INACTIVE if the task is currently in an INACTIVE state.
RC_TASK_ABORTED if the task is currently in an ABORT_BLOCK state.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_TASK if the specified task ID is not valid.
FE_UNINITIALIZED_TASK if the specified task has not yet been initialized.
Example 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.
task The number of the task being queried.
Chapter 2: Task Services 59
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
60 RTXC Kernel Services Reference, Volume 2
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.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_TASK if the specified task ID is not valid.
FE_UNINITIALIZED_TASK if the specified task has not yet been initialized.
Example Example 2-21 gets the tick-slice quantum for the SCANR task. If the quantum has not been defined, it defines the task’s tick quantum as 100 msec.
Example 2-21. Read Task Tick-Slice Quantum
#include "rtxcapi.h" /* 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);
task The number of the task being queried.
Chapter 2: Task Services 61
KS_GetTickSlice
June 21, 2002
See Also KS_DefTickSlice, page 38
62 RTXC Kernel Services Reference, Volume 2
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
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 attributes and corresponding masks listed in Table 2-1 on page 48.
Output This service returns a KSRC value as follows:
RC_GOOD if the service completes successfully.
RC_NO_RAM if the initialization fails because there is insufficient system RAM available.
pclassprop A pointer to a Task object class properties structure.
Chapter 2: Task Services 63
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
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
extern const SYSPROP sysprop;extern const KCLASSPROP taskclassprop;
KSRC userinit (void){ KSRC ksrc; static char buf[128];
/* initialize the kernel workspace, allocate RAM for required classes, etc. */
if ((ksrc = INIT_SysProp (&sysprop)) != RC_GOOD) { putline ("Kernel initialization failure"); return (ksrc); /* end initialization process */ } /* kernel is initialized */
/* Need to initialize the necessary kernel object classes */
/* Initialize the Task Kernel Object class */ if ((ksrc = INIT_TaskClassProp (&taskclassprop)) != RC_GOOD) { putline ("Insufficient RAM for Task init."); return (ksrc); /* end initialization process */ }
... Continue with system initialization
}
See Also INIT_SysProp, page 310KS_GetTaskClassProp, page 47
64 RTXC Kernel Services Reference, Volume 2
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.
Chapter 2: Task Services 65
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
#include <stdio.h> /* standard i/o */#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
TASK dyntask;static char buf[128];
/* lookup the task name to see if it exists */if (KS_LookupTask ("DynMuxTask2", &dyntask) != RC_GOOD){ putline ("Task DynMuxTask2 name not found");}else /* task exists */{ sprintf (buf, "DynMuxTask2 is task %d", dyntask); putline (buf);}
See Also KS_DefTaskName, page 30KS_OpenTask, page 66
66 RTXC Kernel Services Reference, Volume 2
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.
Note: To use this service, you must enable the Dynamics attribute of the Task class during system generation.
If the pointer to the task name is not null, the time required to perform this operation varies with the number of task names in use.
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.
Chapter 2: Task Services 67
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.
Output This service returns a KSRC value as follows:
RC_GOOD if the service completes successfully. The service stores the handle of the new dynamic task in the variable pointed to by ptask.
RC_OBJECT_ALREADY_EXISTS if the name search finds another task whose name matches the specified string.
RC_NO_OBJECT_AVAILABLE if the name search finds no match but all dynamic tasks are in use.
Example Example 2-25 allocates a dynamic task and names it DynMuxTask2.
Example 2-25. Allocate Dynamic Task
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
KSRC ksrc;TASK dyntask;
if ((ksrc = KS_OpenTask ("DynMuxTask2", &dyntask)) != RC_GOOD){ if (ksrc == RC_OBJECT_ALREADY_EXISTS) putline ("DynMuxTask2 task name in use"); else if (ksrc == RC_NO_OBJECT_AVAILABLE) putline ("No dynamic tasks available"); else putline ("Tasks are not a defined class");}else{ ... task was opened correctly. Okay to use it now}
See Also KS_CloseTask, page 25KS_LookupTask, page 64KS_UseTask, page 74
68 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_TASK if the specified task ID is not valid.
FE_UNINITIALIZED_TASK if the specified task has not yet been initialized.
task The number of the task to resume.
Chapter 2: Task Services 69
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
70 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
Example In Example 2-27, the Current Task is put to sleep for a period of 100 msec. After some processing, the task is put to sleep again for a period of 50 msec.
Example 2-27. Put Current Task to Sleep
#include "rtxcapi.h" /* 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.
Chapter 2: Task Services 71
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).
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_TASK if the specified task ID is not valid.
FE_UNINITIALIZED_TASK if the specified task has not yet been initialized.
Example In Example 2-28, the Current Task suspends the LKDETECT task and then suspends itself.
Example 2-28. Suspend Task
#include "rtxcapi.h" /* 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.
72 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_TASK if the specified task ID is not valid.
FE_UNINITIALIZED_TASK if the specified task has not yet been initialized.
task The number of the task to terminate.
Chapter 2: Task Services 73
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
74 RTXC Kernel Services Reference, Volume 2
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.
Note: To use this service, you must enable the Dynamics attribute of the Task class during system generation.
The time required to perform this operation varies with the number of task names in use.
Output This service returns a KSRC value as follows:
RC_GOOD if the search and registration is successful. The service stores the matching task’s handle in the variable pointed to by ptask.
RC_STATIC_OBJECT if the specified name belongs to a static task.
RC_OBJECT_NOT_FOUND if the service finds no matching task name.
Example 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
pname A pointer to a null-terminated name string.
ptask A pointer to a variable in which to store the task’s handle, if found.
Chapter 2: Task Services 75
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
#include <stdio.h> /* standard i/o */#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
TASK dyntask;KSRC ksrc;static char buf[128];
if ((ksrc = KS_UseTask ("DynMuxTask3", &dyntask)) != RC_GOOD){ if (ksrc == RC_STATIC_OBJECT) putline ("Task DynMuxTask3 is a static task"); else putline ("Task DynMuxTask3 not found");}else{ /* task was found and its handle is in dyntask. */ sprintf (buf, "DynMuxTask3 is task %d", dyntask); putline (buf);}
See Also KS_DefTaskProp, page 34KS_DefTaskName, page 30KS_OpenTask, page 66
76 RTXC Kernel Services Reference, Volume 2
KS_YieldTask
June 21, 2002
KS_YieldTask Yield to the next ready task of the same priority.
Synopsis KSRC KS_YieldTask (void)
Inputs This service has no inputs.
Description The KS_YieldTask kernel service voluntarily releases control by the Current Task without violating the policy of the highest priority runnable task being the Current Task. This service is useful only when there are two or more tasks operating at the same priority. When KS_YieldTask is called and there is one more task in the Ready List at the same priority, the calling task is removed from the Ready List and reinserted into the Ready List immediately following the last runnable task with the same priority. The task remains unblocked.
Yielding when there is no other task at the same priority causes no change in the Ready List and the calling task resumes immediately.
Output This service returns a KSRC value as follows:
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.
Chapter 2: Task Services 77
KS_YieldTask
June 21, 2002
Example 2-31. Yield to Another Task
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
/* yield to next READY task at same priority */if (KS_YieldTask () == RC_NO_YIELD){ ... no READY task exists at same priority level take whatever action is required}/* otherwise, the yield was successful and the next *//* line of code following this comment will execute *//* when the task next gains control of the CPU /*
78 RTXC Kernel Services Reference, Volume 2
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
80 RTXC Kernel Services Reference, Volume 2
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.
Output This service returns a KSRC value as follows:
RC_GOOD if the service is successful.
RC_STATIC_OBJECT if the specified semaphore is not dynamic.
RC_OBJECT_NOT_INUSE if the specified semaphore does not correspond to an active dynamic semaphore.
RC_OBJECT_INUSE if the Current 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.
Chapter 3: Semaphore Services 81
KS_CloseSema
June 21, 2002
Note: RC_OBJECT_INUSE does not necessarily indicate an error condition. The calling task must interpret its meaning.
Error This service may generate the following fatal error code:
FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
Example In Example 3-1, the Current Task waits on a signal from another task indicating that it is time to close a dynamic semaphore. The handle of the dynamic semaphore is specified in dynsema. When the signal is received on the ENDALL semaphore, the Current Task closes its use of the associated dynamic semaphore.
Example 3-1. Close Semaphore
#include "rtxcapi.h" /* 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
82 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.
Example 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.
Chapter 3: Semaphore Services 83
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
84 RTXC Kernel Services Reference, Volume 2
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.
Note: To use this service, you must enable the Dynamics attribute of the Semaphore class during system generation.
This service does not check for duplicate semaphore names.
Output This service returns a KSRC value as follows:
RC_GOOD if the service completes successfully.
RC_STATIC_OBJECT if the semaphore being named is static.
RC_OBJECT_NOT_FOUND if the Dynamics attribute of the Semaphore class is not enabled.
RC_OBJECT_NOT_INUSE if the specified semaphore does not correspond to an active dynamic semaphore.
Error This service may generate the following fatal error code:
FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
sema The handle of the semaphore being defined.
pname A pointer to a null-terminated name string.
Chapter 3: Semaphore Services 85
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
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
SEMA dynsema;
if (KS_DefSemaName (dynsema, "NewSema") != RC_GOOD){ ... Naming operation failed. Deal with it here}
... naming operation was successful. Continue
See Also KS_OpenSema, page 100KS_GetSemaName, page 92KS_LookupSema, page 98KS_UseSema, page 120
86 RTXC Kernel Services Reference, Volume 2
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.
sema The handle of the semaphore being defined.
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.
Chapter 3: Semaphore Services 87
KS_DefSemaProp
June 21, 2002
Output This service does not return a value.
Error This service may generate the following fatal error code:
FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
Example In Example 3-5, the Current Task defines the properties of the dynamic semaphore specified in dynsema so that any tasks waiting for the event are ordered in descending order of task priority.
Example 3-5. Specify Semaphore Waiting Order
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
SEMA dynsema;SEMAPROP sprop;KSRC ksrc;
/* get current properties of the semaphore */KS_GetSemaProp (dynsema, &sprop);
/* use priority waiters */sprop.attributes &= ~ATTR_FIFO_ORDER;
KS_DefSemaProp (dynsema, &sprop); /* define properties */
... Continue
See Also KS_GetSemaProp, page 94INIT_SemaClassProp, page 96KS_OpenSema, page 100
88 RTXC Kernel Services Reference, Volume 2
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.
Chapter 3: Semaphore Services 89
KS_GetSemaClassProp
June 21, 2002
Output If successful, this service returns a pointer to a KCLASSPROP structure.
If the Semaphore class is not initialized, the service returns a null pointer ((KCLASSPROP *)0).
If pint is not null ((int *)0), the service returns the number of available dynamic semaphores in the variable pointed to by pint.
Example In Example 3-7, the Current Task needs the information contained in the KCLASSPROP structure for the Semaphore object class.
Example 3-7. Read Semaphore Object Class Properties
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
KCLASSPROP *psemaclass;int free_dyn;
/* Get the semaphore kernel object class properties */if ((psemaclassprop = KS_GetSemaClassProp (&free_dyn)) == (const KCLASSPROP *)0) { putline ("Semaphore Class not initialized");}else{ ... /* semaphore object class properties are available for use */ /* "free_dyn" contains the number of available dynamic semas */}
See Also INIT_SemaClassProp, page 96
Table 3-1. Semaphore Class Attributes and Masks
Attribute Mask
Static Names ATTR_STATIC_NAMES
Dynamics ATTR_DYNAMICS
Statistics ATTR_STATISTICS
90 RTXC Kernel Services Reference, Volume 2
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.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.
sema The handle of the semaphore being queried.
Chapter 3: Semaphore Services 91
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
92 RTXC Kernel Services Reference, Volume 2
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).
Error This service may generate the following fatal error code:
FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
Example In Example 3-9 on page 93, the Current Task needs to report the name of the dynamic semaphore specified in dynsema.
sema The handle of the semaphore being queried.
Chapter 3: Semaphore Services 93
KS_GetSemaName
June 21, 2002
Example 3-9. Read Semaphore Name
#include <stdio.h> /* standard i/o */#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
static char buf[128];SEMA dynsema;char *pname;
if ((pname = KS_GetSemaName (dynsema)) == (char *)0 ) sprintf (buf, "Semaphore %d has no name\n", dynsema);else sprintf (buf, "Semaphore %d name is %s\n", dynsema, pname);
putline (buf); /* send message to console */
See Also KS_DefSemaName, page 84KS_OpenSema, page 100
94 RTXC Kernel Services Reference, Volume 2
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.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.
Example In Example 3-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.
sema The handle of the semaphore being queried.
psemaprop A pointer to the Semaphore properties structure in which to store the semaphore’s properties.
Chapter 3: Semaphore Services 95
KS_GetSemaProp
June 21, 2002
Example 3-10. Read Semaphore Properties
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
SEMA dynsema;SEMAPROP sprop; KS_GetSemaProp (dynsema, &sprop); /* get properties */
if (sprop.attributes & ATTR_FIFO_ORDER){ /* use priority mode*/ sprop.attributes &= ~ATTR_FIFO_ORDER;
/* define properties */ KS_DefSemaProp (dynsema, &sprop);}
... continue
See Also KS_DefSemaProp, page 86
96 RTXC Kernel Services Reference, Volume 2
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.
Output This service returns a KSRC value as follows:
RC_GOOD if the service completes successfully.
RC_NO_RAM if the initialization fails because there is insufficient system RAM available.
Example During system initialization, the startup code must initialize the Semaphore object class before using any kernel service for that class. The system generation process produces a KCLASSPROP structure containing the information about the semaphore object class necessary for its initialization. Example 3-11 references that structure externally to the code module.
pclassprop A pointer to a Semaphore object class properties structure.
Chapter 3: Semaphore Services 97
INIT_SemaClassProp
June 21, 2002
Example 3-11. Initialize Semaphore Object Class
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
static char buf[128];
/* created by system generation*/extern const SYSPROP sysprop; extern const KCLASSPROP semaclassprop;
KSRC userinit (void){ KSRC ksrc;
/* initialize the kernel workspace, allocate RAM for required classes, etc. */ if ((ksrc = INIT_SysProp (&sysprop)) != RC_GOOD) { putline ("Kernel initialization failure\n"); return (ksrc); /* end initialization process */ } /* kernel is initialized */
/* Need to initialize the necessary kernel object classes */
/* Initialize the Semaphore kernel object class */ if ((ksrc = INIT_SemaClassProp (&semaclassprop)) != RC_GOOD) { putline ("No RAM for Semaphore init"); return (ksrc); /* end initialization process */ }
... Continue with system initialization
}
See Also INIT_SysProp, page 310KS_GetSemaClassProp, page 88
98 RTXC Kernel Services Reference, Volume 2
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.
Output This service returns a KSRC value as follows:
RC_GOOD if the search succeeds. The service stores the matching semaphore’s handle in the variable pointed to by psema.
RC_OBJECT_NOT_FOUND if the service finds no matching semaphore name.
pname A pointer to a null-terminated name string.
psema A pointer to a SEMA variable for storing the semaphore handle, if found.
Chapter 3: Semaphore Services 99
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
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
SEMA dynsema;
/* lookup the semaphore name to get its handle */if (KS_LookupSema ("Chnl2Sema ", &dynsema) != RC_GOOD){ ... Semaphore name not found. Deal with it}else /* got the handle for Chnl2Sema */{ ... Do something with the semaphore now}
See Also KS_DefSemaName, page 84KS_OpenSema, page 100
100 RTXC Kernel Services Reference, Volume 2
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.
Note: To use this service, you must enable the Dynamics attribute of the Semaphore class during system generation.
If the pointer to the semaphore name is not null, the time required to perform this operation varies with the number of semaphore names in use.
If the pointer to the semaphore name is null, no search of semaphore names takes place and the time to perform the
pname A pointer to a null-terminated name string.
psema A pointer to a SEMA variable in which to store the allocated semaphore’s handle.
Chapter 3: Semaphore Services 101
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.
Output This service returns a KSRC value as follows:
RC_GOOD if the service completes successfully. The service stores the handle of the new dynamic semaphore in the variable pointed to by psema.
RC_OBJECT_ALREADY_EXISTS if the name search finds another semaphore whose name matches the specified string.
RC_NO_OBJECT_AVAILABLE if the name search finds no match but all dynamic semaphores are in use.
Example Example 3-13 on page 101 allocates a dynamic semaphore and names it MuxChnl2Sema. If the name is in use, the example outputs a message on the console using the putline routine.
Example 3-13. Allocate Dynamic Semaphore
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
KSRC ksrc;SEMA dynsema;
if ((ksrc = KS_OpenSema ("MuxChnl2Sema", &dynsema)) != RC_GOOD){ if (ksrc == RC_OBJECT_ALREADY_EXISTS) putline ("MuxChnl2Sema semaphore name in use"); else if (ksrc == RC_NO_OBJECT_AVAILABLE) putline ("No dynamic Semaphores available"); else putline ("Semaphore class is not defined");}else{ ... semaphore was opened correctly. Okay to use it now}
See Also KS_CloseSema, page 80KS_LookupSema, page 98KS_UseSema, page 120
102 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.
sema The handle of the semaphore to signal.
Chapter 3: Semaphore Services 103
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
104 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.
psemalist A pointer to a null-terminated semaphore list.
Chapter 3: Semaphore Services 105
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
106 RTXC Kernel Services Reference, Volume 2
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.
Output This service returns a KSRC value as follows:
RC_GOOD if the service detects a signal (semaphore count was > 0).
RC_NO_SIGNAL if the service detects a semaphore count less than or equal to zero (0).
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.
Example 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.
Chapter 3: Semaphore Services 107
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
108 RTXC Kernel Services Reference, Volume 2
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.
Output This service returns a KSRC value as follows:
RC_GOOD if a semaphore signal has occurred.
sema The handle of the semaphore to test.
counter The counter associated with the tick interval defined by ticks.
ticks The number of ticks on the specified counter to wait for the signal.
Chapter 3: Semaphore Services 109
KS_TestSemaT
June 21, 2002
RC_TICKOUT if the specified number of ticks elapses before the semaphore receives a signal.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.
FE_ILLEGAL_COUNTER if the specified counter ID is not valid.
FE_UNINITIALIZED_COUNTER if the specified counter has not yet been initialized.
Example In Example 3-17, the Current Task needs to wait for a keypad character to be pressed, but it 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
110 RTXC Kernel Services Reference, Volume 2
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.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.
psemalist A pointer to a null-terminated semaphore list.
Chapter 3: Semaphore Services 111
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
112 RTXC Kernel Services Reference, Volume 2
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
The specified number of ticks elapses.
Note: It is illegal for a semaphore to occur more than once in the semaphore list.
psemalist A pointer to a null-terminated semaphore list.
counter The counter associated with the tick interval defined by ticks.
ticks The number of ticks on counter to wait for the signal.
Chapter 3: Semaphore Services 113
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.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.
FE_ILLEGAL_COUNTER if the specified counter ID is not valid.
FE_UNINITIALIZED_COUNTER if the specified counter has not yet been initialized.
Example In Example 3-19 on page 114, the Current Task needs to know when either of two events occur. The SW1CLOSE and SW2CLOSE events are associated with switch closures, and either one, but only one, is expected to occur within two seconds after the occurrence of another event associated with the KEYSW semaphore. When either event happens, the task performs a code segment specific to that event.
114 RTXC Kernel Services Reference, Volume 2
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
Chapter 3: Semaphore Services 115
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.
Note: It is illegal for a semaphore to occur more than once in the semaphore list.
Output This service returns the handle of the semaphore receiving the event signal.
Note: If the service detects multiple signals on multiple semaphores, it preserves the signaling order only for the first event. For example, a call to KS_TestSemaMW tests the A, B, and C semaphores and finds no signals. The service blocks the requesting task and waits for a signal. Now, assume the C semaphore receives a signal, but before the
psemalist A pointer to a null-terminated semaphore list.
116 RTXC Kernel Services Reference, Volume 2
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.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.
Example In Example 3-20 on page 117, the Current Task needs to know when any of three events occur. The SWITCH1 and SWITCH2 events are associated with switch closures while TIMERA is associated with a timer. When any one event occurs, the task performs a code segment specific to that event.
Chapter 3: Semaphore Services 117
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
118 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.
Example 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.
sema The handle of the semaphore to test.
Chapter 3: Semaphore Services 119
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
120 RTXC Kernel Services Reference, Volume 2
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.
Note: To use this service, you must enable the Dynamics attribute of the Semaphore class during system generation.
The time required to perform this operation varies with the number of semaphore names in use.
Output This service returns a KSRC value as follows:
RC_GOOD if the search and registration is successful. The service stores the matching semaphore’s handle in the variable pointed to by psema.
RC_STATIC_OBJECT if the specified name belongs to a static semaphore.
RC_OBJECT_NOT_FOUND if the service finds no matching semaphore name.
Example Example 3-22 on page 121 locates a dynamic semaphore named DynMuxSema3 and obtains its handle for subsequent use.
pname A pointer to a null-terminated name string.
psema A pointer to a SEMA variable for storing the semaphore handle, if found.
Chapter 3: Semaphore Services 121
KS_UseSema
June 21, 2002
Example 3-22. Read Semaphore Handle and Register It
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
KSRC ksrc;SEMA dynsema;
if ((ksrc = KS_UseSema ("DynMuxSema3", &dynsema)) != RC_GOOD){ if (ksrc == RC_STATIC_OBJECT) putline ("DynMuxSema3 is a static semaphore"); else putline ("Semaphore DynMuxSema3 not found");}else{ ... semaphore was found and its handle is in dynsema. Okay to use it now}
See Also KS_DefSemaProp, page 86KS_DefSemaName, page 84KS_OpenSema, page 100
122 RTXC Kernel Services Reference, Volume 2
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
124 RTXC Kernel Services Reference, Volume 2
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.
Output This service returns a KSRC value as follows:
RC_GOOD if the service is successful.
RC_STATIC_OBJECT if the specified queue is not dynamic.
RC_OBJECT_NOT_INUSE if the specified queue does not correspond to an active dynamic queue.
RC_OBJECT_INUSE if the Current 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.
Chapter 4: Queue Services 125
KS_CloseQueue
June 21, 2002
Note: RC_OBJECT_INUSE does not necessarily indicate an error condition. The calling task must interpret its meaning.
Error This service may generate the following fatal error code:
FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
Example In Example 4-1, the Current Task waits for a signal from another task indicating that it is time to close a dynamic queue. The handle of the dynamic queue is specified in dynqueue. When the signal is received, the Current Task closes the associated queue.
Example 4-1. Close Queue
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
QUEUE dynqueue; /* handle of queue to be closed */SEMA dynsema;
KS_TestSemaW (dynsema); /* wait for signal */
KS_CloseQueue (dynqueue); /* then close the queue */
See Also KS_OpenQueue, page 152KS_UseQueue, page 162
126 RTXC Kernel Services Reference, Volume 2
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.
Note: To use this service, you must enable the Dynamics attribute of the Queue class during system generation.
This service does not check for duplicate queue names.
Output This service returns a KSRC value as follows:
RC_GOOD if the service completes successfully.
RC_STATIC_OBJECT if the queue being named is static.
RC_OBJECT_NOT_FOUND if the Dynamics attribute of the Queue class is not enabled.
RC_OBJECT_NOT_INUSE if the specified queue does not correspond to an active dynamic queue.
Error This service may generate the following fatal error code:
FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
queue The handle of the queue being defined.
pname A pointer to a null-terminated name string.
Chapter 4: Queue Services 127
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
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
QUEUE dynqueue;
if (KS_DefQueueName (dynqueue, "NewQueue") != RC_GOOD){ ... Error in naming the queue. Deal with it here}
... naming operation was successful. Continue
See Also KS_OpenQueue, page 152KS_GetQueueName, page 142KS_LookupQueue, page 150KS_UseQueue, page 162
128 RTXC Kernel Services Reference, Volume 2
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:
Output This service does not return a 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.
Chapter 4: Queue Services 129
KS_DefQueueProp
June 21, 2002
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
FE_UNINITIALIZED_QUEUE if the specified queue has not yet been initialized.
FE_NULL_QUEUEBASE if the specified queue base address is null.
FE_ZERO_QUEUEWIDTH if the specified queue width is zero.
FE_ZERO_QUEUEDEPTH if the specified queue depth is zero.
Example During system initialization, the startup code must create and initialize the Queue kernel object class and then define all of the static queues to the system before the first use of queues by any task. Example 4-4 illustrates this process.
Example 4-4. Define Queue Object Class Properties
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
extern const KCLASSPROP queueclassprop;extern const QUEUEPROP queueprop[];
static char buf[128];int objnum;
if ((ksrc = INIT_QueueClassProp (&queueclassprop)) != RC_GOOD) { putline ("Queue class initialization failed"); return (ksrc); } /* if class inits successfully, define the queues to the system */ for (objnum = 1; objnum <= queueclassprop.n_statics; objnum++) KS_DefQueueProp (objnum, &queueprop[objnum]);
See Also KS_GetQueueProp, page 144INIT_QueueClassProp, page 148KS_OpenQueue, page 152
130 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
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.
Chapter 4: Queue Services 131
KS_DefQueueSema
June 21, 2002
FE_UNINITIALIZED_QUEUE if the specified queue has not yet been initialized.
FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.
FE_INVALID_QEVENT if the specified queue event value is not either QNF or QNE.
Example In Example 4-5 on page 132, the Current Task needs to associate the Queue_Not_Empty condition for the DATAQ1 and DATAQ2 queues with the GOT1 and GOT2 semaphores, respectively.
Notice that the example does not check the return value of KS_GetQueueData. This procedure is acceptable because the example associates the QNE event with the semaphores. Because the QNE event indicates that data must be in the queue, the KSRC value of RC_QUEUE_EMPTY cannot occur.
132 RTXC Kernel Services Reference, Volume 2
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
Chapter 4: Queue Services 133
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
134 RTXC Kernel Services Reference, Volume 2
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.
Example 2-22 on page 62 shows the organization of the KCLASSPROP structure.
The attributes element of the Queue KCLASSPROP structure supports the class property attributes and masks listed in Table 4-1 on page 135.
Output If successful, this service returns a pointer to a KCLASSPROP structure.
If the Queue class is not initialized, the service returns a null pointer ((KCLASSPROP *)0).
If pint is not null, the service returns the number of available dynamic queues in the variable pointed to by pint.
pint A pointer to a variable in which to store the number of available dynamic queues.
Chapter 4: Queue Services 135
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
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
KCLASSPROP *pqueueclassprop;int free_dyn;
/* Get the queue kernel object class properties */if ((pqueueclassprop = KS_GetQueueClassProp (&free_dyn)) == (KCLASSPROP const *)0) { putline ("Queue Class not initialized");}else{ ... queue object class properties are available for use free_dyn contains the number of available dynamic queues}
See Also INIT_QueueClassProp, page 148
Table 4-1. Queue Class Attributes and Masks
Attribute Mask
Static Names ATTR_STATIC_NAMES
Dynamics ATTR_DYNAMICS
Semaphores ATTR_SEMAPHORES
136 RTXC Kernel Services Reference, Volume 2
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_GOOD if the service completes successfully.
RC_QUEUE_EMPTY if the queue is empty at the time of the kernel service request.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
FE_UNINITIALIZED_QUEUE if the specified queue has not yet been initialized.
FE_NULL_DESTBUFFER if the pointer to the destination buffer is null.
Example In Example 4-7 on page 137, the Current Task needs to get an entry containing several bytes of data from the DATAQ queue.
queue The handle of the queue being queried.
pdest A pointer to the destination buffer.
Chapter 4: Queue Services 137
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
138 RTXC Kernel Services Reference, Volume 2
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
The specified number of ticks elapses.
Output This service returns a KSRC value of:
RC_GOOD if the service completes successfully. If pevent is not null, the service stores the event indicators for any queue events that occur during the data movement in the variable pointed to by pevent.
RC_TICKOUT if the specified number of ticks elapses before the empty queue receives an entry.
queue The handle of the queue being queried.
pdest A pointer to the destination buffer.
counter The counter associated with the interval defined by ticks.
ticks The number of ticks on the specified counter to wait for a queue entry.
Chapter 4: Queue Services 139
KS_GetQueueDataT
June 21, 2002
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
FE_UNINITIALIZED_QUEUE if the specified queue has not yet been initialized.
FE_ILLEGAL_COUNTER if the specified counter ID is not valid.
FE_UNINITIALIZED_COUNTER if the specified counter has not yet been initialized.
FE_NULL_DESTBUFFER if the pointer to the destination buffer is null.
Example Example 4-8 gets an entry from the DATAQ queue and stores it in the structure called entry. If DATAQ is empty, the task waits no longer than 250 msec relative to CLKCOUNTER for data to become available before proceeding.
Example 4-8. Read Queue 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
140 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
FE_UNINITIALIZED_QUEUE if the specified queue has not yet been initialized.
FE_NULL_DESTBUFFER if the pointer to the destination buffer is null.
Example Example 4-9 on page 141 gets an entry from the DATAQ static queue and stores it in the structure called entry. If DATAQ is empty, the task waits for data to become available before proceeding.
queue The handle of the queue being queried.
pdest A pointer to the destination buffer.
Chapter 4: Queue Services 141
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
142 RTXC Kernel Services Reference, Volume 2
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).
Error This service may generate the following fatal error code:
FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
Example In Example 4-10 on page 143, the Current Task needs to report the name of the dynamic queue specified in dynqueue.
queue The handle of the queue being queried.
Chapter 4: Queue Services 143
KS_GetQueueName
June 21, 2002
Example 4-10. Read Dynamic Queue Name
#include <stdio.h> /* standard i/o */#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
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
144 RTXC Kernel Services Reference, Volume 2
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.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
FE_UNINITIALIZED_QUEUE if the specified queue has not yet been initialized.
queue The handle of the queue being queried.
pqueueprop A pointer to a Queue properties structure.
Chapter 4: Queue Services 145
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
146 RTXC Kernel Services Reference, Volume 2
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).
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
FE_UNINITIALIZED_QUEUE if the specified queue has not yet been initialized.
FE_INVALID_QEVENT if the specified queue event value is not either QNF or QNE.
queue The handle of the queue being queried.
event A queue event value.
Chapter 4: Queue Services 147
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
148 RTXC Kernel Services Reference, Volume 2
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.
Example 2-22 on page 62 shows the organization of the KCLASSPROP structure.
The attributes element of the Queue KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 4-1 on page 135.
Output This service returns a KSRC value as follows:
RC_GOOD if the service completes successfully.
RC_NO_RAM if the initialization fails because there is insufficient system RAM available.
Example During system initialization, the startup code must initialize the Queue object class before using any kernel service for that class. The system generation process produces a KCLASSPROP structure containing the information about the kernel object necessary for its initialization. In Example 4-13 on page 149, that structure is referenced externally to the code module.
pclassprop A pointer to a Queue object class properties structure.
Chapter 4: Queue Services 149
INIT_QueueClassProp
June 21, 2002
Example 4-13. Initialize Queue Object Class
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
extern const SYSPROP sysprop;extern const KCLASSPROP queueclassprop;
KSRC userinit (void){ int objnum; KSRC ksrc;
/* initialize the kernel workspace, allocate RAM */ /* for required classes, etc. */
if ((ksrc = INIT_SysProp (&sysprop)) != RC_GOOD) { putline ("Kernel initialization failure"); return (ksrc); /* end initialization process */ } /* kernel is initialized */
/* Need to initialize the necessary kernel object classes */
/* Initialize the Queue Kernel Object class */ if ((ksrc = INIT_QueueClassProp (&queueclassprop)) != RC_GOOD) { putline ("No RAM for Queue initialization"); return (ksrc); /* end initialization process */ }
... Continue with system initialization}
See Also INIT_SysProp, page 310KS_GetQueueClassProp, page 134
150 RTXC Kernel Services Reference, Volume 2
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.
Output This service returns a KSRC value as follows:
RC_GOOD if the search succeeds. The service also stores the matching queue’s handle in the variable pointed to by pqueue.
RC_OBJECT_NOT_FOUND if the service finds no matching queue name.
pname A pointer to a null-terminated name string.
pqueue A pointer to a variable in which to store the queue handle, if found.
Chapter 4: Queue Services 151
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
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
QUEUE dynqueue;QEVENT qevent;char data[4];
/* lookup the queue name to see if it exists */if (KS_LookupQueue ("DynChnl2Q", &dynqueue) != RC_GOOD){ ... queue name not found. Deal with it}else{ /* queue named DynChnl2Q exists, get data from it, */ /* ignore queue events */ KS_GetQueueDataW (dynqueue, &data, &qevent); ... continue}
See Also KS_DefQueueName, page 126KS_OpenQueue, page 152
152 RTXC Kernel Services Reference, Volume 2
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.
Note: To use this service, you must enable the Dynamics attribute of the Queue class during system generation.
If the pointer to the queue name is not null ((char *)0), the time required to perform this operation varies with the number of queue names in use.
pname A pointer to a null-terminated name string.
pqueue A pointer to a variable in which to store the queue handle.
Chapter 4: Queue Services 153
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.
Output This service returns a KSRC value as follows:
RC_GOOD if the service completes successfully. The service stores the handle of the new dynamic queue in the variable pointed to by pqueue.
RC_OBJECT_ALREADY_EXISTS if the name search finds another queue whose name matches the specified string.
RC_NO_OBJECT_AVAILABLE if the name search finds no match but all dynamic queues are in use.
Example Example 4-15 on page 154 allocates a dynamic queue and names it DynDataQ2. It also obtains a block from the QUEBODY memory partition, then defines the properties for the new queue: the width of each queue entry is four bytes, the depth is as many four-byte entries as can fit in the memory partition block, and the queue is initialized as empty.
154 RTXC Kernel Services Reference, Volume 2
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}
Chapter 4: Queue Services 155
KS_OpenQueue
June 21, 2002
See Also KS_CloseQueue, page 124KS_LookupQueue, page 150KS_UseQueue, page 162
156 RTXC Kernel Services Reference, Volume 2
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.
Output This service returns a KSRC value as follows:
RC_GOOD if the service completes successfully.
RC_QUEUE_FULL if the service failed to insert data into the specified queue.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
FE_UNINITIALIZED_QUEUE if the specified queue has not yet been initialized.
FE_NULL_SORUCEBUFFER if the pointer to the source buffer is null.
Example Example 4-16 on page 157 moves data from the entry structure into the DATAQ static queue and ensures that the operation succeeded.
queue The handle of the queue.
psource A pointer to the source buffer.
Chapter 4: Queue Services 157
KS_PutQueueData
June 21, 2002
Example 4-16. Put Data Into Queue
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */#include "kqueue.h" /* defines DATAQ */
struct{ int type; int value;} entry;
/* enqueue packet of data into DATAQ */if (KS_PutQueueData (DATAQ, &entry) == RC_GOOD){ ... data put into queue }}else{ ... no room in queue. Deal with it here.}
See Also KS_PutQueueDataT, page 158KS_PutQueueDataW, page 160
158 RTXC Kernel Services Reference, Volume 2
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
The specified number of ticks elapses.
When the full condition is cleared by another task removing an entry from the queue through a call to KS_GetQueueData or one of its variants, the service puts the new entry into the queue and unblocks the waiting task.
Output This service returns a KSRC value as follows:
RC_GOOD if the service completes successfully.
RC_TICKOUT if the specified number of ticks elapses before an entry is removed from the full queue.
queue The handle of the queue.
psource A pointer to the source buffer.
counter The counter associated with the tick interval defined by ticks.
ticks The number of ticks on the specified counter to wait for the queue to have room.
Chapter 4: Queue Services 159
KS_PutQueueDataT
June 21, 2002
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
FE_UNINITIALIZED_QUEUE if the specified queue has not yet been initialized.
FE_ILLEGAL_COUNTER if the specified counter ID is not valid.
FE_UNINITIALIZED_COUNTER if the specified counter has not yet been initialized.
FE_NULL_SOURCEBUFFER if the pointer to the source buffer is null.
Example Example 4-17 inserts data found in the entry structure into the DATAQ queue. If the queue is full, it waits for 500 msec using the TIMEBASE counter or until the KS_PutQueueDataT operation is successful.
Example 4-17. Put Data Into Queue—Wait Number of Ticks If Queue is Full
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */#include "kqueue.h" /* DATAQ */#include "kproject.h" /* CLKTICK */
struct{ int type; int value;} entry;
/* enqueue packet of info into DATAQ */if (KS_PutQueueDataT (DATAQ, &entry, TIMEBASE, (TICKS)500/CLKTICK) == RC_GOOD){... queue operation was successful. Process the data}else{ ... counter expired. Queue was full longer than 500 ms. Handle it here.}
See Also KS_PutQueueData, page 156KS_PutQueueDataW, page 160
160 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
FE_UNINITIALIZED_QUEUE if the specified queue has not yet been initialized.
FE_NULL_SORUCEBUFFER if the pointer to the source buffer is null.
Example 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.
queue The handle of the queue.
psource A pointer to the source buffer.
Chapter 4: Queue Services 161
KS_PutQueueDataW
June 21, 2002
Example 4-18. Put Data Into Queue—Wait Until Queue Has Room
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */#include "kqueue.h" /* defines DATAQ */
struct{ int type; int value;} entry;
/* enqueue packet of info into DATAQ */KS_PutQueueDataW (DATAQ, &entry);
... continue
See Also KS_PutQueueData, page 156KS_PutQueueDataT, page 158
162 RTXC Kernel Services Reference, Volume 2
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.
Note: To use this service, you must enable the Dynamics attribute of the Queue class during system generation.
The time required to perform this operation varies with the number of queue names in use.
Output This service returns a KSRC value as follows:
RC_GOOD if the search and registration is successful. The service also stores the matching queue’s handle in the variable pointed to by pqueue.
RC_STATIC_OBJECT if the specified name belongs to a static queue.
RC_OBJECT_NOT_FOUND if the service finds no matching queue name.
Example Example 4-19 on page 163 locates a dynamic queue named DynMuxQ3 and obtains its handle for subsequent use.
pname A pointer to a null-terminated name string.
pqueue A pointer to a variable in which to store the queue handle.
Chapter 4: Queue Services 163
KS_UseQueue
June 21, 2002
Example 4-19. Read Queue Handle and Register It
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
KSRC ksrc;QUEUE dynqueue;
if ((ksrc = KS_UseQueue ("DynMuxQ3", &dynqueue)) != RC_GOOD){ if (ksrc == RC_OBJECT_NOT_FOUND) putline ("Queue DynMuxQ3 not found"); else putline ("Queue DynMuxQ3 is a static queue");}else{ ... queue was found and its handle is in dynqueue. Okay to use it now}
See Also KS_DefQueueProp, page 128KS_DefQueueName, page 126KS_OpenQueue, page 152
164 RTXC Kernel Services Reference, Volume 2
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
166 RTXC Kernel Services Reference, Volume 2
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.
Output This service returns a KSRC value as follows:
RC_GOOD if the service is successful.
RC_STATIC_OBJECT if the specified mailbox is not dynamic.
RC_OBJECT_NOT_INUSE if the specified mailbox does not correspond to an active dynamic mailbox.
RC_OBJECT_INUSE if the Current 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.
Chapter 5: Mailbox Services 167
KS_CloseMbox
June 21, 2002
Note: RC_OBJECT_INUSE does not necessarily indicate an error condition. The calling task must interpret its meaning.
Error This service may generate the following fatal error code:
FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.
Example In Example 5-1, the Current Task waits on a signal from another task indicating that it is time to close a dynamic mailbox. The handle of the dynamic semaphore associated with the signal is specified in dynsema. The handle of the dynamic mailbox is specified in dynmbox. When the signal is received, the Current Task closes the dynamic mailbox even if there are other users.
Example 5-1. Close Mailbox
#include "rtxcapi.h" /* RTXC Kernel Services prototypes */
MBOX dynmbox;SEMA dynsema;KSRC ksrc;
KS_TestSemaW (dynsema); /* wait for signal */
/* then close the mailbox */if ((ksrc = KS_CloseMbox (dynmbox)) != RC_GOOD){ /* okay if other users exist */ if (ksrc != RC_OBJECT_INUSE) { ... mailbox cannot be closed. Deal with it here. }}/* Otherwise, mailbox closed and released to the *//* free pool */
... Continue
See Also KS_OpenMbox, page 188KS_DefMboxProp, page 170
168 RTXC Kernel Services Reference, Volume 2
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.
Note: To use this service, you must enable the Dynamics attribute of the Mailbox class during system generation.
This service does not check for duplicate task names.
Output This service returns a KSRC value as follows:
RC_GOOD if the service completes successfully.
RC_STATIC_OBJECT if the mailbox being named is static.
RC_OBJECT_NOT_FOUND if the Dynamics attribute of the Mailbox class is not enabled.
RC_OBJECT_NOT_INUSE if the specified mailbox does not correspond to an active dynamic mailbox.
Error This service may generate the following fatal error code:
FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.
mbox The handle of the mailbox being defined.
pname A pointer to a null-terminated name string.
Chapter 5: Mailbox Services 169
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
#include "rtxcapi.h" /* RTXC Kernel Services prototypes */
MBOX dynmbox;
if (KS_DefMboxName (dynmbox, "NewMbox") != RC_GOOD){ ... Naming operation failed. Deal with it here}
... naming operation was successful. Continue
See Also KS_OpenMbox, page 188KS_GetMboxName, page 178KS_LookupMbox, page 186KS_UseMbox, page 191
170 RTXC Kernel Services Reference, Volume 2
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:
The default value for the Waiting Order attribute can be restored by ANDing the attributes field with ~ATTR_FIFO_ORDER.
Output This service does not return a value.
Error This service may generate the following fatal error code:
FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.
mbox The handle of the mailbox being defined.
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.
Chapter 5: Mailbox Services 171
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
#include "rtxcapi.h" /* RTXC Kernel Services prototypes */
MBOX dynmbox;MBOXPROP mprop;KSRC ksrc;
KS_GetMboxProp (dynmbox, &mprop); /* Get properties */
/* use priority waiters */mprop.attributes &= (~ATTR_FIFO_ORDER);
KS_DefMboxProp (dynmbox, &mprop); /* define properties */
... Continue
See Also KS_GetMboxProp, page 180INIT_MboxClassProp, page 184KS_OpenMbox, page 188
172 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.
FE_UNINITIALIZED_MBOX if the specified mailbox has not yet been initialized.
FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.
mbox The handle of the mailbox being defined.
sema The handle of a semaphore to associate with the mailbox.
Chapter 5: Mailbox Services 173
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.
174 RTXC Kernel Services Reference, Volume 2
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
Chapter 5: Mailbox Services 175
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
176 RTXC Kernel Services Reference, Volume 2
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.
Example 2-22 on page 62 shows the organization of the KCLASSPROP structure.
The attributes element of the Mailbox KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 5-1.
Output If successful, this service returns a pointer to a KCLASSPROP structure.
If the Mailbox class is not initialized, the service returns a null pointer ((KCLASSPROP *)0).
If pint is not null, the service returns the number of available dynamic mailboxes in the variable pointed to by pint.
Table 5-1. Mailbox Class Attributes and Masks
Attribute Mask
Static Names ATTR_STATIC_NAMES
Dynamics ATTR_DYNAMICS
Semaphores ATTR_SEMAPHORES
Chapter 5: Mailbox Services 177
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
#include "rtxcapi.h" /* RTXC Kernel Services prototypes */
KCLASSPROP *pmboxclassprop;int *free_dyn;
/* Get the mailbox kernel object class properties */if ((pmboxclassprop = KS_GetMboxClassProp (&free_dyn)) == (KCLASSPROP *)0){ putline ("Mailbox Class not initialized");}else{ ... mailbox object class properties are available for use free_dyn contains the number of free dynamic mailboxes}
See Also INIT_MboxClassProp, page 184
178 RTXC Kernel Services Reference, Volume 2
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).
Error This service may generate the following fatal error code:
FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.
Example In Example 5-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.
Chapter 5: Mailbox Services 179
KS_GetMboxName
June 21, 2002
Example 5-7. Read Mailbox Name
#include <stdio.h> /* standard i/o */#include "rtxcapi.h" /* RTXC Kernel Services prototypes */
static char buf[128];
MBOX dynmbox;char *pname;
if ((pname = KS_GetMboxName (dynmbox)) == (char *)0) sprintf (buf, "Mailbox %d has no name", dynmbox);
else sprintf (buf, "Mailbox %d name is %s", dynmbox, pname);
putline (buf);
See Also KS_DefMboxName, page 168KS_OpenMbox, page 188
180 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.
FE_UNINITIALIZED_MBOX if the specified mailbox has not yet been initialized.
Example 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
mbox The handle of the mailbox being queried.
pmboxprop A pointer to a Mailbox properties structure.
Chapter 5: Mailbox Services 181
KS_GetMboxProp
June 21, 2002
properties of the specified mailbox and then forces priority order waiting.
Example 5-8. Read Mailbox Properties
#include "rtxcapi.h" /* RTXC Kernel Services prototypes */
MBOX dynmbox;MBOXPROP mboxprop;
KS_GetMboxProp (dynmbox, &mboxprop); /* get properties */
/* force priority Waiting Order */mboxprop.attributes &= (~ATTR_FIFO_ORDER);
/* define properties */KS_DefMboxProp (dynmbox, &mboxprop);
... continue
See Also KS_GetMboxProp, page 180
182 RTXC Kernel Services Reference, Volume 2
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).
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.
FE_UNINITIALIZED_MBOX if the specified mailbox has not yet been initialized.
Example In Example 5-9 on page 183, the Current Task needs to know the handle of the Mailbox_Not_Empty semaphore associated with the MAINMBOX static mailbox. If it finds a semaphore already defined, it waits on that event or another associated with the MBXSEMA2 semaphore. If there is no semaphore defined, the Current Task
mbox The handle of the mailbox being queried.
Chapter 5: Mailbox Services 183
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
184 RTXC Kernel Services Reference, Volume 2
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.
Example 2-22 on page 62 shows the organization of the KCLASSPROP structure.
The attributes element of the Mailbox KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 5-1 on page 176.
Output This service returns a KSRC value as follows:
RC_GOOD if the service completes successfully.
RC_NO_RAM if the initialization fails because there is insufficient system RAM available.
Example During system initialization, the startup code must initialize the Mailbox object class before using any kernel service for that class. The system generation process produces a KCLASSPROP structure containing the information about the kernel object necessary for its initialization. In Example 5-10 on page 185, that structure is referenced externally to the code module.
pclassprop A pointer to a Mailbox object class properties structure.
Chapter 5: Mailbox Services 185
INIT_MboxClassProp
June 21, 2002
Example 5-10. Initialize Mailbox Object Class
#include "rtxcapi.h" /* RTXC Kernel Services prototypes */
extern const SYSPROP sysprop;extern const KCLASSPROP mboxclassprop;
KSRC userinit (void){ int objnum; KSRC ksrc;
/* initialize the kernel workspace, allocate RAM */ /* for required classes, etc. */
if ((ksrc = INIT_SysProp (&sysprop)) != RC_GOOD) { putline ("Kernel initialization failure"); return (ksrc); /* end initialization process */ } /* kernel is initialized */
/* Need to initialize the necessary kernel object */ /* classes */
/* Initialize the Mailbox Kernel Object class */ if ((ksrc = INIT_MboxClassProp (&mboxclassprop)) != RC_GOOD) { putline ("No RAM for Mailbox initialization"); return (ksrc); /* end initialization process */ }
... Continue with system initialization
}
See Also INIT_SysProp, page 310KS_GetMboxClassProp, page 176
186 RTXC Kernel Services Reference, Volume 2
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.
Output This service returns a KSRC value as follows:
RC_GOOD if the search succeeds. The service also stores the matching mailbox’s handle in the variable pointed to by pmbox.
RC_OBJECT_NOT_FOUND if the service finds no matching mailbox name.
pname A pointer to a null-terminated name string.
pmbox A pointer to a variable in which to store the mailbox handle, if found.
Chapter 5: Mailbox Services 187
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
#include <stdio.h> /* standard i/o */#include "rtxcapi.h" /* RTXC Kernel Services prototypes */
static char buf[128]; /* buffer space */
MBOX dynmbox;
/* lookup the mailbox name to see if it exists */if (KS_LookupMbox ("DynMbox2", &dynmbox) != RC_GOOD){ ... mailbox name not found. Deal with it}else{ /* mailbox named "DynMbox2" exists, */ /* display its name and handle */ sprintf (buf, "Mailbox %d is DynMbox2", dynmbox); putline (buf); /* output the text */}
See Also KS_DefMboxName, page 168KS_OpenMbox, page 188
188 RTXC Kernel Services Reference, Volume 2
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.
Note: To use this service, you must enable the Dynamics attribute of the Mailbox class during system generation.
If the pointer to the mailbox name is not null, the time required to perform this operation varies with the number of mailbox names in use.
If the pointer to the mailbox name is null, no search of mailbox names takes place and the time to perform the
pname A pointer to a null-terminated name string.
pmbox A pointer to a variable in which to store the mailbox handle.
Chapter 5: Mailbox Services 189
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.
Output This service returns a KSRC value as follows:
RC_GOOD if the service completes successfully. The service also stores the handle of the new dynamic mailbox in the variable pointed to by pmbox.
RC_OBJECT_ALREADY_EXISTS if the name search finds another mailbox whose name matches the specified string.
RC_NO_OBJECT_AVAILABLE if the name search finds no match but all dynamic mailboxes are in use.
Example Example 5-12, allocates a dynamic mailbox and names it DynMbox1. After the mailbox is opened successfully, it can be used to receive a message.
Example 5-12. Allocate Mailbox
#include "rtxcapi.h" /* RTXC Kernel Services prototypes */
KSRC ksrc;MBOX dynmbox;char *msg;MSGENV *penvelope;
if ((ksrc = KS_OpenMbox ("DynMbox1", &dynmbox)) != RC_GOOD){ if (ksrc == RC_OBJECT_ALREADY_EXISTS) putline ("DynMbox1 mailbox name in use"); else if (ksrc == RC_NO_OBJECT_AVAILABLE) putline ("No dynamic mailboxes available"); else putline ("Mailbox not a defined object class");}else{ /* mailbox was opened correctly. Use it now to receive a message */ msg = KS_ReceiveMsgW (dynmbox, &penvelope);...continue}
190 RTXC Kernel Services Reference, Volume 2
KS_OpenMbox
June 21, 2002
See Also KS_CloseMbox, page 166KS_LookupMbox, page 186KS_UseMbox, page 191
Chapter 5: Mailbox Services 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.
Note: To use this service, you must enable the Dynamics attribute of the Mailbox class during system generation.
The time required to perform this operation varies with the number of mailbox names in use.
Output This service returns a KSRC value as follows:
RC_GOOD if the search and registration is successful. The service also stores the matching mailbox’s handle in the variable pointed to by pmbox.
RC_STATIC_OBJECT if the specified name belongs to a static mailbox.
RC_OBJECT_NOT_FOUND if the service finds no matching mailbox name.
Example Example 5-13 on page 192 locates a dynamic mailbox by the name of DynMbox1 and obtains its handle for subsequent use.
pname A pointer to a null-terminated name string.
pmbox A pointer to a variable in which to store the mailbox handle.
192 RTXC Kernel Services Reference, Volume 2
KS_UseMbox
June 21, 2002
Example 5-13. Read Mailbox Handle and Register It
#include "rtxcapi.h" /* RTXC Kernel Services prototypes */
KSRC ksrc;MBOX dynmbox;
if ((ksrc = KS_UseMbox ("DynMbox1", &dynmbox)) != RC_GOOD){ if (ksrc == RC_OBJECT_NOT_FOUND) putline ("Mailbox DynMbox1 not found"); else putline ("Mailbox DynMbox1 is a static mailbox");}else{ ... mailbox was found and its handle is in dynmbox. Okay to use it now}
See Also 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
194 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
Errors This service may generate the following fatal error code:
FE_NULL_MSGENV if the pointer to the message envelope is null.
Example 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.
Chapter 6: Message Services 195
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
196 RTXC Kernel Services Reference, Volume 2
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.
Chapter 6: Message Services 197
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.
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.
FE_UNINITIALIZED_MBOX if the specified mailbox has not yet been initialized.
FE_INVALID_MSG_PRIORITY if the specified message priority value is not either URGENT or NORMAL.
FE_NULL_MSGENV if the pointer to the message envelope is null.
Example Example 6-2 on page 198 forwards a message at NORMAL priority to the MAILBOX3 static mailbox. The message is in a structure named msgbody.
198 RTXC Kernel Services Reference, Volume 2
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
Chapter 6: Message Services 199
KS_ForwardMsg
June 21, 2002
200 RTXC Kernel Services Reference, Volume 2
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).
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.
FE_UNINITIALIZED_MBOX if the specified mailbox has not yet been initialized.
Example In Example 6-3 on page 201, a task wants to receive the next message from any sender in the MYMAIL mailbox. If a message is received, it is processed and at the conclusion of processing, the sending task is notified. If no message is in the mailbox, the task executes special code to manage the situation.
mbox A handle for the mailbox from which the message is being received.
pmsgenv A pointer to a message envelope pointer.
Chapter 6: Message Services 201
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
202 RTXC Kernel Services Reference, Volume 2
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.
The messages are processed in the sequence they occur in the mailbox, as specified by the mailbox’s attributes.
If the mailbox is empty, the service blocks the requesting task and starts an internal alarm for the interval specified in ticks on the specified counter. The task remains blocked until either of two events occurs:
Another task sends a message to the specified mailbox and that message meets the reception criteria of the waiting task, or
The specified number of ticks elapses.
Output This service returns a pointer to the body of the received message if one was in the mailbox.
If the specified number of ticks elapses before the mailbox receives any mail, the service returns a null pointer ((void *)0).
mbox A handle for the mailbox from which the message is being received.
pmsgenv A pointer to a message envelope.
counter The counter associated with the interval defined by ticks.
ticks The number of ticks on the specified counter to wait for a message.
Chapter 6: Message Services 203
KS_ReceiveMsgT
June 21, 2002
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.
FE_UNINITIALIZED_MBOX if the specified mailbox has not yet been initialized.
FE_ILLEGAL_COUNTER if the specified counter ID is not valid.
FE_UNINITIALIZED_COUNTER if the specified counter has not yet been initialized.
Example In Example 6-4, the Current Task attempts to receive the next message from the MYMAIL mailbox. If there is no mail in the mailbox, the task is to wait for up to 500 msec using the TIMEBASE counter for mail to arrive. If the 500 msec period elapses without receipt of mail, the task is to resume and perform a special code segment to handle the timeout situation.
Example 6-4. Receive Message—Wait Number of Ticks If Necessary
#include "rtxcapi.h" /* 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
204 RTXC Kernel Services Reference, Volume 2
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.
The messages are processed in the sequence they occur in the mailbox, as specified by the mailbox’s attributes.
If the mailbox is empty, the service blocks the requesting task and waits for the mailbox to receive the next message.
Output This service returns a pointer to the body of the received message.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.
FE_UNINITIALIZED_MBOX if the specified mailbox has not yet been initialized.
Example 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.
mbox A handle for the mailbox from which the message is being received.
pmsgenv A pointer to a message envelope pointer.
Chapter 6: Message Services 205
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
206 RTXC Kernel Services Reference, Volume 2
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.
Each message has a user-defined priority of either URGENT_MSG or NORMAL_MSG. If the sending or forwarding task does not explicitly define the priority (priority =(MSG_PRIORITY)0), the kernel assigns the message a priority of NORMAL_MSG. Using the message priority, the kernel adds each message to the specified mailbox. Messages of NORMAL_MSG priority are added to the mailbox in chronological (FIFO) order. For messages having an URGENT_MSG priority, the kernel adds them at the front of the list of messages in the mailbox (LIFO order).
When sending or forwarding a message to a mailbox, there may or may not be a task waiting to receive it. If not, the kernel adds the message to the mailbox according to the message’s priority. If a task is waiting to receive a message from the mailbox, the kernel passes the message directly to the receiving task and unblocks it. If, as a result, the receiving task becomes ready to run, the kernel places it in the Ready List at a position determined by its priority. If the receiving task’s priority is higher than that of the sending or forwarding task, a preemption occurs.
mbox A handle for the mailbox to which the message is being sent.
pmsgenv A pointer to the message envelope.
pmsgbody A pointer to the body of the message.
priority The priority of the message.
Chapter 6: Message Services 207
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.
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.
FE_UNINITIALIZED_MBOX if the specified mailbox has not yet been initialized.
FE_INVALID_MSG_PRIORITY if the specified message priority value is not either URGENT or NORMAL.
FE_NULL_MSGENV if the pointer to the message envelope is null.
Example Example 6-6 on page 208 sends a message asynchronously at NORMAL priority to the MAILBOX3 static mailbox. The message is in a structure named msgbody. After sending the message, the example performs other operations and waits for the completion of processing of the message.
208 RTXC Kernel Services Reference, Volume 2
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) */
struct { int command; /* start of message body */ char data[10];} msgbody;
... 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
Chapter 6: Message Services 209
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.
Each message has a user-defined priority of either URGENT_MSG or NORMAL_MSG. If the sending or forwarding task does not explicitly define the priority (priority =(MSG_PRIORITY)0), the kernel assigns the message a priority of NORMAL_MSG. Using the message priority, the kernel adds each message to the specified mailbox. Messages of NORMAL_MSG priority are added to the mailbox in chronological (FIFO) order. For messages having an URGENT_MSG priority, the kernel adds them at the front of the list of messages in the mailbox (LIFO order).
When sending or forwarding a message to a mailbox, there may or may not be a task waiting to receive it. If not, the kernel adds the message to the mailbox according to the message’s priority. If a task is waiting to receive a message from the mailbox, the kernel passes the message directly to the receiving task and unblocks it. If, as a
mbox A handle for the mailbox to which to send the message.
pmsgenv A pointer to the message envelope.
pmsgbody A pointer to the body of the message.
priority The priority value of the message.
counter The counter associated with the interval defined by ticks.
ticks The number of ticks on counter to wait for an acknowledgment.
210 RTXC Kernel Services Reference, Volume 2
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 specified number of ticks elapses.
The service returns a value indicating the form of completion.
Note: A duration of zero (0) ticks does not cause an internal alarm to be started and is, therefore, equivalent to the KS_SendMsgW service.
Output This service returns a KSRC value as follows:
RC_GOOD if the message is successfully sent and processed within the specified timeout duration.
RC_TICKOUT if the specified number of ticks elapses and the message has not been received, that is, the message is still in the mailbox. If this situation occurs, the kernel removes the message from the mailbox.
RC_NO_ACK if the specified number of ticks elapses and the message has been received but not yet acknowledged, that is, the message is not in the mailbox.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.
FE_UNINITIALIZED_MBOX if the specified mailbox has not yet been initialized.
FE_ILLEGAL_COUNTER if the specified counter ID is not valid.
Chapter 6: Message Services 211
KS_SendMsgT
June 21, 2002
FE_UNINITIALIZED_COUNTER if the specified counter has not yet been initialized.
FE_INVALID_MSG_PRIORITY if the specified message priority value is not either URGENT or NORMAL.
FE_NULL_MSGENV if the pointer to the message envelope is null.
Example In Example 6-7 on page 212, the task synchronously sends a message to the MAILBOX3 static mailbox with an envelope address specified in msgenv and a message body in the msgbody structure. The priority of the message is URGENT. If the acknowledgment takes longer than 250 msec using the TIMEBASE counter, the example handles the situation with a special code segment.
212 RTXC Kernel Services Reference, Volume 2
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;
struct { int command; /* start of message body */ char data[10];} msgbody;
...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
Chapter 6: Message Services 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.
Each message has a user-defined priority of either URGENT_MSG or NORMAL_MSG. If the sending or forwarding task does not explicitly define the priority (priority =(MSG_PRIORITY)0), the kernel assigns the message a priority of NORMAL_MSG. Using the message priority, the kernel adds each message to the specified mailbox. Messages of NORMAL_MSG priority are added to the mailbox in chronological (FIFO) order. For messages having an URGENT_MSG priority, the kernel adds them at the front of the list of messages in the mailbox (LIFO order).
When sending or forwarding a message to a mailbox, there may or may not be a task waiting to receive it. If not, the kernel adds the message to the mailbox according to the message’s priority. If a task is waiting to receive a message from the mailbox, the kernel passes the message directly to the receiving task and unblocks it. If, as a result, the receiving task becomes ready to run, the kernel places it in the Ready List at a position determined by its priority. If the receiving task’s priority is higher than that of the sending or forwarding task, a preemption occurs.
mbox A handle for the mailbox to which the message is being sent.
pmsgenv A pointer to the message envelope.
pmsgbody A pointer to the body of the message.
priority The priority value of the message.
214 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_MBOX if the specified mailbox ID is not valid.
FE_UNINITIALIZED_MBOX if the specified mailbox has not yet been initialized.
FE_INVALID_MSG_PRIORITY if the specified message priority value is not either URGENT or NORMAL.
FE_NULL_MSGENV if the pointer to the message envelope is null.
Example In Example 6-8, the task synchronously sends a message to the MAILBOX3 static mailbox using an envelope located at the address given by the content of msgenv and whose body is contained in the msgbody structure. The priority of the message is NORMAL.
Example 6-8. Send Message—Wait for Acknowledgment
#include "rtxcapi.h" /* RTXC Kernel Services prototypes */#include "kmbox.h" /* defines MAILBOX3 */
MSGENV msgenv; /* Message envelope (required) */
struct { int command; /* start of message body */ char data[10];} msgbody;
... 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
Chapter 6: Message Services 215
KS_SendMsgW
June 21, 2002
See Also KS_SendMsg, page 206KS_SendMsgT, page 209
216 RTXC Kernel Services Reference, Volume 2
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.
Error This service may generate the following fatal error code:
FE_NULL_MSGENV if the pointer to the message envelope is null.
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.
pmsgenv A pointer to a message envelope.
Chapter 6: Message Services 217
KS_TestAck
June 21, 2002
Example 6-9. Test for Message Acknowledgment
#include "rtxcapi.h" /* RTXC Kernel Services prototypes */#include "kmbox.h" /* defines MAILBOX3 */
MSGENV msgenv; /* Message envelope (required) */
struct { int command; /* start of message body */ char data[10];} msgbody;
... fill in the message body content
/* send message asynchronously to MAILBOX3 at *//* NORMAL_MSG priority */KS_SendMsg (MAILBOX3, &msgenv, &msgbody, NORMAL_MSG);
... do some other processing
/* test now to see if message has been acknowledged */while (KS_TestAck (&msgenv) != RC_GOOD){ KS_SleepTask (TIMEBASE, (TICKS)5);}... continue after message is acknowledged
See Also KS_TestAckT, page 218KS_TestAckW, page 220KS_AckMsg, page 194
218 RTXC Kernel Services Reference, Volume 2
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
The specified number of ticks elapses.
Output This service returns a KSRC value as follows:
RC_GOOD if the message has been acknowledged.
RC_TICKOUT if the specified number of ticks elapses before the message is acknowledged and the message is still in the mailbox. If this situation occurs, the kernel removes the message from the mailbox.
RC_NO_ACK if the timeout expires and the message is not in the mailbox but has not yet been acknowledged.
pmsgenv A pointer to a message envelope.
counter The counter associated with the interval defined by ticks.
ticks The number of ticks on the specified counter to wait for an acknowledgment.
Chapter 6: Message Services 219
KS_TestAckT
June 21, 2002
Errors This service may generate one of the following fatal error codes:
FE_NULL_MSGENV if the pointer to the message envelope is null.
FE_ILLEGAL_COUNTER if the specified counter ID is not valid.
FE_UNINITIALIZED_COUNTER if the specified counter has not yet been initialized.
Example Example 6-10 sends a message asynchronously and tests for message acknowledgment. If the service determines that the acknowledgment has not occurred, it waits for no more than five ticks on the TIMEBASE counter.
Example 6-10. Test for Message Acknowledgment—Wait Number of Ticks for Acknowledgment
#include "rtxcapi.h" /* RTXC Kernel Services prototypes */#include "kmbox.h" /* defines MAILBOX3 */
MSGENV msgenv; /* Message envelope (required) */
struct { int command; /* start of message body */ char data[10];} msgbody;
... fill in the message body content
/* send message asynchronously to MAILBOX3 at NORMAL_MSG priority*/KS_SendMsg (MAILBOX3, &msgenv, &msgbody, NORMAL_MSG);
if (KS_TestAckT (&msgenv, TIMEBASE, (TICKS)5) != RC_GOOD){ ... internal counter expired. Deal with it here.}... continue when message is acknowledged
See Also KS_TestAck, page 216KS_TestAckW, page 220KS_AckMsg, page 194
220 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
Error This service may generate the following fatal error code:
FE_NULL_MSGENV if the pointer to the message envelope is null.
Example 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.
pmsgenv A pointer to a message envelope.
Chapter 6: Message Services 221
KS_TestAckW
June 21, 2002
Example 6-11. Test for Acknowledgment and Wait if Necessary
#include "rtxcapi.h" /* RTXC Kernel Services prototypes */#include "kmbox.h" /* defines MAILBOX3 */
MSGENV msgenv; /* Message envelope (required) */
struct { int command; /* start of message body */ char data[10];} msgbody;
... fill in the message body content
/* send message asynchronously to MAILBOX3 at NORMAL_MSG priority*/KS_SendMsg (MAILBOX3, &msgenv, &msgbody, NORMAL_MSG);
... do some processing before testing for acknowledgment
/* wait if message not acknowledged */KS_TestAckW (&msgenv);
... continue after message is acknowledged
See Also KS_TestAck, page 216KS_TestAckT, page 218KS_AckMsg, page 194
222 RTXC Kernel Services Reference, Volume 2
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
224 RTXC Kernel Services Reference, Volume 2
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).
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_PART if the specified partition ID is not valid.
FE_UNINITIALIZED_PART if the specified partition has not yet been initialized.
Example In Example 7-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.
Chapter 7: Memory Partition Services 225
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
226 RTXC Kernel Services Reference, Volume 2
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
The specified number of ticks elapses.
If a block becomes available, the service returns the address of the allocated memory block to the caller. If, however, the specified number of ticks elapses and causes the task to resume, the service returns a null pointer ((void *)0).
Output This service returns a pointer to the allocated memory block.
If the specified number of ticks elapses before there is memory to allocate, the service returns a null pointer ((void *)0).
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_PART if the specified partition ID is not valid.
part A handle for a partition.
counter The counter associated with the interval defined by ticks.
ticks The number of ticks on the specified counter to wait for an available block of memory.
Chapter 7: Memory Partition Services 227
KS_AllocBlkT
June 21, 2002
FE_UNINITIALIZED_PART if the specified partition has not yet been initialized.
FE_ILLEGAL_COUNTER if the specified counter ID is not valid.
FE_UNINITIALIZED_COUNTER if the specified counter has not yet been initialized.
Example Example 7-2 allocates a block of memory from the PART1 partition to be used for a character buffer. It stores the address of the block in the p character pointer. If there is no memory available at the time of the request, the example uses TIMEBASE to wait for a period of 50 msec for a block to become available before proceeding. If there is no memory available after 50 msec, it handles the situation with a special code segment.
Example 7-2. Allocate Block of Memory—Wait Number of Ticks If Necessary
#include "rtxcapi.h" /* 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
228 RTXC Kernel Services Reference, Volume 2
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.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_PART if the specified partition ID is not valid.
FE_UNINITIALIZED_PART if the specified partition has not yet been initialized.
Example In Example 7-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.
part A handle for a partition.
Chapter 7: Memory Partition Services 229
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
230 RTXC Kernel Services Reference, Volume 2
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.
Output This service returns a KSRC value as follows:
RC_GOOD if the service is successful.
RC_STATIC_OBJECT if the specified partition is not dynamic.
RC_OBJECT_NOT_INUSE if the specified partition does not correspond to an active dynamic partition.
RC_OBJECT_INUSE if the Current Task’s use of the specified partition is closed but the partition remains open for use by other tasks.
Note: RC_OBJECT_INUSE does not necessarily indicate an error condition. The calling task must interpret its meaning.
part The handle for the partition being closed.
Chapter 7: Memory Partition Services 231
KS_ClosePart
June 21, 2002
Error This service may generate the following fatal error code:
FE_ILLEGAL_PART if the specified partition ID is not valid.
Example In Example 7-4, the Current Task waits on a signal from another task indicating that it is time to close a dynamic memory partition. The handle of the dynamic partition is specified in dynpart. When the signal is received, the Current Task closes the memory partition.
Example 7-4. Close Memory Partition
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
PART dynpart;SEMA dynsema;
KS_TestSemaW (dynsema); /* wait for signal */
/* then close the partition */if (KS_ClosePart (dynpart) != RC_GOOD){ /* something is possibly wrong. Deal with it here */}... partition is closed. Continue
See Also KS_OpenPart, page 254KS_UsePart, page 256
232 RTXC Kernel Services Reference, Volume 2
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.
Note: To use this service, you must enable the Dynamics attribute of the Partition class during system generation.
This service does not check for duplicate partition names.
Output This service returns a KSRC value as follows:
RC_GOOD if the service completes successfully.
RC_STATIC_OBJECT if the memory partition being named is static.
RC_OBJECT_NOT_FOUND if the Dynamics attribute of the Partition class is not enabled.
RC_OBJECT_NOT_INUSE if the specified partition does not correspond to an active dynamic partition.
Error This service may generate the following fatal error code:
FE_ILLEGAL_PART if the specified partition ID is not valid.
part The handle of the partition being defined.
pname A pointer to a null-terminated name string.
Chapter 7: Memory Partition Services 233
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
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
PART dynpart;
if ((KS_DefPartName (dynpart, "NewPart")) != RC_GOOD){ ... something may be wrong. Deal with it here}
... naming operation was successful. Continue
See Also KS_OpenPart, page 254KS_GetPartName, page 244KS_LookupPart, page 252KS_UsePart, page 256
234 RTXC Kernel Services Reference, Volume 2
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:
part The handle of the partition being defined.
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.
The default value for the Waiting Order attribute can be restored by ANDing the attributes field with ~ATTR_FIFO_ORDER.
Chapter 7: Memory Partition Services 235
KS_DefPartProp
June 21, 2002
The value of size, the block size argument, must be at least the size of a data pointer.
Output This service does not return a value.
Error This service may generate one of the following fatal error codes:
FE_ILLEGAL_PART if the specified partition ID is not valid.
FE_NULL_PARTBASE if the specified partition base address is null.
FE_ZERO_PARTSIZE if the specified partition size is zero.
FE_ZERO_PARTCOUNT if the specified partition block count is zero.
Example During system initialization, the startup code must create and initialize the Partition object class and define all of the static partitions to the system before beginning multitasking operations, as shown in Example 7-6.
Example 7-6. Define Memory Partition Properties
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
extern const KCLASSPROP partclassprop;extern const PARTPROP partprop[];
int objnum;
if ((ksrc = INIT_PartClassProp (&partclassprop)) != RC_GOOD) { printf ("Partition initialization failed: %d", ksrc); } for (objnum = 1; objnum <= partclassprop.n_statics; objnum++) KS_DefPartProp (objnum, &partprop[objnum]);
See Also KS_GetPartProp, page 246INIT_PartClassProp, page 250KS_OpenPart, page 254
236 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_PART if the specified partition ID is not valid.
FE_UNINITIALIZED_PART if the specified partition has not yet been initialized.
FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.
Example In Example 7-7 on page 237, the Current Task associates the
part The handle of the partition being defined.
sema The handle of the semaphore to associate with the partition.
Chapter 7: Memory Partition Services 237
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
238 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
part The handle of a partition.
pblk A pointer to the block of memory to be freed.
Chapter 7: Memory Partition Services 239
KS_FreeBlk
June 21, 2002
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_PART if the specified partition ID is not valid.
FE_UNINITIALIZED_PART if the specified partition has not yet been initialized.
FE_NULL_PARTBLKPTR if the pointer to the block of memory is null.
Example Example 7-8 allocates a block of memory from the BUFFBLKS partition, uses it for a while as a character buffer, and then returns it to BUFFBLKS.
Example 7-8. Allocate and Free Memory Block
#include "rtxcapi.h" /* 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
240 RTXC Kernel Services Reference, Volume 2
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.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_PART if the specified partition ID is not valid.
FE_UNINITIALIZED_PART if the specified partition has not yet been initialized.
Example In Example 7-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.
Chapter 7: Memory Partition Services 241
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 */
static char buf[128];
KCOUNT nblks;
for (;;){ /* wait for the report period */ KS_SleepTask (TIMEBASE, (TICKS)30000/CLKTICK);
/* get block count */ nblks = KS_GetFreeBlkCount (PART32);
sprintf (buf, "PART32 contains %d blocks", nblks); putline (buf); /* report block count */}
242 RTXC Kernel Services Reference, Volume 2
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 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 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.
Chapter 7: Memory Partition Services 243
KS_GetPartClassProp
June 21, 2002
Output If successful, this service returns a pointer to a KCLASSPROP structure.
If the Partition class is not initialized, the service returns a null pointer ((KCLASSPROP *)0).
Example In Example 7-10, the Current Task needs access to the information contained in the KCLASSPROP structure for the partition object class.
Example 7-10. Read Memory Partition Object Class Properties
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
KCLASSPROP *ppartclassprop;int free_dyn;
/* Get the partition kernel object class properties */if ((ppartclassprop = KS_GetPartClassProp (&free_dyn)) == (KCLASSPROP *)0) { putline ("Partition Class not initialized");}else{ ... partition object class properties are available for use "free_dyn" contains the number of free dynamic partitions}
See Also INIT_PartClassProp, page 250
Table 7-1. Memory Partition Class Attributes and Masks
Attribute Mask
Static Names ATTR_STATIC_NAMES
Dynamics ATTR_DYNAMICS
Semaphores ATTR_SEMAPHORES
Statistics ATTR_STATISTICS
244 RTXC Kernel Services Reference, Volume 2
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).
Error This service may generate the following fatal error code:
FE_ILLEGAL_PART if the specified partition ID is not valid.
Example In Example 7-11 on page 245, the Current Task needs to report the name of the dynamic partition specified in dynpart.
part The handle of the partition being queried.
Chapter 7: Memory Partition Services 245
KS_GetPartName
June 21, 2002
Example 7-11. Read Memory Partition Name
#include <stdio.h> /* standard i/o */#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
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
246 RTXC Kernel Services Reference, Volume 2
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) is not equal to 0, waiters have chronological ordering.
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.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_PART if the specified partition ID is not valid.
part The handle of the partition being queried.
ppartprop A pointer to a Partition properties structure.
Chapter 7: Memory Partition Services 247
KS_GetPartProp
June 21, 2002
FE_UNINITIALIZED_PART if the specified partition has not yet been initialized.
Example In Example 7-13, the Current Task needs to ensure that the properties of the dynamic partition specified in dynpart are defined such that any tasks waiting to receive a block of memory from the partition are ordered in descending order of task priority. The task first reads the existing properties of the partition and then forces priority order waiting.
Example 7-13. Read Memory Partition Properties
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
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
248 RTXC Kernel Services Reference, Volume 2
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).
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_PART if the specified partition ID is not valid.
FE_UNINITIALIZED_PART if the specified partition has not yet been initialized.
Example In Example 7-14 on page 249, the Current Task needs to know the handle of the Partition_Not_Empty semaphore associated with the BLK256 static memory partition. If the return from KS_GetPartSema indicates there is no semaphore defined, the Current Task defines one using the BLK256NE semaphore, adds it to semalist, and waits for the indicated events.
part The handle of the partition being queried.
Chapter 7: Memory Partition Services 249
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
250 RTXC Kernel Services Reference, Volume 2
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 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 Partition KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 7-1 on page 243.
Output This service returns a KSRC value as follows:
RC_GOOD if the service completes successfully.
RC_NO_RAM if the initialization fails because there is insufficient system RAM available.
Example During system initialization, the startup code must initialize the Partition object class before using any kernel service for that class. In
pclassprop A pointer to a Partition object class properties structure.
Chapter 7: Memory Partition Services 251
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
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
extern const SYSPROP sysprop;extern const KCLASSPROP partclassprop;
KSRC userinit (void){ int objnum; KSRC ksrc;
/* initialize the kernel workspace, allocate RAM */ /* for required classes, etc. */
if ((ksrc = InitSysProp (&sysprop)) != RC_GOOD) { putline ("Kernel initialization failure"); return (ksrc); /* end initialization process */ } /* kernel is initialized */
/* Need to init the necessary kernel object classes */
/* Init the Memory Partition Kernel Object class */ if ((ksrc = INIT_PartClassProp (&partclassprop)) != RC_GOOD){ putline ("No RAM for Partition initialization"); return (ksrc); /* end initialization process */ }
... Continue with system initialization
}
See Also INIT_SysProp, page 310KS_GetPartClassProp, page 242
252 RTXC Kernel Services Reference, Volume 2
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.
Output This service returns a KSRC value as follows:
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.
pname A pointer to a null-terminated name string.
ppart A pointer to a variable in which to store the partition handle if found.
Chapter 7: Memory Partition Services 253
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
#include <stdio.h> /* standard i/o */#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
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
254 RTXC Kernel Services Reference, Volume 2
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.
Note: To use this service, you must enable the Dynamics attribute of the Partition class during system generation.
If the pointer to the partition name is not null ((char *)0), the time required to perform this operation varies with the number of partition names in use.
If the pointer to the partition name is null, no search of partition names takes place and the time to perform the
pname A pointer to a null-terminated name string.
ppart A pointer to a variable in which to store the partition handle if found.
Chapter 7: Memory Partition Services 255
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.
Output This service returns a KSRC value as follows:
RC_GOOD if the service completes successfully. The service also stores the handle of the allocated partition in the variable pointed to by ppart.
RC_OBJECT_ALREADY_EXISTS if the name search finds another memory partition whose name matches the given string.
RC_NO_OBJECT_AVAILABLE if the name search finds no match but all dynamic memory partitions are in use.
Example Example 7-17 allocates a dynamic partition and names it DynPart1.
Example 7-17. Allocate and Name Memory Partition
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
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
256 RTXC Kernel Services Reference, Volume 2
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.
Note: To use this service, you must enable the Dynamics attribute of the Partition class during system generation.
The time required to perform this operation varies with the number of partition names in use.
Output This service returns a KSRC value as follows:
RC_GOOD if the search and registration is successful. The service also stores the matching memory 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.
pname A pointer to a null-terminated name string.
ppart A pointer to a variable in which to store the partition handle if found.
Chapter 7: Memory Partition Services 257
KS_UsePart
June 21, 2002
Example 7-18. Read Memory Partition Handle and Register It
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
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
258 RTXC Kernel Services Reference, Volume 2
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
260 RTXC Kernel Services Reference, Volume 2
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.
Output This service returns a KSRC value as follows:
RC_GOOD if the service is successful.
RC_STATIC_OBJECT if the specified mutex is not dynamic.
RC_OBJECT_NOT_INUSE if the specified mutex does not correspond to an active dynamic mutex.
RC_OBJECT_INUSE if the Current Task’s use of the specified mutex is closed but the mutex remains open for use by other tasks.
Note: RC_OBJECT_INUSE does not necessarily indicate an error condition. The calling task must interpret its meaning.
Error This service may generate the following fatal error code:
FE_ILLEGAL_MUTX if the specified mutex ID is not valid.
mutex A handle for a mutex.
Chapter 8: Mutex Services 261
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
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
MUTX dynmutx;SEMA dynsema;
KS_TestSemaW (dynsema); /* wait for signal */
KS_CloseMutx (dynmutx); /* then close the mutex */
See Also KS_OpenMutx, page 284
262 RTXC Kernel Services Reference, Volume 2
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.
Note: To use this service, you must enable the Dynamics attribute of the Mutex class during system generation.
This service does not check for duplicate mutex names.
Output This service returns a KSRC value as follows:
RC_GOOD if the service completes successfully.
RC_STATIC_OBJECT if the mutex being named is static.
RC_OBJECT_NOT_FOUND if the Dynamics attribute of the Mutex class is not enabled.
RC_OBJECT_NOT_INUSE if the specified mutex does not correspond to an active dynamic mutex.
Error This service may generate the following fatal error code:
FE_ILLEGAL_MUTX if the specified mutex ID is not valid.
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.
pname A pointer to a null-terminated name string.
Chapter 8: Mutex Services 263
KS_DefMutxName
June 21, 2002
Example 8-2. Close Mutex
#include <stdio.h> /* standard i/o */#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
KSRC ksrc;MUTX dynmutx;
if ((ksrc = KS_DefMutxName (dynmutx, "NewMutx")) != RC_GOOD){ if (ksrc == RC_OBJECT_NOT_FOUND) putline ("Dynamic Mutexes are not enabled"); else if (ksrc == RC_STATIC_OBJECT) { sprintf (buf, "Mutex %d is a static mutex", dynmutx); putline (buf); } else { sprintf (buf, "Mutex %d is not attached for use", dynmutx); putline (buf); }}
... naming operation was successful. Continue
See Also KS_OpenMutx, page 284KS_GetMutxName, page 272KS_LookupMutx, page 282KS_UseMutx, page 296
264 RTXC Kernel Services Reference, Volume 2
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.
Chapter 8: Mutex Services 265
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.
Output This service does not return a value.
Error This service may generate the following fatal error code:
FE_ILLEGAL_MUTX if the specified mutex ID is not valid.
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.
266 RTXC Kernel Services Reference, Volume 2
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
Chapter 8: Mutex Services 267
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.
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_MUTX if the specified mutex ID is not valid.
FE_UNINITIALIZED_MUTX if the specified mutex has not yet been initialized.
FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
FE_UNINITIALIZED_SEMA if the specified semaphore 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.
268 RTXC Kernel Services Reference, Volume 2
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)
Chapter 8: Mutex Services 269
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
270 RTXC Kernel Services Reference, Volume 2
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.
Example 2-22 on page 62 shows the organization of the KCLASSPROP structure.
The attributes element of the Mutex KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 8-1 on page 271.
Output If successful, this service returns a pointer to a KCLASSPROP structure.
If the Mutex class is not initialized, the service returns a null pointer ((KCLASSPROP *)0).
pint A pointer to a variable in which to store the number of available dynamic mutexes.
Chapter 8: Mutex Services 271
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
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
KCLASSPROP *pmutxclassprop;int free_dyn;
/* Get the mutex kernel object class properties */if ((pmutxclassprop = KS_GetMutxClassProp (&free_dyn)) == (KCLASSPROP *)0){ putline ("Mutex Class not initialized");}else{ ... mutex object class properties are available for use "free_dyn" contains the number of available dynamic mutexes}
See Also INIT_MutxClassProp, page 280
Table 8-1. Mutex Class Attributes and Masks
Attribute Mask
Static Names ATTR_STATIC_NAMES
Dynamics ATTR_DYNAMICS
Semaphores ATTR_SEMAPHORES
Inversion ATTR_INVERSION
Statistics ATTR_STATISTICS
272 RTXC Kernel Services Reference, Volume 2
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).
Error This service may generate the following fatal error code:
FE_ILLEGAL_MUTX if the specified mutex ID is not valid.
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.
Chapter 8: Mutex Services 273
KS_GetMutxName
June 21, 2002
Example 8-6. Read Mutex Name
#include <stdio.h> /* standard i/o */#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
static char buf[128];
MUTX dynmutx;char *pname;
if ((pname = KS_GetMutxName (dynmutx)) == (char *)0) sprintf (buf, "Mutex %d has no name", dynmutx);else sprintf (buf, "Mutex %d name is %s", dynmutx, pname);
putline (buf); /* send buffer to console */
See Also KS_DefMutxName, page 262KS_OpenMutx, page 284
274 RTXC Kernel Services Reference, Volume 2
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).
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_MUTX if the specified mutex ID is not valid.
FE_UNINITIALIZED_MUTX if the specified mutex has not yet been initialized.
Example 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.
mutex The handle of the mutex being queried.
pcount A pointer to a variable in which to store the current nesting level of mutex locking.
Chapter 8: Mutex Services 275
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
276 RTXC Kernel Services Reference, Volume 2
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:
Output This service does not return a value.
mutex The handle of the mutex being queried.
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) is not equal to 0, waiters have chronological ordering.
If (attributes & ATTR_FIFO_ORDER) equals 0, waiters are ordered by priority.
Inversion Indicates whether the kernel should apply priority inversion to the mutex:
If (attributes & ATTR_INVERSION) is not equal to 0, the kernel applies priority inversion to the mutex.
If (attributes & ATTR_INVERSION) equals 0, the kernel does not apply priority inversion to the mutex.
Chapter 8: Mutex Services 277
KS_GetMutxProp
June 21, 2002
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_MUTX if the specified mutex ID is not valid.
FE_UNINITIALIZED_MUTX if the specified mutex has not yet been initialized.
Example In Example 8-8, the Current Task ensures that the Priority Inversion attribute of the dynamic mutex specified in dynmutx is defined so that the kernel handles mutex priority inversion should it occur. The task first reads the existing properties of the specified mutex and then forces priority inversion In the example, the mutex has not yet been used by any task.
Example 8-8. Read Mutex Properties
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
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
278 RTXC Kernel Services Reference, Volume 2
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).
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_MUTX if the specified mutex ID is not valid.
FE_UNINITIALIZED_MUTX if the specified mutex has not yet been initialized.
Example In Example 8-9 on page 279, the Current Task needs to know the handle of the Mutex_Not_Busy semaphore associated with the MAINMUTX static mutex. If it finds a semaphore already defined, it waits on that event or another associated with the MTXSEMA2 semaphore. If there is no semaphore defined for MAINMUTX, the
mutex The handle of the mutex being queried.
Chapter 8: Mutex Services 279
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
280 RTXC Kernel Services Reference, Volume 2
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.
Example 2-22 on page 62 shows the organization of the KCLASSPROP structure.
The attributes element of the Mutex KCLASSPROP structure supports the class property attributes and corresponding masks listed in Table 8-1 on page 271.
Output This service returns a KSRC value as follows:
RC_GOOD if the service completes successfully.
RC_NO_RAM if the initialization fails because there is insufficient system RAM available.
Example During system initialization, the startup code must initialize the Mutex object class before using any kernel service for that class. The system generation process produces a KCLASSPROP structure containing the information about the kernel object necessary for its initialization. In Example 8-10 on page 281, that structure is referenced externally to the code module.
pclassprop A pointer to a Mutex object class properties structure.
Chapter 8: Mutex Services 281
INIT_MutxClassProp
June 21, 2002
Example 8-10. Initialize Mutex Object Class
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
extern const SYSPROP sysprop;extern const KCLASSPROP mutxclassprop;
KSRC userinit (void){ KSRC ksrc;
/* initialize the kernel workspace and allocate RAM */ /* for required classes, etc. */
if ((ksrc = INIT_SysProp (&sysprop)) != RC_GOOD) { putline ("Kernel initialization failure"); return (ksrc); /* end initialization process */ } /* kernel is initialized */
/* Need to initialize the necessary kernel */ /* object classes */
/* Initialize the Mutex kernel object class */ if ((ksrc = INIT_MutxClassProp (&mutxclassprop)) != RC_GOOD) { putline ("No RAM for Mutex init"); return (ksrc); /* end initialization process */ }
... Continue with system initialization
}
See Also INIT_SysProp, page 310KS_GetMutxClassProp, page 270
282 RTXC Kernel Services Reference, Volume 2
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.
Output This service returns a KSRC value as follows:
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
pname A pointer to a null-terminated name string.
pmutex A pointer to a variable in which to store the mutex handle.
Chapter 8: Mutex Services 283
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
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
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
284 RTXC Kernel Services Reference, Volume 2
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.
Note: To use this service, you must enable the Dynamics attribute of the Mutex class during system generation.
If the pointer to the mutex name is not null ((char *)0), the time required to perform this operation varies with the number of mutex names in use.
If the pointer to the mutex name is null, no search of mutex names takes place and the time to perform the service is
pname A pointer to a null-terminated name string.
pmutex A pointer to a variable in which to store the mutex handle.
Chapter 8: Mutex Services 285
KS_OpenMutx
June 21, 2002
fixed. You can define the mutex name at a later time with a call to the KS_DefMutxName service.
Output This service returns a KSRC value as follows:
RC_GOOD if the service completes successfully. The service also stores the handle of the allocated mutex in the variable pointed to by pmutex.
RC_OBJECT_ALREADY_EXISTS if the name search finds another mutex whose name matches the specified string.
RC_NO_OBJECT_AVAILABLE if the name search finds no match but all dynamic mutexes are in use.
Example Example 8-12 allocates a dynamic mutex and names it MuxChnl2Mutx. If the name is already being used, the example outputs a message on the console.
Example 8-12. Allocate and Name Mutex
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
KSRC ksrc;MUTX dynmutx;
if ((ksrc = KS_OpenMutx ("MuxChnl2Mutx", &dynmutx)) != RC_GOOD){ if (ksrc == RC_OBJECT_ALREADY_EXISTS) putline ("MuxChnl2Mutx mutex name in use"); else if (ksrc == RC_NO_OBJECT_AVAILABLE) putline ("No dynamic mutexes available"); else putline ("Mutexes object class not defined");}
... mutex was opened correctly. Okay to use it now
See Also KS_CloseMutx, page 260KS_LookupMutx, page 282KS_UseMutx, page 296
286 RTXC Kernel Services Reference, Volume 2
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.
Output This service returns a KSRC value as follows:
RC_GOOD if the mutex is released and not nested.
RC_NESTED if the calling task is the mutex owner but has not issued as many releases as locks.
RC_BUSY if the mutex is owned by another task.
RC_ILLEGAL_USE if the mutex is not owned by any task.
mutex The handle of the mutex being released.
Chapter 8: Mutex Services 287
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.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_MUTX if the specified mutex ID is not valid.
FE_UNINITIALIZED_MUTX if the specified mutex has not yet been initialized.
Example In Example 8-13, the Current Task needs to update a memory resident database without other tasks preempting the operation. Therefore, the task needs exclusive access to the database during the update operation. The database resource is associated with the DATABASE mutex. After performing the update, the task permits other tasks to access the database.
Example 8-13. Release Mutex
#include "rtxcapi.h" /* 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
288 RTXC Kernel Services Reference, Volume 2
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.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_MUTX if the specified mutex ID is not valid.
FE_UNINITIALIZED_MUTX if the specified mutex has not yet been initialized.
Example In Example 8-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.
Chapter 8: Mutex Services 289
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
290 RTXC Kernel Services Reference, Volume 2
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
The specified number of ticks elapses.
Output This service returns a TASK type value as follows:
mutex The handle of the mutex being tested.
pcount A pointer to a variable in which to store the nesting level of the mutex.
counter The counter associated with the interval defined by ticks.
ticks The number of ticks on the specified counter to wait for the mutex to become available.
Chapter 8: Mutex Services 291
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.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_MUTX if the specified mutex ID is not valid.
FE_UNINITIALIZED_MUTX if the specified mutex has not yet been initialized.
FE_ILLEGAL_COUNTER if the specified counter ID is not valid.
FE_UNINITIALIZED_COUNTER if the specified counter has not yet been initialized.
Example In Example 8-15 on page 292, the Current Task wants to output a system status report to the system printer without interspersed messages from other system monitors. When the report is finished, the task releases exclusive use of the printer.
If the printer is unavailable for a period of five seconds relative to the SECCLK counter, the example executes a code segment to handle the situation and then tries it again.
292 RTXC Kernel Services Reference, Volume 2
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
Chapter 8: Mutex Services 293
KS_TestMutxT
June 21, 2002
294 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
Errors This service may generate one of the following fatal error codes:
FE_ILLEGAL_MUTX if the specified mutex ID is not valid.
FE_UNINITIALIZED_MUTX if the specified mutex has not yet been initialized.
Example In Example 8-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.
mutex The handle of the mutex being tested.
Chapter 8: Mutex Services 295
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
296 RTXC Kernel Services Reference, Volume 2
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.
Note: To use this service, you must enable the Dynamics attribute of the Mutex class during system generation.
The time required to perform this operation varies with the number of mutex names in use.
Output This service returns a KSRC value as follows:
RC_GOOD if the search is successful. The service also stores the matching 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.
pname A pointer to a null-terminated name string.
pmutex A pointer to a variable in which to store the mutex handle.
Chapter 8: Mutex Services 297
KS_UseMutx
June 21, 2002
Example 8-17. Read Mutex Handle and Register It
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
KSRC ksrc;MUTX dynmutx;
if ((ksrc = KS_UseMutx ("DynMuxMutx3", &dynmutx)) != RC_GOOD){ if (ksrc == RC_STATIC_OBJECT) putline ("DynMuxMutx3 is a static mutex"); else putline ("Mutex DynMuxMutx3 name not found");}
... mutex was found and its handle is in dynmutx. Okay to use it now
See Also KS_DefMutxProp, page 264KS_DefMutxName, page 262KS_OpenMutx, page 284
298 RTXC Kernel Services Reference, Volume 2
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
300 RTXC Kernel Services Reference, Volume 2
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.
Chapter 9: Special Services 301
XX_AllocSysRAM
June 21, 2002
Example 9-1. Allocate System RAM from Zone 3
#include "rtxcapi.h" /* RTXC Kernel Services prototypes */
void *p;
if ((p = KS_AllocSysRAM (256)) == (void *)0){ ... Deal with no memory available}else{ ... Allocation was successful}
302 RTXC Kernel Services Reference, Volume 2
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.
Output This service does not return a value.
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.
Chapter 9: Special Services 303
XX_DefFatalErrorHandler
June 21, 2002
Example 9-2. Define Fatal Error Function
#include "rtxcapi.h" /* RTXC Kernel Services prototypes */
void fehandler (FEPACKET *fepacket); /* prototype for Error Handler */
KS_DefFatalErrorHandler (fehandler); /* define error handler function */... continue
/* System Error Handler for Fatal RTXC Usage */void fehandler (FEPACKET *fepacket){ ...Do what has to be done here: display the point of error, kill the system, whatever is suitable to the application return (1); /* have RTXC abort Current Task */}
See Also XX_GetFatalErrorHandler, page 305
304 RTXC Kernel Services Reference, Volume 2
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)
Inputs This service has no inputs.
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
Chapter 9: Special Services 305
XX_GetFatalErrorHandler
June 21, 2002
XX_GetFatalErrorHandler Get the system error function.
Zones TS_GetFatalErrorHandler KS_GetFatalErrorHandler
Synopsis int (*)(void *)) XX_GetFatalErrorHandler (void)
Inputs This service has no inputs.
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
#include "rtxcapi.h" /* RTXC Kernel Services prototypes */
extern void fehandler (FEPACKET *fepacket);
if (KS_GetFatalErrorHandler () == (void (*)(FEPACKET *fepacket))0) KS_DefFatalErrorHandler (fehandler);
...Error handler is now in place, continue
See Also XX_DefFatalErrorHandler, page 302
306 RTXC Kernel Services Reference, Volume 2
KS_GetSysProp
June 21, 2002
KS_GetSysProp Get the system properties.
Synopsis const SYSPROP * KS_GetSysProp (void)
Inputs This service has no inputs.
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.
Chapter 9: Special Services 307
KS_GetSysProp
June 21, 2002
Example 9-5. Read System Properties
#include "rtxcapi.h" /* RTXC Kernel Services prototypes */
static char buf[128];SYSPROP *psysprop = KS_GetSysProp ();
putline (buf);
... continue
See Also INIT_SysProp, page 310
308 RTXC Kernel Services Reference, Volume 2
KS_GetVersion
June 21, 2002
KS_GetVersion Get the version number of the Kernel.
Synopsis unsigned long KS_GetVersion (void)
Inputs This service has no inputs.
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)
Chapter 9: Special Services 309
KS_GetVersion
June 21, 2002
Example 9-6. Read Version Number
#include <stdio.h> /* standard i/o */#include "rtxcapi.h" /* RTXC Kernel Services prototypes */
static char buf[128];union RTXCver{ unsigned long version; struct { unsigned short sysnum; /* reserved for system use */ unsigned char ver; /* version number */ unsigned char rel; /* release number */ } vr;}curVR;
curVR.version = KS_GetVersion (); /* get RTXC version */sprintf (buf, "Current RTXC version.release is %d.%d", curVR.vr.ver, curVR.vr.rel);putline (buf); /* display version # */
... continue
310 RTXC Kernel Services Reference, Volume 2
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.
Chapter 9: Special Services 311
INIT_SysProp
June 21, 2002
Output The service returns a KSRC value as follows:
RC_GOOD if the service completes successfully.
RC_VERSION_MISMATCH if the version number passed in the SYSPROP structure is different from the version stored within the RTXC Kernel.
Example During system initialization, the startup code must initialize the kernel properties before initializing the needed kernel object classes. The system generation process produces a structure of type SYSPROP that contains the information about the system necessary for its initialization. Example 9-7 on page 312 externally references that structure and outputs any error messages to the console.
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
312 RTXC Kernel Services Reference, Volume 2
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 */
... Continue with system initialization
}
See Also KS_GetSysProp, page 306
Chapter 9: Special Services 313
KS_Nop
June 21, 2002
KS_Nop Execute the minimal path through the kernel dispatcher (no operation).
Synopsis void KS_Nop (void)
Inputs This service has no inputs.
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.
Output This service does not return a value.
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
#include <stdio.h> /* standard i/o */#include "rtxcapi.h" /* RTXC Kernel Services prototypes */
static char buf[128];
int i;TICKS timestamp, et; /* sleep for one tick to sync with clock */KS_SleepTask (TIMEBASE, 1);KS_ElapsedCounterTicks (TIMEBASE, ×tamp); /* initialize timestamp */for (i = 0; i < 10000; i++) KS_Nop ();
/* read elapsed time after 10000 loops */et = KS_ElapsedCounterTicks (TIMEBASE, ×tamp);sprintf (buf, "10000 KS_Nop calls in %d ticks", et);putline (buf); /* display the results */
...continue
314 RTXC Kernel Services Reference, Volume 2
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.
Chapter 9: Special Services 315
KS_UserService
June 21, 2002
Example 9-9. Execute Non-RTXC Function as Kernel Service
#include "rtxcapi.h" /* RTXC Kernel Services prototypes */
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);
316 RTXC Kernel Services Reference, Volume 2
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.
318 RTXC Kernel Services Reference, Volume 2
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
320 RTXC Kernel Services Reference, Volume 2
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
322 RTXC Kernel Services Reference, Volume 2
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
324 RTXC Kernel Services Reference, Volume 2
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
326 RTXC Kernel Services Reference, Volume 2
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
328 RTXC Kernel Services Reference, Volume 2
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
330 RTXC Kernel Services Reference, Volume 2
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
332 RTXC Kernel Services Reference, Volume 2
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
allocating 152closing 124code examples
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
allocating 100closing 80code examples
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
334 RTXC Kernel Services Reference, Volume 2
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
336 RTXC Kernel Services Reference, Volume 2
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