RMOS3 V3.50 Reference Manual Part III RMOS3. RMOS3 real-time operating system RMOS3 V3.50 Reference Manual Part III. About this manual...

Transcription

1 About this manual... 1 RMOS3 s 2 RMOS3 C Runtime Library 3 RMOS3 real-time operating system RMOS3 V3.50 Reference Manual Part III Programming Manual 07/2012 A5E

2 Legal information Warning notice system This manual contains notices you have to observe in order to ensure your personal safety, as well as to prevent damage to property. The notices referring to your personal safety are highlighted in the manual by a safety alert symbol, notices referring only to property damage have no safety alert symbol. These notices shown below are graded according to the degree of danger. DANGER indicates that death or severe personal injury will result if proper precautions are not taken. WARNING indicates that death or severe personal injury may result if proper precautions are not taken. CAUTION indicates that minor personal injury can result if proper precautions are not taken. NOTICE indicates that property damage can result if proper precautions are not taken. If more than one degree of danger is present, the warning notice representing the highest degree of danger will be used. A notice warning of injury to persons with a safety alert symbol may also include a warning relating to property damage. Qualified Personnel The product/system described in this documentation may be operated only by personnel qualified for the specific task in accordance with the relevant documentation, in particular its warning notices and safety instructions. Qualified personnel are those who, based on their training and experience, are capable of identifying risks and avoiding potential hazards when working with these products/systems. Proper use of Siemens products Note the following: Trademarks WARNING Siemens products may only be used for the applications described in the catalog and in the relevant technical documentation. If products and components from other manufacturers are used, these must be recommended or approved by Siemens. Proper transport, storage, installation, assembly, commissioning, operation and maintenance are required to ensure that the products operate safely and without any problems. The permissible ambient conditions must be complied with. The information in the relevant documentation must be observed. All names identified by are registered trademarks of Siemens AG. The remaining trademarks in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owner. Disclaimer of Liability We have reviewed the contents of this publication to ensure consistency with the hardware and software described. Since variance cannot be precluded entirely, we cannot guarantee full consistency. However, the information in this publication is reviewed regularly and any necessary corrections are included in subsequent editions. Siemens AG Industry Sector Postfach NÜRNBERG GERMANY A5E P 07/2012 Technical data subject to change Copyright Siemens AG All rights reserved

3 Table of contents 1 About this manual About this manual Notations RMOS3 s RmActivateTask RmAlloc RmBindTask RmCatalog RmChangeDescriptor RmChangeDescriptorAccess RmClrShIntISHandler RmCreateBinSemaphore RmCreateChildTask RmCreateDescriptor RmCreateDriver RmCreateFlagGrp RmCreat box RmCreateMemPool RmCreateMessageQueue RmCreateOS RmCreateTask RmCreateTaskEx RmCreateUnit RmDecode RmDeleteBinSemaphore RmDeleteDescriptor RmDeleteFlagGrp RmDelet box RmDeleteMemPool RmDeleteMessageQueue RmDeleteTask RmDisableScheduler RmEnableScheduler Programming Manual, 07/2012, A5E

4 Table of contents 2.30 RmEndTask RmExclude RmFlatToSegAddress RmFree RmFreeAll RmGetAbsTime RmGetBindTaskInfo RmGetBinSemaphore RmGetEntry RmGetFlag RmGetHWClockTime RmGetIntHandler RmGetLinAddress RmGetMemPoolInfo RmGetName RmGetPeriodHPET RmGetPhysAddress RmGetSize RmGetSpinLock RmGetSpinLockIRQ RmGetStatusMessageQueue RmGetSysB RmGetSystemPeriod RmGetSystemTime RmGetTaskID RmGetTaskInfo RmGetTaskPriority RmGetTaskState RmGetTimeHPET RmHookException RmInitFastTask RmInitFastTick RmInitHPET RmInitShIntClient RmInitSpinLock Programming Manual, 07/2012, A5E

5 Table of contents 2.65 RmInitOS RmIO RmKillTask RmList RmMapMemory RmMemPoolAlloc RmPauseTask RmPciSearch RmPciSearchSub RmQueueStartTask RmReadMessage RmReAlloc RmReceiv RmReleaseBinSemaphore RmReleaseSpinLock RmReleaseSpinLockIRQ RmRemoveFastTask RmRemoveFastTick RmReserveInterrupt RmResetFlag RmResetLocalFlag RmResetOS RmRestartTask RmRestoreIntHandler RmResumeDriver RmResumeTask RmRunOS RmSegToFlatAddress RmSendMail RmSendMailCancel RmSendMailDelayed RmSendMessage RmSetDeviceHandler RmSetFlag RmSetFlagDelayed Programming Manual, 07/2012, A5E

6 Table of contents RmSetHWClockTime RmSetIntDefHandler RmSetIntDIHandler RmSetIntISHandler RmSetIntMailboxHandler RmSetIntTaskHandler RmSetLocalFlag RmSetMailboxSize RmSetMessageQueueSize RmSetOS RmSetProfilerPoint RmSetPutcharProc RmSetShIntISHandler RmSetShIntISHandler RmSetSMRCount RmSetSVC RmSetSystemTime RmSetTaskPriority RmStartTask RmSuspendDriver RmSuspendTask RmUncatalog C Runtime Library _ctime _gmtime _localtime _time abort abs access acos asctime asin assert atan Programming Manual, 07/2012, A5E

7 Table of contents 3.13 atan atexit atof atoi atol bsearch calloc ceil changevib chdir checkpoint chmod clearerr clock close cos cosh createvib ctime difftime dismount div duread duwrite errno, errno exit exp fabs fclose fduopen fdureopen feof ferror fflush fgetc Programming Manual, 07/2012, A5E

8 Table of contents 3.48 fgetpos fgets fileno floor fmod fopen fprintf fputc fputs fread free freopen frexp fscanf fseek fsetpos ftell fwrite getc getchar getcwd getenv gets gettimestamp getvolumestatus getw gmtime inhibitabort isalnum isalpha isascii iscntrl isdigit isgraph islower Programming Manual, 07/2012, A5E

