6AR1403-0CC3 - SIEMENS - Product.Network

RMOS3 V3.50 Reference Manual Part II

___________________

RMOS3

RMOS3 real-time operating system

RMOS3 V3.50

Reference Manual Part II

Programming Manual

07/2012

A5E03692298

-01

About this manual...

Function groups

Data structures

Error codes and messages

Functions and configuration

of the basic I/O system

Abbreviations/glossary

Siemens AG

Industry Sector

Postfach 48 48

90026 NÜRNBERG

GERMANY

A5E03692298-01

Ⓟ

07/2012 Technical data subject to change

Legal information

Warning notice system

This manual contains notices you have to observe in order to ensure your personal safety, as well as to prevent

damage to property. The notices referring to your personal safety are highlighted in the manual by a safety alert

symbol, notices referring only to property damage have no safety alert symbol. These notices shown below are

graded according to the degree of danger.

DANGER

indicates that death or severe personal injury will result if proper precautions are not taken.

WARNING

indicates that death or severe personal injury may result if proper precautions are not taken.

CAUTION

indicates that minor personal injury can result if proper precautions are not taken.

NOTICE

indicates that property damage can result if proper precautions are not taken.

If more than one degree of danger is present, the warning notice representing the highest degree of danger will

be used. A notice warning of injury to persons with a safety alert symbol may also include a warning relating to

property damage.

Qualified Personnel

The product/system described in this documentation may be operated only by

personnel qualified

for the specific

task in accordance with the relevant documentation, in particular its warning notices and safety instructions.

Qualified personnel are those who, based on their training and experience, are capable of identifying risks and

avoiding potential hazards when working with these products/systems.

Proper use of Siemens products

Note the following:

WARNING

Siemens products may only be used for the applications described in the catalog and in the relevant technical

documentation. If products and components from other manufacturers are used, these must be recommended

or approved by Siemens. Proper transport, storage, installation, assembly, commissioning, operation and

maintenance are required to ensure that the products operate safely and without any problems. The permissible

ambient conditions must be complied with. The information in the relevant documentation must be observed.

Trademarks

All names identified by ® are registered trademarks of Siemens AG. The remaining trademarks in this publication

may be trademarks whose use by third parties for their own purposes could violate the rights of the owner.

Disclaimer of Liability

We have reviewed the contents of this publication to ensure consistency with the hardware and software

described. Since variance cannot be precluded entirely, we cannot guarantee full consistency. However, the

information in this publication is reviewed regularly and any necessary corrections are included in subsequent

editions.

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 3

Table of contents

1 About this manual... .............................................................................................................................. 11

1.1 About this manual... ..................................................................................................................... 11

1.2 Notations ...................................................................................................................................... 12

2 Function groups .................................................................................................................................... 15

2.1 RMOS3 functions ......................................................................................................................... 15

2.1.1 Notes on programming in C ......................................................................................................... 16

2.1.2 Short description of the RMOS3 functions ................................................................................... 17

2.1.3 Configuration functions ................................................................................................................ 23

2.1.4 Miscellaneous functions ............................................................................................................... 25

2.2 CLI functions ................................................................................................................................ 26

2.2.1 Startup code for C programs ........................................................................................................ 26

2.2.2 Problems when aborting a program ............................................................................................. 26

2.2.3 Short description of the CLI functions .......................................................................................... 27

2.3 C library functions ........................................................................................................................ 28

2.3.1 Scope of the C library .................................................................................................................. 28

2.3.2 Short description of the C library functions .................................................................................. 28

2.4 Driver functions ............................................................................................................................ 37

2.4.1 Application model ......................................................................................................................... 37

2.4.2 Short description of the driver functions ...................................................................................... 38

2.4.3 System variables for parameter transfer ...................................................................................... 39

2.4.4 Differences between type I and type II drivers ............................................................................. 39

3 Data structures ..................................................................................................................................... 43

3.1 RmAbsTimeStruct ........................................................................................................................ 43

3.2 RmAsciiTimeStruct....................................................................................................................... 44

3.3 RmDCDStruct .............................................................................................................................. 45

3.4 RmEntryStruct .............................................................................................................................. 46

3.5 RmIntrhandMailStruct .................................................................................................................. 47

3.6 RmIOStatusStruct ........................................................................................................................ 48

3.7 RmIRBStruct ................................................................................................................................ 49

3.8 RmMailboxStruct .......................................................................................................................... 50

3.9 RmMailIDStruct ............................................................................................................................ 51

3.10 RmMemPoolInfoStruct ................................................................................................................. 52

3.11 RmSpinLockStruct ....................................................................................................................... 53

3.12 RmSysB ....................................................................................................................................... 54

3.13 RmTaskInfoStruct ........................................................................................................................ 57

Table of contents

RMOS3 V3.50 Reference Manual Part II

4 Programming Manual, 07/2012, A5E03692298-01

3.14 RmTCDStruct .............................................................................................................................. 59

3.15 RmTimeStruct ............................................................................................................................. 62

3.16 RmTMBStruct .............................................................................................................................. 63

3.17 RmUCDHeadStruct ..................................................................................................................... 67

3.18 RmUCDStruct ............................................................................................................................. 68

3.19 loader_result ................................................................................................................................ 69

3.20 stdstruct ....................................................................................................................................... 71

4 Error codes and messages ................................................................................................................... 73

4.1 Nucleus ....................................................................................................................................... 73

4.2 Error codes of the RMOS3 API calls ........................................................................................... 76

4.3 SVC exception handler ............................................................................................................... 80

4.4 CLI ............................................................................................................................................... 81

4.5 CRUN .......................................................................................................................................... 84

4.6 HSFS ........................................................................................................................................... 86

4.7 Debugger..................................................................................................................................... 87

4.8 Resource reporter ....................................................................................................................... 90

4.9 Task loader stl_load, stl_free....................................................................................................... 91

4.10 LOADRM task loader .................................................................................................................. 93

5 Functions and configuration of the basic I/O system .............................................................................. 95

5.1 Overview ..................................................................................................................................... 95

5.2 BYT driver ................................................................................................................................... 96

5.2.1 Properties .................................................................................................................................... 96

5.2.1.1 Optional EGA functions ............................................................................................................... 97

5.2.1.2 Half/full duplex mode ................................................................................................................... 97

5.2.1.3 Control characters for BYT drivers and terminals ....................................................................... 99

5.2.1.4 History mode ............................................................................................................................. 101

5.2.1.5 Data flow of received characters ............................................................................................... 101

5.2.1.6 Special features for EGA units .................................................................................................. 104

5.2.1.7 Opcodes of the BYT driver (bits 0..3) ........................................................................................ 111

5.2.2 RmIO interface .......................................................................................................................... 113

5.2.2.1 Function parameter ................................................................................................................... 113

5.2.2.2 Parameter pState ...................................................................................................................... 115

5.2.2.3 Parameter pParam .................................................................................................................... 117

5.2.3 Opcodes of the BYT driver ........................................................................................................ 118

5.2.3.1 Reserve unit (BYT_RESERVE) ................................................................................................ 118

5.2.3.2 Release unit (BYT_RELEASE) ................................................................................................. 120

5.2.3.3 Read (BYT_READ) ................................................................................................................... 121

5.2.3.4 Write (BYT_WRITE) .................................................................................................................. 123

5.2.3.5 Unconditional writing (BYT_XWRT) .......................................................................................... 125

5.2.3.6 Read character in transparent mode (BYT_ONE_XREAD) ...................................................... 125

5.2.3.7 Write and read in transparent mode (BYT_WRT_XREAD) ....................................................... 125

5.2.3.8 Write and read (BYT_WRT_READ) .......................................................................................... 126

Table of contents

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 5

5.2.3.9 Skip line (BYT_SKIP_LINE) ....................................................................................................... 127

5.2.3.10 Clear screen (BYT_FORM_FEED) ............................................................................................ 127

5.2.3.11 Read character to buffer in transparent mode (BYT_HSFS_XREAD) ....................................... 127

5.2.3.12 Write character (BYT_HSFS_WRT) ........................................................................................... 128

5.2.3.13 Read interim buffer in transparent mode (BYT_POLL_XBUF) .................................................. 128

5.2.3.14 Check input buffer for abort characters (BYT_CHECK_ABO) ................................................... 129

5.2.3.15 Redefine and initialize the unit (BYT_CREATE_NEW) .............................................................. 130

5.2.3.16 Multifunction (only for EGA units) .............................................................................................. 131

5.2.4 Configuration .............................................................................................................................. 141

5.2.4.1 Driver Control Data table (RmDCDStruct in RMTYPES.H) ....................................................... 142

5.2.4.2 Unit Control Data table (RmUCDStruct in RMTYPES.H) .......................................................... 142

5.2.4.3 Driver-specific parameters in the UCD block ............................................................................. 143

5.2.4.4 Interrupt routines of the BYT driver ............................................................................................ 153

5.2.4.5 Configuring the control characters in Rinitbyt.c ......................................................................... 154

5.2.4.6 EGA–specific configuration ........................................................................................................ 155

5.2.4.7 Ribtega.c .................................................................................................................................... 156

5.2.4.8 Stack requirements of the BYT driver ........................................................................................ 159

5.3 CRT drivers ................................................................................................................................ 160

5.3.1 Properties ................................................................................................................................... 160

5.3.1.1 Sequence of functions ............................................................................................................... 160

5.3.1.2 Timeout handling........................................................................................................................ 160

5.3.1.3 Control characters ...................................................................................................................... 161

5.3.1.4 Opcodes of the CRT driver (bits 0 to 3) ..................................................................................... 162

5.3.2 RmIO interface ........................................................................................................................... 162

5.3.2.1 Function parameter .................................................................................................................... 163

5.3.2.2 Parameter pState ....................................................................................................................... 164

5.3.2.3 Parameter pParam ..................................................................................................................... 165

5.3.3 Opcodes of the CRT driver ........................................................................................................ 165

5.3.3.1 Reserve unit (CRT_RESERVE) ................................................................................................. 165

5.3.3.2 Release unit (CRT_RELEASE) .................................................................................................. 166

5.3.3.3 Read (CRT_READ) .................................................................................................................... 166

5.3.3.4 Write (CRT_WRITE) .................................................................................................................. 167

5.3.3.5 Write (CRT_WRITE) .................................................................................................................. 167

5.3.3.6 Read character in transparent mode (CRT_ONE_XREAD) ...................................................... 168

5.3.3.7 Write and read in transparent mode (CRT_WRT_XREAD) ....................................................... 168

5.3.3.8 Write and read (CRT_WRT_READ) ........................................................................................... 169

5.3.3.9 Line feed/skip line (CRT_SKIP_LINE) ....................................................................................... 169

5.3.3.10 Form feed/clear screen (CRT_FORM_FEED) ........................................................................... 169

5.3.3.11 Read character in transparent mode (CRT_HSFS_XREAD) ..................................................... 170

5.3.3.12 Write character (CRT_HSFS_WRITE) ....................................................................................... 170

5.3.3.13 Redefine unit (CRT_CREATE_NEW) ........................................................................................ 170

5.3.3.14 Keyboard control characters for I/O devices .............................................................................. 171

5.3.3.15 ASCII codes used by the CRT DRIVER .................................................................................... 171

5.3.4 Configuration .............................................................................................................................. 172

5.3.4.1 Driver control data table (DCD) .................................................................................................. 172

5.3.4.2 Unit Control Data table (UCD) ................................................................................................... 172

5.3.4.3 Driver-specific parameters in the UCD block ............................................................................. 173

5.3.4.4 Interrupt routines of the CRT2 driver ......................................................................................... 177

5.3.4.5 Stack requirements of the CRT2 driver ..................................................................................... 177

5.4 RAM disk driver .......................................................................................................................... 178

5.4.1 Properties ................................................................................................................................... 178

Table of contents

RMOS3 V3.50 Reference Manual Part II

6 Programming Manual, 07/2012, A5E03692298-01

5.4.1.1 Sequence of the RmIO system call ........................................................................................... 179

5.4.1.2 Opcodes of the RAM DISK driver ............................................................................................. 179

5.4.2 RmIO interface .......................................................................................................................... 180

5.4.2.1 Function parameter ................................................................................................................... 180

5.4.2.2 Parameter pState ...................................................................................................................... 181

5.4.2.3 Parameter pParam .................................................................................................................... 182

5.4.3 Opcodes .................................................................................................................................... 183

5.4.3.1 Reserve RAM DISK (00H) ........................................................................................................ 183

5.4.3.2 Release RAM DISK (01H) ......................................................................................................... 183

5.4.3.3 Read logical block (02H) ........................................................................................................... 184

5.4.3.4 Write logical block (03H) ........................................................................................................... 184

5.4.3.5 Dummy operation (04H) ............................................................................................................ 184

5.4.3.6 Read logical blocks (05H) ......................................................................................................... 185

5.4.3.7 Write logical blocks (06H) ......................................................................................................... 185

5.4.3.8 I/O control operation (0EH) ....................................................................................................... 186

5.4.4 Configuration ............................................................................................................................. 187

5.4.4.1 Driver control data (DCD) table ................................................................................................. 187

5.4.4.2 Unit Control Data table .............................................................................................................. 188

5.5 DMA driver ................................................................................................................................ 190

5.5.1 Properties .................................................................................................................................. 190

5.5.1.1 Functionality of the DMA driver ................................................................................................. 190

5.5.1.2 Note for use as subprogram...................................................................................................... 190

5.5.1.3 Special features of the DMA controller ..................................................................................... 190

5.5.2 RmIO interface .......................................................................................................................... 191

5.5.2.1 Function parameter ................................................................................................................... 191

5.5.2.2 Parameter pState ...................................................................................................................... 192

5.5.2.3 Parameter pParam .................................................................................................................... 193

5.5.3 Opcodes .................................................................................................................................... 193

5.5.3.1 Reserve unit (DMA_RESERVE) ............................................................................................... 193

5.5.3.2 Release unit (DMA_RELEASE) ................................................................................................ 194

5.5.3.3 Read from memory (DMA_READ) ............................................................................................ 194

5.5.3.4 Write to memory (DMA_WRITE) ............................................................................................... 194

5.5.3.5 Transmission abortion (DMA_ABORT) ..................................................................................... 195

5.5.3.6 Redefine unit (DMA_CREATE) ................................................................................................. 195

5.5.3.7 Subprogram calls of the DMA driver ......................................................................................... 196

5.5.3.8 Program call (X_DM2_DRIVER) ............................................................................................... 199

5.6 FD0 driver.................................................................................................................................. 200

5.6.1 Properties .................................................................................................................................. 200

5.6.1.1 Sequence of functions ............................................................................................................... 201

5.6.1.2 Opcodes of the FD0 driver ........................................................................................................ 201

5.6.2 RmIO interface .......................................................................................................................... 202

5.6.2.1 Function parameter ................................................................................................................... 202

5.6.2.2 Parameter pState ...................................................................................................................... 203

5.6.2.3 Parameter pParam .................................................................................................................... 205

5.6.3 Opcodes .................................................................................................................................... 206

5.6.3.1 Reserve unit (FD2_RESERVE) ................................................................................................. 206

5.6.3.2 Release unit (FD2_RELEASE) ................................................................................................. 206

5.6.3.3 Read logical block (FD2_READ_1) ........................................................................................... 207

5.6.3.4 Write logical block (FD2_WRITE_1) .......................................................................................... 207

5.6.3.5 Format floppy disk (FD2_FORMAT) ......................................................................................... 207

5.6.3.6 Read logical blocks (FD2_READ) ............................................................................................. 207

Table of contents

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 7

5.6.3.7 Write logical blocks (FD2_WRITE) ............................................................................................. 208

5.6.3.8 Position to track (FD2_SEEK) .................................................................................................... 208

5.6.3.9 Position to track 0 (FD2_RECA) ................................................................................................ 208

5.6.3.10 Get drive status (FD2_UNIT_RDY) ............................................................................................ 208

5.6.3.11 Remove drive parameters (delete) (FD2_DELETE) .................................................................. 209

5.6.3.12 Define drive parameters (create) (FD2_CREATE) .................................................................... 209

5.6.4 Configuration .............................................................................................................................. 210

5.6.4.1 Driver control data (DCD) table .................................................................................................. 210

5.6.4.2 Unit Control Data (UCD) table ................................................................................................... 210

5.6.4.3 Interrupt routines of the FD0 driver ............................................................................................ 216

5.6.4.4 Stack requirements of the FD0 driver ........................................................................................ 216

5.7 HD0 driver .................................................................................................................................. 217

5.7.1 Properties ................................................................................................................................... 217

5.7.1.1 Area of application and opcode ................................................................................................. 218

5.7.2 RmIO interface ........................................................................................................................... 218

5.7.2.1 Function parameter .................................................................................................................... 219

5.7.2.2 Parameter pState ....................................................................................................................... 220

5.7.2.3 Parameter pParam ..................................................................................................................... 222

5.7.3 Opcodes ..................................................................................................................................... 223

5.7.3.1 Reserve unit (00H) ..................................................................................................................... 223

5.7.3.2 Release unit (01H) ..................................................................................................................... 223

5.7.3.3 Read logical block (02H) ............................................................................................................ 223

5.7.3.4 Write logical block (03H) ............................................................................................................ 223

5.7.3.5 Format hard disk (04H) .............................................................................................................. 224

5.7.3.6 Read logical blocks (05H) .......................................................................................................... 224

5.7.3.7 Write logical blocks (06H) .......................................................................................................... 224

5.7.3.8 Read drive parameters (0AH) .................................................................................................... 225

5.7.3.9 Remove drive parameters (delete or dismount) (0BH) .............................................................. 225

5.7.3.10 Define drive parameters (create or mount) (0CH) ..................................................................... 225

5.7.4 Configuration .............................................................................................................................. 226

5.7.4.1 Driver control data (DCD) table .................................................................................................. 226

5.7.4.2 Unit Control Data (UCD) table ................................................................................................... 226

5.7.4.3 Driver-specific parameters in the UCD block ............................................................................. 227

5.7.4.4 Interrupt routines of the HD0 driver............................................................................................ 233

5.7.4.5 Stack requirements of the HD0 driver ........................................................................................ 233

5.8 COM driver ................................................................................................................................. 234

5.8.1 Properties ................................................................................................................................... 234

5.8.1.1 Sequence of functions ............................................................................................................... 234

5.8.1.2 Timeout handling........................................................................................................................ 235

5.8.1.3 Transfer protocol ........................................................................................................................ 235

5.8.1.4 Signal sequences ....................................................................................................................... 236

5.8.1.5 Example of signal sequences .................................................................................................... 238

5.8.1.6 Control characters ...................................................................................................................... 241

5.8.1.7 Opcodes of the COM driver ....................................................................................................... 241

5.8.2 RmIO interface ........................................................................................................................... 242

5.8.2.1 Function parameter .................................................................................................................... 242

5.8.2.2 Parameter pState ....................................................................................................................... 243

5.8.2.3 Parameter pParam ..................................................................................................................... 244

5.8.3 Opcodes ..................................................................................................................................... 245

5.8.3.1 Reserve unit (C64_RESERVE) .................................................................................................. 245

5.8.3.2 Release unit (C64_RELEASE) ................................................................................................... 246

Table of contents

RMOS3 V3.50 Reference Manual Part II

8 Programming Manual, 07/2012, A5E03692298-01

5.8.3.3 Read (C64_READ) .................................................................................................................... 246

5.8.3.4 Write (C64_WRITE) .................................................................................................................. 247

5.8.3.5 Redefine unit (C64_CREATE_NEW) ........................................................................................ 247

5.8.4 Configuration ............................................................................................................................. 248

5.8.4.1 Driver Control Data table (RmDCDStruct in RMTYPES.H) ...................................................... 248

5.8.4.2 Unit Control Data table (RmUCDStruct in RMTYPES.H) ......................................................... 249

5.8.4.3 Driver-specific parameters in the UCD block ............................................................................ 249

5.8.4.4 Interrupt routines of the COM driver ......................................................................................... 254

5.8.4.5 Stack requirements of the COM driver ...................................................................................... 255

5.9 SRAM driver .............................................................................................................................. 256

5.9.1 Areas of application ................................................................................................................... 256

5.9.1.1 Organization of tasks/functions ................................................................................................. 256

5.9.2 RmIO interface .......................................................................................................................... 257

5.9.2.1 Function parameter ................................................................................................................... 258

5.9.2.2 Parameter pState ...................................................................................................................... 259

5.9.2.3 Parameter pParam .................................................................................................................... 260

5.9.3 Opcodes .................................................................................................................................... 260

5.9.3.1 Reserve unit (RD40_RESERVE) .............................................................................................. 260

5.9.3.2 Release unit (RD40_FREE) ...................................................................................................... 260

5.9.3.3 Read logical block (RD40_READ_ONE) ................................................................................... 261

5.9.3.4 Write logical block (RD40_WRITE_ONE) ................................................................................. 261

5.9.3.5 Format (RD40_FORMAT) ......................................................................................................... 261

5.9.3.6 Read logical blocks (RD40_READ_MORE) .............................................................................. 262

5.9.3.7 Write logical blocks (RD40_WRITE_MORE) ............................................................................. 262

5.9.3.8 I/O control operation (RD40_IOCTRL) ...................................................................................... 262

5.9.4 Configuration ............................................................................................................................. 264

5.9.4.1 Driver control data (DCD) table ................................................................................................. 264

5.9.4.2 Unit Control Data (UCD) table................................................................................................... 265

A Abbreviations/glossary ......................................................................................................................... 267

Index ................................................................................................................................................... 275

Table of contents

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 9

Tables

Table 1- 1 Commands ................................................................................................................................... 12

Table 1- 2 Abbreviations ............................................................................................................................... 12

Table 1- 3 General data types ....................................................................................................................... 13

Table 1- 4 Data types of the RMOS3 API ..................................................................................................... 13

Table 5- 1 Combination of read and write operations in DUPLEX mode ...................................................... 98

Table 5- 2 Function code of the internal input interface .............................................................................. 108

Table 5- 3 RmIO parameter Function of the BYT driver ............................................................................. 113

Table 5- 4 Configuration as I/O device (e.g. terminal) ................................................................................ 114

Table 5- 5 Configuration as output device (e.g. line printer) ....................................................................... 115

Table 5- 6 Configuration as input device (e.g. keyboard): .......................................................................... 115

Table 5- 7 RmIO parameter pState ............................................................................................................. 116

Table 5- 8 RmIO parameter pState (continuation) ...................................................................................... 117

Table 5- 9 ASCII characters ........................................................................................................................ 157

Table 5- 10 Defines for status displays ......................................................................................................... 260

Table 5- 11 Parameters in UCD_HEAD ........................................................................................................ 265

Table 5- 12 Parameters in UCD_RD40_TYPE.............................................................................................. 265

Table 5- 13 Parameters in UCD_RD40_COMMON ...................................................................................... 265

Table of contents

RMOS3 V3.50 Reference Manual Part II

10 Programming Manual, 07/2012, A5E03692298-01

Figures

Figure 2-1 System processes ........................................................................................................................ 37

Figure 5-1 Data flow of an incoming expected character in the BYT driver ................................................ 101

Figure 5-2 Data flow of an incoming unexpected character in the BYT driver ............................................ 102

Figure 5-3 Handling of control characters in the BYT driver for transparent read jobs ............................... 102

Figure 5-4 Handling of control characters in the BYT driver for standard read jobs ................................... 103

Figure 5-5 Handling of character output in the BYT driver .......................................................................... 103

Figure 5-6 Keyboard integration .................................................................................................................. 108

Figure 5-7 Example of unit 2 (debugger) output to the assigned window 2 on page 2 ............................... 109

Figure 5-8 Page 0, window arrangement .................................................................................................... 110

Figure 5-9 Page 0, window arrangement .................................................................................................... 110

Figure 5-10 Assigning scan codes to the individual keys .............................................................................. 156

Figure 5-11 Character table from 0 to 255 (0H to FFH), part 1 ..................................................................... 158

Figure 5-12 Character table from 0 to 255 (0H to FFH), part 2 ..................................................................... 159

Figure 5-13 Receiving data ........................................................................................................................... 238

Figure 5-14 Sending data .............................................................................................................................. 239

Figure 5-15 Master slave configuration with initiation conflict ....................................................................... 240

Figure 5-16 Structure of the RMOS3 driver functions ................................................................................... 257

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 11

About this manual...

1.1

About this manual...

Overview

This reference manual provides you with support for programming the RMOS3 system. It

contains an overview of the supported function calls, of RMOS3 data structures, of error

codes and error messages, as well as of the programming of RMOS3 drivers.

Chapter 1

"About this manual . . " offers you a guideline to the documentation and explains the

notations used in the manual.

Chapter 2

""Function groups (Page 15)" shows the programmable functions in their logical context. If

looking for a solution for a specific task, this chapter will help you to identify the function that

is suitable for your application. The chapter also provides a description of the conditions for

using the individual call groups. For a more detailed description of the individual functions,

refer to the part III and IV of the reference manual.

Chapter 3

""Data structures (Page 43)" contains the most important structure definitions used for

programming.

Chapter 4

""Error codes and error messages (Page 73)" lists all possible error codes for the RMOS3

components.

Chapter 5

"Functions and configuration of the basic I/O system (Page 95)" provides a separate

description of the function of each RMOS3 driver and explains the call syntax.

About this manual...

1.2 Notations

RMOS3 V3.50 Reference Manual Part II

12 Programming Manual, 07/2012, A5E03692298-01

1.2

Notations

We use the following notation to enhance legibility of the RMOS3 documentation:

Commands

Commands control program sequences in dialog or batch mode. The Courier font is used in

the text to highlight the commands. A command consists of at least one element. Elements

are constants or variables. They are comprised of letters, numbers and special characters

