RMOS3 V3.50 System Manual - Siemens AG V3.50 System Manual System Manual, 07/2012, A5E03692294-01

RMOS3 V3.50 System Manual

___________________

___________________

___________________

___________________

___________________

___________________

RMOS3

Real-time operating system RMOS3 RMOS3 V3.50 System Manual

System Manual

07/2012 A5E03692294-01

About this document . . 1

Configuring the RMOS3 nucleus

2

Driver development 3

System tasks 4

System programs 5

Abbreviations/Glossary A

Siemens AG Industry Sector Postfach 48 48 90026 NÜRNBERG GERMANY

A5E03692294-01 Ⓟ 07/2012 Technical data subject to change

Copyright © Siemens AG 2012. All rights reserved

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:

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.

Trademarks 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.

RMOS3 V3.50 System Manual System Manual, 07/2012, A5E03692294-01 3

Table of contents

1 About this document . . ........................................................................................................................... 9

1.1 About this document . . .................................................................................................................. 9

1.2 Notations ...................................................................................................................................... 10

2 Configuring the RMOS3 nucleus ........................................................................................................... 13

2.1 Introduction .................................................................................................................................. 13

2.2 RMOS3 operating system components ....................................................................................... 13 2.2.1 RMOS3 nucleus ........................................................................................................................... 13 2.2.2 High-level languages interface ..................................................................................................... 14 2.2.3 APIC driver ................................................................................................................................... 14 2.2.4 BYT driver .................................................................................................................................... 14 2.2.5 CRT driver .................................................................................................................................... 14 2.2.6 COM driver ................................................................................................................................... 15 2.2.7 DMA driver ................................................................................................................................... 15 2.2.8 RAM-DISK driver.......................................................................................................................... 15 2.2.9 Floppy disk driver FD0 ................................................................................................................. 15 2.2.10 Hard disk driver HD0 .................................................................................................................... 16 2.2.11 Hard disk driver UDMA ................................................................................................................ 16 2.2.12 HPET driver .................................................................................................................................. 16 2.2.13 Network drivers ............................................................................................................................ 16 2.2.14 PCI driver ..................................................................................................................................... 17 2.2.15 Command line interpreter CLI ...................................................................................................... 17 2.2.16 HSFS file management system ................................................................................................... 17 2.2.17 CRUN C runtime support ............................................................................................................. 18 2.2.18 Low level real-time debugger ....................................................................................................... 18 2.2.19 High-level language debugger ..................................................................................................... 19 2.2.20 Resource reporter ........................................................................................................................ 19 2.2.21 Profiler RPROF ............................................................................................................................ 19 2.2.22 Exception interrupt handler .......................................................................................................... 20 2.2.23 Arithmetic processor .................................................................................................................... 20 2.2.24 SVC exception handler ................................................................................................................ 20 2.2.25 Relocatable task loader ............................................................................................................... 20 2.2.26 Boot loaders for the operating system ......................................................................................... 20

2.3 Structures and elements of the RMOS3 nucleus ......................................................................... 21 2.3.1 Tasks ............................................................................................................................................ 21 2.3.2 Internal nucleus structures SRB and SMR .................................................................................. 21 2.3.3 Drivers and devices ..................................................................................................................... 23 2.3.4 Interrupt vectors ........................................................................................................................... 23 2.3.5 Memory pools ............................................................................................................................... 23 2.3.6 Memory allocation of the RMOS3 nucleus .................................................................................. 24 2.3.7 Meaning of the system parameters.............................................................................................. 24 2.3.8 Meaning of the task control data (TCD) ....................................................................................... 25 2.3.9 Driver control data (DCD) ............................................................................................................ 28 2.3.10 Unit control data table (UCD) ....................................................................................................... 29

Table of contents

RMOS3 V3.50 System Manual 4 System Manual, 07/2012, A5E03692294-01

2.3.11 Interrupt handler of RMOS3 standard drivers ............................................................................. 31 2.3.12 Creating interrupt vectors ............................................................................................................ 31 2.3.13 Logging unexpected interrupts .................................................................................................... 31 2.3.14 Logging incorrect system calls .................................................................................................... 31 2.3.15 Definition of the I/O directions ..................................................................................................... 32

2.4 Drivers in the configurable nucleus ............................................................................................. 33 2.4.1 EIDE driver .................................................................................................................................. 33 2.4.2 TCP/IP connection ...................................................................................................................... 33 2.4.3 UDMA support for EIDE drives ................................................................................................... 34 2.4.3.1 Messages .................................................................................................................................... 34 2.4.4 PCI support by Shared Interrupt Server (SIS) ............................................................................ 34 2.4.4.1 Messages .................................................................................................................................... 35 2.4.5 APIC support ............................................................................................................................... 35 2.4.5.1 Messages .................................................................................................................................... 36 2.4.6 HPET support .............................................................................................................................. 36 2.4.6.1 Messages .................................................................................................................................... 37

2.5 Configurable nucleus .................................................................................................................. 38 2.5.1 Booting with the second stage boot loader RMLDR ................................................................... 39 2.5.2 Booting with MS-DOS and RMOS3 load program LOADX ......................................................... 40 2.5.3 Startup messages and system outputs ....................................................................................... 41 2.5.4 Section [System] ......................................................................................................................... 45 2.5.5 Section [RMOS] .......................................................................................................................... 49 2.5.6 Section [HSFS] ............................................................................................................................ 51 2.5.7 Section [SCANDISK] ................................................................................................................... 52 2.5.8 Section [CPU] .............................................................................................................................. 53 2.5.8.1 General keys ............................................................................................................................... 53 2.5.8.2 Examples..................................................................................................................................... 56 2.5.9 Section [TCP] .............................................................................................................................. 56

2.6 RMOS3 parameters .................................................................................................................... 59 2.6.1 Memory requirements of RMOS3 data structures ...................................................................... 59 2.6.2 Number of system resources ...................................................................................................... 59

3 Driver development ............................................................................................................................... 61

3.1 What is a driver? ......................................................................................................................... 61

3.2 Driver tasks ................................................................................................................................. 63 3.2.1 Driver initialization ....................................................................................................................... 64 3.2.2 Processing driver requests.......................................................................................................... 64 3.2.3 Interrupt processing in drivers ..................................................................................................... 67 3.2.4 Timeout monitoring in the driver ................................................................................................. 68 3.2.5 Completing an I/O operation ....................................................................................................... 68

3.3 Data structures ............................................................................................................................ 69 3.3.1 Driver control data (DCD) ............................................................................................................ 70 3.3.2 Driver control block (DCB) .......................................................................................................... 71 3.3.3 Unit control data table (UCD) ...................................................................................................... 72 3.3.4 Unit control block (UCB) .............................................................................................................. 73 3.3.5 I/O request block (IRB) ................................................................................................................ 74 3.3.6 Timer monitor block (TMB) .......................................................................................................... 75 3.3.7 Link of data structures ................................................................................................................. 76

3.4 Operating system support for drivers .......................................................................................... 78

Table of contents


3.4.1 Driver subprograms ..................................................................................................................... 78 3.4.2 System variables for parameter transfer ...................................................................................... 80 3.4.3 Differences between type I and type II drivers ............................................................................. 81

3.5 Notes on driver implementation ................................................................................................... 83 3.5.1 Data and stack environments of driver programs ........................................................................ 83 3.5.2 Resetting/Initializing units ............................................................................................................ 85 3.5.3 Creating and deleting device drivers ........................................................................................... 86 3.5.4 Initiating SVC RmIO ..................................................................................................................... 87 3.5.4.1 Handling the SVC RmIO for type I drivers ................................................................................... 88 3.5.4.2 Handling of SVC RmIO by type II drivers .................................................................................... 91 3.5.5 Interrupt handling by RMOS3 standard drivers ........................................................................... 93 3.5.6 Timeout processing ...................................................................................................................... 95 3.5.7 I/O termination for drivers ............................................................................................................ 96 3.5.8 Operation of a unit by several drivers .......................................................................................... 98 3.5.9 Summary ...................................................................................................................................... 98 3.5.10 RMOS3 compliant interrupt handlers ........................................................................................... 99

4 System tasks ...................................................................................................................................... 101

4.1 Command Line Interpreter ......................................................................................................... 101 4.1.1 CLI operation .............................................................................................................................. 101 4.1.2 Redirecting input and output data .............................................................................................. 101 4.1.3 Naming conventions .................................................................................................................. 102 4.1.4 Notes on the support for long file names (VFAT16 or VFAT32) ................................................ 103 4.1.5 Notes on HSFS and on using volumes ...................................................................................... 104

4.2 Debugger ................................................................................................................................... 104 4.2.1 Task-and monitor operating modes ........................................................................................... 104 4.2.2 General notes on operation ....................................................................................................... 107 4.2.3 RMOS3 operating environment of the debugger ....................................................................... 107 4.2.4 Operating the debugger ............................................................................................................. 107 4.2.5 Task processing ......................................................................................................................... 108 4.2.6 Debugger start ........................................................................................................................... 108 4.2.7 Debugger-I/O interface x_d_rio .................................................................................................. 109 4.2.8 General syntax rules .................................................................................................................. 109 4.2.9 Detailed command syntax .......................................................................................................... 111 4.2.10 Command scope of the debugger.............................................................................................. 114 4.2.11 Error messages of the debugger ............................................................................................... 115

4.3 Resource reporter ...................................................................................................................... 118 4.3.1 General notes on operation ....................................................................................................... 118 4.3.2 RMOS3 support ......................................................................................................................... 118 4.3.3 Operating resource reporter ....................................................................................................... 118 4.3.4 Parameter settings with pointers to a structure ......................................................................... 119 4.3.5 Error messages of resource reporter ......................................................................................... 124

4.4 Exception Interrupt Handler ....................................................................................................... 125 4.4.1 Real-time capability .................................................................................................................... 125 4.4.2 Design and function ................................................................................................................... 125 4.4.3 On-screen output ....................................................................................................................... 127 4.4.4 Non-Maskable Interrupt ............................................................................................................. 129 4.4.5 Product package ........................................................................................................................ 129 4.4.6 Modifying the Exception Interrupt Handler ................................................................................. 129

Table of contents


4.5 Busy task ................................................................................................................................... 130

4.6 Utility programs for HSFS ......................................................................................................... 130 4.6.1 HSFS terminology and definitions ............................................................................................. 131 4.6.1.1 Data volume names .................................................................................................................. 132 4.6.1.2 File names ................................................................................................................................. 132 4.6.1.3 File attributes ............................................................................................................................. 132 4.6.2 HSFS requirements for device drivers ...................................................................................... 133 4.6.3 Processing requests to the file management system ............................................................... 135 4.6.4 Internal organization of the HSFS ............................................................................................. 136 4.6.5 Volume structure ....................................................................................................................... 138 4.6.5.1 Maximum file and volume lengths ............................................................................................. 139 4.6.5.2 Format data structures .............................................................................................................. 139 4.6.5.3 Organization of directory entries ............................................................................................... 140 4.6.6 System programs for HSFS ...................................................................................................... 141

5 System programs ................................................................................................................................. 143

5.1 Introduction................................................................................................................................ 143

5.2 RDISK.EXE ............................................................................................................................... 143 5.2.1 (Error) messages of RDISK.EXE .............................................................................................. 145

5.3 RDISK32.EXE ........................................................................................................................... 146

5.4 VERS.EXE ................................................................................................................................ 147

5.5 LOADER.386 ............................................................................................................................ 148 5.5.1 Error messages ......................................................................................................................... 148

5.6 RMLDR, RMLDRFAT.16, RMLDRFAT.32 ................................................................................ 149 5.6.1 Installing the second stage boot loader RMLDR ...................................................................... 150

5.7 LOADX.EXE .............................................................................................................................. 151

5.8 BLOWUP ................................................................................................................................... 152

5.9 SYSCOPY.EXE ......................................................................................................................... 153

5.10 SYSCOPY32.EXE ..................................................................................................................... 155

A Abbreviations/Glossary ........................................................................................................................ 157

Index ................................................................................................................................................... 165

Table of contents


Tables

Table 1- 1 Commands ................................................................................................................................... 10 Table 1- 2 Abbreviations ............................................................................................................................... 10 Table 1- 3 General data types ....................................................................................................................... 11 Table 1- 4 Data types of the RMOS3 API ..................................................................................................... 11 Table 2- 1 Number of SMR blocks required .................................................................................................. 22 Table 2- 2 Overview of SVC entry points ...................................................................................................... 24 Table 2- 3 TCD block structure ..................................................................................................................... 25 Table 2- 4 Meaning of the task flags ............................................................................................................. 27 Table 2- 5 DCD block structure ..................................................................................................................... 28 Table 2- 6 Meaning of the driver flags ........................................................................................................... 29 Table 2- 7 UCD block structure ..................................................................................................................... 29 Table 2- 8 Organization of the stack when SVC returns a value unequal to 0 ............................................. 32 Table 2- 9 Section [System] .......................................................................................................................... 46 Table 2- 10 Section [RMOS] ........................................................................................................................... 49 Table 2- 11 Section [HSFS]............................................................................................................................. 51 Table 2- 12 Section [SCANDISK] .................................................................................................................... 52 Table 2- 13 Section [CPU], general keys ........................................................................................................ 53 Table 2- 14 Section [CPU], COM A interface with BYT driver ........................................................................ 54 Table 2- 15 Section [CPU], COM A interface with 3964R driver ..................................................................... 55 Table 2- 16 Section [TCP] ............................................................................................................................... 56 Table 2- 17 Memory requirements of RMOS3 data structures ....................................................................... 59 Table 2- 18 System resources ........................................................................................................................ 59 Table 3- 1 Parameters of SVC RmIO ............................................................................................................ 65 Table 3- 2 DCD block .................................................................................................................................... 70 Table 3- 3 DCB .............................................................................................................................................. 71 Table 3- 4 UCD block .................................................................................................................................... 72 Table 3- 5 UCB block .................................................................................................................................... 73 Table 3- 6 IRB block ...................................................................................................................................... 74 Table 3- 7 TMB block .................................................................................................................................... 75 Table 3- 8 Driver functions for assembler routines ....................................................................................... 79 Table 3- 9 Driver functions for assembler and C routines ............................................................................. 79 Table 3- 10 System variables .......................................................................................................................... 80 Table 4- 1 EAX and EBX parameters at the start of the debugger ............................................................. 108 Table 4- 2 Argument definitions for addresses ........................................................................................... 111 Table 4- 3 Argument entries for expressions .............................................................................................. 111

Table of contents


Table 4- 4 Argument entries for formatting.................................................................................................. 112 Table 4- 5 Argument entries for breakpoints ............................................................................................... 113 Table 4- 6 Parameter structure of resource reporter ................................................................................... 120 Table 4- 7 Coding of parameter analyze_type ............................................................................................ 122 Table 4- 8 Coding of the restart parameter ................................................................................................. 123 Table 4- 9 Resource reporter table ............................................................................................................. 124 Table 4- 10 Structure of the Exception Interrupt Handler .............................................................................. 126 Table 4- 11 Functions of mass storage device drivers .................................................................................. 133 Table 4- 12 Parameters ................................................................................................................................. 134 Table 4- 13 Completion status indicators ...................................................................................................... 134 Table 4- 14 Structure of a mass storage unit ................................................................................................ 139 Table 4- 15 Structure of a directory entry ...................................................................................................... 140

Figures

Figure 3-1 Call environment of driver programs ............................................................................................ 63 Figure 3-2 Serial driver (one controller for several units) .............................................................................. 76 Figure 3-3 Parallel driver (one controller per unit) ......................................................................................... 77 Figure 3-4 System processes ........................................................................................................................ 78 Figure 3-5 System processes and interrupt handling .................................................................................... 96 Figure 3-6 Example of the interaction between an interrupt handler and a task ........................................... 99 Figure 3-7 Flow chart for a task that needs an interrupt handler .................................................................. 99 Figure 3-8 Example of an interrupt handler that supports a task ................................................................ 100 Figure 4-1 Task mode and monitor mode of the RMOS3 debugger ........................................................... 105


About this document . . 1 1.1 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.

About this document . . 1.2 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.

1847 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



Data types The following data types may be used for the C compilers approved for RMOS3:

Table 1- 3 General data types

Data type Data length char 8 bit short 16 bit int 32 bit long 32 bit long long 1 64 bit void _FAR * 2 48 bit void _NEAR * 2 32 bit enum 32 bit float 32 bit double 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 Pointer to function type

void _FAR f(void) 48 bit

rmnearproc 1 Pointer to function type void _NEAR f(void)

32 bit

rmproc 1 Pointer to function type void _NEAR f(void)

32 bit

1 Pointers in flat programs always have a length of 32 bit. No distinction is made between NEAR and FAR.




Configuring the RMOS3 nucleus 2 2.1 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.

2.2.1 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

Configuring the RMOS3 nucleus 2.2 RMOS3 operating system components


2.2.2 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

2.2.3 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)

2.2.4 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, ...

2.2.5 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





2.2.6 COM driver ● I/O driver for host to host communication using the 3964(R) protocol

● Configurable: e.g. for UART blocks 8250, 8530



2.2.7 DMA driver ● Management of DMA control blocks or DMA control of an 80186/188 CPU and PC

hardware.

2.2.8 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

2.2.9 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


● Formatting floppy disks

● Positioning the read/write head onto a track

● Reading/deleting/redefining floppy disk operating parameters



2.2.10 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/deleting/redefining hard disk operating parameters

2.2.11 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


2.2.12 HPET driver ● High Precision Event Timer that can be reloaded

● Using timer 0 for the operating system clock rate

2.2.13 Network drivers ● Reloadable TCP/IP stack and network adapter drivers

TCP/IP utilities:

● FTP, server and client

● TELNET, server and client



2.2.14 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.

2.2.15 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).

2.2.16 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



● 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

2.2.17 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

2.2.18 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 80386 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



● 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

2.2.19 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 80386 debug registers

● All registers can be modified, including CS/EIP, after a task was suspended by means of breakpoint

2.2.20 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

2.2.21 Profiler RPROF ● Reloadable by means of CLI

● Menu controlled operation

Determine ...

● System parameters

● System load

● Task activities

● Interrupt latencies



2.2.22 Exception interrupt handler ● Logs exception interrupts of the processor at the system console.

● Also supplied as source code for customization.

2.2.23 Arithmetic processor ● Can be used simultaneously by several tasks

● Emulation is possible

2.2.24 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

2.2.25 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

2.2.26 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

Configuring the RMOS3 nucleus 2.3 Structures and elements of the RMOS3 nucleus


2.3 Structures and elements of the RMOS3 nucleus

2.3.1 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.

2.3.2 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.



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 (RmReceiveMail). RmReceiveMail 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



2.3.3 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.

2.3.4 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.

2.3.5 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.



2.3.6 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.

2.3.7 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).



2.3.8 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 4 ...7 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 10 ...15 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



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.



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 10...15 Reserved: Must be 0.



2.3.9 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_CODE32.

3. 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_CODE32.



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)

3 ... 7 Reserved

2.3.10 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)



1. Number of UCDs or UCBs (UCD.PID)

Bit 0 ... 5: 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.



2.3.11 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.

2.3.12 Creating interrupt vectors

Note

The interrupt vectors 0 to 31 may only be used for processor exception interrupts.

2.3.13 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.

2.3.14 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:



Table 2- 8 Organization of the stack when SVC returns a value unequal to 0

Stack organization RMOS3 Return address 4 bytes Task ID 4 bytes Status word 4 bytes SVC number 4 bytes

The exception handler runs in S state.

The stack segment register and data segment register contain RM3_DATA; both may not have changed on completion of the return action.

All other registers can be changed. An example is available in the SVCEXC.ASM file in the SOURCE\ETC\CADUL directory.

You may explicitly disable SVC messages by setting the RmSetOS function.

2.3.15 Definition of the I/O directions You can define the I/O directions using the initialization functions of the operated driver, (e.g. RcInitByt). You need to create an analog function if you want to customize a driver for a specific hardware. Select a similar initialization function from the initialization functions for which the source code is included with your package for use as template.

Configuring the RMOS3 nucleus 2.4 Drivers in the configurable nucleus


2.4 Drivers in the configurable nucleus

2.4.1 EIDE driver The configurable nucleus contains an EIDE driver. This driver can be used to address, partition and format hard disks in LBA mode up to a size of 8 GB.

The EIDE driver also supports the secondary EIDE controller. The driver enables operation of up to three hard disks.

Note

If you partition and format two hard disks in MS-DOS, the sequence of the logical volume names in RMOS3 differs to that in MS-DOS.

● The EIDE driver supports ATA-3.

● The EIDE driver supports the LBA mode

● The EIDE driver supports 32-bit data transfer.

● Hdinit automatically acquires the HD parameters and sets the Default Translation Mode on the HD.

● The EIDE driver supports the addresses of the secondary channel

● Hdinit automatically detects the secondary channel. The BIOS parameters are only evaluated for the secondary channel if the program has not yet detected two HD on the primary channel.

Note

The secondary channel supports only one HD. This means that you can operate up to three HD (2 on the primary, one on the secondary channel) drives.

● The startup routine checks for the presence of a HD on the secondary channel. If a HD was found, a driver with the addresses for the secondary channel will be installed and "SEC_CHANNEL" is written to the resource catalog.

2.4.2 TCP/IP connection The configurable nucleus contains the configuration for the TCP/IP connection of the onboard LAN block of the CPU module. The stack and driver are included with your package and are loaded dynamically at runtime (RMOS.INI).

Accessories required

You need to place a separate order for the RMOS3-TCP/IP package.

BSP-SIMATIC PC contains the latest network drivers.

Note

You cannot create a new socket application if missing the RMOS3-TCPIP package.



2.4.3 UDMA support for EIDE drives You may load the UDMA driver at runtime to replace the HD0 driver. That driver supports both the UDMA and the PIO mode, which means that all drives are operated at their ideal transmission rate. The drive must be operated in LBA mode.

The UDMA driver should be started in advance of PCI driver (RMISHSRV.DRV), and after the APIC driver (PCIAPIC.DRV).

You can use switch "-p" to transfer specific priorities to the driver. Without the switch, the UDMA driver employs the priority of the HSFS_C task plus 1.

Example run=C:\RM3RUN\LOADER.386 C:\RM3RUN\UDMA.DRV

Example on a SIMATIC Box PC 827B: RMOS3 EIDE(UDMA) Driver V1.11 (C) Copyright 2007, Siemens AG. All rights reserved. ICH7: IDE controller on PCI bus 00 dev fa hda: ST380815AS, ATA DISK drive hda: 156301488 sectors (80026 MB) w/8192KiB Cache,CHS=9729/255/63,UDMA(100)

2.4.3.1 Messages The following information is output after the UDMA was loaded:

RMOS3 EIDE(UDMA) Driver Vx.y

(C) Copyright yyyy, Siemens AG. All rights reserved.

Successful initialization.

*** UDMA: cannot find eide(emem) driver

The EMEM driver was not set up in the system configuration (rmconf.c).

*** UDMA: CHS mode in BIOS for drive hda selected

A drive is set in CHS mode.

*** UDMA: eide(udma) driver already started

UDMA driver already started.

2.4.4 PCI support by Shared Interrupt Server (SIS) The RMISHSRV.DRV SIS is loaded automatically by the configurable nucleus.

The PCI Shared Interrupt Server scans the entire PCI bus and automatically maps all memory areas found for access at privilege level 0 and privilege level 3.



Example Example on a SIMATIC Box PC 827B: RMOS3 PCI Initialization V2.5.3 (C) Copyright 2008, Siemens AG. All rights reserved. PCI: init server ok

2.4.4.1 Messages The following information is output after the server was loaded:

© Siemens AG, RMOS3PCI Initialization Vx.y

RMOS3PCI: init server ok.

Successful initialization.

RMOS3PCI error: Server is already catalogued

RMOS3PCI already found in the catalog.

RMOS3PCI error : Could not catalogue server

RMOS3PCI could not be cataloged.

RMOS3PCI Error : init server

Driver initialization failed.

2.4.5 APIC support RMOS3 always boots in PIC mode. In this mode, all PCI interrupts are assigned a free interrupt from IRQ0 to IRQ15. This rule is valid for onboard PCI interrupts (e.g. LAN, USB) and for external PCI interrupts (expansion cards on the PCI bus). The assigned interrupt is saved to Configuration Space.

To enable operation in APIC mode, the reloadable APIC driver PCIAPIC.DRV must be started in RMOS.INI. This is done automatically, provided the DisableApic key is deactivated in the configurable nucleus. PCIAPIC.DRV must be started before the start of the UDMA, LAN and USB drivers. The PCI Shared Interrupt Server can be started before or after the driver start.

run=C:\RM3RUN\LOADER C:\RM3RUN\PCIAPIC.DRV

The assignment of PCI interrupts is now changed. The assignment of onboard PCI interrupts is fixed and depends on the chipset.

The PCIAPIC.DRV now adjusts the interrupts entered in Configuration Space.

Switch "-m" activates the RMOS3 multiprocessing mode.



2.4.5.1 Messages The following information is output after the driver was started:

RMOS3 PCIAPIC Initialization Vx.y.z

(C) Copyright yyyy, Siemens AG. All rights reserved. PCIAPIC: try to switch from PIC

to APIC

PCIAPIC: switch from PIC to APIC finished

Change to APIC mode was completed successfully.

PCIAPIC: ICH6 found (BOX PC 627)

Output of the ICH block found.

PCIAPIC: intr USB#0 changed to IRQ16 (ICH6)

New assignment of an onboard PCI interrupt.

PCIAPIC: IRQ03 changed to IRQ22 (DeviceID: 1409, VendorID: 7168)

New assignment of an external PCI interrupt.

PCIAPIC: RMOS configured without APIC

CPU without APIC support.

PCIAPIC: no pci device found

No PCI device was found on the PCI bus.

PCIAPIC: board not supported

The chipset is not supported.

