Operating System Manual. Realtime Communication System for netx. Kernel API Function Reference.

Transcription

1 Operating System Manual Realtime Communication System for netx Kernel API Function Reference Language: English

2 rcx - Kernel API Function Reference 2 Copyright Information Copyright 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, mechanical, photocopying, recording, or otherwise, without the prior written consent of the Author. The Author makes no warranty of any kind with regard to this material, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. The Author assumes also no responsibility for any errors that may appear in this document. And finally the Author makes no commitment to update or to keep current the information contained in this document.

3 rcx - Kernel API Function Reference 3 Revision History Revisioter Date Chap- Notes 11/01/ Initial Release 1 11/22/ Changed Prototype of rx_mtxcreatemutex() New function rx_diagetinformationfield(), rx_mbxgettaskmailbox() 2 03/01/ New function rx_sysspinlock(), rx_sysspinunlock(), rx_quegetqueueload() rx_memallocatenamedmemory() Function Prototype of rx_syscreatetask() corrected 3 01/18/2005 New function rx_sysenterkernel() 4 23/01/2008 Updated for rcx version V2.x

4 rcx - Kernel API Function Reference 4 Table Of Contents 1 INTRODUCTION About this Technical Overview Hard Real-Time Architecture Preemptive Kernel Dynamic Objects Rich API Functions Tool Support Tasks Static Task Dynamic Task Task Enter-Function and Task-Initialization Task Leave-Function Task State Interrupt Service Routines (ISR) Drivers (DRV) Hardware Abstraction Layer (HAL) KERNEL API FUNCTIONS One Include-File to include all rcx specific Include-Files Header File rx_includes.h rcx common Data Types Definitions Header-File rx_types.h System Services Header-File AP_Sys.h rx_sysenterkernelext() Enters the RX-Kernel Module rx_sysgetsystemticks() Get the Current System-Timer Tick Value rx_syssetsystemticks() Set the System-Timer Tick Count Value rx_syslockirq() Disables all Hardware Interrupts rx_sysunlockirq() Allows Hardware Interrupts rx_sysgetsystemcycletime() Gets the Cycletime of the System timer rx_syscreatehooksystemstatus() Install a System Status Changes Callback rx_sysspinlock() Attempts to acquire a Shared Variable and to lock it rx_sysspinunlock() Releases a previously Locked Shared Variable rx_syslockscheduler() Supresses the Task Pre-emption rx_sysunlockscheduler() Enables Task Pre-emption Task Services Header-File AP_Task.h rx_syscreatetask() Creates a Dynamic Task at Runtime rx_sysidentifytask() Identify a Task by Name rx_syssettaskinitialized() Signal the End of the Current Task Initialization rx_sysdeletetask() Delete a Task rx_syssleeptask() Suspend the current Task for a specified Time rx_sysdelaytaskuntil() Delay a Task for a specified Time rx_syswakeuptask() Abort the Sleep State of a Task... 46

5 rcx - Kernel API Function Reference rx_sysblocktask() Stop the scheduling of the specified Task rx_sysresumetask() Resume a previously blocked Task rx_systerminatetask() Terminate a Task rx_syschangepriority() Change the Priority of a Task rx_sysgetowninstance() Get the Instance number of the calling Task Queue Services Header-File AP_Que.h rx_quecreatequeue() Create a Queue of dynamic Size and Elements rx_queidentifyqueue() Identify a Queue by Name rx_quewaitforpacket() Wait for a Queue-Packet to be received rx_quepeekpacket() Check for a Queue-Packet in a Queue rx_quesendpacket() Send a Packet to a Queue in FIFO principle rx_quesendprioritypacket() Send a Packet to a Queue in LIFO principle rx_quedeletequeue() Delete a Queue rx_queflushqueue() Delete all Packets in a Queue rx_quegetqueueload() Return the current Fill Level of a Queue Event Services Header-File AP_Eve.h rx_evecreateeventgroup() Create an Eventgroup for 32 possible Events rx_eveidentifyeventgroup() Identify an Eventgroup by Name rx_evesetupeventgroup() Set the Eventgroup Parameters rx_evewaitforeventgroup() Wait on Eventgroup Events rx_evechangeeventgroup() Change Events in an Eventgroup rx_evedeleteeventgroup() Delete an Eventgroup Signal Services Header-File AP_Sig.h rx_sigcreatesignal() Create a Signal rx_sigidentifysignal() Identify a Signal by Name rx_sigwaitforsignal() Wait for a Signal rx_sigsetsignal() Set a Signal rx_sigresetsignal() Reset a Signal rx_sigdeletesignal() Delete a Signal Mutex Services Header-File AP_Mtx.h rx_mtxcreatemutex() Create a Mutex rx_mtxidentifymutex() Identify a Mutex by Name rx_mtxlockmutex() Lock a Mutex rx_mtxunlockmutex() Unlock a Mutex rx_mtxdeletemutex() Delete a Mutex Semaphore Services Header-File AP_Sem.h rx_semcreatesemaphore() Create a Semaphore rx_semidentifysemaphore() Identify a Semaphore by Name rx_semwaitforsemaphore() Wait to get a Semaphore rx_semgetsemaphore() Try to get a Semaphore rx_semputsemaphore() Return a retrieved Semaphore rx_semdeletesemaphore() Delete a Semaphore rx_semwaitforsemaphorecount() Wait for a Semaphore rx_semclearsemaphorecount() Clear the Semaphore Count Value Timer Services Header-File AP_Tim.h rx_timcreatetimer() Creates an Application specific Timer rx_timsettime() Sets the current time of a Timer rx_timsetreload() Sets the reload value of a Timer rx_timgettime() Gets the current timer value of a Timer rx_timresettimer() Reloads a Timer rx_timstoptimer() Stops a Timer rx_timhalttimer() Halts a Timer rx_timresumetimer() Resumes a halted Timer rx_timdeletetimer() Deletes a Timer rx_timcreatecycle() Activates a Timer for periodic Task Activation rx_timwaitforcycle() Wait for a cyclic Timer

6 rcx - Kernel API Function Reference Introduction rx_timresetcycle() Reset a cyclic Task Timer rx_timdeletecycle() Delete a cyclic Timer Diagnostic Services Header-File AP_Dia.h rx_diacreateinformationfield() Creates an Information structure rx_diagetinformationfield() Gets a Task s Information structure reference rx_diacreatehooktaskstatus() Installs a Callback function for Task Status changes rx_diasettaskstatus() Changes the Status Code of a Task rx_diagettaskstatus() Returns the Status Code of a Task Memory Services Header-File AP_Mem.h rx_memallocatememory() Requests a Memory Block from the Pool rx_memfreememory() Returns an allocated Memory Block to the Pool rx_memcreatesharedmemory() Creates one Memory to Share rx_memidentifysharedmemory() Identifies a Shared Memory by Name rx_memgetsharedmemoryinfo() Gets the Shared Memory Parameters rx_memlocksharedmemory() Locks Shared Memory against Concurrent Accesses rx_memunlocksharedmemory() Releases the lock to a Shared Memory Triple Buffer Services Header-File AP_Mem.h rx_memcreatetriplebuffer() Creates a Triple Buffer for Exchanging Data rx_memidentifytriplebuffer() Identifies a Triple Buffer by Name rx_memexchangegetcurrentbuffer() Get the Current Write Buffer rx_memexchangebuffer() Exchange the Write Buffer and Mark Triple Buffer as updated rx_memgetexchangedbuffer() Gets the Current Read Buffer rx_memgetexchangedbufferwait() Wait for an Update and retrieve the Current Buffer rx_memenabletriplebuffercallback() Sets an Update Callback on a Triple Buffer rx_memdisabletriplebuffercallback() Clears the Update Callback on a Triple Buffer rx_memdeletetriplebuffer() Deletes a Triple Buffer Fault Services Header-File AP_Flt.h rx_fltloggfault() Records a Task event rx_fltfatalerror() Reports a Heavy Runtime Error Verbose Output Services Header-File AP_Vbs.h rx_vbsprintf() Prints a formatted string to debug port CONTACT...196

