RMOS3 V3.50 System Manual RMOS3. Real-time operating system RMOS3 RMOS3 V3.50 System Manual. About this document.. Configuring the RMOS3 nucleus

Transcription

1 About this document.. 1 Configuring the RMOS3 nucleus 2 RMOS3 Real-time operating system RMOS3 RMOS3 V3.50 System Manual System Manual Driver development 3 System tasks 4 System programs 5 A Abbreviations/Glossary 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 document About this document Notations Configuring the RMOS3 nucleus Introduction RMOS3 operating system components RMOS3 nucleus High-level languages interface APIC driver BYT driver CRT driver COM driver DMA driver RAM-DISK driver Floppy disk driver FD Hard disk driver HD Hard disk driver UDMA HPET driver Network drivers PCI driver Command line interpreter CLI HSFS file management system CRUN C runtime support Low level real-time debugger High-level language debugger Resource reporter Profiler RPROF Exception interrupt handler Arithmetic processor SVC exception handler Relocatable task loader Boot loaders for the operating system Structures and elements of the RMOS3 nucleus Tasks Internal nucleus structures SRB and SMR Drivers and devices Interrupt vectors Memory pools Memory allocation of the RMOS3 nucleus Meaning of the system parameters Meaning of the task control data (TCD) Driver control data (DCD) Unit control data table (UCD) System Manual, 07/2012, A5E

4 Table of contents Interrupt handler of RMOS3 standard drivers Creating interrupt vectors Logging unexpected interrupts Logging incorrect system calls Definition of the I/O directions Drivers in the configurable nucleus EIDE driver TCP/IP connection UDMA support for EIDE drives Messages PCI support by Shared Interrupt Server (SIS) Messages APIC support Messages HPET support Messages Configurable nucleus Booting with the second stage boot loader RMLDR Booting with MS-DOS and RMOS3 load program LOADX Startup messages and system outputs Section [System] Section [RMOS] Section [HSFS] Section [SCANDISK] Section [CPU] General keys Examples Section [TCP] RMOS3 parameters Memory requirements of RMOS3 data structures Number of system resources Driver development What is a driver? Driver tasks Driver initialization Processing driver requests Interrupt processing in drivers Timeout monitoring in the driver Completing an I/O operation Data structures Driver control data (DCD) Driver control block (DCB) Unit control data table (UCD) Unit control block (UCB) I/O request block (IRB) Timer monitor block (TMB) Link of data structures Operating system support for drivers System Manual, 07/2012, A5E

5 Table of contents Driver subprograms System variables for parameter transfer Differences between type I and type II drivers Notes on driver implementation Data and stack environments of driver programs Resetting/Initializing units Creating and deleting device drivers Initiating SVC RmIO Handling the SVC RmIO for type I drivers Handling of SVC RmIO by type II drivers Interrupt handling by RMOS3 standard drivers Timeout processing I/O termination for drivers Operation of a unit by several drivers Summary RMOS3 compliant interrupt handlers System tasks Command Line Interpreter CLI operation Redirecting input and output data Naming conventions Notes on the support for long file names (VFAT16 or VFAT32) Notes on HSFS and on using volumes Debugger Task-and monitor operating modes General notes on operation RMOS3 operating environment of the debugger Operating the debugger Task processing Debugger start Debugger-I/O interface x_d_rio General syntax rules Detailed command syntax Command scope of the debugger Error messages of the debugger Resource reporter General notes on operation RMOS3 support Operating resource reporter Parameter settings with pointers to a structure Error messages of resource reporter Exception Interrupt Handler Real-time capability Design and function On-screen output Non-Maskable Interrupt Product package Modifying the Exception Interrupt Handler System Manual, 07/2012, A5E

6 Table of contents 4.5 Busy task Utility programs for HSFS HSFS terminology and definitions Data volume names File names File attributes HSFS requirements for device drivers Processing requests to the file management system Internal organization of the HSFS Volume structure Maximum file and volume lengths Format data structures Organization of directory entries System programs for HSFS System programs Introduction RDISK.EXE (Error) messages of RDISK.EXE RDISK32.EXE VERS.EXE LOADER Error messages RMLDR, RMLDRFAT.16, RMLDRFAT Installing the second stage boot loader RMLDR LOADX.EXE BLOWUP SYSCOPY.EXE SYSCOPY32.EXE A Abbreviations/Glossary Index System Manual, 07/2012, A5E