PCIAPIC: cannot route IRQxx (DeviceID: xxxx, VendorID: yyyy

New interrupt assignment failed.

PCIAPIC: booting processor 1 (APIC_ID=1)

PCIAPIC: processor 1 has booted

Multiprocessing mode: A second core was found and activated.

2.4.6 HPET support The HPET.DRV driver uses a high-resolution timer (HPET) for the operating system clock rate. This timer is not available on every target system The timer must be activated in BIOS with start address 0xfed00000.

This driver checks whether or not an HPET is available at address 0xfed00000. If an HPET was found, timer 0 of the HPET is used for the operating system clock rate. The 8254 timer continuous without triggering a further interrupt.

Properties of the timers:

● 3 timers

● 64-bit

● "Interrupt Legacy Mode"

● Clock rate 69841279 femto-seconds (100000000 = 100 ns)



In "Interrupt Legacy Mode", in PIC mode timer 0 uses IRQ0, and IRQ 2 in APIC mode.

The reloadable HPET.DRV driver must be started in RMOS.INI to enable the use of HPET. It can only be loaded at PL0.

The HPET driver saves the physical start address of the HPET timers to catalog entry "HPET_INFO". You may view this entry in the debugger, for example: >dir misc lo Cataloged resources Symbolic-name kind id ide HPET_INFO MISC 006BH FED00000H

2.4.6.1 Messages The following information is output after the driver was started: RMOS3 HPET Driver Vx.y.z (C) Copyright yyyy, Siemens AG. All rights reserved. clk period=69841279 femtoseconds, counter size=64-bits, number of timers=3

Change to HPET mode was completed successfully. *** HPET: no HPET timer found

No HPET is available on the system, or an incorrect base address is set in BIOS.

Configuring the RMOS3 nucleus 2.5 Configurable nucleus


2.5 Configurable nucleus

Overview and notes The configurable RMOS3 nucleus is always configured by means of the RMOS.INI configuration file to load the necessary module drivers, initialize the interfaces, set environment variables, and launch applications. it is no longer necessary to generate the nucleus.

Structure of the RMOS.INI configuration file Configuration file RMOS.INI is organized in sections where you make your settings. The following chapters describe generally valid keys. Information on CPU-specific keys is also available in the BSP-SIMATIC IPC User Manual.

The file is created using a standard text editor (edit, wordpad, ...).

You configure the nucleus by entering group names / sections and keywords in the file. The group names entered are enclosed in square brackets, e.g. [System]. The keywords consist of a name and an assignment, e.g. name = RMOS-SYSTEM.

You must strictly adhere to the notation (uppercase/lowercase) when entering the group names and keywords. Examples are available in the respective chapter.

Values identified in the following as default values do not necessarily need to be specified, as these are set automatically.

Keys that you always need to specify are marked in bold in the following table.

Entries that you do not need can be commented out by setting a semicolon ";" or "REM" at the line start.

Note

The specified default value is invalid if you do not enter a value for the respective key or omit its entry in the RMOS.INI configuration file.

Variants of the configurable RMOS3 nucleus The configurable RMOS3 nucleus is stored in the SYSTEM\PC_CNUC<version> directory. The latest version is available in the directory SYSTEM\PC_CNUC.



2.5.1 Booting with the second stage boot loader RMLDR The second stage boot loader RMLDR can be used to load the configurable RMOS3 nucleus as of 1 MB above the adapter gap.

For this purpose, you need the following files:

RMLDR Second stage boot loader for RMOS3 nucleus. Must be located in

first place in the root directory of the volume. RM3_PC1.SYS RMOS3 nucleus. Can be located at any position in the root

directory. CNFTSK.386 Configuration program. The root directory of all available drives is

scanned for an existing CNFTSK.386 file. RMOS.INI Configuration file for RMOS3 nucleus. The root directory of all

available drives is scanned for an existing RMOS.INI file.

You need to observe the following points for commissioning:

● The boot sector for the second stage boot loader RMLDR must be installed with RDISK on the boot medium.

● The second stage boot loader RMLDR must be located in first position on the data volume and written in uppercase! The data volume may not be labeled!

● The RMOS3 boot file RM3_PC1.SYS may be located anywhere in the root directory of the data volume, but may not be fragmented (see chapter "SYSCOPY.EXE (Page 153)", or "SYSCOPY32.EXE (Page 155)")! It may also be written in lowercase notation.

● The second stage boot loader always starts by searching for RM3_PC1.SYS. This file will be loaded if found on the data volume. The first file with extension *.SYS is loaded if RM3_PC1.SYS is not found. The procedure checks whether or not this is an RMOS3 boot file.

The boot medium must be prepared as specified in the User Manual chapter 4, "Installing RMOS3".



2.5.2 Booting with MS-DOS and RMOS3 load program LOADX Boot loader LOADX can be used in MS-DOS to load the configurable RMOS3 nucleus as of 1 MB above the adapter gap.

For this purpose, you need the following files:

IO.SYS, MSDOS.SYS MS-DOS system files. AUTOEXEC.BAT, CONFIG.SYS

Components of MS-DOS.

LOADX.EXE Load program for RMOS3 nucleus in MS-DOS. May be stored in any directory; the path name is specified in AUTOEXEC.BAT.

RM3_PC1.LOC RMOS3 nucleus. Can be stored in any directory; the path name is specified in AUTOEXEC.BAT.

CNFTSK.386 Configuration program. The root directory of all available drives is scanned for an existing CNFTSK.386 file.

RMOS.INI Configuration file for RMOS3 nucleus. The root directory of all available drives is scanned for an existing RMOS.INI file. RMOS.INI may also be stored in a subdirectory if CNFTSK.INI is used.

Conditions for using LOADX:

● The boot medium must be capable of booting MS-DOS.

● The CONFIG.SYS and AUTOEXEC.BAT files must be customized as follows.

● No MS-DOS drivers may be loaded if LOADX is used.

For more information on installation, refer to chapter 4, "Installing RMOS3" in the User Manual.

CONFIG.SYS structure You must not include any drivers in CONFIG.SYS.

The file must contain the "DOS = LOW" entry.

Example: DOS = LOW

AUTOEXEC.BAT structure AUTOEXEC.BAT must contain the following entry: c:\loadx c:\rm3_pc1.loc

The path names must correspond to the directories to which the files were copied.

Example: c:\loadx c:\rm3_pc1.loc



Using configuration file CNFTSK.INI You may also start the RMOS3 nucleus with different RMOS.INI configuration files. In this case, however, you must always use CNFTSK.INI and specify a boot menu in CONFIG.SYS. RMOS.INI is loaded from the root directory if CNFTSK.INI does not exist.

Example of CONFIG.SYS:

[menu]

menuitem=CONF1

menuitem=CONF2

menudefault=CONF1,5

[CONF1]

DOS = LOW

[CONF2]

DOS = LOW

Example of AUTOEXEC.BAT:

goto %config%

:CONF1

echo c:\conf1\rmos.ini > c:\cnftsk.ini

goto GOON

:CONF2

echo c:\conf2\rmos.ini > c:\cnftsk.ini

goto GOON

:GOON

c:\loadx c:\rm3_pc1.loc

Example for the automatically generated CNFTSK.INI:

C:\conf1\rmos.ini

2.5.3 Startup messages and system outputs

Outputs of RMOS3 nucleus Messages of the RMOS3 nucleus are output to system console COM2, if not specified otherwise in RMOS.INI. You can monitor these messages on a connected terminal. These messages can be logged in parallel to a LOG file for evaluation at a later time. An example of this file is available further down in this chapter. The various steps are also displayed on a connected VGA monitor. The data output to this screen is listed below, as well.

Loading the RMOS3 nucleus LOADX.EXE (MS-DOS) or the second stage boot loader RMLDR (RMOS3) is then called to load the RMOS3 nucleus to RAM above the 1 MB area and the code of the RMOS3 nucleus is processed.



Basic initialization of the nucleus The timers, interrupt controllers, the serial interface for the system console and other basic utilities are now initialized in an initial "STARTUP" phase. Real-time capabilities and multitasking mechanisms are not available in this phase.

Startup messages by means of system console, part 1 "STARTUP" NUC: init passpoint COM1

NUC: RAM size: 3056 MB

NUC: no memory hole detected

NUC: no ram-disk from LAN-BOOT detected

NUC: init pic

NUC: init OS

NUC: init byt driver

NUC: init ega

NUC: init com1 (19200,8,n,1)

NUC: set system parameter

NUC: create reporter

NUC: config debugger

NUC: create error logger

NUC: create exception handler

NUC: init hsfs

NUC: create remote task

NUC: config usb-memdriver

NUC: starting system

NUC: SIMATIC BOX PC 827B Profibus detected

NUC: init hd0 driver(CMOS=0x0)

NUC: found disk on primary master

NUC: config udma(emem) driver

Start of INITTASK The real-time multitasking system starts with system message "NUC: starting system": All interrupt controllers are enabled, the scheduler is activated and the first task, namely the "INITTASK", is started. The CPU type is determined, the hard disks/ROM disks are initialized, and configurator "CNFTSK.386" is started in the following procedure.

Startup messages by means of system console, part 2 "INITTASK" INIT: init hd0

RMOS3 Harddisk Initialization V1.9g

The following partitions were announced:

Partition FAT16, size: 2047.9 MB, announced as: C

RMOS3 V03.50.08 R01 (Aug 12 2009)

INIT: local drives: C A

INIT: start configuration

INIT: execute C:\cnftsk.386



Start of the configurator and interpretation of RMOS.INI The configurator starts with a version message, locates and opens the RMOS.INI configuration file, and processes the sections in the following order:

1. Section [System] (Page 45)

2. Section [HSFS] (Page 51)

3. Section [SCANDISK] (Page 52)

4. Section [CPU] (Page 53)

5. Section [RMOS] (Page 49)

6. Section [TCP] (Page 56)

The configurator is then terminated automatically.

Startup messages by means of system console, part 3 "Configurator" RMOS3 Configuration V03.50.08 R01 (Aug 12 2009)

(C) Copyright 2009, Siemens AG. All rights reserved

RMOS3 PCIAPIC Initialization V1.1.10

(C) Copyright 2009, Siemens AG. All rights reserved.

RMOS3 EIDE(UDMA) Driver V1.11.3

(C) Copyright 2009, Siemens AG. All rights reserved.

hda: ST380815AS, ATA DISK drive

hda: 156301488 sectors (80026 MB) w/8192KiB Cache,CHS=9729/255/63,UDMA(100)

...

cnftsk.386: FINISHED SUCCESSFULL

You can set the switch Messages = YES, Section [System] (Page 45), in the RMOS.INI configuration file to enable the output of additional messages.

Start of the customer's application The task "INITTASK" releases allocated memory space and launches the customer's application by means of StartUpFile or BootBatch.

Startup messages via system console, part 4 INIT: file C:\cnftsk.386 started (Exit-State: 0)

INIT: initialisation completed

INIT: Start Application

INIT: System is ready

INIT: Available Heap is: 3048425 KB



Logging of startup messages The startup messages are logged to a file if the Messages switch is set to YES in configuration file RMOS.INI, Section [System] (Page 45). The name of this file is also defined in configuration file RMOS.INI. An example of this file is shown below.

CNF: System started at: Wed Aug 12 08:46:42 2009

CNF:[System]

CNF: Messages: yes

CNF: Description: RMOS3 V3.50 EXAMPLE CONFIGURATION

CNF: LogFile: C:\RMOS.LOG

CNF: RmosPath: C:\RM3RUN

CNF: new directory: C:

CNF: SystemFlagGroup: SysFlgGrp

CNF: RamDiskSize: 2097152 Bytes (2048KB)

CNF: BootFilePath: C:\RM3_PC1.SYS

CNF: nucleus version V3.50.08

CNF: configurator version V03.50.08 R01 (Aug 12 2009)

...

CNF:[System]

CNF: StartupFile: not defined

CNF: BootBatch not defined

CNF:

Startup messages on the VGA screen You can monitor the various bootstrapping phases on a connected VGA screen. The messages are visualized in the upper third of the screen on different background colors, depending on the current bootstrap phase. These include in particular:

● Check for CPU

● CPU-Detection done

● INIT: init hd0

● INIT: start configuration

● Configuration started

● Config CPU

● Config USB

● Config Boards

● Config TCP/IP

● Setup Bootfiles

● INIT: System is ready



Completion of the boot process The RMOS3 system is booted completely as soon as the System is ready

message is output.

Error messages Error messages generated in the configurator session are displayed in the format

CNF-ERROR: *** <error message>,

with <error message> representing the corresponding error message.

The configurator is closed automatically if an error was found and the alarm

INIT: *** Configuration error ***

is output on the VGA console on a red background and on the system console.

Note

The RMOS3 system may not be put into operation if an error was found, because the functional scope is possibly restricted!

Examples CNF-ERROR: *** wrong nucleus version V 2.22.04

Configuration program CNFTSK.386 is not suitable for use with RMOS3 Nucleus V2.22.04.

CNF-ERROR: *** no config file available

No RMOS.INI configuration file found.

CNF-ERROR: *** unknown key: [System], test = 456

The key test = 456 in in the group [System] is not supported.

2.5.4 Section [System]

Overview The section [System] serves to provide a general description of the RMOS3 system.

For the purpose of diagnostics and service, this section provides you with the option of assigning a computer name to the RMOS3 system, of creating a log file for all system messages, and of defining a system flag group that indicates any possibly generated general protection errors such as DIVIDE ERROR, STACK FAULT, GENERAL PROTECTION, FLOATING POINT ERROR, and PROCESSOR CHECK TEMPERATURE REACHED (as far as supported by the CPU).



In this section, you may also set environment variables such as the path to the reloadable RMOS3 programs and automatically launch user applications: either by means of a StartUpFile initialization task with optional prioritization, or using a BootBatch file

Table 2- 9 Section [System]

Keys Value range Description Default value Comment Description String

(max. 40 characters)

String (e.g. COMPUTER1) is stored as SYSTEM environment variable (e.g. SYSTEM=COMPUTER1).

CPU name Can be defined by users.

RmosPath String RMOS3 directory that contains all reloadable RMOS3 programs/drivers.

<X>:\RM3RUN <X> represents the boot volume (e.g. "C") and must be entered accordingly.

BootFilePath String Boot directory, including the name of the loaded nucleus (e.g. C:\RM3_PC1.SYS)

--- If no entry exists, the ‘RM3_PC1.LOC’ is located and entered in the BootFilePath key.

StartUpFile String RMOS3 task that is launched on completion of the system startup.

--- 1 Default name: STARTUP.386 2

1 No task is started if the entry does not exist. 2 It is not possible to pass parameters to the program. The loader result segment is

cataloged and may be used for debugging purposes.



Keys Value range Description Default value Comment StartUpFilePrio 0 ... 255 Priority of the

‘StartUpFile’ task to be started

128 (0x80) ---

BootBatch String CLI batch that is executed once on completion of the boot process.

--- 1 Default name: RM_INIT.BAT

LogFile String File to which the startup messages of the nucleus are saved. 2

R:\RMOS.LOG ---

LogExceptions yes | no If feasible, exceptions are included in the log file

no An exception in the file system will lead to a deadlock.

SystemFlagGroup String (max. 14 characters)

Name of a dynamic flag group to which system events such as general protection faults are written

SysFlagGroup ---

RamDiskSize 0 | 8192 .. 0x7FF00000

Size of the RAM DISK 2097152 (2 MB) The RAM DISK has a minimum size of 8 KB. 0: No RAM DISK is created.

Messages yes | no Enabling or disabling startup messages of the nucleus on the system console and the log file

no Affects only the startup messages that are output after evaluation of RMOS.INI

1 No batch file is launched if the entry is not available 2 If it already exists at system startup, the file is renamed with extension 'old‘.

Special features Execution sequence:

If the section specifies both the StartUpFile and a boot batch, the programs are processed in the following order:

1. StartUpFile, e.g. STARTUP.386

2. BootBatch, e.g. RM_INIT.BAT

Value range for strings:

If not specified otherwise, a string may not exceed the maximum length of 255 characters.



IDs for the flag group ‘SystemFlagGroup’ up to V3.30.02 R23: DIVIDE ERROR 0x00000001 STACK FAULT 0x00001000 GENERAL PROTECTION 0x00002000 FLOATING POINT ERROR 0x00010000 PROCESSOR CHECK TEMPERATURE REACHED 0x01000000 PROCESSOR CHECK TEMPERATURE 100°C REACHED 0x02000000

IDs for the flag group ‘SystemFlagGroup’ as of V3.30.02 R24: Current CPU temperature 0x000000FF DIVIDE ERROR 0x00000100 STACK FAULT 0x00001000 GENERAL PROTECTION 0x00002000 FLOATING POINT ERROR 0x00010000 PROCESSOR CHECK TEMPERATURE REACHED 0x01000000 PROCESSOR CHECK TEMPERATURE 100°C REACHED 0x02000000 FAN ERROR 0x04000000

Temperature monitoring is activated in two phases:

1. With activated temperature monitoring ( "CheckCoreTemperature" key in section [CPU]), the "PROCESSOR CHECK TEMPERATURE REACHED" flag indicates that the processor temperature is exceeded.

2. The "PROCESSOR CHECK TEMPERATURE 100°C REACHED" flag is set if the 100°C temperature threshold is exceeded. The flag is not reset after the temperature has dropped below the threshold.

Additional IDs for the flag group ‘SystemFlagGroup’ as of V3.50.04 R01: PAGE FAULT 0x00004000 BATTERY ERROR 0x08000000

Additional IDs for the flag group ‘SystemFlagGroup’ as of V3.50.04 R02: FLAG_OPHOURS_REACHED 0x10000000

StartUpFile: The task selected with this key is loaded to system memory (Heap). The loader result segment is cataloged under the name "STARTUP_LRS". The task is also cataloged under the name "STARTUPFILE".

Example [System] Description = TESTSYSTEM RmosPath = c:\rm3run BootFilePath = c:\rm3_pc1.loc StartUpFile = c:\startup.386 StartUpFilePrio = 0x40 BootBatch = c:\rm_init.bat LogFile = r:\rmos.log ; create LOG file in RAM- ; DISK LogException = yes



2.5.5 Section [RMOS]

Overview This [RMOS] section is downwards compatible with previous RMOS3 versions. In this section, you can customize various resources that are already predefined in the RMOS3 nucleus to suit your requirements.

Table 2- 10 Section [RMOS]

Keys Value range Description Default value Comment rate 1 .... 54 system clock rate in

milliseconds 1 ---

semaphores 10 ... 1023 Number of ‘static’ semaphores

10 ---

flags 10 ... 127 Number of ‘static’ flag groups

10 ---

mailboxes 10 ... 255 Number of ‘static’ mailboxes

10 ---

smrs 500 … 65534 Limit of the available number of SMRs (System Memory Block)

65534 A high limit for the dynamically allocated SMRs can be set at this parameter. Refer to chapter "Internal nucleus structures SRB and SMR (Page 21)".

logsvcx yes | no Log system messages yes Upper case and lower case values allowed.

sysdev BYT_COM1 | BYT_COM2 | BYT_EGA_0 | BYT_EGA_1 | BYT_EGA_2 | BYT_EGA_3

System console BYT_COM2 Upper case and lower case values allowed. Following switching of the system console, the messages of configuration program CNFTSK.386 will still appear at BYT_COM2. The messages of all loaded programs are output immediately after switching at the new system console



Keys Value range Description Default value Comment keyboard French |

German | Italian | Spanish | UK-English | US-English

Keyboard layout used for the PS/2 interface

US-English Upper case and lower case values allowed.

run String (max. 128 characters)

Execute Run command --- Allow a maximum of 15 entries per Run command

RunDelay 0 … 10,000 Delay time in milliseconds expiring after each Run command

0 Evaluated once only. Last entry is valid.

RoundRobin 1 … 100 Round-Robin factor 10 Round-Robin interval = RoundRobin * rate

ReporterTableSize 0x4500 ... 0xFFFFFFFF

Table size for Resource Reporter in bytes

0x4500 The necessary size depends on the number of cataloged resources/tasks

VGATaskPriority 0 ... 255 VGA task priority 254 Debugger yes | no Switch that decides

whether or not to load debugger.drv

yes

Example [RMOS] rate = 1 semaphores = 20 flags = 20 mailboxes = 20 logsvcx = yes sysdev = BYT_COM2 keyboard = German ReporterTableSize = 0x5000 run = c:\sp049.386 RunDelay = 1000 ; 1 sec pause, after the ; Run command



2.5.6 Section [HSFS]

Overview You may edit the most important parameters of the file system in the [HSFS] section.

Table 2- 11 Section [HSFS]

Keys Value range Description Default value Comment prio 0 ... 255 Priority of the file system 253 --- channels 10 … 600 Number of channels

(CCBs, see chapter "Internal organization of the HSFS (Page 136)").

600

files 10 … 512 Number of files (FCBs, see chapter "Internal organization of the HSFS (Page 136)").

512

buffersize 1 | 2 | 4 | 8 | 16 Buffer length as multiple of 512 byte blocks

16

buffers 16 ... 1024(128) Number of data buffers (BBs, see chapter "Internal organization of the HSFS (Page 136)").

1024(128) A default value of 1024 is automatically assumed for systems with more than 16 MB RAM, and 128 for systems with less than 16 MB RAM.

DisableUDMA yes | no Disable the UDMA driver no

Description The channels and files keys are used to define the nesting depth of the directories and the maximum number of simultaneously open files.

Parameter buffersize determines the buffer size in 512 byte blocks (sectors) that is provided by the operating system for each access to the memory medium. Access can be optimized to suit the respective memory medium used. If an IDE flash disk e.g. allows access to one sector per read/write command you can set the buffersize = 1 parameter to enhance performance.

Example [HSFS] prio = 250 channels = 128 files = 64 buffersize = 16



2.5.7 Section [SCANDISK]

Overview In section [SCANDISK], you can specify whether or not to call the SCANDISK during startup.

Table 2- 12 Section [SCANDISK]

Keys Value range Description Default value Comment Use yes | no yes: SCANDISK is

executed no ---

Drives C:, D:, E:, F:, P0:, P1:, P2:, P3:, O0:, O1:, R1

Drives to verify at startup --- It is possible to specify 1 to 11 drives.

Repair auto | no Auto: Errors are corrected automatically

auto ---

Messages yes | no Yes: SCANDISK outputs messages to the system console

yes ---

Description The Use key specifies whether or not to call the SCANDISK during startup.

The Drives key specifies the drives to verify.

The Repair key specifies whether or not to correct errors automatically.

The Messages key specifies whether or not SCANDISK outputs messages to the system console.

Example [SCANDISK] Use = yes Drives = C:, D: Repair = auto Messages = no

Commissioning The following file must be available in directory ‘C:\RM3RUN’ on the target computer: SCANDISK.386 Loadable scandisk(HD diagnose tool)



2.5.8 Section [CPU]

Overview Chapter "General keys (Page 53)" describes the keys that are valid for all CPUs. The CPU-specific keys are described in the successive chapters.

2.5.8.1 General keys

Table 2- 13 Section [CPU], general keys

Keys Value range Description Default value Comment Type AUTO CPU type used AUTO The CPU detected in the

BIOS routine is used if AUTO is set.

Driver_A BYT | 3964 | none Initialize COM A interface driver

none For information on driver settings, refer to the following chapters

DisableAPIC yes | no Deactivate APIC mode no DisableHPET yes | no Deactivate the HPET

driver no

DisableMulticore yes | no Deactivate multicore support

no

Comment If IRQ4 for the COM A interface is not a Legacy ISA interrupt (but is a PCI interrupt instead), the configuration is terminated with error message.



COM A interface with BYT driver

Overview The COM A interface is initialized with the BYT driver if the key Driver_A = BYT is entered. The default values will be valid if none of the following keys is specified.

Table 2- 14 Section [CPU], COM A interface with BYT driver

Keys Value range Description Default value Comment Baud_A 2400 | 4800 | 9600

| 19200 | 38400 | 57600 | 115200

Baud rate 19200 ---

Data_A 7 | 8 Number of data bits 8 --- Parity_A none | odd | even Parity none --- Stop_A 1 | 2 Number of stop bits 1 --- Name_A String (max. 14

characters) Name of the unit. BYT_COM1 The name must be

"OSB_COM" if OSB is running on the system.

PoolLength_A 0 … 255 Length of the buffer for COM A in bytes

255 No buffer is created if 0 is set

Emulation_A DS2 | DS3 | PC | X Emulation: DS2 = SME DS3 = VT100 PC = IBM PC/AT X = transparent mode

DS3 ---

Rts_A yes | no Status of the RTS signalyes = active

yes ---

Transparent mode

Terminal mode

Mode_A 0 … 255 Value of modext for COM_A

--- --- Has preference over Emulation_A. For more information on the advanced modes of the BYT driver, refer to chapter 5.2.4.3 MODEXT (extended modes) in the Reference Manual, Part II.

UnsolTask_A String (max. 14 characters)

Name of the CLI dispatcher for COM A

--- CLI_DPAT ---

UnsolCharacter1_A

^R | ^D | none Characters used to start the CLI dispatcher for COM A

--- ^R ---

UnsolCharacter2_A

^R | ^D | none Characters used to start the CLI dispatcher for COM A

--- ^D ---



COM A interface with 3964R driver

Overview The COM A interface is initialized with the 3964R driver if the Driver_A = 3964 key is entered. The default values will be valid if none of the following keys is specified.

Table 2- 15 Section [CPU], COM A interface with 3964R driver

Keys Value range Description Default value Comment Baud_A 2400 | 4800 | 9600

| 19200 | 38400 | 57600 | 115200

Baud rate 19200 ---

Data_A 7 | 8 Number of data bits 8 --- Parity_A none | even | odd Parity none --- Stop_A 1 | 2 Number of stop bits 1 --- Name_A String (max. 14

characters) Name of the unit. 3964R_COM1 ---

MasterSlave_A master | slave 3964R mode for COM A master --- TimeoutAcknowledge_A 0 … 65535 Timeout value for

Acknowledge COM A 0 Acknowledgment

monitoring time TQ as multiple of 10 ms. The RMOS3 system clock rate must be set to rate = 1 ms. A 0 value defines the default TQ = 2000 ms.

TimeoutCharacter_A 0 … 65535 Timeout value per character for COM A

0 Character monitoring time TZ as multiple of 10 ms. The RMOS3 system clock rate must be set to rate = 1 ms. A 0 value defines the default TZ = 200 ms.

BlockLength_A 0 … 65535 Block length COM A 5 Block length that is followed by the transmission of control character DLE ETB during data transmission. No block is generated if the 0 value is set.



2.5.8.2 Examples [CPU] Type = AUTO Driver_A = 3964 ; COM1 has 3964R driver Baud_A = 9600 Data_A = 8 Parity_A = none Stop_A = 1 IPAddress = 192.168.0.1 ; TCP/IP address IPMask = 255.255.255.0 ; TCP/IP mask

2.5.9 Section [TCP]

Overview If you need network support, use the following keys to start the Telnet and FTP daemons.

Table 2- 16 Section [TCP]

Keys Value range Description Default value Comment TCPPath String (max. 255

characters) Directory containing the TCP/IP files

--- An RmosPath entry found in the group [System] is appended to this entry.

SyslogStart yes | no yes: Load Syslogger

no Necessary for the Telnet daemon

SyslogFile String (max. 255 characters)

Syslog file --- Necessary for the Telnet daemon

EnvironmentNETETC String (max. 255 characters)

Directory for file HOSTS

--- Necessary for the Telnet and FTP daemons

EnvironmentHOST String (max. 255 characters)

Name of the local station

--- Necessary for the Telnet and FTP daemons

EnvironmentTERM VT100 | VT52 | TVI910 | TVI925 | QVT101 | SME | RMOSEGA | AT386

Telnet terminal emulation

VT100 Necessary for the Telnet daemon

NumberFTPD 0 … 4 Load the specified number of FTP daemons

0 ---

FTPDPriority 1 … 255 Priority of the FTP daemon

64

LogFTPD yes | no FTPD logs to the Syslog file

no If ‘yes’, then SyslogStart must also be set to ‘yes’



Keys Value range Description Default value Comment NumberTELNETD 0 … 4 Load the specified

number of TELNET daemons

0 If unequal to 0, it is mandatory to set SyslogStart to ‘yes’

TELNETDPriority 1 … 255 Priority of the TELNET daemon

64

EnvironmentTELNETD_PWD yes | no Manage password prompt for TELNETD

yes

Sockets 64 … 4096 Number of available sockets

192

NTPCStart yes | no yes: Start NTP client

no

NTPCMode single | cyclic | standby

NTPC mode cyclic

NTPCRefreshTime 1 … 0xFFFFFFFF

NTPC refresh time in seconds

86400 86400 = 24 hours

NTPCPriority 1 … 255 NTPC priority 64 NTPCTimeout 1 …

0xFFFFFFFF NTPC waiting time for server in seconds

4

NTPCServer String Server name WEBServerStart yes | no yes: Start

WebServer no

WEBServerPriority 1 … 255 Web server priority 64 WEBServerConfigPath String (max. 255

characters) Path to the configuration directory of the Web server

C:\RM3WEB\ WEB_CONFIG

WEBServerRootPath String (max. 255 characters)

Path to the basic directory of Web contents

C:\RM3WEB\ WEB_ROOT

Example [TCP] TCPPath = C:\RM3RUN SyslogStart = yes SyslogFile = C:\ETC\syslog EnvironmentNETETC = C:\ETC\ EnvironmentHOST = SIMATIC_PC EnvironmentTERM = VT100 NumberFTPD = 4 NumberTELNETD = 2



Commissioning The following files need to be copied to the RmosPath (e.g. ‘c:\rm3run’) on the target computer: TCPIP.DRV Loadable Stack (Socket and TCP/IP) TCPCONF.386 HW-Driver Configuration for TCP/IP ROUTECFG.386 Default Gateway Configuration ADDROUTE.386 Routing Table Configuration DELROUTE.386 Routing Table Configuration LOADER.386 Loader for Stack and Ethernetdriver SYSLOGD.386 System-logger (called by SYSLOGI) SYSLOGI.386 System-logger TELNET.386 Telnet Client TELNETD.386 Telnet Daemon FTP.386 FileTransferProgram FTPD.386 FileTransferProgram Daemon PING.386 ICMP ECHO Program

Configuring the RMOS3 nucleus 2.6 RMOS3 parameters


2.6 RMOS3 parameters

2.6.1 Memory requirements of RMOS3 data structures

Table 2- 17 Memory requirements of RMOS3 data structures

Data structures Size (bytes) decimal RMOS3 control data structures 230 TCD per task 68 TCB per task 72 DCD per driver 20 DCB per driver 256 UCD per unit 256 UCB per unit 256 Memory pool table per memory pool 22 Mailbox table per mailbox 20 Discrete I/O table per discrete byte 6 Vector table per vector 8 Event flag table per flag group 8 Semaphore table per semaphore 14 RMOS3 stack (configurable) 400

2.6.2 Number of system resources

Table 2- 18 System resources

Configuration parameters Amount/value Tasks 32768 (depending on available memory space

and configuration in swnuc.inc) Unit software driver 255 Units per driver 255 Mailboxes 255 Global event flag groups 127 Local event flags per task 32 Memory pools 8 Semaphores 4095 File handles 512 File handles per task 37 Sockets 192 System clock rate 1ms ≤ system clock rate ≤ 54ms

Configuring the RMOS3 nucleus 2.6 RMOS3 parameters



Driver development 3

In RMOS3, the drivers and interrupt handlers are referred to as basic I/O system because these are based directly upon the hardware.

The following sections provide a general overview of the driver tasks, of fundamental structures, and of functions.

For more information, programming notes and driver configuration,refer to chapter 5, "Functions and configuration of the basic I/O system" in the Reference Manual Part II.

3.1 What is a driver?

Task: Controlling I/O devices A device driver usually consists of several programs that are written, for example, in C or Assembler (work sequences, system processes), which manage one or several I/O devices of the same type, or their controllers.

I/O devices of the same type are for example several terminals that are controlled by means of V.24 interfaces. Drivers contain a standardized interface to the RMOS3 nucleus in the form of data structures or procedure entry points.

Jobs via SVC RmIO All tasks are capable of outputting jobs to a driver by means of SVC RmIO. The nucleus validates the SVC, copies the parameters to an internal data structure, and calls the corresponding driver program.

Other programs of the driver will simultaneously interface the device hardware and the RMOS3 nucleus. This interface is implemented by means of interrupt handlers. All programs of the driver work with the same data structures. In most situations, the driver programs access these data structures independently .

Priority of drivers All programs of a driver are part of the RMOS3 system and are implicitly assigned a higher priority level compared to the application tasks. The following parts of the driver may be implemented as separate programs:

● Initialization (hardware and, partially, data structures)

● Handling requests by means of RmIO SVC

● Handling interrupts

● Handling timeouts

● Handling a request

Driver development 3.1 What is a driver?


Driver customization A driver must be capable of controlling and managing several devices of the same type, or their controllers. The drivers are set up for the controllers by means of initialized data structures (DCD and UCD tables) in the configuration.

The term unit used in the following sections always refers to controllers and their connected I/O devices that are controlled by the driver. Units can be addressed directly as I/O devices (direct I/O method), or as memory (memory-oriented I/O method).

Serial drivers If separate addressing of several I/O devices of the same type it is not possible you cannot control more than one RmIO SVC at any given time, even if the driver manages several units. This scenario could develop, for example, if the controller handles several I/O devices (e.g., one controller for several floppy disk drives). In this case, we speak of a serial driver

Parallel drivers Parallel drivers can simultaneously process several units, provided independent activation of I/O devices by separate controllers is supported. Example: Terminals with separate serial controllers.

It may be necessary for two drivers to share the same unit. Both drivers can share the same common controller. The capability of sharing unit is a property of driver implementation that is only used in special situations.

You have two options of coordinating the runtime behavior of drivers that share the same unit:

● The first driver processes all queued requests until these are completed, before it passes the control to a second driver.

● A driver terminates a request and passes the control to a different driver.

Driver development 3.2 Driver tasks


3.2 Driver tasks

Drivers react to events Each driver is responsible to react to different events that are linked to the control and management of one or several units. These events may include:

● hardware interrupts of units

● an RmIO SVC

● a timeout

● a re-initialization

● completion of an I/O request.

A driver needs to provide one or several procedures for each event that are called either by the nucleus or an interrupt routine. The procedures can be called independently. The procedures interact by means of data structures to obtain a proper response of the driver to requests from the RMOS3 nucleus and the units. The driver entry points are used when you configure the system.

Figure 3-1 Call environment of driver programs



3.2.1 Driver initialization

Initialization procedure All drivers are registered in RMOS3 by means of a data structure that is called the DCD block. During system start-up (boot process), RMOS3 calls each driver that is identified as ready in the DCD block by means of an event flag (DCDFLAGS: bit 2 = 0). Each driver must contain an initialization procedure, even if the unit does not need initialization. The start of the initialization procedure is defined in the DCD block (DCDINIT component). If driver initialization can be dispensed with, this program will consist merely of a RETURN command.

Setting units to their initial state The call of the initialization routine at system start-up enables the driver to set the managed controllers and their connected I/O devices to a defined initial state, before requests are output to these units. The driver can initialize its own internal data structures and buffers, reset the controllers and I/O devices, enable the corresponding controller interrupts, and run any other initialization routine that may be necessary.

3.2.2 Processing driver requests

Using SVC RmIO A unit can be activated by a user application if a task outputs an SVC RmIO to RMOS3. This represents the central call for all driver functions.

Syntax Syntax of system call RmIO:

#include <rmapi.h>

int RmIO(

uint Function,

uint DeviceID,

uint UnitID,

uint FlagID,

uint FlagMask,

RmIOStatusStruct *pState,

void *pParam);

Parameters SVC RmIO contains global and driver-dependent parameters.



Global data structures The following parameters of SVCs RmIO are valid for all drivers:

Table 3- 1 Parameters of SVC RmIO

Parameters Function Function This parameter defines the operations to be executed by the unit and all

control variations. Bit Meaning 7 If set (=1), the I/O request is executed immediately (preemptive bit) 6 Wait for I/O completion if set (=1) 5 If this bit is set, all queued I/O requests (provided the driver controls

this bit) and the currently processed I/O request are terminated with – 4 error status. A new opcode must be passed simultaneously with the CANCEL function.

4 Reserved (must be set to 0) 3 2 1 0

Opcode (00H – 0FH). The following operation codes are uniform for all drivers: 00H – Reserve unit 01H – Release unit 02H – Read 03H – Write All other combinations can be used to suit requirements and are specific for each driver. To reserve a unit means that only the calling task controls the unit. I/O requests from other tasks are not processed until a unit is released, or a timeout has been triggered.

DeviceID ID (identification code) of the driver. The driver is assigned an identity code at system start-up, namely the device ID. All RmIO calls addressing the driver must use this ID.

UnitID Identity code that designates the subunit of the driver during system start-up. FlagID ID of the flag group in which the job processing state is to be indicated. FlagMask Flag mask that indicates the processing state of the job in the flag group.



Parameters Function pState This parameter is a dword address for an 8-byte field in the data segment. The

first part contains the primary status code, while the second byte represents the secondary status code. The next two bytes form a 16-bit word that contains driver-specific return values (usually, the number of actually transferred bytes in I/O operations). The next four bytes are available for driver-specific use. The following agreements for the primary status code are valid for all drivers: 0 The I/O request is queued for processing (at a later time). 1 The I/O request is being processed 2 Successful completion of the I/O request -1 The I/O request was aborted with error due to the entry of an incorrect

RmIO parameter. -2 The I/O request of the type RESERVE or RELEASE was aborted with

error due to one of the following facts: The unit in question was already reserved An attempt was made to execute an incorrect release (e.g. the unit is already released).

-3 The I/O request was aborted due to timeout -4 The I/O request was terminated by a "CANCEL" function. Note: A negative primary status code always indicates an error state. All other positive or negative termination codes can be defined by the driver. The secondary status byte and the second status word depend on the driver implementation.

Driver-dependent parameters The following parameters depend on the addressed driver:

● the function to execute (BIT0 – BIT3 in parameter Function),

● the length and content of the parameter block (pParam)

● the content (not the length) of the status block (pState).

Typical contents of the parameter block include the number of bytes, special functions, I/O buffer addresses, or timeout values. The status block returns diverse error code and status messages.

Sequence of SVC RmIO General sequence of SVCs RmIO:

The SVC RmIO of an application task causes a software interrupt. The nucleus validates the ID of the driver and unit, and the flag ID. If validation fails, RMOS3 terminates the I/O request and returns a value unequal 0.



If it accepts the SVC, the nucleus resets the event flag bits that are specified at the FlagID and FlagMask parameters. The nucleus checks whether or not "Wait for completion" is specified at parameter Function (BIT 6 = 1). If the wait state is necessary, the nucleus sets the task to BLOCKED state until the I/O request is completed and then transfers the request to the driver.

To transfer the job to the driver, the nucleus allocates an I/O request block (IRB), taken from an internal list of free data structures (SMRs), to which such data as the RmIO parameters, the task priority and task ID are copied, and then passes the control to the requested driver. The driver entry point is defined in the DCD block (DCDSVC) and serves to initiate processing of the RmIO by the driver.

The driver must determine whether to execute the request immediately, or whether it needs to be transferred to the queue. It initiates processing if able to execute the request immediately.

Execution of the I/O request by the driver is referred to as I/O operation. At the end of the I/O operation, the driver writes the current status that provides information about the sequence of the operation to a status field of a length of 8 byte. Control is then returned to the nucleus that sets the event flag bits specified at the FlagID and FlagMask parameters.

Synchronization of the task execution after termination of the SVCs RmIO is handled by the SVC RmGetFlag based on the event flags defined at FlagID and FlagMask , by setting the wait bit at parameter Function , or by polling the primary status byte.

3.2.3 Interrupt processing in drivers Interrupts serve for synchronization of the driver states and the hardware, meaning that the hardware reports a specific state to the software (e.g., that a character can be read). Every driver that is synchronized by means of interrupts contains at least one or several entry points for jumps from an interrupt routine. It is necessary to provide several different entry points, for example, if the driver operates several controllers of different types (e.g. timer and V.24 controllers). The nucleus loads the UCB address to the EBX register prior to the start of interrupt handling by the driver.

Note

Drivers using interrupts can only be started on PL0.

Expected and unexpected interrupts Depending on the status of the driver or unit, a distinction is made between expected and unexpected interrupts.

Expected interrupts, for example, signal termination of a processing step by the hardware and initiate the next processing step, or a status transition at the driver.



An unexpected interrupt (e.g. no request pending for this unit) is processed according to the requirements of the unit that caused the interrupt. If the unexpected interrupt does not make sense for the unit, an error which the driver has to respond to may have occurred (e.g. simply by ignoring the interrupt). However, if an unexpected interrupt does make sense, a typical reaction of the driver may be to save a character to an internal buffer, or to start a task for processing the event.

3.2.4 Timeout monitoring in the driver

Monitoring by the nucleus When initiating a processing job, the driver can request timeout monitoring by the RMOS3 nucleus.

If a timeout is now triggered while the request is being processed, the nucleus triggers a jump to the driver procedure for execution of this timeout. The driver reports the entry point to the nucleus when processing the timeout request. Following its call by the nucleus, the timeout procedure of the driver must initiate the necessary measures (typical actions are repetitions, or the return of an error message).

3.2.5 Completing an I/O operation

Driver tasks on completion The driver executes the following functions on completion of the I/O request (usually, by means of the call of subroutines provided by the RMOS3 system):

● Canceling the timeout monitoring that was requested during initiation of I/O processing.

● Setting the event flags that were specified in the RmIO SVC, and setting the READY state for the tasks that were waiting for the event flags which are now set.

● Return of the completion status in I/O state.

● Setting the address for operation of the unexpected interrupt, if necessary.

● Determining whether the requesting task is waiting for completion of the RmIO function; if yes, it must be returned to the queue of the tasks in READY state.

● Determining whether or not a different RmIO SVC is waiting for operation; if yes the next processing sequence is initiated.

Note

All subprograms are of the type NEAR; for this reason, the driver code must be available in segment RM3_CODE32.

Driver development 3.3 Data structures


3.3 Data structures

Overview of the data structures The procedures of a driver are called independently. In order to achieve a proper response of the driver for the RMOS3 nucleus and the various I/O devices, the driver programs must be customized to suit unit requirements and exchange information with regard to the respective states of the processing requests and I/O devices.

These actions are handled by means of data structure. The driver procedures are influenced by the content of these data structures in terms of their program runtime.

The data structures again are linked by means of pointers and form a logical image of the structure of the I/O devices.

This section describes all data structures, including their interdependencies, which the RMOS3 drivers use, or to which the drivers are related. The data structures are named as follows

DCD: Driver control data

DCB: Driver control block

UCD: Unit control data

UCB: Unit control block

IRB: I/O request block

TMB: Timer monitor block

The DCD and UCD data structures contain constant values. These structures are initialized during configuration and are usually stored in the ROM area. The nucleus copies a UCD that is stored in RAM to a separate data area in response to RmCreateUnit().

The DCD data structure is used to report the existence and type of the driver to the RMOS3 nucleus. DCD data structures are organized in arrays, with each array being identified by an ID code (driver ID).

UCD data structures are organized in arrays, as well (each one with separate unit ID). Parameters for the driver programs define the number and start of the array of UCD data structures. All necessary constants (e.g. port addresses) are defined in the UCD data structure to enable proper operation of an I/O device or of its controller by the driver.

A data structure is automatically reserved in RAM during configuration for each driver and the units it manages and controls.

DCB: data structure assigned to the driver

UCB: data structure assigned to the unit

In addition to a global part, these data structures are also set up with a driver-specific part because certain procedures of the nucleus will also access these data structures.

The nucleus copies each SVC RmIO of an application task to an IRB data structure. The IRB data structure is allocated from a free list of multipurpose data structures, namely the SMRs. The IRB data structure is released again once the driver has completed the processing job. The program sequence of the requesting task and job processing by the driver are decoupled by copying the SVCs to a specifically allocated data structure. This copy process does not concern the parameter block for the I/O request, but only its address.



The driver can set up a timer monitor block (TMB) if necessary for handling a timeout. The RMOS3 nucleus modifies the TMB accordingly. The nucleus transfers timeout events for further handling to a driver procedure. The driver must write the corresponding entry point address to the TMB.

3.3.1 Driver control data (DCD) The DCD (Driver Control Data) encompasses a data structure that is created in the course of configuration. This data structure is used to report the existence and type of the driver to the RMOS3 nucleus. The essential parts of the data structure include the specification of the entry point address, the number of units to manage, and the driver type. All parameters of this structure are fixed constants that are stored in segment RM3_CODE32. This structure is passed to the nucleus for each driver with RmCreateDriver.

Table 3- 2 DCD block

Array Size Description UCD 4H Reserved UNITS 1H Reserved SHR 1H Identity code (ID) of a different DCD that also uses this control (0FFH =

none). Not used by type II drivers (always 0FFH).

INIT 4H Start address of the driver initialization routine (DWORD, EIP/CS)

SVC 4H Type I driver: address of the RmIO system utility (DWORD, EIP/CS) Tye II driver: address of the branching table for the driver functions, starting with code 2 (DWORD)

FLAGS 1H Driver flags: The corresponding bit is set to 1 by specifying the parameter. RM_DFL_PARA Bit 0 = 1 Parallel driver

Bit 0 = 0 Serial driver RM_DFL_TYPE2 Bit 1 = 1 Type II driver

Bit 1 = 0 Type I driver RM_DFL_DORMANT Bit 2 = 1 Driver not initialized after

system initialization and set to DORMANT state.

Bit 2 = 0 Driver was also initialized after system initialization and is in ready state

FMAX 1H Maximum function code for type II drivers. This value is equivalent to the number of entries in the branching table + 1

4H 4 reserved bytes, set to 0

Total scope: 14H



Note

References to DCD data structures are facilitated by means of the assignment of default values and are saved to the RMTYPES.H and RMDEF.H files in directory INC. The default value assignments are added to the driver in the compiler or assembler session.

Driver-specific parts can be assigned new definitions for each driver.

3.3.2 Driver control block (DCB) The DCB (Driver Control Block) contains all driver-specific data. The structure is created in segment RM3_DATA.

This data structure is particularly useful for storing the variables for managing driver states. These status variables are relevant to all I/O devices.

Note

The RMOS3 nucleus creates and, if necessary, initializes this data block for each driver. References to DCB data structures are facilitated by means of the assignment of default values and are saved to the RMTYPES.H and RMDEF.H files in directory INC. The default value assignments are added to the driver in the compiler or assembler session.

Driver-specific parts can be assigned new definitions for each driver.

Table 3- 3 DCB

Array Size Description LINK 4H Cross-reference/link to the next DCB ID 1H Driver ID STS 1H Driver status

Bit 0 = 0 Not busy Bit 0 = 1 Busy Bit 1 - 7 User-definable

QIRB 2H I/O request block, IRB queue (serial driver) CIRB 4H Currently processed IRB (serial driver) UCB 4H Cross-reference/link to the next unit control block (UCB) DCD 4H Address of the driver control data (DCD) GPR 0EAH Memory space for status variables (driver-specific)

Total scope: 100H

RMOS3 initializes the content of the DCB data structure at the call of RmCreateDriver: DCB.LINK, DCB.ID, DCB.UCB, and DCB.DCD are initialized with the respective values. All other variables are set to zero.

DCB.CIRB and DCB.QIRB are valid for serial drivers. Serial drivers cannot operate more than one unit at any given time. For this reason, the RmIO requests (IRB data structures) are appended directly to the driver data structure and not to the unit data structure (UCB).



3.3.3 Unit control data table (UCD) The UCD (Unit Control Data) encompasses data structures that contain all constants which are necessary for managing and controlling an I/O device and its controller. The nucleus copies this data structure from any data segment in which it is stored to RM3_DATA; otherwise, it is retained in RM3_CODE32. Only this data structure is used to make an I/O device known to the driver and to initialize it

The data structure contains a general and a unit-specific part. The general part contains the specification of the task ID that is to be started following an unexpected interrupt (provided this option is supported), as well as the specification of an interrupt vector and handler.

The interrupt vector and handler entries in the UCD block are optional and usually made in a different part of the configuration to obtain a clear overview of the interrupt vectors used.

The absolutely most important part of the entire data structure are the 0F6H bytes that you can occupy with driver specific constants. All address specifications, controller types, operating modes, and initialization sequences must be set up in these constants.

The UCD data structure must be created and initialized separately for each unit in the course of system configuration. References to UCD data structures are facilitated by means of the assignment of default values and are saved to the RMTYPES.H and RMDEF.H files in directory INC. The structures for device specific parts of the UCD are defined in DRVSPEC.H for units included with your package. The Rc..configuration calls preset the UCDs and report these to RMOS3 with RmCreateUnit. Driver-specific parts can be assigned new definitions for each unit.

Table 3- 4 UCD block

Array Size Description PID 1H reserved

Bit 6 = 1 RioByteUnit (RM_RIOBYTE) Bit 7 = 1 RioBlockUnit (RM_RIOBLOCK)

INTNO 1H Interrupt vector number (0= no interrupt) INTADR 6H Address of the interrupt handler routine (DWORD)

For units that can be transformed into a system console (RM_RIOBYTE), you can specify the address of an emergency Putchar function in UCD.INTADR (UCD.INTNO=0) that is reported to the x_nucprintf function at changes of the system console with SVC RmSetPutcharProc .

UNS 2H Interrupt task for unexpected input/output (–1 = ignore) PORT 0F6H Driver specific constants: addresses, operating modes, controller types,

unit initialization

Total scope: 100H



3.3.4 Unit control block (UCB) The UCB (Unit Control Block) contains all driver-specific data. The data structure is stored in segment RM3_DATA. This data structure is particularly useful for storing the variables used to manage I/O device states. Device states, for example, could be interrupts pending, or a unit reservation.

All UCB data structures contain a general and a driver-specific part.

The general parts are initialized at the call of function RmCreateUnit. The RMOS3 nucleus can also access these general UCB parts at runtime, e.g. when creating IRB queues (type II drivers). References to UCB data structures are facilitated by means of the assignment of default values and are saved to the RMTYPES.H and RMDEF.H files. The default value assignments are added to the driver in the compiler or assembler session.

Each unit-specific parameter of the UCB data structure can be redefined by means of local value assignment. You may also redefine data words with different values for each driver.

Table 3- 5 UCB block

Array Size Description LINK 4H Cross-reference/link to the next UCB of this driver (0 = end of the list) UNIT 1H Unit ID STS 1H Unit status

Bit 0 = 0 Not busy Bit 0 = 1 Busy Bit 1 - 7 Free for use

QIRB 4H I/O request block (IRB) queue (used if the driver is capable of simultaneously processing requests for several units)

CIRB 4H Currently processed IRB request block SEG 2H UCD segment DCB 4H Address of the DCB (driver) that controls this unit UCD 4H Address of the UCD data structure TCB 4H TCB of the task that has reserved this unit

(0 = not reserved) GPR 0E4H Variables

(can be defined for the driver)

Total scope: 100H

RMOS3 initializes the content of the UCB data structure at the call of RmCreateUnit: UCB.LINK, UCB.UNIT, UCB.DCB, and UCB.UCD are initialized with the respective values. All other variables are set to zero.



3.3.5 I/O request block (IRB) An IRB (I/O Request Block) is created for each SVC RmIO. The IRB is decoupled from an internal list of free SMR data structures by means of an RmIO.

SMR memory blocks represent data structures that the system needs for various purposes (e.g. for creating an IRB). You may configure the number of SMR blocks.

The nucleus then copies the RmIO parameters, the task priority and task ID to the IRB data structure, for example, and passes the control to the selected driver (entry point in DCD.SVC). The driver must determine whether to execute the request immediately, or whether it needs to be transferred to a queue at the DCB (serial driver), or at the UCB (parallel driver).

Table 3- 6 IRB block

Array Size Description LINK 4H Cross-reference/link to the next IRB (0 = end of the list) PRI 2H Priority of the I/O request TCB 4H Pointer to the TCB of the requesting task UCB 4H Pointer to the associated UCB TMB 4H Address of the timer monitor block that is assigned to this IRB. Copy of the current SVC parameters: RIO 1H SVC number FUNCT 1H Parameter FUNCTN DEVICE 1H Parameter DEV_ID UNIT 1H Parameter UNIT_ID GRP 1H Parameter FLG_ID FLAGS 4H Parameter FLG_MASK STATUS 6H Parameter STATUS_PTR BUFR 6H Parameter PARM_PTR SEQ 2H Reserved

Total scope: 29H



3.3.6 Timer monitor block (TMB) A TMB (Time Monitor Block) is always set up if it is necessary to monitor the timing of a request. The nucleus creates the data structure. Depending on the driver type, this data structure is initialized either directly by the driver (type I driver), or by nucleus subprograms (type II driver). The nucleus employs this data structure to control the time management of SVCs.

TMB.TYPE must be set to 1 to indicate a unit timeout. The data structure is in the RMTYPES.H file in directory INC.

Table 3- 7 TMB block

Array Size Description LINK 4H Cross-reference/link to the next TMB (0 = end of the list) LTIME 4H Monitored interval in ms

(low Dword) HTIME 4H Monitored interval in ms

(high Dword) TYPE 1H Must be 1: Unit timeout.

All other values are reserved 1H Reserved UCB 4H UCB of the unit monitored with timeout SADR 4H Entry point address for timeout processing (EIP) 6H Reserved

Total scope: 1CH



3.3.7 Link of data structures

Serial driver A serial driver can only process one IRB request at any given time (resultant from an SVC RmIO). This is possibly due to the type of implementation, but is´usually related to the existing hardware. A typical example are several floppy disk drives that are addressed by one controller. If this controller cannot process several drives simultaneously, the driver is forced to manage all requests for the various units (in this case the drives) and process these in successive order. This is handled by appending the IRB data structures as queue directly to the DCB data structure of the driver. The UCB data structure represents the central data structure for the driver. All other data structures are interconnected by means of this data structure. This data structure is passed as parameter at each call of the driver procedures. All other information and data structures can be derived from this structure.

Figure 3-2 Serial driver (one controller for several units)



Parallel driver A parallel driver processes one IRB request initiated by an RmIO at any given time. All other requests for this unit are queued and processed at a later time. This is handled by saving the IRB requests to a queue that is appended directly to the UCB data structure of the unit. This data structure represents the central initiation point. The UCB data structure is passed as parameter at each call of the driver procedures. All other information and data structures can be derived from this structure.

Figure 3-3 Parallel driver (one controller per unit)

Driver development 3.4 Operating system support for drivers


3.4 Operating system support for drivers

3.4.1 Driver subprograms All routines in the S state are considered as system processes. All system processes are executed in serial mode until terminated automatically. The operating system core supports the functions of system processes by means of system variables and driver subprograms. These driver subprograms are called from the S state if not specified otherwise and support the allocation of memory space, communication with the tasks, and the management of RMOS3 data structures.

Figure 3-4 System processes

Note

In RMOS3, all subprogram calls are of the type NEAR; for this reason, the driver code always has to be available in segment RM3_CODE32.

The parameters for these subprograms are passed with the help of static transfer variables. These transfer variables are reserved exclusively for system processes and may not be influenced by interrupt handlers in DI or I state. These transfer variables are also used to transfer parameters to driver entry points for handling RmIO requests.



Assembler The following functions can only be used in assembler routines:

Table 3- 8 Driver functions for assembler routines

Function Description X_ELIPSE Change from DI to I state X_SYSTATE Change from I to S state X_SYSTATE_SW Change from I to S state without EOI X_XEL Change from I state to the scheduler X_XEL_SW Change from I state to the scheduler without EOI

Assembler and C The following functions are available for programming in assembler and in C:

Table 3- 9 Driver functions for assembler and C routines

Function Description XCATALOG Enter in the RMOS3 resource catalog XCHANGEDESC Change the descriptor base and/or limit XCHANGEDESC-ACCESS

Change the access byte of a descriptor

XCREATEDESC Create a descriptor XDELDESC Delete descriptor specified by means of selector XDELTMB Remove TMB from the monitor list XDEVDATA Calculate XDCB and XUCB based on XDEVNUM and XDEVUNIT XDQTMB Removing a TMB from the monitor list without releasing it. XDWORD Conversion of the offset address of an RMOS3 data variable into a

Dword address. XERRLOG Log error at the system console, if available (error logger task) XEXSYS Exit the S state (end system process) XGETSMR Request system memory block XHALOC Allocate memory space from a pool XHDALOC Release memory space XIODONE Complete processing of SVC RmIO for type I drivers XOVER, xjmp_xover Conclusion of I/O request for type II drivers in C XPHYSADR Determine the physical address XPUTSMR Return system memory block XQPIRB Add current IRB to the queue of a parallel driver XQSETUNS Queue start of a user task for unexpected interrupts XQSIRB Add current IRB to the queue of a serial driver



Function DescriptionXQSTRT Add task start request to queue XQTMB Add TMB from the monitor list to the queue XRECV Receive message from local mailbox XREF Reset event flag XSEF Set event flag XSEND Send message to local mailbox XSETUNS Start user task for unexpected interrupts XSYSTEM Change from DI state to system state XTEF Test event flag XTIMEOUT Set up unit timeout (only type II drivers)

3.4.2 System variables for parameter transfer The following variables are used to pass parameters to the subprograms of the nucleus and to pass parameters returned by the operating system kernel. All variables may only be used in S state. Table 3- 10 System variables

Name Description Length XCIRB Address of the current I/O request block (IRB) 46 bytes XDEVNUM Current driver ID 11 bytes XDEVUNIT Current unit ID 11 bytes XUCB Current UCB address 46 bytes XDCB Current DCB address 46 bytes XERRMSG Address of an error message 46 bytes XOFFSET OFFSET address; general-purpose 24 bytes XPOINTER OFFSET/SEGMENT address; general-purpose 46 bytes XSTATUS Status data to be returned to the task 48 bytes XTUNIT Time interval for timers 11 bytes XTNUM Number of time intervals for timers 1 byte XPOOLNUM memory pool-ID for XHALOC and XHDALOC 1 byte XBLKLEN Number of bytes for XALOC and XDALOC 4 bytes XSEQ Sequential number of the current IRB 2 bytes XSEG Selector for segment handling 2 bytes XSEGLIM Segment limit 4 bytes XTASK Task ID 2 bytes XPRIS Options for priority source 1 byte XPRIV Priority to be used 1 byte XP1 Parameter 1 4 bytes XP2 Parameter 2 4 bytes XGRP Global event flag ID 1 byte XFLAGS Mask for flag group 4 bytes XBOX Local mailbox ID 1 byte XGENB General-purpose byte 1 byte XGENW General-purpose word 2 bytes XGEND General-purpose dword 4 bytes



3.4.3 Differences between type I and type II drivers RMOS3 supports two different interfaces for drivers. We speak of a type I or type II driver, depending on the interface that is required. Since type II drivers are provided more support by the subprograms of the nucleus compared to type I drivers, it is easier to program type II drivers. You need to program this nucleus support for the interface for type I drivers yourself.

The significant differences in the interfaces for type I and type II drivers are in particular:·

● Handling of the RmIO parameter Function

● Reserving and releasing units

● Handling timeouts

● Update of status bits·

● Job completion

● Support by subprograms

These differences are highlighted in the following sections:

Handling the RmIO parameter Function The type I driver has only one entry point for handling RmIOs and needs to operate and execute all functions by itself, dependent on parameter Function.

The type II driver has a jump table for handling the functions. The nucleus employs this jump table to jump to a driver procedure following an RmIO, dependent on parameter Function. The driver jump table begins with function 2, as the functions 0 (reserve unit) and 1 (release unit) are already implemented on the operating system core. Possible syntax of a jump table for a type II driver for handling an RmIO : BRANCH_TBL DD READ_BLK ; code 2: read a block DD WRITE_BLK ; code 3: write a block DD CLEAR_UNIT ; code 4: reset unit

The nucleus jumps directly to the procedures identified by the addresses in the table if requests to the driver with the corresponding functions are pending. The nucleus directly calls the WRITE_BLK procedure, for example, if a request with function code 3 is pending.

Note

In RMOS3, the jump table consists of the offset address (32-bit). The code must be available in segment RM3_CODE32.

Driver development 3.5 Notes on driver implementation


Reserving and releasing units The reserve or release functions are implemented completely in the operating system core for a type II driver. A unit can only be released by the task that has executed the reserve function. When bit 7 of parameter Function is set and the I/O device is currently processing an I/O request, the priority of the I/O request is raised to 255 and the IRB block is written to the first position in the queue after any preemptive requests that may already be queued. A reservation of the unit by a different task will be ignored.

Handling timeouts A timeout event at the type I driver must be handled entirely by the driver. This provides greater flexibility and scope to programmers.

A timeout event at the type II driver is handled by the nucleus, but may also be handled by the driver itself.

Updating status bits The nucleus sets or resets bit 0 (status) of DCB.STS or UCB.STS (serial/parallel) for type II drivers.

Terminating a job The type I driver terminates an I/O request. Following this action, the type I driver itself then needs to scan the request queue and possibly initiate the next processing sequence. This also facilitates the handling of the sharing of a unit with a different driver (if it is necessary to implement this property).

The type II driver terminates an I/O request by calling a nucleus procedure. This procedure manages the I/O request queue of this driver. The driver is reactivated by means of the jump list if the queue contains another request.

Support by subprograms Both driver interfaces are supported by subprograms. The subprograms partially support only one interface type.



3.5 Notes on driver implementation Drivers are part of the RMOS3 operating system. Drivers belong to the most complex programming tasks because timing and concurrent aspects play a significant role. For this reason, you should avoid greater complexity by dispensing with unnecessary functions. The drivers should be as simple as possible to suit simple requirements. Any DI and I system states used must be understood and used properly.

Note

A driver error may cause a system failure. For this reason, the drivers need to be designed, coded and tested with meticulous care!

3.5.1 Data and stack environments of driver programs

Important rules for using the stack The driver may only use the current stack, the DCB, the UCB, and specific RMOS3 PUBLIC SYMBOLS (starting with "X", followed by any valid symbol except "_"). Strictly observe this rule.

The sole exception is that in assembler the driver may use the subprograms beginning with "X" mentioned in the earlier section. Local variables may also be created on the stack (caution: observe the stack depth) but are are only valid within one runtime state. The stack must be used with meticulous care, because the program will change to the RMOS3 system stack at transitions from the DI to the I or S state. Moreover, parameters such as driver or unit states may not be transferred to other program sections of the driver (e.g. an interrupt handler) via the stack; always use driver-specific or unit-specific variables in the DCB and UCB data structures instead. A driver may never modify the current stack segment or stack, not even on a temporary basis.

All drivers can create their own variables in the driver-specific section of its DCB block. These variables can be addressed from all entry points of the driver. Interrupt handlers of RMOS3 drivers are assigned a pointer to the corresponding UCB block as parameter before the entry point of the driver is called. All unit-specific status variables are saved to the unit-specific section of the UCB block.

The following listing highlights the driver environment, depending on the RMOS3 operating states.



Stack The nucleus sets or resets bit 0 (status) of DCB.STS or UCB.STS (serial/parallel) for type II drivers.

DI state The stack may be used, but must have been returned to its original state

when the program exits the DI state. I state The stack may be used, but must have been returned to its original state

when the program exits the I state. S state The stack may be used. The scheduler resets the stack on completion of a

system process, which means that no parameters can be passed on the stack to other driver programs. However, it is always possible to pass parameters on the stack for subprogram calls.

UCB and UCD block The UCD data structures are stored in segment RM3_CODE32 or RM3_DATA, while the UCB data structures are stored in segment RM3_DATA.

DI state The specific parts of the data structures may always be modified (e.g. for

use as variable or shadow register). I state See DI state S state See DI state

Internal data structures Internal data structures (e.g. buffers).

DI state These data structures may always be changed. The nucleus does not

provide support for these data structures by means of subprograms. Observe the naming conventions for these structures.

I state See DI state S state See DI state

Registers DI state All registers used must be retrieved and be restored when the program

exits the DI state. I state All registers are available S state All registers are available



Definition of the data structures All RMOS3 data structures are defined in include file EQUS.EQU with EQU instructions (for C in RMTYPES.H). This file should be linked accordingly to each assembler driver by means of "$INCLUDE (:F1:EQUS.EQU)" control instruction.

3.5.2 Resetting/Initializing units Each driver has an entry point to a program that resets/initializes the units controlled by this driver. RMOS3 always uses this entry point if one of the following conditions is met:

● System initialization

● System reset

All interrupts are disabled for the duration of the reset/initialization process. The RMOS3 nucleus determines the entry point address for each driver based on the DCD data structure (component DCD.INIT) and executes a subprogram call (NEAR). For each unit of the driver, RMOS3 outputs a subprogram call to the driver for executing a reset/initialization routine. The program returns from the initialization routine by executing the RET command. The driver must ensure that the specified unit is reset and initialized at each call and then initiate the return to RMOS3. Interrupts may not be used to this effect.

The nucleus sets the following parameters and registers for the reset/initialization subprogram calls:

XDEVNUM Contains the current driver ID XDEVUNIT Contains the current unit ID XUCB Pointer to the current unit control block (UCB data structure) XDCB Pointer to the current driver control block (DCB data structure) ES register Undefined DS register RM3_DATA

The scope of the program section for reset/initialization procedures in the driver depends on the properties of the respective units to be operated. The units must be released at least for processing I/O requests. The nucleus completes the following steps prior to the call of the reset/initialization routine:

● Deleting the DCB and UCB data structures (reset to zero) and resolving specific queues

● The nucleus initializes parts of the DCB and UCB arrays

The initialization program of the driver only needs to handle initialization of the units or controllers, and set the driver-specific variables in the corresponding UCB and DCB data structure. All transfer parameters (z.B. XDEVNUM, XDEVUNIT, ...) of the RMOS3 system are stored in segment RM3_DATA.



The ASSUME instruction for a driver has the following syntax:

"ASSUME DS:RM3_DATA, SS:RM3_DATA"

Note

The assume instruction for the code segment may not be used in programs that are compiled with ASM386.

DCD blocks are stored in segment RM3_CODE32, i.e. within the executable code. UCD blocks may also be stored in this segment; if not, the nucleus copies these to RM3_DATA.

3.5.3 Creating and deleting device drivers RMOS3 allows you to define a driver (RmCreateDriver) and to suspend it (setting it to BLOCKED state with SVC RmSuspendDriver).

RmResumeDriver launches the initialization routine of the driver, while RmSuspendDriver only sets the DCB flag RM_DFL_DORMANT (refer to section "Driver control data (DCD) (Page 70)").

Repeated creation or deletion of a driver may possibly pose a problem if the driver requests memory space for the initialization routine, because this memory space is not released automatically when a driver is deleted.

When the driver is recreated with RmResumeDriver, it requests memory space that it already occupies. The resultant waste of resources may even lead to a system crash in certain situations.

A feasible solution is that the driver sets a flag bit in the UCB of each unit that indicates whether or not it was already initialized once before, and then read this bit to decide on the actions to be taken.

Sequence RMOS3 initializes the UCB of all units with a 0 value (refer to section "Unit control block (UCB) (Page 73)").

When initialized, the driver reads the corresponding UCB bit and, based on the 0 value, recognizes that it is being initialized for the first time. It sets the bit to 1 and continues its initialization routine as usual.

The driver reads the UCB bit again if it is suspended with RmSuspendDriver and reset to READY state with RmResumeDriver. Since this bit is set to 1, the driver can recognize that it was initialized once before. The memory space requested during the first initialization now needs to be released again (XHDALOC), or the driver may not request any memory space.

A similar problem arises when a driver catalogs itself (XCATALOG).

Based on the method mentioned earlier, the driver can use the UCB bit to decide whether or not to catalog itself (bit = 0), or whether it is already cataloged (bit = 1).



3.5.4 Initiating SVC RmIO

Overview RMOS3 first validates the following parameters when an SVC RmIO is executed: the driver ID, the unit ID, and the event flag–ID. If one of these parameter is outside the valid range, the user task is informed accordingly with a "rejected system call request" return value (the status is also returned by means of the status of the processor flags).

Are all parameters in the valid range, RMOS3 verifies that the function includes a "Wait until I/O operation was executed". If yes, the requesting task is removed from the READY queue and its task status is set to "Waiting for completion of the I/O request".

If the basic parameters are found valid, processing of the SVC is passed to the driver. The driver is now running as system process. The driver first needs to check whether an executable function will be requested, and then validate the passed parameters. The parameters are stored in the IRB data structure

If the function parameter is faulty or one of the other parameters is invalid, the driver executes the I/O termination routine (XIODONE - refer to section "I/O termination for drivers") and returns an error code. In addition, it sets the status in an array of a length of 8 bytes that was defined by a pointer at the call.

The return value indicates the cause of the error. The task must then evaluate the status array. If XIODONE is called before the request has been added to the IRB queue and a different call is currently executed, UCB.CIRB or DCB.CIRB must be written to a buffer because XIODONE deletes these parameters if congruent with XCIRB.

It is much simpler to immediately add all requests to the IRB queue and wait for the verification of the parameters until the requests are being processed. Certain requests such as "Preemptive bit is set" must be handled immediately.

An I/O request that is the only element in the queue is processed immediately. For this purpose, the corresponding process must be initiated and the status information for the interrupt handler has to be updated and conditioned (e.g. to be able to distinguish between an expected and unexpected interrupt).



3.5.4.1 Handling the SVC RmIO for type I drivers

System call interface for type I drivers The SVC entry point for the driver is reached by means of a FAR (inter-segment) CALL. RMOS3 determines this entry point based on the DCD data structure of the driver (component DCD.SVC). The return to RMOS3 is executed with the help of the RETURN command. Along with the RETURN command, the control is returned to the RMOS3 scheduler. RMOS3 sets up data structures, initializes system transfer parameters, and presets the register values prior to the jump to the driver:

● The dword address of the IRB request block to process, in which the RmIO parameters are stored, is entered in XCIRB.

● The IRB contains the address of an assigned timer monitor block (component IRB.TMB) that was created by the nucleus. This TMB can be used to set timeouts.

● Byte variable XDEVNUM contains the driver ID.

● Byte variable XDEVUNIT contains the unit ID

● XDCB is a pointer to the corresponding driver control block (DCB data structure) of the driver (dword address).

● XUCB is a pointer to the corresponding unit control block (UCB data structure) of the unit (dword address).

● The status bytes (addressed by the RmIO parameter STATUS_PTR) are preset with zero value.

● Processor register DS addresses the RM3_DATA segment.

Processor register SS addresses a stack in the RM3_DATA segment.

Processing of an RmIO by means of type I driver The driver takes the following steps to initiate processing of an I/O request:

1. Validation of the function request and of the other I/O parameters. If a faulty parameter was found, the driver calls the RMOS3 I/O termination routine XIODONE. Prior to calling the completion routines, the driver needs to set the error display in an 8–byte XSTATUS array. The completion routine copies these 8 bytes to the status array that is addressed by the RmIO parameter status_ptr.

2. Check whether the function is a CANCEL request. A CANCEL request needs special processing and depends on driver requirements. While CANCEL is being processed, you should set UCB status UCB.STS (user-defined driver states) to CANCEL. The CANCEL state or driver states should be used to report a special situation that originates from interrupts possibly triggered by the unit to the activated interrupt handler.

Execution of the CANCEL function includes that all requests for the affected unit are terminated in the IRB queue (resolving the IRB queue with corresponding status messages). A further possible measure could be to reset and re-initialize the unit or controller. On completion of the handling of the CANCEL request, it is imperative to revoke the CANCEL state.



3. Once it has verified the RmIO parameters, the driver must decide whether it needs the timer monitor block that was assigned in advance (the address is available in component IRB.TMB of the IRB data structure). If not, the Delete Monitor Block Routine XDELTMB is called to release this system resource again (cf. item 7). The routine needs the correct address of the UCB block in system transfer parameter XCIRB.

4. The type I driver needs to decide whether or not the current IRB is to be added to an IRB queue. The queues represent linear lists that are sorted based on priority (equivalent to task priority, except the preemptive bit). The I/O queue for serial drivers processing RmIO requests in successive order is linked to a pointer in the DCB (component DCB.QIRB). An I/O queue is generated per unit for parallel drivers that simultaneously handle several unit requests. The queues are assigned to the pointer in the respective UCB (component UCB.QIRB).

The driver first needs to determine whether or not it is currently busy handling a different request by evaluating the BUSY status bit in UCB.STS at parallel drivers and in DCB.STS at serial drivers. At serial drivers it is possibly necessary to check the status of a different driver that shares a controller. You obtain the DCB address of this driver by calling subprogram XDEVDATA with corresponding parameters (see XDEVDATA). If the BUSY status is returned, the IRB is added to the I/O queue according to its priority.

The RMOS3 nucleus provides two subprograms for adding the current IRB data structure to the queue:

XQSIRB: Adding data structures to the queue of a serial driver

XQPIRB: Adding data structures to the queue of a unit (parallel driver)

Set the corresponding system parameters prior to the call.

5. If the status is NOT BUSY, the UCB status is polled to determine whether the unit is currently reserved (true if UCB.TCB is unequal zero). If the unit is reserved, it is checked whether it was the requesting task that reserved the unit. For this purpose, it is necessary to compare UCB.TCB and IRB.TCB. If these are in agreement, or the unit is not reserved, the IRB is treated as the current IRB. The IRB offset is then entered in the DCB (component DCB.CIRB) for serial drivers, or in the UCB (component UCB.CIRB) for parallel drivers.

If the request does not originate from the task that has reserved the unit, the IRB is added to the corresponding queue (regardless of whether the BUSY status flag of the unit is not set).



6. Once the IRB is set as current I/O request, processing of the IRB request is considered to be initiated. The driver then sets the status flag to BUSY (DCB.STS for serial drivers, and UCB.STS for parallel drivers).

If the requested function is a "reserve" (reserve), the RESERVED status is set by entering the TCB address of the requesting task (component IRB.TCB) in UCB.TCB. The "release" function resets the RESERVED state (UCB.TCB = 0).

Following the execution of the research or release function, the driver calls the subprogram (XIODONE) for completion of the I/O request. All other requested driver functions ( e.g. read or write) now need to save their parameters for handling the IRB request in cooperation with the interrupt handlers to the specific sections of the UCB and DCB data structures. The parameters depend on the implementation and may comprise the following values:

– Setting buffer pointers

– Setting counter variables

– Initialization of maximum count values or pointers

– Initialization of status variables or bits

– Initialization of entry point addresses

The programmer is responsible for proper initialization of these data areas. These data areas also represent the interface for the interrupt handlers. You may customize the entire design of this interface from the data areas to the interrupt handlers.

7. The driver can set a unit timeout. It uses the timer monitor block (TMB) that is assigned automatically to the IRB (component IRB.TMB) by the nucleus. For this purpose, it is necessary for the driver to initialize components of the TMB data structure. For this purpose, the driver writes an entry point address to the TMB data structure (component TMB.SADR). The driver also needs to initialize the TMB.TIME component. TMB.TIME is a 32–bit value that contains the time interval in milliseconds. Timeout monitoring by the nucleus is activated by means of a call to subprogram XQTMB. The TMB data structure is accordingly entered in a list that is managed by the nucleus.

8. The driver then activates the unit or its controller, depending on the respective situation. This may include release of the unit, setting control words, or any other I/O measure (e.g. output of the first data byte). Further processing and particularly termination of the job is taken over by the interrupt handlers that will possibly branch to system processes.

9. The driver program re-activates the scheduler by executing a RETURN (NEAR) command.



3.5.4.2 Handling of SVC RmIO by type II drivers

System call interface for type II drivers A type II driver provides a separate entry point for each function. The entry points must be stored accordingly in an array (array of pointers to functions). The start of the array is stored in the DCD data structure of the driver (DCD.SVC component).

The RMOS3 nucleus employs the function number minus 2 (for type II drivers, the functions 0 and 1 in the Function parameter are reserved for the nucleus) in parameter Function of SVC RmIO as offset for the function call by means of the pointer array.

The return to RMOS3 is executed with the help of the RETURN command. Control is now returned to the RMOS3 scheduler.

RMOS3 sets up data structures, initializes system transfer parameters, and presets the register values prior to the jump to the driver:

● The address of the IRB request block that is to be processed and that contains the RmIO parameters is entered in XCIRB.

● The IRB contains the address of an assigned timer monitor block (component IRB.TMB) that was taken from RMOS3 system memory. This TMB can be used to set timeouts.

● Byte variable XDEVNUM contains the driver ID.

● Byte variable XDEVUNIT contains the unit ID

● XDCB is a pointer to the corresponding driver control block (DCB data structure) of the driver.

● XUCB is a pointer to the corresponding unit control block (UCB data structure) of the unit.

● The status bytes (addressed by the RmIO parameter STATUS_PTR) are preset with zero value.

● Processor register DS addresses segment RM3_DATA.

● Processor register SS addresses a stack in the RM3_DATA segment.

Syntax of the jump table tor type II drivers:

The jump table of the driver begins with function 2, as the functions 0 (reserve unit) and 1 (release unit) are already implemented on the operating system core. The array may consist of the following data: BRANCH_TBL DD READ_BLK ; function2: read a block DD WRITE_BLK ; function3: write a block DD CLEAR_UNIT ; function4: reset unit



The nucleus calls the addresses in the table directly if requests to the driver with the corresponding functions are pending. The nucleus calls address WRITE_BLK, for example, if an RmIO request with function code 3 is pending.

Note

Offset addresses must be available in segment RM3_CODE32.

Processing of an RmIO with type II drivers The driver takes the following steps to initiate processing of an I/O request:

1. Validation of the I/O parameters. The driver must jump to the XOVER label if a faulty parameter was found. Prior to calling the completion routine, the driver needs to set the error display in the XSTATUS array. The completion routine copies this array to the status array that is addressed by the RmIO parameter STATUS_PTR.

2. Once it has verified the RmIO parameters, the driver must decide whether it needs the timer monitor block that was assigned in advance (the address is available in component IRB.TMB of the IRB data structure). If not, the delete monitor block routine XDELTMB is called to release this system resource again. The routine needs the correct address of the UCB block in system transfer parameter XCIRB.

3. Processing of a request is initiated with the jump to the function. The nucleus manages the status flag (bit 0 of DCB.STS at serial drivers, or UCB.STS at parallel drivers) that is now set to BUSY. The driver functions ( e.g. read or write) now need to save their parameters for handling the IRB request in cooperation with the interrupt handlers to the specific sections of the UCB and DCB data structures. The parameters depend on the implementation and may comprise the following values:

– Setting buffer pointers

– Setting counter variables

– Initialization of maximum count values or pointers

– Initialization of status variables or bits

– Initialization of entry point addresses

The programmer is responsible for proper initialization of these data areas. These data areas also represent the interface for the interrupt handlers. You may customize the entire design of this interface from the data areas to the interrupt handlers.



4. The driver can set a unit timeout. It uses the timer monitor block (TMB) that is assigned automatically to the IRB (component IRB.TMB) by the nucleus. For this purpose, the driver needs to initialize the components of the TMB data structure.

This is effected by the driver setting a time interval in XTUNIT and the number of time intervals in XTNUM, and calling the nucleus subprogram XTIMEOUT.

These actions also start timeout monitoring by the nucleus. In the event of a timeout, the nucleus will then terminate current I/O processing with error.

5. In the next step, the driver activates the unit or its controller. This may include release of the unit, setting control words, or any other I/O measure (e.g. output of the first data byte). Further processing and particularly termination of the job is taken over by the interrupt handlers that will possibly branch to system processes.

6. The driver program re-activates the scheduler by executing a RETURN (NEAR) command.

3.5.5 Interrupt handling by RMOS3 standard drivers Each interrupt handler of a driver must manipulate and evaluate specific variables in the DCB and UCB parameter blocks to ensure proper operation of the unit. These include:

● Correction of counters

● Incrementing buffer pointers

● Output of control or data values

● Refreshing states

Another problem is to determine the unit that is ready for operation. On the condition that each unit is provided an internal interrupt vector, it would be a solution to provide a separate entry point to the driver for each unit (different interrupt handlers). In contrast, if an interrupt vector is assigned to several units (e.g. the controller is capable of simultaneously controlling several devices, but provides only one interrupt output), the interrupt-triggering unit must be identified with the help of a polling method (applied to the registers of the corresponding controller).

The requested function may provide several sequential states. These sequential states can be implemented, for example, by re-programming the interrupt vector to the next entry point, or by means of a fixed entry point that branches to different processing steps depending on a status variable. The status variable that contains the current state is then stored in the respective DCB or UCB data structure and is updated dynamically with each processing step.

If each unit is provided at least one internal interrupt vector, you may also write a single driver program that handles the interrupt of the unit. The interrupt routine then transfers a parameter in the register to the driver program.



RMOS3 standard drivers expect that the unit, or its controller, to be managed provides at least one internal interrupt vector. This means that each interrupt can be assigned precisely to one unit. Interrupt handling is not initiated until the I is set. A direct jump to the interrupt handler of the driver is avoided to preserve RMOS3 flexibility in the configuration session. Instead, a a jump is executed to a short program segment that initiates the following steps:

1. Switch to the I state

2. Write the current UCB address of the respective device to the EBX register

3. Jump to the interrupt handler

The driver will then handle the interrupt and therefore adheres to the following sequence: DRV_INT_0 PROC FAR CALL X_ELIPSE ;I state ;All regs can be used ;[DS] := RM3_DATA ;[SS/SP] = RMOS–Stack MOV EBX, OFFSET UCB[unit] ;Unit UCB JMP NEAR PTR DRV_INT_HANDLER DRV_INT_0 ENDP

This sequence is created in the configuration data if the RmSetDeviceHandler ( IntNum, pDeviceName, pUnitName, DRV_INT_HANDLER);

call is used. <device_name> is a symbolic name in the configuration data and contains the ID of the interrupt triggering unit. The offset is determined by creating all UCB data structures in successive order identical to the order of the UCD data structures in the configuration file. The macro assembler calculates the offset by means of macros.

The interrupt handler of the driver will then initiate the corresponding steps and status transitions, depending on the driver and/or unit state that is represented by the status variables of the driver in the UCB and/or DCB data structures. As of the I state, the interrupt handler of the driver always receives the following data as start parameters:

● DS register initializing to RM3_DATA.

● DS/EBX points to the current UCB data structure of the unit.

Starting at the UCB address, it is possible to reach all other necessary data structures (UCD, DCB, DCD) by means of pointers. Interrupt handling by the driver has therefore become independent of the number of units of this driver, as the program sequence is only controlled by data and states (again data) in in the data structures.



Unexpected interrupts The driver has the following options of responding to unexpected interrupts:

● Ignore

● Logging errors (XERRLOG) in S state

● Activating a task (if defined in UCB.UNS) for processing the interrupt by means of the call of XSETUNS or XQSETUNS. Two status words (XSTATUS) can be passed to the task's EAX and EBX registers.

3.5.6 Timeout processing All drivers that support timeouts must provide at least one entry point for timeout processing. The driver writes this entry point address to the associated TMB data structure at timeout activation (described in Processing of an SVC RmIO).

Parallel drivers may also contain an implementation that consists of different procedure entry points for handling the timeouts for each unit. If the RMOS3 nucleus detects a unit timeout it initiates a CALL (NEAR) to the timeout entry point. Timeout handling is running as system process. XGEND contains the offset address of the triggering TMB, while XUCB contains the address of the UCB data structure of the unit that initiated the timeout.

Using the UCB address of the unit, it is possible to address all other data structures that are necessary for processing the timeout. The current start parameters for handling the timeouts are listed below:

● XUCB contains the offset of the UCB data structure of the interrupt triggering unit.

● XGEND contains the offset to the triggering TMB data structure.

● Register DS points to segment RM3_DATA.

● The timeout is handled as system process.

Type I driver The driver needs to specify the necessary timeout handling for the unit concerned (e.g terminating the current I/O request (IRB data structure) with parameter error). An error message can be output to the system console by calling the RMOS3 error logging subprogram (XERRLOG), provided that the error logger task is configured. The driver must complete timeout handling with a RETURN command.



Note Handling of a timeout is a system process. By adding it to the queue of system processes, a certain time will elapse before handling of the timeout is initiated. A possible incoming interrupt and its handling in the meantime may render timeout handling superfluous (race condition). Observe this aspect when implementing the timeout handling routine.

Example Once the nucleus has completed processing of the queued system processes, the handling of a timeout that was added in last place to the queue may be rendered superfluous.

Figure 3-5 System processes and interrupt handling

Interrupt events and their handling in DI or I state within the queuing period may render the timeout superfluous.

Type II driver The nucleus handles the timeout completely, which is why type II drivers are relieved from this task.

3.5.7 I/O termination for drivers

I/O termination for drivers A processing request can only be completed as system process. One of the reasons could be that an interrupt handler detects completion of a processing sequence (e.g. all characters were read), transforms into a system process, and takes over completion handling.

Another possibility is that a job completion is detected by a system process (e.g. evaluation of a CANCEL request) that immediately executes completion handling. On completion of the processing of any I/O requests, the system process of the driver must perform the following actions:



1. Writing the completion status to status array XSTATUS.

2. Updating the driver states by modifying the data structure.

3. Call of the XIODONE subprogram. This call completes an I/O request (processing request that is linked to an IRB data structure). The corresponding event flags are now set; tasks waiting for these event flags to be set are assigned the READY state. The routine removes the IRB for the completed I/O handling from the queue and returns the memory space used for this IRB to RMOS3 system memory. Any timeout pending that is related to this processing request is deleted. The bytes in XSTATUS are written to the array that was addressed at SVC RmIO with parameter status_ptr.

4. The driver now has to determine the next request to be processed, i.e, the next IRB data structure to process. The next I/O request can only be executed for a reserved unit by the task that has actually reserved this unit. If no request was found in the I/O queue, the I/O queue may actually contain IRBs, but no IRB to process. If none of the queued requests can be processed, the driver returns the control to RMOS3 (RETURN from the system process).

5. A further IRB that can be processed is handled basically in the same step sequence as for an SVC. However, the driver itself must set any necessary system variables (e.g. XCIRB).

6. Control is passed to the scheduler from the system process by executing a RETURN command.

I/O termination for type II drivers A processing request is completed as system process. An interrupt handler that detects completion of a processing sequence (e.g. all characters were read) must transform into a system process that takes over completion handling.

Another possibility is that a job completion is detected by a system process (e.g. evaluation of a CANCEL request) that immediately executes completion handling. On completion of the processing of any I/O requests, the system process of the driver must perform the following actions:

1. Writing the completion status to status array XSTATUS.

2. Updating the driver states by modifying the data structure.

3. Jump to the XOVER label for drivers in assembler, and to XJMP_XOVER for drivers in C. This call completes an I/O request – processing request that is linked to an IRB data structure. The corresponding event flags are now set; tasks waiting for these event flags to be set are assigned the READY state. The routine removes the IRB for the completed I/O handling from the queue and returns the memory space used for this IRB to RMOS3 system memory. Any timeout pending that is related to this processing request is deleted. The bytes in XSTATUS are written to the array that was addressed at SVC RmIO with parameter status_ptr.

4. The system process ends with this jump. The following statements are no longer executed. RMOS3 nucleus initiates the next processing procedure.



3.5.8 Operation of a unit by several drivers RMOS3 supports operation of a unit by two drivers. This property can only be implemented for type I drivers. On completion of an I/O request and before it is possible to process another request, it is necessary for drivers that share a control to run additional processing sequences. The mode of processing depends on the type of sharing of the unit:

● Flipflop sharing

● Completing all requests

Flipflop sharing In this case, it is necessary to check the partner driver to see whether it is waiting to initiate a processing request. This check can be performed, for example, by evaluation of a bit in DCB.STS that is defined for both drivers. The bit must be know to both drivers. In this case, the driver needs to determine whether or not a request is pending, and accordingly set the status bit I/O requests.

If it is necessary to serve the other driver, a jump to the predefined, shared entry point should be used. This entry point is not listed in any table and rather represents an entry point that is agreed for both drivers. The next I/O request in the queue is started after the jump to this entry point. A standard RETURN statement is necessary for completion of the driver.

Completing all requests The driver must complete all processing steps before it attempts to jump to the partner driver. In this case, too, the jump to the other driver should be dependent on a corresponding status indication.

3.5.9 Summary As drivers belong to the most complex programming tasks, you should avoid greater complexity by dispensing with unnecessary functions. The drivers should be as simple as possible to suit simple requirements. Any DI and I system states used must be understood and used carefully.

Note

A driver error may cause a system failure. Drivers need to be designed, coded and tested with meticulous care!

Only one system process of a driver should be opened at runtime (SRB). This rule applies in particular to hardware interrupts. Otherwise, you must expect heavy system load or, in extreme situations, even failure of the system (if no SRBs can be allocated in system memory). However, such a state may also develop due to hardware fault (e.g. interrupts that are not debounced). If possible, the nucleus also outputs the following alarm: ***nuc: <date> <time> no SRBS, SYSTEM HALTED



3.5.10 RMOS3 compliant interrupt handlers It is not necessary to implement drivers for all interrupt processing tasks. You always have the option of programming a custom, relatively compact interrupt handler that you can use to resolve such problems. This custom interrupt handler will then communicate with a task that is tailored to the interrupt handler. Communication can be handled by means of the operating system and shared internal data structures (e.g. buffers). The following example demonstrates an interrupt handler – task combination.

Figure 3-6 Example of the interaction between an interrupt handler and a task

The interrupt handler receives the values from an ADC and writes these to an alternating buffer. On buffer overflow, the interrupt handler changes to the system state and sets an event flag with subprogram call. The task is disabled until event flag 1, or event flag 2, is set. Once an event flag was set, the task is switched from the BLOCKED state to READY state, resets the flag and processes the alternating buffer depending on the flag setting. The entire process is initiated by enabling the interrupt and initiating the ADC. The task could be realized as follows:

Figure 3-7 Flow chart for a task that needs an interrupt handler



The interrupt handler could be realized as follows:

Figure 3-8 Example of an interrupt handler that supports a task

The example does not take into account whether or not the task processes the buffer data at an appropriate speed. The time expiring until the next buffer is filled is available as data processing time to the task. The factors that you can influence for proper implementation include the task priority and length of the buffer. Always take into account the other factors such as total system load, or the maximum buffer processing time (usually, default calculated values).

An advantage of this type of interrupt processing is that you can control all essential details related to interrupt handling. You may specify all time-critical details by selecting the state for interrupt handling, as well as the interrupt level (wiring). Always observe the limits for the duration of sessions in the various states.


System tasks 4 4.1 Command Line Interpreter

4.1.1 CLI operation Start the Command Line Interpreter (CLI) by entering the <CTRL>+R keystroke.

Keyboard input at the command line is handled by the BYT driver. Provided the driver is configured accordingly, a separate history of the specified length buffer is made available for each CLI session, which means that you can use the arrow keys to select previously entered commands.

You can edit command lines using the following keys:

Letters, numbers Always overwrite existing characters Arrow right/left Generate a cursor movement Arrow up/down Copy/paste a previously entered command from the history

buffer to the command line INS Generates a whitespace character, or inserts a string that was

previously cut with <CTRL>+a DEL Deletes the character at the cursor position Backspace Replaces the character on the left side of the cursor position

with a whitespace <CTRL>+a Deletes the line from the cursor position to the line end <CTRL>+h Same as Backspace <CTRL>+z Terminates input when copying from the console, e.g. end of

command copy con file.txt.

<CTRL>+s Stop CLI output <CTRL>+q Resume CLI output

4.1.2 Redirecting input and output data Input data can be redirected from a file or interface. Output data can be redirected to a file or interface.

This procedure is possible for:

● All CLI commands

● All programs using the standard C functions reading their input data from stdin , and writing their output data to stdout oder stderr.

System tasks 4.1 Command Line Interpreter


A redirection is specified by one of the following entries at the command line: > <file> or 1> <file>

Redirects all data output to stdout to the specified file. The file is created or overwritten.

>> <file> or 1>> <file>

Redirects all data output to stdout to the specified file. The output data is appended to an existing file; if the file does not exist, a new one will be created.

2> <file> Redirects all data output to stderr to the specified file. The file is created or overwritten.

2>> <file> Redirects all data output to stderr to the specified file. The output data is appended to an existing file; if the file does not exist, a new one will be created.

< <file> Initiates the reading of data input from stdin from the specified file.

You may also specify a unit name instead of the file name. However, such a unit name must be entered in the resource catalog as a unit that is compatible with the BYT driver.

4.1.3 Naming conventions As matter of principle, names may only contain characters that are valid in DOS. This means that all characters greater than ASCII 0x21 are valid in the names, provided they do not feature one of the following functions:

The placeholder character (joker character, wildcard) "*" in file names represents undefined naming supplements up to the maximum valid length.

The "?" wildcard in file names represents precisely one undefined character in file names.

Drive names are concluded with the ":" character.

Directory names must be separated from the next file/directory name by means of the backslash character "\".

All CLI commands use a command line argument that begins with the slash "/" as identifier for options or switches, but not for path names.

Each job is assigned a current directory. Paths and routes may be specified as absolute values, i.e. starting with the drive letter, or as relative value, i.e. the structure is specified starting at the current directory. In this case, the two dots ".." represent the parent directory.

Example of a valid file name:

C:\CLISTART.BAT

DIR.386

..\DIR.386

BIN\DIR.386

Usually, the CLI employs file names that are compatible with DOS. You may specify reloadable programs and CLI commands without file name extension. The CLI searches for the extension in a directory level in the following order:

386, EXE and BAT.

Note

CLI cannot execute DOS programs that are available as EXE file.

System tasks 4.1 Command Line Interpreter


The CLI converts file names, directories and drives into uppercase notation. However, the arguments of the command lines are transferred without changes. This is why a program running under CLI is able to retain lowercase notation.

4.1.4 Notes on the support for long file names (VFAT16 or VFAT32)

Presentation of long file names Support for long file names in the FAT16 file system is also known as VFAT16. In the FAT32 file system, these are known as VFAT32. This support function now extends the file system to enable the uses of long file names in addition to the previous 8.3 file names.

The string length of a "long name" in RMOS3 may not exceed 195 characters. In other operating systems the name may have a length of up to 255 characters. All long file names are provided an additional 8.3 name that is displayed as representative of the long name.

Syntax of the 8.3 name:

● First 6 characters of the long name

● "~" character

● Number "1"

Optionally appended:

● Dot character "."

● 3-digit extension

If the name already exists, the number "1" at position eight is incremented by the count of 1. If that name already exists, too, the number is incremented up to the maximum count of 9. If this name exists as well, the short name is formed as follows:

● First two characters of the long name

● 4-digit random number (derived from timertick)

● "~" character

● "1" character

Optionally appended:

● Dot character "."

● 3-digit extension

The naming is not case sensitive, i.e. all file names are stored in uppercase notation. Also, long file names are not converted to language-dependent Unicode.

Long file names may contain a whitespace. However, in this case the file name must be enclosed in double quotes, e.g. "C:\blank test". Any whitespace at the end of the file name is removed. Whitespaces at the beginning of a file name are invalid and trigger the "illegal filename" error.

System tasks 4.2 Debugger


Dots appended to the file name are removed.

Double quotes are not supported for file redirection.

4.1.5 Notes on HSFS and on using volumes In the RMOS3 file management system HSFS, you need to mount all volumes prior to their use (MOUNT). You are provided several different methods of mounting the volumes. The response is also influenced by the HSFS configuration:

● If bit VL_NO_MOUNTING is set in the volume flags, you need to mount the volume with MOUNT to enable access to the drive.

● If this bit is not set (default configuration), the volume is mounted automatically when you open a file. The volume remains in mounted state, even if opening of the file was canceled with error.

At the change from the current directory (command CD) to a directory on a different volume, CRUN mounts the target volume, if not already mounted.

You can also automate mounting by setting the corresponding search path (PATH).

4.2 Debugger

4.2.1 Task-and monitor operating modes The debugger runs in task mode by default, which is the operating mode for debugging programs at task level. In this operating mode, breakpoints may only be set at task level and not in the code of RMOS3 drivers.

The debugging of RMOS3 drivers is only possible in monitor mode.

You may change to the selected operating mode by executing a corresponding command, or by calling a special breakpoint handling routine.



Figure 4-1 Task mode and monitor mode of the RMOS3 debugger

Debugger prompt The debugger prompt displays the current operating mode and the current context:

Debugger in monitor mode: Breakpoint context DEBUG_MB>

Prompt for use of host debugger >

Debugger prompt in task mode: Escape context: DEBUG_T>

Breakpoint context: DEBUG_TB>

Prompt for use of host debugger >

For reasons of compatibility, only a truncated prompt message > is output, provided the interface to the host debugger (HD) is configured. This interface is configured in the configuration sample that is available in the SYSTEM\PC directory. The truncated prompt is output to the screen on completion of the boot process. Using the HELP command, you may change from the truncated prompt message >

to the detailed prompt message, e.g. DEBUG_T>

or DEBUG_TB>



Task mode The task mode represents the operating mode for debugging at task level and the default operating mode of the debugger. The debugger runs as separate task and is controlled by the operating system. The scheduler assigns the CPU time to the debugger.

Specific tasks may be stopped by setting breakpoints, without having a direct impact on other tasks (real-time behavior of the debugger).

A task interrupted by a breakpoint is set to the "Blocked, debugger breakpointed" state and the debugger task changes to the breakpoint context. You can view and edit the registers, the stack, and all necessary memory areas of the interrupted task.

It is possible to switch from the task mode to the monitor mode by setting a monitor breakpoint (see Qualify), or by executing the MONITOR command.

Monitor mode In monitor mode, the debugger is acting as monitor program and takes over control of the application. Once the debugger has entered the monitor mode, all interrupts are disabled and all further activities of the operating system are canceled, which means that all tasks are suspended (no real-time behavior).

Once a monitor breakpoint has been reached, the task cannot change to the debugger. The debugger is called instead as function of the interrupted program. The stack of the interrupted program remains unchanged, because the system changes to the stack of the debugger. The status of the interrupted program is written to a breakpoint structure (shadow register) and can be viewed and edited at the runtime of the debugger.

On exiting the debugger (GO/STEP/EXIT/EXITK), the register values are retreived from the breakpoint structure (shadow register) and activated, the interrupts are released, and the interrupted program is resumed. The operating system recovers control at this instance.

You cannot use the TASK command to change to the task mode in the monitor breakpoint context. Program execution is not resumed and the monitor mode is not terminated until a subsequent GO command was executed. The debugger has then returned to the task mode.

Notes:

● Task-specific commands are no longer allowed in monitor mode. As the interrupts are disabled, the communication interface is operated based on the polling method.

● The monitor mode is only available at a serial interface and cannot be used at an EGA unit of the BYT driver.

● The debugger is not suitable for testing drivers that access the serial interface controller that is also in use by the debugger.

● In task mode, a monitor breakpoint can always interrupt the debugger.

If the debugger was interrupted by a monitor breakpoint while outputting the prompt, after a GO command a truncated prompt message is output in monitor mode.

● When debugging drivers in monitor mode, you may not set any DATA ACCESS breakpoints to system variables such as XCIRB, XUCB (cf. section "System variables for parameter transfer (Page 80)"), because the debugger also accesses these variables.



4.2.2 General notes on operation ● You can customize the scope of commands and, therefore, memory requirements of the

debugger.

● With a suitable system configuration (program code in RAM or debug register of the 80386) you can usually dispense with additional emulator hardware.

● The debugger does not intervene in the system sequence unless requested accordingly. The tasks to be debugged should be stored in RAM, as this allows for accelerated program changes and unrestricted setting of breakpoints.

4.2.3 RMOS3 operating environment of the debugger The following resources must be configured to enable operation of the debugger:

● Driver for serial communication, e.g. BYT driver

● The INT 3 instruction (the only 1–byte interrupt instruction of the CPU) and the single–step interrupt (INT 1) are used for debugger breakpoints. The debugger initializes these interrupt vectors with pointers to an interrupt handler as long as a breakpoint is set. The original interrupt vectors are re-initialized after the last breakpoint was cleared. This procedure ensures the functioning of a previously installed INT1 /INT3 handler.

4.2.4 Operating the debugger

Meaning of the context The way a debugger was activated and the sequences that were interrupted as a consequence have a significant impact on the various functions of the debugger commands. The term "context" is used to distinguish between these actions. Context has an influence on the definition of specific command functions, or on their basic usability.

We distinguish between two types of context:

1. Escape context: The rules for escape context apply if the last start of the debugger was initiated by means of keyboard input on the terminal (task start due to unexpected input). The foremost implication is that it is not possible to manipulate any registers of the task. The commands for task register manipulation are not available and the debugger runs with its own task ID and priority. The character code for a task start triggered by unexpected input can be configured.

2. Breakpoint context: This context is valid if the debugger was activated by a breakpoint (INT3/debug register breakpoint). In this case, a task that triggered a breakpoint is stopped and the debugger is started. With active breakpoint context it is possible to view and edit the registers (i.e. the CPU registers active at the time of interrupt) of the stopped task. A GO or EXITK command returns the control to the suspended task. EXITK also clears all set breakpoints.



4.2.5 Task processing The debugger can inhibit task processing, which means that no further task is executed, with exception of the debugger. This action can be handled by executing an INHIB command, or as general measure at the start of the debugger (specified in the course of configuration). All task states are frozen while task processing is deactivated until task processing is released again (debugger termination, or INHIB). Already initiated SVCs of a task are terminated if no task is required for their processing. The RmIO calls of a task are terminated, for example, and the calling task is then in READY state. EXIT, EXITK and GO terminate the debugger and revoke the inhibit of task processing again.

4.2.6 Debugger start You start the debugger by means of <CTRL>+D keystroke.

The debugger outputs a message at each start, for example:

RMOS3 DYNAMIC DEBUGGER, Vm.n

>

The debugger can be started by means of key input at the console (configurable), by a different task, or as initialization task after system startup. For the start as initialization task, you need to set the device ID and unit ID at parameter TCD.EAX, and the status for task processing at parameter TCD.EBX (see the following table).

Table 4- 1 EAX and EBX parameters at the start of the debugger

TCD.EAX Bit 0 ... 7 Contains the device ID Bit 8 ... 15 Contains the unit ID

TCD.EBX Bit 0 = 0 Bit 0 = 1

Task processing allowed Task processing inhibited

Bit 1 = 0 Bit 1 = 1

No reservation of the console The console is reserved at the start of the debugger, which means that output and input from a different task will be delayed until the debugger is terminated

Bit 2 ... 15 Reserved, must be 0

The EAX start parameter must contain the driver ID and the device ID if the debugger is started by another task. The EBX start parameter is reserved and must be 0

if the debugger was activated by a breakpoint, it outputs the following message:

{{Stepbreak/BreakpointBPID} reached in {task TaskID/monitor mode}/

End of task TaskID detected}

Priority 255 is always set for the debugger in the breakpoint context.



4.2.7 Debugger-I/O interface x_d_rio You may configure the device /unit ID of the driver for communication with the debugger, and customize communication with interface x_d_rio to suit special requirements.

All I/O operations of the debugger are handled by means of an x_d_rio function in which the SVC rio is transferred to the corresponding driver. The function is available in the FILTER module that is integrated by default from the RMOS3 library.

A user-specific FILTER module can be used for convenient adaptation of the I/O to special units, or to modify the I/O strings. For this purpose, the user module is linked as separate object module in the corresponding order (object module before library).

A sample program is supplied as source code in your SW package.

4.2.8 General syntax rules The debugger outputs the following prompt after startup: DEBUG_T>

and expects the following input format:

[<repetition factor><empty>] <command> [;[<repetition

factor><empty>]<command>]...<return>

whereby

<command> =<command word><DEL><Arg1><DEL><Arg2>...

The repetition factor specifies the number of times the command is to be executed. 0 means that the command can always be executed. This parameter is optional.

The command word consists of several characters and defines the selected function. The number of arguments is command-dependent.

The command words of the debugger are summarized in a table. The CPU register names <cpureg> are only allowed in the breakpoint context. You may also enter all command words in truncated form, provided the abbreviation can be distinguished uniquely. For example, you may abbreviate BREAKS with BRE, BREA or BREAK, the START command with STAR, but not with STA because this abbreviation cannot be distinguished from STACK. The abbreviation must contain at least three 3 letters (exception: EX for EXIT).

Command word input is not case sensitive. The debugger does not start evaluation of an input line until you entered CR (Carriage Return).

The debugger automatically requests the parameters if these are not specified during command input. On input of a command without associated parameters, the debugger outputs a message and waits for the input of parameters (interactive command input).

In a command line that contains several numerical parameters you need to enter individual signed parameters, e.g. –1, in round brackets (–1). Otherwise, the sign is treated as operator, without separation to the previous parameter.



An input line may contain more than one command. You may enter several commands, separated by semicolon, in the line until the limit of the command line length has been reached. A retry counter may lead the command name. The count value specifies the number of times the next command is to be executed. Repetition counter value zero forces command or breakpoint execution in an endless loop that can only be canceled with a CTRL–C keystroke.

Input of the count values is interpreted by default in decimal or hexadecimal notation. The BASE command is used to set the default number base. BASE=10 sets the decimal and BASE=16 the hexadecimal interpretation of entries. However, individual values may be entered with prefix for the hexadecimal, decimal, octal, or dual number base, or as ASCII string.

Prefixes for the number base:

0x hexadecimal 0n decimal 0o octal 0m dual ‘ ‘ ASCII

An ASCII value is assumed if one or several values are enclosed in apostrophes (‘). The left of two characters corresponds to the most significant byte of the word.

The following numerical presentations in a line are of equal meaning:

0n09 0x09 0o011 0m00001001 (non-printable character) 0n14 0x0E 0o016 0m00001110 (non-printable character) 0n65 0x41 0o101 0m01000001 ‘A’

Floating-point values must be entered with decimal point or exponent. The numbers used in the exponential notation of real numbers that are displayed by means of the DISPLAY command are interpreted as decimals.

The display, fill and change commands are only supported for floating-point numbers if the calculate command is configured.

Example of floating-point numbers:

CALC 3.141592654E+5 * 2.718281828E–3 +8.539734222+002

The debugger responds to command input with incorrect syntax with its general

Syntax error!

error message and requests a new entry.

The following sections show debugger outputs in different font . Meaning of additional entries:

xx current memory content CR command input with carriage return



4.2.9 Detailed command syntax This section describes argument values frequently used for command input.

Address Address in protected mode:

<address> {<selector>:<offset>|<abs_addr>{L|P}}

Table 4- 2 Argument definitions for addresses

Argument Meaning <selector> Selector that references a descriptor in the current GDT or

LDT. <selector> may be <expr> <offset> 32–bit value, <offset> can be <expr> <abs_addr> is an absolute 32–bit address L/P Keyword for linear/physical address (without paging unit

identical) <expr> (see below)

You can use the segment registers to specify a selector. However, the task register names are only available in the breakpoint context.

A selector always needs to be referenced to a valid segment descriptor (ER/RW). Otherwise, error message

WRONG SELECTOR

is output. The entry of a selector with offset value for the address is valid as preset for subsequent commands.

Expression (expr) An expression with <expr> may contain constants, register contents, memory contents, input ports, links with arithmetical and logical operators.

<expr> [{–|~}] <term> [[{+|–|^|’|’|&|<<|>>} <term>]...]

Table 4- 3 Argument entries for expressions

Argument Meaning <term> <factor>[[{*|/|%}<factor>]...] <factor> {<ident>|<const>|(<expr>)} <ident> {<cpureg>|<memory>|<port>} <cpureg> {CS|DS|ES|SS|FS|GS|EIP|EAX|EBX|ECX|EDX|

EDI|ESI|ESP|EBP|EFL||IP|AX|BX|CX|DX|DI| SP|BP|FL|AL|AH|BL|BH|CL|CH|DL|DH|GDTR|LDR|IDTR| TR|CR0|CR2|CR3| DR0|DR1|DR2|DR3|DR6|DR7|TR31)|TR41)|TR51)|TR6|TR7} 1) only for 486 processors or higher

