Realtime Communication System for netX Kernel API Function...

www.hilscher.com

Operating System Manual

Realtime Communication System for netX

Kernel API Function Reference

Language: English

rcX - Kernel API Function Reference • 2

Hilscher Gesellschaft für Systemautomation mbH – Rheinstr. 15 – D 65795 Hattersheim Edition 4 – OS:rcX Kernel API Function Reference#EN – 2008/01

Copyright Information Copyright 2005 - 2007 Hilscher GmbH. All rights reserved. No part of this publication may be reproduced. Translated into another language, stored in a retrieval system, or transmitted in any form by means, electronic, me-chanical, photocopying, recording, or otherwise, without the prior written consent of the Au-thor. The Author makes no warranty of any kind with regard to this material, including but not lim-ited to the implied warranties of merchantability and fitness for a particular purpose. The Au-thor assumes also no responsibility for any errors that may appear in this document. And fi-nally the Author makes no commitment to update or to keep current the information con-tained in this document.



Revision History Revi-sion

Date Chap-ter

Notes

11/01/2005 - Initial Release 1 11/22/2005 - Changed Prototype of rX_MtxCreateMutex()

New function rX_DiaGetInformationField(), rX_MbxGetTaskMailbox()

2 03/01/2005 - New function rX_SysSpinLock(), rX_SysSpinUnlock(), rX_QueGetQueueLoad() rX_MemAllocateNamedMemory() Function Prototype of rX_SysCreateTask() cor-rected

3 01/18/2005 New function rX_SysEnterKernel() 4 23/01/2008 Updated for rcX version V2.x



Table Of Contents

1 INTRODUCTION ..................................................................................................7

1.1 About this Technical Description ............................................................................................ 7

1.2 Overview..................................................................................................................................... 8

1.3 Hard Real-Time Architecture.................................................................................................... 9

1.4 Preemptive Kernel ..................................................................................................................... 9

1.5 Dynamic Objects ....................................................................................................................... 9

1.6 Rich API Functions.................................................................................................................... 9

1.7 Tool Support .............................................................................................................................. 9

1.8 Tasks ........................................................................................................................................ 10 1.8.1 Static Task......................................................................................................................... 10 1.8.2 Dynamic Task.................................................................................................................... 10 1.8.3 Task Enter-Function and Task-Initialization ...................................................................... 10 1.8.4 Task Leave-Function......................................................................................................... 10 1.8.5 Task State ......................................................................................................................... 11

1.9 Interrupt Service Routines (ISR) ............................................................................................ 13

1.10 Drivers (DRV) ........................................................................................................................... 13

1.11 Hardware Abstraction Layer (HAL)........................................................................................ 13

2 KERNEL API FUNCTIONS ................................................................................14

2.1 One Include-File to include all rcX specific Include-Files – Header File rX_Includes.h... 14

2.2 rcX common Data Types Definitions – Header-File rX_Types.h ........................................ 15

2.3 System Services – Header-File AP_Sys.h ............................................................................ 16 2.3.1 rX_SysEnterKernelExt() – Enters the RX-Kernel Module ................................................. 16 2.3.2 rX_SysGetSystemTicks() – Get the Current System-Timer Tick Value............................ 18 2.3.3 rX_SysSetSystemTicks() – Set the System-Timer Tick Count Value ............................... 19 2.3.4 rX_SysLockIrq() – Disables all Hardware Interrupts ......................................................... 20 2.3.5 rX_SysUnlockIrq() – Allows Hardware Interrupts.............................................................. 21 2.3.6 rX_SysGetSystemCycletime() – Gets the Cycletime of the System timer ........................ 22 2.3.7 rX_SysCreateHookSystemStatus() – Install a System Status Changes Callback............ 24 2.3.8 rX_SysSpinLock() – Attempts to acquire a Shared Variable and to lock it ....................... 26 2.3.9 rX_SysSpinUnlock() – Releases a previously Locked Shared Variable ........................... 28 2.3.10 rX_SysLockScheduler() – Supresses the Task Pre-emption............................................ 30 2.3.11 rX_SysUnlockScheduler() – Enables Task Pre-emption................................................... 32

2.4 Task Services – Header-File AP_Task.h ............................................................................... 33 2.4.1 rX_SysCreateTask() – Creates a Dynamic Task at Runtime............................................ 33 2.4.2 rX_SysIdentifyTask() – Identify a Task by Name .............................................................. 36 2.4.3 rX_SysSetTaskInitialized() – Signal the End of the Current Task Initialization................. 38 2.4.4 rX_SysDeleteTask() – Delete a Task ................................................................................ 40 2.4.5 rX_SysSleepTask() – Suspend the current Task for a specified Time ............................. 42 2.4.6 rX_SysDelayTaskUntil() – Delay a Task for a specified Time........................................... 44 2.4.7 rX_SysWakeupTask() – Abort the Sleep State of a Task ................................................. 46



2.4.8 rX_SysBlockTask() – Stop the scheduling of the specified Task...................................... 48 2.4.9 rX_SysResumeTask() – Resume a previously blocked Task ........................................... 50 2.4.10 rX_SysTerminateTask() – Terminate a Task .................................................................... 52 2.4.11 rX_SysChangePriority() – Change the Priority of a Task.................................................. 53 2.4.12 rX_SysGetOwnInstance() – Get the Instance number of the calling Task........................ 55

2.5 Queue Services – Header-File AP_Que.h ............................................................................. 56 2.5.1 rX_QueCreateQueue() – Create a Queue of dynamic Size and Elements....................... 56 2.5.2 rX_QueIdentifyQueue() – Identify a Queue by Name ....................................................... 58 2.5.3 rX_QueWaitForPacket() – Wait for a Queue-Packet to be received................................. 60 2.5.4 rX_QuePeekPacket() – Check for a Queue-Packet in a Queue ....................................... 62 2.5.5 rX_QueSendPacket() – Send a Packet to a Queue in FIFO principle .............................. 64 2.5.6 rX_QueSendPriorityPacket() – Send a Packet to a Queue in LIFO principle ................... 66 2.5.7 rX_QueDeleteQueue() – Delete a Queue ......................................................................... 68 2.5.8 rX_QueFlushQueue() – Delete all Packets in a Queue .................................................... 70 2.5.9 rX_QueGetQueueLoad() – Return the current Fill Level of a Queue................................ 72

2.6 Event Services – Header-File AP_Eve.h ............................................................................... 74 2.6.1 rX_EveCreateEventGroup() – Create an Eventgroup for 32 possible Events .................. 74 2.6.2 rX_EveIdentifyEventGroup() – Identify an Eventgroup by Name...................................... 76 2.6.3 rX_EveSetupEventGroup() – Set the Eventgroup Parameters......................................... 78 2.6.4 rX_EveWaitForEventGroup() – Wait on Eventgroup Events............................................. 80 2.6.5 rX_EveChangeEventGroup() – Change Events in an Eventgroup ................................... 82 2.6.6 rX_EveDeleteEventGroup() – Delete an Eventgroup........................................................ 84

2.7 Signal Services – Header-File AP_Sig.h ............................................................................... 86 2.7.1 rX_SigCreateSignal() – Create a Signal............................................................................ 86 2.7.2 rX_SigIdentifySignal() – Identify a Signal by Name .......................................................... 88 2.7.3 rX_SigWaitForSignal() – Wait for a Signal ........................................................................ 90 2.7.4 rX_SigSetSignal() – Set a Signal ...................................................................................... 92 2.7.5 rX_SigResetSignal() – Reset a Signal .............................................................................. 94 2.7.6 rX_SigDeleteSignal() – Delete a Signal ............................................................................ 96

2.8 Mutex Services – Header-File AP_Mtx.h ............................................................................... 98 2.8.1 rX_MtxCreateMutex() – Create a Mutex ........................................................................... 98 2.8.2 rX_MtxIdentifyMutex() – Identify a Mutex by Name ........................................................ 100 2.8.3 rX_MtxLockMutex() – Lock a Mutex................................................................................ 102 2.8.4 rX_MtxUnlockMutex() – Unlock a Mutex......................................................................... 104 2.8.5 rX_MtxDeleteMutex() – Delete a Mutex .......................................................................... 106

2.9 Semaphore Services – Header-File AP_Sem.h .................................................................. 108 2.9.1 rX_SemCreateSemaphore() –Create a Semaphore ....................................................... 108 2.9.2 rX_SemIdentifySemaphore() – Identify a Semaphore by Name..................................... 110 2.9.3 rX_SemWaitForSemaphore() – Wait to get a Semaphore.............................................. 112 2.9.4 rX_SemGetSemaphore() – Try to get a Semaphore....................................................... 114 2.9.5 rX_SemPutSemaphore() – Return a retrieved Semaphore ............................................ 116 2.9.6 rX_SemDeleteSemaphore() – Delete a Semaphore....................................................... 118 2.9.7 rX_SemWaitForSemaphoreCount() – Wait for a Semaphore......................................... 120 2.9.8 rX_SemClearSemaphoreCount() – Clear the Semaphore Count Value......................... 123

2.10 Timer Services – Header-File AP_Tim.h ............................................................................. 125 2.10.1 rX_TimCreateTimer() – Creates an Application specific Timer....................................... 125 2.10.2 rX_TimSetTime() – Sets the current time of a Timer ...................................................... 127 2.10.3 rX_TimSetReload() – Sets the reload value of a Timer .................................................. 129 2.10.4 rX_TimGetTime() – Gets the current timer value of a Timer........................................... 131 2.10.5 rX_TimResetTimer() – Reloads a Timer ......................................................................... 133 2.10.6 rX_TimStopTimer() – Stops a Timer ............................................................................... 134 2.10.7 rX_TimHaltTimer() – Halts a Timer ................................................................................. 135 2.10.8 rX_TimResumeTimer() – Resumes a halted Timer ........................................................ 137 2.10.9 rX_TimDeleteTimer() – Deletes a Timer ......................................................................... 139 2.10.10 rX_TimCreateCycle() – Activates a Timer for periodic Task Activation ...................... 141 2.10.11 rX_TimWaitForCycle() – Wait for a cyclic Timer ......................................................... 143

rcX - Kernel API Function Reference Introduction • 6


2.10.12 rX_TimResetCycle() – Reset a cyclic Task Timer....................................................... 145 2.10.13 rX_TimDeleteCycle() – Delete a cyclic Timer.............................................................. 147

2.11 Diagnostic Services – Header-File AP_Dia.h...................................................................... 149 2.11.1 rX_DiaCreateInformationField() – Creates an Information structure .............................. 149 2.11.2 rX_DiaGetInformationField() – Gets a Task’s Information structure reference.............. 151 2.11.3 rX_DiaCreateHookTaskStatus() – Installs a Callback function for Task Status changes153 2.11.4 rX_DiaSetTaskStatus() – Changes the Status Code of a Task ...................................... 155 2.11.5 rX_DiaGetTaskStatus() – Returns the Status Code of a Task........................................ 156

2.12 Memory Services – Header-File AP_Mem.h........................................................................ 158 2.12.1 rX_MemAllocateMemory() – Requests a Memory Block from the Pool.......................... 158 2.12.2 rX_MemFreeMemory() – Returns an allocated Memory Block to the Pool..................... 160 2.12.3 rX_MemCreateSharedMemory() – Creates one Memory to Share ................................ 162 2.12.4 rX_MemIdentifySharedMemory() – Identifies a Shared Memory by Name .................... 164 2.12.5 rX_MemGetSharedMemoryInfo() – Gets the Shared Memory Parameters.................... 166 2.12.6 rX_MemLockSharedMemory() – Locks Shared Memory against Concurrent Accesses 168 2.12.7 rX_MemUnlockSharedMemory() – Releases the lock to a Shared Memory .................. 170

2.13 Triple Buffer Services – Header-File AP_Mem.h................................................................ 172 2.13.1 rX_MemCreateTripleBuffer() – Creates a Triple Buffer for Exchanging Data................. 172 2.13.2 rX_MemIdentifyTripleBuffer() – Identifies a Triple Buffer by Name ................................ 175 2.13.3 rX_MemExchangeGetCurrentBuffer() – Get the Current Write Buffer............................ 177 2.13.4 rX_MemExchangeBuffer() – Exchange the Write Buffer and Mark Triple Buffer as updated 179 2.13.5 rX_MemGetExchangedBuffer() – Gets the Current Read Buffer.................................... 181 2.13.6 rX_MemGetExchangedBufferWait() – Wait for an Update and retrieve the Current Buffer 183 2.13.7 rX_MemEnableTripleBufferCallback() – Sets an Update Callback on a Triple Buffer .... 185 2.13.8 rX_MemDisableTripleBufferCallback() – Clears the Update Callback on a Triple Buffer187 2.13.9 rX_MemDeleteTripleBuffer() – Deletes a Triple Buffer ................................................... 189

2.14 Fault Services – Header-File AP_Flt.h................................................................................. 191 2.14.1 rX_FltLoggFault() – Records a Task event ..................................................................... 191 2.14.2 rX_FltFatalError() – Reports a Heavy Runtime Error ...................................................... 193

2.15 Verbose Output Services – Header-File AP_Vbs.h............................................................ 194 2.15.1 rX_VbsPrintf() – Prints a formatted string to debug port ................................................. 194

3 CONTACT ........................................................................................................196



1 Introduction 1.1 About this Technical Description This guide is intended for software developers programming embedded Real-Time applica-tions under the realtime communication-system for netX, short rcX. You should be familiar with standard Real-Time operating system functions and the C pro-gramming language. In the subsequent chapters, this manual describes the application interface (API) functions that can be used to write own application tasks.



1.2 Overview



1.3 Hard Real-Time Architecture The architecture of rcX is organized to provide excellent hard Real-Time performance for embedded netX applications from small to medium sizes. The internal kernel design covering the object data structures, inter-task communication and time management are highly opti-mized in their sizes and access speed. The result is that the rcX offers a very low interrupt latency and fast task switching time.

1.4 Preemptive Kernel The rcX Kernel is a pre-emptive, full featured, multitasking operating system that can operate with a scalable number of tasks.

1.5 Dynamic Objects All rcX objects such as tasks, interrupts, timers, and inter-task communication objects can be created and deleted during runtime. Or statically configured due to a “front-end” configuration file, allowing an easy, centralized configuration of your project and provides an overview of the configured resources.

1.6 Rich API Functions rcX provides a wide variety of API functions for the following inter-task communication ob-jects:

• Messages • Queues • Mutexes • Semaphores • Timers • Event groups • Signals

1.7 Tool Support rcX is tightly integrated with the HiTop tool suite delivered by the company Hitex aimed mak-ing your debugging job easier. Internal task states as well as states of the different kind of objects can be monitored.



1.8 Tasks

1.8.1 Static Task Static Tasks are created by the kernel at system start-up. They are configured inside a con-figuration table named atrXStaticTasks[…] within the Config.c-File, defining parameters like the name and all other Task parameters such as priority or stack size. One of these parame-ters defines if a task is put into READY or SUSPENDED state after its creation. The parame-ters within the Config.c file are explained in the “rcX Configuration Manual”. Static tasks are supposed to be alive as long as the whole system is alive. But nevertheless static tasks can be deleted at runtime like any other task.

1.8.2 Dynamic Task Dynamic tasks can be created and deleted during run-time with the rX_SysCreateTask(…) or the rX_SysDeleteTask(…) functions. Often, dynamic tasks are used to run multiple instances of common static code. The number of instances is only limited by the available system re-sources.

1.8.3 Task Enter-Function and Task-Initialization After the kernel has been initialized, all configured static tasks within the Config.c file are created. rcX starts all tasks, configured with RX_TASK_AUTO_START, in an ascending or-der based on their position in the static task list, starting with the first list entry. A task has to call the rX_SysSetTaskInitialized() function, to signal the end of its initialization sequence. This function suspends the calling task immediately and starts the next following one. rX_SysSetTaskInitialized() does not return before all tasks have signalled their end of the initialization. Attention must be paid if functions are called during the initialization phase that could lock-up the start sequence. This could delay the Initialization time and can also lead into a dead-lock situation. rcX does not supervise the initialization time of the tasks. Therefore, if a task does not finish their initialization function, the whole system initialization will not continue at all. A start sequence like this has the advantage that the resources one task needs from another task can be easily granted by just listing a task before the other in the static task list, inde-pendent of whether the task has a higher priority or not.

1.8.4 Task Leave-Function A tasks under rcX can define a leave function void (* fnTskLve)(void* pvInpt). If defined, the rcX will call this function whenever a task is deleted or a system shutdown is performed. Usually a task does not have a chance to unload and free the used resources when it is de-leted (“killed”). In this case, the allocated resources of the task remain active, even if the task is not available any more. Defining a leave function allows the system to deallocate and free the task resources. Fur-thermore the leave function can be used to inform other tasks, e.g. a connected network, about the termination. All API functions are callable by the leave function, even if they are pre-emptive. Allocating new resources (e.g by calling rX_BarCreateMailbox(…) or rX_MemAllocateMemory(…)) is not permitted. When rcX gets a request to delete a task, it changes the tasks current context immediately to the leave function, independent of the current task state and the task is re-scheduled accord-ing to its priority.



Setting the leave-function pointer to NULL disables the leave function.

1.8.5 Task State A task under rcX can be in different states:

The task with the highest priority, which is ready, will be dispatched when the next system call in either an interrupt, a task or wait completion will enter the scheduler. There are three possibilities how a task leaves RUNNING state:

• a task with higher priority is set ready by a system call • the task suspends itself • the task calls a function waiting for a currently not satisfied condition

There are four possibilities how a task enters READY state:

• a task with a higher priority is activated • the task is in the waiting state and the wait condition is satisfied • the task is in the suspended state and reactivated by a call to rX_SysResumeTask • the task was created in ready state