7 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 Table 2-1 Number of SMR blocks required Table 2-2 Overview of SVC entry points Table 2-3 TCD block structure Table 2-4 Meaning of the task flags Table 2-5 DCD block structure Table 2-6 Meaning of the driver flags Table 2-7 UCD block structure Table 2-8 Organization of the stack when SVC returns a value unequal to Table 2-9 Section [System] Table 2-10 Section [RMOS] Table 2-11 Section [HSFS] Table 2-12 Section [SCANDISK] Table 2-13 Section [CPU], general keys Table 2-14 Section [CPU], COM A interface with BYT driver Table 2-15 Section [CPU], COM A interface with 3964R driver Table 2-16 Section [TCP] Table 2-17 Memory requirements of RMOS3 data structures Table 2-18 System resources Table 3-1 Parameters of SVC RmIO Table 3-2 DCD block Table 3-3 DCB Table 3-4 UCD block Table 3-5 UCB block Table 3-6 IRB block Table 3-7 TMB block Table 3-8 Driver functions for assembler routines Table 3-9 Driver functions for assembler and C routines Table 3-10 System variables Table 4-1 EAX and EBX parameters at the start of the debugger Table 4-2 Argument definitions for addresses Table 4-3 Argument entries for expressions System Manual, 07/2012, A5E

8 Table of contents Table 4-4 Argument entries for formatting Table 4-5 Argument entries for breakpoints Table 4-6 Parameter structure of resource reporter Table 4-7 Coding of parameter analyze_type Table 4-8 Coding of the restart parameter Table 4-9 Resource reporter table Table 4-10 Structure of the Exception Interrupt Handler Table 4-11 Functions of mass storage device drivers Table 4-12 Parameters Table 4-13 Completion status indicators Table 4-14 Structure of a mass storage unit Table 4-15 Structure of a directory entry Figures Figure 3-1 Call environment of driver programs Figure 3-2 Serial driver (one controller for several units) Figure 3-3 Parallel driver (one controller per unit) Figure 3-4 System processes Figure 3-5 System processes and interrupt handling Figure 3-6 Example of the interaction between an interrupt handler and a task Figure 3-7 Flow chart for a task that needs an interrupt handler Figure 3-8 Example of an interrupt handler that supports a task Figure 4-1 Task mode and monitor mode of the RMOS3 debugger System Manual, 07/2012, A5E

9 About this document About this document.. Overview This System Manual covers all aspects of the configuration of the RMOS3 nucleus. The major part of the information was prepared in tabular format that highlights the function principle of RMOS3 and facilitates system customization to suit your specific requirements. Moreover, the manual contains the description of the interfaces to the Human Machine Interface. That specific section provides you with notes on operating the RMOS3 system. Chapter 1 This chapter offers you a documentation guideline and explains the notations employed in the manual. Chapter 2 Starting with an overview of the structure and configuration of an RMOS3 nucleus, "Configuring the RMOS3 nucleus (Page 13)" shows you how you can adapt the nucleus to the hardware situation on the basis of the RMOS3 nucleus versions included in your package. Chapter 3 Chapter "Driver development (Page 61)" describes the structure of an RMOS3 driver. This chapter assists experienced programmers in programming an RMOS3 driver. Chapter 4 Chapter "System tasks (Page 101)" provides an overview of the handling of the utility programs that facilitate your work with RMOS3. Chapter 5 Chapter "System programs (Page 143)" contains the description of the tools used for the nucleus and application, as well as the boot loaders for the RMOS3 nucleus. System Manual, 07/2012, A5E

10 About this document 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 Meaning Text passage cfg configurable System calls uintmax maximum unsigned integer (FFFF FFFFH) System calls dp data pointer (sel:off) 48-bit pointer System calls 10 System Manual, 07/2012, A5E

11 About this document 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. System Manual, 07/2012, A5E

12 About this document Notations 12 System Manual, 07/2012, A5E

13 Configuring the RMOS3 nucleus Introduction RMOS3 contains a multifunctional operating system nucleus. This configurable nucleus contains numerous module drivers that can be assigned parameters by means of an ASCII configuration file during the startup phase of the operating system. This means that you can dispense with creation of your own operating system nucleus and start immediately with application programming on the basis of a robust, maintained operating system. For information on this configurable nucleus, refer to chapter "Configurable nucleus (Page 38)". Chapters "RMOS3 operating system components (Page 13)" and "Structures and elements of the RMOS3 nucleus (Page 21)" provide an overview of the components, elements and structures of the RMOS3 operating system. Moreover, a selection of RMOS3 parameters is provided at the end of this chapter. 2.2 RMOS3 operating system components Overview RMOS3 has a modular structure. In the course of configuration, you define the components to be used for an RMOS3 system and the scope of performance of these components. The following sections provides a description of the various components and their possible scope of performance RMOS3 nucleus Priority controlled multitasking and multiprocessing with preemptive scheduling Round Robin counters for CPU allocation based on the time sharing method Task management (maximum number of tasks depending on available memory space) Task synchronization by means of event flag groups Task communication via priority controlled mailboxes Task communication by means of messages Resource management by means of binary semaphores Memory management using memory pools Time management Hooks, functions for customer-specific expansions of the nucleus Interrupt controlled driver interface Symbolic resource management Startup messages System Manual, 07/2012, A5E