7 rcx - Kernel API Function Reference Introduction 7 1 Introduction 1.1 About this Technical This guide is intended for software developers programming embedded Real-Time applications under the realtime communication-system for netx, short rcx. You should be familiar with standard Real-Time operating system functions and the C programming language. In the subsequent chapters, this manual describes the application interface (API) functions that can be used to write own application tasks.

8 rcx - Kernel API Function Reference Introduction Overview

9 rcx - Kernel API Function Reference Introduction 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 optimized 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 objects: 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 making your debugging job easier. Internal task states as well as states of the different kind of objects can be monitored.

10 rcx - Kernel API Function Reference Introduction Tasks Static Task Static Tasks are created by the kernel at system start-up. They are configured inside a configuration 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 parameters defines if a task is put into READY or SUSPENDED state after its creation. The parameters 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 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 resources 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 order 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, independent of whether the task has a higher priority or not 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 deleted ( 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. Furthermore 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_barcreat box() 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 according to its priority.

11 rcx - Kernel API Function Reference Introduction 11 Setting the leave-function pointer to NULL disables the leave function 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

12 rcx - Kernel API Function Reference Introduction 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 Ready (executable) The Ready state signals a task is ready to run. This means if no other task, with a higher priority 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 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 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 Dormant (terminated) This state indicates that the task has been terminated.

13 rcx - Kernel API Function Reference Introduction 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 program 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 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 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 registers and variables of the hardware directly. Because of the different interfaces of the Peripherals 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.

14 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 prototype of the service. Prototypes can be found in the corresponding application header file using 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 variables or Hardware Registers directly. This would cause protection faults if Memory Management 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 preempted 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.

15 rcx - Kernel API Function Reference Kernel API Functions 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 Data Types Notes Examples PREFIX Definitions c INT8 (signed 8 bit signed byte INT8 cmysigned8; // signed char char) sz CHAR (char) Array of 8 bit CHAR szmystring[ ]; // ASCII-String signed byte f BOOLEAN 8Bit,16bit,32bit unsigned BOOLEAN fmyflag; // TRUE/FALSE integer processor dependant b UINT8 (unsigned char) 8 bit unsigned byte UINT8 bmyunsigned8; // unsigned char s INT16 (short) 16 bit signed integer INT16 smysigned16; // short us UINT16 (unsigned short) 16 bit unsigned integer UINT16 usmyunsigned16; // unsigned short l INT32 (long) 32 bit signed long INT32 lmysigned32; // long ul UINT32 (unsigned long) 32 unsigned long UINT32 ulmyunsigned32; // unsigned long i INT (integer) 8 bit, 16bit, 32bit signed integer processor dependant INT imysigned; // signed integer u UINT(unsigned integer) 8 bit, 16bit, 32bit unsigned integer processor dependant UINT umysigned; // unsigned integer h RX_HANDLE Handle to Object RX_HANDLE hmyhandle; // Handle (handle) fn Function void fnmyfunction; // function p Pointer to any Data Type pv Pointer to a VOID Data Type a Array of any Data type e ENUM Declaration of a variable of type Structure ENUM pmypointer; // Pointer pvmyvoidpointer // Pointer to void UINT8 abmyunsigned8array; // Array of bytes RX_TASK_PRIORITY ethrhld // Structure variable of type ENUM

16 rcx - Kernel API Function Reference Kernel API Functions System Services Header-File AP_Sys.h Providing System Services <#include AP_Sys.h > 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 described 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 ptkernelparam Pointer to a Kernel Configuration Data Structure. This structure is described in detail in the rcx Configuration Manual. Function Return Values Return Value none RX_FATAL Without having detected a fatal error this function will never return. 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

17 rcx - Kernel API Function Reference Kernel API Functions 17 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) */ 0x ; 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);

18 rcx - Kernel API Function Reference Kernel API Functions 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 None None Function Return Values Return Value 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)

19 rcx - Kernel API Function Reference Kernel API Functions 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 ulticks New value for the system timer tick count. Function Return Values Return Value 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 */

20 rcx - Kernel API Function Reference Kernel API Functions rx_syslockirq() Disables all Hardware Interrupts rx_syslockirq() locks all hardware interrupts within the CPU globally. This condition will remain 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 None None Function Return Values Return Value 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();

21 rcx - Kernel API Function Reference Kernel API Functions 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 None None Function Return Values Return Value 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 of execution*/ rx_syslockirq(); /* Re-enable all interrupts again */ rx_sysunlockirq();

22 rcx - Kernel API Function Reference Kernel API Functions 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 * / rx_sysgetsystemcycletime() Function Syntax in C -Convention UINT rx_sysgetsystemcycletime( void ) Function Arguments Argument None None Function Return Values Return Value usystimprd Current system period time in microseconds Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No.

23 rcx - Kernel API Function Reference Kernel API Functions 23 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();

24 rcx - Kernel API Function Reference Kernel API Functions 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 hhok fnntfy pvinp Pointer to the memory location the task had created a memory resource for previously. Pointer to the function that shall be called in the case of a system status 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. Callback specific data pointer that is provided as second parameter to the specified callback function. Function Return Values Return Value RX_OK (0x0000) Hook successfully installed.

25 rcx - Kernel API Function Reference Kernel API Functions 25 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 function */ /* 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);

26 rcx - Kernel API Function Reference Kernel API Functions 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 puispinlock Pointer to the lock variable Function Return Values Return Value None None Allowed to be called by Tasks only. Pre-emption possible Yes.

27 rcx - Kernel API Function Reference Kernel API Functions 27 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);

28 rcx - Kernel API Function Reference Kernel API Functions 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 puispinlock Pointer to the lock variable Function Return Values Return Value None None Allowed to be called by Tasks only. Pre-emption possible Yes.

29 rcx - Kernel API Function Reference Kernel API Functions 29 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);

30 rcx - Kernel API Function Reference Kernel API Functions 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 preemptable. 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 None None Function Return Values Return Value None None Allowed to be called by Tasks Pre-emption possible No

31 rcx - Kernel API Function Reference Kernel API Functions 31 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();

32 rcx - Kernel API Function Reference Kernel API Functions 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 None None Function Return Values Return Value 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();

33 rcx - Kernel API Function Reference Kernel API Functions Task Services Header-File AP_Task.h Providing Task Services <#include AP_Task.h > 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 psztsknam fntsk pvinpt pvstck ustcksiz usrtmod ethrhld eprio Task name Pointer to a NUL terminated string of a length of 16 bytes, including the terminating 0 character. Function pointer to the task entry function. Pointer to input data passed to the task entry function. Pointer to the stack region of the task. It will always point to the beginning (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. 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 element is 4 bytes. This value defines the start mode of the task. A value of RX_TASK_AUTO_START lets the task start automatically and be scheduled according to its priority A value RX_TASK_AUTO_STOP prevents the task from starting automatically. Only a call to rx_sysresumetask( ) during runtime will start the task. not implemented Initial task priority The value ranges from TSK_PRIO_1 to TSK_PRIO_55. TSK_PRIO_1 represents the highest priority.

34 rcx - Kernel API Function Reference Kernel API Functions 34 Task token etok uinst fntsklve Unique task Identification. The token ranges from TSK_TOK_1 to TSK_TOK_55. The token value has to be unique for every task. Task instance This value is necessary, if a task is created multiple times. The instance value should start with the value 0 and must be incremented for each instance. 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 resources. A value of NULL defines no leave function. Function Return Values Return Value RX_OK (0x0000) RX_KNL_PRIORITY_EXIST (0x0003) RX_KNL_PRIORITY_INVALID (0x0004) RX_KNL_TOKEN_INVALID (0x000A) RX_KNL_TOKEN_DOUBLE (0x000B) Function successful. The specified priority is already in use by another task. Specified priority out of range and not in its limits. Specified token out of range and not in its limits. Specified token is already in use by another task. Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible Yes

35 rcx - Kernel API Function Reference Kernel API Functions 35 Example Code UINT16 aussndtskstck[sndtsk_stk_size]; UINT32 ulinput = 0x ; /* 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 */