9 Table of contents 3.83 isprint ispunct isspace isupper isxdigit labs ldexp ldiv localtime log log longjmp lseek malloc matherr memccpy memchr memcmp memcpy memmove memset mkdir mktime modf mount open perror pow printf putc putchar putenv puts putw qsort Programming Manual, 07/2012, A5E

10 Table of contents raise rand read realloc remap remove rename rewind rmdir scanf search searchlong setbuf setjmp setvbuf signal sin sinh sleep snprintf sprintf sqrt srand sscanf strcat strchr strcmp strcpy strcspn strerror strftime strlen strncat strncmp strncpy Programming Manual, 07/2012, A5E

11 Table of contents strpbrk strrchr strspn strstr strtod strtok strtol strtoul sys_errlist, sys_nerr tan tanh time tmpfile tmpnam toascii tolower, _tolower toupper, _toupper tzset ungetc unlink vfprintf vfscanf vprintf vscanf vsnprintf vsprintf vsscanf write x_cr_gettaskid x_cr_gettaskparam x_cr_initenv x_cr_killtsk x_cr_setexit xinitc xinitt Programming Manual, 07/2012, A5E

12 Table of contents Tables Table 1-1 Commands Table 1-2 Abbreviations Table 1-3 General data types Table 1-4 Data types of the RMOS3 API Programming Manual, 07/2012, A5E

13 About this manual About this manual... Overview Above all this reference manual supports you in programming the RMOS3. It is the central reference work for programming, testing and monitoring of source codes. Chapter 1 "About this manual..." (Page 13) provides guidelines to the documentation and explains the notations used in the manual. Chapter 2 "RMOS3 functions" (Page 17) offers a detailed description of the RMOS3 functions in alphabetical order. Chapter 3 "C runtime library" (Page 195) offers a detailed description of the CRUN functions in alphabetical order. Programming Manual, 07/2012, A5E