14 Configuring the RMOS3 nucleus 2.2 RMOS3 operating system components High-level languages interface SVC language interfaces for GNU compilers, as well as compilers of Intel, CAD-UL and Borland (not for new applications) Task and nucleus linking by means of software interrupt Customizable for any compiler (parameter sequence on stack, compiler syntax); delivered in source code Upwards compatible with regard to RMOS3 SVCs APIC driver Switching from PIC mode to APIC mode Activation of multiprocessor support Suitable for all processors of the latest generation 24 interrupt lines are supported (IRQ0 to IRQ23) Accelerated interrupt processing in APIC mode (reduced interrupt sharing and accelerated access) BYT driver Universal I/O driver for character-oriented I/O devices: Terminals, data display stations, keyboards, printers, IBM PC/XT/AT with terminal emulation Configurable: e.g. for UART blocks (8255, 8530, 8250), EGA (text mode) Transmission rate depending on the CPU, UART,... Supports 255 terminal devices with different parameter assignment Handshake: XON/XOFF History buffer Commands: read, write, reserve, release, CRT driver Universal I/O driver for ASCII oriented I/O devices: terminals, data display stations, keyboards, printers, simple host to host communication Driver template for user-specific developments Delivery in source code (Assembler) Configurable: e.g. for UART block 8250 Supports 255 terminal devices with different parameter assignment Commands: read, write, reserve, release, System Manual, 07/2012, A5E

15 Configuring the RMOS3 nucleus 2.2 RMOS3 operating system components COM driver I/O driver for host to host communication using the 3964(R) protocol Configurable: e.g. for UART blocks 8250, 8530 Supports 255 terminal devices with different parameter assignment Commands: read, write, reserve, release, DMA driver Management of DMA control blocks or DMA control of an 80186/188 CPU and PC hardware RAM-DISK driver Manages a RAM area similar to a block-oriented device Memory is requested from the HEAP. Locks itself if configuration errors are found A type II driver sample in C source code is included in the scope of delivery Operations: Reserving and releasing RAM DISK Reading/writing one or several logic blocks Reading/redefining RAM DISK operating parameters Floppy disk driver FD0 Control by means of PC/AT compatible floppy controller Supports 3.5" drives with maximum 1.44 MB floppy disk (high capacity) Automatic detection of the drives (PC) by means of configuration routine in the RMCONF.C file. Management of up to two floppy disk drives Interprets the IBM AT register set for the controller Operations: Reserving or releasing a floppy disk drive Reading/writing one or several logic blocks Formatting floppy disks Positioning the read/write head onto a track Reading/deleting/redefining floppy disk operating parameters System Manual, 07/2012, A5E

16 Configuring the RMOS3 nucleus 2.2 RMOS3 operating system components Hard disk driver HD0 Supports EIDE hard disks to ATA standard. Support for the LBA mode Support for 32-bit data transfer Support for 2 EIDE controllers (Primary Channel and Secondary Channel) Drive parameters can be set by means of configuration data (permanent setting) and using the RmCreateUnit function (dynamic setting). The BIOS EPROM routines are used for initialization. Operations: Reserving or releasing a hard disk drive Reading/writing one or several logic blocks Reading/deleting/redefining hard disk operating parameters Hard disk driver UDMA Supports EIDE hard disks to ATA standard. Support for the LBA mode Support for 32-bit data transfer Support for 2 EIDE controllers (Primary Channel and Secondary Channel) Drivers can be reloaded using RMOS.INI Reserving or releasing a hard disk drive Reading/writing one or several logic blocks HPET driver High Precision Event Timer that can be reloaded Using timer 0 for the operating system clock rate Network drivers Reloadable TCP/IP stack and network adapter drivers TCP/IP utilities: FTP, server and client TELNET, server and client 16 System Manual, 07/2012, A5E

17 Configuring the RMOS3 nucleus 2.2 RMOS3 operating system components PCI driver Reloadable Shared Interrupt Server for managing level-triggered interrupts on the PCI bus Shared Interrupt Client as interface between the user application and the Shared Interrupt Server. The client provides the option of installing and deleting interrupt service routines in the server. PCI scanner for identifying the resources of individual or of all modules on the PCI bus Command line interpreter CLI RMOS3 user interface similar to MS DOS Multitasking capability, which means that background jobs are managed and several CLIs are almost capable of running in parallel Redirecting input and output data Wildcards may be used in the search criteria Differentiation between inline and reloadable commands Finding and executing a reloadable command by means of preset search path (PATH) Command line parameter are transferred to commands in standard C format (argc/argv) You may create new commands A function interface allows you to integrate essential CLI capabilities in commands Command procedures (batch files) can be processed (in the background, as well) Reloadable commands and programs can be canceled both in the foreground (with <Ctrl>+<C>) and in the background (CANCEL command) HSFS file management system Format compatible with MS DOS as of V2.11 Support for FAT12, FAT16, FAT32, VFAT16, and VFAT32 Hierarchic file management system with the elements main directory, subdirectory and file HSFS is capable of managing I/O devices by means of device driver files. This means that the devices are treated as files and the major part of the HSFS operations can be used without changes for these I/O devices Multitasking capability, which means that tasks can use the HSFS for quasi parallel access to data volumes, directories, or files System Manual, 07/2012, A5E