36 rcx - Kernel API Function Reference Kernel API Functions 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 psztsknam uinst phtsk petok peprio Pointer to a task name as NUL- terminated string. A NULL pointer identifies the calling task. Instance of the task to be identified Pointer to destination for the task handle Pointer to the destination variable for the task s token. If this pointer is NULL, the token ID value is not returned. Pointer to the destination variable for the task s priority. If this pointer is NULL, the priority value is not returned. Function Return Values Return Value RX_OK (0x0000) RX_KNL_TASK_UNKNOWN (0x0006) Function successful. The task does not exist. Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible No

37 rcx - Kernel API Function Reference Kernel API Functions 37 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 */

38 rcx - Kernel API Function Reference Kernel API Functions 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 suspended 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 pvinpt If a leave function is configured, this pointer will be passed as parameter to it when the task is about to become deleted Function Return Values Return Value None None Allowed to be called by Tasks Pre-emption possible Yes.

39 rcx - Kernel API Function Reference Kernel API Functions 39 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_mbxcreat box("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);...

40 rcx - Kernel API Function Reference Kernel API Functions 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 htsk utcks Handle of the task Number of system ticks the task deletion is delayed. If the value is configured to 0, the task is deleted immediately without any delay. Function Return Values Return Value RX_OK (0x0000) RX_KNL_TASK_UNKNOWN (0x0006) RX_KNL_TASK_DOWN (0x000C) Task has been requested to be deleted and its leave Function has been called. Task does not exist in scheduler s task list. Specified task is already shutting down.

41 rcx - Kernel API Function Reference Kernel API Functions 41 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 */

42 rcx - Kernel API Function Reference Kernel API Functions rx_syssleeptask() Suspend the current Task for a specified 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 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. Function Return Values Return Value Current number of remaining ticks UINT ulfttim Typically, this value is 0, but if the task has been reactivated by the rx_syswakeuptask() function the value returns the remaining ticks. Allowed to be called by Tasks Pre-emption possible Yes

43 rcx - Kernel API Function Reference Kernel API Functions 43 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() */

44 rcx - Kernel API Function Reference Kernel API Functions 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 usysticks Absolute tick count until which the task will be suspended Function Return Values Return Value 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.

45 rcx - Kernel API Function Reference Kernel API Functions 45 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();

46 rcx - Kernel API Function Reference Kernel API Functions 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 htsk Handle of the task to wake up Function Return Values Return Value RX_OK (0x0000) RX_KNL_TASK_UNKNOWN (0x0006) RX_KNL_TASK_BLOCKED (0x0009) The specified task has been re-entered into Ready" state. Task does not exist in scheduler task list. Specified task is currently suspended. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible Yes.

47 rcx - Kernel API Function Reference Kernel API Functions 47 Example Code RX_HANDLE htsk1; /* Wakes up a task with the handle htsk1 */ erxres = rx_syswakeuptask(htsk1); if( erxres == RX_OK ) /* success*/ else /* failed */

48 rcx - Kernel API Function Reference Kernel API Functions 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 Waiting" 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 htsk Handle of the task to be suspended Function Return Values Return Value RX_OK (0x0000) RX_KNL_TASK_UNKNOWN (0x0006) Function successful. Task does not exist in the scheduler task list Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible Yes.

49 rcx - Kernel API Function Reference Kernel API Functions 49 Example Code RX_HANDLE htsk1; /* Blocks the Task with Handle htsk1 */ erxres = rx_sysblocktask(htsk1); if( erxres == RX_OK ) /* success*/ else /* failed */

50 rcx - Kernel API Function Reference Kernel API Functions rx_sysresumetask() Resume a previously blocked Task rx_sysresumetask() returns a task from Suspended" state to the Ready" state or Waiting" 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 htsk Handle of the task to be de-suspended Function Return Values Return Value RX_OK (0x0000) RX_KNL_TASK_UNKNOWN (0x0006) RX_KNL_TASK_NOT_BLOCKED (0x0007) The specified suspended task has been returned to Ready" state or Waiting" state. Task does not exist in the scheduler task list Task is not in Suspended" state. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible Yes.

51 rcx - Kernel API Function Reference Kernel API Functions 51 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 */

52 rcx - Kernel API Function Reference Kernel API Functions 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 defining the termination reason. Function Syntax in C -Convention void rx_systerminatetask( UINT ursncod ) Function Arguments Argument ursncod Termination reason code Function Return Values Return Value 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 */

53 rcx - Kernel API Function Reference Kernel API Functions 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 htsk enewprio Handle of the task The value of the new task priority. The value ranges from TSK_PRIO_1 to TSK_PRIO_55. Function Return Values Return Value RX_OK (0x0000) RX_KNL_PRIORITY_EXIST (0x0003) RX_KNL_PRIORITY_INVALID (0x0004) RX_KNL_TASK_UNKNOWN (0x0006) The task priority has been changed. The specified priority is already in use. The specified priority level is not a valid priority. Task does not exist in scheduler task list. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible Yes.

54 rcx - Kernel API Function Reference Kernel API Functions 54 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 */

55 rcx - Kernel API Function Reference Kernel API Functions 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 None None Function Return Values Return Value 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();

56 rcx - Kernel API Function Reference Kernel API Functions Queue Services Header-File AP_Que.h Providing Queue Services <#include AP_Que.h> 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 pszidn hque papvque udep Queue name Pointer to a 0 terminated string of a length of maximum 16 bytes including the NUL character (15+1) Pointer to a memory block with RX_QUEUE_SIZE bytes. Pointer to the start of the queue pointer list. Depth of the queue as number of pointer elements within the queue. Function Return Values Return Value RX_OK (0x0000) RX_KNL_DUPLICATE_NAME (0x001C) RX_KNL_NAME_TOO_LONG (0x001D) The queue has been created. A queue with the name and the current task instance number exists already. The specified Id string is longer than 16 bytes

57 rcx - Kernel API Function Reference Kernel API Functions 57 Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible Yes Example Code 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 */

58 rcx - Kernel API Function Reference Kernel API Functions 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 pszidn uinst phque Pointer to a queue name as NUL-terminated string Instance number of the queue Pointer to destination for the queue handle Function Return Values Return Value RX_OK (0x0000) RX_QUE_UNKNOWN (0x0906) Queue has been found. Queue is not listed in the queue list Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible Yes

59 rcx - Kernel API Function Reference Kernel API Functions 59 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 */

60 rcx - Kernel API Function Reference Kernel API Functions rx_quewaitforpacket() Wait for a Queue-Packet to be received 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 hque ppvpkt utimeout Queue handle Pointer to the variable to fill in the packet pointer if successful Timeout value in system timer ticks 0x xFFFFFFFE These values specify a tick count how many ticks to be waited if no packet has been received in time RX_INFINITE (0x ) rx_quewaitforpacket() will wait until a packet has been received RX_FINITE (0xFFFFFFFF) It tells rx_quewaitforpacket() just to check for a packet readily available to be received. Otherwise, it returns an error. Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) RX_QUE_DELETED (0x0903) RX_TIMEOUT (0x0001) RX_QUE_EMPTY (0x0308) A packet has been received. The handle is invalid. While waiting for a packet, the queue has been deleted. No packet available within the specified tick time. The queue is empty This result will be returned if utimopt = RX_FINITE