(e.g.

#*?

The Courier font is also used to present program listings. They are printed in compliance

with the characters and do not follow the notation for commands. The programming

language C, for example, distinguishes between uppercase and lowercase notation.

Table 1- 1 Commands

Representation

Property

Comment

UPPERCASE Constant Elements in uppercase notation represent constants. Entries

are made in accordance with the character notation with

support of uppercase and lowercase letters.

1847

Constant

Numbers are always constants.

x Variable

Elements in lowercase notation represent variables that can be

replaced by current elements.

()\:;> Special

characters

Special characters and whitespaces serve as delimiters

between elements and always need to be entered.

The use of elements is described by meta characters. Meta characters are not entered.

Representation

Property

Comment

< >

Delimiters

Variables are enclosed in angled brackets

[ ]

Optional

Elements in angled brackets are optional.

|a|b|c| Selection An element can be selected if several elements are arranged

vertically in braces or horizontally between vertical lines.

...

Repetition

Ellipses indicate a possible repetition of the previous element.

Abbreviations

A number of abbreviations and short names apply to the entire RMOS3 documentation:

Table 1- 2 Abbreviations

Abbreviation

Meaning

Text passage

cfg configurable System calls

uintmax

maximum unsigned integer (FFFF FFFFH)

System calls

data pointer (sel:off) 48-bit pointer

System calls

About this manual...

1.2 Notations

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 13

Data types

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

Table 1- 3 General data types

Data type

Data length

char

8 bit

short

16 bit

int

32 bit

long

32 bit

long long

64 bit

void _FAR *

48 bit

void _NEAR *

32 bit

enum

32 bit

float

32 bit

double

64 bit

Only available for GNU programs.

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

NEAR and FAR.

Table 1- 4 Data types of the RMOS3 API

Name

Data type

Data length

uchar

unsigned char

8 bit

ushort

unsigned short

16 bit

uint

unsigned int

32 bit

ulong

unsigned long

32 bit

rmfarproc 1 Pointer to function type

void _FAR f(void)

48 bit

rmnearproc 1 Pointer to function type

void _NEAR f(void)

32 bit

rmproc 1 Pointer to function type

void _NEAR f(void)

32 bit

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

NEAR and FAR.

About this manual...

1.2 Notations

RMOS3 V3.50 Reference Manual Part II

14 Programming Manual, 07/2012, A5E03692298-01

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 15

Function groups

The chapter lists the expressions used to program RMOS3 in their logical context. If using

the functions of a group in reloadable tasks or programs, you need to provide the

corresponding library during linking:

For GNU compilers:

RMOS3 kernel functions

libhlig.a

CLI functions

libclig.a

C library functions

libcrig.a

2.1

RMOS3 functions

RMOS3 V3.11 or higher offers a new application programming interface (API). The API is a

pure function interface, with the return value of the function generally providing information

related to the sequence (error code etc.). The function may also return notes.

This API is supplied as library for compilers with segmented memory model and for

compilers with FLAT memory model. Certain calls (descriptor operations, configuration calls)

are not implemented in the FLAT interface.

Programs and tasks that output calls to RMOS3 in accordance with V3.0 or earlier can still

be executed.

RMAPI.H is included as header file with the prototypes for the API. This file, in turn, includes

the RMTYPES.H (SVC specific type definitions) and RMDEF.H (general definitions such as

error codes etc.) files.

The RMCOMP.H header file contains macros for customizing the application to the different

C compilers and memory models. These macros are used by other include files (RMAPI.H,

CRUN).

The header file SVC.H is only required for SVCs to be migrated from an interface for RMOS3

V3.0.

Function groups

2.1 RMOS3 functions

RMOS3 V3.50 Reference Manual Part II

16 Programming Manual, 07/2012, A5E03692298-01

2.1.1

Notes on programming in C

The RMOS3 system calls are demonstrated based on code examples written in C.

The C interface is described by the RMAPI.H file in directory INC. This file contains all

function prototypes of the RMOS3 API. The files RMDEF.H and RMTYPES.H are also

included. RMDEF.H contains the define constants, while RMTYPES.H contains the

structures for programming the system calls.

It is advisable to use the defined constants from RMDEF.H to exclude parameter errors.

The parameters are always transferred via stack, with the return value containing the SVC

error code. RM_OK (= 0) is returned if no errors were found. A value greater than 0 is

returned if errors are found. Certain SVCs also return negative values, e.g. RmSetFlag

returns RM_FLAG_ALREADY_SET if the flag was already set.

Example of a system call:

main()

{

int Error;

void *Pointer;

...

Error = RmAlloc( RM_CONTINUE, RM_NOAUTOFREE,

0ul, &Pointer)

...

}

Allocates a memory space of 1000 bytes that is not released automatically, therefore it is not

allocated to specific tasks. The program does not wait on allocation if there is not sufficient

memory space available.

Notes on using PUBLIC symbols

All PUBLIC symbols used in RMOS3 start with an x or x_ coding. These symbols are also

available for the software drivers. It is advisable to dispense with the usage of PUBLIC

symbols beginning with x or x_ to avoid possible conflicts.

Interrupt numbers

The interrupt number for all interrupt handler SVCs can be set in two different ways:

1. Number between 0 and 255

The interrupt is handled as software interrupt.

2. IRQ<n>

The number <n> is entered directly, e.g. IRQ1, IRQ2. The interrupt is handled as

hardware interrupt.

Values such as IRQ1 or IRQ2 are specified in an include file. The IRQ(x) macro can be

used to transfer the IRQ number in a variable. (x) can be a value between 0 and the

maximum available interrupt. The range of values 0..15 (0..23 for APIC) is valid on the

PC.

Function groups

2.1 RMOS3 functions

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 17

Notes on timer programming

Timeout values used in your program are entered in the timer queue according to their

expiration time (sorted by timer ticks). Multiple timeout requests for a timer tick are

processed based on the

Last In First Out

principle.

If a timer tick is triggered between two timeout requests of the same duration, the requests

are distributed to different timer ticks.

Example:

Timeout request 1,2,3 within one timer tick, and timeout request 4,5,6 within the next timer

tick. The order in the timer queue is 3,2,1,6,5,4.

Proceed as follows to ensure that all timer calls are executed within the same timer tick.

1. Set the task to maximum system priority to prevent other tasks from interrupting it.

2. Pause with 0 for synchronization to the next timer tick.

3. Output the timeout requests.

4. Reset task priority to its original value.

Verify that processing is completed within one timer tick.

2.1.2

Short description of the RMOS3 functions

Overview

The RMOS3 functions form the interface to the operating system and enable access to the

operating system utilities. For a detailed description of these functions, refer to Reference

Manual Part III.

System startup

RmCreateOS

Adapt dynamic to static resource IDs

RmInitOS

Pass start addresses of the subprograms for hardware operation

RmResetOS

Start operating system configuration

RmRunOS

Initialize all driver units

RmSetOS

Run system configuration

RmSetPutcharProc

Publish the address of function putchar()

RmSetSMRCount

Set SMR limit

RmSetSVC

Initialize SVC table

Function groups

2.1 RMOS3 functions

RMOS3 V3.50 Reference Manual Part II

18 Programming Manual, 07/2012, A5E03692298-01

Memory

RmAlloc

Allocate HEAP memory area

RmCreateMemPool

Create dynamic memory pool

RmDeleteMemPool

Delete dynamic memory pool

RmExclude

Reserve memory pool area

RmFree

Release memory area for specific task

RmFreeAll

Release all memory areas for specific tasks

RmGetSize

Get memory area length

RmMemPoolAlloc

Allocate memory area from memory pool

RmReAlloc

Change memory area size

RmGetMemPoolInfo

Get information on memory pool

Descriptors

RmChangeDescriptor

Change descriptor

RmChangeDescriptorAccess

Change descriptor access rights

RmCreateDescriptor

Create descriptor

RmDeleteDescriptor

Delete descriptor

RmGetLinAddress

Get linear address from pointer

RmGetPhysAddress

Get physical address of a memory area

RmMapMemory

Address physical memory

Task control

RmActivateTask

Activate task

RmBindTask

Bind task to core

RmCreateTask

Registers static or reloadable task with the operating system

RmCreateChildTask

Registers static or reloadable task with the operating system

RmCreateTaskEx

Define dynamic task

RmDeleteTask

Delete dynamic task

RmDisableScheduler

Disable scheduler

RmEnableScheduler

Enable scheduler

RmEndTask

End task

RmGetBindTaskInfo

Get task binding information

RmGetTaskID

Get task ID

RmGetTaskInfo

Get task information

RmGetTaskPriority

Get task priority

RmGetTaskState

Get task state

RmKillTask

Set task to DORMANT or NON-EXISTENT state

RmPauseTask

Wait for expiration of time interval

Function groups

2.1 RMOS3 functions

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 19

RmQueueStartTask

Add task start request to queue. The task is

started as soon as it is in DORMANT state.

RmRestartTask

End and then restart the task on expiration of the time interval.

RmResumeTask

Terminate interval that was initiated with RmSuspendTask or

RmPauseTask

RmSetTaskPriority

Change task priority

RmStartTask

Task start request for tasks in DORMANT state.

RmSuspendTask

Set task to BLOCKED state

Resources

RmCatalog

Enter resource in resource catalog

RmGetEntry

Find catalog entry

RmGetName

Search catalog for entry

RmList

List catalog entries

RmUncatalog

Remove resource from catalog

Messages

RmCreateMessageQueue

Create message queue

RmDeleteMessageQueue

Clear message queue

RmReadMessage

Fetch message from message queue

RmSendMessage

Add message to message queue

RmSetMessageQueueSize

Set message queue length

Mails

RmCreateMailbox

Define dynamic mailbox

RmDeleteMailbox

Delete dynamic mailbox

RmReceiveMail

Receive mail from local mailbox

RmSendMail

Send mail to local mailbox

RmSendMailCancel

Cancel timer that was started with RmSendMailDelayed

RmSendMailDelayed

Transfer mail to mailbox with time-delay

RmSetMailboxSize

Set mailbox limits

Function groups

2.1 RMOS3 functions

RMOS3 V3.50 Reference Manual Part II

20 Programming Manual, 07/2012, A5E03692298-01

Flags

RmCreateFlagGrp

Define dynamic flag group

RmDeleteFlagGrp

Delete dynamic flag group

RmGetFlag

Test event flag

RmResetFlag

Reset event flag

RmResetLocalFlag

Reset local event flag

RmSetFlag

Set event flag

RmSetFlagDelayed

Set event flag on expiration of an interval

RmSetLocalFlag

Set local event flag

Semaphores

RmCreateBinSemaphore

Define dynamic semaphore

RmDeleteBinSemaphore

Delete dynamic semaphore

RmReleaseBinSemaphore

Reset semaphore

RmGetBinSemaphore

Test and set semaphore

SpinLocks

RmInitSpinLock

Initialize SpinLock

RmGetSpinLock

Request SpinLock

RmGetSpinLockIRQ

Request SpinLock and disable interrupts

RmReleaseSpinLock

Release SpinLock

RmReleaseSpinLockIRQ

Release SpinLock and enable interrupts

Time management

RmSetSystemTime

Set date and time

RmGetSystemTime

Transfer date and time from the system

RmSetHWClockTime

Set date and HW clock

RmGetHWClockTime

Transfer date and HW clock

RmGetAbsTime

Transfer date and absolute time from the system

RmGetSystemPeriod

Query system clock rate

Function groups

2.1 RMOS3 functions

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 21

Fast cycle times

RmInitFastTick

Initialize fast cycle with time pattern shorter than one millisecond

RmRemoveFastTick

Remove fast cycle

RmInitFastTask

Start task in fast cycle

RmRemoveFastTask

Remove task from fast cycle

HPET functions

RmInitHPET

Initialize function for reading HPET timer 0

RmGetTimeHPET0

Read current counter of HPET timer 0

RmGetPeriodHPET0

Query period of HPET timer 0

Drivers

RmCreateDriver

RmCreateUnit

RmIO

Request I/O operation

RmResumeDriver

Define new device driver

RmSuspendDriver

Suspend device driver (set to BLOCKED state)

System

RmDecode

Decode RMOS3 error number

RmGetSysB

Read System Control Block

Interrupt handlers

RmGetIntHandler

Read interrupt handler

RmReserveInterrupt

Reserve interrupt

RmRestoreIntHandler

Restore DI interrupt handler in GNU

RmSetIntDIHandler

Set DI interrupt handler

RmSetIntISHandler

Set S or I interrupt handler

RmSetIntTaskHandler

Set task start by interrupt handler

RmSetIntMailboxHandler

Set mailbox interrupt handler

RmSetDeviceHandler

Create driver interrupt handler

RmSetIntDefHandler

Install default interrupt handler

Effective only at system startup

Function groups

2.1 RMOS3 functions

RMOS3 V3.50 Reference Manual Part II

22 Programming Manual, 07/2012, A5E03692298-01

Interrupt handlers on the PCI bus

RmPciSearchFunction

Scan the PCI bus for PCI devices (vendor and device ID)

RmPciSearchSubFunction

Scan the PCI bus for PCI devices and their subsystem IDs (vendor

and device ID)

RmIntShSrv

Initialize Shared Interrupt Server

RmInitShIntClient

Initialize Shared Interrupt Client

RmSetShIntISHandler1

Install Shared Interrupt Handler in compatibility mode

RmSetShIntISHandler2

Install Shared Interrupt Handler in fast mode

RmClrShIntISHandler

Delete Shared Interrupt Handler

Miscellaneous

RmHookException

Hook callback function that is called on exception

RmSetProfilerPoint

Set orientation points in the profiler for "Task Activity" measurement

Function groups

2.1 RMOS3 functions

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 23

2.1.3

Configuration functions

Overview

In addition to general information, these functions offer the possibility of performing a task-

/driver-/block-specific configuration. For a description of these functions, refer to Reference

Manual Part IV.

RcEOIProcPC

EOI routine for PC–compatible modules

RcGetCMOSDateTime

Read date and time from the CMOS clock (PC)

RcGetCMOSSize

Read length of RAM from CMOS RAM (PC)

RcDummyGetClock

Dummy function

RcGetFloppyType

Read type and ID of floppy drives from CMOS RAM

RcGetHardDiskType

Read HDD type from CMOS RAM

RcRAMSize

Configure RAM size

RcInit3964

RcInit3964r8250

RcInit3964r8530

RcInit3964rCOM1

RcInit3964rCOM2

RcInit8254

Initialize 8254 timer

RcInit8259A

Initialize 8259A interrupt controller

RcInitByt

RcInitByt8250

RcInitByt8251

RcInitByt8255

RcInitByt8530

RcInitBytCOM1

RcInitBytCOM2

RcInitBytEga

RcInitBytLPT1

RcInitBytLPT2

RcInitCLIDispatcher

Create dispatcher task for debugger and CLI

RcInitCrt

RcInitCrt8250

RcInitCrtCOM1

RcInitCrtCOM2

RcInitDEBDispatcher

Create dispatcher task without CLI

RcInitDebugger

Create debugger

RcInitEmul

Initialize co-processor emulator

RcInitErrorLogger

Create error logger task

RcInitFd0

RcInitHd0

Function groups

2.1 RMOS3 functions

RMOS3 V3.50 Reference Manual Part II

24 Programming Manual, 07/2012, A5E03692298-01

RcInitHsfs

Allocate resources for HSFS

RcInitNPX

Initialize co-processor

RcInitPasspoint8250

Initialize 8250 block

RcInitPasspoint8251

Initialize 8251 block

RcInitPasspoint8530

Initialize 8530 block

RcInitPasspointEga

Initialize EGA adapter

RcInitPICPC

Initialize interrupt controller on PC hardware

RcInitRamdisk

RcInitRamdisk32

RcInitRemoteTask

Create remote task

RcInitReporter

Create reporter task

RcInitReporterX

Create ReporterX task

RcInitTimerPC

Initialize 8254 timer on PC hardware

RcInitUserTask

Create user task

RcPutchar8250COM1

Output character to 8250 block (COM1)

RcPutchar8250COM2

Output character to 8250 block (COM2)

RcPutchar8251

Output character to 8251 block

RcPutchar8530

Output character to 8530 block

RcPutcharEga

Output character to EGA adapter

RcScanRAMSize

Query RAM length (with memory test)

RcSetCMOSDateTime

Set date and time of the CMOS clock (PC)

RcSetDummyDateTime

Dummy function

RcSetFloppyType

Set type and ID of floppy drives in CMOS RAM (PC)

Function groups

2.1 RMOS3 functions

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 25

2.1.4 Miscellaneous functions

Overview

This chapter describes special functions. Corresponding information is available in

Reference Manual Part IV.

Task start parameters

get2ndparm Read task start parameter EBX

getparm Read task start parameter as pointer

getdword Read task start parameter as long value

Task operations

stl_load Load task

stl_free De-allocate task

HDD functions

x_hd_init Integration of one or several HD partitions into the HSFS

System functions for BUSY task

x_bu_init Initialize BUSY task

x_bu_get Query average system idle time in percent

Function groups

2.2 CLI functions

RMOS3 V3.50 Reference Manual Part II

26 Programming Manual, 07/2012, A5E03692298-01

2.2

CLI functions

2.2.1

Startup code for C programs

Initialization

At the jump to the loaded program, the CLI performs the following actions:

● Register task with xinitt as task using CRUN support.

● Redirect stdin, stdout or stderr , if necessary.

● Disassemble the command line and convert to argc/argv format.

The startup code is executed on completion. _FAR is defined in the RMCOMP.H file.

2.2.2

Problems when aborting a program

A program is aborted by entering <CTRL>+<C> or executing the CANCEL command.

The task immediately jumps to CRUN function exit, regardless of its current activity.

Abortion is only delayed if the task has output a system call (SVC) and is not executed until

this call was completed.

System resources requested by means of CRUN calls are released automatically. This rule

applies both to dynamically allocated memory space and to files opened with fopen or

fduopen.

System resources that were not requested by means of CRUN calls are not released. The

same applies to files opened with HSFS calls, for example.

If the task is currently in possession of a semaphore, this semaphore is not released.

You may install an atexit handler (CRUN function) to release resources allocated directly by

RMOS3 (e.g: semaphores, flags, mailboxes). You can also inhibit abortion for the duration of

a specific time. The x_cli_inhibit_abort CLI function and the inhibitabort CRUN function

are available for this purpose.

Function groups

2.2 CLI functions

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 27

2.2.3

Short description of the CLI functions

RMOS3 programs can utilize the following CLI functions. For information about these

functions, refer to Reference Manual Part IV.

x_cli_cancel

Cancel job started with

x_cli_extended_session or

x_cli_extended_start.

x_cli_cmdexec

Execute CLI command

x_cli_cmdline

Read command line and process any redirection

character that was possibly read

x_cli_errorlevel

Read error level

x_cli_extended_session

Start foreground job

x_cli_extended_start

Start background job

x_cli_get_device

Determines whether a given name is a device

name. If yes, the device and unit numbers will be

returned.

x_cli_inhibit_abort

Inhibit command abortion across a specific

period, or permit it again

x_cli_inhibit_control_c

Inhibit command abortion with <CTRL>+C

x_cli_init_manager

Initialize CLI program manager

x_cli_job_command

Returns a pointer to the command line that was

used to start a job

x_cli_job_command_tail

Returns a pointer to the parameters which were

used to start a job

x_cli_prompt

Returns the current prompt in expanded form.

x_cli_restart_job_pl0

Restart application at privilege level 0

x_cli_session

Start foreground job

x_cli_start

Start background job

x_cli_test_abort

Determines whether an attempt was made to

abort a job with <CTRL>+C or cancel while this

action was inhibited.

x_cli_truename

Convert file name to file name with absolute path

Function groups

2.3 C library functions

RMOS3 V3.50 Reference Manual Part II

28 Programming Manual, 07/2012, A5E03692298-01

2.3

C library functions

2.3.1

Scope of the C library

The C library encompasses functions and macros in accordance with the following

classification criteria or function classes (these function classes are identical to the greater

extent with those mentioned in standard technical references):

● I/O operations, e.g. HDD, terminal, printer, ...

● Character management

● String operations

● Memory operations

● Memory allocation

● Mathematical functions

● Time and date functions

● Control functions

● Error handling

● Miscellaneous functions

2.3.2

Short description of the C library functions

I/O operations

I/O operations form the most extensive function class of the C library . It includes functions

used in C programs to execute I/O operations (also by means of RMOS3 drivers), as well as

functions for verifying/formatting I/O data and for file management. The functions are

declared in the IO.H and STDIO.H header files.

Current Working Directory

The name of a file or directory is specified for certain functions (access, fopen, freopen, open,

remove, rename, unlink and chdir). This name always relates to the task-specific Current

Working Directory (CWD), with each task having a separate CWD. The CWD of a task is not

initialized initially and is set by means of function call chdir.

Function groups

2.3 C library functions

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 29

Rules for file and directory names

● The colon ‘:’ is used as delimiter between the drive name and the file or directory name. It

may be entered as second or third character in the path string and is not allowed in any

other positions. This also implies that you may only use drive names with a length of one

or two letters.

Example: R:TEST

● The ‘\’ and ‘/’ delimit the directory names, or the directory name and file name.

Example: DIR1\DIR2\DATEI

● Path names that begin with a drive name, i.e. with colon ‘

’ as second or third character

(drive name on the left), are absolute path names. The path name is transferred directly

to the HSFS, while the CWD is ignored.

Example:

CWD: B:DEMO.DIR\SOURCE

Path name: A:TEXT\README.TXT

The addressed README.TXT file is located in the TEXT directory on drive A.

● Path names that begin with one of the delimiters ‘\’ or ‘

’ are a special form of absolute

path name. In this case, the drive name is copied from the CWD and the path name is

appended. The absolute path name generated in this way is transferred to the HSFS and

the CWD is no longer taken into account.

Requirement: the CWD must already be initialized if you are using this type of path name.

Example:

CWD: B:DEMO.DIR\SOURCE

Path name: \TEXT\README.TXT

The addressed README.TXT file is located in the TEXT directory on drive B.

● A path with "\" or "/" is a further variant that is used to address the root directory of the

drive specified in the CWD. A typical application is the chdir("\") or chdir("/")

command.

● Path names that do not begin with a delimiter (‘\’ or ‘

’) or drive name represent relative

path names that relate to the CWD.

Example:

CWD: B:DEMO.DIR\SOURCE

Path name: IO\IOTEST.C

The addressed IOTEST.C is located in directory DEMO.DIR\SOURCE\IO on drive B.

Function groups

2.3 C library functions

RMOS3 V3.50 Reference Manual Part II

30 Programming Manual, 07/2012, A5E03692298-01

● Path names beginning with "

<delimiter>" (e.g. "

..\

") are special variants of relative path

names. Each string of "

<delimiter>" at the beginning of the path returns the level by one

step to the data volume name, starting at the CWD.

Example:

CWD: B:DEMO.DIR\SOURCE

Path name: ..\BIN\IOTEST.386

The addressed IOTEST.386 file is located in directory DEMO.DIR\BIN on drive B.

Example:

CWD: B:DEMO.DIR\SOURCE

Path name: ..\..\DOC.DIR\IO.TXT

The addressed IO.TXT file is located in directory DOC.DIR on drive B.

The path specification with ".." is a variant. It is used to address the directory that is

closer by one level to the drive name than the CWD. A typical application is the

chdir("..") command.

● You always need to specify absolute path names if the task CWD is not yet initialized.

CRUN calls supported in the FAT16/FAT32 file systems

The file system is adapted to support the use of long file names with the following CRUN

calls:

● fopen

A file can be opened with both the long and the short name.

● rename

Rename supported for files with long or short name.

● unlink

A file can be deleted with both the long and the short name.

● remove

A file can be deleted with both the long and the short name.

● mkdir

A directory can be created with both the long and the short name.

● search

A file can be searched for with both the long and the short name. For searches with long

name, the short name is always written to the DIR_ENTRY structure.

● searchlong

A file can be searched for with both the long and the short name.

● rmdir

A directory can be deleted with both the long and the host name.

Function groups

2.3 C library functions

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 31

Text mode – Binary mode

Whether to open a stream/handle in text or binary mode is specified in the fopen, fduopen,

freopen, fdureopen and open functions. If a stream or handle is opened in text mode, all ‘\n’

(New Line) are converted into ‘\r\n’ (Carriage Return – New Line) for write access, while all

‘\r\n’ (Carriage Return – New Line) strings are converted into ‘\n’ (New Line) for read

operations. No conversion is performed for streams or handles that were opened in binary

mode.

NUL file

You can open a NUL file that exists in the system, without the file actually being physically

present anywhere. Once it is opened, you can use the NUL file to perform all operations that

are also possible with standard files. The difference is that write calls (e.g. fwrite) and read

calls (e.g. fread) in conjunction with the NUL file are terminated immediately without I/O

operations having been performed. All write operations accessing the NUL file are

terminated (return value, errno, errno2, etc.) so that no error is signaled. Read operations to

the NUL file report an EOF (End of File).

The NUL file is addressed if NUL is set for the file or path name (any uppercase/lowercase

combination) (e.g. fopen("NUL", "w")).

File access functions

The following function calls are used to read/write data and to open, close, rename or delete

files.

access

Verify access to file

chdir

Change current working directory

changevib

Change description block of data volume

checkpoint

Save data from (HSFS) intermediate file buffer

chmod

Change file attributes

clearerr

Reset stream error status

Close file

createvib

Create new description block of data volume

dismount

Log off device from HSFS file system

duread

Read character by means of RMOS3 driver

duwrite

Write character by means of RMOS3 driver

fclose

Close stream

fduopen

Open stream to RMOS3 driver

fdureopen

Redirect stream to driver

feof

Query stream status after EOF

ferror

Query stream status after I/O error

fflush

Flush stream buffer

fgetc

Read character from stream

fgetpos

Return current position in file

fgets

Read string from stream

fileno

Determine file descriptor

fopen

Open stream

fprintf

Formatted output to stream

fputc

Write character to stream

Function groups

2.3 C library functions

RMOS3 V3.50 Reference Manual Part II

32 Programming Manual, 07/2012, A5E03692298-01

fputs

Write string to stream

fread

Read data from stream

freopen

Replace file assigned to a stream

fscanf

Formatted input from stream

fseek

Position data pointer in stream

fsetpos

Set current position in file

ftell

Determine data pointer in stream

fwrite

Write data to stream

getc

Read character from stream

getchar

Read character from the standard input

getcwd

Determine current working directory

gets

Read string from stream

getvolumestatus

Get status information of data volume

getw

Read word from stream

lseek

Position data pointer in file

mkdir

Create directory

mount

Mount device in HSFS

open

Open file for read/write access

printf

Formatted output to standard output

putc

Write character to stream

putchar

Write character to standard output

puts

Write string to stream

putw

Write word to stream

read

Read data from file

remap

Format data volume

remove

Remove file

rename

Rename file

rewind

Position data pointer in stream

rmdir

Delete directory

scanf

Formatted input from standard input

Search for files

setbuf

Set stream buffer

setvbuf

Set stream buffer

sprintf

Formatted output to string

sscanf

Formatted input from a string

tmpfile

Create temporary file

tmpnam

Create name for temporary file

ungetc

Write back character to stream

unlink

Formatted output to stream

vfprintf

Formatted output to stream

vprintf

Formatted output to stream

vsprintf

Formatted output to string

write

Write data to file

Function groups

2.3 C library functions

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 33

Character management

Character management contains functions that are used to convert and classify character

types and that are declared in the CTYPE.H header file.

_tolower

Convert characters to lowercase

_toupper

Convert characters to uppercase

isalnum

Specify whether a character is alphanumerical

isalpha

Specify whether a character is alphabetical

isascii

Specify whether a character is an ASCII character

iscntrl

Specify whether a character is an ASCII control character

isdigit

Specify whether a character is a decimal number

isgraph

Specify whether a character is printable

islower

Specify whether a character is a lowercase letter

isprint

Specify whether a character is printable

ispunct

Specify whether a character is a punctuation mark

isspace

Specify whether a character is a whitespace

isupper

Specify whether a character is an uppercase letter

isxdigit

Specify whether a character is a hexadecimal number

toascii

Convert character to integer

tolower

Convert character to lowercase

toupper

Convert character to uppercase

String operations

String operations can be used to verify and edit strings or byte sequences and are declared

in the STRING.H and STDLIB.H header files.

atof

Convert string to double number

atoi

Convert string to integer

atol

Convert string to long integer

strcat

Append string to second string

strchr

Search for character in a string

strcmp

Compare two strings

strcpy

Copy string to second string

strcspn

Compare two strings

strlen

Get string length

strncat

Append string segment to second string

strncmp

Compare two string segments

strncpy

Copy string segment

strpbrk

Compare characters in two strings

strrchr

Search for character in a string

strspn

Compare two strings

strstr

Compare two strings

strtod

Convert string to double number

strtok

Find character unequal to delimiter in string

strtol

Convert string to long integer

strtoul

Convert string to unsigned long integer

Function groups

2.3 C library functions

RMOS3 V3.50 Reference Manual Part II

34 Programming Manual, 07/2012, A5E03692298-01

Memory operations

Memory operations can be used to copy characters and compare or write to memory areas.

and are declared in the STRING.H and MEMORY.H header files.

memccpy

Copy character from source to target

memchr

Find character

memcmp

Compare content of two memory ranges

memcpy

Copy character from source to target

memmove

Copy character from source to target

memset

Pad memory area with characters

Memory allocation

These functions are declared in the MALLOC.H and STDLIB.H header files.

calloc

Request memory space an initialize with 0

free

Release memory

realloc

Change length of memory space

malloc

Request memory space

Mathematical functions

Functions declared in header file STDLIB.H can only be applied to integers, whereas floating

point functions are declared in header file MATH.H.

abs

Calculate absolute value of an integer

acos

Arc cosine

asin

Arc sine

atan

Arc tangent

atan2

Arc tangent of two double numbers

ceil

Round double number

cos

Cosine

cosh

Cosine hyperbolicus

div

Integer division

exp

Exponential function

fabs

Calculate absolute value of double number

floor

Round down a double number

fmod

Determine division remainder from two double numbers

frexp

Split double number

labs

Determine absolute value of long integer

ldexp

Generate double number

Function groups

2.3 C library functions

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 35

ldiv

Long integer division

log

Natural logarithm

log10

Decadic logarithm

matherr

Application-specific error handling

modf

Split double number into integer and fraction

pow

Power function

rand

Generate random integer

sin

Sine

sinh

Sine hyperbolicus

sqrt

Square root function

srand

Set init value for rand

tan

Tangent

tanh

Tangent hyperbolicus

Time and date functions

These functions can be used to adjust time and date information e.g., convert and adjust to

the respective time zone. The functions are declared in header file TIME.H.

asctime

Convert date and time to string

ctime

Convert date and time to string

_ctime32

Convert date and time to string (for

time data beyond January 19, 2038)

difftime

Determine length of period

gmtime

Convert date and time to GMT

_gmtime32

Convert date and time to GMT (for time data beyond January 19, 2038)

localtime

Convert date and time to local time

_localtime32

Convert date and time to local time (for time data beyond January 19,

2038)

mktime

Convert local time

strftime

Output formatted date and time

time

Calculate system time since 01.01.1970, 00:00:00 GMT

_time32

Calculate system time since 01.01.1970, 00:00:00 GMT (for time data

beyond January 19, 2038)

tzset

Set time zones

Control functions

The control functions are required to end tasks and are declared in the STDLIB.H and

TASK.H header files.

abort

End task

assert

Abort task conditionally

atexit

Specify the routines to call on task completion

exit

Clear task and exit with defined state

x_cr_killtsk

Delete task

inhibitabort

Inhibit task abortion by means of CTRL–C (IO.H)

Function groups

2.3 C library functions

RMOS3 V3.50 Reference Manual Part II

36 Programming Manual, 07/2012, A5E03692298-01

Error handling

Along with errno , an additional errno2 macro is available (RMOS3 extension). For more

information, refer to the description of the errno call. The corresponding declarations are

available in header file ERRNO.H.

errno, errno2

Error numbers of system calls and library functions

perror

Ouput CRUN error message

strerror

Get error text

sys_nerr

Number of entries in sys_errlist

sys_errlist

String array of error messages

Miscellaneous functions

Summary of functions that cannot be assigned unambiguously to a class.

bsearch

Find element in sorted table

getenv

Get environment variable

longjmp

Execute non-local jump

putenv

Change or add environment variable

qsort

Sorting function

raise

Trigger signal

setjmp

Set mark for non-local jump

signal

Install exception handling function (signal handler)

sleep

Stop task for a specific time

x_cr_gettaskid

Get ID of the calling task

x_cr_gettaskparam

Determine stdin, stdout, stderr and the task environment

x_cr_initenv

Initialize task environment

x_cr_setexit

Set task-specific exit handler

xinitc

Initialize CRUN

xinitt

Execute task-specific initialization of CRUN

Function groups

2.4 Driver functions

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 37

2.4

Driver functions

2.4.1

Application model

All routines in S state are interpreted as system processes. All system processes are

executed sequentially and terminated automatically. The operating system core provides

system variables and subprograms to support the functions of system processes. These

subprograms support memory allocation, task communication, and the management of

RMOS3 data structures.

These driver functions can only be called by drivers which were linked statically in the

system during system generation.

Figure 2-1 System processes

Note

All subprogram cal

ls in RMOS3 are of the type NEAR, which means that the driver code

must always be available in segment RM3_CODE32.

The corresponding subprogram parameters are passed by means of static transfer variables.

These transfer variables are reserved for system processes only and may not be

manipulated by interrupt handlers in DI or I state. Transfer variables are also used to pass

parameters to driver entry points for handling I/O requests.

Function groups

2.4 Driver functions

RMOS3 V3.50 Reference Manual Part II

38 Programming Manual, 07/2012, A5E03692298-01

2.4.2

Short description of the driver functions

Assembler

_ELIPSE

Transition from DI to I state

X_SYSTATE

Transition from I to S state

X_SYSTATE_SW

Transition from I to S state without EOI

X_XEL

Change from I state to scheduler

X_XEL_SW

Change from I state to scheduler without EOI

Assembler and C

XCATALOG

Enter in the RMOS3 resource catalog

XCHANGEDESC

Change descriptor base and/or limits

XCHANGEDESCACCESS

Change descriptor access byte

XCREATEDESC

Create descriptor

XDELDESC

Delete the descriptor specified by means of selector

XDELTMB

Remove TMB from monitoring list

XDEVDATA

Calculate XDCB and XUCB according to XDEVNUM and XDEVUNIT

XDQTMB

Exclude TMB from the monitoring list without releasing it

XDWORD

Convert the offset address of an RMOS3 data variable to doubleword

address

XERRLOG

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

XEXSYS

Exit the S state (end system process)

XGETSMR

Request system memory block

XHALOC

Allocate pool memory space

XHDALOC

Release memory space

XIODONE

Complete processing of SVC RmIO for type I drivers

XOVER, xjmp_xover

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

XPHYSADR

Determine physical address

XPUTSMR

Return system memory block

XQPIRB

Add active IRB to the queue of a parallel driver

XQSETUNS

Queue start of user task for unexpected interrupts

XQSIRB

Add active IRB to the queue of a serial driver

XQSTRT

Add task start request to queue

XQTMB

Add TMB from monitoring list

XRECV

Receive mail from local mailbox

XREF

Reset event flag

XSEF

Set event flag

XSEND

Send mail to local mailbox

XSETUNS

Start user task for unexpected interrupts

XSYSTEM

Transition from DI to System state

XTEF

Test event flag

XTIMEOUT

Set device timeout (only type II drivers)

Function groups

2.4 Driver functions

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 39

2.4.3

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.

Name

Description

Length

XCIRB

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

6 bytes

XDEVNUM

Current driver ID

1 byte

XDEVUNIT

Current device ID

1 byte

XUCB

Current UCB address

6 bytes

XDCB

Current DCB address

6 bytes

XERRMSG

Error message address

6 bytes

XOFFSET

OFFSET address; general usage

4 bytes

XPOINTER

OFFSET/SEGMENT address; general usage

6 bytes

XSTATUS

Status data to return to the task

8 bytes

XTUNIT

Time interval for timers

1 byte

XTNUM

Number of time intervals for timers

1 byte

XPOOLNUM

Memory pool ID for XHALOC and XHDALOC

1 byte

XBLKLEN

Number of bytes for XHALOC and XHDALOC

4 bytes

XSEQ

Sequential number of current IRB

2 bytes

XSEG

Selector for segment handling

2 bytes

XSEGLIM

Segment limit

4 bytes

XTASK Task ID 2 bytes

XPRIS

Options for priority source

1 byte

XPRIV Priority to use 1 byte

XP1

Parameter 1

4 bytes

XP2

Parameter 2

4 bytes

XGRP

Global event flag ID

1 byte

XFLAGS

Mask for flag group

4 bytes

XBOX

Local mailbox ID

1 byte

XGENB

Byte for general usage

1 byte

XGENW

Word for general usage

2 bytes

XGEND

Dword for general usage

4 bytes

2.4.4

Differences between type I and type II drivers

RMOS3 supports two different interfaces for drivers. Depending on the type of interface

required, this driver is named type I or type II driver. Compared to type I drivers, type II

drivers are more supported by subprograms of the nucleus and are therefore easier to

program. You need to explicitly program nucleus support for type I drivers.

Function groups

2.4 Driver functions

RMOS3 V3.50 Reference Manual Part II

40 Programming Manual, 07/2012, A5E03692298-01

Primary differences between type I and type II drivers include the following:

Handling RmIO parameter

Function

Type I drivers only have one entry point for handling I/O requests and must handle and

execute all functions on their own dependent on the Function parameter.

Type II drivers are provided with an entry point table for handling the functions. Depending

on the Function parameter, the nucleus uses this entry point table to jump to a procedure of

the driver for handling I/O requests pending. The driver jump table starts with function 2,

because function 0 (reserve device) and function 1 (release device) are already implemented

in the operating system kernel. Possible layout of the entry point table for type II drivers for

handling an RmIO SVC:

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 corresponding functions are pending. The nucleus, for example,

directly calls the WRITE_BLK procedure if a request with function code 3 is pending.

Note

The jump table in RMOS3 consists of offset addresses (32

-bit). The code must be available

in segment RM3_CODE32.

Reserving and releasing devices

The reserve and release functions are implemented directly in the operating system kernel

for type II drivers. Only the task that has reserved the device may release it. 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

device by another task is ignored.

Handling timeouts

Type I drivers must completely process timeout events. This gives the programmer more

scope. Although the nucleus handles timeout events at type II drivers, the driver can actually

handle the event by itself.

Status bits

The nucleus sets and resets bit 0 (status) of DCB_STS or UCB_STS (sequential/parallel) for

type II drivers.

Function groups

2.4 Driver functions

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 41

Completing a job

The type I driver terminates an I/O request and must then scan the request queue to initiate

the next execution. This also enables the sharing of devices with another driver (if it is

necessary to implement this property).

The type II driver completes an I/O request by calling a nucleus procedure. This procedure

manages the I/O request queue of the corresponding driver. The driver is reset to the active

state via the entry point table if a further request is pending in the queue.

Subprograms

Both driver interfaces are supported by subprograms. Certain subprograms support only one

interface type.

Function groups

2.4 Driver functions

RMOS3 V3.50 Reference Manual Part II

42 Programming Manual, 07/2012, A5E03692298-01

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 43

Data structures

3.1

RmAbsTimeStruct

Syntax

#include <rmtypes.h>

typedef struct _RmAbsTimeStruct

{

ulong lotime;

ulong hitime;

}RmAbsTimeStruct;

Description

Contains the system time and date (absolute system time) and is used by the RmGetAbsTime

and RmSetAbsTime SVCs.

Field

Type

Meaning

lotime

ulong

Least significant segment of the absolute time

hitime

ulong

Most significant segment of the absolute time

See also

RmGetAbsTime, RmSetAbsTime

Data structures

3.2 RmAsciiTimeStruct

RMOS3 V3.50 Reference Manual Part II

44 Programming Manual, 07/2012, A5E03692298-01

3.2

RmAsciiTimeStruct

Syntax

#include <rmtypes.h>

typedef struct _RmAsciiTimeStruct

{

char day[2]; /* 01 ... 31 (ASCII) */

char delim0; /* '–' */

char month[3];/* JAN ... DEC (ASCII) */

char delim1; /* '–' */

char year[4]; /* 0 ... 9999 (ASCII) */

char blank; /* ' ' */

char hour[2]; /* 0 ... 23 (ASCII) */

char colon0; /* ':' */

char min[2]; /* 0 ... 59 (ASCII) */

char colon1; /* ':' */

char sec[2]; /* 0 ... 59 (ASCII) */

}RmAsciiTimeStruct;

Description

Contains the system time and date (local or global system time) in ASCII format; used by the

RmGetSystemTime and RmSetSystemTime SVCs. The various elements have the value ranges

specified in the comments.

See also

RmGetSystemTime, RmSetSystemTime

Data structures

3.3 RmDCDStruct

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 45

3.3

RmDCDStruct

Syntax

#include <rmtypes.h>

typedef struct _RmDCDStruct

{

struct _RmUCDStruct _NEAR * ucd;

uchar units;

uchar shr;

rmproc init;

rmproc svc;

uchar flags;

uchar fmax;

#if RM3

uchar res[4];

#else

uchar res[2];

#endif

}RmDCDStruct;

Description

The RmDCDStruct structure defines a structure for driver control data

Field

Type

Meaning

ucd Pointer to

RmUCDStruct

UCD address

units

uchar

Reserved

shr

uchar

Device number of a shared device (0FFH=no sharing)

init

rmproc

Address of the driver init routine

svc

rmproc

Address of the RmIO entry point

flags

uchar

Bit

Meaning

0=1

Parallel driver

0=0

Sequential driver

1=1

Type II driver

1=0

Type I driver

2=0

Driver is initialized after system init

2=1

Driver is not initialized after system init and suspended

(in BLOCKED state)

fmax

uchar

Maximum function code of the driver

res[24] uchar Reserved

See also

RmIO

RmUCDHeadStruct (Page 67)

RmUCDStruct (Page 68)

Data structures

3.4 RmEntryStruct

RMOS3 V3.50 Reference Manual Part II

46 Programming Manual, 07/2012, A5E03692298-01

3.4

RmEntryStruct

Syntax

#include <rmtypes.h>

typedef struct _RmEntryStruct

{

uchar slen;

char string[16];

uchar type;

ulong ide;

ushort id;

}RmEntryStruct;

Description

The RmEntryStruct structure is used in SVCs RmList and RmGetEntry to read catalog entries.

Field

Type

Meaning

slen uchar Length of next string.

string

char[16]

String containing a resource name.

type uchar Sets the resource type.

The following values are possible:

Value

Meaning

RM_CATALOG_TASK Task

RM_CATALOG_DEVICE Device driver

(Device)

RM_CATALOG_POOL

Memory pool

RM_CATALOG_SEMAPHORE

Semaphore

RM_CATALOG_EVENTFLAG

Global event flag

RM_CATALOG_CNTRL

Monitored program access

RM_CATALOG_LOCALMAILBOX

Local mailbox

RM_CATALOG_MISC

Reserved

RM_CATALOG_USER

User-defined type

RM_CATALOG_UNIT

Device (Unit)

RM_CATALOG_MESSAGE

Messages

RM_CATALOG_ALL

ide ulong Returns the extended resource ID. The range of values depends

on the type and configured maximum values.

id ushort Specifies the resource ID. The range of values depends on the

type and configured maximum values.

Note

Resource type RM_CATALOG_USER is not reserved for specific RMOS3 resources and can

be used to suit requirements. For example, you could display the availability of specific

library modules by entering the library name and type RM_CATALOG_USER in the catalog.

See also

RmCatalog, RmList, RmGetEntry

Data structures

3.5 RmIntrhandMailStruct

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 47

3.5

RmIntrhandMailStruct

Syntax

#include <rmtypes.h>

typedef struct _RmIntrhandMailStruct

{

uint int_no ;

uint int_vec :8 ;

uint int_kind :1 ;

uint lost_int_overflow :1 ;

#if RM3

uint dummy_2 :22 ;

#else

uint dummy_2 :6 ;

#endif

ushort lost_int;

#if RM3

ushort dummy_3;

#endif

}RmIntrhandMailStruct

Description

SVC RmSetIntMailboxHandler can be used to define interrupt handlers for sending mails to a

mailbox. The RmIntrhandMailStruct structure defines the format of this mail that is saved to

the mailbox after the corresponding interrupt was triggered. The structure consists of

altogether three 23-bit words

Field

Type

Meaning

int_no

uint

Specifies the interrupt number.

int_vec

8-bit

Specifies the associated interrupt vector.

int_kind

1-bit

Identifies the interrupt type:

Value Meaning

Hardware interrupt

Software interrupt

lost_int_

overflow

1-bit This bit is set (= 1) if interrupts were lost.

dummy_2

22 bit

Reserved

lost_int

8-bit

Specifies the number of lost interrupts.

dummy_3

24-bit

Reserved

See also

RmSetIntMailboxHandler

Data structures

3.6 RmIOStatusStruct

RMOS3 V3.50 Reference Manual Part II

48 Programming Manual, 07/2012, A5E03692298-01

3.6

RmIOStatusStruct

Syntax

#include <rmtypes.h>

typedef struct _RmIOStatusStruct

{

char primary;

char secondary;

ushort count;

#if RM3

ushort status3;

ushort status4;

#endif

}RmIOStatusStruct;

Description

The RmIOStatusStruct structure defines a structure to which return values are saved on

completion of I/O requests (RmIO)

Field

Type

Meaning

primary

char

First status byte

secondary

char

Second status byte

count

ushort

Number of bytes transmitted

status3

ushort

Third status word

status4

ushort

Fourth status word

See also

RmIO

Data structures

3.7 RmIRBStruct

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 49

3.7

RmIRBStruct

Syntax

#include <rmtypes.h>

typedef struct _RmIRBStruct

{

struct _RmIRBStruct _NEAR * link;

ushort pri;

struct _RmTCBStruct _NEAR * tcb;

struct _RmUCBStruct _NEAR * ucb;

struct _RmTMBStruct _NEAR * tmb;

uchar rio;

uchar funct;

uchar device;

uchar unit;

uchar grp;

uint flags;

void * status;

#if RMFLAT

ushort status_seg;

#endif

void * bufr;

#if RMFLAT

ushort bufr_seg;

#endif

ushort seq;

}RmIRBStruct;

Description

The RmIRBStruct structure defines a structure for I/O requests (RmIO).

Field

Type

Meaning

link

Pointer to RmIRBStruct

Forward link or 0

pri

ushort

Priority

tcb

Pointer to RmTCBStruct

TCB address of the requesting task

ucb

Pointer to RmUCBStruct

UCB address of the requested device

tmb

Pointer to RmTMBStruct

TMB address of current request

rio

uchar

Start of SDB image

funct

uchar

Function code

device

uchar

Driver ID

unit

uchar

Device ID

grp

uchar

Flag group (always zero)

flags

uint

Flag mask

status

void*

Address of status buffer

status_seg ushort Fill word for FLAT model

bufr

void*

Address of the device-specific parameter list

bufr_seg

ushort

Fill word for FLAT model

seq

ushort

Reserved

See also

RmIO

Data structures

3.8 RmMailboxStruct

RMOS3 V3.50 Reference Manual Part II

50 Programming Manual, 07/2012, A5E03692298-01

3.8

RmMailboxStruct

Syntax

#include <rmtypes.h>

typedef struct _RmMailboxStruct

{

void *adr;

#if RMFLAT

ushort adr_res;

#endif

#if RM3

ushort pqd;

#endif

uint len;

}RmMailboxStruct;

Description

RmMailboxStruct is used for indirect transmission of a message via the mailbox by

transferring the memory address and message length in the mailbox instead of the actual

message.

Field

Type

Meaning

adr

void*

Contains a pointer to the memory address of the message.

adr_res

ushort

Fill word for FLAT model

pad ushort If adr is a FAR pointer it comprises 48 bits. pad is padded to

64 bits.

len

uint

Specifies the message length.

See also

RmSendMail, RmReceiveMail

Data structures

3.9 RmMailIDStruct

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 51

3.9

RmMailIDStruct

Syntax

#include <rmtypes.h>

typedef struct _RmMailIDStruct

{

ulong low;

ulong high;

}RmMailIDStruct;

Description

Field

Type

Meaning

low

ulong

Least significant segment of the mail ID

high

ulong

Most significant segment of the mail ID

See also

RmSendMailCancel, RmSendMailDelayed

Data structures

3.10 RmMemPoolInfoStruct

RMOS3 V3.50 Reference Manual Part II

52 Programming Manual, 07/2012, A5E03692298-01

3.10

RmMemPoolInfoStruct

Syntax

#include <rmtypes.h>

typedef struct _RmMemPoolInfoStruct

{

ulong pool_size;

ulong avail_mem_size;

ulong max_block_size;

ulong reserved[5]

}RmMemPoolInfoStruct;

Description

Return value of function RmGetMemPoolInfo. The return value contains information about the

specified memory pool.

Field

Type

Meaning

pool_size ulong Total length of the memory

avail_mem_size

ulong

Total length of available memory

max_block_size

ulong

Length of the largest memory block (always -1)

See also

RmGetMemPoolInfo

Data structures

3.11 RmSpinLockStruct

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 53

3.11

RmSpinLockStruct

Syntax

#include <misc86.h>

struct _RmSpinLockStruct

{

uchar Spin;

uchar CoreID;

uchar Reserved;

uchar Count;

uint Interruptflags;

} GNU_PACKED;

typedef struct _RmSpinLockStruct RmSpinLockStruct;

Description

Return value of function RmInitSpinLock. Contains information about the initialized SpinLock.

Field

Type

Meaning

Spin

uchar

1, if SpinLock is occupied, 0 if free

CoreID

uchar

Core on which the SpinLock was requested

Reserved

uchar

For internal use

Count uchar Number of times the SpinLock was requested on the same

core

Interruptflags

uint

Flags for the interrupt state

See also

RmInitSpinLock, RmGetSpinLock, RmGetSpinLockIRQ, RmReleaseSpinLock,

RmReleaseSpinLockIRQ

Data structures

3.12 RmSysB

RMOS3 V3.50 Reference Manual Part II

54 Programming Manual, 07/2012, A5E03692298-01

3.12

RmSysB

Syntax

#include <rmtypes.h>

typedef struct _RmSysB

{

uchar version[6];

ushort proctype;

ushort systemtype;

ushort res1;

ulong reserved;

char statname[16];

uchar bootfname[128];

uchar bootnode[6];

uchar bootdrive;

uchar res2;

ulong ram_size;

uint smr_max;

uint smr_used;

uint smr_avail;

uint out_of_smr_count;

#if RM3

ushort fl_er_sel;

ushort fl_rw_sel;

#endif

ushort rate_msec;

ulong rate_usec;

ulong pit_count;

ushort timer_int;

rmproc issue_eoi_entry;

uchar pic_count;

uchar pic_base[8];

uchar pic_mask[8];

#if RM3

uchar res3[3];

#else

uchar fres3[1];

#endif

int (_FAR _FIXED * set_pic_mask) (uint irq);

#if RM3

#if RMFLAT

ushort res4f;

#endif

ushort res4;

#endif

int (_FAR _FIXED * init_pit) (void);

#if RM3

#if RMFLAT

ushort res5f;

#endif

ushort res5;

#endif

int (_FAR _FIXED * set_rtc_entry) (RmTimeStruct*);

#if RM3

#if RMFLAT

ushort res6f;

#endif

ushort res6;

#endif

int (_FAR _FIXED * get_rtc_entry) (RmTimeStruct*);

#if RM3

#if RMFLAT

ushort res7f;

#endif

ushort res7;

Data structures

3.12 RmSysB

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 55

#endif

int (_FAR _FIXED * putchar_entry) (char);

#if RMFLAT

ushort res8f;

#endif

} RmSysB;

Description

The RmSysB structure defines the System Control Blocks (SYSB). SYSB is created in the

data segment of the nucleus. SYSB must be moved to a secure area prior to the booting of a

new system, to enable access to it by the loaded system and to prevent its destruction, for

example, during initialization of the system's data area.

Field

Type

Meaning

version[6]

uchar

RMOS version number

proctype ushort Processor type

The proctype can be logically linked by AND with

different bit patterns to decode the processor

information:

Bit pattern

Single information

0x0F00

CPU type

0x00F0

CPU model (Pentium)

0x000F CPU stepping

(Pentium)

0x8000

FPU available

systemtype ushort RMOS type

Value

Meaning

RMOS2

RMOS3

RMOS for WINDOWS

res1

ushort

Reserved

reserved

ulong

Reserved

statname[16]

char

Station name

bootnode[6]

uchar

LAN address of the boot server

bootfname[128]

uchar

File specification of the load system

Data structures

3.12 RmSysB

RMOS3 V3.50 Reference Manual Part II

56 Programming Manual, 07/2012, A5E03692298-01

Field

Type

Meaning

bootdrive

uchar

RMOS3 boot drive

Value

Meaning

Floppy drive 0

Hard disk 0

Memory card

LAN

EPROM

Boot volume in bootfname

res2

ushort

Reserved

ram_size

ulong

Size of RAM area in bytes

smr_max

uint

Maximum number of SMRs

smr_used

uint

Number of SMRs used

smr_avail

uint

Available number of SMRs

out_of_smr_count uint Specification of the number of times it was not

possible to request new SMR areas

fl_rw_sel ushort FLAT selector for code

fl_rw_sel

ushort

FLAT selector for data

rate_msec

ushort

RMOS3 system clock rate in milliseconds

rate_usec

ulong

RMOS3 system clock rate in microseconds

pit_count

ulong

Number of timer ticks between two timer interrupts

timer_int

ushort

Interrupt number for timer

issue_eoi_entry rmproc Address of the EOI function

pic_count

uchar

Number of PICs

pic_base[8]

uchar

Lowest vector address of PIC 1..8 (1=Master)

pic_mask[8]

uchar

PIC masks for PIC 1..8

res3[3]

uchar

Reserved

res3[1]

uchar

Reserved

set_pic_mask

(pointer to function)

Function for manipulating the PIC mask

res4f

ushort

Reserved

res4

ushort

Reserved

init_pit

(pointer to function)

Function for timer initialization

res5f

ushort

Reserved

res5

ushort

Reserved

set_rtc_entry

(pointer to function)

Function for writing the real-time clock

res6f

ushort

Reserved

res6

ushort

Reserved

get_rtc_entry

(pointer to function)

Function for reading the real-time clock

res7f

ushort

Reserved

res7

ushort

Reserved

put_char_entry

(pointer to function)

Function putchar for nucleus outputs

res8f ushort Reserved

See also

RmGetSysB

Data structures

3.13 RmTaskInfoStruct

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 57

3.13

RmTaskInfoStruct

Syntax

#include <rmtypes.h>

typedef struct _RmTaskInfoStruct

{

uchar pri;

uchar state;

uint*sp_ss;

#if RM3

#if RMFLAT

ushort sp_ss_res;

#endif

longlong rdy_time;

#else

uint rdy_time[3];

#endif

char cpu_id;

char flg;

struct _RmTCDStruct *tcd_ptr;

#if RMFLAT

ushort tcd_ptr_res;

#endif

} RmTaskInfoStruct;

Description

Structure RmTaskInfoStruct defines the task data that SVC RmGetTaskInfo returns

Field

Type

Meaning

pri

uchar

Current task priority

state

uchar

The two least significant bits define the task state

Name

Meaning

RM_DORMANT

Task in DORMANT state.

RM_READY

Task in READY state.

RM_BLOCKED Task in BLOCKED state. The reason is

decoded in the 6 most significant bits of

state, so that state assumes one of the

following values:

RM_STA_EF

Waiting for event flag

RM_STA_SEMA Waiting for semaphore

RM_STA_LOAD

Wait until target task is loaded.

RM_STA_STRT

Waiting for start of the target task

RM_STA_ENDT

Waiting for end of the target task

RM_STA_MSG

Waiting for receipt of message

RM_STA_MSGRCVD

Waiting for receipt of transmitted message

RM_STA_POOL Waiting for allocation of memory pool

space

RM_STA_HLT

Stopped by DEBUGGER

RM_STA_BREAK

Interrupted by DEBUGGER breakpoint

Data structures

3.13 RmTaskInfoStruct

RMOS3 V3.50 Reference Manual Part II

58 Programming Manual, 07/2012, A5E03692298-01

Field

Type

Meaning

RM_STA_PAUSE Waiting for expiration of time interval

(RmPauseTask)

RM_STA_CNTRL

Waiting for completion of an I/O operation

RM_STA_WAIT

Wait for expiration of time interval

RM_STA_ERR0 Runtime error, type 0 (Division by 0

Interrupt)

RM_STA_ERR1 Runtime error, type 1 (Single Step

Interrupt)

RM_STA_ERR2 Runtime error, type 3 (Breakpoint

Interrupt)

RM_STA_ERR3

Runtime error, type 4 (Overflow Interrupt)

RM_STA_ERR4 Runtime error, type 5 (Array Bound

Interrupt)

RM_STA_ERR5

Runtime error, type 6 (Unused Opcode)

RM_STA_ERR6

Runtime error, type 7 (Escape Opcode)

RM_STA_ERR7

Runtime error, type 8 (Double Fault)

RM_STA_ERR8 Runtime error, type 9 (NDP Segment

Overrun)

RM_STA_ERR9 Runtime error,

type 13 (General Protection)

RM_STA_ERR10 Runtime error, type 16 (Floating Point

Error)

RM_STA_ERR11

Runtime error, type 10 (Invalid TSS)

RM_STA_ERR12 Runtime error, type 11 (Segment Not

Present)

RM_STA_ERR13

Runtime error, type 12 (Stack Fault)

RM_STA_ERR14

Runtime error, type 14 (Page Fault)

RM_STA_ERR15

Runtime error, type 17 (Alignment Check)

RM_STA_LOOK

Wait for catalog entry

RM_STA_KEND End of task with SVC RmKillTask (e.g. on

completion of the current I/O operation)

RM_STA_KDEL Delete task with SVC RmKillTask (e.g. on

completion of the current I/O operation)

RUNNING

Task in RUNNING state.

sp_ss

uint

Pointer to current stack pointer address

sp_ss_res

ushort

Fill word for FLAT model

rdy_time

ulong

Time of last change of the task to READY state

cpu_id

char

Reserved, must be 0

flg char Task flags (Bits 7...0)

tcd_ptr Pointer to

RmTCDStruct

TCD address

tcd_ptr_res

ushort

Fill word for FLAT model

Data structures

3.14 RmTCDStruct

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 59

3.14

RmTCDStruct

Syntax

#include <rmtypes.h>

typedef struct _RmTCDStruct

{

uint eax;

uint ebx;

ushort ds;

ushort es;

char *stck;

#if RMFLAT

ushort stck_res;

#endif

rmfarproc task;

#if RMFLAT

ushort task_res;

#endif

#if RM3

char *load;

#if RMFLAT

ushort load_res;

#endif /* RMFLAT */

#else

uint efg[2];

#endif /* RM3 */

ushort time;

uchar ovpri;

uchar bpri;

uchar inpri;

uchar pid;

ushort flags;

ushort rr_ticks;

#if RM3

uint efg[2];

#endif

#if RM3

uchar reserve[4];

#else

uchar reserve[2];

#endif

}RmTCDStruct;

Description

Structure RmTCDStruct defines the TCD (Task Control Data) of an RMOS3 task. TCD

contains the constants that the operating system needs to manage a task. TCDs for static

tasks are configured using the RcInitUserTask functions and published to the system. TCDs

for dynamic tasks are published to the system by means of SVC RmCreateTaskEx . An

application may also receive a pointer to the TCD of a task by calling SVC RmGetTaskInfo.

Meaning of the fields of the structure:

Data structures

3.14 RmTCDStruct

RMOS3 V3.50 Reference Manual Part II

60 Programming Manual, 07/2012, A5E03692298-01

Field

Type

Meaning

eax

uint

Value transferred on the stack at task start.

ebx

uint

Value transferred in the EBX register at task start.

ushort

Returns the length of the data segment in bytes.

ushort

The ES register of the task is initialized with this value.

stck char * Bit RM_TFL_STK=0 in the flags field means that stck is a

pointer to the stack of the task. If RM_TFL_STK is set, stck

returns the stack length in bytes.

stck_res

ushort

Fill word for FLAT model

task

rmfarproc

Pointer to the task start address.

load char * Address of the load descriptor string for reloadable task,

otherwise (char *) 0.

load_res

ushort

Fill word for FLAT model

efg

uint

Local event flag group.

time ushort Time unit for timeout of the runtime-dependent priority control

(see RM_TFL_OVPRI in the flags field). The time interval is

calculated based on ?? * time. The following values are

possible:

Symbolic name

Time unit

RM_TCD_MSEC_1 00 1 ms

RM_TCD_MSEC_10

10 ms

RM_TCD_MSEC_100

100 ms

RM_TCD_SEC

1 s

RM_TCD_SEC_10

10 s

RM_TCD_MIN

1 min

RM_TCD_MIN_10

10 min

HOUR

1 h

*) value (decimal) to enter for ??

ovpri uchar The task priority is incremented by this value if runtime-

dependent priority control is activated (see RM_TFL_OVPRI in

the flags field) and the timeout has expired. Must be initialized

with 0 if RM_TFL_OVPRI is not set

bpri uchar Limit up to which the runtime-dependent priority control (see

RM_TFL_OVPRI in the flags field) increments the task priority.

Must be initialized with 0 if RM_TFL_OVPRI is not set

inpri

uchar

Specifies the priority of task start.

pid

uchar

Reserved, must be 0

Data structures

3.14 RmTCDStruct

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 61

Field

Type

Meaning

flags ushort Specifies further task properties. These properties can be

combined with the help of the bit-oriented OR operator |. flags

can be a combination of the following values (all other values re

reserved; the corresponding bits must be 0):

Symbol. Name

Meaning

RM_TFL_NPX Must be set if the task uses the

numerical co-processor.

RM_TFL_

NOHLT

The task cannot be stopped by other

tasks.

RM_TFL_

OVPRI

Activates runtime-dependent priority

control. If this bit is set and the task is

still in READY or RUNNING state on

expiration of the timeout interval

specified in ?? * time, the priority is

incremented by the count of ovpri ,

provided the bpri limit was not yet

reached. The timeout is retriggered at

the task start, on expiration of the

timeout after an increase of the priority

level, and by the call of SVC

RmSetTaskPriority.

RM_TFL_STK Specifies that RMOS3 automatically

allocates system HEAP memory space

to the task stack.

RM_TFL_DS Specifies that RMOS3 automatically

allocates system HEAP memory space

to the data segment of the task.

rr_ticks ushort Task-specific Round–Robin counter, if the ROUND_ROBIN is

defined as RM_RR_TASK in the RMCONF.C file or RmSetOS

was called with RM_RR_TASK as second parameter.

reserve[4]

uchar

4 reserved bytes.

See also

RmCreateTask, RmGetTaskInfo

Data structures

3.15 RmTimeStruct

RMOS3 V3.50 Reference Manual Part II

62 Programming Manual, 07/2012, A5E03692298-01

3.15

RmTimeStruct

Syntax

#include <rmtypes.h>

typedef struct _RmTimeStruct

{

uchar day;

uchar month;

ushort year;

uchar hours;

uchar minutes;

uchar seconds

}RmTimeStruct;

Description

Contains the system time and date (global system time) and is used by the RmGetHWTime and

RmSetHWTime SVCs.

Field

Type

Meaning

day

uchar

Tag

month

uchar

Month

year

ushort

Year

hours

uchar

Hours

minutes uchar Minutes

seconds

uchar

Seconds

See also

RmGetHWTime, RmSetHWTime

Data structures

3.16 RmTMBStruct

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 63

3.16

RmTMBStruct

Syntax

#include <rmtypes.h>

typedef struct _RmTMBStruct

{

/* *** Common part *** */

struct _RmTMBStruct _NEAR * link;

uint ltime;

uint htime;

uchar type;

union

{

/* *** Type 1 *** */

struct

{

uchar res;

struct _RmUCBStruct _NEAR * ucb;

void * sadr

#if RMFLAT

void * sadr_seg

#endif

} type_1;

/* *** Type 2 *** */

struct

{

uchar res;

struct _RmTCBStruct _NEAR * tcb;

} type_2;

/* *** Type 3 *** */

struct

{

uchar efgrp;

struct _RmTCBStruct _NEAR * tcb;

uint efmask;

} type_3;

/* *** Type 4 *** */

struct

{

uchar res;

struct _RmTCBStruct _NEAR * tcb;

} type_4;

/* *** Type 5 *** */

struct

{

uchar res;

struct _RmTCBStruct _NEAR * tcb;

uchar ovpri

uchar bpri

uchar ovtime

} type_5;

/* *** Type 6 *** */

struct

{

uchar res;

struct _RmTCBStruct _NEAR * tcb;

uint swb;

uint sem;

} type_6;

Data structures

3.16 RmTMBStruct

RMOS3 V3.50 Reference Manual Part II

64 Programming Manual, 07/2012, A5E03692298-01

/* *** Type 7 *** */

struct

{

uchar res;

struct _RmIRBStruct _NEAR * irb;

} type_7;

/* *** Type 8 *** */

struct

{

uchar res;

uint tjt;

ushort svc;

uint qh;

uint wb;

} type_8;

/* *** Type 9 *** */

struct

{

uchar res[3];

uint alarm;

ushort tib;

} type_9;

} utmb;

}RmTMBStruct

Description

Structure RmTMBStruct defines a structure for timer monitoring blocks

Field

Type

Meaning

link Pointer to

RmTMBStruct

Forward link or 0

ltime

uint

Least significant DWORD of the absolute time

htime

uint

Most significant DWORD of the absolute time

type uchar

TMB type:

Value

Meaning

Driver or tod timeout

Task pause timeout

Event flag

Task restart timer

Override priority timer

Reserved

SVC timeout

Message delay

TMB type 1

Field

Type

Meaning

res

uchar

Reserved

ucb Pointer to

RmUCBStruct

UCB address

sadr

void*

Address of the timeout routine

sadr_seg

ushort

Fill word for FLAT model

Data structures

3.16 RmTMBStruct

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 65

TMB type 2

Field

Type

Meaning

res

uchar

Reserved

tcb Pointer to

RmTCBStruct

TCB address

TMB type 3

Field

Type

Meaning

res

uchar

Reserved

efgrp

uchar

Event flag group

tcb Pointer to

RmTCBStruct

TCB address

efmsk

uint

Flag mask

TMB type 4

Field

Type

Meaning

res

uchar

Reserved

tcb Pointer to

RmTCBStruct

TCB address

TMB type 5

Field

Type

Meaning

res

uchar

Reserved

tcb Pointer to

RmTCBStruct

TCB address

ovpri

uchar

Priority increment

bpri uchar Priority limit

ovtime

uchar

Priority time interval in ms

TMB type 6

Field

Type

Meaning

res uchar Reserved

tcb Pointer to

RmTCBStruct

TCB address

swb

uint

Address of the semaphore wait block

sem

uint

Semaphore address

Data structures

3.16 RmTMBStruct

RMOS3 V3.50 Reference Manual Part II

66 Programming Manual, 07/2012, A5E03692298-01

TMB type 7

Field

Type

Meaning

res

uchar

Reserved

irb Pointer to

RmIRBStruct

IRB address

TMB type 8

Field

Type

Meaning

res

uchar

Reserved

tjt

uint

Timeout jump table

svc

ushort

Bit-coded SVC

uint

Specific queue header

uint

Specific wait block

TMB type 9

Field

Type

Meaning

res

uchar

Reserved

alarm

uint

Alarm routine called on expiration

tib

uint

Associated TIB

See also

RmTCDStruct (Page 59)

Data structures

3.17 RmUCDHeadStruct

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 67

3.17

RmUCDHeadStruct

Syntax

#include <rmtypes.h>

typedef struct _RmUCDHeadStruct

{

uchar pid;

uchar intno;

rmfarproc intadr;

ushort uns;

}RmUCDHeadStruct;

Description

Structure RmUCDHeadStruct defines the general structure of unit control data.

Field

Type

Meaning

pid

uchar

Reserved

intno

uchar

Interrupt number

intadr

rmfarproc

Interrupt vector address

uns

ushort

Task ID for unexpected interrupt

See also

RmIO, RmUCDStruct (Page 68)

Data structures

3.18 RmUCDStruct

RMOS3 V3.50 Reference Manual Part II

68 Programming Manual, 07/2012, A5E03692298-01

3.18

RmUCDStruct

Syntax

#include <rmtypes.h>

typedef struct _RmUCDStruct

{

uchar pid;

uchar intno;

rmfarproc intadr;

ushort uns;

#if RM3

uchar port[256–10];

#else

uchar port[128–8];

#endif

}RmUCDStruct;

Description

Structure RmUCDStruct defines the general and a specific structure of unit control data.

Field

Type

Meaning

pid

uchar

Reserved

intno

uchar

Interrupt number

intadr

rmfarproc

Interrupt vector address

uns

ushort

Task ID for unexpected interrupt

port [256-10]

uchar

Device-dependent parameter

See also

RmIO, RmDCDStruct (Page 45) , RmUCDHeadStruct (Page 67)

Data structures

3.19 loader_result

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 69

3.19

loader_result

Syntax

#include <load.h>

struct loader_result

{

ushort except_code;

ushort shareable;

char reserved_byte;

ushort reserved_word2;

uint code_seg_offset;

ushort code_seg_base;

uint stack_offset;

ushort stack_seg_base;

uint stack_size;

ushort data_seg_base;

char num_more_slots;

ushort more_slots [1];

ushort reserved_word3;

void _FAR *reserved_pointer1;

};

typedef struct struct loader_result LOADER_RESULT;

Description

Structure loader_result defines the configuration of the loader result segment that the task

loader generates while programs are loaded. The loader result segment contains the

following information about a task loaded with stl_load function

Field

Type

Meaning

except_code ushort Return status of the load operation; contains the same

value as the return status of function stl_load. Since the

loader result segment is only created for successful load

operations, only the 0 value and values in the range from

8100H to 810FH will be set for this segment.

reserved_

word1

ushort Reserved.

reserved_

byte

byte Reserved.

reserved_

word2

ushort Reserved.

code_seg_

offset

uint Instruction pointer (EIP register); init value of the loaded

task.

code_seg_

base

ushort Code segment (CS register); init value of the loaded task.

stack_

offset

uint Stack pointer (SP register); init value of the loaded task.

stack_seg_

base

ushort Stack segment (SS register); init value of the loaded task.

stack_size

uint

Stack size of the loaded task in bytes.

Data structures

3.19 loader_result

RMOS3 V3.50 Reference Manual Part II

70 Programming Manual, 07/2012, A5E03692298-01

Field

Type

Meaning

data_seg_

base

ushort Data segment (DS register); init value of the loaded task.

This value equals 0 if the task does not need an

initialization data segment, i.e. the module contains no

static global nor local data.

num_more_

slots

char Number of segments assigned to the loaded task,

including initialization data/stack/code segments. This

value always equals 255, even if the task was assigned

more than 255 segments.

more_slots [1] ushort Field that contains all segment selectors of the loaded

task. The length of the field is stored in num_more_slots.

reserved_

word3

ushort Reserved.

reserved_

pointer1

void* Reserved.

See also

stl_load

Data structures

3.20 stdstruct

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 71

3.20

stdstruct

Syntax

#include <task.h>

struct std_struct

{

int stdin_dev;

int stdin_unit;

int stdout_dev;

int stdout_unit;

int stderr_dev;

int stderr_unit;

char *stdin_fname;

#if RMFLAT

unsigned short stdin_fill;

#endif

char *stdout_fname;

#if RMFLAT

unsigned short stdout_fill;

#endif

char *stderr_fname;

#if RMFLAT

unsigned short stderr_fill;

#endif

char *tmp_path;

#if RMFLAT

unsigned short tmp_fill;

#endif

};

typedef struct std_struct STDSTRUCT;

Description

Structure STDSTRUCT defines the stdin, stdout I/O channels and error output channel

stderr of a program. A channel can be defined based on the device/unit number

combination, or on the file name

Field

Type

Meaning

stdxx_dev int A value >= 0 determines the number of an I/O driver

(device number). Meaning of values < 0:

Value

Meaning

–1 The file name specified in stdxx_fname is

used. A new file is generated in the case of

stdout and stderr.

stdxx_unit

is not used.

–2 The file name specified in stdxx_fname is

used. In the case of stdout and stderr the

output data is appended to the end of the file,

provided the file already exists. stdxx_unit

is not used.

–3 You should handle this value similar to

stdxx_dev = –2, because the value only has

the following meaning for the interactive CLI

command START: The output file is inherited

from the calling job and cannot be inherited by

other jobs.

stdxx_unit int If the value in stdxx_dev >= 0 , stdxx_unit

determines the number of an I/O device (unit number). If

the value in stdxx_dev < 0, stdxx_unit is insignificant.

Data structures

3.20 stdstruct

RMOS3 V3.50 Reference Manual Part II

72 Programming Manual, 07/2012, A5E03692298-01

Field

Type

Meaning

stdxx_fname char * Points to a file name string. The file of the specified

name is used if the value in stdxx_dev < 0 as described

above.

stdxx_fill

unsigned short

reserved; fill word for FLAT model

tmp_path char * Points to a file name string that defines a file for

temporary data.

tmp_fill

unsigned short

reserved; fill word for FLAT model

Note

The values –2 and –3 in stdxx_dev described above are only relevant to the RMOS3 CLI.

Function x_cr_gettaskparams always returns values stdxx_dev >= –1.

The file name specified in the temp_path field and the name set in function xinitt() for the

temporary file are identical

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 73

Error codes and messages

4.1

Nucleus

The nucleus outputs its error messages to the console that is defined in the configuration as

SYSCON.

Lack of system resources

The following error messages may be output if the system is lacking resources:

*** nuc: <date> <time> no SRBS, SYSTEM HALTED

The operating system is out of system request blocks (SRB).

*** nuc: <date> <time> no SMRS, SYSTEM HALTED

The operating system is out of system memory blocks (SMR) (e.g. driver requesting SMR).

*** nuc: <date> <time> SMRS increased

The nucleus has added 50 system memory blocks (SMR).

*** nuc: <date> <time> SMRS reached 0

Could not increase the number of SMRs; the SVC was delayed. This state only develops if

no memory space is available in the heap, or the number of SMRS was limited with an

RmSetSMRCount call. Only the tasks requesting the SMRS, e.g. by means of SVCs, will be

blocked. Other tasks are continued, even those of lower priority. The blocked tasks are

resumed as soon as SMRs are available again.

Exception interrupt handler

The exception interrupt handler logs the exceptions of the 80386/80486 or Pentium

processors, as well as unexpected interrupts.

The first line in the log output for processor exception interrupts defines the time and type of

interrupt. In RMOS3, the third line returns the error code that the processor has written to the

stack for exception interrupts 8, 10, 11, 12, 13, 14 and 17. The fourth line returns details

about the "triggering source". The next lines show the current register values. The decoded

flag register is displayed in the last line.

Error codes and messages

4.1 Nucleus

RMOS3 V3.50 Reference Manual Part II

74 Programming Manual, 07/2012, A5E03692298-01

The following example shows the output for an exception interrupt that was triggered by a

task in A state.

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

The third line is changed as follows if the exception interrupt was triggered by an interrupt

handler routine in I state:

caused by interrupt handler in i state, SYSTEM HALTED

The third line is output as follows if the exception interrupt was triggered by an interrupt

handler routine in S state:

caused by interrupt handler in s state, SYSTEM HALTED

The exception interrupt handler stops the system in both of the latter situations.

<CoreID> specifies the ID of the core on which the exception has occurred.

<Exception text> depends on the exception interrupt and is representative for the following

strings:

INT–NUM

STRING

INT 0:

DIVIDE ERROR AT ADDRESS:

INT 1:

DEBUG EXCEPTION NEAR ADDRESS:

INT 3:

BREAKPOINT EXCEPTION NEAR ADDRESS:

INT 4:

OVERFLOW EXCEPTION NEAR ADDRESS:

INT 5:

BOUNDS CHECK NEAR ADDRESS:

INT 6:

INVALID OPCODE AT ADDRESS:

INT 7:

NO COPROCESSOR AVAILABLE AT ADDRESS:

INT 8:

DOUBLE FAULT EXCEPTION AT ADDRESS:

INT 9:

NPX SEGMENT OVERRUN NEAR ADDRESS:

INT 10:

INVALID TSS AT ADDRESS:

INT 11:

SEGMENT NOT PRESENT AT ADDRESS:

INT 12:

STACK FAULT AT ADDRESS:

INT 13:

GENERAL PROTECTION AT ADDRESS:

INT 14:

PAGE FAULT AT ADDRESS:

INT 16:

FLOATING–POINT ERROR NEAR ADDRESS:

INT 17:

ALIGNMENT CHECK NEAR ADDRESS:

AT ADDRESS or NEAR ADDRESS is output, depending on whether the EIP register contains the

address of the triggering or of the next command after the exception interrupt.

Error codes and messages

4.1 Nucleus

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 75

NMI (Non-Maskable Interrupt)

The following string is output for an NMI (INT 2):

*** nuc-<CoreID>: <date> <time> NMI INTERRUPT

Unexpected interrupts

Unexpected interrupts trigger the output of the following message:

*** nuc-<CoreID>: <date> <time> UNEXPECTED INTERRUPT

Extending the interrupt handler for unexpected interrupts

You have the option of including the interrupt number of the unexpected interrupt in the

output message. For this purpose, a call of RcInitExtDefHandler() must be output in the

initialization task (InitTask()).

*** nuc-<CoreID>: <date> <time> UNEXPECTED INTERRUPT 0xXX

XX defines the interrupt number.

Error codes and messages

4.2 Error codes of the RMOS3 API calls

RMOS3 V3.50 Reference Manual Part II

76 Programming Manual, 07/2012, A5E03692298-01

4.2

Error codes of the RMOS3 API calls

Return values

Calls of the RMOS3 API may fail under specific circumstances. For this reason, all functions

of the RMOS3 API return

error codes

as return value from which you can derive the

successful or unsuccessful execution of functions. The return value is of data type

int

Return value

RM_OK

(=0) signals successful execution of RMOS3 API calls.

RM_OK:

No error.

Certain calls of the RMOS3 API return values that do not signal an error and are used

instead to output a message to the calling instance. These messages are always output as

negative

integer value ( < 0 ).

Failure of RMOS3 API calls return error codes with true

positive

( > 0 ) integer value.

Overview: Messages

The following return values are no error numbers; instead, they represent messages and

have negative values.

RM_ENTRY_REMOVED: ( -263 )

Entry was successfully removed from the catalog.

RM_ERROR_OUT_OF_RANGE: ( -265 )

Invalid error number

RM_FLAG_ALREADY_SET: ( -258 )

A flag was already set.

RM_FLAG_RESET: ( -260 )

A flag was reset.

RM_FLAG_SET: ( -259 )

A flag was set.

RM_PRI_NOT_CHANGED: ( -261 )

Priority was not changed.

RM_TASK_RESUMED: ( -256 )

Task was resumed.

RM_TASK_WAITING: ( -262 )

Task had to wait for execution (in WAIT mode).

Error codes and messages

4.2 Error codes of the RMOS3 API calls

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 77

Overview: Error codes

The following listing contains all possible error codes returned by RMOS3 API calls.

RM_ALL_DEBUGREGISTERS_USED: ( 45 )

All debug registers are in use.

RM_BOUND_REACHED: ( 27 )

The limit entered with RmSetMailboxSize was exceeded.

RM_BREAKPOINT_ALREADY_SET: ( 29 )

Breakpoint was already set for the specified address.

RM_BREAKPOINT_ID_ALREADY_USED: ( 28 )

The specified breakpoint ID was already used.

RM_CATALOG_EXCEEDED: ( 100 )

The configurable number of catalog entries was exceeded.

RM_GDT_FULL: ( 9 )

No more GDT entries available.

RM_GOT_TIMEOUT: ( 4 )

RMOS3 API call aborted on expiration of the specified timeout period.

RM_INVALID_CFG_STATE: ( 52 )

Invalid configuration state

RM_INVALID_FUNCTION: ( 44 )

The function number transferred is invalid or not supported.

RM_INVALID_ID: ( 36 )

Transferred ID is invalid.

RM_INVALID_INTERRUPT_NUMBER: ( 56 )

Interrupt number was not in the valid range (0-255).

RM_INVALID_IRQ_NUMBER: ( 41 )

An IRQ number was used for an undefined PIC.

RM_INVALID_MEMORYBLOCK: ( 17 )

An attempt was made to release an invalid memory block.

RM_INVALID_OFFSET: ( 39 )

Offset was not in valid range.

RM_INVALID_POINTER: ( 42 )

A pointer was invalid.

RM_INVALID_POOL_CFG: ( 51 )

Invalid memory pool configuration.

RM_INVALID_SECTION_DECLARATION: ( 62 )

Invalid section declaration.

RM_INVALID_SECTION_NAME: ( 65 )

Invalid section name.

RM_INVALID_SEGMENTLENGTH: ( 6 )

Invalid segment length specified.

Error codes and messages

4.2 Error codes of the RMOS3 API calls

RMOS3 V3.50 Reference Manual Part II

78 Programming Manual, 07/2012, A5E03692298-01

RM_INVALID_SELECTOR: ( 21 )

An invalid selector was used.

RM_INVALID_SIZE: ( 38 )

Invalid size definition.

RM_INVALID_STRING: ( 37 )

Invalid string length.

RM_INVALID_TASK_ENTRY: ( 60 )

Invalid task entry.

RM_INVALID_TASK_STATE: ( 22 )

An invalid RmKillTask call was output.

RM_INVALID_TASK_PL: ( 72 )

Call cannot be executed at privilege level 3.

RM_INVALID_TYPE: ( 35 )

Invalid transfer of parameter (

mode

type

pri_type

, etc.) .

RM_IS_ALREADY_CATALOGED: (47 )

String is already cataloged.

RM_IS_NOT_CATALOGED: ( 48 )

String is not cataloged.

RM_LINE_TOO_LONG: ( 61 )

Line too long.

RM_MEMORY_ALREADY_USED: ( 25 )

Memory block to be reserved is already in use.

RM_NO_EOI: ( 53 )

Missing EOI function definition.

RM_NO_INIT_TIMER: ( 54 )

No timer init function transferred.

RM_NO_MESSAGE: ( 43 )

No message (mail) in mailbox (message queue).

RM_NOT_HALTABLE: ( 46 )

Task could not be stopped.

RM_OUT_OF_FLAGGROUPS: ( 12 )

Configured number of event flags is exceeded.

RM_OUT_OF_MAILBOXES: ( 15 )

Configured number of mailboxes is exceeded.

RM_OUT_OF_MEMORY: ( 3 )

System is out of memory.

RM_OUT_OF_MEMORYPOOLS: ( 13 )

The configured number of memory pools is exceeded.

RM_OUT_OF_SEMAPHORES: ( 16 )

The configured number of semaphores is exceeded

RM_PARAMETER_ERROR: ( 2 )

Invalid call parameters.

Error codes and messages

4.2 Error codes of the RMOS3 API calls

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 79

RM_QUEUE_EXIST: ( 59 )

Message queue already exists.

RM_QUEUE_NOT_EXIST: ( 58 )

No message queue available.

RM_RESOURCE_BUSY: ( 18 )

The resource to be deleted is busy.

RM_RESOURCE_NOT_AVAILABLE: ( 23 )

The requested resource is unavailable.

RM_STATEMENT_OUTSIDE_SECTION: ( 64 )

Statement is outside the valid section.

RM_SVC_NOT_CONFIGURED: ( 33 )

An attempt was made to execute a non-configured RMOS3 API call. You can identify the

respective RMOS3 API call based on the data output by the RMOS3 exception handler.

RM_SYNTAX_ERROR: ( 55 )

Syntax Error

RM_SYSTEMERROR: ( 1 )

Missing initialization

RM_TASK_DORMANT: ( 7 )

Task is in DORMANT state.

RM_TASK_KILLED: ( 49 )

Task was deleted with the RMOS3 API call RmKillTask.

RM_TASK_NOT_DORMANT: ( 20 )

An attempt was made to delete or start a task that was not in DORMANT state.

RM_TASK_NOT_IN_BP_CONTEXT: ( 31 )

Task was not interrupted by a breakpoint.

RM_TASK_NOT_IN_RTE_HALT: ( 32 )

Task was not interrupted by a runtime error.

RM_TASK_NOT_PAUSED: ( 26 )

The task to resume by means of RmResumeTask was not stopped with RmPauseTask.

RM_TASK_NOT_READY: ( 30 )

An attempt was made to stop a task that is not in READY state.

RM_TEST_NOT_OK: ( 57 )

Test failed.

RM_UNKNOWN_SECTION: ( 63 )

Unknown section

Error codes and messages

4.3 SVC exception handler

RMOS3 V3.50 Reference Manual Part II

80 Programming Manual, 07/2012, A5E03692298-01

4.3

SVC exception handler

An exception handler that can be configured for the SVC calls logs all SVCs terminated with

error to the system console:

*** nuc-<CoreID>: <date> <time>, svc <name> <status text>

failed: <error number>(<error text>)

Meaning of the abbreviations:

ID of the core at which the error has occurred

<name>

Decoded SVC name, e.g. RmGetFlag

One of the following text strings is inserted, depending on the

system state at the call of the SVC exception handler.

from task: <name> id: 0xXX

during system startup

in monitor mode

in s-state

in i-state

failed

Decoded error text (cf. RmDecode)

If the SVC was called via the old interface, the error message is

output with the following syntax:

0xYY <error number> (<decoded error flags>).

Example

*** nuc-0: 14-FEB-2008 16:20:57, svc RmGetEntry from task: RUN id: 0x29

failed: 36 (Invalid ID)

Error codes and messages

4.4 CLI

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 81

4.4

CLI

The following error codes are used:

● as return value by most of the CLI functions, or

● as exit status of all CLI commands.

The meaning of an error code can be viewed by executing CLI command ERROR. The

values are defined in the CLI.H file.

E_CLI_OK

No error

E_CLI_NOT_RESIDENT

No resident task

E_CLI_FILE_FORMAT

Invalid file format

E_CLI_DYNAMIC_MEM

Out of dynamic memory

E_CLI_INTERNAL_ERROR

Internal error

E_CLI_LTT_FULL

Loaded

task table is full

E_CLI_CJT_FULL

CLI job table is full

E_CLI_CREATE_ERROR

Error when creating a task

E_CLI_START_ERROR

Task start error

E_CLI_DELTSK_ERROR

Error when deleting a task

E_CLI_LT_ACTIVE

The specified loaded task is active

E_CLI_JOB_ACTIVE

The specified CLI job is computing

E_CLI_FILE_NOT_FOUND

File not found

E_CLI_NOT_A_CLI_JOB

Task is not a CLI job

E_CLI_NOT_A_CRUN_JOB

Task is not a CRUN task

E_CLI_NOT_INLINE

Not an Inline command

E_CLI_SYNTAX_ERROR

Syntax error

E_CLI_ENVIRONMENT_FULL

No memory available for new environment

0x8201

0x8202

0x8203

0x8204

0x8205

0x8206

0x8207

0x8208

0x8209

0x820A

0x820B

0x820C

0x820D

0x820E

0x820F

0x8210

0x8211

Error codes and messages

4.4 CLI

RMOS3 V3.50 Reference Manual Part II

82 Programming Manual, 07/2012, A5E03692298-01

E_CLI_NO_COMMAND

Command not available

E_CLI_EOF

End of file

E_CLI_EXIT_STATUS

Exit status (as return value of the EXIT command)

E_CLI_CATALOG_FULL

RMOS3 catalog is full

E_CLI_CREATESEMA_ERROR

Error when creating a semaphore

E_CLI_REDIR_STDIN_FAIL

Error when redirecting stdin

E_CLI_REDIR_STDOUT_FAIL

Error when redirectin

g stdout

E_CLI_REDIR_STDERR_FAIL

Error when redirecting stderr

E_CLI_UNKNOWN_SWITCH

Unknown switch

E_CLI_TOO_MANY_PARAMS

Too many parameters

E_CLI_INVALID_FILENAME

Invalid file name

E_CLI_INVALID_LT_INDEX

Invalid task index

E_CLI_INVALID_JOB_INDEX

valid CLI job number

E_CLI_TOO_FEW_PARAMS

Insufficient number of parameters

E_CLI_FILE_READ_ERROR

File read error

E_CLI_FILE_WRITE_ERROR

File write error

E_CLI_COPY_TO_SELF

Attempt to copy a file to itself

E_CLI_UNEXPECTED_EOF

Unexpected EOF reached

E_CLI_PERMANENT_TASK

Permanent CLI task

E_CLI_NO_PROMPT

Missing prompt definition

E_CLI_JOB_ABORTED

Job was aborted

E_CLI_NOT_A_DEVICE

Not a device name

0x8212

0x8213

0x8214

0x8215

0x8216

0x8217

0x8218

0x8219

0x821A

0x821B

0x821C

0x821D

0x821E

0x821F

0x8220

0x8221

0x8222

0x8223

0x8224

0x8225

0x8226

0x8227

Error codes and messages

4.4 CLI

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 83

E_CLI_MKDIR_FAIL

Creation of directory failed

E_CLI_BATCH_FILE

File is a batch file

E_CLI_NOT_MOUNTED

Volume not mounted

E_CLI_INVALID_WILDCARD

Invalid use of wildcards

E_CLI_NOT_A_DIRECTORY

Not a directory

E_CLI_DIR_OPEN_FAIL

Failed to open directory

E_CLI_FILE_OPEN_FAIL

Failed to open file

E_CLI_FILE_CLOSE_FAIL

Failed to close file

E_CLI_SVC_ERROR

SVC error

E_CLI_DEV_READ_ERROR

Error when reading from device

E_CLI_DEV_WRITE_ERROR

Error when writing to device

E_CLI_IS_A_DIRECTORY

File is a directory

E_CLI_INLINE

Inline CLI command

E_CLI_COMPLETED

CLI job is completed

E_CLI_UNINITIALISED

CLI job was not initialized

E_CLI_OUT_OF_RANGE

Index out of range

E_CLI_NO_SPACE_FOR_NPX

Setup of NPX context failed when creating the task

E_CLI_NO_PARENT_JOB

No parent job

E_CLI_INVALID_VOL_NAME

Invalid volume name

E_CLI_MOUNTED

Volume is mounted

E_CLI_INVALID_DATE_TIME

Invalid date or time format

E_CLI_READ_ONLY

File is read only

0x8228

0x8229

0x822A

0x822B

0x822C

0x822D

0x822E

0x822F

0x8230

0x8231

0x8232

0x8233

0x8234

0x8235

0x8236

0x8237

0x8238

0x8239

0x823A

0x823B

0x823C

0x823D

Error codes and messages

4.5 CRUN

RMOS3 V3.50 Reference Manual Part II

84 Programming Manual, 07/2012, A5E03692298-01

4.5

CRUN

Structure of the error message

CRUN error messages are output as follows:

*** crun: <date> <time>, <error message>

caused by task <taskname> id: <taskid>

<date>

Date at which the error occurred

<time>

Time at which the error occurred

Actual error message

String by which the task th

at has caused the

error is entered in the resource catalog.

ID of the task that was the source of error

Example

*** crun: 20-OCT-94 17:32:20, sin not configured - task aborted

caused by task FLTTEST id: 0x23

The error messages are output by means of the error logger task. If the error logger task is

not configured, the messages are output with RmIO based on the device/unit ID specified in

xinitc .

Error messages

<function>: unknown hsfs return value xxxx

An HSFS call was terminated in CRUN function <function> with (unexpected) error code

xxxx .

<function>: cannot allocate memory

No more memory could be requested for internal operations in CRUN function <function>.

catalog entry "ERRLOG" not found

The ERRLOG entry was not found in the resource catalog. CRUN is therefore prevented

from using the error logger task to output error data and, instead, outputs error messages to

the system console by means of BYT driver.

fclose: cannot delete temporary file

A temporary file created with tmpfile could not be deleted when closing with fclose .

automatic xinitc failed - task aborted

Automatic initialization of CRUN failed (cf. xinitc). The task having caused automatic CRUN

initialization was aborted with exit .

Error codes and messages

4.5 CRUN

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 85

automatic xinitt failed - task aborted

Automatic initialization of a task within CRUN failed (cf. xinitt). The task having caused

automatic initialization was aborted with exit .

illegal function code

xxxx

- task aborted

An invalid function code xxxx was passed to the interface for reloadable tasks. The calling

task was terminated with exit.

reserved function code

xxxx

- task aborted

The reserved function code xxxx was passed to the interface for reloadable tasks. The

calling task was terminated with exit.

<function> not configured - task aborted

The <function> function was called by a reloadable task but is not configured for the

interface for reloadable tasks. The calling task was terminated with exit.

Error codes and messages

4.6 HSFS

RMOS3 V3.50 Reference Manual Part II

86 Programming Manual, 07/2012, A5E03692298-01

4.6

HSFS

Exit codes

Access to the HSFS functions is initiated by means of CRUN call. All possible error values

are also documented with the CRUN calls.

If several user tasks simultaneously output requests to the file management system and a

sufficient number of open files, channel connections , or intermediate buffers is not available,

one of the following additional messages is output to the system console (by means of RmIO):

*** HSF: no FCBS

*** HSF: no CCBS

*** HSF: no BBS!

In this case, you are strongly advised to run a DISMOUNT and reinitialize the file system.

Error codes and messages

4.7 Debugger

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 87

4.7

Debugger

If command input does not conform to the syntax rules, the debugger responds with its

general error message and prompts you to make a new entry.

‘]’ expected!