<memory> {BYTE|WORD|DWORD|POI|SPOI}’[‘<address>‘]’ <port> {INB|INW|IND} ‘[‘<port_address>‘]’ <port_address> <expr>



Argument Meaning ~ NOT – Negation + – * / arithmetical basic operations % Remainder of integer division ^ XOR | OR & AND << shift left >> shift right

Constant (const) Constants may be entered with hexadecimal, decimal, or octal number base, or in ASCII notation. Moreover, constants are also distinguished based on their memory format:

BYTE, WORD, DWORD, QWORD

Delimiters (DEL) The following delimiter characters are valid:

● Blank ( )

● Comma (,)

● Equal (=)

It is allowed to enter several delimiters (DEL) between two successive arguments.

Format <format> {[<memory_format>][<display_format>]|data_type}

Table 4- 4 Argument entries for formatting

Argument Meaning <memory_format> {byte|word|dword| qword}

selects the element length of a specified memory range byte 1 byte word 2 bytes dword 4 bytes qword 8 bytes

<display_format> {Mask|Octal|Hex| Unsigned|Signed| ASCII}

selects the format for display on the console Mask Display as bit pattern: xxxx xxxx Octal Display as octal number Unsigned Display as unsigned decimal Signed Display as signed decimal



Argument Meaning Hex Representation as hexadecimal number ASCII Display as string (1 byte per letter)