61 rcx - Kernel API Function Reference Kernel API Functions 61 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 */

62 rcx - Kernel API Function Reference Kernel API Functions 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 available, it will always return immediately. Function Syntax in C -Convention RX_RESULT rx_quepeekpacket( RX_HANDLE hque, void** ppvpkt ) Function Arguments Argument hque ppvpkt Queue handle Pointer to destination variable for the packet pointer Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) RX_QUE_EMPTY (0x0908) A packet has been retrieved. The handle is invalid. No packet currently available. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible Yes.

63 rcx - Kernel API Function Reference Kernel API Functions 63 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 */

64 rcx - Kernel API Function Reference Kernel API Functions 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 always return immediately. Function Syntax in C -Convention RX_RESULT rx_quesendpacket( RX_HANDLE hque, void* pvpkt, UINT utimeout ) Function Arguments Argument hque pvpkt Queue handle Pointer to the packet Timeout value in system timer ticks 0x xFFFFFFFE These values specify a tick count how many ticks to be waited if no packet could have been put into the queue yet utimeout RX_INFINITE (0x ) 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. Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) RX_QUE_DELETED (0x0903) RX_TIMEOUT (0x0001) RX_QUE_FULL (0x0907) The packet was successfully sent. The handle is invalid. While waiting for a successful sending, the queue has been deleted. Timeout occurred while waiting for successful sending Queue is full, the packet was not sent

65 rcx - Kernel API Function Reference Kernel API Functions 65 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 */

66 rcx - Kernel API Function Reference Kernel API Functions 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 always return immediately. Function Syntax in C -Convention RX_RESULT rx_quesendprioritypacket( RX_HANDLE hque, void* pvpkt, UINT utimopt ) Function Arguments Argument hque pvpkt Queue handle Pointer to the packet to be placed into the queue Timeout value in system timer ticks 0x xFFFFFFFE These values specify a tick count how many ticks to be waited if no packet could have been put into the queue yet utimopt RX_INFINITE (0x ) rx_quesendprioritypacket() will wait until the packet has been put into the queue RX_FINITE (0xFFFFFFFF) It tells rx_quesendprioritypacket() to try to put the packet into the queue. If it was not able to, it will return an error. Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) RX_QUE_DELETED (0x0903) RX_TIMEOUT (0x0001) RX_QUE_FULL (0x0907) The packet was successfully sent The handle is invalid. While waiting for a successful sending, the queue has been deleted. Timeout occurred Queue is full, the packet was not sent

67 rcx - Kernel API Function Reference Kernel API Functions 67 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 */

68 rcx - Kernel API Function Reference Kernel API Functions 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 hque Queue handle Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) The queue has been successfully removed. The handle is invalid. Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible Yes

69 rcx - Kernel API Function Reference Kernel API Functions 69 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 */

70 rcx - Kernel API Function Reference Kernel API Functions 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 hque Queue handle Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) Queue successfully flushed The handle is invalid. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible Yes

71 rcx - Kernel API Function Reference Kernel API Functions 71 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 */

72 rcx - Kernel API Function Reference Kernel API Functions 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 hque puld Queue handle Pointer where the current queue load value will be copied to Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) Queue fill level successfully returned The handle is invalid. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No

73 rcx - Kernel API Function Reference Kernel API Functions 73 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 */

74 rcx - Kernel API Function Reference Kernel API Functions Event Services Header-File AP_Eve.h Providing Event Services <#include AP_Eve.h> rx_evecreateeventgroup() Create an Eventgroup for 32 possible Events rx_evecreateeventgroup() creates a group of 32 possible events. Each event is represented 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 pszidn hevegrp Event group name Pointer to a NUL terminated ASCII string of 16 bytes, including the terminating NUL character. Pointer to a memory block with RX_EVENTGROUP_SIZE bytes. Function Return Values Return Value RX_OK (0x0000) RX_KNL_DUPLICATE_NAME (0x001C) RX_KNL_NAME_TOO_LONG (0x001D) 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.

75 rcx - Kernel API Function Reference Kernel API Functions 75 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, 0x , 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 & 0x ) /* Event 1 */ if(ulcureve & 0x ) /* Event 2 */ if(ulcureve & 0x ) /* Event 3 */ else /* error, waiting has failed */

76 rcx - Kernel API Function Reference Kernel API Functions 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 pszidn uinst phevegrp Pointer to a name as a NUL terminated ASCII string Instance number Pointer to store the Eventgroup handle Function Return Values Return Value RX_OK (0x0000) RX_EVEGRP_UNKNOWN (0x0707) Eventgroup found. Eventgroup is not known. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No.

77 rcx - Kernel API Function Reference Kernel API Functions 77 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 */

78 rcx - Kernel API Function Reference Kernel API Functions rx_evesetupeventgroup() Set the Eventgroup Parameters 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 hevegrp ulevemsk umode pulcureve Eventgroup handle 32 bit unsigned event mask value This mask specifies the events the task wants to wait for. 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. Pointer to store the actual pending event mask, returned by rx_evewaitforeventgroup().

79 rcx - Kernel API Function Reference Kernel API Functions 79 Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) RX_EVEGRP_MODE_INVALID (0x070A) Function successful Invalid handle value. 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, 0x , RX_EVEGRP_MODE_ALL, &ulcureve);...

80 rcx - Kernel API Function Reference Kernel API Functions 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 hevegrp Eventgroup handle Timeout value in system timer ticks 0x xFFFFFFFE Timeout to wait for an event to occure. utimeout RX_INFINITE (0x ) 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. Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) RX_EVEGRP_DELETED (0x0703) RX_EVEGRP_NOEVENT (0x0708) RX_TIMEOUT (0x0001) The requested event bits have occurred. Invalid handle. While a task was waiting, the defined Eventgroup has been deleted. No event. Wait time expired

81 rcx - Kernel API Function Reference Kernel API Functions 81 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 & 0x ) == 0x ) if((ulcurevents & 0x ) == 0x ) else /* error, waiting for the event group failed */

82 rcx - Kernel API Function Reference Kernel API Functions rx_evechangeeventgroup() Change Events in an Eventgroup This function can be used to manually change the state of event bits in the specified eventgroup. 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 hevegrp ulevemsk umode Eventgroup handle 32 bit unsigned event mask value This mask specifies the event bits to be changed. 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 RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) The pending events bit have been modified. The handle is invalid. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible Yes.

83 rcx - Kernel API Function Reference Kernel API Functions 83 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 */