The square closing bracket is missing in an expression.

All debug registers 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 in use by a breakpoint.

Balance error!

Unbalanced number of opening and closing brackets.

Breakpoint_id in use!

Cannot overwrite the breakpoint number (ID).

Can’t allocate memory!

Cannot allocate sufficient memory space, or none at all.

Can’t monitor end of task!

The debugger could not log on to the operating system for monitoring the end of this task.

Catalog error!

Could not create catalog entry.

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

Command not configured!

The command was not configured.

Divide by zero!

Expression contains a division by zero.

Error starting task!

Task start failed.

File does not exist!

The specified file was not found.

I/O error!

An I/O error has occurred.

Illegal mode!

An attempt was made to execute a command in task mode which is only permitted in monitor

mode or an attempt was made to execute a command in monitor mode which is only

permitted in task mode.

Illegal request!

Command not valid in the current state.

Illegal SVC parameter!

Invalid parameter entry in SVC command.

Error codes and messages

4.7 Debugger

RMOS3 V3.50 Reference Manual Part II

88 Programming Manual, 07/2012, A5E03692298-01

Invalid base!

Invalid number base.

Loader error!

Unknown error in task loader.

Loader result segment not found!

Loader result segment not found for the specified task.

Memory not writable!

An attempt was made to set a hard or soft breakpoint in a ROM area.