<data_type> {Short|Long|Float|Double| Tempreal| Pointer|Spointer}

contains memory_format + display_format Short Signed word Long Signed dword Pointer (long pointer) 16–bit selector:32–bit segment Spointer (Short Pointer) 16–bit selector:16–bit segment Float 4–byte real number Double 8–byte real number Tempreal 10–byte real number

Task ID <task-id><expr>

Valid values for <task-id> are 0 ... 32767 and 0FFFFH

Breakpoints When setting breakpoints, you must distinguish between hard breakpoints, soft breakpoints, and debug register breakpoints. Hard and soft breakpoints replace the corresponding OP code with the INT3 instruction and can only be used if the program code is in RAM. Soft breakpoints ($) exist only on a temporary basis and are cleared automatically on completion of processing. In contrast, hard breakpoints (@) are retained until removed with kill.

Up to four debug register breakpoints are available for the 80386 processor where they are used to set breakpoints for read/write access to memory. The processor also supports debugging with execution breakpoints for program code in EPROM.

<breakpoint> {$|@|E|{M|W}{B|W|D}}1...0F

Table 4- 5 Argument entries for breakpoints

Argument Meaning $ Set soft breakpoint @ Set hard breakpoint Set breakpoint in debug register: E Execution breakpoint in the debug register MB Modify (Read or Write) Byte Breakpoint MW Modify (Read or Write) Word Breakpoint MD Modify (Read or Write) Dword Breakpoint WB Write Byte Breakpoint WW Write Word Breakpoint WD Write Dword Breakpoint



