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

RMOS3 V3.50 System Manual

RMOS3

Real-time operating system RMOS3

RMOS3 V3.50

System Manual

System Manual

07/2012

A5E03692294-01

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.

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

Table of contents

1

2

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

1.1

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

1.2

Notations ...................................................................................................................................... 10

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

2.1

Introduction .................................................................................................................................. 13

2.2

2.2.1

2.2.2

2.2.3

2.2.4

2.2.5

2.2.6

2.2.7

RMOS3 operating system components ....................................................................................... 13

RMOS3 nucleus ........................................................................................................................... 13

High-level languages interface ..................................................................................................... 14

APIC driver ................................................................................................................................... 14

BYT driver .................................................................................................................................... 14

CRT driver .................................................................................................................................... 14

COM driver ................................................................................................................................... 15

DMA driver ................................................................................................................................... 15

2.2.8

2.2.9

RAM-DISK driver.......................................................................................................................... 15

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

2.3.1

2.3.2

2.3.3

2.3.4

2.3.5

2.3.6

2.3.7

2.3.8

2.3.9

Structures and elements of the RMOS3 nucleus ......................................................................... 21

Tasks ............................................................................................................................................ 21

Internal nucleus structures SRB and SMR .................................................................................. 21

Drivers and devices ..................................................................................................................... 23

Interrupt vectors ........................................................................................................................... 23

Memory pools ............................................................................................................................... 23

Memory allocation of the RMOS3 nucleus .................................................................................. 24

Meaning of the system parameters.............................................................................................. 24

Meaning of the task control data (TCD) ....................................................................................... 25

Driver control data (DCD) ............................................................................................................ 28

2.3.10 Unit control data table (UCD) ....................................................................................................... 29


System Manual, 07/2012, A5E03692294-01

3

4

Table of contents

3

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

2.4.1

2.4.2

2.4.3

Drivers in the configurable nucleus ............................................................................................. 33

EIDE driver .................................................................................................................................. 33

TCP/IP connection ...................................................................................................................... 33

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

2.5.1

2.5.2

2.5.3

2.5.4

2.5.5

2.5.6

2.5.7

Configurable nucleus .................................................................................................................. 38

Booting with the second stage boot loader RMLDR ................................................................... 39

Booting with MS-DOS and RMOS3 load program LOADX ......................................................... 40

Startup messages and system outputs ....................................................................................... 41

Section [System] ......................................................................................................................... 45

Section [RMOS] .......................................................................................................................... 49

Section [HSFS] ............................................................................................................................ 51

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

2.6.1

2.6.2

RMOS3 parameters .................................................................................................................... 59

Memory requirements of RMOS3 data structures ...................................................................... 59

Number of system resources ...................................................................................................... 59

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

3.1

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

3.2

3.2.1

3.2.2

3.2.3

3.2.4

3.2.5

3.3

3.3.1

3.3.2

3.3.3

3.3.4

3.3.5

3.3.6

3.3.7

3.4

Driver tasks ................................................................................................................................. 63

Driver initialization ....................................................................................................................... 64

Processing driver requests.......................................................................................................... 64

Interrupt processing in drivers ..................................................................................................... 67

Timeout monitoring in the driver ................................................................................................. 68

Completing an I/O operation ....................................................................................................... 68

Data structures ............................................................................................................................ 69

Driver control data (DCD) ............................................................................................................ 70

Driver control block (DCB) .......................................................................................................... 71

Unit control data table (UCD) ...................................................................................................... 72

Unit control block (UCB) .............................................................................................................. 73

I/O request block (IRB) ................................................................................................................ 74

Timer monitor block (TMB) .......................................................................................................... 75

Link of data structures ................................................................................................................. 76

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


System Manual, 07/2012, A5E03692294-01

Table of contents

4

4.3

4.3.1

4.3.2

4.3.3

4.3.4

4.3.5

4.4

4.4.1

4.4.2

4.4.3

4.4.4

4.4.5

4.4.6

3.4.1

3.4.2

3.4.3

Driver subprograms ..................................................................................................................... 78

System variables for parameter transfer ...................................................................................... 80

Differences between type I and type II drivers ............................................................................. 81

3.5

3.5.1

3.5.2

3.5.3

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

3.5.6

3.5.7

3.5.8

3.5.9

Notes on driver implementation ................................................................................................... 83

Data and stack environments of driver programs ........................................................................ 83

Resetting/Initializing units ............................................................................................................ 85

Creating and deleting device drivers ........................................................................................... 86

Interrupt handling by RMOS3 standard drivers ........................................................................... 93

Timeout processing ...................................................................................................................... 95

I/O termination for drivers ............................................................................................................ 96

Operation of a unit by several drivers .......................................................................................... 98

Summary ...................................................................................................................................... 98

3.5.10 RMOS3 compliant interrupt handlers ........................................................................................... 99

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

4.1

4.1.1

4.1.2

4.1.3

4.1.4

4.1.5

Command Line Interpreter ......................................................................................................... 101

CLI operation .............................................................................................................................. 101

Redirecting input and output data .............................................................................................. 101

Naming conventions .................................................................................................................. 102

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

Notes on HSFS and on using volumes ...................................................................................... 104

4.2

4.2.1

4.2.2

4.2.3

4.2.4

4.2.5

4.2.6

4.2.7

Debugger ................................................................................................................................... 104

Task-and monitor operating modes ........................................................................................... 104

General notes on operation ....................................................................................................... 107

RMOS3 operating environment of the debugger ....................................................................... 107

Operating the debugger ............................................................................................................. 107

Task processing ......................................................................................................................... 108

Debugger start ........................................................................................................................... 108

Debugger-I/O interface x_d_rio .................................................................................................. 109

4.2.8

4.2.9

General syntax rules .................................................................................................................. 109

Detailed command syntax .......................................................................................................... 111

4.2.10 Command scope of the debugger.............................................................................................. 114

4.2.11 Error messages of the debugger ............................................................................................... 115

Resource reporter ...................................................................................................................... 118

General notes on operation ....................................................................................................... 118

RMOS3 support ......................................................................................................................... 118

Operating resource reporter ....................................................................................................... 118

Parameter settings with pointers to a structure ......................................................................... 119

Error messages of resource reporter ......................................................................................... 124

Exception Interrupt Handler ....................................................................................................... 125

Real-time capability .................................................................................................................... 125

Design and function ................................................................................................................... 125

On-screen output ....................................................................................................................... 127

Non-Maskable Interrupt ............................................................................................................. 129

Product package ........................................................................................................................ 129

Modifying the Exception Interrupt Handler ................................................................................. 129


System Manual, 07/2012, A5E03692294-01

5

6

Table of contents

5

A

5.3

5.4

5.5

5.5.1

5.6

5.6.1

4.5

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

4.6

4.6.1

Utility programs for HSFS ......................................................................................................... 130

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

Processing requests to the file management system ............................................................... 135

4.6.3

4.6.4

4.6.5

Internal organization of the HSFS ............................................................................................. 136

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

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

5.1

Introduction................................................................................................................................ 143

5.2

5.2.1

RDISK.EXE ............................................................................................................................... 143

(Error) messages of RDISK.EXE .............................................................................................. 145

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

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

LOADER.386 ............................................................................................................................ 148

Error messages ......................................................................................................................... 148

RMLDR, RMLDRFAT.16, RMLDRFAT.32 ................................................................................ 149

Installing the second stage boot loader RMLDR ...................................................................... 150

5.7

5.8

5.9

5.10

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

BLOWUP ................................................................................................................................... 152

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

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

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

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


System Manual, 07/2012, A5E03692294-01

Table of contents

Tables

Table 1- 1

Table 1- 2

Table 1- 3

Table 1- 4

Table 2- 1

Table 2- 2

Table 2- 3

Table 2- 4

Table 2- 5

Commands ................................................................................................................................... 10

Abbreviations ............................................................................................................................... 10

General data types ....................................................................................................................... 11

Data types of the RMOS3 API ..................................................................................................... 11

Number of SMR blocks required .................................................................................................. 22

Overview of SVC entry points ...................................................................................................... 24

TCD block structure ..................................................................................................................... 25

Meaning of the task flags ............................................................................................................. 27

DCD block structure ..................................................................................................................... 28

Table 2- 6

Table 2- 7

Table 2- 8

Table 2- 9

Meaning of the driver flags ........................................................................................................... 29

UCD block structure ..................................................................................................................... 29

Organization of the stack when SVC returns a value unequal to 0 ............................................. 32

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

Table 3- 3

Table 3- 4

Table 3- 5

Table 3- 6

Table 3- 7

Table 3- 8

Table 3- 9

DCD block .................................................................................................................................... 70

DCB .............................................................................................................................................. 71

UCD block .................................................................................................................................... 72

UCB block .................................................................................................................................... 73

IRB block ...................................................................................................................................... 74

TMB block .................................................................................................................................... 75

Driver functions for assembler routines ....................................................................................... 79

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

Table 4- 3

Argument definitions for addresses ........................................................................................... 111

Argument entries for expressions .............................................................................................. 111