1.8.5.1 Running (execution)

If a task is in the running state, it is executed on the CPU. This state remains active until the Task is placed into another state (Ready, Waiting or Suspended). In a single CPU system, only one task can be in running state. 1.8.5.2 Ready (executable)

The Ready state signals a task is ready to run. This means if no other task, with a higher pri-ority is active, the task with the highest priority which is in the Ready state will be scheduled with the next call to the task dispatcher. 1.8.5.3 Waiting (self wait)

Waiting signals a task is waiting for an event. In this state the task does not consume any CPU cycles. This state can have several resons:

• The task is trying to receive a message, waits for a barrier, semaphore, mutex or a another synchronisation object.

• The task has called a sleep and waits for the given time delay to expire.

1.8.5.4 Suspended (forcible wait)

A task is in suspended state when it has been either blocked by calling rX_SysBlockTask or created in suspended state. The suspended task has to be set into Ready state by calling rX_SysResumeTask through another task until it will be scheduled. 1.8.5.5 Dormant (terminated)

This state indicates that the task has been terminated.



1.9 Interrupt Service Routines (ISR) Interrupts are a main aspect of real-time systems. Upon detection of an interrupt, the processor saves key information about the current pro-gram execution (usually on the stack) and transfers control to a predefined program area. This predefined program area is commonly called an interrupt service routine (ISR). Interrupts can occur in any operating state and also during execution of an ISR.

1.10 Drivers (DRV) Drivers are the functional part for accessing peripherals from a task context. They provide defined API functions which interfaces between the calling task and the hardware abstraction layer (HAL) modules. Driver functions are executed in the context of the calling task, with the same task priority. Hardware access takes place by Hardware Abstraction Layer modules which are interacting directly with the hardware registers.

1.11 Hardware Abstraction Layer (HAL) A Hardware Abstraction Layer builds the interface between the operating system and the hardware peripherals. Controlled by the driver modules, HALs are allowed to access the reg-isters and variables of the hardware directly. Because of the different interfaces of the Pe-ripherals within different kind of platforms, HALs differ from one hardware platform to another one. At the end, HALs are the only modules that have to be exchanged if an rcX application is ported from one platform to another. The assumption is of course that rcX HALs do exist for the desired type of platform you want to port your application to.

rcX - Kernel API Function Reference Kernel API Functions • 14


2 Kernel API Functions The explanation of the kernel API functions in the next chapters follows a defined format. The beginning of each declaration includes a text explaining of the raw functionality of the service. This is followed by the Function Syntax in „C“-Convention defining the proto-type of the service. Prototypes can be found in the corresponding application header file us-ing following rule set: A rX_Xxx…() function is prototyped in the AP_Xxx.h header file. Next the Function Arguments are listed and explained in detail. Function arguments build the interface between the calling task and rcX internals. Each function’s first argument is always a handle to an object, the task wants to operate with, while the following arguments are related to this object. A task is not allowed to change and to reference system wide vari-ables or Hardware Registers directly. This would cause protection faults if Memory Manage-ment Hardware Support is enabled. Except some simple functions, each rcX function is returning a Function Return Value. This value informs the caller task about the success or failure of the called function. It is strongly recommended to check each function which provides a return value and to evaluate it for all possible and listed error codes. This makes it easier at debugging time to find errors within your written applications. Due to restrictions in the rcX kernel, only certain API functions may be called during different operational states of the kernel. rcX distinguishes 4 different operational states:

• Initialization: All program executions between processor reset and entering the rcX scheduled Kernel. These functions are not pre-emptive and do not call the scheduler. In the view of a task initialization, is the time period between the first call of the task and the task calling it’s rX_SetTaskInitialized() function.

• Task: Program execution called by the rcX scheduler during runtime. Additionally, RX_MODE_INTERRUPT_TASK type interrupts on rcX V2 belong to this category as well.

• Interrupt Service Routines: Running separately in interrupt context. • Application Timer: Created by rX_TimCreateTimer() function

Because of these restrictions, each function chapter contains the Allowed to be Called by paragraph explaining which process may use the function without causing a kernel violation. The Pre-emption possible statement indicates if the task calling that function can be pre-empted which means interrupted and suspended by the scheduler if the function-execution causes a task at a higher priority to become ready. Finally, each function includes Example Code to provide the user with a short example on how to use the function in a application.

2.1 One Include-File to include all rcX specific Include-Files – Header File rX_Includes.h

Including all rcX specific includes files <#include “rX_Includes.h”> All dependencies and rcX-related files included when an application is built up from scratch are within one common include file named rX_Includes.h. This is the only header file that needs to be included by your application to make use of all prototypes and definitions of rcX.



2.2 rcX common Data Types Definitions – Header-File rX_Types.h

Providing Type Definitions <#include “rX_Types.h”> Variables defined in rcX and source code examples follow the Hungarian Variable Naming Convention. This means that each declared variable has a variable prefix which reflects the type of the variable that is defined. The rcX API supports the following types and variable prefixes: Variable PREFIX

Data Types Definitions

Notes

Examples

c INT8 (signed char)

8 bit signed byte INT8 cMySigned8; // signed char

sz CHAR (char) Array of 8 bit signed byte

CHAR szMyString[ ]; // ASCII-String

f BOOLEAN 8Bit,16bit,32bit un-signed integer processor depend-ant

BOOLEAN fMyFlag; // TRUE/FALSE

b UINT8 (un-signed char)

8 bit unsigned byte UINT8 bMyUnsigned8; // unsigned char

s

INT16 (short) 16 bit signed inte-ger

INT16 sMySigned16; // short

us UINT16 (un-signed short)

16 bit unsigned in-teger

UINT16 usMyUnsigned16; // un-signed short

l INT32 (long) 32 bit signed long INT32 lMySigned32; // long ul UINT32 (un-

signed long) 32 unsigned long UINT32 ulMyUnSigned32; // unsigned

long i INT (integer) 8 bit, 16bit, 32bit

signed integer processor depend-ant

INT iMySigned; // signed integer

u UINT(unsigned integer)

8 bit, 16bit, 32bit unsigned integer processor depend-ant

UINT uMySigned; // unsigned integer

h RX_HANDLE (handle)

Handle to Object RX_HANDLE hMyHandle; // Handle

fn Function void fnMyFunction; // function

p Pointer to any Data Type

pMyPointer; // Pointer

pv Pointer to a VOID Data Type

pvMyVoidPointer // Pointer to void

a Array of any Data type

UINT8 abMyUnsigned8Array; // Array of bytes

e ENUM Declaration of a variable of type Structure ENUM

RX_TASK_PRIORITY eThrhld // Structure variable of type ENUM



2.3 System Services – Header-File AP_Sys.h Providing System Services <#include “AP_Sys.h”>

2.3.1 rX_SysEnterKernelExt() – Enters the RX-Kernel Module This function is the initial function that needs to be called to start the rcX operating system. The parameters of the function is the RX_ENTERKERNEL_PARAM_T. This structure is de-scribed in detail in the “rcX Configuration Manual”. Function Syntax in „C“-Convention RX_FATAL FAR rX_SysEnterKernelExt( CONST RX_ENTERKERNEL_PARAM_T* ptKernelParam) Function Arguments Argument

Description

ptKernelParam Pointer to a Kernel Configuration Data Structure. This structure is de-scribed in detail in the “rcX Configuration Manual”.

Function Return Values Return Value

Description

none Without having detected a fatal error this function will never return.

RX_FATAL The definitions of the fatal errors the kernel may return here can be found the the rX_Fatal.h header file.

Allowed to be called by Main function. Pre-emption possible No



Example Code

STATIC CONST FAR RX_STATIC_TASK_T FAR atrXStaticTasks[] = { {"TlrTimer", /* Set Identification */ TSK_PRIO_3, TSK_TOK_1, /* Set Priority,and Token ID */ 0, /* Set Instance to 0 */ &auTskStack_TlrTimer[0], /* Pointer to Stack */ TSK_STACK_SIZE_TLR_TIMER, /* Size of Task Stack */ 0, /* Threshold to maximum possible value */ RX_TASK_AUTO_START, /* Start task automatically */ (void (FAR*)(void FAR*))TaskEnter_TlrTimer,/* Task function to schedule */ NULL, /* Function called when Task is deleted */ (UINT32)&tTlrTimerPrm[0], /* Startup Parameter */ {0,0,0,0,0,0,0,0} /* Reserved Region */ } } STATIC CONST FAR RX_PERIPHERAL_CONFIG_T atrXCfgPre[] = { {RX_PERIPHERAL_TYPE_TIMER,atrXHwTim,MAX_CNT(atrXHwTim)}, {RX_PERIPHERAL_TYPE_INTERRUPT,atrXInt,MAX_CNT(atrXInt)}, }; STATIC RX_ENTERKERNEL_PARAM_T trXEnterKernelParam = { NETX_FREQUENCY_100MHZ, {TSK_PRIO_DEF_RX_TIMER, 350}, /* Static task list */ {atrXStaticTasks, MAX_CNT(atrXStaticTasks), /* Initialization of additional kernel modules */ {NULL, 0}, /* Kernel Peripherals */ {atrXCfgPre, MAX_CNT(atrXCfgPre), /* Driver Peripherals */ {NULL, 0}, /* Jump table */ {NULL, 0}, /* Callback just before static task creation */ NULL, /* Middlewares */ {NULL, 0}, /* Default values for reserved parameters */ NULL, {TRUE, TRUE}, {TRUE}, /* Early callback */ NULL, /* MMU Table Translation Base Pointer (16kB in size) */ {0x80000000} }; INT main(void) { /* Boot the Kernel */ erXFat = rX_SysEnterKernelExt(&trXEnterKernelParam); /* We should never return to here, if so we have a fatal error */ while(erXFat!=RX_OK); }



2.3.2 rX_SysGetSystemTicks() – Get the Current System-Timer Tick Value

The system timer tick count is incremented with each system timer tick. This value can be used to determine how much has been passed since the last call to it. The physical amount of time associated with one timer tick is configured within the Config.C file. Usually it ranges between 1 to 5 milliseconds. This value can be obtained by using the function rX_SysGetSystemCycletime(). Function Syntax in „C“-Convention UINT32 rX_SysGetSystemTicks( void ) Function Arguments Argument

Description

None None Function Return Values Return Value

Description

UINT32 ulTicks The current system timer tick value. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No Example Code

UINT32 ulNow; … ulNow = rX_SysGetSystemTicks(); /* Get the current system-timer tick value */ … if(ulNow > 10000) { … }



2.3.3 rX_SysSetSystemTicks() – Set the System-Timer Tick Count Value

rX_SysSetSystemTicks() sets the system timer tick count value to the new value. Function Syntax in „C“-Convention void rX_SysSetSystemTicks( UINT32 ulTcks ) Function Arguments Argument

Description

ulTicks New value for the system timer tick count. Function Return Values Return Value

Description

None None Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No Example Code

… rX_SysSetSystemTicks(5000); /* Set current system timer tick value to 5000 */ …



2.3.4 rX_SysLockIrq() – Disables all Hardware Interrupts rX_SysLockIrq() locks all hardware interrupts within the CPU globally. This condition will re-main until the function rX_SysUnlockIrq() is called. Attention! The IRQ lock will be intermitted during the following task states: WAITING or SUS-PENDED. Function Syntax in „C“-Convention void rX_SysLockIrq( void ) Function Arguments Argument

Description


Description

None None Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No. Example Code

/* Disable all interrupts globally, no interruption from this point */ rX_SysLockIrq(); /* critical section begins here */ … /* critical section ends here */ /* Re-enable all interrupts again */ rX_SysUnlockIrq();



2.3.5 rX_SysUnlockIrq() – Allows Hardware Interrupts This function re-enables all CPU hardware interrupts. This function must be used after the function rX_SysLockIrq() function has been called. Function Syntax in „C“-Convention void rX_SysUnlockIrq( void ) Function Arguments Argument

Description


Description


… /* Disable all interrupts globally, no interruption of execution*/ rX_SysLockIrq(); … /* Re-enable all interrupts again */ rX_SysUnlockIrq();



2.3.6 rX_SysGetSystemCycletime() – Gets the Cycletime of the System timer

rX_SysGetSystemCycletime() returns the period time of the kernel system timer in multiples of microseconds. The returned value can be used to calculate relative tick values for all rcX functions that need timer tick values as parameter. For example, if you need to wait 5 seconds in your application using the rX_SysSleepTask() function, you will use the following calculation: system timer ticks = time in seconds * 1000000 / rX_SysGetSystemCycletime() Function Syntax in „C“-Convention UINT rX_SysGetSystemCycletime( void ) Function Arguments Argument

Description


Description

uSysTimPrd Current system period time in microseconds Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No.



Example Code

void TaskInit(void) { UINT uSysTim; /* local variable to hold the system cycle time */ … /* Get first the cycle time to be able to calculate relative timings */ uSysTim = rX_SysGetSystemCycletime(); … }



2.3.7 rX_SysCreateHookSystemStatus() – Install a System Status Changes Callback

rX_SysCreateHookSystemStatus() allows a task to install an application specific function to be called when a system status variable has been changed. The system status variables are held in a structure named RX_SYSTEM_STATUS_T and a pointer to this structure is part of the call-back function’s parameter list. The call-back is not allowed to call any function that will cause pre-emption. rX_SysCreateHookSystemStatus() takes a pre-allocated memory block of RX_HOOK_SIZE bytes as a handle. Function Syntax in „C“-Convention RX_RESULT rX_SysCreateHookSystemStatus( RX_HANDLE hHok, RX_RESULT (CALLBACK* fnNtfy) (RX_SYSTEM_STATUS_T* ptSysSta, void* pvInp), void* pvInp ) Function Arguments Argument

Description

hHok Pointer to the memory location the task had created a memory re-source for previously.

fnNtfy

Pointer to the function that shall be called in the case of a system sta-tus change. The function itself has two parameters.

• Pointer that points to the System Status Block of rcX with the structure RX_SYSTEM_STATUS_T.

• A void* Pointer which points to callback specific data.

pvInp Callback specific data pointer that is provided as second parameter to the specified callback function.


Description

RX_OK (0x0000)

Hook successfully installed.



Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible No. Example Code

/* This is the call-back function that is to be called */ RX_RESULT CALLBACK StatChange(RX_SYSTEM_STATUS_T* ptSta,

void* pvPrm) { ... return(RX_OK) } void TaskInit(void) { RX_HANDLE hHok; UINT uInst = 5; /* Instance number to be handed over to the call-back func-tion */ /* Allocate memory for the Hook first of all */ rX_MemAllocateMemory(&hHok,RX_HOOK_SIZE); ... /* Install the System Status Hook in case the status has been changed */ rX_SysCreateHookSystemStatus(hHok,StatChange,&uInst); … }



2.3.8 rX_SysSpinLock() – Attempts to acquire a Shared Variable and to lock it

Spinlocks are used to busy-wait for a certain lock variable. rX_SysSpinLock locks a particular shared lock variable. Function Syntax in „C“-Convention void rX_SysSpinLock( UINT* puiSpinlock ) Function Arguments Argument

Description

puiSpinlock Pointer to the lock variable Function Return Values Return Value

Description

None None Allowed to be called by Tasks only. Pre-emption possible Yes.



Example Code

typedef struct OBJECT_Ttag { UINT uLock; UINT8 abData[16]; } OBJECT_T; … OBJECT_T tObj; … /* Get now the access to the object */ rX_SysSpinLock(&tObj.uLock); /* We are now safe against other task access in this object */ tObj.abData[0] = 0xFF; /* Unlock the spin right after having done our job */ rX_SysSpinUnlock(&tObj.uLock); …



2.3.9 rX_SysSpinUnlock() – Releases a previously Locked Shared Variable

This function releases a previously locked shared lock variable. Function Syntax in „C“-Convention void rX_SysSpinUnlock( UINT* puiSpinlock ) Function Arguments Argument

Description

puiSpinlock Pointer to the lock variable Function Return Values Return Value

Description

None None Allowed to be called by Tasks only. Pre-emption possible Yes.



Example Code

typedef struct OBJECT_Ttag { UINT uLock; UINT8 abData[16]; } OBJECT_T; … OBJECT_T* tObj; … /* Get now the access to the object */ rX_SysSpinLock(&tObj->uLock); /* We are now safe against other task access in this object */ tObj.abData[0] = 0xFF; /* Unlock the spin right after having done our job */ rX_SysSpinUnlock(&tObj->uLock);



2.3.10 rX_SysLockScheduler() – Supresses the Task Pre-emption This function locks the scheduler and prevents any further task scheduling. The currently running task will never beeing pre-empted by another tasks. Attention: It is not allowed to call any system function which will change the task state while the scheduler is locked. This applies to all functions which are defined as pre-emptable. Calling such a function will result in a system dead-lock. However, interrupts are not locked and still working. Unlocking the scheduler must be done by calling rX_SysUnlockScheduler(). Function Syntax in „C“-Convention void rX_SysLockScheduler( void ) Function Arguments Argument

Description


Description

None None Allowed to be called by Tasks Pre-emption possible No



Example Code

UINT8 abMem[200]; … /* suppress the Task pre-emption */ rX_SysLockScheduler(); /* access to memory is now safe from other tasks */ abMem[5] = 0x01; abMem[10] = 0x0a; abMem[7] = 0x0c; /* unlock scheduler now */ rX_SysUnlockScheduler();



2.3.11 rX_SysUnlockScheduler() – Enables Task Pre-emption This function unlocks the task scheduling previously locked due to the call to X_SysLockScheduler() and enables normal task pr-emption. After this call the task with the highest priority, which is ready, will be activated. Function Syntax in „C“-Convention void rX_SysUnlockScheduler( void ) Function Arguments Argument

Description


Description

None None Allowed to be called by Tasks Pre-emption possible Yes Example Code

UINT8 abMem[200]; … /* suppress the Task pre-emption */ rX_SysLockScheduler(); /* access to memory is now save */ abMem[5] = 0x01; abMem[10] = 0x0a; abMem[7] = 0x0c; /* unlock scheduler now */ rX_SysUnlockScheduler();



2.4 Task Services – Header-File AP_Task.h Providing Task Services <#include “AP_Task.h”>

2.4.1 rX_SysCreateTask() – Creates a Dynamic Task at Runtime rX_SysCreateTask() creates a task that starts execution at the specified task entry function pointer. Function Syntax in „C“-Convention RX_RESULT rX_SysCreateTask( STRING* pszTskNam, void (* fnTsk)(void* pvInpt), void* pvInpt, void* pvStck, UINT uStckSiz, UINT uSrtMod, RX_TASK_PRIORITY eThrhld, RX_TASK_PRIORITY ePrio, RX_TASK_TOKEN eTok, UINT uInst, void (* fnTskLve) (void* pvInpt) ) Function Arguments Argument

Description

pszTskNam

Task name Pointer to a NUL terminated string of a length of 16 bytes, including the terminating 0 character.

fnTsk Function pointer to the task entry function. pvInpt Pointer to input data passed to the task entry function.

pvStck

Pointer to the stack region of the task. It will always point to the be-ginning (lowest address) of the stack, independent whether the stack is growing from higher to lower address within the CPU. If this pointer is set to NULL, the stack memory is allocated by rcX itself based on the uStckSiz value.

uStckSiz Number of stack elements that the task can use at runtime. The value should never be less than 128 elements. The size of one stack ele-ment is 4 bytes.

uSrtMod

This value defines the start mode of the task.

• A value of RX_TASK_AUTO_START lets the task start auto-matically and be scheduled according to its priority

• A value RX_TASK_AUTO_STOP prevents the task from start-ing automatically. Only a call to rX_SysResumeTask( ) during runtime will start the task.

eThrhld not implemented

ePrio

Initial task priority The value ranges from TSK_PRIO_1 to TSK_PRIO_55. TSK_PRIO_1 represents the highest priority.



eTok

Task token Unique task Identification. The token ranges from TSK_TOK_1 to TSK_TOK_55. The token value has to be unique for every task.

uInst

Task instance This value is necessary, if a task is created multiple times. The in-stance value should start with the value 0 and must be incremented for each instance.

fnTskLve

Task leave function This function will be called by the operating system if a task should be deleted. This gives the system the possibility to release the task re-sources. A value of NULL defines no leave function.


Description

RX_OK (0x0000)

Function successful.

RX_KNL_PRIORITY_EXIST (0x0003)

The specified priority is already in use by another task.

RX_KNL_PRIORITY_INVALID (0x0004)

Specified priority out of range and not in its limits.

RX_KNL_TOKEN_INVALID (0x000A)

Specified token out of range and not in its limits.

RX_KNL_TOKEN_DOUBLE (0x000B)

Specified token is already in use by another task.

Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible Yes



Example Code

UINT16 ausSndTskStck[SNDTSK_STK_SIZE]; UINT32 ulInput = 0x12345678; /* Creates a task of priority 15 with the token Id 15, and no * leave function */ erXRes = rX_SysCreateTask(“SENDTASK”, SendTask, (void*)&ulInput, (void*)&ausSndTskStck[0], RX_TASK_AUTO_START, SNDTSK_STK_SIZE, 0, TSK_PRIO_15, TSK_TOK_15, 0, (void (*) (void*))NULL); … /* This is the Task entry function */ void SendTask(void* pvInit) { UINT32 ulInitDat; … ulInitDat = *(UINT32*) pvInit; /* get the Initialization data */ … }



2.4.2 rX_SysIdentifyTask() – Identify a Task by Name rX_SysIdentifyTask() identifies a task. Function Syntax in „C“-Convention RX_RESULT rX_SysIdentifyTask( STRING* pszTskNam, UINT uInst, RX_HANDLE* phTsk, RX_TASK_TOKEN* peTok, RX_TASK_PRIORITY* pePrio ) Function Arguments Argument

Description

pszTskNam Pointer to a task name as NUL- terminated string. A NULL pointer identifies the calling task.

uInst Instance of the task to be identified phTsk Pointer to destination for the task handle

peTok Pointer to the destination variable for the task’s token. If this pointer is NULL, the token ID value is not returned.

pePrio Pointer to the destination variable for the task’s priority. If this pointer is NULL, the priority value is not returned.


Description

RX_OK (0x0000)


RX_KNL_TASK_UNKNOWN (0x0006)

The task does not exist.

Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible No



Example Code

RX_TASK_TOKEN eTokTsk1; /* Variable to hold the task 1 token */ RX_HANDLE hTsk; /* Variable to hold the handle to the task */ /* Look for the task named ‘TESTTSK1’, and just get the token of it */ erXRes = rX_SysIdentifyTask("TESTTSK1", 0, &hTsk, &eTokTsk1,NULL); if( erXRes == RX_OK ) { /* success, task has been found */ … } else { /* failed */ … }



2.4.3 rX_SysSetTaskInitialized() – Signal the End of the Current Task Initialization

The function rX_SysSetTaskInitialized() has to be called by each static task at the end of its initialization to report to the rcX that it can schedule the next configured task’s routine. As long as further static tasks are waiting for their initial startup, the calling task will be sus-pended and will not be resumed until all other non-initialized tasks have called rX_SysSetTaskInitialized(). As soon as this “Ready” initialization state is reached, the tasks are woken up. Any subsequent call of the function by any task will not influence the scheduling process. Function Syntax in „C“-Convention void rX_SysSetTaskInitialized( void* pvInpt ) Function Arguments Argument

Description

pvInpt If a leave function is configured, this pointer will be passed as pa-rameter to it when the task is about to become deleted


Description

None None Allowed to be called by Tasks Pre-emption possible Yes.



Example Code

… MY_RESOURCES_T tMyRsr; // local resource pool in one common structure void TaskBody(void* pvInp) { RX_RESULT eRes; eRes = rX_BarCreateBarrier("Bar1",(RX_HANDLE) tMyRsr.abBar,2); eRes = rX_TimCreateCycle("Cyclic1",(RX_HANDLE) tMyRsr.abCyl,3); eRes = rX_MbxCreateMailbox("Mailbox1",(RX_HANDLE) abMbx,TYPE_CHILD); eRes = rX_QueCreateQueue("Queue1",(RX_HANDLE) tMyRsr.abQue, apvQue,MAX_CNT(apvQue)); eRes = rX_MbxCreateMessageStorage((RX_HANDLE) &tMyRsr.abMsgQue); eRes = rX_MemCreateSharedMemory("Shm",(RX_HANDLE)

&tMyRsr.abShm,&bPrioTask1__Test1__); ... /* Initialization is finished */ rX_SysSetTaskInitialized(&tMyRsr); /* The System is Ready, now continue with the task’s objects */ rX_WaitForBarrier(abBar); ... }