4.2.10 Command scope of the debugger A list of debugger commands is shown below. For more information on the actual commands, refer to the Reference Manual Part I.

asm Disassemble memory content base Set number base breaks List breakpoints calculate Calculate floating-point expression Call Execute a program (only in task mode) change View/change memory bytes cont Release interrupted task (only in task mode) cpureg 1 Check/edit register content dir Display index entries (only in task mode) display Output memory content evaluate Calculate integer expression exit Exit debugger exitk Clear breakpoints and release interrupted task fill Fill memory block with byte values freetask Deletes a dynamically loaded task (only in task mode) go Release interrupted task and exit debugger halt Hold task (only in task mode) help Help command in Read I/O port inhib Enable/inhibit task processing (only in task mode) kill Clear breakpoint(s) lines Activate/deactivate paging loadtask Load task (only in task mode) monitor Switch debugger to monitor mode (only in task mode) out Output I/O port qualify Parameterize breakpoint query Query task status (only in task mode) regs Show all register contents report Resource report (only in task mode) set Set breakpoint(s) stack Show stack start Start task in DORMANT state (only in task mode) step Execute single-step svc Generate system call (only in task mode) switch Switch breakpoint context task Switch debugger to task mode tcb Display TCB data of a task (only in task mode) tcd Display TCD data of a task (only in task mode)