System Manual, 07/2012, A5E03692294-01

7

8

Table of contents

Table 4- 4

Argument entries for formatting.................................................................................................. 112

Table 4- 5

Table 4- 6

Table 4- 7

Table 4- 8

Argument entries for breakpoints ............................................................................................... 113

Parameter structure of resource reporter ................................................................................... 120

Coding of parameter analyze_type ............................................................................................ 122

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

Figure 3-2

Figure 3-3

Figure 3-4

Figure 3-5

Figure 3-6

Figure 3-7

Figure 3-8

Figure 4-1

Call environment of driver programs ............................................................................................ 63

Serial driver (one controller for several units) .............................................................................. 76

Parallel driver (one controller per unit) ......................................................................................... 77

System processes ........................................................................................................................ 78

System processes and interrupt handling .................................................................................... 96

Example of the interaction between an interrupt handler and a task ........................................... 99

Flow chart for a task that needs an interrupt handler .................................................................. 99

Example of an interrupt handler that supports a task ................................................................ 100

Task mode and monitor mode of the RMOS3 debugger ........................................................... 105


System Manual, 07/2012, A5E03692294-01

About this document . .

1

1.1

Overview


This System Manual covers all aspects of the configuration of the RMOS3 nucleus. The major part of the information was prepared in tabular format that highlights the function principle of RMOS3 and facilitates system customization to suit your specific requirements.

Moreover, the manual contains the description of the interfaces to the Human Machine

Interface. That specific section provides you with notes on operating the RMOS3 system.

Chapter 1

This chapter offers you a documentation guideline and explains the notations employed in the manual.

Chapter 2

Starting with an overview of the structure and configuration of an RMOS3 nucleus,

"Configuring the RMOS3 nucleus (Page 13)" shows you how you can adapt the nucleus to

the hardware situation on the basis of the RMOS3 nucleus versions included in your package.

Chapter 3

Chapter "Driver development (Page 61)" describes the structure of an RMOS3 driver. This

chapter assists experienced programmers in programming an RMOS3 driver.

Chapter 4

Chapter "System tasks (Page 101)" provides an overview of the handling of the utility

programs that facilitate your work with RMOS3.

Chapter 5

Chapter "System programs (Page 143)" contains the description of the tools used for the

nucleus and application, as well as the boot loaders for the RMOS3 nucleus.


System Manual, 07/2012, A5E03692294-01

9


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

UPPERCASE Constant

Comment

Elements in uppercase notation represent constants. Entries are made in accordance with the character notation with support of uppercase and lowercase letters.

Numbers are always constants. 1847 Constant 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

< > Delimiters

[ ] Optional

Selection

|a|b|c|

... Repetition

Comment

Variables are enclosed in angled brackets

Elements in angled brackets are optional.

An element can be selected if several elements are arranged vertically in braces or horizontally between vertical lines.

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 cfg uintmax dp

Meaning Text passage configurable System calls maximum unsigned integer (FFFF FFFFH) System calls data pointer (sel:off) 48-bit pointer System calls

10


System Manual, 07/2012, A5E03692294-01

Data types


1.2 Notations

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

Table 1- 3 General data types

Data type char short int long long long

1 void _FAR *

2 void _NEAR *

2 enum float double

Data length

8 bit

16 bit

32 bit

32 bit

64 bit

48 bit

32 bit

32 bit

32 bit

64 bit

1 Only available for GNU programs.

2 Pointers in flat programs always have a length of 32 bit. No distinction is made between

NEAR and FAR.

Table 1- 4 Data types of the RMOS3 API

Name uchar ushort uint ulong rmfarproc

1 rmnearproc rmproc

1

1

Data type unsigned char unsigned short unsigned int unsigned long

Pointer to function type void _FAR f(void)

Pointer to function type void _NEAR f(void)

Pointer to function type void _NEAR f(void)

Data length

8 bit

16 bit

32 bit

32 bit

48 bit

32 bit

32 bit

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

NEAR and FAR.


System Manual, 07/2012, A5E03692294-01

11


1.2 Notations

12


System Manual, 07/2012, A5E03692294-01

Configuring the RMOS3 nucleus

2.1

2

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

Overview

RMOS3 operating system components

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


System Manual, 07/2012, A5E03692294-01

13


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

2.2.4

APIC driver

● Switching from PIC mode to APIC mode

● Activation of multiprocessor support

● Suitable for all processors of the latest generation

● 24 interrupt lines are supported (IRQ0 to IRQ23)

● Accelerated interrupt processing in APIC mode (reduced interrupt sharing and accelerated access)

BYT driver

● Universal I/O driver for character-oriented I/O devices:

Terminals, data display stations, keyboards, printers, IBM PC/XT/AT with terminal emulation

● Configurable: e.g. for UART blocks (8255, 8530, 8250), EGA (text mode)

● Transmission rate depending on the CPU, UART, ...

● Supports 255 terminal devices with different parameter assignment

● Handshake: XON/XOFF

● History buffer

● Commands: read, write, reserve, release, ...

2.2.5

14

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




System Manual, 07/2012, A5E03692294-01

2.2.6

2.2.7

2.2.8



COM driver

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

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



DMA driver

● Management of DMA control blocks or DMA control of an 80186/188 CPU and PC hardware.

RAM-DISK driver

● Manages a RAM area similar to a block-oriented device

● Memory is requested from the HEAP.

● Locks itself if configuration errors are found

● A type II driver sample in C source code is included in the scope of delivery

Operations:

● Reserving and releasing RAM DISK

● Reading/writing one or several logic blocks

● Reading/redefining RAM DISK operating parameters

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


System Manual, 07/2012, A5E03692294-01

15



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

16


System Manual, 07/2012, A5E03692294-01

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


System Manual, 07/2012, A5E03692294-01

17



● 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

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


System Manual, 07/2012, A5E03692294-01

2.2.19



● RMOS3 SVCs (seethe reference manual) can be executed as command

● BYT driver as software interface to the terminal

● Operating mode display by means of debugger prompt

High-level language debugger

● The high-level language debugger is part of the RMOS3 GNU product.

● High-level language debugger rm-gdb (GNU debugger) for command line oriented debugging, or graphic debugging with Eclipse IDE

● Communication host debugger (rm-gdb) with GNU Debug-Server GDBSrvGn.386 over

TCP/IP

● Symbolic processing with HLL debugger

● Dynamic task loading at runtime on the target system by means of HSFS.

● Check and disassembly of memory contents and changing the content of RAM areas

● 15 breakpoints (soft breakpoints) in any task (the interrupt address must be known and exist in RAM), 4 breakpoints (hard breakpoints) in EPROM by means of 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


System Manual, 07/2012, A5E03692294-01

19



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

20


System Manual, 07/2012, A5E03692294-01

2.3

2.3.1

2.3.2

SRB

SMR


2.3 Structures and elements of the RMOS3 nucleus

Structures and elements of the RMOS3 nucleus

Tasks

Every application system contains one or several static and/or dynamic tasks.

The TCD block for a dynamic task is always generated by a system call at runtime and can be killed again by a second system call. The task ID is also assigned or released in this process. There is no other difference between dynamic and static tasks. The tasks can be named and be identified by their name in the catalog entry. A task can also be identified by its ID.

Internal nucleus structures SRB and SMR

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.

An SMR block (System Memory Resource) is a dynamic data structure that is used in

RMOS3 for internal management tasks. The number of SMRs to be configured depends on the number of simultaneously active system calls. Each system call needs a specific number of SMR blocks.

The start value for the number of SMRs (at least 50) is specified in the SWNUC.INC file as

X_TASK_NUM. Each SMR block occupies 72 bytes in global RAM. Memory is allocated from the HEAP. The nucleus automatically increases the number of available SMRS. The number of SMRs can be limited by corresponding settings in the RMOS.INI file.


System Manual, 07/2012, A5E03692294-01

21



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

RmStartTask

Number

1

RmQueueStartTask

RmRestartTask

RmPauseTask

RmSetFlagDelayed

RmGetFlag

RmSendMail

RmReceiveMail

RmAlloc

RmIO

RmGetBinSemaphore

DBGSVC

RmCreateTask

RmGetEntry

RmSendMailDelayed

1

1

1

1

1

1

1

1

2

2

1

3

1

2

Using the blocks

RCB (Restart Control Block) for the target task; released when the target task outputs

RmEndTask

.

See

RmStartTask

For TMB (Timer Monitor Block); released when the task is returned to READY state.

For TMB; released when the task is returned to READY state (time expired or

RmResumeTas k).

For TMB; released on expiration of the delay time.

For EWB (Event Flag Wait Block); released if waiting conditions are fulfilled.

For MMB (Mailed Message Block); released after the message was received (

RmReceiveMail

).

For MMB; released after a message was retrieved, or if no "wait for message" was specified in the system call.

For PWB (Pool Wait Block); released when memory is available, or no "wait for memory space" was specified in the system call.

For IRB (I/O Request Block) and driver MB; released on completion of request processing.

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.