18 Configuring the RMOS3 nucleus 2.2 RMOS3 operating system components Hardware independence, meaning that a data volume is not controlled directly from the HSFS, but rather by means of RMOS3 device driver. The calling interface is defined. Internal data buffer of configurable length for increasing performance, with operation based on the LRU strategy (Least Recently Used) Defined call interface for integration of network tasks The data volume has a maximum capacity of 32 GB per partition Up to 128 GB can be managed. Files have a maximum length of 4 GB -1 byte CRUN C runtime support C functions in accordance with ISO/IEC DIS 9899, June 1990 (ANSI C) Reentrant and multitasking capable; linked once only to the RMOS3 system Additional functions: Calls similar to UNIX and expansions specific to RMOS3 EPROM capable, i.e. applications can be passed to EPROM for further execution Replaces compiler-specific C Runtime libraries (e.g. for Intel) Modular structure (at least approximately 25 KB, maximum approximately 120 KB); configurable functions Simple porting of software packets on the basis of the ISO/IEC DIS 9899 standard 1990 between RMOS3 and other operating systems Logical preliminary testing using other commonly available C compilers on the PC Floating point operations Software interrupt gate interface (for CAD-UL and Intel) and software interrupt interface (for GNU) for reloadable tasks Low level real-time debugger Low level real-time debugger for debugging and commissioning RMOS3 tasks in task mode, as well as RMOS3 drivers and RMOS3 routines in monitor mode (no real-time response of the remaining system) Dynamic task loading at runtime on the target system by means of HSFS. Starting tasks in DORMANT state, stopping and re-enabling READY or RUNNING tasks Check and disassembly of memory contents and changing the content of RAM areas 15 breakpoints (soft breakpoints) in any task (the interrupt address must be known and exist in RAM), 4 breakpoints (hard breakpoints) in EPROM by means of debug registers All registers can be modified, including CS/EIP, after a task was suspended by means of breakpoint HELP command for low-level debugger 18 System Manual, 07/2012, A5E

19 Configuring the RMOS3 nucleus 2.2 RMOS3 operating system components RMOS3 SVCs (seethe reference manual) can be executed as command BYT driver as software interface to the terminal Operating mode display by means of debugger prompt High-level language debugger The high-level language debugger is part of the RMOS3 GNU product. High-level language debugger rm-gdb (GNU debugger) for command line oriented debugging, or graphic debugging with Eclipse IDE Communication host debugger (rm-gdb) with GNU Debug-Server GDBSrvGn.386 over TCP/IP Symbolic processing with HLL debugger Dynamic task loading at runtime on the target system by means of HSFS. Check and disassembly of memory contents and changing the content of RAM areas 15 breakpoints (soft breakpoints) in any task (the interrupt address must be known and exist in RAM), 4 breakpoints (hard breakpoints) in EPROM by means of debug registers All registers can be modified, including CS/EIP, after a task was suspended by means of breakpoint Resource reporter Test tool in addition to the real-time debugger Evaluation and display of the current state of resources (tasks, mailboxes, semaphores, memory pools, event flag groups,... ) Evaluation in short or long version Configured as task in the application example Can be called in the debugger using the rep command Profiler RPROF Reloadable by means of CLI Menu controlled operation Determine... System parameters System load Task activities Interrupt latencies System Manual, 07/2012, A5E

20 Configuring the RMOS3 nucleus 2.2 RMOS3 operating system components Exception interrupt handler Logs exception interrupts of the processor at the system console. Also supplied as source code for customization Arithmetic processor Can be used simultaneously by several tasks Emulation is possible SVC exception handler Logs all SVC calls that were not completed with return value RM_OK at the system console. Messages can be suppressed explicitly using RmSetOS Relocatable task loader Dynamic task loading at runtime by means of mass storage access on the target system. Supported file formats: OMF386 loadable format, equivalent to STL (Single Task Loadable) Load Time Locatable (LTL) format Windows NT format PE (portable executable) GNU ELF format Boot loaders for the operating system RMOS3 boot loader for loading the operating system nucleus of a length less than 608 KB below the adapter gap of CPU memory address space Second stage boot loader RMLDR for loading the operating system nucleus above 1 MB of CPU memory address space Boot loader LOADX for loading the operating system nucleus in MS-DOS mode 20 System Manual, 07/2012, A5E