Missing operand(s)!

Expression is missing valid operand.

Missing valid SVC_name!

SVC is invalid or missing.

Nesting exceeded, stack full!

Valid nesting depth exceeded in an integer or floating point expression.

No linear/physical address for breakpoints!

It is not allowed to set a linear/physical address for breakpoints.

No such breakpoint!

An attempt was made to delete a non-existing breakpoint.

No such task!

The task ID was not assigned to any task, or the task is not in DORMANT state.

Not a read–write segment!

The segment specified by means of a selector must be of the type READ–WRITE.

Not an execute–read segment!

The segment specified by means of a selector must be of the type EXECUTE–READ.

NPX not allowed!

Invalid co-processor operation.

Offset exceeds segment limit!

Segment limit exceeded.

Page not present

Only with activated paging mechanism:

Entry for this memory block is missing in the page directory, or the corresponding page is

missing.

Step count > 127!

STEP supports execution of a maximum of 127 commands.

Syntax error!

Syntax error in the last command entered.

Task not halted!

A task cannot be resumed with CONT if its current state is DEBUGGER HALTED.

Error codes and messages

4.7 Debugger

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 89

Too many arguments!

Too many arguments in START <task_id> ARGS ... and SVC <SVC_name>.

Type mismatch!

Invalid TYPE set.

Unexpected End-of-file!

Read access to file returned no or an insufficient number of bytes.

Wrong format!

Invalid format found when loading the task with loadtask command. Valid formats include:

EXE, LTL, STL, and PE (Windows NT)

Wrong report table size!

Incorrect size of the resource reporter table.

Wrong selector!

An attempt was made to set a selector/offset pair as address while the selector element is

missing the pointer to a valid entry in a descriptor table.

Error codes and messages

4.8 Resource reporter

RMOS3 V3.50 Reference Manual Part II

90 Programming Manual, 07/2012, A5E03692298-01

4.8

Resource reporter

Can’t allocate memory !

Request for memory failed during data acquisition.

Wrong reporter table size

System out of memory during data acquisition due to insufficient size in the reporter table

configuration.

The message is output by means of the error logger task.

All other possible errors are only reported in the current state of the calling task. No further

error messages are output to the screen.

Error codes and messages

4.9 Task loader stl_load, stl_free

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 91

4.9

Task loader stl_load, stl_free

Error

number

Error message

Meaning

E_LD_OK

Loading successfully completed.

8100H E_LD_NO_REG_INIT Missing register initialization

Missing initial register values (i.e. no start address). The program was

loaded despite of this error.

8101H E_LD_NO_FIXUPS Missing fixup initialization

The STL or PE module loaded is missing relocation information. The

relocation information for the STL module is generated from BND386

with RCONFIGURE option. It is only conditionally available in the STL

module, because other operating systems do not necessarily need it. In

certain scenarios, e.g. when handling programs consisting of only one

segment, this information can also be discarded in RMOS3.

8110H E_LD_FILE_OPEN_FAIL Cannot open file

Program file could not be opened. It probably does not exist.

8111H E_LD_FILE_FORMAT Unknown file format

The file has an unknown format. The format is identified based on the

first byte or word of the file:

STL: 1st word = 0206H

PE: 1st 16–bit word = "M2"

1st 32–bit word of

NEW EXE header = 00004550H,

Magic number of

optional header == 0413

8112H E_LD_UNEXPECTED_EOF Unexpected end of file

Insufficient number of bytes or none at all transferred during read

access to the file.

8113H E_LD_DYNAMIC_MEMORY Insufficient memory

Allocation of sufficient memory failed.

8114H E_LD_ABSOLUTE Module contains absolute segments

The module contains one or more segments which were linked to a

fixed address or is a PE system file.

8115H E_LD_DALOC Loader result segment destroyed

Error at the call of stl_free. Loader result segment was overwritten.

8116H E_LD_NULL_POINTER Null pointer

stl_free was called with null pointer to the loader result segment.

8117H E_LD_OVERLAY Module contains overlays

The module contains an overlay description.

8130H E_LD_PROCESSOR_TYPE Invalid processor type

The processor type specified in the module header is not of the 80386,

80486, or Pentium family.

Error codes and messages

4.9 Task loader stl_load, stl_free

RMOS3 V3.50 Reference Manual Part II

92 Programming Manual, 07/2012, A5E03692298-01

Error

number

Error message

Meaning

8131H E_LD_NON_EXECUTABLE Module not executable

The module header specification is missing the "executable" attribute.

This means that undefined symbols occurred during linking. With PE

format, this can also mean that the program is de-relativized, or an

attempt was made to load a library image.

8132H E_LD_MULTI_LDT Module contains multiple LDTs

The module contains several local descriptor tables (LDTs)

8133H E_LD_GATES_PRESENT Gates present

The DESCRP record contains gate descriptors.

8134H E_LD_NO_STACK_DESC No stack segment

No defined stack segment.

8135H E_LD_NULL_SEG_FIXUP Null segment fixup