For BPB (Breakpoint Block); released after the breakpoint is cleared.

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.

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.

For TIB and TMB; released with

RmSendMailCancel

, or on timeout

22


System Manual, 07/2012, A5E03692294-01

2.3.3

2.3.4

2.3.5



Drivers and devices

A DCD block and at least one UCD block must be available for each device driver. Those blocks are created in tables by means of the

RmCreateDriver

and

RmCreateUnit

configuration functions. The call order determines the driver ID. The device ID, namely the Unit ID, is derived from the call order.

You may assign the system console to a different driver and different unit by executing

RmSetOS

.

Interrupt vectors

RMOS3 allows the processing of interrupts that are not linked to a device driver. These include: division by zero, single–step (TRAP), non-maskable interrupt (NMI), breakpoint, overflow, call gates, and the interrupt generated by the system timer. The position of the device interrupt vectors is specified by initialization of the interrupt control block.

It is possible to configure the assignment of interrupts to the vectors. In doing so, the following restrictions must be observed:

1. The interrupts 0 to 31 may only be used as exception interrupts of the 80386/80486 processors. The single–step and INT3 interrupts are also used by the debugger. The debugger retrieves and restores the original vectors if a breakpoint is set, or if no breakpoint exists.

2. Hardware interrupts cannot be treated as software interrupts.

3. Unused interrupt entry points are assigned the interrupt handler for unexpected entries.

4. This default setting can be prevented using the

RmReserveInterrupt

function.

Memory pools

RMOS3 manages the entire RAM space above 1 MB as specified in configuration data as a single memory pool, namely the HEAP. Memory space is calculated automatically during system startup.

Tasks or drivers can allocate memory space they need from the HEAP. For reasons of downwards compatibility it is still possible to use SVCs to create additional memory pools.

However, this method should no longer be used for new development.


System Manual, 07/2012, A5E03692294-01

23



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

SVC vector

Meaning of the system parameters

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

TYP3 (flat API)

TYP2 (RMOS2)

TYP1 (RMOS3 API)

Vector number

SVC vector

SVC vector +1

SVC vector +2

RMOS3 stack

The stack length of the nucleus is set to 4096 bytes. Stack requirement is calculated as follows:

● 16 words per software interrupt (SVC entry, or processor exception INT0, INT4...).

● 16 words for NMI

● 16 words per hardware interrupt.

● RMOS3 itself needs approximately 40 words.

● Maximum driver stack needed in DI, I or S state (containing 25 words for the driver subroutines and the actual memory requirements of the driver).

24


System Manual, 07/2012, A5E03692294-01

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

EAX

EBX

DS

Offset

0H

4H

8H

Type uint uint ushort

ES

STCK

TASK

LOAD

TIME

OVPRI

BPRI

INPRI

FLAGS

RR_TICKS

EFG

RESERVE

SEQ

TASKID

RESERVED

SYSESP

NPX

21H

22H

24H

26H

28H

30H

34H

38H

3AH

3CH

40H

AH

CH

12H

18H

1EH

20H ushort void* rmfarproc void* ushort uchar uchar ushort ushort ushort uint[2] uchar[4] uint ushort ushort uint void*

Description first stack parameter second stack parameter

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

Task start value

Stack pointer start value (SS:ESP)

Task start value reserved task-related timeout

Increment of automatic increase of the priority level

Limit of automatic increase of the priority level

Original task priority

Task flags:

Bit 0

Bit 1

Bit 2

RM_TFL_NPX (1H) Task uses

NPX

Reserved, must be 0

RM_TFL_NOHLT (4H) Task cannot be stopped

Bit 3

Bits 4 ...7

Bit 8

Bit 9

RM_TFL_OVPRI (8H) automatic increase of the priority level

Reserved, must be 0

RM_TFL_STK (100H) = 1: automatic stack creation

RM_TFL_DS (200H) = 1:

Automatic creation of the data segment

Bit 10 ...15 Reserved (0) task-specific Round–Robin counter

Local event flag

4 bytes are reserved

ID of the task started after completion

Task ID

2 bytes are reserved

System stack

Near pointer to NPX data


System Manual, 07/2012, A5E03692294-01

25



1. Stack parameters (TCD.AX,TCD.BX, TCD.EAX,TCD.EBX )

The operating system writes these values of the task stack at the start of the task.

2. Data segment (TCD.DS)

Start value of the data segment register (DS) of the task. A segment declaration can be used for external definition of the segment. A task may always change the data segment register during execution. However, TCD.DS is written to the data segment register at each restart of a task. TCD.DS must be declared if a high-level language task was compiled with COMPACT.

TCD.DS defines the length of the data segment in bytes during automatic creation of the data segment (RM_TFL_DS). The data segment may have a maximum length of 64 KB because TCD.DS is a 16–bit value.

3. Extra segment (TCD.ES)

Start value of the extra segment register (ES) of the task if necessary.

4. Stack pointer and stack segment register (TCD.STCK)

Start value of the stack pointer (SPESP) and stack segment register (SS) of the task.

Only the length of the stack segment must be defined at the function call. TCD.ESP defines the stacks length in 32–bit words during automatic creation of the stack.

5. Entry address (TCD.IP, TCD.EIP and TCD.CS)

The task start address is a pointer of type FAR (offset TCD.EIP and segment TCD.CS) and must be declared externally. CS/EIP is occupied with the address of the specified procedure.

6. Task-related timeout (TCD.TIME)

The TCD timeout is activated in response to the following situation:

If the task is still in BLOCKED, READY, or RUNNING state on expiration of the time interval specified in TCD.TIME, the task priority is raised automatically by the value defined in TCD.OVPRI if the TCD.BPRI limit was not yet reached. The timeout is started at the task start and whenever the task has automatically raised its priority.

TCD priority monitoring is specified in parameter TCD.FLAGS. The TCD timeout interval consists of 2 parameters:

Byte 0: time interval from milliseconds to hours (see SVC

RmPauseTask

). The values for a time interval are entered with multiplication factor 4.

Byte 1: number of time intervals (0 to 255)

7. Increment for automatic priority increase (TCD.OVPRI)

This byte specifies the priority increment that is added to the current priority of the task on expiration of TCD.TIME and if RM_TFL_OVPRI is set.

8. Limit for automatic priority increase (TCD.BPRI)

This byte specifies the limit up to which the priority is increased automatically.

26


System Manual, 07/2012, A5E03692294-01



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

4

5

6

0

1

2

3

Symbol

RM_TFL_NPX

RM_TFL_NOHLT

RM_TFL_OVPRI

RM_TFL_CHILDTASK

7

8

9

10...15

RM_TFL_STK

RM_TFL_DS

Function

Task uses a numeric co-processor

Reserved, must be 0

Task may not be stopped by another task

Activates automatic priority increase

Reserved, must be 0.

Reserved, must be 0. inherits stdin, stdout, stderr, current working directory and environment

Reserved, must be 0

1: Automatic creation of the stack

1: Automatic creation of the data segment

Reserved: Must be 0.


System Manual, 07/2012, A5E03692294-01

27



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

UCD

UNITS

SHR

INIT

SVC

FLAGS

FMAX

RESERV

Type

RmUCDStruct _NEAR* uchar uchar rmnearproc rmnearproc uchar uchar

Ulong

Description

Reserved

Reserved

ID of the second driver that shares a control block

Entry point of the initialization routine in the driver

RmIO

SVC entry point for this driver

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

Maximum function code (only type II)

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.

28


System Manual, 07/2012, A5E03692294-01



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

0

Symbol

RM_DFL_PARA

1

2

3 ... 7

RM_DFL_TYPE2

RM_DFL_DORMANT

Function

0

1

0

1

Serial driver

Parallel driver

Type I driver

Type II driver

0

1

Driver initialization in the boot sequence

No driver initialization in the boot sequence (driver

DORMANT)

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

PID

INTNO

INTR_ADR

UNS

Type uchar uchar void* ushort

PORT

Description

Driver type

Number of the interrupt vector for the unit

Address of the interrupt handler

ID of the task that is started after an unexpected entry (0FFFFH if no task is started)

Driver-specific data (246 bytes)


System Manual, 07/2012, A5E03692294-01

29



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.

30


System Manual, 07/2012, A5E03692294-01

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:


System Manual, 07/2012, A5E03692294-01

31



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

Stack organization

Return address

Task ID

Status word

SVC number

RMOS3

4 bytes

4 bytes

4 bytes

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.

32


System Manual, 07/2012, A5E03692294-01

2.4

2.4.1

2.4.2


2.4 Drivers in the configurable nucleus

Drivers in the configurable nucleus

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.

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.


System Manual, 07/2012, A5E03692294-01

33



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.

34


System Manual, 07/2012, A5E03692294-01

Example

2.4.4.1



Example on a SIMATIC Box PC 827B:

RMOS3 PCI Initialization V2.5.3


PCI: init server ok

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.


System Manual, 07/2012, A5E03692294-01

35



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

36

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)


System Manual, 07/2012, A5E03692294-01

2.4.6.1



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

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.