21 Configuring the RMOS3 nucleus 2.3 Structures and elements of the RMOS3 nucleus 2.3 Structures and elements of the RMOS3 nucleus Tasks Every application system contains one or several static and/or dynamic tasks. The TCD block for a dynamic task is always generated by a system call at runtime and can be killed again by a second system call. The task ID is also assigned or released in this process. There is no other difference between dynamic and static tasks. The tasks can be named and be identified by their name in the catalog entry. A task can also be identified by its ID Internal nucleus structures SRB and SMR SRB An SRB (System Request Blocks) represents a management table of the nucleus. The SRB entries are used for runtime management by the nucleus and to resume interrupt processing in S state. The nucleus allocates and initializes an SRB at each transition of an interrupt handler from the DI or I state to the S state and writes it as last entry to the SRB queue. RMOS3 processes this queue of internal processes based on the order of their generation. The SRB is released again on completion of the process. The default number of SRBs is specified in the INC\SWNUC.INC file as X_SRB_NUM. RMOS3 needs at least 32 SRBs. If an interrupt handler requests transition to the S state while no SRB is available, the system will crash because the interrupt handler cannot exit the DI or I state. This means that it is always necessary to provide an appropriate number of SRB blocks. The maximum number of SRBs depends on interrupt load and memory space. 500 SRBs are sufficient for PC hardware. SMR An SMR block (System Memory Resource) is a dynamic data structure that is used in RMOS3 for internal management tasks. The number of SMRs to be configured depends on the number of simultaneously active system calls. Each system call needs a specific number of SMR blocks. The start value for the number of SMRs (at least 50) is specified in the SWNUC.INC file as X_TASK_NUM. Each SMR block occupies 72 bytes in global RAM. Memory is allocated from the HEAP. The nucleus automatically increases the number of available SMRS. The number of SMRs can be limited by corresponding settings in the RMOS.INI file. System Manual, 07/2012, A5E

22 Configuring the RMOS3 nucleus 2.3 Structures and elements of the RMOS3 nucleus The system releases SMR blocks again if these are no longer required. Missing SMR blocks may delay execution of system calls (SMRs are increased automatically), or the system freezes (upper limit is reached). The system calls need the following number of free SMR blocks to enable their execution without delay in RMOS3: Table 2-1 Number of SMR blocks required SVC Number Using the blocks RmStartTask 1 RCB (Restart Control Block) for the target task; released when the target task outputs RmEndTask. RmQueueStartTask 1 See RmStartTask RmRestartTask 1 For TMB (Timer Monitor Block); released when the task is returned to READY state. RmPauseTask 1 For TMB; released when the task is returned to READY state (time expired or RmResumeTask). RmSetFlagDelayed 1 For TMB; released on expiration of the delay time. RmGetFlag 1 For EWB (Event Flag Wait Block); released if waiting conditions are fulfilled. RmSendMail 1 For MMB (Mailed Message Block); released after the message was received (RmReceiv ). RmReceiv 1 For MMB; released after a message was retrieved, or if no "wait for message" was specified in the system call. RmAlloc 1 For PWB (Pool Wait Block); released when memory is available, or no "wait for memory space" was specified in the system call. RmIO 2 For IRB (I/O Request Block) and driver MB; released on completion of request processing. RmGetBinSemaphore 2 For SWB (Semaphore Wait Block) and TMB; SWB is released as soon as semaphore is available, or a timer is active and automatic time management is installed for the requesting task. DBGSVC 1 For BPB (Breakpoint Block); released after the breakpoint is cleared. RmCreateTask 3 For TCB and TCD; released as soon as the task is killed; in specific situations for TMB that raises the priority level if RM_TFL_OVPRI is set in TCD.FLAGS. RmGetEntry 1 For DWB (Directory Wait Block) if "wait for entry" was specified and the entry is not available. Released again after the entry was made, or on overflow of the index. RmSendMailDelayed 2 For TIB and TMB; released with RmSendMailCancel, or on timeout 22 System Manual, 07/2012, A5E

23 Configuring the RMOS3 nucleus 2.3 Structures and elements of the RMOS3 nucleus Drivers and devices A DCD block and at least one UCD block must be available for each device driver. Those blocks are created in tables by means of the RmCreateDriver and RmCreateUnit configuration functions. The call order determines the driver ID. The device ID, namely the Unit ID, is derived from the call order. You may assign the system console to a different driver and different unit by executing RmSetOS Interrupt vectors RMOS3 allows the processing of interrupts that are not linked to a device driver. These include: division by zero, single step (TRAP), non-maskable interrupt (NMI), breakpoint, overflow, call gates, and the interrupt generated by the system timer. The position of the device interrupt vectors is specified by initialization of the interrupt control block. It is possible to configure the assignment of interrupts to the vectors. In doing so, the following restrictions must be observed: 1. The interrupts 0 to 31 may only be used as exception interrupts of the 80386/80486 processors. The single step and INT3 interrupts are also used by the debugger. The debugger retrieves and restores the original vectors if a breakpoint is set, or if no breakpoint exists. 2. Hardware interrupts cannot be treated as software interrupts. 3. Unused interrupt entry points are assigned the interrupt handler for unexpected entries. 4. This default setting can be prevented using the RmReserveInterrupt function Memory pools RMOS3 manages the entire RAM space above 1 MB as specified in configuration data as a single memory pool, namely the HEAP. Memory space is calculated automatically during system startup. Tasks or drivers can allocate memory space they need from the HEAP. For reasons of downwards compatibility it is still possible to use SVCs to create additional memory pools. However, this method should no longer be used for new development. System Manual, 07/2012, A5E