2.4.4 rX_SysDeleteTask() – Delete a Task This function deletes the specified task and removes it from the scheduler’s task list. All objects like semaphores, mutexes, barriers and so on, that have been created by the task during its runtime, are not removed. If a leave function has been configured either via the static task list or rX_SysCreateHookLeave(), it will be used to change the task’s context to. In this function, the task is able to free its resources. The second parameter specifies the timeout in system ticks until which the actual deletion will be delayed, so that a task has a certain amount of time to execute its leave function. Function Syntax in „C“-Convention RX_RESULT rX_SysDeleteTask( RX_HANDLE hTsk, UINT uTcks ) Function Arguments Argument

Description

hTsk Handle of the task

uTcks

Number of system ticks the task deletion is delayed. If the value is configured to 0, the task is deleted immediately without any delay.


Description

RX_OK (0x0000)

Task has been requested to be deleted and its leave Function has been called.


Task does not exist in scheduler’s task list.

RX_KNL_TASK_DOWN (0x000C)

Specified task is already shutting down.



Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible Yes Example Code

RX_HANDLE hTsk25; … /* Deletes a task specified by hTsk25 handle after 500 system-ticks */ erXRes = rX_SysDeleteTask(hTsk25,500); if( erXRes == RX_OK ) { /* success, Task is shutting down */ … } else { /* failed */ … } …



2.4.5 rX_SysSleepTask() – Suspend the current Task for a speci-fied Time

rX_SysSleepTask() suspends the currently running task for the specified number of rcX ticks or forever. A task in “Waiting" state can be reactivated by another task calling the rX_SysWakeupTask() function. Function Syntax in „C“-Convention UINT rX_SysSleepTask( UINT uTicks ) Function Arguments Argument

Description

uTicks Number of ticks to suspend the current running task. The value ranges from 1 to 0xFFFFFFFF. The value RX_INFINITE = 0 lets the task sleep forever.


Description

UINT uLftTim

Current number of remaining ticks Typically, this value is 0, but if the task has been re-activated by the rX_SysWakeupTask() function the value returns the remaining ticks.

Allowed to be called by Tasks Pre-emption possible Yes



Example Code

… /* let the calling Task sleep for 10 timer ticks */ rX_SysSleepTask(10); Process1(); … /* let the calling Task sleep for 20 timer ticks */ rX_SysSleepTask(20); Process2(); … /* all processes are done sleep now forever */ rX_SysSleepTask(RX_INFINITE); … /* Unless we get woken up by someone else due to rX_SysWakeupTask() */ …



2.4.6 rX_SysDelayTaskUntil() – Delay a Task for a specified Time rX_SysDelayTaskUntil() suspends the current running task until the periodic system tick count equals at least the specified tick count value. A task in “Waiting" state can be reactivated by another task calling the rX_SysWakeupTask() function. Function Syntax in „C“-Convention UINT rX_SysDelayTaskUntil( UINT uSysTicks ) Function Arguments Argument

Description

uSysTicks Absolute tick count until which the task will be suspended Function Return Values Return Value

Description

UINT uCurSysTick

The current system timer tick value at the time the task was restored to the “Running" state. This value can differ from the specified uSysTicks value if rX_SysWakeupTask() was called by another task to wake it up.



Allowed to be called by Tasks Pre-emption possible Yes Example Code

UINT uFreezeTime; … uFreezeTime = rX_SysGetSystemTicks(); /* Get the current system timer ticks*/ rX_SysDelayTaskUntil(uFreezeTime + 100); /* Sleep 100 ticks relative */ Process1(); … rX_SysDelayTaskUntil(uFreezeTime + 150); /* Sleep 150 ticks relative */ Process2(); … rX_SysDelayTaskUntil(uFreezeTime + 170); /* Sleep 170 ticks relative */ Process3(); …



2.4.7 rX_SysWakeupTask() – Abort the Sleep State of a Task rX_SysWakeupTask() aborts the sleep or any other timed suspension of the specified task. Function Syntax in „C“-Convention RX_RESULT rX_SysWakeupTask( RX_HANDLE hTsk ) Function Arguments Argument

Description

hTsk Handle of the task to wake up Function Return Values Return Value

Description

RX_OK (0x0000)

The specified task has been re-entered into “Ready" state.


Task does not exist in scheduler task list.

RX_KNL_TASK_BLOCKED (0x0009)

Specified task is currently suspended.

Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible Yes.



Example Code

RX_HANDLE hTsk1; … /* Wakes up a task with the handle hTsk1 */ erXRes = rX_SysWakeupTask(hTsk1); if( erXRes == RX_OK ) { /* success*/ … } else { /* failed */ … } …



2.4.8 rX_SysBlockTask() – Stop the scheduling of the specified Task

rX_SysBlockTask() suspends a given task. rX_SysResumeTask() has to be used to set the task either to the “Ready" state or the “Wait-ing" state depending on the task state when the call to rX_SysBlockTask() has been made. Function Syntax in „C“-Convention RX_RESULT rX_SysBlockTask( RX_HANDLE hTsk ) Function Arguments Argument

Description

hTsk Handle of the task to be suspended Function Return Values Return Value

Description

RX_OK (0x0000)



Task does not exist in the scheduler task list




Example Code

RX_HANDLE hTsk1; … /* Blocks the Task with Handle hTsk1 */ erXRes = rX_SysBlockTask(hTsk1); if( erXRes == RX_OK ) { /* success*/ … } else { /* failed */ … } …



2.4.9 rX_SysResumeTask() – Resume a previously blocked Task rX_SysResumeTask() returns a task from “Suspended" state to the “Ready" state or “Wait-ing" state depending on state the task was during the calling to rX_SysBlockTask(). Function Syntax in „C“-Convention RX_RESULT rX_SysResumeTask( RX_HANDLE hTsk ) Function Arguments Argument

Description

hTsk Handle of the task to be de-suspended Function Return Values Return Value

Description

RX_OK (0x0000)

The specified suspended task has been returned to “Ready" state” or “Waiting" state.


Task does not exist in the scheduler task list

RX_KNL_TASK_NOT_BLOCKED (0x0007)

Task is not in “Suspended" state.




Example Code

RX_HANDLE hTsk1; … /* Let a Task with Handle hTsk1 resume its work */ erXRes = rX_SysResumeTask(hTsk1) if( erXRes == RX_OK ) { /* success*/ … } else { /* failed */ … } …



2.4.10 rX_SysTerminateTask() – Terminate a Task rX_SysTerminateTask() terminates the calling task. The resources created and utilized by this task will remain untouched and can still be used by other tasks. A parameter of this function allows the caller to specify a reason code defin-ing the termination reason. Function Syntax in „C“-Convention void rX_SysTerminateTask( UINT uRsnCod ) Function Arguments Argument

Description

uRsnCod Termination reason code Function Return Values Return Value

Description

None None Allowed to be called by Tasks Pre-emption possible Yes. Example Code

… erXRes = rX_QueSendPacket(hQue, ptPck, RX_INFINITE); if( erXRes != RX_OK) { /* Queue seems to be deleted, unrecoverable fault, terminate the Task */ rX_SysTerminateTask(TSK_RSN_MAILBOX_ERROR); /* never returns */ }



2.4.11 rX_SysChangePriority() – Change the Priority of a Task This function allows the user to change the priority of a task The new priority must not be in use by any other task. Otherwise, the function will not change the priority of the specified task. Function Syntax in „C“-Convention RX_RESULT rX_SysChangePriority( RX_HANDLE hTsk, RX_TASK_PRIORITY eNewPrio ) Function Arguments Argument

Description

hTsk Handle of the task

eNewPrio The value of the new task priority. The value ranges from TSK_PRIO_1 to TSK_PRIO_55.


Description

RX_OK (0x0000)

The task priority has been changed.

RX_KNL_PRIORITY_EXIST (0x0003)

The specified priority is already in use.

RX_KNL_PRIORITY_INVALID (0x0004)

The specified priority level is not a valid priority.


Task does not exist in scheduler task list.




Example Code

RX_HANDLE hTskChng; … /* Changes Task of Handle hTskChng to Priority 9 */ erXRes = rX_SysChangePriority(hTskChng,TSK_PRIO_9) if( erXRes == RX_OK ) { /* success*/ … } else { /* failed */ … } …



2.4.12 rX_SysGetOwnInstance() – Get the Instance number of the calling Task

This function returns the instance number of the calling task and allows to distinguish whether the task is started multiple times or not. The value can be used to identifyi related tasks or resources of the same type sharing the same name. Function Syntax in „C“-Convention UINT rX_SysGetOwnInstance( void ) Function Arguments Argument

Description


Description

UINT uInst Instance number of the calling task Allowed to be called by Tasks Pre-emption possible No. Example Code

void TaskInit(void) { UINT uOwnInst; /* local variable to hold the current instance number */ … /* Get now my own instance number */ uOwnInst = rX_SysGetOwnInstance(); … }



2.5 Queue Services – Header-File AP_Que.h Providing Queue Services <#include AP_Que.h>

2.5.1 rX_QueCreateQueue() – Create a Queue of dynamic Size and Elements

rX_QueCreateQueue() creates a queue. The function has to be provided with pre-allocated memory for the queue, which must have the size of RX_QUEUE_SIZE bytes, as well as for the queue pointers, whose size must match the specified depth multiplied by sizeof(void*). The function does not fill the newly created queue with any pointers. Function Syntax in „C“-Convention RX_RESULT rX_QueCreateQueue( STRING* pszIdn, RX_HANDLE hQue, void** papvQue, UINT uDep ) Function Arguments Argument

Description

pszIdn

Queue name Pointer to a 0 terminated string of a length of maximum 16 bytes in-cluding the NUL character (15+1)

hQue Pointer to a memory block with RX_QUEUE_SIZE bytes. papvQue Pointer to the start of the queue pointer list. uDep Depth of the queue as number of pointer elements within the queue.


Description

RX_OK (0x0000)

The queue has been created.

RX_KNL_DUPLICATE_NAME (0x001C)

A queue with the name and the current task instance number exists already.

RX_KNL_NAME_TOO_LONG (0x001D)

The specified Id string is longer than 16 bytes




RX_HANDLE hQue; /* Queue handle */ void* apvQueElmts[16]; /* Define a static array of 16 void Pointers */ void* pvPkt; /* Pointer for destination of receive Packet in * queue */ … /* Reserve Memory first */ erXRes = rX_MemAllocateMemory(&hQue,RX_QUEUE_SIZE); /* Create the Queue now */ erXRes = rX_QueCreateQueue(“QUEUE1”, hQue, apvQueElmts, sizeof(apvQueElmts) / sizeof(apvQueElmts[0])); if( erXRes == RX_OK ) { /* success, wait now for queue to be filled */ erXRes = rX_QueReceiveQueue(hQue,&pvPkt,RX_INFINITE) … } else { /* error, we have to abort initialization here */ … }