System Manual, 07/2012, A5E03692294-01

37


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 as these are set automatically. default values do not necessarily need to be specified,

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.

38


System Manual, 07/2012, A5E03692294-01

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

RM3_PC1.SYS

CNFTSK.386

RMOS.INI

Second stage boot loader for RMOS3 nucleus. Must be located in first place in the root directory of the volume.

RMOS3 nucleus. Can be located at any position in the root directory.

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

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


System Manual, 07/2012, A5E03692294-01

39



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

AUTOEXEC.BAT,

CONFIG.SYS

LOADX.EXE

MS-DOS system files.

Components of MS-DOS.

RM3_PC1.LOC

CNFTSK.386

RMOS.INI

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

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

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

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

40


System Manual, 07/2012, A5E03692294-01



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.


System Manual, 07/2012, A5E03692294-01

41



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

42


System Manual, 07/2012, A5E03692294-01



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


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


System Manual, 07/2012, A5E03692294-01

43



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

44


System Manual, 07/2012, A5E03692294-01

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

Overview

Section [System]

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


System Manual, 07/2012, A5E03692294-01

45



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

Description

Value range

String

(max. 40 characters)

RmosPath

BootFilePath

StartUpFile

String

String

String

Description

String (e.g.

COMPUTER1) is stored as SYSTEM environment variable

(e.g.

SYSTEM=COMPUTER1

).

RMOS3 directory that contains all reloadable

RMOS3 programs/drivers.

Boot directory, including the name of the loaded nucleus (e.g.

C:\RM3_PC1.SYS)

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

Default value

CPU name

<X>:\RM3RUN

---

---

1

Comment

Can be defined by users.

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

If no entry exists, the

‘RM3_PC1.LOC’ is located and entered in the

BootFilePath key.

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.

46


System Manual, 07/2012, A5E03692294-01



Keys

StartUpFilePrio

BootBatch

LogFile

Messages

LogExceptions

RamDiskSize

SystemFlagGroup

Value range

0 ... 255

String

String yes | no

String

(max. 14 characters)

0 | 8192 ..

0x7FF00000 yes | no

Description Default value

Priority of the

‘StartUpFile’ task to be started

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

128 (0x80)

-- 1

File to which the startup messages of the nucleus are saved.

2

If feasible, exceptions are included in the log file

R:\RMOS.LOG no

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

SysFlagGroup

Size of the RAM DISK 2097152 (2 MB)

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

Comment

---

Default name:

RM_INIT.BAT

---

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

---

The RAM DISK has a minimum size of 8 KB.

0: No RAM DISK is created.

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.


System Manual, 07/2012, A5E03692294-01

47



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

48


System Manual, 07/2012, A5E03692294-01



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 rate

Value range

1 .... 54 semaphores flags

10 ... 1023

10 ... 127 mailboxes smrs

10 ... 255

500 … 65534 logsvcx sysdev yes | no

BYT_COM1 |

BYT_COM2 |

BYT_EGA_0 |

BYT_EGA_1 |

BYT_EGA_2 |

BYT_EGA_3

Description system clock rate in milliseconds

Number of ‘static’ semaphores

Number of ‘static’ flag groups

Number of ‘static’ mailboxes

Limit of the available number of SMRs

(System Memory Block)

Default value

1

10

10

10

65534

Log system messages yes

System console BYT_COM2

Comment

---

---

---

---

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

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


System Manual, 07/2012, A5E03692294-01

49



Keys keyboard run

RunDelay

RoundRobin

ReporterTableSize

Value range

French |

German |

Italian |

Spanish |

UK-English |

US-English

String (max. 128 characters)

Description

Keyboard layout used for the PS/2 interface

Default value

US-English

Execute Run command ---

0 … 10,000

1 … 100

0x4500 ...

0xFFFFFFFF

Delay time in milliseconds expiring after each Run command

Round-Robin factor

0

10

Table size for Resource

Reporter in bytes

0x4500

VGATaskPriority

Debugger

0 ... 255 yes | no

VGA task priority

Switch that decides whether or not to load debugger.drv

254 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

Comment


Allow a maximum of 15 entries per Run command

Evaluated once only.

Last entry is valid.

Round-Robin interval =

RoundRobin * rate

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

50


System Manual, 07/2012, A5E03692294-01

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 prio channels files buffersize buffers

Value range

0 ... 255

10 … 600

Description Default value

Priority of the file system 253

Number of channels

(CCBs, see chapter

"Internal organization of the HSFS (Page 136)").

10 … 512 Number of files (FCBs,

see chapter "Internal organization of the

HSFS (Page 136)").

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

16 ... 1024(128) Number of data buffers

(BBs, see chapter

"Internal organization of the HSFS (Page 136)").

600

512

16

1024(128)

DisableUDMA yes | no Disable the UDMA driver no

Comment

---

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.

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


System Manual, 07/2012, A5E03692294-01

51



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

Use

Drives

Repair

Messages

Value range yes | no

C:, D:, E:, F:,

P0:, P1:, P2:,

P3:, O0:, O1:, R1 auto | no

Description Default value yes: SCANDISK is executed no

Drives to verify at startup --- yes | no

Auto: Errors are corrected automatically

Yes: SCANDISK outputs messages to the system console auto yes

---

---

Comment

---

It is possible to specify 1 to 11 drives.

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

key specifies whether or not SCANDISK outputs messages to the system

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)

52


System Manual, 07/2012, A5E03692294-01

2.5.8

Overview

Section [CPU]

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

Type

Value range

AUTO

Description

CPU type used

Default value

AUTO

Driver_A

DisableAPIC

DisableHPET

BYT | 3964 | none yes | no yes | no

DisableMulticor e yes | no

Initialize COM A interface driver none

Deactivate APIC mode no

Deactivate the HPET driver no

Deactivate multicore support no

Comment

The CPU detected in the

BIOS routine is used if

AUTO is set.

For information on driver settings, refer to the following chapters

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.


System Manual, 07/2012, A5E03692294-01

53



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

Baud_A

Data_A

Parity_A

Stop_A

Rts_A

Mode_A

Name_A

PoolLength_A

Emulation_A

UnsolTask_A

UnsolCharacter1_

A

UnsolCharacter2_

A

Value range

2400 | 4800 | 9600

| 19200 | 38400 |

57600 | 115200

7 | 8


^R | ^D | none

^R | ^D | none

Description

Baud rate

Number of data bits none | odd | even Parity

1 | 2


Number of stop bits

Name of the unit.

0 … 255 Length of the buffer for

COM A in bytes

DS2 | DS3 | PC | X Emulation:

DS2 = SME

DS3 = VT100

PC = IBM PC/AT

X = transparent mode yes | no Status of the RTS signal yes = active

0 … 255

Default value

19200

8 none

1

BYT_COM1

255

DS3 yes

Comment

---

---

---

---

The name must be

"OSB_COM" if OSB is running on the system.

No buffer is created if 0 is set

---

---

Value of modext for

COM_A

Name of the CLI dispatcher for COM A

Characters used to start the CLI dispatcher for

COM A

Characters used to start the CLI dispatcher for

COM A

---

---

Transparent mode

---

---

Terminal mode

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

CLI_DPAT ---

^R

^D

---

---

54


System Manual, 07/2012, A5E03692294-01

COM A interface with 3964R driver



Overview

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

Keys

Baud_A

Data_A

Parity_A

Stop_A

Name_A

MasterSlave_A

TimeoutAcknowledge_A

Value range Description Default value

2400 | 4800 | 9600

| 19200 | 38400 |

57600 | 115200

Baud rate

7 | 8 Number of data bits none | even | odd Parity

1 | 2

String (max. 14 characters) master | slave

0 … 65535

Number of stop bits

Name of the unit.

19200

8 none

1

3964R_COM1

3964R mode for COM A master

Timeout value for

Acknowledge COM A

0

TimeoutCharacter_A

BlockLength_A

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.

0 … 65535

0 … 65535

Timeout value per character for COM A

Block length COM A

0

5

Comment

---

---

---

---

---

---

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.

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.

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.


System Manual, 07/2012, A5E03692294-01

55



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

Table 2- 16 Section [TCP]

Keys

TCPPath

SyslogStart

SyslogFile

LogFTPD

NumberFTPD

FTPDPriority

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

EnvironmentNETETC

EnvironmentHOST

EnvironmentTERM

Value range


Description

Directory containing the

TCP/IP files

Default value

--- yes | no




VT100 | VT52 |

TVI910 | TVI925 |

QVT101 | SME |

RMOSEGA |

AT386

0 … 4

1 … 255 yes | no yes: Load

Syslogger

Syslog file

Directory for file

HOSTS

Name of the local station

Telnet terminal emulation no

---

---

---

VT100

Load the specified number of FTP daemons

Priority of the FTP daemon

FTPD logs to the

Syslog file

0

64 no

Comment

An RmosPath entry found in the group

[System] is appended to this entry.

Necessary for the Telnet daemon


Necessary for the Telnet and FTP daemons

Necessary for the Telnet and FTP daemons


---

If ‘yes’, then