24 Configuring the RMOS3 nucleus 2.3 Structures and elements of the RMOS3 nucleus Memory allocation of the RMOS3 nucleus The memory requirement of the RMOS3 nucleus is split into two areas: 1. ROM (RM3_CODE32) Contains the code and constants that belong to the operating system (nucleus, driver, configuration tables) 2. RAM (RM3_DATA) Contains the data and stack of the operating system Meaning of the system parameters SVC vector The SVC vector describes the central entry point for SVC calls. All SVC calls trigger one of three interrupts by means of call gates. The SVC vector represents the lowest of these three interrupts. It has a value between 32 and 254. The specific interrupt to trigger is determined by the SVC type: Table 2-2 Overview of SVC entry points Type of the SVC call Vector number TYP3 (flat API) SVC vector TYP2 (RMOS2) SVC vector +1 TYP1 (RMOS3 API) SVC vector +2 RMOS3 stack The stack length of the nucleus is set to 4096 bytes. Stack requirement is calculated as follows: 16 words per software interrupt (SVC entry, or processor exception INT0, INT4...). 16 words for NMI 16 words per hardware interrupt. RMOS3 itself needs approximately 40 words. Maximum driver stack needed in DI, I or S state (containing 25 words for the driver subroutines and the actual memory requirements of the driver). 24 System Manual, 07/2012, A5E

25 Configuring the RMOS3 nucleus 2.3 Structures and elements of the RMOS3 nucleus Meaning of the task control data (TCD) Each static task in the system needs a TCD block (Task Control Data) that contains all constants for task management by the nucleus. The TCD blocks are created by means of RmCreateTask function call. Table 2-3 TCD block structure Parameters Offset Type Description EAX 0H uint first stack parameter EBX 4H uint second stack parameter DS 8H ushort The DS start value of the task or data segment length in bytes for automatic creation of the data segment (RM_TFL_DS); the data segment may have a maximum length of 64 KB because TCD.DS is a 16 bit value ES AH ushort Task start value STCK CH void* Stack pointer start value (SS:ESP) TASK 12H rmfarproc Task start value LOAD 18H void* reserved TIME 1EH ushort task-related timeout OVPRI 20H uchar Increment of automatic increase of the priority level BPRI 21H uchar Limit of automatic increase of the priority level INPRI 22H ushort Original task priority FLAGS 24H ushort Task flags: Bit 0 RM_TFL_NPX (1H) Task uses NPX Bit 1 Reserved, must be 0 Bit 2 RM_TFL_NOHLT (4H) Task cannot be stopped Bit 3 RM_TFL_OVPRI (8H) automatic increase of the priority level Bits Reserved, must be 0 Bit 8 RM_TFL_STK (100H) = 1: automatic stack creation Bit 9 RM_TFL_DS (200H) = 1: Automatic creation of the data segment Bit Reserved (0) RR_TICKS 26H ushort task-specific Round Robin counter EFG 28H uint[2] Local event flag RESERVE 30H uchar[4] 4 bytes are reserved SEQ 34H uint ID of the task started after completion TASKID 38H ushort Task ID RESERVED 3AH ushort 2 bytes are reserved SYSESP 3CH uint System stack NPX 40H void* Near pointer to NPX data System Manual, 07/2012, A5E

26 Configuring the RMOS3 nucleus 2.3 Structures and elements of the RMOS3 nucleus 1. Stack parameters (TCD.AX,TCD.BX, TCD.EAX,TCD.EBX ) The operating system writes these values of the task stack at the start of the task. 2. Data segment (TCD.DS) Start value of the data segment register (DS) of the task. A segment declaration can be used for external definition of the segment. A task may always change the data segment register during execution. However, TCD.DS is written to the data segment register at each restart of a task. TCD.DS must be declared if a high-level language task was compiled with COMPACT. TCD.DS defines the length of the data segment in bytes during automatic creation of the data segment (RM_TFL_DS). The data segment may have a maximum length of 64 KB because TCD.DS is a 16 bit value. 3. Extra segment (TCD.ES) Start value of the extra segment register (ES) of the task if necessary. 4. Stack pointer and stack segment register (TCD.STCK) Start value of the stack pointer (SPESP) and stack segment register (SS) of the task. Only the length of the stack segment must be defined at the function call. TCD.ESP defines the stacks length in 32 bit words during automatic creation of the stack. 5. Entry address (TCD.IP, TCD.EIP and TCD.CS) The task start address is a pointer of type FAR (offset TCD.EIP and segment TCD.CS) and must be declared externally. CS/EIP is occupied with the address of the specified procedure. 6. Task-related timeout (TCD.TIME) The TCD timeout is activated in response to the following situation: If the task is still in BLOCKED, READY, or RUNNING state on expiration of the time interval specified in TCD.TIME, the task priority is raised automatically by the value defined in TCD.OVPRI if the TCD.BPRI limit was not yet reached. The timeout is started at the task start and whenever the task has automatically raised its priority. TCD priority monitoring is specified in parameter TCD.FLAGS. The TCD timeout interval consists of 2 parameters: Byte 0: time interval from milliseconds to hours (see SVC RmPauseTask). The values for a time interval are entered with multiplication factor 4. Byte 1: number of time intervals (0 to 255) 7. Increment for automatic priority increase (TCD.OVPRI) This byte specifies the priority increment that is added to the current priority of the task on expiration of TCD.TIME and if RM_TFL_OVPRI is set. 8. Limit for automatic priority increase (TCD.BPRI) This byte specifies the limit up to which the priority is increased automatically. 26 System Manual, 07/2012, A5E