The module contains a fixup for a target segment whose selector is not

a code or data segment.

8136H E_LD_BAD_SEG_FIXUP Invalid segment fixup

The module contains a fixup to a target segment with invalid selector.

8137H E_LD_ACCESS_RIGHTS Access rights error

Error at the call of RmChangeDescriptorAccess.

8138H E_LD_ITERATE Iterate data segment has iBSS format

"Iterated Data Segment" with iBSS attribute.

8140H E_LD_FIXUP_FORMAT Invalid fixup

Fixup format is invalid or not supported.

8141H E_LD_USE16 USE16 segment found

Segment with USE16 attribute. RMOS3 only supports segments with

USE32 attribute.

8150H E_LD_SEEK File seek error

File position could not be set accordingly.

8151H E_LD_DLL Module is a DLL

File is a Dynamic Link Library.

8152H E_LD_INVALID_

DESCRIPTOR

Invalid descriptor

Error when converting a segment address to a physical address.

8153H E_LD_TOO_MANY_OBJECTS Too many objects

8158H E_LD_OUT_OF_SEMAPHORES Couldn’t create a semaphore

Generation of the necessary STL_SEMA semaphore for the task loader

failed

8159H E_LD_CATALOG_EXCEEDED Couldn’t catalog semaphore

Could not catalog the necessary STL_SEMA semaphore for the task

loader

Error codes and messages

4.10 LOADRM task loader

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 93

4.10

LOADRM task loader

The LOADRM program can display the following error messages:

LOADRM ERROR: unable to open device <dev_name>

The transmission channel specified as call parameter does not exist.

LOADRM ERROR: unable to set device <dev_name> to raw mode

The transmission channel specified as call parameter cannot be opened in the necessary

way. The RMRS232C.EXE driver, or the serial interface driver SSRS232C.EXE included

with HLLDEB must be used.

LOADRM ERROR: unable to open file <filename>

The file that is to be loaded and is set as call parameter cannot be opened.

LOADRM ERROR: data transmission error

Errors occurred during data transmission.

Internal error causes program abortion!

LOADRM ERROR: file seek error

Errors occurred during data transmission.

Internal error causes program abortion!

The following additional warnings exist:

LOADRM WARNING: min. block size of 1 is used

A block size value less than 1 was specified at the call of LOADRM, block size was set

automatically to the lowest valid value 1.

LOADRM WARNING: max. block size of 256 is used

A block size value greater than 256 was specified at the call of LOADRM, block size was set

automatically to the valid maximum value of 256.

Error codes and messages

4.10 LOADRM task loader

RMOS3 V3.50 Reference Manual Part II

94 Programming Manual, 07/2012, A5E03692298-01

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 95

Functions and configuration of the basic I/O system

5.1

Overview

Programming with SVC

RmIO

The functions of the basic I/O system are programmed using SVC RmIO . The RmIO

parameters specify the drivers to be activated, the function to execute, and so forth. The

RmIO parameters that are identical for all driver calls (bit 7, 6 of Function, DeviceID

UnitID

FlagID

FlagMask

*pState,*pParam), are defined at the SVC RmIO.

This section provides a description of the properties for each driver, of the parameters of

SVC RmIO, as well as of the respective basic structures that are relevant for driver

configuration.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

96 Programming Manual, 07/2012, A5E03692298-01

5.2

BYT driver

5.2.1

Properties

Parallel driver for byte-oriented input/output

The BYT driver serves for simultaneous management of multiple, byte-oriented distributed

I/O devices (parallel driver). The I/O devices (units) can be controlled via parallel

(Centronics) or serial interface (e.g. V.24). Up to 255 devices (units) are supported. Byte-

oriented units include, for example, terminals and printers. it is possible, for example, to

defined custom control characters for terminals. The driver can be customized to suit the

requirements of all standard controllers. The BYT driver can be operated in unrestricted half

duplex mode, i.e. no simultaneous transmission and receive operations, as well as in

restricted duplex mode. Suitability of the BYT driver for host to host communication is limited,

because no data backup procedures or transmission protocols, except XON and XOFF, are

supported. The driver provides several modes to support control characters. The most

important modes include:

● Terminal mode or transparent mode

● Handling XON/XOFF characters

The terminal and transparent modes differ in terms of the handling of terminal/protocol

control characters required for calls of specific read functions of the BYT driver.

EGA/VGA adapter

The BYT driver can also be used to control an EGA/VGA adapter. It supports adapters that

are capable of managing up to four units. The driver functions also offer unrestricted support

for terminals that are not EGA/VGA units (e.g. serial and parallel interfaces). All functions of

the BYT driver can be mapped to an EGA/VGA adapter and to an IBM–compatible keyboard.

6 keyboard types

The BYT driver supports 6 different keyboard layouts: US, UK, French, German, Italian, and

Spanish.

The default RMOS3 nucleus employs a US keyboard emulation. You may always change to

a different keyboard emulation at runtime using the CHGKBD.386 program. You may also

define a country-specific keyboard layout in RMOS.INI.

For more information about special features and configuration parameters, refer to the driver

description in the system manual.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 97

5.2.1.1

Optional EGA functions

Integrating EGA functions

The EGA functions are made available by calling the RcInitBytEga() initialization function in

RMCONF.C. A separate configuration is not necessary.

Four logical units

The BYT with EGA functions also supports IBM–AT/02/03–compatible keyboards and EGA

adapters that are capable of managing four logical units.

All functions of the BYT driver can be mapped to an EGA adapter and to an IBM–AT/02/03–

compatible keyboard.

The code of this "driver version" (executable EGA functions) consists of approximately 14

KB.

The range of applications of the BYT is extended with the following features:

● Function 15 (multifunctional) as additional BYT driver function, but only for EGA adapters.

● Of the 255 supported devices (units), it is possible to control up to four units via EGA

adapter or an attached IBM–AT/02/03–compatible keyboard.

● management of these four "EGA units" as "virtual" units, of which one is displayed on-

screen as "real" unit (with switch option).

The EGA-specific code is suppressed if EGA functions cannot be executed.

No error messages are output at the call of EGA functions; in this case, function 15 (RmIO

call) is a reserved function.

The code of this "driver version" (non-executable EGA functions) consists of approximately 9

KB.

The meaning of function 15 represents the fundamental difference between both "driver

versions":

● BYT driver without EGA functions: function 15 is reserved.

● BYT driver with EGA functions: function 15 is multifunctional for EGA units.

Note

The EGA

-specific information is provided in this description in contiguous sections as far

as possible, or identifie

d appropriately by means of "Notes on EGA units".

The EGA

-specific information is irrelevant if you are using non-EGA units.

5.2.1.2

Half/full duplex mode

Usually, the BYT driver operates in half duplex mode, i.e. without simultaneous transmission

and receive operations. The BYT driver can allocate in an interim buffer for storing incoming

characters to prevent the loss of characters in a write job. The pool ID for this allocation is

defined in the configuration data. The buffer has a maximum length of 255 characters.

The echo mode, i.e. output of received characters and the handling of terminal control

characters, is restricted to the half duplex mode to prevent collision between simultaneous

read and write jobs.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

98 Programming Manual, 07/2012, A5E03692298-01

The duplex mode, i.e. simultaneous processing of transmission and receive operations, may

only be used in the following combinations of write operations and transparent read

operations.

Table 5- 1 Combination of read and write operations in DUPLEX mode

2nd

Call

Multi-

func-

tion

1st Call

RESERVE

–

RELEASE

–

READ

–

WRITE

–

XWRT

–

ONE_XREAD

–

WRT_XREAD

–

WRT_READ

–

SKIP_LINE

–

FORM_FEED

–

HSFS_XREAD

–

HSFS_WRITE

–

POLL_XBUFF

–

CHECK_ABO

–

CREATE_NEW

–

Multifunction 15 – – – – – – – – – – – – – – – –

no simultaneous function sequence

simultaneous sequence enabled

Conditional simultaneous sequence, if

no data output with function 1

no data output with function 2

no data input with function 1

no data input with function 2

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 99

5.2.1.3

Control characters for BYT drivers and terminals

Expected and unexpected characters

Usually, only the unexpected characters are treated as control characters. All characters

pending for a read job or for operation in transparent mode are treated as expected

characters. You can prevent any XON/XOFF protocol errors by including a verification of

XON/XOFF characters on receiving expected characters in programming.

XOFF <CTRL>+<S>

Unexpected character:

An active output operation is interrupted until XON has been received. The character is not

written to the interim buffer.

Expected character:

The character will be transfered to the user buffer. The echo mode is activated (^S) (if no

transparent read operation).

Expected character and XON/XOFF verification:

The character is copied to the user buffer (Echo ^S) (if no transparent read operation) and

the active output operation is interrupted until XON has been received.

XON <CTRL>+<S>

Unexpected character:

Any XOFF is revoked. The character is not written to the interim buffer.

Expected character:

The character will be transfered to the user buffer (Echo ^Q) (if no transparent read

operation).

Expected character and XON/XOFF verification:

The character is copied to the user buffer (Echo ^Q) (if no transparent read operation) and

an XOFF is revoked.

ABORT_INPUT

Unexpected character:

The character sets an abort Flag in the BYT driver; this flag can be queried with function 13.

The character is configured in the file RINITBYT.C in the directory CONFIG (usually:

<CTRL>+<C>).

Expected character:

The character will be copied to the user buffer.

Task start character

Unexpected character:

A task can be started by two different control characters (task start due to unexpected input).

The characters are configured in the UCD block of the unit (UCD.UNSCHR).

Expected character:

The character will be copied to the user buffer.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

100 Programming Manual, 07/2012, A5E03692298-01

Terminal control characters

The BYT driver is adapted to a terminal type by the initialization of terminal control

characters (e.g. specific keys of a keyboard) in the file RINITBYT.C, directory CONFIG.

These characters are interpreted as control characters only in terminal mode and while no

transparent read job is pending. The control characters specified in the file enable the BYT

driver to identify keyboard input such as Clear Screen, or cursor movements without error.

The control characters are processed in the terminal-specific sequences that must be

defined in RINITBYT.C.

The following terminal control character entries are identified:

READ_TERMINATE

Terminate input without echo

RUBOUT_INPUT

Delete last character entered

BACKSPACE_INPUT

Delete character left of the cursor position

NEXT_HISTORY

History mode: go forward

LAST_HISTORY

History mode: go backward

INSERT_BLANK

Insert blank at cursor position

DELETE_CHAR

Delete character at cursor position

ZAP_RIGHT_INPUT

Delete line characters on the right side

CURSOR_START

Set cursor to the start of the entry

CURSOR_END

Set cursor to the end of the entry

CURSOR_RIGHT

Shift cursor right by one character

CURSOR_LEFT

Shift cursor left by one character

CLEAR_SCREEN

Clear screen

In terminal mode (exception: transparent reading mode), the control characters listed above

are not passed to the input buffer and are handled by the driver instead.

ABORT_OUTPUT

Unexpected character:

Abort and terminate current output operation (single RmIO with write function). The character

is configured in the file RINITBYT.C in the directory CONFIG (usually: <CTRL>+<X>).

Expected character in terminal mode:

The input buffer is cleared (including the echoed characters at the terminal). The read job

pending is maintained.

Expected character in transparent mode:

The character will be copied to the user buffer

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 101

5.2.1.4 History mode

Buffer for all non-transparent entries

The history mode is configured in UCD.UCMODE. The driver allocates memory space from

a static pool for operation in this mode. In this mode, all non-transparent entries (functions 02

and 07) are also saved to a 256-byte history buffer and can be activated by entering terminal

control characters. The history buffer never contains more than the last 256 bytes.

5.2.1.5 Data flow of received characters

Interpretation of incoming characters

The following diagrams show the data flow of an incoming character in simplified form.

These diagrams show you when a character is interpreted as expected, unexpected or as a

control character. Pay particular attention to the fact that not all of these characters are

transferred to the buffer when you operate in terminal mode and that control characters may

also be read with the active transparent reading function. If an intermediate buffer is used

which already contains input characters, the character is taken from this intermediate buffer.

Error code (–9) is returned in the primary status byte on buffer overflow.

Figure 5-1 Data flow of an incoming expected character in the BYT driver

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

102 Programming Manual, 07/2012, A5E03692298-01

Figure 5-2 Data flow of an incoming unexpected character in the BYT driver

Figure 5-3 Handling of control characters in the BYT driver for transparent read jobs

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 103

Figure 5-4 Handling of control characters in the BYT driver for standard read jobs

Figure 5-5 Handling of character output in the BYT driver

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

104 Programming Manual, 07/2012, A5E03692298-01

5.2.1.6

Special features for EGA units

HW requirements for EGA functions of BYT

Prerequisite for EGA functionality of the BYT driver is a hardware platform that contains an

IBM–compatible PC/AT, or an IBM–PC/AT–compatible module system with monochrome,

EGA, or VGA adapter.

The following conditions must be met:

● The memory addresses from A0000H to C7FFFH are reserved for the graphic display

buffer and the ROM I/O adapter.

● The I/O addresses from 3B0H to 3DFH are reserved for the display adapter.

● You can use keyboards that are compatible with IBM–AT/02 and IBM–AT/03

specifications.

Timeout handling

You cannot configure a timeout that only affects write jobs (parameter UCD.TIMOUT) for

EGA units.

Units, pages and windows

You may configure the BYT driver so that the PC/AT–compatible system can simultaneously

behave as one, two, three, or four "PCs". The software interprets this setup internally as four

units. Usually, only one keyboard and screen are available on a PC/AT. This means that the

keyboard assignment must alternate between the four units. Moreover, it is necessary to

organize on-screen visualization to the effect that each one of these units is capable of

outputting data to the screen. For this purpose, the BYT driver manages altogether 4 screen

pages that are assigned to the four units. The page assignments are specified in the driver

configuration.

You can configure the BYT driver so that several units are able to output data to a single

page. Observe the following details:

1. Each page can be distributed to four windows (page-oriented window arrangement).

2. You can define up to four windows per unit, but only one of these per page (unit-oriented

window arrangement).

A window corresponds to any rectangular screen section. A check of whether or not any

windows overlap on a page is discarded. Along with the two extreme scenarios, i.e. four

units being assigned to the four pages, which requires a total of 16 windows, and one unit

that only writes to one page, all variations are feasible.

Observe the following

● Only complete pages or units are selected instead of windows.

● The entire screen content is swapped along with the change to a different page

● Changes are always page– or unit-related, and the only purpose of windows is to

separate the display of data output to the same screen page from several units.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 105

Windows are always configured in pages for each unit, i.e. maximum of four windows per

unit, with one of each per page. Two page classes are defined:

Write page:

One of the four pages that is assigned unambiguously to a unit and used by this unit to

output data to a window is referred to as write page. The window occupies the full screen

page, or only a section thereof.

Display page:

This denotes one of the four pages that is currently visualized on-screen.

Observe the following:

The current write page and the display page may not be identical, so that it is possible to run

all I/O operations in the background.

Configuration options

The following configuration options are available:

1. Number of units (max. 4)

2. pages assigned to a unit for data output

3. Position, size, character/background color of the windows necessary for data output

Static number of units

The number of configured EGA units (max. 4) is static and cannot be manipulated at

runtime. Such basic settings can only be changed by reconfiguring the system.

Unit 0 is always handled as main unit, and the remaining three as subunits. The units differ

only in terms of their internal initialization. These differences are irrelevant to user programs.

UCDs must be in direct succession

The unit control data tables of the EGA units mus be installed in direct succession.

The configured background colors, font colors and corner coordinates of a window are

independent of other windows, which means that the windows may overlap or cover each

other on a page.

Meaning of the function keys

Function keys F1 ... F8 have the following meaning for EGA units, independent of the job

state of the driver (e.g. read job):

(Keys F9 ... F10 (for AT/02–compatible keyboards) and F9 ... F12 (for AT/03–compatible

keyboards) are reserved.)

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

106 Programming Manual, 07/2012, A5E03692298-01

F1 ... F4

Press function keys F1 ... F4 to assign the keyboard to unit 0, 1, 2, or 3. The display page is

switched simultaneously to the current write page of the new keyboard unit.

F1 assigns the keyboard to unit 0

F2 assigns the keyboard to unit 1

F3 assigns the keyboard to unit 2

F4 assigns the keyboard to unit 3

The key for a non-configured unit is irrelevant.

F5 ... F8

These function keys switch the current display page.

F5: Selects display page 0.

F6: Selects display page 1.

F7: Selects display page 2.

F8: Selects display page 3.

This function is always executed, irrespective of whether or not the selected display page is

the write page of a unit.

A read call can never be used to access one of the 10 or 12 function keys.

Internal management

The BYT driver manages 4 pages. In alpha mode, a maximum of four units can output data

to each page.

Representation: Characters in alpha mode

In alpha mode, the screen page consists of a matrix with 25 rows, each with 80 characters.

Each character is interpreted as character that can be visualized based on information

consisting of the respective ASCII code and color attribute. For information about the

character database, including semi-graphic characters and possible color attributes, refer to

the Reference Manual.

At each RmIO call (output), the driver identifies the page (of four) used to output the data

(write page). It also defines the page that is currently displayed on-screen (display page) and

manages the screen coordinates of the corresponding windows for each unit.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 107

Write position

Moreover, the program manages a write position for each unit and page. This means that

each unit is assigned up to four different write positions (one per page). Once the write page

of a unit is changed, the write position of this page is applied immediately. If the program

returns to the previous write page, the previous write position is activated accordingly. This

means that the write position of a unit always depends on the currently set write page. Since

the write position can never drift out of the defined window, a "Set/Get Cursor Position"

function has been dispensed with. All functions relate to the current write position.

Cursor only on the write page

General rule:

The cursor is only displayed at the current write position of the unit that the keyboard has

been assigned to. When "paging" through the four pages using the F5 to F8 keys, you see

the cursor only on one page, because the keyboard is always assigned only to one unit that

has only one current write page.

Keyboard: 6 types

The BYT driver supports 6 different keyboard types (US, German, English, French, Italian

and Spanish). The keyboard type to be used is specified in the configuration. You cannot

configure more than one keyboard type for use at a given time. This type can be changed at

runtime using the CHGKBD command. You can assign the keyboard to the configured units

at runtime using function keys F1 to F4.

Each character received is initially saved to a 16-byte buffer (EGA unit-specific) where it is

converted to match the configured keyboard type. The character is then fetched from the

interim buffer in the next processing phase and transferred to the unit the keyboard is

currently assigned to.

Entering special characters in ASCII code

In addition to the characters that can be set by means of direct keyboard input, you can enter

all other characters (e.g. semi-graphic characters) using the following method:

● Press the ALT key and keep it pressed.

● Enter the 3–digit decimal ASCII code of the selected character using the numerical keys

of the keyboard.

● Release the ALT key.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

108 Programming Manual, 07/2012, A5E03692298-01

Figure 5-6 Keyboard integration

Internal input interface

Subfunction 15 of the multifunction can be used to open the internal input interface for

external access. This means that characters received can be fetched from the buffer directly

after they were converted for a specific keyboard type (EGA unit-specific). Higher-level BYT

driver functions do not process these characters. You should only open the internal input

interface if special entries cannot be realized using the available functions.

The characters are fetched using a software interrupt interface that is compatible with BIOS

interrupt 16H of an IBM–AT–compatible PC. The number of the software interrupt can be

configured. The interrupt is configured by entering the X_BYT_KBD_REC_INT vector in the

software configuration file (interrupt table). You may not enter this interrupt if this interface is

not used.

The interface provides the following functionality. To execute its functions, write the function

code to the AH register.

Table 5- 2 Function code of the internal input interface

Function code Meaning

0 Read next ASCII character from keyboard.

The character code is transferred to the AL register, while the scan code of

the key is transferred to the AH register.

If no character exists, the program waits until a character is available. Take

this aspect into account when calling this function.

1 Set zero flag if the buffer is not cleared.

ZF = 1 –> no character.

ZF = 0 –> character available.

2 Fetch SHIFT status to AL register

You can use subfunction 15 of the multifunction to close the internal input interface again. As

soon as it is closed, it is not longer possible to fetch characters via this interface.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 109

Internal output interface

The internal output interface can be switch on and off by executing subfunction 14 of the

multifunction. All RmIOs are terminated with "successful" status when the interface is switched

off. As of this point in time, the BYT driver will only execute the subfunctions 10 to 15 of the

multifunction.

Subfunction 14 provides direct access to the display adapter. All output data must be written

directly to the display buffer if the internal output interface is in off state. Once the internal

output interface is re-activated, the BYT driver resumes operation at the position where the

internal output interface was deactivated. It is necessary to restore the original state,

depending on the output activities performed in the meantime (while the output interface was

deactivated), to ensure the correct output of data. You should not deactivate the internal

output interface unless special entries cannot be realized using the available functions.

The following figure demonstrates the internal structure of the driver in standard situations:

Figure 5-7 Example of unit 2 (debugger) output to the assigned window 2 on page 2

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

110 Programming Manual, 07/2012, A5E03692298-01

Output in graphic mode

The BYT driver supports data output in alpha mode. It will be necessary to output the data in

graphic mode if this mode is not appropriate for handling the additional semi-graphic

characters. Proceed as follows:

● Turn off the internal output interface with subfunction 14 of the multifunction.

● Direct write access to the display buffer is enabled on completion and you need to

program the corresponding registers of the EGA adapter.

Example

In this example, the program I is assigned Unit 0 and write page 0, program II is assigned

Unit 1 and write page 0, and program III is assigned Unit 2 and write page 0.

Figure 5-8 Page 0, window arrangement

Keyboard assignment

The keyboard is assigned to Unit 0 (or to program I) by pressing the F1 key. All entries are

now transferred to program I, or saved to the Unit 0 buffer. Write page 0 is simultaneously

displayed on-screen (display page).

The keyboard is assigned to Unit 2 (or to program III) by pressing the F3 key. All entries are

now transferred to program III, or saved to the Unit 2 buffer. Write page 0 is still displayed on

the screen.

At the change of the write page of Unit 2 to Page 1, program III executes all output

operations in the lower window of page 1.

Figure 5-9 Page 0, window arrangement

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 111

Switching display pages

The pages 0 or 1 can be displayed on-screen using the F5 and F6 function keys. Assuming

that the keyboard is still assigned to program III and page 1 is still displayed on the screen,

the F5 key triggers the following actions:

Page 0 is visualized on the screen. However, the cursor will remain hidden because the

keyboard is not assigned to program I or II. All entries are still transferred to program III (or to

unit 1). Active output operations of program III are not interrupted and are continued in the

background.

You can restore the output of page 1 on the screen by pressing F6. The cursor flashes on

this page because the keyboard is still assigned to program III. You can now press F1 to

assign the keyboard to program I and display page 0 on the screen. Unit 1 output can still be

directed to a corresponding window independent of this setting. The keyboard is assigned to

unit 1 by pressing F2. The F4 key is insignificant, because unit 3 is not configured for this

example.

5.2.1.7

Opcodes of the BYT driver (bits 0..3)

The BYT driver executes the following opcodes, depending on the configured unit type (see

UCD.UCMODE). The corresponding literals of the RIO.H and RIO.EQU include files are set

in parentheses.

Terminal

a) Configuration as I/O device (e.g. terminal):

00H

Reserve unit (BYT_RESERVE)

01H

Release unit (BYT_RELEASE)

02H

Read (BYT_READ)

03H

Write (BYT_WRITE)

04H

Unconditional writing (BYT_XWRT)

05H

Read character in transparent mode (BYT_ONE_XREAD)

06H

Write and read in transparent mode (BYT_WRT_XREAD)

07H

Write and read (BYT_WRT_READ)

08H

Skip line (BYT_SKIP_LINE)

09H

Clear screen (BYT_FORM_FEED)

0AH

Read character to buffer in transparent mode (BYT_HSFS_XREAD)

0BH

Write character from buffer (BYT_HSFS_WRT)

0CH

Read interim buffer in transparent mode (BYT_POLL_XBUF)

0DH

Check input buffer for abort characters (BYT_CHECK_ABO)

0EH

Redefine and initialize the unit (BYT_CREATE_NEW)

0FH Multifunction (only for EGA units)

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

112 Programming Manual, 07/2012, A5E03692298-01

Printer

b) Output device (e.g. line printer):

00H

Reserve unit (BYT_RESERVE)

01H

Release unit (BYT_RELEASE)

03H

Write (BYT_WRITE)

08H

Line feed (BYT_SKIP_LINE)

09H

Form feed (BYT_FORM_FEED)

0BH

Write character from buffer (BYT_HSFS_WRT)

0EH

Redefine and initialize the unit (BYT_CREATE_NEW)

0FH

Multifunction (only for EGA units)

Keyboard

c) Input device (e.g. keyboard):

00H

Reserve unit (BYT_RESERVE)

01H Release unit (BYT_RELEASE)

05H

Read character in transparent mode (BYT_ONE_XREAD)

0AH

Read character to buffer in transparent mode (BYT_HSFS_XREAD)

0CH

Read interim buffer in transparent mode (BYT_POLL_XBUF)

0DH

Check input buffer for abort characters (BYT_CHECK_ABO)

0EH

Redefine and initialize the unit (BYT_CREATE_NEW)

0FH

Multifunction (only for EGA units)

Invalid opcodes

On detection of an invalid opcode, the BYT driver stops execution of I/O requests and

returns an error code (–1) in the primary status byte. For more information on the handling of

opcodes, refer to the next chapter.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 113

5.2.2

RmIO interface

The parameters of SVC RmIO that are of importance for the description of driver properties

are listed below:

Function, bit 5

Cancel bit

Function, bit 3..0

Function code of the selected driver function

pState

Status pointer that reports internal states of the

driver.

pParam

Points to a data block with other function-specific

parameters.

5.2.2.1

Function parameter

This parameter sets the selected BYT driver functions (bit 0..3) and controls the sequence of

the driver function.

Table 5- 3 RmIO parameter Function of the BYT driver

Bit

Values

Function

Preemptive bit

Sort I/O request based on priority

Set I/O request to the start of the queue

Wait bit

Wait for completion of the I/O operation

No waiting

Cancel bit

Cancel active I/O operations

No abortion

reserved

3..0

00..0EH

Valid opcode

0FH Reserved if the EGA functions cannot be executed (by implementing

EGADMY.OBJ)

0FH Multifunction (only for EGA units), if the BYT driver is able to execute

the EGA functions (no linking of EGADMY.OBJ).

Note

The additional opcode value 15 is only valid for EGA units. This opcode remains reserved for

all other configuration options; the driver reports an RmIO parameter error (FFH).

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

114 Programming Manual, 07/2012, A5E03692298-01

Cancel bit (bit 5)

If the cancel bit is set, all I/O operations currently executed by this unit are aborted and

reported with error code (–4) in the primary status byte. Queued requests are not affected by

this action. The cancel request is then added to the queue of requests in accordance with its

priority.

Opcode (bit 0 .. 3)

The BYT driver executes the following function codes depending on the configured unit type

(see UCD.UCMODE in chapter "UCMODE (Unit Control Code) (Page 144)"). The

corresponding literals of the RIO.H, RIO.EPD and RIO.EQU include files are set in

parentheses.

a) Configuration as I/O device (e.g. terminal):

Table 5- 4 Configuration as I/O device (e.g. terminal)

Opcode

Meaning

00H

Reserve unit (BYT_RESERVE)

01H

Release unit (BYT_RELEASE)

02H

Read (BYT_READ)

03H

Write (BYT_WRITE)

04H

Unconditional writing (BYT_XWRT)

05H

Read character in transparent mode (BYT_ONE_XREAD)

06H

Write and read in transparent mode (BYT_WRT_XREAD)

07H

Write and read (BYT_WRT_READ)

08H

Skip line (BYT_SKIP_LINE)

09H

Clear screen (BYT_FORM_FEED)

0AH

Read character to buffer in transparent mode (BYT_HSFS_XREAD)

0BH

Write character from buffer (BYT_HSFS_WRT)

0CH

Read interim buffer in transparent mode (BYT_POLL_XBUF)

0DH

Check input buffer for abort characters (BYT_CHECK_ABO)

0EH

Redefine and initialize the unit (BYT_CREATE_NEW)

0FH

Multifunction (only for EGA units)

Note

For EGA units

Functions 0 to 14 can be mapped to an EGA adapter. In this context, note the following:

1. All write calls are directed to the current write page of the EGA unit. All characters are

accordingly assigned the attribute specified in the page d

escriptors (see function 15,

subfunction 19) for this page. The scrolled new lines are assigned the screen attribute.

2. All read calls can only be answered if the keyboard is assigned to the corresponding unit.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 115

b) Output device (e.g. line printer):

Table 5- 5 Configuration as output device (e.g. line printer)

Opcode

Meaning

00H

Reserve unit (BYT_RESERVE)

01H

Release unit (BYT_RELEASE)

03H

Write (BYT_WRITE)

08H

Line feed (BYT_SKIP_LINE)

09H

Form feed (BYT_FORM_FEED)

0BH

Write character from buffer (BYT_HSFS_WRT)

0EH

Redefine and initialize the unit (BYT_CREATE_NEW)

0FH

Multifunction (only for EGA units)

c) Input device (e.g. keyboard):

Table 5- 6 Configuration as input device (e.g. keyboard):

Opcode

Meaning

00H

Reserve unit (BYT_RESERVE)

01H

Release unit (BYT_RELEASE)

05H

Read character in transparent mode (BYT_ONE_XREAD)

0AH

Read character to buffer in transparent mode (BYT_HSFS_XREAD)

0CH

Read interim buffer in transparent mode (BYT_POLL_XBUF)

0DH

Check input buffer for abort characters (BYT_CHECK_ABO)

0EH

Redefine and initialize the unit (BYT_CREATE_NEW)

0FH

Multifunction (only for EGA units)

On detection of an invalid function code, the BYT driver stops execution of I/O requests and

returns an error code (–1) in the primary status byte. For more information on the handling of

function codes, refer to the next section "BYT driver functions".

5.2.2.2

Parameter pState

SVC RmIO uses parameter pState to pass a pointer to an 8-byte field. The driver writes the

status information to this field on completion of the corresponding job. It is advisable to

evaluate the status field on completion of each job. It is not appropriate to check an RmIO only

by the return value, because this only contains information about the OK state of parameters

from the nucleus, but not the status of the actual driver.

The first byte is the primary status byte and the second is the secondary status byte, while

the next two bytes are used to enter the number of actually transferred bytes on completion

or abortion of the I/O operation. The following table describes the codes for the primary and

secondary status bytes, as well as for the second status word for the BYT driver.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

116 Programming Manual, 07/2012, A5E03692298-01

If several RmIO calls are handled in parallel (bit 6 in parameter Function), each pending call

must be assigned a unique parameter field for the transfer of parameters, because the

nucleus only copies the pointer, but not the actual field at the RmIO call.

The controller status is only checked (e.g. parity) if the corresponding status bit is set in

UCD.UCMODE. If another error occurs along with a status error, only the latter will be

reported. An additional error message is output if the error logger task is configured (e.g.: ‘***

ERROR BYT: BAD STS USRT 8251’).

Table 5- 7 RmIO parameter pState

Primary

status byte

Secondary

status byte

2nd status

word

3rd and 4th

status word

Meaning

0 00H 0000H 0000

0000H

I/O request is queued.

1 00H 0000H 0000

0000H

Busy processing the I/O request.

2 1 2 0000

0000H

I/O request successfully completed.

–1 (FFH) 00H 0000H 0000

0000H

I/O request rejected due to invalid

parameterization

–2 (FEH) 00H 0000H 0000