SyslogStart

must also be set to ‘yes’

56


System Manual, 07/2012, A5E03692294-01



Keys

NumberTELNETD

TELNETDPriority

EnvironmentTELNETD_PWD

Sockets

NTPCStart

NTPCMode

NTPCRefreshTime

NTPCPriority

NTPCServer

NTPCTimeout

WEBServerStart

WEBServerPriority

WEBServerConfigPath

WEBServerRootPath

Value range

0 … 4

Description

Load the specified number of

TELNET daemons

Default value

0

Comment

If unequal to 0, it is mandatory to set

SyslogStart to ‘yes’

1 … 255 yes | no

64 … 4096 yes | no single | cyclic | standby

1 …

0xFFFFFFFF

1 … 255

1 …

0xFFFFFFFF

String yes | no

1 … 255



Priority of the

TELNET daemon

Manage password prompt for

TELNETD

Number of available sockets yes: Start NTP client

NTPC mode

64 yes

192 no cyclic

NTPC refresh time in seconds

86400

NTPC priority

NTPC waiting time for server in seconds

64

4

Server name yes: Start

WebServer no

Web server priority 64

Path to the configuration directory of the

Web server

C:\RM3WEB\

WEB_CONFIG

Path to the basic directory of Web contents

C:\RM3WEB\

WEB_ROOT

86400 = 24 hours

Example

[TCP]

TCPPath = C:\RM3RUN

SyslogStart = yes

SyslogFile = C:\ETC\syslog

EnvironmentNETETC = C:\ETC\

EnvironmentHOST = SIMATIC_PC

EnvironmentTERM = VT100

NumberFTPD = 4

NumberTELNETD = 2


System Manual, 07/2012, A5E03692294-01

57



Commissioning

The following files need to be copied to the computer:

RmosPath

(e.g. ‘c:\rm3run’) on the target

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

58


System Manual, 07/2012, A5E03692294-01

2.6

2.6.1


2.6 RMOS3 parameters

RMOS3 parameters

Memory requirements of RMOS3 data structures

Table 2- 17 Memory requirements of RMOS3 data structures

Data structures

RMOS3 control data structures

TCD per task

TCB per task

DCD per driver

DCB per driver

UCD per unit

UCB per unit

Memory pool table per memory pool

Mailbox table per mailbox

Discrete I/O table per discrete byte

Vector table per vector

Event flag table per flag group

Semaphore table per semaphore

RMOS3 stack (configurable)

256

22

20

6

8

8

14

400

Size (bytes) decimal

230

68

72

20

256

256

2.6.2 Number of system resources

Table 2- 18 System resources

Configuration parameters

Tasks

Unit software driver

Units per driver

Mailboxes

Global event flag groups

Local event flags per task

Memory pools

Semaphores

File handles

File handles per task

Sockets

System clock rate


System Manual, 07/2012, A5E03692294-01

Amount/value

32768 (depending on available memory space and configuration in swnuc.inc)

255

255

255

127

32

8

4095

512

37

192

1ms ≤ system clock rate ≤ 54ms

59


2.6 RMOS3 parameters

60


System Manual, 07/2012, A5E03692294-01

Driver development

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

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 corresponding driver program.

RmIO

. The nucleus validates the SVC, copies the parameters to an internal data structure, and calls the

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


System Manual, 07/2012, A5E03692294-01

61

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.

62


System Manual, 07/2012, A5E03692294-01

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


System Manual, 07/2012, A5E03692294-01

63

Driver development

3.2 Driver tasks

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.

64


System Manual, 07/2012, A5E03692294-01

Driver development

3.2 Driver tasks

Global data structures

The following parameters of SVCs

RmIO are valid for all drivers:

Table 3- 1 Parameters of SVC

RmIO

Parameters

Function

DeviceID

UnitID

FlagID

FlagMask

Function

This parameter defines the operations to be executed by the unit and all control variations.

Bit Meaning

7

6

5

If set (=1), the I/O request is executed immediately (preemptive bit)

Wait for I/O completion if set (=1)

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.

Reserved (must be set to 0) 4

1

0

3

2

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.

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.

Identity code that designates the subunit of the driver during system start-up.

ID of the flag group in which the job processing state is to be indicated.

Flag mask that indicates the processing state of the job in the flag group.


System Manual, 07/2012, A5E03692294-01

65

Driver development

3.2 Driver tasks

Parameters pState

Function

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.

66


System Manual, 07/2012, A5E03692294-01

Driver development

3.2 Driver tasks

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.


System Manual, 07/2012, A5E03692294-01

67

Driver development

3.2 Driver tasks

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.

68


System Manual, 07/2012, A5E03692294-01

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.


System Manual, 07/2012, A5E03692294-01

69

Driver development

3.3 Data structures

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

UCD

UNITS

SHR

Size

4H

1H

1H

INIT

SVC

FLAGS

FMAX

4H

4H

1H

1H

4H

Total scope: 14H

Description

Reserved

Reserved

Identity code (ID) of a different DCD that also uses this control (0FFH = none).

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

Start address of the driver initialization routine

(DWORD, EIP/CS)

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)

Driver flags: The corresponding bit is set to 1 by specifying the parameter.

RM_DFL_PARA Bit 0 = 1 Parallel driver

RM_DFL_TYPE2

RM_DFL_DORMANT

Bit 0 = 0

Bit 1 = 1

Bit 1 = 0

Bit 2 = 1

Bit 2 = 0

Serial driver

Type II driver

Type I driver

Driver not initialized after system initialization and set to

DORMANT state.

Driver was also initialized after system initialization and is in ready state

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

4 reserved bytes, set to 0

70


System Manual, 07/2012, A5E03692294-01

Driver development

3.3 Data structures

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

LINK

ID

STS

QIRB

CIRB

UCB

DCD

GPR

Size

4H

1H

1H

2H

4H

4H

4H

0EAH

Description

Cross-reference/link to the next DCB

Driver ID

Driver status

Bit 0 = 0

Bit 0 = 1

Bit 1 - 7

Not busy

Busy

User-definable

I/O request block, IRB queue (serial driver)

Currently processed IRB (serial driver)

Cross-reference/link to the next unit control block (UCB)

Address of the driver control data (DCD)

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


System Manual, 07/2012, A5E03692294-01

71

Driver development

3.3 Data structures

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

PID

Size

1H

INTNO

INTADR

UNS

PORT

1H

6H

2H

0F6H

Description reserved

Bit 6 = 1 RioByteUnit (RM_RIOBYTE)

Bit 7 = 1 RioBlockUnit (RM_RIOBLOCK)

Interrupt vector number (0= no interrupt)

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

.

Interrupt task for unexpected input/output (–1 = ignore)

Driver specific constants: addresses, operating modes, controller types, unit initialization

Total scope: 100H

72


System Manual, 07/2012, A5E03692294-01

3.3.4

Driver development

3.3 Data structures

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

LINK

UNIT

STS

QIRB

CIRB

SEG

DCB

UCD

TCB

GPR

4H

2H

4H

4H

4H

Size

4H

1H

1H

4H

0E4H

Description

Cross-reference/link to the next UCB of this driver (0 = end of the list)

Unit ID

Unit status

Bit 0 = 0 Not busy

Bit 0 = 1 Busy

Bit 1 - 7 Free for use

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

Currently processed IRB request block

UCD segment

Address of the DCB (driver) that controls this unit

Address of the UCD data structure

TCB of the task that has reserved this unit

(0 = not reserved)

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.


System Manual, 07/2012, A5E03692294-01

73

Driver development

3.3 Data structures

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

LINK

PRI

TCB

UCB

Size

4H

2H

4H

4H

Description

Cross-reference/link to the next IRB (0 = end of the list)

Priority of the I/O request

Pointer to the TCB of the requesting task

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

FUNCT

DEVICE

UNIT

GRP

FLAGS

STATUS

BUFR

SEQ

1H

1H

1H

1H

1H

4H

6H

6H

2H

SVC number

Parameter FUNCTN

Parameter DEV_ID

Parameter UNIT_ID

Parameter FLG_ID

Parameter FLG_MASK

Parameter STATUS_PTR

Parameter PARM_PTR

Reserved

Total scope: 29H

74


System Manual, 07/2012, A5E03692294-01

3.3.6

Driver development

3.3 Data structures

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

LINK

LTIME

Size

4H

4H

HTIME

TYPE

UCB

SADR

4H

1H

1H

4H

4H

6H

Total scope: 1CH

Description

Cross-reference/link to the next TMB (0 = end of the list)

Monitored interval in ms

(low Dword)

Monitored interval in ms

(high Dword)

Must be 1: Unit timeout.

All other values are reserved

Reserved

UCB of the unit monitored with timeout

Entry point address for timeout processing (EIP)

Reserved


System Manual, 07/2012, A5E03692294-01

75

Driver development

3.3 Data structures

3.3.7

Serial driver

Link of data structures

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.

76

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


System Manual, 07/2012, A5E03692294-01

Driver development

3.3 Data structures

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)


System Manual, 07/2012, A5E03692294-01