27 Configuring the RMOS3 nucleus 2.3 Structures and elements of the RMOS3 nucleus 9. Initial priority (TCD.INPRI) This 16-bit value specifies the initial priority, or the permanent priority of a task before it is changed. The priority ranges between zero (lowest priority) and 255 (top priority). 10.Task flags (TCD.FLAGS) This value specifies certain task options and conditions (see at the end). 11.Round Robin counter (TCD.RR_TICKS) This parameter is used to set the task-related Round Robin counter. This function is only activated if the task-related Round-Robin was activated (#define RoundRobin RM_RR_TASK in the system configuration, or SVC RmSetOS (RM_RR_TASK)). Task flags: The task flags have the following meaning: Table 2-4 Meaning of the task flags Bit Symbol Function 0 RM_TFL_NPX Task uses a numeric co-processor 1 Reserved, must be 0 2 RM_TFL_NOHLT Task may not be stopped by another task 3 RM_TFL_OVPRI Activates automatic priority increase 4 Reserved, must be 0. 5 Reserved, must be 0. 6 RM_TFL_CHILDTASK inherits stdin, stdout, stderr, current working directory and environment 7 Reserved, must be 0 8 RM_TFL_STK 1: Automatic creation of the stack 9 RM_TFL_DS 1: Automatic creation of the data segment Reserved: Must be 0. System Manual, 07/2012, A5E

28 Configuring the RMOS3 nucleus 2.3 Structures and elements of the RMOS3 nucleus Driver control data (DCD) A DCD (Device Control Data) block is required for each device driver in the system. The DCD block must be created in code segment RM3_CODE32 and published to RMOS3 using the RmCreateDriver function. The DCD contains all constants that RMOS3 needs to integrate the driver. Data structure in the DCD block: Table 2-5 DCD block structure Parameters Type Description UCD RmUCDStruct _NEAR* Reserved UNITS uchar Reserved SHR uchar ID of the second driver that shares a control block INIT rmnearproc Entry point of the initialization routine in the driver SVC rmnearproc RmIO SVC entry point for this driver FLAGS uchar Driver flags: RM_DFL_PARA (1H) Bit 0=0: Serial driver Bit 0=1: Parallel driver RM_DFL_TYPE2 (2H) Bit 1 = 0: Type I driver Bit 1=1 Type II driver RM_DFL_DORMANT (4H) Bit 2=0: Driver initialized after booting Bit 2=1: Driver DORMANT after booting FMAX uchar Maximum function code (only type II) RESERV Ulong 4 reserved bytes 1. ID of the second driver that shares the control block (DCD.SHR) This byte contains the driver ID of the second driver, or 1 (0FFH). This system facility is not supported for type II drivers. 2. Procedure address for driver initialization (DCD.INIT) The procedure is declared externally and called once for each device of the driver. If no initialization is required it is nonetheless necessary to jump to a dummy procedure. The procedure must be available in segment RM3_CODE Entry point for execution of an SVC RmIO (DCD.SVC) For a type I driver, this specifies the procedure address for execution of an SVC RmIO by the driver. For type II drivers, the address of the entry table for execution of the various functions of RmIO is entered. The procedure or jump table must be available in segment RM3_CODE System Manual, 07/2012, A5E

29 Configuring the RMOS3 nucleus 2.3 Structures and elements of the RMOS3 nucleus 4. Driver flags (DCD.FLAGS); see at the end. 5. Maximum function code of the driver (DCD.FMAX) This byte specifies the maximum value of the function code for type II drivers. This number is equivalent to the number of addresses + 1 in the jump table of the driver. DCD.FMAX must be 0 for a type I driver. Driver flags The driver flags have the following meaning: Table 2-6 Meaning of the driver flags Bit Symbol Function 0 RM_DFL_PARA 0 Serial driver 1 Parallel driver 1 RM_DFL_TYPE2 0 Type I driver 1 Type II driver 2 RM_DFL_DORMANT 0 Driver initialization in the boot sequence 1 No driver initialization in the boot sequence (driver DORMANT) Reserved Unit control data table (UCD) One UCD block must be available for each device (unit). UCDs can be created in any memory area. The data is copied to RAM at the call of RmCreateUnit. A device driver is capable of handling between 1 and 255 units with IDs from 0 to 254. The data structure of the driver is linked to the data structures of its units by means of a pointer in the DCB data structure (component DCB.UCB). This is handled internally in the nucleus. Structure of the data in the UCD block: Table 2-7 UCD block structure Parameters Type Description PID uchar Driver type INTNO uchar Number of the interrupt vector for the unit INTR_ADR void* Address of the interrupt handler UNS ushort ID of the task that is started after an unexpected entry (0FFFFH if no task is started) PORT Driver-specific data (246 bytes) System Manual, 07/2012, A5E

30 Configuring the RMOS3 nucleus 2.3 Structures and elements of the RMOS3 nucleus 1. Number of UCDs or UCBs (UCD.PID) Bit : A number N entry specifies that the UCDs or UCBs of the next N calls of RmCreateUnit are written to memory in successive order. Bit 6 and 7: These bits are used to specify whether this is an RIO byte-(rm_riobyte), or an RIO block driver (RM_RIOBLOCK) 2. Number of the interrupt vector (UCD.INTNO) A vector number equal to 0 indicates that no interrupt vector is initialized. Usually, the vectors of a unit are entered in the vector table for non unit interrupts. A value unequal 0 indicates that the unit vector is initialized. If the unit employs several interrupt vectors, the remaining vectors must be entered in the vector table for non unit interrupts, or be built by the driver during initialization. The interrupt vector definition takes priority if an interrupt vector exists twice because it was allocated both in the interrupt vector definition and in the unit definition. 3. Interrupt entry point (UCD.INTADR) The UCD.INTNO vector is initialized by the driver with address UCD.INTADR. If UCD.INTNO = 0, an emergency putchar function can be defined in UCD.INTADR and activated at the changeover of the system console to this unit (cf. RmSetOS, RmSetPutcharProc). 4. Task start after unexpected interrupt This parameter contains the task ID that is started in response to an unexpected interrupt event; otherwise, the parameter is initialized with a 1 value. Note There is no restriction for the "task start after unexpected interrupt". The active task should not execute any processes that are usually handled by the driver. This system facility serves to process exception conditions. A task started by an unexpected input is assigned four data bytes in the EAX and EBX registers. The meaning of these four bytes depends on the driver. Usually, AL contains the driver ID, AH the unit ID, BL the input byte, and BH a zero value. 5. Device-related parameter list (UCD.PORT) You can use these 246 bytes to specify port addresses, operating parameters of the devices, interrupt control data, and similar. 30 System Manual, 07/2012, A5E

31 Configuring the RMOS3 nucleus 2.3 Structures and elements of the RMOS3 nucleus Interrupt handler of RMOS3 standard drivers RMOS3 standard drivers operate their devices with a single interrupt handler. The interrupt handler is installed at the call of RmSetDeviceHandler. There is no direct jump to this handler when an interrupt is triggered. Instead, a short lead-in will handle the changeover to the I state and assign the driver a parameter that points to the UCB block of the triggering unit Creating interrupt vectors Note The interrupt vectors 0 to 31 may only be used for processor exception interrupts Logging unexpected interrupts RMOS3 supports the logging of unexpected interrupts. An exception handler is installed for this purpose. However, this message does not provide any information related to the interrupt number. If interested in the reporting of the interrupt number in the test phase, you can enable this functionality by initially calling the XSET_UNX_INT procedure in the initialization task. All unexpected interrupts are then output with the syntax *** nuc: <date> <time> UNEXPECTED INTERRUPT 0x67. The hexadecimal number returned is equivalent to the interrupt number; in this example IRQ7 of the first interrupt controller. You need to provide at least approximately 2.5 KB of program memory to support this function. If you do not need this function because you want to save memory space, do not set an external reference to this symbol. The source code of this extended handler is available in the UNXINT.ASM file in the SOURCE\ETC\CADUL directory. To enable the use of the enhanced interrupt handler for unexpected interrupts, insert the RcInitExtDefHandler call into the InitTask (RMCONF.C) function Logging incorrect system calls Provided the return value is greater than RM_OK (value: 0), the SVC exception handler is called as soon as a task outputs an SVC. You may replace the SVC exception handler with a customized procedure. This FAR procedure can be installed in any segment. This procedure must be installed in segment RM3_CODE32. The procedure transfers three parameters to the stack, which you need to remove again. The following table highlights the stack organization of the parameters: System Manual, 07/2012, A5E