0000H

Reserve/release operation was not

executed, as the unit is already

reserved/not reserved.

–3 (FDH) 1 2 0000

0000H

I/O request terminated due to timeout

–4 (FCH) 1 2 0000

0000H

BYTE: I/O request terminated by cancel

function

–5 (FBH) 1 2 0000

0000H

BYTE: I/O request aborted due to

invalid status check

–6 (FAH) 1 2 0000

0000H

I/O request terminated by External

Change Interrupt at the SCC 8530 block

–7 (F9H) 1 2 0000

0000H

I/O request terminated by Special

Receive Interrupt at the SCC 8530

block

–8 (F8H) 00H 0000H 0000

0000H

BYTE: Polling request rejected (read

interim buffer in transparent mode,

BYT_POL_XBUF) due to missing buffer

mode configuration.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 117

Table 5- 8 RmIO parameter pState (continuation)

Primary

status byte

Secondary

status byte

2nd status

word

3rd and 4th

status word

Meaning

–9 (F7H) 1 2 0000

0000H

BYTE: Input request in buffer mode

terminated due to buffer overflow

–10 (F6H) 00H 0000H 0000

0000H

Multifunction not executed

The last byte read or transferred is entered, depending on the I/O request.

2 Number of actually transferred bytes.

5.2.2.3

Parameter pParam

SVC RmIO uses parameter pParam to pass a pointer to a 24-byte field. This field must be

initialized prior to the call, depending on the selected BYT driver function (e.g. read). The

respective meaning of the bytes of the parameter block is explained in the description of BYT

driver functions. Many functions are capable of receiving data from two different parameter

blocks. Certain function calls do not need all 24 bytes of the parameter block. If a restricted

interpretation of the parameter block was configured in UCD.UCMODE, it is possible to

transfer smaller blocks in the system call. Always set the reserved parameters in the

parameter block to zero.

Note

For EGA units:

Parameter

pParam defines (other than for functions 0 .. 14 ) a pointer to a 12-byte field in the

data segment for function 15 (multifunction), with subsequent definition of the structural

arrangement.

Parameter block for functions 0..14 (or 0..15, if the EGA functions

cannot

be executed;

function 15 is reserved!):

Type

Offset

Description

Note

POINTER far 0 Offset/segment of the output buffer or input

request text

WORD int 6 Length of the output buffer or input request

text

POINTER far 10 Offset/segment of the input buffer or

transformation table

WORD int

Length of the input buffer, or timeout value

WORD int

Block status information

Total scope

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

118 Programming Manual, 07/2012, A5E03692298-01

Parameter block of function 15 (multifunction):

Type

Offset

Description

Note

BYTE char

Subfunction number

BYTE char

Variable

WORD short

Variable

POINTER far

to user buffer

POINTER far

to user buffer

Total scope

Note

Subfunctions 0 to 18 only need a 4

-byte parameter block.

1 The drivers always use the same segment value to execute I/O operations, which means

changes to the segment value are ignored in the case of offset overrun (FFFFH..0H).

2 I/O data has a maximum length of 64 K. Only the least significant 2 bytes of 4 bytes are

used.

3 Reserved for the transfer of block-related status information upon completion of an I/O

operation (UCD.STMODE). The least significant byte contains the status information read for

the status check. The most significant byte is only set to the content of RR0 at the 8274 und

8530 blocks. The least significant byte contains RR1 (status register 0 or 1). The most

significant 2 bytes of the status word are set to 0.

4 A description of the parameters for the corresponding parameter block is available in the

description of subfunctions of the multifunction.

5.2.3

Opcodes of the BYT driver

5.2.3.1

Reserve unit (BYT_RESERVE)

Opcode: 00H BYT_RESERVE

Parameter block length: 24 bytes

This function reserves the unit specified in the RmIO (unit_id) exclusively for I/O requests of

the calling task. I/O requests of other tasks are accepted, but not executed until the unit has

been released. An exception are I/O requests with set preemptive bit.

I/O requests to a reserved unit are processed in a fixed order:

● Calls with set preemptive bit in chronological order

● Calls of the task that has reserved the unit in chronological order

● Calls of other tasks in the order of priority after the unit has been released

If a task attempts to once again reserve a unit that has not yet been released, an error

message (–2) is returned in the primary status byte. The previous reservation is retained.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 119

Reservation option of the BYT driver

The parameter block for unit reservation is optional and only evaluated if unrestricted

parameter block interpretation was configured in the Unit Control Code (UCD.UCMODE).

The following functions are then available:

● Define input request text

● Define transformation table

● Change unit timeout value

Parameter block for reservation call:

Type

Offset

Description

POINTER far

Address of the input request text

WORD int

Length of the input request text

POINTER far

Address of the transformation table

WORD int

Timeout value (multiple of 256 ms)

WORD int

reserved

Input request text (reservation)

The input request text consists of a string that is output from a read operation by means of

simulated echo. Non-reserved units do not use request text. The input request text is defined

during reservation and remains valid for the duration of reservation. The function is

discarded and the specified string is ignored if the unit is not an I/O type (e.g. a terminal). A

string length of 0 is also ignored.

Transformation table (reservation)

This table has a length of 128 bytes and is used for the transformation of characters received

in a read operation. A transformation table that is activated by the configuration

(UCD.TABBUF) is replaced with a table that is specified in the reservation, while data output

is not affected. The most significant bit (bit 7) is hidden and the resultant input value (0..127)

is used as index in the transformation table. If the segment or address offset of the

transformation table is unequal to zero, the transformation of input data is executed prior to

the echo; the data is transferred to a user-defined buffer. The input transformation is

discarded in the reservation phase at the following conditions:

● Input request with transparent read operation

● Input character corresponds to a control character

A NULL pointer (0:0) at offset 10 is interpreted as a not requested function. See also section

"Data flow of a character received (Page 101)".

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

120 Programming Manual, 07/2012, A5E03692298-01

Timeout parameter (reservation)

The timeout parameter is used to force termination of an I/O request that was not completed

within a specified time. At a value greater than zero, all I/O operations are subject to timeout

monitoring (timeout interval = value x 256) and replaces the corresponding timeout value

that was calculated for output operations(UCD.TIMOUT) for the duration of unit reservation.

In contrast to

UCD.TIMOUT, this timeout value is not multiplied by the total number of characters to be

output.

On timeout, the I/O request is aborted and an error code (–3) is entered in the primary status

byte. The secondary status byte contains the most recently read or transmitted byte if status

word 2 reports a value greater than zero.

Note

The reservation is revoked automatically and m

ust be repeated if necessary when the error

code (

-3) is triggered.

The reservation is also revoked if the unit was reserved by the same task in order to prevent

system deadlocks. In this case, a successive release request of the task is terminated with

error code (–2) in the primary status byte.

A 0 value in the timeout parameter at the time of reservation only suppresses time

monitoring for input requests. If the time monitoring for output requests is to be omitted,

UCD.TIMOUT must also be set to zero.

5.2.3.2

Release unit (BYT_RELEASE)

Opcode: 01H BYT_RELEASE

Parameter block: None

This function revokes the reservation of the unit specified in RmIO (unit_id). I/O requests

that were blocked due to the reserved state are now executed in the order of their priority. If

the task attempts to release a unit it has not reserved, or which was already released, error

code (–2) is returned in the primary status byte. This is the case, for example, if the

reservation was already revoked by timeout.

If you set the preemptive bit along with opcode 01H (i.e. opcode 81H) at an RmIO , it is also

possible to release a unit that was reserved by a different task.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 121

5.2.3.3

Read (BYT_READ)

Opcode: 02H BYT_READ

Parameter block: 24 bytes, 20 bytes restricted

This function transfers characters from an I/O device to a user-defined input buffer with echo

mode. The length and address of the user buffer are transferred in the parameter block. The

length of the input buffer corresponds to the maximum number of characters to be read. With

zero user buffer length, the input request is terminated without having been processed and

without error message.

Parameter block for read request:

Type

Offset

Description

Note

POINTER far

reserved

WORD int

reserved

POINTER far

Address of the input buffer

WORD int

Length of the input buffer

WORD int

Status information

1 Unrestricted interpretation

The characters input on the keyboard (masked with 7FH) are saved to the input buffer (if

configured) and displayed as echo on the terminal. The BYT driver adds the value 40H to

characters that cannot be mapped (input value less than 20H, or equal to 7FH), and the

echo is output (masked with 7FH) along with the circumflex (^). In the case of a reservation

with request text, the BYT driver will first output the input request.

Terminating read operations

The read operation is terminated at the following conditions:

1. Carriage return character (CR)

2. Terminator character input

BYTE: READ_TERMINATE is configurable in RINITBYT.C

(usually CTRL Z)

3. Maximum buffer length reached

4. Timeout expired

On completion of a read request, the secondary status byte receives the last character read

and the second status word receives the number of bytes actually read. The carriage return

characters (CR), as well the LF characters in line feed mode, are included in the count. CR

and LF are saved to the input buffer, while the latter is only saved in line feed mode and if

sufficient space is available in the input buffer.

After CR, the following output appears on the screen:

Carriage return CR (0DH)

Line feed (only in line feed mode) LF (0AH)

In contrast, input terminator character will not generate echo output or change the cursor

position on the screen, but the character is also saved to the input buffer.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

122 Programming Manual, 07/2012, A5E03692298-01

Handling terminal control characters

During input, a number of terminal control characters are available that you can customize in

RINITBYT.C to suit the respective terminal. These control characters are not written to the

input buffer.

Cursor control:

● Shift cursor right by one character

● Shift cursor left by one character

● Set cursor to the start of the entry

● Set cursor to the end of the entry

Delete/Insert functions:

● Delete last input character

● Delete backspace and input character

● Delete all input characters up to current cursor position

● Delete all input characters after the cursor position

● Delete input character at cursor position

● Insert blank at cursor position

History buffer (only in history mode):

● Output predecessor in history memory

● Output successor in history memory

Special functions:

● Set abortion detection

● Clear screen

Using the intermediate buffer

If a buffer is used (configurable) that already contains input characters, the program first

processes the buffer as if these characters had just been entered. If the number of the

characters to be read is greater than the number of characters in the intermediate buffer and

the intermediate buffer contains no end character, the program will wait for further input. If

the buffer contains no end character, but in total more characters than the maximum number

of characters to be read, the corresponding number of input characters is fetched from the

buffer and the input request is terminated. On buffer overflow prior to the input request, an

error code (–9) is returned in the primary status byte on completion of the input request. Line

feed characters at the beginning of the buffer are ignored.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 123

Note

Input requests of length 1 in combination with the use of a intermediate buffer will initiate a

special handling routine, which means that all successive input characters are collected in

the intermediate buffer and the first character is only transferred from the intermediate buffer

to the user buffer (1 character) on detection of an end character. On each successive input

request of length 1, a further character is returned until the actual end character has been

reached.

If input length 1 is selected, the intermediate buffer is cleared and filled as explained earlier

at the call of the read function.

This special handling routine is necessary for the runtime support of editing functions, but

can be bypassed by executing the input request for a character by means of a "write and

read" function (opcode 07) and output length parameter set to zero.

5.2.3.4

Write (BYT_WRITE)

Opcode: 03H BYT_WRITE

Parameter block: 24 bytes, 10 bytes restricted

This function transfers characters from a user-defined output buffer to an I/O device. The

length and address of the output buffer are transferred in the parameter block. The length of

the output buffer corresponds to the maximum number of characters to be written. With zero

output buffer length, the write request is terminated without actual processing or error

message.

Parameter block for write request:

Type

Offset

Description

Note

POINTER far

Address of the output buffer

WORD int

Length of the output buffer

POINTER far

BYTE: Address of the extension table

WORD int

reserved

WORD int

Status information

1 Unrestricted interpretation

Terminating write operation

The write operation is terminated under the following conditions:

● Output terminator character (WRITE_TERMINATOR); only in terminal mode

● The specified number of characters was output

● Timeout expired

On completion of the RmIO , the secondary status byte contains the last character output,

while the second status word contains the number of bytes actually transferred. A status

check (if configured) or status report of the I/O block are executed at the start of a write job.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

124 Programming Manual, 07/2012, A5E03692298-01

Output text extension table

The additional output text extension function is only taken into account if unrestricted

parameter block interpretation is configured in the UCD block (UCD.UCMODE). The table is

used to extend escape sequences in the output text. An escape sequence consists of:

● Escape character (01BH)

● Index

● Optional parameter bytes

The index serves as pointer into the extension table and selects one of the texts that are

stored sequentially in the extension table and separated by the delimiter 0FFH. On

identification of an escape sequence in the output text, the program accesses the extension

text in the extension table and outputs the text up to the position of a delimiter. Fill characters

(0FEH) detected are replaced with the corresponding successive, optional parameter bytes.

The output text is then resumed. An example of the use of escape sequences is the output

of default text objects in which you only have to enter a small number of variable text

segments. This default text is taken from the extension table, while the variable text

segments are stored as parameter bytes in an escape sequence of the output text. Each

output operation begins with the specified output text. However, the first character may

already be an escape character that signals an extension.

Note

The value for the length of the output text must correspond to the total length of actual output

(i.e. output text length + length of selected escape sequences).

Example of an ASM386 code for handling an extension table:

ESC EQU 01BH ;ESCAPE CHARACTER

X EQU 0FEH ;FILL CHARACTER

STOP EQU 0FFH ;DELIMITER

CR EQU 00DH ;CARRIAGE RETURN

LF EQU 00AH ;LINE FEED

IND EQU 000H ;INDEX FOR EXTENSION

;TABLE (ESCAPE_TABLE)

ESCAPE_TABLE DB 'YEAR: 19',X,X,' MONTH: ',X,X,'

' DAY: ',X,X,STOP

OUTPUT_TEXT

DB 'DATE ',ESC,IND,'900812',CR,LF,0

TEXT_LENGTH DW 43

; OUTPUT WITH OUTPUT REQUEST AND CORRESPONDING PARAMETER

; BLOCK ALLOCATION:

'DATE YEAR: 1990 MONTH: 08 DAY: 12'

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 125

5.2.3.5

Unconditional writing (BYT_XWRT)

Opcode: 04H BYT_XWRT

Parameter block: 24 bytes, 10 bytes restricted

With the exception of the routine for handling extension tables, the parameter block

corresponds to the write function (03H). An extension table is not provided for this function.

In contrast to to the write function (03H), the function is handled correctly in duplex mode

even if a non-transparent read system call with echo mode (02H) is pending.

Type

Offset

Description

Note

POINTER far

Address of the output buffer

WORD int

Length of the output buffer

POINTER far

reserved

WORD int

reserved

WORD int

Status information

1 Unrestricted interpretation

5.2.3.6

Read character in transparent mode (BYT_ONE_XREAD)

Opcode: 05H BYT_ONE_XREAD

Parameter block: None

This function reads a single character from the unit without echo output. Each character

input or key function (exception: abort characters) are transferred along with their binary

value to the secondary status byte and therefore terminates the input request.

The second status word for the number of actually transferred bytes then contains the value

1. No input prompt text is output for this function, regardless of whether or not such output

was specified in the reservation. All characters are transferred if the transparent mode was

configured.

Note

See also section "

Data flow of a character received (Page 101)"

5.2.3.7

Write and read in transparent mode (BYT_WRT_XREAD)

Opcode: 06H BYT_WRT_XREAD

Parameter block: 24 bytes, 20 bytes restricted

The BYT driver transfers characters from a user-defined output buffer to an I/O device and

then expects input characters from this unit. The length and address of the I/O buffers are

passed in the parameter block.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

126 Programming Manual, 07/2012, A5E03692298-01

Type

Offset

Description

Note

POINTER far

Address of the output buffer

WORD int

Length of the output buffer

POINTER far

Address of the input buffer

WORD int

Length of the input buffer

WORD int

Status information

1 Unrestricted interpretation

With zero output buffer length, the write operation is ignored and only the read operation is

processed. No read operation is initiated at zero length of the input buffer. Except for the

extension table, the conditions for the writing parts of the call are similar to those for function

03. In contrast to function 02, the following restrictions must be taken into account when

reading character input:

● No input request text is output.

● Input characters do not generate echoes on the screen.

● End and control characters have no further influence and are also transferred to the input

buffer if the interim buffer does not contain a sufficient number of characters (exception:

abort character in terminal mode). See also section "Data flow of a character received

(Page 101)".

● The input operation is not terminated until the maximum length of the input buffer has

been reached.

The conclusion of the I/O request corresponds to that of function 02 in terms of the

secondary status byte. The function is not terminated until the read call is completed.

5.2.3.8

Write and read (BYT_WRT_READ)

Opcode: 07H BYT_WRT_READ

Parameter block: 24 bytes, 20 bytes restricted

This function corresponds to a combination of write and read operation. First, the program

executes the output operation, and secondly the input operation.

Type

Offset

Description

Note

POINTER far

Address of the output buffer

WORD int

Length of the output buffer

POINTER far

Address of the input buffer

WORD int

Length of the input buffer

WORD int

Status information

1 Unrestricted interpretation

With zero output buffer length, the write operation is ignored and only the read operation is

processed. No read operation is initiated at zero length of the input buffer. Write conditions

are similar to those for function 03. Reading corresponds to function 02, except that an input

request text that was specified in the reservation is not output for the BYT driver.

On completion of the I/O request, the secondary status byte contains the last character input,

while the second status word contains the number of input bytes actually transferred.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 127

5.2.3.9

Skip line (BYT_SKIP_LINE)

Opcode: 08H BYT_SKIP_LINE

Parameter block: 24 bytes, 10 bytes restricted

This function executes a carriage return/line feed CR/LF on the output unit. The number of

CR/LF operations is defined in the parameter block. No CR/LF is executed if the value

equals zero. The Carriage Return (0DH) and Line Feed (0AH) characters are output for the

CR/LF operation. With normal completion, the second status word contains twice the number

of CR/LFs that were specified in the parameter block and executed (2 characters per feed).

Type

Offset

Description

Note

POINTER far

reserved

WORD int

Number of carriage returns/line feeds

POINTER far

reserved

WORD int

reserved

WORD int

Status information

1 Unrestricted interpretation

5.2.3.10

Clear screen (BYT_FORM_FEED)

Opcode: 09H BYT_FORM_FEED

Parameter block: None

This function executes a form feed on the output device, or clears the screen. The necessary

control characters are obtained from the UCD block (UCD.TOPCHR). This application must

be supported by the hardware of the output device.

Note

For EGA units:

Provided they are unequal to ze

ro, the control characters from UCD.TOPCHR are output to

the EGA unit at the call of the function. This action will not clear the screen.

On EGA units, you need to execute subfunction 5 of the multifunction to clear the screen.

5.2.3.11

Read character to buffer in transparent mode (BYT_HSFS_XREAD)

Opcode: 0AH BYT_HSFS_XREAD

Parameter block: 24 bytes, 6 bytes restricted

This function corresponds to the "read character in transparent mode" function, with the

exception that the character that was read is not returned in the secondary status byte, but in

the user buffer.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

128 Programming Manual, 07/2012, A5E03692298-01

The parameter block to initialize prior to the call has the following structure:

Type

Offset

Description

Note

POINTER far

Address of the input buffer

WORD int

reserved

POINTER far

reserved

WORD int

reserved

WORD int

Status information

1 Unrestricted interpretation

5.2.3.12

Write character (BYT_HSFS_WRT)

Opcode: 0BH BYT_HSFS_WRT

Parameter block: 24 bytes, 6 bytes restricted

This function transfer a single character to the output device (exception: An output terminator

terminates the output request without actual output processing (terminal mode)).

Type

Offset

Description

Note

POINTER far

Address of the output buffer

WORD int

reserved

POINTER far

reserved

WORD int

reserved

WORD int

Status information

1 Unrestricted interpretation

5.2.3.13

Read interim buffer in transparent mode (BYT_POLL_XBUF)

Opcode: 0CH BYT_POLL_XBUF

Parameter block: 24 bytes

This function copies characters from the interim buffer of a unit to a user-defined input puffer.

If the interim buffer does not contain a sufficient number of characters, or none at all, the call

is terminated without waiting for a new character and without error message. If the interim

buffer contains more characters, the remaining characters will be retained in the buffer. The

actual number of characters read is written to the second status word. With zero input buffer

length, the call is terminated without having been processed and without error message.

If no buffer mode was configured, the primary status byte contains the error code (-8).

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 129

Type

Offset

Description

Note

POINTER far

reserved

WORD int

reserved

POINTER far

Address of the input buffer

WORD int

Length of the input buffer

WORD int

Status information

1 Unrestricted interpretation

5.2.3.14

Check input buffer for abort characters (BYT_CHECK_ABO)

Opcode: 0DH BYT_CHECK_ABO

Parameter block: 24 bytes

This function checks whether the BYT driver has received the ABORT_INPUT character

from an I/O device since the last function call. The number of abort characters received is

ignored. The abort character is not saved to the user-defined input buffer or interim buffer but

serves for function control only.

Type

Offset

Description

Note

POINTER far

Address of abort feedback

WORD int

reserved

POINTER far

Address of the abort routine

WORD int

reserved

WORD int

reserved

If ABORT_INPUT was received, the secondary status byte returns 0FFH, and otherwise

00H. The following procedure depends on the value set for the "address of abort feedback":

● Pointer unequal 0

The secondary status byte is also written to the specified address. Moreover, an internal

mechanism of the function is activated that writes the value 0FFH to the specified

address on each successive incoming abort character.

● Pointer equal to 0

Only the secondary status byte returns feedback. The internal mechanism of the function

is deactivated.

This function can also be used to pass the entry point address of a user-defined abort

routine. This routine is also started by the BYT driver after the abort character was received

(parameter: AL = driver ID, AH = unit ID, all other registers must be backed up) if the

PUBLIC symbol X_BYT_PROG_CC was assigned a value unequal zero in RINITBYT.C.

With offset and segment equal to zero, the additional call of a user-defined abort routine is

discarded.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

130 Programming Manual, 07/2012, A5E03692298-01

5.2.3.15

Redefine and initialize the unit (BYT_CREATE_NEW)

Opcode: 0EH BYT_CREATE_NEW

Parameter block: 20 bytes

This function is used to re-initialize a unit assigned to the driver, or the controller of this unit,

and/or to read the current operating parameters of the unit to a user buffer. Meaning of the

parameter block:

Type

Offset

Description

Note

POINTER far

Address of the output buffer

WORD int

Length of the output buffer

POINTER far

Address of the input buffer

WORD int

Length of the input buffer

The structure of the output/input buffer is similar to that of a UCD block (see chapter

"RmUCDStruct (Page 68)"). The content of the output buffer must be initialized prior to the

system call (initially in the course of system configuration, at system startup).

Reading current operating parameters of the unit:

The address and length of the output buffer must be equal to NULL or 0. The length of the

input buffer contains the length of the UCD block. The current operating parameters of the

unit are transferred to the input buffer. A copy of the current parameter definition of the unit is

saved to the input buffer. This means that the UCB parameters as of parameter

UCD.UCMODE will be copied, depending on the length of the input buffer.

Writing and re-initializing the unit:

The address and length of the input buffer must be equal to NULL or 0. The length of the

output buffer contains the length of the UCD block to transfer. The modified unit parameters

are written to the output buffer. This means that the UCB parameters as of parameter

UCD.UCMODE will be copied, depending on the length of the input buffer. Caution: define

an appropriate input buffer length.

The program first executes the read request if a read and a re-initialization request are

pending simultaneously.

Note

This function can be used to manipulate all parameters of the EGA units, except the page

descriptors. If these, or only these ar

e to be manipulated, you (additionally) need to call the

corresponding subfunction of the multifunction.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 131

5.2.3.16

Multifunction (only for EGA units)

In UCD.UCMODE, the multifunction offers only the following subfunctions for USART

number 1000B (EGA adapter and IBM–compatible keyboard):

Opcode: 0FH

Parameter block: 4 bytes for subfunctions 0..18

16 bytes for subfunction 19

Possible subfunction numbers:

Number

Function

Move write position to right

Move write position to left

Set write position

Read current write position

Set cursor mode

Scroll screen

Read character

Write character

Write character with attribute

Delete character left of write position

Delete character right of write position

Switch write page

Switch display page

Switch keyboard

Enable/disable output

Enable/disable input

16 Activate/deactivate screen scrolling

Activate/deactivate emulation

18 Get status

Read/write page descriptors

20 255

n.a.

Subfunctions 0..14:

A value is always returned in the variable at offset 2 in the parameter blocks of subfunctions

0..14.

Subfunctions 0..10:

Write and read functions: All calls relate to the write page set for the unit.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

132 Programming Manual, 07/2012, A5E03692298-01

Subfunction 0,

move write position to right

The write position is moved to the right by the specified number of positions.

If the function cannot be executed in one line, it is continued in the next line(s). The write

position on the right remains inside the defined window.

Once the write position has reached the bottom edge of the window, the window is scrolled

up.

Rules for the parameter block of subfunction 0:

● (1) Type: variable, length 1 byte; offset = 1

Number of positions by which the write position

is moved.

● (2) Type: variable, length 2 bytes; offset = 2

Most significant byte

Least significant byte

Data direction

Current write page UCD.TOPCHR,

least significant byte

Output

(3), (4) insignificant

Subfunction 1,

move write position to left

The write position is moved to the left by the specified number of positions.

If the function cannot be executed in one line, it is continued in the previous line(s). The write

position on the right remains inside the defined window.

Once the write position has reached the top edge of the window, the window is scrolled

down.

Rules for the parameter block of subfunction 1:

● (1) Type: variable, length 1 byte; offset = 1

Number of positions by which the write position is moved.

● (2) Type: variable, length 2 bytes; offset = 2

Most significant byte

Least significant byte

Data direction

Current write page UCD.TOPCHR,

least significant byte

Output

(3), (4) insignificant

Subfunction 2,

set write position

The write position is set to the specified position. The requested position must be inside the

defined window.

If FFH:FFH is specified as the line:column, the write position is set to the upper left corner of the

window (HOME function).

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 133

Rules for the parameter block of subfunction 2:

● (1) insignificant

● (2) Type: variable, length 2 bytes; offset = 2

Most significant byte

Least significant byte

Data direction

Row

Column

Input

Undefined

FFH

Output (on error)

Current write page UCD.TOPCHR, least

significant byte

Output (if successful)

(3), (4) insignificant

Subfunction 3,

read current write position

Rules for the parameter block of subfunction 3:

● (1) insignificant

● (2) Type: variable, length 2 bytes; offset = 2

Most significant byte

Least significant byte

Data direction

Row Column

Output

(3), (4) insignificant

Subfunction 4,

set cursor mode

You can resize the cursor by specifying the top and bottom grid within a character field.

Rules for the parameter block of subfunction 4:

● (1) insignificant

● (2) Type: variable, length 2 bytes; offset = 2

Most significant byte

Least significant byte

Data direction

Cursor top grid (bits 0..4)

Cursor bottom grid (bits 0..4)

Input

Undefined

Output

The row numbers of the grid are counted from top to bottom. Row 0 is at the top end of the

cursor.

(3), (4) insignificant

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

134 Programming Manual, 07/2012, A5E03692298-01

Subfunction 5,

scroll screen

The window of the current write page is scrolled by the specified number of rows. The write

position remains unchanged.

Rules for the parameter block of subfunction 5:

● (1) insignificant

● (2) Type: variable, length 2 bytes; offset = 2

Most significant byte

Least significant byte

Data direction

= 6: Scroll screen up

≠ 6: Scroll screen down

Number of rows

(0 = clear window)

Input

Window background color

Output

(3), (4) insignificant

Subfunction 6,

read character

Reads the character at the cursor position. The character and its attribute are returned. The

attributes can be evaluated based on the table in the "Configuration" section.

Rules for the parameter block of subfunction 6:

● (1) insignificant

● (2) Type: variable, length 2 bytes; offset = 2

Most significant byte

Least significant byte

Data direction

Character attribute Character (ASCII code)

Output

(3), (4) insignificant

Subfunction 7,

write character

Writes the specified character x times (1 ≤ x ≤ 255), starting at the current write position.

The character is assigned the current attribute that is defined in the page descriptors for this

page.

After the write position has reached the right edge of the window, the write call is continued

in the next row.

The window is scrolled up when the write position reaches the bottom edge of the window.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 135

Rules for the parameter block of subfunction 7:

● (1) Type: variable, length 1 byte; offset = 1

character (ASCII code)

● (2) Type: variable, length 2 bytes; offset = 2

Most significant byte

Least significant byte

Data direction

Undefined

Repetition factor x

Input

Character attribute

Character (ASCII code)

Output

(3), (4) insignificant

Subfunction 8,

write character with attribute

Writes the specified character that contains the set attribute

x times (1 ≤ x ≤ 255), starting at the current write position.

The available attributes can be obtained from the table in the section "Configuration".

Once the write position has reached the right edge of the window, the write call is continued

in the next row.

The window is scrolled up when the write position reaches the bottom edge of the window.

Rules for the parameter block of subfunction 8:

● (1) Type: variable, length 1 byte; offset = 1

character (ASCII code)

● (2) Type: variable, length 2 bytes; offset = 2

Most significant byte

Least significant byte

Data direction

Character attribute

Repetition factor x

Input

Character attribute

Character (ASCII code)

Output

(3), (4) insignificant

Subfunction 9,

delete character left of the write position

Deletes the specified number of characters to the left of the current write position. The write

position is followed accordingly.

On reaching the left edge of the window, the function is continued in the next row up.

The function is canceled after the top edge of the window was reached.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

136 Programming Manual, 07/2012, A5E03692298-01

Rules for the parameter block of subfunction 9:

● (1) Type: variable, length 1 byte; offset = 1

Number of characters to delete (1 to 255).

● (2) Type: variable, length 2 bytes; offset = 2

Most significant byte

Least significant byte

Data direction

Character attribute

Output

(3), (4) insignificant

Subfunction 10,

delete characters to the right of the write position

Deletes the specified number of characters to the right of the current write position. The write

position remains unchanged.

The function is canceled after the bottom edge of the window was reached.

Rules for the parameter block of subfunction 10:

● (1) Type: variable, length 1 byte; offset = 1

Number of characters to delete (1 to 255).

● (2) Type: variable, length 2 bytes; offset = 2

Most significant byte

Least significant byte

Data direction

Character attribute

Output

(3), (4) insignificant

Subfunction 11,

switch write page

Switches the current write page. The function is not executed if the unit is not assigned a

window on the specified page.

Rules for the parameter block of subfunction 11:

● (1) Type: variable, length 1 byte; offset = 1

Number of the selected write page (0, 1, 2, or 3)

● (2) Type: variable, length 2 bytes; offset = 2

Most significant byte

Least significant byte

Data direction

Undefined

New write page

Output (if successful)

Undefined

FFH

Output (on error)

(3), (4) insignificant

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 137

Subfunction 12,

switch display page

Switches the current display page.

Rules for the parameter block of subfunction 12:

● (1) Type: variable, length 1 byte; offset = 1

Number of the selected display page (0, 1, 2, or 3)

● (2) Type: variable, length 2 bytes; offset = 2

Most significant byte

Least significant byte

Data direction

Undefined

New display page

Output (if successful)

Undefined

FFH

Output (on error)

(3), (4) insignificant

Subfunction 13,

switch keyboard

Switches the keyboard to the specified unit. The function is not executed if the specified unit

is not configured.

Rules for the parameter block of subfunction 13:

● (1) Type: variable, length 1 byte; offset = 1

Number of the selected unit (0, 1, 2, or 3)

● (2) Type: variable, length 2 bytes; offset = 2