84 rcx - Kernel API Function Reference Kernel API Functions 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 hevegrp Eventgroup handle Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) Function succeed successfully The handle is invalid. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible Yes.

85 rcx - Kernel API Function Reference Kernel API Functions 85 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 */

86 rcx - Kernel API Function Reference Kernel API Functions 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 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 pszidn pusignl fmanrst Signal name Pointer to a string NUL terminated string of a maximum of 16 bytes includeing the terminating NUL character Pointer to the destination variable where the signal handle will be copied to 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(). Function Return Values Return Value RX_OK (0x0000) RX_SIG_NAME (0x0C01) RX_SIG_OUTOF_EVENTS (0x0C03) A signal has been allocated. The specified ID string is longer than 16 bytes. No further signal could be allocated.

87 rcx - Kernel API Function Reference Kernel API Functions 87 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 */...

88 rcx - Kernel API Function Reference Kernel API Functions 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 pszidn pusignlldx Pointer to a signal name as 0 terminated string Pointer to destination variable for the signal handle Function Return Values Return Value RX_OK (0x0000) RX_SIG_EVENT_UNKNOWN (0x0C06) Signal has been identified. Signal is not known. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No.

89 rcx - Kernel API Function Reference Kernel API Functions 89 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 */

90 rcx - Kernel API Function Reference Kernel API Functions 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 usignlidx utimeout Signal handle Timeout value in system timer ticks 0x xFFFFFFFE These values specify a tick count how many ticks to be waited for the signal if it has not been set. RX_INFINITE (0x ) 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. Function Return Values Return Value RX_OK (0x0000) RX_SIG_TIMEOUT (0x0C04) RX_SIG_EVENT_INVALID (0x0C05) RX_SIG_MULTI_WAIT (0X0C07) RX_SIG_NOT_PRESENT (0x0C08) The signal has been set. The signal has not been set within the specified timeout. The signal handle is invalid. More than one task tries to wait for the specified signal. Signal is not pending.

91 rcx - Kernel API Function Reference Kernel API Functions 91 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 */

92 rcx - Kernel API Function Reference Kernel API Functions rx_sigsetsignal() Set a Signal rx_sigsetsignal() sets a signal. If no task is currently waiting, the signal counter is incremented by 1. Function Syntax in C -Convention RX_RESULT rx_sigsetsignal( UINT usignlidx ) Function Arguments Argument usignlidx Handle to the signal Function Return Values Return Value RX_OK (0x0000) RX_SIG_EVENT_INVALID (0x0C04) The specified signal has been set. The signal handle is invalid. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible Yes.

93 rcx - Kernel API Function Reference Kernel API Functions 93 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 */

94 rcx - Kernel API Function Reference Kernel API Functions 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 usignlidx Handle to the signal Function Return Values Return Value RX_OK (0x0000) RX_SIG_EVENT_INVALID (0x0C04) Function completed successfully. The signal handle is invalid. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No.

95 rcx - Kernel API Function Reference Kernel API Functions 95 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 */

96 rcx - Kernel API Function Reference Kernel API Functions rx_sigdeletesignal() Delete a Signal rx_sigdeletesignal() deletes a signal. Function Syntax in C -Convention RX_RESULT rx_sigresetsignal( UINT usignlidx ) Function Arguments Argument usignlidx Handle to the signal Function Return Values Return Value RX_OK (0x0000) RX_SIG_EVENT_INVALID (0x0C04) The specified signal has been deleted. The signal handle is invalid. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No.

97 rcx - Kernel API Function Reference Kernel API Functions 97 Example Code UINT usignl; /* index handle to signal */ /* Delete the signal now */ erxres = rx_sigdeletesignal(usignlidx);

98 rcx - Kernel API Function Reference Kernel API Functions 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 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 pszidn hmtx umaxprc Mutex name Pointer to a NUL terminated string of a maximum of 16 bytes, including the terminating NUL character Pointer to a memory block with RX_MUTEX_SIZE bytes. not implemented Function Return Values Return Value RX_OK (0x0000) RX_KNL_DUPLICATE_NAME (0x001C) RX_KNL_NAME_TOO_LONG (0x001D) Function successful. Object with same name already exists. Name too long. Allowed to be called by Initialization, Task and Application Timers.

99 rcx - Kernel API Function Reference Kernel API Functions 99 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 */

100 rcx - Kernel API Function Reference Kernel API Functions 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 pszidn uinst phmtx Mutex name Pointer to a NUL terminated string of a maximum of 16 bytes, including the terminating NUL character Instance number Pointer to variable where to copy the mutex handle to. Function Return Values Return Value RX_OK (0x0000) RX_MTX_UNKNOWN (0x0606) Function successful. Mutex is unknown. Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible Yes

101 rcx - Kernel API Function Reference Kernel API Functions 101 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 */

102 rcx - Kernel API Function Reference Kernel API Functions 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 hmtx utimeout Mutex handle not implemented set always to RX_INFINITE Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) RX_MTX_DELETED (0x0603) Function successful. The handle is invalid. While waiting to lock the mutex, the mutex has been deleted. Allowed to be called by Initialization, Tasks and Application Timers. Pre-emption possible Yes

103 rcx - Kernel API Function Reference Kernel API Functions 103 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 */

104 rcx - Kernel API Function Reference Kernel API Functions 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 hmtx Mutex handle Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) Function successful. The handle is invalid. Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible Yes

105 rcx - Kernel API Function Reference Kernel API Functions 105 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 */

106 rcx - Kernel API Function Reference Kernel API Functions rx_mtxdeletemutex() Delete a Mutex This function deletes a mutex. It is the task s responsibility to manage the memory area associated with the mutex after the deletion. Function Syntax in C -Convention RX_RESULT rx_mtxdeletemutex( RX_HANDLE hmtx ) Function Arguments Argument hmtx Mutex handle Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) Function successful. The handle is invalid. Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible Yes

107 rcx - Kernel API Function Reference Kernel API Functions 107 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 */

108 rcx - Kernel API Function Reference Kernel API Functions 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 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 pszidn hsem umaxprc Semaphore name Pointer to a NUL terminated name string of a maximum of 16 bytes, including the terminating 0 character Pointer to a memory block with RX_SEMAPHORE_SIZE bytes. Initial count value of the semaphore Function Return Values Return Value RX_OK (0x0000) RX_KNL_DUPLICATE_NAME (0x001C) RX_KNL_NAME_TOO_LONG (0x001D) Function successful. Name already exists. Name too long. Allowed to be called by Initialization, Task and Application Timers.

109 rcx - Kernel API Function Reference Kernel API Functions 109 Pre-emption possible Yes Example Code 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)

110 rcx - Kernel API Function Reference Kernel API Functions 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 pszidn uinst phsem Pointer to a NUL terminated name string Instance number Pointer to variable to receive the semaphore handle in Function Return Values Return Value RX_OK (0x0000) RX_SEM_UNKNOWN (0x0506) Function successful. Semaphore is not known. Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible No.

111 rcx - Kernel API Function Reference Kernel API Functions 111 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 */