2.5.2 rX_QueIdentifyQueue() – Identify a Queue by Name rX_QueIdentifyQueue() identifies a queue with the specified name and instance. Function Syntax in „C“-Convention RX_RESULT rX_QueIdentifyQueue( STRING* pszIdn, UINT uInst, RX_HANDLE* phQue ) Function Arguments Argument

Description

pszIdn Pointer to a queue name as NUL-terminated string uInst Instance number of the queue phQue Pointer to destination for the queue handle


Description

RX_OK (0x0000)

Queue has been found.

RX_QUE_UNKNOWN (0x0906)

Queue is not listed in the queue list




Example Code

RX_HANDLE hQueTsk1; /* Get the handle to a queue named ‘QUEUE1’ */ erXRes = rX_QueIdentifyQueue(“QUEUE1”,0,&hQueTsk1); if( erXRes == RX_OK ) { /* success*/ … } else { /* failed, queue was not installed */ … }



2.5.3 rX_QueWaitForPacket() – Wait for a Queue-Packet to be re-ceived

rX_QueWaitForPacket() retrieves a packet from the specified queue. If the queue is empty, it will wait for the specified timeout. Function Syntax in „C“-Convention RX_RESULT rX_QueWaitForPacket( RX_HANDLE hQue, void** ppvPkt UINT uTimeout ) Function Arguments Argument

Description

hQue Queue handle ppvPkt Pointer to the variable to fill in the packet pointer if successful

uTimeout

• Timeout value in system timer ticks • • 0x00000001 – 0xFFFFFFFE

These values specify a tick count how many ticks to be waited if no packet has been received in time

• • RX_INFINITE (0x00000000)

rX_QueWaitForPacket() will wait until a packet has been re-ceived

• • RX_FINITE (0xFFFFFFFF)

It tells rX_QueWaitForPacket() just to check for a packet read-ily available to be received. Otherwise, it returns an error.


Description

RX_OK (0x0000)

A packet has been received.

RX_KNL_HANDLE_INVALID (0x0019)

The handle is invalid.

RX_QUE_DELETED (0x0903)

While waiting for a packet, the queue has been deleted.

RX_TIMEOUT (0x0001)

No packet available within the specified tick time.

RX_QUE_EMPTY (0x0308)

The queue is empty This result will be returned if uTimOpt = RX_FINITE



Allowed to be called by Tasks, if uTimOpt = RX_FINITE then also ISR and Application Timers. Pre-emption possible Yes. Example Code

RX_HANDLE hQueTsk1; /* queue handle */ void* pvPkt /* Pointer to the packet */ /* Wait for a packet at least 500 ticks */ erXRes = rX_QueWaitForPacket(hQueTsk1,&pvPkt,500); if(erXRes == RX_OK) { /* success, packet has been received */ if(((TSK_MSG_T*)pvPkt)->abMsgData[5]) { … } } else if(erXRes == RX_TIMEOUT) { /* timeout, no packet available */ … } else { /* something went wrong, we have to check whether we can * survive that error */ … }



2.5.4 rX_QuePeekPacket() – Check for a Queue-Packet in a Queue

This function tries to retrieve a packet from the specified queue. If there is no packet avail-able, it will always return immediately. Function Syntax in „C“-Convention RX_RESULT rX_QuePeekPacket( RX_HANDLE hQue, void** ppvPkt ) Function Arguments Argument

Description

hQue Queue handle ppvPkt Pointer to destination variable for the packet pointer


Description

RX_OK (0x0000)

A packet has been retrieved.



RX_QUE_EMPTY (0x0908)

No packet currently available.




Example Code

RX_HANDLE hQueTsk1; /* pointer to the queue */ void* pvPkt; /* pointer to the packet */ for(;;) { erXRes = rX_QuePeekPacket(hQueTsk1,&pvPkt); if( erXRes == RX_OK ) { /* success, packet has been received */ if(((TSK_MSG_T*)pvPkt)->abMsgData[5] ) { … } else if ( erXRes == RX_QUE_EMPTY) { /* No packet there, just continue */ … } else { /* something went wrong, let’s check how we need to react on that */ … } } }



2.5.5 rX_QueSendPacket() – Send a Packet to a Queue in FIFO principle

rX_QueSendPacket puts a packet as the last element into the specified queue. If the queue is full, it will wait for the specified timeout. If the timeout is specified as RX_FINITE, it will al-ways return immediately. Function Syntax in „C“-Convention RX_RESULT rX_QueSendPacket( RX_HANDLE hQue, void* pvPkt, UINT uTimeout ) Function Arguments Argument

Description

hQue Queue handle pvPkt Pointer to the packet

uTimeout

• Timeout value in system timer ticks • 0x00000001 – 0xFFFFFFFE

These values specify a tick count how many ticks to be waited if no packet could have been put into the queue yet

• RX_INFINITE (0x00000000)

rX_QueSendPacket() will wait until the packet has been put into the queue

• RX_FINITE (0xFFFFFFFF)

It tells rX_QueSendPacket() to try to put the packet into the queue. If it was not able to, it will return an error.


Description

RX_OK (0x0000)

The packet was successfully sent.




While waiting for a successful sending, the queue has been deleted.

RX_TIMEOUT (0x0001)

Timeout occurred while waiting for successful sending

RX_QUE_FULL (0x0907)

Queue is full, the packet was not sent



Allowed to be called by Initialization and Tasks if uTimOpt = RX_FINITE then ISR and Application Timers are allowed too Pre-emption possible Yes. Example Code

RX_HANDLE hQueTsk10; /* queue handle */ void* pvPkt; /* pointer to the packet */ … /* Send a packet to task’s 10 queue */ erXRes = rX_QueSendPacket(hQueTsk10,ptPkt,RX_INFINITE); if( erXRes == RX_OK ) { /* success, packet has been sent */ … } else { /* something went wrong, we have to bail out here with an error */ … }



2.5.6 rX_QueSendPriorityPacket() – Send a Packet to a Queue in LIFO principle

rX_QueSendPacket puts a packet as new first element into the specified queue. If the queue is full, it will wait for the specified timeout. If the timeout is specified as RX_FINITE, it will al-ways return immediately. Function Syntax in „C“-Convention RX_RESULT rX_QueSendPriorityPacket( RX_HANDLE hQue, void* pvPkt, UINT uTimOpt ) Function Arguments Argument

Description

hQue Queue handle pvPkt Pointer to the packet to be placed into the queue

uTimOpt


These values specify a tick count how many ticks to be waited if no packet could have been put into the queue yet


rX_QueSendPriorityPacket() will wait until the packet has been put into the queue


It tells rX_QueSendPriorityPacket() to try to put the packet into the queue. If it was not able to, it will return an error.


Description

RX_OK (0x0000)

The packet was successfully sent




While waiting for a successful sending, the queue has been deleted.

RX_TIMEOUT (0x0001)

Timeout occurred

RX_QUE_FULL (0x0907)

Queue is full, the packet was not sent



Allowed to be called by Initialization and Task if uTimOpt = RX_FINITE then ISR and Application Timer are allowed too Pre-emption possible Yes. Example Code

RX_HANDLE hPrcQue; /* processing handle */ void* pvPkt; /* pointer to the packet */ … /* Send a packet to task’s process queue */ erXRes = rX_QueSendPriorityPacket(hPrcQue,ptPkt,RX_INFINITE); if( erXRes == RX_OK ) { /* success, packet has been sent */ … } else { /* something went wrong, we have to bail out here with an error */ … }



2.5.7 rX_QueDeleteQueue() – Delete a Queue rX_QueDeleteQueue() deletes a queue. If a task is waiting on that queue to be filled with a packet during deletion, the task will be woken up and the error code RX_QUE_DELETED will be returned. It is the task’s responsibility to manage the memory area associated with the queue after the deletion. Function Syntax in „C“-Convention RX_RESULT rX_QueDeleteQueue( RX_HANDLE hQue ) Function Arguments Argument

Description

hQue Queue handle Function Return Values Return Value

Description

RX_OK (0x0000)

The queue has been successfully removed.






Example Code

RX_HANDLE hSendQue; /* queue handle */ void* apvQueElmts; /* pointer to queue-elements body */ … void stop(void) { /* Delete the send queue */ erXRes = rX_QueDeleteQueue(hSendQue); if(RX_OK == erXRes) { erXRes = rX_MemFreeMemory(hSendQue); } if( RX_OK == erXRes ) { /* success the queue is deleted, free the used memory resources */ erXRes = rX_MemFreeMemory(apvQueElmt); } else { /* error, for some reason we cannot delete the queue */ … } }



2.5.8 rX_QueFlushQueue() – Delete all Packets in a Queue rX_QueFlushQueue() flushes all contained packet pointers currently stored in the specified queue. Function Syntax in „C“-Convention RX_RESULT rX_QueFlushQueue( RX_HANDLE hQue ) Function Arguments Argument

Description

hQue Queue handle Function Return Values Return Value

Description

RX_OK (0x0000)

Queue successfully flushed



Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible Yes



Example Code

RX_HANDLE hSendQue; /* Pointer to the Queue */ … /* Clear all Packets in Queue */ erXRes = rX_QueFlushQueue(hSendQue); if( erXRes == RX_OK ) { /* success the queue body is deleted */ … } else { /* error, must be fatal */ … }



2.5.9 rX_QueGetQueueLoad() – Return the current Fill Level of a Queue

rX_QueGetQueueLoad() returns the current fill level of the specified queue. Function Syntax in „C“-Convention RX_RESULT rX_QueGetQueueLoad( RX_HANDLE hQue, UINT* puLd ) Function Arguments Argument

Description

hQue Queue handle puLd Pointer where the current queue load value will be copied to


Description

RX_OK (0x0000)

Queue fill level successfully returned



Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No



Example Code

RX_HANDLE hSendQue; /* Pointer to the queue */ UINT uCurLd; … /* Get the current load factor of the queue */ erXRes = rX_QueGetQueueLoad(hSendQue, &uCurLd); if( erXRes == RX_OK ) { /* success, we got the fill level */ if(uCurLd == 0) { /* There is nothing in the queue, it is empty */ rX_SysSleepTask(1); /* fall asleep for a while */ } else { /* At least one element is in the queue, get one */ rX_QuePeekPacket(…) … } … } else { /* error, we were not able to read the load count. * See whether we have to bail out due to the current state */ … }



2.6 Event Services – Header-File AP_Eve.h Providing Event Services <#include AP_Eve.h>

2.6.1 rX_EveCreateEventGroup() – Create an Eventgroup for 32 possible Events

rX_EveCreateEventGroup() creates a group of 32 possible events. Each event is repre-sented by an own bit in a 32 bit value. The function has to be provided with pre-allocated memory for the group, which must have the size of RX_EVENTGROUP_SIZE bytes. Function Syntax in „C“-Convention RX_RESULT rX_EveCreateEventGroup( STRING* pszIdn, RX_HANDLE hEveGrp ) Function Arguments Argument

Description

pszIdn

Event group name Pointer to a NUL terminated ASCII string of 16 bytes, including the terminating NUL character.

hEveGrp Pointer to a memory block with RX_EVENTGROUP_SIZE bytes. Function Return Values Return Value

Description

RX_OK (0x0000)

Eventgroup successfully created.


A queue with the name and the current task instance number exists already.


Object name is longer than 16 bytes

Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible No.



Example Code

UINT32 ulCurEve; /* Where to copy the current event bits to */ RX_HANDLE hEveGrp; /* event group handle */ … /* Reserve memory first */ erXRes = rX_MemAllocateMemory(&hEveGrp,RX_EVENTGROUP_SIZE); … /* Create the event group now */ erXRes = rX_EveCreateEventGroup(“EGRP”, hEveGrp);

/* Setting the event group parameters */ erXRes = rX_EveSetupEventGroup(hEveGrp, 0x80000500, RX_EVEGRP_MODE_ONE, &ulCurEve); if( erXRes == RX_OK ) { /* success, wait now for an event to occur */ erXRes = rX_EveWaitForEventGroup(hEveGrp,RX_INFINITE); if(ulCurEve & 0x8000000) { /* Event 1 */ } if(ulCurEve & 0x0000400) { /* Event 2 */ } if(ulCurEve & 0x0000100) { /* Event 3 */ } … } else { /* error, waiting has failed */ … }



2.6.2 rX_EveIdentifyEventGroup() – Identify an Eventgroup by Name

rX_EveIdentifyEventGroup() identifies an event group with the specified name and instance. Function Syntax in „C“-Convention RX_RESULT rX_EveIdentifyEventGroup( STRING* pszIdn, UINT uInst, RX_HANDLE* phEveGrp ) Function Arguments Argument

Description

pszIdn Pointer to a name as a NUL terminated ASCII string uInst Instance number phEveGrp Pointer to store the Eventgroup handle


Description

RX_OK (0x0000)

Eventgroup found.

RX_EVEGRP_UNKNOWN (0x0707)

Eventgroup is not known.

Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No.



Example Code

RX_HANDLE hEveGrpTsk1; /* Get the handle to a event group named ‘EGRP1’ */ erXRes = rX_EveIdentifyEventGroup(“EGRP1”,0,&hEveGrpTsk1); if(erXRes == RX_OK) { /* success*/ … } else { /* failed, event group does not seem not to be existing */ … }



2.6.3 rX_EveSetupEventGroup() – Set the Eventgroup Parame-ters

rX_EveSetupEventGroup() selects the mode and the event bits, within the event mask, on which rX_EveWaitForEventGroup() will wait for. Function Syntax in „C“-Convention RX_RESULT rX_EveSetupEventGroup( RX_HANDLE hEveGrp, UINT32 ulEveMsk, UINT uMode, UINT32* pulCurEve ) Function Arguments Argument

Description

hEveGrp Eventgroup handle

ulEveMsk 32 bit unsigned event mask value This mask specifies the events the task wants to wait for.

uMode

Waiting mode It specifies weather any or all of the requested event bits of the event mask have to match before the eventgroup is signaled. The following values can be specified:

• RX_EVEGRP_MODE_ONE The event is signaled, if at least one of the specified event bit became active.

• RX_EVEGRP_MODE_ALL

The event is signaled, if all specified event bits are active.

pulCurEve Pointer to store the actual pending event mask, returned by rX_EveWaitForEventGroup().




Description

RX_OK (0x0000)

Function successful


Invalid handle value.

RX_EVEGRP_MODE_INVALID (0x070A)

The specified mode value is invalid.

Allowed to be called by Tasks Pre-emption possible No. Example Code

UINT32 ulCurEve; /* Where to copy the current event bits to */ RX_HANDLE hEveGrp; /* event group Handle */ … /* Set the parameter, all bits have to be set to cause an * event group event */ erXRes = rX_EveSetupEventGroup(hEveGrp, 0x80010001, RX_EVEGRP_MODE_ALL, &ulCurEve); ...



2.6.4 rX_EveWaitForEventGroup() – Wait on Eventgroup Events rX_EveWaitForEventGroup() wait on an eventgroup for a specified event. Events are specified by rX_EveSetupEventGroup(). Function Syntax in „C“-Convention RX_RESULT rX_EveWaitForEventGroup( RX_HANDLE hEveGrp, UINT uTimeout ) Function Arguments Argument

Description


uTimeout

Timeout value in system timer ticks • 0x00000001 – 0xFFFFFFFE

Timeout to wait for an event to occure. • RX_INFINITE (0x00000000)

Wait for ever until an event occures. • RX_FINITE (0xFFFFFFFF)

Do not wait. This can be used to check for pending events. The function returns RX_EVEGRP_NOEVENT, if none of the events are active.


Description

RX_OK (0x0000)

The requested event bits have occurred.


Invalid handle.

RX_EVEGRP_DELETED (0x0703)

While a task was waiting, the defined Eventgroup has been deleted.

RX_EVEGRP_NOEVENT (0x0708)

No event.

RX_TIMEOUT (0x0001)

Wait time expired



Allowed to be called by Tasks, If ulTimOpt = RX_FINITE also usable by an ISR and Application Timers. Pre-emption possible Yes. Example Code

RX_HANDLE hEveGrpTsk7; /* handle to the event group */ UINT32 ulCurEvents; /* Wait for an event group forever */ erXRes = rX_EveWaitForEventGroup(hEveGrpTsk7,RX_INFINITE); if( erXRes == RX_OK ) { /* Success, one of the events has occurred, look now which one */ if((ulCurEvents & 0x00008000) == 0x00008000) { … } if((ulCurEvents & 0x00000100) == 0x00000100) { … } … } else { /* error, waiting for the event group failed */ … }



2.6.5 rX_EveChangeEventGroup() – Change Events in an Event-group

This function can be used to manually change the state of event bits in the specified event-group. ulMode defines if the event bits should be set or cleared. Function Syntax in „C“-Convention RX_RESULT rX_EveChangeEventGroup( RX_HANDLE hEveGrp, UINT32 ulEveMsk, UINT uMod ) Function Arguments Argument

Description


ulEveMsk 32 bit unsigned event mask value This mask specifies the event bits to be changed.

uMode

Operation mode

• RX_EVEGRP_MODE_SET Sets the corresponding event bits in the eventgroup.

• RX_EVEGRP_MODE_CLR

Clears the corresponding event bits in the eventgroup. Function Return Values Return Value

Description

RX_OK (0x0000) The pending events bit have been modified.






Example Code

RX_HANDLE hEveGrpTsk7; /* Handle to the event group */ /* Change now to event bits 0x8000 and 0x0001 */ erXRes = rX_EveChangeEventGroup(hEveGrpTsk7,0x8001, RX_EVEGRP_MODE_SET);