Most significant byte

Least significant byte

Data direction

Undefined New write page of the unit that

the keyboard is assigned to

Output (if successful)

Undefined FFH Output (on error)

(3), (4) insignificant

Subfunction 14,

disable/enable output

This subfunction can be used to disable output to the EGA adapter. All write jobs following a

disable are completed with "successful" status. Subfunctions 10 to 15 remain executable.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

138 Programming Manual, 07/2012, A5E03692298-01

Rules for the parameter block of subfunction 14:

● (1) Type: variable, length 1 byte; offset = 1

0 = enable output, 1 = disable output

● (2) Type: variable, length 2 bytes; offset = 2

Most significant byte

Least significant byte

Data direction

Undefined

Current display page

Output (if successful)

(3), (4) insignificant

Subfunction 15,

disable/enable input

If the "disable input" function was triggered, it is still possible to receive characters from the

keyboard and write these to an IBM-compatible keyboard buffer. However, they are no

longer transferred from the buffer. At the same time, the internal interface of the driver is

opened for external access so that you can manually fetch the characters from this buffer.

The "enable input" function closes the interface. Characters remaining in the buffer without

having been processed yet are not cleared automatically.

You can fetch these characters via the internal input interface.

Rules for the parameter block of subfunction 15:

● (1) Type: variable, length 1 byte; offset = 1

0 = enable input

1 = disable input

● (2) Type: variable, length 2 bytes; offset = 2

Most significant byte

Least significant byte

Data direction

Undefined

Current display page

Output (if successful)

(3), (4) insignificant

Subfunction 16,

activate/deactivate screen scrolling

This function can be used to enable/disable unit-related automatic screen scrolling. Cursor

correction for write jobs is discarded if screen scrolling is disabled. If a write call is executed

(03H), for example, while screen scrolling is deactivated, all characters will be output

successively at the same cursor position.

Write operations with subfunctions 7 and 8 end at the right edge of the screen. The cursor

position remains unchanged. Subfunction 16 is used, for example, to write a character to the

bottom right corner of the window without scrolling the screen.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 139

Rules for the parameter block of subfunction 16:

● (1) Type: variable, length 1 byte; offset = 1

0 = activate screen scrolling

1 = deactivate screen scrolling

● (2) Type: variable, length 2 bytes; offset = 2

Most significant byte

Least significant byte

Data direction

Undefined

Output

(3), (4) insignificant

Subfunction 17,

activate/deactivate emulation

This function can be used to activate/deactivate emulation for a specific unit.

Activation of emulation for a unit has the following effect:

New characters entered inherit the attribute of the character on the left of the current write

position.

If the current write position is at the left edge of the window, the character inherits the screen

attribute.

This facilitates, for example, SME emulation that is included with your package.

Rules for the parameter block of subfunction 17:

● (1) Type: variable, length 1 byte; offset = 1

0 = activate emulation

1 = deactivate emulation

● (2) Type: variable, length 2 bytes; offset = 2

Most significant byte

Least significant byte

Data direction

Undefined

Output

(3), (4) insignificant

Subfunction 18,

Get status

This function can be used to query the current descriptors for the respective unit(s).

Rules for the parameter block of subfunction 18:

● (1) insignificant

● (2) Type: variable, length 2 bytes; offset = 2

Most significant byte

Least significant byte

Data direction

UCD.TOPCHR,

most significant byte

UCD.TOPCHR,

least significant byte

Output

(3), (4) insignificant

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

140 Programming Manual, 07/2012, A5E03692298-01

Subfunction 19,

read/write page descriptors

This subfunction is used to read or edit the page descriptors. The descriptors have a length

of 104 bytes per unit.

Description of the descriptors:

Offset

Meaning

0 (WORD short)

Window size

Number of columns

Number of rows

A size of 0101H prevents access to this page. In this case, the top left and

bottom right corners of the window would be identical.

The number S (Z) of existing columns (rows) in the window can be

calculated as follows:

S = Sbr Stl +1, Z = Zbr Ztl +1 with Sbr, Zbr: columns, row number of the

bottom right corner of the window and Stl, Ztl columns, row number of the

top left corner of the window.

2 (WORD short)

Top left corner of the window

Column

Row

Example: Coordinates of the top left corner of the window: 0:0

4 (WORD short)

Bottom right corner of the window

Column

5 Row

Example: Coordinates of the bottom right corner of the screen: 18H:4FH.

6 (BYTE char) Color attribute for rows

This attribute is assigned to all characters of a new row (for information on

the color pallet, see "Configuration").

7 (BYTE char)

Color attribute for characters

This attribute is assigned to all characters (for information on the color

pallet, see "Configuration").

8 (WORD short)

Cursor mode

Top grid of the cursor in a character field

Bottom grid of the cursor in a character field

The row must be specified in bits 0 to 4 respectively.

10 (WORD short)

Cursor position

The cursor position is specified as absolute value.

Value page 0 = 0000H; page 1 = 0800H; page 2 = 1000H; page 3 = 1800H

12 (POINTER far)

Write position for windows

12 (WORD int)

Write position offset

The offset value relates to the page start. Each character requires two

bytes. The offset value, for example, for position row:column 1:4 is with 80

characters/row:

(1 * 80 + 4) * 2 = 168.

Write position selector

The selector values are specified in the builder session

8 bytes SME emulation

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 141

26 bytes in total for each one of the 4 pages.

104 bytes in total per unit.

Rules for the parameter block of subfunction 19:

● (1) insignificant

● (2) insignificant

● (3) This is a pointer to a buffer from which the new descriptors are to be transferred (set

function). Set this pointer to 0:0 if you want to discard this function.

● (4) This is a pointer to a buffer to which the current descriptors are transferred and that

you must provide for this purpose (get function). Set this pointer to 0:0 if you want to

discard this function.

If both pointers are unequal 0:0, the program transfers the old descriptors to the user buffer

(get function) first and then activates the new descriptors (set function).

If both pointers equal 0:0, no function is executed and the I/O operation is completed with

"successful" state.

Note

It is not checked, for example, whether or not the bottom right co

rner of the window is still in

the visible range, or whether or not the window size matches the specified corners.

5.2.4

Configuration

The DCD block (Driver Control Data table) that is identical for all drivers is created in

configuration area "Device definitions". The linking of the RMOS3 standard drivers in a

system is supported to a great extent by C function calls.

The UCD block (Unit Control Data table) has a general and a driver-specific part. For

information about the init specifications for the general part of the UCD block, refer to

chapter 2.3.10 "Unit Control Data table (UCD)" in the System Manual.

This chapter describes the driver-specific entries in the UCD blocks and lists the interrupt

routines and stack requirements for the drivers. A further topic deals with the EGA–specific

configuration of the BYT driver.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

142 Programming Manual, 07/2012, A5E03692298-01

5.2.4.1

Driver Control Data table (RmDCDStruct in RMTYPES.H)

The DCD block is created in configuration area "Device definitions". To configure the DCD

block of the BYTE driver, you can use the C function RcInitByt() that runs a default

initialization of the DCD block. See the System Manual, chapter 2.3.9 "Driver Control Data

(DCD)".

Parameters

Description

Type

Standard value

UCD

Address of the first UCD structure for this driver

int

UNITS

Number of units for this driver

char

SHR

Identification of shared controllers (0FFH if none)

char

0FFH

INIT

Entry point of the initialization routine in the driver

void NEAR *

X_BYT_INIT

SVC

RIO–SVC entry point for drivers

void NEAR *

X_BYT_SVC

FLAGS

Driver flags:

char 03H

Bit0=1:

Parallel driver

Bit1=1:

Type II driver

Bit2=0:

Initialization in the boot sequence

FMAX

Maximum function code for type II driver

char

0CH

RESERV

2 reserved bytes

char

00H, 00H

1 This value is occupied during system configuration.

5.2.4.2

Unit Control Data table (RmUCDStruct in RMTYPES.H)

The UCD block (Unit Control Data table) has a general and a driver-specific part. For

information about the init specifications for the general part of the UCD block, refer to

chapter 2.3.10 "Unit Control Data table (UCD)" in the System Manual.

Parameters

Offset

Type

Description

Note

PID

char

reserved

INTNO 1 char Number of the interrupt vector for

this unit

INT_ADR 2 void FAR * Address of the interrupt handler

routine (occupied internally)

UNS 8 short Task ID of the task started after an

unexpected input

PORT

short

Driver-specific data (120/246 bytes)

256

Total

1 See Interrupt routines of the BYT driver.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 143

5.2.4.3

Driver-specific parameters in the UCD block

The driver-specific parameters are available as of offset PORT in the UCD block. The

meaning of the various parameters is documented in the following sections.

Parameters

Offset

Type

Description

Note

UCMODE

short

Unit Control Code

PRTSEG

short

USART segment

PRTDAT

int

USART data port

PRTCMD

int

USART command port

PORT_2

int

USART extra port 2

PORT_3

int

USART extra port 3

PRTSTA

int

USART status port

STMODE

short

Status Control Mask

STARET 36 short Error Reset byte and retry

factor for USART status check

TOPCHR

short

Form feed character

TIMOUT

short

Timeout value/character

TABBUF

void FAR *

I/O transformation table

POOLID 48 char Pool ID used to allocate interim

and history buffers

POOLEN

char

Length of the interim pool

UNSCHR 50 short Start character for unexpected

task start

RECOVR

char

I/O delay value

MODEXT

553

char

Mode extension of the driver

ICOUNT

short

Number of init outputs

MOBYTE 56 short 1. Initialization output 2

.....

...

MOBYTE

254

short

nth init output

These parameters are insignificant in an EGA configuration and must be set to 0.

These parameters require special declarations for an EGA configuration (see below).

The number of initialization units is limited to 26 in an EGA configuration, because the page

configurations follow as of offset 60H in the UCD block.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

144 Programming Manual, 07/2012, A5E03692298-01

UCMODE (Unit Control Code)

Bit

Designation

Meaning

15 DP 0 = no duplex mode

1 = with duplex mode

reserved

13 HB 0 = no history memory

1 = with history memory

12 LF 0 = CR without LF

1 = CR followed by LF

USART ID:

0000 = USART 8251A

0001 = PPI 8255A w/o Strobe

0100 = SCC 8530

0101 = PPI 8255A w/ Strobe

0110 = TIMER E19/E18

1000 = EGA terminal and IBM/AT/02-compatible keyboard

1001 = UART 8250

all others are reserved

8 UC

7 PB ID for interpretation of a parameter block.

0 = unrestricted interpretation

1 = restricted or no interpretation

ID for use of a transformation table:

00 = not used

01 = used for output routines

10 = used for input routines

11 = used for I/O routines

5 TO

ID for unit type

00 = I/O device (always specify this ID for EGA units!)

01 = output device

10 = input device

11 = reserved

3 OP

USART status check

00 = no status check

01 = status check with mask in STMODE

10 = status is read and transferred in the RIO parameter block

11 = status is checked and transferred in the RIO parameter block

1 CT

0 MD ID for DIO or MMIO

0 = DIO

1 = MMIO

(this setting is ignored for EGA units. All data is output to memory. The keyboard is addressed

directly by means of the corresponding registers.)

The extended modes of the BYTE driver are configured in the most significant byte of

RECOVR!

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 145

PRTSEG (USART segment)

If MMIO is selected in UCMODE, you must specify the value of the USART segment/selector

in this parameter; otherwise, the word can be ignored.

For operation in MMIO mode, use RmCreateDescriptor to create a descriptor with the base

address of the USART (e.g. 0xDF900). This descriptor is entered as USART segment

PRTSEG in the UCD block (e.g. 0x0C0).

PRTDAT (USART data port)

If MMIO is selected in UCMODE, you must declare the address offset of the data port from

the controller at this parameter. In direct I/O mode, enter the port address of the data port.

For operation in MMIO mode, declare the offset for the generated descriptor at this

parameter (see chapter "PRTSEG (USART segment) (Page 145)")

(e.g. 0x0 for USART data port, 0x1 for USART command port,...). This means that the

USART is addressed, for example, via 0C0:00 ... 0C0:07.

PRTCMD (USART command port)

If MMIO is selected in UCMODE, you must declare the address offset of the command port

from the controller at this parameter. In direct I/O mode, enter the port address of the

command port.

For operation in MMIO mode, declare the offset for the generated descriptor at this

parameter (see chapter "PRTSEG (USART segment) (Page 145)")

(e.g. 0x0 for USART data port, 0x1 for USART command port,...). This means that the

USART is addressed, for example, via 0C0:00 ... 0C0:07.

PORT_2, PORT_3 (extra ports)

The ports are controller-specific. The necessary init information depends on the controller

that was selected in UCMODE.

PRTSTA (USART status port)

If MMIO is selected in UCMODE, you must declare the address offset of the status port from

the controller at this parameter. In direct I/O mode, enter the port address of the status port.

For operation in MMIO mode, declare the offset for the generated descriptor at this

parameter (see chapter "PRTSEG (USART segment) (Page 145)")

(e.g. 0x0 for USART data port, 0x1 for USART command port,...). This means that the

USART is addressed, for example, via 0C0:00 ... 0C0:07.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

146 Programming Manual, 07/2012, A5E03692298-01

Comments on entering port addresses

The table contains the controller-specific entries for the port addresses in the UCD table:

Controllers

PRTDAT

PRTCMD

PORT_2

PORT_3

PTRSTA

8530

DATA A/B

CMD A/B

–

CMD A

CMD B

8251

DATA

CMD

–

STS

8255 with

SW strobe

DATA OUT CMD STS BITMASK (set

and reset)

DATA IN CMD STS

8255 with

HW strobe

DATA OUT CMD STS – – CMD STS

8250 DATA MODEM CTRL LINE CTRL INTR

ENABLE

LINE STS

The following points must be kept in mind:

● When configuring I/O devices that use the PPI 8255A controller, take into account that

PRTDAT must be used for the output data port and PORT_3 for the input data port. To

enable the additional execution of the strobe/function after data output, set the

corresponding command bytes at PORT_2, whereby the least significant byte must

contain the bit mask for strobe/set, and the most significant byte must contain the bit

mask for strobe/reset.

● On the SMP–E19 and SMP–E18 modules, data output to printers is controlled by means

of a timer. This means that the corresponding timer is addressed after data was output.

Accordingly, set the timer command port at extra port 3 and the timer command word at

extra port 2. If PRTSEG contains a value unequal zero, the memory I/O method is used

for timer control, independent of UCMODE. In this case, the timer command port must

contain the relevant offset value.

● If you don't need the additional PORT_2 and PORT_3 parameters for special

configurations, you can use them for other init purposes (e.g. as port addresses for

timers).

STMODE (Status Control Mask)

If a status check (CT = 1, SW/SR <> 00) was selected in the Unit Control Code (UCMODE) ,

the BYT driver expects a value of the following meaning in STMODE:

Least significant byte:

Filter mask for selecting corresponding bits of

the status information read

Most significant byte:

Comparison mask for filtered status

information

The BYT driver checks the USART status at the end of an input request, or at the start of a

write request.

The I/O request is terminated with error if a repeated status check remains unsuccessful in

accordance with the number configured in STARET (least significant byte), i.e. the filtered

value of the comparison mask mismatches the status information read. The BYT driver

resets the controller status to the value configured in STARET (most significant byte) and

returns the I/O request with error code (–5) in the primary status byte.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 147

An additional error message is output if the error logger task is configured.

Note

On timeout of the I/O request, no status check is performed at the end of an input or write

request and an error code (

-3) is returned in the primary status byte.

STARET (Status Reset)

The status check (STMODE) is repeated several times. The number of repetitions is stored

in the least significant byte of STARET. In error case, the BYT driver uses the value

configured in STARET (most significant byte) to run the necessary error reset routine of the

corresponding controller.

Take the following into account when using EGA units:

● Least significant byte:

SRB minimum, i.e. the minimum number of SRBs that must still be available. If resources

fall short of this figure, the driver suspends all outputs until a sufficient number of SRBs is

available again to the system.

No output requests will be lost in this phase.

Rule for the SRB_NUM value specified in the software configuration:

SRB minimum + x < SRB_NUM ≤ 255, with x being the value to calculate. It is

recommended to set a value of approximately 180 for SRB_NUM (depending on x).

● Most significant byte:

reserved (must be set to 0)

TOPCHR (form feed characters)

The BYT driver expects the corresponding control characters in this field to execute the

"form feed/clear" (0BH) function. The field is set to zero if the unit does not support this

function. A maximum of two control characters can be specified, whereby control character 1

is set in the least significant byte and control character 2represents the most significant byte

for form feed or clear screen.

Note

For EGA units:

The meaning of this parameter is transformed into a unit control word.

The most significant byte contains the unit-specific information (local descriptor) for each

EGA unit.

The least significant byte is the same (global descriptor) for all EGA units (main units and

subunits).

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

148 Programming Manual, 07/2012, A5E03692298-01

Bit

Designation

Meaning

Unit number

0 = main unit

1 3 = subunits

All units must be configured in direct succession, with the unit numbers to be assigned in

ascending order.

14 UN

13 SD Scroll screen

SD = 0: activate

SD = 1: deactivate

12 EI Emulation

EE = 0: activate

EE = 1: deactivate

Start Page: page displayed at startup. This page must be the same for all units.

Current write page (page 0 ... page 3)

7 D1 Input

D1 = 0: enable

D1 = 1: disable

6 D0 Output

D0 = 0: enable

D0 = 1: disable

Number of the unit the keyboard is assigned to (0 ‘number of units’)

Number of units (0 ... 3)

Current display page (page 0 … page 3)

TIMOUT value/character

This value is only valid for write requests and only on the condition that no timeout value was

assigned to the unit in the reservation or that the unit is not reserved. The BYT driver

multiplies the expected value in milliseconds by the total number of characters to output for

an output request and uses the result as timeout value. TIMOUT has a range of values from

0 to 0FFFH. Bits 12 to15 are reserved and must be set to zero.

A zero value suppresses time monitoring if the reservation timeout value was also set to zero

in the reservation request.

Note

For EGA units:

This value is not

defined for EGA units and must be set to –1.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 149

TABBUF (I/O transformation table)

The BYT driver interprets this address as pointer to a 256–byte field if a transformation table

must be provided for the unit. The BYT driver uses the transformation table to run input

and/or output routines, depending on the bits set in UCMODE.

The input or output value (0 to 7FH) is used to calculate the offset value (= I/O value * 2) in

the transformation table. The BYT driver fetches the interpretation value from the least

significant byte of the table word when running input routines. The content of the most

significant value of the table word is used accordingly for the output routines. Transformation

tables can therefore be used to assign other values to the ASCII control functions of the BYT

driver.

Comment:

If you use transformation tables for output requests, you have to take into account that

ESCAPE (1BH), limiter characters (0FFH) and filler characters (0FEH) are used by the BYT

driver as standard values.

Example:

In the following transformation table, an input value 0 is interpreted for an input value 1, while

an output value 1 corresponds to interpretation value 0.

Input value

Interpretation value for input

Interpretation value for output

Offset table

Least significant byte

Most significant byte

...

255

POOLID (pool ID for the interim buffer)

This value configures the buffer mode. The byte specifies the memory pool (pool ID) from

which the BYT driver may request an interim buffer. Static memory pool IDs are restricted to

values from 00 to 31. No interim buffer will be used if the byte value is 0FFH.

Note

For EGA units:

A pool of appropriate size must be configured for the EGA units. The pool configured

in the

least significant byte is loaded with additional 64K page management data for each EGA

unit.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

150 Programming Manual, 07/2012, A5E03692298-01

POOLEN

The value determines the size of the interim buffer to use (01H to 0FFH, or 1 to 255 bytes).

No interim buffer will be requested if the value is zero. When setting the history mode bit in

UCMODE (most significant byte), you need to allocate additional memory space of 256 bytes

from the same memory pool.

Note

The BYT driver requests interim buffer by running XALOC (internal system routine) that

pecifies a minimum request length of 4 bytes.

UNSCHR (Task start due to unexpected input)

The BYT driver expects the corresponding control characters in this field to run the "Task

start due to unexpected input" function. You can define two start characters (least and most

significant bytes).

Set this field to zero value if this function is discarded for the BYT driver. All unexpected

input characters (exception: <CTRL>+<Q>, <CTRL>+<S>, and abort characters) are

compared with the two start characters in UNSCHR (if unequal zero); the task start is

initiated if the values match. The 0FFFFH setting always and without exception triggers the

"Task start due to unexpected input" function whenever an unexpected input character is

detected. The ID of the task to start is specified in UNS, in the general parameter area of the

UCD block.

In addition, the BYT driver sets the following values at status dword XSTATUS:

BYTE char

XSTATUS + 00

Driver ID

(EAX register)

BYTE char

XSTATUS + 01

Device ID

(EAX register)

BYTE char

XSTATUS + 02

00H

(EAX register)

BYTE char

XSTATUS + 03

00H

(EAX register)

BYTE char

XSTATUS + 04

Start character

(EBX register)

BYTE char

XSTATUS + 05

Current count from the

interim buffer prior to

task start

(EBX register)

BYTE char

XSTATUS + 06

00H

(EBX register)

BYTE char

XSTATUS + 07

00H

(EBX register)

The XSTATUS parameters are transferred at task start to the (E)AX and (E)BX registers of

the processor. The task which is started due to an unexpected input can evaluate the start

character by reading the start character in the (E)BX register and possibly start additional

tasks.

RECOVR (recovery time)

The BYT driver uses this parameter internally to set a delay between two successive I/O

errors. The waiting time (recovery time) to be maintained is specified in the description of the

controller. The delay value depends on the processor used and on its clock frequency.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 151

MODEXT (extended modes)

This byte is used to set further modes of the BYTE driver.

Bit

Designation

Meaning

Reserved (0)

Selection of the control character table for adaptation to the terminal type:

00: Table 0

01: Table 1

10: Table 2

11: Table 3

4 T0

Reserved (0)

1 RQX XON/XOFF handling of expected characters

0: no XON/XOFF protocol (standard mode)

1: XON/XOFF protocol (special mode)

0 RWX Operating mode

0: Terminal mode (normal mode)

1: Transparent mode (special mode)

In transparent mode, all characters including control characters are transferred to the receive

buffer of the user in the read operation. This procedure is also applied to characters that are

written to the interim buffer. With expected characters the check for XON/XOFF is set using

the RQX bit. If RQX=0, expected characters are not checked for XON/XOFF. If RQX=1,

expected characters are also checked for XON/XOFF and evaluated. However, these

characters are transferred simultaneously to the user buffer.

ICOUNT

This value defines the number of init units (MOBYTE). The system provides 99 init units. If

the value at parameter IOCOUNT is higher, the program initializes a maximum of 99 units.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

152 Programming Manual, 07/2012, A5E03692298-01

MOBYTE (init output)

This value corresponds to an init unit and is interpreted by the BYT driver as follows:

Least significant byte:

Init byte or mode byte to be output.

Most significant byte:

Bits 8 to 13:

ID for the output port with the following meaning:

Identifier

USART port

Parameters

Data port

PRTDAT

Command port

PRTCMD

Extra port 2

PORT_2

Extra port 3

PORT_3

Status port

PRTSTA

or offset for PRTDAT.

Bit 14:

Value is output.

Value is read (certain controllers are initialized by reading registers).

Bit 15:

Bits 8 to 13 are interpreted as ID.

Bits 8 to 13 are interpreted as offset of PRTDAT (actual address

equals PRTDAT + Bit 8 to13)

ID values greater than 4 are interpreted as ID 0. The number of MOBYTEs necessary for

controller initialization is declared at parameter ICOUNT.

Note

For EGA units:

You may not configure the parameters for extra ports and status p

orts (PORT_2, PORT_3

and PRTSTA). Always set these parameters to 0.

The number of init units is limited to 20, because the page configuration is now entered as of

offset 60H in the block.

Page configuration (only for EGA units)

The options for access to the 4 pages and the color attributes are configured as of offset 60H

in the UCD block. For each of the 4 pages the following must be specified:

● The top left corner of the window on page n

● The bottom right corner of the window on page n (the unit is prevented from writing to this

page if both corners have the same coordinate).

● The page background color (this attribute is assigned to each character of the new row

that appears when you scroll the screen.)

● The color for the characters on this page (this attribute is assigned to each character that

is displayed on the page).

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 153

Bit

Designation

Meaning

Background color

Foreground color

dec

hex

Foreground color

Background color

Flashing

Black

Blue

Green

Cyan

Red

Magenta

Brown

Yellow

Light gray

White

Dark gray

Black

Yes

Light blue

Blue

Yes

10 A Light green Green Yes

Light green

Cyan

Yes

Light red

Red

Yes

Light magenta

Magenta

Yes

Yellow

Yes

White

Yes

The settings in the "flashing" field relate to the background color.

Example:

Attribute 047H as character attribute displays light-gray characters on a red background.

Attribute 0C7H sets additional flashing of the character.

5.2.4.4

Interrupt routines of the BYT driver

The BYT driver provides 3 entry point addresses for its interrupt handler routines that are

declared as PUBLIC symbols with the following meaning:

X_BYT_RCVR_INTR:

Interrupt handler routine for input units (receiver for I/O devices) (e.g. 8255, 8251).

X_BYT_TMTR_INTR:

Interrupt handler routine for output units (transmitter for I/O devices) (e.g. 8251, 8255).

X_BYT_COM_INTR:

Entry point address for controllers (I/O devices) with shared interrupt for all actions (e.g.

8530, 8250).

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

154 Programming Manual, 07/2012, A5E03692298-01

Note

For EGA units:

Observe the information provid

ed in chapter "EGA–specific configuration (Page 155)".

5.2.4.5

Configuring the control characters in Rinitbyt.c

The BYT driver needs the RInitbyt.C file in directory APL_ETC for interpretation of the control

characters in order to execute specific control functions. You can assign a control character

(keyboard value) to each control function that is specified in this file. Control functions are

ignored if their associated control character is set to zero. The content of Rinitbyt.C and the

default assignments are shown below. In Rinitbyt.C, you may configure up to four tables for

terminals with different control character assignments. The tables are assigned to the unit in

MODEXT.

The following listing of ASCII values (key assignments) reflect a possible assignment of

control characters to execution of functions. You can edit these proposed values in

Rinitbyt.C.

Keys

ASCII value

Function

CTRL–C

03H

Set internal abort ID to TRUE (0FFH)

RETURN

0DH

Complete entry with output echo

CTRL–Z

1AH

Input terminator without echo

CTRL–X

18H

Delete last entry up to cursor position and reset cursor

RUBOUT

7FH

Delete last character entered

08H

Backspace and delete character

CTRL–N

0EH

Output input successor/history

CTRL–P

10H

Output input predecessor/history

CTRL–I

09H

Insert blank at cursor position

CTRL–F 09H Delete character at cursor position

CTRL–Y

19H

Delete previous entry as of cursor position

CTRL–B

02H

Set cursor to the start of the input buffer

CTRL–E

05H

Set cursor to the end of the input buffer

CTRL–R

12H

Shift cursor right by one character

CTRL–L

0CH

Shift cursor left by one character

HOME

1DH

Clear screen

0AH

Line feed

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 155

5.2.4.6

EGA–specific configuration

Software requirements

In addition to the public symbols, the BYT driver uses the following symbols for EGA units:

(The driver needs these for internal operations. They are only of interest to the user in that

they should never be used to program application tasks.)

X_BYT_EGA_INIT

X_BYT_KEYBOARD_DISABLE

X_BYT_KEYBOARD_ENABLE

X_BYT_KEYBOARD_INT

X_BYT_KBD_REC_INT

X_EGA_FUNCTION

X_KBD_CHAR_CODES

X_KBD_HIGH_CODE

X_KBD_CODE_VER

X_EGA_EMULATION

These are supplemented with the following public symbols from the Ribtega.c configuration

file of the BYT driver:

X_BYT_SCAN_SPECI_TAB

Table for EGA–specific control characters

X_BYT_INT_SYS

Number of the interrupt vector

X_BYT_CTRL_ALT_DEL

Number of the interrupt vector

X_RESET_INT

Interrupt routine

X_SYS_REQ_INT

Interrupt routine

The BYT driver uses data segment RM3_DATA (RM3).

Shared interrupt handler

You must install an interrupt handler for the IBM–compatible keyboard and enter the

corresponding interrupt vector in the interrupt table (receiver interrupt).

Since driver output to the EGA adapter is executed in RAM, it is not necessary to install a

transmitter interrupt.

Moreover, the driver triggers internal software interrupts on keyboard input

CONTROL+ALT+DELETE or SYS–REQ. Corresponding routines must be implemented for

these interrupts in the interrupt table. You can always access the actual routines in

Ribtega.c. The interrupt vector numbers can be selected as required. Take into account that

these may be overwritten at RMOS3 system restart if set to special values.

Interrupt X_BYT_KBD_REC_INT should only be entered to open the internal INPUT

interface.

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

156 Programming Manual, 07/2012, A5E03692298-01

5.2.4.7

Ribtega.c

The following settings:

OUTPUT-CHARACTERS FOR CURSOR MOVMENT RIGHT (SCREEN)

OUTPUT-CHARACTERS FOR CURSOR MOVMENT LEFT (SCREEN)

OUTPUT-CHARACTERS FOR CLEAR SCREEN

do not apply to the EGA adapter, but remain valid for all other terminals.

You may also customize the assignment of ASCII codes to keys with scan codes 47H to

53H. Keys included: HOME, CURSOR UP, PAGE DOWN, CURSOR LEFT, CURSOR

RIGHT, END, CURSOR DOWN, PAGE DOWN, INSERT and DELETE

The following diagram shows the assignment of scan codes to the keys (e.g. on a US

keyboard):

Figure 5-10 Assigning scan codes to the individual keys

char const _FAR x_byt_scan_speci_tab[] =

{

0x02, /* scan code 47 : HOME */

0x0b, /* scan code 48 : CURSOR UP */

0x1d, /* scan code 49 : PG UP (used for clear screen) */

0x00, /* scan code 4a : not used */

0x1f, /* scan code 4b : CURSOR LEFT */

0x00, /* scan code 4c : not used */

0x0c, /* scan code 4d : CURSOR RIGHT */

0x00, /* scan code 4e : not used */

0x05, /* scan code 4f : END */

0x0a, /* scan code 50 : CURSOR DOWN */

0x00, /* scan code 51 : not used (PG DN) */

0x09, /* scan code 52 : INS */

0x7f /* scan code 53 : DEL */

};

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 157

Keys assigned ASCII code 0 cannot be accessed with normal read calls.

The assigned ASCII codes are conditioned using the X_BYT_SPECI_TAB table. This means,

for example, that:

● The DEL key is assigned ASCII code 07FH.

● ASCII code 07FH in the X_BYT_SPECI_TAB table is assigned to the DELETE LEFT

CHAR function.

● This means that the driver will now execute this function, because the program first

assigned ASCII 07FH to the key scan code, and then branched to the DELETE function

based on the X_BYT_SPECI_TAB table.

Scan codes 4AH, 4CH and 4EH must be set to 0.

You also need to declare the interrupt vector numbers for both interrupt routines that are

triggered by keyboard input CONTROL+ALT+DELETE and SYS–REQ. These numbers must

always match the settings in the software configuration.

You can now customize these interrupt routines to suit special requirements. You can always

access the code of these routines in Ribtega.C. However, you are strongly advised to

exercise particular care when modifying these routines, because they represent driver

elements. Observe the following rules in particular:

● The driver is in S state at the call of the routines

● All registers used in these routines must be retrieved.

ASCII codes