1 cpureg is is a wildcard for names of the CPU registers (EAX, EBX, etc.). The registers can only be displayed or edited in the breakpoint context.



4.2.11 Error messages of the debugger The debugger responds to command input with incorrect syntax with its general error message and then requests a new entry. no debugger dispatcher task found

The debugger is not loaded. ‘]’ expected!

Closing square bracket missing in expression. All debugregisters in use!

An attempt was made to set more than 4 breakpoints of the type ‘debug register breakpoint’. Already a breakpoint!

The address is already occupied by a breakpoint. Balance error!

Unequal number of opening and closing brackets. Breakpoint_id in use!

The breakpoint number (ID) cannot be overwritten. Can’t allocate memory!

Allocation of sufficient memory space failed. Can’t monitor end of task!

Debugger was unable to log on to the operating system for monitoring the end of this task. Catalog error!

Generation of the catalog entry failed. Command not allowed on this unit!

An attempt was made to switch to monitor mode, or to set a monitor breakpoint at a console that does not support this operating mode. Command not configured!

The command was not configured. Divide by zero!

An expression contains a division by zero. Error starting task!

Task start failed. File does not exist!

The specified file is unavailable. I/O error!

An I/O error has occurred.



Illegal mode!

An attempt was made in task mode to execute a command that is only allowed in monitor mode, or to execute a command in monitor mode that is only allowed in task mode. Illegal request!

The command is invalid in the current state. Illegal SVC parameter!

Invalid parameter input at SVC command. Invalid base!

Invalid number base. Loader error!

Unknown error of the task loader. Loader result segment not found!

A loader result segment does not exist for the specified task. Memory not writeable!

An attempt was made to set a hard or soft breakpoint in a ROM area. Missing operand(s)!

Expression is missing a valid operand. Missing valid SVC_name!

SVC is faulty or does not exist. Nesting exceeded, stack full!

The nesting depth in an integer or floating point expression was exceeded. No linear/physical address for breakpoints!

A linear/physical address is not allowed for setting breakpoints. No such breakpoint!

An attempt was made to clear a breakpoint that does not exist. No such task!

The task ID was not assigned to a task, or the task is in DORMANT state. Not a read–write segment!

The segment specified by a selector must be of the type READ–WRITE. Not an execute–read segment!

The segment specified by a selector must be of the type EXECUTE–READ. NPX not allowed!

Invalid co-processor operation. Offset exceeds segment limit!

The segment limit was exceeded.



Page not present

Only with activated paging mechanism: No entry in the page directory for this memory area, or the associated page is unavailable. Stepcount > 127!

STEP cannot be used to execute more than 127 commands. Syntax error!

Incorrect syntax in the last command entered. Task not halted!

A task cannot be resumed with CONT if stopped by means of DEBUGGER HOLD. Too many arguments!

Too many arguments transferred with START <task_id> ARGS ... and SVC <SVC_name>. Type mismatch!

Invalid TYPE setting. Unexpected End-of-file!

Read access to a file returned an insufficient number of bytes, or none at all. Wrong format!

Invalid format detected when loading with loadtask command. Valid formats include: EXE, LTLEXE, LTL, STL, and PE (Windows NT) Wrong report table size!

Incorrect size of the resource reporter table. Wrong selector!

An attempt was made to enter a selector/offset pair as address, while the selector part does not point to a valid entry in a descriptor table.

System tasks 4.3 Resource reporter


4.3 Resource reporter

4.3.1 General notes on operation Resource reporter receives the operating system information it needs from a special SVC (REPSVC). This safely prevents collision of activities at task level with information acquisition of resource reporter.

Resource reporter is a task that is linked in the course of system configuration. It does not participate in system runtime unless called.

The respective evaluation type and presentation are specified (in the call syntax) at the start of resource reporter. It can be restarted on expiration of a time interval.

Interrupt handling is also ensured while resource reporter runs the evaluation procedures in S state.

The resource reporter is cataloged with the REP string and its task ID at system startup.

4.3.2 RMOS3 support The configuration must contain the BYT or CRT driver to enable operation of the resource reporter.

4.3.3 Operating resource reporter

Starting resource reporter Resource reporter is started as separate task by the debugger, or by a user task. Output is made either to a device, to memory or to a file, or simultaneously to all targets.

The resource reporter task logs on at each start with: RMOS3 RESOURCE REPORTER, Vm.n dd–mmm–yyyy hh:mm:ss

The m.n code in the logon message represents the version.release.

dd–mmm–yyyy hh:mm:ss represents the date and time. The date and time are determined using SVC time and correspond with the format of this SVC.



Resource reporter provides two task entry points, one of which you can select in the configuration:

● The first entry point is configured using the call RcInitReporterX(). Compared to the second, this entry point includes the option of data output to memory and to a file in addition to a device. The start parameters must contain a pointer to a structure in which all options are stored.

● The second entry point primarily exists only for reasons of compatibility and is configured with the call RcInitReporter().

This configuration only allows data output via a device for which a device ID/unit ID combination was assigned to resource reporter in the system configuration. The start parameters must contain the type of evaluation and the restart option in coded form.

4.3.4 Parameter settings with pointers to a structure The following form of parameter setting is only valid if the task was configured in RMCONF.C with the RcInitReporterX() call.

Via the start parameters (parameters RegVal1 and RegVal2 for RmStartTask and RmQueueStartTask;see Reference Manual part III,chapter 2 "RMOS3 functions") at the task start a pointer to a structure with control information is passed that defines the evaluation type, the restart and the output target. In addition, the resource reporter can write back status information.

The evaluation results of resource reporter can be output in short or long format. For the short version, you only need to set the bit for the corresponding resource in the structure. You need to set a second bit for the long version. The following section describes the bit positions in the structure.

If no parameter is specified for the evaluation selection, resource reporter relies on the default and outputs all evaluation results in the short version. The restart parameter is not evaluated in this case.

The restart option in combination with output to memory or file is not allowed, because the risk of overflow cannot be excluded.

Syntax of the structure: struct rep_struct { unsigned int analyze_type; /* Bit coded type */ unsigned int id; /* ID or –1 */ unsigned int res1; /* Reserved, should be 0 */ unsigned int timed_restart; /* Time unit/count */ unsigned int *status; /* Pointer to status field */ unsigned int output_type; /* Code for destination */ unsigned int dev_id; /* Output device */ unsigned int unit_id; /* Output unit */ unsigned int heap_len; /* Max length of memory*/ char* heap; /* Pointer to beginning */ short res2; /* Reserved, should be 0 */ unsigned int access_type; /* Code for file access */ char* file_name; /* Pointer to filename */ short res3; /* Reserved, should be 0 */ };



Table 4- 6 Parameter structure of resource reporter

Parameters Meaning analyze_type Type of evaluation; a description of the coding is

provided below. id If analyze_type selects only one type of resource and

id does not contain –1, only this object with the ID specified in id (If it exists) will be output. All existing objects are output if id contains the -1 entry.

res1 Reserved for future expansions; res1 should be 0. timed_restart Restart code; a description of the coding is provided

below. status Pointer to a status array; 0 means that no status is

written back. The following error codes are defined: 0 no error 1 invalid combination of restart and output to

memory or file 2 invalid pointer to memory area 3 insufficient memory for completion of output 4 file already existed and could not be

overwritten (see access_type) 5 no memory request for data collection All other values up to 127 are reserved. Values above 128 correspond to error codes returned by the device driver or file system.

Output_type type of output; the different bits may be set simultaneously and determine which of the following parameters are evaluated: Bit 0 device, e.g. terminal, printer, or similar Bit 1 data storage in memory; not allowed in

combination with restart Bit 2 write to file ; HSFS required; not allowed in

combination with restart. All other bits are reserved.

Device parameters: The device is reserved and released with function code 0 and 1 (see SVC RmIO). Function code 3 with wait state is used for write access. Dev_id Driver ID unit_id ID of the device Memory parameters: heap_len Maximum number of characters that can be saved to

memory. Heap Pointer to the start of a contiguous memory area. Res2 Reserved for future expansions; should be 0



Parameters Meaning File parameters: If the volume is not mounted, an attempt is launched to mount it in DOS format. The file is opened with lock option (exclusive use). A volume mounted by the resource reporter is dismounted again on completion (no FORCED DISMOUNT). Access_type Mode to employ for file access:

0 A new file is created; any existing file is overwritten

1 The file is only created if it does not yet exist 2 Data is appended to a file; a new file is created

if it does not yet exist All other values are RESERVED.

file_name Pointer to a valid file name that is concluded with 0 value; naming convention in accordance with HSFS naming

res3 Reserved for future expansions; should be 0

Parameter settings with bit coding The following form of downwards compatible parameter setting is only valid if the task was configured in RMCONF.C with the call of RcInitReporter().

Resource reporter evaluates the start parameters transferred in the EAX and EBX registers (parameters RegVal1 and RegVal2 for RmStartTask and RmQueueStartTask; see Reference Manual Part III). The parameter in EAX determines the evaluation type, while the parameter in EBX specifies whether or not to restart resource reporter.

Evaluation parameter analyze_type by means of EAX parameter The evaluation types of resource reporter can be output in the short or long version. The evaluation type is selected by setting a bit in the EAX parameter. When selecting the long version, you need to set the bit for the respective resource in addition to the long version bit. The following figure provides detailed information on the various bits.

If no parameter is specified for the evaluation selection, resource reporter relies on the default and outputs all evaluation results in the short version. The restart parameter is not evaluated in this case.



Coding of parameter analyze_type Coding of the parameter for evaluation type analyze_type:

Table 4- 7 Coding of parameter analyze_type

Evaluation type SHORT VERSION = 0 LONG VERSION = 1

Resource to evaluate

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0

Tasks Device drivers

Memory pools Semaphores

Global event flags Programs with monitored access

Mailboxes Messages

Tasks Device drivers

Memory pools Semaphores

Global event flags Programs with monitored access

Mailboxes Messages

Example of the usage of the evaluation parameter Evaluation parameter analyze_type = 0426H (0000 0100 0010 0110B)

triggers the following output:

● Device driver, short version

● Memory pool, long version

● Programs with monitored access, short version

Start parameters via EBX parameter The EBX restart parameter provides the following options:

● Restart flag

● Specification of the time unit (time_unit)

● Number of time units (count)

● Timebase (time_base)



The next figure shows the usage of the various bits.

You may set time units (time_unit) from milliseconds to hours (see SVC endr). The range of time units (count) starts at 0 and ends at 07FH. This setting defines the number of units to expire before the next restart. The reference time (time_base) is 0 or 1. If time_base=0 is set, the restart is based on the most recently set start time. If time_base=1 is set, the restart is based on the most current time. The restart flag specifies whether or not to perform a restart (TRF). If flag=1, resource reporter is restarted on expiration of the specified interval. A 0 value specifies normal completion.

Coding of the restart parameter:

Table 4- 8 Coding of the restart parameter

Restart 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 count

n.c. Time_unit

n.c. Time_base

Restart flag

Example of the usage of the evaluation parameter Restart parameter

Restart = 8601H (10xx 011x x000 0001B) (x = unused bits)

triggers a restart of resource reporter at one second after the most recently specified start time (count=1H, time_unit=3H, time_base=0H, restart flag=1H).

Starting resource reporter from the debugger The evaluation results of resource reporter can be output from the debugger using the REPORT command (see Reference Manual Part I, chapter 3 "Reference of debugger commands").

Resource reporter may also be started by means of debugger command START (starts a task that is currently in DORMANT state).

However, it is not allowed to call the debugger command REPORT while running resource reporter as task.

Starting resource reporter from a user task Resource reporter is started from a task by means of SVC RmStartTask or RmQueueStartTask. The options are transferred with the P1 (EAX register) and P2 (EBX register) start parameters.



Resource reporter table Resource reporter saves the acquired data to a table; memory space of this table is requested dynamically. Pool ID –1 is used (HEAP). The length of this table depends on the system configuration, the activities at the time of data acquisition, and on the selected evaluations.

No data is acquired and a corresponding error message is output if resource reporter is denied the requested memory space.

The length of the resource reporter table is defined in RMCONF.C using the define REPORTER_TABLE_SIZE.

Table 4- 9 Resource reporter table

Evaluation type Long version Necessary memory spaces in bytes

Tasks 58 For each task not in DORMANT state Device drivers 264

262 40

For each driver For each device For each active or queued I/O request

Memory pools 16 12

For each pool For each queued memory request

Semaphores 12 8

For each semaphore For each queued task

Global flags 12 For each flag group Event flags 14 For each queued task Mailboxes 8

4 22

For each mailbox For each queued task For each message

Messages 4 24

For each message queue For each message

4.3.5 Error messages of resource reporter can’t allocate memory

Memory space could not be requested while acquiring data. wrong reporter table size

Table out of memory space during data acquisition due to inappropriate configuration of the length of the reporter table.

The message is output by means of error logger task.

All other possible error states are reported only in the status of the calling task. No further on-screen messages.

System tasks 4.4 Exception Interrupt Handler


4.4 Exception Interrupt Handler Der Exception Interrupt Handler (named EIH in the following) is always called if an exception interrupt of the processor occurs. It has the following properties:

● Outputs the name of the exception interrupt that was triggered, the content of processor registers, as well as additional information such as the system state at the time of occurrence of the exception interrupt to the screen.

● The EIH has a modular structure and is split into an Assembler and a C section. The exception interrupt is analyzed and handled in the assembler section. The information, e.g. the system state at the time of occurrence of the exception interrupt, is transferred via defined interface to the C section. From there, the information is output to the screen in a comprehensible form.

● The defined interface and clear separation of the assembler and C sections makes it easy to implement changes and expansions. You only need to edit the C section, for example, to visualize the information on-screen in a different form, or initiate additional actions for specific exception interrupts (e.g. start of an application-specific task). Special knowledge, e.g. about the handling of the respective exception interrupt, is not required.

● You can optionally start the RMOS3 debugger if the exception interrupt was triggered while task processing was active. This start is specified by means of switch in the C section.

● The interrupt handler routines for exception interrupts 8 (DOUBLE FAULT) and 12 (STACK FAULT) are started by means of CPU task switch.

4.4.1 Real-time capability The EIH impairs the real-time capability of RMOS3 as it employs the polling method for data output to the screen. The x_nuc_printf routine does not explicitly disable interrupts.

4.4.2 Design and function The EIH is split into an Assembler section (MISCIN.ASM) and a C section (EXCOUT.C). For each exception interrupt, the assembler section provides an interrupt handler routine with a name consisting of the string x_excep_ and number (e.g. 0, 1, 2 ... 15) of the exception interrupt. The handler routines are assigned automatically to the exception interrupts.

The respective interrupt handler routine is started in response to an exception interrupt that was triggered by the CPU. First, the routine determines the current system state. If the exception interrupt was triggered in A state, i.e. while task processing was active, it also inhibits the corresponding task. The x_exc_out routine is then called in the C section of the EIH with the following parameters. The interrupts are disabled.