if( erXRes == RX_OK ) { /* success, the event bits have been set */ } else { /* error, we could not access the event group */ … }



2.6.6 rX_EveDeleteEventGroup() – Delete an Eventgroup rX_EveDeleteEventGroup() deletes an eventgroup. If a task is waiting on the eventgroup, it will be activated and the error code RX_EVEGRP_DELETED is returend by rx_EveWaitForEventGroup(). Function Syntax in „C“-Convention RX_RESULT rX_EveDeleteEventGroup( RX_HANDLE hEveGrp ) Function Arguments Argument

Description

hEveGrp Eventgroup handle Function Return Values Return Value

Description

RX_OK (0x0000) Function succeed successfully






Example Code

RX_HANDLE hEveGrp; /* handle of the event group */ … void stop(void) { /* delete the event group */ erXRes = rX_EveDeleteEventGroup(hEveGrp); if( erXRes == RX_OK ) { /* success the event group is removed, don’t forget to return * memory resource */ erXRes = rX_MemFreeMemory(hEveGrp); } else { /* error, the event group has not been deleted */ … } }



2.7 Signal Services – Header-File AP_Sig.h Providing Signal Services <#include AP_Sig.h> Signals are also know as events and providing the same functionality.

2.7.1 rX_SigCreateSignal() – Create a Signal rX_SigCreateSignal() creates a signal (event). Function Syntax in „C“-Convention RX_RESULT rX_SigCreateSignal( STRING* pszIdn, UINT* puSignl, BOOLEAN fManRst ) Function Arguments Argument

Description

pszIdn

Signal name Pointer to a string NUL terminated string of a maximum of 16 bytes includeing the terminating NUL character

puSignl Pointer to the destination variable where the signal handle will be copied to

fManRst

Boolean value configuring whether the signal is automatically reset fManRst = FALSE

rcX will automatically reset the signal fManRst = TRUE

the user has to explicitly reset the signal by calling rX_SigResetSignal().


Description

RX_OK (0x0000) A signal has been allocated.

RX_SIG_NAME (0x0C01) The specified ID string is longer than 16 bytes.

RX_SIG_OUTOF_EVENTS (0x0C03) No further signal could be allocated.



Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No Example Code