112 rcx - Kernel API Function Reference Kernel API Functions 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 another task has called rx_semputsemaphore(). Function Syntax in C -Convention RX_RESULT rx_semwaitforsemaphore( RX_HANDLE hsem, UINT utimeout ) Function Arguments Argument hsem Semaphore handle Timeout value in system timer ticks 0x xFFFFFFFE Time in tick count, the function will wait for the the semaphore. utimeout RX_INFINITE (0x ) rx_semwaitforsemaphore() will wait until the semaphore can be obtained. RX_FINITE (0xFFFFFFFF) Check if semaphore can be otained or not. If it was not possible to get it, an error is returned. Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) RX_SEM_DELETED (0x0503) RX_TIMEOUT (0x0001) RX_SEM_NOT_AVAILABLE (0x0507) Semaphore was successfully obtained (decremented) The handle is invalid. Semaphore is deleted while witing on it. The semaphore was not available within the specified tick time. Semaphore cannot be obtained.

113 rcx - Kernel API Function Reference Kernel API Functions 113 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 */

114 rcx - Kernel API Function Reference Kernel API Functions 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 hsem Semaphore handle Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) RX_SEM_NOT_AVAILABLE (0x0507) Semaphore successfully obtained (decremented). The handle is invalid. Semaphore cannot be obtained. Allowed to be called by Tasks Pre-emption possible Yes.

115 rcx - Kernel API Function Reference Kernel API Functions 115 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 */

116 rcx - Kernel API Function Reference Kernel API Functions 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 hsem Semaphore handle Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) RX_SEM_OVERFLOW (0x0507) Semaphore successfully released (incremented). The handle is invalid. Semaphore counter value overflow (0xFFFFFFFF) Allowed to be called by Initialization, Task, ISR and Application Timer Pre-emption possible Yes.

117 rcx - Kernel API Function Reference Kernel API Functions 117 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 */

118 rcx - Kernel API Function Reference Kernel API Functions 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 after the deletion. Function Syntax in C -Convention RX_RESULT rx_semdeletesemaphore( RX_HANDLE hsem ) Function Arguments Argument hsem Semaphore handle Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) Function successful. Object handle invalid. Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible Yes

119 rcx - Kernel API Function Reference Kernel API Functions 119 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 */

120 rcx - Kernel API Function Reference Kernel API Functions 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 hsem pucurcnt Semaphore handle. Pointer to destination variable where to copy the current number of counted events to. Timeout value in system timer ticks 0x xFFFFFFFE Time in tick counts to wait, if the semaphore value was 0. utimeout RX_INFINITE (0x ) rx_semwaitforsemaphorecount() will wait until the value of the semaphore is unequal 0. RX_FINITE (0xFFFFFFFF) Retrieve the current semaphore count and resets the counter to 0. If it was 0, it will return an error.

121 rcx - Kernel API Function Reference Kernel API Functions 121 Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) RX_SEM_DELETED (0x0503) RX_SEM_TIMEOUT (0x0505) RX_SEM_NO_COUNT (0x050B) Function successful. The handle is invalid. Semaphore object deleted, while waiting on it. Semaphore not been incremented during the given wait time. Semaphore was not incremented. Allowed to be called by Tasks If ultimopt = RX_FINITE then also ISR and Application Timers. Pre-emption possible Yes

122 rcx - Kernel API Function Reference Kernel API Functions 122 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 */

123 rcx - Kernel API Function Reference Kernel API Functions 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 hsem Semaphore handle Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) Function successful The handle is invalid. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No.

124 rcx - Kernel API Function Reference Kernel API Functions 124 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 */

125 rcx - Kernel API Function Reference Kernel API Functions 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 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 htim fnexp pvinpt Pointer to a memory block with RX_TIMER_SIZE bytes. Pointer to the call-back function being called when the timer expires. User data pointer for the call-back function This value defines the behaviour of the timer at expiration. Following values are possible: etimfnc utimtckrld RX_TIM_AUTO_STOP The timer stops automatically after its expiration, but is not deleted. 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. Reload value in system timer ticks (only used if RX_TIM_AUTO_RELOAD is set) The value range is 0x to 0xFFFFFFFF.

126 rcx - Kernel API Function Reference Kernel API Functions 126 usrttckdly Initial timer start value in system timer ticks The value range is 0x to 0xFFFFFFFF. If a value of zero is specified, the timer is created in stop mode. Function Return Values Return Value RX_OK (0x0000) Function successful. Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible Yes Example Code 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);

127 rcx - Kernel API Function Reference Kernel API Functions 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 htim unewval Timer handle Value the timer should be set to in system timer ticks. he value range is 0x to 0xFFFFFFFF. If the value specified is 0, the timer will be stopped. Function Return Values Return Value RX_OK (0x0000) RX_TIM_INVALID (0x0201) Function successful. The handle is invalid. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No.

128 rcx - Kernel API Function Reference Kernel API Functions 128 Example Code RX_HANDLE hmytimer; /* timer handle */ void restart(void) erxres = rx_timsettime(hmytimer, 500); /* Set the timer to 500 ticks */

129 rcx - Kernel API Function Reference Kernel API Functions 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 htim unewrld Timer handle New value the timer reload value in ticks. The value range is 0x to 0xFFFFFFFF. If the value is specified to 0, the timer is stopped on the next reload. Function Return Values Return Value RX_OK (0x0000) RX_TIM_INVALID (0x0201) Function successful. The handle is invalid. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No.

130 rcx - Kernel API Function Reference Kernel API Functions 130 Example Code RX_HANDLE hmytimer; /* timer handle */ void NewAndReset(UINT utcks) erxres = rx_timsetreload(hmytimer, utcks); /* Set new reload value */

131 rcx - Kernel API Function Reference Kernel API Functions 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 htim pucurval Timer handle Pointer to UINT variable where to copy the tick value to Function Return Values Return Value RX_OK (0x0000) RX_TIM_INVALID (0x0201) Function successful. The handle is invalid. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No.

132 rcx - Kernel API Function Reference Kernel API Functions 132 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 */

133 rcx - Kernel API Function Reference Kernel API Functions 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 htim Timer Handle Function Return Values Return Value RX_OK (0x0000) RX_TIM_INVALID (0x0201) Function successful. The handle is invalid. 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 */

134 rcx - Kernel API Function Reference Kernel API Functions 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 htim Timer handle Function Return Values Return Value RX_OK (0x0000) RX_TIM_INVALID (0x0201) Function successful. The handle is invalid. 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 */

135 rcx - Kernel API Function Reference Kernel API Functions 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 htim Timer handle Function Return Values Return Value RX_OK (0x0000) RX_TIM_INVALID (0x0201) Function successful. The handle is invalid. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No.

136 rcx - Kernel API Function Reference Kernel API Functions 136 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 */

137 rcx - Kernel API Function Reference Kernel API Functions 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 htim Timer handle Function Return Values Return Value RX_OK (0x0000) RX_TIM_INVALID (0x0201) RX_TIM_NOT_HALTED (0x0206) Function successful. The handle is invalid. The specified timer has not been resumed before. Allowed to be called by Initialization, Task, ISR and Application Timer Pre-emption possible No.

138 rcx - Kernel API Function Reference Kernel API Functions 138 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 */

139 rcx - Kernel API Function Reference Kernel API Functions 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 htim Timer handle Function Return Values Return Value RX_OK (0x0000) RX_TIM_INVALID (0x0201) Function successful. The handle is invalid. Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible Yes

140 rcx - Kernel API Function Reference Kernel API Functions 140 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 */

141 rcx - Kernel API Function Reference Kernel API Functions 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 pszidn hcyl utim Cyclic name Pointer to a string of a length of maximum 16 bytes 0 (15+1) terminated Pointer to a memory block with RX_CYCLIC_SIZE bytes Cyclic timer period in ticks The value range is 0x to 0xFFFFFFFF. Function Return Values Return Value RX_OK (0x0000) RX_TIM_ZERO (0x203) RX_TIM_CYCLE_INVALID (0x0208) Function successful. utim is 0. The handle is invalid. Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible No.