14 About this manual Notations 1.2 Notations We use the following notation to enhance legibility of the RMOS3 documentation: Commands Commands control program sequences in dialog or batch mode. The Courier font is used in the text to highlight the commands. A command consists of at least one element. Elements are constants or variables. They are comprised of letters, numbers and special characters (e.g. #*?). The Courier font is also used to present program listings. They are printed in compliance with the characters and do not follow the notation for commands. The programming language C, for example, distinguishes between uppercase and lowercase notation. Table 1-1 Commands Representation Property Comment UPPERCASE Constant Elements in uppercase notation represent constants. Entries are made in accordance with the character notation with support of uppercase and lowercase letters Constant Numbers are always constants. x Variable Elements in lowercase notation represent variables that can be replaced by current elements. ()\:;> Special characters Special characters and whitespaces serve as delimiters between elements and always need to be entered. The use of elements is described by meta characters. Meta characters are not entered. Representation Property Comment < > Delimiters Variables are enclosed in angled brackets [ ] Optional Elements in angled brackets are optional. a b c Selection An element can be selected if several elements are arranged vertically in braces or horizontally between vertical lines.... Repetition Ellipses indicate a possible repetition of the previous element. Abbreviations A number of abbreviations and short names apply to the entire RMOS3 documentation: Table 1-2 Abbreviations Abbreviation Text passage cfg configurable System calls uintmax maximum unsigned integer (FFFF FFFFH) System calls dp data pointer (sel:off) 48-bit pointer System calls 14 Programming Manual, 07/2012, A5E

15 About this manual Notations Data types The following data types may be used for the C compilers approved for RMOS3: Table 1-3 General data types Data type char short int long long long 1 void _FAR * 2 void _NEAR * 2 enum float double Data length 8 bit 16 bit 32 bit 32 bit 64 bit 48 bit 32 bit 32 bit 32 bit 64 bit 1 Only available for GNU programs. 2 Pointers in flat programs always have a length of 32 bit. No distinction is made between NEAR and FAR. Table 1-4 Data types of the RMOS3 API Name Data type Data length uchar unsigned char 8 bit ushort unsigned short 16 bit uint unsigned int 32 bit ulong unsigned long 32 bit rmfarproc 1 rmnearproc 1 rmproc 1 Pointer to function type void _FAR f(void) Pointer to function type void _NEAR f(void) Pointer to function type void _NEAR f(void) 48 bit 32 bit 32 bit 1 Pointers in flat programs always have a length of 32 bit. No distinction is made between NEAR and FAR. Programming Manual, 07/2012, A5E

16 About this manual Notations 16 Programming Manual, 07/2012, A5E

17 RMOS3 s RmActivateTask Activate task #include <rmapi.h> int RmActivateTask(uint TaskID); TaskID Task ID This call switches another task to the READY state, if it was previously in the BLOCKED state. RmActivateTask is not permitted in any of the following states and will be terminated with an error code if invoked: End/delete by RmKillTask was already initiated Debugger breakpoint For all runtime errors (e.g. division errors) Note The wait condition of the target task will be reset (e.g. the time condition of RmPauseTask is reset to 0, or the wait time is set to RM_CONTINUE by RmGetFlag). The target task then changes to READY. ID dec 0 RM_OK SVC successfully completed Programming Manual, 07/2012, A5E

18 RMOS3 s 2.1 RmActivateTask Error codes ID dec Error code 36 RM_INVALID_ID An invalid TaskID was passed. 22 RM_INVALID_TASK_STATE Call invalid in the current task state. (Task is in DORMANT, RUNNING, READY state, or BLOCKED for I/O completion) Debugger command QUERY 18 Programming Manual, 07/2012, A5E

19 RMOS3 s 2.2 RmAlloc 2.2 RmAlloc Allocate memory from HEAP #include <rmapi.h> int RmAlloc ( ulong TimeOutValue, uint Mode, ulong Size, void **ppmemory); TimeOutValue Mode Maximum time to wait for execution 0 RM_CONTINUE Continue task without waiting for memory allocation. -1 RM_WAIT Wait for memory allocation ULONG_MAX Time interval in ms. For time, the values for hours, minutes and seconds can be linked by addition. The maximum waiting time is 2 31 milliseconds. RM_HOUR(hour) Waits (hour) hours RM_MINUTE(min) Waits (min) minutes RM_SECOND(sec) Waits (sec) seconds RM_MILLISECOND(ms) Waits (ms) milliseconds Times must only be specified as a multiple of the system clock rate (default 10 ms). Memory allocation method: RM_AUTOFREE (0) RM_NOAUTOFREE (2) Memory is released automatically with RmFreeAll (Page 63). Memory allocation is task-specific. Memory is not released automatically with RmFreeAll (Page 63). Programming Manual, 07/2012, A5E

20 RMOS3 s 2.2 RmAlloc Mode (cont.) Size ppmemory RM_FLATALLOC (0x0C) RM_STACKALLOC (0x2000) RM_USERALLOC (0x20) RM_SYSALLOC (0x10) The ppmemory pointer contains FlatSelector:FlatOffset. FlatOffset can be passed directly to FLAT programs as pointer. This mode applies to segmented programs only. For using the memory with RmCreateTaskEx as stack. Memory is protected with "Guarded Pages". A stack over-run is recognized. Address lies above address 0xf If the address is converted with RmGetPhysAddress (Page 80), the converted address cannot be accessed on privilege level 3 (PL3). For use with memory requirement of a segmented privilege level 0 (PL0) task that wishes to send the pointer to the memory area to a PL3 task. For use with memory requirement of a segmented privilege level 3 (PL3) task that wishes to send the pointer to the memory area to a PL0 task. The modes can be combined by, e.g. RM_AUTOFREE RM_FLATALLOC Size of the memory area (-1 = largest available block) Address of pointer to a memory area This call allocates a memory area of size Size from the HEAP. A memory requested on privilege level 0 (PL0) can only be used on PL3 with CADUL programs if the call was called with the option "RM_USERALLOC". ID dec 0 RM_OK successfully completed 20 Programming Manual, 07/2012, A5E

21 RMOS3 s 2.2 RmAlloc Error codes ID dec Error code 9 RM_GDT_FULL All entries in the GDT are occupied. One GDT entry is required for each memory area. 4 RM_GOT_TIMEOUT Appropriate memory space could not be allocated at the specified time. 42 RM_INVALID_POINTER Invalid pointer found. 38 RM_INVALID_SIZE Size=0 or size greater than HEAP 3 RM_OUT_OF_MEMORY Memory of the specified size is not available RmCreateMemPool (Page 38) RmDeleteMemPool (Page 54) RmFree (Page 62) RmGetSize (Page 81) RmMemPoolAlloc (Page 115) RmReAlloc (Page 126) Programming Manual, 07/2012, A5E

22 RMOS3 s 2.3 RmBindTask 2.3 RmBindTask Bind task to a core #include <rmapi.h> int RmBindTask ( uint TaskID, uint CoreID); TaskID CoreID ID of the task that is to be bound to a core ID of the core 0 RM_CORE_0 Core 0 1 RM_CORE_1 Core 1 2 RM_CORE_2 Core 2 3 RM_CORE_3 Core RM_CORE_ALL Task may run on any core The call binds the task with the ID TaskID to the core with the ID CoreID. The call results in the immediate change of the task to another core, if the specified core does not conform to the current executing core. A task should only be bound to a core in exceptional cases. The preset for a task is that it can be executed on any core. ID dec 0 RM_OK successfully completed. Error codes ID dec Error code 36 RM_INVALID_ID The specified Task ID is invalid. 2 RM_PARAMETER_ERROR The specified Core ID is invalid. RmGetBindTaskInfo (Page 65) 22 Programming Manual, 07/2012, A5E

23 RMOS3 s 2.4 RmCatalog 2.4 RmCatalog Enter resource in resource catalog #include <rmapi.h> int RmCatalog ( uint Type, uint ID, ulong IDEx, char * pname) ; Type ID IDEx pname Resource type Resource ID Extended ID Address of the name under which the entry is stored. The string can be defined according to C or PLM notation. The call inserts the specified parameters in the catalog. ID dec 0 RM_OK successfully completed. Programming Manual, 07/2012, A5E

24 RMOS3 s 2.4 RmCatalog Error codes ID dec Error code 3 RM_OUT_OF_MEMORY An internal attempt failed to allocate memory from the HEAP. 35 RM_INVALID_TYPE The specified Type is invalid. 0<= Type<=11 36 RM_INVALID_ID The specified ID is invalid. The possible IDs depend on the Type: 0 RM_CATALOG_TASK 0<=id<= RM_CATALOG_DEVICE 0<=id<=255 2 RM_CATALOG_POOL 0<=id<=63 3 RM_CATALOG_SEMAPHORE 0<=id<= RM_CATALOG_EVENTFLAG 0<=id<=63 6 RM_CATALOG_LOCALMAILBOX 0<=id<=255 7 RM_CATALOG_MISC 0<=id<= RM_CATALOG_USER 0<=id<= RM_CATALOG_UNIT 0<=id<= RM_CATALOG_MESSAGE 0<=id<= RM_INVALID_STRING Invalid string length. The specified length was either zero or greater than RM_INVALID_POINTER The pointer to the string is invalid, or would cause an access violation. 47 RM_IS_ALREADY_CATALOGED The specified string is already cataloged. The string must be unique. For this reason, a string cannot be cataloged more than once. 100 RM_CATALOG_EXCEEDED The catalog is full. A maximum of 4096 entries is permitted. RmGetEntry (Page 68) RmGetName (Page 77) RmList (Page 112) RmUncatalog (Page 194) 24 Programming Manual, 07/2012, A5E

25 RMOS3 s 2.5 RmChangeDescriptor 2.5 RmChangeDescriptor Change descriptor #include <rmapi.h> int RmChangeDescriptor( selector Sel, ulong LinAddress, ulong Limit); Sel Valid selector for descriptor LinAddress Absolute physical address Limit Segment length 1 RmChangeDescriptor enters a new base address and a new segment length into the descriptor specified by a selector. Only descriptors from the GDT can be modified. Note This function is not necessary in the flat memory model. ID dec 0 RM_OK SVC successfully completed Error codes ID dec Error code 21 RM_INVALID_SELECTOR An invalid descriptor was used. RmChangeDescriptorAccess (Page 26) RmCreateDescriptor (Page 33) RmDeleteDescriptor (Page 51) RmFlatToSegAddress (Page 61) RmGetLinAddress (Page 75) RmGetPhysAddress (Page 80) RmSegToFlatAddress (Page 149) Programming Manual, 07/2012, A5E

26 RMOS3 s 2.6 RmChangeDescriptorAccess 2.6 RmChangeDescriptorAccess Change descriptor access rights #include <rmapi.h> int RmChangeDescriptorAccess( selector Sel, uint Access); Sel Valid selector Access ACS_ER 9AH Execute-Read access rights ACS_RW 92H Read-Write access rights ACS_RWD 96H Read-Write-Expand-Down access rights RmChangeDescriptorAccess enters a new access rights byte into the descriptor specified by a selector. This byte is stored in the low-order byte of the access rights word. If RmChangeDescriptorAccess causes a data segment of length n*4 kbyte to change from EXPAND-UP type to EXPAND-DOWN type, or vice versa, the base address and limit of the descriptor are corrected accordingly. The previously selected physical address area is left unchanged. If the length of the data segment is not an integer multiple of 4 kbyte, the expand direction cannot be changed. Only descriptors from the GDT can be modified. Note This function is not necessary with the flat memory model, but it can be called. ID dec 0H RM_OK SVC successfully completed 26 Programming Manual, 07/2012, A5E

27 RMOS3 s 2.6 RmChangeDescriptorAccess Error codes ID dec Error code 21 RM_INVALID_SELECTOR An invalid descriptor was used. 6 RM_INVALID_SEGMENTLENGTH Invalid segment length specified ( n * 4 kbyte). RmChangeDescriptor (Page 25) RmCreateDescriptor (Page 33) RmDeleteDescriptor (Page 51) RmFlatToSegAddress (Page 61) RmGetLinAddress (Page 75) RmGetPhysAddress (Page 80) RmSegToFlatAddress (Page 149) Programming Manual, 07/2012, A5E

28 RMOS3 s 2.7 RmClrShIntISHandler 2.7 RmClrShIntISHandler Remove Shared Interrupt Handler (contained in RMISHCLI.LIB) #include <rmpci.h> int RmClrShIntISHandler ( uint Irqx, uint chainid); Irqx chainid Interrupt Request Number (IRQ0-15 or IRQ0-23) It can be derived with function call RmPciSearch from the PCI_CONFIG_SPACE structure (element IntLine). Pointer to ID for InterruptHandlerEntry RmClrShIntISHandler calls a server function that deletes the corresponding interrupt handler entry from the server, regardless of the entry mode. If the last entry for interrupt Irqx is removed, the default interrupt handler of RMOS3 is installed. ID dec 0 RM_OK successfully completed Error codes ID dec Error code 38 RM_INVALID_SIZE No handler to delete 41 RM_INVALID_IRQ_NUMBER Irqx invalid 36 RM_INVALID_ID Invalid chainid Example See RmSetShIntISHandler2 (Page 183) RmInitShIntClient (Page 104) RmPciSearch (Page 118) RmPciSearchSub (Page 120) RmSetShIntISHandler1 (Page 181) RmSetShIntISHandler2 (Page 183) 28 Programming Manual, 07/2012, A5E

29 RMOS3 s 2.8 RmCreateBinSemaphore 2.8 RmCreateBinSemaphore Define dynamic semaphore #include <rmapi.h> int RmCreateBinSemaphore( char *psemaphorename, uint *psemaphoreid); psemaphorename psemaphoreid Pointer to a C string containing the name under which the semaphore is to be cataloged. If this pointer = NULL, the semaphore is not cataloged. Pointer to semaphore ID RmCreateBinSemaphore defines a dynamic semaphore. The semaphore ID is returned in the specified memory area. The maximum number of dynamic semaphores is 1024; you can edit the file RMOS.INI to increase this number to The semaphore is automatically cataloged under the specified name. ID dec 0 RM_OK *psemaphoreid contains the valid semaphore ID Programming Manual, 07/2012, A5E

30 RMOS3 s 2.8 RmCreateBinSemaphore Error codes ID dec Error code 16 RM_OUT_OF_ SEMAPHORES 42 RM_INVALID_POINTER Invalid pointer found. The request exceeds the maximum number of semaphores. 100 RM_CATALOG_EXCEEDED Catalog capacity is exceeded (see RmCatalog). 37 RM_INVALID_STRING Invalid string length. The specified length was either zero or greater than RM_IS_ALREADY_CATALOGED The specified string is already cataloged. The string must be unique. For this reason, a string cannot be cataloged more than once. RmDeleteBinSemaphore (Page 50) RmGetBinSemaphore (Page 66) RmReleaseBinSemaphore (Page 130) 30 Programming Manual, 07/2012, A5E

31 RMOS3 s 2.9 RmCreateChildTask 2.9 RmCreateChildTask Register task with the operating system #include <rmapi.h> int RmCreateChildTask ( char * ptaskname, ulong TaskStackSize, uint Priority, rmfarproc TaskEntry, uint * ptaskid); ptaskname Pointer to a C string containing the name under which the task is to be cataloged. If this pointer = NULL, the task is not cataloged. The C string may have a maximum of 15 characters + \0. TaskStackSize Size of requested stack in words (32 bit). Priority Task priority (0..255) TaskEntry Entry point address of the task ptaskid Pointer to task ID RmCreateChildTask reports tasks to the operating system. The task is transferred from the NON-EXISTENT state to the DORMANT state. The task is automatically cataloged under the specified name. If a NULL pointer is passed for ptaskname, cataloging does not take place. When generating the child task, the console, the current working directory and the environment are inherited from the parent task. This process includes access to the file system if the parent task has a working directory. ID dec 0 RM_OK successfully completed. *ptaskid contains the valid task ID. Programming Manual, 07/2012, A5E

32 RMOS3 s 2.9 RmCreateChildTask Error codes ID dec Error code 3 RM_OUT_OF_MEMORY Insufficient memory to create stack segment, or RmCatalog is out of memory. 23 RM_RESOURCE_NOT_AVAILABLE Maximum number of tasks is exceeded. 37 RM_INVALID_STRING Invalid string length. The specified length was either zero or greater than RM_INVALID_SIZE The specified stack length was 0 or 1GB 42 RM_INVALID_POINTER The pointer to the string is invalid, or would cause an access violation. 47 RM_IS_ALREADY_CATALOGED The specified string is already cataloged. The string must be unique. For this reason, a string cannot be cataloged more than once. 60 RM_INVALID_TASK_ENTRY Invalid entry point address for the task. 100 RM_CATALOG_EXCEEDED Catalog capacity is exceeded (see RmCatalog). RmCreateTask (Page 42) RmDeleteTask (Page 56) xinitt (Page 438) 32 Programming Manual, 07/2012, A5E

33 RMOS3 s 2.10 RmCreateDescriptor 2.10 RmCreateDescriptor Create descriptor #include <rmapi.h> int RmCreateDescriptor( ulong LinAdress, ulong Limit, selector *psel); LinAddress Absolute physical segment start address Limit Segment length 1 psel Pointer to a descriptor RmCreateDescriptor creates a descriptor in the GDT and returns the selector to this descriptor. The descriptor has the READ/WRITE attribute. Memory is not reserved under the specified address. Note There are no restrictions with regard to the segment length. However, as of a length of 1 MB, the segment length is increased to a multiple of 4 KB. This function is not necessary in the FLAT memory model. ID dec 0 RM_OK *psel contains a pointer to the descriptor Error codes ID dec Error code 9 RM_GDT_FULL The global descriptor table has no space for additional entries. 42 RM_INVALID_POINTER Invalid pointer found. RmChangeDescriptor (Page 25) RmChangeDescriptorAccess (Page 26) RmDeleteDescriptor (Page 51) RmFlatToSegAddress (Page 61) RmGetLinAddress (Page 75) RmGetPhysAddress (Page 80) RmSegToFlatAddress (Page 149) Programming Manual, 07/2012, A5E

34 RMOS3 s 2.11 RmCreateDriver 2.11 RmCreateDriver Register driver with the operating system #include <rmapi.h> int RmCreateDriver ( uint Mode, char * pdevicename, RmDCDStruct *pdcd, uint *pdriverid); Mode Reserved (set to 0) pdevicename Pointer to a C string containing the name under which the driver is to be cataloged. If this pointer = NULL, the driver is not cataloged. In this case the driver must catalog itself. pdcd Pointer to a structure of the RmDCDStruct type defined as follows: typedef struct _RmDCDStruct { struct _RmUCDStruct _NEAR * ucd; uchar units; uchar shr; rmproc init; rmproc svc; uchar flags; uchar fmax; #if RM3 uchar res[4]; #else uchar res[2]; #endif }RmDCDStruct; pdriverid Returned driver ID 34 Programming Manual, 07/2012, A5E

35 RMOS3 s 2.11 RmCreateDriver This call announces a driver to the operating system. The driver is automatically cataloged under the specified name. Drivers cannot be reloaded. The driver code and the DCD must be located in segment RM3_CODE32. Note This function cannot be used with the flat memory model. ID dec 0 RM_OK successfully completed Error codes ID dec Error code 3 RM_OUT_OF_MEMORY Insufficient memory for creating internal data structures, or RmCatalog is out of memory. 100 RM_CATALOG_EXCEEDED Catalog capacity is exceeded (see RmCatalog). 37 RM_INVALID_STRING Invalid string length. The specified length was either zero or greater than RM_IS_ALREADY_CATALOGED The specified string is already cataloged. The string must be unique. For this reason, a string cannot be cataloged more than once. 66 RM_INVALID_DCD_SEGMENT DCD is not located in the nucleus code segment RM3_CODE RM_INVALID_POINTER The pointer to the string is invalid, or would cause an access violation. RmCreateUnit (Page 47) Programming Manual, 07/2012, A5E

36 RMOS3 s 2.12 RmCreateFlagGrp 2.12 RmCreateFlagGrp Define dynamic flag group #include <rmapi.h> int RmCreateFlagGrp( char *pflaggrpname, uint *pflaggrpid); pflaggrpname pflaggrpid Pointer to a C string containing the name under which the flag group is to be cataloged. If this pointer = NULL, the flag group is not cataloged. Pointer to ID of flag group RmCreateFlagGrp defines a dynamic global flag group. The ID of the flag group is returned in the specified memory area. The flag group is automatically cataloged under the specified name. ID dec 0 RM_OK *pflaggrpid contains the valid ID of the flag ID Error codes ID dec Error code 12 RM_OUT_OF_FLAGGROUPS The request exceeds the maximum number of event flags. 42 RM_INVALID_POINTER Invalid pointer found. 100 RM_CATALOG_EXCEEDED Catalog capacity is exceeded (see RmCatalog). 37 RM_INVALID_STRING Invalid string length. The specified length was either zero or greater than RM_IS_ALREADY_CATALOGED The specified string is already cataloged. The string must be unique. For this reason, a string cannot be cataloged more than once. RmResetFlag (Page 138) RmSetFlag (Page 159) RmSetFlagDelayed (Page 160) RmDeleteFlagGrp (Page 52) RmGetFlag (Page 70) 36 Programming Manual, 07/2012, A5E

37 RMOS3 s 2.13 RmCreat box 2.13 RmCreat box Define dynamic mailbox #include <rmapi.h> int RmCreat box( char *pmailboxname, uint *pmailboxid); pmailboxname pmailboxid Pointer to a C string containing the name under which the mailbox is to be cataloged. If this pointer = NULL, the mailbox is not cataloged. Pointer to ID of a mailbox RmCreat box defines a dynamic mailbox. The ID of the mailbox is returned in the specified memory area. The mailbox is automatically cataloged under the specified name. ID dec 0 RM_OK *pmailboxid contains the valid mailbox ID Error codes ID dec Error code 100 RM_CATALOG_EXCEEDED Catalog capacity is exceeded (see RmCatalog). 42 RM_INVALID_POINTER Invalid pointer found. 37 RM_INVALID_STRING Invalid string length. The specified length was either zero or greater than RM_IS_ALREADY_CATALOGED The specified string is already cataloged. The string must be unique. For this reason, a string cannot be cataloged more than once. 15 RM_OUT_OF_MAILBOXES The request exceeds the maximum number of mailboxes. 3 RM_OUT_OF_MEMORY Memory of the specified size is not available RmDelet box (Page 53) Programming Manual, 07/2012, A5E

38 RMOS3 s 2.14 RmCreateMemPool 2.14 RmCreateMemPool Create dynamic memory pool greater than 64 kbyte #include <rmapi.h> int RmCreateMemPool( char *ppoolname, void *ppooladdress, ulong Size, uint *ppoolid); ppoolname ppooladdress Size ppoolid Pointer to a C string containing the name under which the memory pool is to be cataloged. If this pointer = NULL, the memory pool is not cataloged. Start address of pool Length of memory area in bytes Pointer to pool ID RmCreateMemPool defines a memory pool on a paragraph boundary. *ppoolid contains valid memory pool ID. The maximal number of memory pools is 8; the minimum size of a memory area is 16 bytes. The memory space for a memory pool can be allocated with RmAlloc from the HEAP. The returned address from RmAlloc is used as the address for the memory pool. During initialization the memory pools are placed on the next base address that can be divided by 16. The length is reduced to the next value that is divisible by 16. RmMemPoolAlloc guarantees that the returned pointer always has a base address that is divisible by 16 and an offset equal to 0. The memory pool is automatically cataloged under the specified name. If a NULL pointer is passed for ppoolname, a catalog entry is discarded. Note Note that pool_addr consists of a selector and an offset and that the absolute address is not obtained by adding the segment (shifted left by 4 bits) and offset, but by adding the segment base address and offset. Therefore, an existing selector must be specified in pool_addr for RmCreateMemPool. This selector can reference either an existing segment or new segment created with RmCreateDescriptor. The dynamically created descriptor can be deleted when the memory pool is cleared. This function cannot be used in the FLAT memory model. 38 Programming Manual, 07/2012, A5E

39 RMOS3 s 2.14 RmCreateMemPool ID dec 0 RM_OK *pool_id_ptr contains valid memory pool IDs Error codes ID dec Error code 39 RM_INVALID_OFFSET Offset (pool_addr) outside the valid range (<> 0000H). 38 RM_INVALID_SIZE Invalid size setting (size < 16). 42 RM_INVALID_POINTER Invalid pointer found. 100 RM_CATALOG_EXCEEDED Catalog capacity is exceeded (see RmCatalog). 37 RM_INVALID_STRING Invalid string length. The specified length was either zero or greater than RM_IS_ALREADY_CATALOGED The specified string is already cataloged. The string must be unique. For this reason, a string cannot be cataloged more than once. 13 RM_OUT_OF_MEMORYPOOLS The request exceeds the maximum number of memory pools. Memory pools RmFree (Page 62) RmFreeAll (Page 63) RmMemPoolAlloc (Page 115) Programming Manual, 07/2012, A5E

40 RMOS3 s 2.15 RmCreateMessageQueue 2.15 RmCreateMessageQueue Create message queue #include <rmapi.h> int RmCreateMessageQueue ( char * pmessagequeuename, uint TaskID); pmessagequeuename TaskID Pointer to a C string containing the name with which the message queue is to be cataloged. If this pointer = NULL, the message queue is not cataloged. Target task ID The call establishes a message queue for the task specified by TaskID. The message queue is automatically cataloged under the specified name. ID dec 0 RM_OK successfully completed. Error codes ID dec Error code 36 RM_INVALID_ID Invalid task ID 59 RM_QUEUE_EXIST The message queue already exists. 100 RM_CATALOG_EXCEEDED Catalog capacity is exceeded (see RmCatalog). 42 RM_INVALID_POINTER Invalid pointer found. 37 RM_INVALID_STRING Invalid string length. The specified length was either zero or greater than RM_IS_ALREADY_CATALOGED The specified string is already cataloged. The string must be unique. For this reason, a string cannot be cataloged more than once. RmDeleteMessageQueue (Page 55) RmReadMessage (Page 124) RmSendMessage (Page 155) 40 Programming Manual, 07/2012, A5E

41 RMOS3 s 2.16 RmCreateOS 2.16 RmCreateOS Align dynamic with static resource IDs #include <rmapi.h> int RmCreateOS ( uint SemaphoreNum, uint FlagNum, uint MailboxNum); SemaphoreNum FlagNum MailboxNum Number of static semaphores to be generated (0=unchanged) Number of static flags to be generated (0=unchanged) Number of static mailboxes to be generated (0=unchanged) This call creates dynamic resources with the same IDs that were used in the previous version for static resources. This allows existing applications with static resources to be ported very easily. The call also provides a convenient method for creating a specific number of resources in a new application. (In general, you should avoid this call because it is implemented only to ensure upward compatibility). IDs are assigned from 0 to (number of resources to be generated)-1. The call can be issued at any time. If resources previously generated are generated again by RmCreateOS(), the resources are left unchanged. Resources already generated remain unchanged. ID dec 0 RM_OK successfully completed. Error codes ID dec Error code 15 RM_OUT_OF_MAILBOXES Too many mailboxes were requested. 12 RM_OUT_OF_FLAGGROUPS Too many flags were requested. 16 RM_OUT_OF_SEMAPHORES Too many semaphores were requested. Programming Manual, 07/2012, A5E

42 RMOS3 s 2.17 RmCreateTask 2.17 RmCreateTask Register task with the operating system #include <rmapi.h> int RmCreateTask ( char * ptaskname, ulong TaskStackSize, uint Priority, rmfarproc TaskEntry, uint * ptaskid); ptaskname Pointer to a C string containing the name under which the task is to be cataloged. If this pointer = NULL, the task is not cataloged. TaskStackSize Size of requested stack in words (32 bit). Priority Task priority (0..255) TaskEntry Entry point address of the task ptaskid Pointer of the task ID This call announces tasks to the operating system. A TCD is automatically created internally from the specified parameters and is used to register the task with the operating system. The task is switched from the NON-EXISTENT state to the DORMANT state. The task is automatically cataloged under the specified name. ID dec 0 RM_OK successfully completed. 42 Programming Manual, 07/2012, A5E

43 RMOS3 s 2.17 RmCreateTask Error codes ID dec Error code 3 RM_OUT_OF_MEMORY Insufficient memory to create stack segment or catalog had insufficient memory. 23 RM_RESOURCE_NOT_AVAILABLE Maximum number of tasks is exceeded. 38 RM_INVALID_SIZE The specified length of stack was 0 or 1G 100 RM_CATALOG_EXCEEDED Catalog capacity is exceeded (see RmCatalog). 37 RM_INVALID_STRING Invalid string length. It is either zero or greater than RM_IS_ALREADY_CATALOGED The specified string is already cataloged. The string must be unique. For this reason, a string cannot be cataloged more than once. 60 RM_INVALID_TASK_ENTRY Invalid entry point address for the task. 42 RM_INVALID_POINTER The pointer to the string is invalid, or would cause an access violation. RmCreateChildTask (Page 31) RmCreateTaskEx (Page 44) RmDeleteTask (Page 56) xinitt (Page 438) Programming Manual, 07/2012, A5E

44 RMOS3 s 2.18 RmCreateTaskEx 2.18 RmCreateTaskEx Register task with the operating system #include <rmapi.h> int RmCreateTaskEx( char *ptaskname, RmTCDStruct *ptcd, uint *ptaskid); ptaskname ptcd ptaskid Pointer to a C string containing the name under which the task is to be cataloged. If this pointer = NULL, the task is not cataloged. Pointer to a structure of type RmTCDStruct Pointer to the returned task ID RmCreateTaskEx changes the state of a dynamic task from NON-EXISTENT to DORMANT. The structure of the RmTCDStruct type must have been previously initialized. The structure corresponds to the TCD block of a task. The structure is no longer required after the call. The task is then always accessed via the returned task ID. The task is automatically cataloged under the specified name. You specify in the task flags (TCD.flags) if the characteristics of the task (see RmCreateChildTask) should be inherited with RM_TFL_CHILD to the generated task. The stack and data segment can be automatically created when a task is created. The memory for the stack and data segment must be taken from a pool (HEAP) for this purpose. The respective stack and data segments of the task are released automatically when the task is deleted. Whether the stack and/or data segment should be created automatically is defined in the task flags (TCD.FLAGS) (see System Manual chapter " of Task Control Data (TCD)"). If the RM_TFL_STK flag is set, the length of the stack must be stored in TCD.ESP in words (32 bit). If the RM_TFL_STK flag is not set, the start address of the stack must be stored in TCD.SS und TCD.ESP. If the RM_TFL_DS flag is set, the length of the data segment must be stored in TCD.DS. For high-level language tasks compiled with the COMPACT model, TCD.DS must be preset with the data segment of the task to be created if RM_TFL_DS is not set. TCD.DS does not need to be preset when compiling with the LARGE model. Because TCD.DS is a 16-bit value, the length of data segments is restricted to 64 kbyte. To enable automatic stack allocation when creating a task with RmCreateTaskEx (see configuration in System Manual), you must indicate the desired stack size using the following instruction: 44 Programming Manual, 07/2012, A5E

45 RMOS3 s 2.18 RmCreateTaskEx In the segmented model TCD.stck = buildptr(0,(void near *)<stacksize>); Example for stack size 2048: TCD.stck = buildptr(0,(void near *)2048); In the FLAT model TCD.stck = (char *) <stacksize>; Example for stack size 2048: TCD.stck = (char *) 2048; Note The maximum number of dynamic tasks depends on the configuration and is equal to half the number of configured SMRs (X_TASK_NUM) in SWNUC.INC. ID dec 0 RM_OK *ptaskid contains valid task ID Error codes ID dec Error code 2 RM_PARAMETER_ERROR Flag RM_TFL_DS may not be set for flat calls. 3 RM_OUT_OF_MEMORY Insufficient memory for creating stack segment or the catalog is full. 23 RM_RESOURCE_NOT_AVAILABLE Maximum number of tasks is exceeded. 38 RM_INVALID_SIZE The stack length size was RM_CATALOG_EXCEEDED Catalog capacity is exceeded (see RmCatalog). 37 RM_INVALID_STRING Invalid string length. The specified length was either zero or greater than RM_IS_ALREADY_CATALOGED The specified string is already cataloged. The string must be unique. For this reason, a string cannot be cataloged more than once. 60 RM_INVALID_TASK_ENTRY Invalid entry point address for the task. 42 RM_INVALID_POINTER The pointer to the string is invalid, or would cause an access violation. Programming Manual, 07/2012, A5E

46 RMOS3 s 2.18 RmCreateTaskEx System configuration RmCreateChildTask (Page 31) RmCreateTask (Page 42) RmDeleteTask (Page 56) 46 Programming Manual, 07/2012, A5E

47 RMOS3 s 2.19 RmCreateUnit 2.19 RmCreateUnit Register unit with the operating system #include <rmapi.h> int RmCreateUnit ( char * pdevicename, char * punitname, RmUCDStruct *pucd, uint *punitid); pdevicename punitname pucd Pointer to a C string containing the name under which the driver was cataloged. Pointer to C string containing the name under which the unit is to be cataloged. If this pointer = NULL, the unit is not cataloged. In this case the driver should have cataloged the unit itself. Pointer to a structure of type RmUCDStruct which is defined as follows: punitid typedef struct _RmUCDStruct { uchar pid; uchar intno; rmfarproc intadr; ushort uns; #if RM3 uchar port[256 10]; #else uchar port[128 8]; #endif }RmUCDStruct; Return of the unit ID This call is used to announce units for a driver to the operating system. During the configuration phase the initialization is only performed with the call RmRunOS(). During runtime operation the initialization is performed immediately. An output function for system messages can be delivered in the UCD entry UCD.INTADR for each RIO byte driver. In this case the UCD entry UCD.INTNO must be set to 0. If the system console is changed with RmSetOS(), the corresponding Putchar function is also installed. When a unit is created, the number N of contiguous UCBs can be specified in UCD.PID bit 0 to 5. The UCBs of the following N RmCreateUnit calls are then stored contiguously. This is required for the drivers with block The interrupt driver handlers are installed with the call RmSetDeviceHandler. Note This function cannot be used with the flat memory model. Programming Manual, 07/2012, A5E

48 RMOS3 s 2.19 RmCreateUnit ID dec 0 RM_OK successfully completed Error codes ID dec Error code 3 RM_OUT_OF_MEMORY Insufficient memory for creating internal data structures or catalog had insufficient memory. 100 RM_CATALOG_EXCEEDED Catalog capacity is exceeded (see RmCatalog). 37 RM_INVALID_STRING Invalid string length. The specified length was either zero or greater than RM_IS_ALREADY_CATALOGED The specified string is already cataloged. The string must be unique. For this reason, a string cannot be cataloged more than once. 42 RM_INVALID_POINTER The pointer to the string is invalid, or would cause an access violation. 21 RM_INVALID_SELECTOR Invalid selector was used. 48 RM_IS_NOT_CATALOGED The driver is not cataloged with pdevicename. RmCreateDriver (Page 34) 48 Programming Manual, 07/2012, A5E

49 RMOS3 s 2.20 RmDecode 2.20 RmDecode Decode RMOS3 code number #include <rmapi.h> int RmDecode ( uint CodeType, int Code, char *ptext) ; CodeType Code ptext Code type Code number Pointer to buffer for return of text The call decodes the specified RMOS3 code number and returns a C string containing a plain text message to the specified buffer. RM_MAXDECODELEN specifies the minimum buffer size. The code type specifies the type of decoding operation: RM_SVCERROR (1) SVC error number RM_SVCNAME (2) SVC function number for SVC name If the code cannot be converted to a string, a NULL string is returned. ID dec 0 RM_OK successfully completed -265 RM_ERROR_OUT_OF_RANGE No text is available for specified code. Error codes ID dec Error code 33 RM_SVC_NOT_CONFIGURED SVC RmDecode() is not available 42 RM_INVALID_POINTER The pointer passed did not point to a permitted memory area. 35 RM_INVALID_TYPE Invalid CodeType. Programming Manual, 07/2012, A5E

50 RMOS3 s 2.21 RmDeleteBinSemaphore 2.21 RmDeleteBinSemaphore Delete dynamic semaphore #include <rmapi.h> int RmDeleteBinSemaphore(uint SemaphoreID); SemaphoreID Semaphore ID RmDeleteBinSemaphore deletes a dynamic semaphore defined with RmCreateBinSemaphore. The SemaphoreID parameter specifies the ID of the semaphore to be deleted. If a catalog entry was generated, it is deleted again. ID dec 0 RM_OK SVC successfully completed Error codes ID dec Error code 36 RM_INVALID_ID Invalid ID passed. 18 RM_RESOURCE_BUSY The semaphore is still in possession of a task. RmCreateBinSemaphore (Page 29) RmGetBinSemaphore (Page 66) RmReleaseBinSemaphore (Page 130) 50 Programming Manual, 07/2012, A5E

51 RMOS3 s 2.22 RmDeleteDescriptor 2.22 RmDeleteDescriptor Delete descriptor #include <rmapi.h> int RmDeleteDescriptor(selector Sel); Sel Valid selector for descriptor RmDeleteDescriptor removes a descriptor specified by the selector from the global descriptor table. Note The descriptor to be deleted is not checked. i.e. if the descriptor specified by Sel is 0, the SVC is successfully completed. This function is not necessary in the FLAT memory model. ID dec 0 RM_OK Selector removed from descriptor table Error codes ID dec Error code 21 RM_INVALID_SELECTOR An invalid selector was used. RmChangeDescriptor (Page 25) RmChangeDescriptorAccess (Page 26) RmCreateDescriptor (Page 33) RmFlatToSegAddress (Page 61) RmGetLinAddress (Page 75) RmGetPhysAddress (Page 80) RmSegToFlatAddress (Page 149) Programming Manual, 07/2012, A5E

52 RMOS3 s 2.23 RmDeleteFlagGrp 2.23 RmDeleteFlagGrp Delete dynamic flag group #include <rmapi.h> int RmDeleteFlagGrp(uint FlagGrpID); FlagGrpID ID of the flag group RmDeleteFlagGrp deletes a dynamic global flag group defined with RmCreateFlagGrp. The FlagGrpID parameter specifies the ID of the flag group to be deleted. If a catalog entry was generated, it is deleted again. ID dec 0 RM_OK SVC successfully completed Error codes ID dec Error code 36 RM_INVALID_ID Flag group = 0 or invalid ID 18 RM_RESOURCE_BUSY Tasks are still waiting for flags of this flag group (SVC RmGetFlag) to be set, or an SVC RmSetFlagDelayed is still active. RmCreateFlagGrp (Page 36) RmGetFlag (Page 70) 52 Programming Manual, 07/2012, A5E

53 RMOS3 s 2.24 RmDelet box 2.24 RmDelet box Delete dynamic mailbox #include <rmapi.h> int RmDelet box(uint MailboxID); MailboxID Mailbox ID RmDelet box deletes a dynamic mailbox defined with RmCreat box. The MailboxID parameter specifies the ID of the mailbox to be deleted. If a catalog entry was generated, it is deleted again. Note If you install an interrupt handler that sends a message to a mailbox, you must uninstall the interrupt handler before you delete the mailbox. ID dec 0 RM_OK SVC successfully completed Error codes ID dec Error code 36 RM_INVALID_ID Invalid ID passed. 18 RM_RESOURCE_BUSY Tasks are still waiting for messages in this mailbox, or the mailbox still contains messages, or an SVC RmSendMailDelayed is still active. RmCreat box (Page 37) RmDeleteTask (Page 56) Programming Manual, 07/2012, A5E