77

Driver development

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.

78


System Manual, 07/2012, A5E03692294-01

Assembler

Driver development


The following functions can only be used in assembler routines:

Table 3- 8 Driver functions for assembler routines

Function

X_ELIPSE

X_SYSTATE

X_SYSTATE_SW

X_XEL

X_XEL_SW

Description

Change from DI to I state

Change from I to S state

Change from I to S state without EOI

Change from I state to the scheduler

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

XCATALOG

XCHANGEDESC

XCHANGEDESC-

ACCESS

XCREATEDESC

XDELDESC

XDELTMB

XDEVDATA

XDQTMB

XDWORD

XERRLOG

XEXSYS

XGETSMR

XHALOC

XHDALOC

XIODONE

XOVER, xjmp_xover

XPHYSADR

XPUTSMR

XQPIRB

XQSETUNS

XQSIRB

Description

Enter in the RMOS3 resource catalog

Change the descriptor base and/or limit

Change the access byte of a descriptor

Create a descriptor

Delete descriptor specified by means of selector

Remove TMB from the monitor list

Calculate XDCB and XUCB based on XDEVNUM and XDEVUNIT

Removing a TMB from the monitor list without releasing it.

Conversion of the offset address of an RMOS3 data variable into a

Dword address.

Log error at the system console, if available (error logger task)

Exit the S state (end system process)

Request system memory block

Allocate memory space from a pool

Release memory space

Complete processing of SVC

RmIO for type I drivers

Conclusion of I/O request for type II drivers in C

Determine the physical address

Return system memory block

Add current IRB to the queue of a parallel driver

Queue start of a user task for unexpected interrupts

Add current IRB to the queue of a serial driver


System Manual, 07/2012, A5E03692294-01

79

Driver development


3.4.2

Function

XQSTRT

XQTMB

XRECV

XREF

XSEF

XSEND

XSETUNS

XSYSTEM

XTEF

XTIMEOUT

Description

Add task start request to queue

Add TMB from the monitor list to the queue

Receive message from local mailbox

Reset event flag

Set event flag

Send message to local mailbox

Start user task for unexpected interrupts

Change from DI state to system state

Test event flag

Set up unit timeout (only type II drivers)

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

XCIRB

XDEVNUM

XDEVUNIT

XSEGLIM

XTASK

XPRIS

XPRIV

XP1

XP2

XGRP

XFLAGS

XBOX

XGENB

XGENW

XGEND

XUCB

XDCB

XERRMSG

XOFFSET

XPOINTER

XSTATUS

XTUNIT

XTNUM

XPOOLNUM

XBLKLEN

XSEQ

XSEG

Description

Address of the current I/O request block (IRB)

Current driver ID

Current unit ID

Current UCB address

Current DCB address

Address of an error message

OFFSET address; general-purpose

OFFSET/SEGMENT address; general-purpose

Status data to be returned to the task

Time interval for timers

Number of time intervals for timers memory pool-ID for XHALOC and XHDALOC

Number of bytes for XALOC and XDALOC

Sequential number of the current IRB

Selector for segment handling

Segment limit

Task ID

Options for priority source

Priority to be used

Parameter 1

Parameter 2

Global event flag ID

Mask for flag group

Local mailbox ID

General-purpose byte

General-purpose word

General-purpose dword

Length

46 bytes

11 bytes

11 bytes

4 bytes

2 bytes

1 byte

1 byte

4 bytes

4 bytes

1 byte

4 bytes

1 byte

1 byte

2 bytes

4 bytes

46 bytes

46 bytes

46 bytes

24 bytes

46 bytes

48 bytes

11 bytes

1 byte

1 byte

4 bytes

2 bytes

2 bytes

80


System Manual, 07/2012, A5E03692294-01

Driver development


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

RmIO s 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.


System Manual, 07/2012, A5E03692294-01

81

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.

82


System Manual, 07/2012, A5E03692294-01

3.5

Driver development


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 unitspecific section of the UCB block.

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


System Manual, 07/2012, A5E03692294-01

83

Driver development


Stack

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

DI state

I state

S state

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

The stack may be used, but must have been returned to its original state when the program exits the I 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

I state

S state

The specific parts of the data structures may always be modified (e.g. for use as variable or shadow register).

See DI state

See DI state

Internal data structures

Internal data structures (e.g. buffers).

DI state

I state

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

See DI state

See DI state

Registers

DI state

I state

S state

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

All registers are available

All registers are available

84


System Manual, 07/2012, A5E03692294-01

Driver development


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

XDEVUNIT

XUCB

XDCB

ES register

DS register

Contains the current driver ID

Contains the current unit ID

Pointer to the current unit control block (UCB data structure)

Pointer to the current driver control block (DCB data structure)

Undefined

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.


System Manual, 07/2012, A5E03692294-01

85

Driver development


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

86


System Manual, 07/2012, A5E03692294-01

3.5.4

Overview

Initiating SVC RmIO

Driver development


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


System Manual, 07/2012, A5E03692294-01

87

Driver development


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.

88


System Manual, 07/2012, A5E03692294-01

Driver development


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


System Manual, 07/2012, A5E03692294-01

89

Driver development


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.

90


System Manual, 07/2012, A5E03692294-01

3.5.4.2

Driver development


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


System Manual, 07/2012, A5E03692294-01

91

Driver development


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.

92


System Manual, 07/2012, A5E03692294-01

3.5.5

Driver development


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.

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.


System Manual, 07/2012, A5E03692294-01

93

Driver development


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.

94


System Manual, 07/2012, A5E03692294-01

Driver development


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.


System Manual, 07/2012, A5E03692294-01

95

Driver development


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:

96


System Manual, 07/2012, A5E03692294-01

Driver development


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.


System Manual, 07/2012, A5E03692294-01

97

Driver development


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

98


System Manual, 07/2012, A5E03692294-01

3.5.10

Driver development


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


System Manual, 07/2012, A5E03692294-01

99

Driver development


The interrupt handler could be realized as follows:

100

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 Manual, 07/2012, A5E03692294-01

System tasks

4.1

4.1.1

4

Command Line Interpreter

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

Arrow right/left

Arrow up/down

INS

DEL

Backspace

<CTRL>+a

<CTRL>+h

<CTRL>+z

<CTRL>+s

<CTRL>+q

Always overwrite existing characters

Generate a cursor movement

Copy/paste a previously entered command from the history buffer to the command line

Generates a whitespace character, or inserts a string that was previously cut with <CTRL>+a

Deletes the character at the cursor position

Replaces the character on the left side of the cursor position with a whitespace

Deletes the line from the cursor position to the line end

Same as Backspace

Terminates input when copying from the console, e.g. end of command copy con file.txt

.

Stop CLI output

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 writing their output data to stdout oder stderr

.

, and


System Manual, 07/2012, A5E03692294-01

101

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>

>> <file> or

1>> <file>

2> <file>

2>> <file>

< <file>

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

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.

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

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.

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.

102


System Manual, 07/2012, A5E03692294-01

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 Manual, 07/2012, A5E03692294-01

103

System tasks

4.2 Debugger

4.1.5

Dots appended to the file name are removed.

Double quotes are not supported for file redirection.

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

4.2.1

Debugger

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.

104


System Manual, 07/2012, A5E03692294-01

System tasks

4.2 Debugger

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>


System Manual, 07/2012, A5E03692294-01

105

System tasks

4.2 Debugger

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.

106


System Manual, 07/2012, A5E03692294-01

4.2.2

System tasks

4.2 Debugger

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.


System Manual, 07/2012, A5E03692294-01

107

System tasks

4.2 Debugger

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

TCD.EBX

Bit 0 ... 7

Bit 8 ... 15

Bit 0 = 0

Bit 0 = 1

Bit 1 = 0

Bit 1 = 1

Bit 2 ... 15

Contains the device ID

Contains the unit ID

Task processing allowed

Task processing inhibited

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

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.

108


System Manual, 07/2012, A5E03692294-01

4.2.7

4.2.8

System tasks

4.2 Debugger

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.

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.


System Manual, 07/2012, A5E03692294-01

109

System tasks

4.2 Debugger

0x

0n

0o

0m

‘ ‘

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: hexadecimal decimal octal 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

0n14

0n65

0x09

0x0E

0x41

0o011

0o016

0o101

0m00001001

0m00001110

0m01000001

(non-printable character)

(non-printable character)

‘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

CR current memory content command input with carriage return

110


System Manual, 07/2012, A5E03692294-01

System tasks

4.2 Debugger

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

<selector>

<offset>

<abs_addr>

L/P

<expr>

Meaning

Selector that references a descriptor in the current GDT or

LDT. <selector> may be <expr>

32–bit value, <offset> can be <expr> is an absolute 32–bit address

Keyword for linear/physical address (without paging unit identical)

(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

<term>

<factor>

<ident>

<cpureg>

Meaning

<factor>[[{*|/|%}<factor>]...]

{<ident>|<const>|(<expr>)}

{<cpureg>|<memory>|<port>}

{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|TR3

1)

|TR4

1)