142 rcx - Kernel API Function Reference Kernel API Functions 142 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? */

143 rcx - Kernel API Function Reference Kernel API Functions 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 hcyl Cycle handle Function Return Values Return Value RX_OK (0x0000) RX_TIM_CYCLE_INVALID (0x0208) Function successful. The handle is invalid. Allowed to be called by Tasks Pre-emption possible Yes.

144 rcx - Kernel API Function Reference Kernel API Functions 144 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 */

145 rcx - Kernel API Function Reference Kernel API Functions rx_timresetcycle() Reset a cyclic Task Timer rx_timresetcycle() reloads the cyclic timer to the configured tick count value (the timer internal missed event counter is also cleared). Function Syntax in C -Convention RX_RESULT rx_timresetcycle( RX_HANDLE hcyl ) Function Arguments Argument hcyl Cycle handle Function Return Values Return Value RX_OK (0x0000) RX_TIM_CYCLE_INVALID (0x0208) Function successful. The handle is invalid. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No.

146 rcx - Kernel API Function Reference Kernel API Functions 146 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();

147 rcx - Kernel API Function Reference Kernel API Functions rx_timdeletecycle() Delete a cyclic Timer rx_timdeletecycle() deletes a cyclic timer. Tasks, waiting on the cyclic timer, will be activated 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 hcyl Cycle handle Function Return Values Return Value RX_OK (0x0000) RX_TIM_CYCLE_INVALID (0x0208) Function successful. The handle is invalid. Allowed to be called by Initialization, Task and Application Timer Pre-emption possible No.

148 rcx - Kernel API Function Reference Kernel API Functions 148 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);

149 rcx - Kernel API Function Reference Kernel API Functions Diagnostic Services Header-File AP_Dia.h Providing Diagnostic Services <#include AP_Dia.h > rx_diacreateinformationfield() Creates an Information structure rx_diacreateinformationfield() creates a structured information block which is used for additional 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 htsknfo ulen pvstr Pointer to a memory block with RX_INFORMATION_SIZE bytes Length of the information block Pointer to the information block Function Return Values Return Value RX_OK (0x0000) Information block has been created. Allowed to be called by Task Pre-emption possible No.

150 rcx - Kernel API Function Reference Kernel API Functions 150 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++;...

151 rcx - Kernel API Function Reference Kernel API Functions 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 htsk unfonum ptnfo Handle of the task The index of the diagnostic information block in the task Pointer to a structure RX_INFORMATION_ENTRY_T where the function will copy the length of the field and its location pointer to Function Return Values Return Value RX_OK (0x0000) RX_DIA_INFO_INVALID (0x1001) The specified information block has been found. The specified diagnostic information block number is invalid. Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible No.

152 rcx - Kernel API Function Reference Kernel API Functions 152 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 */

153 rcx - Kernel API Function Reference Kernel API Functions rx_diacreatehooktaskstatus() Installs a Callback function 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 hhok fnntfy pvinp Pointer to a memory block with RX_HOOK_SIZE bytes. Pointer to call-back function Its parameters are: Pointer to the task status block of rcx. A void pointer with user data User data pointer Function Return Values Return Value RX_OK (0x0000) Hook successfully installed. Allowed to be called by Task Pre-emption possible No.

154 rcx - Kernel API Function Reference Kernel API Functions 154 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);

155 rcx - Kernel API Function Reference Kernel API Functions 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 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. Function Return Values Return Value 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);

156 rcx - Kernel API Function Reference Kernel API Functions 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 htsk pusta Handle of the task Pointer to destination variable to copy the status code to Function Return Values Return Value RX_OK (0x0000) RX_KNL_TASK_UNKNOWN (0x0006) The status code has been retrieved. The task handle is invalid. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No.

157 rcx - Kernel API Function Reference Kernel API Functions 157 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 */

158 rcx - Kernel API Function Reference Kernel API Functions 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 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 ppvmem ulsiz Pointer to the variable where to copy the pointer of the memory block to Size of the memory block in Bytes Function Return Values Return Value RX_OK (0x0000) RX_MEM_RESOURCE (0x0103) A memory block has been allocated. Out of memory Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible Yes

159 rcx - Kernel API Function Reference Kernel API Functions 159 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);...

160 rcx - Kernel API Function Reference Kernel API Functions 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 pvmem Pointer of the memory block to be freed Function Return Values Return Value RX_OK (0x0000) The Memory block is freed. Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible Yes

161 rcx - Kernel API Function Reference Kernel API Functions 161 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);

162 rcx - Kernel API Function Reference Kernel API Functions 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 associated with it. Function Syntax in C -Convention RX_RESULT rx_memcreatesharedmemory ( STRING* pszidn, RX_HANDLE hshm, void* pvshm, UINT usiz ) Function Arguments Argument pszidn hshm pvshm usiz Shared memory name Pointer to a string of a length of maximum 16 bytes 0 (15+1) terminated Pointer to a memory block with RX_SHAREDMEMORY_SIZE bytes Pointer to the memory area to be shared Size of the memory area to be shared in bytes Function Return Values Return Value RX_OK (0x0000) RX_MEM_NAME (0x0101) The shared memory has been created A shared memory object with the same name exists already. Allowed to be called by Initialization, Task, and Application Timers. Pre-emption possible Yes

163 rcx - Kernel API Function Reference Kernel API Functions 163 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));...

164 rcx - Kernel API Function Reference Kernel API Functions 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 pszidn uinst phshm Pointer to a shared memory name as 0 terminated string Instance number Pointer to a variable where to copy the handle of the shared memory to Function Return Values Return Value RX_OK (0x0000) RX_MEM_UNKNOWN (0x0109) Shared memory object has been identified. Shared memory object is not known. Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible Yes

165 rcx - Kernel API Function Reference Kernel API Functions 165 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 */

166 rcx - Kernel API Function Reference Kernel API Functions 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 hshm ppvshm pusiz Shared memory handle Pointer to the variable where to copy the pointer of the shared memory pointer to Pointer to the variable where to copy the size of the shared memory area to Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) The information has been retrieved. The handle is invalid. Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No.

167 rcx - Kernel API Function Reference Kernel API Functions 167 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 */

168 rcx - Kernel API Function Reference Kernel API Functions 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 hshm utimeout Shared memory handle Timeout value in system timer ticks 0x xFFFFFFFE 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 (0x ) rx_memlocksharedmemory() will wait until the shared memory 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. Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) RX_MEM_NO_ACCESS (0x010B) RX_TIMEOUT (0x0001) RX_MEM_DELETED (0x010D) The shared memory object has been locked. The handle is invalid. The shared memory object could not be locked. Timeout occurred before the shared memory could be locked. The shared memory has been deleted while waiting for locking it.

169 rcx - Kernel API Function Reference Kernel API Functions 169 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 */

170 rcx - Kernel API Function Reference Kernel API Functions 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 hshm Shared memory handle Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) The shared memory has been unlocked. The handle is invalid. Allowed to be called by Initialization, Task and Application Timer Pre-emption possible Yes.

171 rcx - Kernel API Function Reference Kernel API Functions 171 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 */