void far x_exc_out (unsigned int state, RmTCBStruct *tcb_ptr, unsigned int task_id, unsigned int svc_no, unsigned int intr_no, unsigned int err_code, unsigned int eflag, unsigned int eip, unsigned short cs, unsigned int eax, unsigned int ebx, unsigned int ecx, unsigned int edx, unsigned int esi, unsigned int edi, unsigned int ebp, unsigned int esp, unsigned short ss, unsigned short ds, #if RM3 unsigned short es, unsigned short fs, unsigned short gs) #else unsigned short es) #endif

Table 4- 10 Structure of the Exception Interrupt Handler

Parameters Meaning state Bits 0-1 0 Exception interrupt in A state

1 Exception interrupt during SVC handling 2 Exception interrupt in I state 3 Exception interrupt in S state

Bit 2 0 Exception interrupt returns no CPU error code 1 Exception interrupt returns CPU error code

Further bits are reserved and set to 0. tcb_ptr Pointer to the TCB of the task that triggered the exception interrupt (0:0, if the

nucleus triggered the interrupt). task_id ID of the task that triggered the exception interrupt.

(-1, if the nucleus triggered the interrupt) svc_no Number of the SVC that was processed when the exception interrupt was

triggered. (-1, if the interrupt was triggered while no SVC was processed)

intr_no Number of the exception interrupt triggered err_code CPU error code, if generated in response to an exception interrupt (see the CPU

description). CPU error codes are only generated by specific exception interrupts.

eflag, eip, cs, eax, ebx, ecx, edx, esi, edi, ebp, esp, ss, ds, es, fs, gs

Register contents at the time of exception interrupt.



The routine x_exc_out then outputs the passed information to the screen in a comprehensible form. An exception triggered in A state initiates the following procedure, depending on the setting of switch DEB_START (EXCOUT.C):

#define DEB_START FALSE RMOS3 debugger is not started #define DEB_START TRUE RMOS3 debugger is started

The control is then returned to the assembler section of the EIH. An exception interrupt triggered in I or S state, e.g. while an interrupt or SVC was handled, initiates a system stop. Otherwise, the program branches to the RMOS3 scheduler.

4.4.3 On-screen output On-screen output is handled by means of the RMOS3 nucleus routine x_nucprintf. Except the date and time (second row of an output), the EIH outputs all numerical values in hexadecimal format. The text output depends on the specific exception interrupt that was triggered in a specific system state (I, S, or A). Four different scenarios may develop in this case:

Scenario Exception triggered by System state 1 Task A 2 SVC S 3 Interrupt handler routine I 4 Interrupt handler routine S

Output data of the EIH has the following structure, with "x" representing any character (except space), while y represents any string. The error code line is only output if the corresponding exception interrupt returns a CPU error code.

An exception interrupt triggered by a task in A state leads to the following on-screen output.

*** nuc-<CoreID>: <date> <time> <exception text>: xxxx:xxxxxxxx

xxxx:yyyyyyyy ZZ....command

error code: y

caused by task <name> id: 0xXX tcb at address: xxxx:xxxxxxxx

eax: xxxxxxxx ebx: xxxxxxxx ecx: xxxxxxxx edx: xxxxxxxx

esi: xxxxxxxx edi: xxxxxxxx ebp: xxxxxxxx esp: xxxxxxxx

ss: xxxx ds: xxxx es: xxxx fs: xxxx gs: xxxx

cr0: xxxxxxxx, cr2: xxxxxxxx, cr3: xxxxxxxx

eflag: xxxxxxxx <(decoded flags)>

Line three will change if an interrupt handling routine in I state triggered the exception interrupt and return the following information:

caused by interrupt handler in I state, SYSTEM HALTED



Line three will change if an interrupt handling routine in S state triggered the exception interrupt and return the following information:

caused by interrupt handler in S state, SYSTEM HALTED

The exception interrupt handler will stop the system in both of these situations.

<exception text> depends on the exception interrupt and is representative for the following strings:

INT–NUM STRING INT 0: DIVIDE ERROR AT ADDRESS: INT 1: DEBUG EXCEPTION NEAR ADDRESS: INT 3: BREAKPOINT EXCEPTION NEAR ADDRESS: INT 4: OVERFLOW EXCEPTION NEAR ADDRESS: INT 5: BOUNDS CHECK NEAR ADDRESS: INT 6: INVALID OPCODE AT ADDRESS: INT 7: NO COPROCESSOR AVAILABLE AT ADDRESS: INT 8: DOUBLE FAULT EXCEPTION AT ADDRESS: INT 9: NPX SEGMENT OVERRUN NEAR ADDRESS: INT 10: INVALID TSS AT ADDRESS: INT 11: SEGMENT NOT PRESENT AT ADDRESS: INT 12: STACK FAULT AT ADDRESS: INT 13: GENERAL PROTECTION AT ADDRESS: INT 14: PAGE FAULT AT ADDRESS: INT 16: FLOATING–POINT ERROR NEAR ADDRESS: INT 17: ALIGNMENT CHECK NEAR ADDRESS:

Depending on whether the EIP register contains the address of the command that triggered the exception interrupt, or of the next command, the EIH outputs AT ADDRESS or NEAR ADDRESS.

Example of on-screen output:

*** nuc-0: 02-JAN-2003 10:39:44, GENERAL PROTECTION AT ADDRESS: 0270:0000027A

0270:0000027A 64C60000 MOV BYTE PTR FS:[EAX],00

error code: 0

caused by task id: 0x21: ‘exep prot’

eax: FFFFFFFF, ebx: 00000000, ecx: 00000280, edx: 00000068

esi: AA55AA55, edi: 000002B8, ebp: FFFFFF78, esp: FFFFFF64

ss: 0278, ds: 0280, es: 0280, fs: 0000, gs: 0228

cr0: 7FFFFFE3, cr2: 00000000, cr3: 0000C000

eflag: 00010282 ( SIGN INTERRUPT IOPL(0) RESUME )***

The example shows the on-screen output of the EIH following a GENERAL PROTECTION exception interrupt that was triggered by the EXEP task with ID 21.

A Page Fault Exception is triggered by attempts to write data to memory areas that are read only for the respective privilege level. Errors can be analyzed using the GNU tools.



4.4.4 Non-Maskable Interrupt The NMI (INT 2) is processed only in the Assembler section of the EIH. The following strings are output to the screen:

*** nuc-0: <date> <time> NMI INTERRUPT

4.4.5 Product package The EIH is included by default in RM3BAS.LIB and is linked automatically when the system is generated. The EIH is also supplied as source code for customization purposes in the MISCIN.ASM and EXCOUT.C files in the SOURCE\ETC\CADUL directory. The DEB_START switch is accordingly set to FALSE by default, which means that the RMOS3 debugger is not started if an exception interrupt is triggered during task processing.

4.4.6 Modifying the Exception Interrupt Handler Complete the following steps to customize the EIH to suit your requirements:

1. Edit the MISCIN.ASM and EXCOUT.C files in directory SOURCE\ETC\CADUL to suit your requirements.

2. Add the following lines to the batch file that you use to generate your RMOS3 system to compile the EIH source files:

Rule for generation with CAD-UL: AS386 MISCIN.ASM -VSYMUPPER -DRM3=1

@ECHO OFF

ECHO -VANSI -VNEARFAR -VROM -VFIXEDPARAMS -VSYMUPPER > CC.CMD

ECHO -VFARCRT -D_ARCHITECTURE_=386 -DRM3=1 >>CC.CMD

ECHO -VNDP -VCOMPACT -VSUBSYS=RM3CFG.SUB >>CC.CMD

IF "%EMU%"=="TRUE" ECHO -DFPU_EMULATOR=1 >>CC.CMD

ECHO ON

CC386 %RBASE%\SOURCE\ETC\CADUL\EXCOUT.C -I%RBASE%\INC @CC.CMD

@IF ERRORLEVEL 1 GOTO END

Rule for generation with INTEL: ASM386 %RBASE%\SOURCE\ETC\CADUL\MISCIN.ASM

IC386 %RBASE%\SOURCE\ETC\CADUL\EXCOUT.C SI (%RBASE%\INC\)

3. The generated MISCIN.OBJ and EXCOUT.OBJ object files must be linked before RM23BAS.LIB in the compiler session. Edit the batch file that you use to generate your RMOS3 system accordingly.

Note

Intel tools create the objects in the directory that contains the source file, while the CAD-UL tools create them in the current directory.

4. Generate your RMOS3 system.

System tasks 4.5 Busy task


4.5 Busy task

System task Due to its priority 1, the BUSY task is always active when no other task is active on the respective core. It is used for calculating the system load.

The source code of BUSY_MNG.C is available in directory SOURCE\ETC\CADUL. The RMOS3 nucleus creates and starts this task in the initialization task by means of x_bu_init procedure. The BU_COUNT task is cataloged accordingly and the following variables are provided:

act_count Current count value ref_count Reference value act_time Current system time in milliseconds start_time System time in milliseconds at the last call of x_bu_init or x_bu_get

Application example The reloadable BUSY.C task calls the x_bu_get function to determine the percentage of the system idle time.

The source code of the BUSY task (BUSY.C) is available in directory EXAMPLES\BUSY. You can use batch file BUSY.BAT to generate the reloadable program BUSY.386.

Possible output of the task:

interval too short

<idle time> % idle time on core 0




4.6 Utility programs for HSFS

HSFS functions The advanced I/O system processes file I/O requests of the nucleus. It positions itself between the nucleus and the basic I/O system and is realized with the help of the HSFS (High Speed File System) file management system.

In RMOS3, the HSFS manages the mass storage volumes (floppy disk and HD drives) and accesses the storage media by means of drivers (HD0, FD0). RMOS3 will therefore take complete and exclusive control of individual physical drives.

System tasks 4.6 Utility programs for HSFS


High Speed File System HSFS is a high-performance system for handling file-oriented operations in an RMOS3 environment. The organization on the storage medium is DOS–compatible, which means that data can be exchanged between RMOS3 and the PC system without any problem.

Read and write access to mass storage media is possible by means of CRUN calls to preserve the DOS–compatible file format. Since CRUN calls are compliant with the ISO/IEC DIS 9899 standard, portability of the programs is always ensured with CRUN calls.

The following system programs belong to HSFS:

● SCANDISK, for verifying and repairing the file system (cf. Reference Manual Part I)

● SYSCOPY, for non-fragmented storage of the boot file on the boot partition (see sections "SYSCOPY.EXE (Page 153)" and "SYSCOPY32.EXE (Page 155) ").

4.6.1 HSFS terminology and definitions

Three levels Stored data is accessed at three levels:

1. Data carrier

2. Directory

3. File

Data volume, partitions A data volume is a device that is operated by a device driver under control of the HSFS. The HSFS interprets this as a group of blocks that can be addressed independently (sectors), with uniquely retrievable block numbers of which each one contains 512 bytes. The HSFS can operate the data volumes as unit (e.g. floppy disk) or split into several areas. Such areas are called partitions. In the following, we do not differentiate between data volumes and partitions. The term data volume denotes the respective partitions of the physical storage medium. The data volume must be assigned a unique name in HSFS, the data volume name.

Directories The data volume name can be used to reach the root directory of each data volume. The root directory represents the root for further directories or files.

All other directories are referred to as subdirectories because in the hierarchy they are located below the root directories. Files contain the data that was saved by an application. Files must be assigned a name that is unique in the directory in which they were created.



The name and other management data is saved to a directory entry. There is only one unique path to this file from the root directory via one or several subdirectories. This is the so-called path. The path consists of the name of the data volume and of all subdirectories. The various names are separated by delimiters [:,\,/].

4.6.1.1 Data volume names

Unique designation consisting of two characters Each HSFS volume must be assigned a unique designation with a maximum length of two characters by the system originator. This designation is used for all subsequent operations with the data volume.

Both characters of the volume name must be in the range from 021H to 0FEH and must not contain question marks (?), asterisks (*), or delimiters [/,\,:] .

4.6.1.2 File names The characters [\, /, :] can be used as delimiters for the volume name, the directory, and the actual file name.

Note

File names (8.3) may be entered in uppercase and lowercase. HSFS converts lowercase to corresponding uppercase letters, provided these are defined in the ASCII-8 character set (e.g.: "ß" is not converted).

4.6.1.3 File attributes The following attributes can be assigned to files:

● Directory

● Volume name

● Byte/block unit file

● Write protection

● System file (no function)

● Hidden



File attribute byte These properties are stored in the file attribute byte that forms part of the control information in the directory block. Along with the apparent meaning, the following restrictions apply:

● You cannot edit, extend, delete or rename a write-protected file.

● You can only set the directory attribute when creating a file. It is not possible to subsequently delete or set this attribute.

● You cannot delete, extend, or rename files stored in a write-protected directory or change the file attributes, even when the files themselves are not write-protected.

● It is not possible to create new files in a write-protected directory.

● Files and directories with "hidden" attribute cannot be displayed using the DIR command. The RD /S can be used to delete the files.

● The "system file" attribute is only supported to preserve DOS compatibility. It has no function otherwise.

4.6.2 HSFS requirements for device drivers

Mass storage media convention HSFS interprets all mass storage volumes as a sequence of n blocks numbered from 0 to n–1, with a fixed block length of 512 bytes. All HSFS device drivers must conform to this convention, independent of the physical storage organization of the respective unit.

Function list of the mass storage device driver HSFS presumes that all mass storage device drivers provide the following functions:

Table 4- 11 Functions of mass storage device drivers

Function number Function 2 Read block 3 Write block 4 Format unit 5 Read blocks 6 Write blocks



Functions 2, 3, 5 and 6 are assigned the following parameters:

Table 4- 12 Parameters

Byte Content 0..3 Block number (dword) 4..9 Buffer address 10..13 Number of blocks to read or write; only necessary

for functions 5 and 6 Length: 14 bytes

A parameter list is not expected for function 4.

I/O completion status HSFS interprets only the following completion status indicators, which are to be transferred to the least significant byte of the dword:

Table 4- 13 Completion status indicators

Status Meaning 0 Request is queued 1 (reserved) 2 Successful completion 0FFH (–1) Parameter error 0FEH (–2) (reserved) 0FDH (–3) Timeout error 0FCH (–4) (reserved) 0FBH (–5) Hardware I/O error

Sequence of access to data volumes Once a mass storage volume was mounted in HSFS, the system first reads block 0 of the volume (boot sector), and secondly the file allocation table (FAT) that indicates the volume blocks that are already allocated and the blocks not yet occupied. This table is saved to a RAM buffer and can be accessed as long as the volume is mounted.

Performance factors HSFS allocates space available on the volume in ascending order of the block numbers. This means that it is always likely that access is preferably made to a block in the lower number range, rather than to a block in the upper number range.



This assignment characteristic may have an impact on performance, as HSFS device drivers convert block numbers into a physical memory address prior to memory access. For this reason, the device drivers of a portable HD with multiple platters support the following strategies for block numbering:

● The blocks are numbered horizontally along tracking area 0, then along tracking area 1, etc.

● The blocks are numbered in perpendicular mode along cylinder 0, then along cylinder 1, etc.

It follows with the first assignment strategy that tracking area 0 is out of space before tracking area 1, a.s.f.

In contrast, the second strategy occupies available storage space based on the order of the cylinder numbers.

It is apparent that method one involves a significantly higher number of scan operations (head movements) and therefore diminishes HSFS performance.

When designing drivers for mass storage devices, these aspects must be taken into account if minimum reaction times of HSFS are an issue.

Sectors Cluster length Sectors/clusters FAT length < 4085 1.5 (12 bits) 1 Sectors/314 4086 ... 8171 1.5 (12 bits) 2 12 8172 ... 16243 1.5 (12 bits) 4 12 > 16344 2 (16 bits) 4 Sectors/1024

4.6.3 Processing requests to the file management system All requests to the file management system are handled by means of the C runtime interface CRUN.

One task per volume A dynamic task is created for each volume during HSFS initialization. Each task is assigned its own stack and data range.

The HSFS request is transferred by the CRUN interface and converted into SVC calls. Based on the parameter block and opcode, the SVC handler now determines the target volume for the request. With a RmQueueStartTask request, a start request is transferred to RMOS3 for the respective task. The user information is written to the RCB that the operating system needs for queuing operations.

Parallel/sequential processing With this approach, requests to one volume are processed sequentially in the order of their occurrence, while requests to different volumes are processed in quasi-parallel mode. It is no longer possible to cancel a request that was already queued.



HSFS error codes If several user tasks simultaneously output requests to the file management system and the number of open files (FCB), channel links (CCB) or buffer blocks (BB) is insufficient, one of the following messages is output (by means of RmIO) to the system console:

*** HSF: no FCBS!

*** HSF: no CCBS!

*** HSF: no BBS!

In this case, it is necessary to adjust the file system parameters in section [HSFS] of RMOS.INI, or in the system generation (RcInitHSFS).

4.6.4 Internal organization of the HSFS

Buffering the FAT HSFS loads the FAT (File Allocation Table) to RAM when a volume is mounted in order to accelerate access to individual blocks of a file. The FAT is written back to the HD when you dismount the volume.

Data structures HSFS employs a number of different data structures for processing. A differentiation is made between local and global data. Local data is assigned respectively to an HSFS task and therefore to a volume. Global data is available in a constant quantity (configurable) and provided to the respective tasks by means of corresponding routines. Access to the global data is protected by means of a semaphore, which means that only one HSFS task can fetch such a data block from the linked lists.

VCB Volume Control Block

The VCB is a local block that contains all data that is necessary for handling the respective volume. The block is used, for example, to store the volume flags, device and unit, pointers to the FAT buffer and to the boot sector of the volume.

FCB File Control Block

This block is a global data structure. An FCB is created for each open file and contains, in addition to the complete directory index, all valid global data for the file.



CCB Channel Control Block

The CCB is also a global data structure. One CCB is assigned to each open channel. The CCB is always linked to an FCB. The CCB is used to store all channel-related values such as the current position of the read or write pointers. The channel number transferred to a user corresponds internally to a CCB.

BB Buffer Block

Buffer blocks (BB) are used to store blocks read from volumes. These blocks facilitate immediate availability of data that is frequently used without having to output a driver call. Buffer management employs a Least–Recently–Used method (LRU), to remove blocks with the lowest access rate from the buffer, while retaining blocks with higher access rates in the buffer.

8-character names plus 3-characters extension for FAT12 /FAT16/FAT32 All HSFS files of a volume, including the directories, are assigned a file name. The file name defines the target of an open, close, or search operation in the directory. File names consist of two parts, namely the name with a maximum length of 8 characters plus the extension with a maximum length of 3 characters. The file name and extension are delimited by a dot. Valid characters include those in the range from 20h to 0FEH, except the following characters: [?, *, \, /, :]. A file name containing more than 8 characters is truncated to 8 characters. File names and extensions shorter than the valid values are padded with blanks. A file name that consists only of space characters is invalid.

Extensions for VFAT16/VFAT32 Support for long file names in the FAT16 file system is also known as VFAT16. In the FAT32 file system, this is known as VFAT32. The file system was extended so that long file names can now be used in addition to the previous 8.3 file names.

A "long name" including the pathname may consist of a maximum of 195 characters. An additional 8.3 file name is therefore available as representative for any long name.



4.6.5 Volume structure

Boot sector A volume consists of a fixed number of blocks. The first block, the so-called boot sector, describes the structure and size of the volume.

FAT The information on allocated and free data blocks, including their assignment to files or directories is stored in blocks that immediately follow the boot sector. These blocks are also known as File Allocation Table (FAT). Their size depends primarily on the volume size. Since this is vital information, one or even several copies of the FAT are saved to the volume. The length of the FAT and the number of copies are written to the boot sector.

Root directory In FAT16, these entries are followed immediately by the root directory with a length that is also entered in the boot sector. The blocks between the last block of the root directory block through to the last block of the volume are available for storing data. A conventional root directory no longer exists in FAT32. It is written to linked clusters in the data area, similar to the subdirectories.

Cluster An unnecessary length of the FAT is avoided by grouping several contiguous blocks in management units, namely clusters. The cluster length determines the number of blocks per cluster. A cluster is the smallest allocation unit. Each file is always assigned an integer number of clusters. This means that a file containing only one byte as parameter will occupy one or several blocks on the volume. DOS allows cluster lengths with power of two, i.e. values in the range [1,2, 4..128].

Finding blocks Blocks belonging to a file are found with the help of the FAT. This block scan is based on a calculation method as in DOS.



4.6.5.1 Maximum file and volume lengths

8 GB volume, with max. 2 GB per partition for FAT16 A FAT16 volume that is accessible in HSFS may encompass 8 GB, with maximum partition size of 2 GB (231 bytes). A storage unit that physically exceeds this size must be partitioned to obtain two or several partitions with a maximum size of 2 GB.

The length of files is unlimited within the storage limits of the volume. The file may have a maximum length close to 2 GB, because at least one block must be reserved for the root directory.

128 GB volume, with max. 32 GB per partition for FAT32 Each FAT32 partition has a maximum assured size of 32 GB.

Note

You could use FreeDos to create partitions of a greater size, but his may lead to fatal system errors!

A storage unit of a physical size exceeding 32 GB must be partitioned to obtain two or several partitions (maximum 4) of which none exceeds the size of 32 GB. The maximum file size is 4 GB – 1 byte (4,294,967,295 bytes).

4.6.5.2 Format data structures HSFS is completely organized internally based on a file-oriented concept. HSFS, for example, interprets the directories of a volume mounted with mount as open files that do not differ in any way from other files and handles these accordingly. Prerequisite are recursive runtime-invariant properties of the HSFS basic routines that result in an ultra-compact program system.

An HSFS mass storage unit with n blocks has the following structure:

Table 4- 14 Structure of a mass storage unit

Block Content 0 Boot sector; necessary for identification of the volume format. 1..k FAT; stores the logical organization of the data sectors. The

number of blocks reserved for the FAT is specified in the VIB table. k+1..(fat_cnt+1)*k This storage area comprises fat_cnt copies of the FAT. If it is

omitted, the next areas are shifted forward by k blocks. (fat_cnt+1)*k+1..m Root directory (FAT16 only); the number of blocks reserved for the

root directory is specified in the VIB table. m+1..n–1 Available storage space and file structures.



4.6.5.3 Organization of directory entries The search call reports a directory entry that has the following structure (however, the physical structure of the data conforms to DOS conventions):

Table 4- 15 Structure of a directory entry

Byte Content 0–11 File name; left aligned, padded with blanks, byte 8 is always "." 12–13 Record length in bytes (1) 14–17 Number of records in file 18–21 Index for the first occupied cluster of the file 22–23 Reserved 24 File attributes

Bit Meaning 0 System file 1 hidden 2 read-only 3 Directory 4 Volume name 5 Archive 6 reserved 7 Device driver file

25 Reserved 26–27 Time of creation or last change of the file 28–29 Date of creation or last change of the file 30–31 Reserved Length: 32 bytes

Date and time values are stored based on the following scheme:

Byte 27 Byte 26 H H H H H M M M M M M S S S S S whereby: H = binary number of hours (0..23) M = binary number of minutes (0..59) S = binary number of seconds divided by 2 (0..29) Byte 29 Byte 28 Y Y Y Y Y Y Y M M M M D D D D D whereby: Y = binary number of years starting 1980 (0..119,1980..2099) M = binary number of months (1..12) D = binary number of days (1..31)



4.6.6 System programs for HSFS The following system programs belong to HSFS:

● SCANDISK, for identifying and repairing data volume errors (cf. Reference Manual Part I)

The program is available in OMF–386–STL format and can be launched by means of CLI or debugger.

● SYSCOPY, for non-fragmented storage of the boot file on the boot partition (cf. Reference Manual Part I and section "SYSCOPY.EXE (Page 153)"). This program is only available for FAT16 partitions.

● SYSCOPY32, for non-fragmented storage of the boot file on the boot partition (cf. Reference Manual Part I and chapter " SYSCOPY32.EXE (Page 155)"). This program is only available for FAT32 partitions.




System programs 5 5.1 Introduction

DOS programs RDISK.EXE sets up a boot sector on a formatted floppy disk, or on a primary partition that is formatted in DOS.

VERS.EXE displays the version number of RMOS3 modules.

LOADX serves to load the RMOS3 nucleus to address ranges above 1 MB.

BLOWUP.EXE serves to enlarge the RMOS3 nucleus to a uniform file length.

SYSCOPY.EXE writes the non-fragmented boot file to the boot partition.

Windows PE programs RDISK32.EXE sets up a boot sector on a primary partition that is formatted in Windows PE.

SYSCOPY32.EXE writes the non-fragmented boot file to the boot partition.

RMOS boot loader RMLDR represents the RMOS boot loader on the target system.

RMLDRFAT.16 is the factory state of RMLDR for FAT16 partitions.

RMLDRFAT.32 is the factory state of RMLDR for FAT32 partitions.

RDISK.EXE or RDISK32.EXE will automatically rename RMLDRFAT.16 and RMLDRFAT.32 to RMLDR during setup on the target system.

5.2 RDISK.EXE RDISK.EXE sets up a boot sector on a formatted floppy disk, or on an active primary partition that is formatted in MS-DOS. RDISK.EXE is a 16-bit program.

Run RDISK.EXE from subdirectory UTIL. RDISK returns the following syntax information:

Syntax RDISK Version x.y usage: RDISK <drive> [<bootfile>] <drive> ; 0 = floppy disk A: or disk C: ; 1 = floppy disk B: or disk D: [<bootfile>] ;up to 12 chars xxxxxxxx.xxx

System programs 5.2 RDISK.EXE


The <bootfile> setting is optional; the default value of <bootfile> is derived from the further runtime. The reference to 12 bytes relates to the full length of the file name, including the dot and extension. Path names cannot be implemented in this variable.

Menu 1 For example, if you enter

RDISK 0

(for floppy disk A: or hard disk partition C:), the following menu is displayed on the screen (with RDISK 1 accordingly drives B: and D:):

RDISK Version x.y

E = Exit

1 = Install RMOS PC1 boot sector on diskette drive A:

2 = Install RMOS PC1 boot partition on hard disk drive C:

3 = Change active hard disk partition

Enter [Function–# <CR>] or [E <CR>]

Menu 2 If you now make a further selection, e.g.

1 = Install RMOS PC1 boot sector on diskette drive A:

RDISK activates an additional menu in which you can view the default name of the boot file.

E = Exit ––> no bootsector installation

1 = Install default bootfilename RM2_PC1.SYS for RMOS2

2 = Install default bootfilename RM3_PC1.SYS for RMOS3

3 = Install default bootfilename RMLDR for second stage boot

Enter [Function–# <CR>] or [E <CR>]

Note

This menu is only output if you have not specified the <bootfile> variable in the call of RDISK.

Menu 3 If you select

2 = Install RMOS PC1 boot partition on hard disk drive C:

in menu 1, RDISK.EXE displays the available HD partitions, e.g:

System programs 5.2 RDISK.EXE


┌────────────────────────────────────────────────────────────────────────────────┐ │Drive 0: 5 Heads and 731 Cylinders with 17 Sectors │ │Partitionable of Home Partition Sector │ ├───┬──────┬────────────────┬───────────────┬───────────────┬─────────┬──────────┤ │ │ │ │ Starting loc. │ Ending loc. │ rel. │ max. │ │ # │ Boot │ System Type │ Head Cyl. Sec │ Head Cyl. Sec │ BootSec │ Sectors │ ├───┼──────┼────────────────┼───────────────┼───────────────┼─────────┼──────────┤ │ 0 │ No │ not used │ 0 │ 0 │ │ │ │ │ │ │ 0 │ 0 │ 0 │ 0 │ │ │ │ │ 0 │ 0 │ │ │ ├───┼──────┼────────────────┼───────────────┼───────────────┼─────────┼──────────┤ │ 1 │ No │ not used │ 0 │ 0 │ │ │ │ │ │ │ 0 │ 0 │ 0 │ 0 │ │ │ │ │ 0 │ 0 │ │ │ ├───┼──────┼────────────────┼───────────────┼───────────────┼─────────┼──────────┤ │ 2 │ No │ not used │ 0 │ 0 │ │ │ │ │ │ │ 0 │ 0 │ 0 │ 0 │ │ │ │ │ 0 │ 0 │ │ │ ├───┼──────┼────────────────┼───────────────┼───────────────┼─────────┼──────────┤ │ 3 │ Yes │ DOS, 16-Bit-FAT│ 1 │ 4 │ │ │ │ │ │ │ 0 │ 731 │ 17 │ 62203 │ │ │ │ │ 1 │ 17 │ │ │ └───┴──────┴────────────────┴───────────────┴───────────────┴─────────┴──────────┘ Enter [Partition-# <CR>] or [E <CR>]

Note

If you unintentionally select a partition that you want to use as boot partition along with your RMOS3 partition (e.g. a DOS partition) you can no longer boot from this partition. In this case, the system expects a boot file, e.g. RM3_PC1.SYS, that does not exist on the DOS partition.

If the <bootfile> variable was not specified, menu 2 is displayed after you selected the partition. Select the default name of the <bootfile> variable in this menu. Otherwise, menu 2 is skipped.

RDISK ends itself after you selected the floppy drive or HD with the message:

RMOS FATxx bootsector installed for file <bootfile> boot

5.2.1 (Error) messages of RDISK.EXE RMOS FATxx bootsector installed for file <filename> boot

Successful installation of the boot sector, including the specification of the boot file name. RMOS PC1 bootsector not installed

RDISK was canceled prematurely by the user.

System programs 5.3 RDISK32.EXE


5.3 RDISK32.EXE

Function RDISK32.EXE sets up a boot sector on an active primary partition that is formatted in Windows PE. RDISK32.EXE is an 32-bit application.

Syntax RDISK32 <drive letter>

Parameters Parameters Meaning drive letter Letter of the drive on which the boot sector has to be set up. With or without

":".

Description The RDISK32.EXE tool ensures that a boot sector is set up on an active primary partition that is formatted in Windows PE. The tool runs in Windows PE.

Note

If you unintentionally select a partition that you want to use as boot partition along with your RMOS3 partition (e.g. a DOS partition) you can no longer boot from this partition. In this case, the system expects a boot file, e.g. RM3_PC1.SYS, that does not exist on the DOS partition.

On completion, RDISK32 outputs the following message and is closed automatically: RMOS (FATxx) boot loader successfully installed on drive c:

Error messages *** RDISK32: Access is denied.

RDISK32 was used on the system volume.

*** RDISK32: Illegal drive letter.

The specified volume was not found.

Example RDISK32 c:

System programs 5.4 VERS.EXE


5.4 VERS.EXE VERS is a utility program that can display the version numbers of modules, which are contained in object files, libraries, or system files. The files from which VERS.EXE extracts this information must contain a specific data array. The example below highlights the structure of this data array for the C programming language.

static const char idstr [ ] =

{

"\0" "(C) SIEMENS AG 1994" "\0"

"\1" "EXP_CRUN.C" "\1"

"\2" "0007" "\2"

"\3" "P.F." "\3"

};

The string "(C) SIEMENS AG 1994" that is enclosed by two characters (bytes) with ASCII value 0 serves as identifier for the VERS.EXE program. For this reason, you can only edit the year value if you use the VERS.EXE tool. The entry with the name of the source file is enclosed by two characters with ASCII value 1. This is followed by the version number, enclosed by two characters with the ASCII value 2. The program author is entered between the two characters with the ASCII value 3.

Wildcards are not supported.

VERS is based on the following syntax:

Syntax VERS <file name>

Example VERS RM3HLI.LIB <CR> Vers Vx.y Mon Apr 14 18:34:55 1997 rm3hli.lib RMOS3–HLI V2.5 P.F.

System programs 5.5 LOADER.386


5.5 LOADER.386 The LOADER program loads a dynamic RMOS3 to the background and then terminates itself. The program can be called manually from the CLI, or automatically by means of RUN command in RMOS.INI.

Syntax LOADER.386 [<pl0path>\PL0.386][CORE <n>] <path>\<progname>.<ext> [<arg2>] [<arg3>]...

Parameter name Meaning <pl0path> Complete path of the directory that contains the

PL0.386 tool. For example, C:\RM3RUN PL0.386 The program to load is to run on PL0. CORE <n> The program to load is to be bound to CORE

<n>. <path> Complete path to the directory that contains the

program to load. For example, C:\RM3RUN

<progname> Name of the program to load. For example, RmIShSrv

<ext> Extension of the program to load. For example DRV

<arg n> Transfer parameter of the program to load.

If the loader is started without call parameters, it displays its call syntax on the screen.

Example Example for calls from the CLI:

C:\RM3RUN\LOADER.386 C:\RM3RUN\RMISHSRV.DRV

C:\RM3RUN\LOADER.386 CORE 0 C:\RM3RUN\USB11.DRV

C:\RM3RUN\LOADER.386 C:\RM3RUN\PL0.386 CORE 0 C:\RM3RUN\USB11.DRV

Example for calls from RMOS.INI

run=C:\RM3RUN\LOADER.386 C:\RM3RUN\RMISHSRV.DRV

5.5.1 Error messages LOADER_ERROR: FILE NOT FOUND

The specified file was not found (in the specified path). LOADER_ERROR: ALLOC_ERROR

The loader failed to allocate memory it needs.

System programs 5.6 RMLDR, RMLDRFAT.16, RMLDRFAT.32


5.6 RMLDR, RMLDRFAT.16, RMLDRFAT.32

General Using the standard RMOS3 boot loader stored in the boot sector of a HD/Compact Flash Card with utility RDISK.EXE (MCFORM.EXE for MC, not included in the scope of delivery), you can only load RMOS3 to the 640 KB memory space. Spatial reasons prevent the boot loader from switching to the protected mode to load RMOS3 to the address space above 1 MB.

As solution, a second stage RMOS3 boot loader is loaded along with the standard RMOS3 boot loader. This second stage boot loader (default name: RMLDR) switches to the protected mode to load the RMOS3 system to any position in memory.

Notes Observe the following aspects:

● Partitions in FAT32 must have a minimum size of 4 GB.

● One RMLDR version is available for FAT16 (RMLDRFAT.16), and one for FAT32 (RMLDRFAT.32). RDISK.EXE or RDISK32.EXE identifies a FAT16 or FAT32 partition and automatically uses the correct RMLDR.

● The RMLDR (second stage boot loader) must be installed in first position on the data volume and written in uppercase!

● The RMOS3 boot file RM3_PC1.SYS must follow RMLDR in second place on the data volume and may not be fragmented! It may also be written in lowercase notation. You can use the SYSCOPY or SYSCOPY32 tool to save the file in non-fragmented state (see sections "SYSCOPY.EXE (Page 153)" and "SYSCOPY32.EXE (Page 155)").

● You cannot load code to the address space below 0x8000 (32 KB)!

● RMLDR can only be used to boot from the primary partition.

The second stage boot loader always starts by scanning the volume for RM3_PC1.SYS.

● This file will be loaded if found on the data volume.

● The first file with extension *.SYS is loaded if RM3_PC1.SYS is not found. RMLDR verifies that this is an RMOS3 boot file.

System programs 5.6 RMLDR, RMLDRFAT.16, RMLDRFAT.32


5.6.1 Installing the second stage boot loader RMLDR

Installation on HD or Compact Flash Card with DOS USB Flash Drive ● Boot MS-DOS.

● Format the HD. Call: "format c: /q/u"

● Call "rdisk 0".

● Select "2 (Install RMOS PC1 boot partition on harddisk drive C:)".

● "Select "0" (boot partition).

● "Select "3 (Install default boot file name RMLDR for second stage bootloader)".

● ""E Exit" rdisk

● Copy "RM3_PC1.SYS" to the HD using SYSCOPY.

Installation on HD or Compact Flash Card using a Windows PE USB Flash Drive ● Boot Windows PE.

● Format the HD. Call: "format c: /fs:fat /q", or "format c: /fs:fat32 /q"

● ""rdisk32 c:"

● Copy "RM3_PC1.SYS" to the HD using SYSCOPY32.

System programs 5.7 LOADX.EXE


5.7 LOADX.EXE

Function Load the RMOS3 nucleus to an address space above 1 MB.

Syntax LOADX <filename> [/s]

Parameters Parameters Meaning filename RMOS3 nucleus as LOC file with OMF386 output

format, e.g. RM3_PC1.LOC /s Silent mode, LOADX messages re suppressed.

Description LOADX.EXE can be used to load the RMOS3 nucleus to an address space above 1 MB. This is necessary if the length of the RMOS3 nucleus exceeds 608 K. LOADX.EXE is called in MS-DOS. No drivers or memory managers may be loaded concurrently at this point in time. The percentage of already loaded data of the RMOS3 nucleus is displayed on a progress counter: Loading xxxxxxxx bytes at address yyyyyyyy ( zzz% )

MS-DOS no longer exists after the RMOS3 operating system was booted.

Error message Processor is already executing in Virtual 86 mode ! Load aborted.

The processor is already running in Virtual 86 mode. Remedy: reboot the system in MS-DOS. Try again with a filename

LOADX was started without call parameters File is not in OMF386 bootloadable format: <filename> Was it output from BLD386 ?

An attempt was made to load a file that is incompatible with OMF386 bootstrapping Loading xxxxxxxx bytes at address yyyyyyyy ( zzz% )

The progress counter has frozen. Remedy: A driver or memory manager was loaded in MS-DOS. Remove the driver or memory manager and reboot.

Example Call in AUTOEXEC.BAT: LOADX C:\RM3RUN\RM3_PC1.LOC

System programs 5.8 BLOWUP


5.8 BLOWUP

Function BLOWUP.EXE can be used to extend the RMOS3 nucleus RM3_PC1.SYS to a selected length.

Syntax blowup <size> <name>

Parameters Parameters Meaning size Selected file size in KB.

Default is 608 KB. name Name of the file to extend.

Default is "RM3_PC1.SYS".

Description You can prevent fragmentation on a boot volume with different RMOS3 systems of different length by extending the RMOS3 nucleus RM3_PC1.SYS to a specific length.

RMOS3 systems to be loaded below 1 MB may not exceed a maximum length of 608 KB. There is no restriction above 1 MB.

System programs 5.9 SYSCOPY.EXE


5.9 SYSCOPY.EXE

Function Copy unfragmented RMOS3 nucleus ((e.g. RM3_PC1.SYS) to the boot partition.

Syntax SYSCOPY <filename> <volume_name>

Parameters Parameters Meaning filename Name of the boot file (including the pathname) (source file) volume_name Boot partition (target volume)

Description SYSCOPY.EXE serves to install a new version of RMOS3 nucleus RM3_PC1.SYS.

For this purpose, SYSCOPY.EXE verifies that the specified RM3_PC1.SYS file can be copied to the second place in the file system after the second stage boot loader RMLDR. SYSCOPY.EXE extends the RM3_PC1.SYS to 1 MB to ensure that the RMOS3 nucleus is written to the target volume in non-fragmented state during updates.

Target drive must be the active primary partition of the volume.

SYSCOPY.EXE is called in DOS (16-bit).

Long file names are not supported

An executable version for Windows PE or RMOS3 is also available (see section "SYSCOPY32.EXE (Page 155)", or SYSCOPY.386 in the Reference Manual Part I).

Error message No support for long filenames.

The source file must be provided in 8.3 format. Long file names are not supported Cannot open <filename>.

Error when opening the <filename> file. File <filename> has not the correct file size (is: <size>; expected: <exp_size>) Use the old SYSCOPY V1.0!

Target file size is not 1 MB. In this case, use SYSCOPY.EXE V1.0. File size of <filename> is too high (is: <size>; expected: <exp_size>)

This error occurs if the length of the source file exceeds 1 MB.

System programs 5.9 SYSCOPY.EXE


Cannot allocate memory

This error occurs if the system runs out of memory resources. Unknown FAT system

This error occurs if the file system format is unknown. RMOS bootfile <bootfile> is not the second file on the disk. Use the old SYSCOPY V1.0

This error occurs if the boot file is not in second place on the partition. In this case, use SYSCOPY.EXE V1.0. File is too big for destination!

This error occurs if insufficient storage space

is available on the target volume. Wrong arguments!

Incorrect call parameters. Only c: and d: are allowed for destination disk.

Only C: and D: are valid target drives. Partition <x> is not active.

The partition is not active.

Example SYSCOPY C:\RM3_PC1.SYS D:

System programs 5.10 SYSCOPY32.EXE


5.10 SYSCOPY32.EXE

Function Copy unfragmented RMOS3 nucleus ((e.g. RM3_PC1.SYS) to the boot partition.

Syntax SYSCOPY32 <filename> <volume_name>

Parameters Parameters Meaning filename Name of the boot file (including the pathname) (source file) volume_name Boot partition (target volume)

Description SYSCOPY32.EXE serves to install a new version of RMOS3 nucleus RM3_PC1.SYS.

For this purpose, SYSCOPY32.EXE verifies that the specified RM3_PC1.SYS file can be copied to the second place in the file system after the second stage boot loader RMLDR. SYSCOPY32.EXE extends the RM3_PC1.SYS to 1 MB to ensure that the RMOS3 nucleus is written to the target volume in non-fragmented state during updates.

Target drive must be the active primary partition of the volume.

SYSCOPY32.EXE is called in Windows PE (32-bit).

Long file names are not supported.

An executable version for DOS or RMOS3 is also available (see section "SYSCOPY.EXE (Page 153)", or SYSCOPY.386 in the Reference Manual Part I).

Error message No support for long filenames.

The source file must be provided in 8.3 format. Long file names are not supported. Cannot open <filename>.

Error when opening the <filename> file. File <filename> has not the correct file size (is: <size>; expected: <exp_size>) Use the old SYSCOPY V1.0!

Target file size is not 1 MB. In this case, use SYSCOPY.EXE V1.0. File size of <filename> is too high (is: <size>; expected: <exp_size>)

This error occurs if the length of the source file exceeds 1 MB.

System programs 5.10 SYSCOPY32.EXE


Cannot allocate memory

This error occurs if the system runs out of memory resources. Unknown FAT system

This error occurs if the file system format is unknown. RMOS bootfile <bootfile> is not the second file on the disk. Use the old SYSCOPY V1.0

This error occurs if the boot file is not in second place on the partition. In this case, use SYSCOPY.EXE V1.0. File is too big for destination!

This error occurs if insufficient storage space

is available on the target volume. Wrong arguments!

Incorrect call parameters.

Example SYSCOPY32 W:\RM3_PC1.SYS C:


Abbreviations/Glossary A

API Application Programming Interface

APIC Advanced Programmable Interrupt Controller

BIOS Basic Input/Output System

BPB BreakPoint Block

BSP Board Support Package.

CAD-UL Computer Aided Design Ulm, compiler manufacturer

CLI Command Line Interpreter, user interface to the operating system.

Client Consumer or client of a utility, sometimes the term denotes a role behavior in the relation between two co-operating processes in which the client takes over the active, requesting role.

Configuration space All modules on the PCI bus must provide a block of 64 dwords for their configuration data. The first 16 dwords are defined by the PCI specification.

Abbreviations/Glossary


CPCI Compact Peripheral Component Interconnect

CRUN ANSI C runtime library for RMOS3. Provides all C functions in accordance with ANSI Draft standard ISO/IEC DIS 9899 (published 1990) in the RMOS3 multitasking environment.

DCB Driver Control Block; table that lists the current dynamic data of the driver.

DCD Driver Control Data; table that contains the default configuration values.

Device Driver program; I/O operations are handled in RMOS3 by means of special programs, driver programs - in short drivers - and their units. The drivers to be made available to the operating system are specified during system configuration. The operating system identifies drivers based on their number, namely the device ID.

DMA Direct Memory Addressing

Driver Program module in the operating system, which operates or controls an I/O block

DWB Directory Wait Block

EIDE Enhanced Integrated Drive Electronics

EOI End Of Interrupt

EPROM Erasable Programmable Read Only Memory, semiconductor memory chip that can be programmed by users



EEPROM Electrically Erasable EPROM (non-volatile memory)

EWB Event Flag Wait Block, management block for waiting for an event flag

FTP File Transfer Protocol

GDT Global Descriptor Table

Heap Memory pool

HLL High Level Language debugger

HPET High Precision Event Timer

HSFS High Speed File System

IDT Interrupt Descriptor Table

IMC Industrial MicroComputer

IRB I/O Request Block transferred to a driver.

Job Programs and commands started from the CLI (RMOS3 command line interpreter).



LAN Local Area Network

LBA Logical Block Addressing

Message A message is interpreted in RMOS3 as content of a 3-word buffer

MMB Mailed Message Block; management block for waiting to fetch a message.

MPIC Master Programmable Interrupt Controller

NMI Non-Maskable Interrupt

NPX Numeric Processor Extension; numerical co-processor

PCI Peripheral Component Interconnect; data bus system of 32 bit width

PIC Programmable Interrupt Controller

PIT Programmable Interrupt Timer



Placeholder character Also known as wildcard or joker character. Special characters as ellipsis:

"*" represents a group of letters or numbers

"?" represents a single alphanumerical character

PWB Pool Wait Block; management block for waiting to allocate memory

Queue Queue

RAM Random Access Memory

RCB Restart Control Block; management block for start requests of tasks

RMB Receive Message Block; management block for waiting to receive messages.

RMOS Real-time Multitasking Operating System

ROM Read-Only Memory

Root directory In HSFS, files are stored in directories. In HSFS, directories form a hierarchic structure. The root directory represents the top level directory of a volume. Only one root directory is available per volume (partition).

RTQ Ready Task Queue, internal data structure of the nucleus for managing all tasks that are in READY state.



SDB Supervisor Descriptor Block; used for the transfer of parameters at system calls.

Server Service-providing partner in the relationship between two cooperating processes

SMR System Memory Resource; system memory block set up by the nucleus for internal management. Generic term for TMB, SWB, RMB, RCB, PWB, MMB,IRB, EWB

SPIC Slave Programmable Interrupt Controller

SRAM Shadow Random Access Memory

SRB System Request Block; supervisor request block, structure for storing status transitions

Subdirectory Denotes all directories on a volume that are not the root directory. Subdirectories must be assigned a name that is unique in the directory in which they were created.

SVC Supervisor Call; system call

SWB Semaphore Wait Block; data structure that the nucleus sets up for waiting for semaphore.

TCB Task Control Block; table that lists the current dynamic data for controlling a task.

TCD Task Control Data; table listing the default values. Created for static tasks in the configuration, and by the loader for dynamic task.



TCP Transmission Control Protocol

TCP/IP TCP Internet Protocol

Telnet Telecommunication Network, dialog service via TCP/IP networks

TIB Timer Control Block

TMB Time Monitor Block; set up by the nucleus for managing time-related calls

UART Universal Asynchronous Receiver and Transmitter; block for serial data transmission

UCB Unit Control Block; table that lists the current dynamic data for controlling a unit.

UCD Unit Control Data; table listing the default configuration values

Unit I/O device. One or several units are addressed by drivers. The units that a driver may address are specified in the driver configuration data. The operating system identifies units based on their number, namely the unit ID.




Index

3 3964(R) protocol, 15

A APIC support, 35 Argument value, 111 Attribute byte, 133 Automatic priority increase, 26

B BASE, 110 BB, 136, 137 Block length, 133 BLOWUP.EXE, 152 Boot sector, 138 bootfile, 144 BPB, 22 Breakpoint, 107, 108 Breakpoint Block, 22 Breakpoint context, 107, 108, 111 Breakpoints, 106 Buffer block, 136 Buffers, 99 BUSY, 89, 92 BUSY task, 130

C CANCEL, 96 CCB, 136, 137 CLI, 101 Clusters, 138 CNFTSK.386, 39, 40 CNTRL, 22 Communication, 99 Completion, 96 Configurable RMOS3 nucleus, 38 Configurator, 43 Context, 105 CREATE, 22

D Data types, 11 DCB, 89 DCB_CIRB, 87, 89 DCB_QIRB, 89 DCB_STS, 89, 90, 92 DCD, 91 DCD_FLAGS, 29 DCD_FMAX, 29 DCD_INIT, 28 DCD_SHR, 28 DCD_SVC, 88 Debug register, 107 Debug register breakpoint, 113 Debugger, 104 Device driver file, 140 Device drivers, 61 Device ID, 108 Directory Wait Block, 22 Driver, 61 Driver Control Block, 71 Driver Control Data, 70 Driver ID, 108 Driver initialization, 28 DWB, 22

E EIDE, 16 EIH, 125 ENDR, 22 Entry point, 91, 93 Error logger task, 124 Escape context, 107 Event flag, 59 Event Flag Wait Block, 22 EWB, 22 Exception handler, 31 Exception Interrupt Handler, 125 Execution breakpoint, 113 EXITK, 107 Expected interrupt, 67

Index


F FAT, 134, 139 FCB, 136 File Allocation Table, 134 File attribute, 132 Function, 91 Function code, 92

G GO, 107

H Hard breakpoint, 113 Heap, 124 High Speed File System, 130 HPET, 16 HPET support, 36 HSFS, 131

I I/O Request Block, 74 INHIB, 108 Initial priority, 27 Initialization task, 108 Interrupt handler, 93, 96, 99 Interrupt state, 94 Interrupt vector, 94 IRB, 74, 87, 88, 89, 90, 91, 97 IRB_TCB, 89 IRB_TMB, 88

L LBA mode, 16 LOADER, 148 LOADX.EXE, 151 Long file names, 103 Long form, 119 LOOK, 22 LRU, 137

M Mailbox, 59 Mailed Message Block, 22 Memory format, 112

Memory pool, 23, 59 MMB, 22 Monitor mode, 104, 106 Multitasking, 13

N NMI, 129 Number base, 110 Numerical notation, 110

P Parallel driver, 77, 89, 92, 95 Parallel drivers, 62 Partitions, 131 PAUSE, 22 Pool Wait Block, 22 Preemptive, 13 Preemptive bit, 87 Primary Channel, 16 Priority, 89 PWB, 22

R Race, 96 RCB, 22 RDISK.EXE, 143 release, 90, 91 Repetition counter, 110 REPSVC, 118 reserve, 90, 91 reserved, 89, 97 Resource reporter, 118 Restart Control Block, 22 RIO, 22 RM3_CODE32, 24 RM3_DATA, 24 RM3_PC1.LOC, 40 RM3_PC1.SYS, 39 RmIO, 87, 88, 95 RMLDR, 149 RMOS.INI, 38, 39, 40 Round-Robin, 13, 27, 50 Run, 50

S Scheduler, 97

Index


Second stage RMOS3 boot loader, 149 Secondary Channel, 16 Sectors, 131 SEFET, 22 Segment descriptor, 111 Segment registers, 111 Selector, 111 Semaphore, 59 Semaphore Wait Block, 22 Serial driver, 76, 89, 92 Serial drivers, 62 Shared interrupt, 17, 34 Short form, 119 Single-step interrupt, 107 SMR, 21, 49 Soft breakpoint, 113 SRB, 21 SRBS, 98 Stack, 24, 59 Stack requirement, 24 Start address, 26 Status array, 87 Status bytes, 91 Status variable, 93 status_ptr, 88, 91, 92, 97 SVC exception handler, 31 SVC vector, 24 SVC_VECTOR, 22 SWB, 22 System clock rate, 59 System console, 41, 49 System Memory Frequency, 21 System process, 78, 87, 95 System Request Block, 21

T Task Control Data, 25, 28 Task mode, 104, 106 TCB, 90 TCD, 22, 25, 59 TCD_AX, 26 TCD_BPRI, 26 TCD_BX, 26 TCD_CS, 26 TCD_DS, 26 TCD_EAX, 26 TCD_EBX, 26 TCD_EIP, 26 TCD_ES, 26 TCD_ESP, 26 TCD_FLAGS, 27

TCD_INPRI, 27 TCD_IP, 26 TCD_OVPRI, 26 TCD_RR_TICKS, 27 TCD_TIME, 26 TCP/IP, 16, 33 Time Monitor Block, 75 Timeout, 90, 93 Timeouts, 91, 95 Timer Monitor Block, 22 TMB, 75, 88, 89, 90, 93, 95 TMB_SADR, 90 TRAPNMI, 23 TSF, 22 Type I driver, 81, 98 Type II driver, 81, 91, 96

U UCB, 73, 89, 94, 95 UCB_CIRB, 87, 89 UCB_QIRB, 89 UCB_STS, 90, 92 UCB_TCB, 89, 90 UCD, 72 UCD_INTADR, 30 UCD_INTNO, 30 UCD_PORT, 30 Unexpected interrupt, 31, 68 Unit Control Block, 73 Unit Control Data, 72

V VCB, 136 VERS.EXE, 147 VFAT16, 103, 137 VFAT32, 103, 137

W Waiting, 87 Write protection, 133

X x_nucprintf, 127 XCIRB, 87, 88, 91 XDCB, 85, 88, 91 XDELTMB, 89, 92

Index


XDEVNUM, 88, 91 XDEVUNIT, 88, 91 XIODONE, 87, 88, 90, 97 XOVER, 92, 97 XQSETUNS, 95 XQTMB, 90 XSET_UNX_INT, 31 XSETUNS, 95 XSTATUS, 88, 92, 95, 97 XTIMEOUT, 93 XTNUM, 93 XTUNIT, 93 XUCB, 85, 88, 91, 95

Documents

RMOS3 V3.50 System Manual - Siemens AG V3.50 System Manual System Manual, 07/2012, A5E03692294-01