UINT uSignlEve; /* Signal Handle */ … /* create the signal now */ erXRes = rX_SigCreateSignal(“Watchdog”, // Name

&uSignlEve, // Pointer to Handle FALSE); // automatic reset

if( erXRes == RX_OK ) { /* success, wait now for an Event to occur */ erXRes = rX_SigWaitForSignal(uSnglEve,RX_INFINITE); ... } else { /* something seems to be wrong with the signal * we have to bail out with an error */ ... }



2.7.2 rX_SigIdentifySignal() – Identify a Signal by Name The function can be used to identify a signal object with a specified name. Function Syntax in „C“-Convention RX_RESULT rX_SigIdentifySignal( STRING* pszIdn, UINT* puSignlIdx ) Function Arguments Argument

Description

pszIdn Pointer to a signal name as 0 terminated string puSignlldx Pointer to destination variable for the signal handle


Description

RX_OK (0x0000)

Signal has been identified.

RX_SIG_EVENT_UNKNOWN (0x0C06)

Signal is not known.




Example Code

UINT uSignlIdx; /* Get the handle to a signal named ‘Watchdog’ */ erXRes = rX_SigIdentifySignal(“Watchdog”, &uSignlIdx); if( erXRes == RX_OK ) { /* success */ … } else { /* failed, Signal seems not to be installed */ … }



2.7.3 rX_SigWaitForSignal() – Wait for a Signal rX_SigWaitForSignal() waits for a signal to occur. Only one task is allowed to wait for a signal at the same time. Otherwise an error code is returned. If an event occures and no task is waiting for it, the event is counted and will be delivered on the next call to rX_SigWaitForSignal(). The function will successfully return immediately for each counted event. All previously counted events can be discarded by a call to rX_SigResetSignal(). Function Syntax in „C“-Convention RX_RESULT rX_SigWaitForSignal( UINT uSignlIdx, UINT uTimeout ) Function Arguments Argument

Description

uSignlIdx Signal handle

uTimeout


These values specify a tick count how many ticks to be waited for the signal if it has not been set.


rX_SigWaitForSignal() will wait until the signal has been set • RX_FINITE (0xFFFFFFFF)

It tells rX_SigWaitForSignal() to check whether the signal has been set. If it has not been set, it will return an error.


Description

RX_OK (0x0000)

The signal has been set.

RX_SIG_TIMEOUT (0x0C04)

The signal has not been set within the specified timeout.

RX_SIG_EVENT_INVALID (0x0C05)

The signal handle is invalid.

RX_SIG_MULTI_WAIT (0X0C07)

More than one task tries to wait for the specified signal.

RX_SIG_NOT_PRESENT (0x0C08)

Signal is not pending.



Allowed to be called by Tasks, if uTimOpt = RX_FINITE then also ISR and Application Timers. Pre-emption possible Yes. Example Code

UINT uSignlIdx; /* Handle to Signal */ /* Wait for the signal forever */ erXRes = rX_SigWaitForSignal(uSignlIdx,

RX_INFINITE); if( erXRes == RX_OK ) { /* the signal has occurred */ … } else { /* the signal has not occured */ … }



2.7.4 rX_SigSetSignal() – Set a Signal rX_SigSetSignal() sets a signal. If no task is currently waiting, the signal counter is incre-mented by 1. Function Syntax in „C“-Convention RX_RESULT rX_SigSetSignal( UINT uSignlIdx ) Function Arguments Argument

Description

uSignlIdx Handle to the signal Function Return Values Return Value

Description

RX_OK (0x0000)

The specified signal has been set.






Example Code

UINT uSignl; /* Index Handle to Signal */ /* Set now Event to activate a Task */ erXRes = rX_SigSetSignal(uSignl);

if( erXRes == RX_OK ) { /* success, the Event has been set */ } else { /* the signal has been deleted * we have to bail out them */ … }



2.7.5 rX_SigResetSignal() – Reset a Signal rX_SigResetSignal() resets the signal counter to 0. Function Syntax in „C“-Convention RX_RESULT rX_SigResetSignal( UINT uSignlIdx ) Function Arguments Argument

Description


Description

RX_OK (0x0000)

Function completed successfully.






Example Code

UINT uSignl; /* index handle to signal */ /* reset the event counter */ erXRes = rX_SigResetSignal(uSignl); if( erXRes == RX_OK ) { /* success, the signal event counter has been reset we can wait again */ erXRes = rX_SigWaitForSignal(uSignlIdx, RX_INFINITE); … } else { /* error */ … }



2.7.6 rX_SigDeleteSignal() – Delete a Signal rX_SigDeleteSignal() deletes a signal. Function Syntax in „C“-Convention RX_RESULT rX_SigResetSignal( UINT uSignlIdx ) Function Arguments Argument

Description


Description

RX_OK (0x0000)

The specified signal has been deleted.






Example Code

UINT uSignl; /* index handle to signal */ … /* Delete the signal now */ erXRes = rX_SigDeleteSignal(uSignlIdx); …



2.8 Mutex Services – Header-File AP_Mtx.h Providing Mutex Services <#include AP_Mtx.h> A Mutex (Mutual Exclusion Object) is used to prevent simultaneous access to code and data areas.

2.8.1 rX_MtxCreateMutex() – Create a Mutex rX_MtxCreateMutex() creates a mutex. The function has to be provided with pre-allocated memory for the mutex, which must have the size of RX_MUTEX_SIZE bytes. Function Syntax in „C“-Convention RX_RESULT rX_MtxCreateMutex( STRING* pszIdn, RX_HANDLE hMtx, UINT uMaxPrc ) Function Arguments Argument

Description

pszIdn

Mutex name Pointer to a NUL terminated string of a maximum of 16 bytes, includ-ing the terminating NUL character

hMtx Pointer to a memory block with RX_MUTEX_SIZE bytes. uMaxPrc not implemented


Description

RX_OK (0x0000)



Object with same name already exists.


Name too long.

Allowed to be called by Initialization, Task and Application Timers.



Pre-emption possible Yes Example Code

RX_HANDLE hMtxTsk1; /* Mutex Handle */ … erXRes = rX_MemAllocateMemory(&hMtxTsk1,RX_MUTEX_SIZE); /* Create the mutex now */ erXRes = rX_MtxCreateMutex(“MTX500”, hMtxTsk1,10); if(erXRes == RX_OK) { /* success, wait now to get mutex */ erXRes = rX_MtxLockMutex(hMtxTsk1,RX_INFINITE) … } else { /* error, the mutex does not seem to exist * we have to abort our processing */ }



2.8.2 rX_MtxIdentifyMutex() – Identify a Mutex by Name This function identifies a mutex with the specified name and instance number. Function Syntax in „C“-Convention RX_RESULT rX_MtxIdentifyMutex( STRING* pszIdn, UINT uInst, RX_HANDLE* phMtx ) Function Arguments Argument

Description

pszIdn

Mutex name Pointer to a NUL terminated string of a maximum of 16 bytes, includ-ing the terminating NUL character

uInst Instance number phMtx Pointer to variable where to copy the mutex handle to.


Description

RX_OK (0x0000)


RX_MTX_UNKNOWN (0x0606)

Mutex is unknown.




Example Code

RX_HANDLE hMtxTsk1; /* Get the Handle to a mutex named ‘MTX500’ */ erXRes = rX_MtxIdentifyMutex(“MTX500”,0,&hMtxTsk1); if( erXRes == RX_OK ) { /* success*/ … } else { /* mutex does not exist */ … }



2.8.3 rX_MtxLockMutex() – Lock a Mutex This function locks a mutex. Recursive locking is supported. Function Syntax in „C“-Convention RX_RESULT rX_MtxLockMutex( RX_HANDLE hMtx, UINT uTimeout ) Function Arguments Argument

Description

hMtx Mutex handle

uTimeout • not implemented • set always to RX_INFINITE


Description

RX_OK (0x0000)




RX_MTX_DELETED (0x0603)

While waiting to lock the mutex, the mutex has been de-leted.

Allowed to be called by Initialization, Tasks and Application Timers. Pre-emption possible Yes



Example Code

RX_HANDLE hMtxTsk2; /* Mutex Handle */ /* Wait for a mutex to be locked */ erXRes = rX_MtxLockMutex(hMtxTsk2,RX_INFINITE); if( erXRes == RX_OK ) { /* success, the mutex was successfully locked */ … } else { /* we could not get the mutex, something must be wrong * we abort our processing with an error */ … }



2.8.4 rX_MtxUnlockMutex() – Unlock a Mutex This function unlocks the mutex. For each call to rX_MtxLockMutex(), a call to rX_MtxUnlockMutex() must be done. Function Syntax in „C“-Convention RX_RESULT rX_MtxUnlockMutex( RX_HANDLE hMtx ) Function Arguments Argument

Description

hMtx Mutex handle Function Return Values Return Value

Description

RX_OK (0x0000)







Example Code

extern UINT uResource; /* External Resource */ … RX_HANDLE hMtxTsk2; /* Mutex Handle */ … /* Wait to get the Mutex */ erXRes = rX_MtxLockMutex(hMtxTsk2,RX_INFINTE); /* The Mutex has been granted */ uResource++; /* change the shared Resource */ /* Unlock the Mutex */ erXRes = rX_MtxUnLockMutex(hMtxTsk2); if( erXRes == RX_OK ) { /* success, the mutex was successfully unlocked */ … } else { /* seems that something went wrong * we have to return an error here */ … }



2.8.5 rX_MtxDeleteMutex() – Delete a Mutex This function deletes a mutex. It is the task’s responsibility to manage the memory area as-sociated with the mutex after the deletion. Function Syntax in „C“-Convention RX_RESULT rX_MtxDeleteMutex( RX_HANDLE hMtx ) Function Arguments Argument

Description

hMtx Mutex handle Function Return Values Return Value

Description

RX_OK (0x0000)







Example Code

RX_HANDLE hMtx; /* Mutex Handle */ … void stop(void) { /* Delete the mutex */ erXRes = rX_MtxDeleteMutex(hMtx); if( erXRes == RX_OK ) { /* success, the mutex is removed */ … } else { /* error, the mutex was not deletable */ … } }



2.9 Semaphore Services – Header-File AP_Sem.h Providing Semaphore Services <#include AP_Sem.h> Semaphores are used to synchronize tasks and also used to synchronize access to shared resources. If more than one task is waiting to obtain a semaphore, the one with the highest priority is released if the semaphore becomes available.

2.9.1 rX_SemCreateSemaphore() –Create a Semaphore rX_SemCreateSemaphore() creates a semaphore. The function has to be provided with pre-allocated memory for the semaphore, which must have the size of RX_SEMAPHORE_SIZE bytes. Function Syntax in „C“-Convention RX_RESULT FAR rX_SemCreateSemaphore( STRING* pszIdn, RX_HANDLE hSem, UINT uMaxPrc ) Function Arguments Argument

Description

pszIdn

Semaphore name Pointer to a NUL terminated name string of a maximum of 16 bytes, including the terminating 0 character

hSem Pointer to a memory block with RX_SEMAPHORE_SIZE bytes. uMaxPrc Initial count value of the semaphore


Description

RX_OK (0x0000)



Name already exists.


Name too long.





RX_HANDLE hSemTsk1; /* semaphore handle */ … erXRes = rX_MemAllocateMemory(&hSemTsk1,RX_SEMAPHORE_SIZE); /* Create the semaphore now */ erXRes = rX_SemCreateSemaphore(“SEM2003”,hSemTsk1,5); if( erXRes == RX_OK ) { /* success, wait now for semaphore to get */ erXRes = rX_SemGetSemaphore(hSemTsk1,RX_INFINITE) … }



2.9.2 rX_SemIdentifySemaphore() – Identify a Semaphore by Name

rX_SemIdentifySemaphore() identifies a semaphore with the specified name and instance. Function Syntax in „C“-Convention RX_RESULT rX_SemIdentifySemaphore( STRING* pszIdn, UINT uInst, RX_HANDLE* phSem ) Function Arguments Argument

Description

pszIdn Pointer to a NUL terminated name string uInst Instance number phSem Pointer to variable to receive the semaphore handle in


Description

RX_OK (0x0000)


RX_SEM_UNKNOWN (0x0506)

Semaphore is not known.




Example Code

RX_HANDLE hSemTsk1; /* Get the handle to a semaphore named ‘SEM2003’ */ erXRes = rX_SemIdentifySemaphore(“SEM2003”,0,&hSemTsk1); if( erXRes == RX_OK ) { /* success */ … } else { /* failed, semaphore seems not to be installed */ … }



2.9.3 rX_SemWaitForSemaphore() – Wait to get a Semaphore rX_SemWaitForSemaphore() tries to get the defined semaphore. The function will decrement the semaphore counter and if it is already 0, it will wait for the specified timout or until an-other task has called rX_SemPutSemaphore(). Function Syntax in „C“-Convention RX_RESULT rX_SemWaitForSemaphore( RX_HANDLE hSem, UINT uTimeout ) Function Arguments Argument

Description

hSem Semaphore handle

uTimeout


Time in tick count, the function will wait for the the semaphore. • RX_INFINITE (0x00000000)

rX_SemWaitForSemaphore() will wait until the semaphore can be obtained.


Check if semaphore can be otained or not. If it was not possi-ble to get it, an error is returned.


Description

RX_OK (0x0000)

Semaphore was successfully obtained (decremented)



RX_SEM_DELETED (0x0503)

Semaphore is deleted while witing on it.

RX_TIMEOUT (0x0001)

The semaphore was not available within the specified tick time.

RX_SEM_NOT_AVAILABLE (0x0507)

Semaphore cannot be obtained.



Allowed to be called by Initialization and Tasks if uTimOpt = RX_FINITE then also ISR and Application Timers. Pre-emption possible Yes. Example Code

RX_HANDLE hSemTsk; /* semaphore Handle */ /* Wait for a semaphore resource an infinite time */ erXRes = rX_SemWaitForSemaphore(hSemTsk,RX_INFINTE); if( erXRes == RX_OK ) { /* success, got one resource of the semaphore */ … } else { /* the waiting was aborted, so we need to determine the reason why */ … }



2.9.4 rX_SemGetSemaphore() – Try to get a Semaphore rX_SemGetSemaphore() tries to obtain a semaphore by decrement the semaphore counter. If it has already reached 0, an error is returned. Function Syntax in „C“-Convention RX_RESULT rX_SemGetSemaphore( RX_HANDLE hSem ) Function Arguments Argument

Description

hSem Semaphore handle Function Return Values Return Value

Description

RX_OK (0x0000)

Semaphore successfully obtained (decremented).



RX_SEM_NOT_AVAILABLE (0x0507)

Semaphore cannot be obtained.

Allowed to be called by Tasks Pre-emption possible Yes.



Example Code

RX_HANDLE hSemTsk; /* semaphore handle */ /* Just try to get one semaphore resource */ erXRes = rX_SemGetSemaphore(hSemTsk); if(erXRes == RX_OK ) { /* success, got one resource of the semaphore */ … } else { if( erXRes == RX_SEM_NOT_AVAILABLE ) { /* Failed, semaphore does not have any resource left */ … } else { /* unexpected error here, check how to handle it */ … } }



2.9.5 rX_SemPutSemaphore() – Return a retrieved Semaphore rX_SemPutSemaphore() released the given semaphore by incrementing the semaphore counter. If it the counter was 0, a waiting task will be set into the ready state. Function Syntax in „C“-Convention RX_RESULT rX_SemPutSemaphore( RX_HANDLE hSem ) Function Arguments Argument

Description


Description

RX_OK (0x0000)

Semaphore successfully released (incremented).



RX_SEM_OVERFLOW (0x0507)

Semaphore counter value overflow (0xFFFFFFFF)

Allowed to be called by Initialization, Task, ISR and Application Timer Pre-emption possible Yes.



Example Code

extern UINT uResource; /* external resource */ … RX_HANDLE hSem; /* semaphore handle */ … /* Wait to get one resource of the semaphore */ erXRes = rX_SemWaitForSempahore(hSem,RX_INFINTE); /* A resource was received */ uResource++; /* change the shared Resource */ /* Unlock the Mutex */ erXRes = rX_SemPutSemaphore(hSem); if( erXRes == RX_OK ) { /* success, the resource could be granted */ … } else { /* could not access the semaphore */ … }



2.9.6 rX_SemDeleteSemaphore() – Delete a Semaphore rX_SemDeleteSemaphore() deletes a semaphore. If a task is waiting on this semaphore, it will be activated and the error code RX_SEM_DELETED is returned. It is the task’s responsibility to manage the memory area associated with the semaphore af-ter the deletion. Function Syntax in „C“-Convention RX_RESULT rX_SemDeleteSemaphore( RX_HANDLE hSem ) Function Arguments Argument

Description


Description

RX_OK (0x0000)



Object handle invalid.




Example Code

RX_HANDLE hSem; /* semaphore handle */ … void stop(void) { /* Delete the semaphore */ erXRes = rX_SemDeleteSemaphore(hSem); if( erXRes == RX_OK ) { /* success the semaphore has been removed */ … } else { /* failed to delete the semaphore */ … } }



2.9.7 rX_SemWaitForSemaphoreCount() – Wait for a Semaphore This function can be used to handle a semaphore as a counting semaphore. The semaphore resource counter is used as an event counting variable. Such a semaphore is usually required if the Semaphore is required to count events that are needed to be handed over from one to another Task. The Task that is setting the events uses rx_SemPutSemaphore(), while the Task that is waiting on events is using rX_SemWaitForSemaphoreCount(). Whenever rX_SemWaitForSemaphoreCount() returns, it resets the resource counter to the value 0 and all new occurrences of these events are counted from this time on. Note: The semaphore counter does not have an upper limit (wrap-qround possible) Function Syntax in „C“-Convention RX_RESULT rX_SemWaitForSemaphoreCount( RX_HANDLE hSem, UINT* puCurCnt, UINT uTimeout ) Function Arguments Argument

Description

hSem Semaphore handle.

puCurCnt Pointer to destination variable where to copy the current number of counted events to.

uTimeout


Time in tick counts to wait, if the semaphore value was 0. • RX_INFINITE (0x00000000)

rX_SemWaitForSemaphoreCount() will wait until the value of the semaphore is unequal 0.


Retrieve the current semaphore count and resets the counter to 0. If it was 0, it will return an error.




Description

RX_OK (0x0000)




RX_SEM_DELETED (0x0503)

Semaphore object deleted, while waiting on it.

RX_SEM_TIMEOUT (0x0505)

Semaphore not been incremented during the given wait time.

RX_SEM_NO_COUNT (0x050B)

Semaphore was not incremented.

Allowed to be called by Tasks If ulTimOpt = RX_FINITE then also ISR and Application Timers. Pre-emption possible Yes



Example Code

RX_HANDLE hSemTsk; /* semphore handle */ Task1: ... /* Set the event by incrementing the resource counter of the semaphore */ erXRes = rX_SemPutSemaphore(hSemTsk); Task2: UINT uCnt; ... /* Wait for a semaphore counter an infinite time */ erXRes = rX_SemWaitForSemaphoreCount(hSemTsk,&uCnt,RX_INFINTE); if( erXRes == RX_OK ) { /* success, semaphore got a counter */ while(uCnt--) { /* Execute the loop as often as the semaphore has been counted */ } … } else { /* something happened with the semaphore, * let’s determine the reason */ … }



2.9.8 rX_SemClearSemaphoreCount() – Clear the Semaphore Count Value

rX_SemClearSemaphoreCount() resets the semaphore (semaphore counter = 0). Function Syntax in „C“-Convention RX_RESULT rX_SemClearSemaphoreCount( RX_HANDLE hSem ) Function Arguments Argument

Description


Description

RX_OK (0x0000)

Function successful






Example Code

RX_HANDLE tSemTsk; /* semaphore handle */ ... erXRes = rX_SemClearSemaphoreCount(hSemTsk); if( erXRes == RX_OK ) { /* success, semaphore counter has been cleared */ … } else { /* semaphore seems not to exist anymore */ … }



2.10 Timer Services – Header-File AP_Tim.h Providing Timer Services <#include “AP_Tim.h”> Timer services are based on the system timer of the rcX.

2.10.1 rX_TimCreateTimer() – Creates an Application specific Timer

rX_TimCreateTimer() creates an application timer. The function has to be provided with pre-allocated memory for the timer, which must have the size of RX_TIMER_SIZE bytes. Function Syntax in „C“-Convention RX_RESULT rX_TimCreateTimer( RX_HANDLE hTim, void (CALLBACK* fnExp) (void* pvInpt), void* pvInpt, RX_TIM_FUNCTION eTimFnc, UINT uTimTckRld, UINT uSrtTckDly ) Function Arguments Argument

Description

hTim Pointer to a memory block with RX_TIMER_SIZE bytes. fnExp Pointer to the call-back function being called when the timer expires. pvInpt User data pointer for the call-back function

eTimFnc

This value defines the behaviour of the timer at expiration. Following values are possible:

• RX_TIM_AUTO_STOP The timer stops automatically after its expiration, but is not de-leted.

• RX_TIM_AUTO_RELOAD

The timer reloads itself with the specified uTimTckRld value automatically after its expiration.

• RX_TIM_AUTO_DELETE

The timer is deleted after its expiration.

uTimTckRld

Reload value in system timer ticks (only used if RX_TIM_AUTO_RELOAD is set) The value range is 0x00000001 to 0xFFFFFFFF.



uSrtTckDly

Initial timer start value in system timer ticks The value range is 0x00000000 to 0xFFFFFFFF. If a value of zero is specified, the timer is created in stop mode.


Description

RX_OK (0x0000)



RX_HANDLE hMyTimer; /* timer handle */ static const abIdx [] = {1,5,6,9,10}; /* Some indices handed over to timer function */ /* Callback routine of timer */ void CALLBACK TxTimer(void* pvIndex) { abBuffer[*((UINT8 *)pvIndex)] = TRUE; } … erXRes = rX_MemAllocateMemory(&hMyTimer,RX_TIMER_SIZE); erXRes = rX_TimCreateTimer(hMyTimer,TxTimer,&abIdx[3],

RX_TIM_AUTO_STOP, 0,100);

…



2.10.2 rX_TimSetTime() – Sets the current time of a Timer rX_TimSetTime() sets a new value from which the application timer begins to count down the ticks from. Function Syntax in „C“-Convention RX_RESULT rX_TimSetTime( RX_HANDLE hTim, UINT uNewVal ) Function Arguments Argument

Description

hTim Timer handle

uNewVal

Value the timer should be set to in system timer ticks. he value range is 0x00000000 to 0xFFFFFFFF. If the value specified is 0, the timer will be stopped.


Description

RX_OK (0x0000)


RX_TIM_INVALID (0x0201)





Example Code

RX_HANDLE hMyTimer; /* timer handle */ void restart(void) { erXRes = rX_TimSetTime(hMyTimer, 500); /* Set the timer to 500 ticks */ … }



2.10.3 rX_TimSetReload() – Sets the reload value of a Timer rX_TimSetReload() sets a new reload value. Function Syntax in „C“-Convention RX_RESULT rX_TimSetReload( RX_HANDLE hTim, UINT uNewRld ) Function Arguments Argument

Description

hTim Timer handle

uNewRld

New value the timer reload value in ticks. The value range is 0x00000000 to 0xFFFFFFFF. If the value is specified to 0, the timer is stopped on the next reload.


Description

RX_OK (0x0000)







Example Code

RX_HANDLE hMyTimer; /* timer handle */ void NewAndReset(UINT uTcks) { erXRes = rX_TimSetReload(hMyTimer, uTcks); /* Set new reload value */ … }



2.10.4 rX_TimGetTime() – Gets the current timer value of a Timer This function allows a task to read the current tick value of the specified timer. Function Syntax in „C“-Convention RX_RESULT rX_TimGetTime( RX_HANDLE hTim, UINT* puCurVal ) Function Arguments Argument

Description

hTim Timer handle puCurVal Pointer to UINT variable where to copy the tick value to


Description

RX_OK (0x0000)







Example Code

RX_HANDLE hMyTimer; /* timer handle */ UINT uCurRunVlu; … erXRes = rX_TimGetTime(hMyTimer, &uCurRunVlu); /* get the current time */

if( uCurRunVul < 300 ) { /* check if timer passed 300 ticks already */ … } else if(uCurRunVul < 100 ) { /* timer passed 100 ticks */ … } else { /* it’s not time to do anything */ … } …



2.10.5 rX_TimResetTimer() – Reloads a Timer rX_TimResetTimer() reloads the timer to the currently configured reload value. Function Syntax in „C“-Convention RX_RESULT rX_TimResetTimer( RX_HANDLE hTim ) Function Arguments Argument

Description

hTim Timer Handle Function Return Values Return Value

Description

RX_OK (0x0000)




Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No. Example Code

RX_HANDLE hMyTimer; /* timer handle */ … erXRes = rX_TimResetTimer(hMyTimer); /* reset the timer */

…



2.10.6 rX_TimStopTimer() – Stops a Timer rX_TimStopTimer() stops the current timer. The timer tick count value will be changed to 0. Function Syntax in „C“-Convention RX_RESULT rX_TimStopTimer( RX_HANDLE hTim ) Function Arguments Argument

Description

hTim Timer handle Function Return Values Return Value

Description

RX_OK (0x0000)




Allowed to be called by Initialization, Task, ISR and Application Timer Pre-emption possible No. Example Code

RX_HANDLE hMyTimer; /* timer handle */ … erXRes = rX_TimStopTimer(hMyTimer); /* stop the timer */ …



2.10.7 rX_TimHaltTimer() – Halts a Timer rX_TimHaltTimer() halts the specified timer. The tick count value is frozen until rX_TimResumeTimer() is called. Function Syntax in „C“-Convention RX_RESULT rX_TimHaltTimer( RX_HANDLE hTim ) Function Arguments Argument

Description


Description

RX_OK (0x0000)







Example Code

RX_HANDLE hMyTimer; /* timer handle */ UINT halt(void) { erXRes = rX_TimHaltTimer(hMyTimer); /* halt the timer */

if( erXRes == RX_OK ) { /* success, timer halted */ … } else { /* the timer could not be halted */ … } … }



2.10.8 rX_TimResumeTimer() – Resumes a halted Timer rX_TimResumeTimer() resumes a previously halted timer. Function Syntax in „C“-Convention RX_RESULT rX_TimResumeTimer( RX_HANDLE hTim ) Function Arguments Argument

Description


Description

RX_OK (0x0000)




RX_TIM_NOT_HALTED (0x0206)

The specified timer has not been resumed before.

Allowed to be called by Initialization, Task, ISR and Application Timer Pre-emption possible No.



Example Code

RX_HANDLE hMyTimer; /* timer handle */ … erXRes = rX_TimResumeTimer(hMyTimer); /* Resume the timer */

if( erXRes == RX_OK ) { /* success, timer resumed */ … } else { /* the timer could not be resumed */ … }



2.10.9 rX_TimDeleteTimer() – Deletes a Timer rX_TimDeleteTimer() deletes an application timer. The task, which creates the timer, is responsibility to manage the memory area associated with the timer after the deletion. Function Syntax in „C“-Convention RX_RESULT rX_TimDeleteTimer( RX_HANDLE hTim ) Function Arguments Argument

Description


Description

RX_OK (0x0000)







Example Code

RX_HANDLE hTim; /* timer handle */ … void shutdown(void) { /* Delete the timer */ erXRes = rX_TimDeleteTimer(hTim); if( erXRes == RX_OK ) { /* success the timer has been removed */ … } else { /* the timer could not be deleted */ … } }



2.10.10 rX_TimCreateCycle() – Activates a Timer for periodic Task Activation

rX_TimCreateCycle() creates an cycle timer for periodic task activation The function has to be provided with pre-allocated memory for the timer, which must have the size of RX_CYCLIC_SIZE bytes. Function Syntax in „C“-Convention RX_RESULT rX_TimCreateCycle( STRING* pszIdn, RX_HANDLE hCyl, UINT uTim ) Function Arguments Argument

Description

pszIdn

Cyclic name Pointer to a string of a length of maximum 16 bytes 0 (15+1) termi-nated

hCyl Pointer to a memory block with RX_CYCLIC_SIZE bytes

uTim Cyclic timer period in ticks The value range is 0x00000001 to 0xFFFFFFFF.


Description

RX_OK (0x0000)


RX_TIM_ZERO (0x203)

uTim is 0.

RX_TIM_CYCLE_INVALID (0x0208)





Example Code

RX_HANDLE hMyCycle; /* cycle handle */ … erXRes = rX_MemAllocateMemory(&hMyCycle,RX_CYCLIC_SIZE); /* Set up a cycle of 100 timer ticks */ erXRes = rX_TimCreateCycle(“MyTick”,hMyCycle,100); … for(;;) { /* Wait now for the cyclic event */ erXRes = rX_TimeWaitForCycle(hMyCycle); if( erXRes == RX_OK ) { /* success, a cyclic event did occur? */ … } }



2.10.11 rX_TimWaitForCycle() – Wait for a cyclic Timer rX_TimWaitForCycle() waits for the expiration of a cyclic timer. The calling task is suspended until the wait time expires or the timer is deleted. Function Syntax in „C“-Convention RX_RESULT rX_TimWaitForCycle( RX_HANDLE hCyl ) Function Arguments Argument

Description

hCyl Cycle handle Function Return Values Return Value

Description

RX_OK (0x0000)




Allowed to be called by Tasks Pre-emption possible Yes.



Example Code

RX_HANDLE hMyCycle; /* cycle handle */ … erXRes = rX_MemAllocateMemory(&hMyCycle,RX_CYCLIC_SIZE); /* Set up a cycle of 100 timer ticks*/ erXRes = rX_TimCreateCycle(hMyCycle,100); … for(;;) { /* Wait now for the cyclic event */ erXRes = rX_TimWaitForCycle(hMyCycle); if( erXRes == RX_OK ) { /* success, we have been activated due the periodic event */ … } }



2.10.12 rX_TimResetCycle() – Reset a cyclic Task Timer rX_TimResetCycle() reloads the cyclic timer to the configured tick count value (the timer in-ternal missed event counter is also cleared). Function Syntax in „C“-Convention RX_RESULT rX_TimResetCycle( RX_HANDLE hCyl )

Function Arguments Argument

Description


Description

RX_OK (0x0000)







Example Code

RX_HANDLE hMyCycle; /* cycle handle */ ... erXRes = rX_MemAllocateMemory(&hMyCycle,RX_CYCLIC_SIZE); /* set up a cycle of 100 timer ticks*/ erXRes = rX_TimCreateCycle(hMyCycle,100); … for(;;) { /* Before we wait for the periodic event clear all collected events */ rX_TimResetCycle(hMyCycle); /* wait now for the cyclic event */ rX_TimWaitForCycle(hMyCycle); /* we have been activated due to the periodic event */ DoMyProcess(); }



2.10.13 rX_TimDeleteCycle() – Delete a cyclic Timer rX_TimDeleteCycle() deletes a cyclic timer. Tasks, waiting on the cyclic timer, will be acti-vated and the error code RX_TIM_CYCLE_INVALID is returned. The task, which created the timer, is responsibile to manage the memory area associated with the cyclic timer after the timer is deleted. Function Syntax in „C“-Convention RX_RESULT rX_TimDeleteCycle( RX_HANDLE hCyl ) Function Arguments Argument

Description


Description

RX_OK (0x0000)




Allowed to be called by Initialization, Task and Application Timer Pre-emption possible No.



Example Code

RX_HANDLE hMyCycle; /* cycle handle */ ... erXRes = rX_MemAllocateMemory(&hMyCycle,RX_CYCLIC_SIZE); /* Set up a cycle of 100 timer ticks*/ erXRes = rX_TimCreateCycle(hMyCycle,100); … for(;;) { /* Wait now for the cyclic event */ erXRes = rX_TimWaitForCycle(hMyCycle); if( erXRes == RX_OK ) { /* success, an event did occur, but which one ?*/ … } ... break; } erXRes = rX_TimDeleteCycle(hMyCycle);



2.11 Diagnostic Services – Header-File AP_Dia.h Providing Diagnostic Services <#include “AP_Dia.h”>

2.11.1 rX_DiaCreateInformationField() – Creates an Information structure

rX_DiaCreateInformationField() creates a structured information block which is used for addi-tional diagnostic information. Multiple blocks can be registered for each task. The function has to be provided with pre-allocated memory for the information field, which must have the size of RX_INFORMATION_SIZE bytes. Function Syntax in „C“-Convention RX_RESULT rX_DiaCreateInformationField ( RX_HANDLE hTskNfo, UINT uLen, void* pvStr ) Function Arguments Argument

Description

hTskNfo Pointer to a memory block with RX_INFORMATION_SIZE bytes uLen Length of the information block pvStr Pointer to the information block


Description

RX_OK (0x0000)

Information block has been created.

Allowed to be called by Task Pre-emption possible No.



Example Code

typedef struct TSK_STATS_Ttag { UINT32 ulNumofRXBytes; UINT32 ulNumofTXBytes; UINT32 ulNumofErrors; UINT16 usLastError; } TSK_STATS_T; TSK_STATS_T tTskStats; /* task statistic information field */ RX_HANDLE hTskNfo; /* information field handle */ ... erXRes = rX_MemAllocateMemory(&hTskNfo,RX_INFORMATION_SIZE); erXRes = rX_DiaCreateInformationField(hTskNfo, sizeof(TSK_STATS_T), &tTskStats); … void DoStats(fRx,fTx,fErr) { if(fRx == TRUE) { tTskStats.ulNumofRXBytes++; } if(fTx == TRUE) { tTskStats.ulNumofTXBytes++; } ... }



2.11.2 rX_DiaGetInformationField() – Gets a Task’s Information structure reference

rX_DiaGetInformationField() retrieves a diagnostic information block from a particular task. The diagnostic information blocks are numbered in ascending order which is defined by the order of the registration by rX_DiaCreateInformationField(). Function Syntax in „C“-Convention RX_RESULT rX_DiaGetInformationField ( RX_HANDLE hTsk, UINT uNfoNum, RX_INFORMATION_ENTRY_T* ptNfo ) Function Arguments Argument

Description

hTsk Handle of the task uNfoNum The index of the diagnostic information block in the task

ptNfo Pointer to a structure RX_INFORMATION_ENTRY_T where the func-tion will copy the length of the field and its location pointer to


Description

RX_OK (0x0000)

The specified information block has been found.

RX_DIA_INFO_INVALID (0x1001)

The specified diagnostic information block number is in-valid.




Example Code

RX_HANDLE hRemoteTask; RX_INFORMATION_ENTRY_T tNfo; void* pvDest; ... /* interested in first information structure the task has created */ erXRes = rX_DiaGetInformationField(hRemoteTask, 0, &tNfo); if(erXRes == RX_OK) { /* information field has been found */ rX_MemAllocateMemory(&pvDest, tNfo.uLen); /* get memory for local copy */ memcpy(pvDest,tNfo.pvStr,tNfo.uLen); /* make a local copy */ … } else { /* information field does not exist */ }



2.11.3 rX_DiaCreateHookTaskStatus() – Installs a Callback func-tion for Task Status changes

rX_DiaCreateHookTaskStatus() allows a task to install a call-back on task status updates. All status codes of all tasks are organized in an array in the structure RX_TASKS_STATUS_T. A pointer to this structure is passed to the specified call-back. The call-back is not allowed to call any function that will cause pre-emption. rX_DiaCreateHookTaskStatus() takes a pre-allocated memory block of RX_HOOK_SIZE bytes as a handle. Function Syntax in „C“-Convention RX_RESULT rX_DiaCreateHookTaskStatus( RX_HANDLE hHok, RX_RESULT (CALLBACK* fnNtfy) (RX_TASKS_STATUS_T* ptTskSta, void* pvInp), void* pvInp ) Function Arguments Argument

Description

hHok Pointer to a memory block with RX_HOOK_SIZE bytes.

fnNtfy

Pointer to call-back function Its parameters are:

• Pointer to the task status block of rcX. • A void pointer with user data

pvInp User data pointer Function Return Values Return Value

Description

RX_OK (0x0000)

Hook successfully installed.

Allowed to be called by Task Pre-emption possible No.



Example Code

/* This is the callback function that suppose to be called */ RX_RESULT CALLBACK TskChange(RX_TASKS_STATUS_T* ptSta, void* pvPrm) { ... return(RX_OK) } void TaskInit(void) { RX_HANDLE hHok; /* instance number to be handed over to the callback function */ UINT uInst = 5; /* allocate memory for the hook first of all */ rX_MemAllocateMemory(&hHok,RX_HOOK_SIZE); ... /* install the system status hook in case the status has been changed */ rX_DiaCreateHookTaskStatus(hHok,TskChange,&uInst); … }



2.11.4 rX_DiaSetTaskStatus() – Changes the Status Code of a Task

rX_DiaSetTaskStatus() allows a task to report a task-specific status code, which can be read by diagnostic tools. Function Syntax in „C“-Convention void rX_DiaSetTaskStatus( UINT uSta ) Function Arguments Argument

Description

uSta

Status code to report A value of TASK_STA_OK (0) signals that the task has no status condition or error condition to report.


Description

None None Allowed to be called by Task Pre-emption possible No. Example Codes

void InitializationFinished(void) { /* clears task’s error condition */ rX_DiaSetTaskStatus(TASK_STA_OK); } void RuntimError(UINT uErrCod) { … /* set a task’s error to a User defined error code */ rX_DiaSetTaskStatus(uErrCod); }



2.11.5 rX_DiaGetTaskStatus() – Returns the Status Code of a Task rX_DiaGetTaskStatus() returns the status code of a specified task. Function Syntax in „C“-Convention RX_RESULT rX_DiaGetTaskStatus( RX_HANDLE hTsk, UINT* puSta ) Function Arguments Argument

Description

hTsk Handle of the task puSta Pointer to destination variable to copy the status code to


Description

RX_OK (0x0000)

The status code has been retrieved.


The task handle is invalid.




Example Code

RX_RESULT erXRes; RX_HANDLE hTsk; UINT uTskSta; /* look for the task named ‘TESTTSK1’ */ erXRes = rX_SysIdentifyTask("TESTTSK1", 0, &hTsk, NULL,NULL); if(erXRes == RX_OK) { /* task is identified */ /* get the current status of that task */ erXRes = rX_DiaGetTaskStatus(hTsk,&uTskSta); if(erXRes == RX_OK) { /* we got the status of it */ … } } …



2.12 Memory Services – Header-File AP_Mem.h Providing Memory Services <#include “AP_Mem.h”> Memory functions are based on the libc library, included in the rcX.

2.12.1 rX_MemAllocateMemory() – Requests a Memory Block from the Pool

rX_MemAllocateMemory() allocates a memory block from the memory heap. This function calls the malloc() function of the libc library. Function Syntax in „C“-Convention RX_RESULT rX_MemAllocateMemory( void** ppvMem, UINT32 ulSiz ) Function Arguments Argument

Description

ppvMem Pointer to the variable where to copy the pointer of the memory block to

ulSiz Size of the memory block in Bytes Function Return Values Return Value

Description

RX_OK (0x0000)

A memory block has been allocated.

RX_MEM_RESOURCE (0x0103)

Out of memory




Example Code

RX_HANDLE hBar; RX_HANDLE hMbx; RX_HANDLE hQue; ... /* Allocate memory for the handles */ erXRes = rX_MemAllocateMemory(&hBar,RX_BARRIER_SIZE); erXRes = rX_MemAllocateMemory(&hMbx,RX_MAILBOX_SIZE); erXRes = rX_MemAllocateMemory(&hQue,RX_QUEUE_SIZE); ...



2.12.2 rX_MemFreeMemory() – Returns an allocated Memory Block to the Pool

rX_MemFreeMemory() frees a memory block, which has been previously allocated by rX_MemAllocateMemory(). This function calls the free() function of the libc library. Function Syntax in „C“-Convention RX_RESULT rX_MemFreeMemory( void* pvMem ) Function Arguments Argument

Description

pvMem Pointer of the memory block to be freed Function Return Values Return Value

Description

RX_OK (0x0000)

The Memory block is freed.




Example Code

RX_HANDLE hBar; RX_HANDLE hMbx; RX_HANDLE hQue; ... /* Allocate Memory for the Handles */ erXRes = rX_MemAllocateMemory(&hBar,RX_BARRIER_SIZE); erXRes = rX_MemAllocateMemory(&hMbx,RX_MAILBOX_SIZE); erXRes = rX_MemAllocateMemory(&hQue,RX_QUEUE_SIZE); ... /* Deallocate the previous Memory when leaving */ erXRes = rX_MemFreeMemory(hBar); erXRes = rX_MemFreeMemory(hMbx); erXRes = rX_MemFreeMemory(hQue);



2.12.3 rX_MemCreateSharedMemory() – Creates one Memory to Share

rX_MemCreateSharedMemory() creates a shared memory block The function has to be provided with pre-allocated memory for the shared memory, which must have the size of RX_SHAREDMEMORY_SIZE bytes as well as the memory block as-sociated with it. Function Syntax in „C“-Convention RX_RESULT rX_MemCreateSharedMemory ( STRING* pszIdn, RX_HANDLE hShm, void* pvShm, UINT uSiz ) Function Arguments Argument

Description

pszIdn

Shared memory name Pointer to a string of a length of maximum 16 bytes 0 (15+1) termi-nated

hShm Pointer to a memory block with RX_SHAREDMEMORY_SIZE bytes pvShm Pointer to the memory area to be shared uSiz Size of the memory area to be shared in bytes


Description

RX_OK (0x0000)

The shared memory has been created

RX_MEM_NAME (0x0101)

A shared memory object with the same name exists al-ready.

Allowed to be called by Initialization, Task, and Application Timers. Pre-emption possible Yes



Example Code

UINT8 abOutputData; /* output area to share */ UINT8 abInputData; /* input area to share */ RX_HANDLE hShmOut; /* shared memory handle output data*/ RX_HANDLE hShmIn; /* shared memory handle input data */ … /* Reserve memory first */ erXRes = rX_MemAllocateMemory(&hShmOut,RX_SHAREDMEMORY_SIZE); erXRes = rX_MemAllocateMemory(&hShmIn,RX_SHAREDMEMORY_SIZE); … /* Create the shared memory now */ erXRes = rX_MemCreateSharedMemory(“OUT”, hShmOut, &abOutputData, sizeof(abOutputData)); erXRes = rX_MemCreateSharedMemory(“In”, hShmIn, &abInputData, sizeof(abInputData)); ...



2.12.4 rX_MemIdentifySharedMemory() – Identifies a Shared Memory by Name

rX_MemIdentifySharedMemory() identifies a shared memory object with the specified name and instance. Function Syntax in „C“-Convention RX_RESULT rX_MemIdentifySharedMemory( STRING* pszIdn, UINST uInst, RX_HANDLE* phShm ) Function Arguments Argument

Description

pszIdn Pointer to a shared memory name as 0 terminated string uInst Instance number

phShm Pointer to a variable where to copy the handle of the shared memory to


Description

RX_OK (0x0000)

Shared memory object has been identified.

RX_MEM_UNKNOWN (0x0109)

Shared memory object is not known.




Example Code

RX_HANDLE hShm; /* Get the handle to a shared memory named ‘Shared’ instance 5 */ erXRes = rX_MemIdentifySharedMemory(“Shared”,5,&hShm); if(erXRes == RX_OK) { /* success*/ … } else { /* failed, shared memory seems not to be existing */ … }



2.12.5 rX_MemGetSharedMemoryInfo() – Gets the Shared Memory Parameters

rX_MemGetSharedMemoryInfo() returns the information about the shared memory object which includes the pointer to the actual memory and the size of it. However, it does not lock it. Function Syntax in „C“-Convention RX_RESULT rX_MemGetSharedMemoryInfo( RX_HANDLE hShm, void** ppvShm, UINT* puSiz ) Function Arguments Argument

Description

hShm Shared memory handle

ppvShm Pointer to the variable where to copy the pointer of the shared mem-ory pointer to

puSiz Pointer to the variable where to copy the size of the shared memory area to


Description

RX_OK (0x0000)

The information has been retrieved.






Example Code

RX_HANDLE hShm; UINT uSiz; void* pShm; … /* Get the parameters of the shared memory */ erXRes = rX_MemGetSharedMemoryInfo(hShm,&pShm,&uSiz); if( erXRes == RX_OK ) { /* success*/ … } else { /* failed, shared memory handle is not valid */ … }



2.12.6 rX_MemLockSharedMemory() – Locks Shared Memory against Concurrent Accesses

rX_MemLockSharedMemory() locks the shared memory object against concurrent accesses. Function Syntax in „C“-Convention RX_RESULT rX_MemLockSharedMemory( RX_HANDLE hShm, UINT uTimeout) Function Arguments Argument

Description

hShm Shared memory handle

uTimeout

• Timeout value in system timer ticks • • 0x00000001 – 0xFFFFFFFE

These values specify a tick count how many ticks to be waited if rX_MemLockSharedMemory has not been able to lock the shared memory yet.

• • RX_INFINITE (0x00000000)

rX_MemLockSharedMemory() will wait until the shared mem-ory could have been locked.

• • RX_FINITE (0xFFFFFFFF)

It tells rX_SemWaitForSemaphore() to try to lock the shared memory. If it could not be locked, it will return an error.


Description

RX_OK (0x0000)

The shared memory object has been locked.



RX_MEM_NO_ACCESS (0x010B)

The shared memory object could not be locked.

RX_TIMEOUT (0x0001)

Timeout occurred before the shared memory could be locked.

RX_MEM_DELETED (0x010D)

The shared memory has been deleted while waiting for locking it.



Allowed to be called by Initialization, Tasks if uTimOpt = RX_FINITE then Application Timers too. Pre-emption possible Yes. Example Code

RX_HANDLE hShm; UINT uSiz; UINT8* pbShm; /* Get the parameters of the shared memory */ erXRes = rX_MemGetSharedMemoryInfo(hShm,&pbShm,&uSiz); /* Wait for the access right to the shared memory */ erXRes = rX_MemLockSharedMemory(hShm,RX_INFINITE); if( erXRes == RX_OK ) { /* success, access the memory now */ pbShm[5] = 0xAA; … } else { /* failed, shared memory does not seem to be created */ … }



2.12.7 rX_MemUnlockSharedMemory() – Releases the lock to a Shared Memory

rX_MemUnlockSharedMemory() releases the lock to a shared memory object. Function Syntax in „C“-Convention RX_RESULT rX_MemUnlockSharedMemory( RX_HANDLE hShm ) Function Arguments Argument

Description

hShm Shared memory handle Function Return Values Return Value

Description

RX_OK (0x0000)

The shared memory has been unlocked.



Allowed to be called by Initialization, Task and Application Timer Pre-emption possible Yes.



Example Code

RX_HANDLE hShm; UINT uSiz; UINT8* pbShm; /* Get the parameters of the shared memory */ erXRes = rX_MemGetSharedMemoryInfo(hShm,&pbShm,&uSiz); /* Wait for the access right to the shared memory */ erXRes = rX_MemLockSharedMemory(hShm,RX_INFINITE); if( erXRes == RX_OK ) { /* success, access the memory now*/ pbShm[5] = 0xAA; … /* return the access right */ erXRes = rX_MemUnlockSharedMemory(hShm); } else { /* failed, shared memory does not seem to be created */ … }



2.13 Triple Buffer Services – Header-File AP_Mem.h

2.13.1 rX_MemCreateTripleBuffer() – Creates a Triple Buffer for Exchanging Data

rX_MemCreateTripleBuffer() creates a triple buffer. The function has to be provided with pre-allocated memory for the triple buffer control block, which must have the size of RX_TRIPLEBUFFER_SIZE bytes. Function Syntax in „C“-Convention RX_RESULT rX_MemCreateTripleBuffer( STRING* pszIdn, RX_HANDLE hTrp, RX_BUFFERPOOL_T* ptBufPool ) Function Arguments Argument

Description

pszIdn

Triple Buffer name Pointer to a string of a length of maximum 16 bytes 0 (15+1) termi-nated

hTrp Pointer to a memory block with RX_TRIPLEBUFFER_SIZE bytes.

ptBufPool

Pointers to three buffer pointers to be used pabBufA Pointer to first buffer pabBufB Pointer to second buffer pabBufC Pointer to third buffer


Description

RX_OK (0x0000)

Function succeed.


A triple buffer with the name and the current’s task in-stance number exists already.


The specified ID string is longer than 16 bytes





UINT8 g_aabBufferIn[3][100]; UINT8 g_aabBufferOut[3][100]; VOID LoopBackTest(VOID* pvParam) { RX_HANDLE hTrpIn; /* Triple buffer handle: data in */ RX_HANDLE hTrpOut; /* data out */ RX_BUFFERPOOL_T tBufPoolIn; RX_BUFFERPOOL_T tBufPoolOut; UINT8* pabWriteBuffer; UINT8* pabReadBuffer; tBufPoolIn.pabBufA = &g_aabBufferIn[0][0]; tBufPoolIn.pabBufB = &g_aabBufferIn[1][0]; tBufPoolIn.pabBufC = &g_aabBufferIn[2][0]; tBufPoolOut.pabBufA = &g_aabBufferOut[0][0]; tBufPoolOut.pabBufB = &g_aabBufferOut[1][0]; tBufPoolOut.pabBufC = &g_aabBufferOut[2][0]; erXRes = rX_MemAllocateMemory(&hTrpIn, RX_TRIPLEBUFFER_SIZE); if(RX_OK != erXRes) { ... return; } /* Create the input triple buffer now */ erXRes = rX_MemCreateTripleBuffer(“INPUT_DATA”, hTrpIn, &tBufPool); if(RX_OK != erXRes) { ... return; } erXRes = rX_MemAllocateMemory(&hTrpOut, RX_TRIPLEBUFFER_SIZE); if(RX_OK != erXRes) { ... return; } /* Create the output triple buffer now */ erXRes = rX_MemCreateTripleBuffer(“OUTPUT_DATA”, hTrpOut, &tBufPool); if(RX_OK != erXRes) { ... return; } erXRes = rX_MemExchangeGetCurrentBuffer(hTrpOut, &pabWriteBuffer); if(RX_OK != erXRes) { ...



return erXRes; } /* loop back data every 10 ticks */ for(;;) { rX_SysSleepTask(10); /* wait 10 ticks */ /* get the current read buffer */ rX_MemGetExchangedBuffer(hTrpIn, &pabReadBuffer); /* copy the data */ memcpy(pabWriteBuffer, pabReadBuffer, 100); /* exchange the buffer and retrieve a new write buffer */ rX_MemExchangeBuffer(hTrpOut, &pabWriteBuffer); } }



2.13.2 rX_MemIdentifyTripleBuffer() – Identifies a Triple Buffer by Name

This function identifies a triple buffer with the specified name and instance. Function Syntax in „C“-Convention RX_RESULT rX_MemIdentifyTripleBuffer( STRING* pszIdn, UINT uInst, RX_HANDLE* phTripleBuffer ) Function Arguments Argument

Description

pszIdn Pointer to a name as 0 terminated string uInst Instance number phTripleBuffer Pointer to variable where to copy the triple buffer handle to.


Description

RX_OK (0x0000)

Function succeed.


A triple buffer with the name and the current’s task in-stance number exists already.


The specified ID string is longer than 16 bytes




Example Code

VOID CommunicateWithLoopBackTest(VOID* pvParam) { RX_HANDLE hTrpIn; /* Triple buffer handle: data in */ RX_HANDLE hTrpOut; /* data out */ UINT8* pabWriteBuffer; UINT8* pabReadBuffer; /* Identify the input triple buffer */ erXRes = rX_MemIdentifyTripleBuffer(“INPUT_DATA”, 0, &hTrpIn); if(RX_OK != erXRes) { ... return; } /* Identify the output triple buffer */ erXRes = rX_MemIdentifyTripleBuffer(“OUTPUT_DATA”, 0, &hTrpOut); if(RX_OK != erXRes) { ... return; } /* Loop back test’s output is our input */ erXRes = rX_MemExchangeGetCurrentBuffer(hTrpIn, &pabWriteBuffer); if(RX_OK != erXRes) { ... return erXRes; } /* increment data every 10 ticks and read back from the loopback */ for(;;) { UINT uIdx; rX_SysSleepTask(10); /* wait 10 ticks */ for(uIdx = 0; uIdx < 100; ++uIdx) { ++pabWriteBuffer[uIdx]; } /* exchange the buffer and retrieve a new write buffer */ rX_MemExchangeBuffer(hTrpIn, &pabWriteBuffer); /* get the current read buffer */ rX_MemGetExchangedBuffer(hTrpOut, &pabReadBuffer); WriteOutData(pabReadBuffer, 100); } }



2.13.3 rX_MemExchangeGetCurrentBuffer() – Get the Current Write Buffer

rX_MemExchangeGetCurrentBuffer() retrieves the current write buffer for the writer at the beginning. Afterwards, the function rX_MemExchangeBuffer() provides continuously the next write buffer. Function Syntax in „C“-Convention RX_RESULT rX_MemExchangeGetCurrentBuffer( RX_HANDLE hTrp, UINT8** pabWriteBuffer); Function Arguments Argument

Description

hTrp Triple buffer handle pabWriteBuffer • Pointer to a variable to receive the write buffer pointer


Description

RX_OK (0x0000)

Function succeed.






Example Code

UINT8 g_aabBufferOut[3][100]; VOID WriteBufferTest(VOID* pvParam) { RX_HANDLE hTrpOut; /* data out */ RX_BUFFERPOOL_T tBufPoolOut; UINT8* pabWriteBuffer; tBufPoolOut.pabBufA = &g_aabBufferOut[0][0]; tBufPoolOut.pabBufB = &g_aabBufferOut[1][0]; tBufPoolOut.pabBufC = &g_aabBufferOut[2][0]; erXRes = rX_MemAllocateMemory(&hTrpOut, RX_TRIPLEBUFFER_SIZE); if(RX_OK != erXRes) { ... return; } /* Create the output triple buffer now */ erXRes = rX_MemCreateTripleBuffer(“OUTPUT_DATA”, hTrpOut, &tBufPool); if(RX_OK != erXRes) { ... return; } /* initialize the write buffer pointer */ erXRes = rX_MemExchangeGetCurrentBuffer(hTrpOut, &pabWriteBuffer); if(RX_OK != erXRes) { ... return erXRes; } /* increment data every 10 ticks */ for(;;) { UINT uIdx; rX_SysSleepTask(10); /* wait 10 ticks */ for(uIdx = 0; uIdx < 100; ++uIdx) { ++pabWriteBuffer[uIdx]; } /* exchange the buffer and retrieve a new write buffer */ rX_MemExchangeBuffer(hTrpOut, &pabWriteBuffer); } }



2.13.4 rX_MemExchangeBuffer() – Exchange the Write Buffer and Mark Triple Buffer as updated

rX_MemExchangeBuffer() exchanges the buffers and marks the triple buffer as updated. Ad-ditionally, it returns the next write buffer. Function Syntax in „C“-Convention RX_RESULT rX_MemExchangeBuffer( RX_HANDLE hTrp, UINT8** pabNextWriteBuffer); Function Arguments Argument

Description

hTrp Triple buffer handle pabNextWriteBuffer • Next write buffer to be updated


Description

RX_OK (0x0000)

Function succeed.






Example Code

UINT8 g_aabBufferOut[3][100]; VOID FillBufferTest(VOID* pvParam) { RX_HANDLE hTrpOut; /* data out */ RX_BUFFERPOOL_T tBufPoolOut; UINT8* pabWriteBuffer; tBufPoolOut.pabBufA = &g_aabBufferOut[0][0]; tBufPoolOut.pabBufB = &g_aabBufferOut[1][0]; tBufPoolOut.pabBufC = &g_aabBufferOut[2][0]; erXRes = rX_MemAllocateMemory(&hTrpOut, RX_TRIPLEBUFFER_SIZE); if(RX_OK != erXRes) { ... return; } /* Create the output triple buffer now */ erXRes = rX_MemCreateTripleBuffer(“OUTPUT_DATA”, hTrpOut, &tBufPool); if(RX_OK != erXRes) { ... return; } /* initialize the write buffer pointer */ erXRes = rX_MemExchangeGetCurrentBuffer(hTrpOut, &pabWriteBuffer); if(RX_OK != erXRes) { ... return erXRes; } /* increment data every 10 ticks */ for(;;) { rX_SysSleepTask(10); /* wait 10 ticks */ for(uIdx = 0; uIdx < 100; ++uIdx) { ++pabWriteBuffer[uIdx]; } /* exchange the buffer and retrieve a new write buffer */ rX_MemExchangeBuffer(hTrpOut, &pabWriteBuffer); } }



2.13.5 rX_MemGetExchangedBuffer() – Gets the Current Read Buffer

rX_MemGetExchangedBuffer() retrieves the current read buffer to be read. Function Syntax in „C“-Convention RX_RESULT rX_MemGetExchangedBuffer( RX_HANDLE hMtx, UINT8** pabReadBuffer) Function Arguments Argument

Description

hTrp Triple buffer handle pabReadBuffer • Pointer to variable to store current read buffer pointer


Description

RX_OK (0x0000)

Function succeed.






Example Code

UINT8 g_aabBufferIn[3][100]; VOID ReadBufferTest(VOID* pvParam) { RX_HANDLE hTrpIn; /* Triple buffer handle: data in */ RX_BUFFERPOOL_T tBufPoolIn; UINT8* pabReadBuffer; tBufPoolIn.pabBufA = &g_aabBufferIn[0][0]; tBufPoolIn.pabBufB = &g_aabBufferIn[1][0]; tBufPoolIn.pabBufC = &g_aabBufferIn[2][0]; erXRes = rX_MemAllocateMemory(&hTrpIn, RX_TRIPLEBUFFER_SIZE); if(RX_OK != erXRes) { ... return; } /* Create the input triple buffer now */ erXRes = rX_MemCreateTripleBuffer(“INPUT_DATA”, hTrpIn, &tBufPool); if(RX_OK != erXRes) { ... return; } /* read data every 10 ticks */ for(;;) { rX_SysSleepTask(10); /* wait 10 ticks */ /* get the current read buffer */ rX_MemGetExchangedBuffer(hTrpIn, &pabReadBuffer); WriteDataOut(pabReadBuffer, 100); } }



2.13.6 rX_MemGetExchangedBufferWait() – Wait for an Update and retrieve the Current Buffer

rX_MemGetExchangedBuffer() retrieves the current read buffer to be read. If no update has been provided by the writer, it will wait for a specified timeout for a new up-date to the buffer. Function Syntax in „C“-Convention RX_RESULT rX_MemGetExchangedBufferWait(RX_HANDLE hMtx, UINT8** pabReadBuffer, UINT uTimeout ) Function Arguments Argument

Description

hTrp Triple buffer handle

uTimOpt • not implemented • set always to RX_INFINITE


Description

RX_OK (0x0000)

The mutex has been successfully locked.

RX_TIMEOUT (0x0001)

Timeout elapsed before any update has been made.



RX_MEM_DELETED (0x010D)

While waiting for an update, the triple buffer has been deleted.




Example Code

UINT8 g_aabBufferIn[3][100]; VOID ReadBufferTest(VOID* pvParam) { RX_HANDLE hTrpIn; /* Triple buffer handle: data in */ RX_BUFFERPOOL_T tBufPoolIn; UINT8* pabReadBuffer; tBufPoolIn.pabBufA = &g_aabBufferIn[0][0]; tBufPoolIn.pabBufB = &g_aabBufferIn[1][0]; tBufPoolIn.pabBufC = &g_aabBufferIn[2][0]; erXRes = rX_MemAllocateMemory(&hTrpIn, RX_TRIPLEBUFFER_SIZE); if(RX_OK != erXRes) { ... return; } /* Create the input triple buffer now */ erXRes = rX_MemCreateTripleBuffer(“INPUT_DATA”, hTrpIn, &tBufPool); if(RX_OK != erXRes) { ... return; } /* read data every 10 ticks */ for(;;) { /* get the current read buffer */ erXRes = rX_MemGetExchangedBufferWait(hTrpIn, &pabReadBuffer, 10); /* write data to the outputs */ WriteDataOut(pabReadBuffer, 100); } }



2.13.7 rX_MemEnableTripleBufferCallback() – Sets an Update Callback on a Triple Buffer

rX_MemEnableTripleBufferCallback() sets an update callback to be called whenever the tri-ple buffer will be updated. Function Syntax in „C“-Convention RX_RESULT rX_MtxEnableTripleBufferCallback(RX_HANDLE hTrp, TRIPLEBUFFER_CALLBACK pfnCbk, VOID* pvParam) Function Arguments Argument

Description

hTrp Triple buffer handle pfnCbk • Callback to be called on every update pvParam • User data pointer for callback


Description

RX_OK (0x0000)

Function succeed.






Example Code

VOID TripleBufferCallback(RX_HANDLE hTrp, VOID* pvParam) { /* Callback reached */ ... } RX_RESULT TripleBufferCallbackInit(RX_HANDLE hTrp, VOID* pvParam) { RX_RESULT erXRes; erXRes = rX_MemEnableTripleBufferCallback( hTrp, TripleBufferCallback, pvParam); ... return erXRes; }



2.13.8 rX_MemDisableTripleBufferCallback() – Clears the Update Callback on a Triple Buffer

rX_MemDisableTripleBufferCallback() clears the Update Callback. Function Syntax in „C“-Convention RX_RESULT rX_MemDisableTripleBufferCallback(RX_HANDLE hTrp) Function Arguments Argument

Description

hTrp Triple buffer handle Function Return Values Return Value

Description

RX_OK (0x0000)

Function succeed.






Example Code

RX_HANDLE hTrp; /* Mutex Handle */ … /* Clear the triple buffer callback */ erXRes = rX_MemDisableTripleBufferCallback(hTrp); if( erXRes == RX_OK ) { /* success */ … } else { /* we could not clear the triple buffer callback, something must be wrong * we abort our processing with an error */ … }



2.13.9 rX_MemDeleteTripleBuffer() – Deletes a Triple Buffer This function deletes a triple buffer. It is the task’s responsibility to manage the memory area associated with the triple buffer after the deletion. Function Syntax in „C“-Convention RX_RESULT rX_MemDeleteTripleBuffer( RX_HANDLE hTrp ) Function Arguments Argument

Description

hTrp Triple buffer handle Function Return Values Return Value

Description

RX_OK (0x0000)

The triple buffer has been successfully deleted






Example Code

RX_HANDLE hTrp; /* Triple buffer handle */ … void stop(void) { /* Delete the mutex */ erXRes = rX_MemDeleteTripleBuffer(hTrp); if( erXRes == RX_OK ) { /* success, the triple buffer is removed */ … } else { /* error, the triple buffer was not deletable */ … } }



2.14 Fault Services – Header-File AP_Flt.h Providing Fault Services <#include “AP_Flt.h”>

2.14.1 rX_FltLoggFault() – Records a Task event This function records a task event in a trace buffer. The recorded information can be later read and displayed by external diagnostic software. The internal buffer concept is a ring buffer, but does not overwrite old trace entries if the buffer is full. If the diagnostic software does not keep up with the incoming buffer information, new trace entries will be lost. The trace buffer size can be configured within the Config.c File. The parameters within the Config.c file are explained in the Manual “Configuration through Config.c”. Function Syntax in „C“-Convention void rX_FltLoggFault( UINT uFltCod, UINT uPrm, RX_FAULT_SEVERITY eFltSvty, STRING* pszSrcFil, UINT uSrcLin ) Function Arguments Argument

Description

uFltCod Task specific fault code to be logged.

uPrm Extra parameter for general use. Not pre-defined and task specific. value is related to the fault code.

eFltSvty

This value specifies the severity level of the fault or error condition. The following values are possible

• RX_FAULT_INFO • RX_FAULT_WARNING • RX_FAULT_SEVERE • RX_FAULT_FATAL • RX_FAULT_RETENTIVE • RX_FAULT_LOSSY

pszSrcFil Pointer to the source code name of that file that has called the func-tion. Use the compiler specific Marco __FILE__ to get the current file name.

uSrcLin Source code line reflecting the line where the function has been called. Use the compiler specific Marco __LINE__ to get the current line number.




Description

None None Allowed to be called by Initialization, Task, ISR and Application Timer Pre-emption possible No. Example Code

... if(erXRes != RX_OK) { /* Return Error, log this error condition */ rX_FltLoggFault(ERROR_RETURN, RX_FAULT_WARNING, LEVEL3, __FILE__, __LINE__); }

else

{

...

}



2.14.2 rX_FltFatalError() – Reports a Heavy Runtime Error rX_FltFatalError() has to be used to report errors that deny any further operation of the whole system as such. The possible error values that can be reported are defined in the enumeration field RX_FATAL in the AP_Flt.h header file beginning with the RX_FAT_BASE definition. Function Syntax in „C“-Convention void rX_FltFatalError(RX_FATAL eErr) Function Arguments Argument

Description

eErr Fatal error code Function Return Values Return Value

Description

None None Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible Yes



2.15 Verbose Output Services – Header-File AP_Vbs.h Providing Verbose Services <#include “AP_Vbs.h”>

2.15.1 rX_VbsPrintf() – Prints a formatted string to debug port This function writes a printf formatted string to a serial debug port (UART). The following format specifiers are supported: %s – The argument is a pointer to a STRING array. %d – The argument is of the type INT32. %x,X – The argument of the type UINT32 is converted into an unsigned hexadecimal number. Function Syntax in „C“-Convention void rX_VbsPrintf(const CHAR* pchFmt,...) Function Arguments Argument

Description

pchFmt Printf-style format string . . . Arguments specified in the format string




Description


... /* Print the timer value */ rX_VbsPrintf("Time: %d\n\r", ulTimer); /* Print the producer string */ rX_VbsPrintf("Producer: %s\n\r", pszIdn); /* Print the pointer in segment and offset string */ rX_VbsPrintf("Pointer: %x:%x\n\r", (UINT32) FP_SEG(ptFoo),

(UINT32) FP_OFF(ptFoo)); ...

rcX - Kernel API Function Reference Contact • 196


3 Contact Headquarter Germany Hilscher Gesellschaft für Systemautomation mbH Rheinstrasse 15 65795 Hattersheim Phone: +49 (0) 6190 9907-0 Fax: +49 (0) 6190 9907-50 E-Mail: [email protected] netX Support Phone: +49 (0) 6190 9907-97 E-Mail: [email protected] Subsidiaries China Hilscher Ges.f.Systemaut. mbH Shanghai Representative Office 200010 Shanghai Phone: +86 (0) 21-6355-5161 E-Mail: [email protected] Support Phone: +86 (0) 21-6355-5161 E-Mail: [email protected] France Hilscher France S.a.r.l. 69500 Bron Phone: +33 (0) 4 72 37 98 40 E-Mail: [email protected] Support Phone: +33 (0) 4 72 37 98 40 E-Mail: [email protected] Italy Hilscher Italia srl 20090 Vimodrone (MI) Phone: +39 02 25007068 E-Mail: [email protected] Support Phone: +39 / 02 25007068 E-Mail: [email protected]

Japan Hilscher Japan KK Tokyo, 160-0022 Phone: +81 (0) 3-5362-0521 E-Mail: [email protected] Support Phone: +81 (0) 3-5362-0521 E-Mail: [email protected] Switzerland Hilscher Swiss GmbH 4500 Solothurn Phone: +41 (0) 32 623 6633 E-Mail: [email protected] Support Phone: +49 (0) 6190 9907-99 E-Mail: [email protected] USA Hilscher North America, Inc. Lisle, IL 60532 Phone: +1 630-505-5301 E-Mail: [email protected] Support Phone: +1 630-505-5301 E-Mail: [email protected]

mailto:[email protected]














Date post:	19-Jul-2020
Category:	Documents
Upload:	others
View:	9 times
Download:	0 times

Realtime Communication System for netX Kernel API Function...

Documents