172 rcx - Kernel API Function Reference Kernel API Functions Triple Buffer Services Header-File AP_Mem.h 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 pszidn htrp ptbufpool Triple Buffer name Pointer to a string of a length of maximum 16 bytes 0 (15+1) terminated Pointer to a memory block with RX_TRIPLEBUFFER_SIZE bytes. Pointers to three buffer pointers to be used pabbufa Pointer to first buffer pabbufb Pointer to second buffer pabbufc Pointer to third buffer Function Return Values Return Value RX_OK (0x0000) RX_KNL_DUPLICATE_NAME (0x001C) RX_KNL_NAME_TOO_LONG (0x001D) Function succeed. A triple buffer with the name and the current s task instance number exists already. The specified ID string is longer than 16 bytes Allowed to be called by Initialization, Task and Application Timers.

173 rcx - Kernel API Function Reference Kernel API Functions 173 Pre-emption possible Yes Example Code 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)...

174 rcx - Kernel API Function Reference Kernel API Functions 174 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);

175 rcx - Kernel API Function Reference Kernel API Functions 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 pszidn uinst phtriplebuffer Pointer to a name as 0 terminated string Instance number Pointer to variable where to copy the triple buffer handle to. Function Return Values Return Value RX_OK (0x0000) RX_KNL_DUPLICATE_NAME (0x001C) RX_KNL_NAME_TOO_LONG (0x001D) Function succeed. A triple buffer with the name and the current s task instance number exists already. The specified ID string is longer than 16 bytes Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible Yes

176 rcx - Kernel API Function Reference Kernel API Functions 176 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);

177 rcx - Kernel API Function Reference Kernel API Functions 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 htrp Triple buffer handle pabwritebuffer Pointer to a variable to receive the write buffer pointer Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) Function succeed. The handle is invalid. Allowed to be called by Initialization, Tasks and Application Timers. Pre-emption possible Yes

178 rcx - Kernel API Function Reference Kernel API Functions 178 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);

179 rcx - Kernel API Function Reference Kernel API Functions rx_memexchangebuffer() Exchange the Write Buffer and Mark Triple Buffer as updated rx_memexchangebuffer() exchanges the buffers and marks the triple buffer as updated. Additionally, it returns the next write buffer. Function Syntax in C -Convention RX_RESULT rx_memexchangebuffer( RX_HANDLE htrp, UINT8** pabnextwritebuffer); Function Arguments Argument htrp pabnextwritebuf fer Triple buffer handle Next write buffer to be updated Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) Function succeed. The handle is invalid. Allowed to be called by Initialization, Tasks and Application Timers. Pre-emption possible Yes

180 rcx - Kernel API Function Reference Kernel API Functions 180 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);

181 rcx - Kernel API Function Reference Kernel API Functions 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 htrp Triple buffer handle pabreadbuffer Pointer to variable to store current read buffer pointer Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) Function succeed. The handle is invalid. Allowed to be called by Initialization, Tasks and Application Timers. Pre-emption possible Yes

182 rcx - Kernel API Function Reference Kernel API Functions 182 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);

183 rcx - Kernel API Function Reference Kernel API Functions 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 update to the buffer. Function Syntax in C -Convention RX_RESULT rx_memgetexchangedbufferwait(rx_handle hmtx, UINT8** pabreadbuffer, UINT utimeout ) Function Arguments Argument htrp utimopt Triple buffer handle not implemented set always to RX_INFINITE Function Return Values Return Value RX_OK (0x0000) RX_TIMEOUT (0x0001) RX_KNL_HANDLE_INVALID (0x0019) RX_MEM_DELETED (0x010D) The mutex has been successfully locked. Timeout elapsed before any update has been made. The handle is invalid. While waiting for an update, the triple buffer has been deleted. Allowed to be called by Initialization, Tasks and Application Timers. Pre-emption possible Yes

184 rcx - Kernel API Function Reference Kernel API Functions 184 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);

185 rcx - Kernel API Function Reference Kernel API Functions rx_memenabletriplebuffercallback() Sets an Update Callback on a Triple Buffer rx_memenabletriplebuffercallback() sets an update callback to be called whenever the triple buffer will be updated. Function Syntax in C -Convention RX_RESULT rx_mtxenabletriplebuffercallback(rx_handle htrp, TRIPLEBUFFER_CALLBACK pfncbk, VOID* pvparam) Function Arguments Argument htrp Triple buffer handle pfncbk Callback to be called on every update pvparam User data pointer for callback Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) Function succeed. The handle is invalid. Allowed to be called by Initialization, Tasks and Application Timers. Pre-emption possible Yes

186 rcx - Kernel API Function Reference Kernel API Functions 186 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;

187 rcx - Kernel API Function Reference Kernel API Functions 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 htrp Triple buffer handle Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) Function succeed. The handle is invalid. Allowed to be called by Initialization, Tasks and Application Timers. Pre-emption possible Yes

188 rcx - Kernel API Function Reference Kernel API Functions 188 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 */

189 rcx - Kernel API Function Reference Kernel API Functions 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 htrp Triple buffer handle Function Return Values Return Value RX_OK (0x0000) RX_KNL_HANDLE_INVALID (0x0019) The triple buffer has been successfully deleted The handle is invalid. Allowed to be called by Initialization, Task and Application Timers. Pre-emption possible Yes

190 rcx - Kernel API Function Reference Kernel API Functions 190 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 */

191 rcx - Kernel API Function Reference Kernel API Functions Fault Services Header-File AP_Flt.h Providing Fault Services <#include AP_Flt.h > 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 ufltcod uprm efltsvty pszsrcfil usrclin Task specific fault code to be logged. Extra parameter for general use. Not pre-defined and task specific. value is related to the fault code. 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 Pointer to the source code name of that file that has called the function. Use the compiler specific Marco FILE to get the current file name. Source code line reflecting the line where the function has been called. Use the compiler specific Marco LINE to get the current line number.

192 rcx - Kernel API Function Reference Kernel API Functions 192 Function Return Values Return Value 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...

193 rcx - Kernel API Function Reference Kernel API Functions 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 eerr Fatal error code Function Return Values Return Value None None Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible Yes

194 rcx - Kernel API Function Reference Kernel API Functions Verbose Output Services Header-File AP_Vbs.h Providing Verbose Services <#include AP_Vbs.h > 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 pchfmt Printf-style format string... Arguments specified in the format string

195 rcx - Kernel API Function Reference Kernel API Functions 195 Function Return Values Return Value None None Allowed to be called by Initialization, Task, ISR and Application Timers. Pre-emption possible No. Example Code... /* 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));...

196 rcx - Kernel API Function Reference Contact Contact Headquarter Germany Hilscher Gesellschaft für Systemautomation mbh Rheinstrasse Hattersheim Phone: +49 (0) Fax: +49 (0) [email protected] netx Support Phone: +49 (0) [email protected] Subsidiaries China Hilscher Ges.f.Systemaut. mbh Shanghai Representative Office Shanghai Phone: +86 (0) [email protected] Support Phone: +86 (0) [email protected] France Hilscher France S.a.r.l Bron Phone: +33 (0) [email protected] Support Phone: +33 (0) [email protected] Italy Hilscher Italia srl Vimodrone (MI) Phone: [email protected] Support Phone: +39 / [email protected] Japan Hilscher Japan KK Tokyo, Phone: +81 (0) [email protected] Support Phone: +81 (0) [email protected] Switzerland Hilscher Swiss GmbH 4500 Solothurn Phone: +41 (0) [email protected] Support Phone: +49 (0) [email protected] USA Hilscher North America, Inc. Lisle, IL Phone: [email protected] Support Phone: [email protected]