|TR5

1)

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


System Manual, 07/2012, A5E03692294-01

111

System tasks

4.2 Debugger

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

<memory_format>

{byte|word|dword| qword}

<display_format>

{Mask|Octal|Hex|

Unsigned|Signed|

ASCII}

Meaning selects the element length of a specified memory range byte word dword

1 byte

2 bytes

4 bytes qword 8 bytes selects the format for display on the console

Mask Display as bit pattern: xxxx xxxx

Octal

Unsigned

Signed

Display as octal number

Display as unsigned decimal

Display as signed decimal

112


System Manual, 07/2012, A5E03692294-01

System tasks

4.2 Debugger

Argument

<data_type>

{Short|Long|Float|Double|

Tempreal|

Pointer|Spointer}

Meaning

Hex Representation as hexadecimal number

ASCII Display as string (1 byte per letter) contains memory_format + display_format

Short Signed word

Long

Pointer

Spointer

Float

Double

Tempreal

Signed dword

(long pointer) 16–bit selector:32–bit segment

(Short Pointer) 16–bit selector:16–bit segment

4–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

MB

MW

Execution breakpoint in the debug register

Modify (Read or Write) Byte Breakpoint

Modify (Read or Write) Word Breakpoint

MD

WB

WW

WD

Modify (Read or Write) Dword Breakpoint

Write Byte Breakpoint

Write Word Breakpoint

Write Dword Breakpoint


System Manual, 07/2012, A5E03692294-01

113

System tasks

4.2 Debugger

4.2.10

114

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. start step svc switch task tcb tcd inhib kill lines loadtask monitor out qualify query regs report set stack asm base breaks calculate

Call change cont cpureg

1 dir display evaluate exit exitk fill freetask go halt help in

Disassemble memory content

Set number base

List breakpoints

Calculate floating-point expression

Execute a program (only in task mode)

View/change memory bytes

Release interrupted task (only in task mode)

Check/edit register content

Display index entries (only in task mode)

Output memory content

Calculate integer expression

Exit debugger

Clear breakpoints and release interrupted task

Fill memory block with byte values

Deletes a dynamically loaded task (only in task mode)

Release interrupted task and exit debugger

Hold task (only in task mode)

Help command

Read I/O port

Enable/inhibit task processing (only in task mode)

Clear breakpoint(s)

Activate/deactivate paging

Load task (only in task mode)

Switch debugger to monitor mode (only in task mode)

Output I/O port

Parameterize breakpoint

Query task status (only in task mode)

Show all register contents

Resource report (only in task mode)

Set breakpoint(s)

Show stack

Start task in DORMANT state (only in task mode)

Execute single-step

Generate system call (only in task mode)

Switch breakpoint context

Switch debugger to task mode

Display TCB data of a task (only in task mode)

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.


System Manual, 07/2012, A5E03692294-01

4.2.11

System tasks

4.2 Debugger

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.


System Manual, 07/2012, A5E03692294-01

115

System tasks

4.2 Debugger

116

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.


System Manual, 07/2012, A5E03692294-01

System tasks

4.2 Debugger

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 Manual, 07/2012, A5E03692294-01

117

System tasks

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.

118


System Manual, 07/2012, A5E03692294-01

4.3.4

System tasks


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.

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 */

};


System Manual, 07/2012, A5E03692294-01

119

System tasks


Table 4- 6 Parameter structure of resource reporter

Parameters analyze_type id res1 timed_restart status

Meaning

Type of evaluation; a description of the coding is provided below.

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.

Reserved for future expansions; res1

should be 0.

Restart code; a description of the coding is provided below.

0

1

Pointer to a status array; 0 means that no status is written back. The following error codes are defined: no error invalid combination of restart and output to memory or file

2

3

4 invalid pointer to memory area insufficient memory for completion of output 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.

Device parameters:

Memory parameters: heap_len

All other bits are reserved.

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

Maximum number of characters that can be saved to memory.

Heap

Res2

Pointer to the start of a contiguous memory area.

Reserved for future expansions; should be 0

120


System Manual, 07/2012, A5E03692294-01

System tasks


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: file_name res3

0

1

2

A new file is created; any existing file is overwritten

The file is only created if it does not yet exist

Data is appended to a file; a new file is created if it does not yet exist

All other values are RESERVED.

Pointer to a valid file name that is concluded with 0 value; naming convention in accordance with HSFS naming

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 in EBX specifies whether or not to restart resource reporter.

; see Reference

Manual Part III). The parameter in EAX determines the evaluation type, while the parameter

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.


System Manual, 07/2012, A5E03692294-01

121

System tasks


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

15 14 13 12 11 10 9 8

Resource to evaluate

7 6 5

Tasks

Device drivers

Memory pools

Programs with monitored access

Mailboxes

Messages

Programs with monitored access

Mailboxes

Messages

Semaphores

Global event flags

4 3 2

Semaphores

Global event flags

1 0

Tasks

Device drivers

Memory pools

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

)

122


System Manual, 07/2012, A5E03692294-01

System tasks


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

Time_unit n.c.

Time_base

Restart flag

8 n.c.

7 6 count

5 4 3 2 1 0

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.


System Manual, 07/2012, A5E03692294-01

123

System tasks


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

Tasks

Device drivers

Memory pools

Semaphores

Global flags

Event flags

Mailboxes

Messages

Long version

Necessary memory spaces in bytes

58

264

262

40

16

12

12

8

12

14

8

4

22

4

24

For each task not in DORMANT state

For each driver

For each device

For each active or queued I/O request

For each pool

For each queued memory request

For each semaphore

For each queued task

For each flag group


For each mailbox


For each message

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.

124


System Manual, 07/2012, A5E03692294-01

4.4

4.4.1

4.4.2

System tasks

4.4 Exception Interrupt Handler

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.

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.

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.


System Manual, 07/2012, A5E03692294-01

125

System tasks

4.4 Exception Interrupt Handler 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 state tcb_ptr task_id svc_no intr_no err_code eflag, eip, cs, eax, ebx, ecx, edx, esi, edi, ebp, esp, ss, ds, es, fs, gs

Meaning

Bits 0-1 0

1

Exception interrupt in A state

Exception interrupt during SVC handling

Bit 2

2

3

0

Exception interrupt in I state

Exception interrupt in S state

Exception interrupt returns no CPU error code

1 Exception interrupt returns CPU error code

Further bits are reserved and set to 0.

Pointer to the TCB of the task that triggered the exception interrupt (0:0, if the nucleus triggered the interrupt).

ID of the task that triggered the exception interrupt.

(-1, if the nucleus triggered the interrupt)

Number of the SVC that was processed when the exception interrupt was triggered.

(-1, if the interrupt was triggered while no SVC was processed)

Number of the exception interrupt triggered

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.

Register contents at the time of exception interrupt.

126


System Manual, 07/2012, A5E03692294-01

4.4.3

System tasks


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

#define DEB_START TRUE

RMOS3 debugger is not started

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.

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:

2

3

Scenario

1

4

Exception triggered by

Task

SVC

Interrupt handler routine

Interrupt handler routine

System state

A

S

I

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


System Manual, 07/2012, A5E03692294-01

127

System tasks


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

INT 0:

INT 1:

INT 3:

INT 4:

INT 5:

INT 6:

INT 7:

INT 8:

INT 9:

INT 10:

INT 11:

INT 12:

INT 13:

INT 14:

INT 16:

INT 17:

STRING

DIVIDE ERROR AT ADDRESS:

DEBUG EXCEPTION NEAR ADDRESS:

BREAKPOINT EXCEPTION NEAR ADDRESS:

OVERFLOW EXCEPTION NEAR ADDRESS:

BOUNDS CHECK NEAR ADDRESS:

INVALID OPCODE AT ADDRESS:

NO COPROCESSOR AVAILABLE AT ADDRESS:

DOUBLE FAULT EXCEPTION AT ADDRESS:

NPX SEGMENT OVERRUN NEAR ADDRESS:

INVALID TSS AT ADDRESS:

SEGMENT NOT PRESENT AT ADDRESS:

STACK FAULT AT ADDRESS:

GENERAL PROTECTION AT ADDRESS:

PAGE FAULT AT ADDRESS:

FLOATING–POINT ERROR NEAR ADDRESS:

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.

128


System Manual, 07/2012, A5E03692294-01

4.4.4

System tasks


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 Manual, 07/2012, A5E03692294-01

129

System tasks

4.5 Busy task

4.5

System task

Busy 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 ref_count act_time start_time

Current count value

Reference value

Current system time in milliseconds

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 system idle time.

function to determine the percentage of the

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.

130


System Manual, 07/2012, A5E03692294-01

System tasks


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.


System Manual, 07/2012, A5E03692294-01

131

System tasks


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 [:,\,/].

Data volume names 4.6.1.1

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

132


System Manual, 07/2012, A5E03692294-01

System tasks


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

3

4

5

6

Function number

2

Function

Read block

Write block

Format unit

Read blocks

Write blocks


System Manual, 07/2012, A5E03692294-01