Table 5- 9 ASCII characters

ASCII characters

Value

Function

ASCII–NULL–SPACE

000H

Whitespace for new lines (only for EGA units).

ASCII–CIRCUMFLEX 05EH All are mapped to values from 0 to 255 in

accordance with the character table (not valid for

EGA units)

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

158 Programming Manual, 07/2012, A5E03692298-01

Figure 5-11 Character table from 0 to 255 (0H to FFH), part 1

Notes

x1 = Blank (000H) x8 = Star

x2 = Dot x9 = Arrow right

x3 = Inverse x2 x10 = Arrow left

x4 = Circle x11 = Triangle

x5 = Inverse x4 x12 = Blank (020H)

x6 = One note x13 = Open triangle

x7 = Two notes

Functions and configuration of the basic I/O system

5.2 BYT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 159

Figure 5-12 Character table from 0 to 255 (0H to FFH), part 2

Note:

x14 = Blank (0FFH)

5.2.4.8 Stack requirements of the BYT driver

BYT driver without executable EGA functions BYT driver with executable EGA functions

S state: 70 bytes S state: 140 bytes

I state: 76 bytes I state: 76 bytes

DI state: – DI state: –

The specified values include stack requirements for RMOS2 driver calls (e.g. XIODONE).

Functions and configuration of the basic I/O system

5.3 CRT driver

RMOS3 V3.50 Reference Manual Part II

160 Programming Manual, 07/2012, A5E03692298-01

5.3 CRT driver

5.3.1 Properties

Driver for several terminals

The CRT driver is a type II driver (parallel driver) for simultaneous management of several

terminals. The terminals (units) are controlled via parallel (Centronics) or serial interface (e.g.

V.24). The CRT driver can be customized for operation with all standard I/O controllers

(8251A, 8530, 8250). A maximum of 255 units is supported. The driver operates in half

duplex mode that excludes simultaneous transmission and receive operations.

One or several interrupt vectors are assigned to each connected unit. Prerequisite is a

special wiring between the interrupt outputs of the unit and the inputs of an interrupt

controller.

The driver source code is available in directory APL_DEV\CRT.

5.3.1.1 Sequence of functions

The nucleus verifies the call parameters before it transfers the I/O request that was initiated

by RmIO system call to the corresponding driver. If incorrect parameters are found, the

nucleus terminates the I/O request and outputs a corresponding return value. Once it has

accepted the I/O request, the nucleus resets the event flag bits that were defined at the

FlagID and FlagMask parameters and then transfers the request to the driver. The driver will

now execute the job. I/O job processing by the driver is known as I/O operation. At the end of

an I/O operation, the driver saves the current status that provides information about the

progress of the operation to an 8-byte status field. Control is then returned to the nucleus

that sets the event flag bits declared in the FlagID and FlagMask parameters.

Synchronization of task processing on completion of the RmIO system call is initiated by the

RmGetFlag system calls based on the event flags set in FlagID and FlagMask, by setting the

wait bit at parameter Function , or by polling the primary status byte.

5.3.1.2 Timeout handling

You can avoid system deadlocks by setting a time monitor for I/O requests.

A timeout is restricted to write jobs; the time interval is calculated based on the buffer size

and a timeout value per character. This timeout method is used if UCD.TIMOUT was not set

to zero in the software compilation.

Functions and configuration of the basic I/O system

5.3 CRT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 161

Note

When timeouts are used, the status field must always be checked on completion of RmIO

SVCs by the CRT driver. Each timeout leads to the loss of information that possibly

demands separate handling by the application.

5.3.1.3 Control characters

Usually, only the unexpected characters are treated as control characters. All characters

pending for a read job or for operation in transparent mode are treated as expected

characters. You can prevent any XON/XOFF protocol errors by including a verification of

XON/XOFF characters on receiving expected characters in programming.

● XOFF (<CTRL>+<S>)

Unexpected character:

An active output operation is interrupted until XON has been received.

Expected character:

The character will be passed to the user buffer (echo ^S). An echo is not executed for

transparent reading.

● XON (<CTRL>+<Q>)

Unexpected character:

Any XOFF is revoked. XON and XOFF define a protocol in the CRT driver, which can be

used to synchronize the speed of different units.

Expected character:

The character will be passed to the user buffer (echo ^Q). An echo is not executed for

transparent reading.

● <CTRL>+<X> (CANCEL)

Unexpected character:

Any active output operation (write job) is aborted and terminated.

Expected character:

The input buffer is cleared (including the echoed characters at the terminal). The read job

pending is retained (only for reading with echo). The character for a transparent read job

is transferred to the user buffer.

● Task start character

Unexpected character:

A task can be started by two different control characters (task start due to unexpected

input). The characters are configured in the UCD block of the unit (UCD.UNSCHR).

Expected character:

The character will be copied to the user buffer.

Functions and configuration of the basic I/O system

5.3 CRT driver

RMOS3 V3.50 Reference Manual Part II

162 Programming Manual, 07/2012, A5E03692298-01

5.3.1.4 Opcodes of the CRT driver (bits 0 to 3)

The CRT driver executes the following opcodes, depending on the configured unit type (see

UCD.TYPE).

00H Reserve unit (CRT_RESERVE)

01H Release unit (CRT_RELEASE)

02H Read (CRT_READ)

03H Write (CRT_WRITE)

04H Write (CRT_WRITE)

05H Read character in transparent mode (CRT_ONE_XREAD)

06H Write and read in transparent mode (CRT_WRT_XREAD)

07H Write and read (CRT_WRT_READ)

08H Skip line (CRT_SKIP_LINE)

09H Clear screen (CRT_FORM_FEED)

0AH Read character to buffer in transparent mode (CRT_HSFS_XREAD)

0BH Write character from buffer (CRT_HSFS_WRT)

0CH Redefine and initialize the unit (CRT_CREATE_NEW)

On detection of an invalid opcode, the CRT driver stops execution of I/O requests and

returns an error code (–1) in the primary status byte. For more information on the handling of

opcodes, refer to the next chapters.

5.3.2 RmIO interface

The parameters of SVC RmIO that are of importance for the description of driver properties

are listed below:

Function, bit 3..0 Function code of the selected driver function

pState Status pointer that reports internal states of

the driver.

pParam Points to a data block with other function-

specific parameters.

Functions and configuration of the basic I/O system

5.3 CRT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 163

5.3.2.1 Function parameter

This parameter sets the selected CRT driver functions (bit 0..3) and controls the sequence of

the driver function.

Bit Values Function

7 Preemptive bit

0 I/O request in the order of

priority

1 Set I/O request to the start of

the queue

6 Wait bit

1 Wait for completion of the I/O

operation

0 No waiting

5 reserved

4 reserved

3..0 00H..0CH Valid opcode

0DH..0FH reserved

Opcode (bits 0 to 3)

The CRT driver executes the following function codes, depending on the configured unit type

(see UCD.TYPE).

00H Reserve unit (CRT_RESERVE)

01H Release unit (CRT_RELEASE)

02H Read (CRT_READ)

03H Write (CRT_WRITE)

04H Write (CRT_WRITE)

05H Read character in transparent mode (CRT_ONE_XREAD)

06H Write and read in transparent mode (CRT_WRT_XREAD)

07H Write and read (CRT_WRT_READ)

08H Skip line (CRT_SKIP_LINE)

09H Clear screen (CRT_FORM_FEED)

0AH Read character to buffer in transparent mode (CRT_HSFS_XREAD)

0BH Write character from buffer (CRT_HSFS_WRT)

0CH Redefine and initialize the unit (CRT_CREATE_NEW)

On detection of an invalid function code, the CRT driver stops execution of I/O requests and

returns an error code (–1) in the primary status byte. For more information on the handling of

the individual function codes, refer to the next section.

Functions and configuration of the basic I/O system

5.3 CRT driver

RMOS3 V3.50 Reference Manual Part II

164 Programming Manual, 07/2012, A5E03692298-01

5.3.2.2 Parameter pState

SVC RmIO uses parameter pState to pass a pointer to an 8-byte field. The driver writes the

status information to this field on completion of the corresponding job. It is advisable to

evaluate the status field on completion of each job. It is not sufficient to check an RmIO only

by the return value, because this only contains information about the OK state of parameters

saved by the nucleus and which cannot be used to derive the RmIO status.

The first byte is the primary status byte and the second is the secondary status byte, while

the next bytes form the 2nd, 3rd and 4th status word. The following table describes the

codes for the primary and secondary status bytes, as well as for the 2nd, 3rd, and 4th status

word for the CRT driver.

If several RmIO calls are handled in parallel (bit 6 in parameter Function), each pending call

must be assigned a unique parameter field for the transfer of parameters, because the

nucleus only copies the pointer, but not the actual field at the RmIO call.

Primary

status byte

Secondary

status byte

2nd status word 3rd and 4th

status word

Meaning

0 00H 0000H 0000 0000H I/O request is queued.

1 00H 0000H 0000 0000H Busy processing the I/O request.

2 1 2 0000 0000H I/O request successfully completed.

–1 00H 0000H 0000 0000H I/O request rejected due to invalid parameterization

–2 00H 0000H 0000 0000H Reserve/release operation was not executed, as the

unit is already resevered/not reserved.

–3 1 2 0000 0000H I/O request terminated due to timeout

–4 0000 0000H reserved

–5 0000 0000H reserved

–6 1 2 0000 0000H I/O request terminated by External Change Interrupt

at the SCC 8530 block

–7 1 2 0000 0000H I/O request terminated by Special Receive Interrupt

at the SCC 8530 block

1 The last byte read or transferred is entered, depending on the I/O request.

2 Number of actually transferred bytes.

Functions and configuration of the basic I/O system

5.3 CRT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 165

5.3.2.3 Parameter pParam

SVC RmIO uses parameter pParam to pass a pointer to a 20-byte field. This field must be

initialized prior to the call, depending on the selected CRT driver function (e.g. read). The

respective meaning of the bytes of the parameter block is explained in the description of

CRT driver functions. Always set reserved parameters to zero.

Type Offset Description Note

POINTER far 0 0 Offset/segment of the output buffer or

input request text

WORD int 6 6 Length of the output buffer or input

request text

POINTER far 10 10 Offset/segment of the input buffer or

transformation table

WORD int 16 Length of the input buffer or

transformation table

20 20 Total scope

1 The drivers always use the same segment value to execute I/O operations, which means that

changes to the segment value are ignored in the case of offset overrun (FFFFH..0H).

5.3.3 Opcodes of the CRT driver

5.3.3.1 Reserve unit (CRT_RESERVE)

Opcode: 00H CRT_RESERVE

Parameter block: None

This function reserves the unit specified in the RmIO (unit_id) exclusively for I/O requests of

the calling task. I/O requests of other tasks are accepted, but not executed until the unit has

been released. I/O requests with set preemptive bit form an exception.

I/O requests to a reserved unit are processed in a fixed order:

● Calls with set preemptive bit in chronological order

● Calls of the task that has reserved the unit in chronological order

● Calls of other tasks in the order of priority after the unit has been released

If a task attempts to once again reserve a unit that has not yet been released, an error

message (–2) is returned in the primary status byte. The previous reservation is retained.

Functions and configuration of the basic I/O system

5.3 CRT driver

RMOS3 V3.50 Reference Manual Part II

166 Programming Manual, 07/2012, A5E03692298-01

5.3.3.2 Release unit (CRT_RELEASE)

Opcode: 01H CRT_RELEASE

Parameter block: None

This function revokes the reservation of the unit specified in RmIO (unit_id). I/O requests

that were blocked due to the reserved state are now executed in the order of their priority. If

the task attempts to release a unit it has not reserved, or which was already released, error

code (–2) is returned in the primary status byte.

5.3.3.3 Read (CRT_READ)

Opcode: 02H CRT_READ

Parameter block: 20 bytes

This function transfers characters from an I/O device to a user-defined input buffer with echo

mode. The length and address of the user buffer are transferred in the parameter block. The

length of the input buffer corresponds to the maximum number of characters to be read. With

zero user buffer length, the input request is terminated without having been processed and

without error message.

The parameter block for read requests must have the following structure:

Type Offset Description Note

POINTER far 0 reserved

WORD int 6 reserved

POINTER far 10 Address of the input buffer

WORD int 16 Length of the input buffer

The characters entered on the keyboard (masked with 7FH) are saved to the user buffer and

displayed as echo on the terminal. The CRT driver adds the value 40H to characters that

cannot be mapped (input value less than 20H, or greater than 7FH), and the echo is output

(masked with 7FH) along with the circumflex (^).

Terminating the read operation

The read operation is terminated at the following conditions:

1. Carriage return characters (CR, 0DH)

2. Input terminators (CTRL Z, 1AH)

3. Maximum buffer length reached

On completion of a read request, the secondary status byte receives the last character read

and the second status word receives the number of bytes actually read. The carriage return

characters (CR), as well the line feed characters (LF) in line feed mode, are included in the

count. CR and LF are saved to the input buffer, while the latter is only saved in line feed

mode and if sufficient space is available in the input buffer. After CR, the following output

appears on the screen:

Carriage return CR (0DH)

Line feed (only in line feed mode) LF (0AH)

Functions and configuration of the basic I/O system

5.3 CRT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 167

In contrast, input of a terminator character will not generate echo output or change the cursor

position on the screen, but the character is also saved to the input buffer.

Two further control characters are available for input:

Delete key (DEL): The last character entered is cleared from the buffer and on the screen

CTRL X: The last entry is cleared from the buffer (and screen). The RmIO

remains open.

5.3.3.4 Write (CRT_WRITE)

Opcode: 03H CRT_WRITE

Parameter block: 20 bytes

This function transfers characters from a user-defined output buffer to a terminal. The length

and address of the output buffer are transferred in the parameter block. The length of the

output buffer corresponds to the maximum number of characters to write. With zero output

buffer length, the write request is terminated without having been processed and without

error message.

Parameter block for write request:

Type Offset Description Note

POINTER far 0 Address of the output buffer

WORD int 6 Length of the output buffer

POINTER far 10 reserved

WORD int 16 reserved

Terminating the write operation

The write operation is terminated under the following conditions:

1. Null byte (WRITE_TERMINATOR) detected

2. The specified number of characters was output

3. Timeout expired

On completion of the RmIO , the secondary status byte contains the last character output,

while the second status word contains the number of bytes actually transferred.

5.3.3.5 Write (CRT_WRITE)

Opcode: 04H CRT_WRITE

Parameter block: 20 bytes

This function is identical with opcode 03.

Functions and configuration of the basic I/O system

5.3 CRT driver

RMOS3 V3.50 Reference Manual Part II

168 Programming Manual, 07/2012, A5E03692298-01

5.3.3.6 Read character in transparent mode (CRT_ONE_XREAD)

Opcode: 05H CRT_ONE_XREAD

Parameter block: None

This function reads a single character without echo output. Each character input or keyboard

function, is transferred with its binary value to the secondary status byte and therefore

terminates the input request. The second status word that indicates the number of actually

transferred bytes will then contain the value 1.

5.3.3.7 Write and read in transparent mode (CRT_WRT_XREAD)

Opcode: 06H CRT_WRT_XREAD

Parameter block: 20 bytes

The CRT driver transfers characters from a user-defined output bufer to an I/O device and

then expects an input character from this unit. The length and address of the I/O buffers are

transferred in the parameter block.

Type Offset Description Note

POINTER far 0 Address of the output buffer

WORD int 6 Length of the output buffer

POINTER far 10 Address of the input buffer

WORD int 16 Length of the input buffer

With zero output buffer length, the write operation is ignored and only the read operation is

processed. No read operation is initiated at zero length of the input buffer. Character output

is subject to the same conditions as for function 03. In contrast to function 02, the following

restrictions must be taken into account for character input:

● Input characters do not generate echoes on the screen.

● Terminators and control characters have no further influence and are also transferred to

the input buffer.

● The input operation is not terminated until the maximum length of the input buffer has

been reached.

The conclusion of the I/O request corresponds to that of function 02 in terms of the

secondary status byte. The function is not terminated until the read call is completed.

Functions and configuration of the basic I/O system

5.3 CRT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 169

5.3.3.8 Write and read (CRT_WRT_READ)

Opcode: 07H CRT_WRT_READ

Parameter block: 20 bytes

This function corresponds to a combination of write and read operation. First, the program

executes the output operation, and secondly the input operation.

Type Offset Description Note

POINTER far 0 Address of the output buffer

WORD int 6 Length of the output buffer

POINTER far 10 Address of the input buffer

WORD int 16 Length of the input buffer

With zero output buffer length, the write operation is ignored and only the read operation is

processed. No read operation is initiated at zero length of the input buffer. The write

operation is subject to the same conditions as for function 03. Reading corresponds to

function 02.

On completion of the I/O request, the secondary status byte contains the last character input,

while the second status word contains the number of input bytes actually transferred.

5.3.3.9 Line feed/skip line (CRT_SKIP_LINE)

Opcode: 08H CRT_SKIP_LINE

Parameter block: 20 bytes

This function executes a carriage return/line feed CR/LF on the output unit. The number of

CR/LF operations is defined in the parameter block. No CR/LF is executed if the value

equals zero. The Carriage Return (0DH) and Line Feed (0AH) characters are output for the

CR/LF operation. With normal completion, the second status word contains twice the number

of CR/LFs that were specified in the parameter block and executed (2 characters per feed).

Type Offset Description Note

POINTER far 0 reserved

WORD int 6 Number of carriage returns/line feeds

POINTER far 10 reserved

WORD int 16 reserved

5.3.3.10 Form feed/clear screen (CRT_FORM_FEED)

Opcode: 09H CRT_FORM_FEED

Parameter block: none

This function executes a form feed on the output device, or clears the screen. The necessary

control characters are obtained from the UCD block (UCD.TOPCHR). This application must

be supported by the hardware of the output device.

Functions and configuration of the basic I/O system

5.3 CRT driver

RMOS3 V3.50 Reference Manual Part II

170 Programming Manual, 07/2012, A5E03692298-01

5.3.3.11 Read character in transparent mode (CRT_HSFS_XREAD)

Opcode: 0AH CRT_HSFS_XREAD

Parameter block: 20 bytes

This function corresponds to function 05, with the exception that the character that was read

is not returned in the secondary status byte, but in the user buffer. The parameter block to

initialize prior to the call has the following structure:

Type Offset Description Note

POINTER far 0 Address of the input buffer

WORD int 6 reserved

POINTER far 10 reserved

WORD int 16 reserved

5.3.3.12 Write character (CRT_HSFS_WRITE)

Opcode: 0BH CRT_HSFS_WRITE

Parameter block: 20 bytes

This function transfers a single character to the output unit. The parameter block to initialize

prior to the call has the following structure:

Type Offset Description Note

POINTER far 0 Address of the output character

WORD int 6 reserved

POINTER far 10 reserved

WORD int 16 reserved

5.3.3.13 Redefine unit (CRT_CREATE_NEW)

Opcode: 0CH CRT_CREATE_NEW

Parameter block: 20 bytes

This function is used to re-initialize a unit assigned to the driver, or the controller of this unit,

and/or to read the current operating parameters of the unit to a user buffer. Meaning of the

parameter block:

Type Offset Description Note

POINTER far 0 Address of the UCD buffer

WORD int 6 reserved

POINTER far 10 Address of the input buffer

WORD int 16 Length of the input buffer

Functions and configuration of the basic I/O system

5.3 CRT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 171

The data structure of the UCD buffer is similar to that of a UCD block as of parameter

UCD.UCMODE. The content must be initialized prior to the system call (see system

configuration) and is copied by the system call. Only the operating parameters are read if the

address of the UCD buffer equals 0:0. With address and length of the input buffer unequal

zero, a copy of the current parameter definition of the unit is saved to the input buffer.

Depending on the length setting for the input buffer, the first 16 words are fetched from the

UCB parameters, while the remaining words are taken from the corresponding UCD

parameters as of UCD.ICOUNT. The program first executes the read request if a

simultaneous re-initialization request is pending.

5.3.3.14 Keyboard control characters for I/O devices

Keys

SCII value Function

CTRL Q 11H Cancel output lock

CTRL S 13H Stop current output operation (output lock)

CTRL X 18H Delete current I/O data

CTRL Z 1AH Terminate input

RUBOUT 7FH Delete last character entered

ESCAPE 1BH Task start due to unexpected input

CTRL D 04H Task start due to unexpected input

Comment:

Characters for task start due to unexpected input can be customized.

5.3.3.15 ASCII codes used by the CRT DRIVER

SCII characters Value Function

CTRL Q 11H Cancel output lock

ASCII CR 0DH Line end character (carriage return)

ASCII LF 0AH Line feed (new line)

ASCII SPACE 20H Whitespace (delete character)

CURSOR LEFT 08H Shift screen position pointer left by one character

ASCII CIRCUMFLEX 5EH Additional ID for characters that cannot be displayed (^)

Functions and configuration of the basic I/O system

5.3 CRT driver

RMOS3 V3.50 Reference Manual Part II

172 Programming Manual, 07/2012, A5E03692298-01

5.3.4 Configuration

5.3.4.1 Driver control data table (DCD)

The DCD block is created in configuration area "Device definitions". To configure the DCD

block of the CRT2 driver, you can use the C function RcInitCRT() that runs a default

initialization of the DCD block. See the System Manual, chapter 2.3.9 "Driver Control Data

(DCD)".

Parameters Description Type Standard value

UCD Address of the first UCD structure for this

driver

int 1

UNITS Number of units for this driver char 1

SHR Identification of shared controllers (0FFH if

none)

char 0FFH 1

INIT Entry point of the initialization routine in the

driver

void

NEAR *

X_CRT_INIT

SVC RIO–SVC entry point for driver void

NEAR *

X_CRT_SVC_BR

FLAGS Driver flags: char 03H

Bit0=1: Parallel driver

Bit1=1: Type II driver

Bit2=0: Initialization in the boot sequence

FMAX Maximum function code for type II driver char 0CH

RESERV 2 reserved bytes char 00H, 00H

1 This value is occupied during system configuration.

5.3.4.2 Unit Control Data table (UCD)

The UCD block (Unit Control Data table) has a general and a driver-specific part. For

information about the init specifications for the general part of the UCD block, refer to

chapter 2.3.10 "Unit Control Data table (UCD)" in the System Manual. The configuration of

the UCD blocks, except for the reserved parameters, is closely oriented on the BYT driver.

The examples for the configuration can therefore be derived from the corresponding

examples of the BYT driver.

Parameters Offset Type Description Note

PID 0 char ID of the processor that operates the unit

INTNO 1 char Number of the interrupt vector for this unit

INT_ADR 2 void FAR * Address of the interrupt handling routine (assigned internally) 1

UNS 8 short Task ID of the task started after an unexpected input (0FFFFH

if none)

PORT 10 Driver-specific data (120/246 bytes)

256 Total

1 See Interrupt routines of the CRT2 driver. (Page 177)

Functions and configuration of the basic I/O system

5.3 CRT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 173

5.3.4.3 Driver-specific parameters in the UCD block

Parameters Offset Type Description

UCMODE 10 short DMA controller type

PRTSEG 12 short USART segment/selector

PRTDAT 14 int USART data port/offset

PRTCMD 18 int USART command port/offset

PORT_2 22 int USART extra port 2/offset

PORT_3 26 int USART extra port 3/offset

PRTSTA 30 int USART status port/offset

STMODE 34 short Reserved

STARET 36 short Reserved

TOPCHR 38 short Form feed character

TIMOUT 40 short Timeout value/character

TABBUF 42 void FAR * Reserved

POOLID 48 char Reserved

POOLEN 49 char Reserved

UNSCHR 50 short Start character for unexpected task start

RECOVR 52 char I/O delay value

MODEXT 53 char Reserved

ICOUNT 54 short Number of init outputs

MOBYTE 56 short 1. Initialization output

MOBYTE 254 short 42. Initialization output

The driver-specific parameters are available as of offset PORT in the UCD block. The

meaning of the various parameters is documented in the following sections.

Functions and configuration of the basic I/O system

5.3 CRT driver

RMOS3 V3.50 Reference Manual Part II

174 Programming Manual, 07/2012, A5E03692298-01

UCMODE (Unit Control Code)

Bit Designatio

Meaning

15 reserved

12 LF 0 = CR without LF

1 = CR followed by LF

11 UC USART ID:

0000 = USART 8251A

0001 = PPI 8255A w/o Strobe

0010 = reserved

0011 = reserved

0100 = SCC 8530

0101 = PPI 8255A w/ Strobe

0110 = TIMER E19/E18

0111 = reserved

1000 = reserved

1001 = UART 8250

1010 = reserved

1011 = reserved

11XX = reserved

10 UC

9 UC

8 UC

7 x reserved

6 x

5 x

4 x

3 x

2 x

1 x

0 MD ID for DIO or MMIO

0 = DIO (direct I/O)

1 = MMIO (Memory Mapped I/O)

Comments on entering port addresses

The table contains the controller-specific entries for the port addresses in the UCD table:

Controllers PRTDAT PRTCMD PORT_2 PORT_3 PTRSTA

8530 DATA A/B CMD A/B – CMD A CMD B

8251 DATA CMD – – STS

8255 with SW

strobe

DATA OUT CMD STS BITMASK (set and

reset)

DATA IN CMD STS

8255 with HW

strobe

DATA OUT CMD STS – – CMD STS

8250 DATA MODEM CTRL LINE CTRL INTR ENABLE LINE STS

Functions and configuration of the basic I/O system

5.3 CRT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 175

Notes:

● When configuring I/O devices that use the PPI 8255A controller, take into account that

PRTDAT must be used for the output data port and PORT_3 for the input data port. To

enable the additional execution of the strobe/function after data output, set the

corresponding command bytes at PORT_2, whereby the least significant byte must

contain the bit mask for strobe/set, and the most significant byte must contain the bit

mask for strobe/reset.

● On the SMP–E19 and SMP–E18 modules, data output to printers is controlled by means

of a timer. This means that the corresponding timer is addressed after data was output.

Accordingly, set the timer command port at PORT_3 and the timer command word at

PORT_2. If PRTSEG contains a value unequal zero, the memory I/O method is used for

timer control, independent of UCMODE. In this case, the timer command port must

contain the relevant offset value.

● If you don't need the additional PORT_2 and PORT_3 parameters for special

configurations, you can use them for other init purposes (e.g. as port addresses for

timers).

TOPCHR (form feed character)

The CRT2 driver expects the corresponding control characters in this field to execute the

function 0BH. The field is set to zero if the unit does not support this function. You may

configure a maximum of two control characters. The least significant byte must contain the

form feed character, while the most significant byte must contain the "clear screen"

character.

TIMOUT value/character

The CRT2 driver multiplies the expected value in milliseconds with the number of all

characters to output for an output request and sets the result as timeout value. TIMOUT has

a range of values from 0 to 0FFFH. Bits 12 to15 are reserved and must be set to zero. A

zero value suppresses time monitoring.

UNSCHR (Task start due to unexpected input)

The CRT2 driver expects the corresponding control characters in this field to run the "Task

start due to unexpected input" function. You can define two start characters (least and most

significant bytes).

Set this field to zero value if this function is discarded for the CRT2 driver. All unexpected

input characters (exception: CTRL–Q, CTRL–S und CTRL–X) are compared with the two

start characters in UNSCHR (if unequal zero); the task start is initiated if the values match.

The ID of the task to start is specified in UNS, in the general parameter area of the UCD

block.

Functions and configuration of the basic I/O system

5.3 CRT driver

RMOS3 V3.50 Reference Manual Part II

176 Programming Manual, 07/2012, A5E03692298-01

In addition, the CRT2 driver sets the following values at status field XSTATUS:

char XSTATUS + 00: DRIVER ID

char XSTATUS + 01: DEVICE ID EAX register

char XSTATUS + 02: 00H

char XSTATUS + 03: 00H

char XSTATUS + 04: Start character

char XSTATUS + 05: 00H EBX register

char XSTATUS + 06: 00H

char XSTATUS + 07: 00H

The XSTATUS parameters are transferred at task start to the EAX and EBX registers of the

processor. The task which is started due to an unexpected input can evaluate the start

character by reading the start character in the EBX register and possibly start additional

tasks.

RECOVR (recovery time)

The CRT2 driver uses this parameter internally to set a delay between two successive I/O

errors. The waiting time (recovery time) to be maintained is specified in the description of the

controller. The delay value depends on the processor used and on its clock frequency.

MOBYTE (init output)

This value corresponds to an init unit and is interpreted by the CRT2 driver as follows:

Least significant byte: Init byte or mode byte to be output.

Most significant byte: Index (ID) for the output port with the following meaning:

Index USART port Parameters

0 Data port PRTDAT

1 Command port PRTCMD

2 Extra port 2 PORT_2

3 Extra port 3 PORT_3

4 Status port PRTSTA

The system provides 99 init units. If the value at parameter ICOUNT is higher, the program

initializes a maximum of 99 units. Index values greater than 4 are interpreted as index 0.

Functions and configuration of the basic I/O system

5.3 CRT driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 177

5.3.4.4 Interrupt routines of the CRT2 driver

The CRT2 driver provides 3 entry point addresses for its interrupt handler routines that are

declared as PUBLIC symbols with the following meaning:

X_CRT_RCVR_INTR:

Interrupt handler for input units (receiver for I/O devices, e.g. 8251, 8255).

X_CRT_TMTR_INTR:

Interrupt handler for output units (transmitter for I/O devices, e.g. 8251, 8255).

X_CRT_COM_INTR:

Entry point address for I/O devices with shared interrupt for all actions (e.g. 8530, 8250).

Verify that the interrupt with lower vector number (higher priority) is assigned to the receiver.

5.3.4.5 Stack requirements of the CRT2 driver

RM3

S state 40 words

I state 48 words

DI state -

Functions and configuration of the basic I/O system

5.4 RAM disk driver

RMOS3 V3.50 Reference Manual Part II

178 Programming Manual, 07/2012, A5E03692298-01

5.4

RAM disk driver

5.4.1

Properties

Purpose of the driver

The RMOS3 nucleus contains a device driver that uses a reserved section in RAM to

simulate an HSFS unit. This area behaves similar to a disk storage volume, but with the

usual shorter reaction time of RAM chips. This area is known as RAM DISK.

RAM disk

A RAM DISK therefore facilitates accelerated access to critical files, but at the cost of certain

management expenditure (files need to be loaded from non-volatile memory to RAM and on

completion vice versa). Moreover, there is also the risk of the loss of data on system failure

or error, i.e. data cannot be written back. The RAM DISK must be formatted before you can

mount it (call of remap).

It should be noted that you can usually dispense with implementation of a RAM DISK if you

provide a well-tuned system that consists of multiple buffers.

The RAM DISK driver manages a defined RAM area similar to a block-oriented unit.

The RAM disk driver is a parallel type II driver. The source code of the RAM DISK driver is

included in directory DEV\RAM. The RAM DISK driver includes the following files:

RAM_DRV.C

C source code

RAM_DRV.H

Header file

RAM_3.SUB

Subsystem definition

If you want to expand or edit the driver, you can use the batch file GEN_RAMC.BAT for

Organon and GEN_RAMI.BAT for Intel Tools in directory DEV to create a custom RAM DISK

driver that is tailored to suit your requirements. The source code has a clear commented

structure and may serve you as template for creating a custom, block-oriented RMOS3

driver.

Functions and configuration of the basic I/O system

5.4 RAM disk driver

RMOS3 V3.50 Reference Manual Part II

Programming Manual, 07/2012, A5E03692298-01 179

5.4.1.1

Sequence of the RmIO system call