133

System tasks


Functions 2, 3, 5 and 6 are assigned the following parameters:

Table 4- 12 Parameters

Byte

0..3

4..9

10..13

Length:

A parameter list is not expected for function 4.

Content

Block number (dword)

Buffer address

Number of blocks to read or write; only necessary for functions 5 and 6

14 bytes

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

0

1

2

0FFH (–1)

0FEH (–2)

0FDH (–3)

0FCH (–4)

0FBH (–5)

Meaning

Request is queued

(reserved)

Successful completion

Parameter error

(reserved)

Timeout error

(reserved)

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.

134


System Manual, 07/2012, A5E03692294-01

System tasks


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

< 4085

4086 ... 8171

8172 ... 16243

> 16344

Cluster length

1.5 (12 bits)

1.5 (12 bits)

1.5 (12 bits)

2 (16 bits)

Sectors/clusters

1

2

4

4

FAT length

Sectors/314

12

12

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.


System Manual, 07/2012, A5E03692294-01

135

System tasks


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.

136


System Manual, 07/2012, A5E03692294-01

CCB

System tasks


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.


System Manual, 07/2012, A5E03692294-01

137

System tasks


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.

138


System Manual, 07/2012, A5E03692294-01

4.6.5.1

System tasks


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 (2

31 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

0

1..k k+1..(fat_cnt+1)*k

(fat_cnt+1)*k+1..m m+1..n–1

Content

Boot sector; necessary for identification of the volume format.

FAT; stores the logical organization of the data sectors. The number of blocks reserved for the FAT is specified in the VIB table.

This storage area comprises fat_cnt copies of the FAT. If it is omitted, the next areas are shifted forward by k blocks.

Root directory (FAT16 only); the number of blocks reserved for the root directory is specified in the VIB table.

Available storage space and file structures.


System Manual, 07/2012, A5E03692294-01

139

System tasks


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

0–11

12–13

14–17

18–21

22–23

24

25

26–27

28–29

30–31

Length:

Content

File name; left aligned, padded with blanks, byte 8 is always "."

Record length in bytes (1)

Number of records in file

Index for the first occupied cluster of the file

Reserved

File attributes

Bit

0

Meaning

System file

3

4

5

1

2 hidden read-only

Directory

Volume name

Archive reserved

Device driver file

6

7

Reserved

Time of creation or last change of the file

Date of creation or last change of the file

Reserved

32 bytes

Date and time values are stored based on the following scheme:

Byte 27

H H H H H 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 26

M M M M M M S

Byte 29

Y Y Y Y Y Y Y M

Byte 28

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

M D

S

D

S

D

S S

D D

140


System Manual, 07/2012, A5E03692294-01

4.6.6

System tasks


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 Manual, 07/2012, A5E03692294-01

141

System tasks


142


System Manual, 07/2012, A5E03692294-01

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 Manual, 07/2012, A5E03692294-01

143

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:

144


System Manual, 07/2012, A5E03692294-01

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 Manual, 07/2012, A5E03692294-01

145

System programs

5.3 RDISK32.EXE

5.3

Function

RDISK32.EXE

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 drive letter

Meaning

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:

146


System Manual, 07/2012, A5E03692294-01

5.4

Syntax

Example

System programs

5.4 VERS.EXE

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:

VERS <file name>

VERS RM3HLI.LIB <CR>

Vers Vx.y Mon Apr 14 18:34:55 1997 rm3hli.lib

RMOS3–HLI V2.5 P.F.


System Manual, 07/2012, A5E03692294-01

147

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

<pl0path>

PL0.386

CORE <n>

<path>

<progname>

<ext>

<arg n>

Meaning

Complete path of the directory that contains the

PL0.386 tool. For example, C:\RM3RUN

The program to load is to run on PL0.

The program to load is to be bound to CORE

<n>.

Complete path to the directory that contains the program to load.

For example, C:\RM3RUN

Name of the program to load.

For example,

RmIShSrv

Extension of the program to load.

For example DRV

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.

148


System Manual, 07/2012, A5E03692294-01

5.6

General

System programs

5.6 RMLDR, RMLDRFAT.16, RMLDRFAT.32

RMLDR, RMLDRFAT.16, RMLDRFAT.32

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 Manual, 07/2012, A5E03692294-01

149

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.

150


System Manual, 07/2012, A5E03692294-01

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 filename

/s

Meaning

RMOS3 nucleus as LOC file with OMF386 output format, e.g. RM3_PC1.LOC

Silent mode, LOADX messages re suppressed.

Description

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

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.

Call in AUTOEXEC.BAT:

LOADX C:\RM3RUN\RM3_PC1.LOC


System Manual, 07/2012, A5E03692294-01

151

System programs

5.8 BLOWUP

5.8

Function

BLOWUP

BLOWUP.EXE can be used to extend the RMOS3 nucleus RM3_PC1.SYS to a selected length.

Syntax

blowup <size> <name>

Parameters

Parameters size name

Meaning

Selected file size in KB.

Default is 608 KB.

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.

152


System Manual, 07/2012, A5E03692294-01

5.9

Function

SYSCOPY.EXE

System programs

5.9 SYSCOPY.EXE

Copy unfragmented RMOS3 nucleus ((e.g. RM3_PC1.SYS) to the boot partition.

Syntax

SYSCOPY <filename> <volume_name>

Parameters

Parameters filename volume_name

Meaning

Name of the boot file (including the pathname) (source file)

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 Manual, 07/2012, A5E03692294-01

153

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:

154


System Manual, 07/2012, A5E03692294-01

5.10

Function

SYSCOPY32.EXE

System programs

5.10 SYSCOPY32.EXE

Copy unfragmented RMOS3 nucleus ((e.g. RM3_PC1.SYS) to the boot partition.

Syntax

SYSCOPY32 <filename> <volume_name>

Parameters

Parameters filename volume_name

Meaning

Name of the boot file (including the pathname) (source file)

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 Manual, 07/2012, A5E03692294-01

155

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:

156


System Manual, 07/2012, A5E03692294-01

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.


System Manual, 07/2012, A5E03692294-01

157


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

158

Erasable Programmable Read Only Memory, semiconductor memory chip that can be programmed by users


System Manual, 07/2012, A5E03692294-01

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


System Manual, 07/2012, A5E03692294-01

159


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

160


System Manual, 07/2012, A5E03692294-01


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.


System Manual, 07/2012, A5E03692294-01

161


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.

162


System Manual, 07/2012, A5E03692294-01

TIB

TMB

UART

UCB

TCP

TCP/IP

Telnet

UCD

Unit


Transmission Control Protocol

TCP Internet Protocol

Telecommunication Network, dialog service via TCP/IP networks

Timer Control Block

Time Monitor Block; set up by the nucleus for managing time-related calls

Universal Asynchronous Receiver and Transmitter; block for serial data transmission

Unit Control Block; table that lists the current dynamic data for controlling a unit.

Unit Control Data; table listing the default configuration values

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.


System Manual, 07/2012, A5E03692294-01

163


164


System Manual, 07/2012, A5E03692294-01

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


System Manual, 07/2012, A5E03692294-01

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

165

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

166

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


System Manual, 07/2012, A5E03692294-01

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


System Manual, 07/2012, A5E03692294-01

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

167

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

168


System Manual, 07/2012, A5E03692294-01

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

Assistant Bot

RMOS3

Real-time operating system RMOS3

RMOS3 V3.50

System Manual

System Manual

07/2012

Legal information

Table of contents

About this document . .

1.1

Overview

About this document . .

Chapter 1

Chapter 2

Chapter 3

Chapter 4

Chapter 5

1.2 Notations

Commands

Abbreviations

Data types

Configuring the RMOS3 nucleus

2.1

Introduction

2.2

Overview

RMOS3 operating system components

2.2.1 RMOS3 nucleus

2.2.2 High-level languages interface

2.2.3

2.2.4

APIC driver

BYT driver

2.2.5

CRT driver

2.2.6

2.2.7

2.2.8

COM driver

DMA driver

RAM-DISK driver

2.2.9 Floppy disk driver FD0

2.2.10 Hard disk driver HD0

2.2.11 Hard disk driver UDMA

2.2.12 HPET driver

2.2.13 Network drivers

2.2.14

PCI driver

2.2.15 Command line interpreter CLI

2.2.16 HSFS file management system

2.2.17 CRUN C runtime support

2.2.18

Low level real-time debugger

2.2.19

High-level language debugger

2.2.20 Resource reporter

2.2.21 Profiler RPROF

2.2.22 Exception interrupt handler

2.2.23 Arithmetic processor

2.2.24 SVC exception handler

2.2.25 Relocatable task loader

2.2.26 Boot loaders for the operating system

2.3

2.3.1

2.3.2

SRB

SMR

Structures and elements of the RMOS3 nucleus

Tasks

Internal nucleus structures SRB and SMR

2.3.3

2.3.4

2.3.5

Drivers and devices

Interrupt vectors

Memory pools

2.3.6 Memory allocation of the RMOS3 nucleus

2.3.7